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

package/bundled/locales/zh-CN/ai/standards/testing.ai.yaml

@@ -0,0 +1,137 @@
+# 测试标准 - AI 优化版
+# 来源: core/testing-standards.md
+
+id: testing
+meta:
+  version: "1.3.0"
+  updated: "2025-12-30"
+  source: core/testing-standards.md
+  description: 测试金字塔与建议的覆蓋率比例，支援框架选项
+  language: zh-CN
+
+# 框架选择 - 根据项目需求选择
+# 參考来源: ISTQB Glossary v4.0, Martin Fowler's Testing Pyramid
+framework_options:
+  decision_point: 根据项目类型选择测试框架
+  choices:
+    - id: istqb-framework
+      file: options/testing/istqb-framework.ai.yaml
+      best_for: 企业项目、认证需求、正式 QA 流程
+    - id: industry-pyramid
+      file: options/testing/industry-pyramid.ai.yaml
+      best_for: 敏捷开发、CI/CD 优化、快速迭代
+
+# 预设金字塔 (业界标准 - 可由框架选择覆蓋)
+pyramid:
+  ratio: "70/20/10"
+  note: "业界标准比例。ISTQB 框架使用 4 层但無固定比例。"
+  levels:
+    - name: 单元测试 (UT)
+      percentage: 70
+      scope: 单一函式/方法
+      speed: 非常快 (<100ms)
+    - name: 集成测试 (IT/SIT)
+      percentage: 20
+      scope: 多个元件
+      speed: 快速 (<1s)
+      note: "IT (敏捷/DevOps) 或 SIT (企业/ISTQB) - 兩者都指集成测试"
+    - name: 端对端测试 (E2E)
+      percentage: 10
+      scope: 使用者流程/系统测试
+      speed: 較慢 (>10s)
+
+options:
+  testing_framework:
+    description: 选择测试框架方法
+    multiSelect: false
+    choices:
+      - id: istqb-framework
+        file: options/testing/istqb-framework.ai.yaml
+      - id: industry-pyramid
+        file: options/testing/industry-pyramid.ai.yaml
+  test_level:
+    description: 选择要实施的测试层级
+    multiSelect: true
+    choices:
+      - id: unit-testing
+        file: options/testing/unit-testing.ai.yaml
+      - id: integration-testing
+        file: options/testing/integration-testing.ai.yaml
+      - id: system-testing
+        file: options/testing/system-testing.ai.yaml
+      - id: e2e-testing
+        file: options/testing/e2e-testing.ai.yaml
+      - id: security-testing
+        file: options/testing/security-testing.ai.yaml
+        best_for: 处理敏感数据的应用程序、安全关鍵系统
+      - id: performance-testing
+        file: options/testing/performance-testing.ai.yaml
+        best_for: 高流量应用程序、即时系统、API
+      - id: contract-testing
+        file: options/testing/contract-testing.ai.yaml
+        best_for: 微服务、API 集成、分散式系统
+
+rules:
+  - id: follow-pyramid
+    trigger: 規划测试策略时
+    instruction: 遵循 70/20/7/3 的单元/集成/系统/端对端比例
+    priority: required
+
+  - id: first-principles
+    trigger: 撰写测试时
+    instruction: 遵循 FIRST 原則（快速、獨立、可重複、自我验证、及时）
+    priority: required
+
+  - id: arrange-act-assert
+    trigger: 組織测试结构时
+    instruction: 使用 Arrange-Act-Assert 模式
+    priority: required
+
+  - id: meaningful-names
+    trigger: 命名测试时
+    instruction: 使用描述性的测试名称，说明测试内容
+    priority: required
+    examples:
+      good:
+        - "should_return_user_when_valid_id_provided"
+        - "test_login_fails_with_invalid_credentials"
+      bad:
+        - "test1"
+        - "testLogin"
+
+  - id: test-boundaries
+    trigger: 选择测试内容时
+    instruction: 專注於邊界条件和邊緣案例
+    priority: recommended
+
+  - id: avoid-test-doubles-overuse
+    trigger: 使用 mocks/stubs 时
+    instruction: 謹慎使用测试替身；當速度足夠快时，優先使用真实实作
+    priority: recommended
+
+quick_reference:
+  test_pyramid:
+    columns: [层级, 百分比, 範圍, 速度]
+    rows:
+      - [单元, 70%, 单一函式, <100ms]
+      - [集成, 20%, 多个元件, <1s]
+      - [系统, 7%, 完整系统, <10s]
+      - [端对端, 3%, 使用者流程, ">10s"]
+
+  first_principles:
+    columns: [原則, 说明]
+    rows:
+      - [快速 (Fast), 测试执行迅速]
+      - [獨立 (Independent), 测试之间無相依性]
+      - [可重複 (Repeatable), 每次执行結果相同]
+      - [自我验证 (Self-validating), 通過/失败無需人工检查]
+      - [及时 (Timely), 与程序码同步撰写]
+
+  test_doubles:
+    columns: [类型, 用途, 使用时机]
+    rows:
+      - [Stub, 回传预设值, 簡单相依性]
+      - [Mock, 验证互动, 複雜相依性]
+      - [Fake, 簡化实作, 数据庫/外部服务]
+      - [Spy, 记录呼叫, 验证行为]
+      - [Dummy, 填充參數, 未使用的參數]

package/bundled/locales/zh-CN/ai/standards/versioning.ai.yaml

@@ -0,0 +1,211 @@
+# 語意化版本标准 - AI 优化版
+# 来源: core/versioning.md
+
+id: versioning
+meta:
+  version: "1.2.0"
+  updated: "2025-12-30"
+  source: core/versioning.md
+  description: 软体發布的語意化版本 (SemVer)
+  language: zh-CN
+
+format:
+  template: "MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]"
+  examples:
+    - "2.3.1"
+    - "1.0.0-alpha.1"
+    - "3.2.0-beta.2+20250112"
+
+components:
+  major:
+    purpose: 破壞性变更
+    when_to_increment:
+      - 不相容的 API 变更
+      - 移除已棄用功能
+      - 重大架構变更
+    guidelines:
+      - 重设 MINOR 和 PATCH 为 0
+      - 记录迁移指南
+      - 在前一个 MINOR 版本提供棄用警告
+
+  minor:
+    purpose: 新功能
+    when_to_increment:
+      - 新增向後相容的功能
+      - 棄用功能（非移除）
+      - 重大內部改进
+    guidelines:
+      - 重设 PATCH 为 0
+      - 既有功能不变
+      - 新功能是选择性的
+
+  patch:
+    purpose: Bug 修正
+    when_to_increment:
+      - Bug 修正（無新功能）
+      - 安全修補
+      - 文件更正
+      - 內部重構（無 API 变更）
+    guidelines:
+      - 無新功能
+      - 無 API 变更
+      - 可以安全立即更新
+
+prerelease:
+  identifiers:
+    - id: alpha
+      purpose: 早期测试
+      stability: 不穩定
+      audience: 內部团队
+
+    - id: beta
+      purpose: 功能完整
+      stability: 大致穩定
+      audience: 早期採用者
+
+    - id: rc
+      purpose: 最終测试（發布候選）
+      stability: 穩定
+      audience: Beta 测试者
+
+  ordering: "alpha < beta < rc < stable"
+
+initial_development:
+  version_0:
+    description: 主版本 0 表示开发阶段
+    guidelines:
+      - API 可能頻繁变更
+      - MINOR 版本允許破壞性变更
+      - API 穩定时升至 1.0.0
+
+deprecation:
+  timeline:
+    internal_api: 1 个 minor 版本
+    partner_api: 2 个 minor 版本 + 3 个月
+    public_api: 2 个 minor 版本 + 6 个月
+    critical_infrastructure: 至少 1 年
+
+  backward_compatibility:
+    breaking_changes:
+      - 移除公開 API 端点
+      - 移除必要请求欄位
+      - 新增必要请求欄位
+      - 变更响应欄位类型
+      - 变更错误码含義
+      - 移除使用者依賴的响应欄位
+
+    safe_changes:
+      - 新增選用请求欄位
+      - 新增响应欄位
+      - 新增端点
+      - 新增错误码
+      - 改善错误消息
+      - 效能改进
+
+api_versioning_strategies:
+  - strategy: URL 路徑
+    format: "/api/v1/users"
+    pros: 清楚、易於路由
+    cons: URL 污染
+    recommended: true
+
+  - strategy: 查詢參數
+    format: "/api/users?version=1"
+    pros: 選用版本控制
+    cons: 快取問題
+
+  - strategy: Header
+    format: "Accept: application/vnd.api.v1+json"
+    pros: 乾淨的 URL
+    cons: 較不可見
+
+release_process:
+  phases:
+    - phase: 1
+      name: 發布前診斷
+      mandatory: true
+      check_items:
+        - 系统工具版本
+        - 必要驅动程序
+        - 磁碟空间
+        - 数据庫連线
+        - 应用程序版本
+        - 设置完整性
+
+    - phase: 2
+      name: 環境准备
+      purpose: 安裝缺少的工具和驅动程序
+
+    - phase: 3
+      name: 套件产生
+      naming: "{PROJECT}-upgrade-v{VERSION}-{DATE}.tar.gz"
+
+    - phase: 4
+      name: 部署执行
+      steps:
+        - 上传升级套件
+        - 解壓套件
+        - 試运行测试（強烈建议）
+        - 实际升级
+
+    - phase: 5
+      name: 發布後验证
+      check_items:
+        - 服务正常运作
+        - API 回传正确版本
+        - 日誌無致命错误
+        - 功能验证通過
+
+rules:
+  - id: semver-compliance
+    trigger: 發布新版本时
+    instruction: 严格遵循語意化版本格式
+    priority: required
+
+  - id: deprecation-warning
+    trigger: 規划破壞性变更时
+    instruction: 在移除前 N-1 版本加入棄用警告
+    priority: required
+
+  - id: migration-guide
+    trigger: 發布 MAJOR 版本时
+    instruction: 记录迁移指南，附前後对照範例
+    priority: required
+
+  - id: changelog-update
+    trigger: 發布任何版本时
+    instruction: 更新 CHANGELOG.md 记录所有重要变更
+    priority: required
+
+  - id: pre-release-diagnosis
+    trigger: 開始發布流程时
+    instruction: 不得跳過診斷阶段
+    priority: required
+
+  - id: dry-run-test
+    trigger: 部署升级时
+    instruction: 不得跳過試运行测试
+    priority: required
+
+quick_reference:
+  version_components:
+    columns: [組成, 用途, 重设]
+    rows:
+      - [MAJOR, 破壞性变更, "MINOR=0, PATCH=0"]
+      - [MINOR, 新功能, "PATCH=0"]
+      - [PATCH, Bug 修正, 無]
+
+  prerelease_order:
+    columns: [識别码, 穩定度, 受眾]
+    rows:
+      - [alpha, 不穩定, 內部团队]
+      - [beta, 大致穩定, 早期採用者]
+      - [rc, 穩定, Beta 测试者]
+
+  deprecation_periods:
+    columns: [API 类型, 最短期间]
+    rows:
+      - [內部 API, 1 个 minor 版本]
+      - [合作夥伴 API, 2 个 minor + 3 个月]
+      - [公開 API, 2 个 minor + 6 个月]
+      - [关鍵基礎设施, 1 年]

package/bundled/locales/zh-CN/core/ai-instruction-standards.md

@@ -0,0 +1,213 @@
+---
+source: core/ai-instruction-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-14
+status: current
+---
+
+# AI 指令文件规范
+
+> **语言**: [English](../../../core/ai-instruction-standards.md) | [简体中文](../../zh-TW/core/ai-instruction-standards.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-01-14
+**适用范围**: 所有使用 AI 编码助手的项目
+
+---
+
+## 目的
+
+本规范定义创建和维护 AI 指令文件（又称「系统提示词文件」）的最佳实践。这些文件引导 AI 助手理解项目特定的惯例、标准和工作流程。
+
+---
+
+## 支持的 AI 工具
+
+| AI 工具 | 指令文件 | 格式 |
+|---------|---------|------|
+| Claude Code | `CLAUDE.md` | Markdown |
+| Cursor | `.cursorrules` | Markdown |
+| Windsurf | `.windsurfrules` | Markdown |
+| Cline | `.clinerules` | Markdown |
+| GitHub Copilot | `.github/copilot-instructions.md` | Markdown |
+| OpenCode | `.opencode/instructions.md` | Markdown |
+
+---
+
+## 核心原则：通用与专用分离
+
+### 为什么要分离？
+
+AI 指令文件通常混合两种类型的内容：
+1. **通用规则**：适用于任何项目
+2. **项目专用配置**：专属于你的项目
+
+分离这些内容可以改善：
+- **可携性**：通用区段可在项目间重复使用
+- **可维护性**：更容易更新而不会意外「泄漏」
+- **清晰性**：用户知道采用标准时需要自定义哪些部分
+
+---
+
+## 文件结构
+
+### 建议的布局
+
+```markdown
+# [项目名称] - AI 指令
+
+## 通用标准
+<!-- 适用于任何项目的规则 -->
+- Commit 消息格式
+- 代码审查清单
+- 测试标准
+- 反幻觉规则
+
+---
+
+## 项目专用配置
+<!-- 专属于本项目 - 采用时需自定义 -->
+
+### 技术栈
+[你的技术在这里]
+
+### 快速指令
+[你的构建/测试/部署指令]
+
+### 文件结构
+[你的项目结构]
+
+### 发布流程
+[你的发布工作流程]
+```
+
+---
+
+## 内容指南
+
+### 通用内容（不要包含项目特定细节）
+
+| 类别 | 示例 |
+|------|------|
+| **Commit 标准** | Conventional Commits 格式、消息结构 |
+| **代码审查** | 审查清单、注释前缀 |
+| **测试** | 测试金字塔比例、命名惯例 |
+| **AI 行为** | 反幻觉规则、来源标注 |
+| **文档** | 写作风格、结构指南 |
+
+**在通用区段中避免：**
+- 特定指令（例如：`npm test`、`pytest`）
+- 硬编码路径（例如：`cli/src/`、`/var/www/`）
+- 版本号（例如：`Node.js 18`、`Python 3.11`）
+- 项目名称和 URL
+
+### 项目专用内容（明确标记这些区段）
+
+| 类别 | 示例 |
+|------|------|
+| **技术栈** | 编程语言、框架、版本 |
+| **指令** | 构建、测试、lint、部署指令 |
+| **文件结构** | 目录布局、关键文件 |
+| **发布流程** | 版本文件、部署步骤 |
+| **团队惯例** | 语言偏好、命名模式 |
+
+---
+
+## 标记惯例
+
+使用明确的标记来区分内容类型：
+
+### 选项 A：区段标题
+
+```markdown
+## 通用标准
+[通用内容]
+
+## 项目专用配置
+[项目专用内容]
+```
+
+### 选项 B：行内标记
+
+```markdown
+> ⚠️ **项目专用**：此区段包含专属于本项目的配置。
+
+### 技术栈
+...
+```
+
+### 选项 C：注释标注
+
+```markdown
+<!-- 通用：以下适用于所有项目 -->
+### Commit 消息格式
+...
+
+<!-- 项目专用：为你的项目自定义 -->
+### 快速指令
+...
+```
+
+---
+
+## 维护检查清单
+
+在提交 AI 指令文件的变更之前：
+
+- [ ] **通用区段**：无项目特定的路径、指令或版本
+- [ ] **项目专用区段**：已用标签明确标记
+- [ ] **交叉引用**：指向标准文档的链接正确
+- [ ] **一致性**：格式与现有区段一致
+
+### 泄漏检测
+
+执行此检查以找出通用区段中可能的项目特定内容泄漏：
+
+```bash
+# 示例：在通用区段中找出硬编码指令
+grep -n "npm\|yarn\|pip\|cargo" CLAUDE.md | head -20
+```
+
+审查每个匹配项，确保它在项目专用区段中。
+
+---
+
+## 快速参考卡
+
+### 通用 vs 项目专用
+
+| 类型 | 包含 | 示例 |
+|------|------|------|
+| **通用** | 通用规则 | 「提交前执行测试」 |
+| **项目专用** | 具体指令 | 「提交前执行 `npm test`」 |
+
+### 区段标记
+
+| 标记 | 含义 |
+|------|------|
+| `## 通用` | 适用于任何项目 |
+| `## 项目专用` | 专属于本项目 |
+| `> ⚠️ 项目专用` | 特定区段的行内警告 |
+
+---
+
+## 相关标准
+
+- [文档结构](documentation-structure.md)
+- [文档写作标准](documentation-writing-standards.md)
+- [反幻觉指南](anti-hallucination.md)
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2026-01-14 | 初始发布 |
+
+---
+
+## 许可证
+
+本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。