QiuSWandClaude Opus 5
3c458bcf5b
修掉一处会让并行保护失效的设计缺口：AGENTS.md 声明「状态」权威在 Vikunja， 但离线门禁的检查 1 读的是 frontmatter 的 status，两者之间没有任何同步。 有人在看板上拖了卡片，frontmatter 不变，门禁就用过期数据放行了。 status 的权威定为 git frontmatter，理由与 write_paths 相同：它是判定 「两个活跃任务不得写同一路径」的输入，而门禁必须离线可跑；status 变更 决定谁能碰哪些文件，本来就该产生 commit。 - AGENTS.md：把 status 从 Vikunja 权威列表移入 git 原生表，并说明 bucket 与 done 仅为人类视图，不一致时以 git 为准 - agent-context.json：tracker.git_native_fields 增加 status - validate_agent_context.py：强制 git_native_fields 必须含 status， 已用反例验证缺失时报错 - vikunja_export.py：新增只读漂移检测，导出时比对 frontmatter status 与 Vikunja done，不一致则提示；只提示不修正，不反向写回 - docs/tasks/README.md、T-008 方案第 1/2 节：同步口径 顺带解决了窄 token 时期的 bucket 401 遗留问题——status 权威在 git， agent 不再依赖 bucket 移动来表达状态。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
任务文件
默认一任务一文件：
docs/tasks/T-<编号>.md。 路线图（../06-tasks.md）只负责建议拆分，不跟踪状态。
命名与状态
- 文件名：
T-001.md；细分任务用T-001a.md。 - 状态：
TODO、DOING、DONE、BLOCKED。 - 路线图已有编号时沿用；新编号不得覆盖已存在文件。
_template.md不是任务。
编号段位
| 段位 | 阶段 |
|---|---|
| T-0xx | Phase 0 地基 |
| T-1xx | Phase 1 真机取证 |
| T-2xx | Phase 2 采购服务核心 |
| T-3xx | Phase 3 双端打通与第一趟试选 |
| T-4xx | Phase 4 第二趟下单与收尾 |
| T-5xx | V2 及以后（图搜、Excel、ERP、订单核对、AI 辅助） |
领取规则
- 每个 agent 同时最多一个
DOING任务。 - 领取编号最小、状态
TODO、依赖全部DONE的任务。 - 开工前写清
write_paths；与其他活跃任务路径重叠时不得并行。scripts/validate_agent_context.py会强制这一条，不通过就不是「注意一下」而是失败。 - 记录默认分支头
context_ref和工作分支。 - 状态改为
DOING后再修改生产代码。 - 验收全部有证据后改
DONE；无法继续时标BLOCKED并写清所需外部输入。
任务文件结构
---
id: T-101
title: 一句话任务名
phase: 1
deps: [T-002]
status: TODO
created: 2026-08-03
vikunja_task_id: null # Vikunja 上对应任务的 id，是两边唯一的连接键
context_ref: null
work_branch: null
needs_device: true # 是否需要真机验收
needs_human_review: false # 是否需要人审原型 / 文案 / 决策后才能 DONE
write_paths:
- docs/tasks/T-101.md
- client/src/android/**
- client/tests/**
---
正文必须包含：
- 问题 / 背景
- 关联需求与交互
- 方案
- 验收要点
- 边界
- 执行记录
验证证据
执行记录至少写：
- 修改的文件。
- 实际运行的完整命令（含参数）。
- 结果是成功、失败还是未运行。
- 未验证范围与 blocker。
涉及真机的任务，额外必须写：
- 设备型号、Android 版本、连接方式（USB / WiFi）。
- 拼多多 App 版本。
- 使用的
goods_id（若涉及具体商品）。 - 截图与页面 XML 的产物路径。
- 是否触发了创建订单的动作；若触发，订单是否已产生、如何处置。
- 安全停止证据（若涉及）。
混合文件格式
任务文件是 Vikunja 投影与 git 原生内容的混合体，自上而下：
- frontmatter。
vikunja_task_id是连接键；write_paths、context_ref、work_branch是 git 原生，导出脚本永不写入。 - 一行 BEGIN 标记（HTML 注释，含
id、synced、sha256）。 - 区块正文：问题 / 背景、关联需求与交互、方案、验收要点、执行记录。
Vikunja 权威，
scripts/vikunja_export.py整段覆盖。 - 一行 END 标记。
## 边界。git 权威，脚本不触碰。
改区块内的内容要去 Vikunja 改，然后重新导出。直接手改会被 sha256 校验抓到并失败——
这是刻意的，两个权威同时可写就一定漂移。
status 例外：它的权威在 frontmatter，不在 Vikunja。 改状态就改 frontmatter 并提交；
Vikunja 的 bucket 位置和 done 标志只是人类视图，不一致时以 git 为准。导出脚本会在
比对到不一致时提示，但不会反向写回。
尚未迁移到 Vikunja 的任务文件（没有导出区块）保持原样，门禁豁免。
硬规则
- 「代码写完」「看起来可以」不能作为
DONE证据。 needs_device: true的任务，agent 不得自行标DONE。 真机验收只能由人完成； agent 保持DOING并写明等待人工验收的具体事项。needs_human_review: true的任务，agent 完成可自动验证部分后仍保持DOING。 执行记录 必须列出给人检查的文件、关键状态和确认问题；只有人明确确认后才能改DONE。- 涉及
../04-architecture.md第四节安全边界的任务，执行记录 必须列出对应的测试用例名。