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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +6 -0
  2. package/bin/uds.js +2 -0
  3. package/bundled/ai/standards/translation-lifecycle-standards.ai.yaml +145 -0
  4. package/bundled/core/translation-lifecycle-standards.md +162 -0
  5. package/bundled/locales/zh-CN/CHANGELOG.md +32 -3
  6. package/bundled/locales/zh-CN/README.md +1 -1
  7. package/bundled/locales/zh-CN/core/anti-hallucination.md +22 -3
  8. package/bundled/locales/zh-CN/core/anti-sycophancy-prompting.md +192 -0
  9. package/bundled/locales/zh-CN/core/capability-declaration.md +123 -0
  10. package/bundled/locales/zh-CN/core/circuit-breaker.md +106 -0
  11. package/bundled/locales/zh-CN/core/dual-phase-output.md +103 -0
  12. package/bundled/locales/zh-CN/core/failure-source-taxonomy.md +99 -0
  13. package/bundled/locales/zh-CN/core/frontend-design-standards.md +289 -0
  14. package/bundled/locales/zh-CN/core/health-check-standards.md +144 -0
  15. package/bundled/locales/zh-CN/core/immutability-first.md +96 -0
  16. package/bundled/locales/zh-CN/core/packaging-standards.md +224 -0
  17. package/bundled/locales/zh-CN/core/recovery-recipe-registry.md +146 -0
  18. package/bundled/locales/zh-CN/core/retry-standards.md +131 -0
  19. package/bundled/locales/zh-CN/core/security-decision.md +104 -0
  20. package/bundled/locales/zh-CN/core/skill-standard-alignment-check.md +112 -0
  21. package/bundled/locales/zh-CN/core/standard-admission-criteria.md +104 -0
  22. package/bundled/locales/zh-CN/core/standard-lifecycle-management.md +116 -0
  23. package/bundled/locales/zh-CN/core/timeout-standards.md +117 -0
  24. package/bundled/locales/zh-CN/core/token-budget.md +108 -0
  25. package/bundled/locales/zh-CN/core/translation-lifecycle-standards.md +159 -0
  26. package/bundled/locales/zh-TW/CHANGELOG.md +32 -3
  27. package/bundled/locales/zh-TW/README.md +1 -1
  28. package/bundled/locales/zh-TW/core/anti-sycophancy-prompting.md +8 -0
  29. package/bundled/locales/zh-TW/core/capability-declaration.md +111 -0
  30. package/bundled/locales/zh-TW/core/circuit-breaker.md +111 -0
  31. package/bundled/locales/zh-TW/core/dual-phase-output.md +132 -0
  32. package/bundled/locales/zh-TW/core/failure-source-taxonomy.md +146 -0
  33. package/bundled/locales/zh-TW/core/frontend-design-standards.md +460 -0
  34. package/bundled/locales/zh-TW/core/health-check-standards.md +144 -0
  35. package/bundled/locales/zh-TW/core/immutability-first.md +159 -0
  36. package/bundled/locales/zh-TW/core/recovery-recipe-registry.md +146 -0
  37. package/bundled/locales/zh-TW/core/retry-standards.md +140 -0
  38. package/bundled/locales/zh-TW/core/security-decision.md +120 -0
  39. package/bundled/locales/zh-TW/core/skill-standard-alignment-check.md +112 -0
  40. package/bundled/locales/zh-TW/core/standard-admission-criteria.md +104 -0
  41. package/bundled/locales/zh-TW/core/standard-lifecycle-management.md +116 -0
  42. package/bundled/locales/zh-TW/core/timeout-standards.md +117 -0
  43. package/bundled/locales/zh-TW/core/token-budget.md +143 -0
  44. package/bundled/locales/zh-TW/core/translation-lifecycle-standards.md +159 -0
  45. package/package.json +2 -1
  46. package/src/commands/check.js +6 -0
  47. package/src/commands/init.js +6 -0
  48. package/src/commands/update.js +6 -0
  49. package/src/utils/detect-self-adoption.js +173 -0
  50. package/standards-registry.json +15 -4
package/README.md CHANGED
@@ -349,6 +349,12 @@ npm install
349
349
  npm link
350
350
  ```
351
351
 
352
+ ### Type Checking | 型別檢查
353
+
354
+ No `typecheck` script is provided — this CLI is pure ESM JavaScript (`.js` / `.mjs`), no TypeScript sources, and no `tsconfig.json`. Static analysis is handled by `npm run lint` (ESLint). Tracked under BUG-A04 (XSPEC-073).
355
+
356
+ 未提供 `typecheck` 腳本 —— 本 CLI 為純 ESM JavaScript(`.js` / `.mjs`),無 TypeScript 原始碼亦無 `tsconfig.json`。靜態分析由 `npm run lint`(ESLint)負責。追蹤於 BUG-A04(XSPEC-073)。
357
+
352
358
  ### Git Hooks | Git 鉤子
353
359
 
354
360
  Git hooks work through Git Bash, which is included with Git for Windows. No additional configuration needed.
package/bin/uds.js CHANGED
@@ -128,6 +128,7 @@ program
128
128
  .option('--content-layout <layout>', 'Content layout (flat, layered) [default: flat]')
129
129
  .option('-y, --yes', 'Use defaults, skip interactive prompts')
130
130
  .option('-E, --experimental', 'Enable experimental features (methodology)')
131
+ .option('--force', 'Bypass UDS source-repo self-adoption guard (DEC-044 / XSPEC-071)')
131
132
  .action(initCommand);
132
133
 
133
134
  program
@@ -173,6 +174,7 @@ program
173
174
  .option('--ci', 'CI mode: disable interactive prompts and set exit code on issues')
174
175
  .option('--migrate', 'Migrate legacy manifest to hash-based tracking')
175
176
  .option('--offline', 'Skip npm registry check for CLI updates')
177
+ .option('--force', 'Bypass UDS source-repo self-adoption guard (DEC-044 / XSPEC-071)')
176
178
  .action(checkCommand);
177
179
 
178
180
  program
@@ -0,0 +1,145 @@
1
+ # Translation Lifecycle Standards - AI Optimized
2
+ # Source: core/translation-lifecycle-standards.md
3
+
4
+ id: translation-lifecycle-standards
5
+ meta:
6
+ version: "1.0.0"
7
+ updated: "2026-04-20"
8
+ status: trial
9
+ since: "2026-04-20"
10
+ expires: "2026-10-20"
11
+ source: core/translation-lifecycle-standards.md
12
+ description: >
13
+ MISSING vs OUTDATED distinction, semver-aware severity (PATCH/MINOR/MAJOR),
14
+ and automation integration for translation sync in multi-locale projects.
15
+ scope: universal
16
+ parent: documentation-lifecycle
17
+
18
+ severity_levels:
19
+ MISSING:
20
+ condition: Translation file does not exist
21
+ exit_code: 1
22
+ label: "[MISSING]"
23
+ action: Create before release
24
+ MAJOR:
25
+ condition: source major version ahead of translation source_version major
26
+ exit_code: 1
27
+ label: "[MAJOR]"
28
+ action: Update before stable release (blocker)
29
+ MINOR:
30
+ condition: source minor version ahead (same major)
31
+ exit_code: 0
32
+ label: "[MINOR]"
33
+ action: Update before next release (advisory)
34
+ PATCH:
35
+ condition: source patch version ahead (same major.minor)
36
+ exit_code: 0
37
+ label: "[PATCH]"
38
+ action: Update when convenient (advisory)
39
+ CURRENT:
40
+ condition: source_version == current source version
41
+ exit_code: 0
42
+ label: "[CURRENT]"
43
+ action: None
44
+
45
+ frontmatter_schema:
46
+ required:
47
+ - source # relative path to source file
48
+ - source_version # source version at last sync (semver)
49
+ - translation_version # translation's own version
50
+ - last_synced # YYYY-MM-DD
51
+ - status # current | outdated | draft
52
+
53
+ trigger_conditions:
54
+ - event: new_standard_added
55
+ action: Create translation in ALL supported locales
56
+ severity: MISSING (blocker if absent)
57
+ - event: standard_patch_bump
58
+ action: Update frontmatter source_version + last_synced
59
+ severity: PATCH (advisory)
60
+ - event: standard_minor_bump
61
+ action: Translate new content + update frontmatter
62
+ severity: MINOR (advisory, before next release)
63
+ - event: standard_major_bump
64
+ action: Full retranslation + update frontmatter
65
+ severity: MAJOR (blocker, before current release)
66
+
67
+ automation:
68
+ pre_commit_hook:
69
+ file: .githooks/pre-commit
70
+ trigger: core/*.md files staged
71
+ behavior: warn on OUTDATED, never block commit
72
+ setup: ./scripts/install-hooks.sh
73
+ release_gate:
74
+ command: bash scripts/check-translation-sync.sh
75
+ exit_1_conditions: [MISSING, MAJOR]
76
+ exit_0_conditions: [MINOR, PATCH, CURRENT]
77
+ bump_version_integration:
78
+ command: runs check-translation-sync.sh after version files updated
79
+ purpose: immediate feedback on translation health at bump time
80
+
81
+ rules:
82
+ - id: missing-is-blocker
83
+ trigger: running release gate check
84
+ instruction: >
85
+ Any translation file that does not exist is a release blocker.
86
+ The release gate must exit 1 if MISSING count > 0.
87
+ priority: required
88
+
89
+ - id: major-gap-is-blocker
90
+ trigger: running release gate check
91
+ instruction: >
92
+ If a translation's source_version MAJOR is behind the current source MAJOR,
93
+ the translation may be fundamentally incorrect. Exit 1.
94
+ priority: required
95
+
96
+ - id: minor-patch-advisory
97
+ trigger: running release gate check
98
+ instruction: >
99
+ MINOR and PATCH version gaps are advisory. Show warnings but exit 0.
100
+ Users can still read the translation; it is slightly stale, not wrong.
101
+ priority: required
102
+
103
+ - id: frontmatter-required
104
+ trigger: creating or updating a translation file
105
+ instruction: >
106
+ Every translation file MUST start with YAML frontmatter containing:
107
+ source, source_version, translation_version, last_synced, status.
108
+ Files without frontmatter are flagged as MISSING_FRONTMATTER.
109
+ priority: required
110
+
111
+ - id: update-on-source-change
112
+ trigger: modifying a source standard in core/
113
+ instruction: >
114
+ After modifying a core standard, check if translations need updating.
115
+ At minimum update frontmatter source_version + last_synced for PATCH changes.
116
+ For MINOR/MAJOR changes, update translated content too.
117
+ priority: recommended
118
+
119
+ scenarios:
120
+ - id: new-standard
121
+ given: A new standard is added to core/ with no translations
122
+ when: check-translation-sync.sh runs
123
+ then: Reports [MISSING] for each locale; exits 1
124
+ error_code: TRANS-001
125
+
126
+ - id: patch-bump
127
+ given: Source goes from 1.0.0 to 1.0.1; translation source_version=1.0.0
128
+ when: check-translation-sync.sh runs
129
+ then: Reports [PATCH] advisory; exits 0
130
+
131
+ - id: major-gap
132
+ given: Source is at 2.0.0; translation source_version=1.5.0
133
+ when: check-translation-sync.sh runs
134
+ then: Reports [MAJOR] blocker; exits 1
135
+ error_code: TRANS-002
136
+
137
+ integration_points:
138
+ - system: check-translation-sync.sh
139
+ role: primary automation; enforces severity levels
140
+ - system: .githooks/pre-commit
141
+ role: commit-time reminder when core/ files staged
142
+ - system: bump-version.sh
143
+ role: release-time advisory snapshot
144
+ - system: pre-release-check.sh
145
+ role: final gate before npm publish (calls check-translation-sync.sh)
@@ -0,0 +1,162 @@
1
+ # Translation Lifecycle Standards
2
+
3
+ > **Language**: English | [繁體中文](../locales/zh-TW/core/translation-lifecycle-standards.md)
4
+
5
+ **Version**: 1.0.0
6
+ **Last Updated**: 2026-04-20
7
+ **Status**: Trial (expires 2026-10-20)
8
+ **Applicability**: All projects with multi-language documentation
9
+ **Scope**: universal
10
+ **Source**: Derived from UDS BUG-A06 post-mortem (2026-04-20)
11
+ **Parent Standard**: [documentation-lifecycle](documentation-lifecycle.md)
12
+
13
+ ---
14
+
15
+ ## Purpose
16
+
17
+ Translation lifecycle standards: MISSING vs OUTDATED distinction, semver-aware severity classification, and automation integration (pre-commit hook, release gate).
18
+
19
+ The `documentation-lifecycle` standard mentions translation sync as a release-gate check, but does not define how to classify or respond to different degrees of drift. This standard fills that gap: a translation that is absent is fundamentally different from one that is slightly stale, and a major-version gap is fundamentally different from a patch bump. Without this distinction, teams either over-block (failing on any staleness) or under-block (ignoring all staleness until it becomes a user-visible defect).
20
+
21
+ **Evidence (BUG-A06 post-mortem)**:
22
+ 1. UDS accumulated 32 missing translations over 3 months of adding new standards without a MISSING gate — only discovered during a Q2 audit.
23
+ 2. `anti-hallucination.md` zh-CN was at 1.5.0 while the source shipped 1.5.1 — a new Agent Epistemic Calibration framework section was completely absent in the zh-CN edition, invisible to users.
24
+
25
+ ---
26
+
27
+ ## Core Rules
28
+
29
+ - `MISSING` (translation file does not exist) is always a release blocker — `exit 1`
30
+ - `MAJOR` version gap (source X vs translation x where X > x) is a release blocker — `exit 1`
31
+ - `MINOR` version gap is advisory — warn prominently, do not block
32
+ - `PATCH` version gap is advisory — warn softly, do not block
33
+ - Severity is determined by semver comparison of `source_version` in translation frontmatter vs current source file version
34
+ - Every translation file MUST have YAML frontmatter with `source`, `source_version`, `translation_version`, `last_synced`, `status`
35
+ - When a source standard is modified, the translation's `source_version` becomes stale immediately — this drift is detectable at commit time via pre-commit hook
36
+
37
+ ---
38
+
39
+ ## Severity Classification
40
+
41
+ | Level | Condition | Exit Code | Action |
42
+ |-------|-----------|-----------|--------|
43
+ | `MISSING` | Translation file does not exist | 1 | Create before release |
44
+ | `MAJOR` | source MAJOR > translation MAJOR | 1 | Update before stable release |
45
+ | `MINOR` | source MINOR > translation MINOR | 0 | Update before next release (advisory) |
46
+ | `PATCH` | source PATCH > translation PATCH | 0 | Update when convenient (advisory) |
47
+ | `CURRENT` | source_version == translation source_version | 0 | No action needed |
48
+
49
+ ### Semver Diff Formula
50
+
51
+ ```
52
+ diff_level = compare(
53
+ strip_prerelease(current_source_version),
54
+ strip_prerelease(translation.source_version)
55
+ )
56
+
57
+ where: MAJOR if maj differs, MINOR if min differs, else PATCH
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Trigger Conditions
63
+
64
+ | Event | Required Action |
65
+ |-------|----------------|
66
+ | New standard added to `core/` | Create translation in all supported locales (MISSING check blocks release) |
67
+ | Standard version bumped (PATCH) | Update translation's `source_version` + `last_synced` when convenient |
68
+ | Standard version bumped (MINOR) | Update translation content + frontmatter before next release |
69
+ | Standard version bumped (MAJOR) | Update translation content + frontmatter before current release (blocker) |
70
+ | Translation file manually updated | Bump `translation_version` + `last_synced` in frontmatter |
71
+
72
+ ---
73
+
74
+ ## Translation Frontmatter Protocol
75
+
76
+ Every translation file MUST begin with:
77
+
78
+ ```yaml
79
+ ---
80
+ source: ../../../core/<filename>.md # relative path to source
81
+ source_version: <X.Y.Z> # source version at last sync
82
+ translation_version: <X.Y.Z> # translation's own version
83
+ last_synced: <YYYY-MM-DD> # date of last sync
84
+ status: current | outdated | draft # human-readable status
85
+ ---
86
+ ```
87
+
88
+ When updating a translation after a source change:
89
+ 1. Translate the new/changed content
90
+ 2. Set `source_version` = new source version
91
+ 3. Set `translation_version` = same as `source_version` (or bump independently)
92
+ 4. Set `last_synced` = today's date
93
+ 5. Set `status: current`
94
+
95
+ ---
96
+
97
+ ## Automation Integration
98
+
99
+ ### Pre-Commit Hook
100
+
101
+ When `core/*.md` files are staged, the pre-commit hook runs `check-translation-sync.sh` and shows OUTDATED warnings. The hook **never blocks** the commit (blocking at commit time is too disruptive) — it is a reminder only.
102
+
103
+ Setup: `./scripts/install-hooks.sh` (one-time, after clone)
104
+
105
+ ### Release Gate (`check-translation-sync.sh`)
106
+
107
+ Run before `npm publish` or as part of `pre-release-check.sh`:
108
+
109
+ ```bash
110
+ bash scripts/check-translation-sync.sh
111
+ # exit 1 if MISSING or MAJOR gap found
112
+ # exit 0 if only MINOR/PATCH gaps (with advisory output)
113
+ ```
114
+
115
+ ### Version Bump Integration (`bump-version.sh`)
116
+
117
+ `bump-version.sh` automatically runs `check-translation-sync.sh` after version files are updated, showing the translation health snapshot at the moment of bump — giving the author immediate feedback on what needs updating before publish.
118
+
119
+ ---
120
+
121
+ ## Scenarios
122
+
123
+ **Scenario 1 — Standard patch bump (1.0.0 → 1.0.1)**
124
+ - Translation `source_version: 1.0.0`, source now at `1.0.1`
125
+ - Severity: `PATCH` — advisory, exit 0
126
+ - Action: Update at next opportunity, no release block
127
+
128
+ **Scenario 2 — Standard minor bump with new section (1.0.0 → 1.1.0)**
129
+ - Translation `source_version: 1.0.0`, source now at `1.1.0`
130
+ - Severity: `MINOR` — advisory, exit 0
131
+ - Action: Update before next release; zh-CN users missing new content
132
+
133
+ **Scenario 3 — Standard major rewrite (1.x.x → 2.0.0)**
134
+ - Translation `source_version: 1.5.0`, source now at `2.0.0`
135
+ - Severity: `MAJOR` — blocker, exit 1
136
+ - Action: Must update before stable release
137
+
138
+ **Scenario 4 — New standard, no translation file**
139
+ - No `locales/zh-TW/core/new-standard.md` exists
140
+ - Severity: `MISSING` — blocker, exit 1
141
+ - Action: Create translation file before release
142
+
143
+ ---
144
+
145
+ ## Error Codes
146
+
147
+ | Code | Description |
148
+ |------|-------------|
149
+ | `TRANS-001` | `MISSING_TRANSLATION` — Translation file does not exist for a source standard |
150
+ | `TRANS-002` | `MAJOR_VERSION_GAP` — Translation source_version is MAJOR behind current source |
151
+ | `TRANS-003` | `MISSING_FRONTMATTER` — Translation file lacks required YAML frontmatter |
152
+ | `TRANS-004` | `STALE_SOURCE_REF` — `source` path in frontmatter points to non-existent file |
153
+
154
+ ---
155
+
156
+ ## References
157
+
158
+ - [documentation-lifecycle.md](documentation-lifecycle.md) — Parent standard; trigger matrix and check pyramid
159
+ - [standard-admission-criteria.md](standard-admission-criteria.md) — How new standards are admitted (triggers TRANS-001)
160
+ - `scripts/check-translation-sync.sh` — Implementation of this standard's automation rules
161
+ - `.githooks/pre-commit` — Pre-commit integration
162
+ - `scripts/install-hooks.sh` — Hook installation
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 5.1.0-beta.7
4
- translation_version: 5.1.0-beta.7
5
- last_synced: 2026-04-17
3
+ source_version: 5.1.0
4
+ translation_version: 5.1.0
5
+ last_synced: 2026-04-20
6
6
  status: current
7
7
  ---
8
8
 
@@ -17,6 +17,35 @@ status: current
17
17
 
18
18
  ## [Unreleased]
19
19
 
20
+ ## [5.1.0] - 2026-04-20
21
+
22
+ > **正式版**:BUG-A06 i18n 完整性 — 新增 32 份缺失翻译、Semver 感知翻译闸门、新增 `translation-lifecycle-standards` UDS 标准。BUG-A07 Shell 测试覆盖 — 20+ 脚本的 bats smoke tests。BUG-A08 假通过测试审计 — 修正 22 个测试。Pre-release Batch 0:6 个标准从 Trial 升至 Adopt(DEC-021/025/031/035/038/040)。标准总数:106 个。
23
+
24
+ ### 新增
25
+ - **`translation-lifecycle-standards`**(Trial,到期 2026-10-20):新 UDS 标准,定义 MISSING 与 OUTDATED 的区别、Semver 严重度分级(MISSING/MAJOR = 发布阻塞器,MINOR/PATCH = advisory),以及自动化集成(pre-commit hook、release gate、bump-version 集成)。来源:BUG-A06 事后分析。
26
+ - **`.githooks/pre-commit`** + **`scripts/install-hooks.sh`**:commit 时若暂存 `core/*.md` 文件则显示 OUTDATED 警告,永不阻塞 commit。通过 `./scripts/install-hooks.sh` 启用。
27
+ - **32 份 zh-TW 与 zh-CN 翻译**(BUG-A06):所有核心标准现已有完整 zh-TW 和 zh-CN 翻译,包含 `circuit-breaker`、`token-budget`、`dual-phase-output`、`failure-source-taxonomy`、`immutability-first`、`security-decision`、`capability-declaration`、`recovery-recipe-registry`、`retry-standards`、`health-check-standards`、`timeout-standards`、`skill-standard-alignment-check`、`standard-admission-criteria`、`standard-lifecycle-management`、`packaging-standards`、`frontend-design-standards`、`translation-lifecycle-standards` 等。
28
+ - **bats smoke tests**(BUG-A07):`tests/scripts/` — 20+ 个 Shell 脚本的 smoke tests,涵盖 `check-translation-sync.sh`、`check-version-sync.sh`、`bump-version.sh`、`install-hooks.sh` 等。
29
+
30
+ ### 变更
31
+ - **`check-translation-sync.sh`**:Semver 感知严重度 — MAJOR 版本落差现在 exit 1(发布阻塞器);MINOR/PATCH 落差 exit 0 附 advisory 警告。新增 `semver_diff()` 函数与 `[MAJOR]`/`[MINOR]`/`[PATCH]` 严重度标签。
32
+ - **`bump-version.sh`**:更新版本文件后自动执行 `check-translation-sync.sh`,在升版时提供翻译健康状态快照。
33
+ - **`scripts/pre-release-check.sh`**:更新为将 `check-translation-sync.sh` 作为硬闸门(MISSING + MAJOR = exit 1)。
34
+
35
+ ### 修正
36
+ - **zh-CN `anti-hallucination.md`**(BUG-A06):从 1.5.0 更新至 1.5.1 — 补上缺失的「Agent 认识论校准」章节(Answer/Ask/Abstain 框架,XSPEC-008)。该章节自 2026-04-13 起在 zh-CN 中完全缺失。
37
+ - **22 个假通过测试**(BUG-A08):修正未正确验证行为的测试,加入真实断言。
38
+
39
+ ### 升至 Adopt(Pre-release Batch 0)
40
+ - `circuit-breaker`(DEC-021):Trial 6 个月后升至 Adopt
41
+ - `token-budget`(DEC-025):Trial 6 个月后升至 Adopt
42
+ - `dual-phase-output`(DEC-031):Trial 6 个月后升至 Adopt
43
+ - `security-decision`(DEC-035):Trial 6 个月后升至 Adopt
44
+ - `immutability-first`(DEC-038):Trial 6 个月后升至 Adopt
45
+ - `failure-source-taxonomy`(DEC-040):Trial 6 个月后升至 Adopt
46
+
47
+ [5.1.0]: https://github.com/AsiaOstrich/universal-dev-standards/compare/v5.1.0-beta.7...v5.1.0
48
+
20
49
  ## [5.1.0-beta.7] - 2026-04-17
21
50
 
22
51
  > **Beta Release**:DEC-043 Wave 1 — 六个 Trial 状态标准,涵盖可靠性模式与治理 Meta 框架。
@@ -6,7 +6,7 @@
6
6
 
7
7
  > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
8
8
 
9
- **版本**: 5.1.0-beta.7 (Pre-release) | **发布日期**: 2026-04-13 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
9
+ **版本**: 5.1.0 | **发布日期**: 2026-04-13 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
10
10
 
11
11
  语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流,确保不同技术栈之间的一致性、质量和可维护性。
12
12
 
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../core/anti-hallucination.md
3
- source_version: 1.5.0
4
- translation_version: 1.5.0
5
- last_synced: 2026-02-10
3
+ source_version: 1.5.1
4
+ translation_version: 1.5.1
5
+ last_synced: 2026-04-20
6
6
  status: current
7
7
  ---
8
8
 
@@ -742,6 +742,24 @@ Redis 是最佳选择。如果这是单实例应用程序且有
742
742
 
743
743
  ---
744
744
 
745
+ ## Agent 认识论校准(v1.4.0,XSPEC-008)
746
+
747
+ Agent 必须使用 Answer / Ask / Abstain 框架声明其认识论状态:
748
+
749
+ | 动作 | 使用时机 | 必填字段 |
750
+ |------|---------|---------|
751
+ | `answer` | 拥有足够信息 | 无(completeness/confidence 为选填)|
752
+ | `ask` | 缺少关键信息 | `missing_variables` 列表 |
753
+ | `abstain` | 真正超出能力范围 | `abstain_reason` |
754
+
755
+ **Fail-closed Agent**(必须始终回答):`evaluator`、`guardian`
756
+
757
+ **向后兼容**:缺少 `epistemic` 字段时默认为 `action_type: "answer"`。
758
+
759
+ 参见:XSPEC-008、DEC-014(PassiveQA)
760
+
761
+ ---
762
+
745
763
  ## 相关标准
746
764
 
747
765
  - [测试标准](testing-standards.md) - 确保验证 AI 分析结果(或使用 `/testing-guide` 技能)
@@ -754,6 +772,7 @@ Redis 是最佳选择。如果这是单实例应用程序且有
754
772
 
755
773
  | 版本 | 日期 | 变更 |
756
774
  |------|------|------|
775
+ | 1.5.1 | 2026-04-13 | 新增: Agent 认识论校准(Answer/Ask/Abstain)框架(XSPEC-008)|
757
776
  | 1.4.0 | 2026-01-19 | 新增: 副作用分析规则(第 7 条禁止行为)、工作流程步骤及检查清单项目 |
758
777
  | 1.3.1 | 2025-12-24 | 新增: 相关标准章节 |
759
778
  | 1.3.0 | 2025-12-22 | 增强: 禁止行为章节,新增详细对比范例 |
@@ -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 设计中的认知谦逊(若适用)