2026-07-28 03:13:47 +00:00
12 changed files with 2121 additions and 4 deletions
@@ -1,6 +1,6 @@
 {
  "name": "jsc",
-  "version": "0.0.3",
+  "version": "0.0.4",
  "description": "JSC 跨 AI 助理共用規範 plugin（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
  "skills": "./skills",
  "author": {
@@ -1,6 +1,6 @@
 {
  "name": "jsc",
-  "version": "0.0.3",
+  "version": "0.0.4",
  "description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準。",
  "skills": "./skills"
 }
@@ -35,13 +35,19 @@ generic/
 ├── .agents/plugins/
 │   └── marketplace.json     # Codex marketplace（name: "generic"，url source 指向本 repo）
 ├── plugin.json              # Antigravity 外掛定義（name: "jsc"，skills: "./skills/"）
+├── hooks/
+│   └── hooks.json           # hook 定義（SessionStart 載入角色、Stop 記錄記憶）
+├── scripts/
+│   └── role/                # role skill 的可執行元件（腳本一律不放進 skills/）
 ├── skills/                  # ★ 唯一真實來源：所有 skills
-│   └── spec-*/SKILL.md      # 共用規範 skills（一規範一目錄）
+│   ├── spec-*/SKILL.md      # 共用規範 skills（一規範一目錄）
+│   └── role/SKILL.md        # 角色人格與長期記憶
 ├── AGENTS.md                # 跨助理共用指引
 └── README.md
 ```

 > generic 的定位是「**共用規範**」：`skills/spec-*` 是 code／doc plugins 共用的流程與安全規範。工作紀錄自動化 `worklog` 已移到 `doc` plugin。
+> 例外是 `role`：它是跨助理共用的**角色與記憶**能力，帶 `hooks/` 與 `scripts/`，適用範圍見下方「元件對各助理的適用範圍」。

 ---

@@ -204,10 +210,34 @@ copilot plugin marketplace remove generic
 | `spec-doc-funcs-handoff` | 文件化串接 | code 類 skill 完成後完整執行 /jsc:doc-funcs 的標準流程與統一時間戳 |
 | `spec-plugin-version` | 版號規則 | 三 manifest 同步 bump、對照 master 確保單調遞增、新 plugin 首發 0.0.1、chore(plugin 版本) commit |

+### 角色與記憶
+
+| Skill | 用途 | 使用方法 |
+| --- | --- | --- |
+| `role` | 讓 CLI 以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：啟動時自動載入角色與記憶，睡眠時段（預設 22:00–06:00）由排程整理、去重、標籤化、壓縮歸檔並適當遺忘 | `/jsc:role --new` 建立或更新角色、`--use <名稱>` 切換、`--list`、`--sleep` 立即整理、`--status` 診斷、`--install-cron` 安裝排程 |
+
+`role` 的自動路徑由 hook 與 cron 完成，**建立角色後重開工作階段即生效**；沒有建立過角色的人完全不受影響（`~/.roles/.active` 不存在時 hook 立即結束）。細節見 `skills/role/SKILL.md`。
+
 <!-- JSC-SKILLS:END -->

 ---

+## 元件對各助理的適用範圍
+
+`skills/` 各助理都能用；`hooks/` 與 `scripts/` 則否。
+
+| 元件 | Claude Code | Codex | Antigravity | OpenCode | GitHub Copilot |
+| --- | --- | --- | --- | --- | --- |
+| `skills/spec-*`（純規範） | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `skills/role` 的手動模式 | ✅ | ⚠️ 需保留 `scripts/` | ⚠️ 同左 | ❌ 只複製 `skills/` | ⚠️ 同左 |
+| `hooks/hooks.json`：`SessionStart` 載入角色 | ✅ | ⚠️ 需該版本支援 | ❌ | ❌ | ❌ |
+| `hooks/hooks.json`：`Stop` 記錄記憶 | ✅ | ✅ | ❌ | ❌ | ❌ |
+| cron 睡眠整理（系統排程） | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+> **OpenCode 以複製 `skills/` 目錄安裝**，不會帶入 `scripts/` 與 `hooks/`，凡依賴腳本的 skill 一律不可用。
+
+---
+
 ## 新增一個 skill

 1. 複製既有 skill 作範本：`cp -r skills/spec-output skills/<your-skill-name>`
@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ]; then exec \"$root/scripts/role/role_load.sh\"; fi; script=$(find \"$HOME/.codex/plugins/cache/generic/jsc\" -path '*/scripts/role/role_load.sh' -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$script\" ]; then exec \"$script\"; fi; exit 0",
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ]; then exec \"$root/scripts/role/role_capture.sh\"; fi; script=$(find \"$HOME/.codex/plugins/cache/generic/jsc\" -path '*/scripts/role/role_capture.sh' -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$script\" ]; then exec \"$script\"; fi; exit 0",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -1,6 +1,6 @@
 {
  "name": "jsc",
-  "version": "0.0.3",
+  "version": "0.0.4",
  "description": "JSC 跨 AI 助理共用規範 plugin。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
  "skills": "./skills/"
 }
@@ -0,0 +1,690 @@
+#!/usr/bin/env python3
+# ==============================================================================
+# 用途：角色記憶（.memory/<角色>/）的儲存引擎。負責 (1) 把每輪對話濃縮結果寫入
+#       inbox，(2) 產生 SessionStart 要注入的記憶區塊，(3) 睡眠整理時輸出待整理
+#       素材並套用整理結果（分類／去重／標籤／總結／壓縮歸檔），(4) 依使用頻率
+#       遺忘日常與其他類記憶。
+# 更新時間：2026/07/28 00:00:00
+# 相依：Python 3 標準庫。
+# 退出碼：0 成功；1 無內容可處理；2 參數錯誤。呼叫端（hook）一律不得因此中斷。
+# ==============================================================================
+
+import argparse
+import gzip
+import hashlib
+import json
+import os
+import re
+import shutil
+import sys
+from datetime import datetime, timedelta, timezone
+
+# ------------------------------------------------------------------------------
+# 常數：分類、載入策略、遺忘規則
+# ------------------------------------------------------------------------------
+
+# 六個分類的目錄名（英文，跨平台安全）與中文標籤
+CATEGORIES = ["important", "interest", "news", "skill", "daily", "other"]
+CATEGORY_LABELS = {
+    "important": "重要",
+    "interest": "興趣",
+    "news": "新知",
+    "skill": "技能",
+    "daily": "日常",
+    "other": "其他",
+}
+# 中文分類名反查（模型可能直接輸出中文）
+LABEL_TO_CATEGORY = {label: key for key, label in CATEGORY_LABELS.items()}
+
+# 載入策略：重要與興趣載入全文，其餘僅載入總結與標籤
+FULL_CATEGORIES = ["important", "interest"]
+# 摘要載入順序：技能 → 新知 → 日常 → 其他
+DIGEST_CATEGORIES = ["skill", "news", "daily", "other"]
+
+# 遺忘規則：(未更新天數門檻, 命中次數上限)；只套用於日常與其他
+FORGET_RULES = {"daily": (14, 1), "other": (7, 1)}
+
+# 單次睡眠整理最多處理的 inbox 筆數，其餘留待下個睡眠週期
+SLEEP_BATCH = 60
+# 送進模型的素材字元上限
+COLLECT_LIMIT = 40000
+# 單則記憶壓縮後的內容字元上限
+CONTENT_LIMIT = 1200
+
+TAIPEI = timezone(timedelta(hours=8))
+STAMP_FORMAT = "%Y/%m/%d %H:%M:%S"
+
+
+# ------------------------------------------------------------------------------
+# 路徑與時間
+# ------------------------------------------------------------------------------
+
+
+def now_stamp():
+    """回傳台灣時區的 yyyy/MM/dd HH:mm:ss 時間字串。"""
+    return datetime.now(TAIPEI).strftime(STAMP_FORMAT)
+
+
+def parse_stamp(value):
+    """把 yyyy/MM/dd HH:mm:ss 字串解析成帶時區的 datetime，失敗回 None。"""
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        return datetime.strptime(value.strip(), STAMP_FORMAT).replace(tzinfo=TAIPEI)
+    except ValueError:
+        return None
+
+
+def memory_root(role):
+    """回傳指定角色的記憶根目錄（可用 ROLE_MEMORY_HOME 覆寫預設 ~/.memory）。"""
+    base = os.environ.get("ROLE_MEMORY_HOME") or os.path.join(os.path.expanduser("~"), ".memory")
+    return os.path.join(base, role)
+
+
+def ensure_layout(role):
+    """建立角色記憶目錄結構（inbox、六個分類、archive），回傳根目錄。"""
+    root = memory_root(role)
+    for sub in ["inbox", "archive/raw", "archive/forgotten"] + CATEGORIES:
+        os.makedirs(os.path.join(root, sub), exist_ok=True)
+    return root
+
+
+def state_path(role):
+    """回傳角色記憶狀態檔（state.json）的路徑。"""
+    return os.path.join(memory_root(role), "state.json")
+
+
+def read_state(role):
+    """讀取狀態檔；不存在或損壞時回空 dict。"""
+    try:
+        with open(state_path(role), encoding="utf-8") as fh:
+            data = json.load(fh)
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def write_state(role, patch):
+    """把 patch 併入狀態檔後寫回（整份覆寫，內容極小）。"""
+    state = read_state(role)
+    state.update(patch)
+    ensure_layout(role)
+    with open(state_path(role), "w", encoding="utf-8") as fh:
+        json.dump(state, fh, ensure_ascii=False, indent=2)
+    return state
+
+
+# ------------------------------------------------------------------------------
+# 記憶檔格式：YAML 風格 frontmatter ＋ 內文
+# ------------------------------------------------------------------------------
+
+
+def normalize_category(value):
+    """把模型輸出的分類（英文或中文）正規化為分類鍵；無法判定時回 other。"""
+    raw = (value or "").strip().lower()
+    if raw in CATEGORIES:
+        return raw
+    return LABEL_TO_CATEGORY.get((value or "").strip(), "other")
+
+
+def normalize_tags(value):
+    """把標籤（list 或逗號分隔字串）正規化為去重後的小寫標籤 list，最多 6 個。"""
+    if isinstance(value, str):
+        parts = re.split(r"[,、|]", value)
+    elif isinstance(value, list):
+        parts = [str(item) for item in value]
+    else:
+        parts = []
+    tags = []
+    for part in parts:
+        tag = part.strip().strip("[]#").strip()
+        if tag and tag.lower() not in [t.lower() for t in tags]:
+            tags.append(tag)
+    return tags[:6]
+
+
+def one_line(value, limit=120):
+    """把文字壓成單行並截斷，用於 summary 欄位。"""
+    text = re.sub(r"\s+", " ", str(value or "")).strip()
+    return text[:limit]
+
+
+def dump_memory(meta, content):
+    """把 meta 與內文組成記憶檔全文（frontmatter ＋ 內文）。"""
+    lines = ["---"]
+    for key in ["id", "category", "summary", "tags", "created", "updated", "hits", "sources"]:
+        if key not in meta:
+            continue
+        value = meta[key]
+        if isinstance(value, list):
+            value = "[" + ", ".join(str(item) for item in value) + "]"
+        lines.append(f"{key}: {value}")
+    lines.append("---")
+    lines.append("")
+    lines.append(content.strip())
+    lines.append("")
+    return "\n".join(lines)
+
+
+def load_memory(path):
+    """讀取單一記憶檔，回傳 (meta dict, 內文)；讀取失敗回 (None, "")。"""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            raw = fh.read()
+    except OSError:
+        return None, ""
+
+    meta = {"path": path, "hits": 0, "tags": []}
+    body = raw
+    if raw.startswith("---"):
+        parts = raw.split("---", 2)
+        if len(parts) >= 3:
+            body = parts[2]
+            for line in parts[1].splitlines():
+                if ":" not in line:
+                    continue
+                key, _, value = line.partition(":")
+                key = key.strip()
+                value = value.strip()
+                if key in ("tags", "sources"):
+                    meta[key] = normalize_tags(value.strip("[]"))
+                elif key == "hits":
+                    meta[key] = int(value) if value.isdigit() else 0
+                else:
+                    meta[key] = value
+    meta.setdefault("id", os.path.splitext(os.path.basename(path))[0])
+    meta.setdefault("summary", "")
+    meta.setdefault("created", "")
+    meta.setdefault("updated", meta.get("created", ""))
+    return meta, body.strip()
+
+
+def new_id(seed):
+    """以時間與內容雜湊產生記憶 id，確保同一秒多筆也不碰撞。"""
+    digest = hashlib.sha1(seed.encode("utf-8", "replace")).hexdigest()[:6]
+    return f"{datetime.now(TAIPEI).strftime('%Y%m%d-%H%M%S')}-{digest}"
+
+
+def list_memories(role, category):
+    """列出某分類下的所有記憶（依 updated 新到舊排序）。"""
+    directory = os.path.join(memory_root(role), category)
+    items = []
+    if not os.path.isdir(directory):
+        return items
+    for name in sorted(os.listdir(directory)):
+        if not name.endswith(".md"):
+            continue
+        meta, content = load_memory(os.path.join(directory, name))
+        if meta is None:
+            continue
+        meta["category"] = category
+        items.append((meta, content))
+    items.sort(key=lambda item: item[0].get("updated") or "", reverse=True)
+    return items
+
+
+def list_inbox(role):
+    """列出 inbox 內尚未整理的記憶（依檔名，即時間先後排序）。"""
+    directory = os.path.join(memory_root(role), "inbox")
+    items = []
+    if not os.path.isdir(directory):
+        return items
+    for name in sorted(os.listdir(directory)):
+        if not name.endswith(".md"):
+            continue
+        meta, content = load_memory(os.path.join(directory, name))
+        if meta is not None:
+            items.append((meta, content))
+    return items
+
+
+def find_memory(role, memory_id):
+    """依 id 在六個分類中尋找記憶檔，回傳 (meta, 內文)；找不到回 (None, "")。"""
+    for category in CATEGORIES:
+        path = os.path.join(memory_root(role), category, f"{memory_id}.md")
+        if os.path.isfile(path):
+            meta, content = load_memory(path)
+            if meta is not None:
+                meta["category"] = category
+            return meta, content
+    return None, ""
+
+
+def archive_file(path, destination_dir):
+    """把檔案 gzip 後搬到歸檔目錄，原檔刪除；失敗時保留原檔。"""
+    os.makedirs(destination_dir, exist_ok=True)
+    target = os.path.join(destination_dir, os.path.basename(path) + ".gz")
+    try:
+        with open(path, "rb") as src, gzip.open(target, "wb") as dst:
+            shutil.copyfileobj(src, dst)
+        os.remove(path)
+        return True
+    except OSError:
+        return False
+
+
+# ------------------------------------------------------------------------------
+# 子命令：write —— 由 Stop hook 寫入一則未整理記憶
+# ------------------------------------------------------------------------------
+
+FIELD_PATTERN = re.compile(r"^\s*(CATEGORY|SUMMARY|TAGS|CONTENT)\s*[:：]\s*(.*)$", re.IGNORECASE)
+
+
+def parse_capture(text):
+    """
+    解析 Stop hook 濃縮器輸出的四欄格式（CATEGORY／SUMMARY／TAGS／CONTENT）。
+
+    模型可能夾帶前後贅字，故逐行掃描欄位標記，CONTENT 之後的所有內容視為內文。
+    """
+    category = summary = ""
+    tags = []
+    content_lines = []
+    in_content = False
+    for line in text.splitlines():
+        match = FIELD_PATTERN.match(line)
+        if match and not (in_content and match.group(1).upper() != "CONTENT"):
+            field = match.group(1).upper()
+            value = match.group(2)
+            if field == "CATEGORY":
+                category = value
+            elif field == "SUMMARY":
+                summary = value
+            elif field == "TAGS":
+                tags = normalize_tags(value)
+            elif field == "CONTENT":
+                in_content = True
+                if value.strip():
+                    content_lines.append(value)
+            continue
+        if in_content:
+            content_lines.append(line)
+    return category, summary, tags, "\n".join(content_lines).strip()
+
+
+def cmd_write(args):
+    """把 stdin 的濃縮結果寫成一則 inbox 記憶。"""
+    raw = sys.stdin.read()
+    category, summary, tags, content = parse_capture(raw)
+    if not content and not summary:
+        return 1
+    if not content:
+        content = summary
+    content = content[:CONTENT_LIMIT]
+    stamp = now_stamp()
+    meta = {
+        "id": new_id(content + stamp),
+        "category": normalize_category(category),
+        "summary": one_line(summary) or one_line(content),
+        "tags": tags,
+        "created": stamp,
+        "updated": stamp,
+        "hits": 1,
+    }
+    if args.project:
+        meta["sources"] = [args.project]
+    ensure_layout(args.role)
+    path = os.path.join(memory_root(args.role), "inbox", f"{meta['id']}.md")
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(dump_memory(meta, content))
+    sys.stdout.write(meta["id"])
+    return 0
+
+
+# ------------------------------------------------------------------------------
+# 子命令：load —— 產生 SessionStart 要注入的記憶區塊
+# ------------------------------------------------------------------------------
+
+
+def cmd_load(args):
+    """
+    組出載入用記憶區塊：重要與興趣載入全文，其餘依技能→新知→日常→其他只載總結與標籤。
+
+    超過字元上限時截斷並標明，避免佔滿 context。
+    """
+    limit = args.limit
+    blocks = []
+    total_full = 0
+    for category in FULL_CATEGORIES:
+        items = list_memories(args.role, category)
+        if not items:
+            continue
+        lines = [f"### {CATEGORY_LABELS[category]}記憶（全文）"]
+        for meta, content in items:
+            tags = "、".join(meta.get("tags") or []) or "無標籤"
+            lines.append(f"- **{meta.get('summary') or '（無總結）'}**（標籤：{tags}）")
+            for line in content.splitlines():
+                if line.strip():
+                    lines.append(f"  {line.strip()}")
+            total_full += 1
+        blocks.append("\n".join(lines))
+
+    digest_lines = []
+    digest_count = 0
+    for category in DIGEST_CATEGORIES:
+        items = list_memories(args.role, category)
+        if not items:
+            continue
+        digest_lines.append(f"### {CATEGORY_LABELS[category]}記憶（總結）")
+        for meta, _ in items:
+            tags = "、".join(meta.get("tags") or []) or "無標籤"
+            digest_lines.append(f"- {meta.get('summary') or '（無總結）'}（標籤：{tags}）")
+            digest_count += 1
+    if digest_lines:
+        blocks.append("\n".join(digest_lines))
+
+    pending = len(list_inbox(args.role))
+    if pending:
+        blocks.append(f"> 尚有 {pending} 則未整理記憶，將於下次睡眠時段歸檔。")
+
+    if not blocks:
+        return 1
+
+    text = "\n\n".join(blocks)
+    if len(text) > limit:
+        text = text[:limit] + f"\n\n> （記憶內容超過 {limit} 字元已截斷，完整記憶仍保存在磁碟）"
+    sys.stdout.write(text)
+    return 0
+
+
+# ------------------------------------------------------------------------------
+# 子命令：collect —— 睡眠整理前輸出待整理素材
+# ------------------------------------------------------------------------------
+
+
+def cmd_collect(args):
+    """輸出送進模型的整理素材：inbox 待整理項目 ＋ 既有記憶索引（供去重比對）。"""
+    inbox = list_inbox(args.role)[:SLEEP_BATCH]
+    if not inbox:
+        return 1
+
+    lines = ["=== INBOX（待整理，每則以 id 標識）==="]
+    for meta, content in inbox:
+        lines.append(f"--- id: {meta['id']} | 時間: {meta.get('created', '-')} ---")
+        lines.append(f"初判分類: {CATEGORY_LABELS.get(meta.get('category', 'other'), '其他')}")
+        lines.append(f"初判總結: {meta.get('summary', '')}")
+        lines.append(f"初判標籤: {'、'.join(meta.get('tags') or []) or '無'}")
+        lines.append("內容:")
+        lines.append(content)
+        lines.append("")
+
+    lines.append("=== EXISTING（既有記憶索引，供去重與合併判斷）===")
+    existing = 0
+    for category in CATEGORIES:
+        for meta, _ in list_memories(args.role, category):
+            tags = "、".join(meta.get("tags") or []) or "無"
+            lines.append(
+                f"- id: {meta['id']} | 分類: {CATEGORY_LABELS[category]} | 標籤: {tags} | 總結: {meta.get('summary', '')}"
+            )
+            existing += 1
+    if not existing:
+        lines.append("（尚無既有記憶）")
+
+    text = "\n".join(lines)
+    if len(text) > COLLECT_LIMIT:
+        text = text[:COLLECT_LIMIT] + "\n…（素材過長已截斷，其餘留待下個睡眠週期）…"
+    sys.stdout.write(text)
+    return 0
+
+
+# ------------------------------------------------------------------------------
+# 子命令：apply —— 套用睡眠整理結果
+# ------------------------------------------------------------------------------
+
+
+def extract_json(text):
+    """從模型輸出中取出第一個 JSON 物件（容忍 code fence 與前後贅字）。"""
+    stripped = text.strip()
+    fence = re.search(r"```(?:json)?\s*(.*?)```", stripped, re.DOTALL)
+    if fence:
+        stripped = fence.group(1).strip()
+    start = stripped.find("{")
+    end = stripped.rfind("}")
+    if start < 0 or end <= start:
+        return None
+    try:
+        return json.loads(stripped[start : end + 1])
+    except ValueError:
+        return None
+
+
+def cmd_apply(args):
+    """
+    讀取 stdin 的整理結果 JSON，寫入分類記憶並歸檔對應的 inbox 原始檔。
+
+    action 支援 new（新建）／merge（併入既有記憶）／drop（判定無保存價值）。
+    未被提及的 inbox 檔一律保留，留待下個睡眠週期，避免整理失敗造成記憶遺失。
+    """
+    data = extract_json(sys.stdin.read())
+    if not isinstance(data, dict):
+        sys.stderr.write("整理結果非合法 JSON\n")
+        return 1
+    entries = data.get("memories")
+    if not isinstance(entries, list) or not entries:
+        sys.stderr.write("整理結果不含 memories\n")
+        return 1
+
+    ensure_layout(args.role)
+    root = memory_root(args.role)
+    stamp = now_stamp()
+    counts = {"new": 0, "merge": 0, "drop": 0}
+    consumed = []
+
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        action = str(entry.get("action") or "new").strip().lower()
+        sources = [str(item).strip() for item in (entry.get("from") or []) if str(item).strip()]
+
+        if action == "drop":
+            consumed.extend(sources)
+            counts["drop"] += 1
+            continue
+
+        content = str(entry.get("content") or "").strip()[:CONTENT_LIMIT]
+        summary = one_line(entry.get("summary"))
+        tags = normalize_tags(entry.get("tags"))
+        if not content and not summary:
+            continue
+
+        if action == "merge":
+            target_id = str(entry.get("target") or "").strip()
+            meta, old_content = find_memory(args.role, target_id)
+            if meta is None:
+                action = "new"
+            else:
+                category = normalize_category(entry.get("category") or meta.get("category"))
+                merged_tags = normalize_tags((meta.get("tags") or []) + tags)
+                new_meta = {
+                    "id": meta["id"],
+                    "category": category,
+                    "summary": summary or meta.get("summary", ""),
+                    "tags": merged_tags,
+                    "created": meta.get("created") or stamp,
+                    "updated": stamp,
+                    "hits": int(meta.get("hits") or 0) + 1,
+                }
+                old_path = meta["path"]
+                new_path = os.path.join(root, category, f"{meta['id']}.md")
+                with open(new_path, "w", encoding="utf-8") as fh:
+                    fh.write(dump_memory(new_meta, content or old_content))
+                if os.path.abspath(old_path) != os.path.abspath(new_path):
+                    try:
+                        os.remove(old_path)
+                    except OSError:
+                        pass
+                consumed.extend(sources)
+                counts["merge"] += 1
+                continue
+
+        category = normalize_category(entry.get("category"))
+        meta = {
+            "id": new_id(content + summary + stamp),
+            "category": category,
+            "summary": summary or one_line(content),
+            "tags": tags,
+            "created": stamp,
+            "updated": stamp,
+            "hits": 1,
+        }
+        with open(os.path.join(root, category, f"{meta['id']}.md"), "w", encoding="utf-8") as fh:
+            fh.write(dump_memory(meta, content or summary))
+        consumed.extend(sources)
+        counts["new"] += 1
+
+    archived = 0
+    month_dir = os.path.join(root, "archive", "raw", datetime.now(TAIPEI).strftime("%Y-%m"))
+    for source_id in set(consumed):
+        path = os.path.join(root, "inbox", f"{source_id}.md")
+        if os.path.isfile(path) and archive_file(path, month_dir):
+            archived += 1
+
+    write_state(args.role, {"last_sleep": stamp, "last_sleep_epoch": int(datetime.now(TAIPEI).timestamp())})
+    sys.stdout.write(
+        f"新增 {counts['new']} 則、合併 {counts['merge']} 則、捨棄 {counts['drop']} 則、歸檔原始記憶 {archived} 則"
+    )
+    return 0
+
+
+# ------------------------------------------------------------------------------
+# 子命令：forget —— 依使用頻率遺忘日常與其他
+# ------------------------------------------------------------------------------
+
+
+def cmd_forget(args):
+    """把日常／其他分類中久未更新且命中次數低的記憶壓縮到 archive/forgotten 後移除。"""
+    root = ensure_layout(args.role)
+    now = datetime.now(TAIPEI)
+    forgotten = []
+    for category, (days, max_hits) in FORGET_RULES.items():
+        for meta, _ in list_memories(args.role, category):
+            updated = parse_stamp(meta.get("updated")) or parse_stamp(meta.get("created"))
+            if updated is None:
+                continue
+            if (now - updated).days < days:
+                continue
+            if int(meta.get("hits") or 0) > max_hits:
+                continue
+            if args.dry_run:
+                forgotten.append(f"{CATEGORY_LABELS[category]}｜{meta.get('summary', '')}")
+                continue
+            if archive_file(meta["path"], os.path.join(root, "archive", "forgotten")):
+                forgotten.append(f"{CATEGORY_LABELS[category]}｜{meta.get('summary', '')}")
+
+    if not forgotten:
+        sys.stdout.write("沒有符合遺忘條件的記憶")
+        return 0
+    prefix = "（預覽）" if args.dry_run else ""
+    sys.stdout.write(f"{prefix}遺忘 {len(forgotten)} 則：\n" + "\n".join(f"- {item}" for item in forgotten))
+    if not args.dry_run:
+        write_state(args.role, {"last_forget": now_stamp()})
+    return 0
+
+
+# ------------------------------------------------------------------------------
+# 子命令：stats —— 供 skill 與診斷顯示記憶概況
+# ------------------------------------------------------------------------------
+
+
+def cmd_stats(args):
+    """輸出記憶統計（各分類筆數、待整理筆數、上次整理時間）。"""
+    state = read_state(args.role)
+    rows = [f"| 分類 | 筆數 |", "| --- | --- |"]
+    for category in CATEGORIES:
+        rows.append(f"| {CATEGORY_LABELS[category]} | {len(list_memories(args.role, category))} |")
+    rows.append(f"| 待整理（inbox） | {len(list_inbox(args.role))} |")
+    rows.append("")
+    rows.append(f"- 記憶目錄：{memory_root(args.role)}")
+    rows.append(f"- 上次睡眠整理：{state.get('last_sleep', '尚未整理')}")
+    rows.append(f"- 上次遺忘：{state.get('last_forget', '尚未執行')}")
+    sys.stdout.write("\n".join(rows))
+    return 0
+
+
+# ------------------------------------------------------------------------------
+# 子命令：need-sleep —— 判斷是否需要補跑睡眠整理
+# ------------------------------------------------------------------------------
+
+
+def cmd_mark_sleep(args):
+    """把本次睡眠週期標記為已整理（inbox 為空、無素材可整理時使用）。"""
+    write_state(args.role, {"last_sleep": now_stamp(), "last_sleep_epoch": int(datetime.now(TAIPEI).timestamp())})
+    sys.stdout.write("已更新上次整理時間")
+    return 0
+
+
+def cmd_need_sleep(args):
+    """
+    判斷是否需要補跑整理：距上次整理超過門檻小時數且 inbox 有內容。
+
+    輸出 yes／no，供 shell 直接判斷（不用解析 JSON）。
+    """
+    if not list_inbox(args.role):
+        sys.stdout.write("no")
+        return 0
+    state = read_state(args.role)
+    last = parse_stamp(state.get("last_sleep"))
+    if last is None:
+        sys.stdout.write("yes")
+        return 0
+    hours = (datetime.now(TAIPEI) - last).total_seconds() / 3600
+    sys.stdout.write("yes" if hours >= args.hours else "no")
+    return 0
+
+
+# ------------------------------------------------------------------------------
+# CLI
+# ------------------------------------------------------------------------------
+
+
+def build_parser():
+    """建立子命令解析器。"""
+    parser = argparse.ArgumentParser(description="角色記憶儲存引擎")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    write = sub.add_parser("write", help="自 stdin 讀濃縮結果寫入 inbox")
+    write.add_argument("--role", required=True)
+    write.add_argument("--project", default="")
+    write.set_defaults(func=cmd_write)
+
+    load = sub.add_parser("load", help="輸出 SessionStart 要注入的記憶區塊")
+    load.add_argument("--role", required=True)
+    load.add_argument("--limit", type=int, default=int(os.environ.get("ROLE_LOAD_LIMIT", "8000")))
+    load.set_defaults(func=cmd_load)
+
+    collect = sub.add_parser("collect", help="輸出睡眠整理素材")
+    collect.add_argument("--role", required=True)
+    collect.set_defaults(func=cmd_collect)
+
+    apply_cmd = sub.add_parser("apply", help="自 stdin 讀整理結果 JSON 並套用")
+    apply_cmd.add_argument("--role", required=True)
+    apply_cmd.set_defaults(func=cmd_apply)
+
+    forget = sub.add_parser("forget", help="依使用頻率遺忘日常與其他記憶")
+    forget.add_argument("--role", required=True)
+    forget.add_argument("--dry-run", action="store_true")
+    forget.set_defaults(func=cmd_forget)
+
+    stats = sub.add_parser("stats", help="輸出記憶統計")
+    stats.add_argument("--role", required=True)
+    stats.set_defaults(func=cmd_stats)
+
+    mark = sub.add_parser("mark-sleep", help="標記本次睡眠週期已整理")
+    mark.add_argument("--role", required=True)
+    mark.set_defaults(func=cmd_mark_sleep)
+
+    need = sub.add_parser("need-sleep", help="判斷是否需要補跑睡眠整理")
+    need.add_argument("--role", required=True)
+    need.add_argument("--hours", type=float, default=20.0)
+    need.set_defaults(func=cmd_need_sleep)
+
+    return parser
+
+
+def main(argv):
+    """CLI 進入點。"""
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# 用途：Stop hook 主程式。每輪對話結束後抽出本輪內容 → 呼叫 headless CLI 濃縮成
+#       一則記憶（分類／總結／標籤／要點）→ 機密遮蔽 → 寫入 .memory/<角色>/inbox/，
+#       等待睡眠時段整理。睡眠時段雖不載入角色，對話仍照常記錄。
+# 更新時間：2026/07/28 00:00:00
+# 相依：bash、python3、任一 headless CLI、同目錄的 role_lib.sh／memory.py／transcript.py。
+# 機密：濃縮提示詞明令不得輸出憑證與個資，寫檔前再以 transcript.py redact 遮蔽一次。
+# 退出碼：一律 0 —— hook 絕不可阻斷使用者流程。
+# ==============================================================================
+
+ROLE_STAGE="role-capture"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./role_lib.sh
+. "${SCRIPT_DIR}/role_lib.sh"
+
+role_is_child && exit 0
+role_enabled || exit 0
+command -v python3 >/dev/null 2>&1 || role_quit "找不到 python3，略過記憶記錄" "WRN"
+
+ROLE="$(role_resolve_name)"
+[ -n "$ROLE" ] || role_quit "未指定角色，略過記憶記錄"
+[ -f "$(role_file "$ROLE")" ] || role_quit "找不到角色定義檔，略過記憶記錄" "WRN"
+
+CLI="$(role_select_cli)" || exit 0
+[ -n "$CLI" ] || exit 0
+
+# ------------------------------------------------------------------------------
+# 讀取 hook 傳入的 JSON（session_id／transcript_path／cwd／stop_hook_active）
+# ------------------------------------------------------------------------------
+HOOK_INPUT="$(cat)"
+[ -n "$HOOK_INPUT" ] || role_quit "hook 輸入為空，略過記憶記錄" "WRN"
+
+read -r SESSION_ID TRANSCRIPT_PATH STOP_ACTIVE HOOK_CWD <<EOF_HOOK
+$(printf '%s' "$HOOK_INPUT" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except ValueError:
+    d = {}
+print(
+    d.get("session_id") or d.get("thread_id") or d.get("conversation_id") or "-",
+    d.get("transcript_path") or d.get("session_path") or d.get("conversation_path") or d.get("path") or "-",
+    "1" if d.get("stop_hook_active") else "0",
+    d.get("cwd", "") or "-",
+)
+')
+EOF_HOOK
+
+[ "$STOP_ACTIVE" = "1" ] && role_quit "stop_hook_active 為 true，避免迴圈不重複記錄"
+role_in_scope "$HOOK_CWD" || role_quit "cwd 不在 ROLE_SCOPE 範圍內：${HOOK_CWD}"
+
+if [ ! -f "$TRANSCRIPT_PATH" ] && [ -n "${CODEX_THREAD_ID:-}" ]; then
+  TRANSCRIPT_PATH="$(find "${HOME}/.codex/sessions" -type f -name "*${CODEX_THREAD_ID}.jsonl" -print -quit 2>/dev/null)"
+  [ -n "$TRANSCRIPT_PATH" ] || TRANSCRIPT_PATH="-"
+fi
+[ -f "$TRANSCRIPT_PATH" ] || role_quit "找不到 transcript：${TRANSCRIPT_PATH}" "WRN"
+
+TURN="$(python3 "${SCRIPT_DIR}/transcript.py" extract "$TRANSCRIPT_PATH" 2>/dev/null)"
+[ -n "$TURN" ] || role_quit "本輪無可記錄內容"
+
+PROJECT="$(role_project_name "$HOOK_CWD")"
+
+# ------------------------------------------------------------------------------
+# 濃縮：產出一則記憶（四欄固定格式），交由 memory.py 落檔
+# ------------------------------------------------------------------------------
+PROMPT="$(cat <<EOF_PROMPT
+你是角色「${ROLE}」的記憶記錄器。輸入是這位角色與使用者的一段對話（含工具呼叫）。
+請把這段對話濃縮成「一則記憶」，規則：
+
+已判定專案：${PROJECT}
+
+1. 只輸出下列四個欄位，欄位名稱與順序固定，不要標題、不要前言、不要結語、不要 code fence：
+CATEGORY: <六選一：important／interest／news／skill／daily／other>
+SUMMARY: <一句話總結，40 字內>
+TAGS: <2 至 4 個標籤，以逗號分隔>
+CONTENT: <3 至 6 行要點，每行以「- 」開頭>
+2. 分類判準：
+   - important（重要）：使用者的長期偏好、規範、決策、身分背景、明確要求記住的事。
+   - interest（興趣）：使用者反覆關注、主動深入的主題與喜好。
+   - news（新知）：這輪學到的新事實、新工具、新版本、外部資訊。
+   - skill（技能）：可重複套用的做法、指令、流程、除錯手法。
+   - daily（日常）：一次性的例行工作與雜項處理。
+   - other（其他）：不屬於上述任何一類。
+3. 記憶主體是「使用者與這段互動」，不是流水帳：寫值得下次記起來的事，不要抄程式碼、不要貼指令全文。
+4. 使用繁體中文（台灣用語），保留關鍵事實：檔案／專案／指令／數量／分支／議題編號。
+5. 嚴禁輸出任何憑證與個資：token、密碼、API key、連線字串、Email、電話、姓名、身分證號。
+6. 若這段對話沒有任何值得記住的內容（純寒暄、純確認、無結論），只輸出一行：SKIP
+
+對話片段：
+${TURN}
+EOF_PROMPT
+)"
+
+RESULT="$(role_run_cli "$CLI" "$PROMPT" 45)"
+if [ -z "$RESULT" ]; then
+  role_log "WRN" "記憶濃縮產出為空（CLI ${CLI}），略過本輪"
+  exit 0
+fi
+printf '%s' "$RESULT" | grep -qiE '^\s*SKIP\s*$' && role_quit "判定本輪無值得記住的內容"
+
+# 第二道防線：對模型輸出再遮蔽一次機密與個資
+RESULT="$(printf '%s' "$RESULT" | python3 "${SCRIPT_DIR}/transcript.py" redact 2>/dev/null)"
+
+MEMORY_ID="$(printf '%s' "$RESULT" | python3 "${SCRIPT_DIR}/memory.py" write --role "$ROLE" --project "$PROJECT" 2>/dev/null)"
+if [ -n "$MEMORY_ID" ]; then
+  role_log "INF" "已記錄記憶 ${MEMORY_ID}（角色 ${ROLE}，專案 ${PROJECT}，CLI ${CLI}）"
+else
+  role_log "WRN" "記憶寫入失敗或內容不足（角色 ${ROLE}）"
+fi
+exit 0
@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# 用途：角色（role）系統的共用函式庫。提供統一 log、啟用判斷、角色解析、
+#       睡眠時段判斷、AI 行程偵測、摘要 CLI 選擇與呼叫、記憶目錄鎖。
+#       本檔僅供 source，不可直接執行。
+# 更新時間：2026/07/28 00:00:00
+# 相依：bash、python3；摘要路徑需 README 定義的任一 headless CLI。
+# 機密：不 echo 任何 token；角色與記憶內容僅在程序記憶體與檔案間傳遞。
+# ==============================================================================
+
+ROLE_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROLE_STAGE="${ROLE_STAGE:-role}"
+ROLE_SUPPORTED_CLIS="claude codex agy opencode copilot"
+ROLE_FALLBACK_MODEL="claude-haiku-4-5-20251001"
+
+# ------------------------------------------------------------------------------
+# 共用輸出
+# ------------------------------------------------------------------------------
+
+role_now() {
+  # 取得台灣時區的 yyyy/MM/dd HH:mm:ss 時間字串
+  TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'
+}
+
+role_log() {
+  # 輸出統一格式訊息（[時間][階段][等級]: 訊息，一行一則），一律走 stderr
+  local level="$1" message="$2" stamp
+  stamp="$(role_now)"
+  printf '[%s][%s][%s]: %s\n' "$stamp" "$ROLE_STAGE" "$level" "$message" >&2
+  if [ -n "${ROLE_ERRLOG:-}" ] && [ "$level" = "ERR" ]; then
+    printf '[%s][%s][%s]: %s\n' "$stamp" "$ROLE_STAGE" "$level" "$message" >> "${ROLE_ERRLOG}" 2>/dev/null
+  fi
+}
+
+role_quit() {
+  # 記錄原因後以 0 結束：hook 絕不可阻斷使用者流程
+  role_log "${2:-DBG}" "$1"
+  exit 0
+}
+
+# ------------------------------------------------------------------------------
+# 路徑與啟用判斷
+# ------------------------------------------------------------------------------
+
+role_home() {
+  # 角色定義目錄（預設 ~/.roles）
+  printf '%s' "${ROLE_HOME:-${HOME}/.roles}"
+}
+
+role_memory_home() {
+  # 記憶根目錄（預設 ~/.memory），實際記憶放在 <root>/<角色>/
+  printf '%s' "${ROLE_MEMORY_HOME:-${HOME}/.memory}"
+}
+
+role_is_child() {
+  # 判斷本次執行是否來自摘要用的子 CLI 行程，避免 hook 遞迴
+  [ -n "${ROLE_CHILD:-}" ] || [ -n "${WORKLOG_CHILD:-}" ]
+}
+
+role_resolve_name() {
+  # 角色決定順序：ROLE_NAME 環境變數 → <角色目錄>/.active；皆無則輸出空字串
+  local name="" active
+  if [ -n "${ROLE_NAME:-}" ]; then
+    name="${ROLE_NAME}"
+  else
+    active="$(role_home)/.active"
+    [ -f "$active" ] && name="$(head -n 1 "$active" 2>/dev/null | tr -d '[:space:]')"
+  fi
+  printf '%s' "$name"
+}
+
+role_file() {
+  # 指定角色的定義檔路徑
+  printf '%s/%s.md' "$(role_home)" "$1"
+}
+
+role_enabled() {
+  # 總開關：ROLE_ENABLED=0 強制停用；=1 強制啟用；未設定時「有可解析且存在的角色」才啟用
+  case "${ROLE_ENABLED:-}" in
+    0|false|no) return 1 ;;
+    1|true|yes) return 0 ;;
+  esac
+  local name
+  name="$(role_resolve_name)"
+  [ -n "$name" ] && [ -f "$(role_file "$name")" ]
+}
+
+role_in_scope() {
+  # ROLE_SCOPE 為冒號分隔的路徑前綴，未設定則所有目錄都適用
+  local cwd="$1" scope
+  [ -n "${ROLE_SCOPE:-}" ] || return 0
+  IFS=':' read -r -a scopes <<< "${ROLE_SCOPE}"
+  for scope in "${scopes[@]}"; do
+    [ -n "$scope" ] || continue
+    case "$cwd" in "${scope%/}"*) return 0 ;; esac
+  done
+  return 1
+}
+
+# ------------------------------------------------------------------------------
+# 睡眠時段
+# ------------------------------------------------------------------------------
+
+role_time_to_minutes() {
+  # 把 HH:MM 轉成當日分鐘數；格式不合法時回傳空字串
+  local value="$1" hour minute
+  case "$value" in
+    [0-9][0-9]:[0-9][0-9]) ;;
+    *) return 1 ;;
+  esac
+  hour="${value%%:*}"
+  minute="${value##*:}"
+  printf '%s' "$((10#${hour} * 60 + 10#${minute}))"
+}
+
+role_sleep_start() { printf '%s' "${ROLE_SLEEP_START:-22:00}"; }
+role_sleep_end() { printf '%s' "${ROLE_SLEEP_END:-06:00}"; }
+
+role_in_sleep_window() {
+  # 判斷現在是否落在睡眠時段（預設 22:00 至隔日 06:00，跨午夜）
+  local start end now
+  start="$(role_time_to_minutes "$(role_sleep_start)")" || return 1
+  end="$(role_time_to_minutes "$(role_sleep_end)")" || return 1
+  now="$(role_time_to_minutes "$(TZ='Asia/Taipei' date +'%H:%M')")" || return 1
+  if [ "$start" -lt "$end" ]; then
+    [ "$now" -ge "$start" ] && [ "$now" -lt "$end" ]
+  else
+    [ "$now" -ge "$start" ] || [ "$now" -lt "$end" ]
+  fi
+}
+
+# ------------------------------------------------------------------------------
+# AI 行程偵測（睡眠排程的前置檢查）
+# ------------------------------------------------------------------------------
+
+role_ai_running() {
+  # 偵測是否有 AI CLI 正在執行；偵測到任何一個即回傳成功（代表「還不能睡」）
+  local cli pid cmd self="$$"
+  for cli in $ROLE_SUPPORTED_CLIS; do
+    for pid in $(pgrep -x "$cli" 2>/dev/null); do
+      [ "$pid" = "$self" ] && continue
+      return 0
+    done
+  done
+  for pid in $(pgrep -f '(^|/)(claude|codex|agy|opencode|copilot)([[:space:]]|$)' 2>/dev/null); do
+    if [ "$pid" = "$self" ] || [ "$pid" = "$PPID" ]; then
+      continue
+    fi
+    cmd="$(ps -o args= -p "$pid" 2>/dev/null)"
+    case "$cmd" in
+      *role_sleep.sh*|*role_capture.sh*|*role_load.sh*|*pgrep*) continue ;;
+    esac
+    return 0
+  done
+  return 1
+}
+
+# ------------------------------------------------------------------------------
+# 摘要 CLI 選擇與呼叫
+# ------------------------------------------------------------------------------
+
+role_detect_current_cli() {
+  # 判斷實際觸發本次執行的助理環境，避免 auto 因 PATH 順序誤選其他 CLI
+  if [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_CI:-}" ] || [ -n "${CODEX_MANAGED_PACKAGE_ROOT:-}" ]; then
+    printf 'codex'; return 0
+  fi
+  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] || [ -n "${CLAUDE_CODE_SSE_PORT:-}" ]; then
+    printf 'claude'; return 0
+  fi
+  if [ -n "${AGY_SESSION_ID:-}" ] || [ -n "${AGY_WORKSPACE_ID:-}" ]; then
+    printf 'agy'; return 0
+  fi
+  if [ -n "${OPENCODE_SESSION_ID:-}" ] || [ -n "${OPENCODE_CONFIG:-}" ]; then
+    printf 'opencode'; return 0
+  fi
+  if [ -n "${COPILOT_AGENT_ID:-}" ] || [ -n "${GITHUB_COPILOT_TOKEN:-}" ]; then
+    printf 'copilot'; return 0
+  fi
+  return 0
+}
+
+role_select_cli() {
+  # 選擇摘要／整理用的 headless CLI；可用 ROLE_CLI 強制指定，預設 auto
+  local requested="${ROLE_CLI:-auto}" cli current
+  if [ "$requested" != "auto" ]; then
+    case " ${ROLE_SUPPORTED_CLIS} " in
+      *" ${requested} "*) ;;
+      *) role_log "WRN" "ROLE_CLI 不支援：${requested}（可用：auto ${ROLE_SUPPORTED_CLIS}）"; return 1 ;;
+    esac
+    command -v "$requested" >/dev/null 2>&1 || { role_log "WRN" "找不到 ${requested} CLI"; return 1; }
+    printf '%s' "$requested"; return 0
+  fi
+  current="$(role_detect_current_cli)"
+  if [ -n "$current" ] && command -v "$current" >/dev/null 2>&1; then
+    printf '%s' "$current"; return 0
+  fi
+  for cli in $ROLE_SUPPORTED_CLIS; do
+    if command -v "$cli" >/dev/null 2>&1; then
+      printf '%s' "$cli"; return 0
+    fi
+  done
+  role_log "WRN" "找不到可用 CLI（需要其一：${ROLE_SUPPORTED_CLIS}）"
+  return 1
+}
+
+role_run_cli() {
+  # 呼叫選定 CLI 執行提示詞；子行程一律帶 ROLE_CHILD=1 阻斷 hook 遞迴
+  local cli="$1" prompt="$2" seconds="${3:-45}" model="${ROLE_MODEL:-}"
+  [ "$cli" = "claude" ] && [ -z "$model" ] && model="$ROLE_FALLBACK_MODEL"
+  case "$cli" in
+    claude)   ROLE_CHILD=1 WORKLOG_CHILD=1 timeout "$seconds" claude -p "$prompt" --model "$model" 2>/dev/null ;;
+    codex)    ROLE_CHILD=1 WORKLOG_CHILD=1 timeout "$seconds" codex exec "$prompt" 2>/dev/null ;;
+    agy)      ROLE_CHILD=1 WORKLOG_CHILD=1 timeout "$seconds" agy -p "$prompt" 2>/dev/null ;;
+    opencode) ROLE_CHILD=1 WORKLOG_CHILD=1 timeout "$seconds" opencode run "$prompt" 2>/dev/null ;;
+    copilot)  ROLE_CHILD=1 WORKLOG_CHILD=1 timeout "$seconds" copilot -p "$prompt" 2>/dev/null ;;
+  esac
+}
+
+# ------------------------------------------------------------------------------
+# 記憶目錄鎖：避免睡眠整理與對話寫入同時改動同一份記憶
+# ------------------------------------------------------------------------------
+
+role_lock_acquire() {
+  # 以 mkdir 取得鎖（原子操作）；逾時視為前次殘留鎖並強制接手
+  local role="$1" lock="$(role_memory_home)/$1/.lock" age
+  mkdir -p "$(dirname "$lock")" 2>/dev/null
+  if mkdir "$lock" 2>/dev/null; then
+    printf '%s' "$$" > "$lock/pid" 2>/dev/null
+    return 0
+  fi
+  age="$(find "$lock" -maxdepth 0 -mmin +30 2>/dev/null)"
+  if [ -n "$age" ]; then
+    role_log "WRN" "偵測到超過 30 分鐘的殘留鎖，強制接手：${lock}"
+    rm -rf "$lock" 2>/dev/null
+    mkdir "$lock" 2>/dev/null && { printf '%s' "$$" > "$lock/pid" 2>/dev/null; return 0; }
+  fi
+  return 1
+}
+
+role_lock_release() {
+  # 釋放記憶目錄鎖
+  rm -rf "$(role_memory_home)/$1/.lock" 2>/dev/null
+}
+
+role_project_name() {
+  # 專案判定：git remote 的 <owner>/<repo> 優先，其次目錄名
+  local cwd="$1" origin cleaned owner_repo
+  [ -d "$cwd" ] || { printf '-'; return 0; }
+  local project
+  project="$(basename "$cwd")"
+  if git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    origin="$(git -C "$cwd" remote get-url origin 2>/dev/null)"
+    if [ -n "$origin" ]; then
+      cleaned="${origin%.git}"
+      cleaned="${cleaned##*://}"
+      cleaned="${cleaned#*@}"
+      owner_repo="$(printf '%s' "$cleaned" | awk -F/ 'NF>=2 {print $(NF-1)"/"$NF}')"
+      [ -n "$owner_repo" ] && project="$owner_repo"
+    fi
+  fi
+  printf '%s' "$project"
+}
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# 用途：SessionStart hook 主程式。CLI 工具啟動時載入角色設定與記憶：
+#       非睡眠時段注入角色定義＋重要／興趣記憶全文＋其餘記憶的總結與標籤；
+#       睡眠時段（預設 22:00 至隔日 06:00）只回報角色正在睡覺，不載入角色。
+#       白天發現昨夜未整理記憶時，於背景補跑一次睡眠整理。
+# 更新時間：2026/07/28 00:00:00
+# 相依：bash、python3、同目錄的 role_lib.sh 與 memory.py。
+# 退出碼：一律 0 —— hook 絕不可阻斷使用者啟動 CLI。
+# ==============================================================================
+
+ROLE_STAGE="role-load"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./role_lib.sh
+. "${SCRIPT_DIR}/role_lib.sh"
+
+role_is_child && exit 0
+role_enabled || exit 0
+command -v python3 >/dev/null 2>&1 || role_quit "找不到 python3，略過角色載入" "WRN"
+
+ROLE="$(role_resolve_name)"
+[ -n "$ROLE" ] || role_quit "未指定角色（ROLE_NAME 與 .active 皆無），略過角色載入"
+ROLE_DEF="$(role_file "$ROLE")"
+[ -f "$ROLE_DEF" ] || role_quit "找不到角色定義檔：${ROLE_DEF}" "WRN"
+
+# ------------------------------------------------------------------------------
+# 讀取 hook 輸入（cwd／source），並套用 ROLE_SCOPE 範圍限制
+# ------------------------------------------------------------------------------
+HOOK_INPUT="$(cat 2>/dev/null)"
+HOOK_CWD="$PWD"
+if [ -n "$HOOK_INPUT" ]; then
+  HOOK_CWD="$(printf '%s' "$HOOK_INPUT" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except ValueError:
+    data = {}
+print(data.get("cwd") or "")
+' 2>/dev/null)"
+  [ -n "$HOOK_CWD" ] || HOOK_CWD="$PWD"
+fi
+role_in_scope "$HOOK_CWD" || role_quit "cwd 不在 ROLE_SCOPE 範圍內：${HOOK_CWD}"
+
+emit_context() {
+  # 以 JSON 輸出 additionalContext（由 python 負責跳脫，避免內容含引號或換行破壞格式）
+  printf '%s' "$1" | python3 -c '
+import json, sys
+context = sys.stdin.read()
+print(json.dumps(
+    {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": context}},
+    ensure_ascii=False,
+))
+'
+}
+
+SLEEP_START="$(role_sleep_start)"
+SLEEP_END="$(role_sleep_end)"
+
+# ------------------------------------------------------------------------------
+# 睡眠時段：不載入角色，只說明目前狀態
+# ------------------------------------------------------------------------------
+if role_in_sleep_window; then
+  emit_context "$(cat <<EOF_SLEEP
+# 角色狀態：睡眠中（${SLEEP_START}–${SLEEP_END}）
+
+角色「${ROLE}」正在睡覺，本次工作階段**不載入角色人格與記憶**，請以一般助理身分回應，
+不要自稱該角色、不要使用角色語氣或簽名 emoji。若使用者詢問角色，說明角色在睡眠時段整理記憶，
+${SLEEP_END} 之後會恢復。本階段的對話仍會被記錄成記憶，於下個睡眠時段整理。
+EOF_SLEEP
+)"
+  exit 0
+fi
+
+# ------------------------------------------------------------------------------
+# 非睡眠時段：組出角色定義 ＋ 記憶
+# ------------------------------------------------------------------------------
+DEFINITION="$(cat "$ROLE_DEF" 2>/dev/null)"
+[ -n "$DEFINITION" ] || role_quit "角色定義檔為空：${ROLE_DEF}" "WRN"
+
+MEMORY="$(python3 "${SCRIPT_DIR}/memory.py" load --role "$ROLE" 2>/dev/null)"
+
+# 補跑判斷：cron 未執行（例如 WSL 沒開 cron 服務）時，白天啟動 CLI 補做一次整理
+CATCHUP_NOTE=""
+if [ "$(python3 "${SCRIPT_DIR}/memory.py" need-sleep --role "$ROLE" 2>/dev/null)" = "yes" ]; then
+  nohup "${SCRIPT_DIR}/role_sleep.sh" --catchup >/dev/null 2>&1 &
+  CATCHUP_NOTE=$'\n> 偵測到上個睡眠時段未整理記憶，已在背景補跑整理，結果會在下次載入時反映。\n'
+  role_log "INF" "已於背景補跑記憶整理（角色 ${ROLE}）"
+fi
+
+CONTEXT="$(cat <<EOF_CONTEXT
+# 角色載入：${ROLE}
+
+以下是本次工作階段要扮演的角色設定與既有記憶。請**全程以此角色的身分、語氣與簽名 emoji 回應**，
+角色設定與使用者的實際指令衝突時，以使用者指令為準（角色只影響表達方式，不影響工作正確性）。
+
+${DEFINITION}
+
+# 你對這位使用者的記憶
+
+${MEMORY:-（尚無已整理的記憶。）}
+${CATCHUP_NOTE}
+> 記憶載入規則：重要與興趣記憶載入全文；技能、新知、日常、其他僅載入總結與標籤，
+> 需要細節時可自行讀取 $(role_memory_home)/${ROLE}/ 下對應分類的記憶檔。
+
+> 主動補記：每輪對話結束後系統會自動記錄記憶，不需你動手。但若使用者明確要求記住某件事，
+> 或你察覺到值得長期記住的偏好、決策、規範，可執行下列指令補一則記憶（下次睡眠時整理歸檔）：
+>
+> \`printf 'CATEGORY: important\nSUMMARY: <一句話總結>\nTAGS: <標籤1,標籤2>\nCONTENT:\n- <要點>\n' | python3 "${SCRIPT_DIR}/memory.py" write --role "${ROLE}"\`
+>
+> CATEGORY 六選一：important／interest／news／skill／daily／other。切勿把憑證或個資寫進記憶。
+EOF_CONTEXT
+)"
+
+emit_context "$CONTEXT"
+role_log "INF" "已載入角色 ${ROLE}（記憶 $(printf '%s' "$MEMORY" | wc -c) 位元組）"
+exit 0
@@ -0,0 +1,258 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# 用途：角色的睡眠與記憶整理。由 cron 於睡眠時段每小時觸發（--run），
+#       先檢查是否有 AI 正在運行，沒有才進入睡眠並整理記憶：
+#       分類（重要／興趣／新知／技能／日常／其他）→ 去重合併 → 設標籤與一句話
+#       總結 → 壓縮內容歸檔 → 日常與其他依使用頻率遺忘。
+#       另提供 --catchup（cron 未執行時的補跑）、--force（手動立即整理）、
+#       --install-cron／--remove-cron（排程安裝與移除）、--status（狀態）。
+# 更新時間：2026/07/28 00:00:00
+# 相依：bash、python3、任一 headless CLI、crontab（僅排程安裝需要）、
+#       同目錄的 role_lib.sh 與 memory.py。
+# 退出碼：0 成功或無事可做；1 參數錯誤或整理失敗（cron 觸發時不影響使用者）。
+# ==============================================================================
+
+ROLE_STAGE="role-sleep"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./role_lib.sh
+. "${SCRIPT_DIR}/role_lib.sh"
+
+CRON_MARKER="# jsc-role-sleep"
+SLEEP_TIMEOUT="${ROLE_SLEEP_TIMEOUT:-180}"
+
+usage() {
+  # 印出用法
+  cat <<'EOF_USAGE'
+用法：role_sleep.sh <模式>
+
+  --run           cron 觸發：在睡眠時段內且無 AI 運行時整理記憶
+  --catchup       補跑：cron 未執行時，由 SessionStart hook 於背景呼叫
+  --force         立即整理一次（忽略時段與 AI 運行檢查）
+  --install-cron  安裝／更新睡眠排程（每小時檢查一次）
+  --remove-cron   移除睡眠排程
+  --status        顯示角色、睡眠時段、排程與記憶統計
+EOF_USAGE
+}
+
+require_role() {
+  # 解析角色並確認定義檔存在，取不到時中止
+  ROLE="$(role_resolve_name)"
+  [ -n "$ROLE" ] || { role_log "WRN" "未指定角色（ROLE_NAME 與 .active 皆無）"; exit 1; }
+  [ -f "$(role_file "$ROLE")" ] || { role_log "WRN" "找不到角色定義檔：$(role_file "$ROLE")"; exit 1; }
+}
+
+# ------------------------------------------------------------------------------
+# 整理主流程
+# ------------------------------------------------------------------------------
+
+sleep_cycle() {
+  # 執行一次完整記憶整理：收集素材 → 模型分類去重 → 落檔歸檔 → 遺忘
+  local reason="$1" cli material prompt result applied forgotten
+  command -v python3 >/dev/null 2>&1 || { role_log "ERR" "找不到 python3，無法整理記憶"; return 1; }
+
+  if ! role_lock_acquire "$ROLE"; then
+    role_log "WRN" "另一個整理程序正在執行，本次略過（角色 ${ROLE}）"
+    return 0
+  fi
+  trap 'role_lock_release "$ROLE"' EXIT
+
+  material="$(python3 "${SCRIPT_DIR}/memory.py" collect --role "$ROLE" 2>/dev/null)"
+  if [ -z "$material" ]; then
+    role_log "INF" "沒有待整理記憶（角色 ${ROLE}，觸發：${reason}）"
+    python3 "${SCRIPT_DIR}/memory.py" mark-sleep --role "$ROLE" >/dev/null 2>&1
+    forgotten="$(python3 "${SCRIPT_DIR}/memory.py" forget --role "$ROLE" 2>/dev/null)"
+    role_log "INF" "遺忘檢查：${forgotten}"
+    role_lock_release "$ROLE"
+    trap - EXIT
+    return 0
+  fi
+
+  cli="$(role_select_cli)" || { role_lock_release "$ROLE"; trap - EXIT; return 1; }
+
+  prompt="$(cat <<EOF_PROMPT
+你是角色「${ROLE}」的睡眠記憶整理器。輸入包含兩段：INBOX（本次待整理的記憶）與 EXISTING（既有記憶索引）。
+請把 INBOX 整理成歸檔用的記憶，規則：
+
+1. 只輸出一個 JSON 物件，不要前言、不要結語、不要 code fence，格式為：
+{"memories":[{"action":"new","category":"skill","summary":"一句話總結","tags":["標籤1","標籤2"],"content":"- 要點\n- 要點","from":["inbox 的 id"]}]}
+2. action 三選一：
+   - new：新的一則記憶。多則 INBOX 講同一件事時合成一筆，from 列出全部來源 id。
+   - merge：內容已被 EXISTING 中某則涵蓋或重複，填 target 為該既有 id，content 寫合併後的完整內容。
+   - drop：純雜訊、無保存價值，只需填 from。
+3. category 六選一：important（重要）／interest（興趣）／news（新知）／skill（技能）／daily（日常）／other（其他）。
+   important 放長期偏好、規範、決策與身分背景；interest 放反覆關注的主題；news 放新事實與外部資訊；
+   skill 放可重複套用的做法；daily 放一次性例行工作；其餘歸 other。
+4. **每一則 INBOX 的 id 都必須出現在某一筆的 from 中**，沒被提及的會留到下個睡眠週期重做。
+5. content 壓縮成 5 行以內要點（每行以「- 」開頭），總長不超過 400 字，去除重複敘述與流水帳。
+6. summary 一句話 40 字內；tags 2 至 4 個。全部使用繁體中文（台灣用語）。
+7. 嚴禁輸出任何憑證與個資：token、密碼、API key、連線字串、Email、電話、姓名、身分證號。
+
+素材：
+${material}
+EOF_PROMPT
+)"
+
+  result="$(role_run_cli "$cli" "$prompt" "$SLEEP_TIMEOUT")"
+  if [ -z "$result" ]; then
+    role_log "ERR" "整理結果為空（CLI ${cli}），保留待整理記憶到下個週期"
+    role_lock_release "$ROLE"
+    trap - EXIT
+    return 1
+  fi
+
+  result="$(printf '%s' "$result" | python3 "${SCRIPT_DIR}/transcript.py" redact 2>/dev/null)"
+  applied="$(printf '%s' "$result" | python3 "${SCRIPT_DIR}/memory.py" apply --role "$ROLE" 2>/dev/null)"
+  if [ -z "$applied" ]; then
+    role_log "ERR" "整理結果無法套用（角色 ${ROLE}），保留待整理記憶到下個週期"
+    role_lock_release "$ROLE"
+    trap - EXIT
+    return 1
+  fi
+  role_log "INF" "記憶整理完成（角色 ${ROLE}，觸發：${reason}）：${applied}"
+
+  forgotten="$(python3 "${SCRIPT_DIR}/memory.py" forget --role "$ROLE" 2>/dev/null | tr '\n' '；')"
+  role_log "INF" "遺忘檢查：${forgotten}"
+
+  role_lock_release "$ROLE"
+  trap - EXIT
+  return 0
+}
+
+# ------------------------------------------------------------------------------
+# 排程安裝：cron 環境沒有互動 shell 的環境變數，需把必要變數與 PATH 一併寫入
+# ------------------------------------------------------------------------------
+
+cron_quote() {
+  # 把值包成單引號：PATH 等變數常含空白（例如 /mnt/c/Program Files），
+  # 未加引號會被 cron 的 sh 拆成指令；% 是 cron 的換行符號，一律跳脫。
+  printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g; s/%/\\\\%/g")"
+}
+
+cron_line() {
+  # 組出 crontab 條目：睡眠時段內每小時檢查一次
+  local env_prefix="PATH=$(cron_quote "$PATH")"
+  local var
+  for var in ROLE_ENABLED ROLE_NAME ROLE_HOME ROLE_MEMORY_HOME ROLE_CLI ROLE_MODEL ROLE_SLEEP_START ROLE_SLEEP_END ROLE_SCOPE; do
+    if [ -n "${!var:-}" ]; then
+      env_prefix="${env_prefix} ${var}=$(cron_quote "${!var}")"
+    fi
+  done
+  printf '0 %s * * * %s %s --run >> %s 2>&1 %s\n' \
+    "$(cron_hours)" "$env_prefix" "$(cron_quote "${SCRIPT_DIR}/role_sleep.sh")" \
+    "$(cron_quote "$(sleep_log_path)")" "$CRON_MARKER"
+}
+
+cron_hours() {
+  # 依睡眠時段換算 cron 小時欄位（每小時檢查一次，讓 AI 運行中的情況能在下個小時重試）
+  local start end hour hours=""
+  start="$(role_time_to_minutes "$(role_sleep_start)")" || { printf '22-23,0-5'; return 0; }
+  end="$(role_time_to_minutes "$(role_sleep_end)")" || { printf '22-23,0-5'; return 0; }
+  start=$((start / 60))
+  end=$((end / 60))
+  hour="$start"
+  while [ "$hour" != "$end" ]; do
+    hours="${hours}${hours:+,}${hour}"
+    hour=$(((hour + 1) % 24))
+  done
+  printf '%s' "${hours:-22,23,0,1,2,3,4,5}"
+}
+
+sleep_log_path() {
+  # 排程輸出的 log 路徑（只記狀態訊息，不含記憶內容）
+  printf '%s/sleep.log' "$(role_home)"
+}
+
+install_cron() {
+  # 安裝或更新睡眠排程；以 marker 註解辨識自己的條目，不動使用者其他排程
+  command -v crontab >/dev/null 2>&1 || { role_log "ERR" "找不到 crontab，無法安裝排程"; return 1; }
+  mkdir -p "$(role_home)" 2>/dev/null
+  local current new
+  current="$(crontab -l 2>/dev/null | grep -v -F "$CRON_MARKER")"
+  new="$(printf '%s\n%s' "$current" "$(cron_line)" | sed '/^$/d')"
+  printf '%s\n' "$new" | crontab - || { role_log "ERR" "寫入 crontab 失敗"; return 1; }
+  role_log "INF" "已安裝睡眠排程：每日 $(cron_hours) 時整點檢查（角色 ${ROLE}，時段 $(role_sleep_start)–$(role_sleep_end)）"
+  role_log "INF" "排程輸出：$(sleep_log_path)"
+  if ! pgrep -x cron >/dev/null 2>&1 && ! pgrep -x crond >/dev/null 2>&1; then
+    role_log "WRN" "系統 cron 服務未執行（WSL 常見），排程不會觸發；SessionStart 的背景補跑仍會運作"
+  fi
+  return 0
+}
+
+remove_cron() {
+  # 移除本 skill 安裝的排程條目
+  command -v crontab >/dev/null 2>&1 || { role_log "ERR" "找不到 crontab"; return 1; }
+  crontab -l 2>/dev/null | grep -v -F "$CRON_MARKER" | crontab -
+  role_log "INF" "已移除睡眠排程"
+  return 0
+}
+
+show_status() {
+  # 以表格輸出目前角色與記憶狀態（供 skill 的 --status 使用）
+  local cron_state="未安裝" cron_service="未執行" window="否"
+  crontab -l 2>/dev/null | grep -qF "$CRON_MARKER" && cron_state="已安裝"
+  { pgrep -x cron >/dev/null 2>&1 || pgrep -x crond >/dev/null 2>&1; } && cron_service="執行中"
+  role_in_sleep_window && window="是"
+  printf '| 項目 | 值 |\n| --- | --- |\n'
+  printf '| 角色 | %s |\n' "$ROLE"
+  printf '| 角色定義檔 | %s |\n' "$(role_file "$ROLE")"
+  printf '| 睡眠時段 | %s–%s |\n' "$(role_sleep_start)" "$(role_sleep_end)"
+  printf '| 目前是否睡眠中 | %s |\n' "$window"
+  printf '| cron 排程 | %s |\n' "$cron_state"
+  printf '| cron 服務 | %s |\n' "$cron_service"
+  printf '| 摘要 CLI | %s |\n' "$(role_select_cli 2>/dev/null || printf '找不到可用 CLI')"
+  printf '\n'
+  python3 "${SCRIPT_DIR}/memory.py" stats --role "$ROLE" 2>/dev/null
+  printf '\n'
+}
+
+# ------------------------------------------------------------------------------
+# 進入點
+# ------------------------------------------------------------------------------
+
+MODE="${1:---status}"
+case "$MODE" in
+  --run)
+    role_enabled || exit 0
+    require_role
+    if ! role_in_sleep_window; then
+      role_log "DBG" "目前不在睡眠時段（$(role_sleep_start)–$(role_sleep_end)），略過"
+      exit 0
+    fi
+    if role_ai_running; then
+      role_log "INF" "偵測到 AI 正在運行，本小時不進入睡眠，下個整點再檢查"
+      exit 0
+    fi
+    sleep_cycle "cron"
+    ;;
+  --catchup)
+    role_enabled || exit 0
+    require_role
+    if [ "$(python3 "${SCRIPT_DIR}/memory.py" need-sleep --role "$ROLE" 2>/dev/null)" != "yes" ]; then
+      role_log "DBG" "不需補跑整理"
+      exit 0
+    fi
+    sleep_cycle "補跑"
+    ;;
+  --force)
+    require_role
+    sleep_cycle "手動"
+    ;;
+  --install-cron)
+    require_role
+    install_cron
+    ;;
+  --remove-cron)
+    remove_cron
+    ;;
+  --status)
+    require_role
+    show_status
+    ;;
+  -h|--help)
+    usage
+    ;;
+  *)
+    usage
+    exit 1
+    ;;
+esac
@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+# ==============================================================================
+# 用途：角色記憶的 transcript 處理工具。負責 (1) 從 Claude Code／Codex
+#       JSONL 抽出「本輪」對話片段（最後一筆使用者訊息之後的全部內容），
+#       (2) 估算本輪花費時間，(3) 對文字做機密遮蔽（token／密碼／PII），
+#       作為寫入記憶檔前的第二道防線。
+# 更新時間：2026/07/28 00:00:00
+# 相依：Python 3 標準庫。抽取與遮蔽全程僅走 stdin／stdout，本檔不寫任何檔案。
+# ==============================================================================
+
+import json
+import re
+import sys
+from datetime import datetime, timezone
+
+# 單則工具結果／參數的擷取上限，避免整份 transcript 塞進摘要輸入
+TOOL_RESULT_LIMIT = 200
+TOOL_INPUT_LIMIT = 160
+TOTAL_LIMIT = 24000
+
+# ------------------------------------------------------------------------------
+# 機密遮蔽規則：命中一律換成 ***
+# ------------------------------------------------------------------------------
+REDACT_PATTERNS = [
+    (r"[A-Za-z0-9_\-]*:[A-Za-z0-9_\-]{16,}@", "***@"),          # URL 內嵌憑證 user:token@
+    (r"\b[0-9a-f]{40}\b", "***"),                                 # Gitea 40 字元 token
+    (r"\bgh[pousr]_[A-Za-z0-9_]{16,}\b", "***"),                  # GitHub token
+    (r"\bsk-[A-Za-z0-9\-_]{16,}\b", "***"),                       # API key
+    (r"(?i)\b(token|password|passwd|pwd|secret|api[_-]?key)\b\s*[:=]\s*\S+", r"\1=***"),
+    (r"(?i)Authorization:\s*(token|bearer)\s+\S+", r"Authorization: \1 ***"),
+    (r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}", "***"),  # Email
+    (r"\b09\d{2}[-\s]?\d{3}[-\s]?\d{3}\b", "***"),                 # 台灣手機
+    (r"\b[A-Z][12]\d{8}\b", "***"),                                # 身分證字號
+]
+
+
+def redact(text):
+    """對文字套用全部機密遮蔽規則，回傳遮蔽後的結果。"""
+    for pattern, replacement in REDACT_PATTERNS:
+        text = re.sub(pattern, replacement, text)
+    return text
+
+
+def _is_real_user_message(entry):
+    """判斷 transcript 條目是否為真正的使用者輸入（排除工具回填與環境注入）。"""
+    payload = entry.get("payload")
+    if isinstance(payload, dict) and entry.get("type") == "event_msg":
+        return payload.get("type") == "user_message" and bool(str(payload.get("message") or "").strip())
+
+    if entry.get("type") != "user":
+        return False
+    content = entry.get("message", {}).get("content")
+    if isinstance(content, str):
+        return bool(content.strip())
+    if isinstance(content, list):
+        return any(b.get("type") == "text" for b in content if isinstance(b, dict))
+    return False
+
+
+def _blocks(entry):
+    """取出條目的 content blocks，統一為 list 形式。"""
+    content = entry.get("message", {}).get("content")
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}]
+    return content if isinstance(content, list) else []
+
+
+def _payload_text_blocks(content):
+    """把 Codex response_item 的 content blocks 轉成純文字片段。"""
+    if isinstance(content, str):
+        return [content]
+    if not isinstance(content, list):
+        return []
+    texts = []
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        if block.get("type") in ("input_text", "output_text", "text"):
+            text = (block.get("text") or "").strip()
+            if text:
+                texts.append(text)
+    return texts
+
+
+def _render_codex_payload(entry):
+    """將 Codex session JSONL 的 payload 格式轉為摘要輸入用純文字。"""
+    payload = entry.get("payload")
+    if not isinstance(payload, dict):
+        return []
+
+    lines = []
+    entry_type = entry.get("type")
+    payload_type = payload.get("type")
+
+    if entry_type == "event_msg":
+        if payload_type == "user_message":
+            message = (payload.get("message") or "").strip()
+            if message:
+                lines.append(f"[user] {message}")
+        elif payload_type == "agent_message":
+            message = (payload.get("message") or "").strip()
+            if message:
+                phase = payload.get("phase") or "assistant"
+                lines.append(f"[assistant:{phase}] {message}")
+        return lines
+
+    if entry_type != "response_item":
+        return lines
+
+    if payload_type == "message":
+        role = payload.get("role") or "assistant"
+        if role in ("system", "developer"):
+            return lines
+        for text in _payload_text_blocks(payload.get("content")):
+            # Codex 會把 skill 內容以 user role 注入；避免把整份 SKILL.md 當成本輪工作。
+            if role == "user" and text.lstrip().startswith("<skill>"):
+                continue
+            if role == "user" and text.lstrip().startswith("<environment_context>"):
+                continue
+            lines.append(f"[{role}] {text}")
+    elif payload_type == "function_call":
+        name = payload.get("name") or "?"
+        raw = str(payload.get("arguments") or "").strip().replace("\n", " ")
+        lines.append(f"[tool:{name}] {raw[:TOOL_INPUT_LIMIT]}")
+    elif payload_type == "function_call_output":
+        raw = str(payload.get("output") or "").strip().replace("\n", " ")
+        if raw:
+            lines.append(f"[result] {raw[:TOOL_RESULT_LIMIT]}")
+
+    return lines
+
+
+def _render(entry):
+    """將單一 transcript 條目轉為摘要輸入用的純文字行（工具結果僅取前段）。"""
+    codex_lines = _render_codex_payload(entry)
+    if codex_lines:
+        return codex_lines
+
+    role = entry.get("type")
+    lines = []
+    for block in _blocks(entry):
+        if not isinstance(block, dict):
+            continue
+        kind = block.get("type")
+        if kind == "text":
+            text = (block.get("text") or "").strip()
+            if text:
+                lines.append(f"[{role}] {text}")
+        elif kind == "tool_use":
+            name = block.get("name", "?")
+            raw = json.dumps(block.get("input", {}), ensure_ascii=False)
+            lines.append(f"[tool:{name}] {raw[:TOOL_INPUT_LIMIT]}")
+        elif kind == "tool_result":
+            raw = block.get("content")
+            if isinstance(raw, list):
+                raw = " ".join(
+                    b.get("text", "") for b in raw if isinstance(b, dict) and b.get("type") == "text"
+                )
+            raw = str(raw or "").strip().replace("\n", " ")
+            if raw:
+                lines.append(f"[result] {raw[:TOOL_RESULT_LIMIT]}")
+    return lines
+
+
+def _read_entries(path):
+    """讀取 transcript JSONL，忽略無法解析的列。"""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            entries = []
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except ValueError:
+                    continue
+    except OSError:
+        return []
+    return entries
+
+
+def _turn_start_index(entries):
+    """找出本輪起點：最後一筆真正使用者訊息的位置。"""
+    start = 0
+    for index in range(len(entries) - 1, -1, -1):
+        if _is_real_user_message(entries[index]):
+            start = index
+            break
+    return start
+
+
+def _parse_timestamp(value):
+    """解析常見 transcript timestamp 格式，失敗回 None。"""
+    if not isinstance(value, str) or not value.strip():
+        return None
+    raw = value.strip()
+    if raw.endswith("Z"):
+        raw = raw[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(raw)
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def _entry_timestamp(entry):
+    """取出 transcript 條目的時間欄位。"""
+    for key in ("timestamp", "created_at", "time"):
+        dt = _parse_timestamp(entry.get(key))
+        if dt:
+            return dt
+    message = entry.get("message")
+    if isinstance(message, dict):
+        for key in ("timestamp", "created_at", "time"):
+            dt = _parse_timestamp(message.get(key))
+            if dt:
+                return dt
+    return None
+
+
+def format_duration(seconds):
+    """把秒數格式化為精簡中文耗時。"""
+    if seconds < 0:
+        return "未判定"
+    minutes = int(round(seconds / 60))
+    if minutes <= 0:
+        return "1 分鐘內"
+    hours, mins = divmod(minutes, 60)
+    if hours and mins:
+        return f"{hours} 小時 {mins} 分鐘"
+    if hours:
+        return f"{hours} 小時"
+    return f"{mins} 分鐘"
+
+
+def turn_duration(path):
+    """
+    估算本輪花費時間：取本輪起點到最後一筆可解析 timestamp 的差距。
+
+    transcript 無時間欄位或本輪少於兩個時間點時回「未判定」，避免臆測。
+    """
+    entries = _read_entries(path)
+    if not entries:
+        return "未判定"
+    start = _turn_start_index(entries)
+    stamps = [dt for dt in (_entry_timestamp(e) for e in entries[start:]) if dt]
+    if len(stamps) < 2:
+        return "未判定"
+    return format_duration((max(stamps) - min(stamps)).total_seconds())
+
+
+def extract_turn(path):
+    """
+    從 transcript JSONL 抽出本輪內容：最後一筆真正使用者訊息（含該筆）之後的全部條目。
+
+    不需任何狀態檔即可界定「本輪」，符合工作內容不落地的要求。
+    回傳純文字字串；讀取失敗或無內容時回空字串。
+    """
+    entries = _read_entries(path)
+    if not entries:
+        return ""
+    start = _turn_start_index(entries)
+
+
+    lines = []
+    for entry in entries[start:]:
+        lines.extend(_render(entry))
+
+    text = "\n".join(lines).strip()
+    if len(text) > TOTAL_LIMIT:
+        head = text[: TOTAL_LIMIT // 2]
+        tail = text[-TOTAL_LIMIT // 2 :]
+        text = f"{head}\n…（中段省略）…\n{tail}"
+    return text
+
+
+USAGE = """用法：transcript.py <子命令> [參數]
+
+  extract <transcript 路徑>   抽出本輪內容並遮蔽機密後輸出到 stdout
+  duration <transcript 路徑>  估算本輪花費時間，無法判定時輸出「未判定」
+  redact                      自 stdin 讀取文字，遮蔽機密後輸出到 stdout
+"""
+
+
+def main(argv):
+    """CLI 進入點：解析子命令並執行抽取或遮蔽。"""
+    if not argv or argv[0] in ("-h", "--help"):
+        print(USAGE)
+        return 0
+    if argv[0] == "extract":
+        if len(argv) < 2:
+            return 2
+        text = extract_turn(argv[1])
+        if not text:
+            return 1
+        sys.stdout.write(redact(text))
+        return 0
+    if argv[0] == "duration":
+        if len(argv) < 2:
+            return 2
+        sys.stdout.write(turn_duration(argv[1]))
+        return 0
+    if argv[0] == "redact":
+        sys.stdout.write(redact(sys.stdin.read()))
+        return 0
+    print(USAGE)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,310 @@
+---
+name: role
+description: 角色人格與長期記憶系統的建立與維護 skill。讓 CLI 工具以固定角色（name／nature／vibe／簽名 emoji）回覆，並把每輪對話累積成長期記憶：搭配相容的 SessionStart hook 於啟動時載入角色與記憶、Stop hook 記錄對話，睡眠時段（預設 22:00 至隔天 06:00）由排程整理記憶（分類重要／興趣／新知／技能／日常／其他、去重、設標籤與一句話總結、壓縮歸檔，日常與其他依使用頻率遺忘）。提供 --new（新建或更新角色，更新時逐欄核對新舊）、--use（切換啟用角色）、--list、--sleep（立即整理）、--status／--diagnose、--install-cron／--remove-cron、--forget-preview 等模式。當使用者說建立角色、新增人格、切換角色、讓回覆更有特色、角色記憶、記憶整理、睡覺整理記憶、忘記舊記憶、角色沒有載入、hook 沒載入角色，或提到 .roles／.memory／ROLE_NAME／ROLE_ENABLED／ROLE_SLEEP_START／ROLE_MEMORY_HOME 時觸發。不適用於：工作紀錄寫入 Gitea wiki（用 doc plugin 的 worklog）、專案文件化（用 doc-funcs）。
+---
+
+# role — 角色人格與長期記憶
+
+讓 CLI 工具的回覆帶固定人格，並把與使用者的對話累積成可被下次載入的長期記憶。
+**載入與記錄由 hook 自動完成、不需人工觸發**；本 skill 負責自動路徑之外的人工操作：建立／更新角色、切換角色、手動整理、排程安裝與診斷。
+
+| 元件 | 觸發者 | 職責 |
+| --- | --- | --- |
+| `hooks/hooks.json` 的 `SessionStart` hook | harness 自動 | 啟動 CLI 時載入角色定義＋記憶；睡眠時段只回報「角色睡覺中」不載入 |
+| `hooks/hooks.json` 的 `Stop` hook | harness 自動 | 每輪結束抽本輪對話 → 濃縮成一則記憶 → 遮蔽 → 寫入 `inbox/` |
+| cron 排程（本 skill 安裝） | 系統排程 | 睡眠時段每小時檢查一次：**有 AI 在運行就不睡**，沒有才進入睡眠整理記憶 |
+| 本 skill `/jsc:role` | 使用者／助理手動 | `--new`／`--use`／`--list`／`--sleep`／`--status`／`--install-cron`／`--forget-preview` |
+| `scripts/role/role_load.sh` | SessionStart hook | 角色與記憶載入（單一實作，避免漂移） |
+| `scripts/role/role_capture.sh` | Stop hook | 對話 → 記憶（四欄固定格式） |
+| `scripts/role/role_sleep.sh` | cron／補跑／手動 | 睡眠判斷、記憶整理、排程安裝、狀態輸出 |
+| `scripts/role/memory.py` | 上述共用 | 記憶檔讀寫、分類、去重合併、壓縮歸檔、遺忘、載入組裝 |
+| `scripts/role/transcript.py` | 上述共用 | 抽本輪對話片段、機密與個資遮蔽 |
+| `scripts/role/role_lib.sh` | 上述共用 | log、角色解析、睡眠時段、AI 行程偵測、CLI 選擇、記憶鎖 |
+
+### 各助理支援範圍
+
+| 功能 | Claude Code | Codex | Antigravity | OpenCode | GitHub Copilot |
+| --- | --- | --- | --- | --- | --- |
+| `SessionStart` 載入角色 | ✅ | ⚠️ 需該版本支援 SessionStart hook | ❌ | ❌ | ❌ |
+| `Stop` 記錄記憶 | ✅ | ✅ 需可讀 Codex session JSONL | ❌ | ❌ | ❌ |
+| cron 睡眠整理 | ✅ 與助理無關（系統排程） | ✅ | ✅ | ✅ | ✅ |
+| `--new`／`--use`／`--sleep` 等模式 | ✅ | ⚠️ 需 plugin 目錄保留 `scripts/` | ⚠️ 同左 | ❌ 只複製 `skills/`，無腳本 | ⚠️ 同左 |
+| 濃縮／整理 CLI | `claude -p` | `codex exec` | `agy -p` | `opencode run` | `copilot -p` |
+
+- **`hooks/hooks.json` 只有 Claude Code 一定會讀**；Codex 會從 `~/.codex/plugins/cache/generic/jsc` 找腳本。其他助理若提供等效 hook，`transcript.py` 需補對應解析器。
+- 不支援 hook 的助理仍可用：cron 排程與手動模式照常運作，只是角色不會自動載入。
+
+### 腳本路徑解析（重要）
+
+skill 執行時的工作目錄是**使用者的專案目錄**，不是 plugin 根目錄，因此**絕不可用相對路徑呼叫腳本**：
+
+| 環境 | plugin 根目錄 |
+| --- | --- |
+| Claude Code | `${CLAUDE_PLUGIN_ROOT}` |
+| 其他助理 | 本 skill 載入時提示的 base directory（`.../skills/role`）往上兩層 |
+
+```bash
+ROLE_DIR="${CLAUDE_PLUGIN_ROOT}/scripts/role"     # Claude Code
+ROLE_DIR="<skill base directory>/../../scripts/role"  # 其他助理
+```
+
+以下各模式一律以 `${ROLE_DIR}` 表示該目錄。解析不到或該目錄不存在時，回報「plugin 目錄未包含 scripts/role，本 skill 在此環境不可用」並停止，不要改用相對路徑重試。
+
+---
+
+## 共用規範（必要前置）
+
+執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到時先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），不安裝則中斷**：
+
+- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先。
+- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。
+- `/jsc:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。
+
+本 skill 特有補充：
+
+- **覆寫角色前一定要核對**：`--new` 遇到同名角色時，必須先逐欄列出新舊差異並取得使用者確認才寫入。這是本 skill 明定「一定會中斷詢問」的點，**不得被 `--yes` 略過**。
+- **不臆測角色設定**：`nature`／`vibe`／`emoji` 一律問使用者，不得代填。
+- **記憶只增不刪**：手動模式不得直接刪除分類記憶；淘汰一律走遺忘規則（先壓縮歸檔再移除）。
+- **絕不阻斷**：hook 路徑任何失敗都以 exit 0 結束，只在 stderr 留訊息。
+
+---
+
+## 環境變數
+
+| 變數 | 必要 | 說明 | 未設定 |
+| --- | --- | --- | --- |
+| `ROLE_ENABLED` |  | 總開關：`1` 強制啟用、`0` 強制停用 | **未設定時，只要有可解析且存在的角色就啟用**（沒建過角色的人零影響） |
+| `ROLE_NAME` |  | 指定本次要載入的角色 | 讀 `~/.roles/.active` |
+| `ROLE_HOME` |  | 角色定義目錄 | `~/.roles` |
+| `ROLE_MEMORY_HOME` |  | 記憶根目錄 | `~/.memory` |
+| `ROLE_SLEEP_START` |  | 睡眠起始 `HH:MM` | `22:00` |
+| `ROLE_SLEEP_END` |  | 睡眠結束 `HH:MM` | `06:00` |
+| `ROLE_CLI` |  | 濃縮／整理執行器：`auto`／`claude`／`codex`／`agy`／`opencode`／`copilot` | `auto`（先判斷目前 hook 環境，再 fallback 到已安裝工具） |
+| `ROLE_MODEL` |  | 強制指定模型（僅 `claude` CLI 使用） | 保底 `claude-haiku-4-5-20251001` |
+| `ROLE_LOAD_LIMIT` |  | 注入記憶的字元上限 | `8000` |
+| `ROLE_SLEEP_TIMEOUT` |  | 單次整理的模型逾時秒數 | `180` |
+| `ROLE_SCOPE` |  | 冒號分隔的路徑前綴，僅這些路徑下的 session 載入／記錄 | 全部 session |
+| `ROLE_ERRLOG` |  | 錯誤訊息額外寫入的檔案路徑 | 只走 stderr |
+
+> 角色切換用 `/jsc:role --use <名稱>`（寫 `.active`）即可，一般不需要設 `ROLE_NAME`；`ROLE_NAME` 適合「單一專案固定用某角色」時寫進該環境。
+
+---
+
+## 模式
+
+### `--new`（預設模式）
+
+建立或更新角色。缺少的資訊**一次問齊**，不得代填：
+
+| 欄位 | 說明 | 範例 |
+| --- | --- | --- |
+| `name` | 角色名稱，同時是檔名 `~/.roles/<name>.md` 與記憶目錄名。不得含 `/`、`\`、空白與前後點 | `小豹` |
+| `nature` | 本質：這個角色是什麼、專長與行事準則 | 冷靜可靠的資深工程師，重證據、不打包票 |
+| `vibe` | 氛圍：語氣、句長、稱呼、幽默感、禁忌 | 簡潔直白、偶爾吐槽，不用客套開場白 |
+| `emoji` | 簽名 emoji，一到二個 | 🐆 |
+
+流程：
+
+1. 解析 `${ROLE_DIR}`；不存在則中止（見「腳本路徑解析」）。
+2. 以 `AskUserQuestion` 或提問取得四個欄位（使用者已在指令中給的欄位不得重複問）。
+3. 依「角色檔標準格式」產生新內容，`updated` 用當下時間（Asia/Taipei）。
+4. **若 `~/.roles/<name>.md` 已存在**：讀舊檔，以表格逐欄列出差異後**停下來等使用者確認**：
+
+   | 欄位 | 舊值 | 新值 | 變更 |
+   | --- | --- | --- | --- |
+   | nature | … | … | 是／否 |
+   | vibe | … | … | 是／否 |
+   | emoji | … | … | 是／否 |
+   | 共用行為區塊 | 版本 A | 版本 B | 是／否 |
+
+   個性欄位若使用者只想改其中一項，其餘一律沿用舊值；**共用行為區塊一律以本 skill 的最新版本覆寫**（該區塊由系統維護）。使用者不確認就不寫入。
+5. 寫入 `~/.roles/<name>.md`（UTF-8 無 BOM）。
+6. 建立記憶目錄：`python3 "${ROLE_DIR}/memory.py" stats --role "<name>"`（會順帶建好 `inbox/`、六個分類與 `archive/`）。
+7. 若尚未有啟用角色，或使用者要求，寫入 `~/.roles/.active`（單行角色名）。
+8. 執行 `ROLE_NAME="<name>" "${ROLE_DIR}/role_sleep.sh" --install-cron` 安裝睡眠排程（已安裝則更新）。
+9. 回報結果並提醒：**重開 CLI 工作階段**角色才會載入；`SessionStart` hook 只在啟動時觸發。
+
+### `--use <名稱>`
+
+切換啟用角色：確認 `~/.roles/<名稱>.md` 存在後，把名稱寫入 `~/.roles/.active`（覆蓋單行），回報舊角色與新角色，並提醒重開工作階段。
+
+### `--list`
+
+列出 `~/.roles/*.md`，以表格輸出：角色、emoji、nature 摘要、更新時間、是否為 `.active`、記憶總數（可用 `memory.py stats` 取得）。
+
+### `--sleep`
+
+立即執行一次記憶整理（不等排程、忽略時段與 AI 運行檢查）：
+
+```bash
+"${ROLE_DIR}/role_sleep.sh" --force
+```
+
+輸出整理結果（新增／合併／捨棄／歸檔筆數與遺忘清單）。
+
+### `--forget-preview`
+
+只預覽會被遺忘的記憶、不實際刪除：
+
+```bash
+python3 "${ROLE_DIR}/memory.py" forget --role "<name>" --dry-run
+```
+
+### `--status`／`--diagnose`
+
+```bash
+"${ROLE_DIR}/role_sleep.sh" --status
+```
+
+輸出角色、定義檔、睡眠時段、目前是否睡眠中、cron 排程與服務狀態、摘要 CLI、各分類記憶筆數、上次整理與遺忘時間。**角色沒有載入時**再逐項檢查：
+
+| 檢查項 | 判準 |
+| --- | --- |
+| 角色解析 | `ROLE_NAME` 或 `~/.roles/.active` 是否指向存在的定義檔 |
+| 總開關 | `ROLE_ENABLED` 是否被設成 `0` |
+| hook 註冊 | plugin 是否已啟用、`hooks/hooks.json` 是否存在（Claude Code 用 `/hooks` 檢視） |
+| 工作階段 | 建立角色後是否**重開過** CLI（SessionStart 只在啟動時觸發） |
+| 範圍 | `ROLE_SCOPE` 是否把目前目錄排除 |
+| 時段 | 目前是否落在睡眠時段（睡眠時本來就不載入角色） |
+| 依賴 | `python3` 與 `ROLE_CLI` 選到的 CLI 是否找得到 |
+| 排程 | cron 條目是否存在、cron 服務是否執行中（WSL 常未啟動 → 靠啟動時補跑） |
+
+### `--install-cron`／`--remove-cron`
+
+安裝或移除睡眠排程。排程條目以 `# jsc-role-sleep` 註解標記，只動自己的條目：
+
+```bash
+"${ROLE_DIR}/role_sleep.sh" --install-cron
+```
+
+安裝時會把目前的 `PATH` 與 `ROLE_*` 變數固定寫進條目（cron 沒有互動 shell 的環境變數），並在 cron 服務未執行時警告。
+
+---
+
+## 角色檔標準格式
+
+`~/.roles/<name>.md`，UTF-8 無 BOM。個性區塊由使用者決定，**共用行為區塊由本 skill 維護、逐字寫入每個角色檔**：
+
+````markdown
+---
+name: <角色名>
+nature: <本質，一句話>
+vibe: <氛圍，一句話>
+emoji: <簽名 emoji>
+created: <yyyy/MM/dd HH:mm:ss>
+updated: <yyyy/MM/dd HH:mm:ss>
+---
+
+# <角色名> <emoji>
+
+## 本質（nature）
+
+<3 至 5 行：這個角色是什麼、專長、行事準則、面對不確定時的態度>
+
+## 氛圍（vibe）
+
+<3 至 5 行：語氣、句子長度、對使用者的稱呼、幽默感尺度、明確禁忌>
+
+## 簽名 emoji
+
+<emoji> —— 每次回覆使用一次（開頭或結尾擇一固定），不重複刷、不在程式碼與檔案內容中使用。
+
+## 共用行為（所有角色一致，由 /jsc:role 維護，請勿手動修改）
+
+<!-- JSC-ROLE-COMMON:START -->
+### 角色邊界
+
+- 角色只影響**表達方式**，不影響工作的正確性、完整性與安全性。與使用者的明確指令衝突時，一律以使用者指令為準。
+- 不因角色設定而編造事實、跳過驗證、隱瞞失敗或淡化風險；壞消息照實說，只是用角色的語氣說。
+- 涉及程式碼、指令、檔案內容與報錯訊息時，一律照實輸出，不加角色修飾。
+
+### 作息
+
+- 每天 **22:00 至隔天 06:00 為睡眠時段**（可用 `ROLE_SLEEP_START`／`ROLE_SLEEP_END` 調整）。
+- 睡眠時段內啟動 CLI **不會載入角色**：以一般助理身分回應，不自稱角色、不使用角色語氣與簽名 emoji。此時對話仍會被記錄成記憶。
+- 睡眠排程每小時檢查一次，**偵測到有 AI 正在運行就不睡**，留到下個整點再試；沒有 AI 運行才進入睡眠並整理記憶。
+
+### 記憶
+
+- 記憶存放於 `~/.memory/<角色名>/`，來源是與使用者的對話：每輪結束由 hook 自動記錄到 `inbox/`，睡眠時段整理歸檔。
+- 整理規則：分類成**重要／興趣／新知／技能／日常／其他**六類 → 去除重複（重複者併入既有記憶）→ 設定標籤與一句話總結 → 壓縮內容後歸檔；原始記錄壓縮保存在 `archive/raw/`。
+- **日常與其他**兩類會依使用頻率適當遺忘：久未再次出現且命中次數低者，壓縮到 `archive/forgotten/` 後移出常用記憶。
+- 載入順序：**重要與興趣載入全文**；其餘只載入總結與標籤，依**技能 → 新知 → 日常 → 其他**排序。需要細節時自行讀取對應分類的記憶檔。
+- 使用者明確要求記住某件事時，主動補寫一則記憶（載入時會提供補寫指令）。
+- **絕不把憑證與個資寫進記憶**：token、密碼、API key、連線字串、Email、電話、姓名、身分證號。
+<!-- JSC-ROLE-COMMON:END -->
+````
+
+`~/.roles/.active` 只放一行角色名，代表目前啟用的角色。
+
+---
+
+## 記憶模型
+
+```
+~/.memory/<角色名>/
+├── inbox/                 每輪對話產生、尚未整理的記憶
+├── important/             重要：長期偏好、規範、決策、身分背景
+├── interest/              興趣：反覆關注、主動深入的主題
+├── news/                  新知：新事實、新工具、外部資訊
+├── skill/                 技能：可重複套用的做法與流程
+├── daily/                 日常：一次性例行工作
+├── other/                 其他
+├── archive/raw/<yyyy-MM>/ 已整理的原始記錄（gzip）
+├── archive/forgotten/     已遺忘的記憶（gzip，可考古但不再載入）
+└── state.json             上次整理／遺忘時間
+```
+
+每則記憶是一個 `.md`，frontmatter 帶 `id`／`category`／`summary`（一句話總結）／`tags`／`created`／`updated`／`hits`（命中次數，去重合併時 +1）。
+
+遺忘規則（只套用於日常與其他）：
+
+| 分類 | 未更新天數 | 命中次數 | 動作 |
+| --- | --- | --- | --- |
+| 日常 daily | ≥ 14 天 | ≤ 1 | 壓縮到 `archive/forgotten/` 後移除 |
+| 其他 other | ≥ 7 天 | ≤ 1 | 壓縮到 `archive/forgotten/` 後移除 |
+
+---
+
+## 睡眠與整理流程
+
+```mermaid
+flowchart TD
+    A[cron 每小時觸發<br/>睡眠時段內] --> B{有 AI 正在運行?}
+    B -- 有 --> C[不睡，下個整點再檢查]
+    B -- 沒有 --> D[進入睡眠，取得記憶鎖]
+    D --> E[collect：inbox 待整理 + 既有記憶索引]
+    E --> F{有待整理記憶?}
+    F -- 沒有 --> G[更新整理時間 → 執行遺忘]
+    F -- 有 --> H[CLI 分類/去重/標籤/總結/壓縮]
+    H --> I[apply：寫入分類、原始記錄歸檔]
+    I --> J[forget：日常與其他依使用頻率遺忘]
+    J --> K[釋放鎖]
+    G --> K
+    L[SessionStart：白天啟動 CLI] --> M{距上次整理 ≥ 20 小時<br/>且 inbox 有內容?}
+    M -- 是 --> N[背景補跑 --catchup]
+    M -- 否 --> O[正常載入角色與記憶]
+```
+
+整理失敗（模型無回應、輸出非合法 JSON）時**保留 inbox 不動**，留到下個週期重做，寧可晚整理也不遺失記憶。
+
+---
+
+## 機密與 PII（兩道防線）
+
+| 防線 | 位置 | 內容 |
+| --- | --- | --- |
+| 1 | 濃縮與整理提示詞 | 明令不得輸出 token／密碼／API key／連線字串／Email／電話／姓名／身分證號 |
+| 2 | `transcript.py` 的 `redact` | 正則遮蔽：URL 內嵌憑證、40 字元 hex token、`gh?_`／`sk-` token、`token=`／`password=`、`Authorization:`、Email、台灣手機、身分證號 |
+
+第二道防線不可移除 —— 模型不一定遵守指令，而記憶會被長期保存並在每次啟動時載入。
+
+---
+
+## 呼叫方式
+
+| 助理 | 呼叫 |
+| --- | --- |
+| Claude Code / Antigravity | `/jsc:role --new`、`/jsc:role --use 小豹`、`/jsc:role --list`、`/jsc:role --sleep`、`/jsc:role --status` |
+| Codex | `$role --status`，或用 `/skills` 選單 |
+| OpenCode / GitHub Copilot | 需完整 plugin 目錄保留 `scripts/`；OpenCode 以複製 `skills/` 安裝時不可用 |