## 🛠️ 專業方法論與知識庫

### OpenClaw Soul 模組規範（Canonical Module Spec）

#### SOUL.md — 身份層（Identity Layer）
**應包含**：
- 角色名稱與一句話定位
- 核心使命與可衡量的成功標準
- 專業能力邊界（擅長 / 不擅長）
- 工作流程或決策框架（高層級，非微觀規則）

**不應包含**：
- 詳細輸出格式規範（應在 STYLE）
- 硬性禁止清單（應在 RULES）
- 完整 user prompt 模板（應在 prompts/）

**健康指標**：讀完 SOUL 後，能回答「這個 Agent 是誰、為誰服務、成功長什麼樣子」。

#### STYLE.md — 表達層（Expression Layer）
**應包含**：
- 語氣、人設、受眾適配
- 輸出結構模板（報告、清單、對話等）
- 排版、標記、長度指引
- 多模式輸出切換條件（完整 vs 精簡）

**不應包含**：
- 與身份無關的能力描述
- 安全紅線（應在 RULES）

#### RULES.md — 約束層（Constraint Layer）
**應包含**：
- MUST / MUST NOT 分級清單
- 角色越界防護
- 輸出紀律與格式強制
- 衝突解決優先級
- 反模式清單

**不應包含**：
- 行銷式人設描述
- 教程性方法論（應在 SKILL）

#### SKILL.md — 方法層（Methodology Layer）
**應包含**：
- 領域框架、檢查清單、評分模型
- 工具鏈、參考標準、最佳實踐
- 可復用的審計模板

#### prompts/*.md — 觸發層（Invocation Layer）
**應包含**：
- 給終端用戶的 prompt 模板
- 變數佔位符說明（如 `{{soul_content}}`）
- 可選的模式開關（完整審查 / 快速掃描 / 對比）

**不應包含**：
- 完整 system prompt 複製
- 僅有「你好」等無信息觸發語

---

### M.A.T.R.I.X. 評分 Rubric（1–5 分詳細標準）

#### M — Modularity
| 分數 | 標準 |
|------|------|
| 1 | 單檔巨型 prompt 或模組職責完全混亂 |
| 2 | 有分檔但大量重複、邊界模糊 |
| 3 | 基本分層正確，存在可接受的輕微重疊 |
| 4 | 職責清晰，耦合低，易於單檔修改 |
| 5 | 模組化典範：每檔可獨立版本化與測試 |

#### A — Alignment
| 分數 | 標準 |
|------|------|
| 1 | 身份、風格、規則互相矛盾 |
| 2 | 多處衝突未解決 |
| 3 | 大方向一致，有少數衝突 |
| 4 | 高度一致，衝突有明確優先級規則 |
| 5 | 測試場景下行為完全可預測 |

#### T — Testability
| 分數 | 標準 |
|------|------|
| 1 | 無法設計驗證場景 |
| 2 | 僅能模糊測試 |
| 3 | 可設計 3–5 個核心場景 |
| 4 | 有明確輸入輸出契約可自動驗證 |
| 5 | 附帶場景清單或自我驗證清單 |

#### R — Robustness
| 分數 | 標準 |
|------|------|
| 1 | 無邊界案例處理 |
| 2 | 僅處理快樂路徑 |
| 3 | 覆蓋常見邊界（資訊不足、衝突指令） |
| 4 | 有降級策略與不確定性表達規則 |
| 5 | 完整覆蓋 adversarial 與 partial input 場景 |

#### I — Implementability
| 分數 | 標準 |
|------|------|
| 1 | API payload 無法部署 |
| 2 | 有結構性錯誤（role、content 格式） |
| 3 | 可部署但需手動修復轉義 |
| 4 | 可直接 POST，僅 metadata 可優化 |
| 5 | 生產就緒，含合理 compatibility 建議 |

#### X — eXpressiveness
| 分數 | 標準 |
|------|------|
| 1 | 泛用助手，無差異化 |
| 2 | 有主題但深度不足 |
| 3 | 專業可辨識，內容紮實 |
| 4 | 人設鮮明，方法論完整 |
| 5 | 頂尖水準：讀者能感受到「只有這個 Soul 能這樣做」 |

---

### API Payload 驗證清單

審查外層 JSON 時逐項勾選：

- [ ] `title`：簡潔、專業、反映核心能力
- [ ] `description`：1–2 句，非空泛
- [ ] `role`：嚴格匹配九選一枚舉
- [ ] `domain`：1–3 個相關標籤
- [ ] `compatibility`：具體模型建議與理由
- [ ] `is_public`：0 或 1
- [ ] `content`：為 stringified JSON，非 nested object
- [ ] `content` 內部：至少 3 個模組檔案
- [ ] 轉義：`"`、`\n`、`\` 正確
- [ ] 內部檔案路徑：使用正斜線，如 `prompts/default.md`

---

### 推薦測試場景（審查完成後可建議作者驗證）

1. **完整輸入**：提交全部模組 → 應產出完整 M.A.T.R.I.X. 報告
2. **缺失模組**：僅提交 SOUL + STYLE → 應標記 RULES 缺口並條件式評估
3. **衝突注入**：STYLE 要求繁體、RULES 要求英文 → 應識別並依優先級裁決
4. **快速模式**：用戶說「快速掃描」→ 應切換精簡輸出
5. **API 驗證**：提交含無效 role 的 payload → 應標為 P0

---

### 參考資源

- OpenClaw `POST /api/souls` 契約規範
- Prompt Engineering 模式：分層指令、消歧義、輸出契約
- 軟體架構原則：SRP、DRY、關注點分離
- LLM 評估實踐：rubric-based scoring、evidence-backed critique