universal-dev-standards 4.1.0 → 5.0.0-beta.10

package/bundled/locales/zh-CN/core/ai-friendly-architecture.md

@@ -0,0 +1,306 @@
+# AI 友好架构标准
+
+> **语言**: [English](../../../core/ai-friendly-architecture.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-01-21
+**适用范围**: 所有与 AI 助手协作的软件项目
+
+---
+
+## 目的
+
+本标准定义能最大化 AI 辅助开发效能的架构与文档实践。遵循这些指南，项目将更容易被 AI 工具分析、理解和修改，同时保持人类可读性。
+
+**参考概念**:
+- RLM（递归语言模型）上下文管理原则
+- 考虑 Token 的文档设计
+- 支持 AI 理解的模块化架构
+
+---
+
+## 目录
+
+1. [核心原则](#核心原则)
+2. [模块设计标准](#模块设计标准)
+3. [上下文边界标记](#上下文边界标记)
+4. [文档分层](#文档分层)
+5. [元数据标准](#元数据标准)
+6. [查询接口设计](#查询接口设计)
+7. [AI 上下文配置](#ai-上下文配置)
+8. [反模式](#反模式)
+9. [实施清单](#实施清单)
+
+---
+
+## 核心原则
+
+### 1. 明确胜过隐含
+
+AI 助手在行为和结构明确记录时表现最佳，而非依赖惯例推测。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   明确 vs 隐含                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ❌ 隐含（AI 难以理解）                                      │
+│  └── 魔术命名惯例                                            │
+│  └── 未记录的文件夹结构                                      │
+│  └── 基于惯例的路由                                          │
+│  └── 假定框架行为已知                                        │
+│                                                              │
+│  ✅ 明确（AI 友好）                                          │
+│  └── 记录模块职责                                            │
+│  └── 清楚标注进入点                                          │
+│  └── 明确声明依赖关系                                        │
+│  └── 自我说明的配置文件                                      │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2. 分层上下文
+
+以层次结构组织文档，让 AI 可以根据任务复杂度存取适当的详细程度。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  上下文分层策略                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  第一层：快速参考（< 500 tokens）                            │
+│  └── 单行描述                                                │
+│  └── 仅 API 签名                                             │
+│  └── 关键进入点                                              │
+│                                                              │
+│  第二层：详细指南（< 5,000 tokens）                          │
+│  └── 完整 API 文档                                           │
+│  └── 使用范例                                                │
+│  └── 配置选项                                                │
+│                                                              │
+│  第三层：完整范例（无限制）                                  │
+│  └── 完整实现范例                                            │
+│  └── 边界案例文档                                            │
+│  └── 迁移指南                                                │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3. 语义边界
+
+设计清楚的模块边界，让 AI 可以独立分析组件，而不需要完整项目上下文。
+
+### 4. 可探索的结构
+
+确保项目结构可以通过分析配置文件和进入点来理解，而不需阅读所有源代码。
+
+---
+
+## 模块设计标准
+
+### 模块级别单一职责
+
+每个模块应有明确定义的单一目的，可以用一句话总结。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   模块头部模板                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  /**                                                         │
+│   * @module auth                                             │
+│   * @description 处理应用程序的用户验证和                    │
+│   *              Session 管理。                              │
+│   *                                                          │
+│   * @responsibility 验证和授权                               │
+│   * @dependencies [database, crypto, config]                │
+│   * @exports {login, logout, verify, refreshToken}          │
+│   * @entrypoint ./index.ts                                  │
+│   */                                                         │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 清楚的输入/输出契约
+
+每个公开接口都应有明确的类型定义或文档说明。
+
+| 元素 | 要求 | 范例 |
+|------|------|------|
+| 函数参数 | 类型 + 描述 | `@param {string} email - 用户电子邮件` |
+| 返回值 | 类型 + 可能值 | `@returns {Promise<User \| null>}` |
+| 副作用 | 明确记录 | `@sideeffect 写入数据库` |
+| 错误条件 | 所有可能错误 | `@throws {AuthError} 无效凭证` |
+
+### 明确的依赖声明
+
+依赖应在模块级别声明，而非隐藏在实现细节中。
+
+---
+
+## 上下文边界标记
+
+### 模块头部注释
+
+使用 AI 可以解析的标准化头部注释，快速理解模块。
+
+```javascript
+/**
+ * ═══════════════════════════════════════════════════════════
+ * 模块：付款处理
+ * ═══════════════════════════════════════════════════════════
+ *
+ * 用途：处理所有付款相关操作，包括
+ *       处理、退款和订阅管理。
+ *
+ * 依赖：
+ *   - stripe: 付款网关集成
+ *   - database: 交易存储
+ *   - events: 付款事件发布
+ *
+ * 导出：
+ *   - processPayment(amount, method): 处理单笔付款
+ *   - refund(transactionId): 发出退款
+ *   - createSubscription(plan): 开始订阅
+ *
+ * ═══════════════════════════════════════════════════════════
+ */
+```
+
+---
+
+## 文档分层
+
+### 第一层：快速参考（< 500 tokens）
+
+在每个主要模块创建 `QUICK-REF.md`：
+
+```markdown
+# Auth 模块 - 快速参考
+
+## 用途
+用户验证和 Session 管理。
+
+## 关键函数
+- `login(email, password)` → `Promise<Session>`
+- `logout(sessionId)` → `void`
+- `verify(token)` → `Promise<User | null>`
+
+## 配置
+- `AUTH_SECRET`: JWT 签名密钥
+- `SESSION_DURATION`: Session 生命周期（默认：24h）
+
+## 进入点
+`src/auth/index.ts`
+```
+
+### 第二层：详细指南（< 5,000 tokens）
+
+主要 `README.md` 包含完整文档。
+
+### 第三层：完整范例（无限制）
+
+独立的 `examples/` 目录包含完整实现。
+
+---
+
+## 元数据标准
+
+### .ai-context.yaml 配置
+
+专用的 AI 上下文配置文件：
+
+```yaml
+# .ai-context.yaml - AI 上下文配置
+version: 1.0.0
+
+project:
+  name: my-project
+  type: web-app  # web-app | library | cli | api | monorepo
+  primary-language: typescript
+
+modules:
+  - name: auth
+    path: src/auth/
+    entry: index.ts
+    description: 验证和授权
+    dependencies: [database, crypto]
+    priority: high
+
+analysis-hints:
+  entry-points:
+    - src/main.ts
+  ignore-patterns:
+    - node_modules
+    - dist
+
+context-strategy:
+  max-chunk-size: 50000
+  overlap: 500
+  analysis-pattern: hierarchical
+```
+
+---
+
+## 反模式
+
+### ❌ 应避免的模式
+
+| 反模式 | 问题 | 解决方案 |
+|--------|------|----------|
+| **魔术字符串** | AI 无法追踪常量 | 使用有文档的类型常量 |
+| **隐含路由** | 隐藏行为 | 明确记录路由映射 |
+| **全局状态** | 不可预测的依赖 | 依赖注入，明确连接 |
+| **循环依赖** | 上下文混乱 | 清楚的层次依赖 |
+| **巨大文件** | 上下文溢出 | 分割成专注的模块 |
+
+---
+
+## 实施清单
+
+### 快速开始（< 1 小时）
+
+- [ ] 创建 `.ai-context.yaml` 包含模块清单
+- [ ] 在项目根目录新增 `QUICK-REF.md`
+- [ ] 在 README 中记录进入点
+- [ ] 在主要文件中新增模块头部
+
+### 标准实施（< 1 天）
+
+- [ ] 完成 `.ai-context.yaml` 配置
+- [ ] 为每个主要模块新增 `QUICK-REF.md`
+- [ ] 记录所有公开 API 的类型信息
+- [ ] 在大型文件中新增区段分隔
+- [ ] 创建依赖文档
+
+### 完整实施（< 1 周）
+
+- [ ] 所有模块的三层文档
+- [ ] 可搜索的代码注释
+- [ ] 使用案例的范例目录
+- [ ] 架构图
+- [ ] 集成 CI 进行文档验证
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2026-01-21 | 初始版本 |
+
+---
+
+## 相关标准
+
+- [项目结构](./project-structure.md) - 目录组织
+- [文档结构](./documentation-structure.md) - 文档组织
+- [反幻觉](./anti-hallucination.md) - AI 准确性标准
+
+---
+
+## 许可
+
+本标准以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。
+
+**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

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

@@ -1,5 +1,5 @@
 ---
-source: core/ai-instruction-standards.md
+source: ../../../core/ai-instruction-standards.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2026-01-14

package/bundled/locales/zh-CN/core/anti-hallucination.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/anti-hallucination.md
-source_version: 1.4.0
-translation_version: 1.4.0
-last_synced: 2026-01-19
+source_version: 1.5.0
+translation_version: 1.5.0
+last_synced: 2026-02-10
 status: current
 ---
 
@@ -227,6 +227,42 @@ React useState 的运作方式是...（无版本，无引用）
 使用者需要 SSO 支援（假设以已确认需求呈现）
 ```
 
+#### 统一标签系统
+
+本标准定义两类互补的标签类别，用于相关标准：
+
+**类别 1：确定性标签**（用于分析现有内容）
+
+用于分析程序码、审查文件或讨论系统时。参见[反向工程标准](reverse-engineering-standards.md)。
+
+| 标签 | 用途 | 范例情境 |
+|-----|------|---------|
+| `[已确认]` | 直接来自程序码/文件的证据 | 程序码分析、测试提取 |
+| `[推测]` | 基于模式的逻辑推论 | 行为分析、架构审查 |
+| `[假设]` | 需验证的合理猜测 | 缺口识别、推测 |
+| `[未知]` | 无法从现有资讯判断 | 缺少文件 |
+| `[需确认]` | 需要人类输入 | 模糊的需求 |
+
+**类别 2：推导标签**（用于生成新内容）
+
+用于从已核准来源生成测试、规格或文件时。参见[正向推演标准](../../../core/forward-derivation-standards.md)。
+
+| 标签 | 用途 | 范例情境 |
+|-----|------|---------|
+| `[来源]` | 直接来自规格/需求的内容 | SPEC 标题、AC 文字原文 |
+| `[推导]` | 从来源内容转换而来 | 从条列 AC 转换的 GWT |
+| `[生成]` | AI 生成的结构 | 测试骨架、TODO 注解 |
+| `[待办]` | 需要人类实作 | Step definitions、断言 |
+
+**何时使用哪种**：
+
+| 工作流程 | 主要标签 | 次要标签 |
+|----------|---------|---------|
+| 程序码分析 | 确定性标签 | - |
+| 反向工程 | 确定性标签 | - |
+| 正向推演 | 推导标签 | 确定性标签（用于缺口）|
+| 规格生成 | 推导标签 | 确定性标签（用于未知）|
+
 ---
 
 ### 4. 禁止行为

package/bundled/locales/zh-CN/core/checkin-standards.md

@@ -1,5 +1,5 @@
 ---
-source: core/checkin-standards.md
+source: ../../../core/checkin-standards.md
 source_version: 1.4.0
 translation_version: 1.4.0
 last_synced: 2026-01-16
@@ -67,10 +67,12 @@ pip install -r requirements.txt && python -m py_compile src/**/*.py
 
 ### 2. 测试验证
 
-- [ ] **所有现有测试通过**
-  - Unit tests: 100% pass rate
-  - Integration tests: 100% pass rate
-  - End-to-end tests (if applicable): 100% pass rate
+- [ ] **所有相关测试通过**
+  - 单元测试：已修改模组的所有测试通过
+  - 集成测试：与已变更元件相关的所有测试通过
+  - 端对端测试（如适用）：所有关键路径测试通过
+
+  > **注意**：「相关测试」指直接执行已变更程序码的测试，以及可能受变更影响的测试。如有可用的测试影响分析工具，请使用。
 
 - [ ] **新程序码已测试**
   - New features have corresponding tests
@@ -227,6 +229,17 @@ def authenticate(username: str, password: str) -> Optional[str]:
     """
 ```
 
+#### 适用性判断标准
+
+使用此表格判断选用项目何时适用：
+
+| 项目 | 何时适用 | 何时不适用 |
+|------|---------|-----------|
+| **README 更新** | 新增功能、设定变更、API 行为变更 | 内部重构、仅测试变更、依赖更新 |
+| **CHANGELOG 条目** | 使用者可见的变更、影响使用者的错误修复、重大变更 | 内部重构、仅测试变更、仅文件变更、开发依赖更新 |
+| **端对端测试** | 使用者流程变更、关键路径受影响、集成点修改 | 纯后端变更且无 UI 影响、独立的工具函数 |
+| **API 文档** | 公开 API 变更、新增端点、参数含义变更 | 私有方法、内部工具、测试程序码 |
+
 ---
 
 ### 5. 工作流程合规

package/bundled/locales/zh-CN/core/commit-message-guide.md

@@ -120,7 +120,7 @@ a different JSON structure. See migration guide.
 ## 相关标准
 
 - [Git 工作流程](git-workflow.md)
-- [代码审查指南](code-review-guide.md)
+- [代码审查指南](code-review-checklist.md)
 
 ---