From 02694918b527de80e6b874b6ee7eb98bffdaec6a Mon Sep 17 00:00:00 2001 From: claude-code-best Date: Sat, 4 Apr 2026 21:09:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E5=8F=8A=E6=9E=84=E5=BB=BA=E8=84=9A=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 73 +-- Run.ps1 | 2 - TODO.md | 26 - V6.md | 1330 ++++++++++++++++++++++++++++++++++++++++++++++++++ build.ts | 9 +- package.json | 2 +- 6 files changed, 1357 insertions(+), 85 deletions(-) delete mode 100644 Run.ps1 delete mode 100644 TODO.md create mode 100644 V6.md diff --git a/README.md b/README.md index bb3ff7d90..4a9bf529a 100644 --- a/README.md +++ b/README.md @@ -16,48 +16,28 @@ [Discord 群组](https://discord.gg/qZU6zS7Q) -赞助商占位符 +- [x] V4 — 测试补全、[Buddy](https://ccb.agent-aura.top/docs/features/buddy)、[Auto Mode](https://ccb.agent-aura.top/docs/safety/auto-mode)、环境变量 Feature 开关 +- [x] V5 — [Sentry](https://ccb.agent-aura.top/docs/internals/sentry-setup) / [GrowthBook](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) 企业监控、[自定义 Login](https://ccb.agent-aura.top/docs/features/custom-platform-login)、[OpenAI 兼容](https://ccb.agent-aura.top/docs/plans/openai-compatibility)、[Web Search](https://ccb.agent-aura.top/docs/features/web-browser-tool)、[Computer Use](https://ccb.agent-aura.top/docs/features/computer-use) / [Chrome Use](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp)、[Voice Mode](https://ccb.agent-aura.top/docs/features/voice-mode)、[Bridge Mode](https://ccb.agent-aura.top/docs/features/bridge-mode)、[/dream 记忆整理](https://ccb.agent-aura.top/docs/features/auto-dream) +- [ ] V6 — 大规模重构石山代码，全面模块分包（全新分支，main 封存为历史版本） -- [x] v1 会完成跑通及基本的类型检查通过; -- [x] V2 会完整实现工程化配套设施; - - [ ] Biome 格式化可能不会先实施, 避免代码冲突 - - [x] 构建流水线完成, 产物 Node/Bun 都可以运行 -- [x] V3 会写大量文档, 完善文档站点 -- [x] V4 会完成大量的测试文件, 以提高稳定性 - - [x] Buddy 小宠物回来啦 [文档](https://ccb.agent-aura.top/docs/features/buddy) - - [x] Auto Mode 回归 [文档](https://ccb.agent-aura.top/docs/safety/auto-mode) - - [x] 所有 Feature 现在可以通过环境变量配置, 而不是垃圾的 bun --feature -- [x] V5 支持企业级的监控上报功能, 补全缺失的工具, 解除限制 - - [x] 移除牢 A 的反蒸馏代码!!! - - [x] 补全 web search 能力(用的 Bing 搜索)!!! [文档](https://ccb.agent-aura.top/docs/features/web-browser-tool) - - [x] 支持 Debug [文档](https://ccb.agent-aura.top/docs/features/debug-mode) - - [x] 关闭自动更新; - - [x] 添加自定义 sentry 错误上报支持 [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup) - - [x] 添加自定义 GrowthBook 支持 (GB 也是开源的, 现在你可以配置一个自定义的遥控平台) [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) - - [x] 自定义 login 模式, 大家可以用这个配置 Claude 的模型! [文档](https://ccb.agent-aura.top/docs/features/custom-platform-login) - - [x] Remote Control / Bridge Mode 支持 [文档](https://ccb.agent-aura.top/docs/features/bridge-mode) - - [x] 修复搜索工具的 rg 缺失问题(需要重新 bun i) - - [x] OpenAI 接口兼容! /login 然后配置 OpenAI 平台即可! [文档](https://ccb.agent-aura.top/docs/plans/openai-compatibility) - - [x] Any Use - - [x] 由于 Chrome Use 和 Computer Use 原本都是未完全验证的能力, 还是比较建议大家用社区里面的 MCP 支持 - - [x] Chrome use 支持 (浏览器插件要订阅权限 ) 感谢 @amDosion [文档](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp) - - [x] 普通用户可以使用 [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp/) 替代, 比较不那么折腾 - - [x] Computer use 支持 感谢 @amDosion [文档](https://ccb.agent-aura.top/docs/features/computer-use) - - [x] Mac 上可以用这个项目 [computer-use-mcp](https://github.com/domdomegg/computer-use-mcp) - - 注意这个库的命名方式与官方冲突了, 需要改为 `claude mcp add --scope user --transport stdio computer-use-mcp -- npx -y computer-use-mcp` - - [x] /voice 支持 @amDosion [文档](https://ccb.agent-aura.top/docs/features/voice-mode) - - [x] /dream 记忆整理命令（手动 + 自动后台触发） [文档](https://ccb.agent-aura.top/docs/features/auto-dream) -- [ ] V6 大规模重构石山代码, 全面模块分包 - - [ ] V6 将会为全新分支, 届时 main 分支将会封存为历史版本 -> 我不知道这个项目还会存在多久, Star + Fork + git clone + .zip 包最稳健; 说白了就是扛旗项目, 看看能走多远 -> -> 这个项目更新很快, 后台有 Opus 持续优化, 几乎几个小时就有新变化; -> -> Claude 已经烧了 1000$ 以上, 没钱了, 换成 GLM 继续玩; @zai-org GLM 5.1 非常可以; -> +## 快速开始(安装版) -## 快速开始 +不用克隆仓库, 从 NPM 下载后, 直接使用 + +```sh +bun i -g claude-code-best +bun pm -g trust claude-code-best +ccb # 直接打开 claude code +``` + +国内对 github 网络较差的, 需要先设置这个环境变量 + +```bash +DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-prebuilt/releases/download/v15.0.1 +``` + +## 快速开始(源码版) ### 环境要求 @@ -109,22 +89,7 @@ bun run build | Opus Model | 高性能模型 ID | `claude-opus-4-6` | - **Tab / Shift+Tab** 切换字段，**Enter** 确认并跳到下一个，最后一个字段按 Enter 保存 -- 模型字段会自动读取当前环境变量预填 -- 配置保存到 `~/.claude/settings.json` 的 `env` 字段，保存后立即生效 -也可以直接编辑 `~/.claude/settings.json`： - -```json -{ - "env": { - "ANTHROPIC_BASE_URL": "https://api.example.com/v1", - "ANTHROPIC_AUTH_TOKEN": "sk-xxx", - "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001", - "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6", - "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6" - } -} -``` > 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。 diff --git a/Run.ps1 b/Run.ps1 deleted file mode 100644 index 6741892cb..000000000 --- a/Run.ps1 +++ /dev/null @@ -1,2 +0,0 @@ -bun install -bun run dev --dangerously-skip-permissions \ No newline at end of file diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 5c0501f4d..000000000 --- a/TODO.md +++ /dev/null @@ -1,26 +0,0 @@ -# TODO - -尽可能实现下面的包, 使得与主包的关系完全吻合 - -## Packages - -- [x] `url-handler-napi` — URL 处理 NAPI 模块 (签名修正，保持 null fallback) -- [x] `modifiers-napi` — 修饰键检测 NAPI 模块 (Bun FFI + Carbon) -- [x] `audio-capture-napi` — 音频捕获 NAPI 模块 (SoX/arecord) -- [x] `color-diff-napi` — 颜色差异计算 NAPI 模块 (纯 TS 实现) -- [x] `image-processor-napi` — 图像处理 NAPI 模块 (sharp + osascript 剪贴板) - -- [x] `@ant/computer-use-swift` — Computer Use Swift 原生模块 (macOS JXA/screencapture 实现) -- [x] `@ant/computer-use-mcp` — Computer Use MCP 服务 (类型安全 stub + sentinel apps + targetImageSize) -- [x] `@ant/computer-use-input` — Computer Use 输入模块 (macOS AppleScript/JXA 实现) - - -## 工程化能力 - -- [x] 代码格式化与校验 -- [x] 冗余代码检查 -- [x] git hook 的配置 -- [x] 代码健康度检查 -- [x] Biome lint 规则调优（适配反编译代码，关闭格式化避免大规模 diff） -- [x] 单元测试基础设施搭建 (test runner 配置) -- [x] CI/CD 流水线 (GitHub Actions) diff --git a/V6.md b/V6.md new file mode 100644 index 000000000..3d970340a --- /dev/null +++ b/V6.md @@ -0,0 +1,1330 @@ +# Claude Code 架构重构规划 + +## 一、当前架构 (As-Is) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Entry Layer │ +│ cli.tsx → main.tsx (4680行) ─┬─→ REPL.tsx (5005行, 交互) │ +│ ├─→ print.ts (Headless/Pipe) │ +│ └─→ SDK (QueryEngine) │ +├─────────────────────────────────────────────────────────────────┤ +│ Core Monolith │ +│ │ +│ ┌──────────┐ ┌──────────────┐ ┌───────────────────────┐ │ +│ │ query.ts │←──│ QueryEngine │ │ AppState (199行类型) │ │ +│ │ (1732行) │ │ (1320行) │ │ UI+MCP+Bridge+ │ │ +│ │ │ │ │ │ Perm+Plugin+Agent │ │ +│ └────┬─────┘ └──────────────┘ └───────────────────────┘ │ +│ │ │ +│ ┌────▼─────────────────────────────────────────────────────┐ │ +│ │ services/api/claude.ts (3415行) │ │ +│ │ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌───────────┐ │ │ +│ │ │Anthropic│ │ Bedrock │ │ Vertex │ │ OpenAI │ │ │ +│ │ │ (主路径)│ │(if分支) │ │(if分支) │ │ (882行 │ │ │ +│ │ │ │ │ │ │ │ │ 已实现) │ │ │ +│ │ └─────────┘ └──────────┘ └─────────┘ └───────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌────▼──────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ tools.ts │ │ services/mcp/│ │ auth.ts │ │ +│ │ (硬编码列表) │ │ client.ts │ │ (2001行,7种认证) │ │ +│ │ 54个Tool │ │ (3351行) │ │ +oauth/(12文件) │ │ +│ └───────────────┘ └──────────────┘ └──────────────────┘ │ +│ │ +│ ┌───────────────┐ ┌───────────────┐ ┌─────────────────┐ │ +│ │ sessionStorage│ │ context.ts │ │ ink/ (104文件) │ │ +│ │ (5106行,JSONL)│ │ (189行,轻量) │ │ (UI框架) │ │ +│ └───────────────┘ └───────────────┘ └─────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ 隐蔽巨文件 │ │ +│ │ tasks/LocalMainSessionTask.ts (15373行) ← 全库最大单文件 │ │ +│ │ utils/hooks.ts (5177行) + hooks/ (5文件 1494行) │ │ +│ │ components/ (596文件) ← UI组件, 低估 3.5x │ │ +│ └───────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + +耦合特征: + ● main.tsx ~2867行内联 action handler (L1003-L3870), 51个subcommand + ● REPL.tsx God Component: 54 useState, 68 useEffect, ~30 自定义Hook + ● AppState 单一类型混合 7+ 个域 (UI/MCP/Permission/Bridge/Agent/Plugin/Team) + ● Provider 分发靠 if/else 字符串比较 (108处 provider 相关引用) + ● Tool 注册为静态列表 (getAllBaseTools), 54个工具, 无发现机制 + ● auth.ts (2001行) + oauth服务 (12文件 1077行) + 其他 (~779行), 总计约3857行 + ● hooks.ts 5177行, 27种 hook 事件类型, 混杂在 utils/ 中 + ● LocalMainSessionTask.ts 15373行为全库最大单体文件, 文档此前未提及 +``` + +--- + +## 二、目标架构 (To-Be) + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Entry Layer │ +│ │ +│ cli.tsx ──→ main.tsx (瘦身) ─┬─→ REPL (纯 UI, Hook 编排) │ +│ ├─→ Headless (JSON 输出) │ +│ ├─→ SDK (程序化接口) │ +│ └─→ Deep Links (claude:// 协议) │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────── packages/agent ──────────────────────────┐ │ +│ │ (核心引擎, 零 UI 依赖) │ │ +│ │ │ │ +│ │ query() QueryEngine HookLifecycle │ │ +│ │ ├─ streaming ├─ turn管理 ├─ PreToolUse │ │ +│ │ ├─ recovery ├─ compaction ├─ PostToolUse │ │ +│ │ ├─ attachments ├─ SDK消息转换 ├─ Notification │ │ +│ │ └─ abort └─ budget追踪 ├─ Stop │ │ +│ │ ├─ SubagentStop │ │ +│ │ CompactionService CronScheduler ├─ UserPromptSubmit │ │ +│ │ (snip/micro/auto) (定时任务/抖动) ├─ SessionStart/End │ │ +│ │ ├─ PreCompact/ │ │ +│ │ LocalMainSessionTask │ PostCompact │ │ +│ │ (15373行 → 分解重构) ├─ Permission* │ │ +│ │ └─ ... (27种事件) │ │ +│ │ QueryDeps (依赖注入) │ │ +│ └──────────────────────────┬────────────────────────────────────┘ │ +│ │ │ +├─────────────────────────────┼───────────────────────────────────────────┤ +│ ▼ │ +│ ┌──────────────── packages/provider ────────────────────────┐ │ +│ │ (适配器层, 可扩展) │ │ +│ │ │ │ +│ │ ┌─────────────────┐ ┌────────────────┐ │ │ +│ │ │ ProviderAdapter │ │ AuthProvider │ │ │ +│ │ │ ├─queryStream() │ │ ├─getCredentials() │ │ +│ │ │ ├─query() │ │ ├─refresh() │ │ │ +│ │ │ ├─isAvailable() │ │ └─invalidate() │ │ │ +│ │ │ └─listModels() │ └────────────────┘ │ │ +│ │ └────────┬────────┘ │ │ +│ │ │ │ │ +│ │ ┌────────▼────────────────────────────────────────┐ │ │ +│ │ │ StreamAdapter (归一化) │ │ │ +│ │ │ 将任意 SSE/WS/流 → 统一的内部事件格式 │ │ │ +│ │ └─────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ ContextProvider (可插拔 prompt 管线) │ │ │ +│ │ │ GitStatus → ClaudeMd → Date → Attribution → ... │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ NetworkLayer (网络/代理) │ │ │ +│ │ │ Proxy / mTLS / CA证书 / Upstream Proxy │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ │ +├─────────────────────────────┼───────────────────────────────────────────┤ +│ ▼ │ +│ ┌──────────────── 具体实现 (Implementation) ──────────────────────┐ │ +│ │ │ │ +│ │ LLM Providers Auth Implementations │ │ +│ │ ├─ Anthropic ├─ AnthropicOAuth │ │ +│ │ ├─ OpenAI ├─ APIKey (Keychain/env/config) │ │ +│ │ ├─ Gemini ├─ AWS (Bedrock IAM) │ │ +│ │ ├─ Mistral ├─ GCP (Vertex ADC) │ │ +│ │ ├─ Bedrock └─ Azure (Managed Identity) │ │ +│ │ ├─ Vertex │ │ +│ │ ├─ 通义千问 Storage Backends │ │ +│ │ └─ 本地推理 ├─ LocalFile (JSONL) │ │ +│ │ (llama.cpp/vLLM) ├─ RemoteAPI │ │ +│ │ └─ Memory (测试) │ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +│ │ +├────────────────────────────────── UI ───────────────────────────────────┤ +│ │ +│ ┌──────────── packages/ink ───────────────────────────────────────┐ │ +│ │ UI 框架 (104文件 + 扩展) │ │ +│ │ ├─ reconciler / hooks (useInput等) / components │ │ +│ │ ├─ Keybinding 系统 (可配置键绑定, 模式解析, 冲突解决) │ │ +│ │ ├─ Vim Emulation (motions / operators / text objects) │ │ +│ │ ├─ Typeahead (命令/文件建议, 模糊搜索, ghost text) │ │ +│ │ └─ InkConfig (12个注入点) │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +├──────────────────────── 基础设施层 ─────────────────────────────────────┤ +│ │ +│ ┌──────── packages/agent-tools ──────────────────────────────────┐ │ +│ │ Agent 工具库 (纯逻辑) │ │ +│ │ ├─ Tool interface + 54 个工具实现 │ │ +│ │ ├─ Sandbox 系统 (沙盒隔离执行) │ │ +│ │ ├─ configs, aliases, cost, deprecation, contextWindow │ │ +│ │ └─ ModelDeps (注入点) │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────── packages/shell ────────────────────────────────────────┐ │ +│ │ Shell 执行层 (独立抽象, 零 UI 依赖) │ │ +│ │ ├─ ShellProvider 接口 (统一 bash/zsh/PowerShell) │ │ +│ │ ├─ Bash/Zsh 实现 (命令前缀注入/超时/环境构建) │ │ +│ │ ├─ PowerShell 实现 (Windows 路径转换/FindGitBash) │ │ +│ │ └─ 子进程环境构建 (subprocessEnv) │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────── packages/config ───────────────────────────────────────┐ │ +│ │ 配置管理 (基础设施层, 被所有模块依赖) │ │ +│ │ ├─ SettingsManager (7层优先级合并: user→project→local→ │ │ +│ │ │ policy→flag→command→session) │ │ +│ │ ├─ FeatureFlagProvider (BunBundle/EnvVar/ConfigFile/Remote) │ │ +│ │ ├─ SettingsSync (跨设备同步) │ │ +│ │ ├─ RemoteManagedSettings (企业管控) │ │ +│ │ └─ GlobalConfig (apiKey/oauthToken等, config.ts 1821行) │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────── packages/telemetry ────────────────────────────────────┐ │ +│ │ 遥测/诊断 (真实实现, 非空 stub, 需谨慎处理) │ │ +│ │ ├─ AnalyticsEventEmitter (OTel日志导出+JSONL批处理, 806行) │ │ +│ │ ├─ GrowthBook客户端 (AB测试/FeatureFlag, 1163行) │ │ +│ │ ├─ Datadog日志 (日志上传, 321行) │ │ +│ │ ├─ SessionTracer (OTel兼容会话追踪) │ │ +│ │ └─ Metadata (事件元数据enrichment, 973行) │ │ +│ │ 总计: services/analytics/ (10文件, 4062行) │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +├──────────────────────── 领域系统 ───────────────────────────────────────┤ +│ │ +│ ┌──────── packages/memory ───────────────────────────────────────┐ │ +│ │ 记忆系统 (独立实现, 零 UI 依赖) │ │ +│ │ ├─ MemoryStore (存储抽象) / MemoryRecall (相关性检索) │ │ +│ │ ├─ MemoryExtract (后台提取) / MemoryConsolidation (合并/清理) │ │ +│ │ └─ 类型: user / feedback / project / reference │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────── packages/permission ───────────────────────────────────┐ │ +│ │ 权限系统 (独立实现, 零 UI 依赖) │ │ +│ │ ├─ PermissionMode (8种模式) / PermissionPipeline (检查管线) │ │ +│ │ ├─ RuleStore (allow/deny/ask 规则) / AutoClassifier (AI分类) │ │ +│ │ └─ ToolPermissionContext │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +├──────────────────────── 扩展系统 (Phase 5) ─────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────────┐ ┌──────────────────────────┐ │ +│ │ ToolRegistry │ │ OutputTarget │ │ packages/swarm │ │ +│ │ ├─ 内置(静态)│ │ ├─ Terminal(Ink) │ │ (多Agent协调) │ │ +│ │ ├─ MCP(动态) │ │ ├─ JSON (SDK) │ │ ├─ Backends │ │ +│ │ ├─ Plugin │ │ ├─ Web (未来) │ │ │ (进程/Tmux/iTerm2) │ │ +│ │ └─ 用户自定义│ │ └─ Silent (后台) │ │ ├─ PermissionSync │ │ +│ └──────────────┘ └──────────────────┘ │ ├─ TeammateMailbox │ │ +│ │ └─ Worktree管理 │ │ +│ ┌──────────────────┐ ┌───────────────┐ └──────────────────────────┘ │ +│ │ packages/ide │ │ packages/server│ │ +│ │ ├─ VS Code │ │ ├─ DirectConn │ ┌──────────────────────────┐ │ +│ │ ├─ JetBrains │ │ └─ LockFile │ │ packages/teleport │ │ +│ │ ├─ LSP Client │ │ (6/11文件stub │ │ ├─ 环境选择/配置 │ │ +│ │ ├─ Code Indexing │ │ 仅371行有效) │ │ ├─ Git 打包 │ │ +│ │ └─ Claude-in- │ │ └─ API 集成 │ │ +│ │ Chrome │ └──────────────────────────┘ │ +│ └──────────────────┘ │ +│ ┌──────────────────────────┐ │ +│ ┌──────────────────┐ │ packages/updater │ │ +│ │ packages/cli │ │ ├─ NativeInstaller │ │ +│ │ ├─ Transport │ │ │ (.deb/.rpm/.pkg) │ │ +│ │ │ (Hybrid/SSE/ │ │ ├─ BinaryDownload │ │ +│ │ │ WS/Worker) │ │ └─ AutoUpdateCheck │ │ +│ │ ├─ StructuredIO │ └──────────────────────────┘ │ +│ │ └─ Rollback │ │ +│ └──────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 三、单体文件分解图 + +``` +main.tsx (4680行) REPL.tsx (5005行) +┌──────────────────────┐ ┌──────────────────────────┐ +│ main() (安全/URL/argv)│ │ God Component │ +├──────────────────────┤ │ 54 useState, 68 useEffect│ +│ .action() handler │ │ ~30 自定义 Hook │ +│ ┌──────────────────┐ │ │ │ +│ │ parseActionOptions│ │ │ ┌─ useQueryLifecycle ──┐│ +│ │ (L1003-L3870, │ │ │ │ query生命周期 (830行) ││ +│ │ ~2867行内联) │ │ │ │ 权限回调, abort处理 ││ +│ ├──────────────────┤ │ │ └──────────────────────┘│ +│ │ mcpSetup │ │ │ ┌─ usePromptSubmit ────┐│ +│ ├──────────────────┤ │ │ │ 命令解析, 队列 (350行)││ +│ │ headlessSetup │ │ │ └──────────────────────┘│ +│ │ buildInitialState│ │ │ ┌─ useDialogManager ───┐│ +│ ├──────────────────┤ │ │ │ 通知优先级 (20路) ││ +│ │ sessionResume │ │ │ └──────────────────────┘│ +│ └──────────────────┘ │ │ ┌─ useScrollManager ───┐│ +├──────────────────────┤ │ │ 视口状态机 (135行) ││ +│ 51个 subcommands │ │ └──────────────────────┘│ +│ mcp/server/ssh/auth │ │ ┌─ useSessionInit ─────┐│ +│ plugin/doctor/update │ │ │ 初始化, initial msg ││ +│ agents/task/autoMode │ │ └──────────────────────┘│ +└──────────────────────┘ └──────────────────────────┘ + +query.ts (1732行) AppState (199行类型定义) +┌──────────────────────┐ ┌──────────────────────────┐ +│ query() 异步生成器 │ │ 单一嵌套类型, ~90字段 │ +│ ┌──────────────────┐ │ │ │ +│ │compactionPipeline│ │ │ ┌─ UISlice ────────────┐│ +│ │ (snip/micro/auto)│ │ │ │ verbose, expanded, ││ +│ ├──────────────────┤ │ │ │ footer, spinner ││ +│ │streamingOrchestrator │ └─────────────────────┘│ +│ │ (流+错误+abort) │ │ │ ┌─ MCPSlice ───────────┐│ +│ ├──────────────────┤ │ │ │ clients, tools, ││ +│ │ recovery │ │ │ │ commands, resources ││ +│ │ (max_tokens/ptl) │ │ │ └─────────────────────┘│ +│ ├──────────────────┤ │ │ ┌─ PermissionSlice ────┐│ +│ │ attachments │ │ │ │ toolPermissionContext││ +│ │ (files/mem/skill)│ │ │ └─────────────────────┘│ +│ └──────────────────┘ │ │ ┌─ BridgeSlice ────────┐│ +└──────────────────────┘ │ │ replBridge* (~20字段)││ + │ └─────────────────────┘│ +services/mcp/client.ts (3351行) │ ┌─ AgentSlice ─────────┐│ +┌──────────────────────┐ │ │ tasks, agents, team ││ +│ ┌──────────────────┐ │ │ └─────────────────────┘│ +│ │transportManager │ │ │ ┌─ PluginSlice ────────┐│ +│ │(stdio/SSE/WS) │ │ │ │ enabled, commands ││ +│ ├──────────────────┤ │ │ └─────────────────────┘│ +│ │ toolDiscovery │ │ └──────────────────────────┘ +│ │(MCPTool实例化) │ │ +│ ├──────────────────┤ │ → Domain Slicing: +│ │ authManager │ │ type AppState = UISlice +│ │(OAuth+重连) │ │ & MCPSlice & PermissionSlice +│ └──────────────────┘ │ & BridgeSlice & AgentSlice +└──────────────────────┘ & PluginSlice & TeamSlice + +LocalMainSessionTask.ts (15373行) ← 全库最大单体文件 +┌──────────────────────┐ (此前文档未提及) +│ 单文件承担本地主会话 │ +│ 全部生命周期管理 │ +│ 包含: turn管理/消息 │ +│ 处理/工具调用/权限 │ +│ 恢复/compaction等 │ +│ 分解优先级: P1 │ +└──────────────────────┘ +``` + +--- + +## 四、适配器层详解 + +### 4.1 LLM Provider 适配器 (P1) + +``` + ┌─────────────────────────┐ + │ agent │ + │ query() / QueryEngine │ + └────────────┬────────────┘ + │ + ┌────────────▼────────────┐ + │ ProviderAdapter │ + │ ┌─ queryStreaming() │ + │ ├─ query() │ + │ ├─ isAvailable() │ + │ └─ listModels() │ + └────────────┬────────────┘ + │ + ┌──────────────────┼──────────────────┐ + │ │ │ + ┌─────────▼──────┐ ┌────────▼───────┐ ┌────────▼───────┐ + │ Anthropic │ │ OpenAI │ │ Gemini │ + │ │ │ (已有参考) │ │ (新增) │ + │ ┌────────────┐ │ │ ┌────────────┐│ │ ┌────────────┐ │ + │ │消息格式转换 │ │ │ │消息格式转换││ │ │消息格式转换│ │ + │ └────────────┘ │ │ └────────────┘│ │ └────────────┘ │ + │ ┌────────────┐ │ │ ┌────────────┐│ │ ┌────────────┐ │ + │ │工具格式转换 │ │ │ │工具格式转换││ │ │工具格式转换│ │ + │ └────────────┘ │ │ └────────────┘│ │ └────────────┘ │ + │ ┌────────────┐ │ │ ┌────────────┐│ │ ┌────────────┐ │ + │ │StreamAdapter│ │ │StreamAdapter ││ │StreamAdapter │ │ + │ │(原生) │ │ │(SSE→内部) ││ │(SSE→内部) │ │ + │ └────────────┘ │ │ └────────────┘│ │ └────────────┘ │ + └────────────────┘ └───────────────┘ └────────────────┘ + ↑ ↑ ↑ + ┌────┴────────────────────┴──────────────────┴────┐ + │ 归一化事件格式 │ + │ content_block_start/delta/stop │ + │ message_start/delta/stop │ + │ error │ + └──────────────────────────────────────────────────┘ + +当前问题: claude.ts 3415行单体, Bedrock/Vertex 靠 if/else 分支 (108处provider引用) +参考实现: src/services/api/openai/ (6文件, 882行) + ├─ streamAdapter.ts (310行, SSE→内部事件流) + ├─ convertMessages.ts (184行, 消息格式转换) + ├─ convertTools.ts (68行, 工具格式转换) + ├─ modelMapping.ts (56行, 模型名称映射) + ├─ client.ts (48行, OpenAI客户端) + └─ index.ts (216行, 入口+queryModel) +已验证可行: 通过 CLAUDE_CODE_USE_OPENAI=1 启用, 流适配器模式已跑通 +``` + +### 4.2 Auth Provider 适配器 (P1, 与 LLM 配套) + +``` +┌──────────────────────────────────────────────────┐ +│ ProviderAdapter │ +│ 需要 Credentials 才能工作 │ +└─────────────────────┬────────────────────────────┘ + │ + ┌────────────▼────────────┐ + │ AuthProvider │ + │ ┌─ getCredentials() │ + │ ├─ refresh() │ + │ ├─ isAuthenticated() │ + │ └─ invalidate() │ + └────────────┬───────────┘ + │ + ┌────────┬────────┼────────┬──────────┐ + │ │ │ │ │ +┌───▼──┐ ┌──▼───┐ ┌──▼──┐ ┌──▼──┐ ┌────▼───┐ +│OAuth │ │APIKey│ │ AWS │ │ GCP │ │ Azure │ +│ │ │ │ │ │ │ │ │ │ +│PKCE │ │Keych │ │IAM │ │ADC │ │Managed │ +│flow │ │env │ │STS │ │ │ │Identity│ +│ │ │config│ │ │ │ │ │ │ +└──────┘ └──────┘ └─────┘ └─────┘ └────────┘ + +当前问题: auth.ts (2001行) + oauth/(12文件 1077行) + 其他(~779行) = 总计约3857行 + 7种认证: APIKey/OAuth/Bedrock IAM/Vertex ADC/Keychain/ApiKeyHelper/Foundry +已有实现: 全部可从现有代码提取 +``` + +### 4.3 Tool Registry (P1) + +``` +┌───────────────────────────────────────────┐ +│ ToolRegistry │ +│ │ +│ register(tool) unregister(name) │ +│ get(name) getAll() │ +│ │ +│ ┌─────────────────────────────────────┐ │ +│ │ 发现机制 │ │ +│ │ 1. BuiltInTools ─── 静态注册 │ │ +│ │ 2. MCPTools ─── 动态加载 (已有)│ │ +│ │ 3. PluginTools ─── npm包+配置 │ │ +│ │ 4. UserTools ─── ~/.claude/ │ │ +│ └─────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ 统一 AgentTool 接口 │ +│ call() / checkPermissions() │ +│ isEnabled() / isReadOnly() │ +└───────────────────────────────────────────┘ + +当前问题: tools.ts getAllBaseTools() 硬编码 54个 (20常驻 + 34条件, feature()控制) +优势: Tool 接口已很干净, MCPTool 已证明动态加载 +``` + +### 4.4 Storage Backend (P2) + +``` +┌───────────────────────────────────────────┐ +│ Project (会话管理) │ +│ 写队列 / 刷新 / 远程同步 │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ StorageBackend │ │ +│ │ read/write/append │ │ +│ │ delete/list │ │ +│ └──────────┬──────────┘ │ +│ │ │ +│ ┌───────────────┼───────────────┐ │ +│ │ │ │ │ +│ ┌──▼──────┐ ┌─────▼──────┐ ┌─────▼───┐ │ +│ │LocalFile│ │ RemoteAPI │ │ Memory │ │ +│ │(JSONL) │ │(已有部分) │ │(测试用) │ │ +│ └─────────┘ └────────────┘ └─────────┘ │ +└───────────────────────────────────────────┘ + +当前问题: sessionStorage.ts (5106行, JSONL) + sessionRestore.ts (551行) + + sessionStoragePortable.ts (793行) + listSessionsImpl.ts (454行) + = 总计约6968行, 硬编码 JSONL 格式 +已有基础: hydrateRemoteSession / persistToRemote 部分实现 +``` + +### 4.5 Output Target (P3) + +``` +┌───────────────────────────────────────────┐ +│ agent │ +│ (产出 Message/Event) │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ OutputTarget │ │ +│ │ renderMessage() │ │ +│ │ renderToolProgress()│ │ +│ │ renderError() │ │ +│ │ renderPermission() │ │ +│ └──────────┬──────────┘ │ +│ │ │ +│ ┌─────────┬───────┼────────┬──────────┐ │ +│ │ │ │ │ │ │ +│ ┌▼───────┐┌▼─────┐┌▼──────┐┌▼────────┐ │ │ +│ │Terminal││ JSON ││ Web ││ Silent │ │ │ +│ │(Ink) ││(SDK) ││(未来) ││(后台) │ │ │ +│ └────────┘└──────┘└───────┘└─────────┘ │ │ +└───────────────────────────────────────────┘ + +当前问题: 170+组件耦合 Ink API, 3种输出路径未抽象 +已有分支: headless/pipe 绕过 Ink, SDK 跳过 Ink +``` + +### 4.6 Context Pipeline (P2) + +``` +┌──────────────────────────────────────────────────┐ +│ System Prompt 装配 │ +│ │ +│ ┌────────────────────────────────────────────┐ │ +│ │ ContextProvider[] │ │ +│ │ (按 priority 排序, 可插拔) │ │ +│ │ │ │ +│ │ ┌─ GitStatusProvider ──── priority: 10 │ │ +│ │ ├─ ClaudeMdProvider ──── priority: 20 │ │ +│ │ ├─ DateProvider ──────── priority: 30 │ │ +│ │ ├─ AttributionProvider ─ priority: 40 │ │ +│ │ ├─ AdvisorProvider ──── priority: 50 │ │ +│ │ └─ CustomProvider ────── priority: 99 │ │ +│ │ (用户通过配置注册) │ │ +│ └────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ 最终 System Prompt │ +└──────────────────────────────────────────────────┘ + +当前问题: context.ts (189行, 轻量) 提供上下文, claude.ts buildSystemPromptBlocks() + 做 prompt 缓存分块, 无自定义 hook 点 +改动范围: 集中在 prompt 装配逻辑 (claude.ts + context.ts) +``` + +### 4.7 Hook 生命周期 (P1, 核心扩展机制) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ HookLifecycle (packages/agent 内) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Hook 点 (用户在 settings.json 配置 shell 命令) │ │ +│ │ 共 27 种事件, 按类型分组: │ │ +│ │ │ │ +│ │ 工具相关: │ │ +│ │ ├─ PreToolUse 工具调用前 → 可阻止/修改输入 │ │ +│ │ ├─ PostToolUse 工具调用后 → 可修改输出 │ │ +│ │ └─ PostToolUseFailure 工具调用失败后 │ │ +│ │ 会话相关: │ │ +│ │ ├─ SessionStart/End 会话生命周期 │ │ +│ │ ├─ UserPromptSubmit 用户提交输入时 │ │ +│ │ ├─ Stop/StopFailure 对话停止时 │ │ +│ │ ├─ PreCompact/PostCompact 上下文压缩前后 │ │ +│ │ └─ CwdChanged 工作目录变更时 │ │ +│ │ 子Agent/团队: │ │ +│ │ ├─ SubagentStart/Stop 子Agent生命周期 │ │ +│ │ ├─ TeammateIdle 队友空闲时 │ │ +│ │ ├─ TaskCreated/Completed 任务生命周期 │ │ +│ │ └─ WorktreeCreate/Remove Worktree管理 │ │ +│ │ 权限/通知: │ │ +│ │ ├─ Notification 通知触发 → 自定义渠道 │ │ +│ │ ├─ PermissionRequest/Denied 权限审批 │ │ +│ │ ├─ Elicitation/Result 用户反馈请求 │ │ +│ │ └─ ConfigChange 配置变更时 │ │ +│ │ 其他: Setup, InstructionsLoaded, FileChanged │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────▼──────────────────────────────────────┐ │ +│ │ HookExecutor (hooks.ts, 5177行 → 提取为独立模块) │ │ +│ │ │ │ +│ │ ├─ spawnShellCommand() → 执行用户配置的 shell 命令 │ │ +│ │ ├─ parseJsonOutput() → 解析 hook 的 JSON 输出 │ │ +│ │ ├─ timeout / abort → 超时和中断处理 │ │ +│ │ ├─ hooksConfigSnapshot → 配置快照 (热加载) │ │ +│ │ └─ fileChangedWatcher → 文件变更监听触发 hook │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: hooks.ts (5177行) + hooks/ (5文件 1494行) = 6713行 │ +│ 混杂在 utils/ 中, 27种事件类型全部硬编码 │ +│ 改动范围: 提取到 packages/agent/hooks/, 作为核心生命周期 │ +│ 依赖关系: HookExecutor ← ToolRegistry (PreToolUse/PostToolUse) │ +│ HookExecutor ← QueryEngine (Stop/SubagentStop) │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.8 Shell 执行层 (P2, BashTool 底层依赖) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ packages/shell (~19000行) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ ShellProvider 接口 │ │ +│ │ ├─ spawn(command, options) → ShellResult │ │ +│ │ ├─ getShellPath() → string │ │ +│ │ ├─ buildEnv(context) → Record │ │ +│ │ └─ wrapCommand(cmd, sandbox) → string (前缀注入) │ │ +│ └──────────────────────────┬──────────────────────────────────┘ │ +│ │ │ +│ ┌────────────────────┼──────────────────────┐ │ +│ │ │ │ │ +│ ┌──────▼─────────┐ ┌──────▼─────────┐ ┌────────▼──────────┐ │ +│ │ BashProvider │ │ ZshProvider │ │ PowerShellProvider│ │ +│ │ │ │ │ │ │ │ +│ │ ├─ bash/(24文件)│ │ ├─ .zshrc 检测│ │ ├─ powershell/ │ │ +│ │ │ 12310行 │ │ ├─ 插件兼容 │ │ │ 3文件, 2305行 │ │ +│ │ ├─ 超时/中断 │ │ └─ compfix │ │ ├─ FindGitBash │ │ +│ │ ├─ 沙盒集成 │ └────────────────┘ │ ├─ Windows路径 │ │ +│ │ └─ 命令前缀 │ │ └─ ExecutionPolicy│ │ +│ └─────────────────┘ └───────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ subprocessEnv.ts → 子进程环境变量构建 │ │ +│ │ ShellCommand.ts (465行) → 命令封装 + 流式输出 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: bash/ 12310行 + powershell/ 2305行 混在 utils/ 中 │ +│ 改动范围: 提取为独立 package, BashTool 通过依赖注入使用 │ +│ 依赖方向: packages/shell ← packages/agent-tools (BashTool) │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.9 配置管理系统 (P2, 基础设施层) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ packages/config (~9700行) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ SettingsManager │ │ +│ │ ├─ 7 层优先级合并 (低→高, 后者覆盖前者): │ │ +│ │ │ 1. userSettings ~/.claude/settings.json │ │ +│ │ │ 2. projectSettings .claude/settings.json │ │ +│ │ │ 3. localSettings .claude/local/settings.json │ │ +│ │ │ 4. policySettings 企业管理 (远程下发) │ │ +│ │ │ 5. flagSettings GrowthBook feature flags │ │ +│ │ │ 6. cliArg --allowed-tools 等 CLI 参数 │ │ +│ │ │ 7. session 临时 ("始终允许" 按钮产生) │ │ +│ │ └─ get(key) / set(key, value, source) / watch(key, cb) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ +│ │ FeatureFlagProvider │ │ SettingsSync │ │ +│ │ ├─ BunBundle │ │ ├─ 跨设备同步 (已部分实现) │ │ +│ │ ├─ EnvVar │ │ ├─ 冲突检测/合并 │ │ +│ │ ├─ ConfigFile │ │ └─ RemoteManagedSettings │ │ +│ │ ├─ Remote (GrowthBook)│ │ (企业管控配置) │ │ +│ │ └─ feature(name)→bool│ └──────────────────────────────────┘ │ +│ └──────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ GlobalConfig (src/utils/config.ts, 1821行) │ │ +│ │ ├─ apiKey / oauthToken / customApiKeyResponses │ │ +│ │ ├─ preferredNotifChannel / projects (per-project) │ │ +│ │ ├─ saveGlobalConfig / getGlobalConfig (文件锁+新鲜度监控) │ │ +│ │ └─ trust dialog / config backup / default factory │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: settings/(3文件 1411行) + config.ts(1821行) 混在utils │ +│ 改动范围: 提取为独立 package, 作为最底层基础设施 │ +│ 依赖方向: 被 packages/agent, packages/permission 等所有模块依赖 │ +│ 注意: feature() 使用181处, 分布在30+文件, 提取需谨慎 │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.10 遥测/诊断系统 (P3, 真实实现, 非空 stub) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ services/analytics/ (10文件, 4062行, 真实实现) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 重要: 这不是空 stub, 而是完整的生产级实现 │ │ +│ │ 包含 OTel 日志导出、GrowthBook AB测试、Datadog 日志上传 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ FirstPartyEventLoggingExporter (806行) │ │ +│ │ ├─ OpenTelemetry LogExporter + JSONL 批处理 + HTTP 上传 │ │ +│ └─ FirstPartyEventLogger (449行) │ │ +│ └─ OTel LoggerProvider + 采样策略 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ GrowthBook 客户端 (1163行) │ │ +│ │ ├─ Feature flags / AB 测试 / 远程配置 │ │ +│ └─ sinkKillswitch (25行) — per-sink 开关 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Datadog 日志 (321行) + Metadata (973行) │ │ +│ │ ├─ Datadog 日志上传 (需环境变量配置端点/密钥) │ │ +│ └─ 事件元数据enrichment │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: 真实实现散布在 services/analytics/, 耦合 GrowthBook │ +│ 建议: 暂不提取为独立 package, 保持原地, 避免引入回归风险 │ +│ 依赖方向: 被多个模块调用, 但不影响核心业务逻辑 │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.11 Compaction 服务 (P2, 从 query.ts 独立) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ CompactionService (packages/agent 内) │ +│ src/services/compact/ (29文件, 4267行) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ CompactionStrategy (策略模式) │ │ +│ │ │ │ +│ │ ├─ SnipCompaction 精确裁剪 (保留首尾, 裁剪中间) │ │ +│ │ ├─ MicroCompaction 摘要压缩 (每 N 轮自动摘要) │ │ +│ │ └─ AutoCompaction 智能压缩 (按 token budget 触发) │ │ +│ └──────────────────────────┬──────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────────▼──────────────────────────────────┐ │ +│ │ ContextWindowManager │ │ +│ │ ├─ token 计数 / budget 分配 │ │ +│ │ ├─ 触发阈值检测 (80%/90%/95%) │ │ +│ │ └─ prompt 构造 (摘要请求 → 模型 → 替换历史) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: 逻辑分散在 query.ts + services/compact/ 两处 │ +│ 改动范围: 统一到 packages/agent/compaction/ │ +│ 依赖方向: ← QueryEngine 调用; → packages/provider (摘要请求) │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.12 Swarm / 多Agent 协调 (P3, 扩展系统) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ packages/swarm (~7548行 + tasks/) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ SwarmOrchestrator │ │ +│ │ ├─ spawnTeammate(config) → TeammateHandle │ │ +│ │ ├─ broadcast(message) → void │ │ +│ │ ├─ getTeamStatus() → TeamStatus[] │ │ +│ │ └─ shutdown() → void │ │ +│ └──────────────────────────┬──────────────────────────────────┘ │ +│ │ │ +│ ┌────────────────────┼──────────────────────┐ │ +│ │ │ │ │ +│ ┌──────▼──────────┐ ┌─────▼───────────┐ ┌──────▼──────────┐ │ +│ │ InProcessBackend│ │ TmuxBackend │ │ ITerm2Backend │ │ +│ │ (同进程, 线程) │ │ (Tmux pane) │ │ (iTerm2 split) │ │ +│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ +│ │ +│ ┌──────────────────────┐ ┌──────────────────────────────────┐ │ +│ │ TeammateMailbox │ │ PermissionSync │ │ +│ │ ├─ send(to, msg) │ │ ├─ 主Agent → 子Agent 权限传递 │ │ +│ │ ├─ receive() │ │ ├─ 规则同步 / 模式继承 │ │ +│ │ └─ broadcast(msg) │ │ └─ 子Agent 结果审批 │ │ +│ └──────────────────────┘ └──────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Task 类型系统 (src/tasks/, 13入口, 含巨文件) │ │ +│ │ ├─ LocalMainSessionTask 15373行 (全库最大!) │ │ +│ │ ├─ DreamTask 后台记忆合并 │ │ +│ │ ├─ InProcessTeammateTask 进程内队友 │ │ +│ │ ├─ LocalAgentTask 本地子Agent │ │ +│ │ ├─ RemoteAgentTask 远程子Agent │ │ +│ │ └─ MonitorMcpTask MCP 监控 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Worktree 管理 (src/utils/worktree.ts, 1519行) │ │ +│ │ ├─ createWorktree() → 隔离的 git worktree │ │ +│ │ ├─ cleanupWorktree() → 合并/丢弃 │ │ +│ │ └─ getWorktreePaths() → 路径映射 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: src/utils/swarm/(22文件, 7548行) + tasks/ 分散 │ +│ swarm 含 13文件(4486行) + backends/(9文件 3062行) │ +│ 改动范围: 统一到 packages/swarm/ │ +│ 依赖方向: ← packages/agent (AgentTool); → packages/shell │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.13 IDE / 编辑器集成 (P3, 扩展系统) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ packages/ide (~6800行) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ IDEConnector 接口 │ │ +│ │ ├─ connect(ideType) → IDEConnection │ │ +│ │ ├─ highlightFile(path, range) │ │ +│ │ ├─ openFile(path, line?) │ │ +│ │ └─ getSelection() → Range | null │ │ +│ └──────────────────────────┬──────────────────────────────────┘ │ +│ │ │ +│ ┌────────────────────┼──────────────────────┐ │ +│ │ │ │ │ +│ ┌──────▼──────────┐ ┌─────▼───────────┐ ┌──────▼──────────┐ │ +│ │ VSCodeProvider │ │ JetBrainsProvider│ │ LSPClient │ │ +│ │ (ide.ts 1494行) │ │ (jetbrains.ts │ │ (services/lsp/ │ │ +│ │ LSP 协议连接 │ │ 191行) │ │ 8文件) │ │ +│ │ 选区/高亮同步 │ │ IDE 集成 │ │ 代码操作/诊断 │ │ +│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ CodeIndexing (native-ts/file-index/) │ │ +│ │ ├─ 文件内容索引 → 快速代码搜索 │ │ +│ │ └─ 增量更新 / 持久化 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Claude-in-Chrome (utils/claudeInChrome/, 7文件, 2337行) │ │ +│ │ ├─ Chrome Native Messaging → 浏览器控制 │ │ +│ │ ├─ 设置管理 / Prompt 注入 │ │ +│ │ └─ 独立于 Computer Use, 通过 --chrome 启用 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: ide.ts + jetbrains.ts + lsp/ + claudeInChrome/ 分散 │ +│ 改动范围: 合并到 packages/ide/ │ +│ 依赖方向: ← packages/agent (LSPTool); 独立于核心循环 │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.14 Server 模式 (P3, 大部分 stub) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ packages/server (11文件, 大部分 stub) │ +│ src/server/ (392行, 其中仅371行有效代码) │ +│ │ +│ 实际实现 (4文件, 371行): │ +│ ├─ directConnectManager.ts (213行) — Direct Connect 管理 │ +│ ├─ createDirectConnectSession.ts (88行) — 会话创建 │ +│ ├─ types.ts (57行) — 类型定义 │ +│ └─ lockfile.ts (13行) — PID 锁 │ +│ │ +│ Stub 文件 (6个, 各3行): │ +│ ├─ server.ts / sessionManager.ts / connectHeadless.ts │ +│ ├─ serverBanner.ts / serverLog.ts / parseConnectUrl.ts │ +│ └─ backends/dangerousBackend.ts │ +│ │ +│ 当前问题: 6/11文件为空 stub, 仅 DirectConnect 有实际代码 │ +│ 建议: 低优先级, 待 stub 被恢复后再考虑提取 │ +│ 依赖方向: ← main.tsx (启动, DIRECT_CONNECT feature); 独立于核心 │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.15 远程执行 / Teleport (P3, 扩展系统) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ packages/teleport (~2200行) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ TeleportProvider │ │ +│ │ ├─ selectEnvironment(config) → Environment │ │ +│ │ ├─ packGitContext() → Archive (Git 打包上传) │ │ +│ │ ├─ execute(command, env) → Result (远程执行) │ │ +│ │ └─ syncResults(remote, local) (结果同步) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: teleport.tsx(1234行) + teleport/(4文件, 956行) │ +│ = 总计约2190行, 散布在 utils/ 中 │ +│ 改动范围: 提取为独立 package │ +│ 依赖方向: ← packages/agent; → packages/shell (远程执行) │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.16 自动更新 / 安装器 (P3, 入口层辅助) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ packages/updater (~3579行) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ NativeInstaller │ │ +│ │ ├─ Linux: .deb / .rpm 包管理 │ │ +│ │ ├─ macOS: .pkg 安装器 │ │ +│ │ └─ Windows: (预留) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ AutoUpdater (autoUpdater.ts, 561行) │ │ +│ │ ├─ 版本检查 (远程 / npm registry) │ │ +│ │ ├─ 二进制下载 + 校验 │ │ +│ │ └─ PID 锁 (防止并发更新) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: nativeInstaller/(5文件 3018行) + autoUpdater.ts(561行)│ +│ = 总计约3579行, 散布在 utils/ 中 │ +│ 改动范围: 提取为独立 package, 仅被 entry layer 调用 │ +│ 依赖方向: ← cli.tsx / main.tsx (启动时检查); 无业务依赖 │ +└───────────────────────────────────────────────────────────────────┘ +``` + +### 4.17 CLI 传输层 (P3, 入口层基础设施) + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ packages/cli (~12700行) │ +│ src/cli/ (127文件) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Transport 层 (可插拔 I/O 传输) │ │ +│ │ │ │ +│ │ ├─ HybridTransport 混合模式 (本地 + 远程) │ │ +│ │ ├─ SSETransport Server-Sent Events │ │ +│ │ ├─ WebSocketTransport WebSocket 双向通信 │ │ +│ │ ├─ WorkerStateTransport Worker 线程通信 │ │ +│ │ └─ SerialBatchTransport 串行批处理 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Handler 模块 (8个, 按 subcommand 分发) │ │ +│ │ ├─ agents / auth / mcp / autoMode / ... │ │ +│ │ ├─ StructuredIO (结构化输入输出) │ │ +│ │ └─ Rollback 机制 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 当前问题: 127文件独立目录但未抽为 package │ +│ 改动范围: 提取为 packages/cli/, 仅被 entry layer 引用 │ +│ 依赖方向: ← cli.tsx / main.tsx; → packages/agent │ +└───────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 五、Packages 目录结构 + +``` +packages/ +├── @ant/ (已有) +│ ├── computer-use-mcp/ +│ ├── computer-use-input/ +│ ├── computer-use-swift/ +│ └── claude-for-chrome-mcp/ +├── audio-capture-napi/ (已有) +├── color-diff-napi/ (已有) +├── image-processor-napi/ (已有) +│ +├── ink/ ← Phase 1 UI 框架 + Keybinding + Vim + Typeahead +├── agent-tools/ ← Phase 2 Agent 工具库 + Sandbox 系统 +├── memory/ ← Phase 2 记忆系统, 独立实现 +├── permission/ ← Phase 2 权限系统, 独立实现 +├── config/ ← Phase 2 配置管理 + FeatureFlag + GlobalConfig +├── telemetry/ ← Phase 2 遥测/诊断 (真实实现, 非空stub) +├── agent/ ← Phase 3 核心引擎 + Hook 生命周期 + Compaction + Cron +├── provider/ ← Phase 4 ProviderAdapter + AuthProvider + NetworkLayer +├── shell/ ← Phase 4 Shell 执行层 (Bash/Zsh/PowerShell) +├── swarm/ ← Phase 5 多Agent协调 + Worktree +├── ide/ ← Phase 5 IDE/LSP/CodeIndex + Claude-in-Chrome +├── server/ ← Phase 5 服务器模式 (大部分stub, 低优先级) +├── teleport/ ← Phase 5 远程执行环境 +├── updater/ ← Phase 5 自动更新 + 原生安装器 +└── cli/ ← Phase 5 CLI 传输层 + Handler 分发 +``` + +--- + +## 六、实施路线图 + +``` +Phase 0: 内部分解 (与 Phase 1-3 并行, 低风险) + ├── main.tsx → 6 个模块 + ├── REPL.tsx → 5 个 Hook + ├── query.ts → 4 个子模块 + ├── services/mcp/client.ts → 3 个模块 + ├── LocalMainSessionTask.ts → 分解 (15373行, 全库最大) + └── AppState → Domain Slicing + +Phase 1: packages/ink/ 风险: 低 + ├── Ink 框架 (reconciler/hooks/components) + ├── Keybinding 系统 (16文件 → 纳入 ink/) + ├── Vim 模拟 (5文件 → 纳入 ink/) + └── Typeahead/Suggestion (→ 纳入 ink/) + +Phase 2: 独立系统提取 风险: 低-中 + ├── packages/agent-tools/ Agent 工具库 + Sandbox + ├── packages/memory/ 记忆系统 + ├── packages/permission/ 权限系统 + ├── packages/config/ 配置管理 + FeatureFlag + GlobalConfig + └── packages/telemetry/ 遥测/诊断 (真实实现, 谨慎提取) + +Phase 3: packages/agent/ 风险: 中-高 + ├── query() + QueryEngine 核心循环 + ├── Hook 生命周期 (hooks.ts 5177行 + hooks/ 5文件 → 提取, 27种事件) + ├── Compaction 服务 (services/compact/ 29文件 → 统一) + ├── Cron/Scheduler (utils/cron* → 提取) + └── FileHistory (utils/fileHistory → 提取) + +Phase 4: packages/provider/ + packages/shell/ 风险: 中 + ├── LLM Provider 适配器 (核心价值最高) + ├── Auth Provider 适配器 + ├── Context Pipeline + ├── NetworkLayer (proxy/mTLS/CA证书) + └── Shell 执行层 (bash/powershell → 提取) + +Phase 5: 扩展系统 风险: 中-高 + ├── Tool Registry / Plugin + ├── Storage Backend / Command System + ├── Output Target / Feature Flag Provider + ├── packages/swarm/ 多Agent协调 + Worktree + ├── packages/ide/ IDE/LSP + CodeIndex + Chrome + ├── packages/server/ 服务器 (大部分stub, 可延后) + ├── packages/teleport/ 远程执行 + ├── packages/updater/ 自动更新 + 安装器 + └── packages/cli/ CLI 传输层 +``` + +--- + +## 七、优先级矩阵 + +| 项目 | 用户价值 | 风险 | 优先级 | +|------|---------|------|--------| +| **LLM Provider 适配器** | 高 (多模型, 已有OpenAI参考实现) | 中 | **P1** | +| **Auth Provider 适配器** | 高 (安全, 7种认证约3857行) | 高 | **P1** | +| **Tool Registry** | 高 (生态, 54个工具) | 低 | **P1** | +| **Hook 生命周期** | 高 (核心扩展点, 27种事件) | 中 | **P1** | +| **LocalMainSessionTask分解** | 高 (15373行巨文件) | 中 | **P1** | +| **Shell 执行层** | 高 (BashTool底层, bash/12310行) | 中 | **P2** | +| **配置管理** | 高 (基础设施, config.ts 1821行) | 低-中 | **P2** | +| **记忆系统** | 高 (跨会话记忆, 24文件 6330行) | 低-中 | **P2** | +| **权限系统** | 高 (安全/可扩展, 24文件 9416行) | 中 | **P2** | +| **Compaction 服务** | 中 (上下文管理, 29文件 4267行) | 低 | **P2** | +| **命令系统** | 中 (可扩展命令, 93目录 96命令) | 低 | P2 | +| Context Pipeline | 中 (自定义prompt) | 低 | P2 | +| Storage Backend | 中 (云同步/测试, 5文件约6968行) | 低-中 | P2 | +| **遥测/诊断** | 中 (可观测性, 真实实现非stub) | 中 | P2 | +| main.tsx 分解 | 中 (可维护性, 4680行) | 低 | P2 | +| REPL.tsx 分解 | 中 (可维护性, 5005行) | 中 | P2 | +| query.ts 分解 | 中 (可维护性, 1732行) | 低 | P3 | +| AppState Slicing | 低 (199行类型) | 低 | P3 | +| mcp/client.ts 分解 | 低 (3351行, services/mcp/) | 低 | P3 | +| Output Target | 中 (596个组件, 范围大) | 中-高 | P3 | +| Feature Flag Provider | 低 (181处使用, 30+文件) | 中 | P3 | +| **Swarm/多Agent** | 高 (并行能力, 22文件 7548行) | 高 | **P3** | +| **IDE/LSP 集成** | 中 (编辑器体验) | 中 | P3 | +| **Server 模式** | 低 (6/11文件为stub, 仅371行有效) | 低 | P4 | +| **Teleport 远程执行** | 中 (远程开发, 约2190行) | 中 | P3 | +| **自动更新/安装器** | 低 (运维, 约3579行) | 低 | P3 | +| **CLI 传输层** | 低 (内部架构, 127文件) | 低 | P3 | + +--- + +## 八、命令系统 + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ 用户输入 "/" 触发 │ +│ │ +│ REPL.tsx (用户按 Enter) │ +│ │ │ +│ ▼ │ +│ handlePromptSubmit.ts (610行) │ +│ │ │ +│ ▼ │ +│ processUserInput.ts (605行) ─── 识别 "/" 前缀 │ +│ │ │ +│ ▼ │ +│ processSlashCommand.tsx (921行) ─── 命令分发器 │ +│ │ │ +│ │ 解析命令名 + 参数 │ +│ │ findCommand() → 查找 Command 对象 │ +│ │ │ +│ ├──────────────┬──────────────────┬─────────────────┐ │ +│ ▼ ▼ ▼ ▼ │ +│ ┌─────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────┐ │ +│ │ local │ │ local-jsx │ │ prompt │ │ 未知命令 │ │ +│ │ │ │ │ │ │ │ → 错误 │ │ +│ │ load() │ │ load() │ │ getPrompt() │ └──────────┘ │ +│ │ →call() │ │ →call() │ │ → 注入消息 │ │ +│ │ →结果 │ │ → ReactNode│ │ → 发送查询 │ │ +│ └─────────┘ └─────────────┘ └──────────────┘ │ +│ │ │ │ │ +│ └──────────────┴──────────────────┘ │ +│ │ │ +│ ▼ │ +│ 返回结果给 REPL │ +└───────────────────────────────────────────────────────────────────┘ + +┌───────────────────────────────────────────────────────────────────┐ +│ 命令注册 (src/commands.ts, ~470行) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ COMMANDS() ─── 静态注册 ~96 个命令 │ │ +│ │ (71个静态导入 + 条件feature控制 + ~25个INTERNAL_ONLY) │ │ +│ │ │ │ +│ │ ┌─ src/commands/ (93个目录, 228文件) ─── 每个命令: │ │ +│ │ │ name, description, aliases, type │ │ +│ │ │ load: () => import('./impl.js') ← 懒加载 │ │ +│ │ │ isEnabled(), availability │ │ +│ │ └───────────────────────────────────────────────────────── │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ + │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ getCommands() ─── 动态源 (合并到最终列表) │ │ +│ │ │ │ +│ │ ├─ getSkillDirCommands() .claude/commands/ + skills/ │ │ +│ │ ├─ getBundledSkills() 内置 skill │ │ +│ │ ├─ getPluginSkills() 插件 skill │ │ +│ │ ├─ getPluginCommands() 插件命令 │ │ +│ │ ├─ getWorkflowCommands() workflow 脚本命令 │ │ +│ │ └─ getDynamicSkills() 运行时动态发现 │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ 过滤: isEnabled → meetsAvailability → 去重 │ +│ │ │ +│ ▼ │ +│ findCommand() / getCommand() / hasCommand() │ +│ (按 name, alias 查找, Fuse.js 模糊匹配) │ +└───────────────────────────────────────────────────────────────────┘ + +┌───────────────────────────────────────────────────────────────────┐ +│ 自动补全 (useTypeahead, 1384行) │ +│ │ +│ 用户键入 "/" │ +│ │ │ +│ ▼ │ +│ generateCommandSuggestions() (567行) │ +│ │ │ +│ ▼ │ +│ Fuse.js 模糊搜索 ─── 精确 > alias > 前缀 > 模糊 │ +│ │ │ +│ ▼ │ +│ Ghost Text 补全 / 列表选择 / Tab/Enter 确认 │ +└───────────────────────────────────────────────────────────────────┘ + +耦合特征: + ● commands.ts (~470行) 静态导入所有命令, 新增命令必须手动注册 + ● src/commands/ 93个目录 228文件, 每个命令独立目录 + ● processSlashCommand.tsx switch 分发, 新命令类型需改分发器 + ● SkillTool (1109行) 提供第二条路径: 模型直接调用 skill + ● REMOTE_SAFE_COMMANDS / BRIDGE_SAFE_COMMANDS 硬编码安全列表 +``` + +--- + +## 九、记忆系统 + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ 记忆系统总览 │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ CLAUDE.md 指令文件 (用户管理) claudemd.ts (1479行) │ │ +│ │ │ │ +│ │ 加载优先级 (低→高, 后者覆盖前者): │ │ +│ │ 1. Managed /etc/claude-code/CLAUDE.md │ │ +│ │ 2. User ~/.claude/CLAUDE.md │ │ +│ │ 3. Project CLAUDE.md, .claude/CLAUDE.md, .claude/rules/ │ │ +│ │ 4. Local CLAUDE.local.md (gitignored) │ │ +│ │ 5. AutoMem MEMORY.md (agent 管理) │ │ +│ │ 6. TeamMem MEMORY.md (团队共享) │ │ +│ │ │ │ +│ │ 特性: │ │ +│ │ ├─ @include 指令 (递归解析, 最深 5 层) │ │ +│ │ ├─ frontmatter paths: 条件规则 │ │ +│ │ ├─ HTML 注释剥离, 循环引用防护 │ │ +│ │ └─ MEMORY.md 截断: 200行 / 25KB │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ Auto-Memory (Agent 管理) memdir/ (9文件, 1743行)│ │ +│ │ │ │ +│ │ 存储位置: ~/.claude/projects//memory/ │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────┐ │ │ +│ │ │ 四类型分类法 │ │ │ +│ │ │ │ │ │ +│ │ │ user 用户角色/偏好/知识 (私有) │ │ │ +│ │ │ feedback 方法指导/纠正/确认 (默认私有) │ │ │ +│ │ │ project 项目工作/目标/决策 (团队共享) │ │ │ +│ │ │ reference 外部系统指针 (团队共享) │ │ │ +│ │ └─────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ +│ │ │ MemoryStore │ │ MemoryRecall │ │ MemoryExtract │ │ │ +│ │ │ 存储抽象 │ │ 相关性检索 │ │ 后台提取 │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ 写入 .md │ │ Sonnet 侧查 │ │ 每轮对话后触发 │ │ │ +│ │ │ + frontmatter│ │ → 选 5 条最 │ │ → fork subagent │ │ │ +│ │ │ + MEMORY.md │ │ 相关记忆 │ │ → 只读工具+写记忆│ │ │ +│ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────┐ │ │ +│ │ │ MemoryConsolidate│ autoDream.ts (326行) │ │ +│ │ │ 合并/清理/修剪 │ 后台运行, 防并发锁 │ │ +│ │ └──────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ extractMemories/ (2文件, 769行) │ │ │ +│ │ │ 后台异步提取, fork subagent, 只读工具+写记忆 │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────────┐ │ │ +│ │ │ teamMemorySync/ (4文件, 2167行) │ │ │ +│ │ │ 团队记忆同步, 跨会话/跨Agent共享 │ │ │ +│ │ └──────────────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ 集成点 │ │ +│ │ │ │ +│ │ context.ts ─── getMemoryFiles() + getClaudeMds() │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ 每轮对话注入指令上下文 │ │ +│ │ │ │ +│ │ stopHooks.ts ─── handleStopHooks() │ │ +│ │ │ │ │ +│ │ ├─→ executeExtractMemories() (异步提取) │ │ +│ │ └─→ executeAutoDream() (异步合并) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ 特性门控: │ +│ CLAUDE_CODE_DISABLE_AUTO_MEMORY, autoMemoryEnabled, │ +│ tengu_passport_quail (提取), tengu_moth_copse (附件模式), │ +│ tengu_herring_clock (团队记忆), EXTRACT_MEMORIES, TEAMMEM │ +│ │ +│ 总规模: 24文件, 约6330行 │ +│ ├─ memdir/ (9文件, 1743行) 存储抽象 │ +│ ├─ services/autoDream/ (4文件, 552行) 合并/清理 │ +│ ├─ services/extractMemories/ (2文件, 769行) 后台提取 │ +│ ├─ services/teamMemorySync/ (4文件, 2167行) 团队同步 │ +│ ├─ tasks/DreamTask/ (1文件, 157行) 后台任务 │ +│ └─ utils/辅助文件 (4文件, ~542行) 检测/操作 │ +└───────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 十、权限系统 + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ 权限模式 (PermissionMode) │ +│ PermissionMode.ts (141行) │ +│ │ +│ ┌──────────────┐ Shift+Tab 循环 │ +│ │ default │ ←→ acceptEdits ←→ plan ←→ bypassPermissions │ +│ │ (每步确认) │ ↑ (YOLO模式) │ +│ └──────────────┘ │ │ +│ auto (仅内部) │ +│ bubble (子agent) │ +│ dontAsk (静默拒绝) │ +└───────────────────────────────────────────────────────────────────┘ + +┌───────────────────────────────────────────────────────────────────┐ +│ 权限检查管线 (核心, 1486行) │ +│ permissions.ts: hasPermissionsToUseToolInner() │ +│ │ +│ Tool 调用请求 │ +│ │ │ +│ ┌────▼────────────────────────────────────────────────────┐ │ +│ │ Step 1: 强制检查 (不可被模式跳过) │ │ +│ │ │ │ +│ │ 1a. deny 规则匹配 → 立即拒绝 │ │ +│ │ 1b. ask 规则匹配 → 需要确认 │ │ +│ │ 1c. tool.checkPermissions() → 工具自检 │ │ +│ │ ├─ 文件工具 → filesystem.ts (1778行) │ │ +│ │ │ 读: UNC/Windows/拒绝/工作目录/内部路径 │ │ +│ │ │ 写: .git/.claude/.bashrc 安全检查 │ │ +│ │ └─ Bash → bashPermissions.ts (2621行) │ │ +│ │ 子命令级别权限校验 │ │ +│ │ 1d. 工具级拒绝 │ │ +│ │ 1e. requiresUserInteraction() → 强制交互 │ │ +│ │ 1f. 内容级 ask 规则 (bypass-immune) │ │ +│ │ 1g. 安全路径检查 (.git/ .claude/ .bashrc) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌────▼────────────────────────────────────────────────────┐ │ +│ │ Step 2: 模式决策 │ │ +│ │ │ │ +│ │ 2a. bypassPermissions → 放行 (除非被 Step 1 拦截) │ │ +│ │ 2b. alwaysAllow 规则匹配 → 放行 │ │ +│ │ 2c. 无匹配 → 转为 ask │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌────▼────────────────────────────────────────────────────┐ │ +│ │ Step 3: 模式后处理 │ │ +│ │ │ │ +│ │ dontAsk → ask 变 deny (静默拒绝) │ │ +│ │ auto → YOLO Classifier (1495行) │ │ +│ │ ├─ Stage 1: 快速分类 (无 thinking) │ │ +│ │ └─ Stage 2: 深度分析 (chain-of-thought) │ │ +│ │ headless → 先跑 PermissionRequest hooks, 再 auto-deny│ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ 结果: allow / deny / ask │ +└───────────────────────────────────────────────────────────────────┘ + +┌───────────────────────────────────────────────────────────────────┐ +│ 规则来源 (优先级从低到高) │ +│ permissionSetup.ts (1533行) │ +│ │ +│ ┌────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ +│ │ userSettings │ │ projectSettings │ │ localSettings │ │ +│ │ ~/.claude/ │ │ .claude/ │ │ .claude/local │ │ +│ │ settings.json │ │ settings.json │ │ settings.json │ │ +│ └────────────────┘ └─────────────────┘ └──────────────────┘ │ +│ ┌────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ +│ │ policySettings │ │ flagSettings │ │ cliArg │ │ +│ │ (企业管理) │ │ (GrowthBook) │ │ --allowed-tools │ │ +│ └────────────────┘ └─────────────────┘ └──────────────────┘ │ +│ ┌────────────────┐ ┌─────────────────┐ │ +│ │ command │ │ session │ │ +│ │ /permissions │ │ (临时, "始终允许"│ │ +│ │ │ │ 按钮产生) │ │ +│ └────────────────┘ └─────────────────┘ │ +│ │ +│ 规则格式: "Bash(git push:*)", "Edit(.claude/**)" │ +│ 解析: permissionRuleParser.ts (198行) │ +│ 三种行为: allow / deny / ask │ +└───────────────────────────────────────────────────────────────────┘ + +┌───────────────────────────────────────────────────────────────────┐ +│ 交互式审批流 (竞速模式) │ +│ interactiveHandler.ts (536行) │ +│ │ +│ ask 结果到达 │ +│ │ │ +│ ▼ │ +│ 推送 ToolUseConfirm 到 React 确认队列 │ +│ │ │ +│ ├─────────────┬──────────────┬──────────────┐ │ +│ ▼ ▼ ▼ ▼ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Terminal │ │ Bridge │ │ Channel Relay│ │ Hooks │ │ +│ │ 本地 Y/N │ │ claude.ai│ │ Telegram/IM │ │ 外部程序审批 │ │ +│ └──────────┘ └──────────┘ └──────────────┘ └──────────────┘ │ +│ │ │ │ │ │ +│ └─────────────┴──────────────┴──────────────┘ │ +│ │ │ +│ createResolveOnce 原子竞争 │ +│ 第一个响应者胜出 │ +└───────────────────────────────────────────────────────────────────┘ + +┌───────────────────────────────────────────────────────────────────┐ +│ ToolPermissionContext (核心状态对象) │ +│ 存储于 AppState.toolPermissionContext │ +│ │ +│ ├─ mode: PermissionMode │ +│ ├─ additionalWorkingDirectories: Map │ +│ ├─ alwaysAllowRules: { [source]: string[] } │ +│ ├─ alwaysDenyRules: { [source]: string[] } │ +│ ├─ alwaysAskRules: { [source]: string[] } │ +│ ├─ isBypassPermissionsModeAvailable: boolean │ +│ ├─ isAutoModeAvailable?: boolean │ +│ ├─ strippedDangerousRules?: { [source]: string[] } │ +│ ├─ shouldAvoidPermissionPrompts?: boolean │ +│ └─ prePlanMode?: PermissionMode │ +└───────────────────────────────────────────────────────────────────┘ + +当前问题: + ● 权限逻辑集中在 src/utils/permissions/ (24文件, 9416行) + ● 核心文件: permissions.ts (1486行), permissionSetup.ts (1533行) + ● filesystem.ts (1778行) 文件工具权限, yoloClassifier.ts (1495行) AI分类 + ● bashPermissions 不在 bash/ 目录, bash分类逻辑在 permissions/bashClassifier.ts + ● 规则来源 7 种, 优先级隐含在加载顺序中 + ● UI 组件 src/components/permissions/ (79文件) 与逻辑混合 +``` diff --git a/build.ts b/build.ts index 80d9e9a62..203fc23d9 100644 --- a/build.ts +++ b/build.ts @@ -1,4 +1,4 @@ -import { readdir, readFile, writeFile } from "fs/promises"; +import { readdir, readFile, writeFile, cp } from "fs/promises"; import { join } from "path"; import { getMacroDefines } from "./scripts/defines.ts"; @@ -59,7 +59,12 @@ console.log( `Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for Node.js compat)`, ); -// Step 4: Bundle download-ripgrep script as standalone JS for postinstall +// Step 4: Copy native .node addon files (audio-capture) +const vendorDir = join(outdir, "vendor", "audio-capture"); +await cp("vendor/audio-capture", vendorDir, { recursive: true }); +console.log(`Copied vendor/audio-capture/ → ${vendorDir}/`); + +// Step 5: Bundle download-ripgrep script as standalone JS for postinstall const rgScript = await Bun.build({ entrypoints: ["scripts/download-ripgrep.ts"], outdir, diff --git a/package.json b/package.json index 20637d6fd..f6419934d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-best", - "version": "1.0.3", + "version": "1.1.0", "description": "Reverse-engineered Anthropic Claude Code CLI — interactive AI coding assistant in the terminal", "type": "module", "author": "claude-code-best ",