dsh-diagon-alley

Readme

# 🧙 对角巷 · 角色面具

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

## ✨ 功能

- **🎭 角色切换**：通过 `switch_role` 工具随时切换 AI 人格
  - 按名称/ID：对话里说"切换到千机匠"或"切到 socrates"
  - 按序号：对话里说"切换到第2个角色"（序号对应 `list_roles` 列表顺序，从 1 开始）
- **📋 角色列表**：`list_roles` 查看所有可用角色（含序号、ID、名称、描述）
- **🔍 当前角色**：`get_current_role` 查看当前激活的角色
- **⚙️ 灵活配置**：在配置中自由增删改角色，支持替换 / 追加两种注入模式

## 📦 安装（用户）

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

```bash
# 从 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
```

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

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

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

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

### 🗑️ 卸载

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

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

```bash
dsh --profile web --dump-config
```

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

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

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

```bash
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：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 唯一标识，模型通过它切换 |
| `name` | string | 显示名称 |
| `prompt` | string | 注入到系统提示词的角色文本 |
| `description` | string | 简短描述（可选） |

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

```yaml
- 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）。

```bash
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](https://dsh-plugin.store)（[dsh-plugin-hub/dsh-plugin-hub](https://github.com/dsh-plugin-hub/dsh-plugin-hub)）
  自动收录（约 30 分钟）；也可向
  [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 精选列表提 PR。

## ⚠️ 已知限制

- 角色状态目前是**进程级**的：一个会话切换角色会影响同进程内所有会话（按 agent 作用域隔离是后续工作）。
- 角色 `prompt` 中的 `{{变量}}` 会被系统提示词渲染器做严格插值：未注册的变量名会在装配时抛错，
  请避免在角色文案中使用 `{{...}}`。
- `replace` 模式会连同 DeepSeek Harness 身份段一起替换；如需保留身份提示词，请使用 `append` 模式。