AGENTS.md@project-template git:20260919.8cff5caA

Immutable. This exact content never changes and is served at /api/v1/blob/7ee91a27e8d7bfe2.

# 项目协作规范（项目级模板）

> 项目级规范 + 项目组级规范引用。**开始任何任务前：先读本文件，再读项目组级规范。**
> 本文件是**唯一根级文档**，同时担任工作区索引：三大类目录索引见 §3。
> 版本: v1.3 ｜ 最近修订: 2026-09-19 ｜ 变更记录见文末。
> **本文件是本项目的规范性规则，不是参考资料**——偏离按偏差处理，不按偏好权衡。

## 0. 项目组级规范（依赖声明）

- 位置：`../shared-standards/AGENTS.md`（与本工作区同级、在工作区之外，**只读引用**）。
- **路径基准（全项目统一）**：本文件与配套文档里出现的一切路径，**一律相对项目根**
  （即本工作区根目录）。这样文档无论被移到哪一层都不会失效。
- 该文件**不在本工作区内**，因此 DSH 的会话指令注入不会包含它——本文件只是指向它，
  由代理按需读取；引用一律相对路径，不复制正文（见 §6 指针化条款）。
- 本文件夹由 `project-template` 复制而来：新项目 = 复制本文件夹到 project-group 下
  并改名，以**独立工作区**在 DSH 打开；`../shared-standards/` 相对路径自动成立。
- 优先级（两档制）：项目组级 TOP 规则为最高优先级、**不可覆盖**；其余组级条款为
  默认值，本项目覆盖时须在本文件 §2 显式写明理由；冲突时以项目组级规范为准。
- 更新项目组级规范：本工作区无写入权限（workspace-write 只覆盖本工作区）；
  需要更新时走**提权通道**——对越界写操作申请一次性权限并说明理由，
  经用户批准后执行；日常使用一律只读，不合并目录、不复制双份。

## TOP 规则（抄自项目组级规范，压缩后仍存活；细节以项目组级规范为准）

1. 未签目标书不立项；未批计划书不执行。
2. 一个单元=一个分支=一个会话；收单元七步打勾缺一不可。
3. 请示用户一律用提问卡片。
4. 闸没过完禁止进入下一单元。
5. 里程碑完成第一时间总结+推送到远端仓库。

## 附：闸 → 谁动手（抄自组级 `../shared-standards/pipeline-and-roles.md` §1.1；冲突以组级为准）

> **这是有标注的投影**，与上方 TOP 规则块同一种手法：本节保证这张表在会话开局就在注入层里，
> 正文真源在组级文件；组级 §1.1 改动时须**同一批**改本节。
> 单会话模式（默认）：下表"谁动手"整列都是当前这一个会话——看它只为认路，不新增约束。
> 多角色模式：角色名就是写权归属；动手前先确认自己在哪一行、上一行交给谁。
> **极简模式读不到本节**（它的预设组合没有注入模块）——见组级 `pipeline-and-roles.md` §4 地板。

| 闸 / 阶段 | 谁动手 |
|---|---|
| 立项闸 | **制作人**（用户卡片签名） |
| 调研阶段（非闸，可选） | **制作人**为主；实测可交实现者跑，结论回制作人登记 |
| 规划闸 | **制作人**（用户在 /plan 批准） |
| 执行闸 · 开单元 | **制作人**（写 `brief.md`，状态「已交底」） |
| 执行闸 · 施工 | **实现者**（写产物 + `build*.md`） |
| 执行闸 · 验收 | **验收员**（写 `accept.md`，不改产物） |
| 执行闸 · 收单元七步 | **制作人**（第 4 步各角色提交自己路径；第 5 步制作人 push） |
| 执行闸 · 返工 | **制作人出增补 → 实现者动手 → 验收员复验** |
| 接续闸 | **每个角色自己**（会话第一步，先定角色） |
| 里程碑复盘（非闸） | **制作人** |
| 结项闸 | **实现者先定版 `outputs/` → 制作人再定版文档、总结、push** |

> 记法：**定方向与记账 = 制作人，动产物 = 实现者，下判断 = 验收员。**

## 1. 项目定位（占位）

- 项目：`<一句话项目定位>`
- 当前阶段：`<当前阶段>`

## 2. 本项目特有规则（项目级补充，冲突以项目组级规范为准）

- `<占位：本项目特色规范，遇新规则沉淀于此>`

## 3. 目录分类索引（三大类）

> 根级文档只有本文件（AGENTS.md），其余全部归入三大类；
> **每个类别文件夹内自行维护内部索引（各自 README.md）**。

| 类别 | 目录 | 语义 | 子结构 |
|---|---|---|---|
| 一、输入素材 | `inputs/` | 项目获得的外部材料 | `user/`（用户提供：`materials/` 资源、`tools/` 工具）；`ai/`（AI 调研：`reports/` 报告、`data/` 数据）——均按文件类型/内容分组 |
| 二、过程工程 | `process/` | 项目进行中的工程与文档 | `tmp/`（临时垃圾文件）；`project/`（正式工程：`scripts/`、`configs/`）；`docs/`（文档**实例区**，含 `docs/plans/` 目标书与计划书、`docs/spec-proposals/` 规约提案）；`templates/`（文档**模板区**，含 `templates/plans/`） |
| 三、输出产物 | `outputs/` | 交付与沉淀成果 | 产物类型由本项目自定：**先在本区 README 登记一行，再建同名子目录**；不预置类型 |

- `process/tmp/`：可随时清空；归档/打包时整体剔除。
- `process/templates/` 为文档**模板区**（`<名>.template.md` 永为模板）；`process/docs/` 为
  **实例区**（实例骨架已预置，填内容参考 templates/ 对应模板，可随时复制覆盖重置）。
- 合规与工程规范（standards.md）在项目组级：`../shared-standards/standards.md`。

## 4. 状态

- [ ] 目标定义书（process/docs/plans/goal-spec.md）已填写并签名
- [ ] 计划书（process/docs/plans/plan.md）已批准
- [ ] `<项目阶段清单>`

## 5. 快速导航

| 目的 | 位置 |
|---|---|
| **新会话接续** | `process/docs/HANDOFF.md` |
| **项目组级规范（只读）** | `../shared-standards/AGENTS.md` |
| 工作日志 | `process/docs/work-log.md` |
| **★施工文档（交付版）** | `process/docs/construction.md` |
| 决策记录 | `process/docs/decisions.md` |
| **目标定义书** | `process/docs/plans/goal-spec.md` |
| **计划书与门禁表** | `process/docs/plans/plan.md` |
| 进度看板（多角色模式） | `process/docs/progress.md` |
| 单元文件夹与角色交接 | `process/docs/units/`、`process/docs/handoff/` |
| **多角色流水线规约（组级，只读）** | `../shared-standards/pipeline-and-roles.md` |
| 假设登记 | `process/docs/assumptions.md` |
| 实测记录 | `process/docs/measurements.md` |
| 文档模板区（格式参考） | `process/templates/` |
| 规约修订提案 | `process/docs/spec-proposals/` |
| 项目配置（用户填） | `process/project/configs/project-config.toml` |

## 6. 规约反作用与文档初始化

- **反作用（修改规约）**：要分析/完善项目规约时，开一个**专用会话**（先读规约 → 分析完整性 →
  讨论确认 → 按组级 AGENTS.md §9 流程落地）；日常干活会话不混入规约修改。
- **文档初始化**：`process/templates/` 为模板区（含格式示例）；`process/docs/` 实例骨架已预置，
  填内容时参考对应模板；需要重置可复制模板（去掉 `.template` 后缀）覆盖实例。
- **本文件体量与指针化**：本文件会被 DSH 在**挂了注入模块的预设**里随会话开局注入
  （连同项目根到工作目录沿途的全部 `AGENTS.md`，合计上限 65536 字节；**极简模式的组合里
  没有注入模块，读不到本文件**）；超出预算时先整体丢弃较宽的文件、最后才截断最具体的
  文件。因此本文件只做**索引与指针**：项目特有规则需要展开时，正文写进 `process/docs/`
  下的独立文档，此处只留一行指向它；**禁止把组级规范正文复制进来**（第二份副本即分叉
  起点，且会占满注入额度）。**唯一的例外是有标注的投影**：TOP 规则块与「附：闸 → 谁动手」
  两节，它们显式写明抄自何处、以组级为准、改动时同批同步。参考上限：20 KB 以内。
- **先确定你的角色**（任何预设都适用）：本项目按角色分工。若你是用**角色预设**启动的，
  角色已由 persona 给定，直接采用；否则**先用提问卡片请用户指定角色**，再往下走。
  三个角色（制作人 / 实现者 / 验收员）的**写权范围、做多了三档、各闸读档顺序**在组级
  `../shared-standards/pipeline-and-roles.md` 里——那是唯一真源，本文件除「附：闸 → 谁动手」
  那一节有标注的投影之外，不复制它的正文。
  **多角色是可选能力**：不用角色时按单会话流程走组级 `AGENTS.md` §7，本文件同样适用。
- **项目内技能**：`.agents/skills/project-flow/SKILL.md` 是本项目的操作技能（开局触发、
  给出读档顺序）。技能只做触发与指针，正文仍在上述组级文件里。
  项目级技能根有两个（`.dsh/skills` 与 `.agents/skills`，DSH 均自动发现），本项目选后者：
  `.dsh` 是用户级 harness home（`~/.dsh`）的目录名，项目级再用它会让项目资产与工具状态同名。
- **并行前提**：同一工作目录同一时刻只有一个活跃写入会话（`git checkout` 按目录生效、
  协作文档为追加或覆盖写）；需要并行时，先在计划书的单元定义里写明该单元预期触碰的
  文件与目录集合，文件集不相交才可并行（见组级 AGENTS.md §6）。

## 变更记录

| 日期 | 版本 | 变更 | 批准 |
|---|---|---|---|
| 2026-09-16 | v1.0 | 首次版本化：补版本头与变更记录；§0 修正相对路径描述并注明组级规范不参与会话注入；§3 补 `docs/plans/`、`docs/spec-proposals/`、`templates/plans/` 并改为产物类型不预置；§5 补目标书、计划书、假设、实测四行；§6 新增本文件体量与指针化、并行前提 | 用户 |
| 2026-09-16 | v1.1 | 顶部补「本文件是本项目的规范性规则，不是参考资料」（不依赖任何预设的效力声明）；§5 导航补进度看板、单元文件夹与角色交接、组级多角色规约三行；§6 新增「先确定你的角色」（任何预设都适用：由 persona 给定或提问卡片确认）、指向组级唯一真源、声明多角色为可选能力，并补项目内技能 `project-flow` 的位置与"只做触发与指针" | 用户 |
| 2026-09-19 | v1.2 | §6 项目内技能路径 `.dsh/skills/` → `.agents/skills/`，并写明选择理由（项目级技能根有两个，`.dsh` 是用户级 harness home 的目录名）。**为何通用**：本条只管"项目内智能体资产用哪个目录名"，与项目领域、技术栈无关；`.dsh` 撞名是 DSH 自身的命名事实，任何用该模板的项目都受同一影响。防的事故（频率×损失）：项目级 `.dsh/` 与用户级 `~/.dsh` 同名，容易被读成"工具状态目录"；为防该误读而设的 `.gitignore` 规则（`.dsh/*` + `!.dsh/skills/`）会把该目录下除技能外的文件**静默**排除出 git（每建一个新项目都在，损失为文件静默不入库）。改用 `.agents/` 后该规则整条删除，项目资产默认入库 | 用户 |
| 2026-09-19 | v1.3 | ①新增「附：闸 → 谁动手」一节——组级 `pipeline-and-roles.md` §1.1 的**有标注投影**，手法与 TOP 规则块相同（写明抄自何处、冲突以组级为准、改动同批同步），目的是让这张表在会话开局的注入消息里就到场，而不是等代理去读第三份文档；单会话模式下整列都归当前会话，本节对它只起认路作用。②§6「本文件体量与指针化」按实测加限定：注入只发生在**挂了注入模块的预设**里，**极简模式读不到本文件**；并把"禁止复制组级正文"的例外明确为"有标注的投影"。③§6「先确定你的角色」相应说明本文件除该投影外不复制组级正文。**为何通用**：任何用本模板的人都要回答"这条规矩放在哪一层才会到场"，投影与反双份的边界（无标注副本 vs 有标注投影）是机制问题，与领域无关。**防的事故（频率×损失）**：新会话开局不知道该谁动手，只能先读三份文档才敢动，读序一断就停下来等用户（多角色每次换角色会话一次，损失为等待与越界）；按"每个预设都会注入"设计落点导致极简模式静默失守（每次有人换模式，损失为约束完全不生效） | 用户（2026-09-19 会话按 diff 逐条批准后落盘） |