universal-dev-standards 5.14.0 → 5.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/uds.js +2 -0
- package/bundled/ai/standards/acceptance-criteria-traceability.ai.yaml +31 -0
- package/bundled/ai/standards/ai-instruction-standards.ai.yaml +190 -3
- package/bundled/ai/standards/forward-derivation-standards.ai.yaml +23 -0
- package/bundled/ai/standards/knowledge-graph-memory.ai.yaml +83 -0
- package/bundled/core/acceptance-criteria-traceability.md +46 -0
- package/bundled/core/ai-instruction-standards.md +136 -11
- package/bundled/core/forward-derivation-standards.md +19 -0
- package/bundled/core/knowledge-graph-memory.md +119 -0
- package/bundled/locales/COVERAGE.md +226 -0
- package/bundled/locales/zh-CN/CHANGELOG.md +42 -3
- package/bundled/locales/zh-CN/README.md +1 -1
- package/bundled/locales/zh-CN/SECURITY.md +1 -1
- package/bundled/locales/zh-CN/core/acceptance-criteria-traceability.md +46 -0
- package/bundled/locales/zh-CN/core/ai-instruction-standards.md +111 -5
- package/bundled/locales/zh-CN/core/forward-derivation-standards.md +19 -0
- package/bundled/locales/zh-CN/skills/ac-coverage/SKILL.md +194 -0
- package/bundled/locales/zh-CN/skills/adr-assistant/SKILL.md +135 -40
- package/bundled/locales/zh-CN/skills/brainstorm-assistant/SKILL.md +217 -63
- package/bundled/locales/zh-CN/skills/brainstorm-assistant/guide.md +599 -0
- package/bundled/locales/zh-CN/skills/commands/brainstorm.md +92 -25
- package/bundled/locales/zh-CN/skills/commit-standards/SKILL.md +78 -16
- package/bundled/locales/zh-CN/skills/contract-test-assistant/SKILL.md +85 -26
- package/bundled/locales/zh-CN/skills/deploy-assistant/SKILL.md +189 -0
- package/bundled/locales/zh-CN/skills/dev-methodology/SKILL.md +110 -0
- package/bundled/locales/zh-CN/skills/dev-methodology/guide.md +255 -0
- package/bundled/locales/zh-CN/skills/dev-workflow-guide/SKILL.md +70 -11
- package/bundled/locales/zh-CN/skills/journey-test-assistant/SKILL.md +209 -0
- package/bundled/locales/zh-CN/skills/knowledge-graph/SKILL.md +58 -0
- package/bundled/locales/zh-CN/skills/knowledge-graph/guide.md +74 -0
- package/bundled/locales/zh-CN/skills/migration-assistant/SKILL.md +125 -8
- package/bundled/locales/zh-CN/skills/observability-assistant/guide.md +188 -0
- package/bundled/locales/zh-CN/skills/orchestrate/SKILL.md +173 -0
- package/bundled/locales/zh-CN/skills/plan/SKILL.md +240 -0
- package/bundled/locales/zh-CN/skills/push/SKILL.md +242 -0
- package/bundled/locales/zh-CN/skills/retrospective-assistant/SKILL.md +104 -36
- package/bundled/locales/zh-CN/skills/reverse-engineer/SKILL.md +88 -32
- package/bundled/locales/zh-CN/skills/runbook-assistant/guide.md +216 -0
- package/bundled/locales/zh-CN/skills/skill-builder/SKILL.md +149 -0
- package/bundled/locales/zh-CN/skills/slo-assistant/guide.md +188 -0
- package/bundled/locales/zh-CN/skills/spec-derivation/SKILL.md +86 -0
- package/bundled/locales/zh-CN/skills/spec-derivation/guide.md +476 -0
- package/bundled/locales/zh-CN/skills/spec-driven-dev/SKILL.md +155 -81
- package/bundled/locales/zh-CN/skills/sweep/SKILL.md +151 -0
- package/bundled/locales/zh-CN/skills/testing-guide/SKILL.md +207 -110
- package/bundled/locales/zh-TW/CHANGELOG.md +46 -3
- package/bundled/locales/zh-TW/README.md +1 -1
- package/bundled/locales/zh-TW/SECURITY.md +1 -1
- package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md +46 -0
- package/bundled/locales/zh-TW/core/ai-instruction-standards.md +130 -5
- package/bundled/locales/zh-TW/core/browser-compatibility-standards.md +222 -5
- package/bundled/locales/zh-TW/core/contract-testing-standards.md +184 -5
- package/bundled/locales/zh-TW/core/cross-flow-regression.md +192 -5
- package/bundled/locales/zh-TW/core/forward-derivation-standards.md +19 -0
- package/bundled/locales/zh-TW/core/knowledge-graph-memory.md +127 -0
- package/bundled/locales/zh-TW/core/release-readiness-gate.md +186 -5
- package/bundled/locales/zh-TW/core/self-review-protocol.md +9 -1
- package/bundled/locales/zh-TW/skills/ac-coverage/SKILL.md +192 -0
- package/bundled/locales/zh-TW/skills/adr-assistant/SKILL.md +21 -42
- package/bundled/locales/zh-TW/skills/ai-collaboration-standards/SKILL.md +5 -1
- package/bundled/locales/zh-TW/skills/brainstorm-assistant/SKILL.md +212 -59
- package/bundled/locales/zh-TW/skills/brainstorm-assistant/guide.md +266 -579
- package/bundled/locales/zh-TW/skills/commands/brainstorm.md +91 -26
- package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +77 -15
- package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +75 -16
- package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md +187 -0
- package/bundled/locales/zh-TW/skills/dev-methodology/SKILL.md +108 -0
- package/bundled/locales/zh-TW/skills/dev-methodology/guide.md +255 -0
- package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +125 -64
- package/bundled/locales/zh-TW/skills/journey-test-assistant/SKILL.md +222 -0
- package/bundled/locales/zh-TW/skills/knowledge-graph/SKILL.md +56 -0
- package/bundled/locales/zh-TW/skills/knowledge-graph/guide.md +74 -0
- package/bundled/locales/zh-TW/skills/migration-assistant/SKILL.md +128 -11
- package/bundled/locales/zh-TW/skills/observability-assistant/guide.md +188 -0
- package/bundled/locales/zh-TW/skills/orchestrate/SKILL.md +173 -0
- package/bundled/locales/zh-TW/skills/plan/SKILL.md +240 -0
- package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md +5 -1
- package/bundled/locales/zh-TW/skills/push/SKILL.md +242 -0
- package/bundled/locales/zh-TW/skills/retrospective-assistant/SKILL.md +94 -28
- package/bundled/locales/zh-TW/skills/reverse-engineer/SKILL.md +84 -28
- package/bundled/locales/zh-TW/skills/runbook-assistant/guide.md +216 -0
- package/bundled/locales/zh-TW/skills/skill-builder/SKILL.md +165 -0
- package/bundled/locales/zh-TW/skills/slo-assistant/guide.md +188 -0
- package/bundled/locales/zh-TW/skills/spec-derivation/SKILL.md +83 -0
- package/bundled/locales/zh-TW/skills/spec-derivation/guide.md +476 -0
- package/bundled/locales/zh-TW/skills/spec-driven-dev/SKILL.md +148 -77
- package/bundled/locales/zh-TW/skills/sweep/SKILL.md +149 -0
- package/bundled/locales/zh-TW/skills/testing-guide/SKILL.md +141 -44
- package/bundled/skills/adr-assistant/SKILL.md +1 -1
- package/bundled/skills/ai-collaboration-standards/SKILL.md +1 -1
- package/bundled/skills/ai-friendly-architecture/SKILL.md +1 -1
- package/bundled/skills/ai-instruction-standards/SKILL.md +1 -1
- package/bundled/skills/api-design-assistant/SKILL.md +1 -1
- package/bundled/skills/audit-assistant/SKILL.md +1 -1
- package/bundled/skills/brainstorm-assistant/SKILL.md +142 -106
- package/bundled/skills/brainstorm-assistant/guide.md +256 -661
- package/bundled/skills/ci-cd-assistant/SKILL.md +1 -1
- package/bundled/skills/commands/brainstorm.md +51 -30
- package/bundled/skills/contract-test-assistant/SKILL.md +1 -1
- package/bundled/skills/database-assistant/SKILL.md +1 -1
- package/bundled/skills/deploy-assistant/SKILL.md +1 -1
- package/bundled/skills/documentation-guide/SKILL.md +1 -1
- package/bundled/skills/error-code-guide/SKILL.md +1 -1
- package/bundled/skills/git-workflow-guide/SKILL.md +1 -1
- package/bundled/skills/incident-response-assistant/SKILL.md +1 -1
- package/bundled/skills/journey-test-assistant/SKILL.md +1 -1
- package/bundled/skills/knowledge-graph/SKILL.md +58 -0
- package/bundled/skills/knowledge-graph/guide.md +69 -0
- package/bundled/skills/logging-guide/SKILL.md +1 -1
- package/bundled/skills/observability-assistant/SKILL.md +1 -1
- package/bundled/skills/orchestrate/SKILL.md +1 -1
- package/bundled/skills/plan/SKILL.md +1 -1
- package/bundled/skills/pr-automation-assistant/SKILL.md +1 -1
- package/bundled/skills/project-structure-guide/SKILL.md +1 -1
- package/bundled/skills/push/SKILL.md +1 -1
- package/bundled/skills/retrospective-assistant/SKILL.md +1 -1
- package/bundled/skills/reverse-engineer/SKILL.md +1 -1
- package/bundled/skills/runbook-assistant/SKILL.md +1 -1
- package/bundled/skills/security-assistant/SKILL.md +1 -1
- package/bundled/skills/security-scan-assistant/SKILL.md +1 -1
- package/bundled/skills/slo-assistant/SKILL.md +1 -1
- package/bundled/skills/sweep/SKILL.md +1 -1
- package/bundled/skills/testing-guide/SKILL.md +1 -1
- package/package.json +2 -2
- package/src/commands/check.js +80 -0
- package/src/commands/init.js +8 -1
- package/src/commands/update.js +49 -14
- package/src/i18n/messages.js +32 -5
- package/src/installers/skills-installer.js +49 -0
- package/src/lint/i18n.js +424 -0
- package/src/utils/config-manager.js +39 -0
- package/src/utils/skills-installer.js +39 -7
- package/standards-registry.json +16 -4
- package/bundled/locales/zh-TW/docs/SKILL-FALLBACK-GUIDE.md +0 -407
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: journey-test-assistant
|
|
3
|
+
source: ../../../../skills/journey-test-assistant/SKILL.md
|
|
4
|
+
source_version: 1.0.0
|
|
5
|
+
translation_version: 1.0.0
|
|
6
|
+
last_synced: 2026-05-28
|
|
7
|
+
scope: partial
|
|
8
|
+
description: "[UDS] 從專案描述生成連貫使用者旅程測試計畫(TESTPLAN)與 E2E 骨架"
|
|
9
|
+
allowed-tools: Read, Write, Grep, Glob
|
|
10
|
+
argument-hint: "[專案描述 | --analyze | --archetype A1|A2|A3]"
|
|
11
|
+
status: stable
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# 旅程測試助手
|
|
15
|
+
|
|
16
|
+
> **語言**: [English](../../../../skills/journey-test-assistant/SKILL.md) | 繁體中文
|
|
17
|
+
|
|
18
|
+
從專案描述生成連貫的使用者旅程測試計畫(TESTPLAN-NNN.md)與對應的 E2E 骨架,讓每個新專案從第一天起就擁有完整測試旅程。
|
|
19
|
+
|
|
20
|
+
## 選擇正確的測試 Skill
|
|
21
|
+
|
|
22
|
+
| 需求 | 使用 |
|
|
23
|
+
|------|------|
|
|
24
|
+
| 單元測試 / TDD 紅綠重構 | `/tdd-assistant` |
|
|
25
|
+
| BDD 場景 / Given-When-Then | `/bdd-assistant` |
|
|
26
|
+
| 驗收測試 / ATDD / 使用者故事 | `/atdd-assistant` |
|
|
27
|
+
| E2E / Playwright / 瀏覽器測試 | `/e2e-assistant` |
|
|
28
|
+
| 合約測試 / API consumer-driven | `/contract-test-assistant` |
|
|
29
|
+
| 測試覆蓋率差距分析 | `/test-coverage-assistant` |
|
|
30
|
+
| 使用者旅程測試計畫 | `/journey-test-assistant` |
|
|
31
|
+
| 一般測試策略 / 測試金字塔 | `/testing-guide` |
|
|
32
|
+
|
|
33
|
+
## 與 /e2e 的差異
|
|
34
|
+
|
|
35
|
+
| 維度 | /e2e | /journey-test |
|
|
36
|
+
|------|------|--------------|
|
|
37
|
+
| 組織單位 | 單一 XSPEC / AC | 跨 Story 的使用者旅程 |
|
|
38
|
+
| 測試結構 | 隔離、獨立 | 連貫、狀態共享 |
|
|
39
|
+
| 產物 | `*.spec.ts` 骨架 | `TESTPLAN.md` + `*.journey.spec.ts` |
|
|
40
|
+
| 觸發時機 | 功能完成後 | 專案建立時(Journey-First) |
|
|
41
|
+
| 偵測目標 | 單一 AC 是否正確 | 跨步驟狀態傳遞是否連貫 |
|
|
42
|
+
|
|
43
|
+
## 工作流程
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
輸入:專案描述 / 現有 TESTPLAN / --analyze
|
|
47
|
+
↓
|
|
48
|
+
Phase 1:定義 Persona
|
|
49
|
+
分析專案描述 → 識別所有使用者角色 → 定義 Actor / Role / Key Permissions
|
|
50
|
+
↓
|
|
51
|
+
Phase 2:設計旅程地圖
|
|
52
|
+
列出主要業務目標 → 拆解為 T-NNN 群組 → 宣告依賴鏈
|
|
53
|
+
↓
|
|
54
|
+
Phase 3:生成 TESTPLAN
|
|
55
|
+
按格式輸出 test-plans/TESTPLAN-001.md(含 Personas、步驟、依賴圖)
|
|
56
|
+
↓
|
|
57
|
+
Phase 4:生成 E2E 骨架
|
|
58
|
+
從 TESTPLAN T-NNN 生成 *.journey.spec.ts(含 skipIf + 共享 state)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## 模式
|
|
62
|
+
|
|
63
|
+
### 1. 生成模式(預設)
|
|
64
|
+
|
|
65
|
+
從專案描述生成完整的 TESTPLAN + E2E 骨架。
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
/journey-test "電商平台,需要 buyer/seller/admin 三個角色"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
產物:
|
|
72
|
+
- `test-plans/TESTPLAN-001.md`:含 Personas、T-000 環境重置、T-001 ~ T-NNN 步驟群組、執行順序依賴圖
|
|
73
|
+
- `src/e2e/journey/main-flow.journey.spec.ts`:含 `describe.skipIf` + 共享 state + T-NNN 對應的完整骨架
|
|
74
|
+
|
|
75
|
+
### 2. 分析模式(--analyze)
|
|
76
|
+
|
|
77
|
+
掃描現有測試,找出旅程覆蓋缺口。
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
/journey-test --analyze
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
執行步驟:
|
|
84
|
+
1. 讀取 `test-plans/TESTPLAN-NNN.md`(若存在)
|
|
85
|
+
2. 掃描 `src/e2e/` 下所有 `*.journey.spec.ts` 與 `*.journey.e2e.test.ts`
|
|
86
|
+
3. 比對 TESTPLAN T-NNN 與自動化測試中的 T-NNN 引用
|
|
87
|
+
4. 輸出覆蓋缺口報告:列出 TESTPLAN 中缺乏自動化對應的 T-NNN 步驟
|
|
88
|
+
|
|
89
|
+
### 3. Archetype 模式(--archetype)
|
|
90
|
+
|
|
91
|
+
使用預設旅程模板,適合已知類型的專案快速啟動。
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
/journey-test --archetype A1 # Spec-driven 旅程
|
|
95
|
+
/journey-test --archetype A2 # UI-driven 旅程
|
|
96
|
+
/journey-test --archetype A3 # Brownfield 旅程
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
| Archetype | 模板 | 適用場景 |
|
|
100
|
+
|-----------|------|---------|
|
|
101
|
+
| A1 | Spec-driven | 需求 → Spec → Code → Test,適合 API / Backend 專案 |
|
|
102
|
+
| A2 | UI-driven | 設計稿 → UI → 視覺回歸,適合前端 / 全端專案 |
|
|
103
|
+
| A3 | Brownfield | 現有程式碼 → 分析 → 重構驗證,適合既有專案補測試 |
|
|
104
|
+
|
|
105
|
+
## TESTPLAN 格式(T-NNN)
|
|
106
|
+
|
|
107
|
+
以下為完整的 TESTPLAN 範本,展示所有必要區段:
|
|
108
|
+
|
|
109
|
+
```markdown
|
|
110
|
+
# TESTPLAN-001 <ProjectName> 主線旅程
|
|
111
|
+
|
|
112
|
+
## Personas
|
|
113
|
+
|
|
114
|
+
| Actor | Role | Key Permissions |
|
|
115
|
+
|----------------|----------------|--------------------------------|
|
|
116
|
+
| platform_admin | Platform Admin | 建立 Org、管理使用者、查看所有資源 |
|
|
117
|
+
| org_member | Org Member | 讀取專案、執行 Pipeline |
|
|
118
|
+
|
|
119
|
+
## Environment
|
|
120
|
+
|
|
121
|
+
- BASE_URL:`http://localhost:3000`(本機) / `$JOURNEY_BASE_URL`(CI)
|
|
122
|
+
- 驗證指令:`curl $BASE_URL/health`
|
|
123
|
+
- 必要帳號:`ADMIN_EMAIL`、`ADMIN_PASSWORD` 環境變數
|
|
124
|
+
|
|
125
|
+
## T-000 環境重置(optional)
|
|
126
|
+
|
|
127
|
+
前置條件:無
|
|
128
|
+
depends_on:無
|
|
129
|
+
|
|
130
|
+
| 步驟 | 操作 | 預期結果 |
|
|
131
|
+
|---------|-------------------------------|---------------|
|
|
132
|
+
| T-000-1 | [API] GET /health | 回傳 200 OK |
|
|
133
|
+
| T-000-2 | [CHECK] 資料庫連線正常 | 無錯誤日誌 |
|
|
134
|
+
|
|
135
|
+
## T-001 Platform Admin 登入
|
|
136
|
+
|
|
137
|
+
前置條件:環境正常運行(T-000 通過)
|
|
138
|
+
depends_on:T-000
|
|
139
|
+
|
|
140
|
+
| 步驟 | 操作 | 預期結果 |
|
|
141
|
+
|---------|--------------------------------------------|-------------------------|
|
|
142
|
+
| T-001-1 | [API] POST /api/auth/login(admin 帳號) | 回傳 200 + authToken |
|
|
143
|
+
| T-001-2 | [CHECK] authToken 存入共享 state | let authToken 有值 |
|
|
144
|
+
|
|
145
|
+
## T-010 主要功能操作
|
|
146
|
+
|
|
147
|
+
前置條件:authToken 已取得(T-001 通過)
|
|
148
|
+
depends_on:T-001
|
|
149
|
+
|
|
150
|
+
| 步驟 | 操作 | 預期結果 |
|
|
151
|
+
|---------|--------------------------------------------|-------------------------|
|
|
152
|
+
| T-010-1 | [API] POST /api/resources(帶 authToken) | 回傳 201 + resourceId ★ |
|
|
153
|
+
| T-010-2 | [CHECK] resourceId 存入共享 state | let resourceId 有值 |
|
|
154
|
+
|
|
155
|
+
## 執行順序依賴圖
|
|
156
|
+
|
|
157
|
+
T-000 → T-001 → T-010
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## E2E 骨架格式(.journey.spec.ts)
|
|
161
|
+
|
|
162
|
+
生成的骨架展示三個核心模式:`describe.skipIf` 環境保護、共享 `let` 狀態、T-NNN 識別碼對應。
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
import { describe, it, expect } from "vitest"
|
|
166
|
+
|
|
167
|
+
// Journey E2E:需要真實後端,不設定 JOURNEY_BASE_URL 則全部 skip
|
|
168
|
+
const BASE_URL = process.env.JOURNEY_BASE_URL || ""
|
|
169
|
+
|
|
170
|
+
describe.skipIf(!BASE_URL)("Platform Admin Journey — T-001 → T-010", () => {
|
|
171
|
+
// 共享 state:每個步驟從前一步驟的結果取值
|
|
172
|
+
let authToken: string
|
|
173
|
+
let resourceId: string
|
|
174
|
+
|
|
175
|
+
it("T-001: Platform Admin 登入並取得 authToken", async () => {
|
|
176
|
+
const res = await fetch(`${BASE_URL}/api/auth/login`, {
|
|
177
|
+
method: "POST",
|
|
178
|
+
headers: { "Content-Type": "application/json" },
|
|
179
|
+
body: JSON.stringify({
|
|
180
|
+
email: process.env.ADMIN_EMAIL,
|
|
181
|
+
password: process.env.ADMIN_PASSWORD,
|
|
182
|
+
}),
|
|
183
|
+
})
|
|
184
|
+
expect(res.status, "T-001 失敗:登入應回傳 200").toBe(200)
|
|
185
|
+
const data = await res.json()
|
|
186
|
+
expect(data.token, "T-001 失敗:應有 token").toBeTruthy()
|
|
187
|
+
authToken = data.token // ← 傳遞給後續步驟
|
|
188
|
+
})
|
|
189
|
+
|
|
190
|
+
it("T-010: 執行主要操作(depends on T-001)", async () => {
|
|
191
|
+
// 若 T-001 失敗,authToken 為 undefined,此步驟的錯誤訊息會清楚說明
|
|
192
|
+
expect(authToken, "T-010 前置失敗:T-001 的 authToken 不存在").toBeTruthy()
|
|
193
|
+
|
|
194
|
+
const res = await fetch(`${BASE_URL}/api/resources`, {
|
|
195
|
+
method: "POST",
|
|
196
|
+
headers: {
|
|
197
|
+
"Content-Type": "application/json",
|
|
198
|
+
Authorization: `Bearer ${authToken}`,
|
|
199
|
+
},
|
|
200
|
+
body: JSON.stringify({ name: "journey-test-resource" }),
|
|
201
|
+
})
|
|
202
|
+
expect(res.status, `T-010 失敗:預期 201,實際 ${res.status}`).toBe(201)
|
|
203
|
+
const data = await res.json()
|
|
204
|
+
resourceId = data.id // ← 傳遞給後續步驟
|
|
205
|
+
})
|
|
206
|
+
})
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## 後續步驟
|
|
210
|
+
|
|
211
|
+
完成後建議:
|
|
212
|
+
|
|
213
|
+
> **TESTPLAN 與 Journey E2E 骨架已生成。建議下一步:**
|
|
214
|
+
> - 執行 `/e2e` 生成各功能的 AC 層測試(補充旅程測試的細節覆蓋)
|
|
215
|
+
> - 執行 `/atdd` 定義各 T-NNN 步驟對應的驗收條件
|
|
216
|
+
> - 執行 `/journey-test --analyze` 定期檢查自動化覆蓋缺口
|
|
217
|
+
|
|
218
|
+
## 參考
|
|
219
|
+
|
|
220
|
+
- 標準:[user-journey-testing.ai.yaml](../../../../.standards/user-journey-testing.ai.yaml)
|
|
221
|
+
- 相關 XSPEC:XSPEC-128(UDS 標準定義)
|
|
222
|
+
- 相關 Skill:`/e2e`(AC 層測試)、`/atdd`(驗收條件定義)
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: knowledge-graph
|
|
3
|
+
source: ../../../../skills/knowledge-graph/SKILL.md
|
|
4
|
+
source_version: 1.0.0
|
|
5
|
+
translation_version: 1.0.0
|
|
6
|
+
last_synced: 2026-05-30
|
|
7
|
+
status: current
|
|
8
|
+
description: "[UDS] 透過知識圖追蹤規格/決策/程式碼的影響鏈(引擎或 Markdown 後備)"
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# 知識圖
|
|
12
|
+
|
|
13
|
+
> **語言**: [English](../../../../skills/knowledge-graph/SKILL.md) | 繁體中文
|
|
14
|
+
|
|
15
|
+
依據[知識圖記憶標準](../../../../core/knowledge-graph-memory.md)的關係 schema,回答橫跨規格、決策與程式碼的結構性問題——*「XSPEC-205 的完整影響鏈是什麼?」*。有無圖引擎皆可運作。
|
|
16
|
+
|
|
17
|
+
> **Implements**: XSPEC-237 Phase 5 — knowledge-graph skill(EngramGraph opt-in)
|
|
18
|
+
|
|
19
|
+
## 模式選擇
|
|
20
|
+
|
|
21
|
+
回答**前**先判斷使用哪種模式:
|
|
22
|
+
|
|
23
|
+
| 條件 | 模式 |
|
|
24
|
+
|------|------|
|
|
25
|
+
| 設定了 `ENGRAM_URL`,或本機圖引擎 `/health` 有回應 | 服務模式(引擎)|
|
|
26
|
+
| 否則 | 降級模式(Markdown)|
|
|
27
|
+
|
|
28
|
+
## 工作流程
|
|
29
|
+
|
|
30
|
+
1. **解析目標**——將參數正規化為標準 id(`XSPEC-205`、`DEC-062`、函式名)。
|
|
31
|
+
2. **選擇模式**——探測圖引擎(服務)否則後備(降級)。
|
|
32
|
+
3. **服務模式(AC-5b)**——送出單一多跳查詢,呈現回傳的鏈(含跨域連結 code → spec → decision):
|
|
33
|
+
```bash
|
|
34
|
+
curl -s -X POST "$ENGRAM_URL/graph/impact-analysis" \
|
|
35
|
+
-H 'content-type: application/json' \
|
|
36
|
+
-d '{"nodeId":"XSPEC-205","maxHops":3}'
|
|
37
|
+
```
|
|
38
|
+
4. **降級模式(AC-5a)**——無引擎時,讀取目標文件,沿其 `impacts`/`impacted_by`/`supersedes`/`related` front-matter 與內文 `[[ref]]` 連結讀取被連結檔案,手動組出鏈(受讀取深度限制)。
|
|
39
|
+
5. **呈現鏈**——列出相連的 Spec 與 Decision、每跳的邊型別、以及(若有)各節點的 `confidence`,高者在前。
|
|
40
|
+
6. **說明使用的模式**——務必告知答案來自引擎或 Markdown 後備,以明確完整度。
|
|
41
|
+
|
|
42
|
+
## 關係 schema
|
|
43
|
+
|
|
44
|
+
見[知識圖記憶標準](../../../../core/knowledge-graph-memory.md)。front-matter 欄位:`related`、`impacts`、`impacted_by`、`supersedes`、`implements`。
|
|
45
|
+
|
|
46
|
+
## 下一步引導
|
|
47
|
+
|
|
48
|
+
- 降級模式若觸及讀取深度上限,告知使用者圖引擎(如 EngramGraph)可給出完整鏈,以及如何設定 `ENGRAM_URL`。
|
|
49
|
+
- 若參照的 id 找不到,標示為待修的懸空參照。
|
|
50
|
+
- 主動提議為遍歷過的文件補上缺漏的 `impacts`/`impacted_by` front-matter。
|
|
51
|
+
|
|
52
|
+
## 參考
|
|
53
|
+
|
|
54
|
+
- 標準:[core/knowledge-graph-memory.md](../../../../core/knowledge-graph-memory.md)
|
|
55
|
+
- 引擎(opt-in):[EngramGraph](https://github.com/AsiaOstrich/EngramGraph) — `engramgraph`
|
|
56
|
+
- 詳細指南:[guide.md](guide.md)
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
source: ../../../../skills/knowledge-graph/guide.md
|
|
3
|
+
source_version: 1.0.0
|
|
4
|
+
translation_version: 1.0.0
|
|
5
|
+
last_synced: 2026-06-02
|
|
6
|
+
source_hash: 9c86b5a2a71d
|
|
7
|
+
status: current
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Knowledge Graph — 詳細指南
|
|
11
|
+
|
|
12
|
+
[SKILL.md](SKILL.md) 的配套說明。兩種運作模式的範例與引擎 API。
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. 服務模式(graph 引擎)
|
|
17
|
+
|
|
18
|
+
當有相容於 EngramGraph 的引擎可連線時,單次查詢即可回傳完整影響鏈。
|
|
19
|
+
|
|
20
|
+
### 影響分析
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
curl -s -X POST "$ENGRAM_URL/graph/impact-analysis" \
|
|
24
|
+
-H 'content-type: application/json' \
|
|
25
|
+
-d '{"nodeId":"XSPEC-205","maxHops":3}'
|
|
26
|
+
# => { "nodeId": "XSPEC-205",
|
|
27
|
+
# "decisions": [ {"id":"DEC-062","title":"...","via":"direct"},
|
|
28
|
+
# {"id":"DEC-069","title":"...","via":"supersedes"} ] }
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
`via: "direct"` 表示該決策直接 IMPACTS 此 spec;`via: "supersedes"` 表示它透過 SUPERSEDES 影響鏈(≤ `maxHops`)連到此 spec。
|
|
32
|
+
|
|
33
|
+
### 信心回饋(SAGE)
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
curl -s -X POST "$ENGRAM_URL/graph/ingest" \
|
|
37
|
+
-H 'content-type: application/json' \
|
|
38
|
+
-d '{"type":"test_fail","functionId":"src/a.ts#execute"}'
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
降低該節點的信心值;之後讀取時會優先浮現信心較高的節點。
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 2. 降級模式(僅 Markdown)
|
|
46
|
+
|
|
47
|
+
不需要引擎。透過讀取檔案重建影響鏈:
|
|
48
|
+
|
|
49
|
+
1. 讀取目標文件(例如 `XSPEC-205`)。
|
|
50
|
+
2. 從其 front-matter(`impacts`、`impacted_by`、`supersedes`、`related`)與行內 `[[ref]]` 連結蒐集 id。
|
|
51
|
+
3. 對每個 id,讀取該文件並重複此過程,直到所需的跳數深度。
|
|
52
|
+
4. 依前綴分類每個 id(`XSPEC-*`/`SPEC-*` → Spec;`DEC-*`/`ADR-*` → Decision)並回報邊。
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# find the documents
|
|
56
|
+
grep -rl "id: XSPEC-205" --include='*.md' .
|
|
57
|
+
# discover outbound references
|
|
58
|
+
grep -nE "(impacts|impacted_by|supersedes|related):|\[\[(XSPEC|DEC|ADR)-" path/to/XSPEC-205.md
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
降級模式永遠正確,但受限於你讀取了多少檔案;跨領域的程式碼連結(function → spec)通常只在服務模式中可用。
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## 3. 等價性
|
|
66
|
+
|
|
67
|
+
兩種模式產生**相同形狀的答案**(一份相連的 Specs/Decisions 清單,附帶邊類型)。服務模式更快且更完整(可包含 code→spec→decision 的跳轉);降級模式則是通用後備。務必告知使用者答案來自哪種模式。
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## 參考
|
|
72
|
+
|
|
73
|
+
- [core/knowledge-graph-memory.md](../../core/knowledge-graph-memory.md)
|
|
74
|
+
- [EngramGraph](https://github.com/AsiaOstrich/EngramGraph)
|
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
name: migration-assistant
|
|
3
3
|
source: ../../../../skills/migration-assistant/SKILL.md
|
|
4
4
|
source_version: 1.0.0
|
|
5
|
+
source_hash: 67b6f33f825e
|
|
5
6
|
translation_version: 1.0.0
|
|
6
|
-
last_synced: 2026-
|
|
7
|
+
last_synced: 2026-06-01
|
|
7
8
|
status: current
|
|
8
9
|
description: "[UDS] 引導程式碼遷移、框架升級與技術現代化"
|
|
9
10
|
---
|
|
@@ -21,19 +22,19 @@ description: "[UDS] 引導程式碼遷移、框架升級與技術現代化"
|
|
|
21
22
|
| `/migrate` | 啟動互動式遷移引導 |
|
|
22
23
|
| `/migrate --assess` | 僅風險評估 |
|
|
23
24
|
| `/migrate "Vue 2 to 3"` | 引導特定遷移 |
|
|
24
|
-
| `/migrate --deps` |
|
|
25
|
+
| `/migrate --deps` | 相依升級分析 |
|
|
25
26
|
| `/migrate --rollback` | 規劃回滾策略 |
|
|
26
27
|
|
|
27
28
|
## 遷移類型
|
|
28
29
|
|
|
29
30
|
| 類型 | 範例 | 風險 |
|
|
30
31
|
|------|------|------|
|
|
31
|
-
| **框架升級** | React 17→18, Vue 2→3 | 中高 |
|
|
32
|
-
| **語言遷移** | JS→TS, Python 2→3 | 高 |
|
|
33
|
-
| **API 版本** | REST v1→v2, GraphQL 更新 | 中 |
|
|
34
|
-
| **資料庫遷移** | MySQL→PostgreSQL | 極高 |
|
|
35
|
-
| **建構工具** | Webpack→Vite | 低中 |
|
|
36
|
-
| **套件管理器** | npm→pnpm | 低 |
|
|
32
|
+
| **框架升級** | React 17→18, Vue 2→3, Angular 15→17 | 中高 |
|
|
33
|
+
| **語言遷移** | JS→TS, Python 2→3, Java 8→17 | 高 |
|
|
34
|
+
| **API 版本** | REST v1→v2, GraphQL schema 更新 | 中 |
|
|
35
|
+
| **資料庫遷移** | MySQL→PostgreSQL, SQL→NoSQL | 極高 |
|
|
36
|
+
| **建構工具** | Webpack→Vite, Grunt→ESBuild | 低中 |
|
|
37
|
+
| **套件管理器** | npm→pnpm, pip→poetry | 低 |
|
|
37
38
|
|
|
38
39
|
## 風險評估矩陣
|
|
39
40
|
|
|
@@ -46,11 +47,97 @@ description: "[UDS] 引導程式碼遷移、框架升級與技術現代化"
|
|
|
46
47
|
## 工作流程
|
|
47
48
|
|
|
48
49
|
1. **評估** - 評估現狀、識別破壞性變更
|
|
49
|
-
2. **規劃** -
|
|
50
|
+
2. **規劃** - 建立含相依關係的遷移清單
|
|
50
51
|
3. **準備** - 設定 codemods、相容層、功能旗標
|
|
51
52
|
4. **遷移** - 分階段執行遷移並測試
|
|
52
53
|
5. **驗證** - 執行完整測試套件、檢查回歸
|
|
53
|
-
6. **清理** -
|
|
54
|
+
6. **清理** - 移除相容層、舊相依
|
|
55
|
+
|
|
56
|
+
## API 遷移合約測試
|
|
57
|
+
|
|
58
|
+
當 API endpoint 從一個技術棧遷至另一個(PHP → .NET、Express → Spring、Python → Go),對**新**實作的單元測試只驗證**新 DTO**——無法捕捉「舊版有但新版漏掉的欄位」。欄位缺漏、欄位 rename、型別漂移,以及頂層 vs nested 層級漂移等問題會靜默流入生產,導致仍預期舊版 shape 的既有前端失靈。
|
|
59
|
+
|
|
60
|
+
**僅靠單元測試、整合測試或 code review 無法防止**。2026-05-24 真實 PROD 事故:67/67 測試全綠流入正式環境,由客戶發現缺漏。
|
|
61
|
+
|
|
62
|
+
### 強制規則
|
|
63
|
+
|
|
64
|
+
每個被遷移的 API endpoint **必須**至少有一份 contract test,比對新實作的 response 與從 legacy 實作捕獲的 fixture。驗證的是結構性等價(keys、type、層級位置),而非值等價。
|
|
65
|
+
|
|
66
|
+
### Fixture 捕獲協議
|
|
67
|
+
|
|
68
|
+
**Legacy 仍運行(典型遷移窗口):**
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# 1. Capture ≥3 representative inputs (happy path, edge case, empty result)
|
|
72
|
+
curl -X POST $LEGACY_BASE/endpoint -d @input1.json \
|
|
73
|
+
> tests/fixtures/migration/endpoint/scenario1.json
|
|
74
|
+
curl -X POST $LEGACY_BASE/endpoint -d @input2_empty.json \
|
|
75
|
+
> tests/fixtures/migration/endpoint/scenario2_empty.json
|
|
76
|
+
curl -X POST $LEGACY_BASE/endpoint -d @input3_edge.json \
|
|
77
|
+
> tests/fixtures/migration/endpoint/scenario3_edge.json
|
|
78
|
+
|
|
79
|
+
# 2. Scrub PII and volatile values (timestamps, generated IDs)
|
|
80
|
+
jq 'walk(if type == "string" and test("@") then "redacted@example.com" else . end)' \
|
|
81
|
+
tests/fixtures/migration/endpoint/scenario1.json > tmp && mv tmp ...
|
|
82
|
+
|
|
83
|
+
# 3. Commit fixtures
|
|
84
|
+
git add tests/fixtures/migration/endpoint/
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
**Legacy 已退役但 source 可讀:**
|
|
88
|
+
|
|
89
|
+
- 追蹤 legacy source code,手動建構預期的 response shape
|
|
90
|
+
- 將每個欄位的來源(SQL 欄位、計算式、hardcoded)記錄於同位置的 `.notes.md` 檔案
|
|
91
|
+
|
|
92
|
+
### Contract test 範本
|
|
93
|
+
|
|
94
|
+
**C# / xUnit:**
|
|
95
|
+
|
|
96
|
+
```csharp
|
|
97
|
+
[Theory]
|
|
98
|
+
[InlineData("scenario1")]
|
|
99
|
+
[InlineData("scenario2_empty")]
|
|
100
|
+
[InlineData("scenario3_edge")]
|
|
101
|
+
public async Task Endpoint_ResponseShape_MatchesLegacyFixture(string scenario)
|
|
102
|
+
{
|
|
103
|
+
var fixture = LoadFixture($"migration/endpoint/{scenario}");
|
|
104
|
+
var response = await CallNewImpl(fixture.Input);
|
|
105
|
+
// StructuralEquivalence checks keys + types + placement, ignores values
|
|
106
|
+
StructuralEquivalence.Assert(response, fixture.ExpectedShape);
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**TypeScript / Jest:**
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
import { structuralEquivalence } from "./test-utils/structural-equivalence";
|
|
114
|
+
|
|
115
|
+
describe.each([
|
|
116
|
+
["scenario1"],
|
|
117
|
+
["scenario2_empty"],
|
|
118
|
+
["scenario3_edge"],
|
|
119
|
+
])("Endpoint response shape vs legacy fixture (%s)", (scenario) => {
|
|
120
|
+
test("matches", async () => {
|
|
121
|
+
const fixture = loadFixture(`migration/endpoint/${scenario}.json`);
|
|
122
|
+
const response = await callNewImpl(fixture.input);
|
|
123
|
+
structuralEquivalence(response, fixture.expectedShape);
|
|
124
|
+
});
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`structuralEquivalence` / `StructuralEquivalence.Assert` 規則:每一層具備相同的 key 集合(不可缺漏、不可多出,除非明確 opt in)、每個 key 具相同的基本型別、相同的層級位置(頂層 vs nested)。值可以不同(timestamps、IDs);型別與結構不可不同。
|
|
129
|
+
|
|
130
|
+
### 逐欄位遷移稽核清單
|
|
131
|
+
|
|
132
|
+
合併任何被遷移的 endpoint 前:
|
|
133
|
+
|
|
134
|
+
- [ ] 所有 legacy response 欄位皆 mapping 至新 DTO(無 silent drop)
|
|
135
|
+
- [ ] 儘量保留命名(避免將 `TotalX` rename 而丟失「per-member」語意)
|
|
136
|
+
- [ ] 保留頂層 vs nested 層級位置
|
|
137
|
+
- [ ] 已驗證型別相容性(string→int 轉換為明確而非巧合)
|
|
138
|
+
- [ ] Error path return code 與 legacy 一致(`509` 而非 `506`;`404` 而非 `400`)
|
|
139
|
+
- [ ] Contract test fixture 已 commit 至 `tests/fixtures/migration/`
|
|
140
|
+
- [ ] Cross-link 至 [contract-test-assistant](../contract-test-assistant/SKILL.md) 做持續的消費端驗證
|
|
54
141
|
|
|
55
142
|
## 回滾策略
|
|
56
143
|
|
|
@@ -61,15 +148,45 @@ description: "[UDS] 引導程式碼遷移、框架升級與技術現代化"
|
|
|
61
148
|
| **雙運行** | 關鍵系統、零停機 |
|
|
62
149
|
| **分支凍結** | 一次性完整遷移 |
|
|
63
150
|
|
|
151
|
+
## 使用範例
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
User: /migrate "Vue 2 to 3"
|
|
155
|
+
AI: Migration Assessment: Vue 2 → Vue 3
|
|
156
|
+
Breaking changes found: 12
|
|
157
|
+
- Options API → Composition API (47 components)
|
|
158
|
+
- Filters removed (8 usages)
|
|
159
|
+
- Event bus removed (3 usages)
|
|
160
|
+
Risk: Medium-High
|
|
161
|
+
Estimated effort: 2-3 weeks
|
|
162
|
+
Recommended: Staged migration with @vue/compat
|
|
163
|
+
```
|
|
164
|
+
|
|
64
165
|
## 下一步引導
|
|
65
166
|
|
|
66
167
|
`/migrate` 完成後,AI 助手應建議:
|
|
67
168
|
|
|
68
169
|
> **遷移分析完成。建議下一步:**
|
|
69
170
|
> - 執行 `/reverse` 深入理解現有程式碼
|
|
70
|
-
> - 執行 `/testing` 確保遷移後測試通過
|
|
171
|
+
> - 執行 `/testing` 確保遷移後測試通過 ⭐ **推薦**
|
|
71
172
|
> - 執行 `/commit` 提交遷移變更
|
|
72
173
|
|
|
73
174
|
## 參考
|
|
74
175
|
|
|
75
176
|
- 核心規範:[refactoring-standards.md](../../../../core/refactoring-standards.md)
|
|
177
|
+
- 相關:[contract-test-assistant](../contract-test-assistant/SKILL.md) — 遷移後持續合約驗證的策略
|
|
178
|
+
|
|
179
|
+
## 版本歷史
|
|
180
|
+
|
|
181
|
+
| 版本 | 日期 | 變更 |
|
|
182
|
+
|------|------|------|
|
|
183
|
+
| 1.1.0 | 2026-05-26 | 新增:API 遷移合約測試章節——強制 fixture 捕獲協議、C#/TS 範本、逐欄位稽核清單(XSPEC-233 / closes #112) |
|
|
184
|
+
| 1.0.0 | 2026-03-24 | 初始版本 |
|
|
185
|
+
|
|
186
|
+
## AI 代理行為
|
|
187
|
+
|
|
188
|
+
> 完整的 AI 行為定義請參閱對應的命令文件:[`/migrate`](../commands/migrate.md#ai-agent-behavior--ai-代理行為)
|
|
189
|
+
|
|
190
|
+
## 授權
|
|
191
|
+
|
|
192
|
+
CC BY 4.0
|