universal-dev-standards 6.14.0-beta.9 → 6.14.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 (711) hide show
  1. package/bin/uds.js +12 -1
  2. package/bundled/ai/options/commit-message/traditional-chinese.ai.yaml +69 -67
  3. package/bundled/ai/standards/commit-message.ai.yaml +12 -2
  4. package/bundled/ai/standards/secret-management-standards.ai.yaml +12 -1
  5. package/bundled/core/commit-message-guide.md +22 -19
  6. package/bundled/core/secret-management-standards.md +13 -1
  7. package/bundled/extensions/locales/zh-tw.md +19 -19
  8. package/bundled/hooks/validate-commit-msg.mjs +52 -9
  9. package/bundled/locales/zh-CN/CHANGELOG.md +2309 -1110
  10. package/bundled/locales/zh-CN/CLAUDE.md +987 -101
  11. package/bundled/locales/zh-CN/README.md +3 -3
  12. package/bundled/locales/zh-CN/SECURITY.md +3 -3
  13. package/bundled/locales/zh-CN/STANDARDS-MAPPING.md +103 -6
  14. package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +68 -97
  15. package/bundled/locales/zh-CN/adoption/DAILY-WORKFLOW-GUIDE.md +2 -1
  16. package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +8 -9
  17. package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +81 -80
  18. package/bundled/locales/zh-CN/adoption/checklists/minimal.md +18 -14
  19. package/bundled/locales/zh-CN/adoption/checklists/recommended.md +49 -46
  20. package/bundled/locales/zh-CN/ai/MAINTENANCE.md +44 -9
  21. package/bundled/locales/zh-CN/ai/options/commit-message/traditional-chinese.ai.yaml +63 -55
  22. package/bundled/locales/zh-CN/core/acceptance-criteria-traceability.md +61 -14
  23. package/bundled/locales/zh-CN/core/acceptance-test-driven-development.md +2 -1
  24. package/bundled/locales/zh-CN/core/accessibility-standards.md +871 -62
  25. package/bundled/locales/zh-CN/core/adr-standards.md +155 -32
  26. package/bundled/locales/zh-CN/core/agent-communication-protocol.md +2 -1
  27. package/bundled/locales/zh-CN/core/agent-dispatch.md +68 -33
  28. package/bundled/locales/zh-CN/core/ai-agreement-standards.md +23 -22
  29. package/bundled/locales/zh-CN/core/ai-command-behavior.md +2 -1
  30. package/bundled/locales/zh-CN/core/ai-friendly-architecture.md +311 -72
  31. package/bundled/locales/zh-CN/core/ai-instruction-standards.md +71 -49
  32. package/bundled/locales/zh-CN/core/ai-response-navigation.md +2 -1
  33. package/bundled/locales/zh-CN/core/alerting-standards.md +231 -36
  34. package/bundled/locales/zh-CN/core/anti-hallucination.md +116 -697
  35. package/bundled/locales/zh-CN/core/anti-sycophancy-prompting.md +34 -33
  36. package/bundled/locales/zh-CN/core/api-design-standards.md +144 -58
  37. package/bundled/locales/zh-CN/core/behavior-driven-development.md +2 -1
  38. package/bundled/locales/zh-CN/core/branch-completion.md +75 -20
  39. package/bundled/locales/zh-CN/core/capability-declaration.md +44 -94
  40. package/bundled/locales/zh-CN/core/change-batching-standards.md +2 -1
  41. package/bundled/locales/zh-CN/core/changelog-standards.md +485 -63
  42. package/bundled/locales/zh-CN/core/chaos-engineering-standards.md +141 -39
  43. package/bundled/locales/zh-CN/core/checkin-standards.md +176 -116
  44. package/bundled/locales/zh-CN/core/circuit-breaker.md +43 -77
  45. package/bundled/locales/zh-CN/core/code-review-checklist.md +37 -23
  46. package/bundled/locales/zh-CN/core/commit-message-guide.md +892 -69
  47. package/bundled/locales/zh-CN/core/containerization-standards.md +259 -57
  48. package/bundled/locales/zh-CN/core/context-aware-loading.md +103 -29
  49. package/bundled/locales/zh-CN/core/database-standards.md +115 -114
  50. package/bundled/locales/zh-CN/core/deprecation-standards.md +155 -40
  51. package/bundled/locales/zh-CN/core/design-document-standards.md +265 -55
  52. package/bundled/locales/zh-CN/core/developer-memory.md +150 -60
  53. package/bundled/locales/zh-CN/core/documentation-lifecycle.md +20 -16
  54. package/bundled/locales/zh-CN/core/documentation-structure.md +1284 -127
  55. package/bundled/locales/zh-CN/core/documentation-writing-standards.md +649 -259
  56. package/bundled/locales/zh-CN/core/dual-phase-output.md +37 -70
  57. package/bundled/locales/zh-CN/core/environment-standards.md +251 -73
  58. package/bundled/locales/zh-CN/core/error-code-standards.md +501 -60
  59. package/bundled/locales/zh-CN/core/estimation-standards.md +174 -41
  60. package/bundled/locales/zh-CN/core/execution-history.md +2 -1
  61. package/bundled/locales/zh-CN/core/failure-source-taxonomy.md +71 -84
  62. package/bundled/locales/zh-CN/core/feature-flag-standards.md +202 -57
  63. package/bundled/locales/zh-CN/core/forward-derivation-standards.md +613 -154
  64. package/bundled/locales/zh-CN/core/frontend-design-standards.md +361 -78
  65. package/bundled/locales/zh-CN/core/git-workflow.md +148 -262
  66. package/bundled/locales/zh-CN/core/git-worktree.md +59 -26
  67. package/bundled/locales/zh-CN/core/guides/file-placement-guide.md +132 -48
  68. package/bundled/locales/zh-CN/core/guides/performance-guide.md +61 -59
  69. package/bundled/locales/zh-CN/core/guides/security-guide.md +2 -0
  70. package/bundled/locales/zh-CN/core/health-check-standards.md +46 -104
  71. package/bundled/locales/zh-CN/core/immutability-first.md +83 -60
  72. package/bundled/locales/zh-CN/core/knowledge-transfer-standards.md +94 -31
  73. package/bundled/locales/zh-CN/core/mutation-testing.md +45 -6
  74. package/bundled/locales/zh-CN/core/observability-standards.md +281 -37
  75. package/bundled/locales/zh-CN/core/performance-standards.md +402 -42
  76. package/bundled/locales/zh-CN/core/pipeline-integration-standards.md +2 -1
  77. package/bundled/locales/zh-CN/core/postmortem-standards.md +358 -53
  78. package/bundled/locales/zh-CN/core/privacy-standards.md +148 -40
  79. package/bundled/locales/zh-CN/core/project-context-memory.md +182 -48
  80. package/bundled/locales/zh-CN/core/project-structure.md +550 -170
  81. package/bundled/locales/zh-CN/core/recovery-recipe-registry.md +54 -114
  82. package/bundled/locales/zh-CN/core/refactoring-standards.md +141 -556
  83. package/bundled/locales/zh-CN/core/requirement-engineering.md +7 -6
  84. package/bundled/locales/zh-CN/core/retrospective-standards.md +215 -22
  85. package/bundled/locales/zh-CN/core/retry-standards.md +46 -101
  86. package/bundled/locales/zh-CN/core/reverse-engineering-standards.md +370 -120
  87. package/bundled/locales/zh-CN/core/runbook-standards.md +294 -48
  88. package/bundled/locales/zh-CN/core/security-decision.md +45 -70
  89. package/bundled/locales/zh-CN/core/security-standards.md +169 -16
  90. package/bundled/locales/zh-CN/core/skill-standard-alignment-check.md +105 -71
  91. package/bundled/locales/zh-CN/core/slo-standards.md +296 -44
  92. package/bundled/locales/zh-CN/core/spec-driven-development.md +37 -6
  93. package/bundled/locales/zh-CN/core/standard-admission-criteria.md +25 -31
  94. package/bundled/locales/zh-CN/core/standard-lifecycle-management.md +49 -57
  95. package/bundled/locales/zh-CN/core/structured-task-definition.md +2 -1
  96. package/bundled/locales/zh-CN/core/supply-chain-security-standards.md +159 -32
  97. package/bundled/locales/zh-CN/core/systematic-debugging.md +87 -42
  98. package/bundled/locales/zh-CN/core/tech-debt-standards.md +202 -86
  99. package/bundled/locales/zh-CN/core/test-completeness-dimensions.md +262 -190
  100. package/bundled/locales/zh-CN/core/test-data-standards.md +252 -30
  101. package/bundled/locales/zh-CN/core/test-driven-development.md +21 -1022
  102. package/bundled/locales/zh-CN/core/test-governance.md +94 -43
  103. package/bundled/locales/zh-CN/core/testing-standards.md +83 -37
  104. package/bundled/locales/zh-CN/core/timeout-standards.md +45 -85
  105. package/bundled/locales/zh-CN/core/token-budget.md +44 -80
  106. package/bundled/locales/zh-CN/core/translation-lifecycle-standards.md +48 -36
  107. package/bundled/locales/zh-CN/core/verification-evidence.md +44 -22
  108. package/bundled/locales/zh-CN/core/versioning.md +737 -73
  109. package/bundled/locales/zh-CN/core/virtual-organization-standards.md +30 -29
  110. package/bundled/locales/zh-CN/core/workflow-enforcement.md +9 -8
  111. package/bundled/locales/zh-CN/core/workflow-state-protocol.md +9 -8
  112. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +2 -1
  113. package/bundled/locales/zh-CN/docs/CLI-FLOW.md +2 -1
  114. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +19 -10
  115. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +8 -6
  116. package/bundled/locales/zh-CN/docs/STANDARDS-REFERENCE.md +2 -1
  117. package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +133 -132
  118. package/bundled/locales/zh-CN/docs/USER-MANUAL.md +11 -3
  119. package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +5 -2
  120. package/bundled/locales/zh-CN/docs/specs/system/memory-adoption-strategy.md +2 -0
  121. package/bundled/locales/zh-CN/docs/user/FAQ.md +2 -0
  122. package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +2 -0
  123. package/bundled/locales/zh-CN/docs/user/GLOSSARY.md +2 -0
  124. package/bundled/locales/zh-CN/docs/user/README.md +4 -2
  125. package/bundled/locales/zh-CN/docs/user/TROUBLESHOOTING.md +2 -0
  126. package/bundled/locales/zh-CN/integrations/codex/AGENTS.md +136 -2
  127. package/bundled/locales/zh-CN/integrations/codex/README.md +62 -10
  128. package/bundled/locales/zh-CN/integrations/gemini-cli/GEMINI.md +59 -1
  129. package/bundled/locales/zh-CN/integrations/gemini-cli/README.md +9 -2
  130. package/bundled/locales/zh-CN/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +7 -1
  131. package/bundled/locales/zh-CN/integrations/github-copilot/README.md +8 -2
  132. package/bundled/locales/zh-CN/integrations/github-copilot/copilot-instructions.md +146 -12
  133. package/bundled/locales/zh-CN/integrations/github-copilot/skills-mapping.md +7 -1
  134. package/bundled/locales/zh-CN/integrations/google-antigravity/AGENTS.md +110 -3
  135. package/bundled/locales/zh-CN/integrations/google-antigravity/README.md +7 -1
  136. package/bundled/locales/zh-CN/integrations/opencode/AGENTS.md +140 -2
  137. package/bundled/locales/zh-CN/integrations/opencode/README.md +7 -1
  138. package/bundled/locales/zh-CN/integrations/opencode/skills-mapping.md +8 -2
  139. package/bundled/locales/zh-CN/integrations/openspec/AGENTS.md +46 -1
  140. package/bundled/locales/zh-CN/integrations/openspec/README.md +7 -1
  141. package/bundled/locales/zh-CN/integrations/spec-kit/AGENTS.md +20 -2
  142. package/bundled/locales/zh-CN/integrations/spec-kit/README.md +7 -1
  143. package/bundled/locales/zh-CN/options/changelog/auto-generated.md +2 -0
  144. package/bundled/locales/zh-CN/options/changelog/keep-a-changelog.md +2 -0
  145. package/bundled/locales/zh-CN/options/code-review/automated-review.md +2 -0
  146. package/bundled/locales/zh-CN/options/code-review/pair-programming.md +2 -0
  147. package/bundled/locales/zh-CN/options/commit-message/bilingual.md +139 -50
  148. package/bundled/locales/zh-CN/options/commit-message/english.md +159 -42
  149. package/bundled/locales/zh-CN/options/commit-message/traditional-chinese.md +156 -75
  150. package/bundled/locales/zh-CN/options/documentation/api-docs.md +3 -1
  151. package/bundled/locales/zh-CN/options/documentation/markdown-docs.md +2 -0
  152. package/bundled/locales/zh-CN/options/documentation/wiki-style.md +2 -0
  153. package/bundled/locales/zh-CN/options/git-workflow/gitflow.md +105 -77
  154. package/bundled/locales/zh-CN/options/git-workflow/github-flow.md +75 -57
  155. package/bundled/locales/zh-CN/options/git-workflow/merge-commit.md +155 -44
  156. package/bundled/locales/zh-CN/options/git-workflow/rebase-ff.md +168 -53
  157. package/bundled/locales/zh-CN/options/git-workflow/squash-merge.md +122 -37
  158. package/bundled/locales/zh-CN/options/git-workflow/trunk-based.md +108 -61
  159. package/bundled/locales/zh-CN/options/project-structure/dotnet.md +266 -47
  160. package/bundled/locales/zh-CN/options/project-structure/go.md +301 -43
  161. package/bundled/locales/zh-CN/options/project-structure/java.md +268 -48
  162. package/bundled/locales/zh-CN/options/project-structure/kotlin.md +2 -0
  163. package/bundled/locales/zh-CN/options/project-structure/nodejs.md +168 -51
  164. package/bundled/locales/zh-CN/options/project-structure/php.md +2 -0
  165. package/bundled/locales/zh-CN/options/project-structure/python.md +210 -52
  166. package/bundled/locales/zh-CN/options/project-structure/ruby.md +2 -0
  167. package/bundled/locales/zh-CN/options/project-structure/rust.md +2 -0
  168. package/bundled/locales/zh-CN/options/project-structure/swift.md +2 -0
  169. package/bundled/locales/zh-CN/options/testing/contract-testing.md +2 -0
  170. package/bundled/locales/zh-CN/options/testing/e2e-testing.md +227 -66
  171. package/bundled/locales/zh-CN/options/testing/industry-pyramid.md +2 -0
  172. package/bundled/locales/zh-CN/options/testing/integration-testing.md +185 -73
  173. package/bundled/locales/zh-CN/options/testing/istqb-framework.md +2 -0
  174. package/bundled/locales/zh-CN/options/testing/performance-testing.md +2 -0
  175. package/bundled/locales/zh-CN/options/testing/security-testing.md +2 -0
  176. package/bundled/locales/zh-CN/options/testing/system-testing.md +270 -96
  177. package/bundled/locales/zh-CN/options/testing/unit-testing.md +185 -71
  178. package/bundled/locales/zh-CN/skills/CONTRIBUTING.template.md +43 -42
  179. package/bundled/locales/zh-CN/skills/INTEGRATION-GUIDE.md +2 -1
  180. package/bundled/locales/zh-CN/skills/README.md +2 -1
  181. package/bundled/locales/zh-CN/skills/_shared/README.md +2 -1
  182. package/bundled/locales/zh-CN/skills/adr-assistant/guide.md +240 -4
  183. package/bundled/locales/zh-CN/skills/agents/README.md +180 -82
  184. package/bundled/locales/zh-CN/skills/agents/code-architect.md +3 -1
  185. package/bundled/locales/zh-CN/skills/agents/doc-writer.md +3 -1
  186. package/bundled/locales/zh-CN/skills/agents/reviewer.md +4 -2
  187. package/bundled/locales/zh-CN/skills/agents/spec-analyst.md +3 -1
  188. package/bundled/locales/zh-CN/skills/agents/test-specialist.md +3 -1
  189. package/bundled/locales/zh-CN/skills/ai-collaboration-standards/SKILL.md +91 -81
  190. package/bundled/locales/zh-CN/skills/ai-collaboration-standards/anti-hallucination.md +79 -59
  191. package/bundled/locales/zh-CN/skills/ai-collaboration-standards/certainty-labels.md +66 -40
  192. package/bundled/locales/zh-CN/skills/ai-friendly-architecture/SKILL.md +23 -36
  193. package/bundled/locales/zh-CN/skills/ai-instruction-standards/SKILL.md +217 -137
  194. package/bundled/locales/zh-CN/skills/api-design-assistant/SKILL.md +13 -2
  195. package/bundled/locales/zh-CN/skills/atdd-assistant/SKILL.md +16 -2
  196. package/bundled/locales/zh-CN/skills/atdd-assistant/acceptance-criteria-guide.md +2 -1
  197. package/bundled/locales/zh-CN/skills/atdd-assistant/atdd-workflow.md +98 -1
  198. package/bundled/locales/zh-CN/skills/atdd-assistant/guide.md +148 -132
  199. package/bundled/locales/zh-CN/skills/audit-assistant/SKILL.md +5 -2
  200. package/bundled/locales/zh-CN/skills/bdd-assistant/SKILL.md +16 -2
  201. package/bundled/locales/zh-CN/skills/bdd-assistant/bdd-workflow.md +2 -1
  202. package/bundled/locales/zh-CN/skills/bdd-assistant/gherkin-guide.md +2 -1
  203. package/bundled/locales/zh-CN/skills/bdd-assistant/guide.md +122 -121
  204. package/bundled/locales/zh-CN/skills/changelog-guide/SKILL.md +9 -2
  205. package/bundled/locales/zh-CN/skills/changelog-guide/guide.md +91 -88
  206. package/bundled/locales/zh-CN/skills/checkin-assistant/SKILL.md +12 -2
  207. package/bundled/locales/zh-CN/skills/checkin-assistant/guide.md +211 -210
  208. package/bundled/locales/zh-CN/skills/ci-cd-assistant/SKILL.md +14 -2
  209. package/bundled/locales/zh-CN/skills/code-review-assistant/SKILL.md +12 -2
  210. package/bundled/locales/zh-CN/skills/code-review-assistant/checkin-checklist.md +79 -78
  211. package/bundled/locales/zh-CN/skills/code-review-assistant/guide.md +119 -45
  212. package/bundled/locales/zh-CN/skills/code-review-assistant/review-checklist.md +89 -88
  213. package/bundled/locales/zh-CN/skills/commands/ac-coverage.md +43 -1
  214. package/bundled/locales/zh-CN/skills/commands/api-design.md +2 -1
  215. package/bundled/locales/zh-CN/skills/commands/atdd.md +71 -1
  216. package/bundled/locales/zh-CN/skills/commands/audit.md +2 -1
  217. package/bundled/locales/zh-CN/skills/commands/bdd.md +160 -62
  218. package/bundled/locales/zh-CN/skills/commands/changelog.md +36 -1
  219. package/bundled/locales/zh-CN/skills/commands/check.md +53 -1
  220. package/bundled/locales/zh-CN/skills/commands/checkin.md +45 -1
  221. package/bundled/locales/zh-CN/skills/commands/ci-cd.md +3 -2
  222. package/bundled/locales/zh-CN/skills/commands/code-review.md +41 -1
  223. package/bundled/locales/zh-CN/skills/commands/commit.md +56 -1
  224. package/bundled/locales/zh-CN/skills/commands/config.md +50 -1
  225. package/bundled/locales/zh-CN/skills/commands/coverage.md +43 -1
  226. package/bundled/locales/zh-CN/skills/commands/database.md +4 -3
  227. package/bundled/locales/zh-CN/skills/commands/derive-all.md +42 -1
  228. package/bundled/locales/zh-CN/skills/commands/derive-atdd.md +35 -1
  229. package/bundled/locales/zh-CN/skills/commands/derive-bdd.md +41 -1
  230. package/bundled/locales/zh-CN/skills/commands/derive-tdd.md +42 -1
  231. package/bundled/locales/zh-CN/skills/commands/derive.md +60 -4
  232. package/bundled/locales/zh-CN/skills/commands/dev-workflow.md +58 -8
  233. package/bundled/locales/zh-CN/skills/commands/discover.md +41 -1
  234. package/bundled/locales/zh-CN/skills/commands/docgen.md +37 -1
  235. package/bundled/locales/zh-CN/skills/commands/docs.md +136 -5
  236. package/bundled/locales/zh-CN/skills/commands/durable.md +4 -3
  237. package/bundled/locales/zh-CN/skills/commands/e2e.md +85 -1
  238. package/bundled/locales/zh-CN/skills/commands/guide.md +2 -1
  239. package/bundled/locales/zh-CN/skills/commands/incident.md +5 -4
  240. package/bundled/locales/zh-CN/skills/commands/init.md +57 -1
  241. package/bundled/locales/zh-CN/skills/commands/methodology.md +166 -77
  242. package/bundled/locales/zh-CN/skills/commands/metrics.md +3 -2
  243. package/bundled/locales/zh-CN/skills/commands/migrate.md +5 -4
  244. package/bundled/locales/zh-CN/skills/commands/observability.md +48 -3
  245. package/bundled/locales/zh-CN/skills/commands/pr.md +4 -3
  246. package/bundled/locales/zh-CN/skills/commands/refactor.md +76 -38
  247. package/bundled/locales/zh-CN/skills/commands/release.md +82 -1
  248. package/bundled/locales/zh-CN/skills/commands/requirement.md +40 -1
  249. package/bundled/locales/zh-CN/skills/commands/reverse-bdd.md +36 -1
  250. package/bundled/locales/zh-CN/skills/commands/reverse-sdd.md +44 -1
  251. package/bundled/locales/zh-CN/skills/commands/reverse-tdd.md +42 -1
  252. package/bundled/locales/zh-CN/skills/commands/reverse.md +43 -1
  253. package/bundled/locales/zh-CN/skills/commands/runbook.md +50 -3
  254. package/bundled/locales/zh-CN/skills/commands/scan.md +3 -2
  255. package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +50 -1
  256. package/bundled/locales/zh-CN/skills/commands/sdd.md +182 -1
  257. package/bundled/locales/zh-CN/skills/commands/security.md +3 -2
  258. package/bundled/locales/zh-CN/skills/commands/slo.md +51 -3
  259. package/bundled/locales/zh-CN/skills/commands/tdd.md +74 -5
  260. package/bundled/locales/zh-CN/skills/commands/update.md +70 -8
  261. package/bundled/locales/zh-CN/skills/commit-standards/SKILL.md +4 -4
  262. package/bundled/locales/zh-CN/skills/commit-standards/conventional-commits.md +45 -44
  263. package/bundled/locales/zh-CN/skills/commit-standards/guide.md +172 -52
  264. package/bundled/locales/zh-CN/skills/commit-standards/language-options.md +50 -47
  265. package/bundled/locales/zh-CN/skills/contract-test-assistant/SKILL.md +2 -2
  266. package/bundled/locales/zh-CN/skills/contract-test-assistant/guide.md +76 -1
  267. package/bundled/locales/zh-CN/skills/database-assistant/SKILL.md +18 -5
  268. package/bundled/locales/zh-CN/skills/dev-methodology/SKILL.md +4 -2
  269. package/bundled/locales/zh-CN/skills/dev-methodology/create-methodology.md +2 -0
  270. package/bundled/locales/zh-CN/skills/dev-methodology/runtime.md +2 -0
  271. package/bundled/locales/zh-CN/skills/docs-generator/SKILL.md +16 -2
  272. package/bundled/locales/zh-CN/skills/docs-generator/guide.md +8 -7
  273. package/bundled/locales/zh-CN/skills/documentation-guide/SKILL.md +209 -184
  274. package/bundled/locales/zh-CN/skills/documentation-guide/documentation-structure.md +73 -72
  275. package/bundled/locales/zh-CN/skills/documentation-guide/readme-template.md +37 -36
  276. package/bundled/locales/zh-CN/skills/durable-execution-assistant/SKILL.md +28 -2
  277. package/bundled/locales/zh-CN/skills/e2e-assistant/SKILL.md +21 -6
  278. package/bundled/locales/zh-CN/skills/error-code-guide/SKILL.md +76 -95
  279. package/bundled/locales/zh-CN/skills/git-workflow-guide/SKILL.md +80 -87
  280. package/bundled/locales/zh-CN/skills/git-workflow-guide/branch-naming.md +44 -43
  281. package/bundled/locales/zh-CN/skills/git-workflow-guide/git-workflow.md +66 -65
  282. package/bundled/locales/zh-CN/skills/incident-response-assistant/SKILL.md +31 -13
  283. package/bundled/locales/zh-CN/skills/metrics-dashboard-assistant/SKILL.md +38 -2
  284. package/bundled/locales/zh-CN/skills/observability-assistant/SKILL.md +75 -1
  285. package/bundled/locales/zh-CN/skills/pr-automation-assistant/SKILL.md +32 -6
  286. package/bundled/locales/zh-CN/skills/project-discovery/SKILL.md +8 -2
  287. package/bundled/locales/zh-CN/skills/project-discovery/guide.md +158 -157
  288. package/bundled/locales/zh-CN/skills/project-structure-guide/SKILL.md +49 -46
  289. package/bundled/locales/zh-CN/skills/project-structure-guide/language-patterns.md +8 -7
  290. package/bundled/locales/zh-CN/skills/refactoring-assistant/SKILL.md +22 -2
  291. package/bundled/locales/zh-CN/skills/refactoring-assistant/guide.md +172 -171
  292. package/bundled/locales/zh-CN/skills/release-standards/SKILL.md +66 -23
  293. package/bundled/locales/zh-CN/skills/release-standards/changelog-format.md +42 -41
  294. package/bundled/locales/zh-CN/skills/release-standards/guide.md +51 -43
  295. package/bundled/locales/zh-CN/skills/release-standards/release-workflow.md +131 -95
  296. package/bundled/locales/zh-CN/skills/release-standards/semantic-versioning.md +62 -61
  297. package/bundled/locales/zh-CN/skills/requirement-assistant/SKILL.md +24 -15
  298. package/bundled/locales/zh-CN/skills/requirement-assistant/guide.md +88 -79
  299. package/bundled/locales/zh-CN/skills/requirement-assistant/requirement-checklist.md +128 -127
  300. package/bundled/locales/zh-CN/skills/requirement-assistant/requirement-writing.md +121 -120
  301. package/bundled/locales/zh-CN/skills/retrospective-assistant/guide.md +206 -2
  302. package/bundled/locales/zh-CN/skills/reverse-engineer/SKILL.md +2 -2
  303. package/bundled/locales/zh-CN/skills/reverse-engineer/bdd-extraction.md +2 -1
  304. package/bundled/locales/zh-CN/skills/reverse-engineer/guide.md +297 -173
  305. package/bundled/locales/zh-CN/skills/reverse-engineer/tdd-analysis.md +2 -1
  306. package/bundled/locales/zh-CN/skills/reverse-engineer/workflow.md +2 -1
  307. package/bundled/locales/zh-CN/skills/runbook-assistant/SKILL.md +9 -2
  308. package/bundled/locales/zh-CN/skills/security-assistant/SKILL.md +24 -6
  309. package/bundled/locales/zh-CN/skills/security-scan-assistant/SKILL.md +34 -10
  310. package/bundled/locales/zh-CN/skills/slo-assistant/SKILL.md +2 -1
  311. package/bundled/locales/zh-CN/skills/spec-derivation/SKILL.md +2 -2
  312. package/bundled/locales/zh-CN/skills/spec-driven-dev/guide.md +38 -6
  313. package/bundled/locales/zh-CN/skills/tdd-assistant/SKILL.md +16 -3
  314. package/bundled/locales/zh-CN/skills/tdd-assistant/guide.md +217 -156
  315. package/bundled/locales/zh-CN/skills/tdd-assistant/language-examples.md +727 -82
  316. package/bundled/locales/zh-CN/skills/tdd-assistant/tdd-workflow.md +396 -214
  317. package/bundled/locales/zh-CN/skills/test-coverage-assistant/SKILL.md +14 -5
  318. package/bundled/locales/zh-CN/skills/test-coverage-assistant/guide.md +25 -12
  319. package/bundled/locales/zh-CN/skills/testing-guide/testing-pyramid.md +99 -98
  320. package/bundled/locales/zh-CN/skills/testing-guide/testing-theory.md +3 -1
  321. package/bundled/locales/zh-CN/skills/tools/cline/README.md +2 -1
  322. package/bundled/locales/zh-CN/skills/tools/copilot/README.md +65 -18
  323. package/bundled/locales/zh-CN/skills/tools/copilot/copilot-instructions.md +2 -1
  324. package/bundled/locales/zh-CN/skills/tools/cursor/README.md +2 -1
  325. package/bundled/locales/zh-CN/skills/tools/windsurf/README.md +2 -1
  326. package/bundled/locales/zh-CN/skills/workflows/README.md +4 -2
  327. package/bundled/locales/zh-CN/templates/reverse-spec-template.md +50 -1
  328. package/bundled/locales/zh-TW/CHANGELOG.md +2282 -1112
  329. package/bundled/locales/zh-TW/CLAUDE.md +962 -76
  330. package/bundled/locales/zh-TW/README.md +3 -3
  331. package/bundled/locales/zh-TW/SECURITY.md +3 -3
  332. package/bundled/locales/zh-TW/STANDARDS-MAPPING.md +103 -6
  333. package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +46 -93
  334. package/bundled/locales/zh-TW/adoption/DAILY-WORKFLOW-GUIDE.md +2 -1
  335. package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +3 -1
  336. package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +10 -9
  337. package/bundled/locales/zh-TW/adoption/checklists/minimal.md +6 -2
  338. package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -4
  339. package/bundled/locales/zh-TW/ai/MAINTENANCE.md +34 -14
  340. package/bundled/locales/zh-TW/ai/options/commit-message/traditional-chinese.ai.yaml +48 -40
  341. package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md +56 -10
  342. package/bundled/locales/zh-TW/core/acceptance-test-driven-development.md +2 -1
  343. package/bundled/locales/zh-TW/core/accessibility-standards.md +895 -46
  344. package/bundled/locales/zh-TW/core/adr-standards.md +2 -1
  345. package/bundled/locales/zh-TW/core/agent-communication-protocol.md +2 -1
  346. package/bundled/locales/zh-TW/core/agent-dispatch.md +102 -33
  347. package/bundled/locales/zh-TW/core/ai-agreement-standards.md +58 -41
  348. package/bundled/locales/zh-TW/core/ai-command-behavior.md +2 -1
  349. package/bundled/locales/zh-TW/core/ai-friendly-architecture.md +306 -67
  350. package/bundled/locales/zh-TW/core/ai-instruction-standards.md +16 -13
  351. package/bundled/locales/zh-TW/core/ai-response-navigation.md +3 -3
  352. package/bundled/locales/zh-TW/core/alerting-standards.md +257 -35
  353. package/bundled/locales/zh-TW/core/anti-hallucination.md +169 -40
  354. package/bundled/locales/zh-TW/core/anti-sycophancy-prompting.md +2 -1
  355. package/bundled/locales/zh-TW/core/api-design-standards.md +2 -1
  356. package/bundled/locales/zh-TW/core/behavior-driven-development.md +3 -17
  357. package/bundled/locales/zh-TW/core/branch-completion.md +130 -34
  358. package/bundled/locales/zh-TW/core/capability-declaration.md +41 -79
  359. package/bundled/locales/zh-TW/core/change-batching-standards.md +2 -1
  360. package/bundled/locales/zh-TW/core/changelog-standards.md +14 -9
  361. package/bundled/locales/zh-TW/core/chaos-engineering-standards.md +138 -36
  362. package/bundled/locales/zh-TW/core/checkin-standards.md +84 -26
  363. package/bundled/locales/zh-TW/core/circuit-breaker.md +48 -87
  364. package/bundled/locales/zh-TW/core/code-review-checklist.md +19 -7
  365. package/bundled/locales/zh-TW/core/commit-message-guide.md +218 -87
  366. package/bundled/locales/zh-TW/core/containerization-standards.md +259 -57
  367. package/bundled/locales/zh-TW/core/context-aware-loading.md +121 -27
  368. package/bundled/locales/zh-TW/core/database-standards.md +2 -1
  369. package/bundled/locales/zh-TW/core/deprecation-standards.md +139 -37
  370. package/bundled/locales/zh-TW/core/design-document-standards.md +265 -55
  371. package/bundled/locales/zh-TW/core/developer-memory.md +102 -12
  372. package/bundled/locales/zh-TW/core/documentation-lifecycle.md +2 -1
  373. package/bundled/locales/zh-TW/core/documentation-structure.md +17 -8
  374. package/bundled/locales/zh-TW/core/dual-phase-output.md +28 -90
  375. package/bundled/locales/zh-TW/core/environment-standards.md +250 -72
  376. package/bundled/locales/zh-TW/core/error-code-standards.md +17 -6
  377. package/bundled/locales/zh-TW/core/estimation-standards.md +177 -44
  378. package/bundled/locales/zh-TW/core/execution-history.md +2 -1
  379. package/bundled/locales/zh-TW/core/failure-source-taxonomy.md +59 -117
  380. package/bundled/locales/zh-TW/core/feature-flag-standards.md +202 -57
  381. package/bundled/locales/zh-TW/core/forward-derivation-standards.md +592 -133
  382. package/bundled/locales/zh-TW/core/frontend-design-standards.md +120 -8
  383. package/bundled/locales/zh-TW/core/git-workflow.md +197 -37
  384. package/bundled/locales/zh-TW/core/git-worktree.md +79 -49
  385. package/bundled/locales/zh-TW/core/guides/anti-hallucination-guide.md +234 -487
  386. package/bundled/locales/zh-TW/core/guides/file-placement-guide.md +86 -2
  387. package/bundled/locales/zh-TW/core/guides/git-workflow-guide.md +411 -464
  388. package/bundled/locales/zh-TW/core/guides/performance-guide.md +2 -0
  389. package/bundled/locales/zh-TW/core/guides/refactoring-guide.md +237 -484
  390. package/bundled/locales/zh-TW/core/guides/security-guide.md +2 -0
  391. package/bundled/locales/zh-TW/core/health-check-standards.md +46 -104
  392. package/bundled/locales/zh-TW/core/immutability-first.md +45 -85
  393. package/bundled/locales/zh-TW/core/knowledge-graph-memory.md +2 -1
  394. package/bundled/locales/zh-TW/core/knowledge-transfer-standards.md +103 -40
  395. package/bundled/locales/zh-TW/core/observability-standards.md +284 -40
  396. package/bundled/locales/zh-TW/core/performance-standards.md +387 -86
  397. package/bundled/locales/zh-TW/core/pipeline-integration-standards.md +2 -1
  398. package/bundled/locales/zh-TW/core/postmortem-standards.md +367 -36
  399. package/bundled/locales/zh-TW/core/privacy-standards.md +153 -46
  400. package/bundled/locales/zh-TW/core/project-context-memory.md +210 -31
  401. package/bundled/locales/zh-TW/core/project-structure.md +240 -19
  402. package/bundled/locales/zh-TW/core/recovery-recipe-registry.md +54 -114
  403. package/bundled/locales/zh-TW/core/refactoring-standards.md +153 -48
  404. package/bundled/locales/zh-TW/core/requirement-engineering.md +8 -37
  405. package/bundled/locales/zh-TW/core/retrospective-standards.md +127 -7
  406. package/bundled/locales/zh-TW/core/retry-standards.md +41 -105
  407. package/bundled/locales/zh-TW/core/reverse-engineering-standards.md +5 -1
  408. package/bundled/locales/zh-TW/core/runbook-standards.md +296 -23
  409. package/bundled/locales/zh-TW/core/secret-management-standards.md +12 -4
  410. package/bundled/locales/zh-TW/core/security-decision.md +43 -84
  411. package/bundled/locales/zh-TW/core/security-standards.md +204 -25
  412. package/bundled/locales/zh-TW/core/self-review-protocol.md +2 -1
  413. package/bundled/locales/zh-TW/core/skill-standard-alignment-check.md +103 -69
  414. package/bundled/locales/zh-TW/core/slo-standards.md +301 -49
  415. package/bundled/locales/zh-TW/core/spec-driven-development.md +36 -7
  416. package/bundled/locales/zh-TW/core/standard-admission-criteria.md +22 -28
  417. package/bundled/locales/zh-TW/core/standard-lifecycle-management.md +40 -48
  418. package/bundled/locales/zh-TW/core/structured-task-definition.md +2 -1
  419. package/bundled/locales/zh-TW/core/supply-chain-security-standards.md +137 -10
  420. package/bundled/locales/zh-TW/core/systematic-debugging.md +94 -38
  421. package/bundled/locales/zh-TW/core/tech-debt-standards.md +170 -54
  422. package/bundled/locales/zh-TW/core/test-completeness-dimensions.md +101 -12
  423. package/bundled/locales/zh-TW/core/test-data-standards.md +245 -23
  424. package/bundled/locales/zh-TW/core/test-driven-development.md +4 -1
  425. package/bundled/locales/zh-TW/core/test-governance.md +92 -32
  426. package/bundled/locales/zh-TW/core/testing-standards.md +61 -14
  427. package/bundled/locales/zh-TW/core/timeout-standards.md +45 -85
  428. package/bundled/locales/zh-TW/core/token-budget.md +41 -112
  429. package/bundled/locales/zh-TW/core/translation-lifecycle-standards.md +28 -16
  430. package/bundled/locales/zh-TW/core/verification-evidence.md +2 -1
  431. package/bundled/locales/zh-TW/core/versioning.md +6 -2
  432. package/bundled/locales/zh-TW/core/virtual-organization-standards.md +42 -36
  433. package/bundled/locales/zh-TW/core/workflow-enforcement.md +2 -1
  434. package/bundled/locales/zh-TW/core/workflow-state-protocol.md +2 -1
  435. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +2 -1
  436. package/bundled/locales/zh-TW/docs/CLI-FLOW.md +2 -1
  437. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +12 -3
  438. package/bundled/locales/zh-TW/docs/DEV-WORKFLOW-MAPPING.md +2 -1
  439. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +8 -6
  440. package/bundled/locales/zh-TW/docs/STANDARDS-REFERENCE.md +2 -1
  441. package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +2 -1
  442. package/bundled/locales/zh-TW/docs/USER-MANUAL.md +9 -1
  443. package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +4 -1
  444. package/bundled/locales/zh-TW/docs/specs/system/memory-adoption-strategy.md +2 -0
  445. package/bundled/locales/zh-TW/docs/user/FAQ.md +2 -0
  446. package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +2 -0
  447. package/bundled/locales/zh-TW/docs/user/GLOSSARY.md +2 -0
  448. package/bundled/locales/zh-TW/docs/user/README.md +2 -0
  449. package/bundled/locales/zh-TW/docs/user/TROUBLESHOOTING.md +2 -0
  450. package/bundled/locales/zh-TW/integrations/claude-code/README.md +2 -1
  451. package/bundled/locales/zh-TW/integrations/codex/AGENTS.md +136 -2
  452. package/bundled/locales/zh-TW/integrations/codex/README.md +7 -1
  453. package/bundled/locales/zh-TW/integrations/gemini-cli/GEMINI.md +59 -1
  454. package/bundled/locales/zh-TW/integrations/gemini-cli/README.md +8 -1
  455. package/bundled/locales/zh-TW/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +7 -1
  456. package/bundled/locales/zh-TW/integrations/github-copilot/README.md +9 -3
  457. package/bundled/locales/zh-TW/integrations/github-copilot/copilot-instructions.md +146 -12
  458. package/bundled/locales/zh-TW/integrations/github-copilot/skills-mapping.md +7 -1
  459. package/bundled/locales/zh-TW/integrations/google-antigravity/AGENTS.md +110 -3
  460. package/bundled/locales/zh-TW/integrations/google-antigravity/README.md +7 -1
  461. package/bundled/locales/zh-TW/integrations/opencode/AGENTS.md +140 -2
  462. package/bundled/locales/zh-TW/integrations/opencode/README.md +7 -1
  463. package/bundled/locales/zh-TW/integrations/opencode/skills-mapping.md +8 -2
  464. package/bundled/locales/zh-TW/integrations/openspec/AGENTS.md +46 -1
  465. package/bundled/locales/zh-TW/integrations/openspec/README.md +7 -1
  466. package/bundled/locales/zh-TW/integrations/spec-kit/AGENTS.md +20 -2
  467. package/bundled/locales/zh-TW/integrations/spec-kit/README.md +7 -1
  468. package/bundled/locales/zh-TW/methodologies/guides/tdd-guide.md +584 -475
  469. package/bundled/locales/zh-TW/options/changelog/auto-generated.md +2 -0
  470. package/bundled/locales/zh-TW/options/changelog/keep-a-changelog.md +2 -0
  471. package/bundled/locales/zh-TW/options/code-review/automated-review.md +2 -0
  472. package/bundled/locales/zh-TW/options/code-review/pair-programming.md +2 -0
  473. package/bundled/locales/zh-TW/options/commit-message/bilingual.md +93 -5
  474. package/bundled/locales/zh-TW/options/commit-message/english.md +118 -1
  475. package/bundled/locales/zh-TW/options/commit-message/traditional-chinese.md +82 -1
  476. package/bundled/locales/zh-TW/options/documentation/api-docs.md +2 -0
  477. package/bundled/locales/zh-TW/options/documentation/markdown-docs.md +2 -0
  478. package/bundled/locales/zh-TW/options/documentation/wiki-style.md +2 -0
  479. package/bundled/locales/zh-TW/options/git-workflow/gitflow.md +99 -71
  480. package/bundled/locales/zh-TW/options/git-workflow/github-flow.md +68 -50
  481. package/bundled/locales/zh-TW/options/git-workflow/merge-commit.md +131 -20
  482. package/bundled/locales/zh-TW/options/git-workflow/rebase-ff.md +142 -27
  483. package/bundled/locales/zh-TW/options/git-workflow/squash-merge.md +100 -15
  484. package/bundled/locales/zh-TW/options/git-workflow/trunk-based.md +103 -56
  485. package/bundled/locales/zh-TW/options/project-structure/dotnet.md +233 -14
  486. package/bundled/locales/zh-TW/options/project-structure/go.md +270 -12
  487. package/bundled/locales/zh-TW/options/project-structure/java.md +235 -15
  488. package/bundled/locales/zh-TW/options/project-structure/kotlin.md +2 -0
  489. package/bundled/locales/zh-TW/options/project-structure/nodejs.md +136 -19
  490. package/bundled/locales/zh-TW/options/project-structure/php.md +2 -0
  491. package/bundled/locales/zh-TW/options/project-structure/python.md +177 -19
  492. package/bundled/locales/zh-TW/options/project-structure/ruby.md +2 -0
  493. package/bundled/locales/zh-TW/options/project-structure/rust.md +2 -0
  494. package/bundled/locales/zh-TW/options/project-structure/swift.md +2 -0
  495. package/bundled/locales/zh-TW/options/testing/contract-testing.md +2 -0
  496. package/bundled/locales/zh-TW/options/testing/e2e-testing.md +182 -21
  497. package/bundled/locales/zh-TW/options/testing/industry-pyramid.md +2 -0
  498. package/bundled/locales/zh-TW/options/testing/integration-testing.md +134 -22
  499. package/bundled/locales/zh-TW/options/testing/istqb-framework.md +2 -0
  500. package/bundled/locales/zh-TW/options/testing/performance-testing.md +2 -0
  501. package/bundled/locales/zh-TW/options/testing/security-testing.md +2 -0
  502. package/bundled/locales/zh-TW/options/testing/system-testing.md +175 -1
  503. package/bundled/locales/zh-TW/options/testing/unit-testing.md +123 -9
  504. package/bundled/locales/zh-TW/skills/CONTRIBUTING.template.md +3 -2
  505. package/bundled/locales/zh-TW/skills/INTEGRATION-GUIDE.md +2 -1
  506. package/bundled/locales/zh-TW/skills/README.md +2 -1
  507. package/bundled/locales/zh-TW/skills/_shared/README.md +2 -1
  508. package/bundled/locales/zh-TW/skills/ac-coverage/SKILL.md +15 -4
  509. package/bundled/locales/zh-TW/skills/adr-assistant/guide.md +123 -3
  510. package/bundled/locales/zh-TW/skills/agents/README.md +99 -1
  511. package/bundled/locales/zh-TW/skills/agents/code-architect.md +2 -0
  512. package/bundled/locales/zh-TW/skills/agents/doc-writer.md +2 -0
  513. package/bundled/locales/zh-TW/skills/agents/reviewer.md +3 -1
  514. package/bundled/locales/zh-TW/skills/agents/spec-analyst.md +2 -0
  515. package/bundled/locales/zh-TW/skills/agents/test-specialist.md +2 -0
  516. package/bundled/locales/zh-TW/skills/ai-collaboration-standards/SKILL.md +48 -37
  517. package/bundled/locales/zh-TW/skills/ai-collaboration-standards/anti-hallucination.md +22 -2
  518. package/bundled/locales/zh-TW/skills/ai-collaboration-standards/certainty-labels.md +29 -3
  519. package/bundled/locales/zh-TW/skills/ai-friendly-architecture/SKILL.md +23 -36
  520. package/bundled/locales/zh-TW/skills/ai-instruction-standards/SKILL.md +12 -36
  521. package/bundled/locales/zh-TW/skills/api-design-assistant/SKILL.md +21 -5
  522. package/bundled/locales/zh-TW/skills/atdd-assistant/SKILL.md +40 -15
  523. package/bundled/locales/zh-TW/skills/atdd-assistant/acceptance-criteria-guide.md +2 -1
  524. package/bundled/locales/zh-TW/skills/atdd-assistant/atdd-workflow.md +98 -1
  525. package/bundled/locales/zh-TW/skills/atdd-assistant/guide.md +24 -8
  526. package/bundled/locales/zh-TW/skills/audit-assistant/SKILL.md +8 -2
  527. package/bundled/locales/zh-TW/skills/bdd-assistant/SKILL.md +29 -6
  528. package/bundled/locales/zh-TW/skills/bdd-assistant/bdd-workflow.md +2 -1
  529. package/bundled/locales/zh-TW/skills/bdd-assistant/gherkin-guide.md +2 -1
  530. package/bundled/locales/zh-TW/skills/bdd-assistant/guide.md +9 -8
  531. package/bundled/locales/zh-TW/skills/changelog-guide/SKILL.md +12 -3
  532. package/bundled/locales/zh-TW/skills/changelog-guide/guide.md +11 -7
  533. package/bundled/locales/zh-TW/skills/checkin-assistant/SKILL.md +19 -3
  534. package/bundled/locales/zh-TW/skills/checkin-assistant/guide.md +5 -3
  535. package/bundled/locales/zh-TW/skills/ci-cd-assistant/SKILL.md +35 -16
  536. package/bundled/locales/zh-TW/skills/code-review-assistant/SKILL.md +19 -2
  537. package/bundled/locales/zh-TW/skills/code-review-assistant/checkin-checklist.md +2 -1
  538. package/bundled/locales/zh-TW/skills/code-review-assistant/guide.md +81 -6
  539. package/bundled/locales/zh-TW/skills/code-review-assistant/review-checklist.md +2 -1
  540. package/bundled/locales/zh-TW/skills/commands/ac-coverage.md +47 -2
  541. package/bundled/locales/zh-TW/skills/commands/api-design.md +3 -2
  542. package/bundled/locales/zh-TW/skills/commands/atdd.md +80 -10
  543. package/bundled/locales/zh-TW/skills/commands/audit.md +3 -2
  544. package/bundled/locales/zh-TW/skills/commands/bdd.md +114 -16
  545. package/bundled/locales/zh-TW/skills/commands/changelog.md +45 -9
  546. package/bundled/locales/zh-TW/skills/commands/check.md +74 -21
  547. package/bundled/locales/zh-TW/skills/commands/checkin.md +56 -11
  548. package/bundled/locales/zh-TW/skills/commands/ci-cd.md +2 -1
  549. package/bundled/locales/zh-TW/skills/commands/code-review.md +43 -2
  550. package/bundled/locales/zh-TW/skills/commands/commit.md +58 -4
  551. package/bundled/locales/zh-TW/skills/commands/config.md +52 -4
  552. package/bundled/locales/zh-TW/skills/commands/coverage.md +45 -4
  553. package/bundled/locales/zh-TW/skills/commands/database.md +3 -2
  554. package/bundled/locales/zh-TW/skills/commands/derive-all.md +44 -2
  555. package/bundled/locales/zh-TW/skills/commands/derive-atdd.md +37 -2
  556. package/bundled/locales/zh-TW/skills/commands/derive-bdd.md +44 -3
  557. package/bundled/locales/zh-TW/skills/commands/derive-tdd.md +45 -3
  558. package/bundled/locales/zh-TW/skills/commands/derive.md +62 -5
  559. package/bundled/locales/zh-TW/skills/commands/dev-workflow.md +60 -9
  560. package/bundled/locales/zh-TW/skills/commands/discover.md +43 -2
  561. package/bundled/locales/zh-TW/skills/commands/docgen.md +39 -2
  562. package/bundled/locales/zh-TW/skills/commands/docs.md +139 -7
  563. package/bundled/locales/zh-TW/skills/commands/durable.md +3 -2
  564. package/bundled/locales/zh-TW/skills/commands/e2e.md +86 -3
  565. package/bundled/locales/zh-TW/skills/commands/guide.md +4 -2
  566. package/bundled/locales/zh-TW/skills/commands/incident.md +3 -2
  567. package/bundled/locales/zh-TW/skills/commands/init.md +72 -15
  568. package/bundled/locales/zh-TW/skills/commands/methodology.md +117 -28
  569. package/bundled/locales/zh-TW/skills/commands/metrics.md +2 -1
  570. package/bundled/locales/zh-TW/skills/commands/migrate.md +2 -1
  571. package/bundled/locales/zh-TW/skills/commands/observability.md +45 -2
  572. package/bundled/locales/zh-TW/skills/commands/pr.md +2 -1
  573. package/bundled/locales/zh-TW/skills/commands/refactor.md +54 -13
  574. package/bundled/locales/zh-TW/skills/commands/release.md +83 -2
  575. package/bundled/locales/zh-TW/skills/commands/requirement.md +41 -2
  576. package/bundled/locales/zh-TW/skills/commands/reverse-bdd.md +37 -2
  577. package/bundled/locales/zh-TW/skills/commands/reverse-sdd.md +45 -2
  578. package/bundled/locales/zh-TW/skills/commands/reverse-tdd.md +43 -2
  579. package/bundled/locales/zh-TW/skills/commands/reverse.md +44 -2
  580. package/bundled/locales/zh-TW/skills/commands/runbook.md +47 -2
  581. package/bundled/locales/zh-TW/skills/commands/scan.md +3 -2
  582. package/bundled/locales/zh-TW/skills/commands/sdd-retro.md +52 -3
  583. package/bundled/locales/zh-TW/skills/commands/sdd.md +209 -28
  584. package/bundled/locales/zh-TW/skills/commands/security.md +3 -2
  585. package/bundled/locales/zh-TW/skills/commands/slo.md +48 -2
  586. package/bundled/locales/zh-TW/skills/commands/tdd.md +71 -2
  587. package/bundled/locales/zh-TW/skills/commands/update.md +64 -2
  588. package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +2 -2
  589. package/bundled/locales/zh-TW/skills/commit-standards/conventional-commits.md +2 -1
  590. package/bundled/locales/zh-TW/skills/commit-standards/guide.md +137 -17
  591. package/bundled/locales/zh-TW/skills/commit-standards/language-options.md +21 -18
  592. package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +2 -2
  593. package/bundled/locales/zh-TW/skills/contract-test-assistant/guide.md +81 -1
  594. package/bundled/locales/zh-TW/skills/database-assistant/SKILL.md +21 -5
  595. package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md +2 -1
  596. package/bundled/locales/zh-TW/skills/dev-methodology/SKILL.md +4 -1
  597. package/bundled/locales/zh-TW/skills/dev-methodology/create-methodology.md +2 -0
  598. package/bundled/locales/zh-TW/skills/dev-methodology/runtime.md +2 -0
  599. package/bundled/locales/zh-TW/skills/docs-generator/SKILL.md +19 -2
  600. package/bundled/locales/zh-TW/skills/docs-generator/guide.md +4 -3
  601. package/bundled/locales/zh-TW/skills/documentation-guide/SKILL.md +67 -42
  602. package/bundled/locales/zh-TW/skills/documentation-guide/documentation-structure.md +2 -1
  603. package/bundled/locales/zh-TW/skills/documentation-guide/readme-template.md +2 -1
  604. package/bundled/locales/zh-TW/skills/durable-execution-assistant/SKILL.md +32 -3
  605. package/bundled/locales/zh-TW/skills/e2e-assistant/SKILL.md +25 -7
  606. package/bundled/locales/zh-TW/skills/error-code-guide/SKILL.md +17 -34
  607. package/bundled/locales/zh-TW/skills/git-workflow-guide/SKILL.md +33 -38
  608. package/bundled/locales/zh-TW/skills/git-workflow-guide/branch-naming.md +2 -1
  609. package/bundled/locales/zh-TW/skills/git-workflow-guide/git-workflow.md +2 -1
  610. package/bundled/locales/zh-TW/skills/incident-response-assistant/SKILL.md +35 -14
  611. package/bundled/locales/zh-TW/skills/journey-test-assistant/SKILL.md +2 -14
  612. package/bundled/locales/zh-TW/skills/knowledge-graph/SKILL.md +6 -2
  613. package/bundled/locales/zh-TW/skills/metrics-dashboard-assistant/SKILL.md +42 -3
  614. package/bundled/locales/zh-TW/skills/observability-assistant/SKILL.md +85 -18
  615. package/bundled/locales/zh-TW/skills/pr-automation-assistant/SKILL.md +27 -3
  616. package/bundled/locales/zh-TW/skills/project-discovery/SKILL.md +11 -3
  617. package/bundled/locales/zh-TW/skills/project-discovery/guide.md +5 -3
  618. package/bundled/locales/zh-TW/skills/project-discovery/workflow.md +2 -1
  619. package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md +19 -16
  620. package/bundled/locales/zh-TW/skills/project-structure-guide/language-patterns.md +2 -1
  621. package/bundled/locales/zh-TW/skills/refactoring-assistant/SKILL.md +26 -3
  622. package/bundled/locales/zh-TW/skills/refactoring-assistant/guide.md +4 -2
  623. package/bundled/locales/zh-TW/skills/release-standards/SKILL.md +91 -45
  624. package/bundled/locales/zh-TW/skills/release-standards/changelog-format.md +4 -3
  625. package/bundled/locales/zh-TW/skills/release-standards/guide.md +14 -5
  626. package/bundled/locales/zh-TW/skills/release-standards/release-workflow.md +5 -1
  627. package/bundled/locales/zh-TW/skills/release-standards/semantic-versioning.md +2 -1
  628. package/bundled/locales/zh-TW/skills/requirement-assistant/SKILL.md +15 -6
  629. package/bundled/locales/zh-TW/skills/requirement-assistant/guide.md +18 -8
  630. package/bundled/locales/zh-TW/skills/requirement-assistant/requirement-checklist.md +2 -1
  631. package/bundled/locales/zh-TW/skills/requirement-assistant/requirement-writing.md +2 -1
  632. package/bundled/locales/zh-TW/skills/retrospective-assistant/guide.md +200 -6
  633. package/bundled/locales/zh-TW/skills/reverse-engineer/bdd-extraction.md +2 -1
  634. package/bundled/locales/zh-TW/skills/reverse-engineer/guide.md +161 -36
  635. package/bundled/locales/zh-TW/skills/reverse-engineer/tdd-analysis.md +2 -1
  636. package/bundled/locales/zh-TW/skills/reverse-engineer/workflow.md +2 -1
  637. package/bundled/locales/zh-TW/skills/runbook-assistant/SKILL.md +9 -1
  638. package/bundled/locales/zh-TW/skills/security-assistant/SKILL.md +25 -5
  639. package/bundled/locales/zh-TW/skills/security-scan-assistant/SKILL.md +34 -8
  640. package/bundled/locales/zh-TW/skills/skill-builder/SKILL.md +3 -21
  641. package/bundled/locales/zh-TW/skills/slo-assistant/SKILL.md +3 -1
  642. package/bundled/locales/zh-TW/skills/spec-derivation/SKILL.md +2 -1
  643. package/bundled/locales/zh-TW/skills/spec-driven-dev/guide.md +35 -2
  644. package/bundled/locales/zh-TW/skills/sweep/SKILL.md +2 -1
  645. package/bundled/locales/zh-TW/skills/tdd-assistant/SKILL.md +10 -2
  646. package/bundled/locales/zh-TW/skills/tdd-assistant/guide.md +68 -9
  647. package/bundled/locales/zh-TW/skills/tdd-assistant/language-examples.md +693 -47
  648. package/bundled/locales/zh-TW/skills/tdd-assistant/tdd-workflow.md +183 -1
  649. package/bundled/locales/zh-TW/skills/test-coverage-assistant/SKILL.md +15 -5
  650. package/bundled/locales/zh-TW/skills/test-coverage-assistant/guide.md +26 -13
  651. package/bundled/locales/zh-TW/skills/testing-guide/testing-pyramid.md +2 -1
  652. package/bundled/locales/zh-TW/skills/testing-guide/testing-theory.md +3 -1
  653. package/bundled/locales/zh-TW/skills/tools/cline/README.md +2 -1
  654. package/bundled/locales/zh-TW/skills/tools/copilot/README.md +65 -18
  655. package/bundled/locales/zh-TW/skills/tools/copilot/copilot-instructions.md +2 -1
  656. package/bundled/locales/zh-TW/skills/tools/cursor/README.md +2 -1
  657. package/bundled/locales/zh-TW/skills/tools/windsurf/README.md +2 -1
  658. package/bundled/locales/zh-TW/skills/workflows/README.md +11 -9
  659. package/bundled/locales/zh-TW/templates/reverse-spec-template.md +50 -1
  660. package/bundled/skills/.claude-plugin/plugin.json +71 -0
  661. package/bundled/skills/commit-standards/SKILL.md +2 -2
  662. package/bundled/skills/commit-standards/guide.md +3 -2
  663. package/bundled/skills/commit-standards/language-options.md +19 -17
  664. package/package.json +2 -2
  665. package/src/commands/audit.js +28 -1
  666. package/src/commands/check.js +72 -3
  667. package/src/commands/compile.js +37 -4
  668. package/src/commands/config.js +49 -24
  669. package/src/commands/init.js +78 -30
  670. package/src/commands/open-work.js +6 -2
  671. package/src/commands/release-messages.js +228 -0
  672. package/src/commands/release.js +127 -68
  673. package/src/commands/run-intent.js +11 -0
  674. package/src/commands/spec.js +4 -2
  675. package/src/commands/update.js +173 -20
  676. package/src/compilers/claude-code-compiler.js +9 -1
  677. package/src/config/ai-agent-paths.js +14 -1
  678. package/src/core/installed-formats.js +15 -0
  679. package/src/core/open-work-config.js +20 -1
  680. package/src/core/project-config.js +55 -0
  681. package/src/i18n/messages.js +106 -2
  682. package/src/installers/hooks-installer.js +1 -1
  683. package/src/installers/manifest-installer.js +1 -1
  684. package/src/installers/skills-installer.js +1 -1
  685. package/src/installers/standards-installer.js +3 -1
  686. package/src/mcp/server.js +9 -3
  687. package/src/prompts/init.js +26 -22
  688. package/src/reconciler/actual-state-scanner.js +2 -8
  689. package/src/reconciler/backup-locations.js +5 -0
  690. package/src/reconciler/backup-manager.js +19 -11
  691. package/src/reconciler/desired-state-calculator.js +89 -57
  692. package/src/reconciler/plan-executor.js +101 -8
  693. package/src/reconciler/recorded-versions.js +49 -0
  694. package/src/reconciler/relative-path.js +23 -0
  695. package/src/uninstallers/hook-uninstaller.js +9 -1
  696. package/src/uninstallers/skills-uninstaller.js +22 -3
  697. package/src/utils/available-standards-report.js +25 -4
  698. package/src/utils/available-standards.js +13 -3
  699. package/src/utils/build-manifest.js +1 -1
  700. package/src/utils/commit-message-judge.js +60 -13
  701. package/src/utils/friction-detector.js +23 -11
  702. package/src/utils/git-hooks.js +106 -4
  703. package/src/utils/integration-generator.js +95 -67
  704. package/src/utils/legacy-hook-migration.js +121 -2
  705. package/src/utils/open-work-tracking.mjs +105 -16
  706. package/src/utils/sdd-header.js +16 -4
  707. package/src/utils/skills-installer.js +2 -1
  708. package/src/utils/spinner.js +14 -4
  709. package/src/utils/standard-validator.js +3 -2
  710. package/standards-registry.json +10 -8
  711. package/bundled/locales/zh-TW/core/guides/testing-guide.md +0 -2280
@@ -1,24 +1,28 @@
1
1
  ---
2
2
  source: ../../../core/versioning.md
3
- source_version: 1.2.0
4
- translation_version: 1.2.0
5
- last_synced: 2026-01-08
6
- status: stale
3
+ source_version: 1.5.0
4
+ translation_version: 1.5.0
5
+ last_synced: 2026-10-16
6
+ source_hash: 5c995171e2a4
7
+ status: current
7
8
  ---
8
9
 
9
- > **语言**: [English](../../../core/versioning.md) | [简体中文](../../zh-TW/core/versioning.md) | 简体中文
10
-
11
10
  # 语义化版本标准
12
11
 
13
- **版本**: 1.0.0
14
- **最后更新**: 2025-12-30
15
- **适用范围**: 所有有版本发布的软件项目
12
+ > **语言**: [English](../../../core/versioning.md) | [繁體中文](../../zh-TW/core/versioning.md) | 简体中文
13
+
14
+ **版本**: 1.5.0
15
+ **最后更新**: 2026-07-01
16
+ **适用范围**: 所有具有版本发布的软件项目
17
+ **范围**: universal
18
+ **行业标准**: Semantic Versioning 2.0.0
19
+ **参考**: [semver.org](https://semver.org/)
16
20
 
17
21
  ---
18
22
 
19
23
  ## 目的
20
24
 
21
- 本标准定义如何使用语义化版本 (SemVer) 为软件发布编号,以清楚地向用户和维护者传达变更。
25
+ 本标准定义如何使用语义化版本(SemVer)对软件发布进行版本控制,以便向用户和维护者清晰地传达变更。
22
26
 
23
27
  ---
24
28
 
@@ -27,20 +31,20 @@ status: stale
27
31
  ```
28
32
  MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
29
33
 
30
- 示例:
34
+ Examples:
31
35
  2.3.1
32
36
  1.0.0-alpha.1
33
37
  3.2.0-beta.2+20250112
34
38
  ```
35
39
 
36
- ### 组成说明
40
+ ### 组件
37
41
 
38
- | 组成 | 用途 | 递增时机 |
39
- |------|------|---------|
42
+ | 组件 | 用途 | 递增时机 |
43
+ |-----------|---------|-------------------|
40
44
  | **MAJOR** | 破坏性变更 | 不兼容的 API 变更 |
41
45
  | **MINOR** | 新功能 | 向后兼容的功能 |
42
- | **PATCH** | 错误修复 | 向后兼容的修复 |
43
- | **PRERELEASE** | 预发布标识 | Alpha、Beta、RC 版本 |
46
+ | **PATCH** | 错误修复 | 向后兼容的错误修复 |
47
+ | **PRERELEASE** | 预发布标识符 | Alpha、beta、rc 版本 |
44
48
  | **BUILD** | 构建元数据 | 构建号、提交哈希 |
45
49
 
46
50
  ---
@@ -55,14 +59,40 @@ MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
55
59
  - 重大架构变更
56
60
  - 不兼容的行为变更
57
61
 
62
+ **示例**:
63
+ ```
64
+ 1.9.5 → 2.0.0 # Remove deprecated API
65
+ 3.2.1 → 4.0.0 # Change return type of public method
66
+ ```
67
+
68
+ **指南**:
69
+ - 将 MINOR 和 PATCH 重置为 0
70
+ - 编写迁移指南文档
71
+ - 在先前的 MINOR 版本中提供弃用警告
72
+
73
+ ---
74
+
58
75
  ### MINOR 版本 (x.Y.0)
59
76
 
60
77
  **递增时机**:
61
78
  - 添加新功能(向后兼容)
62
- - 弃用功能(非移除)
79
+ - 弃用功能(不移除)
63
80
  - 实质性内部改进
64
81
  - 新的公开 API
65
82
 
83
+ **示例**:
84
+ ```
85
+ 2.3.5 → 2.4.0 # Add new API endpoint
86
+ 1.12.0 → 1.13.0 # Add optional parameter to existing function
87
+ ```
88
+
89
+ **指南**:
90
+ - 将 PATCH 重置为 0
91
+ - 现有功能保持不变
92
+ - 新功能为可选启用(opt-in)
93
+
94
+ ---
95
+
66
96
  ### PATCH 版本 (x.y.Z)
67
97
 
68
98
  **递增时机**:
@@ -71,104 +101,738 @@ MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
71
101
  - 文档更正
72
102
  - 内部重构(无 API 变更)
73
103
 
104
+ **示例**:
105
+ ```
106
+ 3.1.2 → 3.1.3 # Fix null pointer exception
107
+ 2.0.0 → 2.0.1 # Security vulnerability patch
108
+ ```
109
+
110
+ **指南**:
111
+ - 无新功能
112
+ - 无 API 变更
113
+ - 可立即安全更新
114
+
74
115
  ---
75
116
 
76
- ## API 版本化策略
117
+ ## 预发布版本
118
+
119
+ 格式: `MAJOR.MINOR.PATCH-PRERELEASE`
120
+
121
+ ### 预发布标识符
122
+
123
+ | 标识符 | 用途 | 稳定性 | 受众 |
124
+ |------------|---------|-----------|----------|
125
+ | `alpha` | 早期测试 | 不稳定 | 内部团队 |
126
+ | `beta` | 功能完备 | 基本稳定 | 早期采用者 |
127
+ | `rc` (release candidate) | 最终测试 | 稳定 | Beta 测试者 |
128
+
129
+ ### 示例
130
+
131
+ ```
132
+ 1.0.0-alpha.1 # First alpha release
133
+ 1.0.0-alpha.2 # Second alpha release
134
+ 1.0.0-beta.1 # First beta release
135
+ 1.0.0-beta.2 # Second beta release
136
+ 1.0.0-rc.1 # Release candidate 1
137
+ 1.0.0 # Stable release
138
+ ```
77
139
 
78
- | 策略 | 格式 | 优点 | 缺点 |
79
- |------|------|------|------|
80
- | URL 路径 | `/api/v1/users` | 清晰、易于路由 | URL 污染 |
81
- | 查询参数 | `/api/users?version=1` | 可选版本 | 缓存问题 |
82
- | 标头 | `Accept: application/vnd.api.v1+json` | URL 干净 | 不可见 |
140
+ ### 排序
83
141
 
84
- **推荐**: 大多数 API 使用 URL 路径版本化。
142
+ 预发布版本按字典序排序:
143
+ ```
144
+ 1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
145
+ ```
85
146
 
86
147
  ---
87
148
 
88
- ## 弃用时间线
149
+ ## 构建元数据
150
+
151
+ 格式: `MAJOR.MINOR.PATCH+BUILD`
152
+
153
+ ### 示例
89
154
 
90
155
  ```
91
- v1.0.0 - 功能引入
92
- v1.5.0 - 添加弃用警告(至少 N-1 版本)
93
- v2.0.0 - 移除功能(记录在迁移指南中)
156
+ 1.0.0+20250112 # Date-based build
157
+ 2.3.1+001 # Sequential build number
158
+ 3.0.0+sha.5114f85 # Git commit hash
159
+ 1.2.0-beta.1+exp.sha.5114f85 # Combined pre-release and build
94
160
  ```
95
161
 
96
- ### 弃用期限指南
162
+ ### 指南
163
+
164
+ - 构建元数据不应(SHOULD NOT)影响版本优先级
165
+ - 用于 CI/CD 跟踪
166
+ - 包含在构件中,但不用于版本比较
97
167
 
98
- | API 类型 | 最短弃用期限 |
99
- |----------|-------------|
100
- | 内部 API | 1 个次要版本 |
101
- | 合作伙伴 API | 2 个次要版本 + 3 个月 |
102
- | 公开 API | 2 个次要版本 + 6 个月 |
103
- | 关键基础设施 | 最少 1 年 |
168
+ > **关键:构建元数据绝不能(MUST NOT)用作部署鉴别器。**
169
+ > 由于工具在优先级与比较中会忽略 `+build`(见上文),仅在构建元数据上存在差异的两个构建(`1.2.3+abc` 与 `1.2.3+def`)**对版本比较工具而言是无法区分的**——回滚目标与 `semver` 比较会将它们视为同一个发布版本。使用 `+sha` 来区分行为不同的已部署构建属于绕过治理:版本将不再是用于 changelog / SBOM / 审计 / 回滚 / SLA / CVE 范围的关联键。交付的变更必须(MUST)获得真实的版本号递增或具有唯一且不可变的构件标识(参见下方的**部署版本标识**)——`+sha` **绝非**替代品。
104
170
 
105
171
  ---
106
172
 
107
- ## 向后兼容性检查清单
173
+ ## 部署版本标识
174
+
175
+ > 来源:一种常见的故障模式——多个行为不同的热修复构建部署在同一个 `X.Y.Z` 下,仅能通过 `+sha` 进行区分,导致回答“生产环境中运行的是哪个构建 / 修复 X 到底部署了没有?”变成了提交考古。
176
+
177
+ 本节规范**可部署单元**的标识——无论该单元对于项目而言是什么(容器镜像、tar 包、发布的软件包)。它是对下文[发布流程](#release-process)的补充,后者描述了一种具体的单机发布流程;此处的标识规则无论采用何种部署机制均适用。
178
+
179
+ ### 核心不变量
180
+
181
+ **每个不同的可部署构建产物必须携带唯一且不可变的版本标识(正式版本号 + 提交 sha)。**部署、*晋级*或*回滚***已有**产物绝不能改变其标识。
182
+
183
+ - **锚定于产物,而非部署动作。**新的构建(不同的源码或依赖项)⇒ 新版本。在不同环境之间流转(staging → prod,一次构建多次部署)、重新部署(蓝绿 / 金丝雀)或回滚的*同一个*构建属于**同一个**产物,并保持其标识——绝不能对其重新递增版本号。在晋级/回滚时重新递增版本号会导致版本号与实际运行的内容不符。(当回滚恢复先前的产物时,它恢复的是该产物的原始标识——而不是生成一个新的标识。)
184
+ - **绝不要在同一个 `X.Y.Z` 下部署两个不同的构建。**
185
+
186
+ ### 通过自动化强制执行,而非仅靠纪律
187
+
188
+ 该不变量应当通过自动化机制而非仅凭人工纪律来强制执行——上述故障模式*正是*因为遗漏了手动递增版本。以下任一方式均可满足要求:
108
189
 
109
- **不要破坏(不升级主版本号)**:
110
- - [ ] 移除公开 API 端点
111
- - [ ] 移除必填请求字段
112
- - [ ] 添加必填请求字段
113
- - [ ] 更改响应字段类型
114
- - [ ] 更改错误码含义
190
+ - **提交驱动的发布自动化**(`semantic-release` / `standard-version`,参见[自动化工具](#automation-tools)):在 CI 中根据提交历史推导并递增版本号,从而避免人工遗忘递增。
191
+ - **基于 Git 拓扑深度的版本化**(MinVer / Nerdbank.GitVersioning / GitVersion):版本号派生自 git 提交拓扑结构,因此从结构上杜绝了冲突的可能。推荐用于多语言 / .NET / JVM 项目(自动化工具一节主要针对 Node)——参见[自动化工具](#automation-tools)下的 git-height 小节。注意单一代码库(monorepo)和 squash-merge 工作流的注意事项。
192
+ - **CI 唯一性关卡**:如果计算出的版本已作为 git 标签存在或已存在于注册表中,则使发布失败。
115
193
 
116
- **安全变更(次要/补丁版本)**:
117
- - [ ] 添加可选请求字段
118
- - [ ] 添加新响应字段
119
- - [ ] 添加新端点
120
- - [ ] 添加新错误码
121
- - [ ] 改进错误消息
194
+ ### 不可变产物(交叉引用)
195
+
196
+ 唯一的*编号*是必要的,但并不充分——*产物*本身也必须是不可变且基于内容寻址的(例如,通过 digest 而非可变标签引用的容器镜像)。产物级别的具体要求——将部署固定到内容地址并禁止复用标签/版本——**属于 container-image-standards 的范畴**,并在其中加以规定;本标准仅要求版本标识本身保持唯一且不可变。
197
+
198
+ ### 构建标识可观测(要求)
199
+
200
+ **已部署的服务必须通过可查询的端点**(专用的 `/version`,或嵌入在 `/health` 中)**暴露其构建标识——`version + commit sha + build time`**,以便运维人员无需检查二进制文件或进行提交考古即可确切了解当前运行的内容。基本原理:手动版本号可能会发生冲突(如上所述),因此运维需要借由 `sha` 来区分在同一个 `X.Y.Z` 下发布的两个构建。
201
+
202
+ 要求:
203
+
204
+ - 暴露的 `sha` 必须与已部署产物的 sha 一致——它是**可验证的,而非自我报告的**(从构建中派生,切勿手动输入)。
205
+ - 端点应当进行访问控制;公开的构建标识端点会泄露内部提交标识。
206
+ - 发布后验证必须断言返回的 sha 等于已部署产物的 sha(参见[阶段 5:发布后验证](#phase-5-post-release-verification)),而不仅仅验证版本号是否正确。
207
+
208
+ 这是部署 / 可观测性关注点:具体的验证*机制*(如何抓取端点以及如何将断言接入关卡)**属于 deployment-standards 的范畴**(将在其中进行规定),而 **supply-chain-attestation** 已经提供出处追踪(provenance),作为“该产物源自该 sha”的密码学背书。
122
209
 
123
210
  ---
124
211
 
125
- ## 预发布版本
212
+ ## 初始开发阶段
126
213
 
127
- ### 预发布标识符
214
+ ### 0.x.x 版本
128
215
 
129
- | 标识符 | 用途 | 稳定性 | 受众 |
130
- |-------|------|-------|-----|
131
- | alpha | 早期测试 | 不稳定 | 内部团队 |
132
- | beta | 功能完成 | 基本稳定 | 早期采用者 |
133
- | rc | 最终测试 | 稳定 | Beta 测试者 |
216
+ ```
217
+ 0.1.0 # Initial development release
218
+ 0.2.0 # Add features
219
+ 0.3.0 # Add more features
220
+ ...
221
+ 1.0.0 # First stable release
222
+ ```
134
223
 
135
- ### 示例
224
+ **指南**:
225
+ - 主版本号为 0 表示处于开发阶段
226
+ - API 可能会频繁变动
227
+ - MINOR 版本中允许包含破坏性变更
228
+ - 当 API 趋于稳定时迁移至 1.0.0
229
+
230
+ ---
231
+
232
+ ## 版本生命周期
233
+
234
+ ### 发布周期示例
235
+
236
+ ```
237
+ Development Phase:
238
+ 0.1.0 → 0.2.0 → 0.9.0
239
+
240
+ First Stable Release:
241
+ 1.0.0
242
+
243
+ Feature Additions:
244
+ 1.0.0 → 1.1.0 → 1.2.0
245
+
246
+ Bug Fixes:
247
+ 1.2.0 → 1.2.1 → 1.2.2
248
+
249
+ Next Major Release:
250
+ 1.2.2 → 2.0.0-alpha.1 → 2.0.0-beta.1 → 2.0.0-rc.1 → 2.0.0
251
+ ```
252
+
253
+ ---
254
+
255
+ ## 变更日志集成
256
+
257
+ > **另请参阅**:有关全面的 CHANGELOG 编写指南、格式模板和示例,请参阅 [changelog-standards.md](changelog-standards.md)。
258
+
259
+ ### CHANGELOG.md 快速参考
260
+
261
+ CHANGELOG 文件应遵循 [Keep a Changelog](https://keepachangelog.com/) 格式,并包含以下类别:
262
+
263
+ | 类别 | 用途 |
264
+ |----------|---------|
265
+ | `Added` | 新功能 |
266
+ | `Changed` | 现有功能的变更 |
267
+ | `Deprecated` | 未来将移除的功能 |
268
+ | `Removed` | 已移除的功能 |
269
+ | `Fixed` | 错误修复 |
270
+ | `Security` | 安全漏洞补丁 |
271
+
272
+ **破坏性变更**:添加前缀 `**BREAKING**:` 以确保可见性。
273
+
274
+ 有关完整的格式模板和示例,请参阅 [changelog-standards.md](changelog-standards.md)。
275
+
276
+ ### 排除规则
136
277
 
278
+ CHANGELOG 不应记录以下类型的变更:
279
+
280
+ #### 1. 被 `.gitignore` 排除的目录
281
+
282
+ 从版本控制中排除的目录不会被提交,因此不应记录在 CHANGELOG 中。
283
+
284
+ **原则**:项目的 `.gitignore` 中列出的任何目录或文件都不应记录在 CHANGELOG 中。
285
+
286
+ **常见排除类别(示例)**:
287
+
288
+ | 类别 | 常见目录/文件 | 原因 |
289
+ |----------|-------------------------|--------|
290
+ | AI 协作工具 | `.claude/`, `.cursor/`, `.ai/` | 本地开发辅助工具,不在版本控制中 |
291
+ | 开发标准 | `.standards/` | 本地标准文档,不在版本控制中 |
292
+ | 构建输出 | `dist/`, `build/`, `out/` | 构建产物,不在版本控制中 |
293
+ | 大数据 | `data/`, `datasets/` | 数据文件,不在版本控制中 |
294
+
295
+ **验证方法**:
296
+
297
+ **macOS / Linux:**
298
+ ```bash
299
+ # Before generating CHANGELOG, check project's .gitignore exclusions
300
+ cat .gitignore | grep -E "^[^#*]" | head -20
137
301
  ```
138
- 1.0.0-alpha.1 # 第一个 alpha 版本
139
- 1.0.0-beta.1 # 第一个 beta 版本
140
- 1.0.0-rc.1 # 候选版本 1
141
- 1.0.0 # 稳定版本
302
+
303
+ **Windows PowerShell:**
304
+ ```powershell
305
+ # Before generating CHANGELOG, check project's .gitignore exclusions
306
+ Get-Content .gitignore | Where-Object { $_ -match "^[^#*]" } | Select-Object -First 20
142
307
  ```
143
308
 
309
+ **注意**:每个项目应根据自身的 `.gitignore` 设置确定排除项。上表仅为常见示例。
310
+
311
+ #### 2. 构建产物和临时文件
312
+
313
+ 以下类型的变更也不应记录:
314
+
315
+ - `bin/`、`obj/`、`Release/`、`Debug/` 及其他构建输出
316
+ - `*.log`、`*.tmp` 及其他临时文件
317
+ - `node_modules/`、`packages/` 及其他依赖目录
318
+
319
+ #### 3. 环境与配置文件(敏感数据)
320
+
321
+ 包含敏感数据的文件不应记录:
322
+
323
+ - `*.env`、`.env.*` 环境变量文件
324
+ - `*.local.json`、`*.local.yaml` 本地配置文件(例如 .NET 的 `appsettings.*.local.json`)
325
+ - `*.pem`、`*.key`、`*.p12` 密钥与证书文件
326
+ - `credentials.*`、`secrets.*` 凭据文件
327
+
328
+ ### 最佳实践
329
+
330
+ 生成 CHANGELOG 时,请遵循以下流程:
331
+
332
+ 1. **列出变更的提交**
333
+
334
+ **macOS / Linux / Windows (Git):**
335
+ ```bash
336
+ git log main..HEAD --oneline
337
+ ```
338
+
339
+ 2. **排除不需要记录的提交**
340
+ - 包含 "gitignore"、"version control" 或 "misc(version control)" 类型的提交
341
+ - 仅修改排除目录的提交
342
+
343
+ 3. **对记录进行分类**
344
+ - 仅记录将提交到仓库的实际代码或文档变更
345
+ - 确保所有记录的文件路径都存在于仓库中
346
+
347
+ 4. **验证记录**
348
+
349
+ **macOS / Linux:**
350
+ ```bash
351
+ # Verify that recorded paths exist in the repository
352
+ git ls-files | grep -E "path/to/file"
353
+ ```
354
+
355
+ **Windows PowerShell:**
356
+ ```powershell
357
+ # Verify that recorded paths exist in the repository
358
+ git ls-files | Select-String -Pattern "path/to/file"
359
+ ```
360
+
144
361
  ---
145
362
 
146
- ## 快速参考卡
363
+ ## 发布流程
147
364
 
148
- ### 版本递增
365
+ ### 概述
149
366
 
150
- | 做了什么? | 递增 |
151
- |-----------|-----|
152
- | 破坏性变更 | MAJOR |
153
- | 新功能 | MINOR |
154
- | 错误修复 | PATCH |
367
+ 完整的 Release 流程包含 5 个阶段:
155
368
 
156
- ### 版本格式
369
+ 1. **发布前诊断** - 强制要求
370
+ 2. **环境准备**
371
+ 3. **包生成**
372
+ 4. **部署执行**
373
+ 5. **发布后验证**
157
374
 
375
+ ### 阶段 1:发布前诊断 - 强制要求
376
+
377
+ **目的**:在生成升级包之前评估目标服务器的环境状态
378
+
379
+ **检查项**:
380
+ - 系统工具版本
381
+ - 所需驱动
382
+ - 磁盘空间
383
+ - 数据库连通性
384
+ - 应用程序版本
385
+ - 配置完整性
386
+
387
+ **通过条件**(质量门禁):
388
+ - 已安装所有必需工具
389
+ - 磁盘空间充足(至少 500MB)
390
+ - 数据库连接正常
391
+ - 无系统级错误
392
+
393
+ **失败处理**:
394
+ - 若诊断失败,执行环境准备(阶段 2)
395
+ - 修复后重新执行诊断
396
+ - 严禁跳过诊断直接进入打包阶段
397
+
398
+ ---
399
+
400
+ ### 阶段 2:环境准备
401
+
402
+ **目的**:根据诊断报告结果安装缺失的工具和驱动
403
+
404
+ **验证标准**:
405
+ - 所有诊断项均通过
406
+ - 数据库连接测试成功
407
+ - 验证工具显示无错误
408
+
409
+ ---
410
+
411
+ ### 阶段 3:包生成
412
+
413
+ **目的**:生成包含最新版本的升级包
414
+
415
+ **执行步骤**:
416
+ ```bash
417
+ # 1. Confirm current branch and version
418
+ git branch
419
+ git describe --tags
420
+
421
+ # 2. Generate upgrade package (using project-provided packaging script)
422
+ ./tools/generate-upgrade-package.sh -v v1.2.1 -o ./dist
423
+
424
+ # 3. Verify upgrade package contents
425
+ tar -tzf dist/upgrade-package-*.tar.gz | head -20
158
426
  ```
159
- MAJOR.MINOR.PATCH
160
- │ │ └── 错误修复
161
- │ └──────── 新功能
162
- └────────────── 破坏性变更
427
+
428
+ #### 升级包命名
429
+
430
+ **格式**:`{PROJECT}-upgrade-v{VERSION}-{DATE}.tar.gz`
431
+
432
+ | 元素 | 说明 | 示例 |
433
+ |------|------|------|
434
+ | `{PROJECT}` | 项目名称(替换为实际项目名称) | `my-app`、`api-server` |
435
+ | `{VERSION}` | 版本号(与 Git tag 一致) | `1.2.1`、`2.0.0-beta.1` |
436
+ | `{DATE}` | 打包日期(YYYYMMDD) | `20251128` |
437
+
438
+ **示例**(将 `{PROJECT}` 替换为您的项目名称):
439
+ ```
440
+ {PROJECT}-upgrade-v1.2.1-20251127.tar.gz
441
+ {PROJECT}-upgrade-v2.0.0-beta.1-20251201.tar.gz
442
+ ```
443
+
444
+ ---
445
+
446
+ ### 阶段 4:部署执行
447
+
448
+ **目的**:在目标服务器上执行升级
449
+
450
+ **执行步骤**:
451
+ ```bash
452
+ # 1. Upload upgrade package to target server
453
+ scp upgrade-package-*.tar.gz user@target:/tmp/
454
+
455
+ # 2. Extract upgrade package
456
+ cd /tmp
457
+ tar -xzf upgrade-package-*.tar.gz
458
+ cd upgrade-package-*/
459
+
460
+ # 3. Dry-run test (strongly recommended)
461
+ sudo ./upgrade.sh --dry-run
462
+
463
+ # 4. Actual upgrade
464
+ sudo ./upgrade.sh
163
465
  ```
164
466
 
467
+ **部署验证**:
468
+ - 备份已创建
469
+ - 服务成功停止
470
+ - 文件成功部署
471
+ - Schema 迁移成功(如适用)
472
+ - 服务成功启动
473
+
474
+ ---
475
+
476
+ ### 阶段 5:发布后验证
477
+
478
+ **目的**:确认升级成功且应用程序正常运行
479
+
480
+ **检查项**:
481
+ ```bash
482
+ # 1. Check service status
483
+ systemctl status your-service
484
+
485
+ # 2. Check application build identity (version + commit sha + build time)
486
+ # Assert the returned sha matches the deployed artifact's sha — not just the version.
487
+ curl http://localhost:PORT/version # or /health, if build identity is embedded there
488
+ # Expected: {"version": "1.2.1", "sha": "<deployed-artifact-sha>", "buildTime": "..."}
489
+
490
+ # 3. Check logs for no errors
491
+ tail -100 /path/to/app.log | grep -i error
492
+ ```
493
+
494
+ **成功标准**:
495
+ - 服务运行正常
496
+ - `/version`(或 `/health`)返回正确的版本号**以及**与已部署制品匹配的
497
+ commit sha——仅版本匹配是不够的,因为两个构建可以共享同一个
498
+ `X.Y.Z`(参见 [Build identity is observable](#build-identity-is-observable-requirement))
499
+ - 日志中无致命错误
500
+ - 功能验证通过
501
+
502
+ ---
503
+
504
+ ### 发布检查清单
505
+
506
+ **发布前(诊断与准备)**:
507
+ - [ ] 执行服务器诊断
508
+ - [ ] 诊断报告通过所有检查项
509
+ - [ ] 环境准备已完成(如有缺失)
510
+ - [ ] 环境验证工具已通过
511
+
512
+ **发布(打包与部署)**:
513
+ - [ ] 升级包生成成功
514
+ - [ ] 升级包内容验证通过
515
+ - [ ] 空运行(Dry-run)测试无异常
516
+ - [ ] 备份计划已准备
517
+ - [ ] 回滚计划已准备
518
+
519
+ **发布后(验证与监控)**:
520
+ - [ ] 服务启动成功
521
+ - [ ] 版本号正确
522
+ - [ ] 功能验证通过
523
+ - [ ] 日志无异常
524
+
525
+ ---
526
+
527
+ ### 质量门禁
528
+
529
+ 以下检查点**必须通过**,否则无法进入下一阶段:
530
+
531
+ | 阶段 | 门禁 | 失败处理 |
532
+ |------|------|----------|
533
+ | **诊断** | 诊断报告无错误 | 环境准备 |
534
+ | **准备** | 验证工具通过 | 修复并重新验证 |
535
+ | **打包** | 升级包结构完整 | 重新打包 |
536
+ | **部署** | 空运行(Dry-run)无异常 | 分析日志并修复 |
537
+ | **验证** | 服务运行正常 | 回滚 |
538
+
539
+ ---
540
+
541
+ ### 回滚计划
542
+
543
+ 如果升级失败,执行以下回滚步骤:
544
+
545
+ ```bash
546
+ # 1. Stop service
547
+ sudo systemctl stop your-service
548
+
549
+ # 2. Restore backup
550
+ BACKUP_PATH="/path/to/backup-$(date +%Y%m%d)"
551
+ sudo rm -rf /path/to/app
552
+ sudo mv "$BACKUP_PATH" /path/to/app
553
+
554
+ # 3. Restart service
555
+ sudo systemctl start your-service
556
+
557
+ # 4. Verify rollback success
558
+ sudo systemctl status your-service
559
+ ```
560
+
561
+ ---
562
+
563
+ ### 合规性
564
+
565
+ **强制要求**:
566
+ - 严禁跳过诊断阶段
567
+ - 严禁跳过空运行(Dry-run)测试
568
+ - 必须保留诊断报告
569
+ - 必须准备回滚计划
570
+
571
+ **审计追踪**:
572
+ - 所有 Release 文档至少保留 12 个月
573
+ - 诊断报告关联至 Git Tag
574
+ - 完整保留升级日志
575
+
576
+ ---
577
+
578
+ ## Git 中的版本标签
579
+
580
+ ### 创建标签
581
+
582
+ ```bash
583
+ # Annotated tag (recommended)
584
+ git tag -a v1.2.0 -m "Release version 1.2.0"
585
+
586
+ # Tag with detailed message
587
+ git tag -a v2.0.0 -m "Release version 2.0.0
588
+
589
+ Major changes:
590
+ - New authentication system
591
+ - Redesigned API
592
+ - Performance improvements"
593
+
594
+ # Push tag to remote
595
+ git push origin v1.2.0
596
+
597
+ # Push all tags
598
+ git push origin --tags
599
+ ```
600
+
601
+ ### 标签命名规范
602
+
603
+ ```
604
+ v1.0.0 ✅ Recommended (with 'v' prefix)
605
+ 1.0.0 ✅ Acceptable (without 'v')
606
+ version-1.0.0 ❌ Avoid (too verbose)
607
+ 1.0 ❌ Avoid (incomplete version)
608
+ ```
609
+
610
+ ---
611
+
612
+ ## 自动化工具
613
+
614
+ ### standard-version (Node.js)
615
+
616
+ ```bash
617
+ # Install
618
+ npm install --save-dev standard-version
619
+
620
+ # Add to package.json
621
+ {
622
+ "scripts": {
623
+ "release": "standard-version"
624
+ }
625
+ }
626
+
627
+ # Create release
628
+ npm run release # Auto-increment based on commits
629
+ npm run release -- --release-as minor # Force minor version
630
+ npm run release -- --release-as 2.0.0 # Specific version
631
+ ```
632
+
633
+ ### semantic-release (Node.js)
634
+
635
+ ```bash
636
+ # Install
637
+ npm install --save-dev semantic-release
638
+
639
+ # Configure in .releaserc.json
640
+ {
641
+ "branches": ["main"],
642
+ "plugins": [
643
+ "@semantic-release/commit-analyzer",
644
+ "@semantic-release/release-notes-generator",
645
+ "@semantic-release/changelog",
646
+ "@semantic-release/npm",
647
+ "@semantic-release/git",
648
+ "@semantic-release/github"
649
+ ]
650
+ }
651
+ ```
652
+
653
+ ### 基于 Git 高度推导的版本控制(多语言:.NET / JVM / 多语言)
654
+
655
+ 上述工具以 Node/npm 为中心。对于 **.NET、JVM 或多语言项目**,更推荐**基于 Git 高度推导的版本控制**,其版本是根据 Git 标签图谱加上自上一个标签以来的提交数量(“提交高度”,commit height)自动计算得出,而不是存储在手动编辑的文件中。由于版本是 Git 历史的确定性函数,**两个不同的构建绝不会在同一版本号上发生冲突**,且不会遗忘任何手动版本递增步骤——这正是它能够从结构上而非依靠自律来满足[部署版本唯一性](#deployment-version-identity)的原因。
656
+
657
+ | 工具 | 生态系统 | 说明 |
658
+ |------|-----------|-------|
659
+ | **MinVer** | .NET / MSBuild | 从最近的 Git 标签加上提交高度推导版本;无需配置文件,无需集成构建服务器 |
660
+ | **Nerdbank.GitVersioning** (nbgv) | .NET(也支持 Node 等) | 读取 `version.json`;将版本 + Git 高度 + 提交 ID 写入程序集和软件包中 |
661
+ | **GitVersion** | 多语言(.NET,外加与语言无关的 CLI) | 由分支和标签拓扑驱动的可配置版本控制模式(例如 Mainline、持续交付 / 持续部署) |
662
+
663
+ **何时使用何种工具:**
664
+
665
+ - **Node / npm 项目** → 提交驱动的自动化(见上文 `semantic-release` / `standard-version`):版本递增由约定式提交(Conventional Commits)推导而来。
666
+ - **多语言 / .NET / JVM 项目** → 基于 Git 高度推导的工具(MinVer / Nerdbank.GitVersioning / GitVersion):版本由 Git 标签 + 提交高度推导而来。
667
+
668
+ 这两类工具都消除了容易被遗忘的手动版本递增。**注意事项:** 在 monorepo(单一代码库)中,单个全仓库范围的提交高度可能无法清晰地映射到各个软件包的版本上,且 squash-merge(压缩合并)工作流程会改变提交高度——请根据你的打标签规范验证推导出的版本。
669
+
670
+ ---
671
+
672
+ ## 依赖版本范围
673
+
674
+ ### npm (package.json)
675
+
676
+ ```json
677
+ {
678
+ "dependencies": {
679
+ "exact": "1.2.3", // Exact version
680
+ "patch": "~1.2.3", // >=1.2.3 <1.3.0
681
+ "minor": "^1.2.3", // >=1.2.3 <2.0.0
682
+ "range": ">=1.2.3 <2.0.0", // Explicit range
683
+ "latest": "*" // ❌ Avoid - any version
684
+ }
685
+ }
686
+ ```
687
+
688
+ **建议**:
689
+ - 大多数依赖项使用 `^`(次要版本更新)
690
+ - 保守更新使用 `~`(仅补丁更新)
691
+ - 关键依赖项使用精确版本
692
+ - 绝不要在生产环境中使用 `*`
693
+
694
+ ---
695
+
696
+ ### .NET (csproj)
697
+
698
+ ```xml
699
+ <ItemGroup>
700
+ <!-- Exact version -->
701
+ <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
702
+
703
+ <!-- Minimum version -->
704
+ <PackageReference Include="Microsoft.Extensions.Logging" Version="[8.0.0,)" />
705
+
706
+ <!-- Version range -->
707
+ <PackageReference Include="AutoMapper" Version="[12.0.0,13.0.0)" />
708
+ </ItemGroup>
709
+ ```
710
+
711
+ ---
712
+
713
+ ## 破坏性变更与弃用
714
+
715
+ 破坏性变更是驱动 **MAJOR** 版本递增的因素(参见[递增规则](#incrementing-rules))——这就是 SemVer 向使用者传达不兼容变更的方式。演进和退役 API 的*契约层级*细节由负责这些关注点的标准所拥有,因此每条规则都有单一事实来源:
716
+
717
+ - **API 版本化策略、向后兼容性检查清单(何为破坏性变更)、代码中的弃用注解以及迁移指南模板** → [API 设计标准](api-design-standards.md#api-versioning-strategies)
718
+ - **弃用生命周期、按 API 级别的最短通知期限、`Sunset` / `Deprecation` 标头以及使用者通知** → [弃用与下线标准](deprecation-standards.md#api-deprecation)
719
+
720
+ 本标准仅保留版本编号规则:不兼容的变更必须作为 MAJOR 升级发布,且弃用应在执行移除的 MAJOR 之前的某个 MINOR 版本中公布(参见 [MAJOR 版本](#major-version-x00)指南)。
721
+
722
+ ---
723
+
724
+ ## 项目配置
725
+
726
+ ### 在 README.md 中记录
727
+
728
+ ```markdown
729
+ ## Versioning
730
+
731
+ This project follows [Semantic Versioning 2.0.0](https://semver.org/).
732
+
733
+ ### Version Format
734
+ `MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`
735
+
736
+ ### Release Cycle
737
+ - **Major releases**: Annually (breaking changes)
738
+ - **Minor releases**: Quarterly (new features)
739
+ - **Patch releases**: As needed (bug fixes)
740
+
741
+ ### Support Policy
742
+ - Latest major version: Full support
743
+ - Previous major version: Security fixes only (1 year)
744
+ - Older versions: No support
745
+
746
+ ### Changelog
747
+ See [CHANGELOG.md](CHANGELOG.md) for release history.
748
+ ```
749
+
750
+ ---
751
+
752
+ ## 版本比较
753
+
754
+ ### 优先级规则
755
+
756
+ ```
757
+ 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1
758
+
759
+ 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0
760
+
761
+ 1.0.0 < 1.0.0+001 (build metadata ignored in precedence)
762
+ ```
763
+
764
+ ### 代码中的比较
765
+
766
+ ```javascript
767
+ // JavaScript (using semver package)
768
+ const semver = require('semver');
769
+
770
+ semver.gt('1.2.3', '1.2.2'); // true
771
+ semver.satisfies('1.2.3', '^1.0.0'); // true
772
+ semver.major('2.3.1'); // 2
773
+ ```
774
+
775
+ ---
776
+
777
+ ## 常见问题
778
+
779
+ ### Q: 我应该何时发布 1.0.0?
780
+
781
+ **A**: 当 API 稳定且准备好承诺向后兼容时。
782
+
783
+ ---
784
+
785
+ ### Q: 内部破坏性变更是否需要递增 MAJOR?
786
+
787
+ **A**: 不需要,仅在公开 API 变更时递增。内部重构属于 PATCH 或 MINOR。
788
+
789
+ ---
790
+
791
+ ### Q: 我可以跳过版本号吗?
792
+
793
+ **A**: 可以,但不推荐。为了清晰起见,请使用连续的版本编号。
794
+
795
+ ---
796
+
797
+ ### Q: 库与应用程序该如何进行版本控制?
798
+
799
+ **A**:
800
+ - **库**:严格遵循 SemVer(API 至关重要)
801
+ - **应用程序**:可以更加灵活(用户体验至关重要)
802
+
165
803
  ---
166
804
 
167
805
  ## 相关标准
168
806
 
169
807
  - [变更日志标准](changelog-standards.md)
170
- - [Git 工作流程](git-workflow.md)
808
+ - [Git 工作流标准](git-workflow.md)
171
809
  - [提交消息指南](commit-message-guide.md)
810
+ - [API 设计标准](api-design-standards.md) — API 版本化策略、向后兼容性规则、迁移指南
811
+ - [弃用与下线标准](deprecation-standards.md) — 弃用生命周期与最短通知期限
812
+
813
+ ---
814
+
815
+ ## 版本历史
816
+
817
+ | 版本 | 日期 | 变更 |
818
+ |---------|------|---------|
819
+ | 1.5.0 | 2026-07-01 | 新增:在自动化工具中为多语言 / .NET / JVM 项目添加了基于 git-height 推导的版本控制工具(MinVer / Nerdbank.GitVersioning / GitVersion)(UDS #138 R2);将“构建标识可观测”提升为一项要求——已部署的服务必须通过可查询端点暴露 `version + commit sha + build time`——并在 Phase 5 发布后验证中添加了 commit-sha + build-time 断言(UDS #138 R3) |
820
+ | 1.4.0 | 2026-06-24 | 移出(至单一来源):API 版本化策略(去重)、弃用时间线 + 各层级期限、向后兼容性检查清单,以及迁移指南模板——现归属于 api-design-standards / deprecation-standards;版本控制标准对其进行交叉引用(XSPEC-298 R8, UDS #126) |
821
+ | 1.3.0 | 2026-06-23 | 新增:部署版本标识章节;构建元数据作为部署区分标识的注意事项(源自 UDS #138) |
822
+ | 1.2.0 | 2025-12-30 | 新增:API 版本化策略、弃用时间线、向后兼容性检查清单 |
823
+ | 1.1.3 | 2025-12-24 | 新增:相关标准章节 |
824
+ | 1.1.2 | 2025-12-11 | 改进:升级包命名示例,使用通用占位符代替硬编码的项目名称 |
825
+ | 1.1.1 | 2025-12-04 | 重构:CHANGELOG 排除规则以使其更通用(移除了特定于项目的目录) |
826
+ | 1.1.0 | 2025-12-04 | 新增:CHANGELOG 排除规则、发布流程章节 |
827
+ | 1.0.0 | 2025-11-12 | 初始版本控制标准 |
828
+
829
+ ---
830
+
831
+ ## 参考资料
832
+
833
+ - [Semantic Versioning 2.0.0](https://semver.org/)
834
+ - [Keep a Changelog](https://keepachangelog.com/)
835
+ - [Calendar Versioning](https://calver.org/)(备用方案)
172
836
 
173
837
  ---
174
838