universal-dev-standards 5.15.1 → 5.17.0

package/bundled/locales/zh-CN/skills/journey-test-assistant/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: journey-test-assistant
+source: ../../../../skills/journey-test-assistant/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 439f49327b75
+status: current
+scope: partial
+description: |
+  [UDS] 从项目描述生成连贯的用户旅程测试计划（TESTPLAN）与 E2E 骨架。
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[项目描述 | --analyze | --archetype A1|A2|A3]"
+---
+
+# Journey Test Assistant | 旅程测试助手
+
+从项目描述生成连贯的用户旅程测试计划（TESTPLAN-NNN.md）与对应的 E2E 骨架，让每个新项目从第一天起就拥有完整的测试旅程。
+
+## 与 /e2e 的区别
+
+| 维度 | /e2e | /journey-test |
+|------|------|--------------|
+| 组织单位 | 单一 XSPEC/AC | 跨 Story 的用户旅程 |
+| 测试结构 | 隔离、独立 | 连贯、状态共享 |
+| 产物 | `*.spec.ts` 骨架 | `TESTPLAN.md` + `*.journey.spec.ts` |
+| 触发时机 | 功能完成后 | 项目创建时（Journey-First） |
+| 检测目标 | 单一 AC 是否正确 | 跨步骤状态传递是否连贯 |
+
+## 工作流程
+
+```
+输入：项目描述 / 现有 TESTPLAN / --analyze
+    ↓
+Phase 1：定义 Persona
+    分析项目描述 → 识别所有用户角色 → 定义 Actor/Role/Key Permissions
+    ↓
+Phase 2：设计旅程地图
+    列出主要业务目标 → 拆解为 T-NNN 分组 → 声明依赖链
+    ↓
+Phase 3：生成 TESTPLAN
+    按格式输出 test-plans/TESTPLAN-001.md（含 Personas、步骤、依赖图）
+    ↓
+Phase 4：生成 E2E 骨架
+    从 TESTPLAN T-NNN 生成 *.journey.spec.ts（含 skipIf + 共享 state）
+```
+
+## 模式
+
+### 1. 生成模式（默认）
+
+从项目描述生成完整的 TESTPLAN + E2E 骨架。
+
+```
+/journey-test "电商平台，需要 buyer/seller/admin 三个角色"
+```
+
+产物：
+- `test-plans/TESTPLAN-001.md`：含 Personas、T-000 环境重置、T-001~T-NNN 步骤分组、执行顺序依赖图
+- `src/e2e/journey/main-flow.journey.spec.ts`：含 `describe.skipIf` + 共享 state + T-NNN 对应的完整骨架
+
+### 2. 分析模式（--analyze）
+
+扫描现有测试，找出旅程覆盖缺口。
+
+```
+/journey-test --analyze
+```
+
+执行步骤：
+1. 读取 `test-plans/TESTPLAN-NNN.md`（若存在）
+2. 扫描 `src/e2e/` 下所有 `*.journey.spec.ts` 和 `*.journey.e2e.test.ts`
+3. 比对 TESTPLAN T-NNN 与自动化测试中的 T-NNN 引用
+4. 输出 Coverage gap 报告：列出 TESTPLAN 中缺乏自动化对应的 T-NNN 步骤
+
+### 3. Archetype 模式（--archetype）
+
+使用预设旅程模板，适合已知类型的项目快速启动。
+
+```
+/journey-test --archetype A1    # Spec-driven 旅程
+/journey-test --archetype A2    # UI-driven 旅程
+/journey-test --archetype A3    # Brownfield 旅程
+```
+
+| Archetype | 模板 | 适用场景 |
+|-----------|------|---------|
+| A1 | Spec-driven | 需求 → Spec → Code → Test，适合 API/Backend 项目 |
+| A2 | UI-driven | 设计稿 → UI → 视觉回归，适合前端/全栈项目 |
+| A3 | Brownfield | 现有代码 → 分析 → 重构验证，适合既有项目补测试 |
+
+## TESTPLAN 格式（T-NNN）
+
+以下为完整的 TESTPLAN 模板，展示所有必要区段：
+
+```markdown
+# TESTPLAN-001 <ProjectName> 主线旅程
+
+## Personas
+
+| Actor         | Role          | Key Permissions              |
+|---------------|---------------|------------------------------|
+| platform_admin | Platform Admin | 创建 Org、管理用户、查看所有资源 |
+| org_member    | Org Member    | 读取项目、执行 Pipeline         |
+
+## Environment
+
+- BASE_URL：`http://localhost:3000`（本机）/ `$JOURNEY_BASE_URL`（CI）
+- 验证命令：`curl $BASE_URL/health`
+- 必要账号：`ADMIN_EMAIL`、`ADMIN_PASSWORD` 环境变量
+
+## T-000 环境重置（optional）
+
+前置条件：无
+depends_on：无
+
+| 步骤    | 操作                              | 预期结果        |
+|---------|-----------------------------------|-----------------|
+| T-000-1 | [API] GET /health                | 返回 200 OK     |
+| T-000-2 | [CHECK] 数据库连接正常            | 无错误日志      |
+
+## T-001 Platform Admin 登录
+
+前置条件：环境正常运行（T-000 通过）
+depends_on：T-000
+
+| 步骤    | 操作                                        | 预期结果                 |
+|---------|---------------------------------------------|--------------------------|
+| T-001-1 | [API] POST /api/auth/login（admin 账号）    | 返回 200 + authToken     |
+| T-001-2 | [CHECK] authToken 存入共享 state            | let authToken 有值       |
+
+## T-010 主要功能操作
+
+前置条件：authToken 已取得（T-001 通过）
+depends_on：T-001
+
+| 步骤    | 操作                                        | 预期结果                 |
+|---------|---------------------------------------------|--------------------------|
+| T-010-1 | [API] POST /api/resources（带 authToken）   | 返回 201 + resourceId ★  |
+| T-010-2 | [CHECK] resourceId 存入共享 state           | let resourceId 有值      |
+
+## 执行顺序依赖图
+
+T-000 → T-001 → T-010
+```
+
+## E2E 骨架格式（.journey.spec.ts）
+
+生成的骨架展示三个核心模式：`describe.skipIf` 环境保护、共享 `let` 状态、T-NNN 标识符对应。
+
+```typescript
+import { describe, it, expect } from "vitest"
+
+// Journey E2E：需要真实后端，不设置 JOURNEY_BASE_URL 则全部 skip
+const BASE_URL = process.env.JOURNEY_BASE_URL || ""
+
+describe.skipIf(!BASE_URL)("Platform Admin Journey — T-001 → T-010", () => {
+  // 共享 state：每个步骤从前一步骤的结果取值
+  let authToken: string
+  let resourceId: string
+
+  it("T-001: Platform Admin 登录并取得 authToken", async () => {
+    const res = await fetch(`${BASE_URL}/api/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: process.env.ADMIN_EMAIL,
+        password: process.env.ADMIN_PASSWORD,
+      }),
+    })
+    expect(res.status, "T-001 failed: login should return 200").toBe(200)
+    const data = await res.json()
+    expect(data.token, "T-001 failed: token should be present").toBeTruthy()
+    authToken = data.token  // ← 传递给后续步骤
+  })
+
+  it("T-010: 执行主要操作（depends on T-001）", async () => {
+    // 如果 T-001 失败，authToken 为 undefined，此步骤的错误信息会清楚说明
+    expect(authToken, "T-010 precondition failed: authToken from T-001 is missing").toBeTruthy()
+
+    const res = await fetch(`${BASE_URL}/api/resources`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${authToken}`,
+      },
+      body: JSON.stringify({ name: "journey-test-resource" }),
+    })
+    expect(res.status, `T-010 failed: expected 201, got ${res.status}`).toBe(201)
+    const data = await res.json()
+    resourceId = data.id  // ← 传递给后续步骤
+  })
+})
+```
+
+## 后续步骤
+
+完成后建议：
+
+> **TESTPLAN 与 Journey E2E 骨架已生成。建议下一步：**
+> - 执行 `/e2e` 生成各功能的 AC 层测试（补充旅程测试的细节覆盖）
+> - 执行 `/atdd` 定义各 T-NNN 步骤对应的验收条件
+> - 执行 `/journey-test --analyze` 定期检查自动化覆盖缺口
+
+## 参考
+
+- 标准：[user-journey-testing.ai.yaml](../../.standards/user-journey-testing.ai.yaml)
+- 相关 XSPEC：XSPEC-128（UDS 标准定义）
+- 相关 Skill：`/e2e`（AC 层测试）、`/atdd`（验收条件定义）

package/bundled/locales/zh-CN/skills/knowledge-graph/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: knowledge-graph
+source: ../../../../skills/knowledge-graph/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 68a0b2a9e02f
+status: current
+description: |
+  [UDS] 通过知识图追踪规格／决策／代码的影响链（引擎或 Markdown 后备）
+---
+
+# 知识图
+
+> **语言**: [English](../../../../skills/knowledge-graph/SKILL.md) | 简体中文
+
+依据[知识图记忆标准](../../../../core/knowledge-graph-memory.md)的关系 schema，回答横跨规格、决策与代码的结构性问题——*「XSPEC-205 的完整影响链是什么？」*。有无图引擎皆可运作。
+
+> **Implements**: XSPEC-237 Phase 5 — knowledge-graph skill（EngramGraph opt-in）
+
+## 模式选择
+
+回答**前**先判断使用哪种模式：
+
+| 条件 | 模式 |
+|------|------|
+| 设定了 `ENGRAM_URL`，或本机图引擎 `/health` 有响应 | 服务模式（引擎）|
+| 否则 | 降级模式（Markdown）|
+
+## 工作流程
+
+1. **解析目标**——将参数规范化为标准 id（`XSPEC-205`、`DEC-062`、函数名）。
+2. **选择模式**——探测图引擎（服务）否则后备（降级）。
+3. **服务模式（AC-5b）**——发出单一多跳查询，呈现返回的链（含跨域链接 code → spec → decision）：
+   ```bash
+   curl -s -X POST "$ENGRAM_URL/graph/impact-analysis" \
+     -H 'content-type: application/json' \
+     -d '{"nodeId":"XSPEC-205","maxHops":3}'
+   ```
+4. **降级模式（AC-5a）**——无引擎时，读取目标文件，沿其 `impacts`/`impacted_by`/`supersedes`/`related` front-matter 与正文 `[[ref]]` 链接读取被链接文件，手动组出链（受读取深度限制）。
+5. **呈现链**——列出相连的 Spec 与 Decision、每跳的边类型、以及（若有）各节点的 `confidence`，高者在前。
+6. **说明使用的模式**——务必告知答案来自引擎或 Markdown 后备，以明确完整度。
+
+## 关系 schema
+
+见[知识图记忆标准](../../../../core/knowledge-graph-memory.md)。front-matter 字段：`related`、`impacts`、`impacted_by`、`supersedes`、`implements`。边推导：Decision `impacts` Spec → IMPACTS；Decision `supersedes` Decision → SUPERSEDES。
+
+## 下一步引导
+
+- 降级模式若触及读取深度上限，告知用户图引擎（如 EngramGraph）可给出完整链，以及如何设定 `ENGRAM_URL`。
+- 若引用的 id 找不到，标示为待修的悬空引用。
+- 主动提议为遍历过的文件补上缺漏的 `impacts`/`impacted_by` front-matter。
+
+## 参考
+
+- 标准：[core/knowledge-graph-memory.md](../../../../core/knowledge-graph-memory.md)
+- 引擎（opt-in）：[EngramGraph](https://github.com/AsiaOstrich/EngramGraph) — `engramgraph`
+- 详细指南：[guide.md](guide.md)

package/bundled/locales/zh-CN/skills/knowledge-graph/guide.md

@@ -0,0 +1,74 @@
+---
+source: ../../../../skills/knowledge-graph/guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 9c86b5a2a71d
+status: current
+---
+
+# Knowledge Graph — 详细指南
+
+[SKILL.md](SKILL.md) 的配套说明。两种运行模式的范例以及引擎 API。
+
+---
+
+## 1. 服务模式（graph 引擎）
+
+当存在可访问的 EngramGraph 兼容引擎时，单次查询即可返回完整的影响链。
+
+### 影响分析
+
+```bash
+curl -s -X POST "$ENGRAM_URL/graph/impact-analysis" \
+  -H 'content-type: application/json' \
+  -d '{"nodeId":"XSPEC-205","maxHops":3}'
+# => { "nodeId": "XSPEC-205",
+#      "decisions": [ {"id":"DEC-062","title":"...","via":"direct"},
+#                     {"id":"DEC-069","title":"...","via":"supersedes"} ] }
+```
+
+`via: "direct"` 表示该决策直接 IMPACTS（影响）此规格；`via: "supersedes"` 表示它通过 SUPERSEDES 链（≤ `maxHops`）触达此规格。
+
+### 信心反馈（SAGE）
+
+```bash
+curl -s -X POST "$ENGRAM_URL/graph/ingest" \
+  -H 'content-type: application/json' \
+  -d '{"type":"test_fail","functionId":"src/a.ts#execute"}'
+```
+
+降低该节点的信心值；后续读取时会优先呈现信心更高的节点。
+
+---
+
+## 2. 降级模式（仅 Markdown）
+
+无需引擎。通过读取文件来重建影响链：
+
+1. 读取目标文档（例如 `XSPEC-205`）。
+2. 从其 front-matter（`impacts`、`impacted_by`、`supersedes`、`related`）以及行内 `[[ref]]` 链接中收集 id。
+3. 对每个 id，读取对应文档并重复此过程，直到达到所需的跳数深度。
+4. 按前缀对每个 id 分类（`XSPEC-*`/`SPEC-*` → 规格；`DEC-*`/`ADR-*` → 决策）并报告边（edges）。
+
+```bash
+# find the documents
+grep -rl "id: XSPEC-205" --include='*.md' .
+# discover outbound references
+grep -nE "(impacts|impacted_by|supersedes|related):|\[\[(XSPEC|DEC|ADR)-" path/to/XSPEC-205.md
+```
+
+降级模式始终是正确的，但受限于你读取的文件数量；跨域的代码链接（function → spec）通常只在服务模式下才可获得。
+
+---
+
+## 3. 等价性
+
+两种模式产生**相同形状的答案**（一组带边类型、互相关联的规格／决策列表）。服务模式更快也更完整（它可以包含 code→spec→decision 的跳转）；降级模式是通用的后备方案。务必告知用户答案来自哪种模式。
+
+---
+
+## 参考
+
+- [core/knowledge-graph-memory.md](../../core/knowledge-graph-memory.md)
+- [EngramGraph](https://github.com/AsiaOstrich/EngramGraph)

package/bundled/locales/zh-CN/skills/migration-assistant/SKILL.md

@@ -1,8 +1,9 @@
 ---
 source: ../../../../skills/migration-assistant/SKILL.md
 source_version: 1.0.0
+source_hash: 67b6f33f825e
 translation_version: 1.0.0
-last_synced: 2026-03-24
+last_synced: 2026-06-01
 status: current
 description: |
   引导代码迁移、框架升级与技术现代化。
@@ -30,12 +31,12 @@ description: |
 
 | 类型 | 范例 | 风险 |
 |------|------|------|
-| **框架升级** | React 17→18, Vue 2→3 | 中高 |
-| **语言迁移** | JS→TS, Python 2→3 | 高 |
-| **API 版本** | REST v1→v2, GraphQL 更新 | 中 |
-| **数据库迁移** | MySQL→PostgreSQL | 极高 |
-| **构建工具** | Webpack→Vite | 低中 |
-| **包管理器** | npm→pnpm | 低 |
+| **框架升级** | React 17→18, Vue 2→3, Angular 15→17 | 中高 |
+| **语言迁移** | JS→TS, Python 2→3, Java 8→17 | 高 |
+| **API 版本** | REST v1→v2, GraphQL schema 更新 | 中 |
+| **数据库迁移** | MySQL→PostgreSQL, SQL→NoSQL | 极高 |
+| **构建工具** | Webpack→Vite, Grunt→ESBuild | 低中 |
+| **包管理器** | npm→pnpm, pip→poetry | 低 |
 
 ## 风险评估矩阵
 
@@ -54,6 +55,92 @@ description: |
 5. **验证** - 执行完整测试套件、检查回归
 6. **清理** - 移除兼容层、旧依赖
 
+## API 迁移契约测试
+
+当 API endpoint 从一个技术栈迁至另一个（PHP → .NET、Express → Spring、Python → Go），对**新**实现的单元测试只验证**新 DTO**——无法捕捉「旧版有但新版漏掉的字段」。字段缺漏、字段 rename、类型漂移，以及顶层 vs nested 层级漂移等问题会静默流入生产，导致仍预期旧版 shape 的既有前端失灵。
+
+**仅靠单元测试、集成测试或 code review 无法防止**。2026-05-24 真实 PROD 事故：67/67 测试全绿流入正式环境，由客户发现缺漏。
+
+### 强制规则
+
+每个被迁移的 API endpoint **必须**至少有一份 contract test，比对新实现的 response 与从 legacy 实现捕获的 fixture。验证的是结构性等价（keys、type、层级位置），而非值等价。
+
+### Fixture 捕获协议
+
+**Legacy 仍运行（典型迁移窗口）：**
+
+```bash
+# 1. Capture ≥3 representative inputs (happy path, edge case, empty result)
+curl -X POST $LEGACY_BASE/endpoint -d @input1.json \
+  > tests/fixtures/migration/endpoint/scenario1.json
+curl -X POST $LEGACY_BASE/endpoint -d @input2_empty.json \
+  > tests/fixtures/migration/endpoint/scenario2_empty.json
+curl -X POST $LEGACY_BASE/endpoint -d @input3_edge.json \
+  > tests/fixtures/migration/endpoint/scenario3_edge.json
+
+# 2. Scrub PII and volatile values (timestamps, generated IDs)
+jq 'walk(if type == "string" and test("@") then "redacted@example.com" else . end)' \
+  tests/fixtures/migration/endpoint/scenario1.json > tmp && mv tmp ...
+
+# 3. Commit fixtures
+git add tests/fixtures/migration/endpoint/
+```
+
+**Legacy 已退役但 source 可读：**
+
+- 追踪 legacy source code，手动构建预期的 response shape
+- 将每个字段的来源（SQL 列、计算式、hardcoded）记录于同位置的 `.notes.md` 文件
+
+### Contract test 模板
+
+**C# / xUnit：**
+
+```csharp
+[Theory]
+[InlineData("scenario1")]
+[InlineData("scenario2_empty")]
+[InlineData("scenario3_edge")]
+public async Task Endpoint_ResponseShape_MatchesLegacyFixture(string scenario)
+{
+    var fixture = LoadFixture($"migration/endpoint/{scenario}");
+    var response = await CallNewImpl(fixture.Input);
+    // StructuralEquivalence checks keys + types + placement, ignores values
+    StructuralEquivalence.Assert(response, fixture.ExpectedShape);
+}
+```
+
+**TypeScript / Jest：**
+
+```typescript
+import { structuralEquivalence } from "./test-utils/structural-equivalence";
+
+describe.each([
+  ["scenario1"],
+  ["scenario2_empty"],
+  ["scenario3_edge"],
+])("Endpoint response shape vs legacy fixture (%s)", (scenario) => {
+  test("matches", async () => {
+    const fixture = loadFixture(`migration/endpoint/${scenario}.json`);
+    const response = await callNewImpl(fixture.input);
+    structuralEquivalence(response, fixture.expectedShape);
+  });
+});
+```
+
+`structuralEquivalence` / `StructuralEquivalence.Assert` 规则：每一层具备相同的 key 集合（不可缺漏、不可多出，除非明确 opt in）、每个 key 具相同的基本类型、相同的层级位置（顶层 vs nested）。值可以不同（timestamps、IDs）；类型与结构不可不同。
+
+### 逐字段迁移审计清单
+
+合并任何被迁移的 endpoint 前：
+
+- [ ] 所有 legacy response 字段皆 mapping 至新 DTO（无 silent drop）
+- [ ] 尽量保留命名（避免将 `TotalX` rename 而丢失「per-member」语意）
+- [ ] 保留顶层 vs nested 层级位置
+- [ ] 已验证类型兼容性（string→int 转换为明确而非巧合）
+- [ ] Error path return code 与 legacy 一致（`509` 而非 `506`；`404` 而非 `400`）
+- [ ] Contract test fixture 已 commit 至 `tests/fixtures/migration/`
+- [ ] Cross-link 至 [contract-test-assistant](../contract-test-assistant/SKILL.md) 做持续的消费端验证
+
 ## 回滚策略
 
 | 方式 | 使用时机 |
@@ -63,15 +150,45 @@ description: |
 | **双运行** | 关键系统、零停机 |
 | **分支冻结** | 一次性完整迁移 |
 
+## 使用范例
+
+```
+User: /migrate "Vue 2 to 3"
+AI: Migration Assessment: Vue 2 → Vue 3
+    Breaking changes found: 12
+    - Options API → Composition API (47 components)
+    - Filters removed (8 usages)
+    - Event bus removed (3 usages)
+    Risk: Medium-High
+    Estimated effort: 2-3 weeks
+    Recommended: Staged migration with @vue/compat
+```
+
 ## 下一步引导
 
 `/migrate` 完成后，AI 助手应建议：
 
 > **迁移分析完成。建议下一步：**
 > - 执行 `/reverse` 深入理解现有代码
-> - 执行 `/testing` 确保迁移后测试通过
+> - 执行 `/testing` 确保迁移后测试通过 ⭐ **推荐**
 > - 执行 `/commit` 提交迁移变更
 
 ## 参考
 
 - 核心规范：[refactoring-standards.md](../../../../core/refactoring-standards.md)
+- 相关：[contract-test-assistant](../contract-test-assistant/SKILL.md) — 迁移后持续契约验证的策略
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.1.0 | 2026-05-26 | 新增：API 迁移契约测试章节——强制 fixture 捕获协议、C#/TS 模板、逐字段审计清单（XSPEC-233 / closes #112） |
+| 1.0.0 | 2026-03-24 | 初始版本 |
+
+## AI 代理行为
+
+> 完整的 AI 行为定义请参阅对应的命令文件：[`/migrate`](../commands/migrate.md#ai-agent-behavior--ai-代理行为)
+
+## 授权
+
+CC BY 4.0