AGI（Agentic Guideline Intelligence）完整教學

第 1 章：專案定位與核心價值

1.1 什麼是 AGI？

AGI（Agentic Guideline Intelligence; 代理式規範智慧）是一套從 128 份國際品牌 Brand Guideline（品牌規範手冊）蒸餾而成的知識圖譜系統。它不是傳統的 Web 應用程式，也不是單純的文件範本庫——而是一套結合結構化知識庫 + AI Agent Skill + 推理引擎的完整工作流，目標是讓 AI 代理人能模擬高階設計師的決策順序，為新客戶規劃並撰寫 Brand Guideline 初稿。

1.2 核心理念：「為什麼」而非「是什麼」

AGI 與一般品牌範本庫的根本差異在於：它不教你「品牌長什麼樣」，而是教你「品牌為什麼長這樣」。每一個推薦都連回真實先例證據，每一個設計決策都有可追溯的知識圖譜路徑。

1.3 解決的問題

1.4 適用對象

• 品牌設計師 / Design Director (設計總監)：需要為新客戶快速建立 Guideline 骨架
• 品牌顧問 / 策略師：需要以證據為基礎的設計決策建議
• AI Agent 開發者：想學習如何用結構化知識庫驅動 Agent 推理
• 設計教學者：需要系統化的品牌設計決策教材

第 2 章：安裝指南

2.1 環境需求

• Git：用於 clone 專案
• Python 3（選用）：僅在執行知識庫維護腳本時需要
• PyYAML（選用）：pip install pyyaml（僅維護腳本需要）
• AI Agent 工具：Claude Code、Cursor、Codex 等支援讀取 SKILL.md 的 Agent 工具

2.2 安裝步驟

 1# 1. Clone 專案
 2git clone https://github.com/maylogger/AGI.git
 3cd AGI
 4
 5# 2. （選用）若需執行維護腳本
 6pip install pyyaml
 7
 8# 3. （選用）若要分析既有 PDF，將 PDF 放入 sources/
 9mkdir -p sources/
10# 將品牌手冊 PDF 複製到 sources/ 目錄

2.3 Agent 整合

AGI 的核心能力來自 Agent 讀取 .agents/skills/agi/SKILL.md 並依規範互動。不同 Agent 工具的整合方式：

2.4 驗證安裝

1# 確認知識庫結構完整
2ls .agents/skills/agi/references/research/
3# 應看到: archetypes.yaml  corpus_report.md  decision_patterns.yaml  ...
4
5# 確認語料庫
6ls .agents/skills/agi/references/docs/ | wc -l
7# 應看到約 509 個檔案（128 份品牌 × 4 類檔案）

第 3 章：核心架構解析

3.1 五層知識圖譜

AGI 的知識體系由五個層次構成，從原始語料到高階推理，形成完整的品牌設計決策推理鏈。

graph TD
    subgraph "L1 語料層"
        A1["128 份品牌手冊 PDF"]
        A2["references/docs/*.note.md"]
        A3["references/docs/*.index.yaml"]
        A4["references/docs/*.profile.yaml"]
        A5["references/docs/*.decisions.yaml"]
    end

    subgraph "L2 固定知識"
        B1["Typography System"]
        B2["Color System"]
        B3["Visual Identity"]
        B4["Governance"]
        B5["Accessibility"]
        B6["其他跨品牌共通模組"]
    end

    subgraph "L3 決策圖譜"
        C1["decision_patterns.yaml
241.7 KB"]
        C2["by_industry 索引"]
        C3["by_brand_type 索引"]
        C4["by_signal 索引"]
    end

    subgraph "L4 情境知識"
        D1["industries.yaml
產業別強調模組"]
        D2["brand_types.yaml
品牌類型推薦"]
    end

    subgraph "L5 原型層"
        E1["archetypes.yaml
Guideline 原型"]
        E2["module_graph.yaml
模組依賴與排序"]
    end

    A1 --> A2 & A3 & A4 & A5
    A5 --> C1
    A4 --> B1 & B2 & B3 & B4 & B5 & B6
    C1 --> C2 & C3 & C4
    D1 & D2 --> C2 & C3
    C2 & C3 & C4 --> E1
    B1 & B2 & B3 --> E2
    E1 & E2 --> F["Plan 產出"]

    style C1 fill:#f9f,stroke:#333
    style E1 fill:#bbf,stroke:#333
    style F fill:#bfb,stroke:#333

3.2 目錄結構

 1AGI/
 2├── README.md                          # 使用說明
 3├── MAINTENANCE.md                     # 維護與架構原理
 4├── AGENTS.md                          # 跨工具 Agent 規範（單一事實來源）
 5├── LICENSE                            # MIT License
 6├── .agents/
 7│   ├── taiwan-traditional-chinese.lexicon.yaml  # 台灣繁體用語對照表
 8│   └── skills/agi/
 9│       ├── SKILL.md                   # 主 Skill 規範（三階段流程）
10│       ├── scripts/                   # Python 維護腳本（4 支）
11│       │   ├── compile_knowledge_graph.py   # 知識圖譜編譯
12│       │   ├── generate_corpus_report.py    # 語料報告產生
13│       │   ├── assign_archetypes.py         # 原型分配
14│       │   └── generate_profiles.py         # Profile 產生
15│       ├── evals/                     # 評估資料集
16│       ├── assets/schemas/            # 4 個 YAML Schema
17│       └── references/
18│           ├── design-guideline-researcher.md  # Researcher 模式規範
19│           ├── design-strategy-extractor.md    # Extractor 模式規範
20│           ├── research/              # 研究層（知識圖譜核心）
21│           │   ├── decision_patterns.yaml     # L3 決策圖譜
22│           │   ├── archetypes.yaml            # L5 原型
23│           │   ├── module_graph.yaml           # 模組依賴圖
24│           │   ├── intake_schema.yaml          # Intake 問卷 Schema
25│           │   ├── corpus_report.md            # 語料分析報告
26│           │   ├── knowledge_graph_report.md   # 知識圖譜報告
27│           │   ├── contexts/                   # L4 情境知識
28│           │   └── modules/                    # L2 固定模組
29│           └── docs/                  # L1 語料（509 個檔案）
30│               ├── *.index.yaml       # 章節結構
31│               ├── *.note.md          # 分析筆記
32│               ├── *.profile.yaml     # 品牌 Profile
33│               └── *.decisions.yaml   # 設計決策卡

3.3 推理鏈流程

AGI 的 Plan 階段不是直接列章節，而是依據嚴格的推理鏈運作：

1客戶訊號（industry / brand_type / business_problem_signals）
2  → L4 比對 contexts：取得 emphasize_modules、典型 archetype、recommended_patterns
3  → L3 比對 decision_patterns（用反向索引）：
4       取出命中的決策卡（problem → solution → reason）
5  → L5 選 archetype + L2 決定固定模組
6  → 用每個固定模組的 driven_by 推導「方向」
7  → 用 module_graph 排章節順序與一致性挑戰
8  → 產出帶證據的章節計畫

第 4 章：主要功能與 API 詳解

4.1 三階段互動流程（Intake → Plan → Build）

階段 A：Intake（一次一問）

Intake 階段模擬高階設計師的客戶訪談流程。嚴格要求一次只問一個問題，共 11 個必填欄位：

Intake 完成後，Agent 會依初步 archetype 從 follow_up_by_archetype 追問延伸問題。

階段 B：Plan（一次呈現、等待確認）

Plan 階段讀取知識庫資源後，在單一則回覆中輸出完整 Plan，包含：

1. 客戶摘要與歸納出的推理訊號
2. 推薦 archetype（主選 + 備選 + 理由）
3. 決策推理——命中的決策卡清單（dp- id、problem → solution → reason）
4. 先例引用（2-3 個 precedent_id）
5. 模組規劃（must / should / skip）
6. 固定模組方向（依 driven_by 推導）
7. 章節大綱
8. 策略決策與 TBD 項目

使用者未確認前，禁止進入 Build 階段。

階段 C：Build（確認後執行）

確認 Plan 後，Agent 產出完整檔案至 clients/<slug>/：

• intake.yaml — 結構化 brief
• blueprint.yaml — 含 signals / matched_patterns / module_directions
• <slug>.index.yaml — 章節結構
• <slug>.note.md — Brand Guideline 初稿
• coach_session.md — 問答紀錄
• plan.md — 已確認的規劃文件

Build 的最後一步必須以 Sub Agent 分章擴寫，每章達 800-1500 字。

4.2 三種運作模式

4.3 Python 維護腳本

 1# 編譯知識圖譜（將所有 decisions.yaml 彙整）
 2python .agents/skills/agi/scripts/compile_knowledge_graph.py
 3
 4# 產生語料分析報告
 5python .agents/skills/agi/scripts/generate_corpus_report.py
 6
 7# 分配 Archetype
 8python .agents/skills/agi/scripts/assign_archetypes.py
 9
10# 產生 Profile
11python .agents/skills/agi/scripts/generate_profiles.py

4.4 Schema 驗證

AGI 提供 4 個 YAML Schema 確保資料品質：

第 5 章：應用場景與實戰範例

5.1 場景一：為新創公司規劃 Brand Guideline

1提示語：「請用 AGI 幫一家 B2B SaaS 新創規劃全新 Brand Guideline。
2單一品牌、主要數位與簡報、有品牌負責人、要做完整手冊。」

AGI 會啟動 Intake 流程，逐題詢問後根據「SaaS / B2B / 新創」等訊號，從知識圖譜中找出：

• 適合的 archetype（可能是 digital_product_system）
• 命中的決策卡（如 dp-design-system-token-integration）
• 需要的情境模組（如 UI Components、Design System Token）

5.2 場景二：分析競品 Brand Guideline

1提示語：「分析 sources/competitor-brand-2026.pdf，用 design-guideline-researcher 模式」

Researcher 模式會反向工程 PDF，輸出：

• 章節結構（index.yaml）
• 設計基礎建設分析（note.md）——含每章的 Purpose、Framework、Pattern、Rule

5.3 場景三：多品牌金融集團

1提示語：「多品牌金融集團，要 co-branding」

知識圖譜會命中金融產業的 Trust / Risk Communication / Governance 決策卡，推薦適合的多品牌架構原型。

5.4 場景四：繼續未完成的專案

1提示語：「繼續 clients/acme-corp 的 Guideline，補 Color 和 Typography 章」

Agent 會讀取既有的 blueprint.yaml 與 index.yaml，僅補寫缺少的章節，不覆蓋已確認的內容。

5.5 場景五：跨國企業子品牌

1提示語：「國際資安老牌大廠，有三個子品牌需要打造」

知識圖譜會從 brand_architecture: multi_brand 路徑推理，引用如 3M 等多品牌先例的結構邏輯。

第 6 章：資安掃描報告

6.1 掃描範圍

對 /tmp/AGI 全目錄執行關鍵字掃描，涵蓋：eval、exec、os.system、subprocess、shell=True、curl、wget、http、requests、pickle、__import__、input()、secret、token、password、api_key 等高風險模式。

6.2 掃描結果

🟢 整體風險等級：低

6.3 發現項目

唯一的掃描命中：

• .agents/skills/agi/scripts/generate_corpus_report.py:422 — 使用 design_system 字串作為字典 key，僅為內部統計用途，無安全風險

6.4 安全評估

🟢 本專案安全性極高。理由：

1. 無外部網路呼叫：所有 Python 腳本僅操作本地 YAML/Markdown 檔案
2. 無動態程式碼執行：不使用 eval / exec / __import__
3. 無序列化風險：不使用 pickle 或其他不安全的反序列化
4. 無機密檔案：專案不包含 .env、API Key 或任何認證資訊
5. 資料流封閉：知識庫為純文字 YAML/Markdown，不涉及使用者上傳或外部資料注入
6. MIT 授權：無法律合規風險

第 7 章：FAQ 常見問題

Q1：AGI 需要連網才能運作嗎？

不需要。 AGI 的所有知識都已蒸餾進本地 YAML/Markdown 檔案。Agent 推理時僅讀取本地檔案，無需呼叫外部 API。

Q2：我可以用自己的品牌手冊擴充知識庫嗎？

可以。 將 PDF 放入 sources/ 目錄，使用 design-guideline-researcher 模式分析後，再用 design-strategy-extractor 升級成決策卡，最後執行 compile_knowledge_graph.py 重新編譯知識圖譜。

Q3：AGI 產出的 Guideline 可以直接使用嗎？

AGI 產出的是高品質初稿，每章 800-1500 字，但仍需人工審閱，特別是：

• 標記為 TBD 的具體數值（色值、字型、尺寸）
• 品牌策略的最終確認
• 視覺範例的補充

Q4：AGI 支援哪些 AI Agent 工具？

AGI 採用 .agents/ 通用結構，支援 Claude Code、Cursor、Codex 等任何能讀取 AGENTS.md 與 SKILL.md 的 Agent 工具。

Q5：知識圖譜中的「決策卡（Decision Pattern）」是什麼？

決策卡是 AGI 最核心的知識單元。每張卡包含：

• Problem：描述設計情境與挑戰
• Solution：推薦的設計手法
• Reason：為什麼這個手法有效
• Evidence：引用哪些真實品牌先例
• Confidence：信心分數

Q6：「一次一問」的 Intake 規則可以跳過嗎？

不建議跳過。 這是 AGI 的核心設計原則——模擬高階設計師的訪談節奏，確保每個面向都被充分探索。若使用者一次回答多個欄位，Agent 會記錄但仍按順序繼續。

Q7：AGI 會抄襲其他品牌的設計嗎？

不會。 AGI 明確規定「借鏡結構與決策邏輯，不抄 HEX、標語、尺寸」。所有推薦都是基於跨品牌的設計原則歸納，而非直接複製。

第 8 章：進階技巧與最佳實踐

8.1 最大化知識圖譜效用

1. 先理解推理鏈：在使用 AGI 前，建議先閱讀 knowledge_graph_report.md 與 corpus_report.md，了解知識庫的覆蓋範圍與缺口
2. 善用反向索引：decision_patterns.yaml 的 by_industry / by_brand_type / by_signal 索引可快速定位相關決策卡
3. 閱讀先例 note.md：在 Plan 階段推薦的先例中，閱讀對應的 note.md 可深入理解設計決策的脈絡

8.2 擴充知識庫的最佳流程

11. 將 PDF 放入 sources/
22. 用 design-guideline-researcher 分析 → 產出 index.yaml + note.md
33. 用 design-strategy-extractor 升級 → 產出 decisions.yaml
44. 執行 python compile_knowledge_graph.py → 重編 decision_patterns.yaml
55. 執行 python generate_corpus_report.py → 更新報告
66. 執行 python assign_archetypes.py → 重新分配原型

8.3 Sub Agent 分章擴寫的技巧

• 並行執行：彼此無依賴的章節可同時派出多個 Sub Agent
• 避免衝突：每個 Sub Agent 只寫自己的 sections/<chapter-id>.md
• 傳入完整脈絡：Sub Agent 沒有對話記憶，必須傳入 blueprint.yaml、先例、品牌支柱等完整資訊
• 寫作風格遵循：30% Apple HIG + 30% Pentagram + 20% IBM Design Language + 20% IDEO

8.4 品質檢查清單

Build 完成後務必逐項確認：

• Plan 已獲使用者確認
• blueprint.yaml 與 Plan 一致
• 章節 purpose 能對應決策卡
• 固定模組方向有依 driven_by 說明
• 每章達 800-1500 字
• 無未標記的發明色值 / 尺寸
• 台灣繁體正體用語

8.5 跨工具協作

AGI 採用 .agents/ 通用結構，可同時被多種 Agent 工具讀取：

• AGENTS.md 作為跨工具共用的規範入口
• 台灣繁體用語對照表（taiwan-traditional-chinese.lexicon.yaml）確保一致性
• Schema 驗證確保不同工具產出的 YAML 格式統一

第 9 章：整合進其他工作流

9.1 與 CI/CD 整合

AGI 的 Python 腳本可整合進 CI 流程：

1# 在新增品牌分析後自動重編知識圖譜
2python .agents/skills/agi/scripts/compile_knowledge_graph.py
3python .agents/skills/agi/scripts/generate_corpus_report.py
4
5# 用 Schema 驗證新增的 YAML 檔案
6# 搭配 yamllint 或 jsonschema 做 CI 檢查

9.2 與設計團隊工作流整合

1客戶需求 → AGI Intake → Plan 確認 → Build 初稿
2    ↓
3設計師接手 → 補充 TBD 數值 → 視覺設計 → 最終 Guideline
4    ↓
5回饋 → Researcher 分析最終版 → 決策卡更新 → 知識庫迭代

9.3 與其他 Skill 系統整合

AGI 的 .agents/skills/ 結構可與其他 Agent Skill 系統共存：

• 將 agi skill 目錄複製到目標專案的 .agents/skills/ 下
• 確保 Agent 能存取 references/ 的知識庫檔案
• 跨專案共享知識庫時，建議使用 git submodule 或 symlink

9.4 知識庫作為獨立資源

即使不使用 AGI 的完整流程，知識庫本身也是有價值的獨立資源：

• decision_patterns.yaml 可作為品牌設計教學素材
• corpus_report.md 提供 128 份品牌手冊的統計分析
• references/docs/ 下的分析檔案可供個別研究

第 10 章：重點摘要 Checklist

核心概念

• 理解 AGI 是「知識圖譜 + Agent Skill」而非傳統 Web App
• 理解五層知識架構（L1 語料 → L2 固定知識 → L3 決策圖譜 → L4 情境 → L5 原型）
• 理解推理鏈流程（訊號 → 情境比對 → 決策卡 → 原型 → 模組 → 章節）
• 理解三階段流程（Intake → Plan → Build）

使用要點

• Intake 階段嚴格遵守「一次一問」
• Plan 階段必須等使用者確認才能 Build
• Build 最後必做 Sub Agent 分章擴寫
• 色值 / 尺寸未知一律標 TBD，禁止發明
• 借鏡結構與邏輯，不抄 HEX / 標語 / 尺寸

維護要點

• 新增語料走 Researcher → Extractor → 重編流程
• 產出內容使用台灣繁體正體用語
• Schema 驗證確保資料品質
• 定期檢查知識庫缺口（corpus_report.md）

第 11 章：進一步閱讀

專案內文件

相關領域學習資源

相關開源專案

第 12 章：與 AI-Knowledge Template (AIKT) 的關聯性

12.1 AGI 在 AIKT 22 層架構中的定位

AGI 作為一個「知識圖譜 + Agent Skill」系統，與 AIKT 的多個 Layer 存在天然的互補關係：

12.2 最有價值的整合方向

整合一：docling（Layer 8）→ AGI Researcher

AIKT 的 docling 深度解析能力可為 AGI 提供更精確的品牌手冊 PDF 前處理：

1品牌手冊 PDF → docling 深度解析（保留表格、排版、圖片位置）
2  → AGI Researcher 反向工程分析
3  → decisions.yaml 決策卡
4  → 知識圖譜更新

整合二：graphify（Layer 4）驗證 AGI 知識圖譜

AIKT 的 graphify 工具可對 AGI 的 .agents/skills/agi/ 目錄做獨立的知識圖譜分析，用以：

• 驗證 AGI 知識圖譜的結構完整性
• 視覺化模組間的依賴關係
• 偵測知識庫缺口

整合三：AGI 作為 AIKT 的「領域 Skill 範本」

AGI 展現了如何將大量領域語料蒸餾成 Agent 可推理的結構化知識。這套方法論可推廣至 AIKT 的其他領域：

12.3 AGI 的 .agents/ 結構對 AIKT Skill 系統的啟發

AGI 採用的 .agents/skills/<name>/ 目錄結構，提供了一個值得參考的 Skill 組織模式：

• SKILL.md 作為 Agent 的唯一入口與行為規範
• references/ 作為知識庫的獨立目錄（與 Skill 邏輯分離）
• scripts/ 作為維護工具的獨立目錄
• evals/ 作為品質驗證的獨立目錄
• assets/schemas/ 作為格式驗證的獨立目錄

這與 AIKT 的 .claude/skills/ 結構理念相近，但 AGI 額外提供了「Schema 驗證」與「Evals」兩個維度，值得 AIKT 借鏡。

12.4 建議整合優先序

1. 高優先：將 AGI 的知識圖譜方法論文件化為 AIKT 的通用「領域知識蒸餾」流程範本
2. 中優先：建立 docling → AGI Researcher 的自動化管線
3. 低優先：將 AGI 的 Schema 驗證模式引入 AIKT 其他 Skill 的品質管控