hehetoshang/dsh-talebook-plugin

dsh-talebook-plugin

为 DeepSeek Harness（DSH） 提供 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 部署：

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 是整体替换而不是深合并。

本地构建与打包

克隆本仓库后运行：

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；同步上游改动时应替换该文件，并重新运行类型检查、插件测试和 Skill evals。

安装到 DSH

使用上一步生成的 tarball：

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

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

pnpm run build
dsh plugin --profile web add .

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

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#

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 仍是 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