AGENTS.md@project-template · diff
git:20260919.8cff5ca to git:20261008.6d88ad6
23 added, 7 removed. Audit A to A.
# 项目协作规范（项目级模板）
> 项目级规范 + 项目组级规范引用。**开始任何任务前：先读本文件，再读项目组级规范。**
> 本文件是**唯一根级文档**，同时担任工作区索引：三大类目录索引见 §3。
- > 版本: v1.3 ｜ 最近修订: 2026-09-19 ｜ 变更记录见文末。
+ > 版本: v1.4 ｜ 最近修订: 2026-10-08 ｜ 变更记录见文末。
> **本文件是本项目的规范性规则，不是参考资料**——偏离按偏差处理，不按偏好权衡。
## 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），其余全部归入三大类；
+ > 根级只有本文件（AGENTS.md）这一份文档，加 `configs/` 这个**本地环境区**（本机环境与配置，
+ > 用户填、不入库）；其余内容全部归入三大类。
> **每个类别文件夹内自行维护内部索引（各自 README.md）**。
| 类别 | 目录 | 语义 | 子结构 |
|---|---|---|---|
+ | 零、本地环境 | `configs/` | 本机环境与配置（用户填，不入库） | 两份配置与它们的模板同目录：`project-config.toml`（非密钥）+ `.env`（密钥）；去掉 `.template` 后缀即实例名 |
| 一、输入素材 | `inputs/` | 项目获得的外部材料 | `user/`（用户提供：`materials/` 资源、`tools/` 工具）；`ai/`（AI 调研：`reports/` 报告、`data/` 数据）——均按文件类型/内容分组 |
- | 二、过程工程 | `process/` | 项目进行中的工程与文档 | `tmp/`（临时垃圾文件）；`project/`（正式工程：`scripts/`、`configs/`）；`docs/`（文档**实例区**，含 `docs/plans/` 目标书与计划书、`docs/spec-proposals/` 规约提案）；`templates/`（文档**模板区**，含 `templates/plans/`） |
+ | 二、过程工程 | `process/` | 项目进行中的工程与文档 | `tmp/`（临时垃圾文件）；`project/`（正式工程：`scripts/`）；`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` |
+ | 本地环境区（项目配置与密钥，用户填、不入库） | `configs/` |
+ ## 附：配置需求点（抄自组级 AGENTS.md §6；成对维护）
+
+ > **这是有标注的投影**，与 TOP 规则块、「闸 → 谁动手」同一手法：正文真源在组级 §6，
+ > 本节保证它在会话注入层里到场；组级 §6 改动时须**同一批**改本节。**不做开局体检**——
+ > 本地模式是合法默认，四个时刻各触发一次即可。
+
+ | 什么时候 | 需要什么 | 缺了会怎样 | 谁引导 / 谁写 |
+ |---|---|---|---|
+ | 第一次 git 远端操作前 | `configs/project-config.toml` 的 `[git] remote_url` | 空＝本地模式，合法；想推远端就必须问一次 | 制作人给一次卡片；值由用户给，文件由制作人落 |
+ | 第一次 commit | git 身份（组级 `user-config.toml`） | 项目未配 → 读组级 → 仍空 → 卡片 | 同上；组级文件在项目工作区之外，项目会话只读 |
+ | 第一次真的要访问某平台 | `configs/.env` 的平台键名 | 密钥空＝对应功能不可用 | 制作人说明「复制哪份模板、填哪些键」；**值由用户直接写入**，不经卡片 |
+ | 第一次从不同系统入口打开 | `[runtime] path_style` | 项目未配 → 读组级 | 制作人判定＋卡片确认，存盘一次 |
+
## 6. 规约反作用与文档初始化
- **反作用（修改规约）**：要分析/完善项目规约时，开一个**专用会话**（先读规约 → 分析完整性 →
讨论确认 → 按组级 AGENTS.md §9 流程落地）；日常干活会话不混入规约修改。
- **文档初始化**：`process/templates/` 为模板区（含格式示例）；`process/docs/` 实例骨架已预置，
填内容时参考对应模板；需要重置可复制模板（去掉 `.template` 后缀）覆盖实例。
- **本文件体量与指针化**：本文件会被 DSH 在**挂了注入模块的预设**里随会话开局注入
（连同项目根到工作目录沿途的全部 `AGENTS.md`，合计上限 65536 字节；**极简模式的组合里
没有注入模块，读不到本文件**）；超出预算时先整体丢弃较宽的文件、最后才截断最具体的
文件。因此本文件只做**索引与指针**：项目特有规则需要展开时，正文写进 `process/docs/`
下的独立文档，此处只留一行指向它；**禁止把组级规范正文复制进来**（第二份副本即分叉
- 起点，且会占满注入额度）。**唯一的例外是有标注的投影**：TOP 规则块与「附：闸 → 谁动手」
- 两节，它们显式写明抄自何处、以组级为准、改动时同批同步。参考上限：20 KB 以内。
+ 起点，且会占满注入额度）。**唯一的例外是有标注的投影**：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 逐条批准后落盘） |
+ | 2026-10-08 | v1.4 | `configs/` 从 `process/project/` 迁到**项目根**，列为第四类「本地环境」：§3 分类表加一行、表上那句改述为「根级只有 AGENTS.md 这一份文档 + 本地环境区」、`process/` 行去掉 configs、§5 导航改指 `configs/`；新增「附：配置需求点」——组级 §6 的**有标注投影**（四个触发时刻、谁引导谁写）。**为何通用**：三大类分的是"内容"（材料/过程/产物），而配置实例是"运行环境"，不属于任何一类；任何用本模板的项目都会撞上同一件事——配置放错区，归属就被"谁是这块路径的主人"带偏，且 gitignored 文件的越界在 diff 里看不见。**防的事故（频率×损失）**：新项目把配置留在工程产物区，写权归属靠位置推断而非判定（每个新项目一次，损失为越界争用与反复裁定）；用户不知道要手动复制模板去后缀，项目静默走本地模式、密钥到用时才发现（每个新项目一次，损失为上线前返工与"以为推了其实没推"） | 用户（2026-10-08 会话批准提案后落盘） |