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.
- package/README.md +6 -0
- package/bin/uds.js +2 -0
- package/bundled/ai/standards/translation-lifecycle-standards.ai.yaml +145 -0
- package/bundled/core/translation-lifecycle-standards.md +162 -0
- package/bundled/locales/zh-CN/CHANGELOG.md +32 -3
- package/bundled/locales/zh-CN/README.md +1 -1
- package/bundled/locales/zh-CN/core/anti-hallucination.md +22 -3
- package/bundled/locales/zh-CN/core/anti-sycophancy-prompting.md +192 -0
- package/bundled/locales/zh-CN/core/capability-declaration.md +123 -0
- package/bundled/locales/zh-CN/core/circuit-breaker.md +106 -0
- package/bundled/locales/zh-CN/core/dual-phase-output.md +103 -0
- package/bundled/locales/zh-CN/core/failure-source-taxonomy.md +99 -0
- package/bundled/locales/zh-CN/core/frontend-design-standards.md +289 -0
- package/bundled/locales/zh-CN/core/health-check-standards.md +144 -0
- package/bundled/locales/zh-CN/core/immutability-first.md +96 -0
- package/bundled/locales/zh-CN/core/packaging-standards.md +224 -0
- package/bundled/locales/zh-CN/core/recovery-recipe-registry.md +146 -0
- package/bundled/locales/zh-CN/core/retry-standards.md +131 -0
- package/bundled/locales/zh-CN/core/security-decision.md +104 -0
- package/bundled/locales/zh-CN/core/skill-standard-alignment-check.md +112 -0
- package/bundled/locales/zh-CN/core/standard-admission-criteria.md +104 -0
- package/bundled/locales/zh-CN/core/standard-lifecycle-management.md +116 -0
- package/bundled/locales/zh-CN/core/timeout-standards.md +117 -0
- package/bundled/locales/zh-CN/core/token-budget.md +108 -0
- package/bundled/locales/zh-CN/core/translation-lifecycle-standards.md +159 -0
- package/bundled/locales/zh-TW/CHANGELOG.md +32 -3
- package/bundled/locales/zh-TW/README.md +1 -1
- package/bundled/locales/zh-TW/core/anti-sycophancy-prompting.md +8 -0
- package/bundled/locales/zh-TW/core/capability-declaration.md +111 -0
- package/bundled/locales/zh-TW/core/circuit-breaker.md +111 -0
- package/bundled/locales/zh-TW/core/dual-phase-output.md +132 -0
- package/bundled/locales/zh-TW/core/failure-source-taxonomy.md +146 -0
- package/bundled/locales/zh-TW/core/frontend-design-standards.md +460 -0
- package/bundled/locales/zh-TW/core/health-check-standards.md +144 -0
- package/bundled/locales/zh-TW/core/immutability-first.md +159 -0
- package/bundled/locales/zh-TW/core/recovery-recipe-registry.md +146 -0
- package/bundled/locales/zh-TW/core/retry-standards.md +140 -0
- package/bundled/locales/zh-TW/core/security-decision.md +120 -0
- package/bundled/locales/zh-TW/core/skill-standard-alignment-check.md +112 -0
- package/bundled/locales/zh-TW/core/standard-admission-criteria.md +104 -0
- package/bundled/locales/zh-TW/core/standard-lifecycle-management.md +116 -0
- package/bundled/locales/zh-TW/core/timeout-standards.md +117 -0
- package/bundled/locales/zh-TW/core/token-budget.md +143 -0
- package/bundled/locales/zh-TW/core/translation-lifecycle-standards.md +159 -0
- package/package.json +2 -1
- package/src/commands/check.js +6 -0
- package/src/commands/init.js +6 -0
- package/src/commands/update.js +6 -0
- package/src/utils/detect-self-adoption.js +173 -0
- 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
|
|
4
|
-
translation_version: 5.1.0
|
|
5
|
-
last_synced: 2026-04-
|
|
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
|
|
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.
|
|
4
|
-
translation_version: 1.5.
|
|
5
|
-
last_synced: 2026-
|
|
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 设计中的认知谦逊(若适用)
|