一个面向 Codex 与 AI 编程智能体的持久化任务规划 Skill。它把计划、进度、验证证据、故障经验和多智能体交接记录写入磁盘，让复杂工程任务即使经历上下文压缩、会话中断或跨天继续，也不必从头分析。
本项目针对 GPT-5.6/Codex 的长时工程任务、多工具调用和多智能体协作做了深度优化，同时保持模型无关的核心设计：Markdown、Git 与 Python 标准库。只要宿主智能体支持 Skill、文件读写和命令执行，就可以采用这套工作流；多智能体能力则按宿主实际提供的工具自动降级。
社区开源项目，非 OpenAI 官方项目。 (岚风科技开源发布)
复杂任务真正浪费时间的地方，往往不是第一次写代码，而是中断后的重新理解、重复踩坑、并行编辑冲突，以及“任务完成了但没有验证证据”。Task Planning 将这些隐性成本变成可追踪的工程状态。
- 每个任务都有独立的 Markdown 计划文件，持续记录范围、验收标准、依赖、进度和下一步。
- 恢复时不会盲信旧计划，而是重新核对
git status、git diff、真实文件和测试结果。 - 文件名保持稳定，生命周期写入 frontmatter，避免状态变化导致引用失效。
- 支持
active、paused、blocked、completed、cancelled、superseded六种状态。
结果是：即使上下文被压缩、任务跨会话继续，或换一个智能体接手，也能从第一个未完成项继续，而不是重新扫描整个项目。
计划中的 Bug & Fix Log 不只记录“改了什么”，还要求写明：
- 症状与复现条件；
- 根因，而不是表面现象；
- 修复涉及的文件；
- 防止复发的测试、断言或检查。
后续处理相同模块时，智能体可以先读取历史故障与防护措施，减少重复犯错和维护时间。
计划在实施前定义范围、非目标、验收标准、风险、回滚方案和依赖关系，并选择真正适合任务的 Mermaid 图：
sequenceDiagram：跨组件调用链和请求/响应流程；flowchart：分支逻辑、流水线和任务依赖；stateDiagram-v2：生命周期与状态机；- dependency graph：迁移、升级和并行任务排序。
图不是装饰。实现发生变化时，计划要求同步更新图和依赖，确保设计记录始终能解释真实代码。
并行不是默认行为。只有接口已经固定、文件所有权不重叠、依赖已经满足且宿主提供子智能体工具时，任务才会被委派。
- 主智能体维护唯一的 Sub-agent Registry；
- 每个子智能体拥有明确的任务、文件范围、接口契约和检查点；
- 中断恢复时只继续未完成且仍有效的工作；
- 已完成、失败、取消或被替代的智能体不会被重复启动；
- 子智能体的结果必须由主智能体审查差异和验证证据后才能集成。
这能提高并行效率，同时减少重复实现、接口漂移和多人修改同一文件造成的冲突。
| 能力 | 作用 |
|---|---|
| 计划与仓库校准 | 将计划作为协调记录，将代码、Git 差异和测试结果作为事实来源 |
| 状态与验证分离 | status=completed 不等于测试通过；verification_status 单独记录 verified、partial 或 not-run |
| 基线测试 | 开始修改前记录已知状态，区分新回归与历史失败 |
| 成本分级验证 | 自动运行快速本地检查；付费、外部、破坏性或耗时检查需先确认 |
| 依赖图校验 | 严格检查重复任务 ID、缺失依赖和依赖环 |
| 原子写入 | 计划通过临时文件和替换操作写入，避免中断留下半个文件 |
| UTF-8 加固 | 显式使用 UTF-8，兼容 Windows 默认 GBK 环境和中英文内容 |
| 零运行时依赖 | 命令行工具仅使用 Python 标准库，无需 pip install |
flowchart TD
A[查找与当前目标匹配的未完成计划] --> B{找到匹配计划?}
B -- 是 --> C[读取完整计划并与仓库事实校准]
B -- 否 --> D[创建计划与验收标准]
C --> E[恢复仍未完成的工作与有效子智能体]
D --> F[定义图、依赖、风险与任务边界]
E --> G[从第一个未完成项继续]
F --> G
G --> H[实施并立即记录变更和故障经验]
H --> I{所有任务完成?}
I -- 否 --> G
I -- 是 --> J[运行验收检查并记录证据]
J --> K[分别更新完成状态与验证状态]
- 支持 Skill 的 Codex 或兼容 AI 编程智能体；
- Python 3.8 或更高版本；
- Git，建议用于恢复时的事实校准；
- Mermaid 渲染是可选能力，不影响计划文件本身。
macOS / Linux：
git clone https://github.com/McXiao1/task-planning.git "${CODEX_HOME:-$HOME/.codex}/skills/task-planning"Windows PowerShell：
$skillRoot = if ($env:CODEX_HOME) { Join-Path $env:CODEX_HOME "skills" } else { Join-Path $HOME ".codex\skills" }
git clone https://github.com/McXiao1/task-planning.git (Join-Path $skillRoot "task-planning")也可以从 Releases 下载 ZIP，并将解压后的目录放到 Codex Skills 目录。安装后新建一个任务，使 Codex 重新发现 Skill。
可以显式调用：
使用 $task-planning 执行这个跨多阶段的项目改造。请持久记录进度、验证证据和下一步，确保中断后可以恢复。
当任务明显是长时、多阶段、跨文件或需要跨会话恢复时，Codex 也可以根据 SKILL.md 的描述自动触发它。
不建议用于只读分析、代码审查或一眼就能完成的局部修改；这些任务创建完整计划的成本通常高于收益。
以下命令应在目标项目目录中运行，并将 <skill-dir> 替换为本 Skill 的安装目录：
python -X utf8 <skill-dir>/scripts/plan.py init --title user-auth-refactor --goal "完成定义"
python -X utf8 <skill-dir>/scripts/plan.py list
python -X utf8 <skill-dir>/scripts/plan.py check plan/<plan-file>.md --strict
python -X utf8 <skill-dir>/scripts/plan.py agents plan/<plan-file>.md --unfinished
python -X utf8 <skill-dir>/scripts/plan.py pause plan/<plan-file>.md --reason "等待接口确认"
python -X utf8 <skill-dir>/scripts/plan.py resume plan/<plan-file>.md
python -X utf8 <skill-dir>/scripts/plan.py close plan/<plan-file>.md| 命令 | 用途 |
|---|---|
init |
创建 Git 感知、带时间戳且不会覆盖旧文件的新计划 |
list |
查看全部计划的状态、验证状态、目标和更新时间 |
check --strict |
检查必填字段、占位符、任务 ID、依赖与依赖环 |
agents --unfinished |
仅列出仍需要恢复或处理的子智能体尝试 |
status |
查看或设置计划状态 |
pause / resume / block |
记录暂停、恢复和阻塞 |
cancel / supersede |
明确终止计划或由新计划替代 |
close |
严格校验通过后关闭计划，并保持文件名不变 |
完整行为与恢复规则请阅读 SKILL.md。可直接参考 完整示例计划。
task-planning/
├── SKILL.md # Codex 加载的核心工作流
├── agents/openai.yaml # Skill 列表与默认提示元数据
├── assets/plan-template.md # 新计划模板
├── references/ # 可恢复任务的完整示例
├── scripts/plan.py # 标准库命令行工具
└── tests/test_plan.py # 状态、校验、恢复与 Git 行为测试
| 环境能力 | 行为 |
|---|---|
| GPT-5.6 / Codex | 主要优化目标，完整使用持久计划、工具验证和条件式多智能体协作 |
| 其他支持 Skills 的模型 | 可使用相同计划协议与命令行工具 |
| 没有子智能体工具 | 保留 Registry 记录，由主智能体串行接管未完成任务 |
| 不在 Git 仓库中 | 必须通过 --dir 显式指定计划目录，不猜测输出位置 |
兼容性表示工作流和文件格式可以使用，不代表所有宿主都提供相同的模型推理能力、子智能体 API 或工具权限。
python -X utf8 -m unittest discover -s tests -v当前测试覆盖 frontmatter 往返、CJK/特殊字符、模板渲染、Git 根目录发现、文件名碰撞、严格校验、任务依赖环、生命周期关闭门禁，以及子智能体恢复筛选。
问题报告和改进建议请提交到 GitHub Issues。代码贡献流程见 CONTRIBUTING.md。提交前请运行完整测试，并确保新增行为有对应测试或可验证的说明。
本项目采用 MIT License。