🧭 CmdCode 项目代码架构地图

CmdCode（npm包名 cmdclaw）是基于开源的 ClawCode 开发的终端中的 AI 编程助手，兼容 Anthropic Claude Code CLI 工具的大部分功能及工程化能力。

TypeScript Bun ≥1.2.0 2986 文件 / 56万行 Ink (React CLI) Hono (Web API)

仓库

git@gitee.com:xusuai/cmdcode.git

本地路径

/root/cmdcode/

开发命令

bun run scripts/dev.ts

构建命令

bun run build.ts

📦 核心技术栈

组件	技术	用途
CLI UI	Ink (React for CLI)	终端交互界面渲染
Web API	Hono	Web CLI 后端 REST + SSE
数据库	Bun:SQLite	Web端用户/会话/消息持久化
AI SDK	@anthropic-ai/sdk	Claude API 调用
模型支持	OpenAI兼容	DeepSeek等第三方模型
MCP	@modelcontextprotocol/sdk	工具/资源扩展协议
认证	bcryptjs + JWT	Web端用户认证
构建	Bun bundle	feature flags + tree-shaking

🌲 代码树与功能布局

src/                              # 主源码（2986文件, 56万行）
├── main.tsx                      🔑 主入口（5467行）Commander CLI定义+启动
├── QueryEngine.ts                🔑 查询引擎（1366行）Agent主循环核心
├── query.ts                      🔑 API查询层（1768行）消息构建+流式处理+compact
├── Tool.ts                       🔑 工具基类（806行）Tool接口定义+权限+上下文
├── tools.ts                      🔑 工具注册表（374行）getTools()加载所有工具
├── commands.ts                   🔑 命令注册表（853行）所有/命令导入+分发
├── history.ts                    # 命令历史管理
├── setup.ts                      # 初始化设置
├── context.ts                    # 全局上下文
├── cost-tracker.ts               # API成本追踪
│
├── entrypoints/                  🚀 入口点
│   ├── cli.tsx                   # CLI启动入口（快速路径+动态加载）
│   ├── init.ts                   # 初始化流程
│   ├── headless.ts               # 无头模式（非交互式）
│   ├── HeadlessSession.ts        # 无头会话
│   ├── mcp.ts                    # MCP服务器入口
│   ├── CliBridgeLocal.ts         # Bridge模式本地连接
│   └── sdk/                      # SDK类型定义
│
├── tools/                        🛠️ 54个工具（309文件）
│   ├── AgentTool/                🌟 多Agent系统（最复杂, AgentTool.tsx=72KB）
│   │   ├── AgentTool.tsx         # Agent工具主逻辑
│   │   ├── UI.tsx                # Agent渲染UI
│   │   ├── runAgent.ts           # Agent执行循环
│   │   ├── forkSubagent.ts       # 子Agent fork
│   │   └── built-in/             # 内置Agent工具集
│   ├── BashTool/                 # Shell命令执行
│   ├── FileEditTool/             # 文件编辑
│   ├── FileReadTool/             # 文件读取
│   ├── FileWriteTool/            # 文件写入
│   ├── GlobTool/                 # 文件搜索(glob)
│   ├── GrepTool/                 # 内容搜索(grep)
│   ├── WebSearchTool/            # 网络搜索
│   ├── WebFetchTool/             # 网页抓取
│   ├── WebBrowserTool/           # 浏览器工具
│   ├── MCPTool/                  # MCP协议工具调用
│   ├── SkillTool/                # 技能加载执行
│   ├── ConfigTool/               # 配置管理
│   ├── ScheduleCronTool/         # 定时任务
│   ├── SendMessageTool/          # 消息发送
│   ├── LSPTool/                  # LSP语言服务
│   ├── NotebookEditTool/         # Notebook编辑
│   ├── TodoWriteTool/            # TODO管理
│   └── ...（共54个工具目录）
│
├── services/                     📦 服务层（268文件）
│   ├── api/src/                  # Claude/OpenAI/Bedrock/Vertex API封装
│   ├── mcp/                      🔌 MCP协议
│   │   ├── client.ts             # MCP客户端连接
│   │   ├── MCPConnectionManager.tsx # MCP连接管理器
│   │   └── types.ts              # MCP类型定义
│   ├── compact/                  # 上下文压缩（autoCompact + reactiveCompact）
│   ├── analytics/                # 分析/遥测（GrowthBook A/B测试）
│   ├── oauth/                    # OAuth认证
│   ├── plugins/                  # 插件系统
│   ├── SessionMemory/            # 会话记忆
│   ├── autoDream/                # /dream 记忆整理
│   ├── extractMemories/          # 记忆提取
│   ├── skillSearch/              # 技能搜索
│   └── lsp/                      # LSP语言服务
│
├── components/                   🎨 UI组件（598文件）
│   ├── agents/                   # Agent UI组件
│   ├── permissions/              # 权限请求对话框（14种）
│   ├── messages/                 # 消息渲染组件
│   ├── PromptInput/              # 输入框组件
│   ├── tasks/                    # 任务UI（7种Task类型）
│   ├── mcp/                      # MCP UI
│   ├── skills/                   # 技能UI
│   ├── diff/                     # Diff显示
│   ├── Settings/                 # 设置面板
│   └── design-system/            # 设计系统
│
├── commands/                     ⌨️ 95个斜杠命令（231文件）
│   ├── help/ config/ compact/ model/ login/ status/
│   ├── doctor/ review/ memory/ mcp/ skills/ agents/
│   ├── tasks/ session/ cost/ permissions/ plan/
│   ├── commit/ resume/ export/ clear/ diff/
│   ├── vim/ voice/ theme/ keybindings/ locale/
│   ├── buddy/ bughunter/ teleport/ thinkback/ workflows/
│   └── ...（95个子目录）
│
├── utils/                        🔧 工具函数（814文件）
│   ├── model/                    # 模型管理
│   ├── permissions/              # 权限系统
│   ├── settings/                 # 配置管理
│   ├── bash/                     # Bash执行封装
│   ├── git/                      # Git操作
│   ├── github/                   # GitHub API
│   ├── hooks/                    # Hook系统
│   ├── processUserInput/         # 用户输入处理
│   ├── secureStorage/            # 安全存储（Keychain）
│   ├── skills/                   # 技能管理
│   ├── swarm/                    # Agent Swarms
│   └── computerUse/              # Computer Use
│
├── hooks/                        🪝 React Hooks（147文件）
├── ink/                          🖥️ Ink终端UI框架（104文件）
├── state/                        📊 状态管理（9文件）
│   ├── AppStateStore.ts          🔑 全局AppState定义
│   └── store.ts                  # 简单Store（setState+subscribe）
├── web-server/                   🌐 Web CLI后端（14文件）
├── skills/                       🎯 技能系统（28文件）
├── cli/                          💻 CLI处理（129文件）
├── bridge/                       🌉 Bridge模式（36文件）
├── i18n/                         🌍 国际化（8文件）
├── vim/                          ⌨️ Vim模式
├── voice/                        🎤 语音模式
├── native-ts/                    🔧 Native绑定
└── ...（共15个顶级模块）

🔄 核心数据流

用户输入
  │
  ├─ 斜杠命令 ──→ commands.ts ──→ 命令分发 ──→ 执行/显示
  │
  └─ 自然语言 ──→ processUserInput.ts ──→ QueryEngine.ts ──→ query.ts
                     │                         │                │
                     │                         │                ├─ 构建系统提示词
                     │                         │                ├─ 加载记忆(memdir)
                     │                         │                ├─ 创建用户消息
                     │                         │                ├─ 调用AI API (Claude/OpenAI/Bedrock)
                     │                         │                ├─ 流式接收响应
                     │                         │                │   ├─ 文本 → 直接渲染
                     │                         │                │   ├─ 思考 → 渲染thinking
                     │                         │                │   └─ 工具调用 → 权限检查 → 执行
                     │                         │                │
                     │                         │                ├─ 工具执行结果 → 追加消息 → 继续循环
                     │                         │                └─ 自动compact（超token阈值时）
                     │                         │
                     │                         ├─ 上下文管理
                     │                         ├─ 成本追踪(cost-tracker)
                     │                         └─ 会话持久化
                     │
                     └─ Ink渲染 ←── Message[] ←── StreamEvent[]

🌐 Web API 路由表

方法	路径	功能
POST	/api/auth/register	用户注册
POST	/api/auth/login	用户登录
GET	/api/auth/me	当前用户
GET	/api/chat/sessions	会话列表
POST	/api/chat/sessions	创建会话
GET	/api/chat/sessions/:id	会话详情
GET	/api/chat/sessions/:id/stream	SSE流式对话
DELETE	/api/chat/sessions/:id	删除会话
GET	/api/files	文件列表
POST	/api/files/read	读取文件
POST	/api/files/write	写入文件
GET	/api/config	获取配置
PUT	/api/config	更新配置
POST	/api/full-query/stream	完整引擎SSE

🌐 Web API 数据流

浏览器
  │
  ├─ /api/auth/* ──→ 注册/登录/JWT
  │
  ├─ /api/chat/* ──→ 会话CRUD
  │
  ├─ /api/chat/sessions/:id/stream ──→ SSE流式响应
  │     │
  │     └─ webQuery.ts ──→ 独立工具执行(DeepSeek API)
  │        或
  │     └─ fullQuery.ts ──→ 直连query.ts（完整引擎）
  │
  ├─ /api/files/* ──→ 工作空间文件管理
  │
  └─ /api/config/* ──→ 用户配置（LLM provider/API key/model）

🤖 Agent 系统架构

AgentTool.tsx
  │
  ├─ loadAgentsDir.ts ──→ 加载 .claude/agents/ 定义
  ├─ runAgent.ts ──→ Agent执行循环
  │     ├─ fork子进程执行
  │     ├─ 消息传递（父↔子）
  │     └─ 结果收集
  ├─ forkSubagent.ts ──→ 子Agent fork
  ├─ AgentMemory ──→ Agent间共享记忆
  │     ├─ agentMemory.ts ──→ 记忆读写
  │     └─ agentMemorySnapshot.ts ──→ 快照
  └─ built-in/ ──→ 内置Agent工具集
        ├─ BashTool
        ├─ FileEditTool
        ├─ FileReadTool
        ├─ FileWriteTool
        ├─ GlobTool / GrepTool
        └─ ...（与主工具集相同但独立实例）

💾 Web 数据库表

表名	字段	用途
users	id, username, email, password_hash	用户
sessions	id, user_id, title	会话
messages	id, session_id, role, content, tool_calls	消息
user_configs	user_id, llm_provider, api_endpoint, api_key_encrypted, model_name	用户配置

🏗️ 关键设计模式

1. Feature Flags

bun:bundle feature() — 编译时feature开关，tree-shake内构建模块

2. safeRequire

内部构建模块的安全加载，外部构建返回null

3. Store模式

简单Flux Store（setState+subscribe），非Redux

4. Ink渲染

React组件模型渲染终端UI，yoga-layout做Flexbox

5. SSE流式

Web端用Server-Sent Events实时推送AI响应

6. MCP协议

外部工具/资源通过MCP标准协议扩展

7. Compact机制

超token自动压缩上下文（autoCompact + reactiveCompact + contextCollapse）

8. 权限系统

14种权限请求类型，规则引擎控制自动/手动许可

9. Bridge模式

本地↔远程IDE双向通信

10. 用户隔离

Web端每个用户独立工作空间（./workspaces/user_xxx/）

📋 重要文件索引

文件	行数	功能
`src/main.tsx`	5467	CLI主入口，Commander定义
`src/tools/AgentTool/AgentTool.tsx`	~1800	Agent工具（最复杂）
`src/tools/AgentTool/runAgent.ts`	~900	Agent执行循环
`src/QueryEngine.ts`	1366	查询引擎主循环
`src/query.ts`	1768	API查询+流处理
`src/Tool.ts`	806	工具基类
`src/commands.ts`	853	命令注册
`src/tools.ts`	374	工具注册
`src/web-server/index.ts`	~100	Web API入口

📦 packages/ 子项目

packages/
├── @ant/
│   ├── claude-for-chrome-mcp/    # Chrome浏览器MCP
│   ├── computer-use-input/       # Computer Use输入
│   ├── computer-use-mcp/         # Computer Use MCP
│   └── computer-use-swift/       # macOS Swift原生
├── audio-capture-napi/           # 音频录制N-API
├── color-diff-napi/              # 颜色差异N-API
├── image-processor-napi/         # 图像处理N-API
├── modifiers-napi/               # 修饰键N-API
└── url-handler-napi/             # URL处理N-API