huangfuren/dsh-outline

English

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

当前版本：0.8.0。支持的 DeepSeek Harness 基线为 0.1.5-rc.2（设置卡片依赖 settings.installSection），Node.js 需要 22.19 或更高版本；原生支持 Windows / macOS / Linux 三大平台，经过全量跨平台兼容性测试（152+ 单元测试）。

功能

• 搜索、读取、统计文档，并返回可点击的 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.git#v0.8.0

#v0.8.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

分发压缩包必须包含 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

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

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

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

如果插件已加载但看不到卡片，重启 dsh web，先在插件列表确认 dsh-outline，再打开插件配置。宿主条目失败时不会注册 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 设为实际要写入的目录。

跨平台兼容性

本插件经过全面测试，原生支持 Windows、macOS 和 Linux 三大平台。所有关键代码路径均采用平台无关的实现模式，无需用户手动配置或额外适配。

Windows 兼容性亮点

• ✅ 自动处理反斜杠输入习惯：在「可写目录」和「路径解析」功能中，用户输入 集合A\目录1（使用 Windows 标准的反斜杠）会被自动归一化为 集合A/目录1，避免误判。
• ✅ 文件名安全化：本地保存时自动替换文件系统非法字符（\ / : * ? " < > |），并保护 Windows 保留设备名（CON、NUL、COM1-9、LPT1-9）不被误用。
• ✅ MAX_PATH 路径长度保护：在 Windows 默认路径限制（260 字符）下，超长文档标题会被自动截断到安全长度（保留 .md 扩展名），确保不会因路径过长导致保存失败。
• ✅ 错误提示可操作：文件系统错误（ENOENT、EACCES、ENOSPC 等）会翻译为用户可理解的中文提示，并根据平台给出针对性建议（例如 Windows 提示"路径过长"，macOS 提示"目录不存在"）。
• ✅ 环境变量回退链：$DSH_HOME → $USERPROFILE → $HOME → 当前工作目录，自动适配 Windows 用户主目录位置。

macOS / Linux 兼容性亮点

• ✅ IPv6 回环地址支持：http://[::1]:3000 形式的本地 IPv6 地址被正确识别为私有地址，不会误拒。
• ✅ 大小写不敏感文件系统：APFS（macOS 默认）和 ext4（Linux 可选）的 case-insensitive 模式下，文件去重逻辑正确处理大小写差异，不会产生冲突。
• ✅ LF/CRLF 行尾透明：Markdown 内容始终使用 LF（\n），跨平台打开无显示异常。
• ✅ UTF-8 Unicode 规范化：支持 NFD（macOS）和 NFC（Windows/Linux）两种 Unicode 规范化形式的文件名，emoji 与 CJK 字符均可正常保存。
• ✅ POSIX 路径限制：macOS 和 Linux 的路径长度限制（通常 1024+ 字符）远高于 Windows，无需截断保护。

已知边界情况（非缺陷）

场景	行为	影响
macOS 大小写不敏感	Test.md 与 test.md 被视为同一文件，去重时会生成 test-2.md	✅ 设计如此，避免覆盖
Windows MAX_PATH 260	超长标题被自动截断到约 100-150 个中文字符	✅ 保护机制生效
Legacy 记事本	Windows 10 之前的记事本打开 LF 文件显示异常	⚠️ 请使用 VS Code / Notepad++
iOS / Android	不支持（Node.js 22.19+ 无法在移动系统运行）	⚠️ 请使用 macOS/Windows/Linux 桌面系统

---

兼容性与发布检查

• 使用 DSH 0.1.5-rc.2 或更高的同一兼容范围测试；更早版本既没有 settings.installSection，也没有客户端注入兼容保证。
• 执行 pnpm typecheck、pnpm build、pnpm test（152 个单元测试，包含跨平台边界用例）和 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 知识库写入任何内容。

安全

所有写操作都要经过 DSH 原生审批与按部署配置的可写目录白名单，两者均 fail-closed：审批服务不可用、闸门内部异常、目标路径无法解析，一律拒绝而不是放行。公开实例必须使用 HTTPS（本机回环与内网私网地址豁免），API token 只保存在 DSH 设置层，不会出现在工具返回值、日志或浏览器端；outline_delete 不可恢复，因此需要二次确认。本地 Markdown 落盘被限制在配置的保存目录内，并按平台做了文件名与路径长度加固。

完整的威胁模型与漏洞上报方式见 SECURITY.md。

开发

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

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

License

MIT