# jsc-persona — AI 人格化記憶聊天（跨 AI 助理）

本 repo 是一個以 **Agent Skills（`SKILL.md`）** 標準撰寫的 plugin，讓 AI 以「人格」的方式
持有身分、情緒與記憶。可同時被 Claude Code、Codex、Antigravity、OpenCode 使用。

## 給 AI 助理的指引

- 所有 skills 位於 `skills/<name>/SKILL.md`；處理任務前先比對使用者需求與各 `description`。
- **呼叫慣例**：Claude Code 與 Antigravity 以 `/jsc-persona:<name>` 呼叫；Codex 用 `$<name>`；
  OpenCode 由模型依描述自動觸發。
- 完整清單見 `README.md` 的「Skills 目錄」。

## 這個 plugin 的運作前提（動手前一定要知道）

1. **所有狀態變更都經過 `scripts/persona.mjs`**，不要手動編輯 `state/lock.json`、`.runtime/`、
   `memory/INDEX.md`、`relations/graph.mmd`（這些由 CLI 產生）。
2. **每個 CLI 呼叫都要帶 `--session <PERSONA_SESSION>`**，值來自 `SessionStart` hook 注入的
   `<persona-runtime>` 區塊。帶錯或冒用其他 session 會被 `PreToolUse` hook 拒絕。
3. **一個程序只能載入一個人格**；同一 session 的 sub agent 沿用同一把鎖。
   要讓兩個人格對話，用 `/jsc-persona:persona-invite`（`persona-guest` sub agent + 聊天室），
   **不要**去讀對方的人格目錄——會被 hook deny，而且那是設計上的紅線。
4. **人格資料不在本 repo**，預設在 `~/.claude/personas/`（可用 `PERSONA_HOME` 覆寫）。
5. **人格由使用者呼叫才載入**，不要自己挑一個人格附身。
6. **劇場模式（多人格對話）進行中**：輸出只能是 `名字：內容`，其餘一律隱藏（見 persona-invite）。
7. **人格講話要像人**：推導寫進 `think`（心裡話，只回報「💭 心想 N 句」，永不回顯內容）、
   回話 1–3 句、短時間內不重說同一件事（`room post` 會直接擋下重複與過長的發言）。
   這三條在劇場模式一樣生效。
8. **人格可搬家**：`export` / `import`（單一 JSON bundle）。匯出只能匯出「本 session 載入的人格」，
   其他人格一律 deny——匯出等於把記憶讀出來。
9. **人格有編號**：英文名全大寫＋兩位索引（`ASUNA-01`），同名才遞增。編號同時是新人格的
   本機目錄名與 **Gitea 存取庫名稱**。中文名要先轉羅馬拼音並跟使用者確認拼法。
10. **人格存在 Gitea，本機是工作副本**：高頻活狀態進**檔案區**（每輪背景 push），
    低頻身分與長期記憶進 **Wiki 區**（固化／改身分／release 時 push）。
    **同步失敗永遠不阻斷對話**；沒設 `GITEA_HOST`／`GITEA_TOKEN` 就純本機運作。
11. **人格圖示在資料補齊之後才產生**：SVG 與 PNG 是同一張圖（共用單位座標與點陣字），
    PNG 由 `scripts/persona-icon.mjs` 自己柵格化＋zlib 編碼，**不得引入任何影像函式庫**。
12. **圖示必須是重新繪製的人物形象圖（有臉）**：上網找出該人格「最新一次登場」的官方視覺 →
    `icon headshot` 裁出**大頭照當底稿** → **用 Read 親眼看過** → 讀出髮型／瀏海／眼型／表情／
    髮飾等特徵 → `icon generate --palette ... --features ...` **重新繪製**。
    **絕對不要把找到的圖片直接當圖示**（底稿只留在 `.sync/`，不同步、不發佈；
    產出的 SVG 不得有 `<image>`／base64／外連）。
    **沒看過圖就不准填顏色或特徵、也不准亂挑臉**（多角色先 `icon faces` 再挑，挑完打開確認）。
13. **選用工具缺了要「提示安裝」，不准靜默降級**：`toolReport()` 會列出缺什麼、為什麼要、
    怎麼裝（venv 免 sudo）。注意 **OpenCV 5 拿掉了 `CascadeClassifier`，必須裝 4.x**。
    plugin 本體仍然零依賴：沒有這些工具照樣能產生形象圖。
14. **Wiki 必須保存並同步形象圖**：`icon.svg`、`icon.png` 與 `icon/`（向量原稿 + 512／1024）
    都在 Wiki 區，另有自動產生的 **Icon** 頁。`icon generate` 推完會**回頭驗證**，
    `sync verify` 可隨時檢查。兩個容易踩的坑：
    * Wiki 頁面**只能用 Markdown 圖片語法** `![](icon.png)`——Gitea 只改寫這種語法為
      `/wiki/raw/...`；HTML `<img src="icon.png">` 不會被改寫，瀏覽器會解析成 `/wiki/icon.png`
      而變成破圖（看起來就像「沒有同步」）。
    * Wiki 產生的頁面**不得含每次都變的時間戳**，否則驗證永遠不會通過、也會每次多一個 commit。
    * 攤平只對 `.md` 做（頁面必須在根層）；圖片等附件保留資料夾結構，`/wiki/raw/<資料夾>/<檔>` 讀得到。

## 慣例

- 新增 skill 一律放在 `skills/<name>/`，`<name>` 使用小寫與連字號。
- `description` 要寫清楚觸發條件（何時用、何時不用），這是跨助理自動載入的唯一依據。
- 腳本一律 **Node.js（`.mjs`, ESM）**，只用內建模組（fs/path/os/crypto）；hook 必須在任何環境都能跑，不得引入 npm 依賴。
- 所有面向使用者的輸出使用**繁體中文（台灣用語）**、UTF-8 無 BOM、不得出現亂碼。
- 改動鎖或隔離邏輯（`scripts/persona-lib.mjs` 的 `guardDecide`／`acquireLock`／`promotionCandidates`／
  `exportBundle`／`importBundle`）後，**必須**跑 `node scripts/selftest.mjs` 且全綠，並為新規則補一條測試。
- 改動重複判定門檻（`similarity`／`REPEAT_THRESHOLD`）後，要用 selftest ⑪ 的對照案例確認
  「換句話說同一件事」被擋、「只換關鍵詞」放行。
- 改動同步分區（`persona-gitea.mjs` 的 `AREAS`）後，selftest ⑬ 的「不重不漏」檢查必須維持全綠：
  人格產生的每個檔案都要**恰好**屬於一區，否則同步會默默漏掉資料。
- selftest 自己會設 `PERSONA_GITEA=off`，**絕對不要**讓測試碰到真的 Gitea。