名称: issue-resolve 描述: 统一问题解决管道，带有源选择功能。通过 AI 探索计划问题，从工件转换，从头脑风暴会话导入，形成执行队列，或将解决方案导出到任务 JSON。触发命令包括 “issue:plan”、“issue:queue”、“issue:convert-to-plan”、“issue:from-brainstorm”、“export-to-tasks”、“resolve issue”、“plan issue”、“queue issues”、“convert plan to issue”。 允许的工具: spawn_agent、wait、send_input、close_agent、AskUserQuestion、Read、Write、Edit、Bash、Glob、Grep
问题解决（Codex 版本）
统一问题解决管道，协调从多个源创建解决方案并形成执行队列。
架构概述
┌─────────────────────────────────────────────────────────────────┐
│ 问题解决协调器（SKILL.md） │
│ → 源选择 → 路由到阶段 → 执行 → 总结 │
└───────────────┬─────────────────────────────────────────────────┘
│
├─ ASK_USER: 选择问题源
│
┌───────────┼───────────┬───────────┬───────────┐
↓ ↓ ↓ ↓ │
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ 阶段 1 │ │ 阶段 2 │ │ 阶段 3 │ │ 阶段 4 │ │
│ 探索 │ │ 转换 │ │ 从头脑 │ │ 形成 │ │
│ 与计划 │ │ 工件 │ │ 风暴 │ │ 队列 │ │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ │
↓ ↓ ↓ ↓ │
解决方案 解决方案 问题+解决方案 执行队列 │
（绑定） （绑定） （绑定） （有序） │
│ │ │ │
└─────┬─────┘───────────┘ │
↓ （可选 --export-tasks） │
.task/TASK-*.json │
│
┌────────────────────────────────┘
↓
/issue:execute
关键设计原则
- 源驱动路由: ASK_USER 选择工作流，然后加载单个阶段
- 渐进式阶段加载: 仅读取所选阶段文档
- CLI 优先数据访问: 所有问题/解决方案的 CRUD 通过
ccw issueCLI 命令 - 自动模式支持:
-y标志跳过源选择（默认为探索与计划）
子代理 API 参考
spawn_agent
创建新子代理并分配任务。
const agentId = spawn_agent({
message: `
## 任务分配
### 强制第一步（代理执行）
1. **读取角色定义**: ~/.codex/agents/{agent-type}.md（必须先读）
2. 读取: {projectRoot}/.workflow/project-tech.json
3. 读取: {projectRoot}/.workflow/project-guidelines.json
## 任务上下文
${taskContext}
## 交付物
${deliverables}
`
})
wait
从子代理获取结果（唯一检索结果的方式）。
const result = wait({
ids: [agentId],
timeout_ms: 600000 // 10 分钟
})
if (result.timed_out) {
// 处理超时 - 可以继续等待或发送输入提示完成
}
send_input
与活动子代理继续交互（用于澄清或跟进）。
send_input({
id: agentId,
message: `
## 澄清答案
${answers}
## 下一步
继续更新分析。
`
})
close_agent
清理子代理资源（不可逆）。
close_agent({ id: agentId })
自动模式
当 --yes 或 -y 时：跳过源选择，使用探索与计划处理问题 ID，或根据路径自动检测源类型。
用法
codex -p "@.codex/prompts/issue-resolve.md <任务描述或问题 ID>"
codex -p "@.codex/prompts/issue-resolve.md [FLAGS] \"<input>\""
# 标志
-y, --yes 跳过所有确认（自动模式）
--source <类型> 预选源: plan|convert|brainstorm|queue
--batch-size <n> 每批代理的最大问题数（计划模式，默认: 3）
--issue <id> 绑定到现有问题（转换模式）
--supplement 向现有解决方案添加任务（转换模式）
--queues <n> 并行队列数（队列模式，默认: 1）
--export-tasks 将解决方案任务导出到 .task/TASK-*.json（task-schema.json 格式）
# 示例
codex -p "@.codex/prompts/issue-resolve.md GH-123,GH-124" # 探索与计划问题
codex -p "@.codex/prompts/issue-resolve.md --source plan --all-pending" # 计划所有待处理问题
codex -p "@.codex/prompts/issue-resolve.md --source convert \".workflow/.lite-plan/my-plan\"" # 转换工件
codex -p "@.codex/prompts/issue-resolve.md --source brainstorm SESSION=\"BS-rate-limiting\"" # 从头脑风暴
codex -p "@.codex/prompts/issue-resolve.md --source queue" # 形成执行队列
codex -p "@.codex/prompts/issue-resolve.md -y GH-123" # 自动模式，计划单个问题
执行流程
输入解析:
└─ 解析标志（--source、-y、--issue 等）和位置参数
源选择:
├─ 提供 --source 标志 → 直接路由
├─ 从输入自动检测:
│ ├─ 问题 ID（GH-xxx、ISS-xxx） → 探索与计划
│ ├─ SESSION="..." → 从头脑风暴
│ ├─ 文件/文件夹路径 → 从工件转换
│ └─ 无输入或 --all-pending → 探索与计划（所有待处理）
└─ 否则 → ASK_USER 选择源
阶段执行（加载一个阶段）:
├─ 阶段 1: 探索与计划 → phases/01-issue-plan.md
├─ 阶段 2: 转换工件 → phases/02-convert-to-plan.md
├─ 阶段 3: 从头脑风暴 → phases/03-from-brainstorm.md
└─ 阶段 4: 形成队列 → phases/04-issue-queue.md
阶段后:
├─ 导出到任务 JSON（可选，带 --export-tasks 标志）
│ ├─ 对每个 solution.tasks[] → 写入 .task/TASK-{T-id}.json
│ └─ 从导出的任务生成 plan.json（plan-overview-base-schema）
└─ 总结 + 下一步建议
阶段参考文档
| 阶段 | 文档 | 加载时机 | 目的 |
|---|---|---|---|
| 阶段 1 | phases/01-issue-plan.md | 源 = 探索与计划 | 通过问题计划代理批量计划问题 |
| 阶段 2 | phases/02-convert-to-plan.md | 源 = 转换工件 | 将轻量计划/会话/标记转换为解决方案 |
| 阶段 3 | phases/03-from-brainstorm.md | 源 = 从头脑风暴 | 将头脑风暴想法转换为问题 + 解决方案 |
| 阶段 4 | phases/04-issue-queue.md | 源 = 形成队列 | 将绑定解决方案排序为执行队列 |
核心规则
- 先选择源: 在加载任何阶段前始终确定源
- 单阶段加载: 仅读取所选阶段文档，绝不加载所有阶段
- CLI 数据访问: 使用
ccw issueCLI 进行所有问题/解决方案操作，绝不直接读取文件 - 内容保留: 每个阶段包含来自原始命令的完整执行逻辑
- 自动检测输入: 智能输入解析减少对显式 --source 标志的需求
- 不要停止: 连续多阶段工作流。完成每个阶段后立即进行下一步
- 显式生命周期: 等待完成后始终 close_agent 以释放资源
输入处理
自动检测逻辑
function detectSource(input, flags) {
// 1. 显式 --source 标志
if (flags.source) return flags.source;
// 2. 从输入内容自动检测
const trimmed = input.trim();
// 问题 ID 模式（GH-xxx、ISS-xxx，逗号分隔）
if (trimmed.match(/^[A-Z]+-\d+/i) || trimmed.includes(',')) {
return 'plan';
}
// --all-pending 或空输入 → 计划所有待处理
if (flags.allPending || trimmed === '') {
return 'plan';
}
// SESSION="..." 模式 → 头脑风暴
if (trimmed.includes('SESSION=')) {
return 'brainstorm';
}
// 文件/文件夹路径 → 转换
if (trimmed.match(/\.(md|json)$/) || trimmed.includes('.workflow/')) {
return 'convert';
}
// 无法自动检测 → 询问用户
return null;
}
源选择（ASK_USER）
// 当无法自动检测源时
const answer = ASK_USER([{
id: "source",
type: "select",
prompt: "您希望如何创建/管理问题解决方案？",
options: [
{
label: "探索与计划（推荐）",
description: "AI 探索代码库并为问题生成解决方案"
},
{
label: "从工件转换",
description: "将现有轻量计划、工作流会话或标记转换为解决方案"
},
{
label: "从头脑风暴",
description: "将头脑风暴会话想法转换为问题及解决方案"
},
{
label: "形成执行队列",
description: "将绑定解决方案排序为执行队列以供 /issue:execute"
}
]
}]); // 阻塞（等待用户响应）
// 根据选择路由
const sourceMap = {
"探索与计划": "plan",
"从工件转换": "convert",
"从头脑风暴": "brainstorm",
"形成执行队列": "queue"
};
数据流
用户输入（问题 ID / 工件路径 / 会话 ID / 标志）
↓
[解析标志 + 自动检测源]
↓
[源选择] ← ASK_USER（如果需要）
↓
[读取所选阶段文档]
↓
[执行阶段逻辑]
↓
[总结 + 下一步]
├─ 计划/转换/头脑风暴后 → 建议 /issue:queue 或 /issue:execute
└─ 队列后 → 建议 /issue:execute
（可选）导出到任务 JSON（当设置 --export-tasks 标志时）:
├─ 对每个 solution.tasks[] 条目:
│ ├─ solution.task.id → id（前缀为 TASK-{T-id}）
│ ├─ solution.task.title → title
│ ├─ solution.task.description → description
│ ├─ solution.task.action → action
│ ├─ solution.task.scope → scope
│ ├─ solution.task.modification_points[] → files[]
│ │ ├─ mp.file → files[].path
│ │ ├─ mp.target → files[].target
│ │ └─ mp.change → files[].changes[]
│ ├─ solution.task.acceptance → convergence
│ │ ├─ acceptance.criteria[] → convergence.criteria[]
│ │ └─ acceptance.verification[]→ convergence.verification（合并）
│ ├─ solution.task.implementation → implementation[]
│ ├─ solution.task.test → test
│ ├─ solution.task.depends_on → depends_on
│ ├─ solution.task.commit → commit
│ └─ solution.task.priority → priority（1→关键、2→高、3→中、4-5→低）
├─ 输出路径: .workflow/issues/{issue-id}/.task/TASK-{T-id}.json
├─ 每个文件遵循 task-schema.json（需要 IDENTITY + CONVERGENCE + FILES）
├─ source.tool = "issue-resolve", source.issue_id = {issue-id}
│
└─ 生成 plan.json（在所有 TASK-*.json 导出后）:
const issueDir = `.workflow/issues/${issueId}`
const taskFiles = Glob(`${issueDir}/.task/TASK-*.json`)
const taskIds = taskFiles.map(f => JSON.parse(Read(f)).id).sort()
// 防护: 若无任务生成则跳过 plan.json
if (taskIds.length === 0) {
console.warn('无任务生成; 跳过 plan.json')
} else {
const planOverview = {
summary: `问题解决计划 ${issueId}: ${issueTitle}`,
approach: solution.approach || "AI 探索的解决策略",
task_ids: taskIds,
task_count: taskIds.length,
complexity: taskIds.length > 5 ? "高" : taskIds.length > 2 ? "中" : "低",
_metadata: {
timestamp: getUtc8ISOString(),
source: "issue-plan-agent",
planning_mode: "agent-based",
plan_type: "feature",
schema_version: "2.0"
}
}
Write(`${issueDir}/plan.json`, JSON.stringify(planOverview, null, 2))
} // 结束防护
输出路径: .workflow/issues/{issue-id}/plan.json
任务跟踪模式
// 用阶段步骤初始化计划
update_plan({
explanation: "问题解决工作流已启动",
plan: [
{ step: "选择问题源", status: "已完成" },
{ step: "执行: [所选阶段名称]", status: "进行中" },
{ step: "总结与下一步", status: "待处理" }
]
})
阶段特定子任务在阶段执行时附加（详见各个阶段文档）。
核心指南
数据访问原则: 问题和解决方案文件可能非常大。为避免上下文溢出:
| 操作 | 正确 | 不正确 |
|---|---|---|
| 列出问题（简要） | ccw issue list --status pending --brief |
Read('issues.jsonl') |
| 读取问题详情 | ccw issue status <id> --json |
Read('issues.jsonl') |
| 更新状态 | ccw issue update <id> --status ... |
直接文件编辑 |
| 绑定解决方案 | ccw issue bind <id> <sol-id> |
直接文件编辑 |
| 批量解决方案 | ccw issue solutions --status planned --brief |
循环个别查询 |
输出选项:
--brief: JSON 带最少字段（协调器使用）--json: 完整 JSON（仅代理使用）
始终使用 CLI 命令进行 CRUD 操作。绝不直接读取整个 issues.jsonl 或 solutions/*.jsonl。
错误处理
| 错误 | 解决方案 |
|---|---|
| 未检测到源 | 显示 ASK_USER 包含所有 4 个选项 |
| 无效源类型 | 显示可用源，重新提示 |
| 阶段执行失败 | 报告错误，建议手动干预 |
| 无待处理问题（计划） | 建议先创建问题 |
| 无绑定解决方案（队列） | 建议先运行计划/转换/头脑风暴 |
阶段后下一步
成功执行阶段后，建议下一步操作:
// 计划/转换/头脑风暴后（解决方案已创建）
ASK_USER([{
id: "next_action",
type: "select",
prompt: "解决方案已创建。下一步是什么？",
options: [
{ label: "形成队列", description: "排序解决方案以供执行（/issue:queue）" },
{ label: "计划更多问题", description: "继续创建解决方案" },
{ label: "查看问题", description: "检查问题详情" },
{ label: "完成", description: "退出工作流" }
]
}]); // 阻塞（等待用户响应）
// 队列后（队列已形成）
// → 直接建议 /issue:execute
相关命令
issue-manage- 交互式问题 CRUD 操作/issue:execute- 使用 DAG 基础并行协调执行队列ccw issue list- 列出所有问题ccw issue status <id>- 查看问题详情