whale-persona

dsh plugin --profile web add whale-persona

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





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

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

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

一份 config.json + 一个收件箱文件，DSH 与 ZCode 两个宿主共用同一个人设。

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

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

维护状态（2026-09-19）：主宿主是 DeepSeek Harness；ZCode 适配器停止开发（维护者 2026-09-19 拍板：

「ZCode 已经决定不再制作了」）。该目录仅作历史保留 —— 不再开发、不再真机回归、出问题不优先修；

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).

---

它解决什么问题

你和编码 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 —— 16 张预设卡

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

产品评审 / 陪练 / 资料整理 / 中译英 / 安全审查 / 提示词工程 / 多智能体分工）。

（上图由该仓的卡文件本身渲染：标题、描述、tags、契约逐条读出，没有手写内容。截图时该仓共 20 个卡文件。）

导入通道就是本仓已有的那条，不需要装新东西：

node scripts/presets.mjs import starter-plus.json   # 下载的卡直接吃
node scripts/presets.mjs list                       # 看有哪些
node scripts/presets.mjs apply starter-plus         # 应用（应用前自动存 autosave，可切回）

两仓的分工是刻意的：内容更新频繁、质量参差、还可能夹带第三方文本，而引擎要的是"出厂空白 + 零行为改变"

可被机器钉死（npm test 与 npm run sec）。混在一起，两边都会被拖坏。内容仓的每张卡都要过

它自己的 check.mjs（结构 + 用真引擎导入一遍 + 隐私门禁）。

60 秒上手

① 装（DSH） —— 一条命令：装插件 + 建预设 + 设默认 + 拷技能 + 自检

npx -y whale-persona     # 不需要克隆仓库；装完重启 DSH

要求：Node ≥ 20、DSH ≥ 0.1.6-alpha.1，装完重启 DSH。

不想用 npx？ 克隆仓库跑同一个脚本，效果一模一样：

git clone https://github.com/shenA2024/whale-persona.git
cd whale-persona
node scripts/install-dsh.mjs --dry-run   # 先看它要做什么
node scripts/install-dsh.mjs             # 真装

两样都不行？ 用 Release 附带的 tarball（与 npm pack 出来的完全同一份文件）：

dsh plugin --profile web add -w https://github.com/shenA2024/whale-persona/releases/download/v0.15.1/whale-persona-0.15.1.tgz

干净 DSH_HOME 实测：3.2 秒把包装上，不需要 git、不需要 npm 账号、不需要改 pnpm 配置。

⚠️ 三条通道的区别：市场 / tarball 那条是"分两半"装的。 npx 与克隆走的是同一个安装脚本，它一次就做完

装包 + 建 agent preset + 挂设置面板 + 拷技能 + 自检；插件市场（以及 tarball、dsh plugin add）只把包挂进

profile 平面 —— 结果是包在、设置面板在，但 agent preset 还没建（人设本体只认预设平面，

而官方市场通道不会替我们建它）。

0.17.3 起不用再跑脚本：重启后进 设置 → 人设 → 「Agent 预设」卡片点一下「建人设预设」

（卡片会直接写明「缺这一步」；要的话勾上「同时设为新任务默认」），然后新开会话。

想用命令行也行：

node "$env:USERPROFILE\.dsh\profiles\web\node_modules\whale-persona\scripts\install-dsh.mjs"

三条通道都会把设置面板自动挂成 profile 层（0.11.1 起本包声明了 dsh.bundle.patch，宿主自动把它加进

dsh.profile.bundles）；安装脚本还会先算清这条行的归属 —— bundle 已经挂了就一条都不插

（见下面「装不上？」表里那条 duplicate loader entry id）。

人设本体故意不自动挂：它要挂在 agent preset 平面才是"鲸鱼模式专属"（挂 profile 层会对所有模式生效）。

然后重启 DSH。脚本会跟随你当前的默认 preset 建一份名为 whale-persona 的预设（不覆盖你原来那份），并提示你之后怎么切过去。

装完是空白的，这是刻意的 —— 出厂零观点、装上不改变任何行为（有单测钉死）。真正必填的只有一段正文

（persona.character）：自称默认「我」、称呼默认「用户」，立场 / 语气 / 形象 / 工作契约全可选、默认关。

两种起步法任选：

• 去关联仓 whale-persona-presets 拿一张现成卡

（node scripts/presets.mjs import <卡.json>；也吃酒馆 v2 角色卡）；

• 或者对 AI 说一句：「加条契约：结尾不要出现征询式问句」。

懒得自己动手？ 把下面这句连同仓库地址丢给你的 AI：

读 https://github.com/shenA2024/whale-persona 的 README，按「60 秒上手」把 whale-persona 装到我的 DSH 上

（要求 Node ≥ 20、DSH ≥ 0.1.6-alpha.1），装完告诉我怎么重启与验证。

装不上？先对两处已知坑（报错原文照抄，可直接搜）：

报错原文 · 原因 · 修法

Failed to connect to github.com:443 / Connection was reset · 你的网络连不上 github.com（国内常见） · git 配代理：git config --global http.proxy socks5h://127.0.0.1:<你的代理端口>；或直接用上面的 tarball 通道

`gi

…(truncated)