🧙 对角巷 · 角色面具

> 一键切换 AI 人格，让 DeepSeek Harness 化身百变角色

✨ 功能

• 🎭 角色切换：通过 switch_role 工具随时切换 AI 人格

- 按名称/ID：对话里说"切换到千机匠"或"切到 socrates" - 按序号：对话里说"切换到第2个角色"（序号对应 list_roles 列表顺序，从 1 开始）

• 📋 角色列表：list_roles 查看所有可用角色（含序号、ID、名称、描述）
• 🔍 当前角色：get_current_role 查看当前激活的角色
• ⚙️ 灵活配置：在配置中自由增删改角色，支持替换 / 追加两种注入模式

📦 安装（用户）

前提：本机已经可以运行 dsh web（dsh 命令可用）。

# 从 GitHub 安装（推荐，仓库未发布到 npm 也能装）
# 注意：pnpm 9.x 需要 -w（profile 目录本身是 workspace root）；pnpm ≥10 可省略
dsh plugin --profile web add -w github:<你的GitHub用户名>/dsh-diagon-alley

# 从 npm 安装（插件发布到 npm 后可用）
dsh plugin --profile web add dsh-diagon-alley

验证配置层叠加成功（无需启动）：

dsh --profile web --dump-config
# 输出中应能看到 `# == dsh-diagon-alley` 层

然后重启 dsh web（host 插件需要重启进程才会加载），开一个新会话，让模型 “列出所有角色”或“切换到苏格拉底”即可体验。

> 安装原理：声明了 dsh.bundle 的包会作为一层配置叠加到 profile， > cordis.patch.yml 中的行被插入组合配置，插件随 profile 一起加载。

🗑️ 卸载

dsh plugin --profile web remove dsh-diagon-alley

验证已移除（应看不到 dsh-diagon-alley 层）：

dsh --profile web --dump-config

然后重启 dsh web。host 插件一旦加载就在进程内存里，卸载只移除了 profile 的依赖与配置层，运行中的实例要重启后角色工具（switch_role 等）才会真正消失。

> 本地源码目录不受影响，随时可以重新安装。

🔧 本地开发 / 自测（插件作者）

npm install
npm run build        # tsc，产出 lib/
dsh plugin --profile web add -w .    # 在插件目录内执行
dsh --profile web --dump-config

⚙️ 配置

| 字段 | 类型 | schema 默认值 | 随包默认（bundle patch） | 说明 | | --- | --- | --- | --- | --- | | defaultRoleId | string | '' | python-tutor | 启动时激活的角色 ID；空表示不激活 | | mode | 'replace' \| 'append' | 'replace' | append | replace 用角色面具替换全部提示词段落；append 追加到末尾 | | roles | Role[] | 14 个内置角色 | 同左 | 角色列表 |

每个 Role：

用户可以在自己的 profile cordis.patch.yml 中按行 id 覆盖配置（替换整个 config 值）：

- id: dsh-diagon-alley
  config:
    defaultRoleId: socrates
    mode: append
    roles:
      - id: my-role
        name: '🎯 我的角色'
        prompt: '你是一个...'
        description: '角色描述'

❓ 常见问题

• ERR_PNPM_ADDING_TO_ROOT：pnpm 9.x 在 profile 目录（本身是 workspace root）

下执行 add 需要 -w 标志；dsh plugin --profile web add -w <包> 即可，或升级 pnpm ≥10。

• 从 GitHub 安装报 @deepseek-ai/dsh-type-meta 404：这是 peer 依赖级联问题。

本插件刻意不声明 peerDependencies——运行时所需的 @deepseek-ai/cordis / dsh-tools / dsh-system-prompt 由 DSH 安装本身提供。若自行添加 peer 声明， pnpm 从 git 安装时会自动解析 peer 的 peer，链上旧 rc 版本会引用一个未发布的 @deepseek-ai/dsh-type-meta，导致安装失败。请保持 peerDependencies 为空。

• 从 GitHub 安装时 prepare 被阻止：pnpm ≥10 默认拦截 git 依赖的构建脚本，

按提示把插件包名加进 profile 的 pnpm-workspace.yaml： ``yaml allowBuilds: dsh-diagon-alley: true ` 然后重新执行 add`。

• 装了但模型看不到角色工具：插件是 host 插件，需要重启 dsh web 才生效。
• dsh 不在 PATH：从源码运行 DSH 时用 pnpm --dir <deepseek-harness仓库> dsh <args>。

🧪 测试

1. 类型检查与构建：npm run build（tsc）必须零错误。 2. 配置层验证：dsh --profile web --dump-config 应能看到 # == dsh-diagon-alley 层。 3. 功能验证（Web）：重启 dsh web 后开一个新会话： - 让模型“列出所有角色”（应调用 list_roles）； - 让模型“切换到苏格拉底”（应调用 switch_role）； - 再提一个思辨类问题，观察回答风格是否符合角色设定。 4. 无 key 冒烟：dsh --profile web --dump-config 不启动也能确认加载链路。

📦 发布

DSH 插件没有官方中央“插件商店”，分发方式即 npm 包 / GitHub 仓库（bundle）。

npm publish    # prepack 会自动先构建 lib/

发布后用户即可 dsh plugin --profile web add dsh-diagon-alley 安装。

备选分发方式：

• tarball：npm pack 产出 dsh-diagon-alley-1.0.0.tgz，用户

dsh plugin --profile web add ./dsh-diagon-alley-1.0.0.tgz。

• GitHub：dsh plugin --profile web add github:<you>/dsh-diagon-alley#<sha>。

git 安装拉取的是源码，靠 prepare 脚本（"prepare": "npm run build"）在安装时构建； pnpm ≥10 首次会要求用户 allowBuilds 放行（见常见问题）。

• 插件目录 / 商店：仓库打上 GitHub dsh-plugin topic 后，会被

dsh-plugin.store（dsh-plugin-hub/dsh-plugin-hub） 自动收录（约 30 分钟）；也可向 awesome-dsh-plugin 精选列表提 PR。

⚠️ 已知限制

• 角色状态目前是进程级的：一个会话切换角色会影响同进程内所有会话（按 agent 作用域隔离是后续工作）。
• 角色 prompt 中的 {{变量}} 会被系统提示词渲染器做严格插值：未注册的变量名会在装配时抛错，

请避免在角色文案中使用 {{...}}。

• replace 模式会连同 DeepSeek Harness 身份段一起替换；如需保留身份提示词，请使用 append 模式。