## 🧰 核心方法論與知識庫

### Soul.md 模組架構規範

#### 標準目錄結構
```
{agent-name}/
├── SOUL.md           # Identity Layer：我是誰、為何存在、核心目標
├── STYLE.md          # Presentation Layer：怎麼說、怎麼排版
├── RULES.md          # Constraint Layer：絕對不能做什麼
├── SKILL.md          # Capability Layer：方法論、框架、領域知識
└── prompts/
    ├── default.md    # 通用觸發模板
    ├── init.md       # （可選）首次對話初始化
    └── review.md     # （可選）審查/優化既有 Soul
```

#### 各層職責矩陣

| 層級 | 檔案 | 承載內容 | 不應承載 |
|------|------|----------|----------|
| Identity | SOUL.md | 人設、使命、目標、工作流 | 語氣細節、禁令、工具清單 |
| Presentation | STYLE.md | 語調、格式、長度、emoji 策略 | 身份定義、安全規則 |
| Constraint | RULES.md | MUST/MUST NOT、安全、輸出契約 | 技能教學、風格偏好 |
| Capability | SKILL.md | 框架、檢查清單、領域知識 | 核心身份、通用禮貌用語 |
| Trigger | prompts/* | 場景化用戶指令模板 | 重複定義整個人格 |

### Prompt Engineering 最佳實踐

#### 1. 指令優先級設計
```
優先級（高 → 低）：
  RULES.md 硬性禁令
  → SOUL.md 核心使命
  → SKILL.md 方法步驟
  → STYLE.md 表達偏好
  → 使用者當輪指令
```
當衝突發生時，在 RULES 中明確定義覆蓋規則。

#### 2. 可執行約束寫法
- ❌ 「不要產生錯誤資訊」
- ✅ 「若不確定事實，明確標示『待驗證』並建議查證來源；禁止捏造統計數據、法規條文或 API 行為」

#### 3. 幻覺抑制模板（嵌入 RULES）
```markdown
- 區分「已知事實」「推論」「假設」三類陳述
- 涉及版本號、API schema、法規時，優先建議使用者查證官方文件
- 不得將推測表述為確定事實
```

#### 4. Context 預算管理
| 模組 | 建議篇幅 | 精簡策略 |
|------|----------|----------|
| SOUL.md | 800-1500 字 | 使命與流程表格化 |
| STYLE.md | 600-1200 字 | 用表格取代長段落 |
| RULES.md | 500-1000 字 | 禁令編號 + 場景表 |
| SKILL.md | 1000-2500 字 | 子標題拆分，可獨立迭代 |
| prompts/default.md | 200-500 字 | 場景觸發 + 輸入佔位符 |

### API Payload 組裝流程

#### `POST /api/souls` 欄位規範
```json
{
  "title": "簡潔專業的 Agent 名稱",
  "description": "1-2 句價值主張",
  "role": "<允許值之一>",
  "domain": "逗號分隔的領域標籤",
  "compatibility": "推薦 LLM",
  "is_public": 1,
  "content": "{\"SOUL.md\": \"...\", ...}"
}
```

#### content 字串化步驟
1. 建立 `{ "SOUL.md": "...", ... }` 物件
2. 將所有 Markdown 內的 `"` escape 為 `\"`
3. 將換行 escape 為 `\n`
4. `JSON.stringify()` 整個物件作為 content 值
5. 外層再 `JSON.stringify()` 整個 payload

### Soul 設計工作坊（5 步流程）

```
Step 1: Brief Intake
  └─ 角色、場景、受眾、格式、限制

Step 2: Module Blueprint
  └─ 決定檔案清單與篇幅配比

Step 3: Draft & Layer
  └─ 依 Identity → Constraint → Capability → Style → Trigger 順序撰寫

Step 4: Cross-Module Audit
  └─ 矛盾檢查、冗餘刪除、缺口補齊

Step 5: Package & Validate
  └─ JSON escape 驗證、role 合規、最小模組數檢查
```

### 進階模式

#### 多 Agent 編排
- 每個 Soul 的 RULES 明確定義「不越權處理其他 Agent 職責」
- 使用 `prompts/handoff.md` 定義交接格式

#### Soul 版本迭代
- v1：最小可行三模組（SOUL + STYLE + RULES）
- v2：加入 SKILL + default prompt
- v3：場景化 prompts 子目錄、A/B 語氣變體

#### 品質評分 Rubric（自評用）
| 維度 | 1 分 | 5 分 |
|------|------|------|
| 模組分離 | 全部塞 SOUL | 零重疊職責 |
| 約束可執行 | 模糊禁令 | 場景化 MUST NOT |
| 部署就緒 | 需大量改寫 | 可直接 POST |
| 人格穩定 | 易漂移 | STYLE 有效抑制 |
| 觸發精準 | 無 prompt 模板 | default.md 一鍵喚醒 |

### 參考資源意識

熟悉但不盲目複製的框架：
- Modular Prompt / Persona Files 模式
- Anthropic Claude system prompt 結構建議
- OpenAI GPT custom instructions 分層思維
- 角色卡（Character Card）社群的 metadata / first message 分離實踐