{"owner":"claude-code-best","repo":"claude-code","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"files":{"AGENTS.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) and other AI coding agents when working with code in this repository.\n\n## Project Overview\n\nThis is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. TypeScript strict mode is enforced — **`bunx tsc --noEmit` must pass with zero errors**.\n\n## Git Commit Message Convention\n\n使用 **Conventional Commits** 规范：\n\n```\n<type>: <描述>\n```\n\n常见 type：`feat`、`fix`、`docs`、`chore`、`refactor`\n\n示例：\n- `feat: 添加模型 1M 上下文切换`\n- `fix: 修复初次登陆的校验问题`\n- `chore: remove prefetchOfficialMcpUrls call on startup`\n\n## Commands\n\n```bash\n# Install dependencies\nbun install\n\n# Dev mode (runs cli.tsx with MACRO defines injected via -d flags)\nbun run dev\n\n# Dev mode with debugger (set BUN_INSPECT=9229 to pick port)\nbun run dev:inspect\n\n# Pipe mode\necho \"say hello\" | bun run src/entrypoints/cli.tsx -p\n\n# Build (code splitting, outputs dist/cli.js + chunk files)\nbun run build\n\n# Build with Vite (alternative build pipeline)\nbun run build:vite\n\n# Test\nbun test                                    # run all tests\nbun test src/utils/__tests__/hash.test.ts   # run single file\nbun test --coverage                         # with coverage report\n\n# Lint & Format (Biome)\nbun run lint              # check only\nbun run lint:fix          # auto-fix\nbun run format            # format all src/\n\n# Health check\nbun run health\n\n# Check unused exports\nbun run check:unused\n\n# Full check (typecheck + lint + test) — run after completing any task\nbun run test:all\nbun run typecheck\n\n# Remote Control Server\nbun run rcs\n\n# Docs dev server (Mintlify)\nbun run docs:dev\n```\n\n详细的测试规范、覆盖状态和改进计划见 `docs/testing-spec.md`。\n\n## Architecture\n\n### Runtime & Build\n\n- **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.\n- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。Build 默认启用 19 个 feature（见下方 Feature Flag 段）。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。\n- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用全部 feature。\n- **Module system**: ESM (`\"type\": \"module\"`), TSX with `react-jsx` transform.\n- **Monorepo**: Bun workspaces — 15 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。\n- **Lint/Format**: Biome (`biome.json`)。`bun run lint` / `bun run lint:fix` / `bun run format`。\n- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.1.888`。\n- **CI**: GitHub Actions — `ci.yml`（构建+测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。\n\n### Entry & Bootstrap\n\n1. **`src/entrypoints/cli.tsx`** — True entrypoint。`main()` 函数按优先级处理多条快速路径：\n   - `--version` / `-v` — 零模块加载\n   - `--dump-system-prompt` — feature-gated (DUMP_SYSTEM_PROMPT)\n   - `--claude-in-chrome-mcp` / `--chrome-native-host`\n   - `--computer-use-mcp` — 独立 MCP server 模式\n   - `--daemon-worker=<kind>` — feature-gated (DAEMON)\n   - `remote-control` / `rc` / `remote` / `sync` / `bridge` — feature-gated (BRIDGE_MODE)\n   - `daemon` [subcommand] — feature-gated (DAEMON)\n   - `ps` / `logs` / `attach` / `kill` / `--bg` — feature-gated (BG_SESSIONS)\n   - `new` / `list` / `reply` — Template job commands\n   - `environment-runner` / `self-hosted-runner` — BYOC runner\n   - `--tmux` + `--worktree` 组合\n   - 默认路径：加载 `main.tsx` 启动完整 CLI\n2. **`src/main.tsx`** (~6981 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。\n3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog)。\n\n### Core Loop\n\n- **`src/query.ts`** — The main API query function. Sends messages to Claude API, handles streaming responses, processes tool calls, and manages the conversation turn loop.\n- **`src/QueryEngine.ts`** — Higher-level orchestrator wrapping `query()`. Manages conversation state, compaction, file history snapshots, attribution, and turn-level bookkeeping. Used by the REPL screen.\n- **`src/screens/REPL.tsx`** — The interactive REPL screen (React/Ink component). Handles user input, message display, tool permission prompts, and keyboard shortcuts.\n\n### API Layer\n\n- **`src/services/api/claude.ts`** — Core API client. Builds request params (system prompt, messages, tools, betas), calls the Anthropic SDK streaming endpoint, and processes `BetaRawMessageStreamEvent` events.\n- **7 providers**: `firstParty` (Anthropic direct), `bedrock` (AWS), `vertex` (Google Cloud), `foundry`, `openai`, `gemini`, `grok` (xAI)。\n- Provider selection in `src/utils/model/providers.ts`。优先级：modelType 参数 > 环境变量 > 默认 firstParty。\n\n### Tool System\n\n- **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).\n- **`src/tools.ts`** — Tool registry. Assembles the tool list; tools are imported from `@claude-code-best/builtin-tools` package. Some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.\n- **`packages/builtin-tools/src/tools/`** — 59 个子目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：\n  - **文件操作**: FileEditTool, FileReadTool, FileWriteTool, GlobTool, GrepTool\n  - **Shell/执行**: BashTool, PowerShellTool, REPLTool\n  - **Agent 系统**: AgentTool, TaskCreateTool, TaskUpdateTool, TaskListTool, TaskGetTool\n  - **规划**: EnterPlanModeTool, ExitPlanModeV2Tool, VerifyPlanExecutionTool\n  - **Web/MCP**: WebFetchTool, WebSearchTool, MCPTool, McpAuthTool\n  - **调度**: CronCreateTool, CronDeleteTool, CronListTool\n  - **其他**: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等\n- **`src/tools/shared/`** / **`packages/builtin-tools/src/tools/shared/`** — Tool 共享工具函数。\n\n### UI Layer (Ink)\n\n- **`src/ink.ts`** — Ink render wrapper with ThemeProvider injection.\n- **`packages/@ant/ink/`** — Custom Ink framework（forked/internal），包含 components、core、hooks、keybindings、theme、utils。注意：不是 `src/ink/`。\n- **`src/components/`** — 149 个组件目录/文件，渲染于终端 Ink 环境中。关键组件：\n  - `App.tsx` — Root provider (AppState, Stats, FpsMetrics)\n  - `Messages.tsx` / `MessageRow.tsx` — Conversation message rendering\n  - `PromptInput/` — User input handling\n  - `permissions/` — Tool permission approval UI\n  - `design-system/` — 复用 UI 组件（Dialog, FuzzyPicker, ProgressBar, ThemeProvider 等）\n- Components use React Compiler runtime (`react/compiler-runtime`) — decompiled output has `_c()` memoization calls throughout.\n\n### State Management\n\n- **`src/state/AppState.tsx`** — Central app state type and context provider. Contains messages, tools, permissions, MCP connections, etc.\n- **`src/state/AppStateStore.ts`** — Default state and store factory.\n- **`src/state/store.ts`** — Zustand-style store for AppState (`createStore`).\n- **`src/state/selectors.ts`** — State selectors.\n- **`src/bootstrap/state.ts`** — Module-level singletons for session-global state (session ID, CWD, project root, token counts, model overrides, client type, permission mode).\n\n### Workspace Packages\n\n| Package | 说明 |\n|---------|------|\n| `packages/@ant/ink/` | Forked Ink 框架（components、hooks、keybindings、theme） |\n| `packages/@ant/computer-use-mcp/` | Computer Use MCP server（截图/键鼠/剪贴板/应用管理） |\n| `packages/@ant/computer-use-input/` | 键鼠模拟（dispatcher + darwin/win32/linux backend） |\n| `packages/@ant/computer-use-swift/` | 截图 + 应用管理（dispatcher + per-platform backend） |\n| `packages/@ant/claude-for-chrome-mcp/` | Chrome 浏览器控制（通过 `--chrome` 启用） |\n| `packages/@ant/model-provider/` | Model provider 抽象层 |\n| `packages/builtin-tools/` | 内置工具集（60 个 tool 实现，通过 `@claude-code-best/builtin-tools` 导出） |\n| `packages/agent-tools/` | Agent 工具集 |\n| `packages/acp-link/` | ACP 代理服务器（WebSocket → ACP agent 桥接） |\n| `packages/cc-knowledge/` | Claude Code 知识库（非 workspace 包） |\n| `packages/langfuse-dashboard/` | Langfuse 可观测性面板（非 workspace 包） |\n| `packages/mcp-client/` | MCP 客户端库 |\n| `packages/mcp-server/` | MCP 服务端库（非 workspace 包） |\n| `packages/remote-control-server/` | 自托管 Remote Control Server（Docker 部署，含 Web UI）— Web UI 已重构为 React + Vite + Radix UI，支持 ACP agent 接入 |\n| `packages/swarm/` | Swarm 解耦模块（非 workspace 包） |\n| `packages/shell/` | Shell 抽象（非 workspace 包） |\n| `packages/audio-capture-napi/` | 原生音频捕获（已恢复） |\n| `packages/color-diff-napi/` | 颜色差异计算（完整实现，11 tests） |\n| `packages/image-processor-napi/` | 图像处理（已恢复） |\n| `packages/modifiers-napi/` | 键盘修饰键检测（macOS FFI 实现） |\n| `packages/url-handler-napi/` | URL scheme 处理（环境变量 + CLI 参数读取） |\n\n### Bridge / Remote Control\n\n- **`src/bridge/`** — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。\n- **`packages/remote-control-server/`** — 自托管 RCS，支持 Docker 部署，含 Web UI 控制面板（React 19 + Vite + Radix UI）。支持 ACP agent 通过 acp-link 接入（ACP WebSocket handler、relay handler、SSE event stream）。通过 `bun run rcs` 启动。\n- CLI 快速路径: `claude remote-control` / `claude rc` / `claude bridge`。\n- 详见 `docs/features/remote-control-self-hosting.md`。\n\n### ACP Protocol (Agent Client Protocol)\n\n- **`src/services/acp/`** — ACP agent 实现，包含 `agent.ts`（AcpAgent 类）、`bridge.ts`（Claude Code ↔ ACP 桥接）、`permissions.ts`（权限处理）、`entry.ts`（入口）。\n- **`packages/acp-link/`** — ACP 代理服务器，将 WebSocket 客户端桥接到 ACP agent。提供 `acp-link` CLI 命令，支持自定义端口/HTTPS/认证/会话管理、RCS 集成（REST 注册 + WS identify 两步流程）、权限模式透传（fallback: 客户端传值 > config > `ACP_PERMISSION_MODE` 环境变量）。\n- ACP 权限管道改进：`createAcpCanUseTool` 统一权限流水线，`applySessionMode` 模式同步，`bypassPermissions` 可用性检测（非 root/sandbox 环境）。\n- ACP Plan 可视化已支持 `session/update plan` 类型的消息展示（PlanView 组件，含进度条/状态图标/优先级标签）。\n\n### Daemon Mode\n\n- **`src/daemon/`** — Daemon 模式（长驻 supervisor）。feature-gated by `DAEMON`。包含 `main.ts`（entry）和 `workerRegistry.ts`（worker 管理）。\n\n### Context & System Prompt\n\n- **`src/context.ts`** — Builds system/user context for the API call (git status, date, CLAUDE.md contents, memory files).\n- **`src/utils/claudemd.ts`** — Discovers and loads CLAUDE.md files from project hierarchy.\n\n### Feature Flag System\n\nFeature flags control which functionality is enabled at runtime. 代码中统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。\n\n**启用方式**: 环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev`。\n\n**Build 默认 features**（19 个，见 `build.ts`）:\n- 基础: `BUDDY`, `TRANSCRIPT_CLASSIFIER`, `BRIDGE_MODE`, `AGENT_TRIGGERS_REMOTE`, `CHICAGO_MCP`, `VOICE_MODE`\n- 统计/缓存: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`\n- P0 本地: `AGENT_TRIGGERS`, `ULTRATHINK`, `BUILTIN_EXPLORE_PLAN_AGENTS`, `LODESTONE`\n- P1 API 依赖: `EXTRACT_MEMORIES`, `VERIFICATION_AGENT`, `KAIROS_BRIEF`, `AWAY_SUMMARY`, `ULTRAPLAN`\n- P2: `DAEMON`\n\n**Dev mode 默认**: 全部启用（见 `scripts/dev.ts`）。\n\n**类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。\n\n**新增功能的正确做法**: 保留 `import { feature } from 'bun:bundle'` + `feature('FLAG_NAME')` 的标准模式，在运行时通过环境变量或配置控制，不要绕过 feature flag 直接 import。\n\n### Multi-API 兼容层\n\n所有兼容层均采用流适配器模式：将第三方 API 格式转为 Anthropic 内部格式，下游代码完全不改。通过 `/login` 命令配置。\n\n#### OpenAI 兼容层\n\n通过 `CLAUDE_CODE_USE_OPENAI=1` 启用，支持 Ollama/DeepSeek/vLLM 等任意 OpenAI Chat Completions 协议端点。含 DeepSeek thinking mode 支持。\n\n- **`src/services/api/openai/`** — client、消息/工具转换、流适配、模型映射\n- 关键环境变量：`CLAUDE_CODE_USE_OPENAI`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`\n\n#### Gemini 兼容层\n\n通过 `CLAUDE_CODE_USE_GEMINI=1` 启用。独立环境变量体系。\n\n- **`src/services/api/gemini/`** — client、模型映射、类型定义\n- 关键环境变量：`GEMINI_API_KEY`（必填）、`GEMINI_MODEL`（直接指定）、`GEMINI_DEFAULT_SONNET_MODEL`/`GEMINI_DEFAULT_OPUS_MODEL`（按能力映射）\n- 模型映射优先级：`GEMINI_MODEL` > `GEMINI_DEFAULT_*_MODEL` > `ANTHROPIC_DEFAULT_*_MODEL`(已废弃) > 原样返回\n\n#### Grok 兼容层\n\n通过 `CLAUDE_CODE_USE_GROK=1` 启用。自定义模型映射支持 xAI Grok API。\n\n- **`src/services/api/grok/`** — client、模型映射\n\n详见各兼容层的 docs 文档。\n\n### 穷鬼模式（Budget Mode）\n\n- 通过 `/poor` 命令切换，持久化到 `settings.json`。\n- 启用后跳过 `extract_memories`、`prompt_suggestion` 和 `verification_agent`，显著减少 token 消耗。\n- 实现在 `src/commands/poor/poorMode.ts`。\n\n### Stubbed/Deleted Modules\n\n| Module | Status |\n|--------|--------|\n| Computer Use (`@ant/*`) | Restored — macOS + Windows + Linux（后端完整度不一） |\n| `*-napi` packages | 全部已恢复/实现：`audio-capture-napi`、`image-processor-napi` 已恢复；`color-diff-napi` 完整；`modifiers-napi`（macOS FFI）；`url-handler-napi`（环境变量+CLI） |\n| Voice Mode | Restored — Push-to-Talk 语音输入（需 Anthropic OAuth） |\n| OpenAI/Gemini/Grok 兼容层 | Restored |\n| Remote Control Server | Restored — 自托管 RCS + Web UI |\n| Analytics / GrowthBook / Sentry | Empty implementations |\n| Magic Docs / LSP Server | Restored — Magic Docs 自动更新 + LSP 服务器管理器 |\n| Plugins / Marketplace | Restored — 插件安装/卸载/启用/禁用 + Marketplace 浏览 |\n| MCP OAuth | Simplified |\n\n### Key Type Files\n\n- **`src/types/global.d.ts`** — Declares `MACRO`, `BUILD_TARGET`, `BUILD_ENV` and internal Anthropic-only identifiers.\n- **`src/types/internal-modules.d.ts`** — Type declarations for `bun:bundle`, `bun:ffi`, `@anthropic-ai/mcpb`.\n- **`src/types/message.ts`** — Message type hierarchy (UserMessage, AssistantMessage, SystemMessage, etc.).\n- **`src/types/permissions.ts`** — Permission mode and result types.\n\n## Testing\n\n- **框架**: `bun:test`（内置断言 + mock）\n- **单元测试**: 就近放置于 `src/**/__tests__/`，文件名 `<module>.test.ts`\n- **集成测试**: `tests/integration/` — 4 个文件（cli-arguments, context-build, message-pipeline, tool-chain）\n- **共享 mock/fixture**: `tests/mocks/`（api-responses, file-system, fixtures/）\n- **命名**: `describe(\"functionName\")` + `test(\"behavior description\")`，英文\n- **包测试**: `packages/` 下各包也有独立测试（如 `color-diff-napi` 11 tests）\n\n### Mock 使用规范\n\n**只 mock 有副作用的依赖链，不 mock 纯函数/纯数据模块。**\n\n被迫 mock 的根源：`log.ts` / `debug.ts` → `bootstrap/state.ts`（模块级 `realpathSync` / `randomUUID` 副作用）。必须 mock 的模块：`log.ts`、`debug.ts`、`bun:bundle`、`settings/settings.js`、`config.ts`、`auth.ts`、第三方网络库。\n\n**`log.ts` 和 `debug.ts` 使用共享 mock**（`tests/mocks/log.ts` / `tests/mocks/debug.ts`），不要在测试文件中内联 mock 定义。使用方式：\n\n```ts\nimport { logMock } from \"../../../tests/mocks/log\";\nmock.module(\"src/utils/log.ts\", logMock);\n\nimport { debugMock } from \"../../../../tests/mocks/debug\";\nmock.module(\"src/utils/debug.ts\", debugMock);\n```\n\n源文件导出变更时只需更新 `tests/mocks/` 下的对应文件，不需要逐个修改测试。\n\n不要 mock：纯函数模块（`errors.ts`、`stringUtils.js`）、mock 值与真实实现相同的模块、mock 路径与实际 import 不匹配的模块。\n\n路径规则：统一用 `.ts` 扩展名 + `src/*` 别名路径，禁止双重 mock 同一模块。\n\n### 类型检查\n\n项目使用 TypeScript strict 模式，**tsc 必须零错误**。每次修改后运行：\n\n```bash\nbun run typecheck\n```\n\n**类型规范**：\n- 生产代码禁止 `as any`；测试文件中 mock 数据可用 `as any`\n- 类型不匹配优先用 `as unknown as SpecificType` 双重断言，或补充 interface\n- 未知结构对象用 `Record<string, unknown>` 替代 `any`\n- 联合类型用类型守卫（type guard）收窄，不要强转\n- `msg.request` 属性访问：`const req = msg.request as Record<string, unknown>`\n- Ink `color` prop：用 `as keyof Theme` 而非 `as any`\n\n## Working with This Codebase\n\n- **tsc must pass** — `bun run typecheck` 必须零错误，任何修改都不能引入新的类型错误。\n- **Feature flags** — 默认全部关闭（`feature()` 返回 `false`）。Dev/build 各有自己的默认启用列表。不要在 `cli.tsx` 中重定义 `feature` 函数。\n- **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)`). This is normal.\n- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`feature()` 只能直接用在 `if` 语句或三元表达式的条件位置**（Bun 编译器限制），不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。正确：`if (feature('X')) {}` 或 `feature('X') ? a : b`。\n- **`src/` path alias** — tsconfig maps `src/*` to `./src/*`. Imports like `import { ... } from 'src/utils/...'` are valid.\n- **MACRO defines** — 集中管理在 `scripts/defines.ts`。Dev mode 通过 `bun -d` 注入，build 通过 `Bun.build({ define })` 注入。修改版本号等常量只改这个文件。\n- **构建产物兼容 Node.js** — `build.ts` 会自动后处理 `import.meta.require`，产物可直接用 `node dist/cli.js` 运行。\n- **Biome 配置** — 大量 lint 规则被关闭（decompiled 代码不适合严格 lint）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。\n- **Ink 框架在 `packages/@ant/ink/`** — 不是 `src/ink/`（该目录不存在）。Ink 相关的组件、hooks、keybindings 都在 packages 中。\n- **Provider 优先级** — `modelType` 参数 > 环境变量 > 默认 `firstParty`。新增 provider 需在 `src/utils/model/providers.ts` 注册。\n\n## Design Context\n\nImpeccable 设计上下文保存在 `.impeccable.md` 中。设计 Web UI（RCS 控制面板、文档站、着陆页）时必须参考该文件。\n\n### 核心设计原则\n\n1. **Considered over clever** — 每个设计选择都应感觉有意为之，而非追逐潮流\n2. **Warmth through subtlety** — 通过橙色色调的中性色、留白布局、有温度的文案来传达温暖\n3. **Density with clarity** — 技术用户需要信息密度，但不能混乱\n4. **Community voice** — 设计应感觉是由使用者创造的，而非遥远的设计团队\n5. **Anthropic's shadow** — 遵循 Anthropic 的设计直觉：干净的布局、充足的间距、温暖的色温\n\n### 品牌色\n\n- 主色：Claude Orange `#D77757`（terra cotta）\n- 辅色：Claude Blue `#5769F7`\n- 暗色模式使用温暖的深色表面（非冷蓝黑色）\n\n### 目标用户\n\n技术团队/企业，在专业工作流中使用 AI 辅助编程。友好的开源社区氛围，非企业 SaaS 风格。\n\n### 视觉参考\n\nAnthropic 公司的设计风格 — 干净、考究、温暖的底色。大量留白，以排版为核心。避免 AI 产品常见的设计套路（渐变文字、玻璃态、霓虹色）。\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) and other AI coding agents when working with code in this repository.\n\n## Project Overview\n\nThis is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. TypeScript strict mode is enforced — **`bun run precheck` 必须零错误通过**（包含 typecheck + lint fix + test）。\n\n## Git Commit Message Convention\n\n使用 **Conventional Commits** 规范：\n\n```\n<type>: <描述>\n```\n\n常见 type：`feat`、`fix`、`docs`、`chore`、`refactor`\n\n示例：\n- `feat: 添加模型 1M 上下文切换`\n- `fix: 修复初次登陆的校验问题`\n- `chore: remove prefetchOfficialMcpUrls call on startup`\n\n## Commands\n\n```bash\n# Install dependencies\nbun install\n\n# Dev mode (runs cli.tsx with MACRO defines injected via -d flags)\nbun run dev\n\n# Dev mode with debugger (set BUN_INSPECT=9229 to pick port)\nbun run dev:inspect\n\n# Pipe mode\necho \"say hello\" | bun run src/entrypoints/cli.tsx -p\n\n# Build (code splitting, outputs dist/cli.js + chunk files)\nbun run build\n\n# Build with Vite (alternative build pipeline)\nbun run build:vite\n\n# Test\nbun test                                    # run all tests\nbun test src/utils/__tests__/hash.test.ts   # run single file\nbun test --coverage                         # with coverage report\n\n# Lint & Format (Biome) — 日常开发用 precheck 代替单独调用\nbun run lint              # lint check (全项目)\nbun run lint:fix          # auto-fix lint issues\nbun run format            # format all (全项目)\nbun run check             # lint + format check (全项目)\nbun run check:fix         # lint + format auto-fix\n\n# Health check\nbun run health\n\n# Check unused exports\nbun run check:unused\n\n# Full check (typecheck + lint fix + test) — 任务完成后必须运行\nbun run precheck\n\n# Remote Control Server\nbun run rcs\n\n# Docs dev server (Mintlify)\nbun run docs:dev\n```\n\n详细的测试规范、覆盖状态和改进计划见 `docs/testing-spec.md`。\n\n## Architecture\n\n### Runtime & Build\n\n- **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.\n- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。Build 默认启用 19 个 feature（见下方 Feature Flag 段）。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。构建时会将 `vendor/audio-capture/` 和 `src/utils/vendor/ripgrep/` 复制到 `dist/vendor/` 下。\n- **Build (Vite)**: `vite.config.ts` + `scripts/post-build.ts`，代码分割模式，chunk 输出到 `dist/chunks/`。post-build 遍历 `dist/` 和 `dist/chunks/` 下所有 `.js` 文件做 `globalThis.Bun` 解构 patch，复制 vendor 文件到 `dist/vendor/`。\n- **Vendor 路径解析**: 构建后 chunk 文件位于 `dist/` 或 `dist/chunks/` 下，vendor 二进制在 `dist/vendor/`。`src/utils/distRoot.ts` 提供共享的 `distRoot` 函数，通过 `import.meta.url` 路径中 `lastIndexOf('dist')` 或 `lastIndexOf('src')` 定位根目录。`ripgrep.ts`、`computerUse/setup.ts`、`claudeInChrome/setup.ts`、`updateCCB.ts` 均使用 `distRoot` 而非内联 `import.meta.url` 路径推算。`packages/audio-capture-napi/src/index.ts` 有独立的 `lastIndexOf('dist')` 逻辑，功能等价。\n- **为什么 Vite 必须代码分割**: Bun/JSC 会全量解析单个大 JS 文件的 bytecode 和 JIT，单文件 17MB 产物导致 RSS 暴涨至 ~1GB（Node/V8 懒解析仅需 ~220MB）。代码分割为 600+ 小 chunk 后 Bun 按需加载，`--version` RSS 从 966MB 降至 35MB，完整加载从 1GB+ 降至 ~500MB。\n- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用全部 feature。\n- **Module system**: ESM (`\"type\": \"module\"`), TSX with `react-jsx` transform.\n- **Monorepo**: Bun workspaces — 17 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。\n- **Lint/Format**: Biome (`biome.json`)。覆盖 `src/`、`scripts/`、`packages/` 全项目（含 `packages/@ant/`）。`bun run lint` / `bun run lint:fix` / `bun run format` / `bun run check` / `bun run check:fix`。42 条规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。\n- **Pre-commit**: husky + lint-staged。提交时自动对暂存文件执行 `biome check --fix`（TS/JS）和 `biome format --write`（JSON）。\n- **CI Lint**: `ci.yml` 在依赖安装后、类型检查前执行 `bunx biome ci .`，lint 或格式化不达标则 CI 失败。\n- **Defines**: 集中管理在 `scripts/defines.ts`。版本号从 `package.json` 读取（不再硬编码）。\n- **CI**: GitHub Actions — `ci.yml`（lint + 构建 + 测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。\n\n### Entry & Bootstrap\n\n1. **`src/entrypoints/cli.tsx`** — True entrypoint。`main()` 函数按优先级处理多条快速路径：\n   - `--version` / `-v` — 零模块加载\n   - `--dump-system-prompt` — feature-gated (DUMP_SYSTEM_PROMPT)\n   - `--claude-in-chrome-mcp` / `--chrome-native-host`\n   - `--computer-use-mcp` — 独立 MCP server 模式\n   - `--daemon-worker=<kind>` — feature-gated (DAEMON)\n   - `remote-control` / `rc` / `remote` / `sync` / `bridge` — feature-gated (BRIDGE_MODE)\n   - `daemon` [subcommand] — feature-gated (DAEMON)\n   - `ps` / `logs` / `attach` / `kill` / `--bg` — feature-gated (BG_SESSIONS)\n   - `new` / `list` / `reply` — Template job commands\n   - `environment-runner` / `self-hosted-runner` — BYOC runner\n   - `--tmux` + `--worktree` 组合\n   - 默认路径：加载 `main.tsx` 启动完整 CLI\n2. **`src/main.tsx`** (~5674 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。\n3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog)。\n\n### Core Loop\n\n- **`src/query.ts`** — The main API query function. Sends messages to Claude API, handles streaming responses, processes tool calls, and manages the conversation turn loop.\n- **`src/QueryEngine.ts`** — Higher-level orchestrator wrapping `query()`. Manages conversation state, compaction, file history snapshots, attribution, and turn-level bookkeeping. Used by the REPL screen.\n- **`src/screens/REPL.tsx`** — The interactive REPL screen (React/Ink component). Handles user input, message display, tool permission prompts, and keyboard shortcuts.\n\n### API Layer\n\n- **`src/services/api/claude.ts`** — Core API client. Builds request params (system prompt, messages, tools, betas), calls the Anthropic SDK streaming endpoint, and processes `BetaRawMessageStreamEvent` events.\n- **7 providers**: `firstParty` (Anthropic direct), `bedrock` (AWS), `vertex` (Google Cloud), `foundry`, `openai`, `gemini`, `grok` (xAI)。\n- Provider selection in `src/utils/model/providers.ts`。优先级：modelType 参数 > 环境变量 > 默认 firstParty。\n\n### Tool System\n\n- **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).\n- **`src/tools.ts`** — Tool registry. Assembles the tool list; tools are imported from `@claude-code-best/builtin-tools` package. Some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.\n- **`src/constants/tools.ts`** — `CORE_TOOLS` 白名单常量（38 个核心工具名），用于 `isDeferredTool` 白名单制判定。\n- **`packages/builtin-tools/src/tools/`** — 60 个工具目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：\n  - **文件操作**: FileEditTool, FileReadTool, FileWriteTool, GlobTool, GrepTool\n  - **Shell/执行**: BashTool, PowerShellTool, REPLTool\n  - **Agent 系统**: AgentTool, TaskCreateTool, TaskUpdateTool, TaskListTool, TaskGetTool\n  - **规划**: EnterPlanModeTool, ExitPlanModeV2Tool, VerifyPlanExecutionTool\n  - **Web/MCP**: WebFetchTool, WebSearchTool, MCPTool, McpAuthTool\n  - **调度**: CronCreateTool, CronDeleteTool, CronListTool\n  - **工具发现**: SearchExtraToolsTool, ExecuteExtraTool, SyntheticOutput（CORE_TOOLS，用于延迟工具按需加载）\n  - **其他**: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等\n- **`src/tools/shared/`** / **`packages/builtin-tools/src/tools/shared/`** — Tool 共享工具函数。\n- **`src/services/searchExtraTools/`** — TF-IDF 工具索引模块（`toolIndex.ts`），为延迟工具提供语义搜索能力。复用 `localSearch.ts` 的 TF-IDF 算法函数（`computeWeightedTf`、`computeIdf`、`cosineSimilarity` 已导出）。修改这些函数时需同步检查工具索引测试。`prefetch.ts` 的 `extractQueryFromMessages` 复用了 `skillSearch/prefetch.ts` 的同名导出函数，修改 skill prefetch 的该函数时需同步检查工具预取行为。工具预取使用独立的 `discoveredToolsThisSession` Set，与 skill prefetch 的去重集合互不影响。\n\n### UI Layer (Ink)\n\n- **`src/ink.ts`** — Ink render wrapper with ThemeProvider injection.\n- **`packages/@ant/ink/`** — Custom Ink framework（forked/internal），包含 components、core、hooks、keybindings、theme、utils。注意：不是 `src/ink/`。\n- **老控制台兼容模式** — `packages/@ant/ink/src/core/legacyConsole.ts`：检测 Windows build < 17763（无 ConPTY 的老系统，如 1709/LTSC 内网机器）时自动启用；`log-update.ts` 的渲染循环每约 1 秒（`LEGACY_CONSOLE_RESET_MS`）用一次全量重绘替换增量 diff，自愈老 conhost 的光标漂移花屏。`CLAUDE_CODE_LEGACY_CONSOLE=1`/`=0` 可强制开/关。其他环境完全不走此路径。\n- **`src/components/`** — 149 个组件目录/文件，渲染于终端 Ink 环境中。关键组件：\n  - `App.tsx` — Root provider (AppState, Stats, FpsMetrics)\n  - `Messages.tsx` / `MessageRow.tsx` — Conversation message rendering\n  - `PromptInput/` — User input handling\n  - `permissions/` — Tool permission approval UI\n  - `design-system/` — 复用 UI 组件（Dialog, FuzzyPicker, ProgressBar, ThemeProvider 等）\n- Components use React Compiler runtime (`react/compiler-runtime`) — decompiled output has `_c()` memoization calls throughout.\n\n### State Management\n\n- **`src/state/AppState.tsx`** — Central app state type and context provider. Contains messages, tools, permissions, MCP connections, etc.\n- **`src/state/AppStateStore.ts`** — Default state and store factory.\n- **`src/state/store.ts`** — Zustand-style store for AppState (`createStore`).\n- **`src/state/selectors.ts`** — State selectors.\n- **`src/bootstrap/state.ts`** — Module-level singletons for session-global state (session ID, CWD, project root, token counts, model overrides, client type, permission mode).\n\n### Workspace Packages\n\n| Package | 说明 |\n|---------|------|\n| `packages/@ant/ink/` | Forked Ink 框架（components、hooks、keybindings、theme） |\n| `packages/@ant/computer-use-mcp/` | Computer Use MCP server（截图/键鼠/剪贴板/应用管理） |\n| `packages/@ant/computer-use-input/` | 键鼠模拟（dispatcher + darwin/win32/linux backend） |\n| `packages/@ant/computer-use-swift/` | 截图 + 应用管理（dispatcher + per-platform backend） |\n| `packages/@ant/claude-for-chrome-mcp/` | Chrome 浏览器控制（通过 `--chrome` 启用） |\n| `packages/@ant/model-provider/` | Model provider 抽象层 |\n| `packages/builtin-tools/` | 内置工具集（60 个 tool 实现，通过 `@claude-code-best/builtin-tools` 导出） |\n| `packages/agent-tools/` | Agent 工具集 |\n| `packages/acp-link/` | ACP 代理服务器（WebSocket → ACP agent 桥接） |\n| `packages/mcp-client/` | MCP 客户端库 |\n| `packages/remote-control-server/` | 自托管 Remote Control Server（Docker 部署，含 Web UI）— Web UI 已重构为 React + Vite + Radix UI，支持 ACP agent 接入 |\n| `packages/cloud-artifacts/` | 独立 Cloudflare Worker + R2 服务：POST `/upload` HTML 上传返回 hash URL，GET `/<7d\\|30d>/<id>.html` 由 Worker 代理读取；R2 lifecycle rule 自动 7/30 天过期 |\n| `packages/audio-capture-napi/` | 原生音频捕获（已恢复） |\n| `packages/color-diff-napi/` | 颜色差异计算（完整实现，11 tests） |\n| `packages/image-processor-napi/` | 图像处理（已恢复） |\n| `packages/modifiers-napi/` | 键盘修饰键检测（macOS FFI 实现） |\n| `packages/url-handler-napi/` | URL scheme 处理（环境变量 + CLI 参数读取） |\n| `packages/weixin/` | 微信集成（非 workspace 包） |\n\n辅助目录（无 package.json，非 workspace 包）: `langfuse-dashboard`（Langfuse 面板）、`shared-web-ui`（共享 Web UI 组件）、`highlight-code`（代码高亮）、`claude-pencil`（编辑器）、`vscode-ide-bridge`（VS Code 桥接）、`pokemon`（示例/测试）。\n\n### Bridge / Remote Control\n\n- **`src/bridge/`** — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。\n- **`packages/remote-control-server/`** — 自托管 RCS，支持 Docker 部署，含 Web UI 控制面板（React 19 + Vite + Radix UI）。支持 ACP agent 通过 acp-link 接入（ACP WebSocket handler、relay handler、SSE event stream）。通过 `bun run rcs` 启动。\n- CLI 快速路径: `claude remote-control` / `claude rc` / `claude bridge`。\n- 详见 `docs/features/remote-control-self-hosting.md`。\n\n### HTML Artifact Hosting\n\n- **`packages/cloud-artifacts/`** — 独立 Cloudflare Worker + R2 服务，类似 `remote-control-server/` 的\"独立部署服务\"定位，**不被主 CLI import**。Worker 处理 `POST /upload`（Bearer token 鉴权 + text/html 校验 + 10MB 上限 + ttl∈{7,30}）和 `GET /<7d|30d>/<id>.html`（从 R2 读 + Cache-Control: max-age=86400）。R2 用 prefix + lifecycle rule 实现 TTL（`7d/` 删 7 天、`30d/` 删 30 天），Worker 不参与过期处理。ID 默认 `nanoid(21)`（126 bit 熵），可指定 `?hash=` 自定义 ID（覆盖语义：先删 7d/30d prefix 旧 key 再写新 key）。Worker 用 `wrangler types` 生成的全局 `Env` 类型（`worker-configuration.d.ts`，已 gitignore），不依赖 `@cloudflare/workers-types`。部署用 `npm create cloudflare@latest` 初始化 + `bun run setup`（创建 bucket + lifecycle + secret）+ `bun run deploy`。生产出口经 Deno Deploy 边缘代理（`https://cloud-artifacts.claude-code-best.win`），副作用是 HTTP status code 被抹平为 200（body 的 `{error}` 字段仍保留）。详见 `packages/cloud-artifacts/README.md`。\n\n### ACP Protocol (Agent Client Protocol)\n\n- **`src/services/acp/`** — ACP agent 实现，包含 `agent.ts`（AcpAgent 类）、`bridge.ts`（Claude Code ↔ ACP 桥接）、`permissions.ts`（权限处理）、`entry.ts`（入口）。\n- **`packages/acp-link/`** — ACP 代理服务器，将 WebSocket 客户端桥接到 ACP agent。提供 `acp-link` CLI 命令，支持自定义端口/HTTPS/认证/会话管理、RCS 集成（REST 注册 + WS identify 两步流程）、权限模式透传（fallback: 客户端传值 > config > `ACP_PERMISSION_MODE` 环境变量）。\n- ACP 权限管道改进：`createAcpCanUseTool` 统一权限流水线，`applySessionMode` 模式同步，`bypassPermissions` 可用性检测（非 root/sandbox 环境）。\n- ACP Plan 可视化已支持 `session/update plan` 类型的消息展示（PlanView 组件，含进度条/状态图标/优先级标签）。\n\n### Daemon Mode\n\n- **`src/daemon/`** — Daemon 模式（长驻 supervisor）。feature-gated by `DAEMON`。包含 `main.ts`（entry）和 `workerRegistry.ts`（worker 管理）。\n\n### Context & System Prompt\n\n- **`src/context.ts`** — Builds system/user context for the API call (git status, date, CLAUDE.md contents, memory files).\n- **`src/utils/claudemd.ts`** — Discovers and loads CLAUDE.md files from project hierarchy.\n\n### Feature Flag System\n\nFeature flags control which functionality is enabled at runtime. 代码中统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。\n\n**启用方式**: 环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev`。\n\n**Build 默认 features**（65+ 个，见 `build.ts` 中 `DEFAULT_BUILD_FEATURES`）:\n- 基础: `BUDDY`, `TRANSCRIPT_CLASSIFIER`, `BRIDGE_MODE`, `AGENT_TRIGGERS_REMOTE`, `CHICAGO_MCP`, `VOICE_MODE`\n- 统计/缓存: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`\n- P0 本地: `AGENT_TRIGGERS`, `ULTRATHINK`, `BUILTIN_EXPLORE_PLAN_AGENTS`, `LODESTONE`\n- P1 API 依赖: `EXTRACT_MEMORIES`, `VERIFICATION_AGENT`, `KAIROS_BRIEF`, `AWAY_SUMMARY`, `ULTRAPLAN`\n- P2: `DAEMON`, `ACP`\n- 工作流: `WORKFLOW_SCRIPTS`, `HISTORY_SNIP`, `MONITOR_TOOL`, `KAIROS`\n- 多 worker: `COORDINATOR_MODE`, `BG_SESSIONS`, `TEMPLATES`\n- 连接器: `CONNECTOR_TEXT`, `COMMIT_ATTRIBUTION`, `DIRECT_CONNECT`\n- 实验性: `EXPERIMENTAL_SKILL_SEARCH`, `EXPERIMENTAL_SEARCH_EXTRA_TOOLS`\n- 模式: `POOR`, `SSH_REMOTE`\n- 已禁用: `CONTEXT_COLLAPSE`, `FORK_SUBAGENT`, `UDS_INBOX`, `LAN_PIPES`, `REVIEW_ARTIFACT`, `TEAMMEM`, `SKILL_LEARNING`\n\n**Dev mode 默认**: 全部启用（见 `scripts/dev.ts`）。\n\n**类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。\n\n**新增功能的正确做法**: 保留 `import { feature } from 'bun:bundle'` + `feature('FLAG_NAME')` 的标准模式，在运行时通过环境变量或配置控制，不要绕过 feature flag 直接 import。\n\n### Multi-API 兼容层\n\n所有兼容层均采用流适配器模式：将第三方 API 格式转为 Anthropic 内部格式，下游代码完全不改。通过 `/login` 命令配置。\n\n#### OpenAI 兼容层\n\n通过 `CLAUDE_CODE_USE_OPENAI=1` 启用，支持 Ollama/DeepSeek/vLLM 等任意 OpenAI Chat Completions 协议端点。含 DeepSeek thinking mode 支持。\n\n- **`src/services/api/openai/`** — client、消息/工具转换、流适配、模型映射\n- 关键环境变量：`CLAUDE_CODE_USE_OPENAI`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`\n\n#### Gemini 兼容层\n\n通过 `CLAUDE_CODE_USE_GEMINI=1` 启用。独立环境变量体系。\n\n- **`src/services/api/gemini/`** — client、模型映射、类型定义\n- 关键环境变量：`GEMINI_API_KEY`（必填）、`GEMINI_MODEL`（直接指定）、`GEMINI_DEFAULT_SONNET_MODEL`/`GEMINI_DEFAULT_OPUS_MODEL`（按能力映射）\n- 模型映射优先级：`GEMINI_MODEL` > `GEMINI_DEFAULT_*_MODEL` > `ANTHROPIC_DEFAULT_*_MODEL`(已废弃) > 原样返回\n\n#### Grok 兼容层\n\n通过 `CLAUDE_CODE_USE_GROK=1` 启用。自定义模型映射支持 xAI Grok API。\n\n- **`src/services/api/grok/`** — client、模型映射\n\n详见各兼容层的 docs 文档。\n\n### 穷鬼模式（Budget Mode）\n\n- 通过 `/poor` 命令切换，持久化到 `settings.json`。\n- 启用后跳过 `extract_memories`、`prompt_suggestion` 和 `verification_agent`，显著减少 token 消耗。\n- 实现在 `src/commands/poor/poorMode.ts`。\n\n### Stubbed/Deleted Modules\n\n| Module | Status |\n|--------|--------|\n| Computer Use (`@ant/*`) | Restored — macOS + Windows + Linux（后端完整度不一） |\n| `*-napi` packages | 全部已恢复/实现：`audio-capture-napi`、`image-processor-napi` 已恢复；`color-diff-napi` 完整；`modifiers-napi`（macOS FFI）；`url-handler-napi`（环境变量+CLI） |\n| Voice Mode | Restored — Push-to-Talk 语音输入（需 Anthropic OAuth） |\n| OpenAI/Gemini/Grok 兼容层 | Restored |\n| Remote Control Server | Restored — 自托管 RCS + Web UI |\n| `packages/shell/`, `packages/swarm/`, `packages/mcp-server/`, `packages/cc-knowledge/` | Removed — 功能合并或废弃 |\n| Analytics / GrowthBook / Sentry | Empty implementations |\n| Magic Docs / LSP Server | Restored — Magic Docs 自动更新 + LSP 服务器管理器 |\n| Plugins / Marketplace | Restored — 插件安装/卸载/启用/禁用 + Marketplace 浏览 |\n| MCP OAuth | Simplified |\n\n### Key Type Files\n\n- **`src/types/global.d.ts`** — Declares `MACRO`, `BUILD_TARGET`, `BUILD_ENV` and internal Anthropic-only identifiers.\n- **`src/types/internal-modules.d.ts`** — Type declarations for `bun:bundle`, `bun:ffi`, `@anthropic-ai/mcpb`.\n- **`src/types/message.ts`** — Message type hierarchy (UserMessage, AssistantMessage, SystemMessage, etc.).\n- **`src/types/permissions.ts`** — Permission mode and result types.\n\n## Testing\n\n- **框架**: `bun:test`（内置断言 + mock）\n- **单元测试**: 就近放置于 `src/**/__tests__/`，文件名 `<module>.test.ts`\n- **集成测试**: `tests/integration/` — 6 个文件（cli-arguments, context-build, message-pipeline, tool-chain, autonomy-lifecycle-user-flow, dependency-overrides）\n- **共享 mock/fixture**: `tests/mocks/`（api-responses, file-system, fixtures/）\n- **命名**: `describe(\"functionName\")` + `test(\"behavior description\")`，英文\n- **包测试**: `packages/` 下各包也有独立测试（如 `color-diff-napi` 11 tests）\n\n### Mock 使用规范\n\n**只 mock 有副作用的依赖链，不 mock 纯函数/纯数据模块。**\n\n被迫 mock 的根源：`log.ts` / `debug.ts` → `bootstrap/state.ts`（模块级 `realpathSync` / `randomUUID` 副作用）。必须 mock 的模块：`log.ts`、`debug.ts`、`bun:bundle`、`settings/settings.js`、`config.ts`、`auth.ts`、第三方网络库。\n\n**`log.ts` 和 `debug.ts` 使用共享 mock**（`tests/mocks/log.ts` / `tests/mocks/debug.ts`），不要在测试文件中内联 mock 定义。使用方式：\n\n```ts\nimport { logMock } from \"../../../tests/mocks/log\";\nmock.module(\"src/utils/log.ts\", logMock);\n\nimport { debugMock } from \"../../../../tests/mocks/debug\";\nmock.module(\"src/utils/debug.ts\", debugMock);\n```\n\n源文件导出变更时只需更新 `tests/mocks/` 下的对应文件，不需要逐个修改测试。\n\n不要 mock：纯函数模块（`errors.ts`、`stringUtils.js`）、mock 值与真实实现相同的模块、mock 路径与实际 import 不匹配的模块。\n\n路径规则：统一用 `.ts` 扩展名 + `src/*` 别名路径，禁止双重 mock 同一模块。\n\n#### 跨文件 mock 污染（process-global `mock.module`）\n\n**Bun 的 `mock.module` 是进程全局的（last-write-wins），不是 per-file 隔离的。** 一个测试文件的 `mock.module` 会污染同一进程中所有其他测试文件的 `require`/`import`。\n\n**关键事实（Bun 1.x 实测验证）：**\n- 测试文件执行顺序**不是严格字母序**，不要假设文件 A 一定在文件 B 之前执行。\n- `mock.module` 在 `beforeAll` 内部调用时**不会被提升**（hoist），但仍会污染后续加载的文件。\n- `require()` 和 `import()` 共享同一模块注册表，`mock.module` 对两者都生效。\n- 一个模块一旦被某个文件的 `mock.module` 替换，同一进程中所有后续 `require`/`import` 都会返回 mock 值，即使调用方使用不同的 specifier 路径。\n\n**核心规则：不要 mock 被测模块的上层业务模块。**\n\n错误做法（会污染同目录的 `api.test.ts`）：\n```ts\n// launchSchedule.test.ts — 直接 mock 源 API 模块 ❌\nmock.module('src/commands/schedule/triggersApi.js', () => ({\n  listTriggers: listTriggersMock,\n  // ...\n}))\n```\n\n正确做法（mock 底层 HTTP 层，不污染业务模块）：参考 `launchSkillStore.test.ts`、`launchVault.test.ts` 的模式。\n```ts\n// launchSchedule.test.ts — mock axios 而非 triggersApi ✅\nimport { setupAxiosMock } from '../../../../tests/mocks/axios.js'\n\nconst axiosHandle = setupAxiosMock()\naxiosHandle.stubs.get = axiosGetMock\naxiosHandle.stubs.post = axiosPostMock\n\nbeforeAll(() => { axiosHandle.useStubs = true })\nafterAll(() => { axiosHandle.useStubs = false })\n```\n\n**判断标准：** 如果目录下同时有 `launch*.test.ts`（集成测试）和 `api.test.ts`（回归测试），`launch*.test.ts` 必须 mock axios 而非源 API 模块。`api.test.ts` 需要测试真实 API 模块的 HTTP 方法/URL/错误处理逻辑，被 mock 后就无法测试。\n\n**排查 mock 污染的方法：**\n1. 单独运行可疑文件确认其通过：`bun test path/to/suspect.test.ts`\n2. 与同目录其他文件一起运行定位污染源：`bun test path/to/__tests__/`\n3. 在两个文件中各加 `console.error('[file] milestone')` 追踪实际执行顺序\n4. 检查 `mock.module` 的 specifier 是否与同目录其他测试的 `require`/`import` 路径解析到同一模块\n\n### 类型检查\n\n项目使用 TypeScript strict 模式，**tsc 必须零错误**。每次修改后运行：\n\n```bash\nbun run precheck\n```\n\n**类型规范**：\n- 生产代码禁止 `as any`；测试文件中 mock 数据可用 `as any`\n- 类型不匹配优先用 `as unknown as SpecificType` 双重断言，或补充 interface\n- 未知结构对象用 `Record<string, unknown>` 替代 `any`\n- 联合类型用类型守卫（type guard）收窄，不要强转\n- `msg.request` 属性访问：`const req = msg.request as Record<string, unknown>`\n- Ink `color` prop：用 `as keyof Theme` 而非 `as any`\n\n## Working with This Codebase\n\n- **precheck must pass** — `bun run precheck`（typecheck + lint fix + test）必须零错误，任何修改都不能引入新的类型/lint/测试错误。\n- **Feature flags** — 默认全部关闭（`feature()` 返回 `false`）。Dev/build 各有自己的默认启用列表。不要在 `cli.tsx` 中重定义 `feature` 函数。\n- **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)`). This is normal.\n- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`feature()` 只能直接用在 `if` 语句或三元表达式的条件位置**（Bun 编译器限制），不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。正确：`if (feature('X')) {}` 或 `feature('X') ? a : b`。\n- **`src/` path alias** — tsconfig maps `src/*` to `./src/*`. Imports like `import { ... } from 'src/utils/...'` are valid.\n- **MACRO defines** — 集中管理在 `scripts/defines.ts`。Dev mode 通过 `bun -d` 注入，build 通过 `Bun.build({ define })` 注入。修改版本号等常量只改这个文件。\n- **构建产物兼容 Node.js** — `build.ts` 会自动后处理 `import.meta.require`，产物可直接用 `node dist/cli.js` 运行。\n- **Biome 配置** — 42 条 lint 规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。格式化覆盖全项目（`src/`、`scripts/`、`packages/`，含 `packages/@ant/`）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。JSON 格式化已启用。`.editorconfig` 与 Biome 配置对齐（2-space 缩进）。修改任何代码后应运行 `bun run precheck` 确认无类型/lint/格式/测试问题，pre-commit hook 会自动拦截不合格提交。\n- **tsc 与 Biome 冲突处理** — 当 tsc 要求声明属性（赋值使用）但 biome 报 `noUnusedPrivateClassMembers`（只写不读）时，用 `// biome-ignore lint/correctness/noUnusedPrivateClassMembers: <原因>` 抑制 lint 警告，保留类型声明。`biome ci` 必须零 warnings。\n- **`@ts-expect-error` 维护** — 只在下方代码确实有类型错误时保留 `@ts-expect-error`。如果类型系统已更新导致 directive 变为 unused（TS2578），直接移除注释。MACRO 替换产生的永假比较（如 `'production' === 'development'`）仍需保留 `@ts-expect-error`。\n- **Ink 框架在 `packages/@ant/ink/`** — 不是 `src/ink/`（该目录不存在）。Ink 相关的组件、hooks、keybindings 都在 packages 中。\n- **Provider 优先级** — `modelType` 参数 > 环境变量 > 默认 `firstParty`。新增 provider 需在 `src/utils/model/providers.ts` 注册。\n\n## Design Context\n\nImpeccable 设计上下文保存在 `.impeccable.md` 中。设计 Web UI（RCS 控制面板、文档站、着陆页）时必须参考该文件。\n\n### 核心设计原则\n\n1. **Considered over clever** — 每个设计选择都应感觉有意为之，而非追逐潮流\n2. **Warmth through subtlety** — 通过橙色色调的中性色、留白布局、有温度的文案来传达温暖\n3. **Density with clarity** — 技术用户需要信息密度，但不能混乱\n4. **Community voice** — 设计应感觉是由使用者创造的，而非遥远的设计团队\n5. **Anthropic's shadow** — 遵循 Anthropic 的设计直觉：干净的布局、充足的间距、温暖的色温\n\n### 品牌色\n\n- 主色：Claude Orange `#D77757`（terra cotta）\n- 辅色：Claude Blue `#5769F7`\n- 暗色模式使用温暖的深色表面（非冷蓝黑色）\n\n### 目标用户\n\n技术团队/企业，在专业工作流中使用 AI 辅助编程。友好的开源社区氛围，非企业 SaaS 风格。\n\n### 视觉参考\n\nAnthropic 公司的设计风格 — 干净、考究、温暖的底色。大量留白，以排版为核心。避免 AI 产品常见的设计套路（渐变文字、玻璃态、霓虹色）。\n"}}