feat: Add explorer and synthesizer roles with commands for codebase exploration and synthesis

- Implemented `explorer` role for parallel codebase exploration using `cli-explore-agent`.
- Created `explore.md` command documentation detailing exploration strategy and execution steps.
- Established `synthesizer` role for integrating insights from explorations, analyses, and discussions.
- Developed `synthesize.md` command documentation outlining synthesis strategy and output format.
- Configured team settings in `team-config.json` to support new roles and pipeline modes.
- Added regression test for CodexLens bootstrap fallback to ensure robustness in error handling.
This commit is contained in:
catlog22
2026-02-18 18:40:12 +08:00
parent 32d2d534ab
commit 65762af254
14 changed files with 3465 additions and 0 deletions

View File

@@ -0,0 +1,194 @@
# Command: explore
> cli-explore-agent 并行代码库探索。根据话题和视角,通过 subagent 收集代码库上下文。
## When to Use
- Phase 3 of Explorer
- 需要收集代码库上下文供后续分析
- 每个 EXPLORE-* 任务触发一次
**Trigger conditions**:
- Explorer Phase 2 完成后
- 任务包含明确的 perspective 和 dimensions
## Strategy
### Delegation Mode
**Mode**: Subagentcli-explore-agent 执行实际探索)
### Decision Logic
```javascript
// 根据 perspective 确定探索策略
function buildExplorationStrategy(perspective, dimensions, topic) {
const strategies = {
'general': {
focus: 'Overall codebase structure and patterns',
searches: [topic, ...dimensions],
depth: 'broad'
},
'technical': {
focus: 'Implementation details, code patterns, technical feasibility',
searches: [`${topic} implementation`, `${topic} pattern`, `${topic} handler`],
depth: 'medium'
},
'architectural': {
focus: 'System design, module boundaries, component interactions',
searches: [`${topic} module`, `${topic} service`, `${topic} interface`],
depth: 'broad'
},
'business': {
focus: 'Business logic, domain models, value flows',
searches: [`${topic} model`, `${topic} domain`, `${topic} workflow`],
depth: 'medium'
},
'domain_expert': {
focus: 'Domain-specific patterns, standards compliance, best practices',
searches: [`${topic} standard`, `${topic} convention`, `${topic} best practice`],
depth: 'deep'
}
}
return strategies[perspective] || strategies['general']
}
```
## Execution Steps
### Step 1: Context Preparation
```javascript
const strategy = buildExplorationStrategy(perspective, dimensions, topic)
const exploreNum = task.subject.match(/EXPLORE-(\d+)/)?.[1] || '001'
const outputPath = `${sessionFolder}/explorations/exploration-${exploreNum}.json`
```
### Step 2: Execute Exploration
```javascript
Task({
subagent_type: "cli-explore-agent",
run_in_background: false,
description: `Explore codebase: ${topic} (${perspective})`,
prompt: `
## Analysis Context
Topic: ${topic}
Perspective: ${perspective}${strategy.focus}
Dimensions: ${dimensions.join(', ')}
Session: ${sessionFolder}
## MANDATORY FIRST STEPS
1. Run: ccw tool exec get_modules_by_depth '{}'
2. Execute searches: ${strategy.searches.map(s => `"${s}"`).join(', ')}
3. Read: .workflow/project-tech.json (if exists)
## Exploration Focus (${perspective} angle)
- **Depth**: ${strategy.depth}
- **Focus**: ${strategy.focus}
${dimensions.map(d => `- ${d}: Identify relevant code patterns, structures, and relationships`).join('\n')}
## Search Strategy
${strategy.searches.map((s, i) => `${i + 1}. Search for: "${s}" — find related files, functions, types`).join('\n')}
## Additional Exploration
- Identify entry points related to the topic
- Map dependencies between relevant modules
- Note any configuration or environment dependencies
- Look for test files that reveal expected behavior
## Output
Write findings to: ${outputPath}
Schema:
{
"perspective": "${perspective}",
"relevant_files": [
{"path": "string", "relevance": "high|medium|low", "summary": "what this file does"}
],
"patterns": ["pattern descriptions found in codebase"],
"key_findings": ["important discoveries"],
"module_map": {"module_name": ["related_files"]},
"questions_for_analysis": ["questions that need deeper analysis"],
"_metadata": {
"agent": "cli-explore-agent",
"perspective": "${perspective}",
"search_queries": ${JSON.stringify(strategy.searches)},
"timestamp": "ISO string"
}
}
`
})
```
### Step 3: Result Processing
```javascript
// 验证输出文件
let result = {}
try {
result = JSON.parse(Read(outputPath))
} catch {
// Fallback: ACE search
const aceResults = mcp__ace-tool__search_context({
project_root_path: ".",
query: `${topic} ${perspective}`
})
result = {
perspective,
relevant_files: [],
patterns: [],
key_findings: [`ACE fallback: ${aceResults?.summary || 'No results'}`],
questions_for_analysis: [`What is the ${perspective} perspective on ${topic}?`],
_metadata: {
agent: 'ace-fallback',
perspective,
timestamp: new Date().toISOString()
}
}
Write(outputPath, JSON.stringify(result, null, 2))
}
// 质量验证
const quality = {
has_files: (result.relevant_files?.length || 0) > 0,
has_findings: (result.key_findings?.length || 0) > 0,
has_patterns: (result.patterns?.length || 0) > 0
}
if (!quality.has_files && !quality.has_findings) {
// 补充搜索
const supplementary = mcp__ace-tool__search_context({
project_root_path: ".",
query: topic
})
// Merge supplementary results
}
```
## Output Format
```json
{
"perspective": "technical",
"relevant_files": [
{"path": "src/auth/handler.ts", "relevance": "high", "summary": "Authentication request handler"}
],
"patterns": ["Repository pattern used for data access", "Middleware chain for auth"],
"key_findings": ["JWT tokens stored in HTTP-only cookies", "Rate limiting at gateway level"],
"module_map": {"auth": ["src/auth/handler.ts", "src/auth/middleware.ts"]},
"questions_for_analysis": ["Is the token refresh mechanism secure?"],
"_metadata": {"agent": "cli-explore-agent", "perspective": "technical", "timestamp": "..."}
}
```
## Error Handling
| Scenario | Resolution |
|----------|------------|
| cli-explore-agent unavailable | Fall back to ACE search + Grep |
| Agent produces no output file | Create minimal result with ACE fallback |
| Agent timeout | Use partial results if available |
| Invalid JSON output | Attempt repair, fall back to raw text extraction |
| Session folder missing | Create directory, continue |