xwcode v1.9.1 — Rust 系统级 AI 编程 Agent

本档 = 用户入口（① 是什么 / 对谁有用 · ② 安装与配置 · ③ 新开发者贡献）· 计数锚 0+ tests （members=[] 极薄根 bin · 结构性零覆盖 —— 有效信号 = build / fmt / clippy 三段 EXIT=0）。 逐版交付面与版本史见 RELEASE_NOTES.md；机器生成之逐版明细见 CHANGELOG.md；版本路标见 ROADMAP.md ∧ openspec/specs/。

一、这是什么 / 对谁有用

xwcode 是一个 Rust 实现的系统级 AI 编程 Agent —— 终端交互（TUI / CLI REPL）+ 工具编排

多 Agent 结构化协作，单二进制部署。

对谁有用：

想在本机跑一个可审计、可离线部署的编码 Agent 的工程师 —— 单二进制（install.sh 一键 / cargo install），配置单档（xwcode.json），Provider 可换（含本地与自建端点）。
需要 Agent 之间结构化协作的自动化流水线搭建者 —— Mailbox v2（wire_protocol）提供 Request / Response / Event / Broadcast 四类消息 ∧ JSONL 持久化 ∧ Direct / Broadcast / Request-Response 三种路由；子 Agent 可主动上报 ∧ 接受中途干预。
想读一个「判据优先」工程实践的 Rust 代码库的开发者 —— 发布门禁（scripts/verify_release.sh） ∧ 判据腿件 ∧ 红侧实证 ∧ 证据档归档，在本仓是一等公民（见 §三）。

能力面

36 工具（M2 三向分流终态，35 LLM-visible + task_complete 条件可见；git_ops 13 ops）
4 语言代码引擎 · tree-sitter AST · LSP · Git · Cargo
EventLog · TaskSpec · ExecutionReport + EvaluationReport

Mailbox v2 协作协议（wire_protocol）

结构化 Agent 间消息协议，支持跨 turn 持久化和双向通信：

消息类型：Request / Response / Event / Broadcast 四种结构化消息
JSONL 持久化：.xwcode/mailboxes/<agent_id>.jsonl，追加写入 O(1)，跨进程恢复
路由引擎：Direct（点对点）/ Broadcast（广播）/ Request-Response（correlation_id 匹配）
Agent 工具：mailbox_send_v2 / read_mailbox / report_event
Coordinator 双向通信：子 Agent 主动上报 + 中途干预（cancel/redirect）
CLI 调试：xwcode mailbox2 ls/read/send

二、安装与配置

安装

一键安装（推荐）——仓库根 install.sh 用户安装盘：release 构建 + 原子部署 ~/.local/bin/xwcode + 版本/sha256/可执行三重验证（失败自动回滚不留半成品）；已装同版本幂等短路。

前置（三件 + 工具链）：

#	前置	必需性	说明
①	`git`	必需	拉取源码 ∧ 依赖解析（`git ls-remote` 亦为网络探针之回退臂）
②	`curl`	可选	仅影响 `rustup` 引导（缺席时回退 `git ls-remote` 探路，并降为 warn）
③	C 链接器 `cc`	必需	release 构建之链接阶段需之。Debian/Ubuntu 装 `build-essential`（或 `gcc`/`clang`）。★ `v1.7.5` 起 `install.sh` 于 `precheck` 前置探测，缺失即 `die 2` 并给指引——归因在环境、非本仓构建缺陷（与 `gitcode` 可达性同族 fail-fast）

Rust 工具链：本仓钉 1.89.0（唯一源 = 仓根 rust-toolchain.toml 之 channel ⇒ 本地 ∧ CI 同源）。★ 语义 = MSRV 下限（floor）：≥1.89.0 皆可，新版可用（非「唯此一版」）。工具链（cargo）缺失时脚本交互询问并引导安装 rustup（官方源仅 https）；--yes 走非交互自动接受（无人值守安装用）。rustup 在场但缺该工具链时不自动下载——退出码 2 并给出手动命令。release 构建需数分钟。

拉取面说明（v1.7.4 传输根治 · v1.9.1 现态）：release 构建的依赖拉取需访问 gitcode.com。v1.7.4 起 [patch.*] 段之 25 条目行（v1.9.1 现态 23 条 —— N1 实撤 2 段）已由 ssh://git@gitcode.com/ 全面改为 https://git@gitcode.com/（git@ 系 RFC 3986 之 userinfo 段，非凭据、无口令）——Cargo.lock 内 git+ssh 源清零，构建全程零 ssh 拨号：无 ssh key、无 ssh-agent 的机器可完整安装。背景（历史成因）：cargo 内置的 libgit2/libssh2 ssh 实现不走系统 ssh 命令行、依赖运行中的 ssh-agent——只有 ssh key 而无 agent 时认证会失败（实证：新机器有 ed25519 key 且 git clone 可用，cargo build 仍报 attempted ssh-agent authentication）；v1.7.4 之前 [patch] 键=https 原源 / 条目=ssh 重定向源系【同源补丁禁令】下的跨 scheme 收敛机制载体（cargo 同源检查硬约束），不构成用户面 ssh 依赖。install.sh 仍保留 CARGO_NET_GIT_FETCH_WITH_CLI=true + GIT_CONFIG_* insteadOf 重写（v1.6.2 AC4，会话级 env 注入不碰用户 git 配置）——v1.7.4 后其三条规则对本仓零命中，地位由【唯一链路】退为纵深（覆盖所钉插件仓 manifest 内可能残留之 ssh 字面量）。手动构建遇同类报错时，先执行上面两个 export 再重试。

bash

## ① 获取仓库（推荐直接 clone 发布 tag——确定性安装该版本）
git clone --depth 1 --branch v1.9.1 https://gitcode.com/kemeng1/xwcode.git
cd xwcode

## ② 安装（缺 Rust 工具链时按提示确认引导安装 rustup）
bash install.sh

## ③ 验证
xwcode --version        # 应输出 xwcode 1.9.1
xwcode --check          # 校验配置 + 列出 Provider

若 ~/.local/bin 不在 PATH，脚本结束时会打印 export 指引，按提示追加后 source ~/.bashrc。

★ 为何用 --branch <tag>: 直取发布 tag（非 master 浮动面）⇒ 安装面确定（同 tag 恒同树；承树身份纪律「禁以移动引用充钉值」）。无人值守（CI / 新机脚本）加 --yes 走非交互。

⛔ curl … | bash 一键装【不可用】（明令禁用 —— 非「待启用」） 由: gitcode 之 /raw/ 端点当前返回网页壳而非脚本正文（实测）⇒ 管道入 bash 者不是脚本（轻则报错，重则执行意外文本）。一律以双步命令为准（git clone + bash install.sh）。 ★ 若将来 /raw/ 端点可用，须另立 AC + 红侧（正文首行校验）方可开禁——禁以「端点可用」推定开禁。脚本单独拷到任意目录执行亦可：远程模式自动 clone 源码到临时目录构建（默认装远程最新 tag，--repo 换源、--version 显式定版）。

常用变体：

bash

bash install.sh --version v1.9.1     # 安装指定 tag（本地源码树内走 worktree 隔离，不触碰工作区）
bash install.sh --yes                 # 非交互自动模式（跳过询问，自动接受 rustup 引导）
bash install.sh --prefix <dir>        # 自定义部署目录（默认 ~/.local/bin）
bash install.sh --force               # 已安装同版本时强制重建
bash install.sh --uninstall           # 卸载（只移除部署位与备份，不动 ~/.xwcode 用户配置）
bash install.sh --help                # 全部选项与退出码语义（0 成功/1 失败/2 环境前置缺失/3 验证失败已回滚/4 用户取消）

**低配机（内存 ~1.7G 级，release 构建易 OOM）**推荐预置产物路径：XW_INSTALL_PREBUILT=<产物路径> bash install.sh --prefix <dir>——跳过 release 构建，仅做部署+版本/sha256/可执行三重验证（产物由高配机或 CI 构建后拷入）。

手动构建（备选）——需先自行安装 Rust stable 工具链：

bash

git clone https://gitcode.com/kemeng1/xwcode.git && cd xwcode
cargo install --path .                # 包名 xwcode-skeleton，产物二进制名 xwcode
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
xwcode --version

使用

bash

xwcode -p "列出项目中的 Rust 文件"           # oneshot 模式
xwcode                                       # 缺省 TUI 交互界面（v0.95.6 opc-3f 起）
xwcode --cli                                 # 显式交互式 CLI/REPL 模式
xwcode --tui                                 # 显式 TUI（兼容，缺省已为 TUI）
xwcode --task tasks/add-feature.md           # 任务文件模式（YAML frontmatter）
xwcode --task t.md --report-dir reports/     # 自定义报告输出目录
xwcode --init                                # 生成配置模板
xwcode --check                               # 校验配置 + 列出 Provider
xwcode --resume <session_id>                 # 恢复中断的会话
xwcode --replay <session_id>                 # 只读回放会话事件时间线

REPL 命令

text

/help  /exit  /model  /tools  /save  /sessions

配置

在项目根目录创建 xwcode.json：

json

{
  "model": "opencode-go/deepseek-v4-flash",
  "providers": {
    "opencode-go": {
      "provider": "opencode-go",
      "wire_protocol": "openai",
      "base_url": "https://opencode.ai/zen/go/v1",
      "api_key": "你的 OpenCode API Key",
      "models": ["deepseek-v4-flash"]
    }
  }
}

api_key 填入你的 OpenCode API Key。也可以用环境变量 OPENCODE_API_KEY 代替内联 key。配置优先级：项目根目录 xwcode.json > $HOME/.xwcode/xwcode.json > 内置默认值。

首次配置自检（新机器验证闭环）

bash

cd 你的项目根目录                       # xwcode.json 按项目目录生效；全局配置放 $HOME/.xwcode/xwcode.json
xwcode --check                         # ① 配置合法 + 列出可用 Provider
xwcode -p "只回复两个字：正常"          # ② 端到端功能冒烟（真实模型一次调用）

两步都通过即完成「安装 → 配置 → 功能验证」闭环；冒烟无回复或报错时，优先检查 api_key 与网络连通。

配置骨架 / 完整字段

运行 xwcode --init 生成含全部可配置字段的配置模板（含缺省值）。
全部字段的类型 / 缺省值 / 含义 / 示例见 docs/CONFIGURATION.md。
支持权限（permission_mode / permission）、模型与供应商、上下文压缩等配置段。

三、新开发者贡献

环境与构建

bash

git clone https://gitcode.com/kemeng1/xwcode.git && cd xwcode
cargo build --release                  # 工具链版本由仓根 rust-toolchain.toml 钉定（唯一源）
cargo nextest run --workspace --all-targets -j 32 --no-fail-fast   # 测试口径（禁裸 cargo test）
cargo fmt --all && cargo fmt --all --check
cargo clippy --all-targets -- -D warnings

★ 测试口径: 一律 cargo nextest run（doctest 例外走 cargo test --doc）；全量 -j 32，局部 / 单 crate -j 4 或 -j 8；全绿声明必须带 --no-fail-fast 并附实际并发路数。 ★ 编译: 本机 CARGO_BUILD_JOBS=16（实测拐点）；调优须先查 docs/COMPILATION_GUIDE.md 既有实测 ⇒ A/B 留痕 ⇒ 才可改值。 ★ rust-toolchain.toml 之坑: cargo 系 rustup 代理，读当前目录之该档；channel 未装时会 静默自动下载 ⇒ 前置检查里裸调 cargo 会「卡住」。探针请带超时 ∧ 显名 cwd。

仓库导航

面	位置
发布门禁（全量检查）	`scripts/verify_release.sh`（`XW_ADJUDICATE_SKIP` 可显式裁定空窗）
判据腿件 / 红侧	`scripts/tests/`（`_leg.sh` 正向腿 ∧ `_redside.sh` 红侧构造）
编译指南	`docs/COMPILATION_GUIDE.md`
协同工作流	`docs/WORKFLOW.md`
版本路标 / 逐版交付面	`openspec/specs/` ∧ `ROADMAP.md` ∧ `RELEASE_NOTES.md`
架构说明	`docs/ARCHITECTURE.md` ∧ `openspec/specs/architecture.md`

提交与发布纪律（要点）

发布期 master 仅接受合并提交（pre-push 钩子拒单父直推）⇒ 走 dev 支 → master 合并通道。
禁 amend / 禁 force / 非快进即停。
报交付件须给面三值: 支 + 尖 + 树（git rev-parse <rev> ∧ <rev>^{tree}），附命令与 rc；禁以移动引用充钉值。
新证据档（机器转储类）入库前须先跑 typos；命中须逐档具名入 typos.toml 之 ①h 族。

参见