whale-persona

whale-persona —— 多宿主人设引擎

简体中文 | [English](README.en.md)

把 AI 编码助手的人设变成一份可开关、可编辑、可记忆的配置：自称（按模型分档）、对用户的称呼、

关系立场、性格正文、逐条可勾选的工作契约、思维链语言，以及带代码级确认闸门的长期记忆。

一份私有 config.json + 一个收件箱文件，可接入 DeepSeek Harness、Codex 与 ZCode；每条记忆线可使用独立配置。

0.12.0 起还带一层条件反射：自己写规则，命中时由插件在代码层注入一步指令（匹配不花 token），

可选把这一步的请求瘦身、把工具裁到白名单 —— 规则是个人资产，默认零规则。

> 维护状态（2026-10-16 更新）：主宿主是 DeepSeek Harness；ZCode 适配器已解冻 —— 2026-09-19 曾因

> ZCode 快照用户工作区而停止开发（原话：ZCode 已经决定不再制作了），2026-10-16 维护者决定恢复：已按

> ZCode 3.15.3 的插件规范把清单对齐；真机回归待做（在本机 ZCode 里装一次、发一轮，见安装段 ②）。

> 这一侧仍只做 UserPromptSubmit hook 注入 + 一个管理技能，0.10.0 起的预设库 / 酒馆卡 / dsh.bundle

> 与它无关。完整取舍与改判记录见 [docs/维护状态.md](docs/维护状态.md)。

MIT · 纯 ESM · 零运行时依赖 · 不联网 · 异常一律降级为空（最坏是"没有人设"，不炸会话）。

English: a persona engine for AI coding harnesses — the English guide (what it is, how to install,

what each feature does, and which documents are authoritative) is [README.en.md](README.en.md).

0.18.0：Codex 连续性与记忆证据。 新增开场读取、本地 CLI 兜底、四个只读 MCP 工具、来源标签与适用条件、自检和内容指纹索引。待确认的记忆替代会保留旧条目，确认后才换版。

Codex 用户从这里开始（Node ≥ 20；零依赖；无需 API 密钥）：

git clone https://github.com/shenA2024/whale-persona.git
cd whale-persona
node scripts/install-codex.mjs --dry-run
node scripts/install-codex.mjs

填写安装命令报告的私有配置，然后重启 Codex、新开会话。已有配置加 --config <绝对路径>，原文件不会被改写。安装默认空白，不预设任何人的身份或关系。完整安装、故障恢复与限制见 [Codex 接入](docs/CODEX.md)；本次吸收的上游机制见 [灵枢研究记录](docs/LINGSHU_RESEARCH.md)。安装只建立加载链路，不能承诺模型在所有宿主和会话中绝不遗忘。

---

它解决什么问题

你和编码 AI 之间那些每次都要重说一遍的事：它老忘、你得反复交代；同一件活今天一个风格明天一个风格；

「别问我还要不要继续」这句话说过一百遍它还是问。

whale-persona 把这些人设事实变成一份你自己的配置，每个会话自动带上。装完是空白的、装上不改变任何行为——

要什么写什么。而它和别人不一样的一点：记忆必须你确认才生效（代码强制，不是提示词约束），

AI 只能提议，改不了你的准则。

先看到效果，再决定装不装（一条命令，只读，不碰你的任何配置）：

node scripts/render-preview.mjs --config examples/demo-config.json --cwd D:/work/demo

它把「此刻实际注入系统提示词的三段文本」逐字打印出来——这就是装完你能得到的东西。

想直接上手：往下跳到 [60 秒上手](#60-秒上手)。第三方要实现同样的格式：看 [SPEC.md](SPEC.md)。

---

它给你什么

| 能力 | 说明 |

|---|---|

| 自称 / 称呼 | {selfName} {userName} 占位符；自称可按具体模型指定（selfNameByModel），未命中回落 flash / pro 两档 |

| 立场与性格 | stance（一句话）与 character（整段正文），渲染在提示词最前面 |

| 形象（appearance） | opt-in、默认关：把「你是谁／长什么样」当既定事实注入（text 通用 + byModel 按模型覆盖，键写宿主真实模型 id）；渲染在立场正文之后、工作契约之前 |

| 形象卡（0.17.0） | appearance.cards：给自己 / 用户本人 / 第三方各存一张卡（标题 + 一行摘要 + 长文 + 照片路径）。默认「本人卡常驻一行摘要、长文与照片按 id 去读」——摘要进提示词、正文留在配置里；每张卡用 auto / expand / on 单独开关。图片永不进提示词（只给路径） |

| 回复语气（tone） | opt-in、默认关：只改措辞与节奏，不改结论、证据标准与工作契约；结构与形象相同，现成文案见 core/presets.js |

| 工作契约 | 逐条可勾选，on:false 即停用；写得具体可验证才有效 |

| 思维链语言 | 只改思考语言，不改答复语言（off / zh-CN / en …） |

| 长期记忆 | 手工条目（权威层）+ 收件箱（AI 提议 → 人确认 → 只追加式入库） |

| 分类路由（0.13.0） | 同一道确认闸门推广到记忆之外：条目标 kind（pitfall / idea …），人确认那一刻按 memory.sinks 路由只追加式落进目标文件；不注入提示词、幂等、无路由会报出来；默认空表 = 零行为改变 |

| 注入体积（0.13.0） | 计量每段字符数与合计（走与渲染同一条通路），面板与 CLI 可见；budget 超限时可选注入一行提醒 —— 只提醒，永不自动裁剪 |

| 条件反射（reflex） | 自己写规则，命中即在代码层注入一步指令（正则 / 近似 / 词袋三通道）；匹配不花 token，可选把这一步的请求瘦身、把工具裁到白名单；默认零规则 |

| 两个编辑入口 | DSH「设置 → 人设」可编辑面板 + 本仓自带本地编辑器页；同一套读写纪律 |

| 零行为改变 | 不写配置 = 三段全空，装上不改变任何行为（有单测钉住） |

| 默认安全 | 不联网、不执行命令、不读你的工作目录；写面逐项登记在 [.github/SECURITY.md](.github/SECURITY.md)，并由安全探针 S15 与代码同步（新增写盘文件不登记 = 安全套件红） |

现成的人设，去关联仓拿（本体只做引擎）

本仓是引擎：出厂空白、零观点、默认不改变行为（有单测钉死）。

想要"拿来就用"的起点——立场、身份正文、逐条可勾选的纪律——去关联仓：

> [whale-persona-presets](https://github.com/shenA2024/whale-persona-presets) —— 16 张预设卡

> （通用起步 / 证据优先 / 讲到你懂 / 去水改稿 / 严格评审 / 需求澄清 / 排障 / 重构 / 看数 /