dsh-outline-auto
DSH 网页插件：从对话中搜索和阅读 Outline 知识库，并支持经过批准且受白名单保护的文档写入。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:huangfuren/dsh-outline-auto#b13e278886e526de3583f15a5ab8ec69e24dbda8Outline Auto 以 dsh-outline-auto 发布，当前版本为 0.7.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A DeepSeek Harness plugin that searches and reads an Outline knowledge base from your conversation. Give it a keyword — it returns matching documents with titles, snippets, and links; ask for one of them and it returns the full content in Markdown. Approved write tools can create, update, and delete documents, with an approval prompt before every write.
Project status: 0.7.2. The current feature set is covered by unit tests, a Mock-server smoke, and a settings-chain integration check. The supported DSH baseline is
0.1.5-rc.2(settings.installSectionis required for the settings card); older Harness builds are not certified.
outline_search accepts an author name/email that resolves against outline_list_users and is pushed down to Outline as a server-side userId filter; hits carry the author's display name when available.baseUrl (Outline returns relative paths); snippets and titles are cleaned of HTML tags so results render cleanly in chat.cacheTtlMs and the cache has an entry cap to bound memory.Retry-After, otherwise exponential backoff capped at 5s).https:// (localhost and private intranet addresses are exempt) so the API token is never sent in clear text.baseUrl and API token, click save, done.$DSH_HOME/settings.yaml, never in git); ideal for team distribution.| Component | Baseline |
|---|---|
| Platform | Windows / macOS / Linux |
| Node.js | 22.19 or newer |
| DeepSeek Harness | 0.1.5-rc.2 (required baseline) |
| Outline instance | reachable from your machine (intranet / VPN), with an API token (Outline → Settings → API keys) |
Install from the public GitHub repository, pinned to the latest release tag:
dsh plugin --profile web add git+https://github.com/huangfuren/dsh-outline-auto.git#v0.7.0
The #v0.7.0 suffix pins the exact release; omit it to track the latest commit on main.
Restart dsh web after installation. The published package contains the built lib/ directory, so a normal Git install does not depend on a local build step. Its install hook only removes stale references to this plugin's old package name (dsh-outline-ai) from the selected DSH profile; it does not remove or rewrite unrelated plugins.
For an AI-assisted installation, use the DSH plugin manager command above and do not manually add a second cordis.patch.yml entry or edit dsh.profile.bundles. If startup still fails and the error names another plugin, repair or disable that named plugin separately.
For a local checkout or extracted archive:
dsh plugin --profile web add link:/absolute/path/to/dsh-outline-auto
The directory must contain package.json, lib/index.js, client.js, cordis.patch.yml, and dsh.plugin.json. Build the package before distributing an archive:
pnpm build
The scripts/hot-install.mjs flow is intended for local development only. It creates a profile link and a patch row, so keep the checkout in a stable directory. Do not use it as the public distribution instructions.
dsh plugin --profile web why dsh-outline-auto
If startup reports that it cannot resolve dsh-outline-ai, an older renamed entry remains in %USERPROFILE%/.dsh/profiles/web/package.json or the profile cordis.patch.yml. Reinstall this package in the affected profile; the install hook migrates the stale references when package lifecycle scripts are enabled. For a profile where scripts were disabled, run this explicit repair:
node node_modules/dsh-outline-auto/scripts/repair-profile.mjs --profile-dir "$env:USERPROFILE/.dsh/profiles/web"
Then run the DSH plugin manager once to refresh the profile lockfile before restarting dsh web. Do not rename the current package back to the old id.
If the package loads but the card is absent, restart dsh web, open Settings → Plugins, check Plugin list for dsh-outline-auto, then check Plugin configuration. A failed host entry will not expose its settings namespace.
The recommended way is the GUI card (Settings → Plugins → plugin configuration → Outline Knowledge Base):
| Field | Description |
|---|---|
| Service URL (baseUrl) | Outline instance root, e.g. https://outline.example.com |
| API Token | create one at Outline → Settings → API keys |
| Writable paths (empty = read-only) | comma-separated directory paths, e.g. Collection A,Knowledge Base/Dir 1; only these directories and their children are writable |
| Local save directory | local directory where outline_save_local writes Markdown files; empty = $DSH_HOME/outline-auto-saves (fallback $HOME/outline-auto-saves). Restart the web profile after changing |
| Synonyms (config row only) | synonyms in the plugin config row (YAML map, e.g. synonyms: { 部署: [上线, 发布] }): on a zero-hit search the plugin retries with mapped words (ladder: original → first word → synonyms) before giving up |
Click Save — applies immediately. Alternatively, configure via environment variables (OUTLINE_BASE_URL / OUTLINE_API_TOKEN) or the plugin config row in cordis.patch.yml. Advanced options in the plugin config row: timeoutMs (request timeout, default 15000), cacheTtlMs (read-cache lifetime in ms, default 60000, range 1000–300000) and synonyms (see above; config-row only, restart to reload).
Read-only by default (v0.3.0): with no writable paths configured, all write tools (outline_create / outline_update_document / outline_delete) refuse to run — no approval prompt is even shown. To allow writes, list the directories that may be modified. A path like Knowledge Base/Dir 1 covers every child under Dir 1; a bare Collection A covers the whole collection. Any path that cannot be resolved (missing collection, invisible directory, moved document) is refused — writes always fail closed.
The public package must not contain organization-specific collection names, URLs, tokens, or document examples. Deployment-specific values are configured per installation — never publish an internal collection name as a schema default or UI placeholder.
0.3.0 removes the protectedCollections deny-list in favor of the writablePaths allow-list. After upgrading, every write is refused until you configure writable paths. If you previously protected a collection via the deny-list, simply leave it out of writablePaths — a collection that is not listed is not writable. Delete the old protectedCollections setting from your plugin config row, then set writablePaths to the directories you actually write to.
| Tool | Description |
|---|---|
outline_search(query, limit?, offset?, collectionId?, author?, userId?, updatedAfter?, all?) | Keyword search; returns the match total, plus title, snippet, document id, author name and link per hit. Optional filters: collection, author (name/email — resolved via users.list and pushed down server-side as userId; ambiguous names return the candidate list), updated-after; offset skips the first N hits for pagination; all=true auto-paginates and de-duplicates up to 100 hits. Identical queries are short-TTL cached (invalidated by writes); multi-word queries with zero hits automatically retry with the first word. |
outline_get_document(id, maxLength?) | Fetch a document's full Markdown by id; maxLength caps the returned text (default 20000). |
outline_count() | Total number of documents in the knowledge base (documents.list total, exact; excludes trashed/deleted — the true total may be slightly higher). |
outline_list_collections() | List visible collections (id, name, permission, document count). |
outline_list_users() | List workspace users (id, name, email) — resolve "documents by 张三" into the author/userId filter for outline_search. |
outline_resolve_path(path) | Resolve a human path like Knowledge Base/Directory A/Subdirectory into collectionId + parentDocumentId; returns the resolved full path. |
outline_list_children(parentId) | List direct child documents of a directory (parent document). |
outline_doc_template() | Return the standard requirement-document template (Markdown) + required section list — call it before writing a requirement doc. |
outline_save_local(ids, title?) | Local save — write one or many fetched Outline documents to a local Markdown file. ids is a comma-separated list from search results (up to 50); multiple docs merge into one file with a table of contents. Filename YYYY-MM-DD-title.md (single doc → its title, many → 首篇标题等N篇); auto-increments on name clash, never overwrites. Writes only to local disk; never touches the knowledge base. Search/get_document results end with a prompt offering this. |
Writes are restricted to the writable paths configured per deployment (read-only when empty). The public package ships with no organization-specific default.
See the full SOP: docs/workflow-requirement-doc.zh.md — locate the directory (outline_resolve_path) → fetch the template (outline_doc_template) → draft → create with approval → verify.
pnpm typecheck, pnpm build, pnpm test, and node scripts/smoke.mjs.lib/, client.js, both manifests, the patch, and public documentation; exclude node_modules, .git, settings files, tokens, internal URLs, and internal document names.web profile and confirm both Settings -> Plugins -> Plugin list and Plugin configuration.pnpm typecheck # strict tsc check
pnpm build # emit lib/
pnpm test # vitest unit tests (mock fetch: success/empty/401/403/404/429/network/bad response)
node scripts/smoke.mjs # local Mock Outline server, end-to-end smoke (prints SMOKE PASS)
node scripts/verify.mjs # real settings → search → count chain (add --create for the create+cleanup chain)
The client half (client.js) is a dependency-free single-file module — no build step. The real-search verification script requires OUTLINE_BASE_URL / OUTLINE_API_TOKEN env vars.
outline_create(collectionId, title, text, publish?, parentDocumentId?) | Write — create a document (default published; nest under a directory via parentDocumentId). Requires approval showing the resolved full path. |
outline_update_document(id, title?, text?) | Write — update a document's title/body. Requires approval showing the document path. |
outline_delete(id) | Write, irreversible — delete a document. Double approval: a first prompt, then a second confirmation before deletion. |