universal-dev-standards 4.1.0 → 4.2.0

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/docs/AI-AGENT-ROADMAP.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../docs/AI-AGENT-ROADMAP.md
-source_version: 2.2.0
-translation_version: 2.2.0
-last_synced: 2026-01-15
+source_version: 2.3.0
+translation_version: 2.3.0
+last_synced: 2026-01-22
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **语言**: [English](../../../docs/AI-AGENT-ROADMAP.md) | [繁體中文](../../zh-TW/docs/AI-AGENT-ROADMAP.md) | 简体中文
 
-**版本**: 2.2.0
-**最后更新**: 2026-01-15
+**版本**: 2.3.0
+**最后更新**: 2026-01-22
 
 本文档提供 Universal Development Standards (UDS) 对 AI Agent 支持的完整参考。
 
@@ -19,16 +19,57 @@ status: current
 
 ## 目录
 
-1. [快速参考](#1-快速参考)
-2. [集成深度](#2-集成深度)
-3. [Skills 系统](#3-skills-系统)
-4. [配置参考](#4-配置参考)
-5. [资源](#5-资源)
-6. [附录：未来发展](#附录未来发展)
+1. [UDS CLI 实现状态](#1-uds-cli-实现状态)
+2. [快速参考](#2-快速参考)
+3. [集成深度](#3-集成深度)
+4. [Skills 系统](#4-skills-系统)
+5. [配置参考](#5-配置参考)
+6. [资源](#6-资源)
+7. [附录：未来发展](#附录未来发展)
 
 ---
 
-## 1. 快速参考
+## 1. UDS CLI 实现状态
+
+> **重要**: 本节描述的是 UDS CLI 对各工具的实现状态，而非工具的原生能力。关于原生能力，请参阅[快速参考](#2-快速参考)。
+
+### 状态定义
+
+| 状态 | 定义 |
+|------|------|
+| `complete` | Skills + Commands 完整支持，已测试且生产就绪 |
+| `partial` | Skills 可用，Commands 受限或不支持 |
+| `preview` | 功能可用但为预览版，可能有边缘案例 |
+| `planned` | CLI 中代码存在但未完整测试 |
+| `minimal` | 仅生成规则文件，不支持 Skills/Commands |
+
+### 实现矩阵
+
+| AI 工具 | UDS 状态 | Skills | Commands | 配置文件 | 备注 |
+|---------|:--------:|:------:|:--------:|----------|------|
+| **Claude Code** | ✅ complete | ✅ | 内建 | `CLAUDE.md` | Marketplace + User + Project 三层级 |
+| **OpenCode** | ✅ complete | ✅ | ✅ | `AGENTS.md` | 完整实现，可读取 Claude 规则 |
+| Cline | 🔶 partial | ✅ | - | `.clinerules` | Skills 通过 fallback，Commands 使用 Workflow |
+| GitHub Copilot | 🔶 partial | ✅ | ✅ | `copilot-instructions.md` | 补充 Copilot Chat |
+| OpenAI Codex | 🔶 partial | ✅ | - | `AGENTS.md`（共享） | Skills 可用 |
+| Gemini CLI | 🧪 preview | ✅ | ✅ (TOML) | `GEMINI.md` | Commands 自动转换为 TOML |
+| Roo Code | ⏳ planned | ✅ | ✅ | - | 实现存在，待测试 |
+| Cursor | 📄 minimal | - | - | `.cursorrules` | 仅规则文件 |
+| Windsurf | 📄 minimal | - | - | `.windsurfrules` | 仅规则文件 |
+| Antigravity | 📄 minimal | - | - | `INSTRUCTIONS.md` | 仅规则文件 |
+
+### 两种「支持」的区别
+
+| 概念 | 定义 | 记录位置 |
+|------|------|----------|
+| **工具原生能力** | AI 工具本身支持什么功能 | [快速参考](#2-快速参考) |
+| **UDS CLI 实现** | UDS CLI 对该工具的实现程度 | 本节 |
+
+示例：Cursor 原生不支持 SKILL.md（工具能力），但 UDS CLI 可以为它生成 `.cursorrules`（实现状态 = minimal）。
+
+---
+
+## 2. 快速参考
 
 ### 配置文件
 
@@ -43,6 +84,7 @@ status: current
 | Windsurf | `.windsurfrules` | 设置 UI | 6K/文件，总计 12K |
 | Gemini CLI | `.gemini/GEMINI.md` | `~/.gemini/GEMINI.md` | 支持 `@import` |
 | Cursor | `.cursor/rules/*.mdc` | `~/.cursor/rules/` | 需要 YAML frontmatter |
+| Antigravity | `.antigravity/` | `~/.antigravity/` | 最低支持，手动模式 |
 
 ### Skills 路径
 
@@ -57,6 +99,7 @@ status: current
 | Windsurf | ✅ 完整 | `.windsurf/rules/` | 设置 UI | 2026/01 起支持 Skills |
 | Gemini CLI | ✅ 预览 | `.gemini/skills/` | `~/.gemini/skills/` | v0.23+ 预览版 |
 | Cursor | ❌ 否 | `.cursor/rules/` | `~/.cursor/rules/` | 仅 Rules，不支持 SKILL.md |
+| Antigravity | ❌ 否 | `.antigravity/skills/` | `~/.antigravity/skills/` | 不支持 SKILL.md |
 
 ### 斜杠命令
 
@@ -71,6 +114,7 @@ status: current
 | Windsurf | ✅ | Rulebook | 自动生成 | 从 `.windsurfrules` |
 | Gemini CLI | ✅ | 系统 + 自定义 | `/clear`, `/memory`, `/mcp` | `.gemini/commands/*.toml` |
 | Cursor | ✅ | 内建 + 自定义 | `/summarize`, `/models` | `.cursor/commands/*.md` |
+| Antigravity | ❌ | N/A | N/A | N/A |
 
 ### 平台支持
 
@@ -82,7 +126,7 @@ status: current
 
 ---
 
-## 2. 集成深度
+## 3. 集成深度
 
 > **说明**: 截至 2026 年 1 月，Agent Skills (SKILL.md) 已成为业界标准。大多数主流 AI 代码工具现在都支持相同的 Skills 格式。
 
@@ -111,11 +155,20 @@ status: current
 - 尚未支持 SKILL.md 格式
 - 社区已提出功能请求
 
+### 最低支持
+
+**工具**: Antigravity
+
+- 不支持 SKILL.md
+- 不支持 AGENT.md
+- 仅手动执行模式
+- 为完整性而收录
+
 ---
 
-## 3. Skills 系统
+## 4. Skills 系统
 
-### 3.1 UDS Skills 兼容性
+### 4.1 UDS Skills 兼容性
 
 | # | Skill | 斜杠命令 | Claude | OpenCode | Cursor | Copilot |
 |---|-------|----------|:------:|:--------:|:------:|:-------:|
@@ -138,7 +191,7 @@ status: current
 | 17 | project-structure-guide | `/config` | 完整 | 完整 | 部分 | 无 |
 | 18 | logging-guide | - | 完整 | 完整 | 完整 | 完整 |
 
-### 3.2 Skills 路径与启用
+### 4.2 Skills 路径与启用
 
 #### Skills 发现路径
 
@@ -153,6 +206,7 @@ status: current
 | Windsurf | `.windsurf/rules/` | 设置 UI | ✅ 是 |
 | Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` | ✅ 是 |
 | Cursor | `.cursor/rules/` | `~/.cursor/rules/` | ❌ 否 |
+| Antigravity | `.antigravity/skills/` | `~/.antigravity/skills/` | ❌ 否 |
 
 #### 启用方式
 
@@ -167,10 +221,11 @@ status: current
 | Windsurf | 手动（@提及）、始终开启、模型决定 |
 | Gemini CLI | 自动触发、通过设置启用/禁用 |
 | Cursor | Glob 模式、`alwaysApply` 标志（仅 rules） |
+| Antigravity | 仅手动 |
 
 **建议**：使用 `.claude/skills/` 作为默认安装路径 — 大多数工具都可读取以获得跨工具兼容性。
 
-### 3.3 跨平台可移植性
+### 4.3 跨平台可移植性
 
 > **业界标准**: 截至 2025 年 12 月，SKILL.md 已被 OpenAI、GitHub、Google 及更广泛的 AI 代码生态系统采用。
 
@@ -185,6 +240,7 @@ status: current
 | Windsurf | ✅ 完整 | 2026/01/09 |
 | Gemini CLI | ✅ 预览版 | 2026/01/07 |
 | Cursor | ❌ 尚未 | 已请求 |
+| Antigravity | ❌ 否 | N/A |
 
 **跨平台安装器**:
 - [skilz](https://github.com/skilz-ai/skilz) - 通用 Skills 安装器（14+ 平台）
@@ -193,9 +249,9 @@ status: current
 
 ---
 
-## 4. 配置参考
+## 5. 配置参考
 
-### 4.1 配置文件
+### 5.1 配置文件
 
 | AI Agent | 项目配置 | 全局配置 | 字符限制 |
 |----------|----------|----------|----------|
@@ -208,8 +264,9 @@ status: current
 | GitHub Copilot | `.github/copilot-instructions.md` | 个人设置 | ~8KB |
 | OpenAI Codex | `AGENTS.md` | `~/.codex/AGENTS.md` | 32KB |
 | Gemini CLI | `GEMINI.md` | `~/.gemini/GEMINI.md` | 1M tokens |
+| Antigravity | N/A | `~/.antigravity/` | N/A |
 
-### 4.2 配置合并行为
+### 5.2 配置合并行为
 
 | AI Agent | 合并策略 | 优先顺序（高到低） |
 |----------|----------|-------------------|
@@ -221,8 +278,9 @@ status: current
 | GitHub Copilot | 组合 | 个人 > 仓库 > 组织 |
 | OpenAI Codex | 串接 | 覆盖文件 > 基础，较近者优先 |
 | Gemini CLI | 串接 | 所有文件支持 `@import` |
+| Antigravity | N/A | N/A |
 
-### 4.3 Skills 文件格式
+### 5.3 Skills 文件格式
 
 > **标准格式**: 带有 YAML frontmatter 的 SKILL.md 是大多数工具支持的通用格式。
 
@@ -237,10 +295,11 @@ status: current
 | Windsurf | ✅ SKILL.md | `.windsurfrules` | YAML |
 | Gemini CLI | ✅ SKILL.md | `GEMINI.md` | YAML |
 | Cursor | ❌ `.mdc` | `.cursor/rules/` | YAML (globs, alwaysApply) |
+| Antigravity | ❌ N/A | N/A | N/A |
 
 ---
 
-## 5. 资源
+## 6. 资源
 
 ### 官方文档
 
@@ -304,6 +363,7 @@ status: current
 
 | 版本 | 日期 | 变更 |
 |------|------|------|
+| 2.3.0 | 2026-01-21 | 新增 Antigravity 至所有表格以与 CLI 保持一致 |
 | 2.2.0 | 2026-01-15 | 新增多 Agent 安装、Gemini CLI TOML 转换 |
 | 2.1.0 | 2026-01-15 | 更新所有工具的 Skills 支持状态（业界广泛采用） |
 | 2.0.0 | 2026-01-15 | 重大重构：整合内容、减少表格 |

package/bundled/locales/zh-CN/integrations/gemini-cli/GEMINI.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../../integrations/gemini-cli/GEMINI.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-01-13
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-01-24
 status: current
 ---
 
@@ -89,10 +89,42 @@ status: current
 
 ---
 
+## 重构指南
+
+参考：`core/refactoring-standards.md`
+
+### 三层策略
+
+| 层级 | 策略 | 时间尺度 |
+|------|------|----------|
+| **战术** | 童子军法则、准备性重构、红绿重构 | 分钟 |
+| **战略** | 绞杀者无花果、防腐层、分支抽象 | 周至月 |
+| **安全** | 特征测试、草稿重构、寻找接缝 | 前置作业 |
+
+### 决策树
+
+1. 在生产环境？否 → 考虑重写
+2. 理解代码？否 → 先写特征测试
+3. 覆盖率 >60%？否 → 先加测试
+4. 架构可挽救？否 → 绞杀者无花果；是 → 渐进重构
+
+### 快速参考
+
+| 情况 | 策略 |
+|------|------|
+| 功能被杂乱代码阻挡 | **准备性重构** |
+| 修 bug 的机会 | **童子军法则** |
+| 替换遗留系统 | **绞杀者无花果** |
+| 与遗留系统共存 | **防腐层** |
+| 未测试的遗留代码 | **先写特征测试** |
+
+---
+
 ## 版本历史
 
 | 版本 | 日期 | 变更 |
 |------|------|------|
+| 1.1.0 | 2026-01-21 | 新增重构指南章节 |
 | 1.0.0 | 2026-01-09 | 初始 Gemini CLI 指令文件 |
 
 ---