知识中心 lightporta/dsh-knowledge-center

dsh-knowledge-center

v1.8.4 · 2026-10-26 — 共享、条目移动与附件导入的可靠性修复。

知识中心 — 一个 DeepSeek Harness 插件：把工作区文档提炼成可复用的 Markdown 知识，在侧边栏面板与 Settings 中以类 VS Code 的样式渲染，并允许被授权的工作区通过智能体工具使用这些知识。

- 中文文档：跳转
- English documentation: Jump

灵感来自 Qoder / Qoder CN「知识中心」「知识库」「Repo Wiki」「知识卡片」的工作流。这是独立的社区实现，与 Qoder、阿里巴巴或 DeepSeek 的源码无关，也未获其背书或派生自其源码。Qoder 的知识功能为闭源。

本轮可靠性修复与验证：修复进度。Host 更新后需重启 Harness，Client 更新后刷新页面。

简介

dsh-knowledge-center 面向一个很具体的问题：工作区里散落着需求、设计、规范、流程等 Markdown/TXT 文档，模型每次都要重新读取、重新理解。知识中心把这些文档一次性提炼为结构化的知识 Markdown，集中存放在本机知识库中；可以像 VS Code Markdown 预览一样浏览、检索、编辑、导出；在被明确授权的工作区里，模型可以主动调用这些知识。插件提供两个入口：左侧栏的知识图标（打开整页面板，Qoder 风格）与 Settings → 知识中心（同一功能的设置页）。

设计上参考了 Qoder CN 知识中心的交互模型：

| Qoder 知识中心 | 本插件对应实现 |
| 知识库（Knowledge Base），源文件可查看渲染后的 Markdown 或 Markdown 源码 | 「知识库」页签：多知识库、条目列表、渲染/源码切换、复制、下载、编辑保存 |
| Repo Wiki / Knowledge Card：从仓库/文档生成结构化 Markdown 知识 | 「生成知识」页签：扫描工作区文档 → 默认模型提炼 → 存入知识库，同一来源重复生成会更新 |
| 按用户 / 工作区作用域使用，Agent 在任务中自动检索 | 「权限与设置」页签：按工作区授权；模型工具 knowledge_search / knowledge_read / knowledge_ingest / knowledge_ingest_attachment |
| 入口位于侧边栏「知识中心」 | 侧边栏知识图标（整页面板）+ Settings → 知识中心（设置页）。受 Harness 当前版本限制，Settings 左侧导航图标对第三方分区固定回退为齿轮，因此带知识图标的入口是侧边栏面板 |

功能

- 双入口
- 左侧栏知识图标：打开整页「知识中心」面板（自定义书本/知识描边图标，跟随主题与选中态）。
- Settings → 知识中心：同一套页签 UI 的设置页入口（该处导航图标受 Harness 硬编码限制显示为齿轮，详见 FAQ）。
- 从工作区提炼知识
- 扫描工作区中的 Markdown / TXT / CSV / HTML / PDF / Word / Excel / PowerPoint 等文档（完整支持列表见下一节）。
- 逐篇调用 Harness 当前默认模型，生成结构化知识 Markdown：标题、摘要、核心要点、详细内容、适用场景、来源。
- 长文档自动分段提炼再合并（最多 16 段，单篇最多约 192k 字符）。
- 提炼自愈：模型输出被推理 token 占满而截断时，先放大输出预算重试，仍然截断才降级提炼调用的推理强度；因此 reasoningEffort: max 下也能产出完整笔记，智能体自身的推理强度不受影响。
- 同一「工作区 + 来源相对路径」重复生成时更新原条目，不会重复创建。
- 知识库管理
- 支持多个知识库（Knowledge Base），作用域为「用户」「工作区」或「共享」；工作区库只在所属工作区可用，共享库由 owner 授权给指定工作区。
- 条目支持搜索、渲染预览、Markdown 源码查看、复制、下载、在线编辑保存、删除；知识库支持删除（同时删除其条目）。
- 类 VS Code 的 Markdown 渲染
- 标题底边线、行内代码、代码块、引用、表格、任务列表、有序/无序列表、链接、分隔线等。
- 容器、文字、边框、代码块等配色使用 Harness 主题令牌（--dsw-alias-，个别装饰性元素如开关圆点/阴影使用中性色或令牌回退），自动适配明暗主题。
- 库级共享
- 共享库可在「权限与设置」中勾选可见的工作区；owner 在「生成知识」里可以把新笔记直接写进共享库，也可以在条目详情里「移动到…」另一个库。模型工具仍只能写当前工作区库，共享与撤销只由 owner 操作，并留下 grant/revoke 审计。
- 按工作区授权
- 默认所有工作区均未授权；模型工具在未授权工作区会明确拒绝。
- 每个工作区单独开关「允许模型调用」。
- 模型工具与提示词
- knowledge_search / knowledge_read / knowledge_ingest / knowledge_ingest_attachment 四个工具，自带工具卡片；附件工具只处理当前会话 attach 的文件，且只能写入当前工作区库。
- 向模型注入一节系统提示词，说明知识中心能力、权限边界，以及「被拒绝时不要重试、不要绕过」。

支持的文档格式

| 类别 | 扩展名 | 提取方式 |
| 文本 / 标记 | .md .markdown .mdx .txt .rst .csv .json .html .htm .xml .log | UTF-8 直读；HTML 会去除脚本/样式并解码实体 |
| Word（现代） | .docx | 内置 OOXML 提取（ZIP + XML，Node 内建 zlib，无第三方依赖），保留段落、表格文本 |
| Excel（现代） | .xlsx | 内置 OOXML 提取，按工作表输出行文本（共享字符串、数字、布尔） |
| PowerPoint（现代） | .pptx | 内置 OOXML 提取，按幻灯片输出文本 |
| PDF | .pdf | 优先调用可解析到的 pdftotext（可用 PDFTOTEXT_PATH 覆盖路径）；否则使用内置 PDF 文本回退解析器（支持 Flate 压缩流与常见 ToUnicode 映射） |
| 旧版 Office | .doc .xls .ppt | 通过 Harness 内置的 LibreOffice officeToPdf 服务转为 PDF 后走 PDF 提取 |

说明：

- 文本文件上限 10 MiB，二进制文档上限 25 MiB；提取文本上限 40 万字符，随后仍受提炼预算（12k × 16 ≈ 192k 字符）约束。超出提炼预算的部分不送模型，并在 front matter 中标记 truncated: true：10 MiB 级文件可以被接受并提炼预算内的开头部分，而不是整篇逐段精读（那需要数百次模型调用）。
- 各格式提取所需的前置工具与硬性上限见 docs/EXTRACTION.md。
- OOXML/PDF 解压预算为单项 16 MiB、累计 64 MiB；OOXML 忽略未使用的媒体资源。PDF 回退遇到冲突字体映射会明确报错，请使用 pdftotext。
- PDF 只提取文本层；扫描件/纯图片 PDF、Word/PPT 中嵌入图片里的文字不在本次范围（需要 OCR）。
- 旧版 .doc/.xls/.ppt 依赖 Harness profile 中启用的 office-to-pdf（桌面版默认随包提供）；若该服务不可用会给出明确错误。
- 不解析图片、音频、视频；Excel 图表、PPT 备注/图片中的文字不保证提取。

界面

插件提供两个入口，内容一致：

1. 左侧栏知识图标 → 整页面板：自定义知识图标（打开的书本 + 知识星点），页面包含标题区与三个页签。
2. Settings → 知识中心：同样的三个页签；受 Harness 0.2.1-rc.3 的限制，Settings 左侧导航图标由内置 shell 按 section id 硬编码，第三方分区回退为齿轮（这是唯一无法由插件自定义的图标位置，见 FAQ）。

三个页签：

| 页签 | 内容 |
| 知识库 | 知识库筛选、搜索、新建知识库、条目列表、条目详情（渲染 / Markdown 源码 / 编辑）、复制、下载、删除 |
| 生成知识 | 选择工作区 → 扫描文档 → 勾选 → 选择目标知识库与语言 → 逐篇生成，显示进度与每条结果 |
| 权限与设置 | 每个工作区的模型调用开关、生成语言、默认模型、数据目录、工具名、条目统计 |

Markdown 预览采用与 VS Code Markdown 预览接近的排版：14px 正文、h1/h2 底边线、紧凑行内代码块、灰底代码围栏、表格斑马纹、引用左边框等。

环境要求

| 项目 | 要求 |
| DeepSeek Harness | 0.2.1-rc.3 及以上（在 Desktop profile 上验证；Web profile 同样适用） |
| Node.js | ≥ 20.3.0（由 Harness Host 进程提供，插件本身无第三方运行时依赖） |
| 操作系统 | macOS / Windows / Linux（见「跨平台支持」） |
| 模型 | 已在 Harness「Settings → 模型」中配置默认模型（提炼时使用 agentDefaultModel） |

安装

1. 克隆本仓库到任意本地目录：

git clone https://github.com/<you>/dsh-knowledge-center.git

2. 在 Harness 会话中安装本地 bundle（推荐，由 Harness 的 Plugin Manager 完成 profile 安装与启用）：

请使用 plugin_manager 的 install_bundle，把本地目录 /绝对路径/dsh-knowledge-center 安装到当前 profile。

也可以在具备相应权限时直接调用 Harness 的 plugin_manager 工具：

{ "action": "install_bundle", "target": "/absolute/path/to/dsh-knowledge-center" }

3. 安装完成后，在 Settings 左侧会出现 知识中心；若页面已打开但未出现，刷新一次 Harness 页面。

更新：替换仓库文件后，client.js 的改动通常刷新页面即可生效；Host 代码（index.js / lib/）的改动请重启 Harness。Plugin Manager 中禁用再启用可在开发期临时重载，但按 Harness 官方语义，替换已安装包需要重启才能加载新的 JS 模块代际。

卸载：在 Plugin Manager 中移除 dsh-knowledge-center bundle。知识数据不会被自动删除；如需彻底清理，请删除 $DSH_HOME/knowledge-center/（macOS/Linux 通常是 ~/.dsh/knowledge-center/，Windows 通常是 %USERPROFILE%\.dsh\knowledge-center\）。

使用

1. 点击左侧栏的知识图标打开整页知识中心（或打开 Settings → 知识中心）。
2. 选择工作区，点击「扫描文档」，勾选需要提炼的文档，选择目标知识库与生成语言（简体中文 / English），点击「生成知识」。生成由默认模型逐篇完成，耗时取决于文档长度。
3. 切换到「知识库」页签浏览结果：点击条目查看渲染效果；可切换 Markdown 源码、复制、下载、编辑保存或删除。
4. 切换到「权限与设置」，为需要使用知识的工作区打开「允许模型调用」。
5. 在该工作区的会话中直接向模型提问，例如：

请先检索知识中心里关于发布流程的笔记，再按其中的清单检查这次改动。

模型会调用 knowledge_search 找到条目、用 knowledge_read 读取全文，并基于知识回答；只有被授权的工作区才能这样做。

模型工具

| 工具 | 用途 | 参数 | 权限 |
| knowledge_search | 检索知识：标题、摘要、来源、正文关键词；返回 id、标题、知识库、摘要、片段与可访问知识库列表 | query（可空，空则返回最近更新）、limit（1–50，默认 8）、collectionId（可选） | 需授权工作区 |
| knowledge_read | 读取一篇完整知识 Markdown | id | 需授权工作区 |
| knowledge_ingest | 在用户明确要求时，把工作区文档提炼进知识库（每次最多 3 个路径） | paths（工作区相对路径数组）、collectionId（可选）、language（zh / en） | 需授权工作区 |
| knowledge_ingest_attachment | 在用户明确要求时，提炼当前会话附件（每次最多 3 个文件） | path（附件提示中的已保存路径）或 name（匹配当前会话附件），collectionId / language（可选） | 需授权工作区，只能写当前工作区库 |

模型只能在被授权工作区访问该工作区可见的知识：用户库、当前工作区库及 owner 明确共享给该工作区的库。两个提炼工具只能写当前工作区库。工具在未授权工作区会返回明确的权限提示，不会返回任何知识内容。

数据与 Markdown 格式

数据存放在 Harness 的用户级数据目录下（$DSH_HOME，同一台机器的所有 profile 共享；如需隔离可自行设置 DSH_HOME）：

$DSH_HOME/knowledge-center/
├── index.json # 知识库、条目元数据、工作区授权、设置 └── entries/<uuid>.md # 单篇知识：YAML front matter + Markdown 正文

单篇知识示例：

id: "3f0c…"
title: "发布流程" collectionId: "…"
collection: "项目知识库"
sources: ["docs/release.md"]
tags: []
summary: "发布前需要完成的检查项与审批流程。"
language: "zh"
createdAt: 1760000000000
updatedAt: 1760000000000
generator: "provider/model"

发布流程

一句话摘要。

核心要点
- …

详细内容
- …

适用场景
- …

来源
- docs/release.md

知识文件是纯 Markdown，可独立阅读、直接提交到 Git 共享，或交给其他工具处理。front matter 不包含机器绝对路径：工作区路径只保存在本机 index.json，sources 使用工作区相对路径（统一为正斜杠；Windows/macOS 上按大小写不敏感去重），因此知识文件可安全地提交或分享。index.json 保存索引与权限，每次更新前会原子保存上一份有效索引至 index.json.bak。主索引缺失或损坏时会尝试恢复备份，并关闭全部工作区授权、显示恢复提示；备份可能早于最近一次操作。无法恢复且已有数据时会报错保留文件，不会静默重置为空库。此备份不包含知识正文，也不替代完整数据目录备份或版本历史。

权限与安全

- RPC 仅本机 owner：Settings 页面通过 Harness 浏览器连接调用 POST /knowledge-center/<method>；Host 使用 Harness 的连接鉴权（浏览器 Cookie / owner Peer）校验，未认证请求返回 401，非 owner 返回 403。
- 库级共享
- 共享库可在「权限与设置」中勾选可见的工作区；owner 在「生成知识」里可以把新笔记直接写进共享库，也可以在条目详情里「移动到…」另一个库。模型工具仍只能写当前工作区库，共享与撤销只由 owner 操作，并留下 grant/revoke 审计。
- 按工作区授权：默认全部关闭；模型工具只读取「用户作用域 + 当前工作区作用域」的知识。会话子目录归属最具体的已注册工作区，单独注册的嵌套工作区需独立授权，不继承父工作区的授权或专属知识库。
- 数据不离开本机：知识文件只写入 $DSH_HOME，插件不包含任何云同步、遥测或外部上传逻辑；提炼调用的是用户在 Harness 中配置的模型服务。
- 不要把凭证、个人隐私、未授权共享的内容放进工作区文档或知识库。知识文件以明文保存。
- 插件不存储 API Key；模型凭证完全由 Harness 自身管理。

架构

浏览器侧 (client.js) Host 侧 (index.js)
┌─────────────────────────────┐ ┌──────────────────────────────────────┐
│ 侧边栏知识图标 / Settings 页 │ RPC (POST) │ /knowledge-center/<method> │ │ 三页签 UI + Markdown 渲染器 │ ───────────▶ │ owner 鉴权 → API 方法 │ │ 通过 ctx.connection.rpc.call │ ◀─────────── │ 知识库存储 / 文档扫描 / LLM 提炼 │ └─────────────────────────────┘ │ Agent 工具 / 系统提示词 │ └──────────────────────────────────────┘ │ ▼ $DSH_HOME/knowledge-center/ ├── index.json └── entries/<uuid>.md

- Host 半（index.js + lib/paths.js + lib/text.js）：知识库存储（JSON 索引 + Markdown 文件、原子写）、工作区文档扫描（通过 Harness 组合文件系统）、LLM 提炼流水线（单篇直出 / 长文 map-reduce，字符预算 192k）、权限判断、RPC 路由、模型工具与系统提示词。零第三方运行时依赖。
- Client 半（client.js）：浏览器 Cordis 插件，注册三个槽位——sidebar.panellist（左侧栏知识图标）、main（整页知识中心面板）与 settings.section（Settings 设置页）；自研 Markdown→React 渲染器；配色以 Harness 主题令牌为主（装饰性元素使用令牌回退）；通过 ctx.connection.rpc.call 调用 Host。
- 提炼流水线：读取文档 →（长文档）分片提炼要点 → 合并为结构化知识 Markdown → 写入 front matter + 索引；同一来源按（工作区, 相对路径）更新已有条目。
- 工具注册：knowledge_search / knowledge_read / knowledge_ingest / knowledge_ingest_attachment 注册在 Harness Tool Registry，提示词章节说明能力与权限边界。

跨平台支持

插件不依赖任何 macOS 专有 API，Host 代码运行在 Harness 的 Node.js Host 进程中：

| 平台 | 支持 | 说明 |
| macOS | ✅ | 有历史安装、提炼、检索、RPC 与 Settings 注册验证；v1.8.4 发布前在本机通过 152 项回归测试 |
| Windows | ✅ | 使用 win32 路径规则；已完成本机锁修复及历史真实模型、附件流程验证。CI 在 windows-latest 上运行语法、清单及测试 |
| Linux | ✅（CI 覆盖） | 使用 POSIX 路径规则；CI 在 ubuntu-latest 上运行语法、清单及测试；未做真实宿主 GUI 端到端验证 |

跨平台逻辑集中在 lib/paths.js，由仓库测试显式覆盖 win32、darwin 与 POSIX 规则。工作区路径比较仅 Windows 忽略大小写；来源路径先统一为正斜杠，再在 Windows/macOS 忽略大小写去重。数据目录由 DSH_HOME 或 os.homedir() 决定。

v1.8.3 基线已通过三平台 CI；v1.8.4 本轮完成 macOS 本地验证，新提交的三平台结果需在推送后确认。历史实机证据与本轮验证边界见 验证记录 和 测试记录。

已知限制

- 提取为尽力而为：PDF 只提取文本层（扫描件需 OCR）；旧版 Office 需要 LibreOffice 服务；复杂版式（分栏、表格合并、图表）只保留文本顺序，不保留视觉布局。损坏或上传不完整的 OOXML（无 ZIP 中央目录）会明确报错，需重新导出后再试。
- 检索为本地关键词 + 摘要匹配，没有向量嵌入；适合数百篇规模，不适合大规模语义检索。
- 提炼质量与速度取决于 Harness 中配置的默认模型；单篇超长文档只提炼前约 192k 字符，会在 front matter 中标记 truncated: true。
- 本机共享存储使用跨进程锁保护索引读改写，可协调同机多个 profile；不支持多人协作 / 云同步 / 知识正文版本历史。仅对确认退出的本机持锁进程自动回收锁，无法验证时超时并报错。
- Harness 0.2.1-rc.3 的 Settings 导航图标由内置 shell 硬编码，第三方 Settings 分区统一回退为齿轮；插件改用受支持的侧边栏知识图标作为主入口（见 FAQ）。
- 尚未包含自动化 UI 视觉回归测试；v1.8.4 修改后的真实 Harness GUI 全流程待验收。

开发 text dsh-knowledge-center/ ├── index.js # Host 半：存储、扫描、提炼、工具、RPC 路由 ├── lib/paths.js # 跨平台路径工具（POSIX / win32） ├── lib/text.js # 提炼分片的字符预算 ├── lib/extract.js # 文档文本提取（DOCX/XLSX/PPTX/PDF/HTML 等） ├── lib/lock.js # 本机跨进程文件锁与清理 ├── client.js # Client 半：侧边栏图标 + 整页面板 + Settings 页 + Markdown 渲染器 ├── cordis.patch.yml # DSH bundle patch（插入 Host row；Cordis = Harness 插件框架，与 Qoder 无关） ├── locale/ # 插件清单显示标题/描述（en / zh） ├── scripts/ # 跨平台测试与语法检查入口 ├── test/ # 核心回归测试（开发仓库与 CI） ├── docs/ # 提取说明、修复记录与验证边界 ├── test.md # 当前用例清单与历史结果 ├── .github/workflows/ci.yml # 三平台 CI（语法 + JSON + 单测） ├── README.md └── LICENSE bash

无构建步骤、无第三方运行时依赖

npm test # 隔离的核心回归测试
npm run check # 语法、包清单、本地化与路径检查
npm pack --dry-run --ignore-scripts # 发布文件清单

本地开发提示：

- 用 Harness plugin_manager 的 install_bundle 把本目录安装到当前配置档；改动 Host 代码（index.js / lib/）后请重启 Harness。Plugin Manager 的禁用/启用可作为开发期临时重载手段，实际行为以当前 Harness 版本为准。
- client.js 的变化会由页面侧 client HMR 轮询尝试热重载（是否即时取决于 Harness 版本与页面状态）；如未生效，刷新页面。
- 不要改用户配置档的 package.json/cordis.patch.yml 手工安装；交给 Plugin Manager 管理。

测试与验证

测试随仓库发布：npm test 运行 test/.test.mjs，CI 三平台同样执行；用例清单、运行方式与最近结果统一记录在 test.md。npm run check 负责语法、包清单/本地化与本地绝对路径扫描。发布前可用 npm pack --dry-run 核对文件清单。

测试方法、结果、已归档项目与尚未验证的范围统一记录在 验证记录。

常见问题（FAQ）

问：仓库里的 cordis.patch.yml 是 Qoder 的文件吗？
不是。Cordis（@deepseek-ai/cordis）是 DeepSeek Harness 的插件框架；cordis.patch.yml 是 DSH 的 bundle patch，声明安装时要插入的 Host row（id: knowledge-center / name: dsh-knowledge-center），是插件安装与激活的必需文件。本仓库不包含任何 Qoder 代码。

问：为什么 Settings 里「知识中心」前面的图标还是齿轮？
Harness 0.2.1-rc.3 的 Settings 导航图标由内置 shell 按 section id 硬编码（account/models/plugins/agent-presets/archived-sessions），第三方 Settings 分区没有自定义 icon API，统一回退为齿轮。因此插件把定制的知识图标放在官方支持的侧边栏面板入口上；若未来 Harness 暴露 Settings section icon 字段，会切换过去。

问：测试文件会进入插件发布包吗？
不会。核心回归测试保留在开发仓库，供本地与三平台 CI 执行；test/、scripts/ 及本地归档不进入 npm 插件包。用例清单与结果见 测试记录，发布清单可用 npm pack --dry-run --ignore-scripts 核对。

问：知识文件里会不会包含我的绝对路径？
不会。front matter 不含 workspace 绝对路径，sources 是工作区相对路径；绝对路径只保存在本机 index.json。

问：数据会被其他配置档看到吗？
会。数据位于用户级 $DSH_HOME/knowledge-center，同机所有 DSH 配置档共享；需要隔离时可为 Harness 设置独立的 DSH_HOME。

致谢与参考

- 交互灵感：Qoder Knowledge Base、Qoder Repo Wiki、Knowledge Card。
- 同类开源思路：llm-wiki（Qoder Skill 形式的文档→知识 wiki，许可未声明，仅设计参考）、deepwiki-open（MIT）、basic-memory（AGPL-3.0）。
- 本仓库代码为独立实现，MIT 许可。

许可证

MIT © 2026 dsh-knowledge-center contributors

可靠性改动与验证：修复日志。改动 Host 后重启 Harness，改动 Client 后刷新页面。

概览 dsh-knowledge-center 解决一个很具体的问题：需求、设计、约定和流程散落在工作区文档里，模型每做一次任务都要重新读一遍、重新理解一遍。Knowledge Center 把这些文档一次性提炼成结构化知识 Markdown，存进本地知识库，让你用类似 VS Code 的 Markdown 预览来浏览、搜索、编辑和导出，并让明确授权的工作区通过智能体工具使用这些知识。插件有两个入口：侧边栏知识图标（打开整页面板，Qoder 风格）和设置 → Knowledge Center（同一套 UI，作为设置页打开）。

交互模型参考 Qoder CN 的知识功能：

| Qoder Knowledge Center | 本插件 |
| 知识库，源文件可预览为渲染后的 Markdown 或 Markdown 源码 | 「Knowledge Base」标签页：多个知识库、条目列表、渲染/源码切换、复制、下载、编辑并保存 |
| Repo Wiki / Knowledge Cards，从仓库和文档提炼 | 「Generate」标签页：扫描工作区文档 → 用默认模型提炼 → 存入知识库；重新生成同一来源会更新同一条目 |
| 按用户 / 工作区限定使用范围；智能体在任务中检索知识 | 「Access & Settings」标签页：按工作区授权；knowledge_search / knowledge_read / knowledge_ingest / knowledge_ingest_attachment 工具 |
| 侧边栏「Knowledge Center」入口 | 侧边栏知识图标（整页面板）+ 设置 → Knowledge Center。Harness 0.2.1-rc.3 把设置导航图标写死了，第三方分区会回退成齿轮图标，所以自定义知识图标放在受支持的侧边栏面板入口上 |

功能

- 两个入口
- 侧边栏知识图标：打开整页 Knowledge Center 面板（自定义的开卷 + 星芒轮廓图标，跟随主题和选中状态）。
- 设置 → Knowledge Center：同一套标签页 UI，作为设置页打开（那个导航图标是 Harness 的回退齿轮，见 FAQ）。
- 提炼工作区文档
- 扫描工作区文档，包括 Markdown、TXT、CSV、HTML、PDF、Word、Excel 和 PowerPoint（完整列表见下一节）。
- 用 Harness 默认模型生成结构化知识笔记：标题、摘要、要点、详情、适用场景、来源。
- 长文档分块提炼再合并（最多 16 块，每篇文档约 192k 字符）。
- 自愈式提炼：笔记因推理 token 占满输出预算而被截断时，用更大的预算重试，仍不行才用受限的推理强度重试，这样 reasoningEffort: max 也能产出完整笔记，同时不改动智能体自身的推理强度。
- 重新生成同一工作区相对路径的来源时，更新已有笔记，不会重复创建。
- 知识库管理
- 多个知识库，作用域分为 user、workspace 或 shared；workspace 库只留在所属 workspace 内，shared 库需要所有者显式授权给指定 workspace。
- 条目支持搜索、渲染预览、Markdown 源码视图、复制、下载、就地编辑和删除；库可以删除（连同其条目一起删）。
- 类 VS Code 的 Markdown 渲染
- 标题下划线、行内代码、围栏代码、引用、表格、任务列表、有序/无序列表、链接、分隔线。
- 容器、文本、边框和代码颜色取自 Harness 主题 token（--dsw-alias-，少数装饰元素如开关旋钮/阴影带 token 回退），因此浅色和深色主题自动生效。
- 库级共享
- 在 Access & Settings 里可以把 shared 库授权给指定 workspace；所有者可以直接把笔记生成到 shared 库，或用「Move to…」移动已有笔记。模型工具仍然只写入当前 workspace 库，共享与撤销仅限所有者操作，并留有授权/撤销审计。
- 按 workspace 的访问控制
- 每个 workspace 默认拒绝；没有授权时模型工具拒绝运行。
- 每个 workspace 一个开关（「Allow model access」）。
- 模型工具与提示词段落
- knowledge_search、knowledge_read、knowledge_ingest、knowledge_ingest_attachment，各带一张工具调用卡片。附件工具只接受当前会话里附带的文件，并写入当前 workspace 库。
- 系统提示词里有一段说明这项能力和权限边界，包括「访问被拒绝时不要重试或绕过」。

支持的文档格式

| 类别 | 扩展名 | 提取方式 |
| 文本 / 标记 | .md .markdown .mdx .txt .rst .csv .json .html .htm .xml .log | 按 UTF-8 读取；HTML 会去掉 script/style 并解码实体 |
| Word（新版） | .docx | 内置 OOXML 提取（ZIP + XML，走 Node 的 zlib，无第三方依赖）；保留段落和表格文本 |
| Excel（新版） | .xlsx | 内置 OOXML 提取；每个工作表行输出一行（共享字符串、数字、布尔值） |
| PowerPoint（新版） | .pptx | 内置 OOXML 提取；每张幻灯片输出一节 |
| PDF | .pdf | 优先使用可解析到的 pdftotext 二进制（PDFTOTEXT_PATH 可覆盖路径）；否则用内置回退解析器（Flate 流、常见 ToUnicode 映射） |
| 旧版 Office | .doc .xls .ppt | 由 Harness 的 LibreOffice officeToPdf 服务转成 PDF，再走 PDF 管线提取 |

说明：
- 文本文档上限 10 MiB，二进制文档上限 25 MiB；提取出的文本上限 400k 字符，之后还要受蒸馏预算约束（12k × 16 ≈ 192k 字符）。超出预算的内容不会发给模型，并在 front matter 中标记 truncated: true：10 MiB 的文件会被接受，但只从预算内的开头部分做蒸馏，而不是从头读到尾（那样需要数百次模型调用）。
- 各格式提取器的前置条件和硬性限制见 docs/EXTRACTION.md。
- OOXML/PDF 解压上限为每个条目/流 16 MiB，总计 64 MiB。未使用的 OOXML 媒体会被跳过。PDF 回退路径中字体映射冲突会给出明确错误；这类文件请改用 pdftotext。
- PDF 提取只读文本层；扫描件/纯图片 PDF，以及嵌入图片里的文字（Word/PPT），都需要 OCR，不在支持范围内。
- 旧版 .doc/.xls/.ppt 需要在 Harness 配置档中启用 office-to-pdf 服务（Desktop 自带）；服务不可用时会返回明确错误。
- 图片、音频、视频不解析；Excel 图表、PPT 备注/图片里的文字不保证能提取。

UI

插件提供两个入口，内容相同：

1. 侧边栏知识图标 → 整页面板：自定义知识图标（打开的书 + 知识火花）、标题区和三个标签页。
2. Settings → Knowledge Center：同样的三个标签页。Harness 0.2.1-rc.3 按 section id 硬编码 Settings 导航图标，第三方 section 回退为齿轮图标（这是插件唯一无法自定义的图标位；见 FAQ）。

三个标签页：

| 标签页 | 内容 |
| Knowledge Base | 库筛选、搜索、新建库、条目列表、条目详情（渲染视图 / Markdown 源码 / 编辑器）、复制、下载、删除 |
| Generate | 选工作区 → 扫描文档 → 勾选 → 选目标库和语言 → 逐个蒸馏，显示进度和每个文件的结果 |
| Access & Settings | 按工作区的模型访问开关、输出语言、默认模型、数据目录、工具名、库统计 |

预览效果贴近 VS Code 的 Markdown 预览：正文 14px，h1/h2 带下划线，行内代码是紧凑的小色块，围栏代码块用弱化配色，表格斑马纹，引用块左侧有竖线。

环境要求

| 项目 | 要求 |
| DeepSeek Harness | 0.2.1-rc.3 或更新（已在 Desktop 配置档上验证；Web 配置档行为相同） |
| Node.js | ≥ 20.3.0，由 Harness Host 进程提供（插件没有第三方运行时依赖） |
| 操作系统 | macOS / Windows / Linux（见「跨平台」） |
| 模型 | 在 Harness「Settings → Models」中配置默认模型（蒸馏使用 agentDefaultModel） |

安装

1. 克隆仓库：

bash
git clone https://github.com/<you>/dsh-knowledge-center.git
2. 在 Harness 会话里安装本地 bundle（推荐；插件管理器负责配置档的安装与启用）：

用 plugin_manager 的 install_bundle，把本地目录 /absolute/path/to/dsh-knowledge-center 装进当前配置档。

或者，在权限足够时直接调用 Harness 的 plugin_manager 工具：

json
{ "action": "install_bundle", "target": "/absolute/path/to/dsh-knowledge-center" }

3. 之后侧边栏会显示 Knowledge Center 图标（设置里也会出现 Knowledge Center 页面）。如果页面已经打开，刷新一次即可。

升级：替换仓库文件后，client.js 的改动刷新页面即可生效；Host 侧的改动（index.js / lib/）需要重启 Harness。开发过程中，在插件管理器里禁用再启用插件可以临时重载，但按 Harness 插件契约，替换已安装的包后必须重启，才能加载新的 JS 模块代际。

卸载：在插件管理器里移除 dsh-knowledge-center bundle。知识数据不会自动删除；要彻底清除，请删掉 $DSH_HOME/knowledge-center/（macOS/Linux 上是 ~/.dsh/knowledge-center/，Windows 上是 %USERPROFILE%\.dsh\knowledge-center\）。

使用

1. 点击侧边栏的知识图标打开整页 Knowledge Center（也可以打开设置 → Knowledge Center）。
2. 选一个工作区，点扫描文档，选择文件，选好目标知识库和语言（简体中文 / English），再点生成。默认模型会逐篇提炼文档，耗时取决于文档长度。
3. 打开知识库标签页浏览结果：点条目看渲染后的预览，可切换到 Markdown 源码、复制、下载、编辑或删除。
4. 打开访问与设置，为需要使用这些知识的工作区开启允许模型访问。
5. 在该工作区的会话里，让模型使用知识，例如：

在 Knowledge Center 里搜一下我们的发布流程笔记，然后拿这份清单核对本次改动。

模型会调用 knowledge_search 查找条目，调用 knowledge_read 读取完整笔记——仅限已授权的工作区。

模型工具

| 工具 | 用途 | 参数 | 权限 |
| knowledge_search | 按标题、摘要、来源和正文关键词搜索知识；返回 id、标题、知识库、摘要、片段以及可访问的知识库列表 | query（可为空 → 返回最新笔记）、limit（1–50，默认 8）、collectionId（可选） | 需要已授权的工作区 |
| knowledge_read | 读取一篇完整的知识 Markdown 笔记 | id | 需要已授权的工作区 |
| knowledge_ingest | 用户明确要求时，把工作区文档提炼进知识库（每次调用最多 3 个路径） | paths（工作区相对路径数组）、collectionId（可选）、language（zh / en） | 需要已授权的工作区 |
| knowledge_ingest_attachment | 用户明确要求时，提炼当前会话的附件（每次调用最多 3 个文件） | path（附件提示词中保存的路径）或 name（匹配会话附件），可选 collectionId / language | 需要已授权的工作区；只写入它所在工作区的知识库 |

模型只能访问用户知识库、自己工作区的知识库，以及所有者明确共享给该工作区的知识库。两个提炼工具都只写入当前工作区的知识库。没有授权时，工具会报出明确的权限提示并失败，不返回任何知识内容。

数据与 Markdown 格式

数据存放在 Harness 的用户级数据目录下（$DSH_HOME，机器上所有配置档共用；需要隔离就设置 DSH_HOME）：

$DSH_HOME/knowledge-center/
├── index.json # libraries, entry metadata, workspace grants, settings
└── entries/<uuid>.md # one knowledge note: YAML front matter + Markdown body

笔记示例： markdown

id: "3f0c…"
title: "Release Process"
collectionId: "…"
collection: "Project Knowledge"
sources: ["docs/release.md"]
tags: []
summary: "Pre-release checks and the approval flow."
language: "en"
createdAt: 1760000000000
updatedAt: 1760000000000
generator: "provider/model"

Release Process

One-sentence summary.

Key points

- …

Details

- …

When to use it

- …

Sources

- docs/release.md

知识文件就是纯 Markdown：能单独阅读，能提交到 Git，也能给其他工具使用。front matter 不含机器绝对路径：工作区路径留在本地 index.json 里，sources 存的是工作区相对路径，用正斜杠（在 Windows/macOS 上按大小写不敏感去重）。所以笔记可以放心提交或分享。index.json 保存索引和权限；每次更新都会把上一个有效索引原子性地保留为 index.json.bak。主文件缺失或损坏时，可以从这份备份恢复，同时禁用所有工作区授权并显示恢复提示。备份可能早于最近的操作。已有数据无法恢复时，会保留数据并报错，而不是悄悄重置知识库。这份索引备份不含笔记正文，也不能替代整目录备份或版本历史。

权限与安全

- 仅所有者可调用的 RPC：设置页通过 Harness 浏览器连接调用 POST /knowledge-center/<method>；Host 用 Harness 连接认证（浏览器 Cookie / 所有者 Peer）校验。未认证请求返回 401，非所有者请求返回 403。
- 按工作区授权：默认拒绝；模型工具只读取用户范围加当前工作区范围内的知识。子目录中的会话归属最具体的已注册工作区。单独注册的嵌套工作区需要独立授权，不继承父工作区的知识库。
- 数据留在本地：知识文件只写入 $DSH_HOME 下；插件不含云同步、遥测或外传逻辑。蒸馏使用 Harness 里配置的模型服务。
- 绝不摄入凭据、个人数据或你无权分享的内容。 知识文件以明文存储。
- 插件不保存 API key；模型凭据仍归 Harness 所有。

架构 text
Browser (client.js) Host (index.js)
┌─────────────────────────────┐ ┌──────────────────────────────────────┐
│ Sidebar icon / Settings page│ RPC (POST) │ /knowledge-center/<method> │
│ 3-tab UI + Markdown renderer│ ───────────▶ │ owner auth → API methods │
│ ctx.connection.rpc.call │ ◀─────────── │ library storage / scan / LLM distill │
└─────────────────────────────┘ │ agent tools / system prompt │
└──────────────────────────────────────┘
│
▼
$DSH_HOME/knowledge-center/
├── index.json
└── entries/<uuid>.md

- Host half (index.js + lib/paths.js + lib/text.js): library storage (JSON index + Markdown files, atomic writes), workspace document scanning through the composed Harness filesystem, LLM distillation (single-shot or map-reduce for long documents, 192k-character budget), permission checks, RPC route, agent tools and the system-prompt section. Zero third-party runtime dependencies.
- Client half (client.js): a browser Cordis plugin registering three slots — sidebar.panellist (sidebar knowledge icon), main (full-page Knowledge Center panel) and settings.section (Settings page); a self-contained Markdown-to-React renderer; theme-token-driven colors (with token fallbacks for decorative elements); Host calls through ctx.connection.rpc.call.
- Distillation pipeline: read document → (for long documents) distill chunk notes → merge into one structured Markdown note → write front matter + index; re-ingesting the same (workspace, relative path) updates the existing entry.
- Tool registration: knowledge_search, knowledge_read, knowledge_ingest, knowledge_ingest_attachment register in the Harness Tool Registry; the prompt section explains the capability and permission boundary.

Cross-platform

The plugin uses no macOS-specific API; the Host half runs in Harness's Node.js Host process:

| Platform | Support | Notes |
| macOS | ✅ | Historical install, distillation, retrieval, RPC and Settings checks; all 152 local regression tests pass for v1.8.4 |
| Windows | ✅ | Uses win32 path rules; local lock regression checks and historical live-model/attachment flows verified. CI runs syntax, manifest checks and tests on windows-latest |
| Linux | ✅ (CI coverage) | Uses POSIX path rules; CI runs syntax, manifest checks and tests on ubuntu-latest; no real Harness GUI end-to-end verification |

Platform-sensitive logic is centralized in lib/paths.js, with repository tests explicitly covering win32, darwin and POSIX rules. Workspace paths compare case-insensitively only on Windows; source paths use forward slashes and case-insensitive deduplication on Windows/macOS. The data directory comes from DSH_HOME or os.homedir().

The v1.8.3 baseline passed CI on all three platforms. This v1.8.4 round is locally verified on macOS; CI for the new commit must be confirmed after pushing. Historical live evidence and current limits are in the verification log and test record.

Known limitations

- Extraction is best-effort: PDF reads the text layer only (scanned documents need OCR); legacy Office requires the LibreOffice service; complex layouts keep text order but not visual structure. Corrupted or incompletely uploaded OOXML (no ZIP central directory) fails with a clear error and must be re-exported.
- Retrieval is local keyword/summary matching with no vector embeddings; suitable for hundreds of notes, not for large-scale semantic search.
- Distillation quality and speed depend on the configured default model; very long documents are distilled from roughly the first 192k characters and marked truncated: true in the front matter.
- Local shared storage uses a cross-process lock for index updates across profiles on the same machine. No team collaboration, cloud sync or note-body revision history. Lock recovery requires a confirmed exited local owner; an unverifiable owner causes a timeout instead of stealing the lock.
- Harness 0.2.1-rc.3 hardcodes Settings nav icons; third-party Settings sections fall back to a gear, so the plugin uses the supported sidebar knowledge icon as its primary entry (see FAQ).
- No automated UI visual regression tests yet; the v1.8.4 changes still need a real Harness GUI walkthrough.

Development
text
dsh-knowledge-center/
├── index.js # Host half: storage, scanning, distillation, tools, RPC route
├── lib/paths.js # cross-platform path helpers (POSIX / win32)
├── lib/text.js # distillation chunk character budget
├── lib/extract.js # document text extraction (DOCX/XLSX/PPTX/PDF/HTML, …)
├── lib/lock.js # local cross-process file lock and cleanup
├── client.js # Client half: sidebar icon + full-page panel + Settings page + Markdown renderer
├── cordis.patch.yml # DSH bundle patch (inserts the Host row; Cordis is Harness's plugin framework, unrelated to Qoder)
├── locale/ # plugin inventory title/description (en / zh)
├── scripts/ # cross-platform test and syntax-check entry points
├── test/ # core regression tests (development repository and CI)
├── docs/ # extraction guide, repair log and verification limits
├── test.md # current test inventory and historical results
├── .github/workflows/ci.yml # three-platform CI (syntax + JSON + tests)
├── README.md
└── LICENSE
bash

No build step, no third-party runtime dependencies.

npm test # isolated core regression tests
npm run check # syntax, manifest, locales and path checks
npm pack --dry-run --ignore-scripts # release inventory

Development notes:

- Install this directory with Harness plugin_manager install_bundle. After Host code changes (index.js / lib/), restart Harness; disabling/enabling the plugin can temporarily reload during development, subject to the current Harness version.
- client.js changes are picked up by page-side client HMR polling and hot-reloaded when the version/page state allows; refresh the page if necessary.
- Do not hand-edit the user profile's package.json / cordis.patch.yml to install; let Plugin Manager own installation.

Testing and verification

Tests ship with the repository: npm test runs test/.test.mjs and CI executes it on all three platforms; the inventory, how to run it and the latest results live in test.md. npm run check validates syntax, manifest/locales and scans for local absolute paths. Use npm pack --dry-run to inspect the release inventory.

Methods, results, archived checks and verification limits are recorded in the verification log.

FAQ

Q: Is cordis.patch.yml a Qoder file?
No. Cordis (@deepseek-ai/cordis) is DeepSeek Harness's plugin framework; cordis.patch.yml is a DSH bundle patch that declares the Host row to insert (id: knowledge-center / name: dsh-knowledge-center). It is required for installation and activation. This repository contains no Qoder code.

Q: Why is the Settings nav icon for Knowledge Center still a gear?
Harness 0.2.1-rc.3 hardcodes Settings nav icons by section id (account/models/plugins/agent-presets/archived-sessions); third-party Settings sections have no icon API and fall back to a gear. The plugin therefore places its custom knowledge icon on the officially supported sidebar panel entry; if a future Harness exposes a Settings section icon field, we will switch.

Q: Are test files included in the plugin package?
No. Core regression tests remain in the development repository for local runs and three-platform CI. The npm plugin package excludes test/, scripts/ and local archives. See the test record for the inventory and results, and use npm pack --dry-run --ignore-scripts to inspect the release files.

Q: Do knowledge files contain my absolute paths?
No. The front matter has no absolute workspace path; sources are workspace-relative. Absolute paths stay in the local index.json.

Q: Will other profiles on this machine see the data?
Yes. Data lives in the user-level $DSH_HOME/knowledge-center, shared by every DSH profile; set a separate DSH_HOME if you need isolation.

Acknowledgements

- Interaction inspiration: Qoder Knowledge Base, Qoder Repo Wiki, Knowledge Card.
- Related open-source ideas: llm-wiki (a Qoder Skill that distills documents into a wiki; no declared license, design reference only), deepwiki-open (MIT), basic-memory (AGPL-3.0).
- This repository is an independent implementation under the MIT license.

License

MIT © 2026 dsh-knowledge-center contributors