@wneng/create-keel 0.1.0

package/src/templates/docs-skeleton/files/archive-README.md

@@ -0,0 +1,20 @@
+# archive/
+
+退役文档归档。
+
+> 子目录划分属于**软建议**——见 [`docs/README.md`](../README.md) §5.2。
+
+## 何时进 archive/
+
+- 被否决的方案
+- 90 天未采纳的过程文档
+- 已过期 / 已被新版替代的正式文档（保留供溯源）
+
+## 归档约定
+
+- 文件名加日期前缀：`YYYY-MM-原文件名.md`
+- 可选：在文件顶部加一行"已归档：原因"
+
+## AI 触达模式
+
+`mode: read-only`。归档文档**不应被修改**。如需更新，应当作"新文档"放回对应编号目录。

package/src/templates/docs-skeleton/files/archive-_ai-policy.yaml

@@ -0,0 +1,8 @@
+# docs/archive/_ai-policy.yaml
+# 依据 ADR-0003 §4.3
+
+mode: read-only
+
+notes: |
+  退役文档归档。AI 可读作为历史参考，但永不写入；
+  如需更新，应当作"新文档"放回对应编号目录。

package/src/templates/docs-skeleton/files/assets-README.md

@@ -0,0 +1,29 @@
+# assets/
+
+图片、图表源、插图的归属目录。
+
+> 区别于 `docs/design/`：design/ 是**设计真值**（Figma 主线、UI 规范）；assets/ 是**叙事文档里的插图**（架构图、流程截图、Logo 等）。
+
+## 子目录
+
+| 目录 | 内容 |
+|------|------|
+| `diagrams/` | 架构图、时序图源（draw.io、Excalidraw、PlantUML 源） |
+| `images/` | 截图、Logo、其他位图 |
+| `design/` | UI 设计稿（如未启用 design 角色，临时也可放这里；启用 design 角色后建议迁到 `docs/design/`） |
+
+## 引用方式
+
+在 markdown 文档中相对引用：
+
+```md
+![架构总览](../assets/diagrams/architecture.drawio.svg)
+```
+
+## Git LFS
+
+若仓库启用了 `gitLfs`，二进制资源（PSD / 大图 / PDF）走 LFS。规则见 [`../governance/assets.md`](../governance/assets.md)。
+
+## AI 触达模式
+
+`mode: read-only`。AI 不修改资产文件；插图由作者自行维护。

package/src/templates/docs-skeleton/files/assets-_ai-policy.yaml

@@ -0,0 +1,8 @@
+# docs/assets/_ai-policy.yaml
+# 依据 ADR-0003 §4.3
+
+mode: read-only
+
+notes: |
+  图片、图表源、插图。AI 可读作为上下文，但不修改资产文件。
+  完整资产规则见 docs/governance/assets.md。

package/src/templates/docs-skeleton/files/be-README.md

@@ -0,0 +1,29 @@
+# 04-后端详细设计
+
+后端模块详细设计的归属目录。
+
+> 子目录划分属于**软建议**——见 [`docs/README.md`](../README.md) §5.2。
+
+## 一个模块一篇
+
+每个后端模块（用户中心、订单、消息推送等）对应一份详细设计文档。建议命名：`<模块名>.md` 或 `<模块名>/index.md`（多文件时用目录）。
+
+> **特性关联**：若该模块对应一个跨层级特性（有 PRD），文件名使用统一 **slug**（同 [`docs/01-背景与需求/prd-<slug>.md`](../01-背景与需求/) 与 [`docs/05-前端客户端详细设计/<slug>-*`](../05-前端客户端详细设计/) 对齐）。完整规则见 [`../README.md`](../README.md) §6。
+
+## 典型内容
+
+- 模块职责与边界
+- 依赖的契约锚点（`contracts/openapi/api.yaml#/...`、`contracts/events/...`）
+- 数据模型（指向 `contracts/dictionaries/`）
+- 内部状态机（指向 `contracts/states/`，如有）
+- 关键流程与时序
+- 性能 / 安全 / 可观测性考量
+- 测试要点（指向 `docs/07-质量与测试/test-plans/`，如启用 qa 角色）
+
+## 与 contracts/ 的边界
+
+契约说**接口形态**；本目录说**内部实现思路**。两者通过锚点链接，**不复制**契约内容。
+
+## AI 触达模式
+
+`mode: suggest`。AI 在契约或代码变更时提示影响范围，由后端开发定稿。

package/src/templates/docs-skeleton/files/be-_ai-policy.yaml

@@ -0,0 +1,8 @@
+# docs/04-后端详细设计/_ai-policy.yaml
+# 依据 ADR-0003 §4.3
+
+mode: suggest
+
+notes: |
+  后端模块详细设计。AI 在契约变更时提示同步；
+  设计文档由后端开发定稿，AI 不自动改主线。

package/src/templates/docs-skeleton/files/bg-README.md

@@ -0,0 +1,21 @@
+# 01-背景与需求
+
+PRD、需求调研、竞品分析的归属目录。
+
+## 建议子目录（非强制，按项目调整）
+
+> 子目录划分属于**软建议**——见 [`docs/README.md`](../README.md) §5.2。
+
+- `prd/`：产品需求文档（按版本或主题命名）
+- `research/`：用户调研、行业调研
+- `competitive/`：竞品分析
+
+正式 PRD 进本目录；草稿 / 讨论 / 未定稿进 `docs/过程文档/drafts/`，结论固化后再回迁。
+
+## 命名约定（特性关联）
+
+跨层级特性使用同一 kebab-case **slug**；本目录的 PRD 文件名固定为 `prd-<slug>.md`。slug 一旦确立**不改名**。完整规则见 [`../README.md`](../README.md) §6。
+
+## AI 触达模式
+
+`mode: suggest`。AI 在相关变更时仅在 PR 描述中提示影响范围，**不自动改**主线——产品 / 业务负责人是真值源。

package/src/templates/docs-skeleton/files/bg-_ai-policy.yaml

@@ -0,0 +1,8 @@
+# docs/01-背景与需求/_ai-policy.yaml
+# 依据 ADR-0003 §4.3
+
+mode: suggest
+
+notes: |
+  PRD、调研、竞品分析。产品 / 业务是真值源；
+  AI 在相关变更时仅在 PR 描述中提示，不自动改主线。

package/src/templates/docs-skeleton/files/eng-README.md

@@ -0,0 +1,21 @@
+# 03-工程规范与研发基础设施
+
+编码规范、CI/CD 说明、环境管理、本地开发指南的归属目录。
+
+> 子目录划分属于**软建议**——见 [`docs/README.md`](../README.md) §5.2。
+
+## 典型内容
+
+- 编码规范（语言、框架、命名、提交）
+- CI/CD 流水线说明（与 `docs/governance/ci.md` 互补：governance 是规则，本目录是落地说明）
+- 本地开发环境（依赖版本、端口、调试）
+- 环境矩阵（dev / staging / prod 差异）
+
+## 与 `docs/governance/` 的边界
+
+- `governance/` 是**跨项目通用规则**（CI 校验矩阵、Git 工作流、安全 SLA 等）
+- 本目录是**项目专属落地**（具体的 lint 规则、本地启动步骤）
+
+## AI 触达模式
+
+`mode: suggest`。规范变更影响面广，需要工程负责人确认；AI 在相关变更时仅 PR 描述提示。

package/src/templates/docs-skeleton/files/eng-_ai-policy.yaml

@@ -0,0 +1,9 @@
+# docs/03-工程规范与研发基础设施/_ai-policy.yaml
+# 依据 ADR-0003 §4.3
+
+mode: suggest
+
+notes: |
+  编码规范、CI/CD 落地说明、环境管理。
+  与 docs/governance/ 互补（governance 是规则，本目录是落地说明）。
+  规范变更影响广，AI 仅在 PR 描述中提示，不自动改主线。

package/src/templates/docs-skeleton/files/fe-README.md

@@ -0,0 +1,31 @@
+# 05-前端客户端详细设计
+
+前端 / 客户端模块详细设计的归属目录（覆盖 `web/`、`mobile/`、`miniapp/`、`agent/` 各自的功能模块）。
+
+> 子目录划分属于**软建议**——见 [`docs/README.md`](../README.md) §5.2。
+
+## 一个模块一篇
+
+按"功能 + 平台"组织，例如：
+
+- `auth-web.md`（Web 端登录）
+- `auth-miniapp.md`（小程序登录）
+- `chat-mobile.md`（移动端聊天）
+
+或者按平台分子目录（`web/auth.md` `mobile/auth.md`），按团队习惯选。
+
+> **特性关联**：若模块对应一个跨层级特性（有 PRD），文件名前缀使用统一 **slug**（同 [`docs/01-背景与需求/prd-<slug>.md`](../01-背景与需求/) 与 [`docs/04-后端详细设计/<slug>*`](../04-后端详细设计/) 对齐），如 `<slug>-web.md` / `<slug>/web.md`。完整规则见 [`../README.md`](../README.md) §6。
+
+## 典型内容
+
+- 模块职责与边界
+- 调用的契约锚点（`contracts/openapi/api.yaml#/...`）
+- 路由 / 页面结构
+- 状态管理（Redux / Pinia / signals 等）
+- 关键交互流程
+- 设计稿引用（指向 `docs/design/`，如启用 design 角色）
+- 测试要点（指向 `docs/07-质量与测试/`，如启用 qa 角色）
+
+## AI 触达模式
+
+`mode: suggest`。AI 在契约或代码变更时提示影响范围，由前端 / 客户端开发定稿。

package/src/templates/docs-skeleton/files/fe-_ai-policy.yaml

@@ -0,0 +1,8 @@
+# docs/05-前端客户端详细设计/_ai-policy.yaml
+# 依据 ADR-0003 §4.3
+
+mode: suggest
+
+notes: |
+  前端 / 客户端（web/mobile/miniapp/agent）模块详细设计。
+  AI 在契约或代码变更时提示影响范围，由前端 / 客户端开发定稿。

package/src/templates/docs-skeleton/files/governance-README.md

@@ -0,0 +1,28 @@
+# governance/
+
+本目录承载根 `AGENTS.md` 拆出的细化政策（依据 ADR-0001）。每个文件解决一个特定主题，**互不依赖**——所有跳转入口只从 `AGENTS.md` 单向进入。
+
+## 文件清单
+
+| 文件 | 主题 | 维护频率 |
+|------|------|----------|
+| `ci.md` | 完整 CI 校验矩阵与工具命令 | 中 |
+| `security.md` | 依赖安全、漏洞扫描、许可证、SBOM、应急响应 | 中 |
+| `git-workflow.md` | 分支、提交、PR 模板、CODEOWNERS | 低 |
+| `assets.md` | Git LFS 配置、阈值、命名 | 低 |
+| `docs-references.md` | `docs/references/` 来源元数据规则 | 极低 |
+| `integrations.md` | 集成对接完整规则与维护义务 | 中（启用时） |
+| `deploy-ops.md` | `ops/` 与 `deploy/` 完整边界与示例 | 中 |
+| `tools-scripts.md` | `tools/` 与 `scripts/` 完整规则、升级判定 | 低 |
+| `ai-access-modes.md` | AI 访问模式（五档）与 `_ai-policy.yaml` schema | 中（依据 ADR-0003） |
+| `checklists.md` | 完整检查清单（开发 / 提交 / 发布 / 多应用 / 新增工具） | 高 |
+
+## 维护规则
+
+- 每个文件顶部含 `last-reviewed: YYYY-MM-DD` 元数据；超过 6 个月未更新 CI 给出警告。
+- 修改任何文件**必须**在同一 PR 内更新根 `AGENTS.md` 中对应摘要 / 入口（PR 模板已强制 checkbox）。
+- 文件间**不得相互引用**；所有跳转入口只从 `AGENTS.md` 单向进入。如发现强耦合，说明根 AGENTS.md 漏了这个层级。
+
+## 权威映射
+
+完整的"主题 → 唯一权威"对照表见根 [`AGENTS.md`](../../AGENTS.md) §7。本文件不重复维护以避免双写漂移。

package/src/templates/docs-skeleton/files/governance-_ai-policy.yaml

@@ -0,0 +1,13 @@
+# AI 访问策略：docs/governance/
+# 依据 ADR-0003 §4.3
+mode: strict
+on-trigger:
+  - "AGENTS.md"
+  - "docs/governance/**"
+sync-action: required-sync
+human-review-required: true
+notes: |
+  governance/ 与根 AGENTS.md 必须同步。任何 governance 内的修改 PR
+  必须同时更新 AGENTS.md 中对应摘要 / 入口；任何 AGENTS.md 修改
+  PR 必须同时更新对应 governance 文件。strict 模式下，AI 在检测到
+  这两侧之一变化时主动同步另一侧。

package/src/templates/docs-skeleton/files/governance-ai-access-modes.md

@@ -0,0 +1,324 @@
+---
+last-reviewed: <%= it.generatedAt.slice(0, 10) %>
+---
+
+# AI 访问模式（access modes）
+
+> 本文件是 ADR-0003 的权威细则。任何变更需先修订 ADR，再回写本文件。
+>
+> 本规则与 ADR-0001 §6 按需加载索引互补：按需加载解决"AI 应该读什么"，本规则解决"AI 应该写什么 / 不写什么 / 怎么写"。
+
+## 1. 概念基础：产物所有权
+
+仓库里所有产物按"**谁是真值产生者**"分三类：
+
+| 类别 | 真值源 | 例子 | 默认应配 mode |
+|------|--------|------|--------------|
+| **人主导**（Human-authored） | 人是真值源；AI 协助但不自决 | PRD、ADR、设计 | `suggest` 或 `on-demand` |
+| **共同协作**（Co-authored） | 人和 AI 来回迭代，最终人定稿 | 后端 / 前端模块设计、集成对接 | `suggest` |
+| **AI 派生**（AI-derived） | AI 是日常产生者；上游变了应主动同步 | `contracts/`、`<lang>/generated/`、宣发草稿 | `generated` 或 `strict` |
+
+不同所有权决定 AI 的写入边界。**产物所有权是设计访问模式的第一原则**。
+
+## 2. 五档触达模式
+
+每个目录 / 文件通过 `_ai-policy.yaml` 声明触达模式。
+
+| 模式 | 真值源 | AI 可读 | AI 可主动写 | 触发条件 | 典型场景 |
+|------|--------|---------|-------------|---------|---------|
+| `strict` | AI（确定性算法） | ✅ | ✅ 直接覆盖主线，禁止手改 | 上游变 → 立即重生成；CI 校验 diff 为空 | `<lang>/generated/`、规则书面版本 bump |
+| `generated` | AI（基于上游推导） | ✅ | ✅ 写主线，允许手改作为下次输入 | 上游变 → 主动更新 | `contracts/`、宣发 `drafts/` |
+| `suggest` | 人 + AI 共写，人定稿 | ✅ | ❌（仅 PR 描述提示）| 上游变 → PR 描述写"可能影响 X，请确认" | 大部分 docs/、业务代码（默认） |
+| `on-demand` | 人 + AI（节奏由人控） | ⚠️ 默认不读 | ⚠️ 触发关键词后才写 | 用户显式说出 trigger-keyword | 宣发主线、客户专属部署 |
+| `read-only` | 外部 / 历史 | ✅ | ❌ | 永不写 | `references/`、`archive/`、`assets/` |
+
+### 2.1 关键区分
+
+**`strict` vs `generated`**：
+- `strict` 隐含"人不应直接改主线，否则下次重生成会冲掉"——典型如 `<lang>/generated/`
+- `generated` 允许人修改主线（作为下次迭代的输入），AI 在下次生成时考虑这些人工修订
+
+**`generated` vs `suggest`**：
+- `generated` AI 主动写主线（人审稿）
+- `suggest` AI 不自动写，仅 PR 描述提示
+
+**`generated` vs `on-demand`**：
+- `generated` 上游变 → AI 主动同步
+- `on-demand` 必须人喊触发关键词才动
+
+**`on-demand` vs `read-only`**：
+- `on-demand` 用户主动要求时可以写
+- `read-only` 永远不写
+
+### 2.2 核心规则
+
+- **默认 `suggest`**：未声明 `_ai-policy.yaml` 的目录默认是 suggest。这是最安全的中间档。
+- **就近覆盖**：子目录的 `_ai-policy.yaml` 覆盖父目录。
+- **`strict` 与 `generated` 必须显式声明**：这两档允许 AI 写主线，绝不允许通过"默认或继承"获得（继承父目录的 generated 是允许的，但顶层声明必须显式）。
+- **`generated` 必须有 `source-of-truth`**：AI 主动维护必须知道上游是谁。
+- **`on-demand` 必须有 `trigger-keyword`**：用户说什么 AI 才能动。
+
+## 3. `_ai-policy.yaml` Schema
+
+```yaml
+# ---- 必填字段 ----
+mode: strict | generated | suggest | on-demand | read-only
+
+# ---- generated 模式必填 ----
+source-of-truth:                # 上游真值源（glob 列表）
+  - "docs/01-背景与需求/**"
+  - "docs/02-系统方案与架构/**"
+
+# ---- on-demand 模式必填 ----
+trigger-keyword: "更新宣发"     # 字符串或字符串数组；用户必须说出才能触发 AI 写
+# 或：
+# trigger-keyword:
+#   - "更新宣发"
+#   - "刷新对外材料"
+
+# ---- strict 模式必填 ----
+on-trigger:                     # 触发条件（路径 glob 或 keyword）
+  - "contracts/openapi/**"
+sync-action: required-sync      # required-sync | required-record | required-bump
+
+# ---- 推荐字段（所有模式可用）----
+last-aligned-with:              # 上次对齐到的上游状态（generated 必填，初始可为 null）
+  source-commit: "abc1234"      # 或 null（首次未对齐）
+  contracts: "v1.2.0"
+  features: ["用户中心 v3"]
+  aligned-at: "2026-05-15"
+human-review-required: true     # 即使触发，AI 改完也必须人审
+
+# ---- 自由说明 ----
+notes: |
+  自由文字，给 AI 与人类协作者看的额外上下文。
+```
+
+### 3.1 文件命名
+
+- 文件名固定为 `_ai-policy.yaml`
+- 前缀 `_` 与本仓库其它惯例（`_source.yaml`、`_template.md`）一致
+- Jekyll / Hugo 等 SSG 默认忽略 `_` 前缀
+
+### 3.2 多关键词支持
+
+`trigger-keyword` 可以是单个字符串或字符串数组。多关键词等价（任何一个都能触发）。
+
+```yaml
+mode: on-demand
+trigger-keyword:
+  - "更新宣发"
+  - "刷新市场材料"
+  - "regenerate marketing"
+```
+
+### 3.3 `last-aligned-with` 初始值
+
+`generated` 模式下，新创建的目录可以暂时让 `source-commit: null`。第一次 AI 生成时由 AI 填入实际 commit。
+
+```yaml
+mode: generated
+source-of-truth: ["docs/01-背景与需求/**"]
+last-aligned-with:
+  source-commit: null
+  aligned-at: null
+```
+
+### 3.4 `expire` 字段（明确不支持）
+
+不支持触发关键词的过期机制。每次会话视为新的一次触发；AI 不应跨会话"记得"权限。
+
+## 4. 现有目录的默认模式分配
+
+按"产物所有权"维度分配。每个分配都遵循 ADR-0001 既有的目录定位。
+
+### 4.1 contracts/（AI 派生 → generated）
+
+```yaml
+# contracts/_ai-policy.yaml
+mode: generated
+source-of-truth:
+  - "docs/01-背景与需求/**"
+  - "docs/02-系统方案与架构/**"
+last-aligned-with:
+  source-commit: null
+  aligned-at: null
+human-review-required: true
+notes: |
+  contracts/ 是 AI 派生区：AI 根据需求与架构文档主动维护契约。
+  人可以编辑契约（作为下次 AI 生成的输入语境），但应当走 PR
+  让架构组评审契约的合理性。
+  下列子目录有局部覆盖：
+  - tests/acceptance/   suggest（Gherkin 是人表达业务）
+  - tests/contracts/    suggest（消费端驱动，本仓库不主动）
+  - README.md           suggest（人写说明）
+```
+
+子目录覆盖：
+
+| 路径 | 模式 | 理由 |
+|------|------|------|
+| `contracts/README.md` | suggest（局部覆盖） | 人写的目录说明 |
+| `contracts/CHANGELOG.md` | 继承 generated | AI 写条目草稿，人定稿 |
+| `contracts/openapi/` | 继承 generated | AI 主动维护 |
+| `contracts/dictionaries/` `states/` `errors/` `events/` `environment/` | 继承 generated | 同上 |
+| `contracts/resources/examples/` `mocks/` | 继承 generated | 接口变 → 示例自动重写 |
+| `contracts/tests/acceptance/` | suggest（局部覆盖） | Gherkin 人表达业务 |
+| `contracts/tests/contracts/` | suggest（局部覆盖） | Pact 由消费端驱动 |
+| `contracts/tests/postman-collections/` | 继承 generated | 接口变 → 集合更新 |
+
+### 4.2 各模块的 generated/ 子目录（机器派生 → strict）
+
+| 路径 | 模式 |
+|------|------|
+| `server/generated/`（如有） | strict |
+| `web/generated/` `mobile/generated/` `miniapp/generated/` `agent/generated/` | strict |
+
+`strict` 隐含人不应手改这些目录的内容；下次重生成会冲掉手改。CI 校验 `git diff --exit-code generated/`。
+
+### 4.3 docs/（人主导或共写）
+
+| 路径 | 模式 | 理由 |
+|------|------|------|
+| `docs/01-背景与需求/` | suggest | PRD 由产品负责 |
+| `docs/02-系统方案与架构/` | suggest | ADR 历史决策；新 ADR 由人发起 |
+| `docs/03-工程规范与研发基础设施/` | suggest | 规范变更影响广 |
+| `docs/04-后端详细设计/` | suggest | 契约变更时 AI 提示同步 |
+| `docs/05-前端客户端详细设计/` | suggest | 同上 |
+| `docs/06-集成对接/` | strict | pair 存在时**必须**同步 |
+| `docs/governance/` | strict | 与 AGENTS.md 必须同步 |
+| `docs/assets/` | read-only | 资产不应被 AI 直接动 |
+| `docs/references/` | read-only | 外部资料 |
+| `docs/archive/` | read-only | 历史归档 |
+| `docs/过程文档/` | suggest | 草稿区，AI 可在此处生成新内容 |
+
+### 4.4 应用代码与配置
+
+| 路径 | 模式 |
+|------|------|
+| `server/`（除 generated/） | suggest |
+| `web/` `mobile/` `miniapp/` `agent/`（除 generated/） | suggest |
+| `ops/` `deploy/` `tools/` `scripts/` | suggest |
+| `.kiro/` `.codex/` `.cursor/` `.claude/` | suggest |
+
+### 4.5 元规则
+
+| 路径 | 模式 |
+|------|------|
+| `AGENTS.md` | strict |
+| 任意 `_ai-policy.yaml` 自身 | 隐含 strict（架构组守门，CODEOWNERS 守护） |
+
+## 5. 双闸门：高风险目录的特殊保护
+
+`docs/11-市场与对外材料/`、`docs/08-部署与现场实施/` 等"对外或不可逆"目录在 on-demand 之上再加一层结构隔离。
+
+### 5.1 双闸门结构（以宣发为例）
+
+```
+docs/11-市场与对外材料/
+├── _ai-policy.yaml              # mode: on-demand
+├── templates/                   # 母版
+│   └── _ai-policy.yaml          # mode: read-only（局部覆盖）
+├── drafts/                      # AI 生成草稿
+│   └── _ai-policy.yaml          # mode: generated（局部覆盖）
+└── published/                   # 正式对外版本
+    └── _ai-policy.yaml          # mode: read-only（局部覆盖）
+```
+
+**双闸门约束**：
+
+1. AI 触发更新 → 只能写在 `drafts/`
+2. 市场负责人审核 → 手动 `git mv drafts/x.pptx published/`
+3. AI **永远不能**直接写 `published/`
+
+`drafts/` 用 `generated` 而非 `on-demand`：父目录 on-demand 的触发关键词被说出后，drafts/ 这一档允许 AI 主动写。这是**双层授权**：先关键词，再 drafts/ 写。
+
+### 5.2 类似模式应用
+
+- `docs/08-部署与现场实施/`：
+  - `templates/` → read-only
+  - `customer-<id>/` → read-only（已交付不动）
+  - `customer-<id>/.pending/` → generated（待应用的更新）
+- `docs/10-合规与安全/`：
+  - `evidence/` → read-only（提交后不改）
+  - `assessments/` → suggest
+
+## 6. AI 行为约束
+
+### 6.1 strict 模式
+
+- AI 检测到 `on-trigger` 中列出的路径变更，立即重新生成
+- 主线被覆盖；之前的人工修改如果存在，**会丢失**
+- CI 校验 `git diff --exit-code` 必须为空
+- 适用于**人不会修改、机器算法决定全部内容**的产物
+
+### 6.2 generated 模式
+
+- AI 检测到 `source-of-truth` 中列出的路径变更，主动更新主线
+- 主线允许人修改；AI 下次生成时把人的修改作为输入语境
+- PR 应自动打 `auto-generated` 标签（与 `ai-generated` 协同）
+- `human-review-required: true` 强制人审通过才能合并
+- 每次更新后必须更新 `last-aligned-with.source-commit` 与 `aligned-at`
+
+### 6.3 suggest 模式
+
+- AI 检测到上游变更影响本目录时，**仅在 PR 描述中提示**："本变更可能影响 docs/04-后端详细设计/auth.md，请确认是否需要同步"
+- AI 不自动 edit 本目录的文件
+- 这是默认档；最常用
+
+### 6.4 on-demand 模式
+
+- AI 默认**不读不写** on-demand 目录
+- 用户必须显式说出 `trigger-keyword` 才触发 AI 行为
+- 触发后 AI 可以读取并写入；写入路径如有双闸门则受 §5 限制
+- AI 行为完成后**不"记忆"权限**；下一次会话需要重新触发
+
+### 6.5 read-only 模式
+
+- AI 可以读取作为上下文
+- AI 永不写入；任何尝试视为漏标违规
+- 只有架构组在显式 PR 中可以写入（人手工）
+
+## 7. governance-lint 校验规则
+
+| 检查 | 严重度 |
+|------|-------|
+| `_ai-policy.yaml` 可被 schema 解析 | error |
+| `mode` 在五档之内 | error |
+| `mode: generated` 缺 `source-of-truth` | error |
+| `mode: on-demand` 缺 `trigger-keyword` | error |
+| `mode: strict` 缺 `on-trigger` 或 `sync-action` | error |
+| 没有 `_ai-policy.yaml`（默认 suggest） | warning |
+| `last-aligned-with.aligned-at` 过期 > 90 天 | warning |
+| `mode: generated` 且 `last-aligned-with.source-commit` 落后于上游 > 7 天 | warning |
+
+实现：`tools/governance-lint/` 扩展，新增 `--check-access-modes` flag（默认开启）。
+
+## 8. PR 模板更新
+
+`docs/governance/git-workflow.md` 中的 PR 模板加一段：
+
+```markdown
+## AI 触达模式合规
+
+- [ ] 本 PR 没有触及 on-demand 或 read-only 目录
+- [ ] 本 PR 触及了 on-demand 目录，且我已在 PR 标题或 description 中说明触发关键词与人工审核结果
+- [ ] 本 PR 触及了 read-only 目录，违反规则——已说明特殊豁免理由（需架构组批准）
+- [ ] 本 PR 触及了 generated 目录（contracts/ 等），相应 last-aligned-with.source-commit 已更新
+```
+
+## 9. AGENTS.md 联动
+
+§5 文档归属表加一列 "AI 触达模式"。§6 按需加载索引后追加 §6.4「AI 触达模式（access modes）」精简介绍 + 指向本文件的链接。详细联动见 ADR-0003 §6。
+
+## 10. 风险与对冲
+
+| 风险 | 表现 | 对冲 |
+|------|------|------|
+| AI 不读 `_ai-policy.yaml` | 仍按 §6.1 路径触发表大改 | AGENTS.md §2 不可协商原则中加入；让所有 AI 工具默认遵守 |
+| 用户忘了说 trigger-keyword 但 AI 仍主动改 | on-demand 失效 | governance-lint 在 PR 中检测路径，违反就阻断 |
+| 配置漂移：目录搬移时 `_ai-policy.yaml` 漏带走 | AI 误判模式 | governance-lint 检查每个目录是否有 policy 文件 |
+| 过度严格导致 AI 协作低效 | 用户每次都要说关键词 | 默认 suggest 已经是中间档；只有少数目录需要 on-demand |
+| `_ai-policy.yaml` 本身被 AI 误改 | meta 失控 | policy 文件本身的 mode 隐含为 strict（架构组守门） |
+| `generated` 模式下 AI 生成质量差 | 反而增加返工 | human-review-required: true 强制人审；CI 在 PR 阶段拦截 |
+| `source-of-truth` 上游漂移 AI 没察觉 | last-aligned-with 过期 | governance-lint 7 天 warning，90 天 error |

package/src/templates/docs-skeleton/files/governance-assets.md

@@ -0,0 +1,50 @@
+---
+last-reviewed: <%= it.generatedAt.slice(0, 10) %>
+---
+
+# 资产与大文件策略
+
+## LFS 触发阈值
+
+- `docs/assets/` 中**单文件超过 1 MB** 的二进制文件
+- 即使低于阈值，下列扩展名也强制走 LFS：`*.psd` / `*.sketch` / `*.fig` / `*.afdesign`
+
+## `.gitattributes` 模板
+
+```
+* text=auto eol=lf
+*.sh text eol=lf
+*.ps1 text eol=crlf
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.pdf binary
+
+# Git LFS（启用 LFS 的项目）
+docs/assets/**/*.png filter=lfs diff=lfs merge=lfs -text
+docs/assets/**/*.psd filter=lfs diff=lfs merge=lfs -text
+docs/assets/**/*.sketch filter=lfs diff=lfs merge=lfs -text
+docs/assets/**/*.fig filter=lfs diff=lfs merge=lfs -text
+```
+
+## 优先级
+
+1. 文本格式图表源（PlantUML / Mermaid / drawio XML / excalidraw JSON）→ 不进 LFS
+2. 必须导出二进制时，**同时**保留源文件
+3. 截图考虑压缩（pngquant / jpegoptim）后再入仓
+
+## 命名约定
+
+- `docs/assets/diagrams/<module>-<concept>.<ext>`，例：`auth-flow.drawio`
+- `docs/assets/images/<context>-<index>.<ext>`，例：`onboarding-01.png`
+- `docs/assets/design/<feature>-<state>.<ext>`，例：`login-error.fig`
+
+## 引用规则
+
+文档中引用资产用相对路径：
+
+```markdown
+![登录流程](../assets/diagrams/auth-flow.png)
+```
+
+不允许直接引用 LFS pointer URL。