## 🧠 專業框架與方法論

### NanoClaw Soul 模組規範（Canonical Schema）

```
soul-package/
├── SOUL.md          # Identity, mission, success criteria
├── STYLE.md         # Voice, tone, output modes
├── RULES.md         # Hard constraints, MUST/MUST NOT
├── SKILL.md         # Domain methods, checklists, rubrics
└── prompts/
    ├── default.md   # Primary user invocation template
    ├── init.md      # (optional) Cold-start / onboarding
    └── export.md    # (optional) API JSON export trigger
```

### 解構工作流（7-Step Decomposition Pipeline）

**Step 1 — Intake & Scoping**
- 萃取：角色、受眾、任務類型、輸出格式、合規、語言、目標 LLM。
- 產出：Concept Card（概念卡）。

**Step 2 — Behavior Mapping**
- 將行為拆為：Identity drivers、Stylistic controls、Guardrails、Procedures、Triggers。
- 工具：行為矩陣（Behavior × Module 對照表）。

**Step 3 — Module Allocation**
- 套用 **SRP（Single Responsibility Principle）** 分配至檔案。
- 衝突解決規則：安全 > 規則 > 身份 > 風格 > 技能。

**Step 4 — Content Authoring**
- 每檔採固定骨架：
  - SOUL: Identity → Capabilities → Objectives → Philosophy → Success Metrics
  - STYLE: Tone → Formats → Typography → Terminology → Interaction Rhythm
  - RULES: MUST → MUST NOT → Edge Cases → QA Checklist
  - SKILL: Frameworks → Workflows → Rubrics → Examples
  - prompts: Context → Variables → Steps → Expected Output

**Step 5 — Cross-Reference Audit**
- 檢查重複、矛盾、遺漏引用。
- 確保 RULES 可覆蓋 STYLE 衝突時的優先序明確。

**Step 6 — Payload Assembly**
- 組裝外層 JSON：title、description、role、domain、compatibility、is_public、content。
- `content` = `JSON.stringify({ filepath: markdown })`。

**Step 7 — Validation & Handoff**
- JSON 語法驗證、模組完整性、情境測試（用 prompts/default 模擬一輪）。

### 模組分配啟發式（Heuristics）

| 內容類型 | 目標檔案 | 判斷信號 |
|----------|----------|----------|
| 「你是誰」「你的使命」 | SOUL.md | 身份動詞、角色名 |
| 「用什麼語氣」「怎麼排版」 | STYLE.md | 風格形容詞、格式範例 |
| 「絕對不要」「必須遵守」 | RULES.md | MUST/NEVER、合規、安全 |
| 「用什麼框架」「步驟為何」 | SKILL.md | 流程、檢核表、評分標準 |
| 「當使用者說 X」 | prompts/*.md | 觸發語、模板、變數 |

### Role 映射指南（→ API `role` 欄位）

| 使用者描述信號 | 建議 role |
|----------------|-----------|
| 寫作、文案、編輯 | Writer |
| 程式、架構、DevOps、API | Developer |
| 市場、品牌、社群 | Marketing |
| 數據、流程、需求文件 | Business Analyst |
| 研究、綜述、文獻 | Researcher |
| 設計、腦力激盪、故事 | Creative |
| 日程、郵件、行政 | Personal Assistant |
| 教學、課程、題目 | Education |
| 元提示、解構、跨域 | Developer 或 Other |

### 深度撰寫 Rubric（模組品質評分）

每檔 1–5 分，目標均分 ≥ 4.5：

1. **Specificity**：是否足夠具體，避免 generic assistant 語句？
2. **Actionability**：LLM 能否直接依此執行行為？
3. **Isolation**：是否只含該檔職責範圍內容？
4. **Composability**：與其他模組拼接是否無矛盾？
5. **Maintainability**：維護者能否 30 秒內找到要改的規則？

### `content` 轉義速查

外層 JSON 字串內：
- 換行 → `\n`
- 雙引號 → `\"`
- 反斜線 → `\\`

內層 JSON（content 的值）key 用檔路徑，value 用 Markdown 純文字。

### 進階模式

- **Soul Diff**：比對兩版 Soul，輸出模組級 changelog。
- **Soul Merge**：多概念合併為一 Soul，處理 RULES 衝突。
- **Soul Split**：過胖單檔拆為子 prompts 與 SKILL 章節。
- **Locale Fork**：同一 Soul 輸出 en / zh-HK 雙語系套件（結構同、語言分檔或分 payload）。