@mycodemap/mycodemap 0.1.1 → 0.2.0

package/docs/rules/engineering-with-codex-openai.md

@@ -0,0 +1,202 @@
+# 基于 Codex 的工程落地规则
+
+> 目标：把 OpenAI《Engineering with Codex》里的高信号原则，转成当前 CodeMap 仓库可执行的开发与交付规则。
+> 适用范围：本仓库内使用 Codex / Claude / 其他 agent 进行分析、修改、验证、提交流程。
+
+## 1. 先说边界
+
+- 本项目当前主要交付形态是 npm 包与 CLI，不是长期运行的 Web 服务。
+- 因此这里强调的是 `CLI` / `CI` 护栏，而不是 preview 环境或部署沙箱。
+- 涉及长期稳定知识时，优先写入仓库文档与生成物；不要把关键约束留在聊天记录、口头约定或临时笔记里。
+
+## 2. 核心原则
+
+- 人类掌舵，agent 执行：人类负责定义目标、限制、DoD、依赖和验收；agent 负责检索、实现、验证和补文档。
+- 地图优于手册：入口文档保持短小，只做路由；细节下沉到 `ARCHITECTURE.md`、`docs/rules/`、`docs/design-docs/`、`docs/exec-plans/`。
+- 仓库是记录系统：规则、设计权衡、执行计划、生成产物、失败复盘都应进入版本控制。
+- 检索优先于记忆：优先使用 `node dist/cli/index.js query|analyze|deps|impact` 获取事实，再回退到 `rg`、`find`、直接读文件。
+- 规则优先编码：重复出现的评审意见、输出约束、结构边界，优先落为 CLI 子命令、hook、CI 检查或生成契约，而不是停留在 prose。
+
+## 3. 渐进式上下文披露（Harness 规范）
+
+**原则**：不向 AI 提供超过当前任务决策所需的信息，避免注意力稀释。
+
+**上下文层级**（AI 按优先级读取）：
+
+1. **T0-地图层**（始终提供）：架构说明、类型定义、关键约束文件
+   - `AGENTS.md`（仓库级强约束）
+   - `CLAUDE.md`（执行手册）
+   - `src/types/index.ts`（核心类型）
+
+2. **T1-任务相关层**（动态检索）：通过 CodeMap CLI 或文件路径匹配提供
+   - 当前修改文件的依赖图谱（直接上下游）
+   - 相关测试文件（同名 `.test.ts` 或 `.spec.ts`）
+   - 接口定义（如果实现类，提供接口）
+
+3. **T2-按需获取层**（工具调用）：AI 明确请求时才提供
+   - 具体业务逻辑实现细节
+   - 历史提交记录
+   - 第三方库文档
+
+**禁止行为**：不要将整个 `node_modules` 目录或上千行无关代码粘贴给 AI。
+
+## 4. 当前项目的 CLI 护栏
+
+- 仓库内调试与验证优先使用 `node dist/cli/index.js <command>`，因为当前真实 CLI 入口是 `dist/cli/index.js`。
+- 需求澄清、影响分析、引用定位优先走 `query`、`analyze`、`deps`、`impact`，不要直接全仓漫游。
+- 修改 `analyze`、`query`、`ci`、`workflow` 等高影响命令时，至少验证：
+  - `--help` 输出与文档示例一致；
+  - 受影响的真实子命令可以在当前仓库运行；
+  - 若涉及机器输出，`--output-mode machine --json` 仍保持纯 JSON 契约。
+- 若改动会影响 agent 执行手册、README 示例、测试事实或入口路由，先执行 `npm run docs:check`。
+- 若希望通过统一 CLI 护栏入口执行同一检查，使用 `node dist/cli/index.js ci check-docs-sync`。
+- 涉及发布边界时，再补 `npm run build` 与 `npm run validate-pack`；不要把本地临时产物当成发布事实。
+
+## 5. 当前项目的 CI 护栏
+
+- 本地护栏：
+  - `.githooks/pre-commit` 会执行变更相关测试、文件头检查，并尝试生成 AI feed。
+  - 当变更涉及 README、`docs/`、CLI 入口、测试配置或 CI 配置时，`.githooks/pre-commit` 还会执行 `npm run docs:check`。
+  - `.githooks/commit-msg` 会校验 `[TAG] scope: message` 格式与单次 commit 文件数量。
+- 服务端护栏：
+  - `.github/workflows/ci-gateway.yml` 会执行 `npm run docs:check`、`npm run typecheck`、`npm test`、`npm run build`，然后再通过 `node dist/cli/index.js ci ...` 执行 `check-docs-sync`、`check-commits`、`check-commit-size`、`check-headers`、`assess-risk`、`check-output-contract` 与 AI feed 同步检查。
+  - `.github/workflows/publish.yml` 会在发布前执行 `npm test` 与 `npm run build`。
+- 仓库协议仍然禁止通过 `--no-verify`、关闭 hook、放宽阈值、删除检查项来"修复"问题。
+
+## 6. 代码生成红线详细规范（Harness 规范）
+
+AI 生成代码时，以下模式触发**硬性阻断**：
+
+| 红线规则 | 检测方式 | 阻断标准 | 修复策略 |
+|---------|---------|---------|---------|
+| **敏感信息硬编码** | 正则检测 `"password"`, `"secret"`, `"api_key"`, `"token"` 字面量 | 生产代码中出现明文凭证 | 替换为 `process.env.XXX` 读取 + env 类型声明 |
+| **`any` 类型使用** | `tsc --noImplicitAny` + ESLint `@typescript-eslint/no-explicit-any` | 非边界文件使用 `any` | 推导具体类型或使用 `unknown` + 类型守卫 |
+| **函数超过 50 行** | 代码行数统计（不含空行和注释） | 单函数 >50 行 | 拆分为子函数，保持单一职责 |
+| **未处理 Promise** | ESLint `@typescript-eslint/no-floating-promises` | 异步调用无 `await` 或错误处理 | 添加 `await` 或 `.catch()` 处理 |
+| **`console.log` 遗留** | ESLint `no-console` | 非调试代码包含 `console.log` | 使用 `src/cli/runtime-logger.ts` 替代 |
+| **未使用 import** | ESLint `@typescript-eslint/no-unused-vars` | 存在未引用 import | 自动删除或标记为使用 |
+| **缺少文件头** | `.githooks/pre-commit` 检查 | TS 源文件缺少 `[META]` 或 `[WHY]` | 添加标准文件头注释 |
+
+## 7. 依赖流向规则（Harness 规范）
+
+**第一性原理**：业务逻辑必须与实现细节解耦，确保可测试性和技术栈可替换性。
+
+当前项目采用 **MVP3 分层架构**（从上至下依赖）：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLI Layer                            │
+│  src/cli/ - 命令行接口，注册命令、参数解析、用户交互          │
+├─────────────────────────────────────────────────────────────┤
+│                      Server Layer                           │
+│  src/server/ - HTTP API 服务器，RESTful 端点，Handler 处理    │
+├─────────────────────────────────────────────────────────────┤
+│                       Domain Layer                          │
+│  src/domain/ - 核心业务逻辑，领域实体与服务                   │
+│  - entities/: Project, Module, Symbol, Dependency, CodeGraph │
+│  - services/: CodeGraphBuilder                              │
+│  - events/: DomainEvent                                     │
+│  - repositories/: 仓库接口                                  │
+├─────────────────────────────────────────────────────────────┤
+│                   Infrastructure Layer                      │
+│  src/infrastructure/ - 技术实现细节                          │
+│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage, Neo4jStorage
+│  - parser/: TypeScriptParser, GoParser, PythonParser, ParserRegistry
+│  - repositories/: CodeGraphRepositoryImpl                   │
+├─────────────────────────────────────────────────────────────┤
+│                     Interface Layer                         │
+│  src/interface/ - 类型定义与契约，跨层共享的接口              │
+│  - types/: 核心类型定义                                     │
+│  - config/: 配置接口                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**分层依赖规则**（严格自上而下）：
+- CLI → Server → Domain → Infrastructure → Interface
+- **禁止跨层依赖**（如 Domain 层不得导入 CLI 模块）
+- 同层内可以相互依赖
+
+**Enforcement 规则**：
+1. **Domain 层禁止导入**：CLI、Server 层模块
+2. **Infrastructure 层禁止导入**：CLI、Server、Domain 中的具体实现
+3. **Server 层禁止导入**：CLI 层模块
+4. **跨层调用必须通过接口**，依赖 Interface 层契约
+
+**历史架构说明**：
+- MVP3 之前的旧架构（cli→orchestrator→core→parser→generator）已完成迁移
+- 原有 `src/orchestrator/` 部分功能已整合到 Server 层和 CLI 层
+- 原有 `src/core/`、`src/parser/`、`src/generator/` 已迁移到 Domain/Infrastructure 层
+
+**违规检测**：使用 `dependency-cruiser` 或 CodeMap 自身的 `deps` 命令检查跨层依赖。
+
+**违规示例**：
+```typescript
+// ❌ 违规：Domain 层直接依赖 Infrastructure 具体实现
+// src/domain/services/CodeGraphBuilder.ts
+import { FileSystemStorage } from '../infrastructure/storage/FileSystemStorage'; // 错误！
+
+// ✅ 合规：通过 Interface 层契约依赖
+// src/domain/services/CodeGraphBuilder.ts
+import type { IStorage } from '../interface/types/storage'; // 正确：只依赖接口
+```
+
+## 8. 文档与知识落点
+
+- 规则变化：写入 `docs/rules/`
+- 设计权衡：写入 `docs/design-docs/`
+- 执行计划、复盘、技术债：写入 `docs/exec-plans/`
+- 生成物、快照、报告：写入 `docs/generated/`
+- 外部资料摘要：写入 `docs/references/`
+
+如果一次任务无法在 1 天内稳定完成，先拆成更小的执行单元；复杂任务的过程信息不要只留在对话里。
+
+## 9. 失败预演
+
+至少预演一个失败模式，而不是只验证 happy path。当前仓库已经出现过两类高信号风险：
+
+- 文档漂移：例如测试规则曾与真实 `vitest.config.ts` 不一致，导致 agent 按旧规则执行错误命令。
+- 文档检索盲区：当 `analyze documentation` 无法命中文档时，agent 需要立即回退到 `rg` / 直接读文件，并在适用时记录 CodeMap 缺陷，而不是假装"没问题"。
+
+## 10. 最小交付清单（更新版 - Harness 规范）
+
+### 10.1 交付内容
+
+每次 agent 交付至少要说明：
+
+1. **改了什么**：文件清单 + 变更摘要
+2. **为什么改**：需求背景 + 设计决策
+3. **按什么护栏验证**：执行的检查命令和结果
+4. **失败场景或风险模式**：至少一个预演的失败场景
+5. **可信度自评**（见 AGENTS.md 5.1 格式）：确定/推测/需验证/风险
+6. **文档同步说明**：是否更新了相关文档及原因
+
+### 10.2 必须同步文档的触发条件
+
+以下情况**必须**更新对应文档：
+
+| 你的改动 | 必须更新的文档 |
+|---------|--------------|
+| 新增/修改 CLI 命令或参数 | `CLAUDE.md`、`docs/rules/engineering-with-codex-openai.md` |
+| 新增/修改配置项或 Schema | `README.md`、相关配置示例 |
+| 修改类型定义/公共接口 | 接口注释、`docs/rules/` 中相关文档 |
+| 修改 CI/CD 流程 | `docs/rules/validation.md`、`.github/workflows/` |
+| 修改 Git Hooks | `docs/rules/validation.md` |
+| 修改测试规则/覆盖率要求 | `docs/rules/testing.md` |
+| 修改架构分层或依赖规则 | `ARCHITECTURE.md`、`docs/rules/architecture-guardrails.md` |
+| 新增代码质量红线 | `docs/rules/code-quality-redlines.md` |
+| 修改提交格式规范 | `AGENTS.md` |
+| 发现文档与代码不符 | 立即修复对应文档 |
+
+**原则**：若改动会影响其他开发者或 AI 的行为，就必须更新文档。
+
+## 11. 参考来源
+
+- OpenAI Engineering: https://openai.com/engineering/codex/
+- Harness Engineering 方法论：`docs/references/tmp.md`
+- 仓库入口协议：`AGENTS.md`
+- 最小执行手册：`CLAUDE.md`
+- 架构地图：`ARCHITECTURE.md`
+- 当前验证规则：`docs/rules/validation.md`
+- 当前发布规则：`docs/rules/deployment.md`
+- 代码质量红线：`docs/rules/code-quality-redlines.md`
+- 架构护栏：`docs/rules/architecture-guardrails.md`

package/docs/rules/testing.md

@@ -0,0 +1,73 @@
+# 测试规则
+
+> 测试框架、覆盖率要求、基准测试
+
+---
+
+## 测试框架
+
+| 项目 | 配置 |
+|------|------|
+| 框架 | Vitest |
+| 覆盖率工具 | @vitest/coverage-v8 |
+| 目标覆盖率 | >= 80% |
+
+## 测试文件位置
+
+| 类型 | 路径 |
+|------|------|
+| 常规测试 | `src/**/*.test.ts` |
+| 集成测试 | `tests/` 目录（如存在单独集成测试编排） |
+| 基准测试 | `refer/benchmark-quality.test.ts` |
+
+## 测试配置
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    exclude: ['node_modules', 'dist', 'refer/**/*.test.ts'],
+    testTimeout: 10000,
+    hookTimeout: 10000,
+    pool: 'threads'
+  }
+});
+```
+
+## 测试要求
+
+- 所有新功能必须附带测试
+- 测试文件命名：`* .test.ts`
+- 使用 `describe` 和 `it` 组织测试用例
+- 使用 `beforeEach`/`afterEach` 管理测试状态
+
+## 基准测试
+
+- 基准查询集：`refer/benchmark-quality.ts`（30 条预定义查询）
+- 基准测试配置：`vitest.benchmark.config.ts`
+- 关键指标：
+  - Token 消耗降低 >= 40%
+  - Hit@8 >= 90%
+
+## 常用命令
+
+```bash
+# 运行所有测试
+npm test
+npx vitest run
+
+# 运行特定测试文件
+npx vitest run src/orchestrator/__tests__/confidence.test.ts
+
+# 运行与变更相关的测试
+npx vitest run --changed
+
+# 运行覆盖率
+npx vitest run --coverage
+
+# 监视模式
+npx vitest watch
+```

package/docs/rules/validation.md

@@ -0,0 +1,39 @@
+# 验证规则
+
+## 最小验证顺序
+
+1. 先验证与你改动最相关的命令、测试或模块。
+2. 若改动影响 agent 路由、CLI 示例、规则文档或测试事实，先执行 `npm run docs:check`。
+3. 若改动同时影响 CLI 护栏入口，再补 `node dist/cli/index.js ci check-docs-sync`。
+4. 再扩大到 `npm run typecheck`、`npm run lint`、`npm test`。
+5. 涉及发布或打包时，再执行 `npm run build` 与 `npm run validate-pack`。
+
+## CI Gateway 验证流程
+
+CI Gateway 已集成以下自动检查（按执行顺序）：
+
+1. `npm run docs:check` - 文档护栏检查
+2. `npm run typecheck` - TypeScript 类型检查
+3. `npm run lint` - ESLint 代码质量检查（渐进式规则，0 error 通过）
+4. `npm test` - 单元测试
+5. `npm run build` - 构建验证
+6. CLI 相关检查（commit 格式、文件头等）
+
+## 强约束
+
+- 没有验证，不得声称“已解决”。
+- 失败时优先修根因，不绕过护栏。
+- 涉及 CI / hooks / 输出契约时，必须给出失败场景与修复验证证据。
+- 严禁使用 `--no-verify`、禁用 hooks、删除检查项规避失败。
+
+## 常用命令
+
+```bash
+npm run docs:check
+node dist/cli/index.js ci check-docs-sync
+npm run typecheck
+npm test
+npm run lint
+npm run build
+npm run validate-pack
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycodemap/mycodemap",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文",
   "main": "./dist/index.js",
   "type": "module",
@@ -24,13 +24,24 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "docs:check": "node scripts/validate-docs.js && node scripts/validate-ai-docs.js",
+    "docs:check:human": "node scripts/validate-docs.js",
+    "docs:check:ai": "node scripts/validate-ai-docs.js",
     "test": "vitest run",
-    "lint": "eslint src --ext .ts",
+    "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "benchmark": "bash scripts/run-benchmark.sh",
     "test:all": "npm run test && npm run benchmark",
     "prepublishOnly": "npm run build && npm test",
-    "validate-pack": "node scripts/validate-pack.js"
+    "validate-pack": "node scripts/validate-pack.js",
+    "release": "./scripts/release.sh",
+    "check:all": "npm run typecheck && npm run lint && npm test && npm run docs:check",
+    "check:architecture": "echo 'dependency-cruiser not installed, run: npm i -D dependency-cruiser'",
+    "check:security": "npm audit",
+    "check:unused": "echo 'knip not installed, run: npm i -D knip'",
+    "fix:all": "npm run lint -- --fix",
+    "ai:pre-task": "npm run check:all",
+    "ai:post-task": "npm run fix:all && npm run check:all"
   },
   "keywords": [
     "typescript",
@@ -42,10 +53,12 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "@hono/node-server": "^1.19.11",
     "chalk": "^5.3.0",
     "chokidar": "^3.5.3",
     "commander": "^11.1.0",
     "globby": "^14.0.0",
+    "hono": "^4.12.8",
     "ora": "^8.0.1",
     "tree-sitter": "^0.21.1",
     "tree-sitter-typescript": "^0.23.2",
@@ -55,10 +68,10 @@
   "devDependencies": {
     "@types/glob": "^8.1.0",
     "@types/node": "^20.10.0",
-    "@typescript-eslint/eslint-plugin": "^6.15.0",
-    "@typescript-eslint/parser": "^6.15.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
     "@vitest/coverage-v8": "^1.6.1",
-    "eslint": "^8.55.0",
+    "eslint": "^8.57.1",
     "vitest": "^1.1.0"
   },
   "engines": {

package/docs/OMC_TEAM_DEBUG_REPORT.md

@@ -1,285 +0,0 @@
-# OMC Team 模式与 Claude Code 不兼容问题分析报告
-
-> 生成时间：2026-03-07
-> 分析范围：OMC team 模式 + Claude Code 集成
-
----
-
-## 1. 问题现象
-
-### 1.1 观察到的症状
-
-从 trace 数据显示：
-- **worker-1**: spawn 了 **11 次**
-- **worker-2**: spawn 了 **3 次**
-- 主 session 在 16:08 结束，reason: "other"
-
-### 1.2 影响
-
-- 资源快速耗尽（内存、进程）
-- Claude Code 主进程可能因资源压力退出
-- 任务完成状态不稳定
-
----
-
-## 2. 根本原因分析
-
-### 2.1 架构问题：V1 Runtime 的 Watchdog 循环
-
-**问题位置**: `runtime.ts:518-647` (watchdogCliWorkers 函数)
-
-**问题描述**:
-```
-watchdog tick 循环逻辑:
-1. 检查 workers 的 done.json 信号
-2. 如果有信号 -> markTaskFromDone -> killWorkerPane -> spawnWorkerForTask (如果有 pending 任务)
-3. 如果 worker 死了 -> applyDeadPaneTransition -> requeue -> spawnWorkerForTask
-```
-
-**Bug**: 当任务完成后，watchdog 会立即 spawn 新的 worker 来执行其他 pending 任务。这导致：
-- Worker 刚完成就被 kill
-- 立即创建新 worker
-- 如果任务列表只有 1 个任务，也会反复创建同一个 worker
-
-### 2.2 状态同步问题
-
-**问题**: `markTaskFromDone()` 更新任务状态为 completed，但可能存在：
-- 文件系统写入延迟
-- 状态读取不一致
-- 导致 `allTasksTerminal()` 错误判断
-
-### 2.3 Session 管理问题
-
-**观察**:
-- Session 在 16:08 结束 (reason: "other")
-- Workers 在 16:07 完成后反复重建
-- 主 session 可能因资源压力或错误退出
-
-### 2.4 Claude Code 原生 team 集成问题
-
-从 config.json 可见：
-- Workers 使用 `in-process` backend (`"backendType": "in-process"`)
-- 这意味着 workers 运行在同一个 Claude Code 进程内
-- 当 worker 完成后返回结果时，可能触发主进程重新 spawn
-
----
-
-## 3. 具体问题点
-
-### 问题 1: Watchdog 立即重新分配任务
-
-**代码位置**: `runtime.ts:559-565`
-```typescript
-if (signal) {
-  // ... 处理完成信号
-  await killWorkerPane(runtime, wName, active.paneId);
-  if (!(await allTasksTerminal(runtime))) {
-    const nextTaskIndexValue = await nextPendingTaskIndex(runtime);
-    if (nextTaskIndexValue != null) {
-      await spawnWorkerForTask(runtime, wName, nextTaskIndexValue); // 立即 spawn!
-    }
-  }
-}
-```
-
-**问题**: 任务完成后立即 spawn 新 worker，没有给主 session 任何喘息机会
-
-### 问题 2: Worker 复用逻辑缺失
-
-**代码位置**: `runtime.ts:421-426`
-```typescript
-const maxConcurrentWorkers = agentTypes.length;
-for (let i = 0; i < maxConcurrentWorkers; i++) {
-  const taskIndex = await nextPendingTaskIndex(runtime);
-  if (taskIndex == null) break;
-  await spawnWorkerForTask(runtime, workerName(i), taskIndex);
-}
-```
-
-**问题**: 每次都创建新的 workerName，而不是复用已有的 worker
-
-### 问题 3: In-Process Workers 的状态管理
-
-**代码位置**: config.json
-```json
-{
-  "backendType": "in-process"
-}
-```
-
-**问题**: in-process workers 完成后会返回结果给主 agent，这可能触发某种重新调度的 hook，导致反复 spawn
-
-### 问题 4: 缺乏资源限制
-
-**问题**: 没有机制限制：
-- 单个 worker 的最大执行时间
-- 总 worker spawn 次数
-- 内存使用上限
-
----
-
-## 4. 修复方案
-
-### 4.1 方案 A: 启用 V2 Runtime (推荐)
-
-**原理**: V2 runtime 使用事件驱动架构，避免轮询问题
-
-**操作**:
-```bash
-export OMC_RUNTIME_V2=1
-# 然后重新运行 team
-```
-
-**预期效果**:
-- 更稳定的任务状态管理
-- 事件驱动而非轮询
-- 减少不必要的 worker 重建
-
-### 4.2 方案 B: 修复 V1 Runtime
-
-#### B.1 添加冷却期
-
-**修改位置**: `runtime.ts:559-565`
-
-```typescript
-// 在 killWorkerPane 后添加延迟
-await killWorkerPane(runtime, wName, active.paneId);
-
-// 添加冷却期，避免立即重新 spawn
-await new Promise(resolve => setTimeout(resolve, 2000));
-
-if (!(await allTasksTerminal(runtime))) {
-  // ... existing logic
-}
-```
-
-#### B.2 添加 Worker 池机制
-
-**修改位置**: `runtime.ts` - 新增 worker 池状态
-
-```typescript
-interface WorkerPool {
-  availableWorkers: string[];  // 可复用的 worker 名称
-  activeWorkers: Map<string, ActiveWorkerState>;
-}
-
-// 在 spawnWorkerForTask 中复用
-async function spawnWorkerForTask(...) {
-  // 先检查池中是否有可用 worker
-  if (runtime.workerPool.availableWorkers.length > 0) {
-    const reusableWorkerName = runtime.workerPool.availableWorkers.pop();
-    // 复用该 worker
-  }
-  // 否则创建新 worker
-}
-```
-
-#### B.3 添加资源限制
-
-**修改位置**: `runtime.ts` - 新增限制配置
-
-```typescript
-const MAX_WORKER_SPAWNS = 20;  // 最多 spawn 次数
-const WORKER_COOLDOWN_MS = 3000;  // 冷却期
-
-// 在 watchdog 中跟踪 spawn 次数
-let workerSpawnCount = 0;
-
-async function spawnWorkerForTask(...) {
-  if (workerSpawnCount >= MAX_WORKER_SPAWNS) {
-    console.warn('[watchdog] Max worker spawn limit reached');
-    return '';
-  }
-  workerSpawnCount++;
-  // ... existing logic
-}
-```
-
-### 4.3 方案 C: 修复 Claude Code 集成
-
-#### C.1 修改 worker hook 逻辑
-
-**修改位置**: `src/hooks/team-worker-hook.ts`
-
-确保 worker 完成后：
-1. 写入 done.json
-2. **不自动退出** (等待主 session 指示)
-3. 进入空闲状态等待新任务
-
-#### C.2 添加状态一致性检查
-
-**修改位置**: `runtime.ts:allTasksTerminal()`
-
-```typescript
-export async function allTasksTerminal(runtime: TeamRuntime): Promise<boolean> {
-  const root = stateRoot(runtime.cwd, runtime.teamName);
-
-  // 多次重试读取确保一致性
-  for (let retry = 0; retry < 3; retry++) {
-    let allTerminal = true;
-    for (let i = 0; i < runtime.config.tasks.length; i++) {
-      const task = await readTask(root, String(i + 1));
-      if (!task) return false;  // 任务文件不存在
-      if (task.status !== 'completed' && task.status !== 'failed') {
-        allTerminal = false;
-      }
-    }
-    if (allTerminal) return true;
-    await new Promise(r => setTimeout(r, 100));  // 等待状态稳定
-  }
-  return false;
-}
-```
-
----
-
-## 5. 实施建议
-
-### 优先级
-
-| 优先级 | 修复项 | 难度 | 预期效果 |
-|--------|--------|------|----------|
-| P0 | 启用 V2 Runtime | 低 | 立即改善 |
-| P1 | 添加冷却期 | 中 | 减少频繁重建 |
-| P2 | Worker 池机制 | 高 | 根本解决 |
-| P3 | 资源限制 | 中 | 防止资源耗尽 |
-
-### 验证方法
-
-```bash
-# 1. 检查 OMC_RUNTIME_V2 是否启用
-echo $OMC_RUNTIME_V2
-
-# 2. 运行 team 并监控 spawn 次数
-/team 3:executor "test task"
-
-# 3. 观察日志中 worker spawn 次数
-# 修复前: worker-1 spawn 11 次
-# 修复后: worker-1 spawn 1-2 次
-```
-
----
-
-## 6. 附录：相关代码位置
-
-| 文件 | 说明 |
-|------|------|
-| `src/team/runtime.ts` | V1 runtime 核心逻辑 |
-| `src/team/runtime-v2.ts` | V2 runtime (事件驱动) |
-| `src/hooks/team-worker-hook.ts` | Worker 生命周期 hook |
-| `src/hooks/team-leader-nudge-hook.ts` | 主 session 状态 hook |
-| `src/team/tmux-session.ts` | tmux 会话管理 |
-| `src/team/task-file-ops.ts` | 任务文件操作 |
-
----
-
-## 7. 结论
-
-OMC team 模式与 Claude Code 不兼容的主要原因是：
-
-1. **V1 runtime 的 watchdog 逻辑缺陷** - 任务完成后立即重新 spawn worker
-2. **缺乏 worker 复用机制** - 每次都创建新 worker
-3. **资源限制缺失** - 没有防止无限 spawn 的保护
-4. **In-process workers 状态同步问题** - 主进程可能因资源压力退出
-
-**推荐优先尝试方案 A (启用 V2 Runtime)**，这是最简单且最可能立即见效的方案。