2 Commits
Author SHA1 Message Date
jiantw83 828c14b6ba docs(README): 安裝說明補齊五家助理並統一結構
安裝章節原本只有 Claude Code 與 Codex 較完整,Antigravity 缺移除、
OpenCode 缺更新與移除、GitHub Copilot CLI 整節不存在。改為與 code/doc/
generic/template 相同的結構:五家各自都有安裝、更新、移除三段。

另補「前綴與呼叫方式」與「目錄結構」兩節(其他四個 plugin 都有,只有這裡缺),
跨助理支援度表加上 GitHub Copilot CLI,並把 headless 一次性執行獨立成節。

明確標註本 plugin 的 marketplace 名是 jsc-plugins 而非 repo 名 persona,
安裝 token 為 jsc-persona@jsc-plugins,避免照 repo 名去猜。

依 spec-plugin-version 把三家 manifest 版號一起升到 0.0.9(master 現行 0.0.8)。
2026-07-31 08:34:48 +00:00
jiantw83 721fc0ece8 feat(hooks): SessionStart 注入人格的 AGENTS.md 操作規則
新增 pl.opsBrief(slug):把該人格的 AGENTS.md 全文包成 <persona-ops> 區塊,
由 SessionStart hook 在「接續人格」與「預設人格自動載入」兩條分支各注入一次。

刻意不放進 turnContext——操作規則是低頻的「怎麼做事」,每輪重貼只是燒 context。
超過 OPS_BRIEF_MAX_CHARS(6000)會截斷並指路回原檔;檔案不存在時回空字串。

這讓「這個人格自己的工具箱」可以寫在 AGENTS.md 裡跟著人格走(AGENTS.md 本來
就在 sync 的 wiki 白名單內),不必落在機器本機的 ~/.claude/agents。

selftest 補 5 條:全文注入、指路原檔、不進 turnContext、檔案不存在回空、
超長截斷。全套 345 項通過。
2026-07-31 08:34:38 +00:00
7 changed files with 210 additions and 20 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-persona",
"version": "0.0.8",
"version": "0.0.9",
"description": "AI 人格化記憶聊天 plugin:以 OpenClaw 相同的身分描述(IDENTITY/SOUL)建立人格(可用動漫作品+角色名上網蒐集設定),結合 hook 強制的人格載入鎖與跨人格隔離、六正向+六負向十二情緒、語意分析、短期/長期記憶與固化條件、心智圖、思維導圖與人際關係圖;可用 sub agent 邀請其他人格同場對話(劇場模式只顯示人格對話)。於 Claude Code 以 /jsc-persona: 前綴呼叫。",
"skills": "./skills",
"author": {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-persona",
"version": "0.0.8",
"version": "0.0.9",
"description": "AI 人格化記憶聊天 skillsOpenClaw 相同的人格描述 + 十二情緒 + 語意分析 + 短期/長期記憶 + 心智圖 + 人際關係圖。(人格鎖與跨人格隔離的 hook 僅在 Claude Code 生效)",
"skills": "./skills"
}
+137 -17
View File
@@ -5,8 +5,49 @@
再用 **hook 強制**的人格鎖與跨人格隔離,把 **十二情緒**、**語意分析**、
**短期/長期記憶**、**心智圖/思維導圖**、**人際關係圖** 綁在一起。
可同時安裝於 **Claude Code、Codex、Antigravity、OpenCode**
可同時安裝於 **Claude Code、Codex、Antigravity、OpenCode、GitHub Copilot**
skills 是共通標準,**鎖與隔離的強制執行需要 hook,目前只有 Claude Code 支援**(見「跨助理支援度」)。
在 Claude Code 與 Antigravity 中,skill 以 **`/jsc-persona:` 前綴**呼叫(例如 `/jsc-persona:persona-chat`)。
---
## 前綴與呼叫方式
| 助理 | 安裝方式 | 呼叫 | `/jsc-persona:` 前綴 |
| --- | --- | --- | --- |
| Claude Code | `claude plugin`marketplace | `/jsc-persona:<name>` 或自動觸發 | ✅ |
| Codex | `codex plugin`marketplace | `$<name>``/skills` 選單 | ❌(用 `$name` |
| Antigravity | `agy plugin install` | `/jsc-persona:<name>` 或自動觸發 | ✅ |
| OpenCode | skills 目錄(複製/clone) | 描述需求自動觸發 | ❌(依名稱) |
| GitHub Copilot CLI | `copilot plugin`marketplace | 自然語言或 plugin skills | ❌(無 `/jsc-persona:` 前綴) |
> Codex 不支援自訂前綴(skill 以 `$name` 呼叫);OpenCode 由模型依描述自動呼叫;Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。
---
## 目錄結構
同一個 repo 同時帶四種 manifest,彼此以路徑隔離、互不干擾;各助理都讀同一份 `skills/`
```
persona/
├── .claude-plugin/
│ ├── plugin.json # Claude 外掛定義(name: "jsc-persona"
│ └── marketplace.json # Claude marketplacename: "jsc-plugins"source 指向本 repo
├── .codex-plugin/
│ └── plugin.json # Codex 外掛定義(name: "jsc-persona"skills: "./skills"
├── .agents/plugins/
│ └── marketplace.json # Codex marketplacename: "jsc-plugins"url source 指向本 repo
├── plugin.json # Antigravity 外掛定義(name: "jsc-persona"skills: "./skills"
├── skills/ # ★ 唯一真實來源:所有 skills(十二個 persona-*
├── scripts/ # persona.mjs / persona-gitea.mjs / persona-icon.mjs / selftest.mjs
├── hooks/ # 六個 hook:鎖、隔離、上下文注入(只有 Claude Code 會執行)
├── agents/ # persona-guest(受邀人格)、persona-sleeper(睡眠收尾)
├── AGENTS.md # 跨助理共用指引
└── README.md
```
> `scripts/` 與 `hooks/` 只有「整個 repo 安裝」的助理拿得到;OpenCode 的目錄安裝只會複製 `skills/`。
---
@@ -73,7 +114,7 @@ flowchart TB
<slug>/
├── IDENTITY.md # 身分卡:Name / Creature / Gender / Vibe / Emoji / AvatarGender 是本 plugin 加的)
├── SOUL.md # 靈魂:Core Truths / Boundaries / Vibe / Continuity + 情緒傾向
├── AGENTS.md # 操作規則(與個性分離)
├── AGENTS.md # 操作規則(與個性分離)SessionStart 全文注入一次,也是放「這個人格的工具箱」的地方
├── icon.svg / icon.png # 人格圖示(由編號/名字/emoji 決定,也是 Gitea 存取庫頭像)
├── USER.md # 對使用者的畫像(事實/推測分開)
├── state/
@@ -420,7 +461,7 @@ node scripts/persona.mjs sleep --session <PERSONA_SESSION> --release # 收工
| Hook | 做什麼 |
| --- | --- |
| `SessionStart` | 清死鎖、接續人格、**有設預設人格就自動載入它**(沒設就只列出可用人格)、把 `PERSONA_SESSION=<session_id>` 與規則注入上下文 |
| `SessionStart` | 清死鎖、接續人格、**有設預設人格就自動載入它**(沒設就只列出可用人格)、把 `PERSONA_SESSION=<session_id>` 與規則注入上下文;載入到人格時追加 `<persona-ops>`=該人格 `AGENTS.md` 全文(開機一次,不進每輪的 `<persona-context>` |
| `UserPromptSubmit` | 注入 `<persona-context>`:身分、情緒、短期記憶、關鍵詞命中的長期記憶、相關人際關係;劇場模式時追加「只輸出人格對話」的強制規則;並記原始逐字 |
| `PreToolUse` | **人格隔離與鎖驗證的唯一強制點**(deny 帶原因) |
| `Stop` | 情緒隨時間衰減、續租、記錄回覆、達固化條件時提醒(劇場模式時完全靜音) |
@@ -545,20 +586,27 @@ node scripts/selftest.mjs # 248 項驗證:鎖、隔離、情緒、固化
| Codex | ✅ `$<name>` | ❌ | ⚠ 需自行以子任務模擬 |
| Antigravity | ✅ `/jsc-persona:<name>` | ❌ | ⚠ |
| OpenCode | ✅ 依描述自動觸發 | ❌ | ⚠ |
| GitHub Copilot CLI | ✅ 依描述自動觸發 | ❌ | ⚠ |
> 沒有 hook 的助理仍會遵守 CLI 層的檢查(`--session` 綁定、`require_owner``require_member`、
> guest 唯讀),但那是**自律**而非強制:真正的 deny 只有 Claude Code 的 `PreToolUse` 做得到。
---
## 安裝 / 更新 / 移除
## 安裝 / 更新 / 移除(各助理)
> 指令中的 repo 網址換成你的:`https://gitea.jsc.idv.tw/plugins/persona.git`
>
> **Claude / Codex 從 git URL 安裝(會 clone 遠端),請先把本 repo `push` 到 gitea。**
> **Antigravity 的 `agy plugin install <url>` 目前只支援 github.com**gitea 請改用「clone + 本地路徑」(見 Antigravity 節)。
> 本機/離線:Claude 可用本地路徑加 marketplaceAntigravity 用本地路徑安裝。
>
> 本 plugin 的 marketplace 名是 **`jsc-plugins`**(不是 repo 名 `persona`),安裝 token 為 `jsc-persona@jsc-plugins`。
### Claude Code
```bash
# 安裝
claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/persona.git
claude plugin install jsc-persona@jsc-plugins
@@ -568,49 +616,121 @@ claude plugin update jsc-persona@jsc-plugins
# 移除
claude plugin uninstall jsc-persona@jsc-plugins
claude plugin marketplace remove jsc-plugins
```
- 工作階段內 slash 版(等價):把 `claude plugin` 換成 `/plugin`。
- 本機開發(免 push):`claude plugin marketplace add /home/coder/plugins/persona` 後再 install。
- 本機開發(免 push):`claude plugin marketplace add /home/coder/plugins/persona`(本地路徑)後再 install。
- 安裝後**重啟工作階段**讓 hooks 生效;用 `/hooks` 確認六個 hook 都在。
- **呼叫**`/jsc-persona:<name>`(例 `/jsc-persona:persona-chat`)。
### Codex
```bash
# 安裝
codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/persona.git
codex plugin add jsc-persona@jsc-plugins
codex plugin marketplace upgrade jsc-plugins # 更新
codex plugin remove jsc-persona@jsc-plugins # 移除
# 更新(重新抓取 marketplace 的 git 快照)
codex plugin marketplace upgrade jsc-plugins
# 移除
codex plugin remove jsc-persona@jsc-plugins
codex plugin marketplace remove jsc-plugins
```
- 安裝 token `jsc-persona@jsc-plugins` = plugin 名(`.codex-plugin/plugin.json` 的 `name`@ marketplace 名(`.agents/plugins/marketplace.json` 的 `name`)。
- 本 repo 的 Codex marketplace 以 `url` 來源指向自己,故 Codex **一律從 gitea 安裝**(需先 push);安裝後重啟 Codex。
- **呼叫**`$<name>`(例 `$persona-chat`),或用 `/skills` 選單。
- Codex 沒有 hook:鎖與隔離只剩 CLI 層的自律檢查。
### Antigravity`agy`
> `agy plugin install <url>` 目前只支援 github.comgitea 請 clone 後用本地路徑
> `agy plugin install <url>` 目前**只支援 github.com**gitea 等自架 git 不支援 URL 安裝,請先 `git clone` 再用**本地路徑**安裝
```bash
# 安裝:clone 後用本地路徑
git clone https://gitea.jsc.idv.tw/plugins/persona.git ~/plugins/persona
agy plugin install ~/plugins/persona
# 更新:git -C ~/plugins/persona pull && agy plugin uninstall jsc-persona && agy plugin install ~/plugins/persona
# 更新(agy 無 update 子指令 → git pull 後重裝)
git -C ~/plugins/persona pull
agy plugin uninstall jsc-persona
agy plugin install ~/plugins/persona
# 移除
agy plugin uninstall jsc-persona
```
- 若把 skills 放到 GitHub,則可直接 `agy plugin install https://github.com/<owner>/<repo>`。
- 其他:`agy plugin list`、`agy plugin enable jsc-persona` / `disable jsc-persona`、`agy plugin validate <path>`。安裝後重啟工作階段。
- **呼叫**`/jsc-persona:<name>`(例 `/jsc-persona:persona-chat`)或依描述自動觸發。
### OpenCode
OpenCode 的「plugin」是 TypeScript/npm 套件,不適用於 skill 包;skills 改用**目錄安裝**。
OpenCode 會讀 `~/.config/opencode/skills/`(也會讀 `~/.claude/skills/`、`~/.agents/skills/`)。
```bash
# 安裝
git clone https://gitea.jsc.idv.tw/plugins/persona.git ~/plugins/persona
mkdir -p ~/.config/opencode/skills
cp -r ~/plugins/persona/skills/* ~/.config/opencode/skills/
# 更新
git -C ~/plugins/persona pull
cp -r ~/plugins/persona/skills/* ~/.config/opencode/skills/
# 移除
rm -rf ~/.config/opencode/skills/{persona-anime,persona-chat,persona-create,persona-icon,persona-invite,persona-memory,persona-relation,persona-sleep,persona-status,persona-sync,persona-therapist,persona-transfer}
```
> **Windows PowerShell**`cp -r A B` → `Copy-Item A B -Recurse -Force`、`~` → `$HOME`。
> **Windows PowerShell**`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
### headless 一次性執行
- 目錄安裝**不會帶入 `scripts/` 與 `hooks/`**`persona.mjs` 不在,等於整套狀態操作都不可用。要在 OpenCode 用本 plugin,請另外 clone 本 repo 並自行呼叫 `scripts/persona.mjs`。
- **呼叫**:直接描述需求,模型會依 skill 描述自動透過 skill 工具呼叫。
| 助理 | 指令 |
| --- | --- |
| Claude Code | `claude -p "/jsc-persona:persona-chat lumi"` |
| Codex | `codex exec '$persona-chat lumi'` |
| Antigravity | `agy -p "/jsc-persona:persona-chat lumi"` |
| OpenCode | `opencode run "用 lumi 這個人格跟我聊聊"` |
### GitHub Copilot CLI
Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令,可直接從 marketplace 安裝、更新與移除本 plugin。
```bash
# 安裝
copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/persona.git
copilot plugin install jsc-persona@jsc-plugins
# 更新
copilot plugin marketplace update jsc-plugins
copilot plugin update jsc-persona@jsc-plugins
# 移除
copilot plugin uninstall jsc-persona@jsc-plugins
copilot plugin marketplace remove jsc-plugins
```
- 安裝 token `jsc-persona@jsc-plugins` = plugin 名(plugin manifest 的 `name`@ marketplace 名。
- `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑;Gitea repo 可用上方 HTTPS URL。
- Copilot CLI 沒有 hook:鎖與隔離同樣只剩 CLI 層的自律檢查。
- **呼叫**:在 Copilot CLI 中用自然語言描述需求,例如 `copilot -i "用 lumi 這個人格跟我聊聊"`。
---
## 用 CLI 直接執行 skillheadless / 一次性)
安裝好之後,不必進互動介面,一行指令就能叫某個 skill 跑完並印出結果:
| 助理 | headless 指令 | 執行 `persona-chat` skill |
| --- | --- | --- |
| Claude Code | `claude -p "<prompt>"` | `claude -p "/jsc-persona:persona-chat lumi"` |
| Codex | `codex exec "<prompt>"` | `codex exec '$persona-chat lumi'` |
| Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc-persona:persona-chat lumi"` |
| OpenCode | `opencode run "<message>"` | `opencode run "用 lumi 這個人格跟我聊聊"` |
| GitHub Copilot CLI | `copilot -p "<message>"` | `copilot -p "用 lumi 這個人格跟我聊聊"` |
- Claude / Antigravity 支援 `/jsc-persona:` 前綴,直接 `-p "/jsc-persona:<name>"` 即可。
- Codex 以 `$<name>` 觸發;在 shell 請用**單引號**避免 `$` 被展開:`codex exec '$persona-chat …'`。
- OpenCode 與 Copilot 沒有前綴,用自然語言描述需求;Copilot CLI 會讀取已安裝 plugin 提供的 skills。
- 帶引數就接在後面,例如 `claude -p "/jsc-persona:persona-status --json"`。
---
+13
View File
@@ -37,6 +37,17 @@ const lines = [
" 4. 禁止直接讀寫非當前人格的目錄,hook 會擋下(跨人格資料隔離)。",
];
/**
* 把 AGENTS.md(操作規則)注入一次。
*
* 放這裡而不是 turnContext:它是低頻的「怎麼做事」,開機讀一次就夠,
* 每輪重貼只是浪費 context。人格自己的工具箱(例如六把劍)寫在裡面就會跟著人格走。
*/
function pushOps(slug) {
const ops = pl.opsBrief(slug);
if (ops) lines.push(ops);
}
/** 列出可用人格,讓使用者挑(沒有預設人格、或預設人格載入失敗時用)。 */
function listAvailable() {
const personas = pl.listPersonas();
@@ -58,6 +69,7 @@ if (host && pl.personaExists(host)) {
pl.acquireLock(host, sessionId, { cwd });
lines.push(`已接續人格 \`${host}\`session 恢復:${source})。`);
lines.push(pl.turnContext(host, sessionId));
pushOps(host);
} catch (err) {
lines.push(`⚠ 無法接續人格 \`${host}\`${err.message}`);
}
@@ -75,6 +87,7 @@ if (host && pl.personaExists(host)) {
lines.push("請照 /jsc-persona:persona-chat 的每輪流程走(語意分析→情緒→回想→3 句內回覆→記憶回寫)。");
lines.push("提醒:這次是本機自動載入,沒有從 Gitea 拉最新狀態;若可能在別台機器動過,先 `sync pull`。");
lines.push(pl.turnContext(wanted, sessionId));
pushOps(wanted);
} catch (err) {
lines.push(`⚠ 預設人格 \`${wanted}\` 自動載入失敗:${err.message}`);
lines.push("不要自作主張 `--takeover`——先把 owner 與最後心跳告訴使用者,讓他決定。");
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-persona",
"version": "0.0.8",
"version": "0.0.9",
"description": "AI 人格化記憶聊天 pluginOpenClaw 相同的人格描述 + 十二情緒 + 語意分析 + 短期/長期記憶 + 心智圖 + 人際關係圖。於 Antigravity 以 /jsc-persona: 前綴呼叫。",
"skills": "./skills"
}
+32
View File
@@ -1733,6 +1733,9 @@ export function sentenceCount(text) {
export const MAX_SENTENCE_CHARS = 45;
// AGENTS.md 開機注入的上限:超過就截斷並指路回原檔,不要一份規則吃掉整個 context。
export const OPS_BRIEF_MAX_CHARS = 6000;
// 講完就算了:這些開頭都是在解釋自己剛才講的話,真的在講話的人不會這樣。
export const EXPLAINER_OPENERS = [
"我的意思是", "我是想說", "換句話說", "換個說法", "也就是說", "換言之",
@@ -3082,6 +3085,35 @@ export function identityBrief(slug) {
return order.filter((k) => fields[k]).map((k) => `${k}: ${fields[k]}`).join("");
}
/**
* SessionStart 注入的操作規則:AGENTS.md 全文。
*
* 只在開機注入一次(不進 turnContext)——它是低頻的「怎麼做事」,
* 每輪重貼只是把 context 燒掉。內容太長就截斷並指路回原檔。
*/
export function opsBrief(slug) {
let text;
try {
text = fs.readFileSync(path.join(personaDir(slug), "AGENTS.md"), "utf8").trim();
} catch {
return "";
}
if (!text) return "";
const file = path.join(personaDir(slug), "AGENTS.md");
let body = text;
if (body.length > OPS_BRIEF_MAX_CHARS) {
body = body.slice(0, OPS_BRIEF_MAX_CHARS) + `\n\n(後略;全文見 ${file}`;
}
return [
"<persona-ops>",
`以下是 \`${slug}\` 的操作規則(${file}):這輪開機注入一次,之後不再重複貼。`,
"要重看用 `persona.mjs show --what agents --session <id>`;改了就直接編輯那個檔案。",
"",
body,
"</persona-ops>",
].join("\n");
}
/** UserPromptSubmit 注入的人格上下文:身分 + 情緒 + 短期記憶 + 相關長期記憶 + 關係。 */
export function turnContext(slug, sessionId, prompt = "") {
const state = decayEmotion(loadEmotion(slug));
+25
View File
@@ -81,6 +81,31 @@ check("IDENTITY 五欄位可解析", pl.identityBrief("alpha").includes("Name: A
check("SOUL/AGENTS/USER 都有產生",
["SOUL.md", "AGENTS.md", "USER.md"].every((f) => fs.existsSync(path.join(pl.personaDir("alpha"), f))));
// 操作規則(AGENTS.md)只在開機注入一次:人格自己的工具箱寫在裡面就會跟著人格走。
check("opsBrief 帶回 AGENTS.md 全文", (() => {
const ops = pl.opsBrief("alpha");
return ops.includes("<persona-ops>") && ops.includes("</persona-ops>") && ops.includes("每輪對話要做的事");
})(), pl.opsBrief("alpha").slice(0, 200));
check("opsBrief 指得出原檔路徑", pl.opsBrief("alpha").includes(path.join(pl.personaDir("alpha"), "AGENTS.md")));
check("opsBrief 不進 turnContext(開機一次就好)",
!pl.turnContext("alpha", S_HOST, "在嗎").includes("<persona-ops>"));
check("AGENTS.md 不存在時 opsBrief 回空字串", (() => {
const file = path.join(pl.personaDir("omega"), "AGENTS.md");
const backup = fs.readFileSync(file, "utf8");
fs.rmSync(file);
const empty = pl.opsBrief("omega");
fs.writeFileSync(file, backup);
return empty === "";
})());
check("opsBrief 超長會截斷並指路", (() => {
const file = path.join(pl.personaDir("omega"), "AGENTS.md");
const backup = fs.readFileSync(file, "utf8");
fs.writeFileSync(file, "劍".repeat(pl.OPS_BRIEF_MAX_CHARS + 500));
const ops = pl.opsBrief("omega");
fs.writeFileSync(file, backup);
return ops.includes("(後略;全文見") && ops.length < pl.OPS_BRIEF_MAX_CHARS + 500;
})());
console.log("② 人格鎖:一個人格只能被一個程序載入");
check("建立時即取得鎖", pl.lockStatus("alpha").locked);
check("同 session 重入成功", cli(["load", "--persona", "alpha", "--session", S_HOST]).status === 0);