docs: adopt harness coding workflow

docs/tasks/README.md

@@ -0,0 +1,116 @@
+# 任务文件（一任务一文件 · Gitea 实时协调）
+
+> 本目录是项目任务的**默认存放位置**：每个任务一个文件 `docs/tasks/T-<编号>.md`，单 agent 与多 agent 并发通用。
+> 阶段划分、里程碑和待办池见路线图 [`../06-tasks.md`](../06-tasks.md)；路线图只读，不跟踪单任务状态。
+> YoVision 已启用 Gitea：Issue 是实时状态权威，任务文件负责版本化规格、依赖、`write_paths` 和长期执行证据。
+
+## 为什么默认一任务一文件
+
+- **单 agent**：领任务只读一个文件就拿到完整上下文（背景、方案、验收、执行记录），不用在看板、进度流水、快照三个共享文件之间跳转同步；执行记录和任务绑定，审查时 `git log -p` 一个文件即可回放全程。
+- **多 agent 并发**：单个大看板 + 多写者 = **编辑竞争**（读到旧版本、反复重读）、**ID 撞号**（全局递增号是共享计数器）、**合并冲突**（相邻行改动）。一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在**新建文件时当场暴露**（文件已存在就换号）。
+- **零迁移**：项目从单 agent 长到多 agent，无需切换任何约定。
+
+## 文件命名与 ID
+
+- 文件名：`docs/tasks/T-<编号>.md`（如 `docs/tasks/T-101.md`）；同族细分用后缀 `T-101a.md`。
+- 落实路线图建议任务时，**沿用路线图 `../06-tasks.md` 里的建议编号**（如 T-101）。
+- 路线图之外的新任务：取「路线图建议编号 + `docs/tasks/` 现有文件」里最大的 `T-###`，`+1`。
+- **建文件即防撞**：若目标编号文件已存在（别的 agent 先建了），改用下一个号，**不要覆盖别人的文件**。
+- 模板 `_template.md` 以下划线开头，不是真实任务、不参与编号扫描。
+
+## 每个任务文件的结构（frontmatter + 正文）
+
+```markdown
+---
+id: T-101
+title: 一句话任务名
+phase: 1               # 所属阶段，沿用路线图的 Phase 编号
+deps: [T-100]          # 依赖的任务 ID
+status: TODO           # TODO | DOING | DONE | BLOCKED
+created: 【日期】
+issue: null            # Gitea Issue 编号；未启用 Gitea 时保持 null
+context_ref: null      # 领取时默认分支提交 SHA
+claim_branch: null
+work_branch: null
+write_paths:           # 允许修改的仓库相对路径
+  - docs/tasks/T-101.md
+  - 【path/to/module】
+---
+
+## 问题 / 背景
+## 关联需求与交互（如适用）
+## 方案
+## 不可变约束
+## 验收要点
+## 边界（不改什么）
+## 协作约束
+## 执行记录
+```
+
+## 领取 / 完成流程
+
+- 状态：`TODO` · `DOING` · `DONE` · `BLOCKED`。每个 agent 同时最多一个活跃任务；项目可以并行多个写路径互不重叠的任务。
+- 每个 agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
+- 默认一个任务只有一个责任 Agent 和一个写入者。复杂任务在编码前把确认后的方案写进 `## 方案`；范围明确时直接执行，任务内委派只在项目规则显式允许时启用。
+- `## 不可变约束` 逐项写清不能由执行者自行改变的阈值、判定式、安全边界和既有契约字段；没有时明确写“无”，不要留空让执行者猜测。
+- `write_paths` 必须在动手前写清。两个活跃任务路径相同，或一条是另一条的目录前缀，均视为冲突，不能并行。
+- `## 验收要点` 按 [`../03-tech-stack.md`](../03-tech-stack.md) 区分任务相关验证、命中条件才执行的完整门禁，以及必需的人工 / 设备验收；人工门禁未完成时不得改为 `DONE`。
+- UI 任务在动手前写清关联的 US / IX 编号；无用户界面时，在任务文件中标记交互清单不适用。
+- P0 的 UI 任务动手前确认 `docs/design/` 有对应页面原型，没有就先生成（约定见 [`../design/README.md`](../design/README.md)）；显著改版页面的任务在 `## 方案` 中写明第一步为重新生成原型并更新 IX 草稿。
+- 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
+- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。
+- **只改自己那个任务文件**；不要编辑别人正在做的任务文件。
+
+未启用 Gitea 时，在独立分支 / worktree 中把任务文件从 `TODO` 改为 `DOING` 即可。启用 Gitea 时，必须先按 [`../gitea-collaboration.md`](../gitea-collaboration.md) 由 dispatcher 串行分配并创建 `claims/T-<编号>` 防御性标记；assignee、标签、读回和普通 create-branch API 都不能单独提供并发互斥。
+
+## 任务内委派（可选）
+
+任务内委派默认关闭；跨 Agent 并行优先拆成 `write_paths` 互不重叠的不同任务。项目显式允许任务内委派时：
+
+- 只读探索者不得修改或提交仓库；探索结论先由任务所有者核实并写回任务文件。
+- 同一时刻只有一个写入者。任务所有者若把实现交给执行者，自己不与执行者并行修改相同任务路径。
+- 派发内容必须逐项包含任务文件、不可变约束、允许的 `write_paths`、明确不改什么，以及任务相关 / 完整 / 人工三层验证要求；执行者不得自行放宽。
+- 任务所有者保留最终责任，必须独立检查 `git status`、审阅未暂存与已暂存 diff、检查意外行尾变化并重跑已触发的验证；不能仅凭执行者自报把任务标记为 `DONE`。
+
+## 与 Gitea Issue / PR 的映射（可选）
+
+- 一个任务文件对应一个主 Issue；Issue 负责实时领取、阻塞和评审状态，任务文件负责版本化规格和长期证据。
+- 先把任务文件合入默认分支，再创建 Issue；随后把 Issue 编号回填任务文件并合入默认分支，最后才添加 `status/todo`。映射未完成的 Issue 不可领取。
+- Issue、claim 分支、工作分支和 PR 都携带同一个 `T-<编号>`；不得用一个 PR 顺带完成多个任务。
+- 工作分支命名为 `agent/<agent-id>/T-<编号>`，每个 agent 使用独立 worktree。
+- MVP 由一个 dispatcher / 主 agent 串行分配任务，以此保证同一任务不被重复领取，并保证不同任务的 `write_paths` 不冲突。唯一 claim 分支只拦截顺序重试和常见旁路，不能替代 dispatcher 的互斥保证。
+- 进入评审后 Issue 使用唯一 `status/review`；PR 合并且默认分支任务文件为 `DONE` 后，Issue 才能关闭并标记 `status/done`。
+- 领取、结构化 claim 评论、过期锁回收和分支清理的完整规则见 [`../gitea-collaboration.md`](../gitea-collaboration.md)。
+
+## 用户指令暗语（可选约定）
+
+> 用户的工作流通常固定为：提 bug/需求 → 讨论定案 → 落成任务文件 → 提交 → 实现 → 提交。
+> 为减少重复输入，可约定以下触发词；agent 读到即按约定执行。默认值：不注明视角就是全栈工程师视角；每步产物默认提交 git（只提交本次相关文件）。
+
+| 用户输入 | agent 执行 |
+| --- | --- |
+| `bug: <现象>` / `需求: <描述>` | 先查代码再给分析和方案，**只讨论不改代码** |
+| `grill: <方案>` | 反方评审，逐点挑战该方案 |
+| `落task` | 把已讨论定案落成 `docs/tasks/T-<编号>.md`（按上述规则查号防撞），**只写文档不写代码，写完自动提交 git** |
+| `审 T-<编号>` | **以 git 历史为准**（`git log -p` 该任务文件找出最近改动），先核代码事实，再审核该改动是否合理、给缺口 |
+| `补` | 把讨论新增的结论补进当前任务文件并提交 git |
+| `做 T-<编号>` | 实现该任务 + 跑任务内验证命令；**验证全绿才提交**（执行记录、状态 DONE、提交）；验证失败 → 报告、**不提交**、状态留 DOING 或标 BLOCKED 记原因 |
+| `记backlog: <一行>` | 追加进待办池（`docs/06-tasks.md` Backlog）并提交，只记一行、不建任务文件 |
+
+补充规则：
+
+- `落task`/`补` 可带参数（`落task <主题>`、`补 T-<编号>`）；新会话或无对话上下文时 agent **必须先问清指代对象，不得猜**。
+- 采用时把这套暗语同时写进项目的 `AGENTS.md` 工作规则，并**声明 `AGENTS.md` 为唯一权威源**（agent 记忆、模板副本仅为指针/种子）——多副本不声明权威源，改触发词时必然漂移。
+- 触发词可按团队习惯改名，关键是「一个词 = 一个流程阶段 + 默认动作」。
+
+## 看板视图
+
+- 现阶段：`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。
+- 可选：加一个脚本把所有任务文件的 frontmatter 汇总成一张只读看板表，agent 不手改看板。
+
+## 与路线图和共享文件的关系
+
+- [`../06-tasks.md`](../06-tasks.md)：只读路线图（Phase 划分、里程碑、Backlog、建议拆分清单）；未启用 Gitea 时以任务文件 frontmatter 为准，启用后以 Issue 为实时状态、合并后的任务文件为长期事实。
+- `../../progress.md`：可选工件，用作历史归档或项目级大事记；执行记录写各任务文件，不逐任务追加。
+- [`../current-state.md`](../current-state.md)：项目级快照（启动/验证路径、目录要点、blocker）；任务状态不在此维护，可由脚本汇总 frontmatter 生成。
+- [`../gitea-collaboration.md`](../gitea-collaboration.md)：启用 Gitea 时的任务映射、串行分配、防重复 claim、写路径防撞和 PR 状态协议。

docs/tasks/T-001.md

@@ -0,0 +1,63 @@
+---
+id: T-001
+title: 建立摄像头兼容性实验矩阵与采购白名单
+phase: 0
+deps: []
+status: TODO
+created: 2026-08-03
+issue: null
+context_ref: null
+claim_branch: null
+work_branch: null
+write_paths:
+  - docs/tasks/T-001.md
+  - docs/research/camera-compatibility.md
+---
+
+## 问题 / 背景
+
+YoVision 尚未用真实候选摄像头验证 ONVIF/RTSP 厂商差异。直接开始生产接入会把未知兼容性问题带进 Sense，M0 出口要求先验证 3–5 款设备并形成采购白名单。
+
+## 关联需求与交互（如适用）
+
+- 用户故事：US-007。
+- 交互清单：无产品 UI；使用版本化实验记录。
+- 需求：`docs/02-requirements.md` §2，原始来源 `docs/raw/01-需求收集.md` §6.1。
+
+## 方案
+
+1. 在隔离实验室选定 3–5 款候选设备，记录型号、固件、认证方式和网络条件。
+2. 为每款设备执行 GetProfiles、GetStreamUri、SetSystemDateAndTime、主/子码流、认证失败、掉线恢复和时间漂移测试。
+3. 在 `docs/research/camera-compatibility.md` 固化步骤、原始证据摘要、差异、限制和采购结论。
+4. MiBeeNvr 可直接运行作测试台，也可按白名单阅读参考代码；不修改 `_reference/`，临时配置和代码不进入生产基线。
+
+## 不可变约束
+
+- 阈值 / 数值边界：候选设备 3–5 款；每款三个 ONVIF 核心操作全部有证据。
+- 判定式 / 状态转换：只有必过项全部通过才进入采购白名单；失败设备记录原因而不是删除记录。
+- 安全边界：只用自购实验设备和隔离网络；不接真实住户、学校或客户摄像头；不记录密码、完整 RTSP 凭据或可复用 token。
+- 既有契约：`_reference/` 只读，M0 产物不得成为生产 NVR 或长期依赖。
+
+## 验收要点
+
+- 任务相关验证：文档包含设备矩阵、可重复命令/步骤、逐项结果和采购白名单；运行三条 harness 治理命令。
+- 完整门禁：涉及脚本时在隔离环境对全部 3–5 款设备重复执行；没有生产代码则不触发 Go/Python 完整门禁。
+- 人工 / 设备验收：必需；由实施/硬件负责人核对型号、固件和原始测试证据。
+- 构建产物：不适用；交付物为 `docs/research/camera-compatibility.md`。
+
+## 边界（不改什么）
+
+不创建 Sense 生产脚手架，不修改 `_reference/`，不评估 AI 检出率，不承诺 16/128 路容量。
+
+## 协作约束
+
+- 责任 Agent：由 dispatcher 分配。
+- 唯一写入者：同责任 Agent。
+- 委派：默认不启用；设备测试可由指定人员执行，但任务所有者必须核验原始证据。
+- Gitea：Issue 创建后回填；领取时写入 `context_ref`、claim 和工作分支。
+
+任何新增写路径先由 dispatcher 与活跃任务做前缀冲突检查。
+
+## 执行记录
+
+尚未领取。

docs/tasks/T-002.md

@@ -0,0 +1,68 @@
+---
+id: T-002
+title: 关闭架构影响型需求开放问题
+phase: 0
+deps: []
+status: TODO
+created: 2026-08-03
+issue: null
+context_ref: null
+claim_branch: null
+work_branch: null
+write_paths:
+  - docs/tasks/T-002.md
+  - docs/raw/01-需求收集.md
+  - docs/01-vision.md
+  - docs/02-requirements.md
+  - docs/03-tech-stack.md
+  - docs/04-architecture.md
+  - docs/current-state.md
+---
+
+## 问题 / 背景
+
+`docs/raw/01-需求收集.md` §8 中仍有会改变架构、合规或工作量的问题。M0 出口要求关闭这些问题，否则 M1/M3 可能在错误假设上开发。
+
+## 关联需求与交互（如适用）
+
+- 用户故事：影响 US-001～US-006，具体由决策结果确定。
+- 交互清单：本任务不实现 UI；若决策改变 UI 范围，必须同步 IX。
+- 来源：`docs/raw/01-需求收集.md` §8 的 Q1、Q2、Q4–Q12。
+
+## 方案
+
+1. 为每个开放问题指定产品/客户/技术/法务责任人和最晚决策点。
+2. 记录选项、证据、决策、日期、批准人、受影响里程碑和撤销条件。
+3. 回填原始需求，并同步 harness 愿景、需求、技术栈、架构与当前状态。
+4. 仍不能关闭的问题必须转为明确 blocker，说明阻塞哪个任务和可继续的安全范围。
+
+## 不可变约束
+
+- 阈值 / 数值边界：默认 16、最大 128 的已定容量不在本任务中降级或改写。
+- 判定式 / 状态转换：没有责任人、证据和影响分析的口头意见不算“已关闭”。
+- 安全边界：法务、许可证、人脸和未成年人数据问题不得由 agent 代替授权人拍板。
+- 既有契约：事件 v0.1 字段不随开放问题原地修改；需要变化时单独发起契约版本任务。
+
+## 验收要点
+
+- 任务相关验证：Q1、Q2、Q4–Q12 每项有闭环记录或明确 blocker；摘要与原始文档一致；运行三条 harness 治理命令。
+- 完整门禁：若修改 schema/API/路由，触发对应契约与导航完整检查。
+- 人工 / 设备验收：必需；产品负责人确认范围，法务确认合规项，技术负责人确认架构影响。
+- 构建产物：不适用。
+
+## 边界（不改什么）
+
+不实现生产代码，不自行选择客户、前端框架、硬件或供应商，不修改已冻结事件契约。
+
+## 协作约束
+
+- 责任 Agent：由 dispatcher 分配。
+- 唯一写入者：同责任 Agent；外部责任人只提供决策和证据。
+- 委派：默认不启用。
+- Gitea：Issue 创建后回填；领取时写入 `context_ref`、claim 和工作分支。
+
+任何新增写路径先由 dispatcher 与活跃任务做前缀冲突检查。
+
+## 执行记录
+
+尚未领取。

docs/tasks/T-003.md

@@ -0,0 +1,70 @@
+---
+id: T-003
+title: 建立 Sense M1 接入骨架
+phase: 1
+deps: [T-001, T-002]
+status: TODO
+created: 2026-08-03
+issue: null
+context_ref: null
+claim_branch: null
+work_branch: null
+write_paths:
+  - docs/tasks/T-003.md
+  - Sense/
+  - docs/03-tech-stack.md
+  - docs/api.md
+  - docs/current-state.md
+  - init.ps1
+  - init.sh
+---
+
+## 问题 / 背景
+
+当前 `Sense/` 只有占位文件。M1 需要在不继承完整 MiBeeNvr 架构的前提下建立可持续演进的 Go 生产骨架，并正式引入 MediaMTX 数据面。
+
+## 关联需求与交互（如适用）
+
+- 用户故事：US-001、US-002。
+- 交互清单：本任务以 API/脚本为主，不实现正式 Web UI。
+- 架构：`docs/04-architecture.md`；详细目录见 `docs/raw/08-三系统职责划分.md`。
+
+## 方案
+
+1. 冻结 Go、SQLite 和 MediaMTX 的精确版本，记录许可证与升级策略。
+2. 建立 `cmd/sense-api` 与 `internal/onvif`、`store`、`mtx`、`reconcile`、`probe` 的最小目录和测试。
+3. 从 MediaMTX 官方 OpenAPI 生成客户端，手写代码只放薄封装。
+4. 设备台账先使用 SQLite，但 schema 语义与生产 PostgreSQL `sense` schema 保持一致。
+5. 跑通 5 路自动建 path、探活和断线重建的可重复集成测试。
+6. 将真实安装、验证和启动命令同步到标准入口与文档。
+
+## 不可变约束
+
+- 阈值 / 数值边界：验收 5 路；`site.max_video_channels` 默认 16、最大 128，必须测试 17/128/129 边界，不能把 5 或 16 写成架构上限。
+- 判定式 / 状态转换：数据库是期望态真相源；对账幂等、只收敛不跨系统回滚；配额不可用不影响已有流。
+- 安全边界：不提交摄像头凭据；调试/MediaMTX 管理端口不暴露到非可信网络；孤儿删除暂不实现或必须有 10% 安全闸。
+- 既有契约：M1 只动 Sense，不创建 Brain/Bell 业务代码；完整 MiBeeNvr 不进入依赖；MediaMTX 独立二进制。
+
+## 验收要点
+
+- 任务相关验证：`go test ./...`、`go vet ./...`、5 路集成 smoke、断线恢复测试，以及三条 harness 治理命令。
+- 完整门禁：公共 API、schema 或生成客户端变化时运行全部 Sense 测试和契约/迁移检查。
+- 人工 / 设备验收：必需；使用 T-001 白名单中至少一款设备验证 5 路流程，记录 MediaMTX 与探活证据。
+- 构建产物：Sense 二进制/镜像路径、生成命令和哈希在实施任务中冻结；本任务开工前补齐。
+
+## 边界（不改什么）
+
+不开发 Brain、Bell、正式管理端、规则引擎、人脸识别、64/128 路容量实现；不修改 `_reference/`。
+
+## 协作约束
+
+- 责任 Agent：由 dispatcher 分配。
+- 唯一写入者：同责任 Agent。
+- 委派：默认不启用；需要只读调研时结论先回填本文。
+- Gitea：依赖 T-001/T-002 均 DONE 后才可领取；领取时记录 `context_ref`、claim 和工作分支。
+
+任何新增写路径先由 dispatcher 与活跃任务做前缀冲突检查。
+
+## 执行记录
+
+尚未领取，依赖未完成。

docs/tasks/_template.md

@@ -0,0 +1,61 @@
+---
+id: T-XXX
+title: 一句话任务名
+phase: 1
+deps: []
+status: TODO
+created: 【日期】
+issue: null
+context_ref: null
+claim_branch: null
+work_branch: null
+write_paths:
+  - docs/tasks/T-XXX.md
+  - 【允许修改的仓库相对路径】
+---
+
+## 问题 / 背景
+
+（现象、根因、为什么要做）
+
+## 关联需求与交互（如适用）
+
+- 用户故事：【US-编号；无用户故事时说明原因】
+- 交互清单：【IX-编号；无 UI 时写不适用】
+- 相关页面 / 路由：【路径或不适用】
+
+## 方案
+
+（怎么改，落到“改哪个文件、改成什么”。复杂任务把确认后的规划结论写在这里，不只保留在对话中。）
+
+## 不可变约束
+
+- 阈值 / 数值边界：【具体值；无则写“无”】
+- 判定式 / 状态转换：【必须保持的规则；无则写“无”】
+- 安全边界：【不可绕过、不可自动执行的动作；无则写“无”】
+- 既有契约：【字段、接口、兼容性要求；无则写“无”】
+
+## 验收要点
+
+- 任务相关验证：【每次必跑的命令与预期证据】
+- 完整门禁：【触发条件、命令与预期证据；不触发时写明理由】
+- 人工 / 设备验收：【是否必需、执行角色、步骤与证据；不适用时明确写“不适用”】
+- 构建产物：【需要交接 / 部署时填写路径、生成命令和指纹；不适用时明确说明】
+
+## 边界（不改什么）
+
+（明确不碰的模块/流程）
+
+## 协作约束
+
+- 责任 Agent：【Agent 标识】
+- 唯一写入者：【默认同责任 Agent；项目显式启用委派时填写执行者】
+- 委派：【默认不启用；启用时写清只读探索者 / 执行者，并声明其继承本任务全部不可变约束、`write_paths` 和验证要求】
+- Gitea：【启用时填写对应 Issue、领取时的 `context_ref`、claim / 工作分支】
+
+任何新增写路径先检查与其他活跃任务是否重叠；同一时刻只有一个 Agent 修改本任务的 `write_paths`。
+
+## 执行记录
+
+（做完在此记录：改了哪些文件、跑的验证命令与结果、阻塞、关键决策。
+执行记录只写进本任务文件，不逐任务追加共享的 `progress.md`，避免多 agent 抢改共享文件。）