feat: add CLI fallback for MCP calls in team commands

catlog22 · catlog22 · commit 6054a01b8f0a · 2026-02-13T12:05:48.000+08:00
- Implemented CLI fallback using `ccw team` for various team command operations in `execute.md`, `plan.md`, `review.md`, `spec-analyst.md`, `spec-coordinate.md`, `spec-discuss.md`, `spec-reviewer.md`, `spec-writer.md`, and `test.md`.
- Updated command generation templates to include CLI fallback examples.
- Enhanced validation checks to ensure CLI fallback sections are present.
- Added quality standards for CLI fallback in team command design.
- Introduced a new `GlobalGraphExpander` class for expanding search results with cross-directory relationships.
- Added tests for `GlobalGraphExpander` to verify functionality and score decay factors.
diff --git a/.claude/commands/team/execute.md b/.claude/commands/team/execute.md
@@ -55,6 +55,20 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "executor", t
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "executor", to: "coordinator", type: "error", summary: "plan.json路径无效, 无法加载实现计划" })
 ```
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(`ccw team log --team "${teamName}" --from "executor" --to "coordinator" --type "impl_complete" --summary "IMPL-001完成: 5个文件变更" --json`)
+
+// 带 data 参数
+Bash(`ccw team log --team "${teamName}" --from "executor" --to "coordinator" --type "impl_progress" --summary "Batch 1/3 完成" --data '{"batch":1,"total":3}' --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from executor --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]`
+
 ## Execution Process
 
 ```
diff --git a/.claude/commands/team/plan.md b/.claude/commands/team/plan.md
@@ -55,6 +55,17 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "planner", to
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "planner", to: "coordinator", type: "error", summary: "plan-overview-base-schema.json 未找到, 使用默认结构" })
 ```
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(`ccw team log --team "${teamName}" --from "planner" --to "coordinator" --type "plan_ready" --summary "Plan就绪: 3个task" --ref "${sessionFolder}/plan.json" --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from planner --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]`
+
 ## Execution Process
 
 ```
diff --git a/.claude/commands/team/review.md b/.claude/commands/team/review.md
@@ -58,6 +58,17 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "tester", to:
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "tester", to: "coordinator", type: "error", summary: "plan.json未找到, 无法进行需求验证" })
 ```
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(`ccw team log --team "${teamName}" --from "tester" --to "coordinator" --type "review_result" --summary "REVIEW-001: APPROVE, 2 medium findings" --data '{"verdict":"APPROVE","critical":0}' --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from tester --to coordinator --type <type> --summary "<text>" [--data '<json>'] [--json]`
+
 ## Execution Process
 
 ```
diff --git a/.claude/commands/team/spec-analyst.md b/.claude/commands/team/spec-analyst.md
@@ -54,6 +54,17 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-analyst
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-analyst", to: "coordinator", type: "error", summary: "代码库探索失败: 项目根目录无法识别" })
 ```
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(`ccw team log --team "${teamName}" --from "spec-analyst" --to "coordinator" --type "research_ready" --summary "研究完成: 5个探索维度" --ref "${sessionFolder}/discovery-context.json" --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from spec-analyst --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]`
+
 ## Execution Process
 
 ```
diff --git a/.claude/commands/team/spec-coordinate.md b/.claude/commands/team/spec-coordinate.md
@@ -31,6 +31,26 @@ mcp__ccw-tools__team_msg({ operation: "status", team: teamName })
 **日志位置**: `.workflow/.team-msg/{team-name}/messages.jsonl`
 **消息类型**: `research_ready | research_progress | draft_ready | draft_revision | quality_result | discussion_ready | discussion_blocked | fix_required | error | shutdown`
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+// log
+Bash(`ccw team log --team "${teamName}" --from "coordinator" --to "spec-analyst" --type "plan_approved" --summary "研究结果已确认" --json`)
+// list
+Bash(`ccw team list --team "${teamName}" --last 10 --json`)
+// list (带过滤)
+Bash(`ccw team list --team "${teamName}" --from "spec-discuss" --last 5 --json`)
+// status
+Bash(`ccw team status --team "${teamName}" --json`)
+// read
+Bash(`ccw team read --team "${teamName}" --id "MSG-003" --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team <operation> --team <team> [--from/--to/--type/--summary/--ref/--data/--id/--last] [--json]`
+
 ## Pipeline
 
 ```
diff --git a/.claude/commands/team/spec-discuss.md b/.claude/commands/team/spec-discuss.md
@@ -56,6 +56,20 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-discuss
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-discuss", to: "coordinator", type: "error", summary: "DISCUSS-001: 找不到 discovery-context.json" })
 ```
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(`ccw team log --team "${teamName}" --from "spec-discuss" --to "coordinator" --type "discussion_ready" --summary "DISCUSS-002: 共识达成, 3个改进建议" --ref "${sessionFolder}/discussions/discuss-002-brief.md" --json`)
+
+// 带 data 参数（讨论阻塞时）
+Bash(`ccw team log --team "${teamName}" --from "spec-discuss" --to "coordinator" --type "discussion_blocked" --summary "技术选型分歧" --data '{"reason":"微服务 vs 单体","options":[{"label":"微服务"},{"label":"单体"}]}' --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from spec-discuss --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]`
+
 ## 讨论维度模型
 
 每个讨论轮次从4个视角进行结构化分析：
diff --git a/.claude/commands/team/spec-reviewer.md b/.claude/commands/team/spec-reviewer.md
@@ -55,6 +55,17 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-reviewe
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-reviewer", to: "coordinator", type: "fix_required", summary: "质量 FAIL: 55分, 缺少架构 ADR + PRD 验收标准不可测", data: { gate: "FAIL", score: 55, issues: ["missing ADRs", "untestable AC"] } })
 ```
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(`ccw team log --team "${teamName}" --from "spec-reviewer" --to "coordinator" --type "quality_result" --summary "质量检查 PASS: 85分" --data '{"gate":"PASS","score":85}' --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from spec-reviewer --to coordinator --type <type> --summary "<text>" [--data '<json>'] [--json]`
+
 ## Execution Process
 
 ```
diff --git a/.claude/commands/team/spec-writer.md b/.claude/commands/team/spec-writer.md
@@ -55,6 +55,17 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-writer"
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "spec-writer", to: "coordinator", type: "error", summary: "缺少 discovery-context.json, 无法生成 Product Brief" })
 ```
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(`ccw team log --team "${teamName}" --from "spec-writer" --to "coordinator" --type "draft_ready" --summary "Product Brief 完成: 8个章节" --ref "${sessionFolder}/product-brief.md" --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from spec-writer --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]`
+
 ## Execution Process
 
 ```
diff --git a/.claude/commands/team/test.md b/.claude/commands/team/test.md
@@ -59,6 +59,17 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "tester", to:
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "tester", to: "coordinator", type: "error", summary: "jest命令未找到, 请确认测试框架已安装" })
 ```
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+```javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(`ccw team log --team "${teamName}" --from "tester" --to "coordinator" --type "test_result" --summary "TEST-001通过: 98% pass rate" --data '{"passRate":98,"iterations":3}' --json`)
+```
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from tester --to coordinator --type <type> --summary "<text>" [--data '<json>'] [--json]`
+
 ## Execution Process
 
 ```
diff --git a/.claude/skills/team-command-designer/phases/03-command-generation.md b/.claude/skills/team-command-designer/phases/03-command-generation.md
@@ -68,7 +68,18 @@ ${config.message_types.filter(mt => mt.type !== 'error').map(mt =>
   `// ${mt.trigger}
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "${config.role_name}", to: "coordinator", type: "${mt.type}", summary: "${mt.trigger}" })`
 ).join('\n\n')}
-\`\`\``
+\`\`\`
+
+### CLI 回退
+
+当 \`mcp__ccw-tools__team_msg\` MCP 不可用时，使用 \`ccw team\` CLI 作为等效回退：
+
+\\\`\\\`\\\`javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(\\\`ccw team log --team "\${teamName}" --from "${config.role_name}" --to "coordinator" --type "${config.message_types[0]?.type || 'result'}" --summary "<摘要>" --json\\\`)
+\\\`\\\`\\\`
+
+**参数映射**: \`team_msg(params)\` → \`ccw team log --team <team> --from ${config.role_name} --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]\``
 ```
 
 ### Step 4: Generate Phase Implementations
diff --git a/.claude/skills/team-command-designer/phases/05-validation.md b/.claude/skills/team-command-designer/phases/05-validation.md
@@ -42,6 +42,8 @@ const requiredSections = [
   { name: "TaskGet Usage", pattern: /TaskGet/ },
   { name: "TaskUpdate Usage", pattern: /TaskUpdate/ },
   { name: "SendMessage to Coordinator", pattern: /SendMessage.*coordinator/i },
+  { name: "CLI Fallback Section", pattern: /CLI 回退|CLI Fallback/ },
+  { name: "ccw team CLI Example", pattern: /ccw team log/ },
   { name: "Error Handling Table", pattern: /## Error Handling/ },
   { name: "Implementation Section", pattern: /## Implementation/ }
 ]
@@ -110,6 +112,14 @@ const patternChecks = [
       return command.includes('idle') || command.includes('return')
     },
     severity: "medium"
+  },
+  {
+    name: "CLI Fallback Present",
+    check: () => {
+      return (command.includes('CLI 回退') || command.includes('CLI Fallback')) &&
+             command.includes('ccw team log')
+    },
+    severity: "high"
   }
 ]
 
diff --git a/.claude/skills/team-command-designer/specs/quality-standards.md b/.claude/skills/team-command-designer/specs/quality-standards.md
@@ -50,6 +50,7 @@ Quality assessment criteria for generated team command .md files.
 
 **Infrastructure Pattern Checklist:**
 - [ ] Pattern 1: Message bus - team_msg before every SendMessage
+- [ ] Pattern 1b: CLI fallback - `ccw team` CLI fallback section with parameter mapping
 - [ ] Pattern 2: YAML front matter - all fields present, group: team
 - [ ] Pattern 3: Task lifecycle - TaskList/Get/Update flow
 - [ ] Pattern 4: Five-phase structure - all 5 phases present
@@ -114,6 +115,7 @@ Quality assessment criteria for generated team command .md files.
 - Missing error handling table
 - Incomplete Phase implementation (skeleton only)
 - Missing team_msg before some SendMessage calls
+- Missing CLI fallback section (`### CLI 回退` with `ccw team` examples)
 - No complexity-adaptive routing when role is complex
 
 ### Info (Nice to Have)
diff --git a/.claude/skills/team-command-designer/specs/team-design-patterns.md b/.claude/skills/team-command-designer/specs/team-design-patterns.md
@@ -105,22 +105,47 @@ When designing a new role, define role-specific message types following the conv
 - `{action}_complete` - Work phase finished
 - `{action}_progress` - Intermediate progress update
 
+### CLI Fallback
+
+When `mcp__ccw-tools__team_msg` MCP is unavailable, use `ccw team` CLI as equivalent fallback:
+
+```javascript
+// Fallback: Replace MCP call with Bash CLI (parameters map 1:1)
+Bash(`ccw team log --team "${teamName}" --from "<role>" --to "coordinator" --type "<type>" --summary "<summary>" [--ref <path>] [--data '<json>'] --json`)
+```
+
+**Parameter mapping**: `team_msg(params)` → `ccw team <operation> --team <team> [--from/--to/--type/--summary/--ref/--data/--id/--last] [--json]`
+
+**Coordinator** uses all 4 operations: `log`, `list`, `status`, `read`
+**Teammates** primarily use: `log`
+
 ### Message Bus Section Template
 
 ```markdown
-## Message Bus
+## 消息总线
 
-Every SendMessage **before**, must call `mcp__ccw-tools__team_msg` to log:
+每次 SendMessage **前**，必须调用 `mcp__ccw-tools__team_msg` 记录消息：
 
 \`\`\`javascript
 mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "<role>", to: "coordinator", type: "<type>", summary: "<summary>" })
 \`\`\`
 
-### Supported Message Types
+### 支持的 Message Types
+
+| Type | 方向 | 触发时机 | 说明 |
+|------|------|----------|------|
+| `<type>` | <role> → coordinator | <when> | <what> |
+
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+\`\`\`javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(\`ccw team log --team "${teamName}" --from "<role>" --to "coordinator" --type "<type>" --summary "<summary>" --json\`)
+\`\`\`
 
-| Type | Direction | Trigger | Description |
-|------|-----------|---------|-------------|
-| `<type>` | <role> -> coordinator | <when> | <what> |
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from <role> --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]`
 ```
 
 ---
diff --git a/.claude/skills/team-command-designer/templates/command-template.md b/.claude/skills/team-command-designer/templates/command-template.md
@@ -71,6 +71,17 @@ mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "{{../role_na
 {{/each}}
 \`\`\`
 
+### CLI 回退
+
+当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：
+
+\`\`\`javascript
+// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
+Bash(\`ccw team log --team "${teamName}" --from "{{role_name}}" --to "coordinator" --type "{{primary_message_type}}" --summary "<摘要>" --json\`)
+\`\`\`
+
+**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from {{role_name}} --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]`
+
 ## Execution Process
 
 \`\`\`
diff --git a/codex-lens/src/codexlens/config.py b/codex-lens/src/codexlens/config.py
@@ -146,6 +146,11 @@ class Config:
     staged_coarse_k: int = 200  # Number of coarse candidates from Stage 1 binary search
     staged_lsp_depth: int = 2  # LSP relationship expansion depth in Stage 2
     staged_stage2_mode: str = "precomputed"  # "precomputed" (graph_neighbors) | "realtime" (LSP)
+
+    # Static graph configuration (write relationships to global index during build)
+    static_graph_enabled: bool = False
+    static_graph_relationship_types: List[str] = field(default_factory=lambda: ["imports", "inherits"])
+
     staged_realtime_lsp_timeout_s: float = 30.0  # Max time budget for realtime LSP expansion
     staged_realtime_lsp_depth: int = 1  # BFS depth for realtime LSP expansion
     staged_realtime_lsp_max_nodes: int = 50  # Node cap for realtime graph expansion
diff --git a/codex-lens/src/codexlens/search/__init__.py b/codex-lens/src/codexlens/search/__init__.py
@@ -5,6 +5,7 @@
     ChainSearchResult,
     quick_search,
 )
+from .global_graph_expander import GlobalGraphExpander
 
 # Clustering availability flag (lazy import pattern)
 CLUSTERING_AVAILABLE = False
@@ -46,6 +47,7 @@ def check_clustering_available() -> tuple[bool, str | None]:
     "SearchStats",
     "ChainSearchResult",
     "quick_search",
+    "GlobalGraphExpander",
     # Clustering
     "CLUSTERING_AVAILABLE",
     "check_clustering_available",
diff --git a/codex-lens/src/codexlens/search/global_graph_expander.py b/codex-lens/src/codexlens/search/global_graph_expander.py
diff --git a/codex-lens/src/codexlens/storage/index_tree.py b/codex-lens/src/codexlens/storage/index_tree.py
diff --git a/codex-lens/tests/test_global_graph_expander.py b/codex-lens/tests/test_global_graph_expander.py
