docs: add AI propositions and scripts governance (#35)

* docs: architecture - document scripts control plane * docs: readme - add AI propositions --------- Co-authored-by: tradecatlabs <288998340+tradecatlabs@users.noreply.github.com>
2026-07-27 18:57:50 +00:00 · 2026-06-12 13:09:25 +08:00
parent 667ff384e0
commit 004ecadcc0
2 changed files with 89 additions and 2 deletions
@@ -48,6 +48,7 @@
 </p>

 [☯️ 道法术器](#dao-fa-shu-qi)
+[🧠 Vibe Coding 的三条底层命题](#ai-three-propositions)
 [📌 字多不看](#root-tldr)
 [⚡ 1 分钟快速开始](#getting-started)
 [🚀 从零开始完整入门](docs/getting-started/learning-map.md)
@@ -64,6 +65,18 @@

 </div>

+<a id="ai-three-propositions"></a>
+
+## 🧠 Vibe Coding 的三条底层命题
+
+> **一、先解决人与 AI 的协作问题，再用 AI 解决其他可表达、可拆解、可约束、可验证的问题。**
+>
+> **二、模型能力会吞噬一切为弥补模型不足而存在的中间层。**
+>
+> **三、生成物可达，即模型能力可达。**
+
+这三句话是本仓库理解 AI 编程的底层口径：先把人机协作、任务表达、约束和验证机制固定下来；再承认当前很多 Prompt、工作流、Agent 编排、索引、外部记忆和脚手架只是模型能力不足时的工程补丁；最后把大语言模型的能力边界定义为它的生成物能够直接或间接实现、驱动、约束、修改、验证或影响的范围。
+
 <a id="root-tldr"></a>

 <details>
@@ -850,7 +850,21 @@ repo/
 │
 ├── shared/                              # 极薄共享层：无业务语义的库、SDK、测试夹具
 ├── tools/                               # 开发工具、代码生成、迁移工具
-├── scripts/                             # 自动化入口和门禁脚本
+├── scripts/                             # 仓库控制面：本地开发、CI、生成、发布、迁移和质量门禁入口
+│   ├── README.md                        # 脚本总索引：分类、入口、运行方式和风险边界
+│   ├── AGENTS.md                        # Agent 操作边界：可自动跑、需确认和禁止执行的脚本
+│   ├── manifest.yml                     # 脚本登记表：owner、类型、风险、输入、输出和 CI 状态
+│   ├── checks/                          # 只读质量门禁：lint、link、schema、security、policy
+│   ├── generate/                        # 写仓库的生成/同步脚本：TOC、schema、代码生成、索引重建
+│   ├── bootstrap/                       # 环境准备、工具安装、版本探测和依赖缓存
+│   ├── ci/                              # CI 适配层；只做编排，不承载核心逻辑
+│   ├── release/                         # 发布、版本、打包和 changelog；高风险
+│   ├── ops/                             # 迁移、修复和一次性维护脚本；必须支持 dry-run 和审计
+│   ├── dev/                             # 本地开发便利脚本；不默认进入硬门禁
+│   ├── lib/                             # 共享库；导入无副作用
+│   ├── fixtures/                        # 脚本测试数据
+│   ├── tests/                           # 脚本自身测试
+│   └── archive/                         # 已下线脚本；保留原因、替代入口和删除日期
 ├── tests/                               # 跨域集成测试、契约测试和仓库门禁
 ├── docs/                                # 人类可读文档，不替代 contracts/catalog/governance
 └── .github/ or ci/                      # CI 工作流入口
@@ -869,6 +883,7 @@ repo/
 | `governance/` | 标准、决策、门禁、风险和复盘真相 | 业务代码 |
 | `infra/` | 云资源、运行环境、安全、网络和灾备真相 | 业务逻辑 |
 | `shared/` | 无业务语义的薄复用真相 | 领域模型和业务流程 |
+| `scripts/` | 仓库自动化入口、质量门禁和维护操作真相 | 业务规则、生产配置、长期平台产品逻辑 |

 这套目录结构的核心不是“所有企业都必须照抄这些文件夹”，而是把不同生命周期、不同 owner、不同风险等级的资产分开。目录名可以变，职责边界不能变。

@@ -896,6 +911,7 @@ repo/
 | `governance/` | 架构治理 / 安全 / 数据治理 / 合规 | 标准变化、ADR、风险登记、例外审批、门禁升级、复盘反哺 | CI、审计系统、Policy as Code、评审流程 | 管规则、决策和证据。治理资产必须尽量机器可读：门禁、风险、例外、控制项、POA&M、ADR、证据账本都应能被自动校验或导出。 |
 | `infra/` | 平台工程 / SRE / 环境 owner | 环境变更、容量调整、镜像版本发布、集群策略、灾备演练 | GitOps、Kubernetes、云平台、观测系统 | 管运行底座和环境期望状态。它不拥有业务逻辑；它回答“跑在哪里、跑几个、用哪个 digest、什么资源、什么策略、什么发布方式”。 |
 | `shared/` | 平台团队或共享库 owner | 通用 SDK、测试夹具、无业务语义工具升级 | 编译、测试、代码生成 | 只能放薄复用能力。若共享代码开始表达订单、客户、支付、履约等业务概念，应回到对应领域，不应把 `shared/` 演化成隐形中台。 |
+| `scripts/` | 平台工程 / DevEx / SRE / 治理脚本 owner | 质量门禁新增、生成器升级、发布脚本调整、一次性维护任务 | Make、CI、本地开发环境、审计导出 | 管仓库自动化入口。脚本不是杂物间，而是把本地开发、CI、生成、发布、迁移和质量门禁变成可复现、可审计、可维护的控制面。 |

 ### 2.1.3 单仓、多仓和混合仓的落地方式

@@ -945,6 +961,8 @@ events:
 | 服务 owner 和依赖关系 | `catalog/components/` + `domains/*/domain.yaml` | README 手写说明 | owner、依赖和生命周期要能被 Developer Portal、审计和 scorecard 消费 |
 | 架构决策 | `governance/decisions/` | 即时聊天记录 | ADR 需要可追溯、可复审、能关联风险和控制项 |
 | 安全例外 | `governance/architecture-gates/` 或 `governance/evidence/` | CI 注释、临时豁免变量 | 例外必须有 owner、到期时间、补偿控制和自动阻断 |
+| 只读质量检查脚本 | `scripts/checks/` 或稳定的 `scripts/check-*.py` 入口 | CI workflow 内联长命令 | 检查逻辑要能本地复现，失败输出要有路径、行号或可定位原因 |
+| 生成、同步和写仓库脚本 | `scripts/generate/` 或稳定的 `scripts/sync-*.py` 入口 | 手工复制、临时 notebook、CI 内联脚本 | 写入脚本必须幂等，运行后能通过 diff、测试和审计输出验证 |

 ### 2.1.5 最小可执行落地包

@@ -965,6 +983,8 @@ governance/standards/                    # 标准
 governance/decisions/                    # ADR
 governance/architecture-gates/           # 发布门禁
 governance/evidence/                     # 审计和验证证据
+scripts/checks/                          # 本地和 CI 共用的只读质量门禁
+scripts/lib/                             # 多个脚本共享的无副作用辅助库
 ```

 这个最小包能先回答企业落地最关键的问题：
@@ -1067,6 +1087,7 @@ AI 产品定义
 5. 把 `infra/` 当业务仓，在 Helm values 或 Kustomize patch 里隐藏业务开关和业务规则。
 6. 把 AI Prompt、RAG 来源、工具权限和微调审批写在应用代码里，导致无法评估、回滚和审计。
 7. 只有服务仓，没有中心 catalog、契约和治理索引，导致企业无法回答“谁依赖谁、谁负责、风险在哪”。
+8. 把 `scripts/` 当临时杂物间，CI、本地开发、生成、发布和一次性维护脚本混在一起，导致无人敢删、无人敢改、失败不可复现。

 ### 2.1.10 目录级 owner、审批和门禁

@@ -1084,6 +1105,7 @@ CODEOWNERS、必需检查和变更证据：
 | `governance/**` | 架构治理 / 安全 / 数据治理 | 治理 owner 1 人；控制项变更需双人审批 | 控制项覆盖、证据新鲜度、风险/POA&M/ADR 链接完整性 | ADR、风险登记、审计导出 |
 | `infra/**` | SRE / 平台工程 / 环境 owner | 环境 owner 1 人；生产变更需 SRE 审批 | GitOps diff、策略准入、镜像验签、资源限制、灾备影响检查 | 变更单、GitOps 同步记录、回滚证据 |
 | `shared/**` | 共享库 owner | owner 1 人；破坏性变更需所有消费者确认 | API 兼容、依赖影响、反向依赖测试 | 版本说明、消费者迁移记录 |
+| `scripts/**` | 平台工程 / DevEx / SRE / 治理脚本 owner | 脚本 owner 1 人；release/ops 高风险脚本需双人审批 | 脚本测试、dry-run、失败输出定位、工具版本锁定、ShellCheck/静态检查 | 脚本登记表、运行日志、生成物 diff、回滚或删除记录 |

 最重要的规则是：目录 owner 不是“通知人”，而是对资产正确性、演进节奏和事故后果负责的人。审批不能只看
 Markdown 是否写得好，而要验证契约、门禁、证据和运行路径是否闭合。
@@ -1110,6 +1132,7 @@ Markdown 是否写得好，而要验证契约、门禁、证据和运行路径
 | AI Platform | `ai/`、`contracts/ai/`、`catalog/ai-products/` | Prompt 版本、RAG 索引、评估结果、模型路由 | Evals、Guardrails、预算、人工确认点 |
 | Observability | `catalog/`、`service.yaml`、`domain.yaml`、`infra/` | SLO、仪表盘、告警、错误预算 | owner、SLO、日志/指标/链路追踪接入 |
 | GRC / Audit | `governance/`、控制目录、`evidence/`、starter kit | 控制评估、审计导出、POA&M、风险视图 | 证据新鲜度、控制覆盖、签署状态 |
+| Repository Automation | `scripts/`、`Makefile`、`.github/` 或 `ci/` | 校验报告、生成物 diff、审计导出摘要、发布或迁移执行记录 | 脚本登记、入口稳定、工具版本锁定、dry-run、失败可定位 |

 这张映射的意义是把目录从“人看的结构”升级为“工具能执行的接口”。如果某个目录没有稳定 owner、没有工具消费、
 没有门禁和证据输出，就不应被列为企业级标准目录。
@@ -1143,7 +1166,8 @@ Markdown 是否写得好，而要验证契约、门禁、证据和运行路径
 7. 每个治理控制项是否能映射到 schema、示例、checker、证据路径和审计导出结果。
 8. 每个目录是否有 CODEOWNERS、必需检查、变更证据和定期 owner 复核。
 9. 每个关键字段是否只有一个权威真相源，catalog 和文档是否只是派生视图或说明。
-10. 新人能否通过 Developer Portal 或 catalog 在 10 分钟内找到某个能力的 owner、契约、运行状态和风险。
+10. 每个仓库脚本是否能找到 owner、风险等级、入口命令、输入输出、失败契约、dry-run 或删除路径。
+11. 新人能否通过 Developer Portal 或 catalog 在 10 分钟内找到某个能力的 owner、契约、运行状态和风险。

 如果以上问题无法回答，说明目录只是“看起来现代”，还没有形成可运营、可审计、可演进的企业架构骨架。

@@ -1409,9 +1433,58 @@ governance/* / 控制目录 / evidence/*
 | `catalog/` | Developer Portal、依赖图、审计导出 | 服务、资源和 owner 无法被统一发现 |
 | `governance/` | 门禁脚本、审计导出、风险工作流 | 标准和例外无法闭环，审计只能补材料 |
 | `infra/` | GitOps、Kubernetes、云平台、准入控制 | 生产状态依赖人工操作，回滚和追责困难 |
+| `scripts/` | Make、CI、pre-commit、审计重放、agent 工具调用 | 自动化散落在本地命令和 workflow 中，失败不可复现 |

 目录一旦进入企业级标准，就必须定义“谁消费它”。没有消费方的目录应先作为局部文档或实验目录，不应升级为一级标准目录。

+#### 2.1.22.1 `scripts/` 的仓库控制面治理
+
+成熟企业级项目中的 `scripts/` 不是“临时脚本杂物间”，而是仓库控制面。它负责把本地开发、CI、生成、发布、迁移和质量门禁这些操作变成稳定入口，使同一动作可以在开发机、CI runner、审计重放环境和自动化 agent 中得到一致结果。
+
+`scripts/` 的治理目标：
+
+1. 入口稳定：CI、Makefile、开发者和 agent 调用同一组脚本入口，不在 workflow 中复制长命令。
+2. 逻辑集中：入口脚本保持薄，公共解析、路径发现、格式化、错误输出和校验逻辑进入 `scripts/lib/`。
+3. 风险分层：只读检查、写仓库生成、依赖安装、发布变更和一次性运维必须分开治理。
+4. 可复现：脚本必须声明工作目录、输入、输出、依赖工具版本、环境变量和退出码语义。
+5. 可审计：高风险脚本必须支持 `--dry-run`、输出执行计划、保留日志摘要，并能说明回滚或替代入口。
+6. 可删除：废弃脚本进入 `scripts/archive/` 或直接删除；保留时必须说明替代入口、保留期限和删除条件。
+
+推荐分类如下：
+
+| 分类 | 推荐位置 | 风险等级 | 治理要求 |
+| ---- | -------- | -------- | -------- |
+| 只读检查 | `scripts/checks/` 或 `scripts/check-*.py` | 低 | 不写仓库、不访问生产、失败输出必须可定位 |
+| 生成同步 | `scripts/generate/` 或 `scripts/sync-*.py` | 中 | 幂等、可 diff、运行后接质量门禁 |
+| 环境引导 | `scripts/bootstrap/` | 中 | 锁工具版本、声明缓存位置、不隐式提权 |
+| CI 适配 | `scripts/ci/` | 中 | 只做 CI 环境胶水，不承载核心校验逻辑 |
+| 发布脚本 | `scripts/release/` | 高 | 双人审批、dry-run、tag/版本/制品摘要校验和回滚说明 |
+| 运维维护 | `scripts/ops/` | 高 | 明确目标环境、保护生产、审计日志和人工确认点 |
+| 本地便利 | `scripts/dev/` | 低 | 不作为硬门禁，不影响生产发布语义 |
+| 共享库 | `scripts/lib/` | 中 | 导入无副作用，公共函数小而稳定，有脚本测试覆盖 |
+| 脚本测试 | `scripts/tests/`、`scripts/fixtures/` | 低 | 覆盖成功路径、失败路径、边界输入和 fixture 兼容 |
+
+`manifest.yml` 是脚本目录的最小治理账本。它不替代 README，而是让 CI、审计和 agent 能机械判断一个脚本是否允许自动执行：
+
+```yaml
+scripts:
+  - path: scripts/checks/check-links.py
+    owner: platform-devex
+    type: check
+    risk: low
+    writesRepository: false
+    requiresNetwork: false
+    ciRequired: true
+    entrypoint: make check-links
+    inputs:
+      - "**/*.md"
+    outputs:
+      - stdout
+    failureContract: "输出文件路径、行号或可定位的错误原因"
+```
+
+企业规模较小时，不必一次性创建所有子目录。可以先保留扁平入口，例如 `scripts/check-*.py`、`scripts/sync-*.py` 和 `scripts/lib/`；当脚本数量、风险等级或 owner 差异变大，再按 `checks/`、`generate/`、`release/`、`ops/` 拆分。成熟的标志不是目录更多，而是每个脚本都能被登记、测试、复现、审计和安全下线。
+
 ### 2.1.23 资产生命周期和目录字段

 服务、API、事件、数据产品、AI 产品、模型、Agent、平台能力和治理控制项都应有生命周期字段。生命周期不清楚，目录就会
@@ -1508,6 +1581,7 @@ infra/gitops/environments/
 5. 任意一个 AI Agent，能否证明 Prompt 版本、工具权限、RAG 数据源、评估结果、护栏、人工确认点和事故响应路径。
 6. 任意一个治理控制项，能否追到标准、schema、示例、checker、证据、风险、POA&M 和审计导出结果。
 7. 任意一个目录变更，能否说明 owner、消费方、主真相源、派生方向、门禁、迁移方式和回滚方式。
+8. 任意一个高风险脚本，能否证明 owner、风险等级、dry-run、输入输出、执行日志、审批和回滚路径。

 如果这些问题可以被自动化工具回答大部分，目录结构就是企业级平台架构；如果只能靠人开会解释，目录结构仍然只是文档草图。