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

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

@@ -0,0 +1,691 @@
+---
+source: ../../../core/anti-hallucination.md
+source_version: 1.3.1
+translation_version: 1.3.1
+last_synced: 2025-12-25
+status: current
+---
+
+# AI 协作防幻觉标准
+
+> **语言**: [English](../../../core/anti-hallucination.md) | 繁体中文
+
+**版本**: 1.3.1
+**最后更新**: 2025-12-24
+**适用范围**: 所有使用 AI 助理协作的软体专案
+
+---
+
+## 目的
+
+本标准定义 AI 助理的严格准则，以防止在分析程序码、提出建议或撰写系统文件时产生幻觉（生成错误或未经验证的资讯）。
+
+---
+
+## AI 助手互动规范
+
+### 对话语言
+
+AI 助手应适应使用者的偏好语言。当专案指定对话语言时，请遵循以下准则:
+
+| 情境 | 准则 | 范例 |
+|------|------|------|
+| 对话互动 | 使用专案指定语言 | 繁体中文、英文等 |
+| 确定性标签 | 使用专案指定语言 | `[已确认]` 或 `[Confirmed]` |
+| 错误讯息解释 | 使用专案指定语言 | 以使用者语言解释编译/执行错误 |
+| 技术术语 | 保留原文 | JWT、BCrypt、API、Token |
+| 程序码注解 | 遵循专案惯例 | 通常为英文 |
+| Commit 讯息 | 遵循专案惯例 | 如 `feat(auth): 新增登入功能` |
+
+### 选项建议原则
+
+**规则**: 当提供多个选项时，必须同时提出最推荐的选项并说明理由。
+
+| 情境 | 要求 | 范例 |
+|------|------|------|
+| 提供 2+ 选项 | 必须明确标示推荐选项并说明理由 | 「推荐选项 A，因为...」 |
+| 选项优劣明显 | 直接推荐最佳选项，说明理由 | 「建议使用 BCrypt，因为安全性较高」 |
+| 选项各有优劣 | 推荐最适合当前情境的选项，说明权衡考量 | 「考量专案需求，推荐选项 B」 |
+| 无法判断优劣 | 说明需要哪些资讯才能给出推荐 | 「需要确认效能需求才能推荐」 |
+
+**范例**:
+
+❌ **错误**:
+```
+有三个选项:
+1. 使用 Redis 快取
+2. 使用记忆体快取
+3. 使用档案快取
+
+请选择一个。
+```
+
+✅ **正确**:
+```
+有三个选项:
+1. 使用 Redis 快取
+2. 使用记忆体快取
+3. 使用档案快取
+
+**推荐: 选项 1 (Redis)**: 考量专案已有 Redis 基础设施且需要跨实例共享快取，Redis 是最适合的选择。
+```
+
+### 下一步建议
+
+**规则**: 当完成一项任务或子任务时，AI 助手**必须**建议合理的下一步工作，并明确标示**最推荐**的选项。
+
+**指引**:
+- **主动性**: 不要等待使用者问「接下来呢？」。
+- **情境相关**: 建议应遵循专案的工作流程（如：提案 -> 实作 -> 测试）。
+- **明确推荐**: 使用 `[推荐]` 或 `[Recommended]` 标示最佳路径。
+
+**范例**:
+
+✅ **正确**:
+```
+任务完成: API 端点已实作。
+
+**建议下一步**:
+1. **[推荐]** 为新端点新增单元测试 (`src/tests/api/`)
+2. 更新 API 文件 (`docs/api-reference.md`)
+3. 开始前端集成
+```
+
+---
+
+## 核心原则
+
+### 1. 仅基于证据的分析
+
+**规则**: 仅分析和引用已明确提供或读取的内容。
+
+**指引**:
+- ✅ 分析已使用档案读取工具读取的程序码档案
+- ✅ 引用已撷取的文件
+- ✅ 引用已检查的设定档
+- ❌ 不要推测未见过的 API、函式或设定
+- ❌ 不要在未验证的情况下假设框架行为
+- ❌ 不要捏造需求细节
+
+**范例**:
+
+✅ **正确**:
+```
+[证据] 在 src/auth/service.ts:45，JWT 验证逻辑使用 'jsonwebtoken' 函式库
+[证据] package.json 档案（第 12-18 行）列出 Express 4.18.2 作为相依项目
+```
+
+❌ **错误**:
+```
+此系统使用 Redis 进行快取（程序码未审查）
+UserService 应该有 authenticate() 方法（API 未验证）
+需求指出我们需要 SSO 登入支援（需求未确认）
+```
+
+---
+
+### 2. 明确来源标注
+
+**规则**: 所有引用必须包含来源类型、位置与可验证性资讯。
+
+#### 2.1 来源类型
+
+| 来源类型 | 标签 | 说明 | 可靠度 |
+|---------|------|------|--------|
+| 专案程序码 | `[来源: 程序码]` | 直接从程序码库读取 | ⭐⭐⭐⭐⭐ 最高 |
+| 专案文件 | `[来源: 文件]` | README、Wiki、程序码注解 | ⭐⭐⭐⭐ 高 |
+| 外部文件 | `[来源: 外部]` | 官方文件（附 URL） | ⭐⭐⭐⭐ 高 |
+| 网路搜寻 | `[来源: 搜寻]` | 搜寻结果（包含日期） | ⭐⭐⭐ 中 |
+| AI 知识 | `[来源: 知识]` | AI 训练资料（需验证） | ⭐⭐ 低 |
+| 使用者提供 | `[来源: 使用者]` | 使用者对话中的资讯 | ⭐⭐⭐ 中 |
+
+#### 2.2 标注格式
+
+**程序码引用**:
+```
+[来源: 程序码] 档案路径:行号 - 描述
+```
+
+**外部文件**:
+```
+[来源: 外部] URL - 描述（版本: x.x.x，存取: YYYY-MM-DD）
+```
+
+**AI 知识**:
+```
+[来源: 知识] 主题 - 描述（⚠️ 需要验证）
+```
+
+#### 2.3 范例
+
+✅ **正确**:
+```
+[来源: 程序码] UserService.cs:142 - 密码杂凑使用 BCrypt
+[来源: 程序码] app.config:23-28 - 资料库连线字串设定为 SQL Server
+[来源: 文件] README.md:15 - 专案需要 .NET 8.0 SDK
+[来源: 外部] https://react.dev/reference/react/useState - useState hook API（版本: React 18，存取: 2025-12-10）
+[来源: 搜寻] "Express.js middleware order" - 中介软体依注册顺序执行（搜寻: 2025-12-10）
+[来源: 知识] HTTP 状态码 - 404 表示资源未找到（⚠️ 一般知识，请验证您的 API）
+[来源: 使用者] 使用者在对话中表示 - 验证必须支援 OAuth2
+```
+
+❌ **错误**:
+```
+验证服务使用 BCrypt（无来源类型，无档案引用）
+设定档案中某处有资料库连线（模糊引用）
+我认为 README 提到 .NET 8（不确定语言，无来源）
+React useState 的运作方式是...（无版本，无引用）
+```
+
+#### 2.4 版本敏感性
+
+**规则**: 引用函式库、框架或 API 时，必须包含版本资讯（如有）。
+
+**为何重要**:
+- API 在不同版本间会改变
+- 已弃用的功能可能仍出现在 AI 训练资料中
+- 安全性漏洞是版本特定的
+
+**范例**:
+```
+✅ [来源: 外部] Next.js App Router (v14.x) - Server Components 是预设值
+✅ [来源: 程序码] package.json:12 - 使用 "express": "^4.18.2"
+❌ "Next.js 使用 Server Components"（哪个版本？v12 和 v14 行为不同）
+```
+
+---
+
+### 3. 分类确定性等级
+
+**规则**: 明确区分已确认事实、推测与未知事项。
+
+**分类标签**:
+
+| 标签 | 使用时机 |
+|-----|---------|
+| `[已确认]` | 直接来自程序码/文件的证据 |
+| `[推测]` | 基于现有证据的逻辑推论 |
+| `[假设]` | 基于常见模式（需验证）|
+| `[未知]` | 资讯不可得 |
+| `[需确认]` | 需要使用者澄清 |
+
+**范例**:
+
+✅ **正确**:
+```
+[已确认] src/database/connection.ts:12 - 使用 PostgreSQL 驱动程序 'pg'
+[推测] 基于 src/repositories/ 中的 repository 模式，可能使用依赖注入
+[假设] 专案可能使用 OAuth2，但需要审查验证设定
+[未知] API 速率限制策略未记录
+[需确认] 新功能是否应支援多租户？
+```
+
+❌ **错误**:
+```
+系统使用 Redis（无分类，无证据）
+我们应该实作快取（以事实呈现，非建议）
+使用者需要 SSO 支援（假设以已确认需求呈现）
+```
+
+---
+
+### 4. 禁止行为
+
+**AI 助手不得**:
+
+1. **捏造 API 或函式签名**
+   - ❌ 不要编造方法名称、参数或回传类型
+   - ✅ 要读取实际原始码或询问使用者
+
+2. **假设需求**
+   - ❌ 不要猜测使用者需求或业务规则
+   - ✅ 当需求模糊时要提出澄清问题
+
+3. **推测未读取的程序码**
+   - ❌ 不要描述未审查档案的功能
+   - ✅ 要明确表示「需要读取 [档案] 以确认」
+
+4. **编造设定**
+   - ❌ 不要假设环境变数、设定键或资料库结构
+   - ✅ 要审查实际设定档
+
+5. **凭空产生错误或 Bug**
+   - ❌ 不要在无证据的情况下声称程序码有问题
+   - ✅ 要分析实际程序码并引用特定行号
+
+6. **提出选项但不推荐**
+   - ❌ 不要列出选项后要求使用者选择而不提供指引
+   - ✅ 要永远包含推荐选项并附理由
+
+#### 详细范例
+
+##### 1. 捏造 API 或函式名称
+
+❌ **错误**:
+```
+助理: 「你可以呼叫 UserService.GetUserById(int id) 来取得使用者」
+```
+**问题**: 方法不存在或签名不同。
+
+✅ **正确**:
+```
+助理: 「让我读取 UserService 档案以找到正确的方法签名。」
+
+[读取 src/services/UserService.cs 后]
+
+[来源: 程序码] UserService.cs:45 - 找到方法: FindUser(Guid userId)
+实际方法使用 Guid 而非 int 作为使用者 ID 参数。
+```
+
+---
+
+##### 2. 假设使用者需求
+
+❌ **错误**:
+```
+助理: 「系统需要支援 OAuth 和 SAML 以提供企业 SSO。」
+```
+**问题**: 使用者只询问认证，未指定协议。
+
+✅ **正确**:
+```
+助理: 「[需确认] 您提到需要验证功能。
+能否澄清:
+1. 这是给内部使用者、外部客户，还是两者都有？
+2. 您需要企业 SSO（OAuth/SAML）还是简单的使用者名称/密码？
+3. 有任何需要集成的现有身分提供者吗？
+
+这将帮助我推荐最适合的方法。」
+```
+
+---
+
+##### 3. 描述未读取的程序码功能
+
+❌ **错误**:
+```
+助理: 「PaymentService 处理信用卡处理并与 Stripe 集成。」
+```
+**问题**: 档案未读取，功能仅从名称假设。
+
+✅ **正确**:
+```
+助理: 「我在您的专案结构中看到名为 PaymentService.cs 的档案。
+
+[未知] 我尚未读取此档案，因此无法确认其功能。
+
+您想让我读取 src/services/PaymentService.cs 以了解:
+- 它使用哪个支付提供者？
+- 支援哪些支付方式？
+- 交易如何处理？」
+```
+
+---
+
+##### 4. 编造设定细节
+
+❌ **错误**:
+```
+助理: 「设定 DATABASE_URL 环境变数以连线到 PostgreSQL。
+您的连线字串应在 appsettings.json 的 'ConnectionStrings:DefaultConnection' 下。」
+```
+**问题**: 设定结构和变数名称未经验证即假设。
+
+✅ **正确**:
+```
+助理: 「让我检查您的实际设定档。」
+
+[读取 appsettings.json 后]
+
+[来源: 程序码] appsettings.json:8-12 - 找到资料库设定:
+- 连线字串键: "ConnectionStrings:MainDb"（非 "DefaultConnection"）
+- 使用 SQL Server，非 PostgreSQL
+- 额外设定 "CommandTimeout": 30
+
+您的专案使用与 .NET 预设不同的键名称。
+```
+
+---
+
+##### 5. 断言程序码有 Bug（无证据）
+
+❌ **错误**:
+```
+助理: 「您的验证程序码有安全性漏洞 -
+您没有正确进行密码杂凑。」
+```
+**问题**: 未读取实际程序码即声称有 Bug。
+
+✅ **正确**:
+```
+助理: 「让我审查您的验证实作。」
+
+[读取 src/auth/AuthService.cs 后]
+
+[已确认] AuthService.cs:67 - 找到密码杂凑实作:
+- 使用 BCrypt，work factor 为 12 ✅
+- Salt 自动生成 ✅
+- 未侦测到时序攻击漏洞 ✅
+
+您的密码杂凑实作遵循安全性最佳实务。
+在审查的程序码中未发现问题。
+```
+
+---
+
+##### 6. 选项未附推荐
+
+❌ **错误**:
+```
+助理: 「您可以使用: 1) JWT 2) Session 3) OAuth。您偏好哪个？」
+```
+**问题**: 列出选项但未提供指引或考虑情境。
+
+✅ **正确**:
+```
+助理: 「基于您的需求:
+
+**选项**:
+1. JWT - 无状态、可扩展、适合 API
+2. Session - 服务器端状态、传统 Web 应用程序
+3. OAuth - 第三方身分提供者
+
+**推荐: JWT**
+
+[推测] 基于您的微服务架构（见于 docker-compose.yml），
+JWT 是最适合的，因为:
+- 无状态: 跨服务不需要 session 储存
+- 可扩展: 每个服务可独立验证 token
+- 标准: 在您的技术堆叠（.NET、React）中有良好支援
+
+如果之后需要社交登入，可以在 JWT 之上加入 OAuth。」
+```
+
+---
+
+## 实施检查清单
+
+在对程序码、需求或架构做出任何陈述前，请验证:
+
+- [ ] **来源已验证**
+  - 我是否已读取实际的档案/文件？
+
+- [ ] **来源类型已标注**
+  - 我是否已指定来源类型？（`[来源: 程序码]`、`[来源: 外部]`、`[来源: 知识]` 等）
+
+- [ ] **引用已标注**
+  - 我是否已包含档案路径与行号（程序码）？
+  - 我是否已包含 URL 与存取日期（外部文件）？
+
+- [ ] **版本已标注**
+  - 我是否已包含适用的函式库/框架版本？
+
+- [ ] **确定性已分类**
+  - 我是否已标注为 [已确认]、[推测]、[假设]、[未知] 或 [需确认]？
+
+- [ ] **AI 知识已标记**
+  - 我是否已对 `[来源: 知识]` 标记 ⚠️ 验证警告？
+
+- [ ] **无捏造**
+  - 我是否避免了捏造 API、设定或需求？
+
+- [ ] **使用者澄清**
+  - 我是否对模糊点请求澄清？
+
+- [ ] **包含推荐**
+  - 当提出选项时，我是否包含了推荐选项？
+
+---
+
+## 审查情境
+
+### 情境 1: 程序码分析
+
+**使用者请求**: 「审查验证逻辑」
+
+**❌ 不良回应**:
+```
+您的验证系统使用 JWT 搭配 RS256 签名。
+Token 在 1 小时后过期。
+您应该加入 refresh token 支援。
+```
+**问题**: 未读取程序码即做出声明，假设实作细节。
+
+**✅ 良好回应**:
+```
+[需确认] 哪个档案包含验证逻辑？
+可能的位置包括:
+- src/auth/
+- src/services/auth
+- src/middleware/
+
+请引导我找到正确的档案，以便我提供准确分析。
+
+或者，我可以搜寻程序码库中与验证相关的档案。
+```
+
+---
+
+### 情境 2: 架构建议
+
+**使用者请求**: 「我应该如何架构新的付款模组？」
+
+**❌ 不良回应**:
+```
+基于您现有的架构，您应该:
+1. 在 src/services/ 建立 PaymentService
+2. 使用 Stripe API
+3. 将交易储存在 payments 资料表
+```
+**问题**: 未经证据即假设架构、支付提供者和资料库结构。
+
+**✅ 良好回应**:
+```
+为了提供准确的建议，我需要了解您目前的架构:
+
+[需确认]
+1. 您计划使用哪个支付提供者？（Stripe、PayPal、自订等）
+2. 您现有的服务层结构是什么？
+3. 您使用什么资料库？
+
+能否分享:
+- 专案结构（ls -R src/ 或类似）
+- 现有服务范例
+- 资料库结构或 ORM 模型
+
+一旦我审查了这些，就能建议与您的模式一致的结构。
+```
+
+---
+
+### 情境 3: Bug 调查
+
+**使用者请求**: 「登入失败」
+
+**❌ 不良回应**:
+```
+问题可能在您的 validateCredentials() 函式中。
+您可能需要在比对前对密码进行杂凑。
+```
+**问题**: 未看程序码即猜测原因。
+
+**✅ 良好回应**:
+```
+要调查登入失败，我需要更多资讯:
+
+[需确认]
+1. 您看到什么错误讯息？（主控台日志、错误回应）
+2. 哪个档案包含登入逻辑？
+3. 能否分享相关的程序码片段或日志？
+
+建议的除错步骤:
+- 分享登入控制器/服务程序码
+- 提供主控台/服务器的错误日志
+- 描述预期与实际行为
+
+一旦我审查了实际程序码和错误，就能找出根本原因。
+```
+
+---
+
+### 情境 4: 技术选型
+
+**使用者请求**: 「我应该使用什么快取解决方案？」
+
+**❌ 不良回应**:
+```
+您有几个选项:
+1. Redis
+2. Memcached
+3. 记忆体快取
+
+让我知道您想使用哪一个。
+```
+**问题**: 列出选项但未推荐或考虑情境。
+
+**✅ 良好回应**:
+```
+基于可用的选项:
+1. Redis - 分散式、持久化、丰富的资料结构
+2. Memcached - 简单、快速、分散式
+3. 记忆体快取 - 仅本机、无需设定
+
+**推荐: Redis**
+
+[需确认] 在最终决定前，我想了解:
+- 您需要跨多个实例共享快取吗？
+- 需要资料持久化吗？
+- 您现有的基础设施是什么？
+
+如果您已有 Redis 基础设施或需要跨实例共享，
+Redis 是最佳选择。如果这是单实例应用程序且有
+简单的快取需求，记忆体快取就足够了。
+```
+
+---
+
+## AI 助理工作流程
+
+```
+┌─────────────────────────────────┐
+│  收到使用者请求                  │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  识别所需资讯                    │
+│  - 程序码档案？                  │
+│  - 设定？                        │
+│  - 需求？                        │
+└─────────────┬───────────────────┘
+              │
+              ▼
+         ┌────┴────┐
+         │  可取得？ │
+         └────┬────┘
+              │
+      ┌───────┴───────┐
+      │               │
+     是              否
+      │               │
+      ▼               ▼
+┌──────────┐   ┌─────────────┐
+│  读取/   │   │  向使用者   │
+│  分析    │   │  询问资讯   │
+└────┬─────┘   └──────┬──────┘
+     │                │
+     ▼                ▼
+┌─────────────────────────────────┐
+│  为回应加上标签:                 │
+│  - [已确认] 用于事实             │
+│  - [推测] 用于推论               │
+│  - [需确认] 用于缺口             │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  引用来源（档案:行号）           │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  包含推荐                        │
+│  （如提出选项）                  │
+└─────────────┬───────────────────┘
+              │
+              ▼
+┌─────────────────────────────────┐
+│  提供回应                        │
+└─────────────────────────────────┘
+```
+
+---
+
+## 语言无关应用
+
+本标准适用于任何程序语言、框架或领域:
+
+- **Web 开发**: 未经证据不假设 Express/Django/Spring Boot
+- **行动开发**: 未经证据不假设 React Native/Flutter
+- **资料科学**: 未经证据不假设 TensorFlow/PyTorch
+- **DevOps**: 未经证据不假设 Docker/Kubernetes
+
+**通用规则**: 先读取，再分析，永远以证据报告。
+
+---
+
+## 与程序码审查集成
+
+执行程序码审查时，应用这些原则:
+
+1. **引用行号**: 所有审查评论必须引用特定行号
+2. **以证据分类严重性**:
+   - `[已确认 Bug]` - 程序码明显损坏
+   - `[潜在问题]` - 程序码可能造成问题
+   - `[建议]` - 改善想法（非缺陷）
+3. **避免假设**: 如不确定设计意图，询问作者
+
+**审查评论范本**:
+```
+[档案:行号] - [严重性]
+[问题描述与程序码摘录]
+[证据或推理]
+[建议修正或澄清问题]
+```
+
+---
+
+## 相关标准
+
+- [测试标准](testing-standards.md) - 确保验证 AI 分析结果（或使用 `/testing-guide` 技能）
+- [程序码审查清单](code-review-checklist.md) - 审查 AI 生成内容
+- [程序码签入标准](checkin-standards.md) - AI 协作签入流程
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.3.1 | 2025-12-24 | 新增: 相关标准章节 |
+| 1.3.0 | 2025-12-22 | 增强: 禁止行为章节，新增详细对比范例 |
+| 1.2.0 | 2025-12-15 | 新增: AI 助手互动规范章节（对话语言、推荐原则） |
+| 1.1.0 | 2025-12-10 | 增强来源标注，新增来源类型、版本敏感性与可靠度评级 |
+| 1.0.0 | 2025-11-12 | 初版发布 |
+
+---
+
+## 授权
+
+本标准以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。
+您可以自由调整用于您的专案，但需注明出处。
+
+---
+
+**专案特定化**
+
+专案可透过以下方式扩充本标准:
+- 领域特定验证需求（如医疗领域的 HIPAA 合规检查）
+- 工具特定指引（如如何验证 Terraform 设定）
+- 团队特定证据格式（如 JIRA ticket 引用）
+- AI 助手对话的语言偏好