1 line
405 KiB
JSON
1 line
405 KiB
JSON
{"repo": "1207575273/ccode", "files": {"cCli/README.md": {"77b80f9a4d92437741efa6136b6478bf10199ef5": {"t": 1785674071.5648134, "n": 10219, "h": "cffd49522ded29b9", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型，内置 Web Dashboard 与 **A2A 分布式 Agent 协作**。\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](https://www.npmjs.com/package/ccode-cli)\n[](https://github.com/1207575273/CCode)\n\n## 安装\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.yml`（YAML 格式，支持注释），填入 API Key 即可使用：\n\n```yaml\ndefaultProvider: glm\ndefaultModel: glm-5\nproviders:\n glm:\n apiKey: your-api-key\n baseURL: https://open.bigmodel.cn/api/coding/paas/v4\n models:\n - glm-5\n - glm-4.7\n```\n\n> 本项目全程在智谱 GLM 模型下开发与测试。只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n> **从旧版升级**：早期版本用 `~/.ccode/config.json`。首次启动会**自动迁移**到 `config.yml`（写回校验无损后才切换），原文件备份为 `config.json.bak`，无需手动处理。\n>\n> **自定义配置根目录**：设置环境变量 `CCODE_HOME` 可把 `~/.ccode` 整体重定向到别处（用于多环境隔离 / 测试）。\n\n### config.yml 完整字段说明\n\n```yaml\n# ────── 全局设置 ──────\ndefaultProvider: glm # 默认使用的 Provider 名称（必须是下面 providers 的某个 key）\ndefaultModel: glm-5 # 默认模型（必须在对应 provider.models 列表中）\nsubAgentModel: glm-4.7 # [可选] 子 Agent 默认模型，可跨 Provider；留空则继承主 Agent\nstatusBar: true # [可选] 是否显示底部状态栏（token 消耗、模型名、A2A 状态等）\n\n# ────── Provider 配置 ──────\nproviders:\n <provider-name>: # 自定义名称，如 glm / anthropic / my-proxy\n apiKey: sk-xxx # [必填] API 密钥\n baseURL: https://... # [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n protocol: openai # [可选] 协议类型：openai(默认) | anthropic\n models: # [必填] 该 provider 可用的模型列表\n - model-a\n - model-b\n visionModels: # [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n - model-a\n\n# ────── 记忆系统（可选，RAG 向量检索）──────\nmemory:\n enabled: true\n embedding:\n apiKey: your-embedding-api-key\n baseURL: https://your-embedding-api-base-url/v4\n model: embedding-3\n dimension: 2048 # 向量维度，需与 embedding 模型匹配\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `subAgentModel` | string | 否 | 子 Agent 默认模型，可跨 Provider；留空继承主 Agent |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `openai`（默认）或 `anthropic`。仅 Anthropic 官方需设为 `anthropic` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空 |\n| `memory.enabled` | boolean | 否 | 是否开启 RAG 记忆系统 |\n| `memory.embedding.*` | object | 否 | embedding 向量服务配置（apiKey / baseURL / model / dimension） |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```yaml\ndefaultProvider: glm\ndefaultModel: glm-5\nproviders:\n glm:\n apiKey: your-zhipu-api-key\n baseURL: https://open.bigmodel.cn/api/coding/paas/v4\n models:\n - glm-5\n - glm-4.7\n anthropic:\n apiKey: sk-ant-xxx\n protocol: anthropic\n models:\n - claude-sonnet-4-20250514\n visionModels:\n - claude-sonnet-4-20250514\n deepseek:\n apiKey: sk-xxx\n baseURL: https://api.deepseek.com/v1\n models:\n - deepseek-chat\n - deepseek-reasoner\n openai:\n apiKey: sk-xxx\n models:\n - gpt-4o\n - gpt-4o-mini\n visionModels:\n - gpt-4o\n ollama:\n apiKey: ollama\n baseURL: http://localhost:11434/v1\n models:\n - qwen2.5:7b\n - deepseek-r1:14b\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web\n```\n\n浏览器打开 `http://localhost:9800`，获得 6 大管理页面：\n\n#### 1. 总览大盘（Overview）\n\n- 6 大核心指标卡片：调用次数、输入/输出/缓存 Token、总费用\n- 趋势图表（Token + 费用曲线）、Provider / 模型分布饼图\n- 时间范围：当日 / 本周 / 本月 / 自定义日期\n\n#### 2. 实时对话（Chat）\n\n- Web 端直接聊天，Markdown + 代码高亮\n- CLI ↔ Web 双向实时同步\n- 工具调用可视化（名称、参数、结果、耗时）\n- 危险工具权限确认弹窗、用户问卷表单\n- 流式输出 + 思考中状态提示\n\n#### 3. 对话历史（Conversations）\n\n- 全量会话列表、消息回放、子 Agent 快照\n- 一键恢复对话、搜索过滤\n\n#### 4. Agent 网格（Agents）— A2A 协作视图\n\n- 本机活跃会话 + 远程已信任 Agent 的列表与拓扑图\n- 每个会话节点的**标准 A2A 端点浮层**（地址可复制、可打开真实 AgentCard）\n- **被调活动聚合**：谁正在/曾被谁调用，跨进程全景可见\n\n#### 5. 设置管理（Settings）\n\n- Provider 在线配置（apiKey / baseURL / 模型 / Vision 标记）\n- 模型拖拽排序、一键连通性测试\n- 保存后自动广播到所有 CLI 实例，无需重启\n- 计价规则 CRUD（四维价格 + 多币种）\n- 插件 & MCP Server 状态管理\n\n#### 6. 系统日志（Logs）\n\n- Agent 运行诊断、系统事件追踪\n\n**架构**：多 CLI 平等连接 → Bridge Server（纯路由器）→ Web SPA，按 sessionId 隔离。\n\n---\n\n## 核心能力\n\n### Agent 引擎\n\n- **多轮自动循环** — LLM → 工具执行 → 下一轮，AsyncGenerator 事件驱动\n- **内置工具集** — 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、远程 Agent 委托、任务管理\n- **并行工具执行** — 多个 tool_calls 自动并行，安全/危险分类策略\n- **子 Agent (SubAgent)** — general / explore / plan 三种类型，`Ctrl+B` 实时查看执行面板\n- **上下文管理** — `/compact` 三种压缩策略 + auto-compact\n\n### A2A 分布式 Agent 协作（1.0 新增）\n\n让多个 CCode 会话 / 外部 Agent 互相寻址、互相委托任务，并在界面上**双向可观测**——协作的两端都看得见。\n\n- **委托其他 Agent** — `dispatch_remote_agent` 工具把任务委托给本机其他会话或远程 A2A Agent，结果流式返回\n- **本机会话网格** — 每个会话自动起独立 A2A 节点（动态端口），基于 `~/.ccode/instances/` lockfile 自动发现，零配置；`/a2a list` 查看本机活跃会话\n- **标准 A2A Server** — 暴露符合 A2A 0.3.x 规范的端点，可被任意标准 A2A 客户端发现并调用：\n - `GET /.well-known/agent-card.json`（AgentCard，`preferredTransport: JSONRPC`）\n - `POST /` — JSON-RPC `message/send`、`message/stream`(SSE)\n - 任务生命周期 `tasks/get`、`tasks/cancel`、`tasks/resubscribe`\n- **双向可观测** — 调用方与被调方都以 SubAgent 卡片展示执行过程（CLI 状态卡 + Web 完整时间轴），状态栏轻量提示\"被调用\"，且**不打断主对话**\n- **信任白名单** — 远程 Agent 需 `/a2a add <url>` 显式信任后才能调用（安全底线）；本机会话同机受信，无需配置\n\n> 本机互调统一走 `127.0.0.1`。跨机器协作（局域网 IP + 鉴权）规划在后续版本。\n\n### 多模型运行时切换\n\n运行时 `/model` 一键切换，不重启、不丢上下文：\n\n| Provider | 协议 | 模型示例 |\n|----------|------|---------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash |\n| Ollama | OpenAI 兼容 | 任意本地模型 |\n| **任意服务** | OpenAI 兼容 | 配置 `baseURL` 即可接入 |\n\n### 对话持久化与恢复\n\n- **自动持久化** — 每次对话写入 JSONL 事件链\n- **会话恢复** — `ccode --resume` 或 `/resume` 面板恢复历史会话\n- **对话分支** — `/fork` 从任意节点创建新分支\n- **Web 恢复** — 历史页面一键恢复对话\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n### Token 计量与计费\n\n- 四维统计：input / output / cache_read / cache_write\n- 多币种（USD / CNY），按 provider + model 匹配计价规则\n- `/usage` 查看会话/今日/本月统计\n- Web Dashboard 趋势图表\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/.mcp.json（也会读取 ~/.claude.json、~/.mcp.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移方式：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/.mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/a2a` | — | A2A 远程 Agent 白名单（list / add / remove）+ 本机会话 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.yml` | Provider / Model / 记忆（旧 config.json 自动迁移） |\n| MCP | `~/.ccode/.mcp.json` | MCP Server 连接 |\n| A2A 白名单 | `~/.ccode/a2a-trusted.json` | 已信任的远程 A2A Agent |\n| A2A 节点发现 | `~/.ccode/instances/` | 本机会话 lockfile（自动写入/清理） |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n> 全部位于 `~/.ccode/`（可用 `CCODE_HOME` 环境变量重定向整个目录）。\n\n## 文档\n\n详细架构与能力文档见 [GitHub docs/](https://github.com/1207575273/CCode/tree/main/docs)\n\n## License\n\n[BSL 1.1](https://github.com/1207575273/CCode/blob/main/LICENSE) — 个人和非商业使用自由，商业使用需授权。\n"}, "e7a00a03a9e65cfdfeccbd383ca1836112f68b6b": {"t": 1785764470.496073, "n": 10219, "h": "cffd49522ded29b9", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型，内置 Web Dashboard 与 **A2A 分布式 Agent 协作**。\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](https://www.npmjs.com/package/ccode-cli)\n[](https://github.com/1207575273/CCode)\n\n## 安装\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.yml`（YAML 格式，支持注释），填入 API Key 即可使用：\n\n```yaml\ndefaultProvider: glm\ndefaultModel: glm-5\nproviders:\n glm:\n apiKey: your-api-key\n baseURL: https://open.bigmodel.cn/api/coding/paas/v4\n models:\n - glm-5\n - glm-4.7\n```\n\n> 本项目全程在智谱 GLM 模型下开发与测试。只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n> **从旧版升级**：早期版本用 `~/.ccode/config.json`。首次启动会**自动迁移**到 `config.yml`（写回校验无损后才切换），原文件备份为 `config.json.bak`，无需手动处理。\n>\n> **自定义配置根目录**：设置环境变量 `CCODE_HOME` 可把 `~/.ccode` 整体重定向到别处（用于多环境隔离 / 测试）。\n\n### config.yml 完整字段说明\n\n```yaml\n# ────── 全局设置 ──────\ndefaultProvider: glm # 默认使用的 Provider 名称（必须是下面 providers 的某个 key）\ndefaultModel: glm-5 # 默认模型（必须在对应 provider.models 列表中）\nsubAgentModel: glm-4.7 # [可选] 子 Agent 默认模型，可跨 Provider；留空则继承主 Agent\nstatusBar: true # [可选] 是否显示底部状态栏（token 消耗、模型名、A2A 状态等）\n\n# ────── Provider 配置 ──────\nproviders:\n <provider-name>: # 自定义名称，如 glm / anthropic / my-proxy\n apiKey: sk-xxx # [必填] API 密钥\n baseURL: https://... # [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n protocol: openai # [可选] 协议类型：openai(默认) | anthropic\n models: # [必填] 该 provider 可用的模型列表\n - model-a\n - model-b\n visionModels: # [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n - model-a\n\n# ────── 记忆系统（可选，RAG 向量检索）──────\nmemory:\n enabled: true\n embedding:\n apiKey: your-embedding-api-key\n baseURL: https://your-embedding-api-base-url/v4\n model: embedding-3\n dimension: 2048 # 向量维度，需与 embedding 模型匹配\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `subAgentModel` | string | 否 | 子 Agent 默认模型，可跨 Provider；留空继承主 Agent |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `openai`（默认）或 `anthropic`。仅 Anthropic 官方需设为 `anthropic` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空 |\n| `memory.enabled` | boolean | 否 | 是否开启 RAG 记忆系统 |\n| `memory.embedding.*` | object | 否 | embedding 向量服务配置（apiKey / baseURL / model / dimension） |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```yaml\ndefaultProvider: glm\ndefaultModel: glm-5\nproviders:\n glm:\n apiKey: your-zhipu-api-key\n baseURL: https://open.bigmodel.cn/api/coding/paas/v4\n models:\n - glm-5\n - glm-4.7\n anthropic:\n apiKey: sk-ant-xxx\n protocol: anthropic\n models:\n - claude-sonnet-4-20250514\n visionModels:\n - claude-sonnet-4-20250514\n deepseek:\n apiKey: sk-xxx\n baseURL: https://api.deepseek.com/v1\n models:\n - deepseek-chat\n - deepseek-reasoner\n openai:\n apiKey: sk-xxx\n models:\n - gpt-4o\n - gpt-4o-mini\n visionModels:\n - gpt-4o\n ollama:\n apiKey: ollama\n baseURL: http://localhost:11434/v1\n models:\n - qwen2.5:7b\n - deepseek-r1:14b\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web\n```\n\n浏览器打开 `http://localhost:9800`，获得 6 大管理页面：\n\n#### 1. 总览大盘（Overview）\n\n- 6 大核心指标卡片：调用次数、输入/输出/缓存 Token、总费用\n- 趋势图表（Token + 费用曲线）、Provider / 模型分布饼图\n- 时间范围：当日 / 本周 / 本月 / 自定义日期\n\n#### 2. 实时对话（Chat）\n\n- Web 端直接聊天，Markdown + 代码高亮\n- CLI ↔ Web 双向实时同步\n- 工具调用可视化（名称、参数、结果、耗时）\n- 危险工具权限确认弹窗、用户问卷表单\n- 流式输出 + 思考中状态提示\n\n#### 3. 对话历史（Conversations）\n\n- 全量会话列表、消息回放、子 Agent 快照\n- 一键恢复对话、搜索过滤\n\n#### 4. Agent 网格（Agents）— A2A 协作视图\n\n- 本机活跃会话 + 远程已信任 Agent 的列表与拓扑图\n- 每个会话节点的**标准 A2A 端点浮层**（地址可复制、可打开真实 AgentCard）\n- **被调活动聚合**：谁正在/曾被谁调用，跨进程全景可见\n\n#### 5. 设置管理（Settings）\n\n- Provider 在线配置（apiKey / baseURL / 模型 / Vision 标记）\n- 模型拖拽排序、一键连通性测试\n- 保存后自动广播到所有 CLI 实例，无需重启\n- 计价规则 CRUD（四维价格 + 多币种）\n- 插件 & MCP Server 状态管理\n\n#### 6. 系统日志（Logs）\n\n- Agent 运行诊断、系统事件追踪\n\n**架构**：多 CLI 平等连接 → Bridge Server（纯路由器）→ Web SPA，按 sessionId 隔离。\n\n---\n\n## 核心能力\n\n### Agent 引擎\n\n- **多轮自动循环** — LLM → 工具执行 → 下一轮，AsyncGenerator 事件驱动\n- **内置工具集** — 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、远程 Agent 委托、任务管理\n- **并行工具执行** — 多个 tool_calls 自动并行，安全/危险分类策略\n- **子 Agent (SubAgent)** — general / explore / plan 三种类型，`Ctrl+B` 实时查看执行面板\n- **上下文管理** — `/compact` 三种压缩策略 + auto-compact\n\n### A2A 分布式 Agent 协作（1.0 新增）\n\n让多个 CCode 会话 / 外部 Agent 互相寻址、互相委托任务，并在界面上**双向可观测**——协作的两端都看得见。\n\n- **委托其他 Agent** — `dispatch_remote_agent` 工具把任务委托给本机其他会话或远程 A2A Agent，结果流式返回\n- **本机会话网格** — 每个会话自动起独立 A2A 节点（动态端口），基于 `~/.ccode/instances/` lockfile 自动发现，零配置；`/a2a list` 查看本机活跃会话\n- **标准 A2A Server** — 暴露符合 A2A 0.3.x 规范的端点，可被任意标准 A2A 客户端发现并调用：\n - `GET /.well-known/agent-card.json`（AgentCard，`preferredTransport: JSONRPC`）\n - `POST /` — JSON-RPC `message/send`、`message/stream`(SSE)\n - 任务生命周期 `tasks/get`、`tasks/cancel`、`tasks/resubscribe`\n- **双向可观测** — 调用方与被调方都以 SubAgent 卡片展示执行过程（CLI 状态卡 + Web 完整时间轴），状态栏轻量提示\"被调用\"，且**不打断主对话**\n- **信任白名单** — 远程 Agent 需 `/a2a add <url>` 显式信任后才能调用（安全底线）；本机会话同机受信，无需配置\n\n> 本机互调统一走 `127.0.0.1`。跨机器协作（局域网 IP + 鉴权）规划在后续版本。\n\n### 多模型运行时切换\n\n运行时 `/model` 一键切换，不重启、不丢上下文：\n\n| Provider | 协议 | 模型示例 |\n|----------|------|---------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash |\n| Ollama | OpenAI 兼容 | 任意本地模型 |\n| **任意服务** | OpenAI 兼容 | 配置 `baseURL` 即可接入 |\n\n### 对话持久化与恢复\n\n- **自动持久化** — 每次对话写入 JSONL 事件链\n- **会话恢复** — `ccode --resume` 或 `/resume` 面板恢复历史会话\n- **对话分支** — `/fork` 从任意节点创建新分支\n- **Web 恢复** — 历史页面一键恢复对话\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n### Token 计量与计费\n\n- 四维统计：input / output / cache_read / cache_write\n- 多币种（USD / CNY），按 provider + model 匹配计价规则\n- `/usage` 查看会话/今日/本月统计\n- Web Dashboard 趋势图表\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/.mcp.json（也会读取 ~/.claude.json、~/.mcp.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移方式：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/.mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/a2a` | — | A2A 远程 Agent 白名单（list / add / remove）+ 本机会话 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.yml` | Provider / Model / 记忆（旧 config.json 自动迁移） |\n| MCP | `~/.ccode/.mcp.json` | MCP Server 连接 |\n| A2A 白名单 | `~/.ccode/a2a-trusted.json` | 已信任的远程 A2A Agent |\n| A2A 节点发现 | `~/.ccode/instances/` | 本机会话 lockfile（自动写入/清理） |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n> 全部位于 `~/.ccode/`（可用 `CCODE_HOME` 环境变量重定向整个目录）。\n\n## 文档\n\n详细架构与能力文档见 [GitHub docs/](https://github.com/1207575273/CCode/tree/main/docs)\n\n## License\n\n[BSL 1.1](https://github.com/1207575273/CCode/blob/main/LICENSE) — 个人和非商业使用自由，商业使用需授权。\n"}, "6aae8b0170a90928fad3b72ce582f17a07877041": {"t": 1785764471.7821429, "n": 8499, "h": "8a1d33c2ee5cf779", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](https://www.npmjs.com/package/ccode-cli)\n[](https://github.com/1207575273/CCode)\n\n## 安装\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`，填入 API Key 即可使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n> 本项目全程在智谱 GLM 模型下开发与测试。只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n### config.json 完整字段说明\n\n```jsonc\n{\n // ────── 全局设置 ──────\n \"defaultProvider\": \"glm\", // 默认使用的 Provider 名称\n \"defaultModel\": \"glm-5\", // 默认模型（必须在对应 provider.models 列表中）\n \"statusBar\": true, // 是否显示底部状态栏（token 消耗、模型名等）\n\n // ────── Provider 配置 ──────\n \"providers\": {\n \"<provider-name>\": { // 自定义名称，如 \"glm\"、\"anthropic\"、\"my-proxy\"\n \"apiKey\": \"sk-xxx\", // [必填] API 密钥\n \"baseURL\": \"https://...\", // [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n \"protocol\": \"openai\", // [可选] 协议类型：\"openai\"(默认) | \"anthropic\"\n \"models\": [\"model-a\", \"model-b\"], // [必填] 该 provider 可用的模型列表\n \"visionModels\": [\"model-a\"] // [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n }\n }\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"],\n \"visionModels\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"],\n \"visionModels\": [\"gpt-4o\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web\n```\n\n浏览器打开 `http://localhost:9800`，获得 5 大管理页面：\n\n#### 1. 总览大盘（Overview）\n\n- 6 大核心指标卡片：调用次数、输入/输出/缓存 Token、总费用\n- 趋势图表（Token + 费用曲线）、Provider / 模型分布饼图\n- 时间范围：当日 / 本周 / 本月 / 自定义日期\n\n#### 2. 实时对话（Chat）\n\n- Web 端直接聊天，Markdown + 代码高亮\n- CLI ↔ Web 双向实时同步\n- 工具调用可视化（名称、参数、结果、耗时）\n- 危险工具权限确认弹窗、用户问卷表单\n- 流式输出 + 思考中状态提示\n\n#### 3. 对话历史（Conversations）\n\n- 全量会话列表、消息回放、子 Agent 快照\n- 一键恢复对话、搜索过滤\n\n#### 4. 设置管理（Settings）\n\n- Provider 在线配置（apiKey / baseURL / 模型 / Vision 标记）\n- 模型拖拽排序、一键连通性测试\n- 保存后自动广播到所有 CLI 实例，无需重启\n- 计价规则 CRUD（四维价格 + 多币种）\n- 插件 & MCP Server 状态管理\n\n#### 5. 系统日志（Logs）\n\n- Agent 运行诊断、系统事件追踪\n\n**架构**：多 CLI 平等连接 → Bridge Server（纯路由器）→ Web SPA，按 sessionId 隔离。\n\n---\n\n## 核心能力\n\n### Agent 引擎\n\n- **多轮自动循环** — LLM → 工具执行 → 下一轮，AsyncGenerator 事件驱动\n- **16 个内置工具** — 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、任务管理\n- **并行工具执行** — 多个 tool_calls 自动并行，安全/危险分类策略\n- **子 Agent (SubAgent)** — general / explore / plan 三种类型，`Ctrl+B` 实时查看执行面板\n- **上下文管理** — `/compact` 三种压缩策略 + auto-compact\n\n### 多模型运行时切换\n\n运行时 `/model` 一键切换，不重启、不丢上下文：\n\n| Provider | 协议 | 模型示例 |\n|----------|------|---------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash |\n| Ollama | OpenAI 兼容 | 任意本地模型 |\n| **任意服务** | OpenAI 兼容 | 配置 `baseURL` 即可接入 |\n\n### 对话持久化与恢复\n\n- **自动持久化** — 每次对话写入 JSONL 事件链\n- **会话恢复** — `ccode --resume` 或 `/resume` 面板恢复历史会话\n- **对话分支** — `/fork` 从任意节点创建新分支\n- **Web 恢复** — 历史页面一键恢复对话\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n### Token 计量与计费\n\n- 四维统计：input / output / cache_read / cache_write\n- 多币种（USD / CNY），按 provider + model 匹配计价规则\n- `/usage` 查看会话/今日/本月统计\n- Web Dashboard 趋势图表\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移方式：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [GitHub docs/](https://github.com/1207575273/CCode/tree/main/docs)\n\n## License\n\n[BSL 1.1](https://github.com/1207575273/CCode/blob/main/LICENSE) — 个人和非商业使用自由，商业使用需授权。\n"}, "e4d375d0e15969d11015435fe5107560ff1504b9": {"t": 1785764473.0799265, "n": 8074, "h": "e9ce8cb4f2db7388", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](https://www.npmjs.com/package/ccode-cli)\n[](https://github.com/1207575273/CCode)\n\n## 安装\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`，填入 API Key 即可使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n> 本项目全程在智谱 GLM 模型下开发与测试。只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n### config.json 完整字段说明\n\n```jsonc\n{\n // ────── 全局设置 ──────\n \"defaultProvider\": \"glm\", // 默认使用的 Provider 名称\n \"defaultModel\": \"glm-5\", // 默认模型（必须在对应 provider.models 列表中）\n \"statusBar\": true, // 是否显示底部状态栏（token 消耗、模型名等）\n\n // ────── Provider 配置 ──────\n \"providers\": {\n \"<provider-name>\": { // 自定义名称，如 \"glm\"、\"anthropic\"、\"my-proxy\"\n \"apiKey\": \"sk-xxx\", // [必填] API 密钥\n \"baseURL\": \"https://...\", // [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n \"protocol\": \"openai\", // [可选] 协议类型：\"openai\"(默认) | \"anthropic\"\n \"models\": [\"model-a\", \"model-b\"], // [必填] 该 provider 可用的模型列表\n \"visionModels\": [\"model-a\"] // [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n }\n }\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"],\n \"visionModels\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"],\n \"visionModels\": [\"gpt-4o\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式\n\n```bash\nccode --web # 启动 CLI + Bridge Server + Web UI\n```\n\n浏览器打开 `http://localhost:9800`，提供：\n\n- **总览大盘** — Token 消耗/费用统计、趋势图表、模型分布\n- **实时对话** — Web 端聊天，消息/工具/权限双向实时同步\n- **对话历史** — 会话列表、消息回放、一键恢复对话\n- **设置管理** — Provider 配置、模型管理、计价规则、MCP 管理\n- **系统日志** — 诊断与调试\n\n多个 CLI 实例可同时连接同一个 Bridge Server，按 sessionId 隔离。\n\n---\n\n## 核心能力\n\n### Agent 引擎\n\n- **多轮自动循环** — LLM → 工具执行 → 下一轮，AsyncGenerator 事件驱动\n- **16 个内置工具** — 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、任务管理\n- **并行工具执行** — 多个 tool_calls 自动并行，安全/危险分类策略\n- **子 Agent (SubAgent)** — general / explore / plan 三种类型，`Ctrl+B` 实时查看执行面板\n- **上下文管理** — `/compact` 三种压缩策略 + auto-compact\n\n### 多模型运行时切换\n\n运行时 `/model` 一键切换，不重启、不丢上下文：\n\n| Provider | 协议 | 模型示例 |\n|----------|------|---------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash |\n| Ollama | OpenAI 兼容 | 任意本地模型 |\n| **任意服务** | OpenAI 兼容 | 配置 `baseURL` 即可接入 |\n\n### 对话持久化与恢复\n\n- **自动持久化** — 每次对话写入 JSONL 事件链\n- **会话恢复** — `ccode --resume` 或 `/resume` 面板恢复历史会话\n- **对话分支** — `/fork` 从任意节点创建新分支\n- **Web 恢复** — 历史页面一键恢复对话\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n### Token 计量与计费\n\n- 四维统计：input / output / cache_read / cache_write\n- 多币种（USD / CNY），按 provider + model 匹配计价规则\n- `/usage` 查看会话/今日/本月统计\n- Web Dashboard 趋势图表\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移方式：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [GitHub docs/](https://github.com/1207575273/CCode/tree/main/docs)\n\n## License\n\n[BSL 1.1](https://github.com/1207575273/CCode/blob/main/LICENSE) — 个人和非商业使用自由，商业使用需授权。\n"}, "d72b88e08955726da36208adf604c7a3fce9c4c1": {"t": 1785764474.3580463, "n": 6432, "h": "86af9f17ff101913", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](https://www.npmjs.com/package/ccode-cli)\n[](https://github.com/1207575273/CCode)\n\n## 安装\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`，填入 API Key 即可使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n> 本项目全程在智谱 GLM 模型下开发与测试。只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n<details>\n<summary>更多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"providers\": {\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式\n\n```bash\nccode --web # 启动 CLI + Bridge Server + Web UI\n```\n\n浏览器打开 `http://localhost:9800`，提供：\n\n- **总览大盘** — Token 消耗/费用统计、趋势图表、模型分布\n- **实时对话** — Web 端聊天，消息/工具/权限双向实时同步\n- **对话历史** — 会话列表、消息回放、一键恢复对话\n- **设置管理** — Provider 配置、模型管理、计价规则、MCP 管理\n- **系统日志** — 诊断与调试\n\n多个 CLI 实例可同时连接同一个 Bridge Server，按 sessionId 隔离。\n\n---\n\n## 核心能力\n\n### Agent 引擎\n\n- **多轮自动循环** — LLM → 工具执行 → 下一轮，AsyncGenerator 事件驱动\n- **16 个内置工具** — 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、任务管理\n- **并行工具执行** — 多个 tool_calls 自动并行，安全/危险分类策略\n- **子 Agent (SubAgent)** — general / explore / plan 三种类型，`Ctrl+B` 实时查看执行面板\n- **上下文管理** — `/compact` 三种压缩策略 + auto-compact\n\n### 多模型运行时切换\n\n运行时 `/model` 一键切换，不重启、不丢上下文：\n\n| Provider | 协议 | 模型示例 |\n|----------|------|---------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash |\n| Ollama | OpenAI 兼容 | 任意本地模型 |\n| **任意服务** | OpenAI 兼容 | 配置 `baseURL` 即可接入 |\n\n### 对话持久化与恢复\n\n- **自动持久化** — 每次对话写入 JSONL 事件链\n- **会话恢复** — `ccode --resume` 或 `/resume` 面板恢复历史会话\n- **对话分支** — `/fork` 从任意节点创建新分支\n- **Web 恢复** — 历史页面一键恢复对话\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n### Token 计量与计费\n\n- 四维统计：input / output / cache_read / cache_write\n- 多币种（USD / CNY），按 provider + model 匹配计价规则\n- `/usage` 查看会话/今日/本月统计\n- Web Dashboard 趋势图表\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移方式：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [GitHub docs/](https://github.com/1207575273/CCode/tree/main/docs)\n\n## License\n\n[BSL 1.1](https://github.com/1207575273/CCode/blob/main/LICENSE) — 个人和非商业使用自由，商业使用需授权。\n"}, "9b6c53f0c35ac21cf777cee5e0fa712d5ddcdb04": {"t": 1785764475.883356, "n": 2102, "h": "348e5c6f3e618931", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 Claude / OpenAI / GLM / DeepSeek / Ollama\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](https://www.npmjs.com/package/ccode-cli)\n[](https://github.com/1207575273/CCode)\n\n## 安装\n\n```bash\nnpm install -g ccode-cli\n```\n\n安装后执行 `ccode` 进入交互式对话。\n\n```bash\n# 或 npx 直接运行（不安装）\nnpx ccode-cli\n```\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`，填入你的 API Key 即可使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n支持任意 OpenAI 兼容协议的模型（GLM、DeepSeek、Ollama 等），也支持 Anthropic 原生协议（Claude）。\n\n## 核心能力\n\n- **多模型切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **16 个内置工具** — 文件读写、Shell 执行、代码搜索、子 Agent 派发、任务规划\n- **MCP 协议** — 动态注册外部工具（stdio / SSE / streamable-http）\n- **Skills 生态** — 对接 [skills.sh](https://skills.sh/) 275+ 开放 skill\n- **上下文管理** — `/compact` 三种压缩策略 + auto-compact\n- **对话持久化** — `--resume` 恢复历史会话 + `/fork` 分支\n- **SubAgent** — 后台并行运行，`Ctrl+B` 实时查看\n- **Claude Code 兼容** — CLAUDE.md、.mcp.json、插件目录零迁移\n\n## 快捷键\n\n| 操作 | 按键 | 备用按键 |\n|------|------|----------|\n| 提交输入 | Enter | — |\n| 换行（多行输入） | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到当前行首 | Home | Ctrl+A |\n| 跳到当前行尾 | End | Ctrl+E |\n| 查看 SubAgent 面板 | Ctrl+B | — |\n\n## 常用指令\n\n| 指令 | 说明 |\n|------|------|\n| `/model` | 切换模型 |\n| `/compact` | 压缩上下文 |\n| `/context` | 查看上下文使用率 |\n| `/resume` | 恢复历史会话 |\n| `/usage` | Token 用量统计 |\n| `/help` | 查看所有指令 |\n\n## 支持的模型\n\n| Provider | 模型 | 协议 |\n|----------|------|------|\n| Anthropic | Claude Opus/Sonnet/Haiku 4.x | Anthropic 原生 |\n| OpenAI | GPT-4o / GPT-4o-mini | OpenAI 兼容 |\n| 智谱 GLM | GLM-5 / GLM-4.7 | OpenAI 兼容 |\n| DeepSeek | deepseek-chat / deepseek-reasoner | OpenAI 兼容 |\n| Ollama | 任意本地模型 | OpenAI 兼容 |\n\n## 文档\n\n详细文档见 [GitHub](https://github.com/1207575273/CCode)\n\n## License\n\n[BSL 1.1](https://github.com/1207575273/CCode/blob/main/LICENSE) — 个人和非商业使用自由，商业使用需授权。\n"}, "7d27938d6e485118ce0fe0eecbec8969fcb6d9f0": {"t": 1785764477.0669188, "n": 1875, "h": "e38c63bbb636cd2b", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 Claude / OpenAI / GLM / DeepSeek / Ollama\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](https://www.npmjs.com/package/ccode-cli)\n[](https://github.com/1207575273/CCode)\n\n## 安装\n\n```bash\nnpm install -g ccode-cli\n```\n\n安装后执行 `ccode` 进入交互式对话。\n\n```bash\n# 或 npx 直接运行（不安装）\nnpx ccode-cli\n```\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`，填入你的 API Key 即可使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n支持任意 OpenAI 兼容协议的模型（GLM、DeepSeek、Ollama 等），也支持 Anthropic 原生协议（Claude）。\n\n## 核心能力\n\n- **多模型切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **16 个内置工具** — 文件读写、Shell 执行、代码搜索、子 Agent 派发、任务规划\n- **MCP 协议** — 动态注册外部工具（stdio / SSE / streamable-http）\n- **Skills 生态** — 对接 [skills.sh](https://skills.sh/) 275+ 开放 skill\n- **上下文管理** — `/compact` 三种压缩策略 + auto-compact\n- **对话持久化** — `--resume` 恢复历史会话 + `/fork` 分支\n- **SubAgent** — 后台并行运行，`Ctrl+B` 实时查看\n- **Claude Code 兼容** — CLAUDE.md、.mcp.json、插件目录零迁移\n\n## 常用指令\n\n| 指令 | 说明 |\n|------|------|\n| `/model` | 切换模型 |\n| `/compact` | 压缩上下文 |\n| `/context` | 查看上下文使用率 |\n| `/resume` | 恢复历史会话 |\n| `/usage` | Token 用量统计 |\n| `/help` | 查看所有指令 |\n\n## 支持的模型\n\n| Provider | 模型 | 协议 |\n|----------|------|------|\n| Anthropic | Claude Opus/Sonnet/Haiku 4.x | Anthropic 原生 |\n| OpenAI | GPT-4o / GPT-4o-mini | OpenAI 兼容 |\n| 智谱 GLM | GLM-5 / GLM-4.7 | OpenAI 兼容 |\n| DeepSeek | deepseek-chat / deepseek-reasoner | OpenAI 兼容 |\n| Ollama | 任意本地模型 | OpenAI 兼容 |\n\n## 文档\n\n详细文档见 [GitHub](https://github.com/1207575273/CCode)\n\n## License\n\n[BSL 1.1](https://github.com/1207575273/CCode/blob/main/LICENSE) — 个人和非商业使用自由，商业使用需授权。\n"}}, "README.md": {"77b80f9a4d92437741efa6136b6478bf10199ef5": {"t": 1785674072.0335696, "n": 14119, "h": "1115ee761a996928", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 已验证的生产力\n\n> 不是 demo 级别的玩具，是真正在**生产环境**跑出结果的工具。\n\nCCode 已在**多家企业**内部由一线工程师实际使用，独立完成真实业务需求开发：\n\n| 企业 | 行业 | 验证场景 | 模型 |\n|------|------|---------|------|\n| **某互联网大厂** | 在线教育 / 数字出版 | 企业级后台管理系统全链路需求开发 | GLM-5 |\n| **某 A 股上市公司** | 科技 | 前端 + 后端 + 复杂业务需求 | GLM-5 |\n| **CCode 自身** | 开源工具 | 用 CCode 开发 CCode（自举） | GLM-5 / GLM-4.7 |\n\n### 大厂实战案例：企业级后台系统需求交付\n\n以下截图来自**某互联网大厂**内部后台管理系统。工程师使用 CCode + GLM-5 独立完成了一个横跨多模块的\"资源语言\"特性开发 — 从列表筛选、详情展示、表单新增、批量操作到需求管理全链路，**一个人 + CCode 完成了原本需要多人协作的需求**：\n\n<table>\n<tr>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务1.png\" /><br/><sub>列表页：新增资源语言筛选项 + 批量设置入口</sub></td>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务2.png\" /><br/><sub>详情展开：教材语言字段展示 + 批量导出/Json导入</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务3.png\" /><br/><sub>新增表单：资源语言字段联动 + 提交确认逻辑</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务5.png\" /><br/><sub>需求管理：创建需求弹窗 + 多语言选项</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务6.png\" /><br/><sub>多步骤流程表单：需求提报编辑 + 语言联动</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务7.png\" /><br/><sub>需求列表：1646条数据 + 语言筛选 + 分页</sub></td>\n</tr>\n</table>\n\n### 自举案例：用 CCode 开发 CCode\n\nCCode 的 SubAgent 子 Agent 系统、Web Dashboard、记忆系统等核心模块，均由 CCode 自身驱动开发完成。以下是通过 Web Dashboard 会话回放功能录制的真实开发过程：\n\n<img src=\"./cases/001_CCode自举_用CCode开发SubAgent能力/自举开发过程回放.gif\" width=\"800\" />\n\n<sub>CCode 在 Web Dashboard 中回放自举开发 SubAgent 的完整会话过程 — 从分析需求、阅读代码、到实现功能全部由 Agent 自主完成</sub>\n\n**覆盖能力**：\n\n- **前端** — React / Vue 组件开发、复杂表单联动、列表筛选、弹窗交互、多步骤流程\n- **后端** — Java Spring Boot 服务、API 接口设计、数据库字段变更与迁移\n- **全链路** — 从数据库 → API → 前端页面的完整功能闭环，跨模块一致性保障\n\n> 完整案例见 [cases/](./cases/) 目录\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\nnpm install -g ccode-cli\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.yml`（YAML 格式，支持注释）。本项目全程在 **智谱 GLM** 下开发测试，最小配置：\n\n```yaml\ndefaultProvider: glm\ndefaultModel: glm-5\nsubAgentModel: glm-4.7 # [可选] 子 Agent 使用的模型，不配则继承主 Agent\nproviders:\n glm:\n apiKey: your-zhipu-api-key\n baseURL: https://open.bigmodel.cn/api/coding/paas/v4\n models:\n - glm-5\n - glm-4.7\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.yml`，替换 `your-zhipu-api-key`\n3. 启动 `ccode`，即可使用\n\n> 只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n> **从旧版升级**：早期版本用 `~/.ccode/config.json`，首次启动会**自动迁移**到 `config.yml`（写回校验无损后才切换），原文件备份为 `config.json.bak`。设置环境变量 `CCODE_HOME` 可把整个 `~/.ccode` 目录重定向到别处。\n\n### config.yml 完整字段说明\n\n```yaml\n# ────── 全局设置 ──────\ndefaultProvider: glm # 默认使用的 Provider 名称\ndefaultModel: glm-5 # 默认模型（必须在对应 provider.models 列表中）\nsubAgentModel: glm-4.7 # [可选] 子 Agent 独立模型，不配则继承主 Agent 当前模型\nstatusBar: true # 是否显示底部状态栏（token 消耗、模型名、A2A 状态等）\n\n# ────── Provider 配置 ──────\nproviders:\n <provider-name>: # 自定义名称，如 glm / anthropic / my-proxy\n apiKey: sk-xxx # [必填] API 密钥\n baseURL: https://... # [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n protocol: openai # [可选] 协议类型：openai(默认) | anthropic\n models: # [必填] 该 provider 可用的模型列表\n - model-a\n - model-b\n visionModels: # [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n - model-a\n\n# ────── 记忆系统（可选，RAG 向量检索）──────\nmemory:\n enabled: true\n embedding:\n apiKey: your-embedding-api-key\n baseURL: https://your-embedding-api-base-url/v4\n model: embedding-3\n dimension: 2048 # 向量维度，需与 embedding 模型匹配\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `subAgentModel` | string | 否 | 子 Agent 独立模型，不配则继承主 Agent 当前模型。模型优先级：LLM 显式指定 > `subAgentModel` > 继承父 Agent。必须在同 Provider 的 `models` 列表中 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```yaml\ndefaultProvider: glm\ndefaultModel: glm-5\nsubAgentModel: glm-4.7 # 子 Agent 用轻量模型，降低成本\nproviders:\n glm:\n apiKey: your-zhipu-api-key\n baseURL: https://open.bigmodel.cn/api/coding/paas/v4\n models:\n - glm-5\n - glm-4.7\n anthropic:\n apiKey: sk-ant-xxx\n protocol: anthropic\n models:\n - claude-sonnet-4-20250514\n visionModels:\n - claude-sonnet-4-20250514\n deepseek:\n apiKey: sk-xxx\n baseURL: https://api.deepseek.com/v1\n models:\n - deepseek-chat\n - deepseek-reasoner\n openai:\n apiKey: sk-xxx\n models:\n - gpt-4o\n - gpt-4o-mini\n visionModels:\n - gpt-4o\n ollama:\n apiKey: ollama\n baseURL: http://localhost:11434/v1\n models:\n - qwen2.5:7b\n - deepseek-r1:14b\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> 这是 CCode 与 Claude Code CLI 拉开差距的核心能力。Claude Code 是纯终端工具，没有可视化管理界面；CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web # 启动 CLI + Bridge Server + Web Dashboard\n```\n\n浏览器打开 `http://localhost:9800`，获得 6 大管理页面：\n\n<!-- 截图占位：你可以在 docs/res/ 下放截图，用 <img src=\"./docs/res/xxx.png\" width=\"800\" /> 引用 -->\n\n#### 1. 总览大盘（Overview）\n\n- **6 大核心指标卡片**：调用次数、输入/输出/缓存 Token、总费用\n- **趋势图表**：Token 消耗曲线 + 费用曲线，时间粒度自适应（当日按小时，周/月按天）\n- **分布分析**：Provider 分布饼图 + 模型分布饼图\n- **时间范围**：当日 / 本周 / 本月 / 自定义日期区间\n- **最近会话列表**：快速跳转到对话详情\n\n#### 2. 实时对话（Chat）\n\n- **Web 端直接聊天**：与 CLI 终端体验一致，支持 Markdown 渲染 + 代码高亮\n- **双向实时同步**：CLI 端输入 → Web 实时看到，Web 端输入 → CLI 实时响应\n- **工具执行可视化**：工具调用名称、参数、执行结果、耗时全部可视化展示\n- **权限确认弹窗**：危险工具（写文件、执行命令）在 Web 端弹窗确认，不用切回终端\n- **用户问卷表单**：Agent 发起的 ask_user_question 在 Web 端渲染为原生表单（单选/多选/文本）\n- **流式输出**：思考中状态提示 + 逐字流式渲染\n\n#### 3. 对话历史（Conversations）\n\n- **全量会话列表**：按时间倒序，展示 Provider、模型、Token 消耗、时长\n- **消息回放**：完整还原每轮对话，包括用户输入、助手回复、工具调用链\n- **子 Agent 快照**：展开查看子 Agent 的独立执行日志\n- **一键恢复对话**：点击 [恢复] 按钮，在当前 CLI 实例上继续历史会话\n- **搜索过滤**：按关键词搜索历史会话\n\n#### 4. Agent 网格（Agents）— A2A 协作视图\n\n- **本机活跃会话 + 远程已信任 Agent** 的列表与拓扑图\n- **标准 A2A 端点浮层**：点击会话节点查看它暴露的标准 A2A 端点（地址可复制、可打开真实 AgentCard）\n- **被调活动聚合**：谁正在/曾被谁调用，跨进程全景可见\n\n#### 5. 设置管理（Settings）\n\n- **Provider 配置 Tab**\n - 在线编辑 apiKey、baseURL、模型列表\n - 模型标签点击选中（指定测试模型）\n - 拖拽调整模型顺序\n - Vision 多模态标记（👁 标识支持图片理解的模型）\n - 一键连通性测试：选中模型 → 发送测试消息 → 15s 超时 → 返回成功/失败\n - **保存后实时广播**：所有连接的 CLI 实例自动热更新配置，无需重启\n\n- **计价规则 Tab**\n - CRUD 管理：provider + model_pattern 匹配规则\n - 四维价格：input / output / cache_read / cache_write\n - 多币种：USD / CNY\n - 优先级排序：精确匹配优先于通配符\n\n- **插件 & MCP Tab**\n - 查看已加载的 Runtime Plugin 列表、注册的工具和命令\n - MCP Server 连接状态、工具列表、错误信息\n\n#### 6. 系统日志（Logs）\n\n- Agent 运行诊断日志\n- 系统事件追踪\n\n#### 架构特点\n\n```\nBrowser (React SPA)\n ↕ WebSocket（实时双向）\nBridge Server (port 9800) — 纯消息路由器，不持有业务状态\n ↕ WebSocket ↕ WebSocket\nCLI-1 (session-aaa) CLI-2 (session-bbb)\n```\n\n- **多 CLI 平等连接**：多个终端实例同时连接同一个 Bridge Server\n- **Session 隔离**：每个 CLI 的 sessionId 独立，Web 端按需切换查看\n- **CLI 断连感知**：CLI 退出时 Web 端实时提示断开状态\n- **自动端口管理**：默认 9800，冲突自动递增（9801 → 9802），最多重试 3 次\n- **零配置启动**：`--web` 一个参数搞定，自动启动 HTTP Server + WebSocket + Vite HMR\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型运行时切换** | `/model` 一键切换，不重启、不丢上下文 |\n| **17 个内置工具** | 文件读写/编辑、glob/grep 搜索、bash 执行、git 深度集成、子 Agent 派发、任务管理 |\n| **子 Agent (SubAgent)** | general / explore / plan 三种类型，后台并行运行，`Ctrl+B` 实时面板，支持独立模型配置 |\n| **并行工具执行** | 多个 tool_calls 自动并行，安全/危险分类策略 |\n| **上下文管理** | `/compact` 三种压缩策略 + auto-compact + `/context` 查看使用率 |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 + Web 端一键恢复 |\n| **Token 计量** | 四维统计（input/output/cache_read/cache_write）+ 多币种计价 + `/usage` |\n| **A2A 分布式 Agent 协作** | 多会话/Agent 互相委托任务 + 标准 A2A Server 端点 + 双向可观测（详见下文） |\n\n### A2A 分布式 Agent 协作（1.0 新增）\n\n让多个 CCode 会话 / 外部 Agent 互相寻址、互相委托任务，并在界面上**双向可观测**——协作的两端都看得见。\n\n- **委托其他 Agent** — `dispatch_remote_agent` 工具把任务委托给本机其他会话或远程 A2A Agent，结果流式返回\n- **本机会话网格** — 每个会话自动起独立 A2A 节点（动态端口），基于 `~/.ccode/instances/` lockfile 自动发现，零配置；`/a2a list` 查看本机活跃会话\n- **标准 A2A Server** — 暴露符合 A2A 0.3.x 规范的端点，可被任意标准 A2A 客户端发现并调用：\n - `GET /.well-known/agent-card.json`（AgentCard，`preferredTransport: JSONRPC`）\n - `POST /` — JSON-RPC `message/send`、`message/stream`(SSE)\n - 任务生命周期 `tasks/get`、`tasks/cancel`、`tasks/resubscribe`\n- **双向可观测** — 调用方与被调方都以 SubAgent 卡片展示执行过程（CLI 状态卡 + Web 完整时间轴），状态栏轻量提示\"被调用\"，且**不打断主对话**\n- **信任白名单** — 远程 Agent 需 `/a2a add <url>` 显式信任后才能调用（安全底线）；本机会话同机受信，无需配置\n\n> 本机互调统一走 `127.0.0.1`。跨机器协作（局域网 IP + 鉴权）规划在后续版本。\n\n### 父子模型能力联动\n\n子 Agent 的模型选择支持三级优先级：\n\n1. **LLM 显式指定** — 派发时 `model` 参数指定具体模型\n2. **全局配置** — `config.yml` 中的 `subAgentModel` 字段\n3. **继承父 Agent** — 不配置时自动使用主 Agent 当前模型\n\n典型用法：主 Agent 用强模型（如 GLM-5）做决策和编排，子 Agent 用轻量模型（如 GLM-4.7）做搜索和文件操作，**同 Provider 内灵活切换、成本可控**。\n\n```yaml\ndefaultModel: glm-5 # 主 Agent：强模型，负责决策编排\nsubAgentModel: glm-4.7 # 子 Agent：轻量模型，负责执行任务\n```\n\n### Git 深度集成\n\n- **专用 Git 工具** — 13 个子命令（status / log / diff / branch / checkout / commit / merge / rebase / cherry_pick / stash / tag / reset / show），无需通过 bash 调用 git\n- **启动上下文注入** — 冷启动自动收集 Git 状态（当前分支、最近提交、工作区变更）注入 System Prompt\n- **安全防护** — 敏感文件自动拦截（.env / credentials.json / .pem / .key 等）、commit 消息 shell 注入防护\n- **非 Git 仓库感知** — 非 Git 目录启动时给出明确提示，而非静默忽略\n- **Bash 兜底** — 超出 git 工具覆盖范围的操作（如 push、interactive rebase）仍可通过 bash 工具完成\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n---\n\n## 支持的模型\n\n| Provider | 协议 | 模型示例 | 备注 |\n|----------|------|---------|------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 | **项目主力测试模型** |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x | 官方 SDK 直连 |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner | |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini | |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash | |\n| Ollama | OpenAI 兼容 | 任意本地模型 | 本地部署 |\n| **任意服务** | OpenAI 兼容 | — | 配置 `baseURL` 即可接入 |\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/.mcp.json（也会读取 ~/.claude.json、~/.mcp.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/.mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/a2a` | — | A2A 远程 Agent 白名单（list / add / remove）+ 本机会话 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.yml` | Provider / Model / 记忆（旧 config.json 自动迁移） |\n| MCP | `~/.ccode/.mcp.json` | MCP Server 连接 |\n| A2A 白名单 | `~/.ccode/a2a-trusted.json` | 已信任的远程 A2A Agent |\n| A2A 节点发现 | `~/.ccode/instances/` | 本机会话 lockfile（自动写入/清理） |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [docs/](./docs/)\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。历史配置文档见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "c40fa306d59f3988c65ecbb8c2256d4215648748": {"t": 1785764472.2557964, "n": 14119, "h": "1115ee761a996928", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 已验证的生产力\n\n> 不是 demo 级别的玩具，是真正在**生产环境**跑出结果的工具。\n\nCCode 已在**多家企业**内部由一线工程师实际使用，独立完成真实业务需求开发：\n\n| 企业 | 行业 | 验证场景 | 模型 |\n|------|------|---------|------|\n| **某互联网大厂** | 在线教育 / 数字出版 | 企业级后台管理系统全链路需求开发 | GLM-5 |\n| **某 A 股上市公司** | 科技 | 前端 + 后端 + 复杂业务需求 | GLM-5 |\n| **CCode 自身** | 开源工具 | 用 CCode 开发 CCode（自举） | GLM-5 / GLM-4.7 |\n\n### 大厂实战案例：企业级后台系统需求交付\n\n以下截图来自**某互联网大厂**内部后台管理系统。工程师使用 CCode + GLM-5 独立完成了一个横跨多模块的\"资源语言\"特性开发 — 从列表筛选、详情展示、表单新增、批量操作到需求管理全链路，**一个人 + CCode 完成了原本需要多人协作的需求**：\n\n<table>\n<tr>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务1.png\" /><br/><sub>列表页：新增资源语言筛选项 + 批量设置入口</sub></td>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务2.png\" /><br/><sub>详情展开：教材语言字段展示 + 批量导出/Json导入</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务3.png\" /><br/><sub>新增表单：资源语言字段联动 + 提交确认逻辑</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务5.png\" /><br/><sub>需求管理：创建需求弹窗 + 多语言选项</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务6.png\" /><br/><sub>多步骤流程表单：需求提报编辑 + 语言联动</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务7.png\" /><br/><sub>需求列表：1646条数据 + 语言筛选 + 分页</sub></td>\n</tr>\n</table>\n\n### 自举案例：用 CCode 开发 CCode\n\nCCode 的 SubAgent 子 Agent 系统、Web Dashboard、记忆系统等核心模块，均由 CCode 自身驱动开发完成。以下是通过 Web Dashboard 会话回放功能录制的真实开发过程：\n\n<img src=\"./cases/001_CCode自举_用CCode开发SubAgent能力/自举开发过程回放.gif\" width=\"800\" />\n\n<sub>CCode 在 Web Dashboard 中回放自举开发 SubAgent 的完整会话过程 — 从分析需求、阅读代码、到实现功能全部由 Agent 自主完成</sub>\n\n**覆盖能力**：\n\n- **前端** — React / Vue 组件开发、复杂表单联动、列表筛选、弹窗交互、多步骤流程\n- **后端** — Java Spring Boot 服务、API 接口设计、数据库字段变更与迁移\n- **全链路** — 从数据库 → API → 前端页面的完整功能闭环，跨模块一致性保障\n\n> 完整案例见 [cases/](./cases/) 目录\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\nnpm install -g ccode-cli\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.yml`（YAML 格式，支持注释）。本项目全程在 **智谱 GLM** 下开发测试，最小配置：\n\n```yaml\ndefaultProvider: glm\ndefaultModel: glm-5\nsubAgentModel: glm-4.7 # [可选] 子 Agent 使用的模型，不配则继承主 Agent\nproviders:\n glm:\n apiKey: your-zhipu-api-key\n baseURL: https://open.bigmodel.cn/api/coding/paas/v4\n models:\n - glm-5\n - glm-4.7\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.yml`，替换 `your-zhipu-api-key`\n3. 启动 `ccode`，即可使用\n\n> 只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n> **从旧版升级**：早期版本用 `~/.ccode/config.json`，首次启动会**自动迁移**到 `config.yml`（写回校验无损后才切换），原文件备份为 `config.json.bak`。设置环境变量 `CCODE_HOME` 可把整个 `~/.ccode` 目录重定向到别处。\n\n### config.yml 完整字段说明\n\n```yaml\n# ────── 全局设置 ──────\ndefaultProvider: glm # 默认使用的 Provider 名称\ndefaultModel: glm-5 # 默认模型（必须在对应 provider.models 列表中）\nsubAgentModel: glm-4.7 # [可选] 子 Agent 独立模型，不配则继承主 Agent 当前模型\nstatusBar: true # 是否显示底部状态栏（token 消耗、模型名、A2A 状态等）\n\n# ────── Provider 配置 ──────\nproviders:\n <provider-name>: # 自定义名称，如 glm / anthropic / my-proxy\n apiKey: sk-xxx # [必填] API 密钥\n baseURL: https://... # [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n protocol: openai # [可选] 协议类型：openai(默认) | anthropic\n models: # [必填] 该 provider 可用的模型列表\n - model-a\n - model-b\n visionModels: # [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n - model-a\n\n# ────── 记忆系统（可选，RAG 向量检索）──────\nmemory:\n enabled: true\n embedding:\n apiKey: your-embedding-api-key\n baseURL: https://your-embedding-api-base-url/v4\n model: embedding-3\n dimension: 2048 # 向量维度，需与 embedding 模型匹配\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `subAgentModel` | string | 否 | 子 Agent 独立模型，不配则继承主 Agent 当前模型。模型优先级：LLM 显式指定 > `subAgentModel` > 继承父 Agent。必须在同 Provider 的 `models` 列表中 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```yaml\ndefaultProvider: glm\ndefaultModel: glm-5\nsubAgentModel: glm-4.7 # 子 Agent 用轻量模型，降低成本\nproviders:\n glm:\n apiKey: your-zhipu-api-key\n baseURL: https://open.bigmodel.cn/api/coding/paas/v4\n models:\n - glm-5\n - glm-4.7\n anthropic:\n apiKey: sk-ant-xxx\n protocol: anthropic\n models:\n - claude-sonnet-4-20250514\n visionModels:\n - claude-sonnet-4-20250514\n deepseek:\n apiKey: sk-xxx\n baseURL: https://api.deepseek.com/v1\n models:\n - deepseek-chat\n - deepseek-reasoner\n openai:\n apiKey: sk-xxx\n models:\n - gpt-4o\n - gpt-4o-mini\n visionModels:\n - gpt-4o\n ollama:\n apiKey: ollama\n baseURL: http://localhost:11434/v1\n models:\n - qwen2.5:7b\n - deepseek-r1:14b\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> 这是 CCode 与 Claude Code CLI 拉开差距的核心能力。Claude Code 是纯终端工具，没有可视化管理界面；CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web # 启动 CLI + Bridge Server + Web Dashboard\n```\n\n浏览器打开 `http://localhost:9800`，获得 6 大管理页面：\n\n<!-- 截图占位：你可以在 docs/res/ 下放截图，用 <img src=\"./docs/res/xxx.png\" width=\"800\" /> 引用 -->\n\n#### 1. 总览大盘（Overview）\n\n- **6 大核心指标卡片**：调用次数、输入/输出/缓存 Token、总费用\n- **趋势图表**：Token 消耗曲线 + 费用曲线，时间粒度自适应（当日按小时，周/月按天）\n- **分布分析**：Provider 分布饼图 + 模型分布饼图\n- **时间范围**：当日 / 本周 / 本月 / 自定义日期区间\n- **最近会话列表**：快速跳转到对话详情\n\n#### 2. 实时对话（Chat）\n\n- **Web 端直接聊天**：与 CLI 终端体验一致，支持 Markdown 渲染 + 代码高亮\n- **双向实时同步**：CLI 端输入 → Web 实时看到，Web 端输入 → CLI 实时响应\n- **工具执行可视化**：工具调用名称、参数、执行结果、耗时全部可视化展示\n- **权限确认弹窗**：危险工具（写文件、执行命令）在 Web 端弹窗确认，不用切回终端\n- **用户问卷表单**：Agent 发起的 ask_user_question 在 Web 端渲染为原生表单（单选/多选/文本）\n- **流式输出**：思考中状态提示 + 逐字流式渲染\n\n#### 3. 对话历史（Conversations）\n\n- **全量会话列表**：按时间倒序，展示 Provider、模型、Token 消耗、时长\n- **消息回放**：完整还原每轮对话，包括用户输入、助手回复、工具调用链\n- **子 Agent 快照**：展开查看子 Agent 的独立执行日志\n- **一键恢复对话**：点击 [恢复] 按钮，在当前 CLI 实例上继续历史会话\n- **搜索过滤**：按关键词搜索历史会话\n\n#### 4. Agent 网格（Agents）— A2A 协作视图\n\n- **本机活跃会话 + 远程已信任 Agent** 的列表与拓扑图\n- **标准 A2A 端点浮层**：点击会话节点查看它暴露的标准 A2A 端点（地址可复制、可打开真实 AgentCard）\n- **被调活动聚合**：谁正在/曾被谁调用，跨进程全景可见\n\n#### 5. 设置管理（Settings）\n\n- **Provider 配置 Tab**\n - 在线编辑 apiKey、baseURL、模型列表\n - 模型标签点击选中（指定测试模型）\n - 拖拽调整模型顺序\n - Vision 多模态标记（👁 标识支持图片理解的模型）\n - 一键连通性测试：选中模型 → 发送测试消息 → 15s 超时 → 返回成功/失败\n - **保存后实时广播**：所有连接的 CLI 实例自动热更新配置，无需重启\n\n- **计价规则 Tab**\n - CRUD 管理：provider + model_pattern 匹配规则\n - 四维价格：input / output / cache_read / cache_write\n - 多币种：USD / CNY\n - 优先级排序：精确匹配优先于通配符\n\n- **插件 & MCP Tab**\n - 查看已加载的 Runtime Plugin 列表、注册的工具和命令\n - MCP Server 连接状态、工具列表、错误信息\n\n#### 6. 系统日志（Logs）\n\n- Agent 运行诊断日志\n- 系统事件追踪\n\n#### 架构特点\n\n```\nBrowser (React SPA)\n ↕ WebSocket（实时双向）\nBridge Server (port 9800) — 纯消息路由器，不持有业务状态\n ↕ WebSocket ↕ WebSocket\nCLI-1 (session-aaa) CLI-2 (session-bbb)\n```\n\n- **多 CLI 平等连接**：多个终端实例同时连接同一个 Bridge Server\n- **Session 隔离**：每个 CLI 的 sessionId 独立，Web 端按需切换查看\n- **CLI 断连感知**：CLI 退出时 Web 端实时提示断开状态\n- **自动端口管理**：默认 9800，冲突自动递增（9801 → 9802），最多重试 3 次\n- **零配置启动**：`--web` 一个参数搞定，自动启动 HTTP Server + WebSocket + Vite HMR\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型运行时切换** | `/model` 一键切换，不重启、不丢上下文 |\n| **17 个内置工具** | 文件读写/编辑、glob/grep 搜索、bash 执行、git 深度集成、子 Agent 派发、任务管理 |\n| **子 Agent (SubAgent)** | general / explore / plan 三种类型，后台并行运行，`Ctrl+B` 实时面板，支持独立模型配置 |\n| **并行工具执行** | 多个 tool_calls 自动并行，安全/危险分类策略 |\n| **上下文管理** | `/compact` 三种压缩策略 + auto-compact + `/context` 查看使用率 |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 + Web 端一键恢复 |\n| **Token 计量** | 四维统计（input/output/cache_read/cache_write）+ 多币种计价 + `/usage` |\n| **A2A 分布式 Agent 协作** | 多会话/Agent 互相委托任务 + 标准 A2A Server 端点 + 双向可观测（详见下文） |\n\n### A2A 分布式 Agent 协作（1.0 新增）\n\n让多个 CCode 会话 / 外部 Agent 互相寻址、互相委托任务，并在界面上**双向可观测**——协作的两端都看得见。\n\n- **委托其他 Agent** — `dispatch_remote_agent` 工具把任务委托给本机其他会话或远程 A2A Agent，结果流式返回\n- **本机会话网格** — 每个会话自动起独立 A2A 节点（动态端口），基于 `~/.ccode/instances/` lockfile 自动发现，零配置；`/a2a list` 查看本机活跃会话\n- **标准 A2A Server** — 暴露符合 A2A 0.3.x 规范的端点，可被任意标准 A2A 客户端发现并调用：\n - `GET /.well-known/agent-card.json`（AgentCard，`preferredTransport: JSONRPC`）\n - `POST /` — JSON-RPC `message/send`、`message/stream`(SSE)\n - 任务生命周期 `tasks/get`、`tasks/cancel`、`tasks/resubscribe`\n- **双向可观测** — 调用方与被调方都以 SubAgent 卡片展示执行过程（CLI 状态卡 + Web 完整时间轴），状态栏轻量提示\"被调用\"，且**不打断主对话**\n- **信任白名单** — 远程 Agent 需 `/a2a add <url>` 显式信任后才能调用（安全底线）；本机会话同机受信，无需配置\n\n> 本机互调统一走 `127.0.0.1`。跨机器协作（局域网 IP + 鉴权）规划在后续版本。\n\n### 父子模型能力联动\n\n子 Agent 的模型选择支持三级优先级：\n\n1. **LLM 显式指定** — 派发时 `model` 参数指定具体模型\n2. **全局配置** — `config.yml` 中的 `subAgentModel` 字段\n3. **继承父 Agent** — 不配置时自动使用主 Agent 当前模型\n\n典型用法：主 Agent 用强模型（如 GLM-5）做决策和编排，子 Agent 用轻量模型（如 GLM-4.7）做搜索和文件操作，**同 Provider 内灵活切换、成本可控**。\n\n```yaml\ndefaultModel: glm-5 # 主 Agent：强模型，负责决策编排\nsubAgentModel: glm-4.7 # 子 Agent：轻量模型，负责执行任务\n```\n\n### Git 深度集成\n\n- **专用 Git 工具** — 13 个子命令（status / log / diff / branch / checkout / commit / merge / rebase / cherry_pick / stash / tag / reset / show），无需通过 bash 调用 git\n- **启动上下文注入** — 冷启动自动收集 Git 状态（当前分支、最近提交、工作区变更）注入 System Prompt\n- **安全防护** — 敏感文件自动拦截（.env / credentials.json / .pem / .key 等）、commit 消息 shell 注入防护\n- **非 Git 仓库感知** — 非 Git 目录启动时给出明确提示，而非静默忽略\n- **Bash 兜底** — 超出 git 工具覆盖范围的操作（如 push、interactive rebase）仍可通过 bash 工具完成\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n---\n\n## 支持的模型\n\n| Provider | 协议 | 模型示例 | 备注 |\n|----------|------|---------|------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 | **项目主力测试模型** |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x | 官方 SDK 直连 |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner | |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini | |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash | |\n| Ollama | OpenAI 兼容 | 任意本地模型 | 本地部署 |\n| **任意服务** | OpenAI 兼容 | — | 配置 `baseURL` 即可接入 |\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/.mcp.json（也会读取 ~/.claude.json、~/.mcp.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/.mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/a2a` | — | A2A 远程 Agent 白名单（list / add / remove）+ 本机会话 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.yml` | Provider / Model / 记忆（旧 config.json 自动迁移） |\n| MCP | `~/.ccode/.mcp.json` | MCP Server 连接 |\n| A2A 白名单 | `~/.ccode/a2a-trusted.json` | 已信任的远程 A2A Agent |\n| A2A 节点发现 | `~/.ccode/instances/` | 本机会话 lockfile（自动写入/清理） |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [docs/](./docs/)\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。历史配置文档见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "f3bd48d81e720f16085a939303af243be9c026e0": {"t": 1785764473.9642358, "n": 12801, "h": "7e93cbcbed662d7c", "c": "# CCode\n1\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 已验证的生产力\n\n> 不是 demo 级别的玩具，是真正在**生产环境**跑出结果的工具。\n\nCCode 已在**多家企业**内部由一线工程师实际使用，独立完成真实业务需求开发：\n\n| 企业 | 行业 | 验证场景 | 模型 |\n|------|------|---------|------|\n| **某互联网大厂** | 在线教育 / 数字出版 | 企业级后台管理系统全链路需求开发 | GLM-5 |\n| **某 A 股上市公司** | 科技 | 前端 + 后端 + 复杂业务需求 | GLM-5 |\n| **CCode 自身** | 开源工具 | 用 CCode 开发 CCode（自举） | GLM-5 / GLM-4.7 |\n\n### 大厂实战案例：企业级后台系统需求交付\n\n以下截图来自**某互联网大厂**内部后台管理系统。工程师使用 CCode + GLM-5 独立完成了一个横跨多模块的\"资源语言\"特性开发 — 从列表筛选、详情展示、表单新增、批量操作到需求管理全链路，**一个人 + CCode 完成了原本需要多人协作的需求**：\n\n<table>\n<tr>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务1.png\" /><br/><sub>列表页：新增资源语言筛选项 + 批量设置入口</sub></td>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务2.png\" /><br/><sub>详情展开：教材语言字段展示 + 批量导出/Json导入</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务3.png\" /><br/><sub>新增表单：资源语言字段联动 + 提交确认逻辑</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务5.png\" /><br/><sub>需求管理：创建需求弹窗 + 多语言选项</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务6.png\" /><br/><sub>多步骤流程表单：需求提报编辑 + 语言联动</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务7.png\" /><br/><sub>需求列表：1646条数据 + 语言筛选 + 分页</sub></td>\n</tr>\n</table>\n\n### 自举案例：用 CCode 开发 CCode\n\nCCode 的 SubAgent 子 Agent 系统、Web Dashboard、记忆系统等核心模块，均由 CCode 自身驱动开发完成。以下是通过 Web Dashboard 会话回放功能录制的真实开发过程：\n\n<img src=\"./cases/001_CCode自举_用CCode开发SubAgent能力/自举开发过程回放.gif\" width=\"800\" />\n\n<sub>CCode 在 Web Dashboard 中回放自举开发 SubAgent 的完整会话过程 — 从分析需求、阅读代码、到实现功能全部由 Agent 自主完成</sub>\n\n**覆盖能力**：\n\n- **前端** — React / Vue 组件开发、复杂表单联动、列表筛选、弹窗交互、多步骤流程\n- **后端** — Java Spring Boot 服务、API 接口设计、数据库字段变更与迁移\n- **全链路** — 从数据库 → API → 前端页面的完整功能闭环，跨模块一致性保障\n\n> 完整案例见 [cases/](./cases/) 目录\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\nnpm install -g ccode-cli\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`。本项目全程在 **智谱 GLM** 下开发测试，最小配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"subAgentModel\": \"glm-4.7\", // [可选] 子 Agent 使用的模型，不配则继承主 Agent\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 `ccode`，即可使用\n\n> 只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n### config.json 完整字段说明\n\n```jsonc\n{\n // ────── 全局设置 ──────\n \"defaultProvider\": \"glm\", // 默认使用的 Provider 名称\n \"defaultModel\": \"glm-5\", // 默认模型（必须在对应 provider.models 列表中）\n \"subAgentModel\": \"glm-4.7\", // [可选] 子 Agent 独立模型，不配则继承主 Agent 当前模型\n \"statusBar\": true, // 是否显示底部状态栏（token 消耗、模型名等）\n\n // ────── Provider 配置 ──────\n \"providers\": {\n \"<provider-name>\": { // 自定义名称，如 \"glm\"、\"anthropic\"、\"my-proxy\"\n \"apiKey\": \"sk-xxx\", // [必填] API 密钥\n \"baseURL\": \"https://...\", // [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n \"protocol\": \"openai\", // [可选] 协议类型：\"openai\"(默认) | \"anthropic\"\n \"models\": [\"model-a\", \"model-b\"], // [必填] 该 provider 可用的模型列表\n \"visionModels\": [\"model-a\"] // [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n }\n }\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `subAgentModel` | string | 否 | 子 Agent 独立模型，不配则继承主 Agent 当前模型。模型优先级：LLM 显式指定 > `subAgentModel` > 继承父 Agent。必须在同 Provider 的 `models` 列表中 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"subAgentModel\": \"glm-4.7\", // 子 Agent 用轻量模型，降低成本\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"],\n \"visionModels\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"],\n \"visionModels\": [\"gpt-4o\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> 这是 CCode 与 Claude Code CLI 拉开差距的核心能力。Claude Code 是纯终端工具，没有可视化管理界面；CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web # 启动 CLI + Bridge Server + Web Dashboard\n```\n\n浏览器打开 `http://localhost:9800`，获得 5 大管理页面：\n\n<!-- 截图占位：你可以在 docs/res/ 下放截图，用 <img src=\"./docs/res/xxx.png\" width=\"800\" /> 引用 -->\n\n#### 1. 总览大盘（Overview）\n\n- **6 大核心指标卡片**：调用次数、输入/输出/缓存 Token、总费用\n- **趋势图表**：Token 消耗曲线 + 费用曲线，时间粒度自适应（当日按小时，周/月按天）\n- **分布分析**：Provider 分布饼图 + 模型分布饼图\n- **时间范围**：当日 / 本周 / 本月 / 自定义日期区间\n- **最近会话列表**：快速跳转到对话详情\n\n#### 2. 实时对话（Chat）\n\n- **Web 端直接聊天**：与 CLI 终端体验一致，支持 Markdown 渲染 + 代码高亮\n- **双向实时同步**：CLI 端输入 → Web 实时看到，Web 端输入 → CLI 实时响应\n- **工具执行可视化**：工具调用名称、参数、执行结果、耗时全部可视化展示\n- **权限确认弹窗**：危险工具（写文件、执行命令）在 Web 端弹窗确认，不用切回终端\n- **用户问卷表单**：Agent 发起的 ask_user_question 在 Web 端渲染为原生表单（单选/多选/文本）\n- **流式输出**：思考中状态提示 + 逐字流式渲染\n\n#### 3. 对话历史（Conversations）\n\n- **全量会话列表**：按时间倒序，展示 Provider、模型、Token 消耗、时长\n- **消息回放**：完整还原每轮对话，包括用户输入、助手回复、工具调用链\n- **子 Agent 快照**：展开查看子 Agent 的独立执行日志\n- **一键恢复对话**：点击 [恢复] 按钮，在当前 CLI 实例上继续历史会话\n- **搜索过滤**：按关键词搜索历史会话\n\n#### 4. 设置管理（Settings）\n\n- **Provider 配置 Tab**\n - 在线编辑 apiKey、baseURL、模型列表\n - 模型标签点击选中（指定测试模型）\n - 拖拽调整模型顺序\n - Vision 多模态标记（👁 标识支持图片理解的模型）\n - 一键连通性测试：选中模型 → 发送测试消息 → 15s 超时 → 返回成功/失败\n - **保存后实时广播**：所有连接的 CLI 实例自动热更新配置，无需重启\n\n- **计价规则 Tab**\n - CRUD 管理：provider + model_pattern 匹配规则\n - 四维价格：input / output / cache_read / cache_write\n - 多币种：USD / CNY\n - 优先级排序：精确匹配优先于通配符\n\n- **插件 & MCP Tab**\n - 查看已加载的 Runtime Plugin 列表、注册的工具和命令\n - MCP Server 连接状态、工具列表、错误信息\n\n#### 5. 系统日志（Logs）\n\n- Agent 运行诊断日志\n- 系统事件追踪\n\n#### 架构特点\n\n```\nBrowser (React SPA)\n ↕ WebSocket（实时双向）\nBridge Server (port 9800) — 纯消息路由器，不持有业务状态\n ↕ WebSocket ↕ WebSocket\nCLI-1 (session-aaa) CLI-2 (session-bbb)\n```\n\n- **多 CLI 平等连接**：多个终端实例同时连接同一个 Bridge Server\n- **Session 隔离**：每个 CLI 的 sessionId 独立，Web 端按需切换查看\n- **CLI 断连感知**：CLI 退出时 Web 端实时提示断开状态\n- **自动端口管理**：默认 9800，冲突自动递增（9801 → 9802），最多重试 3 次\n- **零配置启动**：`--web` 一个参数搞定，自动启动 HTTP Server + WebSocket + Vite HMR\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型运行时切换** | `/model` 一键切换，不重启、不丢上下文 |\n| **17 个内置工具** | 文件读写/编辑、glob/grep 搜索、bash 执行、git 深度集成、子 Agent 派发、任务管理 |\n| **子 Agent (SubAgent)** | general / explore / plan 三种类型，后台并行运行，`Ctrl+B` 实时面板，支持独立模型配置 |\n| **并行工具执行** | 多个 tool_calls 自动并行，安全/危险分类策略 |\n| **上下文管理** | `/compact` 三种压缩策略 + auto-compact + `/context` 查看使用率 |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 + Web 端一键恢复 |\n| **Token 计量** | 四维统计（input/output/cache_read/cache_write）+ 多币种计价 + `/usage` |\n\n### 父子模型能力联动\n\n子 Agent 的模型选择支持三级优先级：\n\n1. **LLM 显式指定** — 派发时 `model` 参数指定具体模型\n2. **全局配置** — `config.json` 中的 `subAgentModel` 字段\n3. **继承父 Agent** — 不配置时自动使用主 Agent 当前模型\n\n典型用法：主 Agent 用强模型（如 GLM-5）做决策和编排，子 Agent 用轻量模型（如 GLM-4.7）做搜索和文件操作，**同 Provider 内灵活切换、成本可控**。\n\n```jsonc\n{\n \"defaultModel\": \"glm-5\", // 主 Agent：强模型，负责决策编排\n \"subAgentModel\": \"glm-4.7\" // 子 Agent：轻量模型，负责执行任务\n}\n```\n\n### Git 深度集成\n\n- **专用 Git 工具** — 13 个子命令（status / log / diff / branch / checkout / commit / merge / rebase / cherry_pick / stash / tag / reset / show），无需通过 bash 调用 git\n- **启动上下文注入** — 冷启动自动收集 Git 状态（当前分支、最近提交、工作区变更）注入 System Prompt\n- **安全防护** — 敏感文件自动拦截（.env / credentials.json / .pem / .key 等）、commit 消息 shell 注入防护\n- **非 Git 仓库感知** — 非 Git 目录启动时给出明确提示，而非静默忽略\n- **Bash 兜底** — 超出 git 工具覆盖范围的操作（如 push、interactive rebase）仍可通过 bash 工具完成\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n---\n\n## 支持的模型\n\n| Provider | 协议 | 模型示例 | 备注 |\n|----------|------|---------|------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 | **项目主力测试模型** |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x | 官方 SDK 直连 |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner | |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini | |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash | |\n| Ollama | OpenAI 兼容 | 任意本地模型 | 本地部署 |\n| **任意服务** | OpenAI 兼容 | — | 配置 `baseURL` 即可接入 |\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json（兼容 ~/.claude.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [docs/](./docs/)\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。历史配置文档见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "bbdfb21e1f8af1539e78f764adc922bd387dcbb6": {"t": 1785764475.2467551, "n": 12800, "h": "b9067136b2704b94", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 已验证的生产力\n\n> 不是 demo 级别的玩具，是真正在**生产环境**跑出结果的工具。\n\nCCode 已在**多家企业**内部由一线工程师实际使用，独立完成真实业务需求开发：\n\n| 企业 | 行业 | 验证场景 | 模型 |\n|------|------|---------|------|\n| **某互联网大厂** | 在线教育 / 数字出版 | 企业级后台管理系统全链路需求开发 | GLM-5 |\n| **某 A 股上市公司** | 科技 | 前端 + 后端 + 复杂业务需求 | GLM-5 |\n| **CCode 自身** | 开源工具 | 用 CCode 开发 CCode（自举） | GLM-5 / GLM-4.7 |\n\n### 大厂实战案例：企业级后台系统需求交付\n\n以下截图来自**某互联网大厂**内部后台管理系统。工程师使用 CCode + GLM-5 独立完成了一个横跨多模块的\"资源语言\"特性开发 — 从列表筛选、详情展示、表单新增、批量操作到需求管理全链路，**一个人 + CCode 完成了原本需要多人协作的需求**：\n\n<table>\n<tr>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务1.png\" /><br/><sub>列表页：新增资源语言筛选项 + 批量设置入口</sub></td>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务2.png\" /><br/><sub>详情展开：教材语言字段展示 + 批量导出/Json导入</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务3.png\" /><br/><sub>新增表单：资源语言字段联动 + 提交确认逻辑</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务5.png\" /><br/><sub>需求管理：创建需求弹窗 + 多语言选项</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务6.png\" /><br/><sub>多步骤流程表单：需求提报编辑 + 语言联动</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务7.png\" /><br/><sub>需求列表：1646条数据 + 语言筛选 + 分页</sub></td>\n</tr>\n</table>\n\n### 自举案例：用 CCode 开发 CCode\n\nCCode 的 SubAgent 子 Agent 系统、Web Dashboard、记忆系统等核心模块，均由 CCode 自身驱动开发完成。以下是通过 Web Dashboard 会话回放功能录制的真实开发过程：\n\n<img src=\"./cases/001_CCode自举_用CCode开发SubAgent能力/自举开发过程回放.gif\" width=\"800\" />\n\n<sub>CCode 在 Web Dashboard 中回放自举开发 SubAgent 的完整会话过程 — 从分析需求、阅读代码、到实现功能全部由 Agent 自主完成</sub>\n\n**覆盖能力**：\n\n- **前端** — React / Vue 组件开发、复杂表单联动、列表筛选、弹窗交互、多步骤流程\n- **后端** — Java Spring Boot 服务、API 接口设计、数据库字段变更与迁移\n- **全链路** — 从数据库 → API → 前端页面的完整功能闭环，跨模块一致性保障\n\n> 完整案例见 [cases/](./cases/) 目录\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\nnpm install -g ccode-cli\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`。本项目全程在 **智谱 GLM** 下开发测试，最小配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"subAgentModel\": \"glm-4.7\", // [可选] 子 Agent 使用的模型，不配则继承主 Agent\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 `ccode`，即可使用\n\n> 只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n### config.json 完整字段说明\n\n```jsonc\n{\n // ────── 全局设置 ──────\n \"defaultProvider\": \"glm\", // 默认使用的 Provider 名称\n \"defaultModel\": \"glm-5\", // 默认模型（必须在对应 provider.models 列表中）\n \"subAgentModel\": \"glm-4.7\", // [可选] 子 Agent 独立模型，不配则继承主 Agent 当前模型\n \"statusBar\": true, // 是否显示底部状态栏（token 消耗、模型名等）\n\n // ────── Provider 配置 ──────\n \"providers\": {\n \"<provider-name>\": { // 自定义名称，如 \"glm\"、\"anthropic\"、\"my-proxy\"\n \"apiKey\": \"sk-xxx\", // [必填] API 密钥\n \"baseURL\": \"https://...\", // [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n \"protocol\": \"openai\", // [可选] 协议类型：\"openai\"(默认) | \"anthropic\"\n \"models\": [\"model-a\", \"model-b\"], // [必填] 该 provider 可用的模型列表\n \"visionModels\": [\"model-a\"] // [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n }\n }\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `subAgentModel` | string | 否 | 子 Agent 独立模型，不配则继承主 Agent 当前模型。模型优先级：LLM 显式指定 > `subAgentModel` > 继承父 Agent。必须在同 Provider 的 `models` 列表中 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"subAgentModel\": \"glm-4.7\", // 子 Agent 用轻量模型，降低成本\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"],\n \"visionModels\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"],\n \"visionModels\": [\"gpt-4o\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> 这是 CCode 与 Claude Code CLI 拉开差距的核心能力。Claude Code 是纯终端工具，没有可视化管理界面；CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web # 启动 CLI + Bridge Server + Web Dashboard\n```\n\n浏览器打开 `http://localhost:9800`，获得 5 大管理页面：\n\n<!-- 截图占位：你可以在 docs/res/ 下放截图，用 <img src=\"./docs/res/xxx.png\" width=\"800\" /> 引用 -->\n\n#### 1. 总览大盘（Overview）\n\n- **6 大核心指标卡片**：调用次数、输入/输出/缓存 Token、总费用\n- **趋势图表**：Token 消耗曲线 + 费用曲线，时间粒度自适应（当日按小时，周/月按天）\n- **分布分析**：Provider 分布饼图 + 模型分布饼图\n- **时间范围**：当日 / 本周 / 本月 / 自定义日期区间\n- **最近会话列表**：快速跳转到对话详情\n\n#### 2. 实时对话（Chat）\n\n- **Web 端直接聊天**：与 CLI 终端体验一致，支持 Markdown 渲染 + 代码高亮\n- **双向实时同步**：CLI 端输入 → Web 实时看到，Web 端输入 → CLI 实时响应\n- **工具执行可视化**：工具调用名称、参数、执行结果、耗时全部可视化展示\n- **权限确认弹窗**：危险工具（写文件、执行命令）在 Web 端弹窗确认，不用切回终端\n- **用户问卷表单**：Agent 发起的 ask_user_question 在 Web 端渲染为原生表单（单选/多选/文本）\n- **流式输出**：思考中状态提示 + 逐字流式渲染\n\n#### 3. 对话历史（Conversations）\n\n- **全量会话列表**：按时间倒序，展示 Provider、模型、Token 消耗、时长\n- **消息回放**：完整还原每轮对话，包括用户输入、助手回复、工具调用链\n- **子 Agent 快照**：展开查看子 Agent 的独立执行日志\n- **一键恢复对话**：点击 [恢复] 按钮，在当前 CLI 实例上继续历史会话\n- **搜索过滤**：按关键词搜索历史会话\n\n#### 4. 设置管理（Settings）\n\n- **Provider 配置 Tab**\n - 在线编辑 apiKey、baseURL、模型列表\n - 模型标签点击选中（指定测试模型）\n - 拖拽调整模型顺序\n - Vision 多模态标记（👁 标识支持图片理解的模型）\n - 一键连通性测试：选中模型 → 发送测试消息 → 15s 超时 → 返回成功/失败\n - **保存后实时广播**：所有连接的 CLI 实例自动热更新配置，无需重启\n\n- **计价规则 Tab**\n - CRUD 管理：provider + model_pattern 匹配规则\n - 四维价格：input / output / cache_read / cache_write\n - 多币种：USD / CNY\n - 优先级排序：精确匹配优先于通配符\n\n- **插件 & MCP Tab**\n - 查看已加载的 Runtime Plugin 列表、注册的工具和命令\n - MCP Server 连接状态、工具列表、错误信息\n\n#### 5. 系统日志（Logs）\n\n- Agent 运行诊断日志\n- 系统事件追踪\n\n#### 架构特点\n\n```\nBrowser (React SPA)\n ↕ WebSocket（实时双向）\nBridge Server (port 9800) — 纯消息路由器，不持有业务状态\n ↕ WebSocket ↕ WebSocket\nCLI-1 (session-aaa) CLI-2 (session-bbb)\n```\n\n- **多 CLI 平等连接**：多个终端实例同时连接同一个 Bridge Server\n- **Session 隔离**：每个 CLI 的 sessionId 独立，Web 端按需切换查看\n- **CLI 断连感知**：CLI 退出时 Web 端实时提示断开状态\n- **自动端口管理**：默认 9800，冲突自动递增（9801 → 9802），最多重试 3 次\n- **零配置启动**：`--web` 一个参数搞定，自动启动 HTTP Server + WebSocket + Vite HMR\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型运行时切换** | `/model` 一键切换，不重启、不丢上下文 |\n| **17 个内置工具** | 文件读写/编辑、glob/grep 搜索、bash 执行、git 深度集成、子 Agent 派发、任务管理 |\n| **子 Agent (SubAgent)** | general / explore / plan 三种类型，后台并行运行，`Ctrl+B` 实时面板，支持独立模型配置 |\n| **并行工具执行** | 多个 tool_calls 自动并行，安全/危险分类策略 |\n| **上下文管理** | `/compact` 三种压缩策略 + auto-compact + `/context` 查看使用率 |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 + Web 端一键恢复 |\n| **Token 计量** | 四维统计（input/output/cache_read/cache_write）+ 多币种计价 + `/usage` |\n\n### 父子模型能力联动\n\n子 Agent 的模型选择支持三级优先级：\n\n1. **LLM 显式指定** — 派发时 `model` 参数指定具体模型\n2. **全局配置** — `config.json` 中的 `subAgentModel` 字段\n3. **继承父 Agent** — 不配置时自动使用主 Agent 当前模型\n\n典型用法：主 Agent 用强模型（如 GLM-5）做决策和编排，子 Agent 用轻量模型（如 GLM-4.7）做搜索和文件操作，**同 Provider 内灵活切换、成本可控**。\n\n```jsonc\n{\n \"defaultModel\": \"glm-5\", // 主 Agent：强模型，负责决策编排\n \"subAgentModel\": \"glm-4.7\" // 子 Agent：轻量模型，负责执行任务\n}\n```\n\n### Git 深度集成\n\n- **专用 Git 工具** — 13 个子命令（status / log / diff / branch / checkout / commit / merge / rebase / cherry_pick / stash / tag / reset / show），无需通过 bash 调用 git\n- **启动上下文注入** — 冷启动自动收集 Git 状态（当前分支、最近提交、工作区变更）注入 System Prompt\n- **安全防护** — 敏感文件自动拦截（.env / credentials.json / .pem / .key 等）、commit 消息 shell 注入防护\n- **非 Git 仓库感知** — 非 Git 目录启动时给出明确提示，而非静默忽略\n- **Bash 兜底** — 超出 git 工具覆盖范围的操作（如 push、interactive rebase）仍可通过 bash 工具完成\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n---\n\n## 支持的模型\n\n| Provider | 协议 | 模型示例 | 备注 |\n|----------|------|---------|------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 | **项目主力测试模型** |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x | 官方 SDK 直连 |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner | |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini | |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash | |\n| Ollama | OpenAI 兼容 | 任意本地模型 | 本地部署 |\n| **任意服务** | OpenAI 兼容 | — | 配置 `baseURL` 即可接入 |\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json（兼容 ~/.claude.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [docs/](./docs/)\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。历史配置文档见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "5b2a59b1ae876795882955b741a3528dda1d362b": {"t": 1785764476.9930763, "n": 11608, "h": "e58c8a2c251498d6", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 已验证的生产力\n\n> 不是 demo 级别的玩具，是真正在**生产环境**跑出结果的工具。\n\nCCode 已在**多家企业**内部由一线工程师实际使用，独立完成真实业务需求开发：\n\n| 企业 | 行业 | 验证场景 | 模型 |\n|------|------|---------|------|\n| **某互联网大厂** | 在线教育 / 数字出版 | 企业级后台管理系统全链路需求开发 | GLM-5 |\n| **某 A 股上市公司** | 科技 | 前端 + 后端 + 复杂业务需求 | GLM-5 |\n| **CCode 自身** | 开源工具 | 用 CCode 开发 CCode（自举） | GLM-5 / GLM-4.7 |\n\n### 大厂实战案例：企业级后台系统需求交付\n\n以下截图来自**某互联网大厂**内部后台管理系统。工程师使用 CCode + GLM-5 独立完成了一个横跨多模块的\"资源语言\"特性开发 — 从列表筛选、详情展示、表单新增、批量操作到需求管理全链路，**一个人 + CCode 完成了原本需要多人协作的需求**：\n\n<table>\n<tr>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务1.png\" /><br/><sub>列表页：新增资源语言筛选项 + 批量设置入口</sub></td>\n<td width=\"50%\"><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务2.png\" /><br/><sub>详情展开：教材语言字段展示 + 批量导出/Json导入</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务3.png\" /><br/><sub>新增表单：资源语言字段联动 + 提交确认逻辑</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务5.png\" /><br/><sub>需求管理：创建需求弹窗 + 多语言选项</sub></td>\n</tr>\n<tr>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务6.png\" /><br/><sub>多步骤流程表单：需求提报编辑 + 语言联动</sub></td>\n<td><img src=\"./cases/002_某大厂_任务完成截图_分享案例/任务7.png\" /><br/><sub>需求列表：1646条数据 + 语言筛选 + 分页</sub></td>\n</tr>\n</table>\n\n### 自举案例：用 CCode 开发 CCode\n\nCCode 的 SubAgent 子 Agent 系统、Web Dashboard、记忆系统等核心模块，均由 CCode 自身驱动开发完成。以下是通过 Web Dashboard 会话回放功能录制的真实开发过程：\n\n<img src=\"./cases/001_CCode自举_用CCode开发SubAgent能力/自举开发过程回放.gif\" width=\"800\" />\n\n<sub>CCode 在 Web Dashboard 中回放自举开发 SubAgent 的完整会话过程 — 从分析需求、阅读代码、到实现功能全部由 Agent 自主完成</sub>\n\n**覆盖能力**：\n\n- **前端** — React / Vue 组件开发、复杂表单联动、列表筛选、弹窗交互、多步骤流程\n- **后端** — Java Spring Boot 服务、API 接口设计、数据库字段变更与迁移\n- **全链路** — 从数据库 → API → 前端页面的完整功能闭环，跨模块一致性保障\n\n> 完整案例见 [cases/](./cases/) 目录\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\nnpm install -g ccode-cli\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`。本项目全程在 **智谱 GLM** 下开发测试，最小配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 `ccode`，即可使用\n\n> 只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n### config.json 完整字段说明\n\n```jsonc\n{\n // ────── 全局设置 ──────\n \"defaultProvider\": \"glm\", // 默认使用的 Provider 名称\n \"defaultModel\": \"glm-5\", // 默认模型（必须在对应 provider.models 列表中）\n \"statusBar\": true, // 是否显示底部状态栏（token 消耗、模型名等）\n\n // ────── Provider 配置 ──────\n \"providers\": {\n \"<provider-name>\": { // 自定义名称，如 \"glm\"、\"anthropic\"、\"my-proxy\"\n \"apiKey\": \"sk-xxx\", // [必填] API 密钥\n \"baseURL\": \"https://...\", // [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n \"protocol\": \"openai\", // [可选] 协议类型：\"openai\"(默认) | \"anthropic\"\n \"models\": [\"model-a\", \"model-b\"], // [必填] 该 provider 可用的模型列表\n \"visionModels\": [\"model-a\"] // [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n }\n }\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"],\n \"visionModels\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"],\n \"visionModels\": [\"gpt-4o\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> 这是 CCode 与 Claude Code CLI 拉开差距的核心能力。Claude Code 是纯终端工具，没有可视化管理界面；CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web # 启动 CLI + Bridge Server + Web Dashboard\n```\n\n浏览器打开 `http://localhost:9800`，获得 5 大管理页面：\n\n<!-- 截图占位：你可以在 docs/res/ 下放截图，用 <img src=\"./docs/res/xxx.png\" width=\"800\" /> 引用 -->\n\n#### 1. 总览大盘（Overview）\n\n- **6 大核心指标卡片**：调用次数、输入/输出/缓存 Token、总费用\n- **趋势图表**：Token 消耗曲线 + 费用曲线，时间粒度自适应（当日按小时，周/月按天）\n- **分布分析**：Provider 分布饼图 + 模型分布饼图\n- **时间范围**：当日 / 本周 / 本月 / 自定义日期区间\n- **最近会话列表**：快速跳转到对话详情\n\n#### 2. 实时对话（Chat）\n\n- **Web 端直接聊天**：与 CLI 终端体验一致，支持 Markdown 渲染 + 代码高亮\n- **双向实时同步**：CLI 端输入 → Web 实时看到，Web 端输入 → CLI 实时响应\n- **工具执行可视化**：工具调用名称、参数、执行结果、耗时全部可视化展示\n- **权限确认弹窗**：危险工具（写文件、执行命令）在 Web 端弹窗确认，不用切回终端\n- **用户问卷表单**：Agent 发起的 ask_user_question 在 Web 端渲染为原生表单（单选/多选/文本）\n- **流式输出**：思考中状态提示 + 逐字流式渲染\n\n#### 3. 对话历史（Conversations）\n\n- **全量会话列表**：按时间倒序，展示 Provider、模型、Token 消耗、时长\n- **消息回放**：完整还原每轮对话，包括用户输入、助手回复、工具调用链\n- **子 Agent 快照**：展开查看子 Agent 的独立执行日志\n- **一键恢复对话**：点击 [恢复] 按钮，在当前 CLI 实例上继续历史会话\n- **搜索过滤**：按关键词搜索历史会话\n\n#### 4. 设置管理（Settings）\n\n- **Provider 配置 Tab**\n - 在线编辑 apiKey、baseURL、模型列表\n - 模型标签点击选中（指定测试模型）\n - 拖拽调整模型顺序\n - Vision 多模态标记（👁 标识支持图片理解的模型）\n - 一键连通性测试：选中模型 → 发送测试消息 → 15s 超时 → 返回成功/失败\n - **保存后实时广播**：所有连接的 CLI 实例自动热更新配置，无需重启\n\n- **计价规则 Tab**\n - CRUD 管理：provider + model_pattern 匹配规则\n - 四维价格：input / output / cache_read / cache_write\n - 多币种：USD / CNY\n - 优先级排序：精确匹配优先于通配符\n\n- **插件 & MCP Tab**\n - 查看已加载的 Runtime Plugin 列表、注册的工具和命令\n - MCP Server 连接状态、工具列表、错误信息\n\n#### 5. 系统日志（Logs）\n\n- Agent 运行诊断日志\n- 系统事件追踪\n\n#### 架构特点\n\n```\nBrowser (React SPA)\n ↕ WebSocket（实时双向）\nBridge Server (port 9800) — 纯消息路由器，不持有业务状态\n ↕ WebSocket ↕ WebSocket\nCLI-1 (session-aaa) CLI-2 (session-bbb)\n```\n\n- **多 CLI 平等连接**：多个终端实例同时连接同一个 Bridge Server\n- **Session 隔离**：每个 CLI 的 sessionId 独立，Web 端按需切换查看\n- **CLI 断连感知**：CLI 退出时 Web 端实时提示断开状态\n- **自动端口管理**：默认 9800，冲突自动递增（9801 → 9802），最多重试 3 次\n- **零配置启动**：`--web` 一个参数搞定，自动启动 HTTP Server + WebSocket + Vite HMR\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型运行时切换** | `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、任务管理 |\n| **子 Agent (SubAgent)** | general / explore / plan 三种类型，后台并行运行，`Ctrl+B` 实时面板 |\n| **并行工具执行** | 多个 tool_calls 自动并行，安全/危险分类策略 |\n| **上下文管理** | `/compact` 三种压缩策略 + auto-compact + `/context` 查看使用率 |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 + Web 端一键恢复 |\n| **Token 计量** | 四维统计（input/output/cache_read/cache_write）+ 多币种计价 + `/usage` |\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n---\n\n## 支持的模型\n\n| Provider | 协议 | 模型示例 | 备注 |\n|----------|------|---------|------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 | **项目主力测试模型** |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x | 官方 SDK 直连 |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner | |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini | |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash | |\n| Ollama | OpenAI 兼容 | 任意本地模型 | 本地部署 |\n| **任意服务** | OpenAI 兼容 | — | 配置 `baseURL` 即可接入 |\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json（兼容 ~/.claude.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [docs/](./docs/)\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。历史配置文档见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "6aae8b0170a90928fad3b72ce582f17a07877041": {"t": 1785764478.7588577, "n": 10216, "h": "d55c37e3286b52df", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 已验证的生产力\n\nCCode 已在**某互联网大厂**和**某 A 股上市公司**内部由一线工程师实际测试验证，覆盖以下场景并均可独立完成需求开发：\n\n- **前端项目** — React / Vue 组件开发、页面搭建、状态管理重构\n- **后端项目** — Java Spring Boot / Node.js 服务开发、API 设计、数据库变更\n- **复杂项目需求** — 跨模块联调、多服务协作、全栈功能交付\n\n> 真实案例见 [cases/](./cases/) 目录\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\nnpm install -g ccode-cli\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`。本项目全程在 **智谱 GLM** 下开发测试，最小配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 `ccode`，即可使用\n\n> 只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n### config.json 完整字段说明\n\n```jsonc\n{\n // ────── 全局设置 ──────\n \"defaultProvider\": \"glm\", // 默认使用的 Provider 名称\n \"defaultModel\": \"glm-5\", // 默认模型（必须在对应 provider.models 列表中）\n \"statusBar\": true, // 是否显示底部状态栏（token 消耗、模型名等）\n\n // ────── Provider 配置 ──────\n \"providers\": {\n \"<provider-name>\": { // 自定义名称，如 \"glm\"、\"anthropic\"、\"my-proxy\"\n \"apiKey\": \"sk-xxx\", // [必填] API 密钥\n \"baseURL\": \"https://...\", // [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n \"protocol\": \"openai\", // [可选] 协议类型：\"openai\"(默认) | \"anthropic\"\n \"models\": [\"model-a\", \"model-b\"], // [必填] 该 provider 可用的模型列表\n \"visionModels\": [\"model-a\"] // [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n }\n }\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"],\n \"visionModels\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"],\n \"visionModels\": [\"gpt-4o\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式（Claude Code 没有的能力）\n\n> 这是 CCode 与 Claude Code CLI 拉开差距的核心能力。Claude Code 是纯终端工具，没有可视化管理界面；CCode 自带完整的 Web Dashboard，让 AI Agent 的工作过程可观测、可管理、可协作。\n\n```bash\nccode --web # 启动 CLI + Bridge Server + Web Dashboard\n```\n\n浏览器打开 `http://localhost:9800`，获得 5 大管理页面：\n\n<!-- 截图占位：你可以在 docs/res/ 下放截图，用 <img src=\"./docs/res/xxx.png\" width=\"800\" /> 引用 -->\n\n#### 1. 总览大盘（Overview）\n\n- **6 大核心指标卡片**：调用次数、输入/输出/缓存 Token、总费用\n- **趋势图表**：Token 消耗曲线 + 费用曲线，时间粒度自适应（当日按小时，周/月按天）\n- **分布分析**：Provider 分布饼图 + 模型分布饼图\n- **时间范围**：当日 / 本周 / 本月 / 自定义日期区间\n- **最近会话列表**：快速跳转到对话详情\n\n#### 2. 实时对话（Chat）\n\n- **Web 端直接聊天**：与 CLI 终端体验一致，支持 Markdown 渲染 + 代码高亮\n- **双向实时同步**：CLI 端输入 → Web 实时看到，Web 端输入 → CLI 实时响应\n- **工具执行可视化**：工具调用名称、参数、执行结果、耗时全部可视化展示\n- **权限确认弹窗**：危险工具（写文件、执行命令）在 Web 端弹窗确认，不用切回终端\n- **用户问卷表单**：Agent 发起的 ask_user_question 在 Web 端渲染为原生表单（单选/多选/文本）\n- **流式输出**：思考中状态提示 + 逐字流式渲染\n\n#### 3. 对话历史（Conversations）\n\n- **全量会话列表**：按时间倒序，展示 Provider、模型、Token 消耗、时长\n- **消息回放**：完整还原每轮对话，包括用户输入、助手回复、工具调用链\n- **子 Agent 快照**：展开查看子 Agent 的独立执行日志\n- **一键恢复对话**：点击 [恢复] 按钮，在当前 CLI 实例上继续历史会话\n- **搜索过滤**：按关键词搜索历史会话\n\n#### 4. 设置管理（Settings）\n\n- **Provider 配置 Tab**\n - 在线编辑 apiKey、baseURL、模型列表\n - 模型标签点击选中（指定测试模型）\n - 拖拽调整模型顺序\n - Vision 多模态标记（👁 标识支持图片理解的模型）\n - 一键连通性测试：选中模型 → 发送测试消息 → 15s 超时 → 返回成功/失败\n - **保存后实时广播**：所有连接的 CLI 实例自动热更新配置，无需重启\n\n- **计价规则 Tab**\n - CRUD 管理：provider + model_pattern 匹配规则\n - 四维价格：input / output / cache_read / cache_write\n - 多币种：USD / CNY\n - 优先级排序：精确匹配优先于通配符\n\n- **插件 & MCP Tab**\n - 查看已加载的 Runtime Plugin 列表、注册的工具和命令\n - MCP Server 连接状态、工具列表、错误信息\n\n#### 5. 系统日志（Logs）\n\n- Agent 运行诊断日志\n- 系统事件追踪\n\n#### 架构特点\n\n```\nBrowser (React SPA)\n ↕ WebSocket（实时双向）\nBridge Server (port 9800) — 纯消息路由器，不持有业务状态\n ↕ WebSocket ↕ WebSocket\nCLI-1 (session-aaa) CLI-2 (session-bbb)\n```\n\n- **多 CLI 平等连接**：多个终端实例同时连接同一个 Bridge Server\n- **Session 隔离**：每个 CLI 的 sessionId 独立，Web 端按需切换查看\n- **CLI 断连感知**：CLI 退出时 Web 端实时提示断开状态\n- **自动端口管理**：默认 9800，冲突自动递增（9801 → 9802），最多重试 3 次\n- **零配置启动**：`--web` 一个参数搞定，自动启动 HTTP Server + WebSocket + Vite HMR\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型运行时切换** | `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、任务管理 |\n| **子 Agent (SubAgent)** | general / explore / plan 三种类型，后台并行运行，`Ctrl+B` 实时面板 |\n| **并行工具执行** | 多个 tool_calls 自动并行，安全/危险分类策略 |\n| **上下文管理** | `/compact` 三种压缩策略 + auto-compact + `/context` 查看使用率 |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 + Web 端一键恢复 |\n| **Token 计量** | 四维统计（input/output/cache_read/cache_write）+ 多币种计价 + `/usage` |\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n---\n\n## 支持的模型\n\n| Provider | 协议 | 模型示例 | 备注 |\n|----------|------|---------|------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 | **项目主力测试模型** |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x | 官方 SDK 直连 |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner | |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini | |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash | |\n| Ollama | OpenAI 兼容 | 任意本地模型 | 本地部署 |\n| **任意服务** | OpenAI 兼容 | — | 配置 `baseURL` 即可接入 |\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json（兼容 ~/.claude.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [docs/](./docs/)\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。历史配置文档见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "e4d375d0e15969d11015435fe5107560ff1504b9": {"t": 1785764480.1996212, "n": 8482, "h": "9c7bbe29f9a91759", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 已验证的生产力\n\nCCode 已在**某互联网大厂**和**某 A 股上市公司**内部由一线工程师实际测试验证，覆盖以下场景并均可独立完成需求开发：\n\n- **前端项目** — React / Vue 组件开发、页面搭建、状态管理重构\n- **后端项目** — Java Spring Boot / Node.js 服务开发、API 设计、数据库变更\n- **复杂项目需求** — 跨模块联调、多服务协作、全栈功能交付\n\n> 真实案例见 [cases/](./cases/) 目录\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\nnpm install -g ccode-cli\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`。本项目全程在 **智谱 GLM** 下开发测试，最小配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 `ccode`，即可使用\n\n> 只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n### config.json 完整字段说明\n\n```jsonc\n{\n // ────── 全局设置 ──────\n \"defaultProvider\": \"glm\", // 默认使用的 Provider 名称\n \"defaultModel\": \"glm-5\", // 默认模型（必须在对应 provider.models 列表中）\n \"statusBar\": true, // 是否显示底部状态栏（token 消耗、模型名等）\n\n // ────── Provider 配置 ──────\n \"providers\": {\n \"<provider-name>\": { // 自定义名称，如 \"glm\"、\"anthropic\"、\"my-proxy\"\n \"apiKey\": \"sk-xxx\", // [必填] API 密钥\n \"baseURL\": \"https://...\", // [可选] 自定义 API 端点（OpenAI 兼容协议必填）\n \"protocol\": \"openai\", // [可选] 协议类型：\"openai\"(默认) | \"anthropic\"\n \"models\": [\"model-a\", \"model-b\"], // [必填] 该 provider 可用的模型列表\n \"visionModels\": [\"model-a\"] // [可选] 支持图片理解的模型子集（默认空 = 全不支持）\n }\n }\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `defaultProvider` | string | 是 | 启动时默认使用的 Provider |\n| `defaultModel` | string | 是 | 启动时默认使用的模型 |\n| `statusBar` | boolean | 否 | 底部状态栏开关，默认 `true` |\n| `providers.<name>.apiKey` | string | 是 | API 密钥 |\n| `providers.<name>.baseURL` | string | 否 | 自定义端点。Anthropic 可省略，OpenAI 兼容协议必填 |\n| `providers.<name>.protocol` | string | 否 | `\"openai\"`（默认）或 `\"anthropic\"`。仅 Anthropic 官方需设为 `\"anthropic\"` |\n| `providers.<name>.models` | string[] | 是 | 可用模型列表，`/model` 切换时从此列表选择 |\n| `providers.<name>.visionModels` | string[] | 否 | 支持多模态图片理解的模型子集（必须是 `models` 的子集），默认空数组 |\n\n<details>\n<summary>多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"],\n \"visionModels\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"],\n \"visionModels\": [\"gpt-4o\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式\n\n```bash\nccode --web\n```\n\n浏览器打开 `http://localhost:9800`，提供：\n\n- **总览大盘** — Token 消耗/费用统计、趋势图表、模型分布\n- **实时对话** — Web 端聊天，消息/工具/权限双向实时同步\n- **对话历史** — 会话列表、消息回放、一键恢复对话\n- **设置管理** — Provider 配置、模型管理、计价规则、MCP 管理\n- **系统日志** — 诊断与调试\n\n多个 CLI 实例可同时连接同一个 Bridge Server，按 sessionId 隔离。\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型运行时切换** | `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、任务管理 |\n| **子 Agent (SubAgent)** | general / explore / plan 三种类型，后台并行运行，`Ctrl+B` 实时面板 |\n| **并行工具执行** | 多个 tool_calls 自动并行，安全/危险分类策略 |\n| **上下文管理** | `/compact` 三种压缩策略 + auto-compact + `/context` 查看使用率 |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 + Web 端一键恢复 |\n| **Token 计量** | 四维统计（input/output/cache_read/cache_write）+ 多币种计价 + `/usage` |\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n---\n\n## 支持的模型\n\n| Provider | 协议 | 模型示例 | 备注 |\n|----------|------|---------|------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 | **项目主力测试模型** |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x | 官方 SDK 直连 |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner | |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini | |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash | |\n| Ollama | OpenAI 兼容 | 任意本地模型 | 本地部署 |\n| **任意服务** | OpenAI 兼容 | — | 配置 `baseURL` 即可接入 |\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json（兼容 ~/.claude.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [docs/](./docs/)\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。历史配置文档见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "d72b88e08955726da36208adf604c7a3fce9c4c1": {"t": 1785764481.5463972, "n": 6840, "h": "b6a5c59219c44905", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 GLM / Claude / DeepSeek / GPT / Gemini / Ollama 及任意 OpenAI 兼容模型\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n## 已验证的生产力\n\nCCode 已在**某互联网大厂**和**某 A 股上市公司**内部由一线工程师实际测试验证，覆盖以下场景并均可独立完成需求开发：\n\n- **前端项目** — React / Vue 组件开发、页面搭建、状态管理重构\n- **后端项目** — Java Spring Boot / Node.js 服务开发、API 设计、数据库变更\n- **复杂项目需求** — 跨模块联调、多服务协作、全栈功能交付\n\n> 真实案例见 [cases/](./cases/) 目录\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\nnpm install -g ccode-cli\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 快速配置\n\n首次启动自动创建 `~/.ccode/config.json`。本项目全程在 **智谱 GLM** 下开发测试，最小配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 `ccode`，即可使用\n\n> 只要模型服务支持 **OpenAI Chat Completion** 或 **Anthropic Messages** 协议，配置 `baseURL` + `apiKey` 即可接入，无需任何代码改动。\n\n<details>\n<summary>更多 Provider 配置示例</summary>\n\n```jsonc\n{\n \"providers\": {\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxx\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-20250514\"]\n },\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n },\n \"ollama\": {\n \"apiKey\": \"ollama\",\n \"baseURL\": \"http://localhost:11434/v1\",\n \"models\": [\"qwen2.5:7b\", \"deepseek-r1:14b\"]\n }\n }\n}\n```\n\n</details>\n\n---\n\n## 三种运行模式\n\n### 交互模式（默认）\n\n```bash\nccode # 进入交互式终端对话\nccode --web # 交互模式 + Web Dashboard\nccode --resume # 恢复上一次会话\n```\n\n### 管道模式（非交互，适用于脚本 / CI）\n\n```bash\nccode \"这段代码有什么问题\" # 单次问答\ncat error.log | ccode \"分析这个错误日志\" # stdin 管道输入\nccode -p \"生成 API 文档\" --json # JSON 结构化输出\nccode \"跑测试并修复\" --yes # 自动批准工具（CI 场景）\nccode \"解释这个函数\" --no-tools # 纯对话，不调用工具\n```\n\n| 参数 | 说明 |\n|------|------|\n| `-p / --prompt` | 指定问题 |\n| `-m / --model` | 指定模型 |\n| `--provider` | 指定供应商 |\n| `--yes / -y` | 自动批准所有工具调用 |\n| `--no-tools` | 禁用工具，纯对话 |\n| `--json` | 结构化输出（response + usage + cost） |\n| `--verbose / -v` | stderr 输出工具执行进度 |\n\n### Web Dashboard 模式\n\n```bash\nccode --web\n```\n\n浏览器打开 `http://localhost:9800`，提供：\n\n- **总览大盘** — Token 消耗/费用统计、趋势图表、模型分布\n- **实时对话** — Web 端聊天，消息/工具/权限双向实时同步\n- **对话历史** — 会话列表、消息回放、一键恢复对话\n- **设置管理** — Provider 配置、模型管理、计价规则、MCP 管理\n- **系统日志** — 诊断与调试\n\n多个 CLI 实例可同时连接同一个 Bridge Server，按 sessionId 隔离。\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型运行时切换** | `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写/编辑、glob/grep 搜索、bash 执行、子 Agent 派发、任务管理 |\n| **子 Agent (SubAgent)** | general / explore / plan 三种类型，后台并行运行，`Ctrl+B` 实时面板 |\n| **并行工具执行** | 多个 tool_calls 自动并行，安全/危险分类策略 |\n| **上下文管理** | `/compact` 三种压缩策略 + auto-compact + `/context` 查看使用率 |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 + Web 端一键恢复 |\n| **Token 计量** | 四维统计（input/output/cache_read/cache_write）+ 多币种计价 + `/usage` |\n\n### Memory / RAG 记忆系统\n\n- **混合检索** — BM25 关键词 + 向量相似度，中文 jieba 分词\n- **双层存储** — `~/.ccode/memory/`（全局）+ `<项目>/.ccode/memory/`（项目级）\n- **LLM 工具** — `memory_write` / `memory_search` / `memory_delete`，Agent 自动读写\n- **命令管理** — `/remember` 查看、搜索、删除、重建索引\n- **System Prompt 注入** — 冷启动自动检索相关记忆注入上下文\n\n---\n\n## 支持的模型\n\n| Provider | 协议 | 模型示例 | 备注 |\n|----------|------|---------|------|\n| 智谱 GLM | OpenAI 兼容 | GLM-5 / GLM-4.7 | **项目主力测试模型** |\n| Anthropic | Anthropic 原生 | Claude Opus / Sonnet / Haiku 4.x | 官方 SDK 直连 |\n| DeepSeek | OpenAI 兼容 | deepseek-chat / deepseek-reasoner | |\n| OpenAI | OpenAI 兼容 | GPT-4o / GPT-4o-mini | |\n| Google Gemini | OpenAI 兼容 | gemini-2.5-pro / gemini-2.5-flash | |\n| Ollama | OpenAI 兼容 | 任意本地模型 | 本地部署 |\n| **任意服务** | OpenAI 兼容 | — | 配置 `baseURL` 即可接入 |\n\n---\n\n## 扩展生态\n\n### MCP 协议\n\n动态注册外部工具，支持 4 种传输：stdio / SSE / streamable-http / http\n\n```jsonc\n// ~/.ccode/mcp.json（兼容 ~/.claude.json）\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"my-mcp-server\"],\n \"transport\": \"stdio\"\n }\n }\n}\n```\n\n### Skills 系统（兼容 Claude Code Skill 生态）\n\n- 四源发现：内置 → 插件 → 用户级(`~/.ccode/skills/`) → 项目级(`<cwd>/.ccode/skills/`)\n- **SKILL.md 格式与 Claude Code 完全兼容**，社区 Skill（如 [skills.sh](https://skills.sh/) 275+ Skill）可直接使用\n- LLM 自动触发或 `/skills <name>` 手动调用\n\n> 迁移：将 Claude Code 的 `~/.claude/skills/` 复制到 `~/.ccode/skills/` 即可\n\n### Runtime Plugin\n\n```\n~/.ccode/plugins/<name>/runtime/index.js # 用户级\n<cwd>/.ccode/plugins/<name>/runtime/index.js # 项目级\n```\n\n扩展点：注册命令、工具、UI 按钮、状态栏、事件监听、持久化存储。\n\n### Hooks 事件钩子\n\n三层配置（项目 > 用户 > 插件），三类事件：\n\n| 事件 | 时机 | 用途 |\n|------|------|------|\n| SessionStart | 会话启动 | 注入上下文 |\n| PreToolUse | 工具调用前 | 权限控制、参数修改 |\n| PostToolUse | 工具执行后 | 日志、后处理 |\n\n---\n\n## Claude Code 兼容性\n\n| 特性 | CCode | Claude Code | 兼容 |\n|------|-------|------------|------|\n| 指令文件 | CCODE.md | CLAUDE.md | 两者均识别 |\n| MCP 配置 | ~/.ccode/mcp.json | ~/.claude.json | 均可读取 |\n| SKILL.md 格式 | 相同 | 相同 | 直接使用 |\n| 项目设置 | .ccode/settings.local.json | .claude/settings.local.json | 格式兼容 |\n\n---\n\n## 全部指令\n\n| 指令 | 别名 | 说明 |\n|------|------|------|\n| `/help` | — | 显示所有命令 |\n| `/model` | `/m` | 切换模型 |\n| `/clear` | — | 清空对话 |\n| `/compact` | — | 压缩上下文 |\n| `/context` | — | 上下文使用率 |\n| `/resume` | — | 恢复历史会话 |\n| `/fork` | — | 对话分支 |\n| `/usage` | `/cost` | Token 用量统计 |\n| `/gc` | `/cleanup` | 清理过期数据 |\n| `/skills` | `/skill` | Skills 管理 |\n| `/remember` | `/mem` | 记忆管理 |\n| `/mcp` | — | MCP 状态 |\n| `/bridge` | — | Bridge 管理 |\n| `/plugins` | — | 插件列表 |\n| `/exit` | `/quit` | 强制退出 |\n\n## 快捷键\n\n| 操作 | 按键 | 备用 |\n|------|------|------|\n| 提交输入 | Enter | — |\n| 换行 | Alt+Enter | Shift+Alt+Enter |\n| 光标移动 | ↑ ↓ ← → | — |\n| 跳到行首/行尾 | Home / End | Ctrl+A / Ctrl+E |\n| 中断流式 | Escape | Ctrl+C |\n| 强制退出 | Ctrl+C × 2 | /exit |\n| SubAgent 面板 | Ctrl+B | — |\n\n---\n\n## 配置文件一览\n\n| 文件 | 路径 | 用途 |\n|------|------|------|\n| 主配置 | `~/.ccode/config.json` | Provider / Model / Shell |\n| MCP | `~/.ccode/mcp.json` | MCP Server 连接 |\n| 指令文件 | CCODE.md / CLAUDE.md（多层级） | System Prompt 注入 |\n| 项目权限 | `<cwd>/.ccode/settings.local.json` | 工具白名单 |\n| Hooks | `hooks.json`（项目/用户/插件） | 事件钩子 |\n| 记忆 | `~/.ccode/memory/` + `<cwd>/.ccode/memory/` | RAG 记忆存储 |\n| 调试日志 | `<cwd>/.ccode/debug.log` | Debug 日志 |\n\n## 文档\n\n详细架构与能力文档见 [docs/](./docs/)\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。历史配置文档见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "e5d572eb4f927c77a55e51537d3ea3c4c64d12e1": {"t": 1785764482.9571803, "n": 3452, "h": "29e530bdb50bb45f", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 Claude / OpenAI / GLM / DeepSeek / Ollama，一个终端搞定所有模型。\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\n# 全局安装\nnpm install -g ccode-cli\n\n# 启动\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n### 使用示例\n\n```bash\n# 交互式对话\nccode\n\n# 单次提问（Pipe 模式）\nccode \"帮我看看这个项目的目录结构\"\n\n# 恢复上次会话\nccode --resume\n\n# 指定模型\nccode -m glm-5\n```\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型切换** | 运行时 `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写、Shell 执行、代码搜索、子 Agent 派发、任务规划 |\n| **MCP 协议** | stdio / SSE / streamable-http，动态注册外部工具 |\n| **Skills 生态** | 内置 + 项目级 + [skills.sh](https://skills.sh/) 市场一键安装 |\n| **上下文管理** | 实时使用率追踪 + `/compact` 三种压缩策略 + auto-compact |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 |\n| **SubAgent** | 后台并行运行 + CLI 悬浮面板（Ctrl+B）实时查看 |\n| **Token 计量** | 四维 token 统计 + 多币种计价 + `/usage` |\n| **Claude Code 兼容** | CLAUDE.md、.mcp.json、插件目录结构零迁移 |\n\n---\n\n## 配置\n\n首次启动自动创建 `~/.ccode/config.json`：\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\"]\n },\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 作为基准测试模型。最小化配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 CCode（`pnpm dev` 或 `ccode`），即可使用 GLM-5 进行对话和工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需声明 `protocol` 字段。运行时输入 `/model glm-4.7` 可切换模型。\n\n> 更多配置说明（MCP、指令文件、插件、Hooks、权限）见 [HISTORY_README.md](./HISTORY_README.md)\n\n---\n\n## 指令\n\n| 指令 | 说明 |\n|------|------|\n| `/model` | 交互式切换模型 |\n| `/compact` | 压缩上下文（支持 `--strategy` 选择策略） |\n| `/context` | 查看上下文窗口使用率 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/clear` | 清空当前对话 |\n| `/help` | 查看所有指令 |\n\n---\n\n## 支持的模型\n\n| Provider | 模型 | 协议 |\n|----------|------|------|\n| Anthropic | Claude Opus/Sonnet/Haiku 4.x | Anthropic 原生 |\n| OpenAI | GPT-4o / GPT-4o-mini | OpenAI 兼容 |\n| 智谱 GLM | GLM-5 / GLM-4.7 | OpenAI 兼容 |\n| DeepSeek | deepseek-chat / deepseek-reasoner | OpenAI 兼容 |\n| Ollama | 任意本地模型 | OpenAI 兼容 |\n| MiniMax | MiniMax-M2.5 | Anthropic 兼容 |\n\n---\n\n## 技术栈\n\n- **CLI**: TypeScript + Ink 5 + React 18\n- **Web**: Vite + Tailwind + React Router\n- **Agent**: 自研 AgentLoop（AsyncGenerator 事件流）\n- **持久化**: JSONL + libsql (SQLite)\n- **构建**: tsup (CLI) + Vite (Web)\n- **测试**: Vitest · 59 文件 · 453 用例\n\n---\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。完整的配置文档、插件系统、Hook 机制、权限管理等详细说明见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "374c8ce20d534e889f3b3ada88cde6639af6a83d": {"t": 1785764484.1599982, "n": 3501, "h": "a93959a78fa70a36", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 Claude / OpenAI / GLM / DeepSeek / Ollama，一个终端搞定所有模型。\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n```bash\nnpm install -g ccode-cli\n```\n\n---\n\n## 安装与使用\n\n### npm 安装（推荐）\n\n```bash\n# 全局安装\nnpm install -g ccode-cli\n\n# 启动\nccode\n```\n\n### npx 临时运行\n\n```bash\nnpx ccode-cli\n```\n\n### 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n### 使用示例\n\n```bash\n# 交互式对话\nccode\n\n# 单次提问（Pipe 模式）\nccode \"帮我看看这个项目的目录结构\"\n\n# 恢复上次会话\nccode --resume\n\n# 指定模型\nccode -m glm-5\n```\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型切换** | 运行时 `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写、Shell 执行、代码搜索、子 Agent 派发、任务规划 |\n| **MCP 协议** | stdio / SSE / streamable-http，动态注册外部工具 |\n| **Skills 生态** | 内置 + 项目级 + [skills.sh](https://skills.sh/) 市场一键安装 |\n| **上下文管理** | 实时使用率追踪 + `/compact` 三种压缩策略 + auto-compact |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 |\n| **SubAgent** | 后台并行运行 + CLI 悬浮面板（Ctrl+B）实时查看 |\n| **Web Dashboard** | `--web` 唤醒，对话/回放/设置/插件管理 |\n| **Token 计量** | 四维 token 统计 + 多币种计价 + `/usage` |\n| **Claude Code 兼容** | CLAUDE.md、.mcp.json、插件目录结构零迁移 |\n\n---\n\n## 配置\n\n首次启动自动创建 `~/.ccode/config.json`：\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\"]\n },\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 作为基准测试模型。最小化配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 CCode（`pnpm dev` 或 `ccode`），即可使用 GLM-5 进行对话和工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需声明 `protocol` 字段。运行时输入 `/model glm-4.7` 可切换模型。\n\n> 更多配置说明（MCP、指令文件、插件、Hooks、权限）见 [HISTORY_README.md](./HISTORY_README.md)\n\n---\n\n## 指令\n\n| 指令 | 说明 |\n|------|------|\n| `/model` | 交互式切换模型 |\n| `/compact` | 压缩上下文（支持 `--strategy` 选择策略） |\n| `/context` | 查看上下文窗口使用率 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/clear` | 清空当前对话 |\n| `/help` | 查看所有指令 |\n\n---\n\n## 支持的模型\n\n| Provider | 模型 | 协议 |\n|----------|------|------|\n| Anthropic | Claude Opus/Sonnet/Haiku 4.x | Anthropic 原生 |\n| OpenAI | GPT-4o / GPT-4o-mini | OpenAI 兼容 |\n| 智谱 GLM | GLM-5 / GLM-4.7 | OpenAI 兼容 |\n| DeepSeek | deepseek-chat / deepseek-reasoner | OpenAI 兼容 |\n| Ollama | 任意本地模型 | OpenAI 兼容 |\n| MiniMax | MiniMax-M2.5 | Anthropic 兼容 |\n\n---\n\n## 技术栈\n\n- **CLI**: TypeScript + Ink 5 + React 18\n- **Web**: Vite + Tailwind + React Router\n- **Agent**: 自研 AgentLoop（AsyncGenerator 事件流）\n- **持久化**: JSONL + libsql (SQLite)\n- **构建**: tsup (CLI) + Vite (Web)\n- **测试**: Vitest · 59 文件 · 453 用例\n\n---\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。完整的配置文档、插件系统、Hook 机制、权限管理等详细说明见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "94ee7a04372ee1ff64b4ad59caeb3ff17ba58138": {"t": 1785764485.6970854, "n": 3322, "h": "4d6ac14e9dddb304", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 Claude / OpenAI / GLM / DeepSeek / Ollama，一个终端搞定所有模型。\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n---\n\n## 安装\n\n```bash\n# npm 全局安装\nnpm install -g ccode-cli\n\n# 或 npx 直接运行\nnpx ccode-cli\n```\n\n安装后执行 `ccode` 进入交互式对话。\n\n## 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型切换** | 运行时 `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写、Shell 执行、代码搜索、子 Agent 派发、任务规划 |\n| **MCP 协议** | stdio / SSE / streamable-http，动态注册外部工具 |\n| **Skills 生态** | 内置 + 项目级 + [skills.sh](https://skills.sh/) 市场一键安装 |\n| **上下文管理** | 实时使用率追踪 + `/compact` 三种压缩策略 + auto-compact |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 |\n| **SubAgent** | 后台并行运行 + CLI 悬浮面板（Ctrl+B）实时查看 |\n| **Web Dashboard** | `--web` 唤醒，对话/回放/设置/插件管理 |\n| **Token 计量** | 四维 token 统计 + 多币种计价 + `/usage` |\n| **Claude Code 兼容** | CLAUDE.md、.mcp.json、插件目录结构零迁移 |\n\n---\n\n## 配置\n\n首次启动自动创建 `~/.ccode/config.json`：\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\"]\n },\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 作为基准测试模型。最小化配置：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key`\n3. 启动 CCode（`pnpm dev` 或 `ccode`），即可使用 GLM-5 进行对话和工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需声明 `protocol` 字段。运行时输入 `/model glm-4.7` 可切换模型。\n\n> 更多配置说明（MCP、指令文件、插件、Hooks、权限）见 [HISTORY_README.md](./HISTORY_README.md)\n\n---\n\n## 指令\n\n| 指令 | 说明 |\n|------|------|\n| `/model` | 交互式切换模型 |\n| `/compact` | 压缩上下文（支持 `--strategy` 选择策略） |\n| `/context` | 查看上下文窗口使用率 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/clear` | 清空当前对话 |\n| `/help` | 查看所有指令 |\n\n---\n\n## 支持的模型\n\n| Provider | 模型 | 协议 |\n|----------|------|------|\n| Anthropic | Claude Opus/Sonnet/Haiku 4.x | Anthropic 原生 |\n| OpenAI | GPT-4o / GPT-4o-mini | OpenAI 兼容 |\n| 智谱 GLM | GLM-5 / GLM-4.7 | OpenAI 兼容 |\n| DeepSeek | deepseek-chat / deepseek-reasoner | OpenAI 兼容 |\n| Ollama | 任意本地模型 | OpenAI 兼容 |\n| MiniMax | MiniMax-M2.5 | Anthropic 兼容 |\n\n---\n\n## 技术栈\n\n- **CLI**: TypeScript + Ink 5 + React 18\n- **Web**: Vite + Tailwind + React Router\n- **Agent**: 自研 AgentLoop（AsyncGenerator 事件流）\n- **持久化**: JSONL + libsql (SQLite)\n- **构建**: tsup (CLI) + Vite (Web)\n- **测试**: Vitest · 59 文件 · 453 用例\n\n---\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。完整的配置文档、插件系统、Hook 机制、权限管理等详细说明见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "a86576b567514c809f0e37139384d5893eb84444": {"t": 1785764487.2709215, "n": 2767, "h": "01f308b54b364d8d", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 Claude / OpenAI / GLM / DeepSeek / Ollama，一个终端搞定所有模型。\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n---\n\n## 安装\n\n```bash\n# npm 全局安装\nnpm install -g ccode-cli\n\n# 或 npx 直接运行\nnpx ccode-cli\n```\n\n安装后执行 `ccode` 进入交互式对话。\n\n## 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型切换** | 运行时 `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写、Shell 执行、代码搜索、子 Agent 派发、任务规划 |\n| **MCP 协议** | stdio / SSE / streamable-http，动态注册外部工具 |\n| **Skills 生态** | 内置 + 项目级 + [skills.sh](https://skills.sh/) 市场一键安装 |\n| **上下文管理** | 实时使用率追踪 + `/compact` 三种压缩策略 + auto-compact |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 |\n| **SubAgent** | 后台并行运行 + CLI 悬浮面板（Ctrl+B）实时查看 |\n| **Web Dashboard** | `--web` 唤醒，对话/回放/设置/插件管理 |\n| **Token 计量** | 四维 token 统计 + 多币种计价 + `/usage` |\n| **Claude Code 兼容** | CLAUDE.md、.mcp.json、插件目录结构零迁移 |\n\n---\n\n## 配置\n\n首次启动自动创建 `~/.ccode/config.json`：\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\"]\n },\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n> 更多配置说明（MCP、指令文件、插件、Hooks、权限）见 [HISTORY_README.md](./HISTORY_README.md)\n\n---\n\n## 指令\n\n| 指令 | 说明 |\n|------|------|\n| `/model` | 交互式切换模型 |\n| `/compact` | 压缩上下文（支持 `--strategy` 选择策略） |\n| `/context` | 查看上下文窗口使用率 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/clear` | 清空当前对话 |\n| `/help` | 查看所有指令 |\n\n---\n\n## 支持的模型\n\n| Provider | 模型 | 协议 |\n|----------|------|------|\n| Anthropic | Claude Opus/Sonnet/Haiku 4.x | Anthropic 原生 |\n| OpenAI | GPT-4o / GPT-4o-mini | OpenAI 兼容 |\n| 智谱 GLM | GLM-5 / GLM-4.7 | OpenAI 兼容 |\n| DeepSeek | deepseek-chat / deepseek-reasoner | OpenAI 兼容 |\n| Ollama | 任意本地模型 | OpenAI 兼容 |\n| MiniMax | MiniMax-M2.5 | Anthropic 兼容 |\n\n---\n\n## 技术栈\n\n- **CLI**: TypeScript + Ink 5 + React 18\n- **Web**: Vite + Tailwind + React Router\n- **Agent**: 自研 AgentLoop（AsyncGenerator 事件流）\n- **持久化**: JSONL + libsql (SQLite)\n- **构建**: tsup (CLI) + Vite (Web)\n- **测试**: Vitest · 59 文件 · 453 用例\n\n---\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n\n---\n\n> 本项目原名 ZCli / ZCode，2026-03-20 更名为 CCode。完整的配置文档、插件系统、Hook 机制、权限管理等详细说明见 [HISTORY_README.md](./HISTORY_README.md)。\n"}, "367872fe582b5eb07cc73783ccb4f01d274d160d": {"t": 1785764489.6316466, "n": 2645, "h": "031fbc5976047f89", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 支持 Claude / OpenAI / GLM / DeepSeek / Ollama，一个终端搞定所有模型。\n\n> **C** = **C**odeYang（作者）· **C**hina（中国开发者出品）· **C**ode Agent\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n---\n\n## 安装\n\n```bash\n# npm 全局安装\nnpm install -g ccode-cli\n\n# 或 npx 直接运行\nnpx ccode-cli\n```\n\n安装后执行 `ccode` 进入交互式对话。\n\n## 从源码运行\n\n```bash\ncd cCli\npnpm install\npnpm dev\n```\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| **多模型切换** | 运行时 `/model` 一键切换，不重启、不丢上下文 |\n| **16 个内置工具** | 文件读写、Shell 执行、代码搜索、子 Agent 派发、任务规划 |\n| **MCP 协议** | stdio / SSE / streamable-http，动态注册外部工具 |\n| **Skills 生态** | 内置 + 项目级 + [skills.sh](https://skills.sh/) 市场一键安装 |\n| **上下文管理** | 实时使用率追踪 + `/compact` 三种压缩策略 + auto-compact |\n| **对话持久化** | JSONL 会话 + `--resume` 恢复 + `/fork` 分支 |\n| **SubAgent** | 后台并行运行 + CLI 悬浮面板（Ctrl+B）实时查看 |\n| **Web Dashboard** | `--web` 唤醒，对话/回放/设置/插件管理 |\n| **Token 计量** | 四维 token 统计 + 多币种计价 + `/usage` |\n| **Claude Code 兼容** | CLAUDE.md、.mcp.json、插件目录结构零迁移 |\n\n---\n\n## 配置\n\n首次启动自动创建 `~/.ccode/config.json`：\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\"]\n },\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n> 更多配置说明（MCP、指令文件、插件、Hooks、权限）见 [HISTORY_README.md](./HISTORY_README.md)\n\n---\n\n## 指令\n\n| 指令 | 说明 |\n|------|------|\n| `/model` | 交互式切换模型 |\n| `/compact` | 压缩上下文（支持 `--strategy` 选择策略） |\n| `/context` | 查看上下文窗口使用率 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/clear` | 清空当前对话 |\n| `/help` | 查看所有指令 |\n\n---\n\n## 支持的模型\n\n| Provider | 模型 | 协议 |\n|----------|------|------|\n| Anthropic | Claude Opus/Sonnet/Haiku 4.x | Anthropic 原生 |\n| OpenAI | GPT-4o / GPT-4o-mini | OpenAI 兼容 |\n| 智谱 GLM | GLM-5 / GLM-4.7 | OpenAI 兼容 |\n| DeepSeek | deepseek-chat / deepseek-reasoner | OpenAI 兼容 |\n| Ollama | 任意本地模型 | OpenAI 兼容 |\n| MiniMax | MiniMax-M2.5 | Anthropic 兼容 |\n\n---\n\n## 技术栈\n\n- **CLI**: TypeScript + Ink 5 + React 18\n- **Web**: Vite + Tailwind + React Router\n- **Agent**: 自研 AgentLoop（AsyncGenerator 事件流）\n- **持久化**: JSONL + libsql (SQLite)\n- **构建**: tsup (CLI) + Vite (Web)\n- **测试**: Vitest · 59 文件 · 453 用例\n\n---\n\n## License\n\n[BSL 1.1](./LICENSE) — 个人和非商业使用自由，商业使用需授权。\n"}, "5b10d1f20245ad21119b4dc1a004556212ad9b7a": {"t": 1785764491.3690584, "n": 12907, "h": "a0d307a432aa0c1e", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 对标 Claude Code 的交互体验，不绑定单一 LLM 提供商。\n\n> **C** = **C**odeYang（作者）、**C**hina（中国开发者出品）、**C**ode（编程助手）\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n---\n\n## 项目背景\n\n### 改名说明\n\n本项目原名 **ZCli / ZCode**，于 2026 年 3 月更名为 **CCode**。\n\n更名原因：\n- 原名 ZCode 与多个已有项目重名，npm 上 `zcli` 也已被占用\n- **CCode** 的 **C** 寓意 **C**odeYang（作者英文名）、**C**hina（中国开发者出品）、**C**ode Agent\n- npm 包名：`ccode-cli`，安装后命令：`ccode`\n- 配置目录从 `~/.zcli/` 迁移至 `~/.ccode/`，指令文件从 `ZCLI.md` 改为 `CCODE.md`\n\n> 如果你之前使用过旧版，只需将 `~/.zcli/` 重命名为 `~/.ccode/` 即可平滑迁移。\n\n### 为什么做这个\n\nClaude Code 是目前最好的 AI 编程 CLI 工具，但它有一个硬约束：**只能用 Claude 模型**。对于需要在不同场景下切换模型的开发者来说，这意味着要在多个工具之间反复切换，丢失上下文和工作流的连贯性。\n\nCCode 的目标是：**让开发者在终端中自由选择 Claude / GPT / Gemini / GLM / DeepSeek / 本地 Ollama 等任意模型，获得一致的 AI 辅助编码体验。** 同时完全兼容 Claude Code 的生态（CLAUDE.md 指令文件、MCP 协议、插件系统）。\n\n### 核心理念\n\n- **多模型自由切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **Claude Code 生态兼容** — CLAUDE.md、.mcp.json、插件目录结构完全兼容，已有配置零迁移\n- **Agent 能力完整** — 工具调用、并行执行、子 Agent 派发、权限管控、会话持久化\n- **可观测** — Token 计量计费、结构化日志、Session JSONL 全量审计\n- **Web 能力** — CLI 和浏览器双向实时同步，同一对话两端共享\n\n### 当前状态\n\nCCode 处于活跃开发阶段（v0.0.1），核心 Agent 能力已稳定，日常用于驱动自身的开发（self-hosting）。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多模型支持 | Claude / OpenAI / Gemini / GLM / DeepSeek / Ollama，运行时切换 |\n| 内置工具集 | read / write / edit / glob / grep / bash + 子 Agent 派发 |\n| MCP 支持 | stdio / SSE / streamable-http，动态注册外部工具 |\n| Skills 系统 | 自研 Skill 体系 + 兼容 Claude Code 插件生态（superpowers 等） |\n| 对话持久化 | JSONL 会话文件 + --resume 恢复 + /fork 分支 |\n| Token 计量 | 四维 token 记录 + 多币种计价 + /usage 实时统计 |\n| 指令文件 | CCODE.md / CLAUDE.md 多层级注入，完全兼容 Claude Code |\n\n---\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n cCli/ # 项目代码\n src/ # 核心源码（Agent Loop / Tools / Providers / UI）\n tests/ # 测试\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd cCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/ccode.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `Escape` | 中断当前回复 |\n| `Ctrl+C` | 双击退出 |\n\n### 斜杠指令\n\n| 指令 | 说明 |\n|------|------|\n| `/help` | 查看所有指令 |\n| `/model` | 交互式切换模型 |\n| `/model <name>` | 直接切换到指定模型 |\n| `/clear` | 清空当前对话 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | 查看 MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/gc` | 清理过期会话和用量记录 |\n| `/gc --days 0` | 清理全部会话（保留 0 天） |\n| `/gc --dry-run` | 预览将清理的数据量 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nCCode 的配置文件位于 `~/.ccode/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.ccode/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 CCode（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nCCode 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nCCode 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.ccode/.mcp.json` | CCode 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.ccode/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（CCODE.md / CLAUDE.md）\n\nCCode 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `CCODE.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.ccode/CCODE.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/CCODE.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.ccode/CCODE.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/CCODE.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，CCode 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 CCode 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 CCode 定制不同于 Claude Code 的指令时，在同层级放一个 `CCODE.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.ccode/CCODE.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/CCODE.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`ccode \"问题\"`）均会加载指令文件\n\n---\n\n## 插件系统\n\nCCode 支持通过插件包扩展 Skill 能力，兼容 Claude Code 的插件生态（如 [superpowers](https://github.com/obra/superpowers)）。\n\n### 安装插件\n\n将插件目录复制到 `~/.ccode/plugins/` 下即可（目录名即为插件名）：\n\n```bash\n# 方式一：从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.ccode/plugins/superpowers\n\n# 方式二：直接复制已有目录\n# Linux / macOS\ncp -r /path/to/superpowers ~/.ccode/plugins/superpowers\n\n# Windows\nxcopy /E /I \"D:\\path\\to\\superpowers\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n```\n\n> 如果你已安装了 Claude Code 的 superpowers 插件，可以直接从缓存复制：\n> ```bash\n> # Windows\n> xcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n>\n> # Linux / macOS\n> cp -r ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.2 ~/.ccode/plugins/superpowers\n> ```\n\n项目级插件放在 `<项目根>/.ccode/plugins/` 下。\n\n### 插件目录结构\n\n```\n~/.ccode/plugins/\n └── superpowers/ ← 插件包名\n ├── skills/ ← skills 目录（必需）\n │ ├── brainstorming/\n │ │ ├── SKILL.md\n │ │ └── visual-companion.md ← 支撑文件\n │ ├── writing-plans/\n │ │ └── SKILL.md\n │ └── ...\n ├── hooks/ ← hooks 目录（可选）\n │ └── hooks.json\n └── plugin.json ← 插件清单（可选）\n```\n\n### 命名空间\n\n插件内的 Skill 自动添加 `<插件名>:` 前缀，避免与内置 Skill 冲突：\n\n| 来源 | 注册名示例 |\n|------|-----------|\n| 内置 Skill | `commit` |\n| 用户自定义 Skill | `my-tool` |\n| 插件 Skill | `superpowers:brainstorming` |\n\n**优先级**：项目级 > 用户级 > 插件 > 内置\n\n### 以 superpowers 为例\n\n```bash\n# 1. 安装：从 Claude Code 缓存复制（如果已安装 Claude Code superpowers 插件）\n# Windows\nxcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n\n# 或者从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.ccode/plugins/superpowers\n\n# 2. 启动 CCode，自动发现插件中的所有 Skills\npnpm dev\n```\n\n启动后 system prompt 中会包含 `superpowers:brainstorming`、`superpowers:writing-plans` 等 Skill 列表，LLM 会自动按需调用。\n\n---\n\n## Hook 系统\n\nCCode 支持事件钩子，可在会话启动、工具执行前后注入自定义逻辑。\n\n### 事件类型\n\n| 事件 | 触发时机 | 典型用途 |\n|------|----------|----------|\n| `SessionStart` | 会话启动 | 插件启动注入、环境检查 |\n| `PreToolUse` | 工具执行前 | 权限拦截、参数校验 |\n| `PostToolUse` | 工具执行后 | 结果审计、通知 |\n\n### 配置文件\n\nHook 配置来自三层来源（叠加执行，不覆盖）：\n\n| 来源 | 路径 |\n|------|------|\n| 插件包 | `~/.ccode/plugins/<name>/hooks/hooks.json` |\n| 项目级 | `<项目根>/.ccode/hooks.json` |\n| 用户级 | `~/.ccode/hooks.json` |\n\n### hooks.json 格式\n\n```jsonc\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"additionalContext\\\": \\\"hello from hook\\\"}'\",\n \"timeout\": 10000\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"decision\\\": \\\"allow\\\"}'\",\n \"timeout\": 5000\n }\n ]\n }\n ]\n }\n}\n```\n\n- `matcher`：正则表达式，匹配触发条件（SessionStart 匹配子类型，PreToolUse/PostToolUse 匹配工具名）\n- `timeout`：超时毫秒数，默认 10000\n- Hook 通过 stdout 输出 JSON 返回结果，超时或失败静默跳过\n\n> 插件包自带的 `hooks/hooks.json`（如 superpowers 的 SessionStart hook）会被自动发现和执行，无需手动配置。\n\n---\n\n## 项目级权限配置\n\nCCode 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.ccode/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.ccode/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph），AsyncGenerator 事件流架构\n- **持久化**：JSONL 会话文件 + libsql（SQLite）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "38a4a742b99b9849a26c8234980e0ba8cc4a39af": {"t": 1785764493.0277786, "n": 12907, "h": "3425c8c53a63315e", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 对标 Claude Code 的交互体验，不绑定单一 LLM 提供商。\n\n> **C** = **C**odeYang（作者）、**C**hina（中国开发者出品）、**C**ode（编程助手）\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n---\n\n## 项目背景\n\n### 改名说明\n\n本项目原名 **ZCli / ZCode**，于 2026 年 3 月更名为 **CCode**。\n\n更名原因：\n- 原名 ZCode 与多个已有项目重名，npm 上 `zcli` 也已被占用\n- **CCode** 的 **C** 寓意 **C**odeYang（作者英文名）、**C**hina（中国开发者出品）、**C**ode Agent\n- npm 包名：`ccode-cli`，安装后命令：`ccode`\n- 配置目录从 `~/.zcli/` 迁移至 `~/.ccode/`，指令文件从 `ZCLI.md` 改为 `CCODE.md`\n\n> 如果你之前使用过旧版，只需将 `~/.zcli/` 重命名为 `~/.ccode/` 即可平滑迁移。\n\n### 为什么做这个\n\nClaude Code 是目前最好的 AI 编程 CLI 工具，但它有一个硬约束：**只能用 Claude 模型**。对于需要在不同场景下切换模型的开发者来说，这意味着要在多个工具之间反复切换，丢失上下文和工作流的连贯性。\n\nCCode 的目标是：**让开发者在终端中自由选择 Claude / GPT / Gemini / GLM / DeepSeek / 本地 Ollama 等任意模型，获得一致的 AI 辅助编码体验。** 同时完全兼容 Claude Code 的生态（CLAUDE.md 指令文件、MCP 协议、插件系统）。\n\n### 核心理念\n\n- **多模型自由切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **Claude Code 生态兼容** — CLAUDE.md、.mcp.json、插件目录结构完全兼容，已有配置零迁移\n- **Agent 能力完整** — 工具调用、并行执行、子 Agent 派发、权限管控、会话持久化\n- **可观测** — Token 计量计费、结构化日志、Session JSONL 全量审计\n- **Web 能力** — CLI 和浏览器双向实时同步，同一对话两端共享\n\n### 当前状态\n\nCCode 处于活跃开发阶段（v0.0.1），核心 Agent 能力已稳定，日常用于驱动自身的开发（self-hosting）。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多模型支持 | Claude / OpenAI / Gemini / GLM / DeepSeek / Ollama，运行时切换 |\n| 内置工具集 | read / write / edit / glob / grep / bash + 子 Agent 派发 |\n| MCP 支持 | stdio / SSE / streamable-http，动态注册外部工具 |\n| Skills 系统 | 自研 Skill 体系 + 兼容 Claude Code 插件生态（superpowers 等） |\n| 对话持久化 | JSONL 会话文件 + --resume 恢复 + /fork 分支 |\n| Token 计量 | 四维 token 记录 + 多币种计价 + /usage 实时统计 |\n| 指令文件 | CCODE.md / CLAUDE.md 多层级注入，完全兼容 Claude Code |\n\n---\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n src/ # 核心源码（Agent Loop / Tools / Providers / UI）\n tests/ # 测试\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/ccode.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `Escape` | 中断当前回复 |\n| `Ctrl+C` | 双击退出 |\n\n### 斜杠指令\n\n| 指令 | 说明 |\n|------|------|\n| `/help` | 查看所有指令 |\n| `/model` | 交互式切换模型 |\n| `/model <name>` | 直接切换到指定模型 |\n| `/clear` | 清空当前对话 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | 查看 MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/gc` | 清理过期会话和用量记录 |\n| `/gc --days 0` | 清理全部会话（保留 0 天） |\n| `/gc --dry-run` | 预览将清理的数据量 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nCCode 的配置文件位于 `~/.ccode/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.ccode/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 CCode（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nCCode 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nCCode 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.ccode/.mcp.json` | CCode 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.ccode/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（CCODE.md / CLAUDE.md）\n\nCCode 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `CCODE.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.ccode/CCODE.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/CCODE.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.ccode/CCODE.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/CCODE.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，CCode 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 CCode 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 CCode 定制不同于 Claude Code 的指令时，在同层级放一个 `CCODE.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.ccode/CCODE.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/CCODE.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`ccode \"问题\"`）均会加载指令文件\n\n---\n\n## 插件系统\n\nCCode 支持通过插件包扩展 Skill 能力，兼容 Claude Code 的插件生态（如 [superpowers](https://github.com/obra/superpowers)）。\n\n### 安装插件\n\n将插件目录复制到 `~/.ccode/plugins/` 下即可（目录名即为插件名）：\n\n```bash\n# 方式一：从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.ccode/plugins/superpowers\n\n# 方式二：直接复制已有目录\n# Linux / macOS\ncp -r /path/to/superpowers ~/.ccode/plugins/superpowers\n\n# Windows\nxcopy /E /I \"D:\\path\\to\\superpowers\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n```\n\n> 如果你已安装了 Claude Code 的 superpowers 插件，可以直接从缓存复制：\n> ```bash\n> # Windows\n> xcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n>\n> # Linux / macOS\n> cp -r ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.2 ~/.ccode/plugins/superpowers\n> ```\n\n项目级插件放在 `<项目根>/.ccode/plugins/` 下。\n\n### 插件目录结构\n\n```\n~/.ccode/plugins/\n └── superpowers/ ← 插件包名\n ├── skills/ ← skills 目录（必需）\n │ ├── brainstorming/\n │ │ ├── SKILL.md\n │ │ └── visual-companion.md ← 支撑文件\n │ ├── writing-plans/\n │ │ └── SKILL.md\n │ └── ...\n ├── hooks/ ← hooks 目录（可选）\n │ └── hooks.json\n └── plugin.json ← 插件清单（可选）\n```\n\n### 命名空间\n\n插件内的 Skill 自动添加 `<插件名>:` 前缀，避免与内置 Skill 冲突：\n\n| 来源 | 注册名示例 |\n|------|-----------|\n| 内置 Skill | `commit` |\n| 用户自定义 Skill | `my-tool` |\n| 插件 Skill | `superpowers:brainstorming` |\n\n**优先级**：项目级 > 用户级 > 插件 > 内置\n\n### 以 superpowers 为例\n\n```bash\n# 1. 安装：从 Claude Code 缓存复制（如果已安装 Claude Code superpowers 插件）\n# Windows\nxcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n\n# 或者从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.ccode/plugins/superpowers\n\n# 2. 启动 CCode，自动发现插件中的所有 Skills\npnpm dev\n```\n\n启动后 system prompt 中会包含 `superpowers:brainstorming`、`superpowers:writing-plans` 等 Skill 列表，LLM 会自动按需调用。\n\n---\n\n## Hook 系统\n\nCCode 支持事件钩子，可在会话启动、工具执行前后注入自定义逻辑。\n\n### 事件类型\n\n| 事件 | 触发时机 | 典型用途 |\n|------|----------|----------|\n| `SessionStart` | 会话启动 | 插件启动注入、环境检查 |\n| `PreToolUse` | 工具执行前 | 权限拦截、参数校验 |\n| `PostToolUse` | 工具执行后 | 结果审计、通知 |\n\n### 配置文件\n\nHook 配置来自三层来源（叠加执行，不覆盖）：\n\n| 来源 | 路径 |\n|------|------|\n| 插件包 | `~/.ccode/plugins/<name>/hooks/hooks.json` |\n| 项目级 | `<项目根>/.ccode/hooks.json` |\n| 用户级 | `~/.ccode/hooks.json` |\n\n### hooks.json 格式\n\n```jsonc\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"additionalContext\\\": \\\"hello from hook\\\"}'\",\n \"timeout\": 10000\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"decision\\\": \\\"allow\\\"}'\",\n \"timeout\": 5000\n }\n ]\n }\n ]\n }\n}\n```\n\n- `matcher`：正则表达式，匹配触发条件（SessionStart 匹配子类型，PreToolUse/PostToolUse 匹配工具名）\n- `timeout`：超时毫秒数，默认 10000\n- Hook 通过 stdout 输出 JSON 返回结果，超时或失败静默跳过\n\n> 插件包自带的 `hooks/hooks.json`（如 superpowers 的 SessionStart hook）会被自动发现和执行，无需手动配置。\n\n---\n\n## 项目级权限配置\n\nCCode 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.ccode/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.ccode/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph），AsyncGenerator 事件流架构\n- **持久化**：JSONL 会话文件 + libsql（SQLite）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "dee0ba08aec8344ece02346a52c329c3ab8f485a": {"t": 1785764494.6912215, "n": 12364, "h": "b935fe2380b08bbf", "c": "# ZCli\n\n**多模型 AI 编程 CLI 助手** — 对标 Claude Code 的交互体验，但不绑定单一 LLM 提供商。\n\n[](./LICENSE)\n\n---\n\n## 项目背景\n\n### 为什么做这个\n\nClaude Code 是目前最好的 AI 编程 CLI 工具，但它有一个硬约束：**只能用 Claude 模型**。对于需要在不同场景下切换模型的开发者来说，这意味着要在多个工具之间反复切换，丢失上下文和工作流的连贯性。\n\nZCli 的目标是：**让开发者在终端中自由选择 Claude / GPT / Gemini / GLM / DeepSeek / 本地 Ollama 等任意模型，获得一致的 AI 辅助编码体验。** 同时完全兼容 Claude Code 的生态（CLAUDE.md 指令文件、MCP 协议、插件系统）。\n\n### 核心理念\n\n- **多模型自由切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **Claude Code 生态兼容** — CLAUDE.md、.mcp.json、插件目录结构完全兼容，已有配置零迁移\n- **Agent 能力完整** — 工具调用、并行执行、子 Agent 派发、权限管控、会话持久化\n- **可观测** — Token 计量计费、结构化日志、Session JSONL 全量审计\n- **Web 能力** — CLI 和浏览器双向实时同步，同一对话两端共享\n\n### 当前状态\n\nZCli 处于活跃开发阶段（v0.1.0），核心 Agent 能力已稳定，日常用于驱动自身的开发（self-hosting）。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多模型支持 | Claude / OpenAI / Gemini / GLM / DeepSeek / Ollama，运行时切换 |\n| 内置工具集 | read / write / edit / glob / grep / bash + 子 Agent 派发 |\n| MCP 支持 | stdio / SSE / streamable-http，动态注册外部工具 |\n| Skills 系统 | 自研 Skill 体系 + 兼容 Claude Code 插件生态（superpowers 等） |\n| 对话持久化 | JSONL 会话文件 + --resume 恢复 + /fork 分支 |\n| Token 计量 | 四维 token 记录 + 多币种计价 + /usage 实时统计 |\n| 指令文件 | ZCLI.md / CLAUDE.md 多层级注入，完全兼容 Claude Code |\n\n---\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n src/ # 核心源码（Agent Loop / Tools / Providers / UI）\n tests/ # 测试\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `Escape` | 中断当前回复 |\n| `Ctrl+C` | 双击退出 |\n\n### 斜杠指令\n\n| 指令 | 说明 |\n|------|------|\n| `/help` | 查看所有指令 |\n| `/model` | 交互式切换模型 |\n| `/model <name>` | 直接切换到指定模型 |\n| `/clear` | 清空当前对话 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | 查看 MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/gc` | 清理过期会话和用量记录 |\n| `/gc --days 0` | 清理全部会话（保留 0 天） |\n| `/gc --dry-run` | 预览将清理的数据量 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.zcli/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 ZCli（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nZCli 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（ZCLI.md / CLAUDE.md）\n\nZCli 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `ZCLI.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.zcli/ZCLI.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/ZCLI.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.zcli/ZCLI.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/ZCLI.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，ZCli 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 ZCli 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 ZCli 定制不同于 Claude Code 的指令时，在同层级放一个 `ZCLI.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.zcli/ZCLI.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/ZCLI.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`zcli \"问题\"`）均会加载指令文件\n\n---\n\n## 插件系统\n\nZCli 支持通过插件包扩展 Skill 能力，兼容 Claude Code 的插件生态（如 [superpowers](https://github.com/obra/superpowers)）。\n\n### 安装插件\n\n将插件目录复制到 `~/.zcli/plugins/` 下即可（目录名即为插件名）：\n\n```bash\n# 方式一：从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 方式二：直接复制已有目录\n# Linux / macOS\ncp -r /path/to/superpowers ~/.zcli/plugins/superpowers\n\n# Windows\nxcopy /E /I \"D:\\path\\to\\superpowers\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n```\n\n> 如果你已安装了 Claude Code 的 superpowers 插件，可以直接从缓存复制：\n> ```bash\n> # Windows\n> xcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n>\n> # Linux / macOS\n> cp -r ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.2 ~/.zcli/plugins/superpowers\n> ```\n\n项目级插件放在 `<项目根>/.zcli/plugins/` 下。\n\n### 插件目录结构\n\n```\n~/.zcli/plugins/\n └── superpowers/ ← 插件包名\n ├── skills/ ← skills 目录（必需）\n │ ├── brainstorming/\n │ │ ├── SKILL.md\n │ │ └── visual-companion.md ← 支撑文件\n │ ├── writing-plans/\n │ │ └── SKILL.md\n │ └── ...\n ├── hooks/ ← hooks 目录（可选）\n │ └── hooks.json\n └── plugin.json ← 插件清单（可选）\n```\n\n### 命名空间\n\n插件内的 Skill 自动添加 `<插件名>:` 前缀，避免与内置 Skill 冲突：\n\n| 来源 | 注册名示例 |\n|------|-----------|\n| 内置 Skill | `commit` |\n| 用户自定义 Skill | `my-tool` |\n| 插件 Skill | `superpowers:brainstorming` |\n\n**优先级**：项目级 > 用户级 > 插件 > 内置\n\n### 以 superpowers 为例\n\n```bash\n# 1. 安装：从 Claude Code 缓存复制（如果已安装 Claude Code superpowers 插件）\n# Windows\nxcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n\n# 或者从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 2. 启动 ZCli，自动发现插件中的所有 Skills\npnpm dev\n```\n\n启动后 system prompt 中会包含 `superpowers:brainstorming`、`superpowers:writing-plans` 等 Skill 列表，LLM 会自动按需调用。\n\n---\n\n## Hook 系统\n\nZCli 支持事件钩子，可在会话启动、工具执行前后注入自定义逻辑。\n\n### 事件类型\n\n| 事件 | 触发时机 | 典型用途 |\n|------|----------|----------|\n| `SessionStart` | 会话启动 | 插件启动注入、环境检查 |\n| `PreToolUse` | 工具执行前 | 权限拦截、参数校验 |\n| `PostToolUse` | 工具执行后 | 结果审计、通知 |\n\n### 配置文件\n\nHook 配置来自三层来源（叠加执行，不覆盖）：\n\n| 来源 | 路径 |\n|------|------|\n| 插件包 | `~/.zcli/plugins/<name>/hooks/hooks.json` |\n| 项目级 | `<项目根>/.zcli/hooks.json` |\n| 用户级 | `~/.zcli/hooks.json` |\n\n### hooks.json 格式\n\n```jsonc\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"additionalContext\\\": \\\"hello from hook\\\"}'\",\n \"timeout\": 10000\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"decision\\\": \\\"allow\\\"}'\",\n \"timeout\": 5000\n }\n ]\n }\n ]\n }\n}\n```\n\n- `matcher`：正则表达式，匹配触发条件（SessionStart 匹配子类型，PreToolUse/PostToolUse 匹配工具名）\n- `timeout`：超时毫秒数，默认 10000\n- Hook 通过 stdout 输出 JSON 返回结果，超时或失败静默跳过\n\n> 插件包自带的 `hooks/hooks.json`（如 superpowers 的 SessionStart hook）会被自动发现和执行，无需手动配置。\n\n---\n\n## 项目级权限配置\n\nZCli 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.zcli/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.zcli/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph），AsyncGenerator 事件流架构\n- **持久化**：JSONL 会话文件 + libsql（SQLite）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "ff97e63849eb14793e48c93cbb2c29a4e8f591ff": {"t": 1785764496.1244006, "n": 12006, "h": "3e6f6ce83700eb41", "c": "# ZCli\n\n**多模型 AI 编程 CLI 助手** — 对标 Claude Code 的交互体验，但不绑定单一 LLM 提供商。\n\n[](./LICENSE)\n\n---\n\n## 项目背景\n\n### 为什么做这个\n\nClaude Code 是目前最好的 AI 编程 CLI 工具，但它有一个硬约束：**只能用 Claude 模型**。对于需要在不同场景下切换模型的开发者来说，这意味着要在多个工具之间反复切换，丢失上下文和工作流的连贯性。\n\nZCli 的目标是：**让开发者在终端中自由选择 Claude / GPT / Gemini / GLM / DeepSeek / 本地 Ollama 等任意模型，获得一致的 AI 辅助编码体验。** 同时完全兼容 Claude Code 的生态（CLAUDE.md 指令文件、MCP 协议、插件系统）。\n\n### 核心理念\n\n- **多模型自由切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **Claude Code 生态兼容** — CLAUDE.md、.mcp.json、插件目录结构完全兼容，已有配置零迁移\n- **Agent 能力完整** — 工具调用、并行执行、子 Agent 派发、权限管控、会话持久化\n- **可观测** — Token 计量计费、结构化日志、Session JSONL 全量审计\n- **Web 能力** — CLI 和浏览器双向实时同步，同一对话两端共享\n\n### 当前状态\n\nZCli 处于活跃开发阶段（v0.1.0），核心 Agent 能力已稳定，日常用于驱动自身的开发（self-hosting）。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多模型支持 | Claude / OpenAI / Gemini / GLM / DeepSeek / Ollama，运行时切换 |\n| 内置工具集 | read / write / edit / glob / grep / bash + 子 Agent 派发 |\n| MCP 支持 | stdio / SSE / streamable-http，动态注册外部工具 |\n| Skills 系统 | 自研 Skill 体系 + 兼容 Claude Code 插件生态（superpowers 等） |\n| 对话持久化 | JSONL 会话文件 + --resume 恢复 + /fork 分支 |\n| Token 计量 | 四维 token 记录 + 多币种计价 + /usage 实时统计 |\n| 指令文件 | ZCLI.md / CLAUDE.md 多层级注入，完全兼容 Claude Code |\n\n---\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n src/ # 核心源码（Agent Loop / Tools / Providers / UI）\n tests/ # 测试\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.zcli/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 ZCli（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nZCli 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（ZCLI.md / CLAUDE.md）\n\nZCli 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `ZCLI.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.zcli/ZCLI.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/ZCLI.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.zcli/ZCLI.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/ZCLI.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，ZCli 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 ZCli 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 ZCli 定制不同于 Claude Code 的指令时，在同层级放一个 `ZCLI.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.zcli/ZCLI.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/ZCLI.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`zcli \"问题\"`）均会加载指令文件\n\n---\n\n## 插件系统\n\nZCli 支持通过插件包扩展 Skill 能力，兼容 Claude Code 的插件生态（如 [superpowers](https://github.com/obra/superpowers)）。\n\n### 安装插件\n\n将插件目录复制到 `~/.zcli/plugins/` 下即可（目录名即为插件名）：\n\n```bash\n# 方式一：从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 方式二：直接复制已有目录\n# Linux / macOS\ncp -r /path/to/superpowers ~/.zcli/plugins/superpowers\n\n# Windows\nxcopy /E /I \"D:\\path\\to\\superpowers\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n```\n\n> 如果你已安装了 Claude Code 的 superpowers 插件，可以直接从缓存复制：\n> ```bash\n> # Windows\n> xcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n>\n> # Linux / macOS\n> cp -r ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.2 ~/.zcli/plugins/superpowers\n> ```\n\n项目级插件放在 `<项目根>/.zcli/plugins/` 下。\n\n### 插件目录结构\n\n```\n~/.zcli/plugins/\n └── superpowers/ ← 插件包名\n ├── skills/ ← skills 目录（必需）\n │ ├── brainstorming/\n │ │ ├── SKILL.md\n │ │ └── visual-companion.md ← 支撑文件\n │ ├── writing-plans/\n │ │ └── SKILL.md\n │ └── ...\n ├── hooks/ ← hooks 目录（可选）\n │ └── hooks.json\n └── plugin.json ← 插件清单（可选）\n```\n\n### 命名空间\n\n插件内的 Skill 自动添加 `<插件名>:` 前缀，避免与内置 Skill 冲突：\n\n| 来源 | 注册名示例 |\n|------|-----------|\n| 内置 Skill | `commit` |\n| 用户自定义 Skill | `my-tool` |\n| 插件 Skill | `superpowers:brainstorming` |\n\n**优先级**：项目级 > 用户级 > 插件 > 内置\n\n### 以 superpowers 为例\n\n```bash\n# 1. 安装：从 Claude Code 缓存复制（如果已安装 Claude Code superpowers 插件）\n# Windows\nxcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n\n# 或者从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 2. 启动 ZCli，自动发现插件中的所有 Skills\npnpm dev\n```\n\n启动后 system prompt 中会包含 `superpowers:brainstorming`、`superpowers:writing-plans` 等 Skill 列表，LLM 会自动按需调用。\n\n---\n\n## Hook 系统\n\nZCli 支持事件钩子，可在会话启动、工具执行前后注入自定义逻辑。\n\n### 事件类型\n\n| 事件 | 触发时机 | 典型用途 |\n|------|----------|----------|\n| `SessionStart` | 会话启动 | 插件启动注入、环境检查 |\n| `PreToolUse` | 工具执行前 | 权限拦截、参数校验 |\n| `PostToolUse` | 工具执行后 | 结果审计、通知 |\n\n### 配置文件\n\nHook 配置来自三层来源（叠加执行，不覆盖）：\n\n| 来源 | 路径 |\n|------|------|\n| 插件包 | `~/.zcli/plugins/<name>/hooks/hooks.json` |\n| 项目级 | `<项目根>/.zcli/hooks.json` |\n| 用户级 | `~/.zcli/hooks.json` |\n\n### hooks.json 格式\n\n```jsonc\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"additionalContext\\\": \\\"hello from hook\\\"}'\",\n \"timeout\": 10000\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"decision\\\": \\\"allow\\\"}'\",\n \"timeout\": 5000\n }\n ]\n }\n ]\n }\n}\n```\n\n- `matcher`：正则表达式，匹配触发条件（SessionStart 匹配子类型，PreToolUse/PostToolUse 匹配工具名）\n- `timeout`：超时毫秒数，默认 10000\n- Hook 通过 stdout 输出 JSON 返回结果，超时或失败静默跳过\n\n> 插件包自带的 `hooks/hooks.json`（如 superpowers 的 SessionStart hook）会被自动发现和执行，无需手动配置。\n\n---\n\n## 项目级权限配置\n\nZCli 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.zcli/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.zcli/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph），AsyncGenerator 事件流架构\n- **持久化**：JSONL 会话文件 + libsql（SQLite）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "dc272f1c3f9cec28054958296ecf7fada54c6a45": {"t": 1785764497.704598, "n": 11915, "h": "e95c9d69500536d2", "c": "# ZCli\n\n**多模型 AI 编程 CLI 助手** — 对标 Claude Code 的交互体验，但不绑定单一 LLM 提供商。\n\n---\n\n## 项目背景\n\n### 为什么做这个\n\nClaude Code 是目前最好的 AI 编程 CLI 工具，但它有一个硬约束：**只能用 Claude 模型**。对于需要在不同场景下切换模型的开发者来说，这意味着要在多个工具之间反复切换，丢失上下文和工作流的连贯性。\n\nZCli 的目标是：**让开发者在终端中自由选择 Claude / GPT / Gemini / GLM / DeepSeek / 本地 Ollama 等任意模型，获得一致的 AI 辅助编码体验。** 同时完全兼容 Claude Code 的生态（CLAUDE.md 指令文件、MCP 协议、插件系统）。\n\n### 核心理念\n\n- **多模型自由切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **Claude Code 生态兼容** — CLAUDE.md、.mcp.json、插件目录结构完全兼容，已有配置零迁移\n- **Agent 能力完整** — 工具调用、并行执行、子 Agent 派发、权限管控、会话持久化\n- **可观测** — Token 计量计费、结构化日志、Session JSONL 全量审计\n- **Web 能力** — CLI 和浏览器双向实时同步，同一对话两端共享\n\n### 当前状态\n\nZCli 处于活跃开发阶段（v0.1.0），核心 Agent 能力已稳定，日常用于驱动自身的开发（self-hosting）。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多模型支持 | Claude / OpenAI / Gemini / GLM / DeepSeek / Ollama，运行时切换 |\n| 内置工具集 | read / write / edit / glob / grep / bash + 子 Agent 派发 |\n| MCP 支持 | stdio / SSE / streamable-http，动态注册外部工具 |\n| Skills 系统 | 自研 Skill 体系 + 兼容 Claude Code 插件生态（superpowers 等） |\n| 对话持久化 | JSONL 会话文件 + --resume 恢复 + /fork 分支 |\n| Token 计量 | 四维 token 记录 + 多币种计价 + /usage 实时统计 |\n| 指令文件 | ZCLI.md / CLAUDE.md 多层级注入，完全兼容 Claude Code |\n\n---\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n src/ # 核心源码（Agent Loop / Tools / Providers / UI）\n tests/ # 测试\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.zcli/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 ZCli（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nZCli 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（ZCLI.md / CLAUDE.md）\n\nZCli 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `ZCLI.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.zcli/ZCLI.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/ZCLI.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.zcli/ZCLI.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/ZCLI.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，ZCli 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 ZCli 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 ZCli 定制不同于 Claude Code 的指令时，在同层级放一个 `ZCLI.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.zcli/ZCLI.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/ZCLI.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`zcli \"问题\"`）均会加载指令文件\n\n---\n\n## 插件系统\n\nZCli 支持通过插件包扩展 Skill 能力，兼容 Claude Code 的插件生态（如 [superpowers](https://github.com/obra/superpowers)）。\n\n### 安装插件\n\n将插件目录复制到 `~/.zcli/plugins/` 下即可（目录名即为插件名）：\n\n```bash\n# 方式一：从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 方式二：直接复制已有目录\n# Linux / macOS\ncp -r /path/to/superpowers ~/.zcli/plugins/superpowers\n\n# Windows\nxcopy /E /I \"D:\\path\\to\\superpowers\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n```\n\n> 如果你已安装了 Claude Code 的 superpowers 插件，可以直接从缓存复制：\n> ```bash\n> # Windows\n> xcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n>\n> # Linux / macOS\n> cp -r ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.2 ~/.zcli/plugins/superpowers\n> ```\n\n项目级插件放在 `<项目根>/.zcli/plugins/` 下。\n\n### 插件目录结构\n\n```\n~/.zcli/plugins/\n └── superpowers/ ← 插件包名\n ├── skills/ ← skills 目录（必需）\n │ ├── brainstorming/\n │ │ ├── SKILL.md\n │ │ └── visual-companion.md ← 支撑文件\n │ ├── writing-plans/\n │ │ └── SKILL.md\n │ └── ...\n ├── hooks/ ← hooks 目录（可选）\n │ └── hooks.json\n └── plugin.json ← 插件清单（可选）\n```\n\n### 命名空间\n\n插件内的 Skill 自动添加 `<插件名>:` 前缀，避免与内置 Skill 冲突：\n\n| 来源 | 注册名示例 |\n|------|-----------|\n| 内置 Skill | `commit` |\n| 用户自定义 Skill | `my-tool` |\n| 插件 Skill | `superpowers:brainstorming` |\n\n**优先级**：项目级 > 用户级 > 插件 > 内置\n\n### 以 superpowers 为例\n\n```bash\n# 1. 安装：从 Claude Code 缓存复制（如果已安装 Claude Code superpowers 插件）\n# Windows\nxcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n\n# 或者从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 2. 启动 ZCli，自动发现插件中的所有 Skills\npnpm dev\n```\n\n启动后 system prompt 中会包含 `superpowers:brainstorming`、`superpowers:writing-plans` 等 Skill 列表，LLM 会自动按需调用。\n\n---\n\n## Hook 系统\n\nZCli 支持事件钩子，可在会话启动、工具执行前后注入自定义逻辑。\n\n### 事件类型\n\n| 事件 | 触发时机 | 典型用途 |\n|------|----------|----------|\n| `SessionStart` | 会话启动 | 插件启动注入、环境检查 |\n| `PreToolUse` | 工具执行前 | 权限拦截、参数校验 |\n| `PostToolUse` | 工具执行后 | 结果审计、通知 |\n\n### 配置文件\n\nHook 配置来自三层来源（叠加执行，不覆盖）：\n\n| 来源 | 路径 |\n|------|------|\n| 插件包 | `~/.zcli/plugins/<name>/hooks/hooks.json` |\n| 项目级 | `<项目根>/.zcli/hooks.json` |\n| 用户级 | `~/.zcli/hooks.json` |\n\n### hooks.json 格式\n\n```jsonc\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"additionalContext\\\": \\\"hello from hook\\\"}'\",\n \"timeout\": 10000\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"decision\\\": \\\"allow\\\"}'\",\n \"timeout\": 5000\n }\n ]\n }\n ]\n }\n}\n```\n\n- `matcher`：正则表达式，匹配触发条件（SessionStart 匹配子类型，PreToolUse/PostToolUse 匹配工具名）\n- `timeout`：超时毫秒数，默认 10000\n- Hook 通过 stdout 输出 JSON 返回结果，超时或失败静默跳过\n\n> 插件包自带的 `hooks/hooks.json`（如 superpowers 的 SessionStart hook）会被自动发现和执行，无需手动配置。\n\n---\n\n## 项目级权限配置\n\nZCli 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.zcli/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.zcli/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph），AsyncGenerator 事件流架构\n- **持久化**：JSONL 会话文件 + libsql（SQLite）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "e6601eea64e5de537afb88d8db054fa1158d9ecd": {"t": 1785764499.0617087, "n": 12464, "h": "935839cf205610a5", "c": "# ZCli\n\n**多模型 AI 编程 CLI 助手** — 对标 Claude Code 的交互体验，但不绑定单一 LLM 提供商。\n\n---\n\n## 项目背景\n\n### 为什么做这个\n\nClaude Code 是目前最好的 AI 编程 CLI 工具，但它有一个硬约束：**只能用 Claude 模型**。对于需要在不同场景下切换模型的开发者来说，这意味着要在多个工具之间反复切换，丢失上下文和工作流的连贯性。\n\nZCli 的目标是：**让开发者在终端中自由选择 Claude / GPT / Gemini / GLM / DeepSeek / 本地 Ollama 等任意模型，获得一致的 AI 辅助编码体验。** 同时完全兼容 Claude Code 的生态（CLAUDE.md 指令文件、MCP 协议、插件系统）。\n\n### 核心理念\n\n- **多模型自由切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **Claude Code 生态兼容** — CLAUDE.md、.mcp.json、插件目录结构完全兼容，已有配置零迁移\n- **Agent 能力完整** — 工具调用、并行执行、子 Agent 派发、权限管控、会话持久化\n- **可观测** — Token 计量计费、结构化日志、Session JSONL 全量审计\n- **Web 能力** — CLI 和浏览器双向实时同步，同一对话两端共享\n\n### 当前状态\n\nZCli 处于活跃开发阶段（v0.1.0），核心 Agent 能力已稳定，日常用于驱动自身的开发（self-hosting）。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多模型支持 | Claude / OpenAI / Gemini / GLM / DeepSeek / Ollama，运行时切换 |\n| 内置工具集 | read / write / edit / glob / grep / bash + 子 Agent 派发 |\n| MCP 支持 | stdio / SSE / streamable-http，动态注册外部工具 |\n| Skills 系统 | 自研 Skill 体系 + 兼容 Claude Code 插件生态（superpowers 等） |\n| 对话持久化 | JSONL 会话文件 + --resume 恢复 + /fork 分支 |\n| Token 计量 | 四维 token 记录 + 多币种计价 + /usage 实时统计 |\n| Web UI | Bridge Server 双向同步，CLI 和浏览器共享同一对话 |\n| 非交互模式 | `zcli \"问题\"` 单次执行 + stdin 管道输入，适用于脚本/CI |\n| 指令文件 | ZCLI.md / CLAUDE.md 多层级注入，完全兼容 Claude Code |\n| 并行工具 | 多工具调用自动并行执行，大幅缩短响应时间 |\n\n---\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n src/ # CLI 核心源码（Agent Loop / Tools / Providers / UI）\n src/bridge/ # Bridge Server（CLI ↔ Web 桥接层）\n web/ # Web 前端（React SPA，独立 Vite 项目）\n tests/ # 测试\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 开发模式启动（含 Web UI）\n\n```bash\ncd zCli/web && pnpm install # 首次需要安装前端依赖\ncd .. && pnpm dev:web\n```\n\nCLI + Bridge Server + Web UI 同时启动，浏览器打开终端显示的地址即可双向同步对话。\n\n### 4. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.zcli/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 ZCli（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nZCli 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（ZCLI.md / CLAUDE.md）\n\nZCli 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `ZCLI.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.zcli/ZCLI.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/ZCLI.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.zcli/ZCLI.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/ZCLI.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，ZCli 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 ZCli 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 ZCli 定制不同于 Claude Code 的指令时，在同层级放一个 `ZCLI.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.zcli/ZCLI.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/ZCLI.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`zcli \"问题\"`）均会加载指令文件\n\n---\n\n## 插件系统\n\nZCli 支持通过插件包扩展 Skill 能力，兼容 Claude Code 的插件生态（如 [superpowers](https://github.com/obra/superpowers)）。\n\n### 安装插件\n\n将插件目录复制到 `~/.zcli/plugins/` 下即可（目录名即为插件名）：\n\n```bash\n# 方式一：从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 方式二：直接复制已有目录\n# Linux / macOS\ncp -r /path/to/superpowers ~/.zcli/plugins/superpowers\n\n# Windows\nxcopy /E /I \"D:\\path\\to\\superpowers\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n```\n\n> 如果你已安装了 Claude Code 的 superpowers 插件，可以直接从缓存复制：\n> ```bash\n> # Windows\n> xcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n>\n> # Linux / macOS\n> cp -r ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.2 ~/.zcli/plugins/superpowers\n> ```\n\n项目级插件放在 `<项目根>/.zcli/plugins/` 下。\n\n### 插件目录结构\n\n```\n~/.zcli/plugins/\n └── superpowers/ ← 插件包名\n ├── skills/ ← skills 目录（必需）\n │ ├── brainstorming/\n │ │ ├── SKILL.md\n │ │ └── visual-companion.md ← 支撑文件\n │ ├── writing-plans/\n │ │ └── SKILL.md\n │ └── ...\n ├── hooks/ ← hooks 目录（可选）\n │ └── hooks.json\n └── plugin.json ← 插件清单（可选）\n```\n\n### 命名空间\n\n插件内的 Skill 自动添加 `<插件名>:` 前缀，避免与内置 Skill 冲突：\n\n| 来源 | 注册名示例 |\n|------|-----------|\n| 内置 Skill | `commit` |\n| 用户自定义 Skill | `my-tool` |\n| 插件 Skill | `superpowers:brainstorming` |\n\n**优先级**：项目级 > 用户级 > 插件 > 内置\n\n### 以 superpowers 为例\n\n```bash\n# 1. 安装：从 Claude Code 缓存复制（如果已安装 Claude Code superpowers 插件）\n# Windows\nxcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n\n# 或者从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 2. 启动 ZCli，自动发现插件中的所有 Skills\npnpm dev\n```\n\n启动后 system prompt 中会包含 `superpowers:brainstorming`、`superpowers:writing-plans` 等 Skill 列表，LLM 会自动按需调用。\n\n---\n\n## Hook 系统\n\nZCli 支持事件钩子，可在会话启动、工具执行前后注入自定义逻辑。\n\n### 事件类型\n\n| 事件 | 触发时机 | 典型用途 |\n|------|----------|----------|\n| `SessionStart` | 会话启动 | 插件启动注入、环境检查 |\n| `PreToolUse` | 工具执行前 | 权限拦截、参数校验 |\n| `PostToolUse` | 工具执行后 | 结果审计、通知 |\n\n### 配置文件\n\nHook 配置来自三层来源（叠加执行，不覆盖）：\n\n| 来源 | 路径 |\n|------|------|\n| 插件包 | `~/.zcli/plugins/<name>/hooks/hooks.json` |\n| 项目级 | `<项目根>/.zcli/hooks.json` |\n| 用户级 | `~/.zcli/hooks.json` |\n\n### hooks.json 格式\n\n```jsonc\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"additionalContext\\\": \\\"hello from hook\\\"}'\",\n \"timeout\": 10000\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"decision\\\": \\\"allow\\\"}'\",\n \"timeout\": 5000\n }\n ]\n }\n ]\n }\n}\n```\n\n- `matcher`：正则表达式，匹配触发条件（SessionStart 匹配子类型，PreToolUse/PostToolUse 匹配工具名）\n- `timeout`：超时毫秒数，默认 10000\n- Hook 通过 stdout 输出 JSON 返回结果，超时或失败静默跳过\n\n> 插件包自带的 `hooks/hooks.json`（如 superpowers 的 SessionStart hook）会被自动发现和执行，无需手动配置。\n\n---\n\n## 项目级权限配置\n\nZCli 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.zcli/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.zcli/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式），规划中迁移 Bun.js\n- **终端 UI**：Ink 5 + React 18\n- **Web UI**：React 18 + Vite + Tailwind CSS\n- **Bridge Server**：Hono（HTTP + WebSocket 纯消息路由器）\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph），AsyncGenerator 事件流架构\n- **持久化**：JSONL 会话文件 + libsql（SQLite，兼容 Node/Bun/Deno）\n- **包管理**：pnpm\n- **构建**：tsup（CLI）+ Vite（Web）\n- **测试**：Vitest\n"}, "bd5536e287b17266e78e8f44a8174b5470673b6e": {"t": 1785764500.4467764, "n": 10706, "h": "be5ff3d8a42532cf", "c": "# ZCli\n\n多模型 AI 编程 CLI 助手，支持 Claude、OpenAI、Gemini 等任意 OpenAI 兼容协议的模型。\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.zcli/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 ZCli（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nZCli 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（ZCLI.md / CLAUDE.md）\n\nZCli 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `ZCLI.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.zcli/ZCLI.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/ZCLI.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.zcli/ZCLI.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/ZCLI.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，ZCli 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 ZCli 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 ZCli 定制不同于 Claude Code 的指令时，在同层级放一个 `ZCLI.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.zcli/ZCLI.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/ZCLI.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`zcli \"问题\"`）均会加载指令文件\n\n---\n\n## 插件系统\n\nZCli 支持通过插件包扩展 Skill 能力，兼容 Claude Code 的插件生态（如 [superpowers](https://github.com/obra/superpowers)）。\n\n### 安装插件\n\n将插件目录复制到 `~/.zcli/plugins/` 下即可（目录名即为插件名）：\n\n```bash\n# 方式一：从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 方式二：直接复制已有目录\n# Linux / macOS\ncp -r /path/to/superpowers ~/.zcli/plugins/superpowers\n\n# Windows\nxcopy /E /I \"D:\\path\\to\\superpowers\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n```\n\n> 如果你已安装了 Claude Code 的 superpowers 插件，可以直接从缓存复制：\n> ```bash\n> # Windows\n> xcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n>\n> # Linux / macOS\n> cp -r ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.2 ~/.zcli/plugins/superpowers\n> ```\n\n项目级插件放在 `<项目根>/.zcli/plugins/` 下。\n\n### 插件目录结构\n\n```\n~/.zcli/plugins/\n └── superpowers/ ← 插件包名\n ├── skills/ ← skills 目录（必需）\n │ ├── brainstorming/\n │ │ ├── SKILL.md\n │ │ └── visual-companion.md ← 支撑文件\n │ ├── writing-plans/\n │ │ └── SKILL.md\n │ └── ...\n ├── hooks/ ← hooks 目录（可选）\n │ └── hooks.json\n └── plugin.json ← 插件清单（可选）\n```\n\n### 命名空间\n\n插件内的 Skill 自动添加 `<插件名>:` 前缀，避免与内置 Skill 冲突：\n\n| 来源 | 注册名示例 |\n|------|-----------|\n| 内置 Skill | `commit` |\n| 用户自定义 Skill | `my-tool` |\n| 插件 Skill | `superpowers:brainstorming` |\n\n**优先级**：项目级 > 用户级 > 插件 > 内置\n\n### 以 superpowers 为例\n\n```bash\n# 1. 安装：从 Claude Code 缓存复制（如果已安装 Claude Code superpowers 插件）\n# Windows\nxcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.zcli\\plugins\\superpowers\"\n\n# 或者从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.zcli/plugins/superpowers\n\n# 2. 启动 ZCli，自动发现插件中的所有 Skills\npnpm dev\n```\n\n启动后 system prompt 中会包含 `superpowers:brainstorming`、`superpowers:writing-plans` 等 Skill 列表，LLM 会自动按需调用。\n\n---\n\n## Hook 系统\n\nZCli 支持事件钩子，可在会话启动、工具执行前后注入自定义逻辑。\n\n### 事件类型\n\n| 事件 | 触发时机 | 典型用途 |\n|------|----------|----------|\n| `SessionStart` | 会话启动 | 插件启动注入、环境检查 |\n| `PreToolUse` | 工具执行前 | 权限拦截、参数校验 |\n| `PostToolUse` | 工具执行后 | 结果审计、通知 |\n\n### 配置文件\n\nHook 配置来自三层来源（叠加执行，不覆盖）：\n\n| 来源 | 路径 |\n|------|------|\n| 插件包 | `~/.zcli/plugins/<name>/hooks/hooks.json` |\n| 项目级 | `<项目根>/.zcli/hooks.json` |\n| 用户级 | `~/.zcli/hooks.json` |\n\n### hooks.json 格式\n\n```jsonc\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"additionalContext\\\": \\\"hello from hook\\\"}'\",\n \"timeout\": 10000\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"decision\\\": \\\"allow\\\"}'\",\n \"timeout\": 5000\n }\n ]\n }\n ]\n }\n}\n```\n\n- `matcher`：正则表达式，匹配触发条件（SessionStart 匹配子类型，PreToolUse/PostToolUse 匹配工具名）\n- `timeout`：超时毫秒数，默认 10000\n- Hook 通过 stdout 输出 JSON 返回结果，超时或失败静默跳过\n\n> 插件包自带的 `hooks/hooks.json`（如 superpowers 的 SessionStart hook）会被自动发现和执行，无需手动配置。\n\n---\n\n## 项目级权限配置\n\nZCli 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.zcli/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.zcli/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "6e36e77667a5e212d02abe2ddc34b550bf3933ed": {"t": 1785764501.78224, "n": 7572, "h": "b66d52af059b02ef", "c": "# ZCli\n\n多模型 AI 编程 CLI 助手，支持 Claude、OpenAI、Gemini 等任意 OpenAI 兼容协议的模型。\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.zcli/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 ZCli（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nZCli 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（ZCLI.md / CLAUDE.md）\n\nZCli 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `ZCLI.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.zcli/ZCLI.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/ZCLI.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.zcli/ZCLI.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/ZCLI.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，ZCli 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 ZCli 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 ZCli 定制不同于 Claude Code 的指令时，在同层级放一个 `ZCLI.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.zcli/ZCLI.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/ZCLI.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`zcli \"问题\"`）均会加载指令文件\n\n---\n\n## 项目级权限配置\n\nZCli 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.zcli/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.zcli/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "a76b070bf153d91850502855ae303123637fc3f7": {"t": 1785764503.3744748, "n": 6956, "h": "85e798865b62c643", "c": "# ZCli\n\n多模型 AI 编程 CLI 助手，支持 Claude、OpenAI、Gemini 等任意 OpenAI 兼容协议的模型。\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nZCli 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（ZCLI.md / CLAUDE.md）\n\nZCli 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `ZCLI.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.zcli/ZCLI.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/ZCLI.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.zcli/ZCLI.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/ZCLI.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，ZCli 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 ZCli 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 ZCli 定制不同于 Claude Code 的指令时，在同层级放一个 `ZCLI.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.zcli/ZCLI.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/ZCLI.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`zcli \"问题\"`）均会加载指令文件\n\n---\n\n## 项目级权限配置\n\nZCli 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.zcli/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.zcli/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "dee94e8a96fdcf4d3481a741c865bad9dde88e5b": {"t": 1785764504.8237731, "n": 5591, "h": "9274ed138175c3db", "c": "# ZCli\n\n多模型 AI 编程 CLI 助手，支持 Claude、OpenAI、Gemini 等任意 OpenAI 兼容协议的模型。\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nZCli 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 项目级权限配置\n\nZCli 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.zcli/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.zcli/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "af2f531e69297f3e42d64e207d8430669ec6fa49": {"t": 1785764506.2221413, "n": 3683, "h": "22e57f2afff725cd", "c": "# ZCli\n\n多模型 AI 编程 CLI 助手，支持 Claude、OpenAI、Gemini 等任意 OpenAI 兼容协议的模型。\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nZCli 的配置文件位于 `~/.zcli/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.zcli/config.json`\n\n```jsonc\n{\n // 默认使用的 Provider\n \"defaultProvider\": \"anthropic\",\n // 默认使用的模型\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n },\n // 任意 OpenAI 兼容 Provider，通过 baseURL 指定\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-4-flash\", \"glm-4-air\", \"glm-4\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点（OpenAI 兼容协议） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### .mcp.json — MCP Server 配置\n\nZCli 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.zcli/.mcp.json` | ZCli 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.zcli/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：LangChain（`@langchain/openai` / `@langchain/anthropic` / `@langchain/google-genai`）\n- **Agent Loop**：完全自研（不使用 LangGraph）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}, "4c02952a30990fdad8c0442dd493762fc9b7ba93": {"t": 1785764507.6885545, "n": 1029, "h": "d3dc307176c48d72", "c": "# ZCli\n\n多模型 AI 编程 CLI 助手，支持 Claude、OpenAI、Gemini 等任意 OpenAI 兼容协议的模型。\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n zCli/ # 项目代码\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd zCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/zcli.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `/exit` 或 `/quit` | 退出程序 |\n| `Ctrl+C` | 强制退出 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：LangChain（`@langchain/openai` / `@langchain/anthropic` / `@langchain/google-genai`）\n- **Agent Loop**：完全自研（不使用 LangGraph）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}}, "HISTORY_README.md": {"77b80f9a4d92437741efa6136b6478bf10199ef5": {"t": 1785674144.2461865, "n": 12907, "h": "a0d307a432aa0c1e", "c": "# CCode\n\n**开源多模型 AI 编程 CLI 助手** — 对标 Claude Code 的交互体验，不绑定单一 LLM 提供商。\n\n> **C** = **C**odeYang（作者）、**C**hina（中国开发者出品）、**C**ode（编程助手）\n\n[](./LICENSE)\n[](https://www.npmjs.com/package/ccode-cli)\n\n---\n\n## 项目背景\n\n### 改名说明\n\n本项目原名 **ZCli / ZCode**，于 2026 年 3 月更名为 **CCode**。\n\n更名原因：\n- 原名 ZCode 与多个已有项目重名，npm 上 `zcli` 也已被占用\n- **CCode** 的 **C** 寓意 **C**odeYang（作者英文名）、**C**hina（中国开发者出品）、**C**ode Agent\n- npm 包名：`ccode-cli`，安装后命令：`ccode`\n- 配置目录从 `~/.zcli/` 迁移至 `~/.ccode/`，指令文件从 `ZCLI.md` 改为 `CCODE.md`\n\n> 如果你之前使用过旧版，只需将 `~/.zcli/` 重命名为 `~/.ccode/` 即可平滑迁移。\n\n### 为什么做这个\n\nClaude Code 是目前最好的 AI 编程 CLI 工具，但它有一个硬约束：**只能用 Claude 模型**。对于需要在不同场景下切换模型的开发者来说，这意味着要在多个工具之间反复切换，丢失上下文和工作流的连贯性。\n\nCCode 的目标是：**让开发者在终端中自由选择 Claude / GPT / Gemini / GLM / DeepSeek / 本地 Ollama 等任意模型，获得一致的 AI 辅助编码体验。** 同时完全兼容 Claude Code 的生态（CLAUDE.md 指令文件、MCP 协议、插件系统）。\n\n### 核心理念\n\n- **多模型自由切换** — 运行时 `/model` 一键切换，不重启、不丢上下文\n- **Claude Code 生态兼容** — CLAUDE.md、.mcp.json、插件目录结构完全兼容，已有配置零迁移\n- **Agent 能力完整** — 工具调用、并行执行、子 Agent 派发、权限管控、会话持久化\n- **可观测** — Token 计量计费、结构化日志、Session JSONL 全量审计\n- **Web 能力** — CLI 和浏览器双向实时同步，同一对话两端共享\n\n### 当前状态\n\nCCode 处于活跃开发阶段（v0.0.1），核心 Agent 能力已稳定，日常用于驱动自身的开发（self-hosting）。\n\n### 主要特性\n\n| 特性 | 说明 |\n|------|------|\n| 多模型支持 | Claude / OpenAI / Gemini / GLM / DeepSeek / Ollama，运行时切换 |\n| 内置工具集 | read / write / edit / glob / grep / bash + 子 Agent 派发 |\n| MCP 支持 | stdio / SSE / streamable-http，动态注册外部工具 |\n| Skills 系统 | 自研 Skill 体系 + 兼容 Claude Code 插件生态（superpowers 等） |\n| 对话持久化 | JSONL 会话文件 + --resume 恢复 + /fork 分支 |\n| Token 计量 | 四维 token 记录 + 多币种计价 + /usage 实时统计 |\n| 指令文件 | CCODE.md / CLAUDE.md 多层级注入，完全兼容 Claude Code |\n\n---\n\n## 目录结构\n\n```\nclaude_cli_z01/\n docs/ # 需求与设计文档\n cCli/ # 项目代码\n src/ # 核心源码（Agent Loop / Tools / Providers / UI）\n tests/ # 测试\n```\n\n---\n\n## 环境要求\n\n| 工具 | 版本 |\n|------|------|\n| Node.js | >= 20 |\n| pnpm | >= 9 |\n\n> 推荐使用 nvm 管理 Node.js 版本：\n> ```bash\n> nvm install 20\n> nvm use 20\n> ```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd cCli\npnpm install\n```\n\n### 2. 开发模式启动（推荐）\n\n```bash\npnpm dev\n```\n\n直接运行 TypeScript 源码，无需构建，修改代码后重启即可生效。\n\n### 3. 构建后运行\n\n```bash\npnpm build\nnode dist/bin/ccode.js\n```\n\n---\n\n## 界面操作\n\n| 操作 | 说明 |\n|------|------|\n| 直接打字 | 在底部输入框输入消息 |\n| `Enter` | 发送消息 |\n| `Escape` | 中断当前回复 |\n| `Ctrl+C` | 双击退出 |\n\n### 斜杠指令\n\n| 指令 | 说明 |\n|------|------|\n| `/help` | 查看所有指令 |\n| `/model` | 交互式切换模型 |\n| `/model <name>` | 直接切换到指定模型 |\n| `/clear` | 清空当前对话 |\n| `/resume` | 恢复历史会话 |\n| `/fork` | 从某条消息分支对话 |\n| `/usage` | 查看 Token 用量和费用 |\n| `/mcp` | 查看 MCP Server 连接状态 |\n| `/skills` | 列出可用 Skill |\n| `/gc` | 清理过期会话和用量记录 |\n| `/gc --days 0` | 清理全部会话（保留 0 天） |\n| `/gc --dry-run` | 预览将清理的数据量 |\n\n---\n\n## 其他命令\n\n```bash\n# 运行测试\npnpm test\n\n# 监听模式测试（开发时）\npnpm test:watch\n\n# TypeScript 类型检查\npnpm typecheck\n\n# 构建\npnpm build\n```\n\n---\n\n## 配置\n\nCCode 的配置文件位于 `~/.ccode/` 目录下，首次启动时自动创建。\n\n### config.json — 主配置\n\n路径：`~/.ccode/config.json`\n\n```jsonc\n{\n \"defaultProvider\": \"anthropic\",\n \"defaultModel\": \"claude-sonnet-4-6\",\n \"providers\": {\n // Anthropic 官方\n \"anthropic\": {\n \"apiKey\": \"sk-ant-xxxxx\",\n \"models\": [\"claude-opus-4-6\", \"claude-sonnet-4-6\", \"claude-haiku-4-5-20251001\"]\n },\n // OpenAI 兼容协议（GLM、DeepSeek、Ollama 等）\n \"glm\": {\n \"apiKey\": \"your-api-key\",\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n },\n \"openai\": {\n \"apiKey\": \"sk-xxxxx\",\n \"models\": [\"gpt-4o\", \"gpt-4o-mini\"]\n }\n }\n}\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultProvider` | `string` | 启动时默认使用的 Provider 名称 |\n| `defaultModel` | `string` | 启动时默认使用的模型名称 |\n| `providers.<name>.apiKey` | `string` | Provider 的 API Key |\n| `providers.<name>.baseURL` | `string?` | 自定义 API 端点 |\n| `providers.<name>.protocol` | `'anthropic' \\| 'openai'?` | 协议类型（见下方说明） |\n| `providers.<name>.models` | `string[]` | 该 Provider 可用的模型列表 |\n\n> 运行时可通过 `/model` 指令或 `/model <模型名>` 快速切换模型。\n\n### 快速上手：以 GLM 为例\n\n本项目日常开发使用 **智谱 GLM-5** 驱动。以下是一个最小化的 GLM 配置示例，可直接复制使用：\n\n```jsonc\n{\n \"defaultProvider\": \"glm\",\n \"defaultModel\": \"glm-5\",\n \"providers\": {\n \"glm\": {\n \"apiKey\": \"your-zhipu-api-key\", // 智谱开放平台 API Key\n \"baseURL\": \"https://open.bigmodel.cn/api/coding/paas/v4\",\n \"models\": [\"glm-5\", \"glm-4.7\"]\n }\n }\n}\n```\n\n**步骤：**\n\n1. 前往 [智谱开放平台](https://open.bigmodel.cn/) 注册并获取 API Key\n2. 将上述配置写入 `~/.ccode/config.json`，替换 `your-zhipu-api-key` 为你的真实 Key\n3. 启动 CCode（`pnpm dev`），即可使用 GLM-5 进行对话和 Agent 工具调用\n\n> GLM 走 **OpenAI 兼容协议**，无需额外声明 `protocol` 字段。如需切换模型，在对话中输入 `/model glm-4.7` 即可。\n\n### 接入 Anthropic 兼容协议的第三方 Provider\n\nCCode 支持两种 LLM 协议：**Anthropic 原生协议**和 **OpenAI 兼容协议**。\n\n- 名为 `anthropic` 的 provider 自动走 Anthropic 原生协议\n- 其他 provider 默认走 OpenAI 兼容协议\n- 通过 `protocol` 字段可以显式指定协议类型\n\n如果你使用的第三方 API 兼容 Anthropic Messages API（如 MiniMax），需要声明 `\"protocol\": \"anthropic\"`：\n\n```jsonc\n{\n \"defaultProvider\": \"minimax\",\n \"defaultModel\": \"MiniMax-M2.5\",\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-minimax-api-key\",\n \"baseURL\": \"https://api.minimaxi.com/anthropic\",\n \"protocol\": \"anthropic\",\n \"models\": [\"MiniMax-M2.5\", \"MiniMax-M2.5-highspeed\"]\n }\n }\n}\n```\n\n更多示例：\n\n```jsonc\n{\n \"providers\": {\n // DeepSeek — OpenAI 兼容，不需要写 protocol\n \"deepseek\": {\n \"apiKey\": \"sk-xxx\",\n \"baseURL\": \"https://api.deepseek.com/v1\",\n \"models\": [\"deepseek-chat\", \"deepseek-reasoner\"]\n },\n // 某个兼容 Anthropic API 的代理\n \"my-proxy\": {\n \"apiKey\": \"proxy-key\",\n \"baseURL\": \"https://my-proxy.example.com/anthropic/v1\",\n \"protocol\": \"anthropic\",\n \"models\": [\"claude-sonnet-4-6\"]\n }\n }\n}\n```\n\n### .mcp.json — MCP Server 配置\n\nCCode 支持 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，可连接外部工具服务器扩展 Agent 能力。\n\n**配置文件搜索路径（按优先级从高到低）：**\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1（最高） | `~/.ccode/.mcp.json` | CCode 专属配置 |\n| 2 | `~/.claude.json` | Claude Code 用户配置（兼容） |\n| 3 | `~/.mcp.json` | 通用 MCP 全局配置 |\n\n同名 Server 出现在多个文件时，高优先级覆盖低优先级。\n\n路径：`~/.ccode/.mcp.json`\n\n```jsonc\n{\n \"mcpServers\": {\n // Stdio 模式：启动本地子进程\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/allowed/dir\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n },\n // Streamable HTTP 模式：连接远程服务\n \"deepwiki\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://mcp.deepwiki.com/mcp\"\n },\n // SSE 模式\n \"my-sse-server\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n // HTTP 模式（兼容 .claude.json 格式，含自定义请求头）\n \"remote-api\": {\n \"type\": \"http\",\n \"url\": \"https://example.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token\"\n }\n }\n }\n}\n```\n\n**Server 配置字段：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `command` | `string?` | Stdio 模式：要执行的命令 |\n| `args` | `string[]?` | Stdio 模式：命令参数 |\n| `env` | `Record<string, string>?` | Stdio 模式：附加环境变量 |\n| `type` | `'stdio' \\| 'sse' \\| 'streamable-http' \\| 'http'?` | 传输类型（有 `command` 时默认 stdio，有 `url` 时默认 streamable-http） |\n| `url` | `string?` | 远程模式：服务端 URL |\n| `headers` | `Record<string, string>?` | HTTP/Streamable HTTP 模式：自定义请求头 |\n\n> 运行时可通过 `/mcp` 指令查看所有 Server 的连接状态和工具列表。\n\n---\n\n## 指令文件（CCODE.md / CLAUDE.md）\n\nCCode 支持通过指令文件向 LLM 注入自定义规范和偏好，**完全兼容 Claude Code 的 CLAUDE.md 生态**。\n\n### 工作原理\n\n启动时自动扫描以下位置的指令文件，内容注入 system prompt，LLM 在每次对话中自动遵循。\n\n**每个层级优先查找 `CCODE.md`，没有则 fallback 到 `CLAUDE.md`**（同层只取一个）。\n\n### 查找顺序\n\n| 优先级 | 路径 | 说明 |\n|--------|------|------|\n| 1 | `~/.ccode/CCODE.md` → `~/.claude/CLAUDE.md` | 全局用户级 — 你的通用编码习惯和偏好 |\n| 2 | `<git-root>/CCODE.md` → `<git-root>/CLAUDE.md` | 项目根 — 团队共享的项目规范 |\n| 3 | `<git-root>/.ccode/CCODE.md` → `<git-root>/.claude/CLAUDE.md` | 项目配置目录 |\n| 4 | `<cwd>/CCODE.md` → `<cwd>/CLAUDE.md` | 当前工作目录（仅当 cwd ≠ git-root 时） |\n\n所有找到的文件内容会按层级顺序拼接，一起注入 system prompt。\n\n### 兼容 Claude Code\n\n如果你已经在使用 Claude Code 并配置了 `CLAUDE.md`，**无需任何改动**，CCode 会自动加载：\n\n- `~/.claude/CLAUDE.md` — 你的全局 Claude Code 指令会被 CCode 直接复用\n- `<项目>/CLAUDE.md` — 项目级 Claude Code 指令同样生效\n\n当你想为 CCode 定制不同于 Claude Code 的指令时，在同层级放一个 `CCODE.md` 即可覆盖 `CLAUDE.md`。\n\n### 示例\n\n**全局指令**（`~/.ccode/CCODE.md` 或 `~/.claude/CLAUDE.md`）：\n\n```markdown\n# 编码规范\n\n- 永远使用中文与我对话\n- Git 提交信息遵循 Conventional Commits 格式\n- 优先使用 TypeScript，strict 模式\n- 异常处理：禁止空 catch 块\n```\n\n**项目级指令**（`<项目根>/CCODE.md` 或 `<项目根>/CLAUDE.md`）：\n\n```markdown\n# 项目约定\n\n- 这是一个 React + Vite 项目\n- 组件放在 src/components/，hooks 放在 src/hooks/\n- 使用 Tailwind CSS，不写内联样式\n- 测试框架：Vitest + Testing Library\n```\n\n### 注意事项\n\n- 指令文件在会话启动时加载，**会话期间修改不会自动生效**，需重启对话\n- 空文件或读取失败的文件会被静默跳过，不影响启动\n- REPL 模式和 Pipe 模式（`ccode \"问题\"`）均会加载指令文件\n\n---\n\n## 插件系统\n\nCCode 支持通过插件包扩展 Skill 能力，兼容 Claude Code 的插件生态（如 [superpowers](https://github.com/obra/superpowers)）。\n\n### 安装插件\n\n将插件目录复制到 `~/.ccode/plugins/` 下即可（目录名即为插件名）：\n\n```bash\n# 方式一：从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.ccode/plugins/superpowers\n\n# 方式二：直接复制已有目录\n# Linux / macOS\ncp -r /path/to/superpowers ~/.ccode/plugins/superpowers\n\n# Windows\nxcopy /E /I \"D:\\path\\to\\superpowers\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n```\n\n> 如果你已安装了 Claude Code 的 superpowers 插件，可以直接从缓存复制：\n> ```bash\n> # Windows\n> xcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n>\n> # Linux / macOS\n> cp -r ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.2 ~/.ccode/plugins/superpowers\n> ```\n\n项目级插件放在 `<项目根>/.ccode/plugins/` 下。\n\n### 插件目录结构\n\n```\n~/.ccode/plugins/\n └── superpowers/ ← 插件包名\n ├── skills/ ← skills 目录（必需）\n │ ├── brainstorming/\n │ │ ├── SKILL.md\n │ │ └── visual-companion.md ← 支撑文件\n │ ├── writing-plans/\n │ │ └── SKILL.md\n │ └── ...\n ├── hooks/ ← hooks 目录（可选）\n │ └── hooks.json\n └── plugin.json ← 插件清单（可选）\n```\n\n### 命名空间\n\n插件内的 Skill 自动添加 `<插件名>:` 前缀，避免与内置 Skill 冲突：\n\n| 来源 | 注册名示例 |\n|------|-----------|\n| 内置 Skill | `commit` |\n| 用户自定义 Skill | `my-tool` |\n| 插件 Skill | `superpowers:brainstorming` |\n\n**优先级**：项目级 > 用户级 > 插件 > 内置\n\n### 以 superpowers 为例\n\n```bash\n# 1. 安装：从 Claude Code 缓存复制（如果已安装 Claude Code superpowers 插件）\n# Windows\nxcopy /E /I \"%USERPROFILE%\\.claude\\plugins\\cache\\claude-plugins-official\\superpowers\\5.0.2\" \"%USERPROFILE%\\.ccode\\plugins\\superpowers\"\n\n# 或者从 Git 克隆\ngit clone https://github.com/obra/superpowers.git ~/.ccode/plugins/superpowers\n\n# 2. 启动 CCode，自动发现插件中的所有 Skills\npnpm dev\n```\n\n启动后 system prompt 中会包含 `superpowers:brainstorming`、`superpowers:writing-plans` 等 Skill 列表，LLM 会自动按需调用。\n\n---\n\n## Hook 系统\n\nCCode 支持事件钩子，可在会话启动、工具执行前后注入自定义逻辑。\n\n### 事件类型\n\n| 事件 | 触发时机 | 典型用途 |\n|------|----------|----------|\n| `SessionStart` | 会话启动 | 插件启动注入、环境检查 |\n| `PreToolUse` | 工具执行前 | 权限拦截、参数校验 |\n| `PostToolUse` | 工具执行后 | 结果审计、通知 |\n\n### 配置文件\n\nHook 配置来自三层来源（叠加执行，不覆盖）：\n\n| 来源 | 路径 |\n|------|------|\n| 插件包 | `~/.ccode/plugins/<name>/hooks/hooks.json` |\n| 项目级 | `<项目根>/.ccode/hooks.json` |\n| 用户级 | `~/.ccode/hooks.json` |\n\n### hooks.json 格式\n\n```jsonc\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"matcher\": \"startup|resume\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"additionalContext\\\": \\\"hello from hook\\\"}'\",\n \"timeout\": 10000\n }\n ]\n }\n ],\n \"PreToolUse\": [\n {\n \"matcher\": \"bash\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"echo '{\\\"decision\\\": \\\"allow\\\"}'\",\n \"timeout\": 5000\n }\n ]\n }\n ]\n }\n}\n```\n\n- `matcher`：正则表达式，匹配触发条件（SessionStart 匹配子类型，PreToolUse/PostToolUse 匹配工具名）\n- `timeout`：超时毫秒数，默认 10000\n- Hook 通过 stdout 输出 JSON 返回结果，超时或失败静默跳过\n\n> 插件包自带的 `hooks/hooks.json`（如 superpowers 的 SessionStart hook）会被自动发现和执行，无需手动配置。\n\n---\n\n## 项目级权限配置\n\nCCode 支持项目级工具权限白名单，白名单内的工具执行时无需确认，不在白名单内的仍遵循原有的询问确认机制。\n\n### 配置文件\n\n路径：`<项目根目录>/.ccode/settings.local.json`（首次启动时自动创建空模板）\n\n```jsonc\n{\n \"permissions\": {\n \"allow\": [\n \"Bash(*)\", // bash 命令免确认\n \"Read(*)\", // 读文件免确认\n \"Write(*)\", // 写文件免确认\n \"Edit(*)\", // 编辑文件免确认\n \"Glob(*)\", // 文件搜索免确认\n \"Grep(*)\", // 内容搜索免确认\n \"mcp__*\" // 所有 MCP 工具免确认\n ]\n }\n}\n```\n\n### 规则格式\n\n| 格式 | 示例 | 说明 |\n|------|------|------|\n| `FriendlyName(*)` | `Bash(*)`, `Read(*)` | 友好名匹配，自动解析为实际工具名 |\n| `前缀通配符` | `mcp__*` | 匹配所有以该前缀开头的工具 |\n| `精确工具名` | `mcp__context7__query-docs` | 精确匹配特定工具 |\n| `内部工具名` | `bash`, `read_file` | 直接使用内部注册的工具名 |\n\n> 默认模板为 `\"allow\": []`（空），即所有危险工具仍需确认。按需添加规则即可。\n\n> 建议将 `.ccode/settings.local.json` 加入 `.gitignore`，避免团队成员间权限配置冲突。\n\n---\n\n## 技术栈\n\n- **运行时**：Node.js 20 + TypeScript 5（strict 模式）\n- **终端 UI**：Ink 5 + React 18\n- **LLM 调用层**：`@anthropic-ai/sdk`（Anthropic 原生协议）+ `@langchain/openai`（OpenAI 兼容协议）\n- **Agent Loop**：完全自研（不使用 LangGraph），AsyncGenerator 事件流架构\n- **持久化**：JSONL 会话文件 + libsql（SQLite）\n- **包管理**：pnpm\n- **构建**：tsup\n- **测试**：Vitest\n"}}}} |