From 2197012a5a009809c8370cb4ccbbd48d0122d8e8 Mon Sep 17 00:00:00 2001 From: pikastech Date: Tue, 21 Jul 2026 14:09:06 +0200 Subject: [PATCH] docs: simplify TaskTree report completion flow --- .agents/skills/unidesk-tasktree/SKILL.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/.agents/skills/unidesk-tasktree/SKILL.md b/.agents/skills/unidesk-tasktree/SKILL.md index ef0afac3..f56062ef 100644 --- a/.agents/skills/unidesk-tasktree/SKILL.md +++ b/.agents/skills/unidesk-tasktree/SKILL.md @@ -46,12 +46,15 @@ description: >- 执行 `task start`； - 新建后立即开始的任务必须在同一工作回合执行 `task start`，禁止长期留在 `pending`； - - 验收完成后、向用户报告完成前，必须先写 ExecutionReport，再执行 - `task complete`； + - 验收完成后、向用户报告完成前，必须写 ExecutionReport； + - `report write` 成功后默认在同一事务内把任务切换为 `completed`，日常闭环 + 不再额外执行 `task complete`； + - 相同报告幂等写入返回 `mutation=false`，但任务状态滞后时仍必须校正为 + `completed`； - 禁止因为代码已提交、issue 已关闭、服务已上线或准备执行 `$post-task`， 就跳过 TaskTree 状态更新；这些事实只能作为报告证据，不能替代状态 mutation； - - 当前仍受阻时及时更新为 `blocked` 并在报告中写明阻塞证据；阻塞解除并恢复 - 执行时重新 `task start`； + - 当前仍受阻时及时更新为 `blocked` 并在任务说明中写明阻塞证据；阻塞解除并 + 恢复执行时重新 `task start`，验收完成后再写 ExecutionReport； - 父任务的验收目标与全部必要子任务均完成后，父任务也必须写报告并完成， 不能只完成叶子节点而让父节点永久停留在未开始或进行中。 - 每次任务收口必须执行状态复核： @@ -62,7 +65,7 @@ description: >- 状态结束当前回合，并必须向用户报告原因。 - 清理历史滞后状态时不得仅凭标题批量完成： - 逐项核对提交、issue、部署、测试或既有报告证据； - - 证据充分时补写 ExecutionReport 后完成任务； + - 证据充分时补写 ExecutionReport，由报告写入自动完成任务； - 证据不足时保持原状态并补充说明，不伪造完成事实。 ## 能力映射 @@ -97,15 +100,13 @@ bun scripts/cli.ts tasktree task start \ --task ``` -- 完成任务前先写 ExecutionReport： +- 完成任务时写入 ExecutionReport，报告与完成状态在同一事务内提交： ```bash bun scripts/cli.ts tasktree report write \ --task --title "执行报告" --stdin <<'EOF' 验证已完成，记录命令、结果和关键证据。 EOF -bun scripts/cli.ts tasktree task complete \ - --task bun scripts/cli.ts tasktree group stats \ --group ``` @@ -137,6 +138,9 @@ tasktree workflow start - 同批任务必须在一个事务内全部成功或全部失败； - 报告使用 `report write --stdin` 或 `--body-file`； - 相同任务、标题、正文和状态的重复报告返回 `mutation=false`。 + - `report write` 返回完成后的 `task` 和 `taskMutation`； + - 报告内容幂等但任务尚未完成时，`mutation=false` 且 + `taskMutation=true`。 - 参数合同： - 多余位置参数返回 `invalid_arguments`； - 未知选项或命令不支持的选项返回 `invalid_option`； @@ -150,7 +154,9 @@ tasktree workflow start - Subsubtask 禁止继续创建下级。 - 状态流转： - `task start` 把任务标记为 `in_progress`； - - `task complete` 与 `task done` 要求至少一份 ExecutionReport； + - `report write` 成功后自动把任务标记为 `completed`； + - `task complete` 与 `task done` 保留为已有报告场景的显式完成入口，并要求 + 至少一份 ExecutionReport； - 禁止使用 `task update --status completed` 绕过报告门禁； - `task update --status blocked` 用于标记阻塞； - `task delete` 与 `task remove` 使用相同删除合同。