dsh-talebook-plugin

Readme

# dsh-talebook-plugin

为 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) 提供 Talebook 工具。插件把现有 Talebook Skill 的 API 约定、风险门禁和核验规则接入 DSH，并通过随包发布的 Python CLI 访问 Talebook 实例。

## 要求

- Node.js 22 或更高版本
- Python 3（Windows 默认通过 `py -3` 启动，其他平台默认使用 `python3`）
- DSH `0.1.1-rc.2` 或同一 `0.1.x` 兼容版本（依赖 `settings.plugin.item` 的 keyed 槽契约）
- 一个可访问的 Talebook 实例

## 配置

插件可以在没有连接信息时正常加载。安装并启动 DSH 后，打开 **设置 → 插件 → 插件配置 → Talebook**，在展开的卡片中配置：

- **Talebook 地址**：已保存的地址会显示在输入框里，可直接修改；留空并保存会清除它。
- **用户名（可选）**：已保存的用户名会显示在输入框里，可直接修改；只改用户名会保留原密码。留空并保存会清除整个登录信息（用户名和密码一起清除，之后以 guest 身份访问）。
- **密码**：隐藏字段，只写入 DSH 凭据存储，浏览器无法读回原值；留空表示保持当前密码，输入新值并保存才会更新。

首次设置账号（尚无已存密码）时，输入用户名需要同时输入密码。只读浏览可以完全省略用户名和密码。

地址和用户名保存在 DSH 设置文档中（可读、可回填、可直接编辑）；密码是唯一的机密，只存在于凭据存储中，不会进入聊天记录或插件配置文件。未配置（或环境变量缺失/为空）时插件仅在被调用时给出配置提示，不会影响 DSH 启动。

原有环境变量方式继续兼容，适合无 UI、容器和 CI 部署：

```bash
export TALEBOOK_URL="https://books.example.com"
export TALEBOOK_USERNAME="your-username"
export TALEBOOK_PASSWORD="your-password"
```

生效值按 **设置文档 → 插件配置 → 环境变量** 的顺序解析；由环境变量提供的字段会在配置界面显示「由环境变量提供」。

插件 schema 还提供 `timeoutSeconds`、`pythonExecutable`、`maxOutputBytes` 和 `checkUpdates` 配置项。默认值适合常规部署；Windows 如果未安装 `py` launcher，可把 `pythonExecutable` 覆盖为 `python`。需要覆盖这些运行参数时，在 profile 自己的 `cordis.patch.yml` 中重写完整的 `talebook` 行，因为 DSH patch 对同一行的 `config` 是整体替换而不是深合并。

## 本地构建与打包

克隆本仓库后运行：

```bash
git clone https://github.com/hehetoshang/dsh-talebook-plugin.git
cd dsh-talebook-plugin
pnpm install
pnpm run typecheck
pnpm test
pnpm run pack
```

`python/talebook_cli.py` 是随包发布的 Talebook CLI。它的上游来源是
[`talebook/skills`](https://github.com/talebook/skills/blob/master/skills/talebook/scripts/talebook-cli.py)；同步上游改动时应替换该文件，并重新运行类型检查、插件测试和 Skill evals。

## 安装到 DSH

使用上一步生成的 tarball：

```bash
dsh plugin --profile web add ./dsh-talebook-plugin-0.2.6.tgz
dsh --profile web --dump-config
dsh --profile web
```

本地开发时也可直接安装插件目录：

```bash
pnpm run build
dsh plugin --profile web add .
```

也可以直接从 GitHub 安装，或固定到指定 commit。仓库提交了与源码同步的 `lib/` 构建产物，并且不会运行安装期构建脚本，因此不需要配置 pnpm `allowBuilds`：

```bash
dsh plugin --profile web add github:hehetoshang/dsh-talebook-plugin
dsh plugin --profile desktop add github:hehetoshang/dsh-talebook-plugin
dsh plugin --profile web add github:hehetoshang/dsh-talebook-plugin#<commit-sha>
```

bundle 的 `cordis.patch.yml` 使用稳定行 ID `talebook`。用户可在 profile 的 patch 中以同一 ID 覆盖配置。

## 工具概览

插件注册 12 个工具。每个工具通过明确的 `action` 和结构化参数选择动作，不接受任意 shell 命令或原始 argv：

| 工具 | 能力 |
|---|---|
| `talebook_status` | 查看站点、当前身份与公开权限 |
| `talebook_account` | 查看或修改个人资料与设备 |
| `talebook_books` | 搜索、详情、上传、下载、编辑、收藏、书架、阅读状态与发送 |
| `talebook_audios` | 列出、查看或下载已发布有声书 |
| `talebook_remote` | 管理 Legado 书源，执行远程搜索、浏览与保存 |
| `talebook_admin_users` | 管理用户 |
| `talebook_admin_books` | 管理员书库列表、元数据补全、格式转换与批量删除 |
| `talebook_admin_imports` | 扫描并导入书籍 |
| `talebook_admin_booksources` | 管理网络书源 |
| `talebook_admin_opds` | 浏览 OPDS、管理 OPDS 源与导入任务 |
| `talebook_admin_settings` | 管理系统设置、邮件、数据库与更新检查 |
| `talebook_admin_system` | 管理回收站、SSL、主题与日志 |

## 与 Talebook Skill 配合

[`talebook/skills` 中的 Talebook Skill](https://github.com/talebook/skills/tree/master/skills/talebook) 仍是 Agent 的操作流程和风险规范；其中的 `references/` 记录 API 与多步工作流，`scripts/talebook-cli.py` 是本仓库随包 CLI 的上游来源。DSH 插件在这套服务端行为之上提供模型可调用的强类型工具。

更新 CLI 或风险分类时，应同时运行 Skill evals 与本仓库测试。本仓库的 `tests/fixtures/mock_talebook.py` 可在没有真实服务器的情况下提供集成测试实例。

## 安全门禁

- 只读操作直接执行。
- 上传、收藏、书架和阅读状态等常规写入必须来自用户明确请求。
- 发送到邮箱或设备、管理员写入、删除和批量操作会先生成 `confirmation.required` 脱敏预览，再交给 DSH approval；只有 approval 返回一次性许可后工具主体才会执行，模型参数中不存在 `confirmed` 开关。
- Talebook 登录密码通过 DSH credentials API 只写保存，配置界面和模型都无法读回；环境变量方式仍兼容。
- 修改密码、SMTP 测试和数据库连接等敏感参数只接受环境变量名引用，秘密值不会进入工具调用参数或 Python 子进程命令行。
- 写操作前应先通过搜索或列表解析唯一 ID，不猜测书籍、用户、书源或任务 ID。
- 写入后应调用相应只读操作核验；异步任务只报告已启动和任务 ID，不把入队表述为完成。
- 插件不会绕过 Talebook 的登录与权限检查，也不会恢复 CLI 已脱敏的密码、token、API key 或访问码。

## 许可证

[MIT](LICENSE)