| doc_id | doc_agentskill_0018 |
| name | general-data-pipeline |
| description | 武將資料管線 SKILL — 整合「公開資料爬取 → 欄位映射 → 合併去重 → 自動分類 → 品質驗證 → 匯出入庫」的端到端流程。USE FOR: 批次新增武將、從光榮三國志 Wiki 匯入參考數值、建立 master 資料集。DO NOT USE FOR: 故事文案生成（用 general-story-writer）、細部數值微調（用 general-balance-tuner）。 |
| argument-hint | 指定操作階段（scrape / map / merge / classify / validate / export / full）、目標武將範圍（faction / name list / all）、以及資料來源（wiki / koei / manual）。 |
General Data Pipeline
用這個 skill 執行武將資料的完整收集與入庫管線，從公開資料來源到結構化 JSON。
Unity 對照：類似 AssetPostprocessor 的自動匯入管線，但對象是遊戲設計資料而非美術素材。
When to Use
- 需要批次新增數十到數百位武將的基礎資料
- 需要從光榮三國志系列 Wiki 抓取屬性參考值
- 需要將外部資料源映射為 GeneralConfig 格式
- 需要對新匯入的武將自動執行稀有度分類 + 品質驗證
- 需要建立分層的 master 資料集（base / lore / stories）
- 同一批外部來源會被多輪或多個 Agent 重複查詢，想先把它們收斂成 repo-local CLI
Do Not Use
- 不要用這個 skill 生成不存在於公開資料的虛構內容（用
general-story-writer）
- 不要用這個 skill 做精細的單一武將數值微調（用
general-balance-tuner）
- 不要用這個 skill 直接覆蓋正式的
generals.json（匯出前必須人工確認）
Procedure
Phase A：資料收集（Scrape）
A0. 外部來源 intake 先判斷要不要走 agent-cli-factory
- 若來源只會用一次，或授權 / TOS / 反爬風險不清楚，維持手動整理或使用者貼資料。
- 若同一個 Wiki / 網站 / SaaS 會被多輪或多 Agent 反覆查，先用
agent-cli-factory 建立或重用 repo-local CLI。
- CLI 輸出優先固定為
--compact + --json，把 raw HTML / 長頁面 / 大 payload 留在本機 cache，不直接塞進對話。
- CLI 只能寫
artifacts/data-pipeline/ 或 local/agent-cli-cache/ 這類中間產物；不得直接覆蓋 generals.json。
- 現成 intake CLI：
node tools_node/agent-clis/3klife-sanguo-source.js \
--wiki-cache temp_workspace/wiki-cache.json \
--cache-id zhuge-liang \
--name 諸葛亮 \
--compact
node tools_node/agent-clis/3klife-sanguo-source.js \
--input-file artifacts/data-pipeline/source-intake/zhuge-liang-koei.txt \
--source-type koei-stats \
--name 諸葛亮 \
--json
A1. 資料來源
| 來源 | URL 範例 | 取得內容 |
|---|
| 維基百科三國志人物列表 | zh.wikipedia.org/wiki/三國志人物列表 | 姓名、字、籍貫、所屬勢力、生卒年、官職 |
| 光榮三國志 Wiki | koei.fandom.com/wiki/ | 五維數值（武力/智力/統率/政治/魅力）、技能、兵種適性 |
| 手動輸入 | N/A | 自創武將、神話人物、特殊版本 |
A2. 欄位映射表
維基百科 → GeneralConfig：
| Wiki 欄位 | GeneralConfig 欄位 | 轉換規則 |
|---|
| 姓名 | name | 直接映射 |
| 字 | title | 前綴「字」去除 |
| 所屬 | faction | 映射：蜀漢→Shu, 曹魏→Wei, 東吳→Wu, 其他→Qun |
| 籍貫 | storyStripCells[0].text（origin slot） | 簡化為地名 |
| 官職 | role | 映射為戰場定位 |
光榮三國志 → GeneralConfig：
| 光榮欄位 | GeneralConfig 欄位 | 轉換規則 |
|---|
| 武力 | str | 直接映射（0-100） |
| 智力 | int | 直接映射（0-100） |
| 統率 | lea | 直接映射（0-100） |
| 政治 | pol | 直接映射（0-100） |
| 魅力 | cha | 直接映射（0-100） |
| 運 | luk | 直接映射（若有） |
| 特技 | learnedTactics[] | 映射為技能 ID |
| 適性（騎/步/弓/水） | troopAptitude | 映射為 S/A/B/C 等級 |
Phase B：合併去重（Merge）
B1. 合併規則
- 以
name + faction 為 unique key
- 若同一武將在多個來源出現，取光榮數值為主、維基背景為輔
- 產出 master 資料前標記來源：
source: "wiki+koei" / source: "manual"
B2. ID 生成規則
id = kebab-case(name-pinyin)
例：趙雲 → zhao-yun
例：諸葛亮 → zhuge-liang
例：神趙雲 → shen-zhao-yun
templateId 生成規則：
templateId = "GEN_{FACTION}_{NAME_UPPER}"
例：趙雲 → GEN_SHU_ZHAO_YUN
例：曹操 → GEN_WEI_CAO_CAO
Phase C：自動分類（Classify）
呼叫 general-balance-tuner skill 的邏輯：
- 對每位新武將執行雙軸稀有度計算
- 根據五維數值自動建議
characterCategory
- 計算 EP_base 與 epRating
- 產出分類報告
Phase D：品質驗證（Validate）
D1. 必填欄位檢查
必填：id, name, faction, hp, str, int, lea
建議：pol, cha, luk, role, title, characterCategory
D2. 數值範圍驗證
| 欄位 | 有效範圍 |
|---|
| str, int, lea, pol, cha, luk | 0-100（一般）/ 0-120（神話） |
| hp | 80-300 |
| ep | 0-100 |
| maxSp | 50-200 |
D3. 一致性檢查
rarityTier 與雙軸計算結果是否一致characterCategory 與 rarityTier 搭配是否合理- 同陣營武將的數值分布是否過於集中
- 是否有重複 ID 或重複 name+faction
D4. 驗證報告格式
=== 品質驗證報告 ===
檢查武將數：50
通過：45
警告：3
⚠️ 文聘 (wen-pin): pol 欄位缺失
⚠️ 蔣欽 (jiang-qin): 兵種適性全為 B，建議至少 1 個 A
⚠️ 左慈 (zuo-ci): characterCategory=civilian 但 int=95（建議改為 famed）
錯誤：2
❌ 無名氏 (unknown-1): 缺少必填欄位 faction
❌ 重複 ID: zhao-yun 出現 2 次
Phase E：匯出入庫（Export）
E1. 分層匯出
assets/resources/data/
generals.json ← 正式入庫（需人工確認）
master/
generals-base.json ← 基礎屬性（批次匯入中間產物）
generals-lore.json ← 歷史背景（延遲載入資料）
generals-stories.json ← 故事條模板
E2. 匯出前 checklist
Batch Workflow Example
完整的 50 位武將匯入流程：
1. [Scrape] 準備 wiki 資料 + 光榮數值
→ 產出 raw-generals-batch-1.json
2. [Map] 對照欄位映射表轉換格式
→ 產出 mapped-generals-batch-1.json
3. [Merge] 合併雙來源、去重、生成 ID
→ 產出 merged-generals-batch-1.json
4. [Classify] 呼叫 general-balance-tuner 跑雙軸分類
→ 產出 classified-generals-batch-1.json
5. [Validate] 品質驗證
→ 產出 validation-report-batch-1.txt
6. [Review] 人工審核 SSR/UR 武將 + 修正 warning
→ 確認 classified-generals-batch-1.json
7. [Export] 併入 generals.json
→ 更新正式資料 + encoding 檢查
Interconnection
-
下游 skill：
general-balance-tuner — Phase C 自動分類時呼叫general-story-writer — 入庫後為缺少故事的武將批次生成內容encoding-touched-guard — 每次匯出後檢查編碼
-
設定檔依賴：
assets/resources/data/rarity-thresholds.json — 稀有度門檻assets/scripts/core/models/GeneralUnit.ts — GeneralConfig 型別定義
Notes
- Mapping / merge / classify / validate 這幾段是本地 deterministic 流程；只有 scrape intake 可能需要外部來源。
- 若 scrape 會重複發生，優先走
agent-cli-factory 做 repo-local CLI，而不是反覆 Browser/Playwright。
- Wiki 資料的取得若授權或法律風險不清楚，仍建議由使用者手動複製貼上，或只抓可公開使用的 compact 欄位摘要。
- 光榮數值僅作為「參考基準」，最終數值可由設計師調整
- 所有匯出都需要人工確認，skill 不會自動覆蓋正式 generals.json
- 中間產物建議放在
artifacts/data-pipeline/ 目錄
