Skip to content

Latest commit

 

History

History
164 lines (114 loc) · 6.21 KB

TaskFlow.md

File metadata and controls

164 lines (114 loc) · 6.21 KB

TaskFlow 任务流程

本项目使用 TaskFlow 作为团队协作的任务编排与 Git Flow 自动化工具。所有非 trivial 工作建议走 TaskFlow MCP 流程,避免散乱的本地任务清单。


1. 项目绑定

项 值
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]


2. 调用约定

所有普通 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_FORBIDDEN

agent_id 推荐使用稳定字符串(copilot-cli / codex-cli / 个人名),用于多 agent 锁定与责任追溯。


3. 写操作前置校验(强制)

任何写操作前必须先:

validate_project_binding(project_id="ac_fs32")
get_runtime_info(project_id="ac_fs32")   # 确认 selector_type=project_id 且 plan_dir 正确

4. 任务生命周期

create_task_with_steps  →  get_next_task  →  claim_task  →  update_step(in_progress)
        ↓                                                          ↓
  落 .plan/confirmed/                                       update_step(done)
                                                                   ↓
                                                          release_task / 自动完成

Step 状态机

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="...")

5. Git Flow 集成

操作 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 收口任务。


6. CHANGELOG 注意事项

✅ 本项目 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 行尾

7. 多 Agent 锁定

claim_task(task_id="task-001-...", agent_id="copilot-cli")  # 加锁
# ... 执行 ...
release_task(task_id="task-001-...", agent_id="copilot-cli")  # 解锁

异常退出务必解锁,否则任务对其他 agent 不可见。


8. 调度与并发

场景 配置
涉及 Git 操作 set_max_concurrent(1) 强制串行(TaskFlow 默认)
纯文档/分析任务 可 set_max_concurrent(N),N 视任务依赖图而定
周期性任务 set_task_schedule(task_id, cron_expression)

9. 故障排查

错误 处理
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,必要时重装插件

10. 与项目其他规范的关系

  • 本文档 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。