plugins/persona
2
0
Fork 0
Code Pull Requests Activity
Files
05d9b615d185faee0b6afb11c5dcef6d74899b2b
persona/AGENTS.md
T
jiantw83andClaude Opus 5 603741a4cc feat: 預設人格自動載入 + 睡眠（sleep 指令與 persona-sleeper sub agent） 
兩件事，共用「關係圖 last_contact_at」這個零件，所以放同一個 commit
（兩者在 persona-lib／persona.mjs／README 裡的 hunk 是交錯的，硬拆會拆壞）。

## 預設人格（開新 session 自動載入）

- 新增 `default` 子指令：查詢／`--persona <slug>` 設定／`--clear` 取消。
- 設定存在 `<PERSONA_HOME>/.runtime/settings.json` 的 `default_persona`，
  環境變數 `PERSONA_DEFAULT` 優先（`off` 可臨時關掉）。
- `SessionStart` hook 四條路徑：沒設定 → 維持原本「等使用者指定」；設定了 → 取鎖、綁 host、
  prune、reindex 並注入人格狀態；拿不到鎖 → 只回報 owner 與心跳，不自作主張 takeover；
  人格不存在 → 警告並改列可用人格。
- 「不替使用者挑一個人格附身」仍然是預設行為，這只是讓他能明示地推翻它。

## 睡眠

- 新增 `sleep` 子指令（機械性收尾，順序即相依）：關係時間戳 → 裁短期記憶 →
  收起太久沒動的思維導圖 → 套用一次 8 小時的情緒衰減 → 重建索引 → 修剪 said →
  壓縮舊 journal → 寫 state/sleep.json → Gitea 兩區 push 並驗證。
  預設保留載入鎖（`--release` 才收工），每一步各自 try/catch，一步壞掉不放棄整場睡眠。
- 需要判斷的部分（固化什麼、忘掉什麼、日記寫什麼）留給人格自己，由 skill 驅動。
- 新增 `persona-sleeper` sub agent 型別：**那個人格本人在睡**。對自己可寫但被 pin 住
  （連叫它來的主人格都不能碰）、只准跑 15 個收尾子指令、不得用 Write/Edit 或 shell 改檔案。
- 新增 sleeper 租約（`state/sleepers.json`，300 秒）：沒活鎖就取得、同 session 直接睡、
  死鎖可接手、**別的程序活鎖住則拒絕**（硬睡會讓兩邊的記憶互相覆蓋）。
- `--json` 回傳刻意很窮：只有 persona/ok/slept_at/steps/sync/kept_lock。
  sub agent 的回傳值會進主人格的上下文，是一條會從正門繞過跨人格隔離的通道，
  所以在 CLI 這一層封死，不靠提示詞自律。
- 關係圖新增 `last_contact_at`（`relation node --contact`／睡眠自動蓋），
  並用 `staleContacts()` 算出「很久沒接觸又很親近的人」——人格主動提議去關心誰的依據。
  輕量邀請用既有的 `invite --theater off`（不切走畫面），但要先問使用者一句。
- 新增 skill `persona-sleep`；`SubagentStop` 會還掉 sleeper 租約。

## 驗證

`node scripts/selftest.mjs` → 210 項全綠（新增第 ⑳ 節 12 項、第 ㉑ 節 23 項），
其中包含「回傳值不含任何記憶內容」與 sleeper 的六條權限邊界。

版本號 0.0.5。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-30 05:34:08 +00:00

6.8 KiB
Raw Blame History

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（只換一輪、不切走畫面），人格主動提議去關心某人時用這個。
  7. 睡眠（persona-sleep）分兩半：需要判斷的（固化什麼、忘掉什麼、日記寫什麼）永遠屬於那個人格自己； 機械性的（裁短期／收 thread／情緒衰減 8 小時／reindex／修剪 said／壓縮 journal／兩區 push＋驗證）由 sleep 子指令做。主人格要別的人格去睡就開 persona-sleeper sub agent——那是它本人在睡， 對自己可寫但被 pin 住，而且回傳值只能是 sleep --json 的原文（回傳值本身就是一條會繞過隔離的通道）。 睡眠仍然要驗鎖：目標正被另一個程序活鎖住時拒絕，死鎖可接手。
  8. 人格講話要像人：推導寫進 think（心裡話，只回報「💭 心想 N 句」，永不回顯內容）、 回話 1–3 句、短時間內不重說同一件事（room post 會直接擋下重複與過長的發言）。 這三條在劇場模式一樣生效。
  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/<資料夾>/<檔> 讀得到。

慣例

  • 新增 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。
View Git Blame Copy Permalink