Outline 知识库助手huangfuren/dsh-outline-auto

dsh-outline-auto

English

DeepSeek Harness 的 Outline 插件：在对话中搜索、读取并在用户审批后创建、更新或删除文档。插件只连接用户配置的 Outline 实例，不携带任何组织内部地址、token、集合名或文档内容。

当前版本：0.7.2。支持的 DeepSeek Harness 基线为 0.1.5-rc.2（设置卡片依赖 settings.installSection），Node.js 需要 22.19 或更高版本；支持 Windows / macOS / Linux 三种平台。

功能

- 搜索、读取、统计文档，并返回可点击的 Outline 链接；支持按作者姓名/邮箱过滤（服务端下推），命中附带作者名。
- 健壮性：429 限流自动重试（指数退避，最多 3 次）；公网地址强制 HTTPS（localhost 与内网私有地址除外）；读取缓存 TTL 可配置（cacheTtlMs，默认 60s）且带条目上限。
- 列出集合、解析“集合/目录/子目录”路径、列出直接子文档。
- 提供通用需求文档模板。
- 创建、更新和删除属于写操作，每次执行前需要用户审批；删除还需要第二次确认。
- 设置卡片位于 设置 -> 插件 -> 插件配置；插件状态位于 设置 -> 插件 -> 插件列表。
- 未配置 Outline 地址或 token 时，插件仍可启动，工具会返回配置提示。

安装

推荐：DSH 管理安装

从公开 GitHub 仓库安装，并固定到最新发布 tag：

dsh plugin --profile web add git+https://github.com/huangfuren/dsh-outline-auto.git#v0.7.0

#v0.7.0 后缀固定到该发布版本；去掉后缀则跟随 main 分支最新提交。

安装后重启 dsh web。发布包已经包含编译后的 lib/，正常从 Git 安装时不依赖用户本地构建。安装钩子只会清理当前 DSH profile 中本插件旧名称 dsh-outline-ai 的残留引用，不会删除或改写其他插件。

交给 AI 安装时，只使用上面的 DSH 插件管理命令，不要再手动追加 cordis.patch.yml 或编辑 dsh.profile.bundles。如果启动错误指向其他插件，应单独修复或禁用错误中点名的插件。

本地 checkout 或解压后的目录可以使用：

dsh plugin --profile web add link:/absolute/path/to/dsh-outline-auto

分发压缩包必须包含 package.json、lib/index.js、client.js、cordis.patch.yml 和 dsh.plugin.json；构建前先执行：

pnpm build

旧版热安装脚本

scripts/hot-install.mjs 只建议用于本地开发。它会创建 profile 链接并追加 patch 行，公开分发不要把它作为标准安装方式。

启动失败恢复

dsh plugin --profile web why dsh-outline-auto

如果报无法解析 dsh-outline-ai，说明 %USERPROFILE%/.dsh/profiles/web/package.json 或 profile 的 cordis.patch.yml 仍有旧名称。重新在受影响的 profile 中安装本包；启用包生命周期脚本时，安装钩子会自动迁移。如果安装时禁用了脚本，请执行：

node node_modules/dsh-outline-auto/scripts/repair-profile.mjs --profile-dir "$env:USERPROFILE/.dsh/profiles/web"

然后运行一次 DSH 插件管理命令刷新 profile lockfile，再重启 dsh web。不要把当前包名改回旧 id。

如果插件已加载但看不到卡片，重启 dsh web，先在插件列表确认 dsh-outline-auto，再打开插件配置。宿主条目失败时不会注册 settings 命名空间。

配置

推荐在 设置 -> 插件 -> 插件配置 中填写：

| 字段 | 说明 |
| --- | --- |
| Service URL | Outline 实例根地址，例如 https://outline.example.com |
| API Token | 在 Outline 的 API keys 页面创建 |
| 可写目录（留空 = 只读） | 逗号分隔的目录路径，如 集合A,集合B/目录1；仅这些目录及其全部子级允许写入 |
| 同义词表（仅配置行） | 插件配置行 synonyms（YAML 映射，如 synonyms: { 部署: [上线, 发布] }）：搜索零命中时按"原词 → 首词 → 同义词"阶梯自动重试 |

也可以使用环境变量 OUTLINE_BASE_URL 和 OUTLINE_API_TOKEN，或在 cordis.patch.yml 的插件配置行中设置。公开包不得把内部集合名写入 schema 默认值、界面文案、测试数据或示例 URL。

v0.3.0 默认只读：未配置可写目录时，所有写工具（outline_create / outline_update_document / outline_delete）直接拒绝执行，连审批弹窗都不会出现。要允许写入，需列出可写的目录：集合B/目录1 覆盖该目录及其全部子级，单独的 集合A 覆盖整个集合。目标路径解析失败（集合不存在、目录不可见、文档被移动）一律拒绝——写入永远 fail-closed。

从 0.2.x 升级：0.3.0 用 writablePaths 白名单取代了 protectedCollections 黑名单。升级后未配置可写目录前所有写入都会被拒绝；之前用黑名单保护的集合，只需不把它列入 writablePaths（未列出 = 不可写）。请删除插件配置行里的 protectedCollections，并把 writablePaths 设为实际要写入的目录。

兼容性与发布检查

- 使用 DSH 0.1.5-rc.2 或更高的同一兼容范围测试；更早版本既没有 settings.installSection，也没有客户端注入兼容保证。
- 执行 pnpm typecheck、pnpm build、pnpm test 和 node scripts/smoke.mjs。
- 压缩包排除 node_modules、.git、settings 文件、token、内部地址和内部文档名称。
- 在干净的 web profile 中安装 GitHub 地址或压缩包，确认插件列表和插件配置两个入口都可见。
- 发布前搜索整个发布目录中的组织专属名称；检查失败就停止发布。

工具

outline_search、outline_get_document、outline_count、outline_list_collections、outline_list_users、outline_resolve_path、outline_list_children、outline_doc_template、outline_save_local、outline_create、outline_update_document 和 outline_delete。

作者过滤（outline_list_users + outline_search 的 author）

- 想找"某人写的文档"时，先调 outline_list_users 拿到成员 id/姓名/邮箱。
- 或直接给 outline_search 传 author=姓名/邮箱：插件会先 outline_list_users 解析（精确唯一→直接用、多匹配→返回候选列表让你确认、无匹配→提示"未找到"），再把 userId 下推到 Outline 服务端过滤——比盲搜后人工挑更高效、更省 token。
- 搜索命中会附带作者名（如 （作者：张三），实例未返回或 users.list 不可用时缺省）。

检索效率与准确度（v0.7.0）

- 搜索缓存：相同关键词（含过滤参数）短 TTL 缓存，同问不重打 API；增删改文档后自动失效。
- all=true 抓全：需要"列出全部相关文档"时让 AI 传 all=true，插件自动翻页（上限 100 篇）并跨页去重；服务端无视 offset 时自动停，不会死循环。
- 本地重排：服务端排序基础上叠加——标题命中权重高于摘要命中，一年内更新的文档有新近度加成（同分保持服务端原序）。
- 零命中回退阶梯：原词 → 首词（多词查询 AND 易落空）→ 同义词表变体（配置 synonyms），命中即停并标注实际生效词。
- 翻页提示：结果未显示完时尾部提示可用 offset / all 继续获取。

本地保存（outline_save_local）

search / get_document 的结果末尾会多一段提示：是否把本次输出整理成 Markdown 文件存到本地，并给出实际存放目录。

- 默认目录：$DSH_HOME/outline-auto-saves（无 DSH_HOME 时回退 $HOME/outline-auto-saves）。
- 可在 设置 → 插件 → 插件配置 → Outline 知识库 卡片的「本地保存目录」中改成任意绝对路径（修改后需重启 web profile）。
- 用户在对话里回复"保存"后，AI 收集相关文档的 id 调用 outline_save_local（参数 ids=文档id列表，逗号分隔，最多 50 篇）：
- 单篇 → 存为 YYYY-MM-DD-标题.md；
- 多篇 → 合并为一个带目录的 Markdown（首篇标题等N篇.md）。
- 同名文件自动追加序号 -2、-3 … 不覆盖。
- 该能力只写本地磁盘，不会向 Outline 知识库写入任何内容。

开发

pnpm typecheck
pnpm build
pnpm test
node scripts/smoke.mjs

真实 Outline 验证脚本需要环境变量 OUTLINE_BASE_URL 和 OUTLINE_API_TOKEN。token 只通过环境变量或用户本机 settings 传入，不要写入仓库。

License

MIT