universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md

@@ -0,0 +1,333 @@
+---
+source: ../../../docs/USAGE-MODES-COMPARISON.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-12
+status: current
+---
+
+# 使用模式比較：Skills vs 规范文件 vs 兩者并用
+
+> **语言**: [English](../../../docs/USAGE-MODES-COMPARISON.md) | 简体中文
+>
+> **版本**: 1.0.0
+> **最後更新**: 2026-01-12
+
+本文件比較安裝 Universal Development Standards (UDS) 後三种使用模式的效果差異。
+
+---
+
+## 目录
+
+1. [概覽](#概覽)
+2. [模式比較](#模式比較)
+3. [详细比較](#详细比較)
+4. [使用場景建议](#使用場景建议)
+5. [功能覆蓋](#功能覆蓋)
+6. [定量比較](#定量比較)
+7. [結論](#結論)
+
+---
+
+## 概覽
+
+### 模式 A：僅使用 Skills
+
+**配置方式**：
+- 安裝时选择 `standardsScope: minimal`
+- Skills 位置：Plugin Marketplace（推荐）
+- 最小化规范文件複制到项目
+
+**包含内容**：
+- 16 个 Claude Code Skills（互动式命令）
+- 最小化规范文件（僅 reference 类别）
+
+### 模式 B：僅使用规范文件
+
+**配置方式**：
+- 安裝时选择 `standardsScope: full`
+- 跳過 Skills 安裝（或选择非 Claude Code 工具）
+- 完整规范文件複制到 `.standards/`
+
+**包含内容**：
+- 17 个核心规范文件
+- 集成文件（.cursorrules、CLAUDE.md 等）
+- 無互动式 Skills
+
+### 模式 C：同时使用 Skills 与规范文件
+
+**配置方式**：
+- 安裝时选择 `standardsScope: full` + Skills 安裝
+- 或透過 `contentMode: full` 獲得完整规范
+
+**包含内容**：
+- 16 个 Claude Code Skills
+- 17 个核心规范文件
+- 集成文件
+
+---
+
+## 模式比較
+
+### 快速比較表
+
+| 面向 | 僅 Skills | 僅规范文件 | Skills + 规范文件 |
+|------|----------|-----------|------------------|
+| 互动式命令 | 16 个 | 無 | 16 个 |
+| 规范深度 | 中 | 高 | 高 |
+| Token 消耗 | 低 | 中-高 | 高 |
+| 多工具支援 | 僅 Claude Code | 全部 9 个 AI 工具 | 全部 9 个 AI 工具 |
+| 版本控制 | 外部管理 | Git 追蹤 | 混合 |
+| 自订擴展 | 受限 | 完整 | 完整 |
+| 学习曲线 | 低 | 高 | 低 |
+
+### 最適合場景
+
+| 模式 | 推荐对象 |
+|------|---------|
+| **僅 Skills** | 个人开发者，專門使用 Claude Code |
+| **僅规范文件** | 多工具团队、企业環境、離线使用 |
+| **Skills + 规范文件** | 完整体驗、学习 UDS、团队入職 |
+
+---
+
+## 详细比較
+
+### 互动性与使用体驗
+
+| 面向 | 僅 Skills | 僅规范文件 | Skills + 规范文件 |
+|------|----------|-----------|------------------|
+| 互动式命令 | 16 个可用 | 無 | 16 个可用 |
+| 上下文感知 | 自动偵测 | 需手动阅读 | 自动偵测 |
+| 工作流程引導 | 逐步引導 | 需自行理解 | 逐步引導 |
+| 学习曲线 | 低 | 高 | 低 |
+
+**说明**：
+- Skills 提供 `/commit`、`/tdd`、`/review` 等命令进行互动引導
+- 规范文件需要开发者主动阅读并应用
+- Skills 可自动偵测上下文（如 git status、项目语言）
+
+### 内容完整性
+
+| 面向 | 僅 Skills | 僅规范文件 | Skills + 规范文件 |
+|------|----------|-----------|------------------|
+| 规范深度 | 中 | 高 | 高 |
+| 範例數量 | 精簡 | 豐富 | 豐富 |
+| 决策矩陣 | 部分 | 完整 | 完整 |
+| 版本追蹤 | 否 | 是 | 是 |
+| 跨语言範例 | 部分 | 完整 | 完整 |
+
+**说明**：
+- Skills 提取规范文件的精華，但省略部分細节
+- 规范文件包含完整的决策樹、範例、和邊界情况
+- 如大規模重構模式（`refactoring-standards.md`）在 Skills 中無对应功能
+
+### 工具支援
+
+| 工具 | 僅 Skills | 僅规范文件 | Skills + 规范文件 |
+|------|----------|-----------|------------------|
+| Claude Code | 完整 | 基礎 | 完整 |
+| Cursor | 不支援 | 支援 | 支援 |
+| Windsurf | 不支援 | 支援 | 支援 |
+| Cline | 不支援 | 支援 | 支援 |
+| GitHub Copilot | 不支援 | 支援 | 支援 |
+| 其他 AI 工具 | 不支援 | 支援 | 支援 |
+
+**说明**：
+- Skills 僅支援 Claude Code
+- 规范文件可集成到所有 9 个支援的 AI 工具
+- 多工具团队需要规范文件
+
+### 維護与更新
+
+| 面向 | 僅 Skills | 僅规范文件 | Skills + 规范文件 |
+|------|----------|-----------|------------------|
+| 更新方式 | Plugin 自动更新 | `uds update` | 混合 |
+| 版本控制 | 外部管理 | Git 追蹤 | 部分 |
+| 自订擴展 | 受限 | 完整 | 完整 |
+| 团队同步 | 需各自安裝 | Git 同步 | 混合 |
+
+**说明**：
+- Skills 在 Plugin Marketplace 集中管理，但無法版本控制
+- 规范文件可放入 Git，团队自动同步
+- 自订規則需要修改规范文件
+
+### Token 使用效率
+
+| 面向 | 僅 Skills | 僅规范文件 | Skills + 规范文件 |
+|------|----------|-----------|------------------|
+| 基礎 Token 消耗 | 低 | 中-高 | 高 |
+| 按需载入 | 是 | 否 | 部分 |
+| 重複内容 | 無 | 無 | 有 |
+
+**说明**：
+- Skills 按需载入，只在呼叫时消耗 token
+- 规范文件集成到 CLAUDE.md 後，每次对话都会载入
+- 同时使用时，Skills 与规范文件有部分内容重疊
+
+---
+
+## 使用場景建议
+
+### 場景 1：个人开发者 + 僅使用 Claude Code
+
+**推荐模式**：僅使用 Skills（模式 A）
+
+**原因**：
+- Token 消耗最低
+- 互动体驗最佳
+- 無需管理額外文件
+- `/commit`、`/tdd`、`/review` 命令足夠日常使用
+
+**配置方式**：
+```bash
+uds init -y --skills-location marketplace
+# standardsScope 將自动设为 minimal
+```
+
+### 場景 2：团队开发 + 多种 AI 工具
+
+**推荐模式**：同时使用 Skills + 规范文件（模式 C）
+
+**原因**：
+- 规范文件可 Git 同步，确保团队一致性
+- 非 Claude Code 使用者可使用规范文件
+- Skills 提供 Claude Code 使用者更好的体驗
+
+**配置方式**：
+```bash
+uds init -y --skills-location marketplace --content-mode index
+# 在互动提示中选择多个 AI 工具
+```
+
+### 場景 3：嚴格规范要求的企业環境
+
+**推荐模式**：僅使用规范文件（模式 B）
+
+**原因**：
+- 可完全自订规范内容
+- 完整的版本控制和审计追蹤
+- 不依賴外部 Plugin Marketplace
+- 適合需要離线工作的環境
+
+**配置方式**：
+```bash
+uds init -y --skills-location none --content-mode full
+```
+
+### 場景 4：学习 UDS 标准体系
+
+**推荐模式**：同时使用 Skills + 规范文件（模式 C）
+
+**原因**：
+- Skills 提供引導式学习
+- 规范文件提供深入參考
+- 可对照 Skills 行为与规范内容
+
+---
+
+## 功能覆蓋
+
+### Skills 強项但规范文件較弱的功能
+
+| 功能 | 对应 Skill |
+|------|-----------|
+| 方法論切换 | `/methodology switch` |
+| 阶段检查点提醒 | `methodology-system` |
+| 自动提交消息生成 | `/commit` |
+| 互动式 TDD 循環 | `/tdd` |
+
+### 规范文件提供但 Skills 未涵蓋的功能
+
+| 功能 | 对应规范文件 |
+|------|-------------|
+| 大規模重構模式（Strangler Fig） | `refactoring-standards.md` |
+| 技術債评估矩陣 | `refactoring-standards.md` |
+| 完整错误码分类体系 | `error-code-standards.md` |
+| 日誌採样策略 | `logging-standards.md` |
+| 项目类型映射矩陣 | `documentation-writing-standards.md` |
+
+### 兩者均完整覆蓋的功能
+
+| 功能 | Skill | 规范文件 |
+|------|-------|---------|
+| Conventional Commits | `commit-standards` | `commit-message-guide.md` |
+| 测试金字塔 | `testing-guide` | `testing-standards.md` |
+| 代码审查清单 | `code-review-assistant` | `code-review-checklist.md` |
+| 語義化版本 | `release-standards` | `versioning.md` |
+| CHANGELOG 格式 | `changelog-guide` | `changelog-standards.md` |
+
+---
+
+## 定量比較
+
+### 内容量比較
+
+| 指標 | 僅 Skills | 僅规范文件 | Skills + 规范文件 |
+|------|----------|-----------|------------------|
+| 文件數量 | ~16 Skills | ~17 规范 | ~33 總计 |
+| 估计行數 | ~3,000 | ~8,000 | ~11,000 |
+| 估计 Token | ~15K | ~40K | ~50K |
+
+### 各領域功能覆蓋率
+
+| 領域 | 僅 Skills | 僅规范文件 | Skills + 规范文件 |
+|------|----------|-----------|------------------|
+| 版本管理 | 90% | 100% | 100% |
+| 测试规范 | 85% | 100% | 100% |
+| 代码审查 | 95% | 100% | 100% |
+| 重構指引 | 30% | 100% | 100% |
+| 错误处理 | 70% | 100% | 100% |
+| 日誌规范 | 60% | 100% | 100% |
+
+---
+
+## 結論
+
+### 效果差異總結
+
+1. **互动性**：Skills > 规范文件（Skills 提供主动引導）
+2. **完整性**：规范文件 > Skills（规范文件涵蓋更多細节）
+3. **效率**：Skills > 规范文件（按需载入，token 消耗低）
+4. **靈活性**：规范文件 > Skills（可自订、可版本控制）
+5. **多工具支援**：规范文件 > Skills（Skills 僅限 Claude Code）
+
+### 最佳实踐建议
+
+```
+个人开发者 + Claude Code
+  └─ 推荐：僅 Skills（模式 A）
+     └─ 配置：standardsScope: minimal + Plugin Marketplace
+
+团队开发 + 混合工具
+  └─ 推荐：Skills + 规范文件（模式 C）
+     └─ 配置：standardsScope: full + Plugin Marketplace
+     └─ 规范文件納入 Git 管理
+
+企业環境 + 合規要求
+  └─ 推荐：僅规范文件（模式 B）
+     └─ 配置：standardsScope: full + 無 Skills
+     └─ 可完全離线使用
+```
+
+### 總体评价
+
+| 模式 | 適合对象 | 评分 |
+|------|---------|------|
+| 僅 Skills | 个人快速开发 | ★★★★☆ |
+| 僅规范文件 | 多工具团队/企业 | ★★★★☆ |
+| Skills + 规范文件 | 完整体驗/学习 | ★★★★★ |
+
+**結論**：三种模式各有優勢，选择取决於团队規模、工具組合、和合規要求。对於希望獲得最完整体驗的用戶，建议同时使用 Skills 与规范文件。
+
+---
+
+## 相关文件
+
+- [CLI 初始化选项](CLI-INIT-OPTIONS.md) - 完整 CLI 选项指南
+- [採用指南](../../../adoption/ADOPTION-GUIDE.md) - 标准採用指南
+- [Skills README](../../../skills/claude-code/README.md) - Claude Code Skills 文件
+
+---
+
+**由 Universal Dev Standards 团队維護**

package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md

@@ -0,0 +1,215 @@
+---
+source: ../../../docs/WINDOWS-GUIDE.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Windows 开发指南
+
+本指南提供使用和贡献 Universal Development Standards 的 Windows 特定说明。
+
+---
+
+## 先决条件
+
+### 必要
+
+- **Node.js** >= 18.0.0 ([下载](https://nodejs.org/))
+- **Git for Windows** ([下载](https://git-scm.com/download/win))
+  - 包含 Git Bash 用于执行 shell 脚本
+
+### 推荐
+
+- **Windows Terminal** - 更好的终端体验
+- **Visual Studio Code** - 跨平台编辑器
+- **PowerShell 7+** - 现代 PowerShell ([下载](https://github.com/PowerShell/PowerShell))
+
+---
+
+## 安装选项
+
+### 选项一：npm（推荐）
+
+```powershell
+npm install -g universal-dev-standards
+uds init
+```
+
+### 选项二：本地开发
+
+**PowerShell：**
+```powershell
+git clone https://github.com/AsiaOstrich/universal-dev-standards.git
+cd universal-dev-standards\cli
+npm install
+npm link
+```
+
+**Git Bash：**
+```bash
+git clone https://github.com/AsiaOstrich/universal-dev-standards.git
+cd universal-dev-standards/cli
+npm install
+npm link
+```
+
+---
+
+## 安装 Claude Code Skills
+
+**推荐：Plugin Marketplace**
+```bash
+/plugin marketplace add AsiaOstrich/universal-dev-standards
+/plugin install universal-dev-standards@asia-ostrich
+```
+
+**替代方案：手动复制（PowerShell）**
+```powershell
+New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.claude\skills
+Copy-Item -Recurse skills\claude-code\commit-standards $env:USERPROFILE\.claude\skills\
+```
+
+Skills 会安装到：`%USERPROFILE%\.claude\skills\`
+
+---
+
+## 翻译同步检查
+
+**PowerShell：**
+```powershell
+.\scripts\check-translation-sync.ps1
+
+# 带区域参数
+.\scripts\check-translation-sync.ps1 -Locale zh-TW
+```
+
+**Git Bash：**
+```bash
+./scripts/check-translation-sync.sh
+
+# 带区域参数
+./scripts/check-translation-sync.sh zh-TW
+```
+
+---
+
+## Git 钩子
+
+Git 钩子使用 Husky 设定，透过 Git Bash（包含在 Git for Windows 中）自动运作。不需要额外设定。
+
+当您在 `cli/` 目录执行 `npm install` 时，Husky 会自动设定 pre-commit 钩子。
+
+---
+
+## 常见问题与解决方案
+
+### 1. 脚本执行政策
+
+**问题：** 「此系统上已停用脚本执行」
+
+**解决方案：**
+```powershell
+# 以系统管理员身份执行 PowerShell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+### 2. 换行符问题
+
+储存库包含 `.gitattributes` 自动处理换行符。如果您遇到问题：
+
+```bash
+# 在 Git Bash 中
+git config core.autocrlf true
+git rm --cached -r .
+git reset --hard
+```
+
+### 3. 路径长度限制
+
+在 Git 中启用长路径：
+
+```bash
+git config --system core.longpaths true
+```
+
+### 4. PowerShell 版本
+
+- **Windows PowerShell** (v5.1) - 内建于 Windows
+- **PowerShell** (v7+) - 跨平台，推荐
+
+本专案的脚本在两个版本都能运作。
+
+### 5. npm 全域安装路径
+
+如果全域安装后找不到 `uds` 命令：
+
+```powershell
+# 检查 npm 全域 bin 路径
+npm config get prefix
+
+# 如需要，添加到 PATH（替换为您的实际路径）
+$env:PATH += ";C:\Users\YourName\AppData\Roaming\npm"
+```
+
+---
+
+## 环境变数
+
+CLI 支援 Unix 和 Windows 环境变数：
+
+| Unix | Windows | 说明 |
+|------|---------|------|
+| `$HOME` | `$env:USERPROFILE` | 主目录 |
+| `~/.claude/skills/` | `%USERPROFILE%\.claude\skills\` | Skills 位置 |
+
+---
+
+## 开发工作流程
+
+```powershell
+# 1. 克隆储存库
+git clone https://github.com/AsiaOstrich/universal-dev-standards.git
+cd universal-dev-standards
+
+# 2. 安装 CLI 依赖
+cd cli
+npm install
+
+# 3. 执行测试
+npm test
+
+# 4. 执行程序码检查
+npm run lint
+
+# 5. 连结以进行本地测试
+npm link
+
+# 6. 测试 CLI 命令
+uds list
+uds init --help
+```
+
+---
+
+## 终端推荐
+
+| 终端 | 最适合 | 备注 |
+|------|--------|------|
+| **Windows Terminal** | 日常使用 | 现代化，可自订 |
+| **Git Bash** | 执行 shell 脚本 | 类 Unix 环境 |
+| **PowerShell 7** | Windows 脚本 | 跨平台 |
+| **VS Code Terminal** | 开发 | 集成体验 |
+
+---
+
+## 相关文件
+
+- [主 README](../../README.md) - 专案概述
+- [CLI README](../../cli/README.md) - CLI 文件
+- [采用指南](../adoption/ADOPTION-GUIDE.md) - 完整采用指南
+
+---
+
+**需要协助？** 在 [GitHub Issues](https://github.com/AsiaOstrich/universal-dev-standards/issues) 开启 issue

package/bundled/locales/zh-CN/integrations/codex/AGENTS.md

@@ -0,0 +1,115 @@
+---
+source: ../../../../integrations/codex/AGENTS.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-13
+status: current
+---
+
+# 通用开发规范
+
+本项目遵循通用文档规范，以确保高质量、无幻觉的代码与文档。
+
+---
+
+## 规格驱动开发 (SDD) 优先
+
+**规则**：当项目中集成了 SDD 工具（如 OpenSpec、Spec Kit 等）并提供特定命令时，你必须优先使用这些命令，而非手动编辑文件。
+
+**检测方式**：
+- OpenSpec：检查是否有 `openspec/` 目录或 `openspec.json`
+- Spec Kit：检查是否有 `specs/` 目录或 `.speckit` 配置
+
+**原因**：
+- **一致性**：工具确保规格结构遵循严格的 schema
+- **可追溯性**：命令自动处理日志、ID 和链接
+- **安全性**：工具内建验证以防止无效状态
+
+参考：`core/spec-driven-development.md`
+
+---
+
+## 防幻觉协议
+
+参考：`core/anti-hallucination.md`
+
+### 1. 证据基础分析
+
+- 在分析文件之前，你必须先读取文件。
+- 不要猜测 API、类名或库版本。
+- 如果你还没看过代码，请说明：「我需要读取 [文件] 来确认」。
+
+### 2. 来源标注
+
+每个关于代码的事实陈述都必须标注来源：
+- 代码：`[来源: 代码] 路径/文件:行号`
+- 外部文档：`[来源: 外部] http://网址 (访问日期: 日期)`
+
+### 3. 确定性分类
+
+使用标签表示信心程度：
+- `[已确认]` - 已从来源验证
+- `[推论]` - 逻辑推论
+- `[假设]` - 合理假设
+- `[未知]` - 无法确定
+
+### 4. 建议
+
+当提供选项时，你必须明确说明「推荐」的选择及其理由。
+
+---
+
+## 文档与提交
+
+### Commit 消息
+
+遵循 Conventional Commits 格式（参考：`core/commit-message-guide.md`）：
+
+```
+<类型>(<范围>): <主题>
+
+<内文>
+
+<页脚>
+```
+
+**类型**：feat、fix、docs、chore、test、refactor、style
+
+### 文件结构
+
+遵循文档结构指南（参考：`core/documentation-structure.md`）。
+
+### 质量检查
+
+完成前，依据 `core/checkin-standards.md` 验证工作：
+- [ ] 代码编译成功
+- [ ] 所有测试通过
+- [ ] 无硬编码的秘密信息
+- [ ] 如适用，已更新文档
+
+---
+
+## 代码审查规范
+
+参考：`core/code-review-checklist.md`
+
+审查代码时，检查：
+1. **功能性** - 是否按预期运作？
+2. **安全性** - 无漏洞（OWASP Top 10）？
+3. **性能** - 算法和查询是否高效？
+4. **可维护性** - 代码是否整洁、易读？
+5. **测试** - 测试覆盖率是否足够？
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2026-01-09 | 初始 OpenAI Codex 集成 |
+
+---
+
+## 许可证
+
+本文档以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。