本项目使用 TaskFlow 作为团队协作的任务编排与 Git Flow 自动化工具。所有非 trivial 工作建议走 TaskFlow MCP 流程,避免散乱的本地任务清单。
| 项 | 值 |
|---|---|
project_id |
ac_fs32 |
| MCP server name | taskflow |
.plan/ 位置 |
<repo-root>/.plan/ |
| 注册表 | ~/.codex/taskflow-projects.json(Codex/Copilot CLI 共享) |
安装方式:
python <home>/plugins/taskflow/scripts/install_plugin.py --project-dir <repo> --project-id ac_fs32 [--with-copilot]
所有普通 TaskFlow MCP 工具必须传 project_id="ac_fs32"。
# ✅ 正确
get_runtime_info(project_id="ac_fs32")
list_tasks(project_id="ac_fs32", status_filter="todo")
# ❌ 禁止:诊断字段,不要传给普通工具
get_runtime_info(plan_dir=".plan") # PATH_SELECTOR_FORBIDDEN
get_runtime_info(project_dir="E:/...") # PATH_SELECTOR_FORBIDDENagent_id 推荐使用稳定字符串(copilot-cli / codex-cli / 个人名),用于多 agent 锁定与责任追溯。
任何写操作前必须先:
validate_project_binding(project_id="ac_fs32")
get_runtime_info(project_id="ac_fs32") # 确认 selector_type=project_id 且 plan_dir 正确create_task_with_steps → get_next_task → claim_task → update_step(in_progress)
↓ ↓
落 .plan/confirmed/ update_step(done)
↓
release_task / 自动完成
todo → in_progress → done,严禁跳过 in_progress。
# ✅ 两次调用
update_step(task_id=..., step_id="build", status="in_progress", agent_id="copilot-cli")
update_step(task_id=..., step_id="build", status="done", agent_id="copilot-cli", output="...")| 操作 | TaskFlow 工具 | 说明 |
|---|---|---|
| 拉功能分支 | prepare_git_branch(task_id, change_type, slug) |
自动按 feature/* 命名 |
| 合回 develop | finish_git_branch(target_branch="develop", delete_remote=true) |
默认 --no-ff + 删远程 |
| 拉热修分支 | prepare_hotfix_branch(version, slug) |
从 main 切出 |
| 完成热修 | finish_hotfix(version, confirmed=true) |
合 main + tag + 同步 develop |
| 拉发布分支 | prepare_prerelease(version) 或 prepare_release_branch(version) |
从 develop 切出 |
| 完成发布 | finish_release(version, confirmed=true) |
合 main + tag |
| 主线发布 | release_to_main(version, confirmed=true) |
显式合并到 main,必须用户确认 |
finish_git_branch 在 PR 模式下可能超时(gh pr merge 网络往返)。回退方案:
git checkout develop && git pull --ff-only
git merge --no-ff feature/<branch> -m "Merge ..."
git push origin develop
git push origin --delete feature/<branch>
git branch -D feature/<branch>回退后必须手工补 update_step + release_task 收口任务。
✅ 本项目 CHANGELOG 已迁移至 TaskFlow DSL 格式(v0.7.11.10 起):UTF-8 无 BOM + CRLF + 头部
'''块(:project:author:desc:version:last_update)+:history段,每条 entry 为X.Y.Z - YYYY/MM/DD (7位hash) [branch]+:brief+-列表。
针对 ac_fs32 项目的硬性规则:
- ✅ 可调
record_changelog_entry追加新条目(会自动校验缩进、版本号唯一、日期格式) - ✅ 可调
validate_changelog_format/validate_changelog_versions做格式与重复检查 - ✅ 真实 7 位 commit hash 必须在提交后回填,不允许伪造(先用
(PENDING)占位) - ✅ feature 分支上的条目,合并回 develop 后再补一条
[develop]标记的条目 ⚠️ 重复版本号会被拒绝;docs/chore/style 类二次修改使用 4 段版本号(如0.7.11.10)⚠️ v1.x 完整历史(1952 行 / 0.1.0 → 1.39.1)已归档至doc/changelog/v1/CHANGELOG,主 CHANGELOG 仅维护 v0.7.x +(未来)v0.x 后续条目⚠️ 主 CHANGELOG 当超过 ~300 行 minor 段时,按 TaskFlow 归档规则迁出至doc/changelog/v<major>/CHANGELOG
手工 prepend 时的写入约定(用于 (PENDING) 占位等场景):
[System.IO.File]::WriteAllText($path, $content, (New-Object System.Text.UTF8Encoding $false))
# 内容用 "`r`n" 拼,CRLF 行尾claim_task(task_id="task-001-...", agent_id="copilot-cli") # 加锁
# ... 执行 ...
release_task(task_id="task-001-...", agent_id="copilot-cli") # 解锁异常退出务必解锁,否则任务对其他 agent 不可见。
| 场景 | 配置 |
|---|---|
| 涉及 Git 操作 | set_max_concurrent(1) 强制串行(TaskFlow 默认) |
| 纯文档/分析任务 | 可 set_max_concurrent(N),N 视任务依赖图而定 |
| 周期性任务 | set_task_schedule(task_id, cron_expression) |
| 错误 | 处理 |
|---|---|
PATH_SELECTOR_FORBIDDEN |
移除 plan_dir / project_dir,改用 project_id="ac_fs32" |
PROJECT_ID_REQUIRED |
同上 |
| 任务 lock 占用 | get_task 查 lock.by;非本 agent 不可强解 |
| MCP 工具超时 | 见 §5 Git 回退;其他工具重试 + add_step_log(level="warning") 留痕 |
.plan/ 飘移 |
重跑 validate_project_binding,必要时重装插件 |
- 本文档 vs
doc/GitWorkflow.md:GitWorkflow 描述纯 Git 模型;本文档描述如何通过 TaskFlow 自动化执行该模型 - 本文档 vs
CONTRIBUTING.md:CONTRIBUTING 是入门级贡献指南;本文档是 TaskFlow 工具链深度参考 - 本文档 vs
.github/copilot-instructions.md:Copilot 指令文件中的<!-- taskflow-copilot:start -->段落由插件维护,与本文档保持一致
关于 TaskFlow 内部实现,参见
<home>/plugins/taskflow/与上游仓库 README。