# 工作原则与协作规范（AGENTS·项目组级）

> 本文件 = **项目组级公共规范**：位于 `project-group/shared-standards/`，被项目组内
> 各项目工作区**只读引用**（不随项目复制）。**开始任何任务前先读本文件。**
> 变更需用户确认；更新走提权通道（见 §8/§9）。
> 版本: v1.19 ｜ 最近修订: 2026-10-08 ｜ 变更记录见文末。

## TOP 规则（最高优先级，与其他内容冲突时以本块为准）

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

---

## 0. 协作模式（用户-代理）

- **用户**：负责战略方向与重点细节抉择；提供账号注册与权限管理；
  有权驳回请求并给出指引。
- **代理**：负责执行与落地；工作区维护；遵守领域互联网工程规范。
- **工作流程**（每项任务必须走完）：
  1. 先向用户了解工作内容与方向（不臆测，先问）；
  2. 写出详细计划书：待执行步骤 + 验收标准；
  3. 严格执行，**不主动降级任务目标**；
  4. 完成后验收并向用户汇报。
- **被驳回时**：不辩解硬闯，思考备用方案再提出；用户有思路时遵从用户指引。
- **咨询方式**：咨询/请示用户时**优先使用提问卡片**（ask_user_question，带选项，
  推荐项标注），便于快速回复；复杂情况卡片 + 简要文字结合。
- **对话人话化**：对用户的一切回复/卡片/总结用普通陈述句——结论先行、一段只说一件事、
  句子说完整。五条：
  1. **禁裸序号**：不得用内部序号（S0、u6、A002、DECISION-7 这类代号）作主要称呼——
     用户记不住，这不是人类沟通。一律用有含义的名称/主题指代（如「平台可观测性」
     工作单元、API 定价那条假设）；序号只用于文档内定位，对话中最多作括号补充。
  2. **说完整**：动词不省宾语——写「从社区仓库拉取代码」，不写「从社区拉」；不自造
     简称和外号——名词要能脱离当次对话被理解，指代一组事物时把名字列全。
  3. **标识符不翻译**：对话中出现的源代码标识符（包名、目录名、类型名、命令等）一律
     保留原文（如 `packages/core`、`loader`），中文只用于谈概念；把标识符译成中文会
     让用户去找一个不存在的名字。项目不含源代码时本条自然空转，不与任何条款冲突。
  4. **不说书腔**：不写对仗口号与警句体压缩句；比喻最多一个，且必须帮助理解。
     语气平实——不训人、不用反问句施压、不摆权威腔。
     信息正确不等于传达完成——用户一遍读完不费劲才算说完。
  5. **篇幅可伸缩（默认短答）**：结论放第一句；正文默认不超过 10 行；单句不超过 40 字，
     一句只说一件事，不靠逗号把多件事串成一句。长内容写进文档，对话里只留一行指针。
     不复述工具输出、文件原文与已做步骤的流水账。
     用户说「展开」「举例」「详细说」时放开行数，单句上限不变——详细体现在分点、
     例子与表格上，不体现在句子长度上。
  **适用范围**：以上五条只约束代理对用户对话的表达方式；交付物本身（文案、旁白、
  诗词、角色台词等）的文体按各项目自身规范执行，对话中整段引用交付文句不算违规。
- **对话中给用户的路径用当前系统的绝对路径格式**：Windows 系统写盘符 + 反斜杠
  （如 `C:\<任意目录>\<项目名>`），Linux/WSL 系统写斜杠路径（如 `/mnt/c/...`），
  一律用反引号包起，便于用户直接复制使用。运行系统属机器级事实：判定一次存入组级
  `user-config.toml` 的 `[runtime] path_style`（windows/posix），之后直接读档、
  不再逐次判断；仅当某项目从不同系统入口打开（如经 WSL）时，在项目级
  `project-config.toml` 同名条目覆盖（优先级沿用 §6：项目 → 组 → 卡片）。存量环境
  发现无记录时：判定 + 卡片确认后代填存盘，同样只存一次。本条只约束对话回复格式；
  文档/脚本仍按 §4 禁止本地绝对路径。
- **规范沉淀**：每次遇到"规则冲突/无规范可循"的情况，先查可查到的领域规范或
  咨询用户，然后归纳总结、把结论写入本文档或项目级 AGENTS/standards，形成积累。

## 1. 项目组定位

- 项目组：`<一句话项目组定位（例：AI 动画二创项目组）>`
- 成员项目：每个项目 = 一个**独立工作区**（与 shared-standards 同级的文件夹，
  由 `project-template` 复制改名而来，在 DSH 中单独打开）。
- 项目工作区按**三大类**组织：`inputs/`（输入素材）、`process/`（过程工程）、
  `outputs/`（输出产物），根级文档只有 AGENTS.md（三类索引见项目级 AGENTS §3）。
- 各项目 `inputs/ai/reports/` 下调研报告 = **市场调研 + 可行性分析**，不是工程方案，
  不是事实来源。

## 2. 核心工作原则

1. **怀疑态度**：报告中的每个数字都当成"待验证假设"，引用时必须标注假设 ID
   （见项目 `process/docs/assumptions.md`），不得直接作为事实写进方案。
2. **先问人，再搜网**：遇到无法判断或互相矛盾的信息，先问用户；用户不能准确回答时，
   上网搜索核实并附来源链接。
3. **实测优先**：涉及本机能力的结论，必须以真机实测为准；纸面估算只能作为预测，
   并在文档中标注 [ESTIMATED]。
4. **结论分层（强制范围）**：凡文档中出现数字、阈值、事实性结论，必须标注
   [MEASURED] 实测 / [ESTIMATED] 估算 / [UNKNOWN] 未知待定；涉及外部信息同时挂
   [ASSUMPTION-XXX]；纯流程/导航性描述不强制。
5. **定价敏感**：所有价格类信息随时变动，立项前必须重新询价；促销价不代表稳态价格。
   **询价只看官方渠道**（官网定价页/官方文档/官方客服）；第三方评测、自媒体文章、
   AI 生成内容一律不作定价与选型依据。
6. **引用文本保真**：产物中引用外部权威来源的文字——语法关键字、命令、接口名、标题、
   链接文本、版本号——必须**当场取自当前生效的权威源**（官方文档、目标文件本身），
   逐字照录，禁止凭记忆转写或自创简称；出货前以**产物本身**复验，复验手段按项目产物
   形态选定（渲染查看、编译执行、脚本抽查）。凭旧版本记忆书写规范、给链接编造别称，
   均属本条禁止项。

## 3. 已知不可靠内容（各项目登记见各自 process/docs/assumptions.md）

- 第三方价格评测、自媒体价格文章、AI 生成的价格/规格描述——不作定价与选型依据，以官方为准。
- `<项目组级已知不可靠内容，逐条列出>`

## 4. DSH 友好约定（工程协作格式）

- 所有文档：UTF-8（无 BOM）、Markdown、LF 换行。
  **换行靠仓库根 `.gitattributes` 强制**（`* text=auto eol=lf`，二进制类型单独标记）：
  只用 `core.autocrlf` 不够——Windows 上它的行为是「仓库 LF、工作区 CRLF」，与本条要求
  不一致；`eol=lf` 覆盖它，使仓库与工作区都为 LF。新建仓库模板时随附该文件。
- 文件名：小写字母 + 连字符（如 `working-principles.md`），不使用空格和中文文件名。
- 行宽：正文每行 ≤ 100 字符（表格除外），方便逐行读取。
- 标记约定（可 grep 检索）：
  - `[ASSUMPTION-XXX]` —— 引用项目 `process/docs/assumptions.md` 中的假设编号
  - `[TODO]` —— 待办
  - `[VERIFY]` —— 待核实（上网或问人）
  - `[MEASURED]` / `[ESTIMATED]` / `[UNKNOWN]` —— 结论类型
  - `[SOURCE?]` —— 缺来源
- 文件引用一律用相对路径。
- **落盘内容的通用性硬条件**：入库的一切内容须脱离具体项目、具体会话与具体领域仍可
  理解并执行——不得点名具体项目、引用某次会话原话、出现具体产物标题或本机目录安排，也不得
  写入只在单一技术栈或单一领域成立的做法；这类内容留在各项目自己的文档里。清洗、降级
  或改写掉的原委记入本文档变更记录表的"变更"列，条款正文不写。适用范围：写入本仓库的
  规约与模板。
- **禁止本地绝对路径**：文档/脚本中一律不出现用户本地绝对路径（如 `C:\...`、
  本地文件夹全名）；引用一律用项目相对路径或中性描述（如 `process/project/scripts/ctx.cjs`）。
- **审计检查范围**：做全文一致性/残留检查（grep/扫描）时，**必须覆盖隐藏文件与
  .gitignore 排除的文件**（如 `*.env`、`.gitignore` 本身、`secrets/` 等）——曾因只扫
  可见文件漏检 `.env` 旧注释；扫描工具需显式包含隐藏文件，不依赖默认通配符。
- 修改现有文件前先 read；新增文件用 write；小改动用 edit。
- 不要生成超长单行；大文档按小节组织，便于 grep 定位。
- **多行/非 ASCII 参数走文件**：向外部程序传多行文本或非 ASCII 文本（如提交说明、
  配置正文）时，先写入 `process/tmp/` 临时文件，再用该程序自带的文件入参选项传入
  （如 `git commit -F <文件路径>`）；不内联进单行 shell 命令。命令切换了工作目录时，
  注意临时文件路径的解析基准。
- **嵌入文本不手工拼接**：把文档正文作为字符串写进代码或工具参数时，使用所用语言原生
  的安全引用形式，不手工拼接转义；同一类引号/转义语法错误在同一会话出现两次，即停止
  重试拼字符串，改走上一条的文件传参路径。

## 5. 文件职责

| 层级 | 文件 | 职责 |
|---|---|---|
| 项目组级 | shared-standards/AGENTS.md | 本文件：项目组协作规范（只读引用） |
| 项目组级 | shared-standards/standards.md | 全局合规/工程规范与特色定制（横向） |
| 项目组级 | shared-standards/pipeline-and-roles.md | 多角色流水线（**可选能力**）：角色与写权表、**闸→角色映射（§1.1，模板 `AGENTS.md` 有其投影）**、单元文件夹传送带、做多了三档（§3.1）、降级层级、并行纪律与收单元七步切分（§5.1）；**启用多角色时读，单会话项目不必读** |
| 项目组级 | shared-standards/user-config.toml.template | 组级用户配置模板（实例 user-config.toml 本地填写，不入库） |
| 项目级 | AGENTS.md | 项目级规范 + 项目组级引用 + 三大类索引（唯一根级文档） |
| 项目级 | inputs/ | 一、输入素材（user/ 用户提供；ai/ AI 调研）；本区自维护 README 索引 |
| 项目级 | process/ | 二、过程工程（tmp/ 临时；project/ 正式工程；docs/ 实例区；templates/ 模板区）；本区自维护 README 索引 |
| 项目级 | outputs/ | 三、输出产物（按产物类型分组）；本区自维护 README 索引 |
| 项目级 | process/docs/assumptions.md | 假设清单（新增假设在此登记；含 `验证时机` 列） |
| 项目级 | process/docs/measurements.md | 真机实测记录 |
| 项目级 | process/docs/decisions.md | 决策记录（ADR） |
| 项目级 | process/docs/HANDOFF.md | 会话交接（新会话必读）；**含「用户职责表」**；多角色模式下变为静态路由器 |
| 项目级 | process/docs/progress.md | 进度看板（多角色模式下由制作人独占写） |
| 项目级 | process/docs/units/ | 单元文件夹（传送带）：`brief`/`build`/`accept` 各由固定角色写 |
| 项目级 | process/docs/handoff/ | 每角色一份接续索引（多角色模式下的接续点） |
| 项目级 | process/docs/work-log.md | 工作日志（全路径，含反复修改/失败） |
| 项目级 | process/docs/construction.md | 施工文档（只记成功步骤） |
| 项目级 | process/templates/ | 文档模板区（`<名>.template.md` 永为模板；实例=复制到 docs/ 去 `.template` 后缀） |
| 项目级 | process/docs/plans/goal-spec.md | 目标定义书（立项闸产物；6 字段，签名后基本不再增长） |
| 项目级 | process/docs/plans/plan.md | 计划书与门禁表（规划闸产物；活文档，按里程碑分段） |
| 项目级 | process/docs/spec-proposals/ | 规约修订成文提案（§9 D1 流程；批准实施后合并删除） |

**必读文档的读取方式（新增文档必须先归入一类）**：

| 读取类别 | 适用文档 | 规则 |
|---|---|---|
| 覆盖写（有界） | HANDOFF.md、plans/goal-spec.md | 描述"当前状态"的单值文档，每次重写不追加，天然有界 |
| 尾 N 行 | work-log.md | 流水中取尾部，明写 N 的值（接续闸取尾 10 行） |
| 索引 + 按需展开 | decisions.md | 头部维护索引区、每条一行；正文按需展开，接续闸只读索引区 |
| 分段读 | plans/plan.md | 只读当前段的完整门禁表；已完成段看折叠摘要（§7.2） |
| 按字段筛读 | assumptions.md | 全文读「近期可实测」与状态未定的条目；其余按索引引用 |
| 按步骤清单执行 | construction.md | 按步骤清单逐条执行（前置条件/命令或脚本/通过判据），不读叙述 |
| 全文必读 | 两级 AGENTS.md | 规范类锚点；项目级的体量与指针约束见 §6 |

> 新增文档时无法归入上表任一类，先补一条读取规则，再建文件。

## 6. 通用工作规则与项目组特色定制

**通用：**
- 启动工程方案前：先过一遍项目 `process/docs/assumptions.md`，标出会影响方案的关键假设。
- **假设登记义务（A1）**：任何新调研/新数字产出时，**先登记假设，再引用**；调研报告交付的
  同时更新 `process/docs/assumptions.md`——登记条目 = 调研收尾凭证，未登记 = 报告不算交付完成。
- **验证时机分层（A1b）**：假设登记时标注 `验证时机`：近期可实测 / 上线后验证 / 仅参考；
  "上线后验证"类在里程碑复盘统一到期检查，到期未验证的补验证或降级为"仅参考"。
- **决策记录（A2）**：命中下列任一即当天记 ADR 到 `process/docs/decisions.md`
  （与 work-log 同节奏），状态机：提议 → 已批准/已驳回/已废弃：
  ①方向/边界/排除项变化；②指标口径或成功判定变化；③成本上限/预算哲学变化；
  ④技术选型变更；⑤平台集合/渠道变更；⑥影响 ≥2 个单元或跨里程碑。
  **登记人**：单会话模式下由该会话登记；多角色模式下**只有制作人登记**——实现者与验收员的
  发现写在自己单元记录里的「候选决策与候选假设」一节（A1 的假设登记也走这一节回交制作人），
  由制作人判断哪些升格成 ADR、哪些升格成假设条目
  （见 `pipeline-and-roles.md` §2、§5）。
- **新会话接续**：先读项目 `process/docs/HANDOFF.md` + `process/docs/work-log.md`，
  再开始工作；重大决策记入项目 `process/docs/decisions.md`。

**项目组特色定制（全局适用，各项目默认遵守）：**
- **大文件下载规范**：凡需从外网下载大文件（模型权重等），一律由用户在主机执行下载
  （代理沙箱对大文件下载不可靠）。代理负责列出**下载表格**，每行至少含：
  `下载网址` + `下载后存储位置`（完整路径）。下载完成后用户告知，代理再继续。
- **选型规范**：一律选主流成熟方案，不选冷门小众的；除非双方共同确认现有效果不好，
  再由用户决定是否更换。自训微调产物除外。
- **提交习惯**：里程碑式成果或反复修改最终成功的大成果，第一时间总结
  （写进 work-log/decisions + 必要时施工文档），然后**提交 git = 推送到远端仓库**，
  不止本地 commit。真有问题再回滚或 fork 新分支。
- **资源约束**：本机资源紧张的任务不并行（以实测资源占用为准；冲突时由用户排定先后）。
- **施工文档约定**：交付版施工文档 `process/docs/construction.md` 只记录**成功实施步骤**
  （错改对的一步到位），使**换 AI/换工作目录也能从空文件夹复原当前项目进度**。
  ⚠️ 它与 **`process/docs/work-log.md`（每日实际施工日志，全路径，含反复修改/失败）是两份**，勿混。
- **重复动作脚本化**：同一动作第二次出现（人工/纸面重复操作、需复现的步骤），即落地为
  可执行脚本，放项目 `process/project/scripts/`，随 git 版本化。脚本须**可观测**：明确的
  入参/出参、日志输出、非零退出码标识失败。**日志分级**：
  - 关键结点（成功路径）：阶段转换、入参摘要、中间结果——详细记录，不一句带过；
    后续若出现错误，之前的关键成功日志是排错推理的重要依据；
  - 常规过程（成功路径）：简洁，不刷屏，不堆 debug 打印；
  - 错误路径：详尽——错误信息、触发上下文、当时输入状态，以"拿到日志就能排错"为目标。
  目的：减少模型重复推理、节约 token 用量、保证结果一致可复现；收单元验收时可用脚本
  复现替代口头描述。
- **项目级 AGENTS.md 的体量与指针化**：DSH 在**挂了注入模块的预设**里（标准/PTC/创造与自定义
  组合；极简模式的组合里没有这一模块，故不注入）把「用户全局 `AGENTS.md` +
  项目根到会话工作目录沿途的全部 `AGENTS.md`」作为一条基线消息注入，**上限 65536 字节**
  `[MEASURED]`（DSH `dsh-agent-instructions` 的 `maxBytes` 默认值）；超出时先整体丢弃
  较宽的文件、最后才截断最具体的文件，并在会话里留 `Workspace instruction budget ...`
  通知。因此：
  - 项目级 `AGENTS.md` 的定位是**索引与指针，不是手册**；项目特有规则需要展开时，
    正文写进 `process/docs/` 下的独立文档，本文件只留一行指向它。参考上限：本文件
    控制在 20 KB 以内，余量留给沿途嵌套 `AGENTS.md` 与用户全局指令。
  - **组级规范不受此上限约束**——它在项目根之外，永不参与这条注入，故不设字节上限；
    它的成本是代理主动读取时的 token，读几次付几次。
  - **禁止把组级规范正文复制进项目工作区**（与 §8 只读引用同源）：形成第二份副本
    即分叉起点，且会占满上面的注入额度。
- **并行前提（与上条资源约束配套）**：同一工作目录在同一时刻**只有一个活跃写入会话**
  ——`git checkout` 按工作目录生效（一个目录只有一个 HEAD），协作文档为追加或覆盖写，
  多会话并发会静默改变彼此的视图。需要并行时，先在计划书的单元定义里写明该单元
  预期触碰的文件与目录集合；两个单元的文件集不相交才可并行，相交即串行。
- **成本治理**：成本账目记 `measurements.md`（实测）+ `work-log.md`（每单元一行），
  不另开文档；预算总额在计划书（规划闸）确定；超预算 → 停止 + 卡片请示，不自动放行；
  询价结论先登记假设（状态=待询价），实测后转 [MEASURED]。
- **用户配置预留文件（两级，TOML）**：项目级 `process/project/configs/project-config.toml`
  （gitignored，**只含非密钥配置**：git remote、路径、偏好等）+ 组级
  `shared-standards/user-config.toml`（本地填写，.gitignore 排除，不入库；模板
  `user-config.toml.template` 入库）。
  **用户首次配置引导**：复制模板文件（**去掉 `.template` 后缀**）为实例文件并填写——
  组级 `user-config.toml.template` → `user-config.toml`；项目级
  `project-config.toml.template` → `project-config.toml`；未配置走空值逻辑/默认。
  **模板命名规则（统一）**：模板名 = 实例名 + `.template`；`.env` 这类点文件即
  `.env.template`。去后缀必须刚好得到实例名，不得把 `.template` 插在扩展名之前。
  **密钥统一存放**：平台 API 密钥等**只放 `configs/.env`**（gitignored；模板
  `.env.template` 入库），project-config.toml 不列密钥（见 standards.md §2）。
  **配置读取优先级：项目配置 → 组配置 → 卡片提示用户，由用户决定处理逻辑**。
  空值逻辑：`remote_url` 空 = 本地模式；git 身份项目未配 → 读组级 → 仍空 → 卡片；
  密钥空 → 对应功能不可用或卡片。
- **git 双模式**：远端模式（默认推荐：commit + push）与本地模式（仅本地 git，
  commit 即收尾）均合法，模式以 project-config.toml 的 `remote_url` 为准，
  会话中不留痕、不主动追问。**每次 git 操作前**先查 `git remote -v` 并向用户
  说明三问：①是否已设置远端？②是否仅提交本地？③是否已推送远端？——
  防止"以为推了其实没推"。commit 身份（user.name/email）取配置：项目 → 组 → 卡片。
- **里程碑复盘（D3）**：每里程碑（一轮 30 条优化闭环/单元组收完/用户指定）强制复盘：
  ①成功判定逐条打勾；②规约执行偏差清单（未遵守/写不清/执行不了）；
  ③偏差 → 修订提案（走 §9 D1 流程）；④纪要入 decisions + work-log；
  同时执行"上线后验证"假设的到期检查。
- **规则预算（新增规约的过滤器）**：新规则提案须附"防什么事故"说明（频率×损失）；
  无法说明具体事故的不采纳或降为建议。TOP 规则与四道闸为锚点，不参与筛选。

## 7. 门禁执行规范（四道闸·可执行版）

> 目的：门禁靠物理动作执行，不靠自觉。每条含"触发条件/具体动作/通过凭证/失败默认动作"。
> **多角色流水线是可选形态**（见 `pipeline-and-roles.md`）：单会话流程不受影响，
> 只有把同一项目拆成多个角色会话接力时才启用。

### 7.1 立项闸（新项目会话第一步，做完才能做别的）

1. 写项目 `process/docs/plans/goal-spec.md`，固定 6 个必填字段（缺字段不算写完）：
   - `成品形态`：一句话 + 一段让没参与的人能看懂最终成品长什么样的描述
   - `质量上限`：标杆是谁（贴具体链接/图，不许写"高质量"这类形容词）
   - `质量下限`：什么样的结果不可接受（具体到画面/时长/观感）
   - `渠道与受众`
   - `成功判定`：列 3 条事后能打勾的指标
   - `排除项`：明确不做的事
   - 字段可以"**原则级 + [VERIFY] 占位**"签署（方向承诺与细节充实解耦），细节由调研阶段回填。
2. 用提问卡片把 6 字段逐一请用户确认，用户答"通过"=签名。
3. 未签名 → 禁止执行任何后续动作（含调研）。

**目标书修订分级**：
- **字段级变更**（成品形态/渠道与受众/排除项/成功判定结构等）→ 需回到本闸**重新签名**；
- **细节充实**（指标字典版本升级、阈值校准等）→ 用户确认 + 记入 decisions/work-log，
  不必重签。

### 7.2 规划闸（目标签名后）

1. 请用户开 /plan 模式；写计划书并附门禁表（每行固定 4 列：
   `触发条件 | 通过凭证 | 通过后做什么 | 未通过默认动作（停止+卡片请示）`），
   用 exit_plan_mode 提交计划。
   **格式定义与示例在同一小节、同一版本块**（示例不同步更新的修订不予批准）。
   示例行：
   | 触发条件 | 通过凭证 | 通过后做什么 | 未通过默认动作 |
   |---|---|---|---|
   | 单元 U1 验收 | 门禁逐条打勾 + 成果入 work-log/construction + commit/push + 用户确认"通过" | 进入 U2 | 停止 + 卡片请示（修改或重做） |
   | 里程碑 1 结束 | 验收标准逐条打勾 + 决策回写 + 复盘纪要 + 总结推送 | 进入里程碑 2 | 停止 + 卡片请示 |
   | 门禁表全部行完成（计划耗尽） | 目标书「成功判定」逐条打勾的结论 + 用户卡片答复 | 全打勾 → 结项（§7.7）或开新目标书（回立项闸）；未全打勾 → 提交计划书增补并获批准后回执行闸 | 停止 + 卡片请示 |
   **分段与折叠**：门禁表按里程碑分段；已完成的段折叠成一行
   `里程碑 N：已完成 → 见 decisions 的 DECISION-XXX`，只让当前段保持完整 4 列。
   折叠是对计划书这一份活文档的编辑，不属 §7.3 禁止的"修改已提交内容"。
2. 计划书批准 = 用户在 /plan 里点批准；未批准禁止执行。

**决策↔计划书联动（A2b）**：
- 执行中决策：仅"影响验收标准/门禁表/指标口径"的决策须**当天同步计划书对应行**
  （1 行编辑）；背景方向类决策只记 ADR；
- **里程碑收尾全量回写（A 操作）**：该里程碑期间全部决策（含背景类）统一落进
  计划书/门禁表，保证 decisions ↔ 计划书完全对齐；顺序：①决策回写 → ②里程碑复盘 →
  ③总结+推送（TOP 规则 5）→ ④计划余量检查。
- **计划余量检查（A 操作第④步，不可跳过）**：看计划书门禁表还有没有未完成的行，
  三个分支：
  - 还有未完成行 → 照原计划继续执行闸；
  - 已耗尽、但目标书「成功判定」未全部打勾 → **卡片提议续编计划**，附建议的下一期
    里程碑草案与门禁表新行草案；用户批准后回执行闸；
  - 「成功判定」已全部打勾 → **卡片提议结项**（见 §7.7）或开新目标书（回立项闸重签）。
- **目标书 : 计划书 = 1 : N**：一个目标书可对应多期计划书。续编计划的入口判定直接
  复用 §7.1 的「目标书修订分级」，不新增闸：
  - 不触碰目标书 6 个字段 → 只过规划闸（提交计划书增补，exit_plan_mode 批准）；
  - 触碰字段级内容（成品形态/渠道与受众/排除项/成功判定结构）→ 回立项闸重签。

### 7.3 执行闸（每个工作单元循环）

- 工作单元定义写在计划书里，格式固定："一个可验收产出"
  （例：一个模型训练完成并通过验证）。
- **单元命名**：`u<序号>-<kebab-case 主题>`（小写+连字符），如 `u1-platform-observability`；
  分支 = 单元名；会话名 = `<单元名>-<YYYYMMDD>`。
- 开单元：`git checkout -b <单元名>` + 新开会话，会话名=`<单元名>-<日期>`。
- 收单元七步（逐条打勾，缺一不进入下一单元）：
  1. [ ] 对照计划书门禁表逐条验收打勾
  2. [ ] 成果写入 process/docs/work-log.md（表格一行）
  3. [ ] 成功步骤写入 process/docs/construction.md
  4. [ ] `git commit`（信息规范见下）
  5. [ ] `git push origin <分支名>`（远端模式；本地模式仅 commit，模式记入 HANDOFF）
  6. [ ] 提问卡片问"单元 X 验收通过？[通过/修改]"，用户通过才收
  7. [ ] 提议切新会话（见"切会话分工"）
- **commit 信息规范**（Conventional Commits 结构）：
  - 首行：`<type>(<单元名>): <一句话成果>`，如
    `feat(u1-platform-observability): 7平台可观测性核实+指标字典v1.1`
  - type 固定集：`feat`（新成果）/ `fix`（修复）/ `docs`（文档）/ `refactor`（重构）/
    `test`（测试）/ `chore`（杂务/脚本/配置）
  - body：单元收尾类提交**必写**（验收要点、关联 DECISION/ASSUMPTION 编号）；
    简单 chore 可省略
  - footer：GitHub 联动（`Fixes/Closes #N`）可选
- **上下文检查**：每个收尾检查点（单元收完/里程碑/长会话中途）运行上下文占用查询脚本
  （项目 `process/project/scripts/ctx.cjs`），占用 ≥60% → 走切会话收尾流程。脚本按会话身份
  定位数据，两条来源依次尝试：①DSH 原生投影缓存（`session_projcache`，与 DSH 界面上的
  上下文计量环同一数据源、同一口径）；②会话日志。**判据口径**：占用 = `projectedTokens
  ÷ contextWindow`，即"下一次请求的提示词预估长度"，与界面上那个百分数看得是同一个数；
  日志来源只能给"上一次请求的实际长度"，两者同一时刻有一两千 token 的差，**不要混用**。
  窗口一律取自会话记录里路由声明的真实值；两条来源都拿不到时脚本非零退出，此时改由用户
  看界面上的计量环读数（代理看不到界面）。
- **切会话分工**：
  - 代理（收尾方）：停手 → 更新 HANDOFF/work-log/decisions → git 提交 → 卡片提议 +
    给出"**新会话第一句话**"（可复制文本）；
  - 用户（接续方）：新建会话窗口 → 发第一句话 → 新会话自动走接续闸。
- 强制切会话触发条件（任一命中即停手、卡片提议切会话）：
  - 一个单元收完；当日已完成 ≥2 个单元；上下文占用 ≥60%（代理自测或用户提醒）；
    用户说收工
- **等待用户确认期间**（收单元第 6 步、卡片请示）：
  - 允许做"非冲突工作"：不依赖该决策的独立准备（下一单元调研、文档整理、无冲突脚本化）；
    非冲突工作**有界**——完成一项可验收的独立准备即回到等待；无非冲突工作时停止，
    不制造无效工作（不为填时间硬找事做）；
  - **禁止**：开新单元、修改已提交内容、任何越闸动作（闸没过完不进下一单元）；
  - 跨会话无回复：用户收工/新会话开始时，HANDOFF 记"挂起事项 + 等待的决策点 +
    恢复路径"，下个会话从该点继续。

### 7.4 接续闸（新会话第一步，固定顺序）

1. 读 process/docs/HANDOFF.md → 2. 读 AGENTS.md TOP 规则 →
   3. 读 process/docs/work-log 尾 10 行 + process/docs/decisions 索引
   → 4. 读 process/docs/plans/plan.md 的当前段门禁表（执行闸每步对照它，缺了没法判闸）
   → 5. 判断当前处于哪道闸、过闸凭证是否齐全，不齐先补。

### 7.5 文件职责补充

- 项目 `process/docs/plans/goal-spec.md`：目标定义书（立项闸产物，
  6 字段模板见 §7.1），任何项目立项前必写。
- 项目 `process/docs/plans/plan.md`：计划书与门禁表（规划闸产物，见 §7.2），
  执行闸每步对照它、接续闸读它的当前段；目标书与计划书为 1 : N 关系。

### 7.6 调研阶段（可选，立项与规划之间）

> 不是第五道闸，是轻量阶段；目标书细节已明确、无需调研的项目可跳过直接进规划闸。

- 触发：目标书签名后、规划闸前；需要充实目标书细节或为计划书铺路时进入。
- 范围："信息收集"类——平台可观测性、标杆池、互动基线、成本询价、合规核实等；
- 边界：**禁止工程实现**（不写代码、不搭系统）；所有数字须登记假设（A1）
  并标注结论分层；
- 退出凭证：调研报告交付 + 假设登记完整 + 用户确认调研结论；
- 失败默认：停止 + 卡片请示（未知项转 [UNKNOWN]/[VERIFY]，或由用户提供）。
- 产出物：调研报告入 `inputs/ai/reports/`；结论按修订分级回填目标书；登记假设。

### 7.7 结项闸（目标达成后的终态）

> 触发：目标书「成功判定」3 条全部打勾（通常由 §7.2 A 操作第④步的计划余量检查发现）。

1. 逐条打勾目标书「成功判定」，结论写入 work-log；
2. 全量回写：decisions 的未闭合项标记终态（已批准/已驳回/已废弃）；
3. 产出归档：`outputs/` 定版；施工文档 `construction.md` 定版（按 §6 只留成功步骤）；
4. 总结 + commit + push（并入 HANDOFF.md 与 decisions.md 书面记录）；
5. 卡片请示：**结项** 还是 **开新目标书**（开新目标书 = 回立项闸，重写 goal-spec）；
6. 结项后本工作区转为只读归档；要再动，开新目标书。

> 计划耗尽但目标未达成时**不结项**，走 §7.2 A 操作第④步的续编计划分支。

## 8. 依赖与更新规则（项目组级 ↔ 项目级）

- **引用**：各项目工作区的 `AGENTS.md` 第 0 节声明依赖本文件
  （相对路径 `../shared-standards/AGENTS.md`）。
- **新项目创建**：复制 `../project-template/` 到本文件夹同级（project-group 下）
  并改名，以**独立工作区**在 DSH 打开；`../shared-standards/` 相对路径自动成立。
- **只读**：本文件夹对各项目工作区只读（项目代理的写权限只覆盖本项目工作区）；
  项目不得把规范复制进工作区形成双份。
- **更新**：本文件夹规范由用户主导更新；代理需要更新时走**提权通道**——
  对越界写操作申请一次性权限并说明理由，经用户批准后执行。
- **优先级（两档制）**：
  - TOP 规则为最高优先级，**不可被项目覆盖**（动它们需用户主导）；
  - 其余组级条款为**默认值**：项目可覆盖，但须在项目级 AGENTS §2 显式写明覆盖条款
    与理由；覆盖若具通用性，走提权通道回写组级，不留隐性分叉。

## 9. 规约修订流程（D1）

> 规约自身的修改流程。入口：**反作用专用会话**——要分析/修改规约时，开一个专用会话
> （先读规约 → 分析完整性 → 讨论确认 → 按本流程落地）；日常干活会话不混入规约修改。

1. **提案**：修订动议。简单修订（单文件、文字级）会话内确认即可；复杂修订
   （跨文件、机制级、影响面大）写成文提案 = 现状问题 + 拟改条款原文 + 影响范围
   （组级/项目级/模板层），放项目 `process/docs/spec-proposals/`；
2. **批准**：用户确认。组级修订**必须用户明确批准**（代理只提案、不推动）；
   项目级修订用户确认即可；
3. **实施**：项目级 = 工作区内直接改；组级 = 提权通道改 shared-standards
   （发布/同步到远端由管理员自行决定执行）；
4. **版本化**：被改文件版本号 +1（见文末变更记录）；
5. **变更记录**：记入文件内变更记录表；含示例的条款必须同步更新示例
   （作为批准环节校验项）。变更记录须写明该条**为何具备通用性**（防什么事故、为何不
   只对单一场景成立）；说明不了的不落盘。通用性本身的判定属批准环节——组级按本流程第 2 步
   由用户确认，代理只提案、不推动。

## 变更记录

| 日期 | 版本 | 变更 | 批准 |
|---|---|---|---|
| 2026-08-27 | v1.0 | 首次版本化：调研阶段（§7.6）/目标书修订分级/决策↔计划书联动/脚本化+日志分级/成本治理/git 双模式/里程碑复盘/规则预算/修订流程（§9）/优先级两档制/结论分层强制范围/询价限官方/门禁表示例/切会话分工/commit 规范/上下文检查/敏感信息（standards） | 用户 |
| 2026-08-27 | v1.1 | git 双模式改为预留文件填写机制（process/project/configs/git-remote.md，会话中不留痕）；standards 同步 | 用户 |
| 2026-08-27 | v1.2 | 配置预留文件升级 TOML 两级：project-config.toml（项目）+ user-config.toml（组）；配置读取优先级=项目→组→卡片；空值逻辑；standards 同步 | 用户 |
| 2026-08-27 | v1.3 | 组级 user-config.toml 移至 shared-standards/（.gitignore 排除）；模板 user-config.template.toml 入库 | 用户 |
| 2026-08-27 | v1.4 | §4 新增「禁止本地绝对路径」：文档/脚本一律相对路径或中性描述 | 用户 |
| 2026-08-27 | v1.5 | §9 实施步骤措辞弱化：移除"回写 starter 仓库"通用表述（会话限定行为，非项目常驻义务），改为"发布/同步由管理员自行决定" | 用户 |
| 2026-08-27 | v1.6 | §6 用户配置条款补「首次配置引导」：复制模板（去 .template）为实例并填写 | 用户 |
| 2026-08-27 | v1.7 | §5 文件职责表补 templates 模板区（方案丙落地：docs 实例区 + templates 模板区） | 用户 |
| 2026-08-27 | v1.8 | §6 修正：密钥统一 configs/.env（toml 只含非密钥配置），消除 .env 与 [secrets] 双轨重复 | 用户 |
| 2026-08-27 | v1.9 | §4 新增「审计检查范围」：一致性/残留检查须覆盖隐藏与 .gitignore 文件（教训：.env 旧注释漏检） | 用户 |
| 2026-09-01 | v1.10 | §0 新增「对话人话化（禁裸序号）」+「对话路径按当前系统绝对路径格式」：对话回复禁用裸代号；路径按运行系统写可复制绝对路径；`path_style` 机器级判定一次存入组级 `user-config.toml`，项目级同名条目可覆盖（两个配置模板均已加字段；文档/脚本仍按 §4） | 用户 |
| 2026-09-08 | v1.11 | §0「对话人话化（禁裸序号）」更名为「对话人话化」并由单条扩为四条（禁裸序号/说完整/标识符不翻译/不说书腔）+ 补「适用范围」声明；§2 新增第 6 条「引用文本保真」；§4 新增「多行/非 ASCII 参数走文件」「嵌入文本不手工拼接」两条。防的事故（频率×损失）：对话中用裸代号与自造简称导致用户反复追问（每会话数次，直接拖慢决策）；产物引用凭记忆转写导致返工与错误扩散（跨里程碑复发，损失为整篇复验）；引号与转义冲突导致同类语法错误反复重试（同会话三次，损失为上下文与时间）。清洗说明：条款正文不含成员项目名、会话原话与具体产物标题，事故经过只记本表；单一语言/工具特有的写法不入模板 | 用户（2026-09-08 会话按 diff 逐条批准后落盘） |
| 2026-09-16 | v1.12 | 补闭环与通用性：§7.2 A 操作加第④步「计划余量检查」+ 目标书与计划书 1 : N + 门禁表末行「计划耗尽」与分段折叠；§7.4 接续闸补读计划书；§7.5 补 plan.md；新增 §7.7 结项闸；§5 计划书行拆分 + 新增必读文档读取方式分类；§6 新增项目级 AGENTS.md 体量与指针化（含 DSH 注入上限 65536 字节 [MEASURED]）、并行前提，并统一模板命名规则（模板名 = 实例名 + `.template`，三个配置模板改名回归该规则，standards.md 同步）。防的事故（频率×损失）：计划耗尽后无后继规则、代理只能停下等用户提（每个项目末期必发，损失为项目停摆与用户记忆负担）；接续闸不读计划书导致闸位判断缺据（跨会话每次）；协作文档无读取限量导致长项目里逐次全文读（每个项目末期必发，损失为 token 与判闸速度）；模板名与实例名的推导规则不自洽导致代理复制错方向（每次首次配置，损失为配置失败） | 用户 |
| 2026-09-16 | v1.13 | §4 换行条款补落地机制：新增仓库根 `.gitattributes`（`* text=auto eol=lf`，二进制类型单独标记），并写明为何只用 `core.autocrlf` 不够——Windows 上它是「仓库 LF、工作区 CRLF」，与本条要求的 LF 不一致；`eol=lf` 覆盖它。防的事故（频率×损失）：规范要求 LF 而工作区实际长期是 CRLF，同一文档在不同机器/不同会话里换行不一致，合并时出现整文件 diff（每次在 Windows 上提交都发生，损失为无意义的 diff 与逐行比对失效） | 用户 |
| 2026-09-16 | v1.14 | 补通用性硬条件与批准环节校验：§4 新增「落盘内容的通用性硬条件」（不得点名具体项目、引用会话原话、出现具体产物标题或本机目录安排，不得写只在单一技术栈/领域成立的做法；清洗原委只记变更记录表）；§9 第 5 步补「变更记录须写明为何具备通用性，说明不了的不落盘」，并明确通用性判定归批准环节、代理只提案不推动。**为何通用**：本条管的是"往开放模板里写什么"，与具体领域无关，任何用该模板的团队都需要；它填的是既有机制的缺口——§6 规则预算只过滤"值不值得立"，§8 只处理"项目能否覆盖"，都不管"这条脱离本场景是否还成立"。防的事故（频率×损失）：实例域内容（真实平台名、单一领域产物目录等）渗进开源模板，使用者继承不适用的假设（每建一个跨类型项目必发，损失为开局返工） | 用户 |
| 2026-09-16 | v1.15 | 新增**可选能力**：多角色流水线（独立成文 `pipeline-and-roles.md`，本文件只留指针）。§5 文件职责表补该文件与三个新项目路径（`progress.md`/`units/`/`handoff/`）；§6 A2 决策记录补「登记人」——多角色下只有制作人登记，实现者与验收员的发现写在自己单元记录里由其升格（消掉原条款对所有角色的"邀请"，避免与角色边界冲突）；§7 声明多角色为可选形态、单会话流程不受影响。防的事故（频率×损失）：长会话里角色边界被工具结果裁剪吃掉，导致实现者/验收员去写制作人的共享文档并静默覆盖（引入多角色后必发，损失为记录丢失与返工）；多会话并发写同一批文件（引入并行后必然发生，损失为返工） | 用户 |
| 2026-09-18 | v1.16 | §0「对话人话化」由四条扩为五条：第 4 条补「语气平实」（不训人、不用反问句施压、不摆权威腔）；新增第 5 条「篇幅可伸缩（默认短答）」——结论放第一句、正文默认 ≤10 行、单句 ≤40 字、一句只说一件事、长内容写进文档、不复述工具输出与已做步骤的流水账，并给「展开/举例/详细说」留放开行数的入口（单句上限不随展开放开）。**为何通用**：篇幅约束只作用于代理对用户说话这一层，与项目领域无关；换模型只换一种啰嗦法，说明缺口在指令层而非模型层，任何用该模板的团队都受同一问题困扰；默认值与放开入口成对出现，故不牺牲需要细说的场景。防的事故（频率×损失）：默认输出过长导致用户反复重读或要求二次解释（每会话数次，损失为阅读时间与决策速度，且随会话累积） | 用户 |
| 2026-09-19 | v1.17 | **更正一处说过头的话**：§6「项目级 AGENTS.md 的体量与指针化」原写"DSH 每次会话开局注入"，实测不成立——预设的组合就是它自己那份组合文件点名的插件（0.2.1 起该文件为预设声明里的 `config.plugins`，见 `presets/`），极简模式（`minimal`）的组合里没有注入模块，故**完全不注入**（标准/PTC/创造与自定义组合都有这一行）。现给注入加限定"挂了注入模块的预设"。连带：§5 文件职责表的 pipeline 行补上「闸→角色映射（§1.1，模板有其投影）」「做多了三档（§3.1）」「收单元七步切分（§5.1）」三项新内容；§6 A2 的「候选决策」一节扩为「候选决策与候选假设」，与 `pipeline-and-roles.md` §2 同步（A1 的假设登记在实现者侧的出口）。**为何通用**：本条只更正"工具能力"的事实描述，与项目领域无关；任何用该模板的人都需要知道"哪一层真的会到场"，否则会把规矩写在到不了的地方。**防的事故（频率×损失）**：按"任何预设都会注入"设计约束落点，导致极简模式下整套文档约束一句都不生效而使用者毫不知情（每次有人换模式一次，损失为静默失守）；A1 与 §6 A2 两处措辞不一致导致实现者不知该在哪登记（每次实测出数，损失为假设漏登或被越界写） | 用户 |
| 2026-10-08 | v1.18 | §7.3「上下文检查」补全数据来源与判据口径：占用值改由 DSH 原生投影缓存读取（与 DSH 界面上的上下文计量环同一数据源、同一口径），会话日志降为兜底，并写明脚本非零退出时改由用户读界面计量环。**为何通用**：本条只管"怎么量一个百分比"，与项目领域、产物类型无关；量法依赖的是 DSH 自身的公开投影，凡是按本模板建的项目都跑在同一套机制上。**防的事故（频率×损失）**：原条款只说"运行查询脚本"，未写口径与来源，而同一时刻"下一次请求预估"与"上一次实际长度"相差一两千 token（本机实测 26.51% vs 26.54%、10.71% vs 10.84%），照错的那个判 60% 会过早或过晚切会话（每个收尾检查点都在，损失为一次多余的切会话或一次超阈值继续跑）；脚本原先依赖一个已被 DSH 删除的环境变量，无参运行必然失败而条款仍写着"运行脚本"（一直静默失效） | 用户 |
| 2026-10-08 | v1.19 | **预设分发方式随 DSH 变更**：预设不再是「复制文件夹到 DSH 预设目录」，而是一个**组合包**（bundle），装进 profile 后在选择器里出现三条独立声明（制作人 / 实现者 / 验收员）。连带更正：v1.17 变更记录里"预设的组合就是它自己 `agent.cordis.yml` 点名的插件"引用的是已不存在的文件名，改为按当前机制表述（预设声明里的 `config.plugins`）。**为何通用**：本条只更正"预设从哪来、怎么装"这一机器事实，与项目领域无关；任何用该模板的人都要按当前 DSH 的方式装角色预设，否则照旧文档装不上。**防的事故（频率×损失）**：按已失效的目录复制法操作，三个角色预设装不上且选择器里不出现，使用者以为是自己操作有误（每个新使用者必发一次，损失为开局卡住与反复排查） | 用户 |