@wneng/create-keel 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (230) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +21 -0
  3. package/dist/index.js +1479 -0
  4. package/dist/index.js.map +1 -0
  5. package/package.json +55 -0
  6. package/src/templates/.gitkeep +0 -0
  7. package/src/templates/agent-rust-desktop/files/Cargo.toml +12 -0
  8. package/src/templates/agent-rust-desktop/files/README.md +16 -0
  9. package/src/templates/agent-rust-desktop/files/generated-gitkeep +0 -0
  10. package/src/templates/agent-rust-desktop/files/main.rs +24 -0
  11. package/src/templates/agent-rust-desktop/fragment.yaml +18 -0
  12. package/src/templates/ai-claude-code/files/CLAUDE.md +19 -0
  13. package/src/templates/ai-claude-code/files/commands-README.md +7 -0
  14. package/src/templates/ai-claude-code/fragment.yaml +12 -0
  15. package/src/templates/ai-codex/files/project.md +11 -0
  16. package/src/templates/ai-codex/files/prompts-README.md +7 -0
  17. package/src/templates/ai-codex/fragment.yaml +12 -0
  18. package/src/templates/ai-cursor/files/rules-README.md +6 -0
  19. package/src/templates/ai-cursor/files/rules-project.md +15 -0
  20. package/src/templates/ai-cursor/fragment.yaml +12 -0
  21. package/src/templates/ai-kiro/files/prompts-README.md +5 -0
  22. package/src/templates/ai-kiro/files/specs-gitkeep +0 -0
  23. package/src/templates/ai-kiro/files/steering-README.md +5 -0
  24. package/src/templates/ai-kiro/files/steering-project.md +9 -0
  25. package/src/templates/ai-kiro/fragment.yaml +18 -0
  26. package/src/templates/ci-gitee/files/pipeline.yml +18 -0
  27. package/src/templates/ci-gitee/fragment.yaml +9 -0
  28. package/src/templates/ci-github/files/ci.yml +17 -0
  29. package/src/templates/ci-github/fragment.yaml +9 -0
  30. package/src/templates/contracts-base/files/CHANGELOG.md +10 -0
  31. package/src/templates/contracts-base/files/README.md +75 -0
  32. package/src/templates/contracts-base/files/_ai-policy.yaml +20 -0
  33. package/src/templates/contracts-base/files/dictionaries/domain-models.yaml +3 -0
  34. package/src/templates/contracts-base/files/dictionaries/enums.yaml +3 -0
  35. package/src/templates/contracts-base/files/environment/.env.example +3 -0
  36. package/src/templates/contracts-base/files/environment/env.schema.json +10 -0
  37. package/src/templates/contracts-base/files/errors/error-codes.yaml +6 -0
  38. package/src/templates/contracts-base/files/errors/error-response.schema.json +13 -0
  39. package/src/templates/contracts-base/files/events-gitkeep +0 -0
  40. package/src/templates/contracts-base/files/resources-examples-gitkeep +0 -0
  41. package/src/templates/contracts-base/files/resources-mocks-gitkeep +0 -0
  42. package/src/templates/contracts-base/files/states-gitkeep +0 -0
  43. package/src/templates/contracts-base/files/tests-acceptance-gitkeep +0 -0
  44. package/src/templates/contracts-base/files/tests-contracts-gitkeep +0 -0
  45. package/src/templates/contracts-base/files/tests-postman-gitkeep +0 -0
  46. package/src/templates/contracts-base/fragment.yaml +53 -0
  47. package/src/templates/contracts-events/files/asyncapi.yaml +8 -0
  48. package/src/templates/contracts-events/fragment.yaml +9 -0
  49. package/src/templates/contracts-rest/files/api.yaml +7 -0
  50. package/src/templates/contracts-rest/fragment.yaml +9 -0
  51. package/src/templates/contracts-rest-events/files/api.yaml +7 -0
  52. package/src/templates/contracts-rest-events/files/asyncapi.yaml +8 -0
  53. package/src/templates/contracts-rest-events/fragment.yaml +12 -0
  54. package/src/templates/deploy-bare-metal/files/release-checklist.md +8 -0
  55. package/src/templates/deploy-bare-metal/fragment.yaml +9 -0
  56. package/src/templates/deploy-common/files/README.md +5 -0
  57. package/src/templates/deploy-common/fragment.yaml +8 -0
  58. package/src/templates/deploy-docker-compose/files/compose.override.example.yaml +4 -0
  59. package/src/templates/deploy-docker-compose/files/docker-compose.yaml +4 -0
  60. package/src/templates/deploy-docker-compose/fragment.yaml +12 -0
  61. package/src/templates/deploy-kubernetes/files/Chart.yaml +6 -0
  62. package/src/templates/deploy-kubernetes/files/deployment.yaml +18 -0
  63. package/src/templates/deploy-kubernetes/files/namespace.yaml +4 -0
  64. package/src/templates/deploy-kubernetes/files/values.yaml +4 -0
  65. package/src/templates/deploy-kubernetes/fragment.yaml +18 -0
  66. package/src/templates/docs-skeleton/files/README.md +134 -0
  67. package/src/templates/docs-skeleton/files/arch-README.md +18 -0
  68. package/src/templates/docs-skeleton/files/arch-_ai-policy.yaml +8 -0
  69. package/src/templates/docs-skeleton/files/archive-README.md +20 -0
  70. package/src/templates/docs-skeleton/files/archive-_ai-policy.yaml +8 -0
  71. package/src/templates/docs-skeleton/files/assets-README.md +29 -0
  72. package/src/templates/docs-skeleton/files/assets-_ai-policy.yaml +8 -0
  73. package/src/templates/docs-skeleton/files/assets-design-gitkeep +0 -0
  74. package/src/templates/docs-skeleton/files/assets-diagrams-gitkeep +0 -0
  75. package/src/templates/docs-skeleton/files/assets-images-gitkeep +0 -0
  76. package/src/templates/docs-skeleton/files/be-README.md +29 -0
  77. package/src/templates/docs-skeleton/files/be-_ai-policy.yaml +8 -0
  78. package/src/templates/docs-skeleton/files/bg-README.md +21 -0
  79. package/src/templates/docs-skeleton/files/bg-_ai-policy.yaml +8 -0
  80. package/src/templates/docs-skeleton/files/eng-README.md +21 -0
  81. package/src/templates/docs-skeleton/files/eng-_ai-policy.yaml +9 -0
  82. package/src/templates/docs-skeleton/files/fe-README.md +31 -0
  83. package/src/templates/docs-skeleton/files/fe-_ai-policy.yaml +8 -0
  84. package/src/templates/docs-skeleton/files/governance-README.md +28 -0
  85. package/src/templates/docs-skeleton/files/governance-_ai-policy.yaml +13 -0
  86. package/src/templates/docs-skeleton/files/governance-ai-access-modes.md +324 -0
  87. package/src/templates/docs-skeleton/files/governance-assets.md +50 -0
  88. package/src/templates/docs-skeleton/files/governance-checklists.md +55 -0
  89. package/src/templates/docs-skeleton/files/governance-ci.md +36 -0
  90. package/src/templates/docs-skeleton/files/governance-deploy-ops.md +107 -0
  91. package/src/templates/docs-skeleton/files/governance-docs-references.md +39 -0
  92. package/src/templates/docs-skeleton/files/governance-git-workflow.md +45 -0
  93. package/src/templates/docs-skeleton/files/governance-integrations.md +66 -0
  94. package/src/templates/docs-skeleton/files/governance-security.md +69 -0
  95. package/src/templates/docs-skeleton/files/governance-tools-scripts.md +128 -0
  96. package/src/templates/docs-skeleton/files/process-docs-README.md +22 -0
  97. package/src/templates/docs-skeleton/files/process-docs-_ai-policy.yaml +10 -0
  98. package/src/templates/docs-skeleton/files/references-README.md +19 -0
  99. package/src/templates/docs-skeleton/files/references-_ai-policy.yaml +9 -0
  100. package/src/templates/docs-skeleton/files/references-legal-source.yaml +5 -0
  101. package/src/templates/docs-skeleton/files/references-standards-source.yaml +5 -0
  102. package/src/templates/docs-skeleton/files/references-vendors-source.yaml +5 -0
  103. package/src/templates/docs-skeleton/files/usage-quickstart.md +168 -0
  104. package/src/templates/docs-skeleton/fragment.yaml +129 -0
  105. package/src/templates/integrations-docs/files/README.md +53 -0
  106. package/src/templates/integrations-docs/files/_template.md +63 -0
  107. package/src/templates/integrations-docs/fragment.yaml +12 -0
  108. package/src/templates/license-apache-2/files/LICENSE +15 -0
  109. package/src/templates/license-apache-2/fragment.yaml +9 -0
  110. package/src/templates/license-mit/files/LICENSE +21 -0
  111. package/src/templates/license-mit/fragment.yaml +9 -0
  112. package/src/templates/miniapp-wechat/files/README.md +10 -0
  113. package/src/templates/miniapp-wechat/files/app.js +5 -0
  114. package/src/templates/miniapp-wechat/files/app.json +9 -0
  115. package/src/templates/miniapp-wechat/files/app.wxss +4 -0
  116. package/src/templates/miniapp-wechat/files/generated-gitkeep +0 -0
  117. package/src/templates/miniapp-wechat/files/pages-index.js +4 -0
  118. package/src/templates/miniapp-wechat/files/pages-index.json +3 -0
  119. package/src/templates/miniapp-wechat/files/pages-index.wxml +3 -0
  120. package/src/templates/miniapp-wechat/files/pages-index.wxss +10 -0
  121. package/src/templates/miniapp-wechat/files/project.config.json +13 -0
  122. package/src/templates/miniapp-wechat/files/sitemap.json +8 -0
  123. package/src/templates/miniapp-wechat/fragment.yaml +39 -0
  124. package/src/templates/mobile-flutter/files/README.md +14 -0
  125. package/src/templates/mobile-flutter/files/analysis_options.yaml +6 -0
  126. package/src/templates/mobile-flutter/files/generated-gitkeep +0 -0
  127. package/src/templates/mobile-flutter/files/main.dart +18 -0
  128. package/src/templates/mobile-flutter/files/pubspec.yaml +19 -0
  129. package/src/templates/mobile-flutter/fragment.yaml +21 -0
  130. package/src/templates/mobile-react-native/files/App.tsx +10 -0
  131. package/src/templates/mobile-react-native/files/README.md +15 -0
  132. package/src/templates/mobile-react-native/files/app.json +4 -0
  133. package/src/templates/mobile-react-native/files/generated-gitkeep +0 -0
  134. package/src/templates/mobile-react-native/files/index.js +5 -0
  135. package/src/templates/mobile-react-native/files/package.json +14 -0
  136. package/src/templates/mobile-react-native/fragment.yaml +24 -0
  137. package/src/templates/repo-skeleton/files/docs-gitkeep +0 -0
  138. package/src/templates/repo-skeleton/files/ops-README.md +6 -0
  139. package/src/templates/repo-skeleton/files/ops-k8s-gitkeep +0 -0
  140. package/src/templates/repo-skeleton/files/ops-monitoring-gitkeep +0 -0
  141. package/src/templates/repo-skeleton/files/ops-terraform-gitkeep +0 -0
  142. package/src/templates/repo-skeleton/files/scripts-README.md +11 -0
  143. package/src/templates/repo-skeleton/files/scripts-ci-gitkeep +0 -0
  144. package/src/templates/repo-skeleton/files/scripts-dev-gitkeep +0 -0
  145. package/src/templates/repo-skeleton/files/scripts-oneoff-gitkeep +0 -0
  146. package/src/templates/repo-skeleton/files/scripts-ops-gitkeep +0 -0
  147. package/src/templates/repo-skeleton/files/tools-README.md +4 -0
  148. package/src/templates/repo-skeleton/files/tools-contract-gitkeep +0 -0
  149. package/src/templates/repo-skeleton/fragment.yaml +41 -0
  150. package/src/templates/role-data/files/README.md +23 -0
  151. package/src/templates/role-data/files/_ai-policy.yaml +10 -0
  152. package/src/templates/role-data/files/dashboards-gitkeep +0 -0
  153. package/src/templates/role-data/files/data-catalog-gitkeep +0 -0
  154. package/src/templates/role-data/files/tracking-spec-gitkeep +0 -0
  155. package/src/templates/role-data/fragment.yaml +21 -0
  156. package/src/templates/role-design/files/README.md +26 -0
  157. package/src/templates/role-design/files/_ai-policy.yaml +11 -0
  158. package/src/templates/role-design/files/figma-exports-gitkeep +0 -0
  159. package/src/templates/role-design/files/ui-spec-gitkeep +0 -0
  160. package/src/templates/role-design/fragment.yaml +18 -0
  161. package/src/templates/role-field/files/README.md +33 -0
  162. package/src/templates/role-field/files/_ai-policy.yaml +13 -0
  163. package/src/templates/role-field/files/runbooks-README.md +5 -0
  164. package/src/templates/role-field/files/templates-README.md +5 -0
  165. package/src/templates/role-field/files/templates-_ai-policy.yaml +8 -0
  166. package/src/templates/role-field/fragment.yaml +21 -0
  167. package/src/templates/role-legal-security/files/README.md +33 -0
  168. package/src/templates/role-legal-security/files/_ai-policy.yaml +14 -0
  169. package/src/templates/role-legal-security/files/assessments-README.md +5 -0
  170. package/src/templates/role-legal-security/files/assessments-_ai-policy.yaml +9 -0
  171. package/src/templates/role-legal-security/files/evidence-README.md +5 -0
  172. package/src/templates/role-legal-security/files/evidence-_ai-policy.yaml +8 -0
  173. package/src/templates/role-legal-security/fragment.yaml +24 -0
  174. package/src/templates/role-marketing/files/README.md +32 -0
  175. package/src/templates/role-marketing/files/_ai-policy.yaml +14 -0
  176. package/src/templates/role-marketing/files/drafts-README.md +7 -0
  177. package/src/templates/role-marketing/files/drafts-_ai-policy.yaml +19 -0
  178. package/src/templates/role-marketing/files/published-README.md +5 -0
  179. package/src/templates/role-marketing/files/published-_ai-policy.yaml +8 -0
  180. package/src/templates/role-marketing/files/templates-README.md +5 -0
  181. package/src/templates/role-marketing/files/templates-_ai-policy.yaml +8 -0
  182. package/src/templates/role-marketing/fragment.yaml +30 -0
  183. package/src/templates/role-qa/files/README.md +20 -0
  184. package/src/templates/role-qa/files/_ai-policy.yaml +9 -0
  185. package/src/templates/role-qa/files/defects-gitkeep +0 -0
  186. package/src/templates/role-qa/files/test-cases-gitkeep +0 -0
  187. package/src/templates/role-qa/files/test-plans-gitkeep +0 -0
  188. package/src/templates/role-qa/fragment.yaml +21 -0
  189. package/src/templates/root-files/files/.editorconfig +15 -0
  190. package/src/templates/root-files/files/.gitattributes +13 -0
  191. package/src/templates/root-files/files/AGENTS.md +194 -0
  192. package/src/templates/root-files/files/README.md +16 -0
  193. package/src/templates/root-files/fragment.yaml +20 -0
  194. package/src/templates/server-go/files/README.md +3 -0
  195. package/src/templates/server-go/files/generated-gitkeep +0 -0
  196. package/src/templates/server-go/files/go.mod +3 -0
  197. package/src/templates/server-go/files/main.go +7 -0
  198. package/src/templates/server-go/fragment.yaml +18 -0
  199. package/src/templates/server-java/files/Application.java +12 -0
  200. package/src/templates/server-java/files/README.md +48 -0
  201. package/src/templates/server-java/files/application-test.yaml +17 -0
  202. package/src/templates/server-java/files/application.yaml +33 -0
  203. package/src/templates/server-java/files/generated-gitkeep +0 -0
  204. package/src/templates/server-java/files/pom.xml +97 -0
  205. package/src/templates/server-java/fragment.yaml +24 -0
  206. package/src/templates/server-node/files/README.md +6 -0
  207. package/src/templates/server-node/files/generated-gitkeep +0 -0
  208. package/src/templates/server-node/files/package.json +9 -0
  209. package/src/templates/server-node/files/src-index.ts +2 -0
  210. package/src/templates/server-node/fragment.yaml +18 -0
  211. package/src/templates/server-python/files/README.md +4 -0
  212. package/src/templates/server-python/files/app-init.py +1 -0
  213. package/src/templates/server-python/files/generated-gitkeep +0 -0
  214. package/src/templates/server-python/files/pyproject.toml +5 -0
  215. package/src/templates/server-python/fragment.yaml +18 -0
  216. package/src/templates/web-react/files/README.md +29 -0
  217. package/src/templates/web-react/files/generated-gitkeep +0 -0
  218. package/src/templates/web-react/files/index.html +12 -0
  219. package/src/templates/web-react/files/package.json +25 -0
  220. package/src/templates/web-react/files/src-App.tsx +11 -0
  221. package/src/templates/web-react/files/src-main.tsx +14 -0
  222. package/src/templates/web-react/files/tsconfig.json +20 -0
  223. package/src/templates/web-react/files/vite.config.ts +15 -0
  224. package/src/templates/web-react/fragment.yaml +30 -0
  225. package/src/templates/web-vue/files/README.md +3 -0
  226. package/src/templates/web-vue/files/generated-gitkeep +0 -0
  227. package/src/templates/web-vue/files/index.html +11 -0
  228. package/src/templates/web-vue/files/package.json +9 -0
  229. package/src/templates/web-vue/files/src-main.ts +3 -0
  230. package/src/templates/web-vue/fragment.yaml +21 -0
@@ -0,0 +1,55 @@
1
+ ---
2
+ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
3
+ ---
4
+
5
+ # 完整检查清单
6
+
7
+ > 入口摘要在 `AGENTS.md` §13。本文件提供完整可勾选清单。
8
+
9
+ ## 1. 开发前核对(功能开发启动前)
10
+
11
+ - [ ] 相关接口已在 `contracts/openapi/api.yaml` 中定义
12
+ - [ ] 数据模型已在 `contracts/dictionaries/` 中定义
13
+ - [ ] 错误码已在 `contracts/errors/error-codes.yaml` 中注册
14
+ - [ ] 状态机(如有)已在 `contracts/states/` 中定义
15
+ - [ ] 事件(如有)已在 `contracts/events/event-catalog.yaml` 中登记
16
+ - [ ] 设计文档已在 `docs/` 对应编号目录就位
17
+ - [ ] 如需环境变量,已在 `contracts/environment/.env.example` 与 `env.schema.json` 同步
18
+
19
+ ## 2. 提交前核对(PR 发起前)
20
+
21
+ - [ ] `contracts/CHANGELOG.md` 已同步更新
22
+ - [ ] 破坏性变更已按 §6 升级 MAJOR
23
+ - [ ] 生成代码已重新生成且 `git diff` 为空
24
+ - [ ] `docs/README.md` 已按需同步(目录地图 / 分类入口 / 子目录约定)
25
+ - [ ] 若启用 `integrations` 且契约变更影响某 pair,该 pair 已同步
26
+ - [ ] 若修改 `docs/governance/*`,AGENTS.md 中对应摘要已同步
27
+ - [ ] PII、密钥、真实域名未出现在提交中
28
+ - [ ] AI 生成代码已标注(commit 前缀 + PR 标签)
29
+ - [ ] 本地单元测试 / 契约测试已通过
30
+
31
+ ## 3. 发布前核对(合入 main 准备部署前)
32
+
33
+ - [ ] `deploy/` 下对应环境的 values / overlay 已更新
34
+ - [ ] `deploy/pipelines/CHANGELOG.md` 已记录流水线变更(如有)
35
+ - [ ] `deploy/checklists/` 中对应发布 checklist 已走完
36
+ - [ ] 回滚脚本 / 预案已就位并可执行
37
+ - [ ] 监控与告警规则(`ops/`)覆盖新增端点或事件
38
+ - [ ] 生产敏感值通过密钥管理注入,仓库内无明文
39
+ - [ ] 漏洞扫描通过(见 `docs/governance/security.md`)
40
+ - [ ] SBOM 已生成
41
+
42
+ ## 4. 多应用模式核对(当某执行环境包含多个应用时)
43
+
44
+ - [ ] 该目录下不存在裸工程文件与 `apps/` 子目录并存
45
+ - [ ] 每个应用位于 `<env>/apps/<app-name>/`,命名匹配 `^[a-z0-9][a-z0-9-]{0,62}$`
46
+ - [ ] 应用之间没有直接 import;跨应用共享走 `contracts/` 或根 `packages/`
47
+ - [ ] 必要时在 CODEOWNERS 中为具体应用设置守门人
48
+
49
+ ## 5. 新增脚本 / 工具核对
50
+
51
+ - [ ] 已按 §12.3 判定归属(`scripts/` 或 `tools/`)
52
+ - [ ] `scripts/` 脚本顶部注释包含用途、参数、幂等性、危险级别
53
+ - [ ] `scripts/README.md` 索引已更新
54
+ - [ ] `tools/` 工具含独立 `README.md` 与版本号
55
+ - [ ] 跨平台兼容性已确认(或明确标注仅支持某一平台)
@@ -0,0 +1,36 @@
1
+ ---
2
+ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
3
+ ---
4
+
5
+ # CI 校验链路
6
+
7
+ ## 阻断合入的检查矩阵
8
+
9
+ | 检查项 | 工具 / 命令 | 失败处理 |
10
+ | -------------------------------- | ---------------------------------------- | ------------ |
11
+ | 契约 lint | `spectral lint` / `redocly lint` | 阻断合入 |
12
+ | JSON Schema 校验 | `ajv-cli validate` | 阻断合入 |
13
+ | `contracts/CHANGELOG.md` 同步 | 自定义脚本检查 diff | 阻断合入 |
14
+ | 生成代码一致性 | 重新生成 → `git diff --exit-code generated/` | 阻断合入 |
15
+ | 依赖漏洞扫描 | `npm audit` / `pip-audit` / `trivy` | 高危阻断 |
16
+ | Secret scanning | `gitleaks` 或平台内置 | 阻断合入 |
17
+ | 单元测试 | 各模块测试框架 | 阻断合入 |
18
+ | 契约测试(Pact / Postman) | `pact-verifier` / `newman` | 阻断合入 |
19
+ | 代码风格 | `eslint` / `prettier` / 对应语言 linter | 阻断合入 |
20
+
21
+ ## 工作流文件位置
22
+
23
+ - Gitee:`.gitee/pipelines/ci.yml`
24
+ - GitHub:`.github/workflows/ci.yml`
25
+
26
+ ## 失败处理流程
27
+
28
+ 1. CI 标红 → PR 不可合入
29
+ 2. 修复后重跑;不允许通过 admin override 绕过
30
+ 3. 若工具自身故障导致误报,先在 `docs/过程文档/` 备案,再修工具
31
+
32
+ ## 新增检查项的流程
33
+
34
+ 1. 在 `docs/02-系统方案与架构/` 写 ADR 说明动机与影响
35
+ 2. 先以 warning 形式上线,收集 2 周数据
36
+ 3. 升级为阻断;同步更新本表与 AGENTS.md §9 摘要
@@ -0,0 +1,107 @@
1
+ ---
2
+ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
3
+ ---
4
+
5
+ # ops/ 与 deploy/ 完整规则
6
+
7
+ > 快速判定卡在 `AGENTS.md` §快速判定卡。本文件给完整规则、目录结构与示例。
8
+
9
+ ## 1. ops/
10
+
11
+ `ops/` 存放"环境与基础设施本身",**即使没有任何业务应用也需要存在**的资源。
12
+
13
+ ### 1.1 内容范围
14
+
15
+ - Terraform / Pulumi 模块
16
+ - 集群级 Kubernetes 资源(Namespace、Ingress Controller、Cert Manager、StorageClass、SecurityPolicy)
17
+ - 网络、VPC、子网、DNS、防火墙规则
18
+ - 监控、告警、日志采集、备份策略
19
+ - 环境初始化脚本(一次性 bootstrap)
20
+ - 密钥管理基础设施(Vault、KMS 配置)
21
+
22
+ ### 1.2 子目录建议
23
+
24
+ ```
25
+ ops/
26
+ ├── README.md
27
+ ├── terraform/ # 各 provider 的 IaC
28
+ ├── k8s/ # 集群级(区别于 deploy/k8s/ 的应用级)
29
+ └── monitoring/ # Prometheus、Grafana、告警规则
30
+ ```
31
+
32
+ ### 1.3 守门人
33
+
34
+ `@ops-team`。涉及网络与安全资源的 PR 必须双 reviewer。
35
+
36
+ ## 2. deploy/
37
+
38
+ `deploy/` 存放"业务应用如何发布到环境"的产物与配置。
39
+
40
+ ### 2.1 目录结构
41
+
42
+ ```
43
+ deploy/
44
+ ├── README.md
45
+ ├── docker/ # Dockerfile 与镜像构建脚本
46
+ ├── compose/ # docker-compose 及 override
47
+ ├── helm/ # 应用 Helm chart 或 values 覆盖
48
+ ├── k8s/ # 应用层 K8s manifest(区别于 ops/k8s/)
49
+ ├── pipelines/ # CI/CD 发布流水线配置
50
+ └── checklists/ # 发布前 / 回滚 checklist
51
+ ```
52
+
53
+ ### 2.2 约束
54
+
55
+ - 不得包含生产环境的真实凭证;敏感值通过密钥管理(K8s Secret、Vault)注入,仓库内只放**引用**
56
+ - 环境差异通过 values 文件或 overlay 表达,禁止硬编码环境名
57
+ - 发布流水线变更必须在 `deploy/pipelines/CHANGELOG.md` 记录
58
+ - 镜像 tag 必须是不可变标识(commit SHA 或语义版本),禁止 `latest`
59
+
60
+ ### 2.3 守门人
61
+
62
+ `@backend-team @ops-team`。
63
+
64
+ ## 3. 归属判定(详细版)
65
+
66
+ ### 3.1 决策口诀
67
+
68
+ - **"即便没有业务应用也要存在"** → `ops/`
69
+ - **"业务应用的打包与投递"** → `deploy/`
70
+
71
+ ### 3.2 边界示例
72
+
73
+ | 资源 | 归属 | 理由 |
74
+ | --- | --- | --- |
75
+ | 集群本身的 Namespace `kube-system` | `ops/` | 集群级,不属任何应用 |
76
+ | 应用专属的 Namespace `myapp-prod` | `deploy/k8s/` | 跟随应用生命周期 |
77
+ | Ingress Controller 安装 | `ops/` | 平台能力 |
78
+ | 应用的 Ingress 规则 | `deploy/k8s/` | 跟随应用 |
79
+ | Cert Manager 安装与 ClusterIssuer | `ops/` | 平台能力 |
80
+ | 应用使用 Cert Manager 申请的 Certificate | `deploy/k8s/` | 跟随应用 |
81
+ | 一个 Helm chart(chart 本身) | `deploy/helm/` | 部署单元 |
82
+ | Helm chart 依赖的 CRD | `ops/` | 集群能力 |
83
+ | Prometheus Operator 安装 | `ops/` | 监控基础设施 |
84
+ | 应用的 ServiceMonitor / 告警规则 | `deploy/k8s/` 或 `ops/monitoring/`,二选一并保持一致 | 团队自定 |
85
+
86
+ ### 3.3 模糊地带的处理
87
+
88
+ 如果一个资源既能解释为"基础设施"也能解释为"应用部署",**优先放 `ops/`**。代价:被多应用复用时无需迁移;放错位置只是冗余而非破坏。
89
+
90
+ ## 4. 流水线变更日志
91
+
92
+ `deploy/pipelines/CHANGELOG.md` 必须存在。任何流水线 YAML 变更:
93
+
94
+ - 新增 / 删除 stage
95
+ - 改 trigger 条件
96
+ - 改并发策略
97
+ - 改密钥引用
98
+
99
+ 均需在 CHANGELOG 中记录,格式同 `contracts/CHANGELOG.md`。
100
+
101
+ ## 5. 发布制品
102
+
103
+ `deploy/` 不存放编译产物(jar / tar / wheel);编译产物由 CI 推送到 artifact registry。本目录只存"如何把产物部署"的描述。
104
+
105
+ ## 6. SBOM 联动
106
+
107
+ 每次发布生成的 SBOM(见 `docs/governance/security.md` §3)输出到 `deploy/sbom/<version>.json`,与发布制品同步归档。
@@ -0,0 +1,39 @@
1
+ ---
2
+ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
3
+ ---
4
+
5
+ # 外部引用资料元数据规则
6
+
7
+ `docs/references/` 中的每个文件或子目录必须含**来源说明**。
8
+
9
+ ## `_source.yaml` 格式
10
+
11
+ ```yaml
12
+ source: "ISO 27001:2022"
13
+ url: "https://www.iso.org/standard/27001"
14
+ retrieved: "2025-03-15"
15
+ version: "2022 edition"
16
+ ```
17
+
18
+ 字段说明:
19
+
20
+ - `source`(必填):资料的官方名称
21
+ - `url`(必填):来源链接;若为离线材料填 `"offline: <途径>"`
22
+ - `retrieved`(必填):获取日期,ISO 8601
23
+ - `version`(推荐):版本号 / 年份 / 修订号
24
+
25
+ ## 子目录组织
26
+
27
+ ```
28
+ docs/references/
29
+ ├── standards/ # 行业标准、RFC、国标
30
+ ├── vendors/ # 厂商手册
31
+ └── legal/ # 许可证、合规
32
+ ```
33
+
34
+ 每个子目录都允许有自己的 `_source.yaml`(说明整组资料),也允许具体文件旁的 `_source.yaml`(精确到文件)。
35
+
36
+ ## 版权
37
+
38
+ - 仅入仓"可二次分发"或"内部参考"许可范围内的内容
39
+ - 禁止入仓需付费 / 严格 NDA 的资料;这类放在内部 wiki 或加密存储
@@ -0,0 +1,45 @@
1
+ ---
2
+ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
3
+ ---
4
+
5
+ # Git 工作流细则
6
+
7
+ > 基线在 `AGENTS.md` §8。本文件展开 CODEOWNERS 模板与多应用守门。
8
+
9
+ ## CODEOWNERS 基础模板
10
+
11
+ ```
12
+ # contracts/ 由架构/技术负责人守门
13
+ /contracts/ @arch-team
14
+
15
+ # docs/01 由产品负责人守门
16
+ /docs/01-背景与需求/ @product-team
17
+
18
+ # docs/governance/ 改一行就要改 AGENTS.md,由架构组守门
19
+ /docs/governance/ @arch-team
20
+
21
+ # 安全与基础设施
22
+ /.gitignore @security-team
23
+ /ops/ @ops-team
24
+ /deploy/ @backend-team @ops-team
25
+ /tools/ @arch-team
26
+ /scripts/ @all-maintainers
27
+ ```
28
+
29
+ ## 多应用模式下的细化
30
+
31
+ ```
32
+ /server/apps/auth/ @auth-team
33
+ /server/apps/billing/ @billing-team
34
+ /web/apps/admin/ @admin-team
35
+ /agent/apps/cli/ @cli-team
36
+ ```
37
+
38
+ ## 守门人变更流程
39
+
40
+ - CODEOWNERS 修改本身需要架构组与原守门人**双方** review
41
+ - 团队解散 / 合并时,CODEOWNERS 必须在同一 PR 更新
42
+
43
+ ## 与 PR 模板的关系
44
+
45
+ PR 模板(在 AGENTS.md §8.4)的字段不可省略;空字段视为 PR 不完整,应被退回。
@@ -0,0 +1,66 @@
1
+ ---
2
+ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
3
+ ---
4
+
5
+ # 集成对接(integrations)完整规则
6
+
7
+ > 摘要在 `AGENTS.md` §5.4。本文件给完整规则与示例。
8
+
9
+ ## 启用条件
10
+
11
+ 仅当创建项目时显式 `integrations=true`,或后续手动建立 `docs/06-集成对接/` 时启用。判断标准:
12
+
13
+ - 纯内部调用、单仓库、前后端同团队 → **不启用**
14
+ - 仓库内某一端需要与**外部仓库 / 外部团队**对接 → **启用**
15
+
16
+ ## 与 `contracts/` 的边界
17
+
18
+ - `contracts/` —— 机器可验证的权威契约
19
+ - `docs/06-集成对接/` —— 契约不说但双方必须知道的事
20
+
21
+ **禁止复述契约**;通过锚点引用:
22
+
23
+ ```
24
+ contracts/openapi/api.yaml#/paths/~1auth~1login
25
+ ```
26
+
27
+ ## 目录命名
28
+
29
+ ```
30
+ docs/06-集成对接/
31
+ ├── README.md
32
+ ├── _template.md
33
+ ├── agent-to-server/
34
+ ├── web-to-server/
35
+ ├── mobile-to-server/
36
+ └── miniapp-to-server/
37
+ ```
38
+
39
+ - 格式:`<consumer>-to-<producer>/`
40
+ - 多应用模式可细化:`agent-cli-to-server-auth/`
41
+
42
+ ## 7 章模板
43
+
44
+ 复制 `_template.md`:
45
+
46
+ 1. 概览
47
+ 2. 鉴权与会话
48
+ 3. 连接与生命周期
49
+ 4. 数据流与一致性约束
50
+ 5. 错误分支与降级
51
+ 6. 版本兼容矩阵
52
+ 7. 联调 checklist
53
+
54
+ ## 维护义务(存在即维护)
55
+
56
+ 一旦某 pair 目录存在,修改 `contracts/` 且影响到它时**必须**:
57
+
58
+ - PR 描述引用对应 pair 文档
59
+ - 同一 PR 内同步更新该文档(至少更新版本兼容矩阵与受影响章节)
60
+ - `contracts/CHANGELOG.md` 反向链接到集成文档
61
+
62
+ 否则 PR 不得合入。
63
+
64
+ ## CI 联动(可选,未实现)
65
+
66
+ 未来工作:lint `contracts/` diff 与 `docs/06-集成对接/<pair>/` diff 的联动;变更不同步则阻断。
@@ -0,0 +1,69 @@
1
+ ---
2
+ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
3
+ ---
4
+
5
+ # 安全与合规细则
6
+
7
+ > 基线在 `AGENTS.md` §7。本文件展开依赖安全、许可证、SBOM 三块。
8
+
9
+ ## 1. 依赖安全
10
+
11
+ ### 1.1 版本管理
12
+
13
+ - 新增依赖使用**精确版本**(pinned),禁止开放范围
14
+ - `package.json` / `requirements.txt` / `go.mod` / `Cargo.toml` / `pom.xml` 都遵循同一原则
15
+ - 升级依赖独立 PR,便于回滚
16
+
17
+ ### 1.2 漏洞扫描
18
+
19
+ | 语言 | 工具 | 阻断阈值 |
20
+ |------|------|---------|
21
+ | Node | `npm audit --audit-level=high` | high |
22
+ | Python | `pip-audit` | high |
23
+ | Go | `govulncheck` | 任何已知 CVE |
24
+ | Java | OWASP Dependency-Check | CVSS ≥ 7.0 |
25
+ | 容器镜像 | `trivy image` | high |
26
+
27
+ CI 中作为独立 job 运行;失败阻断合入。
28
+
29
+ ### 1.3 typosquatting 防护
30
+
31
+ 引入新依赖前确认:
32
+
33
+ - 包名拼写正确(特别注意 `lodash` vs `lodahs` 类近似名)
34
+ - 维护者真实可查
35
+ - 最近一次发布在 12 个月内,或有合理说明
36
+
37
+ ## 2. 许可证
38
+
39
+ ### 2.1 仓库许可证
40
+
41
+ - 根 `LICENSE` 文件
42
+ - 非 `proprietary` 项目必须存在该文件
43
+
44
+ ### 2.2 第三方许可证
45
+
46
+ - 顶层维护 `THIRD_PARTY_NOTICES.md`,列出所有第三方依赖的许可证
47
+ - 引入新依赖前需确认许可证与项目兼容(GPL / AGPL 与商业项目通常不兼容)
48
+ - 不兼容许可证一律拒绝引入
49
+
50
+ ### 2.3 许可证扫描
51
+
52
+ CI 中跑 `license-checker`(Node)/ `pip-licenses`(Python)/ `go-licenses`,输出与 `THIRD_PARTY_NOTICES.md` diff 不一致时阻断。
53
+
54
+ ## 3. SBOM(软件物料清单)
55
+
56
+ 每次发布生成 SBOM(CycloneDX 或 SPDX 格式):
57
+
58
+ - 工具:`syft` / `cyclonedx-cli`
59
+ - 输出:`deploy/sbom/<version>.json`
60
+ - 与发布制品一同归档
61
+
62
+ ## 4. 应急响应
63
+
64
+ 发现高危漏洞:
65
+
66
+ 1. 立刻在 `docs/过程文档/security-incidents/` 开 issue
67
+ 2. 24 小时内评估影响范围与修复路径
68
+ 3. 修复 PR 不走常规分支策略,可走 `hotfix/*`
69
+ 4. 上线后写入 `docs/02-系统方案与架构/post-mortems/`
@@ -0,0 +1,128 @@
1
+ ---
2
+ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
3
+ ---
4
+
5
+ # tools/ 与 scripts/ 完整规则
6
+
7
+ > 快速判定卡在 `AGENTS.md` §快速判定卡。本文件给完整规则与升级判定。
8
+
9
+ ## 1. tools/
10
+
11
+ "有结构、可复用、近似小产品"的开发工具。
12
+
13
+ ### 1.1 内容范围
14
+
15
+ - 契约代码生成器、mock server 启动器
16
+ - 自研 CLI、数据迁移工具
17
+ - 代码质量检查插件
18
+ - Scaffolder 类工具
19
+
20
+ ### 1.2 结构要求
21
+
22
+ 每个工具一个子目录,**必须**包含:
23
+
24
+ - `README.md`:用途、安装、使用、贡献
25
+ - 入口文件(`bin/` 或 `package.json#bin` / `pyproject.toml`)
26
+ - 独立版本号(`package.json` / `pyproject.toml` / 自身 `CHANGELOG.md`)
27
+ - 至少一份测试或示例
28
+
29
+ ```
30
+ tools/
31
+ ├── README.md
32
+ ├── contract/ # 契约相关工具链统一聚合于此
33
+ │ ├── codegen/
34
+ │ └── mock-server/
35
+ └── project-scaffolder/
36
+ ├── README.md
37
+ ├── package.json
38
+ └── src/
39
+ ```
40
+
41
+ ### 1.3 守门人
42
+
43
+ `@arch-team`。
44
+
45
+ ## 2. scripts/
46
+
47
+ "薄、零散、日常维护"的脚本。
48
+
49
+ ### 2.1 目录结构
50
+
51
+ ```
52
+ scripts/
53
+ ├── README.md
54
+ ├── dev/ # 本地开发辅助(启动、重置、seed)
55
+ ├── ci/ # CI 中调用的薄脚本
56
+ ├── ops/ # 运维日常脚本(日志收集、健康检查)
57
+ └── oneoff/ # 一次性脚本,用完归档或删除
58
+ ```
59
+
60
+ ### 2.2 强制头注释
61
+
62
+ 每个脚本顶部必须包含以下信息(注释中):
63
+
64
+ | 字段 | 取值 |
65
+ | --- | --- |
66
+ | 用途 | 一句话 |
67
+ | 参数 | 列出每个参数与示例 |
68
+ | 幂等性 | `idempotent` 或 `non-idempotent` |
69
+ | 危险级别 | `read-only` / `mutate-local` / `mutate-remote` |
70
+
71
+ 示例(Bash):
72
+
73
+ ```bash
74
+ #!/usr/bin/env bash
75
+ # 用途:清理本地 docker compose 卷,恢复干净开发环境
76
+ # 参数:--keep-data 保留持久化卷
77
+ # 幂等性:idempotent
78
+ # 危险级别:mutate-local
79
+ set -euo pipefail
80
+ ```
81
+
82
+ ### 2.3 跨平台
83
+
84
+ - 优先 Python / Node 实现
85
+ - Windows 专用写 `.ps1`,类 Unix 专用写 `.sh`
86
+ - **不要**在两类脚本之间互相调用(避免在某平台上失效)
87
+ - 跨平台脚本统一放 `scripts/<category>/`,按平台拆分版本时使用同名 + 不同扩展名
88
+
89
+ ### 2.4 oneoff/ 归档规则
90
+
91
+ - 每个 `oneoff/` 脚本顶部除了上述四字段外,**额外**记录:
92
+ - 创建日期
93
+ - 一次性目的(例如"修复 2025-10 数据迁移遗留")
94
+ - 创建后 **30 天**未被再次使用且任务已结束 → 移入 `docs/archive/scripts-oneoff/<date>-<name>/` 或删除
95
+ - CI 可启用 lint:`oneoff/` 下文件 mtime 早于 60 天则警告
96
+
97
+ ### 2.5 守门人
98
+
99
+ `@all-maintainers`。oneoff 脚本可单人合入;其他子目录至少一人 review。
100
+
101
+ ## 3. 升级判定
102
+
103
+ `scripts/` 中的脚本出现以下任一信号,应升级到 `tools/`:
104
+
105
+ | 信号 | 判定 |
106
+ | --- | --- |
107
+ | 出现第二个配置项 | 升级 |
108
+ | 出现第二个子命令 | 升级 |
109
+ | 需要独立依赖声明(package.json / requirements.txt) | 升级 |
110
+ | 需要被多模块或多 CI 阶段复用 | 升级 |
111
+ | 超过 200 行 | 强烈建议升级 |
112
+ | 需要拆分模块(多文件)| 必须升级 |
113
+
114
+ 升级流程:
115
+
116
+ 1. 在 `tools/` 下建子目录与 README
117
+ 2. 将 scripts/ 中的代码迁入并补依赖声明
118
+ 3. 替换所有调用方为新工具
119
+ 4. 删除原 scripts/ 文件,记录在 PR 描述中
120
+ 5. `scripts/README.md` 索引同步更新
121
+
122
+ ## 4. 索引维护
123
+
124
+ `scripts/README.md` 应列出:
125
+
126
+ - 子目录用途
127
+ - 关键脚本的入口与参数
128
+ - 升级到 tools/ 的历史脚本及其新位置(防止"找不到脚本"的迁移盲区)
@@ -0,0 +1,22 @@
1
+ # 过程文档
2
+
3
+ 草稿、会议记录、调研、未定稿的归属目录。**临时 / 讨论 / 未定稿只能放在这里**(AGENTS.md §2 不可协商原则)。
4
+
5
+ ## 子目录
6
+
7
+ | 目录 | 内容 |
8
+ |------|------|
9
+ | `drafts/` | 在编草稿(包括 ADR 草案、方案草稿) |
10
+ | `meeting-notes/` | 会议记录 |
11
+ | `spike-investigations/` | 技术调研 / 探针 |
12
+
13
+ ## 草稿生命周期
14
+
15
+ 1. 进 `drafts/<topic>-plan.md`
16
+ 2. 评审通过 → 提炼到对应编号目录
17
+ 3. 在草案文件顶部加"已采纳 → 见 …"指针
18
+ 4. 被否决 / 90 天未采纳 → 移入 `docs/archive/`
19
+
20
+ ## AI 触达模式
21
+
22
+ `mode: suggest`。草稿区允许 AI 协助起草;定稿由人审。
@@ -0,0 +1,10 @@
1
+ # AI 访问策略:docs/过程文档/
2
+ # 依据 ADR-0003 §4.3
3
+ mode: suggest
4
+ notes: |
5
+ 过程文档区。AI 可在此处生成新草稿(drafts/、meeting-notes/、
6
+ spike-investigations/);正式产出通过 PR 提炼到对应编号目录后,
7
+ 原文档头部加"已采纳 → 见 …"指针。
8
+
9
+ 本目录下所有 markdown 文件视为 suggest;AI 不应在没有显式指令
10
+ 的情况下大规模修改既有草稿,但可以扩写、添加新草稿。
@@ -0,0 +1,19 @@
1
+ # references/
2
+
3
+ 第三方资料的归属目录(行业标准、厂商手册、法规、合规参考)。
4
+
5
+ ## 子目录
6
+
7
+ | 目录 | 内容 |
8
+ |------|------|
9
+ | `standards/` | 行业 / 国际标准(RFC、ISO、GB 等) |
10
+ | `vendors/` | 第三方厂商技术手册(云服务、SDK、硬件) |
11
+ | `legal/` | 法律法规、合规要求、客户合同条款摘录 |
12
+
13
+ ## 来源元数据
14
+
15
+ 每个文件或子目录必须含 `_source.yaml` 说明来源,保留版权与可追溯性。完整规则见 [`../governance/docs-references.md`](../governance/docs-references.md)。
16
+
17
+ ## AI 触达模式
18
+
19
+ `mode: read-only`。第三方资料 AI 不得修改;新资料的纳入由人主导。
@@ -0,0 +1,9 @@
1
+ # docs/references/_ai-policy.yaml
2
+ # 依据 ADR-0003 §4.3
3
+
4
+ mode: read-only
5
+
6
+ notes: |
7
+ 第三方资料(行业标准、厂商手册、法规)。
8
+ AI 可读作为上下文,但不写入;新资料纳入由人主导。
9
+ 来源元数据规则见 docs/governance/docs-references.md。
@@ -0,0 +1,5 @@
1
+ # Copy this file to _source.yaml next to imported material and fill in.
2
+ source: ""
3
+ url: ""
4
+ retrieved: ""
5
+ version: ""
@@ -0,0 +1,5 @@
1
+ # Copy this file to _source.yaml next to imported material and fill in.
2
+ source: ""
3
+ url: ""
4
+ retrieved: ""
5
+ version: ""
@@ -0,0 +1,5 @@
1
+ # Copy this file to _source.yaml next to imported material and fill in.
2
+ source: ""
3
+ url: ""
4
+ retrieved: ""
5
+ version: ""