113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# 任务文件
|
||
|
||
> 默认一任务一文件：`docs/tasks/T-<编号>.md`。
|
||
> 路线图（[`../06-tasks.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 辅助） |
|
||
|
||
## 领取规则
|
||
|
||
1. 每个 agent 同时最多一个 `DOING` 任务。
|
||
2. 领取编号最小、状态 `TODO`、依赖全部 `DONE` 的任务。
|
||
3. 开工前写清 `write_paths`；与其他活跃任务路径重叠时不得并行。
|
||
`scripts/validate_agent_context.py` 会强制这一条，不通过就不是「注意一下」而是失败。
|
||
4. 记录默认分支头 `context_ref` 和工作分支。
|
||
5. 状态改为 `DOING` 后再修改生产代码。
|
||
6. 验收全部有证据后改 `DONE`；无法继续时标 `BLOCKED` 并写清所需外部输入。
|
||
|
||
## 任务文件结构
|
||
|
||
```yaml
|
||
---
|
||
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 原生内容的混合体，自上而下：
|
||
|
||
1. frontmatter。`vikunja_task_id` 是连接键；`write_paths`、`context_ref`、`work_branch`
|
||
是 git 原生，导出脚本永不写入。
|
||
2. 一行 BEGIN 标记（HTML 注释，含 `id`、`synced`、`sha256`）。
|
||
3. 区块正文：问题 / 背景、关联需求与交互、方案、验收要点、执行记录。
|
||
**Vikunja 权威**，`scripts/vikunja_export.py` 整段覆盖。
|
||
4. 一行 END 标记。
|
||
5. `## 边界`。**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`](../04-architecture.md) 第四节安全边界的任务，执行记录
|
||
必须列出对应的测试用例名。
|