universal-dev-standards 5.1.0-beta.7 → 5.1.1

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 (116) hide show
  1. package/README.md +6 -0
  2. package/bin/uds.js +2 -0
  3. package/bundled/ai/standards/checkin-standards.ai.yaml +18 -0
  4. package/bundled/ai/standards/test-governance.ai.yaml +12 -0
  5. package/bundled/ai/standards/testing.ai.yaml +14 -0
  6. package/bundled/ai/standards/translation-lifecycle-standards.ai.yaml +145 -0
  7. package/bundled/core/checkin-standards.md +21 -2
  8. package/bundled/core/test-governance.md +3 -0
  9. package/bundled/core/testing-standards.md +25 -2
  10. package/bundled/core/translation-lifecycle-standards.md +162 -0
  11. package/bundled/locales/zh-CN/CHANGELOG.md +50 -3
  12. package/bundled/locales/zh-CN/README.md +1 -1
  13. package/bundled/locales/zh-CN/core/anti-hallucination.md +22 -3
  14. package/bundled/locales/zh-CN/core/anti-sycophancy-prompting.md +192 -0
  15. package/bundled/locales/zh-CN/core/capability-declaration.md +123 -0
  16. package/bundled/locales/zh-CN/core/checkin-standards.md +22 -3
  17. package/bundled/locales/zh-CN/core/circuit-breaker.md +106 -0
  18. package/bundled/locales/zh-CN/core/dual-phase-output.md +103 -0
  19. package/bundled/locales/zh-CN/core/failure-source-taxonomy.md +99 -0
  20. package/bundled/locales/zh-CN/core/frontend-design-standards.md +289 -0
  21. package/bundled/locales/zh-CN/core/health-check-standards.md +144 -0
  22. package/bundled/locales/zh-CN/core/immutability-first.md +96 -0
  23. package/bundled/locales/zh-CN/core/packaging-standards.md +224 -0
  24. package/bundled/locales/zh-CN/core/recovery-recipe-registry.md +146 -0
  25. package/bundled/locales/zh-CN/core/retry-standards.md +131 -0
  26. package/bundled/locales/zh-CN/core/security-decision.md +104 -0
  27. package/bundled/locales/zh-CN/core/skill-standard-alignment-check.md +112 -0
  28. package/bundled/locales/zh-CN/core/standard-admission-criteria.md +104 -0
  29. package/bundled/locales/zh-CN/core/standard-lifecycle-management.md +116 -0
  30. package/bundled/locales/zh-CN/core/test-governance.md +14 -3
  31. package/bundled/locales/zh-CN/core/testing-standards.md +26 -3
  32. package/bundled/locales/zh-CN/core/timeout-standards.md +117 -0
  33. package/bundled/locales/zh-CN/core/token-budget.md +108 -0
  34. package/bundled/locales/zh-CN/core/translation-lifecycle-standards.md +159 -0
  35. package/bundled/locales/zh-TW/CHANGELOG.md +50 -3
  36. package/bundled/locales/zh-TW/README.md +1 -1
  37. package/bundled/locales/zh-TW/core/anti-sycophancy-prompting.md +8 -0
  38. package/bundled/locales/zh-TW/core/capability-declaration.md +111 -0
  39. package/bundled/locales/zh-TW/core/checkin-standards.md +24 -3
  40. package/bundled/locales/zh-TW/core/circuit-breaker.md +111 -0
  41. package/bundled/locales/zh-TW/core/dual-phase-output.md +132 -0
  42. package/bundled/locales/zh-TW/core/failure-source-taxonomy.md +146 -0
  43. package/bundled/locales/zh-TW/core/frontend-design-standards.md +460 -0
  44. package/bundled/locales/zh-TW/core/health-check-standards.md +144 -0
  45. package/bundled/locales/zh-TW/core/immutability-first.md +159 -0
  46. package/bundled/locales/zh-TW/core/recovery-recipe-registry.md +146 -0
  47. package/bundled/locales/zh-TW/core/retry-standards.md +140 -0
  48. package/bundled/locales/zh-TW/core/security-decision.md +120 -0
  49. package/bundled/locales/zh-TW/core/skill-standard-alignment-check.md +112 -0
  50. package/bundled/locales/zh-TW/core/standard-admission-criteria.md +104 -0
  51. package/bundled/locales/zh-TW/core/standard-lifecycle-management.md +116 -0
  52. package/bundled/locales/zh-TW/core/test-governance.md +14 -3
  53. package/bundled/locales/zh-TW/core/testing-standards.md +31 -0
  54. package/bundled/locales/zh-TW/core/timeout-standards.md +117 -0
  55. package/bundled/locales/zh-TW/core/token-budget.md +143 -0
  56. package/bundled/locales/zh-TW/core/translation-lifecycle-standards.md +159 -0
  57. package/bundled/locales/zh-TW/skills/ac-coverage-assistant/SKILL.md +1 -0
  58. package/bundled/locales/zh-TW/skills/adr-assistant/SKILL.md +1 -0
  59. package/bundled/locales/zh-TW/skills/ai-collaboration-standards/SKILL.md +1 -0
  60. package/bundled/locales/zh-TW/skills/ai-friendly-architecture/SKILL.md +1 -0
  61. package/bundled/locales/zh-TW/skills/ai-instruction-standards/SKILL.md +1 -0
  62. package/bundled/locales/zh-TW/skills/api-design-assistant/SKILL.md +1 -0
  63. package/bundled/locales/zh-TW/skills/atdd-assistant/SKILL.md +1 -0
  64. package/bundled/locales/zh-TW/skills/audit-assistant/SKILL.md +1 -0
  65. package/bundled/locales/zh-TW/skills/bdd-assistant/SKILL.md +1 -0
  66. package/bundled/locales/zh-TW/skills/brainstorm-assistant/SKILL.md +1 -0
  67. package/bundled/locales/zh-TW/skills/changelog-guide/SKILL.md +1 -0
  68. package/bundled/locales/zh-TW/skills/checkin-assistant/SKILL.md +1 -0
  69. package/bundled/locales/zh-TW/skills/ci-cd-assistant/SKILL.md +1 -0
  70. package/bundled/locales/zh-TW/skills/code-review-assistant/SKILL.md +1 -0
  71. package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +1 -0
  72. package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +1 -0
  73. package/bundled/locales/zh-TW/skills/database-assistant/SKILL.md +1 -0
  74. package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +1 -0
  75. package/bundled/locales/zh-TW/skills/docs-generator/SKILL.md +1 -0
  76. package/bundled/locales/zh-TW/skills/documentation-guide/SKILL.md +1 -0
  77. package/bundled/locales/zh-TW/skills/durable-execution-assistant/SKILL.md +1 -0
  78. package/bundled/locales/zh-TW/skills/e2e-assistant/SKILL.md +1 -0
  79. package/bundled/locales/zh-TW/skills/forward-derivation/SKILL.md +1 -0
  80. package/bundled/locales/zh-TW/skills/incident-response-assistant/SKILL.md +1 -0
  81. package/bundled/locales/zh-TW/skills/methodology-system/SKILL.md +1 -0
  82. package/bundled/locales/zh-TW/skills/metrics-dashboard-assistant/SKILL.md +1 -0
  83. package/bundled/locales/zh-TW/skills/migration-assistant/SKILL.md +1 -0
  84. package/bundled/locales/zh-TW/skills/observability-assistant/SKILL.md +1 -0
  85. package/bundled/locales/zh-TW/skills/pr-automation-assistant/SKILL.md +1 -0
  86. package/bundled/locales/zh-TW/skills/process-automation/SKILL.md +1 -0
  87. package/bundled/locales/zh-TW/skills/project-discovery/SKILL.md +1 -0
  88. package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md +1 -0
  89. package/bundled/locales/zh-TW/skills/refactoring-assistant/SKILL.md +1 -0
  90. package/bundled/locales/zh-TW/skills/release-standards/SKILL.md +1 -0
  91. package/bundled/locales/zh-TW/skills/requirement-assistant/SKILL.md +1 -0
  92. package/bundled/locales/zh-TW/skills/retrospective-assistant/SKILL.md +1 -0
  93. package/bundled/locales/zh-TW/skills/reverse-engineer/SKILL.md +1 -0
  94. package/bundled/locales/zh-TW/skills/runbook-assistant/SKILL.md +1 -0
  95. package/bundled/locales/zh-TW/skills/security-assistant/SKILL.md +1 -0
  96. package/bundled/locales/zh-TW/skills/security-scan-assistant/SKILL.md +1 -0
  97. package/bundled/locales/zh-TW/skills/slo-assistant/SKILL.md +1 -0
  98. package/bundled/locales/zh-TW/skills/spec-driven-dev/SKILL.md +1 -0
  99. package/bundled/locales/zh-TW/skills/tdd-assistant/SKILL.md +1 -0
  100. package/bundled/locales/zh-TW/skills/test-coverage-assistant/SKILL.md +1 -0
  101. package/bundled/skills/ai-collaboration-standards/SKILL.md +1 -0
  102. package/bundled/skills/ai-friendly-architecture/SKILL.md +1 -0
  103. package/bundled/skills/ai-instruction-standards/SKILL.md +1 -0
  104. package/bundled/skills/documentation-guide/SKILL.md +1 -0
  105. package/bundled/skills/error-code-guide/SKILL.md +1 -0
  106. package/bundled/skills/git-workflow-guide/SKILL.md +1 -0
  107. package/bundled/skills/logging-guide/SKILL.md +1 -0
  108. package/bundled/skills/project-structure-guide/SKILL.md +1 -0
  109. package/bundled/skills/testing-guide/SKILL.md +1 -0
  110. package/package.json +5 -4
  111. package/src/commands/check.js +6 -0
  112. package/src/commands/init.js +6 -0
  113. package/src/commands/update.js +6 -0
  114. package/src/utils/detect-self-adoption.js +173 -0
  115. package/src/utils/directory-mapper.js +2 -2
  116. package/standards-registry.json +15 -4
@@ -0,0 +1,192 @@
1
+ ---
2
+ source: ../../../core/anti-sycophancy-prompting.md
3
+ source_version: 1.0.0
4
+ translation_version: 1.0.0
5
+ last_synced: 2026-04-20
6
+ status: current
7
+ ---
8
+
9
+ # 防迎合提示词设计标准
10
+
11
+ > **语言**: [English](../../../core/anti-sycophancy-prompting.md) | 简体中文
12
+
13
+ **版本**: 1.0.0
14
+ **最后更新**: 2026-04-15
15
+ **适用范围**: 所有 AI Agent 实现与 LLM Prompt 设计
16
+ **Scope**: universal
17
+ **业界标准**: 无(UDS 原创,参考 RLHF 迎合性研究)
18
+
19
+ ---
20
+
21
+ ## 目的
22
+
23
+ 本标准定义一套技法与规则,用于设计能让 LLM 给出真实、批判性回应的提示词,而非迎合使用者的隐含偏好。
24
+
25
+ LLM 的迎合性源自 RLHF 训练目标:人类评分者倾向于给予令人愉快的回应高分,导致模型将「让使用者满意」置于「准确性」之上。
26
+
27
+ ---
28
+
29
+ ## 核心技法
30
+
31
+ ### 1. Socratic 反诘框架(REQ-1)
32
+
33
+ 将任务从「评估我的想法」改为「攻击我的想法」,消除迎合诱因。
34
+
35
+ | 应该做 | 不应该做 |
36
+ |--------|----------|
37
+ | ✅ 要求列出最致命的 3 个质疑 | ❌ 问「这个想法好吗?」 |
38
+ | ✅ 每个质疑必须有技术依据 | ❌ 允许模糊的正向框架 |
39
+ | ✅ 明确禁止正向开场词语 | ❌ 接受「很好的想法,但是...」模式 |
40
+
41
+ **Prompt 模板**:
42
+ ```
43
+ 不要评估好坏。
44
+ 针对以下想法,列出最致命的 3 个质疑:[你的想法]
45
+ 每个质疑必须有技术依据,且让我无法轻易反驳。
46
+ ```
47
+
48
+ ---
49
+
50
+ ### 2. 先问立场防锚定协议(REQ-2)
51
+
52
+ 在使用者揭示立场前先取得 LLM 的独立判断,防止锚定效应。
53
+
54
+ | 步骤 | 动作 |
55
+ |------|------|
56
+ | 1 | 在未揭示偏好的情况下询问中立比较 |
57
+ | 2 | 取得独立判断 |
58
+ | 3 | 揭示使用者立场 |
59
+ | 4 | 若模型改变立场,要求提出明确的技术理由 |
60
+
61
+ **工作流程**:
62
+ ```
63
+ 回合 1:「针对 [情境],[A] 和 [B] 哪个更好?」
64
+ → 等待独立判断
65
+
66
+ 回合 2:「我倾向 [A]。这改变你的评估吗?为什么?」
67
+ → 模型若改口必须以技术事实为依据
68
+ ```
69
+
70
+ ---
71
+
72
+ ### 3. 强制双栏对称输出(REQ-3)
73
+
74
+ 用格式约束强迫呈现对立观点的平衡。
75
+
76
+ **必要格式**:
77
+ ```
78
+ | 支持这个决策的论点 | 反对这个决策的论点 |
79
+ |-------------------|-------------------|
80
+ | [同等份量的内容] | [同等份量的内容] |
81
+
82
+ 净建议:[必须明确表态,可以是「建议反对」]
83
+ ```
84
+
85
+ **规则**:
86
+ - 两栏字数差距不超过 20%
87
+ - 净建议必须明确,可以是否定的
88
+ - 模型不得借由填充一栏来规避格式
89
+
90
+ ---
91
+
92
+ ### 4. 信心度与不确定性标记(REQ-4)
93
+
94
+ 要求在所有建议上附加信心评分,呈现不确定性。
95
+
96
+ **格式**:
97
+ ```
98
+ 建议:[具体行动]
99
+ 信心:[1-5] — [不确定性原因]
100
+ 未知:[哪些信息会改变这个评估]
101
+ ```
102
+
103
+ **信心度定义**:
104
+
105
+ | 等级 | 意义 |
106
+ |------|------|
107
+ | 5 | 已在类似规模验证,高确定性 |
108
+ | 4 | 业界标准,有充分文献支持 |
109
+ | 3 | 合理推断,建议 PoC 验证 |
110
+ | 2 | 不确定,强烈建议先进行 Spike |
111
+ | 1 | 高度不确定,不建议直接采用 |
112
+
113
+ **规则**:
114
+ - 信心 < 3 必须标示「需要更多信息才能确认」
115
+ - 所有重要主张都需要信心标记
116
+ - 不确定性必须具体(说明哪些信息可以解决不确定性)
117
+
118
+ ---
119
+
120
+ ### 5. 迎合性回应启发式检测(REQ-5)
121
+
122
+ 用于检测迎合性回应的启发式规则,可用于自动化后处理。
123
+
124
+ | 信号类型 | 检测规则 |
125
+ |----------|----------|
126
+ | 正向开场 | 回应前 50 个 token 包含迎合性词语(如「很好」「有趣」「当然」「当然可以」) |
127
+ | 立场翻转 | 使用者揭示偏好后,模型在没有新技术证据的情况下改变立场 |
128
+ | 风险淡化 | 句式:「虽然有些小问题,但整体上...」而未说明具体问题 |
129
+ | 缺乏量化 | 重要建议缺少信心评分或具体度量指标 |
130
+
131
+ **触发条件**:检测到 2 个以上信号 → 以 Red Team 框架触发再评估。
132
+
133
+ ---
134
+
135
+ ## 禁止行为
136
+
137
+ | 禁止 | 正确做法 |
138
+ |------|----------|
139
+ | 以正向肯定开场批评 | 直接从分析开始 |
140
+ | 在无新技术证据的情况下改变立场 | 维持立场,或引用具体的新信息 |
141
+ | 在无依据的情况下将风险描述为「小问题」 | 量化风险或解释为何风险有界 |
142
+ | 提供重要建议却不附信心评分 | 始终附上信心(1-5)与不确定性说明 |
143
+
144
+ ---
145
+
146
+ ## 与 Agent Prompt 的整合
147
+
148
+ 套用至 AI Agent 时:
149
+
150
+ | Agent 类型 | 套用规则 |
151
+ |------------|----------|
152
+ | 代码审查 Agent | REQ-1(Socratic)+ REQ-3(双栏)+ REQ-5(检测) |
153
+ | 架构建议 Agent | REQ-2(先问立场)+ REQ-4(信心度)+ REQ-5(检测) |
154
+ | Bug 分析 Agent | REQ-1(Socratic)+ REQ-4(信心度) |
155
+ | 一般咨询 Agent | REQ-3(双栏)+ REQ-4(信心度) |
156
+
157
+ ---
158
+
159
+ ## 完整防迎合 Prompt 模板
160
+
161
+ ```
162
+ 你是一位对我毫无感情的领域专家。
163
+ 你的职责是找出我思考中的盲点,不是让我感觉良好。
164
+
165
+ 规则:
166
+ - 禁止以正向词语开场(很好、有趣、不错、当然)
167
+ - 每个建议必须附上信心等级(1-5)和你不确定的地方
168
+ - 若你认为我的方向是错的,直接说
169
+
170
+ 我的问题:[问题]
171
+
172
+ 请先列出这个问题中我可能持有的错误假设,
173
+ 再给出你认为正确的建议。
174
+ ```
175
+
176
+ ---
177
+
178
+ ## 检查清单
179
+
180
+ - [ ] 提示词未邀请认同(「这样好吗?」)
181
+ - [ ] 明确禁止正向开场词语
182
+ - [ ] 在揭示使用者偏好前先取得模型的独立立场(若适用)
183
+ - [ ] 评估任务强制使用双栏格式
184
+ - [ ] 重要建议需要信心等级
185
+ - [ ] 对输出套用迎合性检测,再呈现给使用者
186
+
187
+ ---
188
+
189
+ ## 相关标准
190
+
191
+ - [anti-hallucination.md](../../../core/anti-hallucination.md) — 防止幻觉;与防迎合互补
192
+ - [agent-epistemic-calibration.md](../../../core/agent-epistemic-calibration.md) — Agent 设计中的认知谦逊(若适用)
@@ -0,0 +1,123 @@
1
+ ---
2
+ source: ../../../core/capability-declaration.md
3
+ source_version: 1.0.0
4
+ translation_version: 1.0.0
5
+ last_synced: 2026-04-20
6
+ status: current
7
+ ---
8
+
9
+ # Fail-Closed 能力声明标准
10
+
11
+ > **语言**: [English](../../../core/capability-declaration.md) | 简体中文
12
+
13
+ **版本**: 1.0.0
14
+ **最后更新**: 2026-04-17
15
+ **状态**: Trial(到期 2026-10-17)
16
+ **适用范围**: universal
17
+ **来源**: XSPEC-068(DEC-043 Wave 1 可靠性套件)
18
+
19
+ ---
20
+
21
+ ## 目的
22
+
23
+ Fail-Closed 能力声明:工具 / Adapter 默认不安全,必须明确声明才视为安全。
24
+
25
+ 各工具和 Adapter 的并发安全性、只读性等能力未明确声明,导致 Agent 编排时无法判断是否可并发调用。本标准要求所有工具和 Adapter 必须在接口中明确声明其能力属性,未声明的属性默认为 false(Fail-Closed)。
26
+
27
+ ---
28
+
29
+ ## 核心规范
30
+
31
+ - 所有工具(Tool)和 Adapter 必须声明能力接口(`CapabilityDeclaration`)
32
+ - `isConcurrencySafe` 默认 `false`(未声明 = 不可并发)
33
+ - `isReadOnly` 默认 `false`(未声明 = 可能修改状态)
34
+ - `supportsPartialFailure` 默认 `false`
35
+ - Agent 编排器在并发调用前必须检查 `isConcurrencySafe`
36
+
37
+ ---
38
+
39
+ ## CapabilityDeclaration 接口
40
+
41
+ ```typescript
42
+ interface CapabilityDeclaration {
43
+ toolId: string;
44
+
45
+ // 并发安全性:未声明默认 false
46
+ isConcurrencySafe: boolean;
47
+
48
+ // 只读性:未声明默认 false(可能有副作用)
49
+ isReadOnly: boolean;
50
+
51
+ // 是否支持部分失败(单个操作失败不影响其他)
52
+ supportsPartialFailure: boolean;
53
+
54
+ // 最大并发数(isConcurrencySafe=true 时有效)
55
+ maxConcurrency?: number;
56
+
57
+ // 能力声明版本
58
+ declarationVersion: string;
59
+ }
60
+ ```
61
+
62
+ ---
63
+
64
+ ## Fail-Closed 规则
65
+
66
+ | 属性 | 默认值 | 含义 |
67
+ |------|--------|------|
68
+ | `isConcurrencySafe` | `false` | 未声明则禁止并发调用 |
69
+ | `isReadOnly` | `false` | 未声明则假设有副作用,需额外谨慎 |
70
+ | `supportsPartialFailure` | `false` | 未声明则任意失败视为全部失败 |
71
+
72
+ ---
73
+
74
+ ## 编排器检查流程
75
+
76
+ ```
77
+ 调用工具前:
78
+ 1. 读取工具的 CapabilityDeclaration
79
+ 2. 若需要并发调用且 isConcurrencySafe=false → 拒绝并发,改为串行
80
+ 3. 若工具未提供 CapabilityDeclaration → 视为 isConcurrencySafe=false
81
+ 4. 记录 capability_check_result 遥测事件
82
+ ```
83
+
84
+ ---
85
+
86
+ ## 遥测事件
87
+
88
+ **`capability_check_result`**(每次能力检查时上报)
89
+
90
+ | 字段 | 类型 |
91
+ |------|------|
92
+ | `toolId` | `string` |
93
+ | `checkType` | `concurrency\|readonly\|partial_failure` |
94
+ | `declared` | `boolean` |
95
+ | `decision` | `allowed\|denied` |
96
+ | `timestamp` | `string` |
97
+
98
+ ---
99
+
100
+ ## 情境示例
101
+
102
+ **情境 1:并发安全检查**
103
+ - 条件:Agent 编排器需要并发调用 `file-writer` 工具
104
+ - `file-writer` 的 `isConcurrencySafe=false`
105
+ - 结果:编排器改为串行调用,记录 `capability_check_result`(decision=denied)
106
+
107
+ **情境 2:未声明能力(Fail-Closed)**
108
+ - 条件:旧版工具未提供 `CapabilityDeclaration`
109
+ - 结果:视为 `isConcurrencySafe=false, isReadOnly=false`,采用最保守策略
110
+
111
+ **情境 3:只读工具并发**
112
+ - 条件:`search-tool` 声明 `isReadOnly=true, isConcurrencySafe=true, maxConcurrency=5`
113
+ - 结果:允许最多 5 个并发调用
114
+
115
+ ---
116
+
117
+ ## 错误码
118
+
119
+ | 代码 | 说明 |
120
+ |------|------|
121
+ | `CAP-001` | `MISSING_CAPABILITY_DECLARATION` — 工具未提供能力声明,采用 Fail-Closed |
122
+ | `CAP-002` | `CONCURRENCY_DENIED` — isConcurrencySafe=false 但请求并发调用 |
123
+ | `CAP-003` | `MAX_CONCURRENCY_EXCEEDED` — 并发数超过 maxConcurrency 限制 |
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../core/checkin-standards.md
3
- source_version: 1.5.0
4
- translation_version: 1.5.0
5
- last_synced: 2026-03-18
3
+ source_version: 1.6.0
4
+ translation_version: 1.6.0
5
+ last_synced: 2026-04-20
6
6
  status: current
7
7
  ---
8
8
 
@@ -911,6 +911,25 @@ obj/
911
911
  node_modules/
912
912
  ```
913
913
 
914
+ ### 旧版项目文件同步(project-file-sync)
915
+
916
+ > **适用范围**:.NET Framework、MSBuild `.csproj` 及任何需要显式登记文件的旧版格式。
917
+
918
+ 旧版项目格式(如 `.NET Framework .csproj`)不会自动包含磁盘上的源码文件——每个文件都必须在项目 manifest 中显式列出。未登记的文件在**编译时被静默排除,不会产生任何错误或警告**。
919
+
920
+ **风险**:新增 `.cs`/`.aspx.cs` 文件后重建 DLL,该文件被排除。测试通过(测试的是旧 DLL),正式环境崩溃并显示"无法加载类型"。
921
+
922
+ **预提交检查**:
923
+
924
+ ```bash
925
+ # 找出磁盘上未登记于 .csproj 的 .cs 文件
926
+ comm -23 \
927
+ <(find . -name "*.cs" | sort) \
928
+ <(grep -oP '(?<=Include=")[^"]+\.cs' MyProject.csproj | sort)
929
+ ```
930
+
931
+ **规则**:若项目使用旧版格式,每次提交前执行磁盘与 manifest 的比对。发现未登记文件时立即失败。
932
+
914
933
  ---
915
934
 
916
935
  ## 常见违规与解决方案
@@ -0,0 +1,106 @@
1
+ ---
2
+ source: ../../../core/circuit-breaker.md
3
+ source_version: 1.0.0
4
+ translation_version: 1.0.0
5
+ last_synced: 2026-04-20
6
+ status: current
7
+ ---
8
+
9
+ # 断路器标准
10
+
11
+ > **语言**: [English](../../../core/circuit-breaker.md) | 简体中文
12
+
13
+ **版本**: 1.0.0
14
+ **最后更新**: 2026-04-17
15
+ **状态**: Trial(到期 2026-10-17)
16
+ **适用范围**: universal
17
+ **来源**: XSPEC-068(DEC-043 Wave 1 可靠性套件)
18
+
19
+ ---
20
+
21
+ ## 目的
22
+
23
+ 通用断路器标准:三态状态机(CLOSED/HALF_OPEN/OPEN)、阈值配置、与遥测整合。
24
+
25
+ 各模块各自实现断路器导致行为不一致(阈值不同、HALF_OPEN 探针逻辑各异、遥测事件命名混乱)。本标准提供统一的状态机定义、配置键名,以及必须上报的遥测事件,确保 DevAP/VibeOps/telemetry 三端可互相理解断路器状态。
26
+
27
+ ---
28
+
29
+ ## 核心规范
30
+
31
+ - 断路器必须实现三态:CLOSED / HALF_OPEN / OPEN
32
+ - `failureThreshold`、`successThreshold`、`cooldownMs` 必须可配置,有默认值
33
+ - 触发转换时必须上报 `circuit_state_change` 遥测事件
34
+ - HALF_OPEN 状态下只允许单次探针请求(不允许并发探针)
35
+ - 所有断路器实例必须可通过 `circuitId` 唯一标识
36
+
37
+ ---
38
+
39
+ ## 状态机
40
+
41
+ | 状态 | 说明 |
42
+ |------|------|
43
+ | **CLOSED** | 正常状态,放行所有请求;连续失败计数 |
44
+ | **HALF_OPEN** | 冷却后的探针状态;放行单次探针请求 |
45
+ | **OPEN** | 开路状态,拒绝所有请求;等待冷却期 |
46
+
47
+ ### 状态转换规则
48
+
49
+ ```
50
+ CLOSED → OPEN : 连续失败 >= failureThreshold
51
+ OPEN → HALF_OPEN : 冷却期(cooldownMs)到期
52
+ HALF_OPEN → CLOSED : 探针成功 >= successThreshold
53
+ HALF_OPEN → OPEN : 探针失败(立即重新开路)
54
+ ```
55
+
56
+ ---
57
+
58
+ ## 配置参数
59
+
60
+ | 参数 | 默认值 | 说明 |
61
+ |------|--------|------|
62
+ | `failureThreshold` | `3` | 触发 OPEN 的连续失败次数 |
63
+ | `successThreshold` | `1` | 从 HALF_OPEN 恢复到 CLOSED 所需的成功次数 |
64
+ | `cooldownMs` | `30000` | OPEN 状态冷却时间(毫秒)|
65
+ | `circuitId` | 必填 | 断路器唯一标识符 |
66
+
67
+ ---
68
+
69
+ ## 遥测事件
70
+
71
+ **`circuit_state_change`**(每次状态转换时上报)
72
+
73
+ | 字段 | 类型 |
74
+ |------|------|
75
+ | `circuitId` | `string` |
76
+ | `fromState` | `CLOSED\|HALF_OPEN\|OPEN` |
77
+ | `toState` | `CLOSED\|HALF_OPEN\|OPEN` |
78
+ | `reason` | `string` |
79
+ | `failureCount` | `number` |
80
+ | `timestamp` | `string` |
81
+
82
+ ---
83
+
84
+ ## 情境示例
85
+
86
+ **情境 1:CLOSED → OPEN**
87
+ - 条件:连续 3 次调用下游 API 失败(failureThreshold=3)
88
+ - 结果:断路器转 OPEN,后续请求立即回传 `CircuitOpenError`
89
+
90
+ **情境 2:OPEN → HALF_OPEN → CLOSED**
91
+ - 条件:冷却 30s 后放行探针请求,探针成功
92
+ - 结果:断路器恢复 CLOSED,失败计数重置
93
+
94
+ **情境 3:HALF_OPEN → OPEN(探针失败)**
95
+ - 条件:探针请求失败
96
+ - 结果:立即重新开路,重新进入冷却期
97
+
98
+ ---
99
+
100
+ ## 错误码
101
+
102
+ | 代码 | 说明 |
103
+ |------|------|
104
+ | `CB-001` | `CIRCUIT_OPEN` — 断路器为 OPEN 状态,请求被拒绝 |
105
+ | `CB-002` | `PROBE_REJECTED` — HALF_OPEN 状态下拒绝并发探针 |
106
+ | `CB-003` | `CONFIG_INVALID` — 断路器配置参数无效 |
@@ -0,0 +1,103 @@
1
+ ---
2
+ source: ../../../core/dual-phase-output.md
3
+ source_version: 1.0.0
4
+ translation_version: 1.0.0
5
+ last_synced: 2026-04-20
6
+ status: current
7
+ ---
8
+
9
+ # 双阶段输出标准
10
+
11
+ > **语言**: [English](../../../core/dual-phase-output.md) | 简体中文
12
+
13
+ **版本**: 1.0.0
14
+ **最后更新**: 2026-04-17
15
+ **状态**: Trial(到期 2026-10-17)
16
+ **适用范围**: universal
17
+ **来源**: XSPEC-068(DEC-043 Wave 1 可靠性套件)
18
+
19
+ ---
20
+
21
+ ## 目的
22
+
23
+ 双阶段 LLM 输出标准:`<analysis>` 丢弃 + `<summary>` 保留,统一 Agent 的输出过滤行为。
24
+
25
+ Agent 的推理过程(chain-of-thought)不应直接暴露给下游消费者:它消耗 token、包含中间假设、对机器不友好。本标准要求所有 Agent 输出分为两个阶段,`<analysis>` 标签内容在传递给下游前丢弃,只保留 `<summary>` 内容。
26
+
27
+ ---
28
+
29
+ ## 核心规范
30
+
31
+ - 所有 Agent 必须在输出中明确区分 `<analysis>` 与 `<summary>` 两个阶段
32
+ - `<analysis>` 内容为推理过程,不得传递给下游消费者(丢弃)
33
+ - `<summary>` 内容为最终结论,必须保留并传递
34
+ - 若 Agent 输出缺少 `<summary>` 标签,视为格式错误(DUAL-001)
35
+ - 下游模块在消费 Agent 输出前必须执行过滤步骤
36
+
37
+ ---
38
+
39
+ ## 输出格式
40
+
41
+ ```xml
42
+ <analysis>
43
+ [Agent 的推理过程、假设检验、中间步骤]
44
+ [此区段会被丢弃,不传递给下游]
45
+ </analysis>
46
+
47
+ <summary>
48
+ [最终结论、可执行的建议、结构化数据]
49
+ [此区段会被保留并传递给下游消费者]
50
+ </summary>
51
+ ```
52
+
53
+ ---
54
+
55
+ ## 过滤规则
56
+
57
+ | 规则 | 说明 |
58
+ |------|------|
59
+ | 规则 1 | 解析输出时,提取 `<summary>...</summary>` 内容 |
60
+ | 规则 2 | 丢弃 `<analysis>...</analysis>` 及其内容 |
61
+ | 规则 3 | 若两个标签都缺失,回传错误 `DUAL-001` |
62
+ | 规则 4 | 若只有 `<analysis>` 无 `<summary>`,回传错误 `DUAL-001` |
63
+ | 规则 5 | 允许 `<summary>` 内嵌套结构化数据(JSON、YAML、代码块)|
64
+
65
+ ---
66
+
67
+ ## 遥测事件
68
+
69
+ **`dual_phase_filter_applied`**(每次执行过滤时上报)
70
+
71
+ | 字段 | 类型 |
72
+ |------|------|
73
+ | `agentId` | `string` |
74
+ | `analysisTokens` | `number` |
75
+ | `summaryTokens` | `number` |
76
+ | `filterSuccess` | `boolean` |
77
+ | `timestamp` | `string` |
78
+
79
+ ---
80
+
81
+ ## 情境示例
82
+
83
+ **情境 1:正常双阶段输出**
84
+ - Agent 输出包含 `<analysis>` 和 `<summary>` 标签
85
+ - 过滤后只保留 `<summary>` 内容传递给下游
86
+
87
+ **情境 2:缺少 `<summary>` 标签**
88
+ - Agent 输出只有 `<analysis>` 内容
89
+ - 回传 `DUAL-001` 错误,不传递任何内容给下游
90
+
91
+ **情境 3:`<summary>` 内嵌套 JSON**
92
+ - `<summary>` 内包含结构化 JSON 数据
93
+ - 过滤后完整保留 JSON,可被下游直接解析
94
+
95
+ ---
96
+
97
+ ## 错误码
98
+
99
+ | 代码 | 说明 |
100
+ |------|------|
101
+ | `DUAL-001` | `MISSING_SUMMARY_TAG` — 输出缺少 `<summary>` 标签 |
102
+ | `DUAL-002` | `EMPTY_SUMMARY` — `<summary>` 标签内容为空 |
103
+ | `DUAL-003` | `MALFORMED_OUTPUT` — 输出格式无法解析 |
@@ -0,0 +1,99 @@
1
+ ---
2
+ source: ../../../core/failure-source-taxonomy.md
3
+ source_version: 1.0.0
4
+ translation_version: 1.0.0
5
+ last_synced: 2026-04-20
6
+ status: current
7
+ ---
8
+
9
+ # 失败来源分类法
10
+
11
+ > **语言**: [English](../../../core/failure-source-taxonomy.md) | 简体中文
12
+
13
+ **版本**: 1.0.0
14
+ **最后更新**: 2026-04-17
15
+ **状态**: Trial(到期 2026-10-17)
16
+ **适用范围**: universal
17
+ **来源**: XSPEC-045(DEC-035 Recovery Recipe Registry)
18
+
19
+ ---
20
+
21
+ ## 目的
22
+
23
+ 失败来源分类法:8 类 `failureSource`,补充 `TaskStatus` 的 why 维度。
24
+
25
+ `TaskStatus`(succeeded/failed/partial)只描述「是什么」,不描述「为什么失败」。本分类法定义 8 类失败来源,让 Recovery Recipe Registry(XSPEC-046)可以根据 `failureSource` 精准选择恢复策略,而不是对所有失败套用同一个回退逻辑。
26
+
27
+ ---
28
+
29
+ ## 核心规范
30
+
31
+ - 所有失败事件必须附带 `failureSource`(8 类之一)
32
+ - `failureSource` 决定是否可重试(见下表)
33
+ - Recovery Recipe 以 `failureSource` 为匹配键
34
+ - 无法分类的失败标记为 `unknown`,触发人工检查点
35
+ - 单次失败事件只能有一个 `failureSource`(不可多选)
36
+
37
+ ---
38
+
39
+ ## 8 类失败来源
40
+
41
+ | failureSource | 可重试 | 说明 |
42
+ |---------------|--------|------|
43
+ | `transient_network` | ✅ | 短暂网络抖动,如 TCP 超时、DNS 解析失败 |
44
+ | `rate_limit` | ✅ | 速率限制,如 429 Too Many Requests |
45
+ | `upstream_unavailable` | ✅ | 上游服务不可达,断路器可处理 |
46
+ | `tool_failure` | ✅ | 工具层失败,如 CLI 工具崩溃 |
47
+ | `prompt_delivery` | ✅ | 提示词传递失败,可切换模型重试 |
48
+ | `authentication` | ❌ | 凭证错误,重试不会变对 |
49
+ | `validation` | ❌ | 输入验证失败,重试结果不变 |
50
+ | `policy_violation` | ❌ | 安全策略拒绝,禁止绕过 |
51
+ | `quota_exhausted` | ❌ | 配额耗尽,等待刷新 |
52
+ | `model_degradation` | ✅ | 模型质量降级,可切换备用模型 |
53
+ | `resource_exhaustion` | ❌ | 资源耗尽(内存/磁盘),需人工介入 |
54
+ | `branch_divergence` | ✅ | 分支漂移,可 rebase 重试 |
55
+ | `compilation` | ✅ | 编译错误,Fix Loop 可处理 |
56
+ | `test_failure` | ✅ | 测试失败,Fix Loop 可处理 |
57
+ | `unknown` | ❌ | 未能分类,触发人工检查点 |
58
+
59
+ ---
60
+
61
+ ## 与 Recovery Recipe 的对应
62
+
63
+ | failureSource | 推荐 Recovery Strategy |
64
+ |---------------|----------------------|
65
+ | `compilation` | `fix_loop` |
66
+ | `test_failure` | `fix_loop` |
67
+ | `model_degradation` | `model_switch` |
68
+ | `branch_divergence` | `rebase_and_retry` |
69
+ | `resource_exhaustion` | `degraded_mode` |
70
+ | `policy_violation` | `human_checkpoint` |
71
+ | `authentication` | `human_checkpoint` |
72
+ | `transient_network` | `circuit_breaker` + retry |
73
+ | `tool_failure` | `circuit_breaker` |
74
+ | `prompt_delivery` | `model_switch` |
75
+ | `unknown` | `human_checkpoint` |
76
+
77
+ ---
78
+
79
+ ## 遥测事件
80
+
81
+ **`failure_classified`**(每次失败分类时上报)
82
+
83
+ | 字段 | 类型 |
84
+ |------|------|
85
+ | `taskId` | `string` |
86
+ | `failureSource` | `FailureSource` |
87
+ | `isRetryable` | `boolean` |
88
+ | `originalError` | `string` |
89
+ | `timestamp` | `string` |
90
+
91
+ ---
92
+
93
+ ## 错误码
94
+
95
+ | 代码 | 说明 |
96
+ |------|------|
97
+ | `FST-001` | `UNCLASSIFIED_FAILURE` — 失败来源无法分类,标记为 unknown |
98
+ | `FST-002` | `INVALID_FAILURE_SOURCE` — failureSource 不在 8 类定义内 |
99
+ | `FST-003` | `MULTIPLE_SOURCES` — 单次失败标记了多个 failureSource(违规)|