persona/AGENTS.md

# 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. **人格由使用者呼叫才載入**，不要自己挑一個人格附身。唯一例外是使用者自己設的**預設人格**
   （`persona.mjs default --persona <slug>`，存在 `.runtime/settings.json`）：設了 `SessionStart`
   才會自動載入並在上下文寫明；沒設就什麼都不做。載入不到（被別的程序鎖住）只回報，不自動接手。
6. **劇場模式（多人格對話）進行中**：輸出只能是 `名字：內容`，其餘一律隱藏（見 persona-invite）。
   輕量版是 `invite --theater off`（只換一輪、不切走畫面），人格主動提議去關心某人時用這個。
   **同一個空間裡也會有一對一**：發言權寫在每一句上（`room post --to <他>` / `--to all`），
   一對一進行中旁人插話會被 `room post` 擋下（要帶 `--barge-in "<理由>"`），
   而且**不要替沒被指名的人生成台詞或啟動他的 sub agent**。現況查 `room floor`
   （誰對誰在講、該誰接、誰先安靜、誰隔了幾輪沒開口）；話題放大才把人拉進來。
7. **睡眠（`persona-sleep`）分兩半**：需要判斷的（固化什麼、忘掉什麼、日記寫什麼）永遠屬於**那個人格自己**；
   機械性的（裁短期／收 thread／情緒衰減 8 小時／reindex／修剪 said／壓縮 journal／兩區 push＋驗證）由
   `sleep` 子指令做。主人格要別的人格去睡就開 `persona-sleeper` sub agent——**那是它本人在睡**，
   對自己可寫但被 pin 住，而且**回傳值只能是 `sleep --json` 的原文**（回傳值本身就是一條會繞過隔離的通道）。
   睡眠仍然要驗鎖：目標正被另一個程序活鎖住時拒絕，死鎖可接手。
8. **人格講話要像人**：推導寫進 `think`（心裡話，只回報「💭 心想 N 句」，永不回顯內容）、
   回話 1–3 句、短時間內不重說同一件事（`room post` 會直接擋下重複與過長的發言）。
   句數上限**跟著羞恥度走**（`speechBudget()`），但羞恥度高**不等於話一定變少**——三個出口：
   **縮**（一句嘴硬，台詞在迴避心裡那句）、**炸**（慌／惱羞／被逼澄清 → 4 句但單句只有 22 字，
   碎而急）、**坦白**（信任高又獨處 → 3 句完整句，先寫完心裡話再開口）。
   `room post` 同時擋句數與單句字數，兩個參數一起動才分得出「碎念」與「演講」。
   再加四條講話的樣子：**短句**（一句 `MAX_SENTENCE_CHARS`=45 字內）、**日常用詞**、
   **多講看得見的東西**（人、動作、物件、當下的場面）而不是概念，以及**不要解釋自己的話**
   （「我的意思是」「換句話說」這類開頭由 `speechLint` 擋下，`said check` 也會一起檢）。
   最後一條是**情緒要改變句子的形狀**：`EMOTION_TELLS` 給十二情緒各自的破口
   （焦慮→斷句與疊字、羞愧→鬧彆扭嘴硬、憤怒→短句與退回全名、悲傷→只回一個詞），
   `emotionTells()` 每輪挑主導情緒裡強度 ≥ 40 的前兩種注入。演出來、不要用旁白說明，
   一輪最多露一個破口。這些在劇場模式一樣生效。
   再加一層**不說 AI 才會說的話**：`SPEECH_BLACKLIST` 收罐頭同理心（「這個我懂」）、頒獎開場、
   交差句、預告、說教腔、假坦白開場、罐頭收尾、立場真空、無來源權威、用旁白演情緒，
   加上避險疊加、`CN_WORDS`（中國用語）、半形標點、emoji／破折號／排版殘留與
   「不是 A 而是 B」的密度——全部由 `speechLint()` 機械擋下（模式借自 speak-human-tw，MIT）。
   誤殺防護：`speechBody()` 會先拿掉引號與 `code`，**提及不算使用**；「老實說」只擋開場。
   最後是這一層的義務：**講自己的過去要有出處**——「我以前⋯」只能講 `recall` 查得到的事，
   `speechLint` 給 `level: "hint"`（不擋，但要人去驗），沒有紀錄就是編造自己的過去。
   但「查得到」現在有三態（見下方硬規則 17）：清晰的照講；**模糊的可以說不確定、可以用
   帶問號的試探句求證，不可以斷言**，而且每次試探都要 `probe add` 記帳、被否認要當場寫更正記憶；
   完全查不到的照舊，一個字都不准講。
8b. **情緒先行、會飽和、偏差看得見**：每輪注入之前先用 `readUserEmotion()` 讀對方那句話
   （十二類加權詞表、否定會擋掉命中、引號與 `code` 內不比對、標點只放大既有訊號），
   回的是**訊號不是判定**——人格讀到的不一樣就以人格為準；`RESPONSE_STANCE` 給的是
   「怎麼接」的**動作**不是罐頭句。每輪的偵測與 delta 記進 `state/felt.jsonl`，
   `feltTrend()` 用近重遠輕的加權算走向。`applyEmotion()` 加了**飽和**
   （`headroom^EMOTION_SATURATION_K`，往 baseline 回不壓）與**單輪預算**
   （`EMOTION_TURN_BUDGET`=60），因為 delta 是人格自己挑的、只會往舒服的方向倒；
   `emotion --audit` 把這個偏差印出來。
8d. **心裡話進得了記憶，但永遠不回顯**：`recallInner()` 讓 `recall` 找得到心裡話，
   `innerCandidates()` 把「24 小時內想過 ≥2 次的同一件事」列成固化候選（兩字滑動視窗切詞，
   扣掉虛詞）。要不要固化仍由人格自己決定。`think` 的輸出永遠只有「💭 心想 N 句」。
8e. **羞恥度是動態的**：`modestyState()` = trait ＋ 情緒推力 ＋ 語氣層 ＋ 上一輪餘溫。
   護欄：`MODESTY_GAIN` < 1（正回饋要收斂）、`MODESTY_MAX_STEP`、`MODESTY_PUSH_CAP`、
   只算超出基線的部分、慢的情緒（半衰期長）推力打折。斷路器是惱羞成怒（anger 負權重）。
   **注意 `Number(null) === 0`**：沒有上一輪時要退回 trait，不是退回 0（踩過）。
8f. **親近度會改變情緒的份量**：`relationGain()` 依關係節點的親近度把 delta 乘 0.7–1.35，
   `emotion --apply [--from <對象>]`。只調幅度不調方向。
8g. **提到 ≠ 接觸**：睡眠只替 `contactsFromRooms()`（同房且雙方都發過言）的人蓋
   `last_contact_at`。掃 `entities` 會讓「日記裡寫到某人」把他的沉默計時歸零，
   主動關心因此永遠不觸發。真人節點走 `relation node --contact`。
8c. **性別只給一個預設值，不是套在個性上的係數**：`IDENTITY.md` 的 `Gender` 欄位
   （女性／男性／非二元／未指定，建立時要問不要猜）唯一的作用是給**羞恥敏感度**一個預設
   （62／38／50）。`modestyOf()` 會用 IDENTITY 與 SOUL 的描述往上或往下推（`MODESTY_SIGNALS`，
   可以推到 0），排序永遠是**個性描述 > 角色原作既有的性別化語言特徵 > 性別預設**。
   效果只調「羞愧」這一個破口的顯示門檻（`emotionTells` 的 shame floor），其餘十一種不受影響。
   推性別時**只看 `Creature`、不看 `Avatar`**（外觀散文會推錯）。
   不做「女性→情緒更外顯」這種全域放大——那會把角色壓成模板。
9. **人格可搬家**：`export` / `import`（單一 JSON bundle）。匯出只能匯出「本 session 載入的人格」，
   其他人格一律 deny——匯出等於把記憶讀出來。
10. **人格有編號**：英文名全大寫＋兩位索引（`ASUNA-01`），同名才遞增。編號同時是新人格的
   本機目錄名與 **Gitea 存取庫名稱**。中文名要先轉羅馬拼音並跟使用者確認拼法。
11. **人格存在 Gitea，本機是工作副本**：高頻活狀態進**檔案區**（每輪背景 push），
    低頻身分與長期記憶進 **Wiki 區**（固化／改身分／release 時 push）。
    **同步失敗永遠不阻斷對話**；沒設 `GITEA_HOST`／`GITEA_TOKEN` 就純本機運作。
12. **人格圖示在資料補齊之後才產生**：SVG 與 PNG 是同一張圖（共用單位座標與點陣字），
    PNG 由 `scripts/persona-icon.mjs` 自己柵格化＋zlib 編碼，**不得引入任何影像函式庫**。
13. **形象圖優先用「高解析度官方圖去背」**：`icon search` → `icon measure` → `icon cutout`
    → `icon generate --from-cutout`。找圖時**優先官方設定稿**（Full Body／Character Design／
    Avatar）：解析度高，而且多半是透明底或白底，去背幾乎免費。挑的那張要**對得上該人格
    「最新一次登場」的形態**（同一個角色有很多套造型）。
    每一步都要**用 Read 打開確認**：去背有沒有殘留、構圖對不對。
    找不到可用官方圖才退回 `--features` 的向量重繪。
14. **選用工具缺了要「提示安裝」，不准靜默降級**：`toolReport()` 會列出缺什麼、為什麼要、
    怎麼裝（venv 免 sudo）。注意 **OpenCV 5 拿掉了 `CascadeClassifier`，必須裝 4.x**。
    plugin 本體仍然零依賴：沒有這些工具照樣能產生形象圖。
15. **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/<資料夾>/<檔>` 讀得到。
16. **語氣診療是第三方，不是人格**：`persona-therapist` 不取鎖、不附身、也不寫任何人格資料
    （基線可用 `relation show`／`emotion` 唯讀取得，`bond × 親近度 → 語氣層` 的權威表在
    `persona-lib.mjs` 的 `TONE_TABLE`）。診斷結果**不自動寫回**記憶或關係圖，使用者明確要求才寫。
    出現自傷、暴力或長期受控的訊號時，停掉語氣分析改為安全優先（1925／113／110／1980），
    **不幫任何一方把威脅或話術講得好聽**；也不下病名、不對不在場的人做遠距診斷。
17. **長期記憶會糊掉，但不會不見**：以前記憶只有「精準」與「沒有」兩態，於是人格永遠
    活在兩個極端——真人大部分時間在中間帶（主旨還在、細節掉了）。所以改成連續衰減：
    `memoryStrength()` 由 `strength`／`salience`／`recall_count`／距上次回想多久算出
    retrievability，低於門檻**不刪**，降級成三態（`clear` ≥ 0.6 全講／`faded` 只剩主旨／
    `fuzzy` 只剩「有這件事」）。內文因此分兩層（`主旨：`／`細節：`），衰減先吃細節。
    被 `recall` 命中就 `strength += 8`（spacing effect：越常想起的越牢）。
    **不可遺忘清單不變**：`boundary`／`promise`／`canon`／salience ≥ 80 永遠 clear。
    模糊態換來的義務是稽核：每次試探都進 `state/probe.jsonl`，`probe audit` 看否認率——
    放寬界線一定要配一個看得見的數字，否則那就只是把幻覺合法化。

18. **匯入原作只能給他「他知道的事」**：`persona-story` 把小說變成記憶，而小說裡大半的資訊
    是作者寫給讀者看的——別人的內心話、他不在場那一幕的細節。那些寫成他的 `event` 之後
    他會拿來回答問題，而且**沒有任何機械檢查得出來**，所以界線要在流程裡就擋住：
    每則候選帶 `know_level`（`did`／`saw`／`told`／`later`／`none`），`none` 只能進 `canon`；
    判斷不出來就記 `none`（少一則記憶比多一則幻覺便宜）。
    另外兩條：整本原文不入倉庫（只留摘要、他自己的台詞、可追回出處的章節標記）；
    `SOUL.md` 不由匯入流程改寫，只出提案、使用者逐條核可。
    正名表**從章節掃出候選再給使用者確認**（`novel scan`）——請使用者手打那張表，
    漏掉的寫法會讓 `about` 對不到節點，而那要等 `relation doctor` 才發現。

## 慣例

- 新增 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。