mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
Add tests for CLI command generation and model alias resolution
- Implement `test-cli-command-gen.js` to verify the logic of `buildCliCommand` function. - Create `test-e2e-model-alias.js` for end-to-end testing of model alias resolution in `ccw cli`. - Add `test-model-alias.js` to test model alias resolution for different models. - Introduce `test-model-alias.txt` for prompt testing with model alias. - Develop `test-update-claude-command.js` to test command generation for `update_module_claude`. - Create a test file in `test-update-claude/src` for future tests.
This commit is contained in:
catlog22
@@ -1,468 +0,0 @@
|
||||
# Agent Roles Definition
|
||||
|
||||
Agent角色定义和职责范围。
|
||||
|
||||
---
|
||||
|
||||
## Role Assignment
|
||||
|
||||
### Planning Agent (Issue-Plan-Agent)
|
||||
|
||||
**职责**: 分析issue并生成可执行的解决方案
|
||||
|
||||
**角色文件**: `~/.codex/agents/issue-plan-agent.md`
|
||||
**提示词**: `prompts/planning-agent.md`
|
||||
|
||||
#### Capabilities
|
||||
|
||||
**允许**:
|
||||
- 读取代码、文档、配置
|
||||
- 探索项目结构和依赖关系
|
||||
- 分析问题和设计解决方案
|
||||
- 分解任务为可执行步骤
|
||||
- 定义验收条件
|
||||
|
||||
**禁止**:
|
||||
- 修改代码
|
||||
- 执行代码
|
||||
- 推送到远程
|
||||
- 删除文件或分支
|
||||
|
||||
#### Input Format
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "plan_issue",
|
||||
"issue_id": "ISS-001",
|
||||
"title": "Fix authentication timeout",
|
||||
"description": "User sessions timeout too quickly",
|
||||
"project_context": {
|
||||
"tech_stack": "Node.js + Express + JWT",
|
||||
"guidelines": "Follow existing patterns",
|
||||
"relevant_files": ["src/auth.ts", "src/middleware/auth.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Format
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "completed|failed",
|
||||
"solution_id": "SOL-ISS-001-1",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "T1",
|
||||
"title": "Update JWT configuration",
|
||||
"action": "Modify",
|
||||
"scope": "src/config/auth.ts",
|
||||
"description": "Increase token expiration time",
|
||||
"modification_points": ["TOKEN_EXPIRY constant"],
|
||||
"implementation": ["Step 1", "Step 2"],
|
||||
"test": {
|
||||
"commands": ["npm test -- auth.test.ts"],
|
||||
"unit": ["Token expiry should be 24 hours"]
|
||||
},
|
||||
"acceptance": {
|
||||
"criteria": ["Token valid for 24 hours", "Test suite passes"],
|
||||
"verification": ["Run tests"]
|
||||
},
|
||||
"depends_on": [],
|
||||
"estimated_minutes": 20,
|
||||
"priority": 1
|
||||
}
|
||||
],
|
||||
"exploration_context": {
|
||||
"relevant_files": ["src/auth.ts", "src/middleware/auth.ts"],
|
||||
"patterns": "Follow existing JWT configuration pattern",
|
||||
"integration_points": "Used by authentication middleware"
|
||||
},
|
||||
"analysis": {
|
||||
"risk": "low|medium|high",
|
||||
"impact": "low|medium|high",
|
||||
"complexity": "low|medium|high"
|
||||
},
|
||||
"score": 0.95,
|
||||
"validation": {
|
||||
"schema_valid": true,
|
||||
"criteria_quantified": true,
|
||||
"no_circular_deps": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Execution Agent (Issue-Execute-Agent)
|
||||
|
||||
**职责**: 执行规划的解决方案，实现所有任务
|
||||
|
||||
**角色文件**: `~/.codex/agents/issue-execute-agent.md`
|
||||
**提示词**: `prompts/execution-agent.md`
|
||||
|
||||
#### Capabilities
|
||||
|
||||
**允许**:
|
||||
- 读取代码和配置
|
||||
- 修改代码
|
||||
- 运行测试
|
||||
- 提交代码
|
||||
- 验证acceptance criteria
|
||||
- 创建snapshots用于恢复
|
||||
|
||||
**禁止**:
|
||||
- 推送到远程分支
|
||||
- 创建PR（除非明确授权）
|
||||
- 删除分支
|
||||
- 强制覆盖主分支
|
||||
|
||||
#### Input Format
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "execute_solution",
|
||||
"issue_id": "ISS-001",
|
||||
"solution_id": "SOL-ISS-001-1",
|
||||
"solution": {
|
||||
"id": "SOL-ISS-001-1",
|
||||
"tasks": [ /* task objects from planning */ ],
|
||||
"exploration_context": {
|
||||
"relevant_files": ["src/auth.ts"],
|
||||
"patterns": "Follow existing pattern",
|
||||
"integration_points": "Used by auth middleware"
|
||||
}
|
||||
},
|
||||
"project_root": "/path/to/project"
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Format
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "completed|failed",
|
||||
"execution_result_id": "EXR-ISS-001-1",
|
||||
"issue_id": "ISS-001",
|
||||
"solution_id": "SOL-ISS-001-1",
|
||||
"executed_tasks": [
|
||||
{
|
||||
"task_id": "T1",
|
||||
"title": "Update JWT configuration",
|
||||
"status": "completed",
|
||||
"files_modified": ["src/config/auth.ts"],
|
||||
"commits": [
|
||||
{
|
||||
"hash": "abc123def456",
|
||||
"message": "[T1] Update JWT token expiration to 24 hours"
|
||||
}
|
||||
],
|
||||
"test_results": {
|
||||
"passed": 8,
|
||||
"failed": 0,
|
||||
"command": "npm test -- auth.test.ts",
|
||||
"output": "All tests passed"
|
||||
},
|
||||
"acceptance_met": true,
|
||||
"execution_time_minutes": 15,
|
||||
"errors": []
|
||||
}
|
||||
],
|
||||
"overall_stats": {
|
||||
"total_tasks": 1,
|
||||
"completed": 1,
|
||||
"failed": 0,
|
||||
"total_files_modified": 1,
|
||||
"total_commits": 1,
|
||||
"total_time_minutes": 15
|
||||
},
|
||||
"final_commit": {
|
||||
"hash": "xyz789abc",
|
||||
"message": "Resolve ISS-001: Fix authentication timeout"
|
||||
},
|
||||
"verification": {
|
||||
"all_tests_passed": true,
|
||||
"all_acceptance_met": true,
|
||||
"no_regressions": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dual-Agent Strategy
|
||||
|
||||
### 为什么使用双Agent模式
|
||||
|
||||
1. **关注点分离** - 规划和执行各自专注一个任务
|
||||
2. **并行优化** - 虽然执行仍是串行，但规划可独立优化
|
||||
3. **上下文最小化** - 仅传递solution ID，避免上下文膨胀
|
||||
4. **错误隔离** - 规划失败不影响执行，反之亦然
|
||||
5. **可维护性** - 每个agent专注单一职责
|
||||
|
||||
### 工作流程
|
||||
|
||||
```
|
||||
┌────────────────────────────────────┐
|
||||
│ Planning Agent │
|
||||
│ • Analyze issue │
|
||||
│ • Explore codebase │
|
||||
│ • Design solution │
|
||||
│ • Generate tasks │
|
||||
│ • Validate schema │
|
||||
│ → Output: SOL-ISS-001-1 JSON │
|
||||
└────────────┬─────────────────────┘
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ Save to │
|
||||
│ planning- │
|
||||
│ results.json │
|
||||
│ + Bind │
|
||||
└──────┬───────┘
|
||||
↓
|
||||
┌────────────────────────────────────┐
|
||||
│ Execution Agent │
|
||||
│ • Load SOL-ISS-001-1 │
|
||||
│ • Implement T1, T2, T3... │
|
||||
│ • Run tests per task │
|
||||
│ • Commit changes │
|
||||
│ • Verify acceptance │
|
||||
│ → Output: EXR-ISS-001-1 JSON │
|
||||
└────────────┬─────────────────────┘
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ Save to │
|
||||
│ execution- │
|
||||
│ results.json │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Context Minimization
|
||||
|
||||
### 信息传递原则
|
||||
|
||||
**目标**: 最小化上下文，减少token浪费
|
||||
|
||||
#### Planning Phase - 传递内容
|
||||
|
||||
- Issue ID 和 Title
|
||||
- Issue Description
|
||||
- Project tech stack (`project-tech.json`)
|
||||
- Project guidelines (`project-guidelines.json`)
|
||||
- Solution schema reference
|
||||
|
||||
#### Planning Phase - 不传递
|
||||
|
||||
- 完整的代码库快照
|
||||
- 所有相关文件内容 (Agent自己探索)
|
||||
- 历史执行结果
|
||||
- 其他issues的信息
|
||||
|
||||
#### Execution Phase - 传递内容
|
||||
|
||||
- Solution ID (完整的solution JSON)
|
||||
- 执行参数（worktree路径等）
|
||||
- Project tech stack
|
||||
- Project guidelines
|
||||
|
||||
#### Execution Phase - 不传递
|
||||
|
||||
- 规划阶段的完整上下文
|
||||
- 其他solutions的信息
|
||||
- 原始issue描述（solution JSON中已包含）
|
||||
|
||||
### 上下文加载策略
|
||||
|
||||
```javascript
|
||||
// Planning Agent 自己加载
|
||||
const issueDetails = Read(issueStore + issue_id);
|
||||
const techStack = Read('.workflow/project-tech.json');
|
||||
const guidelines = Read('.workflow/project-guidelines.json');
|
||||
const schema = Read('~/.claude/workflows/cli-templates/schemas/solution-schema.json');
|
||||
|
||||
// Execution Agent 自己加载
|
||||
const solution = planningResults.find(r => r.solution_id === solutionId);
|
||||
const techStack = Read('.workflow/project-tech.json');
|
||||
const guidelines = Read('.workflow/project-guidelines.json');
|
||||
```
|
||||
|
||||
**优势**:
|
||||
- 减少重复传递
|
||||
- 使用相同的源文件版本
|
||||
- Agents可以自我刷新上下文
|
||||
- 易于更新project guidelines或tech stack
|
||||
|
||||
---
|
||||
|
||||
## 错误处理与重试
|
||||
|
||||
### Planning 错误
|
||||
|
||||
| 错误 | 原因 | 重试策略 | 恢复 |
|
||||
|------|------|--------|------|
|
||||
| Subagent超时 | 分析复杂或系统慢 | 增加timeout，重试1次 | 返回用户，标记失败 |
|
||||
| 无效solution | 生成不符合schema | 验证schema，返回错误 | 返回用户进行修正 |
|
||||
| 依赖循环 | DAG错误 | 检测循环，返回错误 | 用户手动修正 |
|
||||
| 权限错误 | 无法读取文件 | 检查路径和权限 | 返回具体错误 |
|
||||
| 格式错误 | JSON无效 | 验证格式，返回错误 | 用户修正格式 |
|
||||
|
||||
### Execution 错误
|
||||
|
||||
| 错误 | 原因 | 重试策略 | 恢复 |
|
||||
|------|------|--------|------|
|
||||
| Task失败 | 代码实现问题 | 检查错误，不重试 | 记录错误，标记失败 |
|
||||
| 测试失败 | 测试用例不符 | 不提交，标记失败 | 返回测试输出 |
|
||||
| 提交失败 | 冲突或权限 | 创建snapshot便于恢复 | 让用户决定 |
|
||||
| Subagent超时 | 任务太复杂 | 增加timeout | 记录超时，标记失败 |
|
||||
| 文件冲突 | 并发修改 | 创建snapshot | 让用户合并 |
|
||||
|
||||
---
|
||||
|
||||
## 交互指南
|
||||
|
||||
### 向Planning Agent的问题
|
||||
|
||||
```
|
||||
"这个issue描述了什么问题？"
|
||||
→ 返回：问题分析 + 根本原因
|
||||
|
||||
"解决这个问题需要修改哪些文件？"
|
||||
→ 返回：文件列表 + 修改点
|
||||
|
||||
"如何验证解决方案是否有效？"
|
||||
→ 返回：验收条件 + 验证步骤
|
||||
|
||||
"预计需要多少时间？"
|
||||
→ 返回：每个任务的估计时间 + 总计
|
||||
|
||||
"有哪些风险？"
|
||||
→ 返回：风险分析 + 影响评估
|
||||
```
|
||||
|
||||
### 向Execution Agent的问题
|
||||
|
||||
```
|
||||
"这个task有哪些实现步骤？"
|
||||
→ 返回：逐步指南 + 代码示例
|
||||
|
||||
"所有测试都通过了吗？"
|
||||
→ 返回：测试结果 + 失败原因（如有）
|
||||
|
||||
"acceptance criteria都满足了吗？"
|
||||
→ 返回：验证结果 + 不符合项（如有）
|
||||
|
||||
"有哪些文件被修改了？"
|
||||
→ 返回：文件列表 + 变更摘要
|
||||
|
||||
"代码有没有回归问题？"
|
||||
→ 返回：回归测试结果
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Role文件位置
|
||||
|
||||
```
|
||||
~/.codex/agents/
|
||||
├── issue-plan-agent.md # 规划角色定义
|
||||
├── issue-execute-agent.md # 执行角色定义
|
||||
└── ...
|
||||
|
||||
.codex/skills/codex-issue-plan-execute/
|
||||
├── prompts/
|
||||
│ ├── planning-agent.md # 规划提示词
|
||||
│ └── execution-agent.md # 执行提示词
|
||||
└── specs/
|
||||
├── agent-roles.md # 本文件
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 如果角色文件不存在
|
||||
|
||||
Orchestrator会使用fallback策略：
|
||||
- `universal-executor` 作为备用规划角色
|
||||
- `code-developer` 作为备用执行角色
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 为Planning Agent设计提示词
|
||||
|
||||
✓ 从issue描述提取关键信息
|
||||
✓ 探索相关代码和类似实现
|
||||
✓ 分析根本原因和解决方向
|
||||
✓ 设计最小化解决方案
|
||||
✓ 分解为2-7个可执行任务
|
||||
✓ 为每个task定义明确的acceptance criteria
|
||||
✓ 验证任务依赖无循环
|
||||
✓ 估计总时间≤2小时
|
||||
|
||||
### 为Execution Agent设计提示词
|
||||
|
||||
✓ 加载solution和所有task定义
|
||||
✓ 按依赖顺序执行tasks
|
||||
✓ 为每个task：implement → test → verify
|
||||
✓ 确保所有acceptance criteria通过
|
||||
✓ 运行完整的测试套件
|
||||
✓ 检查代码质量和风格一致性
|
||||
✓ 创建描述性的commit消息
|
||||
✓ 生成完整的execution result JSON
|
||||
|
||||
---
|
||||
|
||||
## Communication Protocol
|
||||
|
||||
### Planning Agent Lifecycle
|
||||
|
||||
```
|
||||
1. Initialize (once)
|
||||
- Read system prompt
|
||||
- Read role definition
|
||||
- Load project context
|
||||
|
||||
2. Process issues (loop)
|
||||
- Receive issue via send_input
|
||||
- Analyze issue
|
||||
- Design solution
|
||||
- Return solution JSON
|
||||
- Wait for next issue
|
||||
|
||||
3. Shutdown
|
||||
- Orchestrator closes when done
|
||||
```
|
||||
|
||||
### Execution Agent Lifecycle
|
||||
|
||||
```
|
||||
1. Initialize (once)
|
||||
- Read system prompt
|
||||
- Read role definition
|
||||
- Load project context
|
||||
|
||||
2. Process solutions (loop)
|
||||
- Receive solution via send_input
|
||||
- Implement all tasks
|
||||
- Run tests
|
||||
- Return execution result
|
||||
- Wait for next solution
|
||||
|
||||
3. Shutdown
|
||||
- Orchestrator closes when done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 2.0 | 2025-01-29 | Consolidated from subagent-roles.md, updated format |
|
||||
| 1.0 | 2024-12-29 | Initial agent roles definition |
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 2.0
|
||||
**Last Updated**: 2025-01-29
|
||||
**Maintained By**: Codex Issue Plan-Execute Team
|
||||
Reference in New Issue
Block a user