mumucc 0.4.1 → 0.4.3

package/AGENTS.md

@@ -0,0 +1,297 @@
+# AGENTS.md
+
+> 变更记录: 2026-03-31 13:28:58 -- 完成全部 33 个模块的 AGENTS.md 文档初始化
+
+本文件为 Codex (Codex.ai/code) 提供项目上下文指引。
+
+## 项目愿景
+
+本仓库是 Codex CLI 的开源版本，基于原始源码进行开发和维护。使用 Bun + TypeScript + React/Ink 技术栈，提供交互式会话、工具调用、多代理协调、MCP 集成等功能。
+
+**主要新增功能：**
+- 三方 Anthropic 兼容模型支持（MiniMax、GLMCodingPlan、KIMICodingPlan、ALiyunCodingPlan 等）
+- 企业级代理配置
+- 更多可配置选项
+
+## 技术栈
+
+- **运行时**: [Bun](https://bun.sh)（非 Node.js -- 使用了 `bun:bundle` 等 Bun 专有 API）
+- **语言**: TypeScript（严格模式）
+- **终端 UI**: React 19 + [Ink](https://github.com/vadimdemedes/ink) -- 终端中的 React
+- **React 编译器**: 代码经 React Compiler 预编译（导入 `react/compiler-runtime`）
+- **CLI 解析**: Commander.js v12 (`@commander-js/extra-typings`)
+- **Schema 验证**: Zod v4 (`zod/v4` 导入路径)
+- **特性开关**: `bun:bundle` -- `feature('FLAG_NAME')` 调用，运行时通过 shim 实现
+
+## 架构总览
+
+```
+src/main.tsx                   -- CLI 入口，Commander.js 解析器 + React/Ink 渲染初始化
+    |
+    +-- src/QueryEngine.ts     -- 外层查询引擎（会话历史、系统提示组装、重试、token 计数）
+    |       |
+    |       +-- src/query.ts   -- 内层查询管线（流式响应、工具调度、自动压缩）
+    |
+    +-- src/context.ts         -- 上下文组装（AGENTS.md、记忆文件、git 状态 -> 系统提示）
+    +-- src/tools.ts           -- 工具注册与池组装
+    +-- src/commands.ts        -- 斜杠命令注册与加载
+    +-- src/state/             -- 全局 React 状态管理
+    +-- src/screens/REPL.tsx   -- 主交互 REPL 界面
+```
+
+## 模块结构图
+
+```mermaid
+graph TD
+    ROOT["Codex CLI"] --> SRC["src/"]
+    ROOT --> SHIMS["shims/"]
+    ROOT --> STUBS["stubs/"]
+    ROOT --> SCRIPTS["scripts/"]
+
+    SRC --> CORE["核心查询"]
+    SRC --> TOOLS["tools/ 工具系统"]
+    SRC --> CMDS["commands/ 命令系统"]
+    SRC --> SVCS["services/ 服务层"]
+    SRC --> STATE["state/ 状态管理"]
+    SRC --> BRIDGE["bridge/ IDE桥接"]
+    SRC --> MEMDIR["memdir/ 记忆系统"]
+    SRC --> HOOKS["hooks/ 钩子系统"]
+    SRC --> INK["ink/ 终端渲染引擎"]
+    SRC --> COMPS["components/ UI组件"]
+    SRC --> CLI["cli/ 非交互CLI"]
+    SRC --> UTILS["utils/ 工具函数"]
+    SRC --> TASKS["tasks/ 后台任务"]
+    SRC --> KEYBIND["keybindings/ 快捷键"]
+    SRC --> CTX["context/ React上下文"]
+    SRC --> SKILLS["skills/ 技能系统"]
+    SRC --> PLUGINS["plugins/ 插件系统"]
+    SRC --> COORDINATOR["coordinator/ 多代理协调"]
+    SRC --> TYPES["types/ 类型定义"]
+    SRC --> CONSTANTS["constants/ 常量"]
+    SRC --> MIGRATIONS["migrations/ 迁移"]
+    SRC --> ENTRYPOINTS["entrypoints/ 入口点"]
+
+    click TOOLS "./src/tools/AGENTS.md" "查看工具系统文档"
+    click CMDS "./src/commands/AGENTS.md" "查看命令系统文档"
+    click SVCS "./src/services/AGENTS.md" "查看服务层文档"
+    click STATE "./src/state/AGENTS.md" "查看状态管理文档"
+    click BRIDGE "./src/bridge/AGENTS.md" "查看桥接系统文档"
+    click MEMDIR "./src/memdir/AGENTS.md" "查看记忆系统文档"
+    click HOOKS "./src/hooks/AGENTS.md" "查看钩子系统文档"
+    click INK "./src/ink/AGENTS.md" "查看终端渲染引擎文档"
+    click COMPS "./src/components/AGENTS.md" "查看UI组件文档"
+    click UTILS "./src/utils/AGENTS.md" "查看工具函数文档"
+    click SHIMS "./shims/AGENTS.md" "查看构建垫片文档"
+    click STUBS "./stubs/AGENTS.md" "查看内部包存根文档"
+```
+
+## 模块索引
+
+| 模块路径 | 职责 | 关键文件 | 文件数(估) |
+|---------|------|---------|-----------|
+| `src/` (根) | CLI 入口、核心查询循环、工具/命令注册 | `main.tsx`, `query.ts`, `QueryEngine.ts`, `Tool.ts`, `tools.ts`, `commands.ts`, `context.ts` | ~18 |
+| `src/tools/` | 工具系统 -- 40+ 工具（Bash/文件读写/搜索/Agent/MCP等） | `BashTool/`, `FileEditTool/`, `AgentTool/`, `GrepTool/` | ~150 |
+| `src/commands/` | 斜杠命令系统 -- 80+ 命令（/compact、/config、/mcp等） | `commands.ts` (注册), 各子目录 | ~120 |
+| `src/services/` | 服务层 -- API客户端、MCP、OAuth、压缩、记忆提取等 | `api/`, `mcp/`, `compact/`, `oauth/`, `analytics/` | ~120 |
+| `src/hooks/` | React 钩子 -- 工具权限、通知、IDE集成、语音等 | `toolPermission/`, `notifs/`, `useTextInput.ts` | ~100 |
+| `src/state/` | 全局状态管理（React Store 模式） | `AppState.tsx`, `AppStateStore.ts`, `store.ts`, `selectors.ts` | 6 |
+| `src/bridge/` | IDE 扩展双向通信（JWT 认证） | `bridgeMain.ts`, `bridgeMessaging.ts`, `replBridge.ts` | ~33 |
+| `src/memdir/` | 持久化记忆系统（YAML frontmatter Markdown） | `memdir.ts`, `findRelevantMemories.ts`, `memoryTypes.ts` | 9 |
+| `src/ink/` | 自定义终端渲染引擎（基于 Ink 深度定制） | `ink.tsx`, `reconciler.ts`, `renderer.ts`, `dom.ts` | ~85 |
+| `src/components/` | UI 组件（消息渲染、设置、对话框等） | `App.tsx`, `messages/`, `Settings/`, `TextInput.tsx` | ~100 |
+| `src/utils/` | 工具函数库（settings、swarm、git、permissions等） | `settings/`, `swarm/`, `permissions/`, `messages/` | ~180 |
+| `src/cli/` | 非交互 CLI 模式（结构化IO、传输层） | `structuredIO.ts`, `transports/`, `handlers/` | ~20 |
+| `src/tasks/` | 后台任务系统（本地Agent、远程Agent、Shell等） | `LocalAgentTask/`, `RemoteAgentTask/`, `LocalShellTask/` | ~14 |
+| `src/keybindings/` | 快捷键系统（解析、匹配、默认绑定） | `parser.ts`, `resolver.ts`, `defaultBindings.ts` | 15 |
+| `src/context/` | React Context 提供者（模态、通知、语音等） | `modalContext.tsx`, `notifications.tsx`, `voice.tsx` | 9 |
+| `src/skills/` | 技能系统（内置技能、MCP技能、技能加载） | `bundled/`, `loadSkillsDir.ts`, `bundledSkills.ts` | ~55 |
+| `src/plugins/` | 插件系统 | `bundled/index.ts`, `builtinPlugins.ts` | 2 |
+| `src/coordinator/` | 多代理协调模式 | `coordinatorMode.ts`, `workerAgent.ts` | 2 |
+| `src/types/` | 共享类型定义（打破循环依赖） | `message.ts`, `permissions.ts`, `tools.ts`, `command.ts` | 15 |
+| `src/constants/` | 全局常量（提示词、API限制、工具限制等） | `prompts.ts`, `apiLimits.ts`, `tools.ts` | 21 |
+| `src/migrations/` | 配置迁移脚本 | `migrateSonnet45ToSonnet46.ts` 等 | 11 |
+| `src/entrypoints/` | 多入口点（CLI、MCP server、Agent SDK） | `cli.tsx`, `mcp.ts`, `init.ts` | 5 |
+| `src/screens/` | 顶层屏幕（REPL、Doctor、ResumeConversation） | `REPL.tsx`, `Doctor.tsx` | 3 |
+| `src/vim/` | Vim 模式支持 | `motions.ts`, `operators.ts`, `transitions.ts` | 5 |
+| `src/buddy/` | Companion 精灵（实验性） | `CompanionSprite.tsx`, `companion.ts`, `sprites.ts` | 6 |
+| `src/remote/` | 远程会话管理 | `RemoteSessionManager.ts`, `SessionsWebSocket.ts` | 4 |
+| `src/native-ts/` | 原生功能的 TypeScript 实现 | `yoga-layout/`, `color-diff/`, `file-index/` | 4 |
+| `src/bootstrap/` | 启动状态管理 | `state.ts` | 1 |
+| `src/proactive/` | 主动模式（实验性，存根） | `index.ts`, `useProactive.ts` | 2 |
+| `src/assistant/` | KAIROS 助手模式（实验性，存根） | `index.ts`, `gate.ts`, `sessionHistory.ts` | 4 |
+| `src/ssh/` | SSH 会话管理（存根） | `SSHSessionManager.ts`, `createSSHSession.ts` | 2 |
+| `src/jobs/` | 后台作业分类器（存根） | `classifier.ts` | 1 |
+| `src/query/` | 查询子系统辅助 | `tokenBudget.ts`, `stopHooks.ts`, `config.ts` | 5 |
+| `shims/` | 构建时垫片（替代 Bun bundler 编译时 API） | `bun-bundle.ts`, `globals.ts` | 2 |
+| `stubs/` | 内部包存根（Anthropic 私有包占位） | `@ant/`, `@anthropic-ai/`, `color-diff-napi/` | 25 |
+| `scripts/` | 构建脚本 | `patch-node-modules.sh` | 1 |
+
+## 开发设置
+
+```bash
+bun install                           # 安装依赖 + 自动 patch node_modules
+bun run start                         # 启动（需要 TTY + ANTHROPIC_API_KEY）
+bun --preload ./shims/globals.ts src/main.tsx -p "prompt"  # 非交互模式
+```
+
+`bun install` 后会自动通过 `postinstall` 运行 `scripts/patch-node-modules.sh` 来修补内部包。
+
+### 构建时垫片
+
+原始代码使用 Bun bundler 的编译时 API，本仓库用运行时垫片替代：
+
+| 原始 | 垫片 | 用途 |
+|------|------|------|
+| `bun:bundle` -> `feature()` | `shims/bun-bundle.ts` | 特性开关（运行时，读取 `ENABLED_FEATURES` 环境变量） |
+| `MACRO.VERSION` 等 | `shims/globals.ts` | 构建时常量（通过 `--preload` 加载） |
+
+启用特性: `ENABLED_FEATURES="VOICE_MODE,PROACTIVE" bun run start`
+
+### 内部包存根
+
+以下内部包在 `stubs/` 中提供了存根，由 `scripts/patch-node-modules.sh` 安装：
+- `@ant/computer-use-*`, `@ant/Codex-for-chrome-mcp` -- Computer Use / Chrome 集成
+- `@anthropic-ai/mcpb` -- DXT 插件处理器
+- `@anthropic-ai/sandbox-runtime` -- 沙箱执行
+- `color-diff-napi` -- 原生 diff 着色
+
+### 缺失源码模块（约123个文件）
+
+部分模块为自动生成的存根（标记 `// AUTO-GENERATED STUB`）。主要包括：
+- 特性门控工具（`MonitorTool`、`WebBrowserTool`、`SnipTool` 等）
+- `src/proactive/` -- 主动模式
+- `src/assistant/` -- KAIROS 助手模式
+- `src/types/message.ts` -- 核心消息类型定义（用 `any` 存根）
+- `src/constants/querySource.ts` -- 查询来源常量
+- 各种缺失特性的 UI 组件
+
+查找所有存根: `grep -rl "AUTO-GENERATED STUB" src/`
+
+## 入口点: src/main.tsx
+
+CLI 的 Commander.js 解析器和 React/Ink 渲染器初始化。前约 20 行故意在其他 import 完成前运行副作用（`startMdmRawRead()`、`startKeychainPrefetch()`）-- 这是刻意的启动并行化，用于在模块求值期间隐藏 macOS 钥匙串和 MDM I/O 延迟。
+
+第 803 行的 TTY 检测: `!process.stdout.isTTY` 触发非交互模式 -- 不进行 Ink 渲染。
+
+## 核心查询循环
+
+API 调用循环跨越两个文件：
+- **`src/query.ts`**（约1,700行）：内层查询管线 -- 处理流式响应、工具调用分发、自动压缩触发和上下文折叠。这是热路径。
+- **`src/QueryEngine.ts`**（约1,300行）：外层引擎 -- 管理会话历史、系统提示组装、重试逻辑、token 计数和会话持久化。调用 `query.ts`。
+
+## 工具系统 (src/tools/)
+
+每个工具是一个自包含的目录，包含其输入 schema（Zod）、权限模型和执行逻辑。基础类型在 `src/Tool.ts`。工具注册在 `src/tools.ts`。每个工具调用的权限检查通过 `src/hooks/toolPermission/` -- 有三个处理器: `interactiveHandler.ts`（提示用户）、`swarmWorkerHandler.ts`（swarm agent）和 `coordinatorHandler.ts`（coordinator agent）。
+
+## 命令系统 (src/commands/)
+
+用 `/` 调用的斜杠命令。每个命令是 `src/commands/` 下的目录或 `.ts` 文件。注册和条件加载（远程模式、bridge 模式等）在 `src/commands.ts` 中完成。许多命令使用条件 `feature()` 导入进行死代码消除。
+
+## 上下文组装 (src/context.ts)
+
+构建系统提示。读取 AGENTS.md 文件（项目 + 父目录）、记忆文件、git 状态，并注入到提示中。使用 lodash 的 `memoize` -- 当系统提示注入发生变化时调用 `getUserContext.cache.clear?.()`。
+
+## 状态管理 (src/state/)
+
+`AppState.tsx` 是在 Ink 组件树中共享的中央 React 状态 store。`AppStateStore.ts` 提供订阅/更新机制。通过 `src/state/selectors.ts` 中的选择器在 hooks 中访问状态。
+
+## 多代理系统
+
+子代理通过 `AgentTool`（`src/tools/AgentTool/`）生成。代理定义来自 `~/.Codex/agents/` 中的 markdown 文件或 JSON，由 `loadAgentsDir.ts` 解析。`coordinator/` 模块处理多代理编排。`TeamCreateTool` 支持并行团队级工作。
+
+## 记忆系统 (src/memdir/)
+
+持久化记忆存储在 `~/.Codex/` 中，以带 YAML frontmatter 的 markdown 文件形式。`memdir.ts` 加载 `MEMORY.md` 索引（上限 200 行 / 25KB）。记忆类型: `user`、`feedback`、`project`、`reference`。
+
+## Bridge 系统 (src/bridge/)
+
+IDE 扩展与 CLI 之间的双向通信。`bridgeMain.ts` 是主循环；`bridgeMessaging.ts` 定义协议；使用 JWT 认证。
+
+## 服务层 (src/services/)
+
+关键子模块: `api/`（Anthropic SDK 客户端）、`mcp/`（MCP 服务器管理）、`oauth/`（认证）、`compact/`（上下文压缩）、`extractMemories/`（自动记忆提取）、`analytics/`（分析/遥测）、`lsp/`（LSP 语言服务器）。
+
+## UI 组件 (src/components/)
+
+React 19 + Ink 渲染的终端 UI 组件系统。核心组件包括 `App`（顶层封装）、`Messages`（虚拟滚动消息列表）、`TextInput`（支持语音波形光标）。子目录覆盖设置界面、消息类型渲染、后台任务状态、Shell 输出、记忆 UI 等。
+
+## 工具函数 (src/utils/)
+
+按职责划分的工具函数库。关键子模块：`settings/`（多层级配置系统 MDM>企业>项目>用户）、`swarm/`（多代理编排 backend）、`permissions/`（权限分类器）、`messages/`（SDK 消息映射）。
+
+## 关键模式
+
+**特性开关门控** -- 用条件导入包裹（不内联 `if`）：
+```typescript
+import { feature } from 'bun:bundle'
+const voiceModule = feature('VOICE_MODE')
+  ? (require('./voice/index.js') as typeof import('./voice/index.js'))
+  : null
+```
+
+**导入路径** -- 所有导入必须使用 `.js` 扩展名（即使是 `.ts` 文件，Bun/ESM 约定）。内部绝对路径使用 `src/` 前缀。
+
+**循环依赖打破** -- 共享类型提取到 `src/types/`。使用惰性 `require()` 加类型断言来打破循环。
+
+**MACRO 常量** -- `MACRO.VERSION`、`MACRO.BUILD_TIME` 等定义在 `shims/globals.ts`（原本由 Bun bundler `--define` 注入）。
+
+## 测试策略
+
+代码中存在测试相关的工具（`TestingPermissionTool`）和条件分支（`process.env.NODE_ENV === 'test'`），表明原始项目有完整的测试套件。
+
+## 编码规范
+
+- TypeScript 严格模式（`tsconfig.json` 中 `strict: true`）
+- 模块解析: `bundler`（Bun 风格）
+- JSX: `react-jsx`
+- 代码经 React Compiler 预编译（`_c` 辅助函数调用模式）
+- `.js` 扩展名用于所有 import（ESM 约定）
+- `eslint` 自定义规则: `custom-rules/no-top-level-side-effects`、`custom-rules/no-process-env-top-level`
+- biome 用于导入组织
+
+## AI 使用指引
+
+- 查找特定工具实现: 查看 `src/tools/<ToolName>/` 目录
+- 查找命令实现: 查看 `src/commands/<command-name>/` 或 `src/commands/<command>.ts`
+- 理解 API 调用流程: `src/main.tsx` -> `src/QueryEngine.ts` -> `src/query.ts`
+- 理解权限模型: `src/hooks/toolPermission/` + `src/utils/permissions/`
+- 理解设置系统: `src/utils/settings/`（多层级配置: MDM > 企业 > 项目 > 用户）
+- 查找自动生成的存根: `grep -rl "AUTO-GENERATED STUB" src/`
+- 默认启用的特性开关: 查看 `shims/bun-bundle.ts` 中的 `DEFAULT_ENABLED` 集合
+
+## 覆盖率报告
+
+| 指标 | 值 |
+|------|-----|
+| 估算总源码文件数 (ts/tsx) | ~2,011 |
+| 已扫描/分析文件数 | ~500 |
+| 扫描覆盖率 | ~24.9% |
+| 已识别模块数 | 33 |
+| 已文档化模块数 | 33 |
+| 自动存根文件数 | 123 |
+| 缺失: CI/CD 配置 | 部分 |
+
+### 各模块覆盖状况
+
+| 模块 | 入口已读 | 接口已读 | 依赖已读 | 覆盖度 |
+|------|---------|---------|---------|--------|
+| 核心 (main/query/QueryEngine) | 是 | 是 | 是 | 高 |
+| tools/ | 是 | 是 | 是 | 高 |
+| commands/ | 是 | 是 | 是 | 高 |
+| services/ | 是 | 部分 | 是 | 中 |
+| state/ | 是 | 是 | 是 | 高 |
+| bridge/ | 是 | 部分 | 是 | 中 |
+| memdir/ | 是 | 是 | 是 | 高 |
+| hooks/ | 部分 | 部分 | 是 | 中 |
+| ink/ | 部分 | 部分 | 否 | 低 |
+| components/ | 部分 | 部分 | 是 | 中 |
+| utils/ | 部分 | 部分 | 是 | 中 |
+| skills/ | 是 | 部分 | 是 | 中 |
+| shims/ | 是 | 是 | 是 | 高 |
+| stubs/ | 是 | 是 | 是 | 高 |
+
+## 变更记录 (Changelog)
+
+- **2026-03-31** -- 初始化开源仓库。更新项目愿景描述，去除 Anthropic 所有权相关表述。
+- **2026-03-31 19:37:16** -- 初始化架构索引。生成根级 AGENTS.md（本文件），识别 33 个模块目录，统计约 2,011 个源码文件和 123 个自动存根。创建模块级 AGENTS.md 文档（tools、commands、services、state、bridge、memdir、hooks、ink）和 .Codex/index.json 索引。
+- **2026-03-31 13:28:58** -- 完成全部 33 个模块的 AGENTS.md 文档初始化。更新根级 Mermaid 图添加 click 链接。更新覆盖率报告（已扫描 500 文件，~24.9%）。所有模块均已添加导航面包屑。

package/bin/mumucc

@@ -42,8 +42,7 @@ if [[ ! -d "$CLAUDE_CONFIG_DIR" ]]; then
   # This is where getMcpConfigsByScope('user') reads from via getGlobalConfig()
   GLOBAL_CONFIG="$CLAUDE_CONFIG_DIR/.mumucc.json"
   if [[ -f "$PROJECT_ROOT/defaults/mcp-servers.json" ]]; then
-    # mumucc: 替换 __MUMUCC_ROOT__ 占位符为实际安装路径
-    sed "s|__MUMUCC_ROOT__|$PROJECT_ROOT|g" "$PROJECT_ROOT/defaults/mcp-servers.json" > "$GLOBAL_CONFIG"
+    cp "$PROJECT_ROOT/defaults/mcp-servers.json" "$GLOBAL_CONFIG"
   elif [[ ! -f "$GLOBAL_CONFIG" ]]; then
     echo '{"mcpServers":{}}' > "$GLOBAL_CONFIG"
   fi
@@ -52,9 +51,8 @@ if [[ ! -d "$CLAUDE_CONFIG_DIR" ]]; then
   echo "  Run 'mumucc /login' to configure your API provider."
 fi
 
-# ── Disable Anthropic-specific traffic (version checks, autoupdater) ──
-# mumucc: 不再设 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC，因为它会杀死 Channels 的特性开关
-# 只禁用自动更新和遥测
+# ── Disable Anthropic-specific traffic (version checks, telemetry) ──
+export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
 export DISABLE_AUTOUPDATER=1
 export DISABLE_TELEMETRY=1