universal-dev-standards 5.15.1 → 5.16.0

package/bundled/locales/zh-CN/skills/spec-driven-dev/SKILL.md

@@ -2,148 +2,222 @@
 source: ../../../../skills/spec-driven-dev/SKILL.md
 source_version: 1.2.0
 translation_version: 1.2.0
-last_synced: 2026-03-23
+last_synced: 2026-06-02
+source_hash: 195f50bcbfb7
 status: current
 description: |
   在编写代码前，建立、审查和管理规格文件。
   使用时机：建立规格、审查设计、规格驱动开发流程。
   关键字：spec, specification, SDD, design, review, 规格, 设计, 审查, 验证。
 ---
+<!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
+  SDD 生命周期编排（7 阶段状态机、阶段转换、闸门检查）已迁移至
+  采用层（XSPEC-095, 2026-04-28）。本 Skill 保留：spec 格式定义、状态
+  描述、delta 操作、决策树。
+  如需强制执行的生命周期，请使用你采用层的工具链。
+-->
 
-# 规格驱动开发助手
+# Spec-Driven Development Assistant | 规格驱动开发助手
 
-> **语言**: [English](../../../../skills/spec-driven-dev/SKILL.md) | 简体中文
+在编写代码前，建立、审查和管理规格文件。
 
 在编写代码前，建立、审查和管理规格文件。
 
-## 快速检查清单
+## When to Use `/sdd` vs `uds spec` | 何时使用
+
+| 场景 | `/sdd` | `uds spec` |
+|----------|--------|------------|
+| 带审查周期的正式功能开发 | ✅ | ❌ |
+| 完整 spec 生命周期（Draft → Archived） | ✅ | ❌ |
+| 快速原型 / Vibe coding | ❌ | ✅ |
+| 小幅增量改动 | ❌ | ✅ |
+| 需要利益相关方签核 | ✅ | ❌ |
+| 从自然语言意图生成 micro-spec | ❌ | ✅ |
+
+> **`/sdd`** = 用于正式开发的完整 spec 生命周期
+> **`uds spec`** = 用于快速迭代的轻量 micro-spec
+>
+> **`/sdd`** = 正式开发的完整规格生命周期
+> **`uds spec`** = 快速迭代的轻量微规格
+
+## TL;DR Quick Checklist | 快速检查清单
 
-- 搜索现有规格：查看 `specs/`、`docs/specs/` 或项目规格目录
-- 决定范围：新功能 vs 修改现有功能
-- 选择唯一的规格 ID：`SPEC-NNN` 或 kebab-case 变更 ID
-- 撰写包含明确 AC（Given/When/Then 格式）的提案
-- 实现前取得核准
-- 依序实现任务，对照规格验证
-- 完成后归档规格
+- 搜索已有 spec：查看 `specs/`、`docs/specs/` 或项目的 spec 目录
+- 确定范围：新增功能 vs 修改既有能力
+- 选取唯一的 spec ID：`SPEC-NNN` 或 kebab-case 变更 ID
+- 撰写提案，包含清晰的 AC（Given/When/Then 格式）
+- 在实作开始前取得批准
+- 按顺序实作各任务，对照 spec 进行验证
+- 完成后归档 spec
 
-## 决策树
+## Decision Tree | 决策树
 
 ```
-新需求？
-├─ 修复符合规格行为的 Bug？ → 直接修复
-├─ 错字/格式/注释？ → 直接修复
-├─ 依赖套件更新（不破坏兼容性）？ → 直接修复
-├─ 新功能/能力？ → 建立提案
-├─ 破坏性变更？ → 建立提案
-├─ 架构变更？ → 建立提案
-└─ 不确定？ → 建立提案（较安全）
+New request? | 新需求？
+├─ Bug fix restoring spec behavior? → Fix directly | 直接修复
+├─ Typo/format/comment? → Fix directly | 直接修复
+├─ Dependency update (non-breaking)? → Fix directly | 直接修复
+├─ New feature/capability? → Create proposal | 建立提案
+├─ Breaking change? → Create proposal | 建立提案
+├─ Architecture change? → Create proposal | 建立提案
+├─ Agent/role definition (spans multiple features)? → Use spec-type: agent | 使用 Agent SPEC template
+└─ Unclear? → Create proposal (safer) | 建立提案（较安全）
 ```
 
-## 工作流程
+## Workflow | 工作流程
 
 ```
 DISCUSS ──► CREATE ──► REVIEW ──► APPROVE ──► IMPLEMENT ──► VERIFY ──► ARCHIVE
 ```
 
-### 0. Discuss - 厘清范围
-在编写规格前，捕捉模糊地带、建立治理原则、解决歧义。
+### 0. Discuss - Clarify Scope | 厘清范围
+捕捉灰色地带、建立指导原则，并在撰写 spec 前消解歧义。
 
-### 1. Create - 编写规格
-定义需求、技术设计、验收条件和测试计划。
+### 1. Create - Write Spec | 撰写规格
+定义需求、技术设计、验收条件与测试计划。
 
-### 2. Review - 审查验证
-与利害关系人检查完整性、一致性和可行性。
+### 2. Review - Validate | 审查验证
+与利益相关方一起检查完整性、一致性与可行性。
 
-### 3. Approve - 核准
-在实现开始前取得利害关系人签核。
+### 3. Approve - Sign Off | 核准
+在实作开始前取得利益相关方签核。
 
-### 4. Implement - 实现
-依据已核准的规格进行开发，参照需求和验收条件。
+### 4. Implement - Code | 实作
+依据已核准的 spec 进行开发，参照需求与 AC。
 
-### 5. Verify - 验证
-确保实现符合规格，所有测试通过，验收条件已满足。
+### 5. Verify - Confirm | 验证
+确保实作与 spec 相符、所有测试通过、AC 满足。
 
-### 6. Archive - 归档
-归档已完成的规格，链接至 commits/PRs。
+### 6. Archive - Close | 归档
+将完成的 spec 归档，并附上指向 commit/PR 的链接。
 
-## 规格状态
+## Spec States | 规格状态
 
-| 状态 | 说明 | State | Description |
-|------|------|-------|-------------|
-| **Draft** | 草稿中 | Draft | Work in progress |
-| **Review** | 审查中 | Review | Under review |
-| **Approved** | 已核准 | Approved | Ready for implementation |
-| **Implemented** | 已实现 | Implemented | Code complete |
-| **Archived** | 已归档 | Archived | Completed or deprecated |
+| 状态 | Description | 说明 |
+|-------|-------------|------|
+| **Draft** | Work in progress | 草稿中 |
+| **Review** | Under review | 审查中 |
+| **Approved** | Ready for implementation | 已核准 |
+| **Implemented** | Code complete | 已实作 |
+| **Archived** | Completed or deprecated | 已归档 |
 
-## 规格结构
+## Spec Structure | 规格结构
 
 ```markdown
 # [SPEC-ID] Feature: [Name]
 
 ## Overview
-简短描述提案变更。
+Brief description of the proposed change.
 
 ## Motivation
-为什么需要这个变更？解决什么问题？
+Why is this change needed? What problem does it solve?
 
 ## Requirements
 ### Requirement: [Name]
-系统 SHALL [行为描述]。
+The system SHALL [behavior description].
 
-#### Scenario: [成功案例]
-- **GIVEN** [初始情境]
-- **WHEN** [执行动作]
-- **THEN** [预期结果]
+#### Scenario: [Success case]
+- **GIVEN** [initial context]
+- **WHEN** [action performed]
+- **THEN** [expected result]
 
 ## Acceptance Criteria
 - AC-1: Given [context], when [action], then [result]
 
 ## Technical Design
-[架构、API 变更、数据库变更]
+[Architecture, API changes, database changes]
 
 ## Test Plan
-- [ ] [组件] 的单元测试
-- [ ] [流程] 的集成测试
+- [ ] Unit tests for [component]
+- [ ] Integration tests for [flow]
 ```
 
-### 场景格式规则
+### Agent SPEC Structure | Agent 规格结构（`spec-type: agent`）
+
+```markdown
+# [SPEC-ID] Agent: [Role Name]
+<!-- spec-type: agent -->
+<!-- agent-id auto-referenced by feature SPECs -->
+
+## Role Definition
+- **Role**: [Agent Name]
+- **Responsibility**: [One sentence]
+- **Autonomy Level**: L[1-5] (per DEC-065)
+
+## Capability Scope
+**Owns:**
+- [Capability 1]
+- [Capability 2]
+
+**Does NOT own:**
+- [Explicit exclusion]
+
+## Interface Contract
+### Input
+| Message Type | Required Fields | Optional Fields |
+|---|---|---|
+| [Type] | [fields] | [fields] |
+
+### Output
+| Artifact Type | Success Condition | Failure Condition |
+|---|---|---|
+| [Type] | [condition] | [condition] |
+
+## Agent Interactions
+- **Upstream**: [Who calls this agent]
+- **Downstream**: [Who this agent calls]
+- **Parallel**: [Agents working alongside]
+
+## Related Feature SPECs
+- [SPEC-NNN] — [This agent's role in that spec]
+```
 
-- 使用 `#### Scenario:` (h4 标题) 撰写每个场景
-- 每个需求必须至少有一个场景
+### Scenario Formatting Rules | 场景格式规则
+
+- 每个场景使用 `#### Scenario:`（h4 标题）
+- 每条 requirement 必须至少有一个场景
 - 使用 **GIVEN/WHEN/THEN** 格式描述结构化行为
-- 使用 **SHALL/MUST** 表达强制需求，**SHOULD** 表达建议
+- 规范性需求使用 **SHALL/MUST**，建议性使用 **SHOULD**
 
-## 变更操作
+## Delta Operations | 变更操作
 
-修改现有规格时，使用 delta 区段：
+修改既有 spec 时，使用 delta 区段：
 
-| 操作 | 说明 |
-|------|------|
-| `## ADDED Requirements` | 新增功能 |
-| `## MODIFIED Requirements` | 修改行为 |
-| `## REMOVED Requirements` | 移除功能 |
-| `## RENAMED Requirements` | 重新命名 |
+| Operation | Description | 说明 |
+|-----------|-------------|------|
+| `## ADDED Requirements` | New capabilities | 新增功能 |
+| `## MODIFIED Requirements` | Changed behavior | 修改行为 |
+| `## REMOVED Requirements` | Deprecated features | 移除功能 |
+| `## RENAMED Requirements` | Name changes | 重新命名 |
 
-## 使用方式
+## Usage | 使用方式
 
-- `/sdd` - 交互式规格建立向导
-- `/sdd auth-flow` - 为特定功能建立规格
-- `/sdd review` - 审查现有规格
-- `/sdd --sync-check` - 检查同步状态
+```
+/sdd                     - Interactive spec creation wizard | 互动式规格建立向导
+/sdd auth-flow           - Create spec for specific feature | 为特定功能建立规格
+/sdd review              - Review existing specs | 审查现有规格
+/sdd --sync-check        - Check sync status | 检查同步状态
+```
 
-## 下一步引导
+## Next Steps Guidance | 下一步引导
 
 `/sdd` 完成后，AI 助手应建议：
 
-> **规格文档已建立。建议下一步：**
-> - 执行 `/derive` 从规格推导测试工件
-> - 执行 `/derive bdd` 仅推导 BDD 场景
-> - 执行 `/derive tdd` 仅推导 TDD 骨架
-> - 审查 AC 完整性，确保所有验收条件可测试
-> - 检查 UDS 规范覆盖率 → 执行 `/audit --patterns`
+> **规格文件已建立。建议下一步 / Specification document created. Suggested next steps:**
+> - 执行 `/derive` 从规格推导测试工件 ⭐ **Recommended / 推荐** — Derive test artifacts from spec
+> - 执行 `/derive bdd` 仅推导 BDD 场景 — Derive BDD scenarios only
+> - 执行 `/derive tdd` 仅推导 TDD 骨架 — Derive TDD skeletons only
+> - 审查 AC 完整性，确保所有验收条件可测试 — Review AC completeness
+> - 检查 UDS 规范覆盖率 → 执行 `/audit --patterns` — Check UDS standard coverage → Run `/audit --patterns`
+
+## Reference | 参考
+
+- Detailed guide: [guide.md](./guide.md)
+- Core standard: [spec-driven-development.md](../../core/spec-driven-development.md)
+
 
-## 参考
+## AI Agent Behavior | AI 代理行为
 
-- 详细指南：[guide.md](./guide.md)
-- 核心规范：[spec-driven-development.md](../../../../core/spec-driven-development.md)
+> 完整的 AI 行为定义请参阅对应的命令文件：[`/sdd`](../commands/sdd.md#ai-agent-behavior--ai-代理行为)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/sdd`](../commands/sdd.md#ai-agent-behavior--ai-代理行为)

package/bundled/locales/zh-CN/skills/sweep/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: sweep
+source: ../../../../skills/sweep/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 712e596d091a
+status: current
+scope: universal
+description: |
+  [UDS] 扫描代码库的调试残留与代码质量问题；可自动修正安全模式。
+  Use when: before committing, during PR review, or periodic codebase cleanup.
+  Keywords: sweep, debug cleanup, console.log, debugger, TODO, ts-any, code quality, 扫描, 清理.
+allowed-tools: Read, Grep, Glob, Bash(find:*), Edit, Write
+argument-hint: "[--fix] [--report] [--path <dir>] [--exclude <pattern>]"
+---
+
+# 扫码助手
+
+> **语言**: [English](../../../../skills/sweep/SKILL.md) | 简体中文
+
+扫描代码库的调试残留、代码质量问题与技术债标记。
+可选择性自动修正安全模式（console.log、debugger 等语句）。
+
+---
+
+## 扫描模式
+
+| Pattern ID | 名称 | 可自动修正 | 说明 |
+|------------|------|-----------|------|
+| `console-log` | console.log / console.debug / console.trace | ✅ 是 | 留在生产环境的调试输出 |
+| `debugger` | debugger 语句 | ✅ 是 | 留在代码中的断点 |
+| `todo-fixme` | TODO / FIXME / HACK / XXX | ❌ 仅报告 | 技术债标记 |
+| `ts-any` | TypeScript `any` 类型 | ❌ 仅报告 | 类型安全违规 |
+
+---
+
+## 使用方式
+
+```bash
+/sweep                        # 扫描当前目录，报告发现
+/sweep --fix                  # 扫描并自动修正可修复项
+/sweep --report               # 扫描并将报告写入 .uds/sweep-report.json
+/sweep --path src/            # 扫描指定目录
+/sweep --exclude "**/*.test.ts"  # 排除模式（glob）
+```
+
+---
+
+## 执行工作流程
+
+### Step 1：搜索文件
+使用 Glob tool 找出目标路径下所有源代码文件。
+默认排除：`node_modules/`、`dist/`、`.git/`、`*.min.js`、`coverage/`。
+
+### Step 2：逐 Pattern 扫描
+对每个 pattern 使用 Grep 在所有文件中查找匹配结果。
+汇总发现：`{ file, line, column, pattern_id, label, fixable, content }`。
+
+### Step 3：报告发现
+输出结构化摘要：
+```
+📊 扫描结果
+─────────────────────────────────────
+console-log:   12 条  （可自动修正）
+debugger:       2 条  （可自动修正）
+todo-fixme:    28 条  （仅报告）
+ts-any:         5 条  （仅报告）
+─────────────────────────────────────
+合计：47 条  |  可修正：14 条
+```
+
+### Step 4：HITL 闸门（--fix 且发现数 > 20）
+若设置 `--fix` **且**可修正发现总数超过 20：
+**暂停并要求用户明确确认**后才应用修正。
+显示将被修改的文件清单。
+
+### Step 5：应用修正（确认 --fix 后）
+对每条可修正发现：
+- `console-log`：若该行仅含 console 语句则删除该行
+- `debugger`：若该行仅含 debugger 语句则删除该行
+
+使用 Edit tool 逐文件应用变更。
+报告：「已修正 N 条，影响 M 个文件。」
+
+### Step 6：保存报告（--report）
+将发现写入 `.uds/sweep-report.json`：
+```json
+{
+  "timestamp": "<ISO8601>",
+  "total_findings": 47,
+  "fixable": 14,
+  "fixed": 14,
+  "findings_by_pattern": { "console-log": 12, "debugger": 2, "todo-fixme": 28, "ts-any": 5 },
+  "files_modified": ["src/auth.ts", "src/utils.ts"]
+}
+```
+
+---
+
+## 设置
+
+通过 `uds.project.yaml` 设置：
+
+```yaml
+sweep:
+  default_path: "src/"
+  exclude_patterns:
+    - "**/*.test.ts"
+    - "**/*.spec.ts"
+    - "**/fixtures/**"
+  hitl_threshold: 20       # 可修正项超过此值时需确认
+  patterns:
+    enabled:
+      - console-log
+      - debugger
+      - todo-fixme
+      - ts-any
+```
+
+---
+
+## 下一步引导
+
+`/sweep` 完成后建议：
+
+> - 执行 `/checkin` 在提交前验证整体代码质量
+> - 执行 `/review` 审查清理后的变更
+> - 执行 `/commit` 提交修正
+
+---
+
+## 相关标准
+
+- [Checkin Standards](../../../../.standards/checkin-standards.ai.yaml) — Pre-commit 质量闸门
+- [Code Review](../code-review-assistant/SKILL.md) — 代码审查助手
+- [Testing Guide](../testing-guide/SKILL.md) — 测试标准
+
+---
+
+## 版本历程
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2026-04-28 | 初始版本 — XSPEC-097 Phase 1（从上游迁移） |
+
+---
+
+## 授权
+
+本 Skill 采用 [MIT License](https://opensource.org/licenses/MIT) 与 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 双重授权发布。