FIT Framework 多 AI 协作开发：使用 Codex CLI 的 complete-task 命令完成任务收尾与归档-育师

人工智能
大模型
AI 应用
后端
AI Agent
RAG
流程编排
微服务

【免费下载链接】fit-framework

FIT: 企业级AI开发框架，提供多语言函数引擎（FIT）、流式编排引擎（WaterFlow）及Java生态的LangChain替代方案（FEL）。原生/Spring双模运行，支持插件热插拔与智能聚散部署，无缝统一大模型与业务系统。

项目地址：https://gitcode.com/ModelEngine/fit-framework

在 FIT Framework 仓库中，.codex/commands/目录维护着一套面向 Codex CLI 的项目级 prompts，用于驱动"需求分析 → 方案设计 → 代码实现 → 代码审查 → 任务归档"的完整开发工作流。本文聚焦其中负责最终收尾环节的complete-task命令：它负责把通过审查、已提交 Git 的任务标记为完成状态，更新任务元数据，并将其从.ai-workspace/active/归档到.ai-workspace/completed/目录。读完本文，你将掌握该命令的完整执行步骤、前置条件判定方法、底层任务文件结构，以及它与check-task、block-task等相邻命令的协作关系。

命令定位：多 AI 协作工作流中的"收尾闸门"

FIT Framework 采用基于 AGENTS.md 标准的多 AI 协作机制，Claude Code、Codex、Gemini CLI 等工具可以在同一个仓库中接力处理任务。每个任务的生命周期由.ai-agents/workflows/下的 YAML 工作流定义驱动（如 feature-development.yaml），标准流程为：

需求分析（requirement-analysis）：输出analysis.md
技术方案设计（technical-design）：输出plan.md
代码实现（implementation）：输出implementation.md
代码审查（code-review）：输出review.md
问题修复（refinement，仅在审查要求修改时进入）
最终确认与提交（finalize）

complete-task命令对应的就是工作流中的finalize阶段之后的人工确认与归档动作。它的命令签名如下（见 complete-task.md 的 frontmatter）：

--- description: 标记任务完成并归档到 completed 目录 argument-hint: <task-id> ---

使用方式为prompts:complete-task <task-id>（安装后以/prompts:complete-task <task-id>调用），其中<task-id>是形如TASK-20260205-202013的任务唯一标识。

前置条件检查：四条"全部满足"才能执行

complete-task明确声明了硬性前置条件，任何一条不满足都不允许执行归档（原文为"如果以上条件未全部满足,请勿执行此命令"）：

前置条件	含义	对应验证命令
所有工作流步骤已完成	工作流进度中的每个步骤都标记为 ✅	`prompts:check-task <task-id>`
代码已审查通过	`review.md`显示"批准"（approve）状态	`prompts:review-task <task-id>`
代码已提交到 Git	变更已通过`commit`相关流程提交	`prompts:commit`
所有测试通过	项目基线命令`mvn clean install`通过	见 AGENTS.md 测试要求

其中"代码审查已批准"这一条在 feature-development.yaml 中体现为code-review步骤的next_steps分支：审查通过（review.status == 'approve'）才进入finalize；若为needs_changes则必须进入refinement修复后重新审查。这一设计保证了"未审查代码绝不归档"。

执行步骤详解：从验证到归档的八步流程

complete-task命令将收尾过程拆解为八个可验证的步骤，每一步都有对应的命令或产物：

1. 验证任务存在

test -f .ai-workspace/active/$1/task.md && echo "✅ 任务存在" || echo "❌ ERROR: 任务不存在"

这里的$1是用户在/prompts:complete-task <task-id>中传入的位置参数，Codex CLI 会将其替换为实际的 task-id（占位符机制详见 .codex/README.md 的"参数传递"章节）。该检查确保任务仍处于active状态——已归档或已阻塞的任务会直接报错，防止重复归档。

2. 读取并验证任务状态

检查任务的所有步骤是否标记为完成 ✅
检查上下文文件完整性：analysis.md、plan.md、implementation.md、review.md四个文件必须全部存在

这四个文件是任务完整上下文的载体，在 .ai-agents/README.md 的目录说明中被明确列为每个任务的标准产物。缺少任意一个，都意味着任务链路不完整，不能归档。

3. 获取当前时间

date '+%Y-%m-%d %H:%M:%S'

该时间将写入updated_at和completed_at两个元数据字段，格式为yyyy-MM-dd HH:mm:ss，与任务模板中的约定一致。

4. 更新任务状态元数据

使用 Edit 工具更新task.md的 YAML frontmatter：

status: completed
current_step: finalize
updated_at: 当前时间
completed_at: 当前时间

这些字段定义于任务模板 task.md 的 frontmatter：

--- id: TASK-{yyyyMMdd-HHmmss} type: feature|bugfix|refactor|review|docs workflow: feature-development|bug-fix|code-review|refactoring status: active|blocked|completed created_at: {yyyy-MM-dd HH:mm:ss} updated_at: {yyyy-MM-dd HH:mm:ss} created_by: human|claude|chatgpt|gemini current_step: {step-id} assigned_to: {当前处理的AI或空} ---

可以看到status的合法取值正是active|blocked|completed三种，complete-task将其从active切换为completed，与 block-task.md 将其切换为blocked形成对称的状态机。

5. 添加完成总结

在task.md末尾追加完成总结，内容包括交付成果和完成标准等，为后续检索、复盘留下可追溯的记录。这与任务模板中"状态更新检查清单"的要求（完成后执行/complete-task归档）相呼应。

6. 归档任务

mkdir -p .ai-workspace/completed && mv .ai-workspace/active/$1 .ai-workspace/completed/

归档采用"移动目录"而非复制，任务连同其全部上下文文件（analysis.md、plan.md、implementation.md、review.md）整体迁入completed目录，保证历史记录的完整性与可审计性。

7. 验证移动成功

test ! -d .ai-workspace/active/$1 && echo "✅ 已移除 active" || echo "❌ active 仍存在" test -d .ai-workspace/completed/$1 && echo "✅ 已归档到 completed" || echo "❌ 归档失败"

双向验证：active中已移除、completed中已存在，两个条件同时满足才算归档成功。这延续了本套命令体系"每步可验证"的设计风格（block-task、check-task均采用同类test验证）。

8. 告知用户

🎉 任务 $1 已完成并归档 归档位置: .ai-workspace/completed/$1/

向用户输出归档位置，便于人工核对。

底层机制：任务目录结构与状态流转

理解complete-task需要先理解.ai-workspace/工作区的目录约定。根据 .ai-agents/README.md，工作区按任务状态分为三个区域（.ai-workspace/为临时文件目录，已被 git ignore）：

.ai-workspace/ ├── active/ # 进行中的任务 │ └── {task-id}/ │ ├── task.md # 任务主文件（含元数据） │ ├── analysis.md # 需求分析 │ ├── plan.md # 技术方案 │ ├── implementation.md # 实现报告 │ └── review.md # 审查报告 ├── completed/ # 已完成的任务（{task-id}/ 下保留全部上下文文件） ├── blocked/ # 被阻塞的任务 └── logs/ # 执行日志

任务在三个目录间的流转构成了状态机：

create-task创建任务 → 进入active/
遇到不可解决的问题 →block-task移入blocked/（解除阻塞后手动mv回active/）
全部完成并验证 →complete-task移入completed/

complete-task正是"最终态"的唯一入口。值得注意的是，任务模板 task.md 的"状态更新检查清单"中明确写道："违反此检查清单将导致任务状态追踪失败，这是不可接受的"，可见状态元数据的正确更新是本套协作机制正常运转的基石。

与相邻命令的配合：完整的任务生命周期

complete-task并非孤立命令，它与.codex/commands/中的其他命令构成完整闭环（命令清单见 .codex/README.md）：

阶段	命令	作用
创建	`create-task`	从自然语言描述创建`task.md`与`analysis.md`，任务进入`active/`
方案	`plan-task`	产出`plan.md`技术方案，需人工审查
实现	`implement-task`	按方案编码与测试，产出`implementation.md`
审查	`review-task`	产出`review.md`，给出批准/需修改结论
状态查询	`check-task`	按`active/ → blocked/ → completed/`优先级查找任务并输出状态报告
阻塞	`block-task`	标记阻塞并移入`blocked/`
收尾	`complete-task`	标记完成、追加总结、归档到`completed/`

其中 check-task.md 的"下一步建议规则"恰好勾勒出这条流水线：需求分析完成 →plan-task；技术方案完成 → 等待人工审查后implement-task；实现完成 →review-task；审查批准 →commit；审查需修改 →refine-task。当流水线走到commit之后，complete-task即为最后一棒。这种"命令间通过.ai-workspace目录与标准文件名解耦"的设计，使得任何 AI（Claude Code、Codex、Gemini CLI）都能通过读取task.md和上下文文件随时接手任务。

安装与调用方式

本套命令以仓库内文档形式维护，需要手动安装后才能通过 Codex CLI 调用（Codex CLI 的自定义 prompts 默认只从用户目录~/.codex/prompts/读取）：

bash .codex/scripts/install-prompts.sh

安装脚本 install-prompts.sh 会把.codex/commands/下所有.md文件复制到~/.codex/prompts/，并打印已安装命令清单。安装后即可通过/prompts:complete-task <task-id>调用。这些 prompt 以"仓库根目录"为默认上下文，作为全局 prompts 使用时需先切换到目标仓库或显式指定路径。

最佳实践与注意事项

complete-task命令在文档末尾给出了三条明确的使用守则，这也应成为团队在多 AI 协作中的收尾共识：

只有在真正完成所有工作后才归档：前置条件检查（工作流步骤、审查批准、Git 提交、测试通过）缺一不可，归档不是"差不多就行"。
归档前确认所有文档都已创建：analysis.md、plan.md、implementation.md、review.md四个上下文文件必须完整，它们是任务可追溯、可复盘的基础。
不要过早归档未完成的任务：状态机中active → completed是单向不可逆的收尾动作（已归档任务不再回到active），一旦误归档，只能手动从completed/移回并修正元数据。

此外，结合 .ai-agents/QUICKSTART.md 的最佳实践，建议在归档前使用check-task生成一份任务状态报告作为最终核对依据，并在完成总结中明确记录交付成果与验收标准，让completed/目录沉淀为项目可检索的任务档案库。