anyone-can-architect 0.2.0 → 0.4.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 (146) hide show
  1. package/CONTEXT.md +2 -2
  2. package/README.md +6 -4
  3. package/README.zh-CN.md +4 -2
  4. package/SSOT.md +5 -0
  5. package/VERSION +1 -1
  6. package/axioms/README.md +1 -1
  7. package/axioms/writing.md +3 -1
  8. package/dist/antigravity/aca/SKILL.md +3 -2
  9. package/dist/antigravity/aca-design/SKILL.md +12 -6
  10. package/dist/antigravity/aca-implement/SKILL.md +102 -114
  11. package/dist/antigravity/aca-release/SKILL.md +13 -20
  12. package/dist/antigravity/aca-repo-audit/SKILL.md +13 -9
  13. package/dist/antigravity/aca-review/SKILL.md +146 -182
  14. package/dist/antigravity/aca-test/SKILL.md +112 -0
  15. package/dist/antigravity/aca-walkthrough/SKILL.md +18 -14
  16. package/dist/antigravity-cli/aca/SKILL.md +3 -2
  17. package/dist/antigravity-cli/aca-design/SKILL.md +12 -6
  18. package/dist/antigravity-cli/aca-implement/SKILL.md +102 -114
  19. package/dist/antigravity-cli/aca-release/SKILL.md +13 -20
  20. package/dist/antigravity-cli/aca-repo-audit/SKILL.md +13 -9
  21. package/dist/antigravity-cli/aca-review/SKILL.md +146 -182
  22. package/dist/antigravity-cli/aca-test/SKILL.md +112 -0
  23. package/dist/antigravity-cli/aca-walkthrough/SKILL.md +18 -14
  24. package/dist/codex/aca/SKILL.md +3 -2
  25. package/dist/codex/aca-design/SKILL.md +12 -6
  26. package/dist/codex/aca-implement/SKILL.md +102 -114
  27. package/dist/codex/aca-release/SKILL.md +13 -20
  28. package/dist/codex/aca-repo-audit/SKILL.md +13 -9
  29. package/dist/codex/aca-review/SKILL.md +146 -182
  30. package/dist/codex/aca-test/SKILL.md +112 -0
  31. package/dist/codex/aca-walkthrough/SKILL.md +18 -14
  32. package/dist/cursor/aca/SKILL.md +3 -2
  33. package/dist/cursor/aca-design/SKILL.md +12 -6
  34. package/dist/cursor/aca-implement/SKILL.md +102 -114
  35. package/dist/cursor/aca-release/SKILL.md +13 -20
  36. package/dist/cursor/aca-repo-audit/SKILL.md +13 -9
  37. package/dist/cursor/aca-review/SKILL.md +146 -182
  38. package/dist/cursor/aca-test/SKILL.md +113 -0
  39. package/dist/cursor/aca-walkthrough/SKILL.md +18 -14
  40. package/dist/grok/aca/SKILL.md +3 -2
  41. package/dist/grok/aca-design/SKILL.md +12 -6
  42. package/dist/grok/aca-implement/SKILL.md +102 -114
  43. package/dist/grok/aca-release/SKILL.md +13 -20
  44. package/dist/grok/aca-repo-audit/SKILL.md +13 -9
  45. package/dist/grok/aca-review/SKILL.md +146 -182
  46. package/dist/grok/aca-test/SKILL.md +112 -0
  47. package/dist/grok/aca-walkthrough/SKILL.md +18 -14
  48. package/doc-design/document-sets/module.md +6 -2
  49. package/doc-design/document-sets/ops-guide.md +25 -27
  50. package/doc-design/documents/class-design.md +7 -4
  51. package/doc-design/documents/instrumentation.md +3 -2
  52. package/doc-design/documents/integration-guide.md +7 -5
  53. package/doc-design/documents/interaction.md +516 -143
  54. package/doc-design/documents/interface.md +12 -7
  55. package/doc-design/documents/release.md +137 -105
  56. package/doc-design/patterns/interface.md +135 -14
  57. package/doc-design/repo-types/client-sdk.md +3 -3
  58. package/doc-design/repo-types/web-app.md +11 -5
  59. package/meta-skills/aca/SKILL.md +3 -2
  60. package/meta-skills/aca/SKILL.md.tmpl +3 -2
  61. package/package.json +1 -1
  62. package/skills/aca-design/SKILL.md +12 -6
  63. package/skills/aca-design/SKILL.md.tmpl +9 -5
  64. package/skills/aca-implement/SKILL.md +102 -114
  65. package/skills/aca-implement/SKILL.md.tmpl +103 -115
  66. package/skills/aca-release/SKILL.md +13 -20
  67. package/skills/aca-release/SKILL.md.tmpl +13 -20
  68. package/skills/aca-repo-audit/SKILL.md +13 -9
  69. package/skills/aca-repo-audit/SKILL.md.tmpl +10 -8
  70. package/skills/aca-review/SKILL.md +146 -182
  71. package/skills/aca-review/SKILL.md.tmpl +143 -181
  72. package/skills/aca-test/SKILL.md +112 -0
  73. package/skills/aca-test/SKILL.md.tmpl +110 -0
  74. package/skills/aca-walkthrough/SKILL.md +18 -14
  75. package/skills/aca-walkthrough/SKILL.md.tmpl +15 -13
  76. package/zh-CN/CONTEXT.md +2 -2
  77. package/zh-CN/SSOT.md +5 -0
  78. package/zh-CN/axioms/README.md +1 -1
  79. package/zh-CN/axioms/writing.md +3 -1
  80. package/zh-CN/dist/antigravity/aca/SKILL.md +3 -2
  81. package/zh-CN/dist/antigravity/aca-design/SKILL.md +12 -6
  82. package/zh-CN/dist/antigravity/aca-implement/SKILL.md +102 -114
  83. package/zh-CN/dist/antigravity/aca-release/SKILL.md +71 -69
  84. package/zh-CN/dist/antigravity/aca-repo-audit/SKILL.md +39 -29
  85. package/zh-CN/dist/antigravity/aca-review/SKILL.md +143 -179
  86. package/zh-CN/dist/antigravity/aca-test/SKILL.md +112 -0
  87. package/zh-CN/dist/antigravity/aca-walkthrough/SKILL.md +18 -14
  88. package/zh-CN/dist/antigravity-cli/aca/SKILL.md +3 -2
  89. package/zh-CN/dist/antigravity-cli/aca-design/SKILL.md +12 -6
  90. package/zh-CN/dist/antigravity-cli/aca-implement/SKILL.md +102 -114
  91. package/zh-CN/dist/antigravity-cli/aca-release/SKILL.md +71 -69
  92. package/zh-CN/dist/antigravity-cli/aca-repo-audit/SKILL.md +39 -29
  93. package/zh-CN/dist/antigravity-cli/aca-review/SKILL.md +143 -179
  94. package/zh-CN/dist/antigravity-cli/aca-test/SKILL.md +112 -0
  95. package/zh-CN/dist/antigravity-cli/aca-walkthrough/SKILL.md +18 -14
  96. package/zh-CN/dist/codex/aca/SKILL.md +3 -2
  97. package/zh-CN/dist/codex/aca-design/SKILL.md +12 -6
  98. package/zh-CN/dist/codex/aca-implement/SKILL.md +102 -114
  99. package/zh-CN/dist/codex/aca-release/SKILL.md +71 -69
  100. package/zh-CN/dist/codex/aca-repo-audit/SKILL.md +39 -29
  101. package/zh-CN/dist/codex/aca-review/SKILL.md +143 -179
  102. package/zh-CN/dist/codex/aca-test/SKILL.md +112 -0
  103. package/zh-CN/dist/codex/aca-walkthrough/SKILL.md +18 -14
  104. package/zh-CN/dist/cursor/aca/SKILL.md +3 -2
  105. package/zh-CN/dist/cursor/aca-design/SKILL.md +12 -6
  106. package/zh-CN/dist/cursor/aca-implement/SKILL.md +102 -114
  107. package/zh-CN/dist/cursor/aca-release/SKILL.md +71 -69
  108. package/zh-CN/dist/cursor/aca-repo-audit/SKILL.md +39 -29
  109. package/zh-CN/dist/cursor/aca-review/SKILL.md +143 -179
  110. package/zh-CN/dist/cursor/aca-test/SKILL.md +113 -0
  111. package/zh-CN/dist/cursor/aca-walkthrough/SKILL.md +18 -14
  112. package/zh-CN/dist/grok/aca/SKILL.md +3 -2
  113. package/zh-CN/dist/grok/aca-design/SKILL.md +12 -6
  114. package/zh-CN/dist/grok/aca-implement/SKILL.md +102 -114
  115. package/zh-CN/dist/grok/aca-release/SKILL.md +71 -69
  116. package/zh-CN/dist/grok/aca-repo-audit/SKILL.md +39 -29
  117. package/zh-CN/dist/grok/aca-review/SKILL.md +143 -179
  118. package/zh-CN/dist/grok/aca-test/SKILL.md +112 -0
  119. package/zh-CN/dist/grok/aca-walkthrough/SKILL.md +18 -14
  120. package/zh-CN/doc-design/document-sets/module.md +6 -2
  121. package/zh-CN/doc-design/document-sets/ops-guide.md +25 -27
  122. package/zh-CN/doc-design/documents/class-design.md +7 -4
  123. package/zh-CN/doc-design/documents/instrumentation.md +3 -2
  124. package/zh-CN/doc-design/documents/integration-guide.md +7 -5
  125. package/zh-CN/doc-design/documents/interaction.md +516 -143
  126. package/zh-CN/doc-design/documents/interface.md +12 -7
  127. package/zh-CN/doc-design/documents/release.md +138 -106
  128. package/zh-CN/doc-design/patterns/interface.md +135 -14
  129. package/zh-CN/doc-design/repo-types/client-sdk.md +3 -3
  130. package/zh-CN/doc-design/repo-types/web-app.md +11 -5
  131. package/zh-CN/meta-skills/aca/SKILL.md +3 -2
  132. package/zh-CN/meta-skills/aca/SKILL.md.tmpl +3 -2
  133. package/zh-CN/skills/aca-design/SKILL.md +12 -6
  134. package/zh-CN/skills/aca-design/SKILL.md.tmpl +9 -5
  135. package/zh-CN/skills/aca-implement/SKILL.md +102 -114
  136. package/zh-CN/skills/aca-implement/SKILL.md.tmpl +102 -114
  137. package/zh-CN/skills/aca-release/SKILL.md +71 -69
  138. package/zh-CN/skills/aca-release/SKILL.md.tmpl +71 -69
  139. package/zh-CN/skills/aca-repo-audit/SKILL.md +39 -29
  140. package/zh-CN/skills/aca-repo-audit/SKILL.md.tmpl +36 -28
  141. package/zh-CN/skills/aca-review/SKILL.md +143 -179
  142. package/zh-CN/skills/aca-review/SKILL.md.tmpl +140 -178
  143. package/zh-CN/skills/aca-test/SKILL.md +112 -0
  144. package/zh-CN/skills/aca-test/SKILL.md.tmpl +110 -0
  145. package/zh-CN/skills/aca-walkthrough/SKILL.md +18 -14
  146. package/zh-CN/skills/aca-walkthrough/SKILL.md.tmpl +15 -13
@@ -18,9 +18,9 @@
18
18
  结构示意:
19
19
 
20
20
  ```text
21
- ## 1 公共契约 按需 · 数据契约
21
+ ## 1 公共契约 按需 · 数据契约及共用连接与认证约定
22
22
  ## 2 <一类业务>
23
- ### 2.1 共用契约 按需 · 数据契约
23
+ ### 2.1 共用契约 按需 · 数据契约及共用连接与认证约定
24
24
  ### 2.2 <接口> 模块接口
25
25
  ### 2.3 <接口> 模块接口
26
26
  ## 3 <接口> 业务只有一个接口时 chapter 本身就是接口 · 模块接口
@@ -30,20 +30,23 @@
30
30
  - 一类业务的 [chapter](../../CONTEXT.md#chapter):每个接口一个 [section](../../CONTEXT.md#section)
31
31
  - 共用契约 [section](../../CONTEXT.md#section):这类业务共用的契约
32
32
 
33
+ 数据结构与校验契约按[数据契约](../patterns/schema.md)表达
34
+ 共用连接与认证约定说明协议入口及认证方式,各接口引用对应内容
35
+
33
36
  ## 3 行文步骤
34
37
 
35
38
  1. 理解并列出全部内容,先不动笔
36
39
  - 理解业务:每个接口服务什么业务
37
- - 理解数据结构:每个接口用到的数据结构
40
+ - 理解契约:每个接口用到的数据结构、连接与认证约定
38
41
  2. 决定公共契约
39
- - 有被不同业务的接口共用的数据结构或校验契约:作为第一个 [chapter](../../CONTEXT.md#chapter),按数据契约 pattern 写
42
+ - 有被不同业务的接口共用的数据结构、校验契约或连接与认证约定:作为第一个 [chapter](../../CONTEXT.md#chapter)
40
43
  - 没有:跳过
41
44
  3. 划分 [chapter](../../CONTEXT.md#chapter) 与 [section](../../CONTEXT.md#section)
42
45
  - 按业务把接口归成几个 [chapter](../../CONTEXT.md#chapter),名字用业务语言,不用协议动词、路径或方法名
43
46
  - 只含一个接口的 [chapter](../../CONTEXT.md#chapter) 就是这个接口,不设 [section](../../CONTEXT.md#section)
44
- - 含多个接口的 [chapter](../../CONTEXT.md#chapter) 内有被多个接口共用的数据结构或校验契约:作为它的第一个 [section](../../CONTEXT.md#section),按数据契约 pattern 写
47
+ - 含多个接口的 [chapter](../../CONTEXT.md#chapter) 内有共用契约:作为它的第一个 [section](../../CONTEXT.md#section)
45
48
  - 含多个接口的 [chapter](../../CONTEXT.md#chapter) 一个接口一个 [section](../../CONTEXT.md#section),名字用业务语言
46
- 4. 逐个写接口:按模块接口 pattern 写,不加解释性说明,不列举调用方
49
+ 4. 逐个写接口:按[模块接口](../patterns/interface.md)选择语言或协议对应的表达方式,引用共用契约,不列举调用方
47
50
 
48
51
  ## 4 示例
49
52
 
@@ -54,6 +57,7 @@
54
57
  | `## 1 公共契约` | 只有标题 |
55
58
  | `### 1.1 错误体与错误码` | [数据契约](../patterns/schema.md) |
56
59
  | `### 1.2 公共类型` | [数据契约](../patterns/schema.md) |
60
+ | `### 1.3 连接与认证` | 共用协议约定,表达参考[连接与认证示例](../patterns/interface.md#51-连接与认证) |
57
61
  | `## 2 订单受理` | 只有标题 |
58
62
  | `### 2.1 订单共用类型` | [数据契约](../patterns/schema.md) |
59
63
  | `### 2.2 创建订单` | [模块接口](../patterns/interface.md) |
@@ -79,6 +83,7 @@
79
83
 
80
84
  - [ ] 只有 [chapter](../../CONTEXT.md#chapter) 与 [section](../../CONTEXT.md#section) 两层,没有一个 [chapter](../../CONTEXT.md#chapter) 只有一个 [section](../../CONTEXT.md#section)
81
85
  - [ ] [chapter](../../CONTEXT.md#chapter) 名与 [section](../../CONTEXT.md#section) 名是业务语言,没有协议动词、路径或方法名
82
- - [ ] 契约类型按使用范围归属,公共契约 [chapter](../../CONTEXT.md#chapter) 里没有只被一个 [chapter](../../CONTEXT.md#chapter) 使用的类型,共用契约 [section](../../CONTEXT.md#section) 里没有只被一个接口使用的类型
86
+ - [ ] 共用契约按使用范围归属,公共契约 [chapter](../../CONTEXT.md#chapter) 里没有只被一个 [chapter](../../CONTEXT.md#chapter) 使用的约定,共用契约 [section](../../CONTEXT.md#section) 里没有只被一个接口使用的约定
87
+ - [ ] 共用连接与认证约定可定位,各接口按调用方使用的语言或协议表达
83
88
  - [ ] 没有列举调用方
84
89
  - [ ] architecture 工况中调用到的接口都在本文档中,本文档列出的接口都有工况触发
@@ -3,162 +3,194 @@
3
3
  ## 1 文档定位
4
4
 
5
5
  定义本仓库从发布前验证到合入 main、锁定 Tag 的完整流程,包括每一步的执行方式、通过条件、失败处理与恢复位置
6
+ 同仓交付的各部分使用同一个仓库版本,统一定义发布流程
6
7
 
7
8
  ## 2 文档结构
8
9
 
9
- 第一章定义发布前提,包括版本来源、需要一致的版本记录、合并链与执行所需条件
10
- 第二章按本仓库的实际顺序展开发布流程,直到合入 main 并锁定 Tag
11
- 每步定义执行方式、通过条件、失败处理与恢复位置
10
+ 第一个 [chapter](../../CONTEXT.md#chapter) 用 [flowchart](../patterns/flowchart.md#21-流程图) 展示发布流程,节点引用对应阶段
11
+ 后续按阶段展开,可以各用一个 [chapter](../../CONTEXT.md#chapter)
12
+ 阶段较少时,可以合并在一个 [chapter](../../CONTEXT.md#chapter) 内,用 [section](../../CONTEXT.md#section) 分开
13
+ 每个阶段说明执行方式、通过条件、失败处理与恢复位置
12
14
  复杂阶段按实际内容[层层深入](../../skills/references/drill-down.md)
13
15
 
14
- 验证步骤按仓库需要安排,包括测试、构建、真实平台验证及其他必要操作
15
- 发布摘要归入锁定 Tag 的步骤,格式需要详细定义时在该步骤下展开
16
- 发布通告按需单独成章,定义触发方式、内容来源、渠道与失败重发
16
+ 发布前提作为需要核对的阶段,说明版本来源、版本记录、合并链及执行条件
17
+ 验证步骤按仓库需要安排,包括测试、构建、真实平台验证及其他必要操作,可统一执行全量验证,或按改动突破的设计边界与依赖范围分级定义
18
+ 发布摘要归入锁定 Tag 的阶段
19
+ 分支清理按仓库策略安排,范围为本次已合并且不再承担后续工作的分支
20
+ 发布通告按需安排
17
21
 
18
- 结构示意:
22
+ 以下[层级树](../patterns/hierarchy-tree.md#21-树)展示阶段分别成章的组织示例,具体阶段按仓库流程确定
19
23
 
20
24
  ```text
21
- ## 1 发布前提
22
- ## 2 发布流程
23
- ### 2.1 <执行阶段>
24
- ### 2.2 <执行阶段>
25
- …
26
- ## 3 发布通告 按需
25
+ <发布文档>
26
+ ├─ 1 发布流程 chapter
27
+ ├─ 2 确认发布前提 chapter
28
+ ├─ 3 收口版本记录 chapter
29
+ ├─ 4 验证候选版本 chapter
30
+ ├─ 5 合入 main chapter
31
+ ├─ 6 核对最终提交 chapter
32
+ ├─ 7 锁定版本 chapter
33
+ ├─ 8 清理版本分支 chapter
34
+ └─ 9 发布通告 chapter,按需
27
35
  ```
28
36
 
29
37
  ## 3 行文步骤
30
38
 
31
- 1. 确定发布前提
32
- - 定义版本号来源、需要一致的版本记录、合并链与目标 Tag
33
- - 确定执行所需的环境、权限、工具与外部依赖
34
- 2. 设计本仓库的发布流程
35
- - 按依赖关系安排版本记录收口、验证与合并等操作
36
- - 为每一步定义命令或操作方式、通过条件、失败处理与恢复位置
37
- - 验证涉及真实平台时,定义所需环境、数据与结果判定
38
- 3. 定义版本固化步骤
39
- - 核对最终提交包含本版内容,版本记录一致,验证结果适用于该提交
40
- - 确认版本按合并链合入 main,定义发布摘要的来源、格式与校验方式
41
- - 在 main 最终提交上创建 annotated Tag 并推送,核对远端 Tag 指向
42
- - Tag 创建后不移动、不重建,推送失败只重推
43
- - 同名 Tag 已存在且指向其他提交时停止,恢复执行时核对已有 Tag 的指向与注解
44
- 4. 按需定义发布通告
45
- - 定义触发方式、内容来源、渠道与接收范围
46
- - 内容从 Tag 注解提取,引用所用工具与校验规则
47
- - 使用飞书卡片时按[卡片示意](../patterns/lark-card-mockup.md)绘制
48
- - 定义凭据来源、缺失行为与失败重发方式,泄露处置引用安全或部署设计
49
- - 通告失败不改变版本固化事实,重发沿用已锁定的 Tag
50
- 5. 按 [§2](#2-文档结构)组织各章,核对完整流程
51
- - 前一步的结果满足后一步的前提,恢复执行不会重复不可重入的操作
52
- - 版本号、Tag、main 最终提交与验证结果能够相互追溯
39
+ 1. **确定发布输入**
40
+ - 确定版本来源、版本记录、合并链与目标 Tag
41
+ - 定位执行所需的环境、权限、工具与外部依赖
42
+ 2. **编排阶段与验证**
43
+ - 按依赖关系安排前提核对、版本记录收口、验证与合并,绘制流程总图
44
+ - 定义各阶段的操作、通过条件与失败后的恢复位置
45
+ - 按改动影响分级验证时,定义对应测试集、升级为全量验证的条件及定期兜底
46
+ - 验证涉及真实平台或模型评测时,定义所需环境、数据与结果判定
47
+ - 最终核验按已有结果的复用条件判断是否重验,验证结果关联最终提交
48
+ 3. **定义版本固化与后续处理**
49
+ - 定义最终版本记录核对、发布摘要的来源、格式与校验方式
50
+ - 在已验证的 main 提交上创建 annotated Tag,推送后核对远端指向与注解
51
+ - Tag 创建后不移动、不重建,推送失败只重推,同名 Tag 冲突时停止
52
+ - 按仓库策略安排本次已合并分支的清理
53
+ - 需要通告时,定义从 Tag 注解提取内容的方式、渠道、发送结果核对与失败重发
54
+ 使用飞书卡片时按[卡片示意](../patterns/lark-card-mockup.md)绘制
55
+ 4. **组织正文并核对**
56
+ - 按[文档结构](#2-文档结构)展开各阶段,核对前后步骤与失败恢复路径
57
+ - 按[检查条件](#5-检查条件)核对版本、Tag、最终提交与验证结果
53
58
 
54
59
  ## 4 示例
55
60
 
56
61
  ````markdown
57
62
  # 报告服务发布
58
63
 
59
- ## 1 发布前提
64
+ ## 1 发布流程
65
+
66
+ ```mermaid
67
+ flowchart TD
68
+ Prepare["确认发布前提 · §2"] --> Close["收口版本记录 · §3"]
69
+ Close --> Verify["验证候选版本 · §4"]
70
+ Verify -->|通过| Merge["合入 main · §5"]
71
+ Verify -->|失败,修正后重验| Close
72
+ Merge --> Final["核对最终提交 · §6"]
73
+ Final -->|通过或验证结果可复用| Tag["锁定版本 · §7"]
74
+ Final -->|需要修正,经修复分支重新验证| Close
75
+ Tag --> Cleanup["清理版本分支 · §8"]
76
+ Cleanup -->|已配置通告| Notice["发布通告 · §9"]
77
+ Cleanup -->|未配置通告| Done([完成])
78
+ Notice --> Done
79
+ click Prepare "#2-确认发布前提"
80
+ click Close "#3-收口版本记录"
81
+ click Verify "#4-验证候选版本"
82
+ click Merge "#5-合入-main"
83
+ click Final "#6-核对最终提交"
84
+ click Tag "#7-锁定版本"
85
+ click Cleanup "#8-清理版本分支"
86
+ click Notice "#9-发布通告"
87
+ ```
88
+
89
+ ## 2 确认发布前提
60
90
 
61
- | 内容 | 定义 |
91
+ 核对以下条件,未满足的条件补齐后继续
92
+
93
+ | 内容 | 本版要求 |
62
94
  | --- | --- |
63
95
  | 版本来源 | VERSION,本次为 2.0.0 |
64
96
  | 版本记录 | CHANGELOG 本版定版段 |
65
- | 一致性要求 | VERSION、pyproject.toml 的项目版本与目标 Tag 版本一致 |
66
- | 合并链 | feature/report-export-v2.0.0 → main,使用 Pull Request 合并 |
97
+ | 一致性要求 | VERSION、pyproject.toml 与目标 Tag 版本一致 |
98
+ | 合并链 | feature/report-export-v2.0.0 → main,通过 Pull Request 合并 |
67
99
  | Tag | v2.0.0,annotated Tag |
68
100
  | 执行环境 | Bash、Git、项目 Python 环境与容器构建工具 |
69
101
  | 仓库权限 | 提交版本记录、合并 Pull Request 与推送 Tag |
70
- | 验证环境 | 独立测试数据库与对象存储,凭据来源见[测试环境 §1](deployment.md#1-测试环境) |
71
-
72
- `scripts/release-verify.sh` 依次执行单元测试、数据库迁移测试、镜像构建及真实对象存储上传与下载验证
73
- 脚本记录源码提交、各项结果与镜像摘要,任一检查失败时返回非零退出码
74
- 验证产生的记录与镜像留在仓库外,验证后清理本次测试数据
75
-
76
- ## 2 发布流程
77
-
78
- ### 2.1 收口版本记录
79
-
80
- **执行**:将 VERSION 与 pyproject.toml 的项目版本更新为 2.0.0,收口 CHANGELOG 本版定版段并提交
102
+ | 验证环境 | 独立测试数据库与对象存储,使用[测试夹具](testcase.md#1-夹具)中定义的隔离资源 |
81
103
 
82
- **通过**:运行 `bash scripts/check-version.sh 2.0.0` 返回 0,工作区干净
104
+ `scripts/release-verify.sh` 执行单元测试、数据库迁移测试、镜像构建及对象存储上传与下载验证
105
+ 验证结果关联源码提交、验证输入、各项结果与镜像摘要,任一检查失败时返回非零退出码
106
+ 验证后清理本次测试数据
83
107
 
84
- **失败与恢复**:停在本阶段,修正版本记录并提交后重新校验
108
+ ## 3 收口版本记录
85
109
 
86
- ### 2.2 验证待合并版本
110
+ 1. 将 VERSION 与 pyproject.toml 的项目版本更新为 2.0.0,收口 CHANGELOG 本版定版段并提交
111
+ 2. 运行 `bash scripts/check-version.sh 2.0.0`
112
+ - 返回 0 且工作区干净:进入[候选验证](#4-验证候选版本)
113
+ - 校验失败:修正版本记录并提交后重新校验
87
114
 
88
- **执行**:运行 `bash scripts/release-verify.sh`
115
+ ## 4 验证候选版本
89
116
 
90
- **通过**:脚本返回 0,所有检查通过,验证记录的源码提交等于当前 HEAD
117
+ 1. 运行 `bash scripts/release-verify.sh`
118
+ 2. 核对执行结果
119
+ - 全部通过,结果关联当前候选提交:进入[合入 main](#5-合入-main)
120
+ - 验证失败:修正后重新执行本阶段
121
+ - 测试数据清理失败:先清理本次数据,再重新验证
91
122
 
92
- **失败与恢复**:不合并,修复并提交后重新执行本阶段
93
- 测试数据清理失败时,先清理本次运行的数据,再重新验证
123
+ ## 5 合入 main
94
124
 
95
- ### 2.3 合入 main
125
+ 1. 创建或更新 Pull Request,完成分支保护要求的审查与检查,再合入 main
126
+ - 需要解决冲突或修改内容:经[候选验证](#4-验证候选版本)后更新 Pull Request
127
+ - Pull Request 尚未合并:停在本阶段
128
+ - Pull Request 已合并:继续[最终核验](#6-核对最终提交)
129
+ 2. 恢复执行时先核对合并状态,已合并的 Pull Request 沿用其合并结果
96
130
 
97
- **执行**:创建 Pull Request,按仓库分支保护规则完成审查与必需检查,再合入 main
131
+ ## 6 核对最终提交
98
132
 
99
- **通过**:Pull Request 已合并,远端 main 包含本版全部提交
133
+ 1. 执行 `git fetch origin`,切换 main 并通过 `git pull --ff-only origin main` 同步
134
+ 2. 核对本地与远端 main 一致,工作区干净,运行 `bash scripts/check-version.sh 2.0.0` 通过
135
+ 3. 核对[候选验证](#4-验证候选版本)的结果是否适用于当前 main
136
+ - 被测内容、测试、夹具、配置、工具链与依赖环境一致,且验证不依赖变化的提交元数据:复用已有结果,并关联当前 main 提交
137
+ - 复用条件不满足:在当前 main 上运行 `bash scripts/release-verify.sh`
138
+ 4. 必需核对与验证均通过后,进入[锁定版本](#7-锁定版本)
139
+ 核对或验证未通过时,停在本阶段处理失败原因并重验
140
+ 需要修正内容时,经修复分支验证并合入 main 后,重新执行本阶段
100
141
 
101
- **失败与恢复**:未合并时停在本阶段
102
- 解决冲突或修改代码后回到 §2.2 验证,再更新 Pull Request
103
- 恢复执行前核对合并状态,已经合并的 Pull Request 不重复合并
142
+ 仅提交号变化时仍需核对上述验证条件,源码内容可用 `git diff --exit-code <候选提交> HEAD` 比较
104
143
 
105
- ### 2.4 核对最终提交
144
+ ## 7 锁定版本
106
145
 
107
- **执行**:执行 `git fetch origin`,切换到 main 并以 `git pull --ff-only origin main` 同步
108
- 重新运行版本校验与 `bash scripts/release-verify.sh`
146
+ 1. 从 CHANGELOG 本版定版段生成仓库外的摘要文件,按[摘要校验工具](../../bin/aca-tag-notify-check)校验格式
147
+ 摘要末条采用[最终核验](#6-核对最终提交)的验证结果
148
+ 校验失败时,修正摘要并重新校验后继续
109
149
 
110
- **通过**:本地 main 与远端 main 一致,工作区干净,版本记录正确,全部验证通过
111
- 验证记录的源码提交等于准备锁定的 main 提交
150
+ ```text
151
+ v2.0.0:报告导出
112
152
 
113
- **失败与恢复**:不创建 Tag
114
- 需要修正代码或版本记录时,经新的修复分支验证并合入 main 后,重新执行本阶段
115
- main 有新提交时,重新验证新的最终提交
116
-
117
- ### 2.5 锁定版本
118
-
119
- **执行**:从 CHANGELOG 本版定版段生成仓库外的摘要文件,按[摘要校验工具](../../bin/aca-tag-notify-check)校验格式
120
- 摘要末条记录 §2.4 的验证结果
121
-
122
- 摘要示例:
123
-
124
- ```text
125
- v2.0.0:报告导出
126
-
127
- ---NOTIFY-BEGIN---
128
- 📄 报告 · 支持导出并下载业务报告
129
- ✅ 验证 · 单元测试、迁移测试、镜像构建与对象存储验证通过
130
- ---NOTIFY-END---
131
- ```
153
+ ---NOTIFY-BEGIN---
154
+ 📄 报告 · 支持导出并下载业务报告
155
+ ✅ 验证 · 单元测试、迁移测试、镜像构建与对象存储验证通过
156
+ ---NOTIFY-END---
157
+ ```
132
158
 
133
- 创建 Tag 前再次同步远端,确认 main 仍指向 §2.4 验证的提交,目标 Tag 尚不存在
134
- 使用 `git tag -a v2.0.0 -F /tmp/report-service-v2.0.0.md` 创建 Tag,再执行 `git push origin v2.0.0`
159
+ 2. 再次同步远端,确认 main 仍指向已验证提交,核对本地与远端目标 Tag
160
+ - 本地与远端均无目标 Tag:使用 `git tag -a v2.0.0 <已验证的main提交> -F /tmp/report-service-v2.0.0.md` 创建 Tag,再执行 `git push origin v2.0.0`
161
+ - main 已变化:回到[最终核验](#6-核对最终提交)
162
+ - Tag 已存在且指向与注解匹配:沿用已有 Tag,远端尚无该 Tag 时补推送
163
+ - 同名 Tag 的指向或注解不匹配:停止并报告冲突
164
+ 3. 核对远端为 annotated Tag,指向已验证的 main 提交,注解包含本版摘要
135
165
 
136
- **通过**:远端 Tag 存在,指向已验证的 main 提交,注解包含本版摘要
166
+ ## 8 清理版本分支
137
167
 
138
- **失败与恢复**:main 已变化时回到 §2.4
139
- 创建前校验失败时,修正摘要或前置条件后重试
140
- Tag 已创建时核对指向与注解,匹配时只补推送,不移动或重建
141
- 同名 Tag 的指向或注解不匹配时停止,报告冲突
168
+ 1. 核对远端 Tag 已通过验证,确认本次版本分支已经合入 main,且不再承担后续工作
169
+ 2. 按本仓库策略清理该版本分支
170
+ - 满足清理条件:删除本次已合并的本地与远端版本分支
171
+ - 仍承担后续工作或无法确认合并情况:保留该分支
172
+ - 清理失败:保留已固化的 Tag,修复清理问题后继续本阶段
142
173
 
143
- ## 3 发布通告
174
+ ## 9 发布通告
144
175
 
145
- 远端 v* Tag 推送触发通告流水线,从 Tag 注解提取通告内容,发送到研发发布群
146
- 内容提取使用[通告提取工具](../../bin/aca-tag-notify-extract)
147
- 机器人凭据来源与泄露处置见[发布机器人 §3](security.md#3-发布机器人)
176
+ 远端 v* Tag 推送触发通告流水线,使用[通告提取工具](../../bin/aca-tag-notify-extract)从 Tag 注解提取内容,发送到研发发布群
177
+ 机器人凭据来源与泄露处置见[发布机器人](security.md#3-发布机器人)
148
178
 
149
- 凭据缺失或发送失败时流水线失败,版本仍保持固化
150
- 修复后使用同一 Tag 重跑通告任务,不重新执行合并、验证或创建 Tag
179
+ 核对通告任务的实际发送结果
180
+ 凭据缺失或发送失败时,补齐凭据或修复故障后,使用同一 Tag 重跑通告任务
151
181
  ````
152
182
 
153
183
  ## 5 检查条件
154
184
 
155
- - [ ] 发布前提定义版本来源、版本记录、合并链、目标 Tag 与执行所需条件
185
+ - [ ] 总图与对应阶段一致,发布前提包含版本来源、版本记录、合并链、目标 Tag 与执行条件
156
186
  - [ ] 流程覆盖本仓库从发布前验证到合入 main、锁定 Tag 的全部必要操作
157
- - [ ] 每一步有执行方式、通过条件、失败处理与恢复位置
158
- - [ ] 验证环境与结果判定已定义,验证结果对应最终锁定的提交
159
- - [ ] 各步骤的前提与结果能够衔接,恢复执行不重复不可重入的操作
187
+ - [ ] 每个阶段有执行方式、通过条件、失败处理与恢复位置
188
+ - [ ] 验证环境、命令与结果判定已定义,已有结果按复用条件核对并关联最终提交
189
+ - [ ] 如采用分级验证,不同影响范围对应的测试集、升级为全量验证的条件及全量验证的兜底方式已定义
190
+ - [ ] 各阶段的前提与结果能够衔接,恢复执行有明确位置
160
191
  - [ ] 版本记录一致,摘要来源、格式与校验方式已定义
161
192
  - [ ] 远端 annotated Tag 指向已验证的 main 最终提交,版本、提交与验证结果可追溯
162
193
  - [ ] Tag 不移动、不重建,推送失败只重推,同名 Tag 的指向或注解冲突时停止
163
- - [ ] 如配置通告,触发、内容提取、渠道、凭据来源、失败行为与重发方式已定义
164
- - [ ] 通告失败不改变版本固化事实,重发使用同一 Tag
194
+ - [ ] 如配置分支清理,范围限定为本次已合并且不再承担后续工作的分支
195
+ - [ ] 如配置通告,触发、内容提取、渠道、凭据来源、发送结果核对与失败重发方式明确
196
+ - [ ] 清理或通告失败时,继续对应阶段并沿用已固化版本
@@ -14,11 +14,19 @@
14
14
  | --- | --- | --- |
15
15
  | 接口定义 | 始终必需 | [§2.1](#21-接口定义) |
16
16
  | 数据结构说明 | 始终必需 | [§2.2](#22-数据结构说明) |
17
- | 业务解释 | 原生文档机制无法承载时必需 | [§2.3](#23-业务解释) |
17
+ | 业务解释 | 声明及关联说明无法承载时必需 | [§2.3](#23-业务解释) |
18
18
 
19
19
  ### 2.1 接口定义
20
20
 
21
- 使用模块方法的原始声明或网络接口的接口描述规范
21
+ 按调用方使用的语言或协议选择表达方式,常见接口如下
22
+
23
+ | 接口对象 | 表达方式 | 契约内容 |
24
+ | --- | --- | --- |
25
+ | 语言方法 | 对应语言的原始声明与文档机制 | 方法签名、参数、返回与异常 |
26
+ | HTTP 接口 | 所选接口描述规范,如 OpenAPI | HTTP 方法、路径、鉴权、请求与响应 |
27
+ | 事件接口 | 所选协议的事件契约 | 连接入口、事件名、发送方向、消息结构与确认方式 |
28
+
29
+ 其他协议按所选协议的接口描述方式定义
22
30
  在声明关联的文档说明中写清调用目的、业务能力、结果交付方式、异常及触发条件
23
31
  按需说明顺序、范围、空结果、失败、超时及业务副作用
24
32
  接口具有幂等性时,说明重复调用的业务含义
@@ -28,7 +36,8 @@
28
36
 
29
37
  ### 2.2 数据结构说明
30
38
 
31
- 使用类型声明及其文档注释、文档字符串或描述字段,已有定义直接引用
39
+ 使用对应语言的类型声明或所选数据描述规范,说明写在文档注释、文档字符串或描述字段中
40
+ 已有定义直接引用
32
41
  被依赖的类型在前,引用它的类型在后
33
42
  在参数、返回类型与字段声明处说明业务含义、取值约束与适用的默认值
34
43
  类型、必填性、枚举等可声明的约束直接写入声明,各类结果的业务含义写入对应的文档说明
@@ -38,7 +47,7 @@
38
47
 
39
48
  ### 2.3 业务解释
40
49
 
41
- 使用代码块外的文字或表格,仅补充原生文档机制未表达的业务含义与约束
50
+ 使用代码块外的文字或表格,仅补充声明及关联说明未表达的业务含义与约束
42
51
  每条业务解释标明对应的接口、字段或结果
43
52
 
44
53
  ## 3 模块方法示例:取消订单(TypeScript)
@@ -178,9 +187,119 @@ export declare function cancelOrder(
178
187
  }
179
188
  ```
180
189
 
181
- ## 5 检查条件
190
+ ## 5 Socket.IO 事件示例:取消订单与状态通知
191
+
192
+ 采用 Socket.IO 4.x,事件映射按[官方类型声明](../../SSOT.md#6-api-设计)表达
193
+ 载荷使用 zod [数据契约](schema.md#21-契约声明),从校验声明派生事件参数类型
194
+
195
+ ### 5.1 连接与认证
196
+
197
+ 以下约定由本节两个事件共用
198
+
199
+ | 项目 | 约定 |
200
+ | --- | --- |
201
+ | 服务地址 | `https://api.example.com` |
202
+ | 连接 path | `/socket.io/` |
203
+ | namespace | `/orders` |
204
+ | 连接认证 | `auth.token` 携带订单访问令牌,结构见 `OrderAuthSchema` |
205
+ | 认证失败 | 拒绝连接,客户端收到 `connect_error`,`message` 为 `UNAUTHORIZED` |
206
+
207
+ ### 5.2 消息数据
208
+
209
+ ```typescript
210
+ import { z } from "zod";
211
+
212
+ /** 订单唯一标识,不能为空或仅含空白字符 */
213
+ const OrderIdSchema = z.string().regex(/\S/);
214
+
215
+ export const OrderAuthSchema = z.object({
216
+ /** 已取得的订单访问令牌 */
217
+ token: z.string().min(1),
218
+ }).strict();
219
+
220
+ export const OrderSchema = z.object({
221
+ id: OrderIdSchema,
222
+ /** 订单当前业务状态 */
223
+ status: z.enum([
224
+ "pending_payment", // 待付款
225
+ "paid", // 已付款
226
+ "cancelled", // 已取消
227
+ ]),
228
+ }).strict();
229
+
230
+ export const CancelRequestSchema = z.object({
231
+ /** 要申请取消的订单 */
232
+ orderId: OrderIdSchema,
233
+ }).strict();
234
+
235
+ const CancelledOrderSchema = OrderSchema.extend({ status: z.literal("cancelled") });
236
+ const PaidOrderSchema = OrderSchema.extend({ status: z.literal("paid") });
237
+
238
+ export const CancelAckSchema = z.discriminatedUnion("outcome", [
239
+ // 本次取消已完成,返回取消后的订单
240
+ z.object({ outcome: z.literal("cancelled"), order: CancelledOrderSchema }).strict(),
241
+ // 此前已取消,返回当前订单
242
+ z.object({ outcome: z.literal("already_cancelled"), order: CancelledOrderSchema }).strict(),
243
+ // 订单已付款,返回当前订单
244
+ z.object({ outcome: z.literal("not_allowed"), order: PaidOrderSchema }).strict(),
245
+ // 指定订单不存在
246
+ z.object({ outcome: z.literal("not_found") }).strict(),
247
+ // 请求不符合 CancelRequestSchema
248
+ z.object({ outcome: z.literal("invalid_request") }).strict(),
249
+ // 当前身份没有操作该订单的权限
250
+ z.object({ outcome: z.literal("forbidden") }).strict(),
251
+ // 本次处理未能确认取消结果
252
+ z.object({ outcome: z.literal("failed") }).strict(),
253
+ ]);
254
+
255
+ /** 客户端已收到本次订单状态通知 */
256
+ export const StatusAckSchema = z.object({
257
+ outcome: z.literal("received"),
258
+ }).strict();
259
+
260
+ export type Order = z.infer<typeof OrderSchema>;
261
+ export type CancelRequest = z.infer<typeof CancelRequestSchema>;
262
+ export type CancelAck = z.infer<typeof CancelAckSchema>;
263
+ export type StatusAck = z.infer<typeof StatusAckSchema>;
264
+ ```
265
+
266
+ ### 5.3 分方向事件声明
267
+
268
+ 以下声明与[消息数据](#52-消息数据)合并为同一个 TypeScript 文件
269
+
270
+ ```typescript
271
+ import type { Socket } from "socket.io-client";
272
+
273
+ export interface ClientToServerEvents {
274
+ /**
275
+ * 客户端向服务端申请取消订单
276
+ * 订单须属于当前身份的可操作范围
277
+ * @param request 取消请求,按 CancelRequestSchema 校验
278
+ * @param ack 交付本次取消的业务结果,按 CancelAckSchema 校验
279
+ * @remarks 5 秒未收到确认或连接中断时,可重发同一 orderId;
280
+ * 已取消的订单返回 already_cancelled,不重复产生取消效果
281
+ */
282
+ "order.cancel": (request: CancelRequest, ack: (result: CancelAck) => void) => void;
283
+ }
284
+
285
+ export interface ServerToClientEvents {
286
+ /**
287
+ * 服务端向客户端推送当前身份可访问订单的最新状态
288
+ * @param order 订单状态,按 OrderSchema 校验
289
+ * @param ack 客户端确认收到本次通知,按 StatusAckSchema 校验
290
+ * @remarks 服务端等待确认 5 秒,本例超时后不重发该通知;
291
+ * 重连后服务端推送当前可访问订单的最新状态
292
+ */
293
+ "order.status": (order: Order, ack: (result: StatusAck) => void) => void;
294
+ }
295
+
296
+ /** 客户端接收 ServerToClientEvents,发送 ClientToServerEvents */
297
+ export type OrderSocket = Socket<ServerToClientEvents, ClientToServerEvents>;
298
+ ```
299
+
300
+ ## 6 检查条件
182
301
 
183
- ### 5.1 接口契约混入实现机制
302
+ ### 6.1 接口契约混入实现机制
184
303
 
185
304
  - [ ] 能力行为不变、内部实现更换后,接口描述仍成立
186
305
  - [ ] 实现机制未替代调用方可验证的行为约束
@@ -193,10 +312,10 @@ export declare function cancelOrder(
193
312
  | 并行查询库存与物流,超时取消在途请求 | 超时时返回已查到的信息,未查到的部分标记为超时 |
194
313
  | 查询走只读副本,不参与事务 | 查询不会修改订单 |
195
314
 
196
- ### 5.2 说明与声明分离
315
+ ### 6.2 说明与声明分离
197
316
 
198
- - [ ] 接口与数据结构均有声明及说明,优先使用目标技术栈的原生文档机制
199
- - [ ] 独立业务解释仅补充原生文档机制无法承载的内容,且能定位对应声明
317
+ - [ ] 接口与数据结构按调用方使用的语言或协议声明,说明写在对应文档机制或描述字段中
318
+ - [ ] 独立业务解释仅补充声明及关联说明无法承载的内容,且能定位对应声明
200
319
 
201
320
  **反例**
202
321
 
@@ -204,9 +323,11 @@ export declare function cancelOrder(
204
323
 
205
324
  调用方必须在声明与表格之间对照,接口契约未在声明处完整表达
206
325
 
207
- ### 5.3 接口定义不规范或类型顺序不符
326
+ ### 6.3 接口定义不规范或类型顺序不符
208
327
 
209
328
  - [ ] 模块方法使用对应语言的原始声明,网络接口按所选接口描述规范定义
329
+ - [ ] 网络接口的连接入口可定位,事件契约明确事件名与发送方向
330
+ - [ ] 采用确认机制时,确认结果的业务含义明确
210
331
  - [ ] 数据结构使用对应语言的类型声明或所选接口描述规范定义
211
332
  - [ ] 数据结构声明中,被依赖的类型在前,引用它的类型在后
212
333
 
@@ -232,7 +353,7 @@ export declare function cancelOrder(
232
353
 
233
354
  该样例未定义字段是否必填,也未定义 `outcome` 的完整允许取值
234
355
 
235
- ### 5.4 数据结构说明不完整
356
+ ### 6.4 数据结构说明不完整
236
357
 
237
358
  - [ ] 每个输入、输出及其数据字段均有业务含义、取值约束与适用的默认值说明
238
359
  - [ ] 沿类型依赖递归说明,直至所用语言或描述规范的基本数据类型
@@ -250,7 +371,7 @@ export interface OrderSummary {
250
371
 
251
372
  既没有给出 `OrderStatus` 的定义与取值含义,也没有提供具体引用位置,无法继续查到完整说明
252
373
 
253
- ### 5.5 接口能力或输出含义不清
374
+ ### 6.5 接口能力或输出含义不清
254
375
 
255
376
  - [ ] 说明调用目的、接口提供的业务能力,以及已约定的各类输出结果的业务含义与交付方式
256
377
  - [ ] 适用的顺序、范围、空结果、失败、超时及业务副作用均有明确约定
@@ -265,9 +386,9 @@ export declare function cancelOrder(orderId: string): Promise<CancelOrderResult>
265
386
 
266
387
  没有说明重复调用、订单不存在、订单已付款时各自得到什么结果,调用方无法据此处理任何一种非正常情况
267
388
 
268
- ### 5.6 文字复述了声明已表达的内容
389
+ ### 6.6 文字复述了声明已表达的内容
269
390
 
270
- - [ ] 原生文档说明补充业务含义与约束,不重复声明已经明确的类型、只读性等信息
391
+ - [ ] 声明关联的说明补充业务含义与约束,不重复声明已经明确的类型、只读性等信息
271
392
 
272
393
  **反例**
273
394
 
@@ -46,7 +46,7 @@
46
46
  ```
47
47
 
48
48
  `user-guide/` 面向产品使用者,指导接入或使用产品
49
- `ops-guide/` 面向运营或数据平台使用者,指导数据收集、分析判断与运营动作,并验证动作效果
49
+ `ops-guide/` 面向运营或数据平台使用者,按本工程需要提供数据收集、分析判断或运营动作指导
50
50
  `user-guide/` 内的指南根据使用方式选用 [integration-guide](../documents/integration-guide.md) 或 [user-manual](../documents/user-manual.md) 的写法
51
51
  `ops-guide/` 按 [ops-guide](../document-sets/ops-guide.md) 文档组组织
52
52
 
@@ -64,7 +64,7 @@
64
64
  | `instrumentation.md` | 始终必需 | [instrumentation](../documents/instrumentation.md) |
65
65
  | `interface.md` | 始终必需 | [interface](../documents/interface.md) |
66
66
  | `module-<标识>/` 文档组 | SDK 包含多个业务模块 | [module](../document-sets/module.md) |
67
- | `ops-guide/` 文档组 | 运营或数据平台使用者需要数据收集、分析判断或运营操作指导 | [ops-guide](../document-sets/ops-guide.md) |
67
+ | `ops-guide/` 文档组 | 本工程需要向运营或数据平台使用者提供数据收集、分析判断或运营操作指导 | [ops-guide](../document-sets/ops-guide.md) |
68
68
  | `release.md` | 需要发布版本 | [release](../documents/release.md) |
69
69
  | `security.md` | 涉及凭据、用户数据、网络传输或权限 | [security](../documents/security.md) |
70
70
  | `testcase.md` | 始终必需 | [testcase](../documents/testcase.md) |
@@ -143,7 +143,7 @@ SDK 分发与后台部署分别由 `sdk/design/distribution.md` 和 `backend/des
143
143
  必要条件沿用各自类型规则
144
144
  运营指南按采集、分析与动作职责分篇
145
145
  各篇的内容组织沿用 [ops-guide](../document-sets/ops-guide.md) 文档组与对应文档设计
146
- 一个运营目标涉及两端时,三篇指南引用对应端的契约、数据与安全设计
146
+ 一个运营目标涉及两端时,已选用的指南引用对应端的契约、数据与安全设计
147
147
  通过跨文档引用串联数据采集、分析判断、运营动作与效果验证
148
148
  共用方法与操作在一处定义,其他指南引用
149
149