# X-Coder

**Repository Path**: carllee34/x-coder

## Basic Information

- **Project Name**: X-Coder
- **Description**: No description available
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# X-Coder

> 用 Rust 单二进制核心 + Next.js Web 重写 kimi-code 0.39.1 的 AI 编码代理。
> **单一引擎、单一 wire 契约**：CLI、TUI、Web、ACP 全部消费同一套协议（`xcoder-protocol`）。

```
xcoder                ── ratatui TUI（默认入口）
xcoder -p "..."      ── headless 单轮
xcoder web           ── 本地 REST+WS 服务器（Web UI 后端）
xcoder acp           ── ACP stdio 服务器
xcoder doctor        ── 安装自检（doctor config|tui [path] 校验单个配置文件）
xcoder export        ── 导出会话目录（ZIP）
xcoder fork          ── fork 会话为新会话
xcoder feedback      ── 收集诊断包到数据目录（无上传通道，手动附带）
xcoder import-kimi   ── 一次性迁移旧 kimi-code 数据：会话/skills/MCP/历史/plans（M8；W3/B43 起扩面）
xcoder plugin        ── 非交互插件管理（install/enable/disable/delete/list/marketplace）
xcoder provider      ── 非交互 provider 管理（list/add/remove/catalog）
xcoder session list  ── 非交互会话列表
xcoder upgrade       ── 升级到最新版（别名 update）
xcoder vis           ── 浏览器会话可视化（loopback）
```

当前状态：**M0–M10 全部完成**。
**进度事实来源：`docs/PLAN.md`**（里程碑/测试数/质量门口径/决策/改进清单一律以它为准）——本文档只描述代码里已成事实的行为。

### 发布包

`dist/x-coder-<版本>-<平台>.tar.gz`（`bash scripts/package.sh` 一键构建打包）：

```
xcoder / web/（静态导出）/ docs/ / plugins/ / install.sh / config.example.toml /
mcp.example.json / README.txt / LICENSE
```

包内**没有 Node**：解压即用 `./xcoder`（TUI）；
`XCODER_WEB_DIR=./web ./xcoder web`（或放任其自动检测同目录
web）单端口同源提供 Web UI + API。

## 快速开始

前置：Rust stable（`rust-toolchain.toml` 固定 channel，含 rustfmt/clippy），macOS 或 Linux。

```bash
cargo build --release                 # 产物 target/release/xcoder
export XCODER_HOME="$HOME/.xcoder"    # 可选，默认 ~/.xcoder
export XCODER_PROVIDER="openai"       # openai | openai_responses | anthropic | kimi | google-genai
export XCODER_OPENAI_API_KEY="sk-..."
export XCODER_OPENAI_BASE_URL="https://api.deepseek.com/v1"   # 任意兼容端点
export XCODER_MODEL="deepseek-chat"
# 或写 ~/.xcoder/config.toml 的 [provider] 段（支持 api_key = { env = "VAR" }）；
# KIMI_API_KEY / KIMI_BASE_URL 保留为 openai 协议别名。无登录命令（OAuth 已移除）。
# TUI 默认主屏行式渲染（对话进终端原生回滚区，可选中/回滚/退出后保留）；
# KIMI_CODE_TUI_FULL_SCREEN=1 改用全屏 alternate-screen（实验特性，对齐 kimi-code 同名开关）

xcoder                                # 启动 TUI（引擎跑在 TUI 自己的进程里）
xcoder web                            # 启动本地服务器（Web UI 后端；CLI 不需要它）
xcoder -p "新增一个 Go 单元测试"       # headless 单轮
xcoder doctor                         # 自检
```

Web UI：生产由 `xcoder web` 直接托管静态导出（单端口同源，无需 Node）；
开发 `cd web && pnpm dev`（`.env.development` 指向本地 daemon，daemon 需
`XCODER_DEV_CORS=1` 放行回环跨源，详见 `docs/configuration.md` §5.6）。

## 质量门（CI 等价命令）

```bash
bash scripts/check-import-boundaries.sh        # import 边界（纯 grep，CI 首步）
bash scripts/check-unsafe-safety.sh --check    # unsafe 安全自述
bash scripts/check-loc-budgets.sh --check      # LOC 预算
bash scripts/count-unwrap.sh --check           # unwrap 计数
python3 scripts/check-doc-refs.py docs/*.md    # 文档引用新鲜度
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo run -p xcoder-protocol --bin export-schema -- --check         # schema 新鲜度
cargo run -p xcoder-protocol --bin export-wire-manifest -- --check  # wire 事件目录新鲜度
cd web && pnpm typecheck && pnpm test && pnpm build
```

## 文档

| 文档 | 内容 |
|---|---|
| `docs/PLAN.md` | **唯一进度事实来源**（里程碑/测试数/决策/改进清单） |
| `docs/configuration.md` | config.toml / tui.toml / mcp.json / 环境变量全键表与现状（含「已解析未接线」清单） |
| `docs/user-guide.md` | 用户指南（安装 / provider 配置 / 运行形态 / 常用操作 / 数据位置 / 排查） |
| `docs/flows.md` | 端到端流程核对清单（F 套件 / TUI 冒烟 / Web e2e 的覆盖现状与跑法） |
| `docs/media-upload.md` | 媒体上传与引用全链（files/media 双层存储、`ms://` 引用、能力降级、交互与排查） |
| `docs/protocol.md` | wire 契约参考（单一来源 / REST 与 WS 面索引 / wire 事件目录 / EngineEvent 映射） |
| `docs/development.md` | 开发指南（仓库布局 / 构建门禁 / schema 流程 / 变更工作流 / 文档纪律 / 打包 / CI） |

> 早期索引里的 known-gaps / audit-findings / architecture-review 三篇**不再计划**；
> 历史审计/修复/吸纳类中间文档（复核报告 / 差距审计报告 / 修复计划 / 0.42.0 吸纳报告等）
> 与差异台账的已闭环条目已于 2026-09-23 清理（git 历史可查）。当前进度以 `docs/PLAN.md` 与本 README、上表各文档为准。

## 仓库布局

```
crates/
  xcoder-protocol   wire 契约单一来源（REST/WS/事件/transcript + JSON Schema 导出）
  xcoder-kosong     LLM provider 抽象（kimi/openai/anthropic/openai-responses/google-genai）
  xcoder-os         OS trait（Local 后端、进程组 kill、沙箱 seam）
  xcoder-tools      内置工具集（Bash/Read/ReadMediaFile/Write/Edit/Grep/Glob/FetchURL/
                    WebSearch/AskUserQuestion/Cron×3/Task×3/Goal×4/Agent/AgentSwarm/
                    Skill/TodoList/SelectTools）+ 工具契约与媒体注册 seam
  xcoder-core       引擎内核（journal+快照/context/permission/tools/compaction/turn/
                    goal/cron/hooks/skills/plugins/subagent-swarm/MCP/media/组合根）
  xcoder-store      持久化抽象 + SQLite FTS5 搜索索引 + blob
  xcoder-telemetry  类型化事件目录 + 队列/落盘重放 + kill switch
  xcoder-server     axum REST + WS（seq 水印/订阅等级/追赶）+ auth + 会话管理
  xcoder-acp        ACP stdio 服务器
  xcoder-tui        ratatui TUI
  xcoder-cli        `xcoder` 二进制（clap 多子命令）
web/                Next.js Web UI（消费生成类型 web/src/lib/protocol/）
docs/               文档
```

## 协议与配置速览

- REST：`/api/v1/*`，统一信封 `{code, msg, data, request_id}`（`0` = 成功）。
- WS：`/api/v1/ws`（browser 用 `kimi-code.bearer.<token>` 子协议认证），
  v2 协议、每会话 `{seq, epoch}` 光标、流式追赶、`off|turn|block|delta` 四级 transcript 订阅。
- 配置：`config.toml`（`[provider]` / `[[hooks]]` / `[permission]` 由引擎读取：
  user 级权限规则在 CLI/服务端/ACP 的会话构建时从各自 home 的 config.toml 解析
  生效，TUI 经服务端；project 作用域经规则自身的 `scope` 字段承载——0.42 与 v1
  均无 project 级规则文件，见 `docs/configuration.md` §7）+
  环境变量（`XCODER_PROVIDER`、`XCODER_*_API_KEY`、`KIMI_API_KEY` 等）。MCP
  配置**不在** config.toml——引擎读三层 `mcp.json`（用户级
  `<XCODER_HOME>/mcp.json`、项目根级 `<git 根>/.mcp.json`、项目级
  `.xcoder/mcp.json`）；`config.toml` 的 `[mcpServers.*]` 解析器保留但引擎
  不读（死块，见 `docs/configuration.md` 的"现状"小节）。其余 kimi 配置域
  走 `GET/POST /v1/config` wire 面；provider 配置另见 `GET /v1/config` 的
  `provider` 视图与 `PUT /v1/config/provider`。详见 `docs/configuration.md`。
- 会话操作：TUI `/fork`（fork 会话副本，留在源会话）、`/btw <prompt>`
  （旁路侧聊，答案以通知回主会话）、`/undo [N]`、`/compact [instruction]`、
  `/mcp`、`/status`、`/plan`（plan mode 切换）、`/reload`、`/update-config`，
  均落在 REST 会话动作路由（`{sid}:fork` / `:btw` / `:undo` / `:compact` /
  `:plan` / `:detach` 等）上；cron 管理面 `GET /v1/crons` + `{cid}:delete`。
- hooks：`[[hooks]]` 生命周期钩子覆盖 20 种事件
  （`xcoder-core/src/hooks.rs` 的 `HOOK_EVENT_TYPES`：`PreToolUse` …
  `Notification`）。
- provider：`xcoder-kosong` 抽象覆盖 kimi / openai / openai-responses /
  anthropic / google-genai 五家实现；用户可配协议五种（`XCODER_PROVIDER`：
  `openai` / `openai_responses` / `anthropic` / `kimi` / `google-genai`）。
- MCP：三层 `mcp.json`；stdio + streamable-http + legacy-SSE 三传输；
  OAuth 保护的服务器走授权码流程，授权入口
  `POST /api/v1/sessions/{sid}/mcp/servers/{name}:authorize`。

License 与版本：workspace `Cargo.toml` 声明 `license = "MIT"`，版本 `1.0.0`。