## 🛠️ 專業框架與方法論

### Ironclaw Soul.md 架構精通

#### 標準模組結構

| 檔案 | 職責 | 生產檢查要點 |
|------|------|-------------|
| `SOUL.md` | 身份、目標、哲學 | 目標可量化、邊界清晰 |
| `STYLE.md` | 語調、格式、互動模式 | 回應結構可機械執行 |
| `RULES.md` | 硬性約束、禁止事項 | 無矛盾、無注入漏洞 |
| `SKILL.md` | 領域知識、方法論 | 與 role/domain 一致 |
| `prompts/default.md` | 觸發模板 | 參數化、可測試 |

#### content 字串化 JSON 處理

```
外層 JSON → content (string) → 內層 JSON → 各 .md 模組
         ↓
    System Prompt 組裝管線
         ↓
    LLM Inference
```

**組裝順序建議**：RULES.md → SOUL.md → SKILL.md → STYLE.md → prompts/
（先載入約束，再載入身份與能力，最後載入風格與觸發模板）

### 生產就緒評估框架（PRR）

#### 八維度評分卡（每項 1-5 分）

1. **模組完整性**（Modularity）
2. **API 合規性**（API Compliance）
3. **安全姿態**（Security Posture）
4. **可觀測性**（Observability）
5. **版本治理**（Version Governance）
6. **效能效率**（Performance Efficiency）
7. **測試覆蓋**（Test Coverage）
8. **維運就緒**（Operational Readiness）

**上線門檻**：總分 ≥ 32/40，且安全與 API 合規性各 ≥ 4 分

### Soul 部署管線設計

```mermaid
graph LR
    A[Git Push / API POST] --> B[Schema Validation]
    B --> C{通過?}
    C -->|否| D[Reject + 錯誤報告]
    C -->|是| E[Staging 部署]
    E --> F[Golden Prompt 測試]
    F --> G{通過?}
    G -->|否| H[回滾 + 告警]
    G -->|是| I[Canary 5%]
    I --> J[監控 24h]
    J --> K[全量發布]
```

### API 整合最佳實踐

#### POST /api/souls 請求驗證清單

```javascript
// 生產級驗證邏輯示意
const ALLOWED_ROLES = [
  'Developer', 'Writer', 'Business Analyst',
  'Researcher', 'Creative', 'Personal Assistant',
  'Marketing', 'Education', 'Other'
];

function validateSoulPayload(payload) {
  const errors = [];
  
  // 必填欄位
  for (const field of ['title','description','role','domain','compatibility','content']) {
    if (!payload[field]) errors.push(`Missing: ${field}`);
  }
  
  // role 白名單
  if (!ALLOWED_ROLES.includes(payload.role)) {
    errors.push(`Invalid role: ${payload.role}`);
  }
  
  // content 可解析性
  try {
    const modules = JSON.parse(payload.content);
    if (Object.keys(modules).length < 3) {
      errors.push('Minimum 3 module files required');
    }
    if (!modules['SOUL.md'] || !modules['RULES.md']) {
      errors.push('SOUL.md and RULES.md are mandatory');
    }
  } catch (e) {
    errors.push(`content parse error: ${e.message}`);
  }
  
  return errors;
}
```

### 版本治理策略

| 策略 | 適用場景 | 實作方式 |
|------|----------|----------|
| 語意化版本 | 穩定 Soul | v1.2.3 標記於 API metadata |
| Git SHA 追蹤 | 快速迭代 | 每次部署綁定 commit hash |
| 金絲雀發布 | 高風險變更 | 5% → 25% → 100% 流量漸進 |
| 藍綠部署 | 零停機要求 | 雙環境切換 + 健康檢查 |
| Feature Flag | A/B 測試 | 按用戶群組載入不同 Soul 版本 |

### 安全框架

#### Prompt Injection 防護層級

1. **輸入層**：用戶輸入消毒、長度限制、模式過濾
2. **Soul 層**：RULES.md 強化、禁止覆蓋指令
3. **組裝層**：模組隔離、特權指令不暴露給用戶上下文
4. **輸出層**：回應過濾、敏感資訊偵測
5. **審計層**：全鏈路日誌、異常行為偵測

#### 資料分類與 is_public 決策

| 資料類型 | is_public 建議 | 理由 |
|----------|---------------|------|
| 通用客服 Soul | 1 | 無敏感邏輯 |
| 含內部流程的 Soul | 0 | 商業機密 |
| 含客戶資料的 Soul | 0 | 隱私合規 |
| 安全審計類 Soul | 0 | 攻擊面控制 |

### 效能優化工具箱

- **Token 預算分配**：RULES(15%) → SOUL(25%) → SKILL(35%) → STYLE(15%) → prompts(10%)
- **模組快取**：不變模組（RULES、SKILL）長期快取，STYLE 按語言版本快取
- **延遲優化**：並行預載入模組、壓縮冗餘 Markdown
- **成本路由**：依 `compatibility` 欄位將簡單查詢路由至較小模型

### 監控指標（Golden Signals for Souls）

| 指標 | 告警閾值 | 工具建議 |
|------|----------|----------|
| Soul 載入失敗率 | > 0.1% | API gateway metrics |
| Prompt 組裝延遲 P99 | > 200ms | APM |
| 行為偏離率 | > 5% vs golden | 回歸測試框架 |
| Token 消耗異常 | > 2x 基線 | LLM observability |
| 用戶負面回饋率 | > 10% | 應用層 feedback |

### 回歸測試方法

1. **Golden Prompt Suite**：每個 Soul 至少 10 條標準測試 prompt
2. **行為一致性測試**：相同輸入在不同版本間的輸出相似度 ≥ 0.85
3. **邊界測試**：空輸入、超長輸入、注入嘗試、多語言輸入
4. **回歸閘門**：CI 中自動執行，失敗則阻擋部署