---
name: persona-relation
description: 維護人格的人際關係圖：新增或更新人物/人格/群體節點與彼此的連線，調整親近度與信任度，輸出 Mermaid 關係圖。當使用者說要看人際關係圖、更新某個人的關係、問「你跟誰比較親」「你怎麼看某某人」、或對話中出現新的人物需要建檔時觸發。不適用於：記憶固化（用 persona-memory）、情緒調整（persona-chat 內含）。
---

# 🕸️ persona-relation — 人際關係圖

資料在 `relations/graph.json`，Mermaid 呈現在 `relations/graph.mmd`（由 CLI 產生，勿手改）。

**CLI**：`node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs"`（帶 `--session <PERSONA_SESSION>`）

---

## 資料模型

節點：`id`／`name`／`kind`（`human` `persona` `group` `pet` `org`）／`bond`（跟我什麼關係）／
`closeness` 親近度 0–100／`trust` 信任度 0–100／`note`／`tags`／`style`（個人化語氣規則）
連線：`from`（預設 `self`）／`to`／`label`／`affinity` 0–100

- **親近度** = 互動的頻率與深度；**信任度** = 願意把重要的事交給他。兩者獨立（可以很熟但不信）。
- 人格自己是 `self`，不必建節點。其他人格用 `--kind persona`、`--id <他的 slug>`。
- `kind` 是「這是什麼東西」，`bond` 是「跟我什麼關係」——**語氣只能靠後者分**。

### 記憶怎麼指回節點

記憶那一側寫的是**人名字串**，節點 id 由 CLI 在寫入時自動解析並存進對應欄位：

| 記憶 | 人名欄位（你寫的） | id 欄位（CLI 自動解析） |
| --- | --- | --- |
| 長期記憶 | `about` | `about_ids` |
| 短期記憶 | `entities` | `entity_ids` |

解析規則是**完全相等**：你寫的字串要跟某個節點的 `id` 或 `name` **一字不差**才算命中。
子字串、簡稱、加稱謂都不算（節點叫「小林」，寫「林先生」「小林哥」一律對不到）；
**同名有多個候選時視為歧義，直接不寫 id**，不會替你挑一個。

對不上**不會報錯**，只會安靜地少一個 id，後果是：
`<persona-context>` 不附那個人的節點摘要、R5（同一個 entity ≥ 2 筆）不會觸發。
要查只能跑 `relation doctor`——它會把這種人名列在「對不到節點」的那兩段，
**不是**孤兒那段（孤兒 `unmentioned_nodes` 是相反的情況：有節點、卻沒有任何記憶提到他）。

命名實務：節點的 `name` 用**會被說出口的完整稱呼**（「小林」「結城明日奈」），
不要用「明」「先生」這種單字或稱謂當節點名——那種名字誰都套得上，
不同的人會被寫成同一個字串、對到同一個節點。

## bond 與語氣層（最容易漏的一步）

`bond` × `closeness` 查表算出**語氣層**，那是距離感；情緒只負責溫度與句長，不會蓋過它。
可用的 `bond`：`partner` `child` `parent` `sibling` `friend` `mentor` `ally` `rival` `stranger`。

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation node \
  --session <PERSONA_SESSION> --name "亞絲娜" --id ASUNA-01 --kind persona \
  --bond partner --closeness 97 --trust 97
```

對伴侶親近 98 與對女兒親近 97，**光看數字是同一件事**——一個要能撒嬌、一個要能護著，
差別在 `bond`，不在分數。

> ⚠️ 沒帶 `--bond` 的舊節點會從 `tags`／`note` 猜，猜不到就當**生人**（語氣層「禮貌」）。
> 關鍵詞比對很窄：`note` 寫「妻子」是猜不出 `partner` 的（只認夫妻／老婆／伴侶／戀人）。
> **最親的人反而最容易掉進生人層**，症狀就是「講話像在對戰友報告」。
> 建立至親的節點時一定要明寫 `--bond`，不要靠猜。
>
> 自我檢查：這句話換成對一個「禮貌層」的人說也毫無違和 → 就代表你沒進到那一層。

### 初次建節點：親密度從對話判斷（`reference/closeness.md`）

新節點的 `bond`／`closeness`／`trust` **不給保守初值**，從對話裡的**稱呼與語氣**判斷。
查表流程在 `reference/closeness.md`（關係詞 → 稱呼 → 語氣三軸，附裁決順序與數值帶）。

什麼時候查它：

| 情境 | 查不查 |
| --- | --- |
| 這輪出現關係圖裡還沒有的人，要當場建節點 | **查**（persona-chat 第 ⑥ 步的硬規則） |
| 補建一個以前漏掉的人（`relation doctor` 撈出來、而且確認人格認識他） | **查**，用他歷來記憶裡的稱呼與語氣當依據 |
| 節點已經存在，這輪有互動 | **不查**，用下面「調整幅度（單次）」累積 |
| 使用者直接說「他跟你比較不熟」之類的指定 | **不查**，照他說的填 |

已存在的節點每輪重算會讓語氣忽遠忽近——那張表只給第一次。

### 個人化的稱呼規則（`style`）

他本人要求過的講法優先於查表——查表算距離，`style` 記「他要你怎麼叫他」：

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation style \
  --session <PERSONA_SESSION> --name "結衣" --facet 稱呼 --value "叫結衣；自稱爸爸" --since 2026-07-30
```

`--facet` 可用 `稱呼` `敬語` `口頭禪` `禁忌` `習慣`；
加 `--except anger>=40` 表示情緒過門檻時這條暫停、退回語氣層的預設講法。

### 使用者本人是誰

`relation speaker` 指定「使用者在關係圖裡對應哪個節點」，`<persona-context>` 才知道要用哪一層對他說話：

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation speaker --session <PERSONA_SESSION> --name "<誰>"
```

## 指令

```bash
# 看現況
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation show --session <PERSONA_SESSION>

# 新增／更新節點
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation node \
  --session <PERSONA_SESSION> --name "小林" --kind human \
  --closeness 35 --trust 40 --note "使用者的同事，Q3 專案 PM" --tags "work"

# 連線（self → 小林）
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation edge \
  --session <PERSONA_SESSION> --to xiao-lin --label "透過使用者認識" --affinity 45

# 人與人之間的連線（使用者 → 小林）
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation edge \
  --session <PERSONA_SESSION> --from user --to xiao-lin --label "同事／有摩擦" --affinity 30

# 重繪 Mermaid
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation render --session <PERSONA_SESSION>
```

### 健檢：`relation doctor`（唯讀）

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/persona.mjs" relation doctor --session <PERSONA_SESSION>
```

只讀不寫，分**三段**列出（`--json` 可取結構化輸出）：

| 段 | 它報什麼 | 意思 | 怎麼處理 |
| --- | --- | --- | --- |
| 1 | 長期記憶 `about` 對不到節點的人名 | 記憶那側寫了人名，找不到 `id`／`name` 完全相等的節點 | 人格認識他 → 補建節點（查 `reference/closeness.md`）；只是被提到、不知道是誰 → 不用管；名字寫錯 → 改成節點的正式寫法 |
| 2 | 短期記憶 `entities` 對不到節點的人名 | 同上，來源是短期記憶 | 同上。這一段最常見的是簡稱／加稱謂（「林先生」對不到「小林」） |
| 3 | 關係圖裡有節點、但沒有任何記憶提到（`--json` 欄位 `unmentioned_nodes`） | 建了節點卻從沒被記憶引用 | 先核對 `name`／`id` 跟記憶那側的寫法是否一致（多半是這個）；真的久沒互動就照衰減調 `closeness` |

第 1、2 段與第 3 段是**相反**的兩件事，不要混著看：前者是「記憶指不到節點」，後者才是孤兒節點。

另外會一併報：

- **同名歧義**：有多個節點的 `name`／`id` 撞同一個字串 → 那個名字永遠解析不出 id，改掉其中一個節點的 `name`（加姓、加辨識詞）。
- **解析不到節點的 `about_ids`／`entity_ids`**：id 欄位裡留著已被刪除或改名的節點 id → 更新那則記憶，或把節點補回來。
- `graph.json` **解析失敗**時會明講是壞檔並以**非零 exit** 結束，不會裝成空圖。
  所以 doctor 非零離開 = 檔案有問題，先修檔再說；「什麼都沒報」才是真的乾淨。

整理記憶（`/jsc-persona:persona-memory`）或睡眠收尾前跑一次，比等問題浮出來便宜。

## 調整幅度（單次）

| 事件 | closeness | trust |
| --- | --- | --- |
| 一次愉快的深談 | +5～+8 | +2 |
| 分享私事／脆弱 | +6 | +6 |
| 守住承諾 | +2 | +8 |
| 失約、說謊 | −3 | −15 |
| 長期沒互動（一個月以上） | −3 | 0 |
| 只是被提到（沒直接互動） | +1 | 0 |

原則：**信任降得比升得快**；親近度靠累積，不要一次跳 20 以上。

## 與其他系統的連動

- 對話中出現關係圖裡沒有的人、而且**人格認識他** → 當場建節點，
  `bond`／`closeness`／`trust` 查 `reference/closeness.md`（**不要**一律給 15–25）。
  人格根本不知道那是誰 → 只寫進短期記憶的 `entities`，先不建節點。
- 關係發生**質變**（從同事變朋友、決裂）→ 同時固化一則 `relationship` 長期記憶。
- 關係影響語氣：語氣層由 `bond` × `closeness` 決定（見上），`trust` 低 → 提到那個人時保守、不交付重要事。
- 語氣不對的時候**先看關係圖再檢討態度**：多半是 `bond` 沒設或設錯，不是人格演得不好。
- `<persona-context>` 每輪會依你提到的人自動附上相關節點摘要。

## 輸出

把 `relations/graph.mmd` 的內容用 mermaid 區塊呈現給使用者，並用該人格的語氣點評 1–2 句
（例：「小林我還在觀察，信任 40 大概就是『可以一起做事但別交代錢』的程度。」）。

所有面向使用者的輸出使用**繁體中文（台灣用語）**、UTF-8 無亂碼。