dsh-agent-persona

dsh-agent-persona

给不同的工作区、不同的会话，用不同的 system prompt 人设。

English

它能做什么

一个 DSH 部署里常常同时跑着好几摊活：写前端、写文档、盯告警、做代码审查。它们需要不同的身份、口径和约束。 这个插件把人设按工作区或会话分发出去，每一份都是 system prompt 里的一段：

• 多个人设，各自声明适用范围：一条人设可以同时用于若干个工作区目录和若干个会话；匹配方式有 完全一致、开头是、包含、正则匹配四种。
• 越具体越优先：会话 ID 的规则优先于工作区，精确优先于前缀/正则；只有具体度相同时才按列表顺序决定。
• 显式默认人设：可以把某一条标成「默认人设」，它会收下所有没被位置命中的会话 —— 同一时刻只允许一条。 不标就没有兜底，那些会话继续用 DSH 自带的 system prompt。
• 一个位置只能属于一条人设：把某个工作区/会话配给新人设时，原来占着它的那条会自动失去它，并告诉你从谁那里转来的。
• 追加或替换：保留 DSH 自带的身份提示、把人设接在后面，或者去掉那句身份提示只用人设。
• 正文为空 = 这里不要人设：给某个位置加一行、正文留空，就显式地在那里关掉人设。
• 改完下一条消息生效，不用重启（正文按文件时间戳在每次组装时重读）。
• 工具改不动人设文件：人设会被注入 system prompt，所以宿主注册了一个全局 tools.guard，拒绝一切指向人设 存储的写入（write / edit 各类文件工具，以及含写入特征的 shell 命令），只读命令照旧放行。
• 存储读不出来时不会悄悄丢：文件存在但读不出来（内容坏了、不是人设存储）时，页面会说明原因，并且在第一次 保存之前先把原文件复制成 personas.json.bak-<时间戳>；备份失败就不会写入。
• 导入 / 导出：导出为一份 JSON 文件（同时复制到剪贴板）；导入可以选文件或粘贴，边输入边预览每条人设的 字数与规则数，再以「一律新建、一律停用」的方式写进去，默认人设不会被替换。

三处界面，各管一件事：

五个偏好开关（编辑后自动保存 / 在对话页显示「人设」标签 / 注册到 dsh-better-sidebar / 禁止模型改写人设文件 / 保存人设版本历史） 都在设置 → Agent 人设页里，并且这个页面不受这些开关影响 —— 关掉「对话页显示」或「注册到 dsh-better-sidebar」后， 回到这里就能重新打开。本插件不在设置 → 通用设置里添加任何条目；鼠标停在开关上会给出每个开关的完整说明。

为什么它压得住 AGENTS.md

DSH 会把工作区指令（AGENTS.md 之类）变成一条 user 角色的消息，那条消息自己的导语就写着 "They do not override system, developer, or direct user instructions." 而这个插件写的是 system prompt 的一个 section（section 名 agent-persona，order 1，紧跟在身份行之后）。

这个先后关系是框架定的，不是插件自己声明的 —— 也正因为如此，工作区里怎么改文件都动不了这层人设。

装

实测过的 DSH 版本：0.1.5-rc.1（作者的开发环境）、0.1.5-rc.2、0.2.0-rc.2 与最新版 0.2.1-rc.2。 package.json 的 dsh.compatibility 声明的就是这四项 —— 含义是"我们在这些版本上跑过"， 不是对更早或更新版本做过兼容工作的承诺；其它版本请自行验证。

侧边栏卡片还需要 dsh-better-sidebar：没装它时，「注册到 dsh-better-sidebar」这个开关不会出现 （没有可注册的地方），插件其余功能照常。

dsh plugin --profile web add dsh-agent-persona

装完重启一次 dsh web：profile 的 bundles 只在启动时读取，插件行是从那里挂进去的。

重启后能看到：

• 设置左栏的 Agent 人设；
• cat ~/.dsh/dsh-agent-persona/state.json —— 插件的加载心跳，写明了它加载了哪个文件、人设存哪、几条人设。

仓库里也有本地安装脚本：bash scripts/install.sh（Windows 是 scripts/install.ps1）。

升级与卸载（dsh plugin … 就是在 profile 目录里代跑包管理器）：

dsh plugin --profile web update dsh-agent-persona            # 升级（按依赖的版本范围取最新）
dsh plugin --profile web add dsh-agent-persona@latest        # 想跨大版本升到最新
dsh plugin --profile web remove dsh-agent-persona            # 卸载

升级或卸载后重启一次 dsh web。人设文件不会被删、也不会被覆盖：卸载是人设只留在文件里的操作。

用起来

点 新建人设 → 在「适用范围」里加行，选工作区或会话 → 写正文 → 打开启用开关 → 保存。

• 新建出来的人设默认停用，所以多一条人设不会影响任何现有会话，配好了再开。
• 适用范围是一行一行加的。每行先选类型（工作区目录 或 某个会话），再从下拉框里挑具体是谁。 两种类型互斥：把一行从「工作区」切成「某个会话」，这一行原来选的值会被清掉，重新选。
• 下拉框里的工作区来自 DSH 的工作区列表（带会话数），会话来自 DSH 的全部会话，按时间倒序， 带标题、工作目录和「几分钟前」—— 不记得 session id 是什么没关系，认标题就行。
• 想用前缀、正则这类高级匹配，选 自己输入… 就会变成输入框。
• 折叠状态下，卡片第二行分开列出这条人设用在了哪些工作区、哪些会话；一个位置都没加时写着 「未设置位置：不生效，该会话仍用 DSH 自带的 prompt」——那是停在草稿状态的人设，不是兜底。
• 想让它兜底，就打开卡片里的 默认人设 开关；列表行上会出现绿色的「默认」标记。

展开一张卡是这样：

版本历史（可选）

打开设置页的 保存人设版本历史，之后每次保存都会把这次的正文改动记成一条 diff（写在 personas.history.json）。编辑器底部的 版本历史 按钮打开对比窗口：

• 只记正文：名称、启用状态、适用范围不参与版本，改这些不会产生一条记录。
• 每条都是 diff：相等行只记行数，只有真正改动的行才存原文，所以一百条版本也远小于一百份正文。
• 恢复：选中任意一条点「恢复到此版本」写回正文；恢复动作本身也记一条，恢复错了还能再回滚。
• 删除：选中任意一条点「删除此版本」（连点两次确认）就把这条记录删掉；它后面的版本会重新计算 diff，仍然可以逐条打开，链不会断。
• 同一份正文只存一条：每条版本带正文的 sha256 前 16 位，保存时若和已有版本的内容哈希相同，就不 再新增记录（撤销、恢复后再保存、导入同样的正文都属于这种情况），列表和对比窗口里都能看到哈希。
• 链式重放：第一条版本作为基准快照，之后逐条重放；超过 200 条时把最旧的几条折进基准， 保留下来的版本仍可逐条打开。每条记录带内容摘要，历史文件被手改坏时重放会报错，不会给出别的正文。
• 关掉开关只是停止记录，已有历史仍可查看与恢复。

看这条会话聊了什么

下拉框旁边那个按钮会打开一个只读弹窗：左右气泡式对话（你的输入在右、Agent 的回复在左）。

• 只显示你真正敲进去的内容：工作区指令（AGENTS.md）、运行时上下文快照、skill 目录说明这类 插件注入的"看起来像用户消息"的东西一律不展示，弹窗顶部只写「已隐藏 N 条插件注入内容」， 不占位置，也不会让你困惑"这条我没说过"。
• 消息过长会被截断，就地提供 展开全文（只重读这一条，换掉这一个气泡）与 收起全文。
• 跳到最新 只显示最后一个用户输入及之后的回复。

对话页的「人设」标签

选中一条会话后，对话页顶部有 人设 / 提示词 / 管理 三个面板：

• 人设：这条会话命中了哪条人设、依据是哪几条规则（命中依据）、正文（Markdown 渲染）， 以及它自己的状态标记（在用 / 已停用、是否默认人设、注入方式）；下面是一个就地编辑器 （名称、默认人设开关、注入方式、正文），改动后卡片头会出现「未保存 · 点击保存」。
• 提示词：这条会话实际发出去的 system prompt，可以切换「渲染 / 源码」、复制、刷新。 没有命中任何人设时，这里显示的就是 DSH 原生注入的 prompt —— 不做任何特殊处理。
• 管理：与设置页同一套卡片（新建、启用/停用、编辑、排序、复制、删除），就地管理。

五个偏好

偏好存在人设文件的 prefs 字段里（不是浏览器），所以它和数据的可见范围一致；浏览器里只留一份镜像， 供"加载时决定要不要注册视图"用。

注入方式：追加还是替换

「替换」只动部署自己写的那句 persona；如果某个 Agent 预设在自己作用域里写了 persona（把这一段遮蔽了）， 插件不会去覆盖它 —— 别人的身份提示优先。

匹配是怎么算的

宿主在每次组装 system prompt 时按这个顺序过一遍：

1. 人设停用了 → 跳过；
2. 一条人设的任意一行匹配上，它就是候选，按"具体度"比较（会话 ID 3 分 > 工作区 1 分；精确 > 前缀/包含/正则）；
3. 具体度相同 → 取列表里靠上的那条（顺序在卡片的 ⋯ 菜单里调）；
4. 一个位置都没加的人设不参与匹配（草稿态），除非它被标成「默认人设」；
5. 谁都没命中 → 看有没有「默认人设」，有就用它，没有就不注入；
6. 赢家的正文是空的 → 不注入任何人设（这是"这里明确不要人设"的表达方式）。

四种匹配方式里只有 完全一致 会把路径归一化（/a/project/ 和 /a/project 算同一个）； 开头是、包含、正则匹配 都是拿你写的字符串直接比。值空着、正则写错、或者会话没有那个字段， 都算「不匹配」，不会报错。

文件与配置

~/.dsh/dsh-agent-persona/
├── personas.json          # 人设数据 + 偏好，权限 600，原子写入
├── personas.history.json  # 版本历史（开关打开后才出现）
└── state.json             # 加载心跳，每次加载时重写

正文里可以写 {{model}} 和 {{cwd}}，渲染时替换成当前的值；其他 {{...}} 会被去掉（未注册的变量会让 整个组装抛错，所以这里做了保护）。

配置项（Schemastery schema，加载时校验，写错类型会加载失败而不是被忽略）：

多个 profile 各用自己的人设文件（可选）

人设数据默认是全局一份（$DSH_HOME/dsh-agent-persona/personas.json，与其它插件的状态目录同一约定）， 所以同一台机器上的多个 profile 共用同一份人设。要让某个 profile 独立，在该 profile 的 cordis.patch.yml 里覆盖它自己的路径（是覆盖字段，不要再 insert 一行）：

# ~/.dsh/profiles/<该 profile>/cordis.patch.yml
- id: agent-persona
  config:
    storePath: /Users/you/.dsh/profiles/<该 profile>/personas.json

也可以用 DSH_HOME 环境变量把整个 ~/.dsh 指向别的目录（那样连会话记录、其它插件状态一起隔离）。 当前生效的文件路径始终显示在「Agent 人设」页面的 meta 行上（保存在 …），不会出现"改了半天不知道改的是哪一份"。

AI 改一版用哪个模型

默认用 DSH 当前设置的模型，设置页里的下拉框会把它预选好；想固定别的模型就用上面的 tuneProvider/tuneModel。 AI 只产出建议稿，点「采用」或「追加」才会进编辑框，再点保存才落盘。

几句实话

• 人设是行为约束，不是安全边界。它约束模型怎么说，不阻止模型用工具。
• 人设文件的防篡改是能力层面的判定：插件注册了全局 tools.guard，它不看工具叫什么名字，而是看这次调用会不会写到 受保护的文件 —— 参数里的路径（解析 ~ 与相对路径）、shell 命令里的重定向目标、写入型命令（删、移、原地改、解释器 -c），以及补丁正文里的 *** Update File: 目标。受保护的是主文件 personas.json、它的历史文件和它们的备份/临时副本。
• 它仍然只是行为约束，绕过面写在明处：本机 danger-full-access 下改插件代码、改 profile 补丁文件都能绕过；脚本里 运行时拼出来的路径静态看不出；$VAR 展开看不出；别名/函数包装也看不出。要更结实得在本机层面做： chflags uchg <人设文件>（自己改之前先 chflags nouchg），或者把 DSH 跑在受限沙箱里、让人设文件属于别的用户。
• 判定按单次工具调用生效：同一条命令里既读又写，写的那部分照样被拒，只读的部分不会被连坐。
• 多处同时匹配时只取第一条，不拼接；规则是线性扫的，几十条没问题，几百条就该重新设计了。
• 一个 profile 里只装一次。同一个进程挂两个同 id 的行会让组合起不来。
• 测试的边界：仓库里的测试是单元测试 + 源码审计（236 条宿主断言 + 187 条客户端断言 + 生成产物漂移校验； 这个数字由测试自己统计，不会随文件改动而失真），它们保证逻辑与代码形状，不驱动浏览器 —— 界面行为 （视图渲染、开关、侧边栏卡片）目前靠人工核对。

开发

源码是 TypeScript，lib/ 是构建产物（不进 git，npm publish 前由 prepare 构建）：

src/index.ts       host 半边：存储、匹配、system-prompt section、远程服务
src/client.ts      client 半边：设置页 + 会话视图 + 侧边栏卡片（打包成单文件 lib/client.js）
src/endpoints.ts   远程方法的单一来源（生成 src/remote.ts 与 src/typert.ts）
scripts/           生成器 + 安装脚本
test/              单元测试与源码审计
docs/              架构、开发笔记、设计决策

npm install
npm run build        # generate:remote → tsc → esbuild（产出 lib/）
npm run typecheck    # 两个 tsconfig 都不报错
npm test             # 236 + 187 条断言 + 生成产物漂移校验
dsh --profile web --dump-config | grep -c 'id: agent-persona'   # 组合自检，应输出 1

改代码之后怎么生效：

• src/** 改完必须 npm run build（lib/ 是产物）。
• 客户端产物（lib/client.js）改内容：客户端会按内容重算，刷新页面即可；别改文件名。
• 宿主产物（lib/index.js）改内容：ESM 按 URL 缓存模块，不会自动重载 —— 重启 dsh web。
• package.json 的 dsh.bundle.patch 或 profile 的 bundles 有改动：必须重启。
• 生成产物（src/remote.ts、src/typert.ts）不要手改：改 src/endpoints.ts 后跑 npm run generate:remote，npm test 会校验它们是否与来源一致。

细节在 docs/development.md，内部结构在 docs/architecture.md。

许可

Apache-2.0，见 LICENSE。