universal-dev-standards 5.16.0 → 6.0.0

package/bundled/locales/zh-CN/docs/user/GLOSSARY.md

@@ -0,0 +1,178 @@
+---
+source: docs/user/GLOSSARY.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS 术语表
+
+> **语言**: [English](../../../../docs/user/GLOSSARY.md) | 简体中文
+
+UDS 专属，或在 UDS 语境下有特定用法的术语。
+
+---
+
+## A
+
+**AC（Acceptance Criterion，验收条件）**
+一条可测试的陈述，定义一个功能何时算完成。以 Given-When-Then 或一般英文撰写。AC 记录在 Spec 文件中，并在测试里被引用。
+_参见：`/atdd`、`/sdd`、`acceptance-test-driven-development` 标准_
+
+**Activity（活动）**
+在 DEC-051 四层分类模型中，Activity 是一个具名的工作流步骤（例如「编写失败的测试」、「执行回归测试」）。Activity 定义于 UDS 标准中，并由 Skill 执行。
+
+**ADR（Architecture Decision Record，架构决策记录）**
+记录一项重大技术决策的文件：上下文、考量过的选项、所选方案，以及后果。
+_参见：`/adr`、`adr-standards` 标准_
+
+**ATDD（Acceptance Test-Driven Development，验收测试驱动开发）**
+一种实践做法：在开始实现前先定义验收条件，并编写测试来验证这些 AC。桥接 BDD 与 TDD。
+_参见：`/atdd`_
+
+---
+
+## B
+
+**BDD（Behavior-Driven Development，行为驱动开发）**
+一种使用自然语言 Given-When-Then 场景来描述系统行为的开发实践。场景同时作为文档与测试规格。
+_参见：`/bdd`、`behavior-driven-development` 标准_
+
+**Bundle（Bundle 层）**
+包含在 `npm install` 包中的 UDS 标准子集（供采用者使用）。与 Source 层不同——后者包含所有标准，含治理与维护工具。
+_参见：DEC-045_
+
+---
+
+## C
+
+**Core Standard（核心标准）**
+位于 `core/`（以及 `.standards/*.md`）的 Markdown 文件，包含某个 UDS 标准完整、人类可读的版本。涵盖背后理由、边界情况、示例与参考资料。
+_对比：AI Standard_
+
+**AI Standard（AI 标准）**
+位于 `.standards/`（以及 `ai/standards/`）的 `.ai.yaml` 文件，是 Core Standard 的 token 精简、为 AI 优化的编码。Skill 在执行时读取它。
+
+---
+
+## D
+
+**DEC（Decision，决策）**
+记录于 `dev-platform/cross-project/decisions/DEC-NNN-*.md` 的跨项目架构或产品决策。DEC 依序编号，追踪重大选择背后的「为什么」。
+
+**Dual-Layer Architecture（双层架构）**
+UDS 的两层设计：Core Standards（完整知识、人类可读）+ AI Standards（token 精简、机器可读）。Skill 使用 AI Standards；开发者阅读 Core Standards。
+
+---
+
+## S
+
+**SDD（Spec-Driven Development，规格驱动开发）**
+一种 UDS 实践做法：在写代码前先创建规格文件。Spec 定义背景、范围、验收条件与范围外项目。
+_参见：`/sdd`、`spec-driven-development` 标准_
+
+**Skill**
+封装为 SKILL.md 文件的预建 AI 工作流。在 Claude Code 输入 `/<name>` 即可激活。Skill 运用 AI Standards 来实现 UDS 的活动。
+_参见：[SKILLS-INDEX.md](../../../../docs/user/SKILLS-INDEX.md)_
+
+**Skill Budget（Skill 预算）**
+Claude Code 的 context window 中保留用于列出可用 skill 的比例。当有 55+ 个 skill 时，描述可能被截断。UDS 以 Tier 来管理这项预算。
+_参见：DEC-061、[skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)_
+
+**Skill Tier（Skill 分级，DEC-061）**
+依使用频率对 skill 进行分类，借此控制列出行为：
+- **Tier 1（Core）**：15 个 skill，每日使用，永远以描述列出
+- **Tier 2（Advanced）**：28 个 skill，每周使用，默认以描述列出
+- **Tier 3（Specialist）**：12 个 skill，事件驱动，默认仅列出名称（仍可通过 `/<name>` 调用）
+
+**Standard（标准）**
+涵盖某项特定实践（例如 commit 消息、API 设计、测试）的 UDS 准则文件。标准与技术、语言无关。每个标准同时存在为 Core Standard（`.md`）与 AI Standard（`.ai.yaml`）。
+
+**Source（Source 层）**
+完整的 UDS 仓库，包含所有标准、治理工具与维护脚本。是 Bundle 层的超集。
+_参见：DEC-045_
+
+---
+
+## T
+
+**TDD（Test-Driven Development，测试驱动开发）**
+一种在实现代码前先编写测试的开发实践。RED-GREEN-REFACTOR 循环：写一个失败的测试 → 让它通过 → 重构。
+_参见：`/tdd`、`test-driven-development` 标准_
+
+---
+
+## U
+
+**UDS（Universal Development Standards，通用开发标准）**
+本项目。一套与语言无关、与框架无关的软件开发质量汇集，含 145 个核心标准、55 个 AI skill 与 51 个斜线命令。
+
+**UDS Manifest（`uds-manifest.json`）**
+所有 UDS 标准与 skill 的机器可读索引。包含统计数据、skill 对命令的对照，以及分类归属。供 UDS CLI 与文档生成器使用。
+
+---
+
+## X
+
+**XSPEC（Cross-Project Spec，跨项目规格）**
+位于 `dev-platform/cross-project/specs/XSPEC-NNN-*.md` 的规格文件。用于影响多个子项目（UDS、VibeOps、telemetry）的功能，或新的 UDS 功能。
+_依集中化政策（2026-04-22），所有新 spec 一律创建为 XSPEC。_
+
+---
+
+## 术语规范化（Canonical Forms，标准形式）
+
+> 跨标准反复出现的术语与符号之单一真实来源（XSPEC-292 T6）。这些表格把**既有、刻意为之**的惯例明文化，让新标准对齐而非漂移。它们**不会**重新命名任何东西——多数看似「双重术语」的情况其实是依层级设计、各得其所（例如 JSON body 中的 `createdAt` 对比数据库字段的 `created_at` 是正确的，并非冲突）。
+
+### 依层级的字段命名
+
+同一个概念依其所在层级的惯例书写。跨越层级边界是一种转换，而非不一致。
+
+| 层级 | 惯例 | 示例 |
+|------|------|------|
+| 结构化日志（JSON） | `snake_case` | `trace_id`、`request_id`、`http_method`、`db_table` |
+| API JSON body | `camelCase` | `createdAt`、`firstName`、`httpStatus` |
+| API 查询参数 | `snake_case` | `?sort_by=created_at` |
+| URL 路径片段 | `kebab-case` | `/user-profiles` |
+| HTTP header 名称 | `lowercase-hyphen` | `x-request-id`、`traceparent` |
+| 数据库数据表／字段 | `snake_case`（单数数据表）| `user_account`、`created_at` |
+| 代码标识符 | 语言原生 | `camelCase`（JS/TS）、`snake_case`（Python/Go）|
+
+_标准：`logging-standards`、`api-design-standards`、`database-standards`。_
+
+### 测试层级缩写
+
+大写＝该术语；小写＝环境标识符。`IT` 永远指 Integration Testing（集成测试），绝非 Information Technology。
+
+| 缩写 | 全称 | 典型环境 |
+|------|------|----------|
+| `UT` | Unit Testing（单元测试）| `local` |
+| `IT` | Integration Testing（集成测试）| `local` / `ci` |
+| `ST` | System Testing（系统测试）| `ci` / `sit` |
+| `E2E` | End-to-End Testing（端到端测试）| `staging` |
+| `AT` | Acceptance Testing（验收测试）| — |
+| `UAT` | User Acceptance Testing（用户验收测试）| — |
+| `SIT` | System Integration Testing（系统集成测试，该术语）；`sit` 是 SIT **环境** id | `ci` |
+
+_标准：`testing`（testing-standards）、`test-governance`。_
+
+### 状态：文字 vs 符号
+
+**文字**是标准／机器可读的值；**符号**是可选的视觉呈现。两者成对，并非互相竞争。
+
+| 标准文字 | 符号 | 领域 |
+|----------|------|------|
+| `covered` | ✅ | AC／测试覆盖 |
+| `partial` | ⚠️ | AC／测试覆盖 |
+| `uncovered` | ❌ | AC／测试覆盖（测试缺口）|
+| `not_implemented` | 🚫 | AC（代码缺口，非测试缺口）|
+
+_领域专属的生命周期各自维持独立的状态机——ADR（`Proposed → Accepted → Deprecated → Superseded`）、文档生命周期（`draft → active → archived`），以及上方的 AC 覆盖彼此不同，**不会**被合并。标准：`acceptance-criteria-traceability`、`adr-standards`、`documentation-structure`。_
+
+---
+
+## 另见
+
+- [FAQ.md](FAQ.md) — 常见问题
+- [SKILLS-INDEX.md](../../../../docs/user/SKILLS-INDEX.md) — 所有 skill 与描述
+- [GETTING-STARTED.md](GETTING-STARTED.md) — 首次设置

package/bundled/locales/zh-CN/docs/user/README.md

@@ -0,0 +1,70 @@
+---
+source: docs/user/README.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS 用户文档
+
+> **语言**: [English](../../../../docs/user/README.md) | 简体中文
+
+欢迎来到 UDS（Universal Development Standards，通用开发标准）用户文档中心。
+
+---
+
+## 新手入门
+
+刚安装完 UDS？从这里开始：
+
+1. **[GETTING-STARTED.md](../../../../docs/user/GETTING-STARTED.md)** — 5 分钟导览：安装 → 初始化 → 第一份 spec → 第一次 commit（简中翻译进行中）
+2. **[GLOSSARY.md](../../../../docs/user/GLOSSARY.md)** — 什么是 Skill？Standard？Tier？所有 UDS 术语的定义（简中翻译进行中）
+3. **[SKILLS-INDEX.md](../../../../docs/user/SKILLS-INDEX.md)** — 按 Tier 与分类浏览全部 55 个 skill（自动生成，仅英文）
+
+---
+
+## 日常使用
+
+| 我想要… | 前往 |
+|---------|------|
+| 找到正确的命令 | [SKILLS-INDEX.md → 触发时机速查](../../../../docs/user/SKILLS-INDEX.md#觸發時機速查-when-to-use) |
+| 查看所有斜线命令 | [COMMANDS-INDEX.md](../../../../docs/user/COMMANDS-INDEX.md) |
+| 自定义列出哪些 skill | [skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md) |
+| 快速参考卡 | [CHEATSHEET.md](../CHEATSHEET.md) |
+| 解答常见问题 | [FAQ.md](../../../../docs/user/FAQ.md) |
+| 修正问题 | [TROUBLESHOOTING.md](../../../../docs/user/TROUBLESHOOTING.md) |
+
+---
+
+## 维护者 / 贡献者
+
+| 主题 | 资源 |
+|------|------|
+| UDS 的结构 | [CONTRIBUTING.md](../../../../CONTRIBUTING.md) |
+| CLI 参考 | [cli/README.md](../../../../cli/README.md) |
+| 采用指南 | [ADOPTION-GUIDE.md](../../../../adoption/ADOPTION-GUIDE.md) |
+| 发布前信息 | [PRE-RELEASE.md](../../../../docs/PRE-RELEASE.md) |
+| 更新自动生成的文档 | 执行 `npm run docs:generate-index` |
+
+---
+
+## 文档地图
+
+```
+docs/
+├── user/                        ← 你在这里（面向用户的文档）
+│   ├── README.md                ← 本档 — 文档中心
+│   ├── GETTING-STARTED.md       ← 首次设置指南
+│   ├── SKILLS-INDEX.md          ← 55 个 skill 按 Tier 与分类（自动生成）
+│   ├── COMMANDS-INDEX.md        ← 所有斜线命令（自动生成）
+│   ├── CHEATSHEET.md            ← 快速参考卡
+│   ├── FAQ.md                   ← 常见问题
+│   ├── GLOSSARY.md              ← 术语表
+│   └── TROUBLESHOOTING.md       ← 问题 → 解法
+├── reference/                   ← 完整参考（自动生成）
+│   └── FEATURE-REFERENCE.md
+└── internal/                    ← 维护者文档（非给终端用户）
+```
+
+> **注意**：标记「自动生成」的文件由 `npm run docs:generate-index` 重建。
+> 请勿手动编辑——下次执行时变更会被覆写。

package/bundled/locales/zh-CN/docs/user/TROUBLESHOOTING.md

@@ -0,0 +1,190 @@
+---
+source: docs/user/TROUBLESHOOTING.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS 疑难排解指南
+
+> **语言**: [English](../../../../docs/user/TROUBLESHOOTING.md) | 简体中文
+
+找到你的问题 → 照着修法做。
+
+---
+
+## 安装问题
+
+**问题：`npm install -g` 之后出现 `uds: command not found`**
+
+```bash
+# 检查 npm 全局 bin 是否在你的 PATH 中
+npm config get prefix
+# 在 ~/.zshrc 或 ~/.bashrc 把 <prefix>/bin 加入 PATH
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+**问题：`uds init` 因权限错误而失败**
+
+```bash
+# 改用 Node 版本管理器（nvm/fnm），而非系统内建的 Node
+# 或修正 npm 全局目录：https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
+```
+
+---
+
+## Claude Code 中未显示 Skill
+
+**问题：我在 Claude Code 菜单中看不到 `/sdd`、`/tdd` 或其他 UDS skill。**
+
+步骤 1 — 验证 UDS 已初始化：
+```bash
+uds check
+```
+若报告文件遗失，重新运行 `uds init`。
+
+步骤 2 — 验证 `.claude/` 配置存在：
+```bash
+ls .claude/settings.json
+```
+若遗失，`uds init` 应会创建它。试试 `uds init --force`。
+
+步骤 3 — 可能超出 skill 预算（skill 太多 → 描述被截断）：
+参阅 [skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)，将少用的 skill 降为 Tier 3。
+
+步骤 4 — 强制重新加载 Claude Code：
+关闭并重新打开正在运行 Claude Code 的 IDE／终端窗口。
+
+**问题：有些 skill 看得到，有些却看不到。**
+
+这对 Tier 3 skill 而言是预期行为。Tier 3 skill 只显示名称（无描述）以节省 context 预算，而某些 AI 客户端可能根本不列出它们。
+
+**Tier 3 skill 仍可直接调用**：输入 `/<name>` 并按 Enter。
+
+若要让某个 Tier 3 skill 显示，加入你的 `.claude/settings.json`：
+```json
+{
+  "skillOverrides": {
+    "brainstorm-assistant": "on"
+  }
+}
+```
+
+---
+
+## Skill 行为不如预期
+
+**问题：Skill 有激活，但给的是通用回应，而非 UDS 专属的指引。**
+
+可能原因：`.standards/` 目录为空或过时。
+```bash
+uds check       # 检查安装了什么
+uds update      # 更新到最新标准
+```
+
+**问题：`/commit` 生成的 commit 消息不符合 Conventional Commits。**
+
+commit-standards skill 会读取你既有的 commit 来学习项目风格。若你先前没有 Conventional Commits 格式的 commit，它可能会偏离。
+
+在 `CLAUDE.md` 加入明确指引：
+```markdown
+## Commit Format
+Always use Conventional Commits: `<type>(<scope>): <subject>`
+Types: feat, fix, docs, chore, test, refactor, style, build, ci
+```
+
+**问题：`/sdd` 创建了 spec，但我想要不同的格式。**
+
+在你的 `CLAUDE.md` 加入内容来自定义 spec 模板：
+```markdown
+## Spec Format
+When creating specs with /sdd, use this template:
+[paste your preferred template here]
+```
+
+---
+
+## 不使用 Claude Code 而使用 UDS
+
+**问题：我用的是 Cursor / GitHub Copilot / Windsurf——skill 无法运作。**
+
+Skill（`/command` 系统）为 Claude Code 专属。对于其他 AI 工具：
+
+1. 运行 `uds init` 并选择你的工具——它会配置 `.cursorrules`、`.github/copilot-instructions.md` 等
+2. `.standards/` 中的 Core Standards 与工具无关，能为任何读取它们的 AI 提供 context
+3. 在你的 AI 指令文件中使用下方的快速参考表
+
+**可嵌入任何 AI 工具的快速参考：**
+
+```markdown
+## Commit Messages
+Format: <type>(<scope>): <subject>
+Types: feat, fix, docs, chore, test, refactor, style
+
+## Testing Pyramid
+Unit: 70% | Integration: 20% | System: 7% | E2E: 3%
+
+## User Stories
+As a [role], I want [feature], so that [benefit].
+INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable
+```
+
+**Skill → Core Standard 对照**（当 skill 无法使用时）：
+
+| Skill | 要参考的 Core Standard |
+|-------|------------------------|
+| `commit-standards` | `.standards/commit-message.md` |
+| `testing-guide` | `.standards/testing.md` |
+| `code-review-assistant` | `.standards/code-review.md` |
+| `requirement-assistant` | `.standards/requirement-engineering.md` |
+| `spec-driven-dev` | `.standards/spec-driven-development.md` |
+| `tdd-assistant` | `.standards/test-driven-development.md` |
+| `bdd-assistant` | `.standards/behavior-driven-development.md` |
+| `git-workflow-guide` | `.standards/git-workflow.md` |
+| `refactoring-assistant` | `.standards/refactoring-standards.md` |
+
+---
+
+## 更新问题
+
+**问题：`uds update` 失败。**
+
+```bash
+# 检查网络／npm registry 连接
+npm ping
+# 试试指定 registry
+npm install -g universal-dev-standards@latest
+# 然后重新初始化
+uds init --force
+```
+
+**问题：更新后，我的 skill 看起来坏掉了。**
+
+更新可能变更了 skill 格式。试试：
+```bash
+uds check
+uds init --force   # 重新安装 skill 配置
+```
+
+---
+
+## 一般诊断
+
+运行 `uds check` 取得完整健康报告：
+```
+uds check
+```
+
+它会检查：
+- 标准安装状态
+- Skill 配置
+- AI 工具兼容性
+- 版本对齐
+
+---
+
+## 还是卡住？
+
+- **GitHub Issues**：[github.com/AsiaOstrich/universal-dev-standards/issues](https://github.com/AsiaOstrich/universal-dev-standards/issues)
+- **FAQ**：[FAQ.md](FAQ.md)
+- **Skill 预算调整**：[skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)

package/bundled/locales/zh-CN/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md

@@ -42,7 +42,7 @@ GitHub Copilot 不支持像 Claude Code 那样的斜杠命令。此参考提供
 
 ### 2. 代码审查
 
-**Claude Code**：`/review`
+**Claude Code**：`/code-review`
 
 **Copilot Chat 提示**：
 ```

package/bundled/locales/zh-CN/integrations/github-copilot/README.md

@@ -109,7 +109,7 @@ GitHub Copilot 相较于其他 AI 编程工具有一些限制：
 Claude Code: /commit
 Copilot:     "Generate a commit message following Conventional Commits..."
 
-Claude Code: /review
+Claude Code: /code-review
 Copilot:     "Review this code following the code review checklist..."
 
 Claude Code: /tdd

package/bundled/locales/zh-CN/integrations/github-copilot/skills-mapping.md

@@ -14,7 +14,7 @@ status: current
 
 ## 概述
 
-Claude Code 提供 25 个 skills 和 17 个斜杠命令。GitHub Copilot 不支持斜杠命令，但大部分功能可通过 Chat 提示和 `copilot-instructions.md` 文件实现。
+Claude Code 提供 55 个 skills 和 51 个斜杠命令。GitHub Copilot 不支持斜杠命令，但大部分功能可通过 Chat 提示和 `copilot-instructions.md` 文件实现。
 
 ---
 
@@ -63,7 +63,7 @@ Claude Code 提供 25 个 skills 和 17 个斜杠命令。GitHub Copilot 不支
 | Claude Code | Copilot Chat 等效提示 |
 |-------------|----------------------|
 | `/commit` | "按照 Conventional Commits 格式生成 commit 消息" |
-| `/review` | "按照代码审查检查清单审查此代码" |
+| `/code-review` | "按照代码审查检查清单审查此代码" |
 | `/tdd` | "使用 TDD（红绿重构）帮我实现" |
 | `/coverage` | "使用 7 维度分析测试覆盖" |
 | `/requirement` | "按照 INVEST 条件撰写用户故事" |
@@ -100,7 +100,7 @@ Claude Code 提供 25 个 skills 和 17 个斜杠命令。GitHub Copilot 不支
    - Copilot：会话间无状态跟踪
 
 3. **斜杠命令**
-   - Claude Code：`/commit`、`/review` 等
+   - Claude Code：`/commit`、`/code-review` 等
    - Copilot：必须在 Chat 中输入完整提示
 
 4. **MCP 工具集成**

package/bundled/locales/zh-CN/integrations/opencode/skills-mapping.md

@@ -14,7 +14,7 @@ status: current
 
 ## 概述
 
-Claude Code 提供 25 个技能和 17 个斜线命令。OpenCode 原生支持技能，且**完全兼容** Claude Code 技能格式。
+Claude Code 提供 55 个技能和 51 个斜线命令。OpenCode 原生支持技能，且**完全兼容** Claude Code 技能格式。
 
 ### 关键优势：原生兼容
 
@@ -74,7 +74,7 @@ OpenCode 支持与 Claude Code 相同的技能调用语法：
 | Claude Code | OpenCode | 备注 |
 |-------------|----------|------|
 | `/commit` | `/commit` 或 `skill("commit-standards")` | 相同 |
-| `/review` | `/review` 或 `skill("code-review-assistant")` | 相同 |
+| `/code-review` | `/code-review` 或 `skill("code-review-assistant")` | 相同 |
 | `/tdd` | `/tdd` 或 `skill("tdd-assistant")` | 相同 |
 | `/coverage` | `/coverage` 或 `skill("test-coverage-assistant")` | 相同 |
 | `/requirement` | `/requirement` 或 `skill("requirement-assistant")` | 相同 |
@@ -195,7 +195,7 @@ OpenCode 没有像 Claude Code 那样的官方 marketplace，但有几个社区
 |------|-------------|----------|
 | 技能格式 | YAML frontmatter + Markdown | ✅ 相同 |
 | 技能搜索路径 | `.claude/skills/` | ✅ + `.opencode/skill/` |
-| 斜线命令 | `/commit`、`/review` 等 | ✅ 相同 |
+| 斜线命令 | `/commit`、`/code-review` 等 | ✅ 相同 |
 | 自动触发 | 基于关键字 | ✅ 相同 |
 | 技能权限 | 按技能设置 | ✅ 相同 |