迅码 使用文档

快速开始 · 装机

一条命令就能把迅码装进终端。它免 sudo、不污染系统目录,卸载也只是删一个文件夹——上手成本压到最低。

macOS(Apple 芯片 / Intel)与 Linux,一行命令安装:

curl -fsSL https://xuncode.com/install.sh | sh
xun --version

1. 识别与校验。脚本自动识别系统与架构、校验 sha256,把 xun 装进 ~/.xun/bin 并自动配好 PATH——全程免 sudo。
2. Windows 走 PowerShell。Windows 10 / 11 · 64 位用 irm https://xuncode.com/install.ps1 | iex 安装。
3. 卸载即删目录。不留系统残余,卸载只需 rm -rf ~/.xun。

配置模型

模型选择权始终在你手里——公网网关、内网 vLLM 还是本地 Ollama,一份配置切换自如,迅码不绑定任何单一模型。

迅码不绑定单一模型。写入全局配置 ~/.xun/config.toml:

api_base = "https://api.maxmodel.com/v1"   # 网关 / vLLM / Ollama 端点
api_key  = "你的 Key"                       # vLLM / Ollama 可留空
model    = "gemini-2.5-flash"

内网 vLLM 用 http://内网IP:8000/v1,本地 Ollama 用 http://127.0.0.1:11434/v1。临时切换模型:xun --model <名称>,或交互界面内 /model <名称>。

第一次对话

直接把任务说给它听,读代码、列待办、改文件、跑命令都由它自己完成——你只在敏感操作前点一下头。

cd 你的项目
xun                                  # 交互式启动
xun "修复 login 模块的空指针"          # 带任务启动,立即开工

直接输入任务即可。迅码会自己读代码、列待办、改文件、跑命令。建议先 xun init 生成 XUN.md(项目记忆)与 xun.toml(项目权限),让它一开始就懂这个项目的规矩。

命令与斜杠命令

一套动词化的子命令覆盖从跑任务、审代码到查审计的全流程;交互界面里再用斜杠命令随手切换状态,手不离键盘。

子命令:

xun "<任务>"            # 运行任务
xun -p "<任务>"         # 无头模式,输出到 stdout(CI / 脚本)
xun -p --json "<任务>"  # 无头 + 结构化 JSON 事件流(供 SDK / 程序解析)
xun --plan "<任务>"     # 计划模式:先出计划再执行
xun --resume            # 续跑本目录最近的会话
xun --resume <id>       # 续跑指定会话
xun sessions            # 列出可续跑的会话
xun review [ref]        # 代码审查(默认审当前改动)
xun fix [目标]          # 定位并修复 bug / 失败的测试
xun init                # 初始化项目
xun checkpoint list|rollback <id>
xun audit list|verify|export <路径>
xun doctor              # 环境自检:配置/签名/许可证/审计链/数据外发面
xun license             # 查看企业许可证状态

交互界面内斜杠命令:

可信执行

这是迅码的核心,也是它敢在生产环境跑的底气:AI 只提议、你来定夺,每条命令逐段评估风险,危险动作强制询问,全程哈希成链留审计。

AI 提议操作、你定夺,每条命令逐段评估风险,敏感操作先批准,全程留审计。权限模式([permissions] mode 或旗标)分三档:

规则按 deny > ask > allow 判定:

[permissions]
allow = ["Bash(cargo build:*)", "Read(src/**)"]
ask   = ["Bash(git:*)"]
deny  = ["Read(~/.ssh/**)"]

链式命令逐段拆解评估 —— ls && rm -rf / 会因 rm 段被拦,命令替换与内嵌脚本也逐层展开;无法解析的命令保守询问。项目级 xun.toml 只能收紧、不能放宽全局权限(防仓库投毒)。

审计链:每个决策与结果写入本机 ~/.xun/audit.jsonl,哈希链串联,任何篡改都会断链。

xun audit list      # 最近记录
xun audit verify    # 校验完整性,断链定位到行
xun audit export a.jsonl   # 合规留档

计划模式

改动越大,越该先看清全貌再动手。计划模式让迅码只读调研、产出可审阅的编号计划,把「想清楚」和「动手做」分成两步。

改动大或需求不明时,先只读调研、产出可审阅的计划:

xun --plan "重构 auth 模块,把回调改成 async/await"

计划模式下迅码只有读取与检索工具,产出编号计划(每步写明涉及文件、改动要点、如何验证);你批准后才动手。交互界面内用 /plan <任务>。

检查点与回滚

让 AI 大胆改代码的前提,是随时能安全撤销。检查点用 git 影子引用悄悄快照,既不碰你的暂存区,也不留提交痕迹。

在 git 仓库中,迅码每个任务开始前自动快照工作区(用 git 影子引用,不碰你的暂存区、不产生提交)。改坏了一键回滚:

xun checkpoint list
xun checkpoint rollback <id>

语音下指令

对着说,比逐字敲快得多。识别全程在你的 Mac 本地完成、不出机器,还继承润迅语音输入的术语词典——人名、命令、专有名词零配置就认得。

1. 首次放行麦克风。在「系统设置 → 隐私与安全性 → 麦克风」中给终端授权(仅需一次)。
2. 输入 /v 开录。交互界面内输入 /v,按说即录、回车结束。
3. 确认后才执行。转写结果先呈现给你,经确认后才作为指令执行,不会误触。

技能与子任务

把一次跑通的方法沉淀成技能,迅码就会越用越懂你的项目;复杂任务再拆给子 Agent 并行推进——单机也能像一支小队。

• 技能:你封装的可复用方法,放 ~/.xun/skills/<名>/SKILL.md(全局)或项目 .xun/skills/。迅码启动时只读名称与描述,任务相关时再加载完整正文——不占无谓上下文。
• 子任务:复杂任务中迅码可把独立子问题派给子 Agent 处理,共享同样的权限与审计策略,不越界。
• 兼容既有约定:已有的 CLAUDE.md / AGENTS.md 会被识别并可沿用,迁移无需从零。

用命令一键安装与查看技能:

MCP 扩展

MCP 让迅码接上数据库、内部 API 和专有工具——能力越接越大,而每次调用仍走同一套批准与审计,权限不失控。

接入外部工具服务器(数据库、内部 API、专有工具)。在 config.toml 或 xun.toml 声明:

[mcp.servers.calc]
command = "python3"
args    = ["/opt/mcp/calc-server.py"]

xun mcp 查看已连接工具。MCP 工具默认每次调用都请求批准,可用 allow = ["Mcp(calc:*)"] 放行信任的工具。

也可用命令增删与导入(都需逐条确认、记入审计):

xun mcp add --env API_KEY=xxx tavily npx -- -y tavily-mcp@latest   # 新增(--env 带密钥,写在命令前)
xun mcp import ~/.cursor/mcp.json    # 导入 Claude / Cursor / VS Code 现成 MCP 配置,逐条确认
xun mcp remove tavily

长会话:自动压缩与续跑

真实任务往往跨很多轮、跨好几天。迅码在两个层面兜底,让长任务既不撞模型窗口、也不因关掉终端而丢进度。

一个真实任务往往跨很多轮。迅码在两个层面保证它不会中断:

上下文自动压缩:上下文占用达阈值(默认 85%)时,迅码自动把此前会话总结压缩、 保留关键上下文(系统提示、项目记忆、最近工作原样保留,只压「过程」),让长任务不因超出 模型窗口而报错中断。也可在交互界面用 /compact [关注点] 手动触发。模型窗口可在 ~/.xun/config.toml 用 context_window 指定。

会话续跑:每个任务完成后,会话自动保存在本机 ~/.xun/sessions/(纯 JSON, 你可直接查看)。关掉终端后:

xun --resume            # 续跑本目录最近的会话
xun sessions            # 列出所有会话(★ 标当前目录)
xun --resume <id>       # 续跑指定会话

无头模式 / CI / SDK

把迅码嵌进流水线和自有程序,它照样守规矩:待批准操作一律自动拒绝,每次工具调用的放行判定对上层完全透明、可审计。

xun -p "<任务>" 执行后输出到 stdout 并退出,适合脚本与 CI。无头模式下待批准操作一律自动拒绝;需要改文件 / 跑命令时配 --yes(危险命令仍拦截),或在 xun.toml 用精确 allow 规则显式授权。

# PR 自动审查(只读)
xun -p "审查本次改动,列出正确性与安全问题" | tee review.txt

结构化事件流:加 --json 后,迅码按行输出 NDJSON 事件(start / text / tool / result 等),其中 tool 事件带 可信执行判定(allow/ask/deny)—— 每次工具调用是否放行对上层完全透明、可审计。

xun -p --json "为 utils/ 补全单元测试"

Agent SDK:Node.js 里可用 @xuncode/sdk 包(npm i @xuncode/sdk)把迅码嵌入自己的程序:

import { query } from "@xuncode/sdk";
for await (const ev of query({ prompt: "修复空指针", cwd: "./app" })) {
  if (ev.type === "tool") console.log(ev.name, ev.decision);
  if (ev.type === "result") console.log(ev.text);
}

企业私有化

对代码和数据不出内网有硬要求的团队,迅码可完全私有化——模型、网关、代码、数据、审计全在你这一侧,连许可证校验都不联网。

迅码支持完全私有化部署:模型、网关、代码、数据全部在你的内网,一个字节不出去。

需要离线安装包、企业许可证与部署支持,请联系我们。