知识复习库 HeWhenJay/dsh-project-knowledge-review

dsh-project-knowledge-review

一个面向中文 DSH 用户的独立本地知识复习插件。

它把文字资料、OCR 图片文字和 ASR 音频转写保存到 DSH 用户目录，在回答知识问题前先检索本地 evidence；严格模式下没有足够证据就明确拒答。插件不需要数据库、向量模型、账号登录或项目 Token，也不会连接、安装或识别任何外部项目。

主要能力

- 零配置本地资料库：首次使用时自动创建 v2 存储。
- Evidence-first 问答：先检索，再根据 evidence 回答；严格模式证据不足即拒答。
- 当前 DSH 模型作答：插件只提供检索 evidence 和系统约束，最终答案仍由当前会话模型生成。
- Markdown 摘要：文字、OCR、ASR 入库后立即生成 Markdown 自动提要；自动过滤导入元数据、RAG 模板和纯时间戳，也可用当前 DSH 模型回写更好的 Markdown 摘要。
- 两级分类：插件自动生成系统初分类，用户可在知识库页面建立并调整自己的二次分类。
- 一级知识库页面：侧栏点击“知识库”进入独立工作区，可查看详细摘要和详细原始内容。
- 安全 Markdown 预览：摘要与原始内容都支持渲染视图和 Markdown 源码视图；不执行 HTML 或脚本。
- 可选 OCR / ASR：默认关闭，只有用户显式开启并配置 DSH 凭据后才访问对应服务。
- 大库友好：轻量 JSONL 索引、单文档原文文件、游标分页和按需原文读取。
- 键盘友好：阅读标签支持方向键切换，抽屉支持 Escape 关闭与焦点返回，并遵循“减少动态效果”偏好。
- v1 自动迁移：旧版整库 JSON 会迁移到 v2，并保留不可覆盖的原始备份。

3 分钟快速上手

第 1 步：安装插件

dsh plugin --profile web add dsh-project-knowledge-review

安装后重新启动当前 DSH Web 进程并刷新页面。成功后可以看到：

- 侧栏出现“知识库”，位置在“工作区”上方；
- “设置”页面出现“知识复习”；
- 新会话可以使用 project_knowledge_ 工具。

第一次使用不需要配置数据库、向量模型、账号或 Token。默认使用“知识库仅供参考”：仍会先检索本地资料，再把知识库证据与模型补充分区展示。

回答策略：reference 资料库：~/.dsh/project-knowledge-review/knowledge.json OCR：关闭 ASR：关闭

第 2 步：添加第一份资料

在任意 DSH 对话中直接粘贴你有权使用的文字，例如：

把下面内容加入知识库，标题是“RAG 证据检索入门”，来源是“我的学习笔记”：

RAG 在生成回答前先检索资料库。严格模式要求回答引用资料标题与来源；当前知识库没有足够证据时，应明确拒答。

插件会调用 project_knowledge_add_text，保存原文并返回：

- 资料 ID；
- Markdown 自动提要；
- 摘要来源；
- 系统初分类；
- 本地保存结果。

请只导入自己编写、公开授权或已确认有权使用的资料。

第 3 步：打开知识库阅读

点击侧栏“知识库”，即可搜索资料、按系统分类或个人分类浏览，并在“摘要 / 原始内容”和“渲染 / Markdown 源码”之间切换。

知识库主阅读界面

界面分为三个按需区域：

- 左侧资料导航：搜索、系统分类、个人分类和资料列表；
- 中间阅读画布：显示完整摘要或按需读取原始内容；
- 右侧资料信息：点击顶部“资料信息”后打开，不会永久挤占正文。

第 4 步：建立自己的分类

在左侧点击“新建分类”，创建例如“RAG 入门”“前端复习”等目录。选择一份资料后，打开“资料信息”，即可修改“我的分类”。

资料信息与个人分类

系统初分类用于解释插件最初如何归类；“我的分类”由你控制，两者互不覆盖。

第 5 步：基于证据复习

回到对话后这样提问：

根据我的知识库解释 RAG 为什么需要引用证据。

插件会先调用 project_knowledge_search。只有返回了 evidence，当前 DSH 模型才会基于证据回答，并引用资料标题与来源。

默认 reference 模式会固定区分：

知识库内容基于本地 evidence 的结论；未命中时明确说明知识库没有相关资料。

模型补充当前模型提供的通用知识，不冒充知识库结论。

如果你希望资料里没有答案就完全拒答，可以在“设置 → 知识复习”切换为 strict。

常用操作速查

| 想做什么 | 对 DSH 说什么 |
| 添加文字资料 | 把下面内容加入知识库，标题是“……”：…… |
| 基于知识库复习 | 根据我的知识库解释…… |
| 查看资料数量 | 我的知识库有多少份资料？ |
| 查看保存位置 | 知识库资料保存在哪里？ |
| 检查项目隔离 | 知识库是否与当前项目共享？ |
| 改进自动提要 | 请根据这份资料生成更准确的 Markdown 摘要并回写 |

查询数量、标题、来源、存储位置或共享范围时，插件调用 project_knowledge_overview。作用域始终是当前 DSH 用户的本地资料库，sharedWithCurrentProject 始终为 false。

知识库页面行为

“知识库”入口采用与“任务看板”一致的侧栏按钮规格，并固定放在“工作区”区块之前。知识库打开后，点击任意对话、设置、任务看板、SSH、文件树或其他外部功能都会自动退出知识库，并让原点击继续生效。任务看板或 SSH 打开时点击知识库，也会在同一次点击中退出原面板并进入知识库；从知识库点击任务看板或 SSH 也能单击反向切换。

窄屏下，资料导航和资料信息会变成抽屉，正文使用完整可用宽度。阅读标签支持方向键切换，抽屉支持 Escape 关闭与焦点返回。

页面只借鉴主流文档与知识产品的信息架构，不复制第三方品牌或素材。

回答策略

strict

- 知识问题必须先检索。
- 只有 answerStatus=ANSWERED 且 evidence 非空时才能回答。
- 只陈述 evidence 支持的结论。
- 没有证据时必须明确说明：当前知识库中没有足够证据，不能回答。
- 不使用模型记忆补齐知识结论。

reference（默认，界面显示“知识库仅供参考”）

- 仍先检索知识库。
- 允许当前模型补充通用知识。
- 必须明确区分“知识库证据”和“模型补充”。

可以在“设置 → 知识复习”中切换策略。

工具

插件公开以下 DSH 工具：

| 工具 | 用途 |
| project_knowledge_overview | 查询数量、标题、来源、存储位置、作用域和共享状态 |
| project_knowledge_search | 检索本地 evidence |
| project_knowledge_add_text | 添加用户提供或确认有权使用的文字资料 |
| project_knowledge_update_summary | 用当前 DSH 模型生成的 Markdown 摘要更新一份资料 |
| project_knowledge_import_image_ocr | 对公开图片 URL 执行 OCR 后入库 |
| project_knowledge_import_audio_asr | 对公开直链音频执行 ASR 后入库 |

工具名为了保持已有 DSH 会话兼容而保留 project_knowledge_ 前缀；这不表示插件会连接任何外部项目。

本地 v2 存储

默认路径：

~/.dsh/project-knowledge-review/knowledge.json

同目录还会出现：

knowledge.json # 常数大小 manifest knowledge.json.index.jsonl # 元数据与检索 token 轻量索引 knowledge.json.documents/ # 每份资料一个 JSON 原文文件 knowledge.json.categories.json # 用户二次分类 knowledge.json.locks/ # 多进程 ticket 锁 knowledge.json.journal.json # 中断恢复日志，仅写入期间存在 knowledge.json.v1.backup*.json # v1 迁移备份（如有）

v2 的设计目标：

- 列表和概览不加载全量原文。
- 原文按单条 ID 哈希文件名直接定位。
- 写入和元数据更新使用跨进程 ticket 锁。
- journal 中断恢复保持清单、JSONL 索引和单条原文一致。
- 单次预览、请求体和媒体文件均有大小限制。

OCR 与 ASR

OCR / ASR 默认关闭。启用步骤：

1. 打开“设置 → 知识复习”。
2. 开启对应服务。
3. 配置 Base URL 与模型名称。
4. 将 API Key 保存到 DSH 凭据库。

安全边界：

- 只接受公开 HTTP(S) 图片 URL，或公开可直接下载的音频 URL。
- 拒绝 URL 用户信息、非 HTTP(S) 协议、本机地址和私有网络地址。
- API Key 不写入插件设置 JSON，也不会回显。
- 插件不自动处理视频网页分享页；请提供字幕文字或公开音频直链。

设置项

| 设置 | 默认值 | 说明 |
| enabled | true | 关闭后工具和提示词保持静默 |
| answerPolicy | reference | 默认“知识库仅供参考”；可切换为严格 strict |
| localStorePath | ~/.dsh/project-knowledge-review/knowledge.json | 插件自己的本地资料库 |
| projectName | 我的知识库 | 用户可见名称；仅是命名，不是外部项目 |
| requestTimeoutMs | 120000 | OCR / ASR 请求超时 |
| ocrEnabled | false | 是否启用 OCR |
| ocrBaseUrl | DashScope OpenAI 兼容地址 | OCR 服务地址 |
| ocrModel | qwen-vl-ocr | OCR 模型 |
| ocrApiKeyEnv | DSH_KNOWLEDGE_OCR_API_KEY | DSH 凭据引用名 |
| asrEnabled | false | 是否启用 ASR |
| asrBaseUrl | OpenAI API 地址 | ASR 服务地址 |
| asrModel | whisper-1 | ASR 模型 |
| asrApiKeyEnv | DSH_KNOWLEDGE_ASR_API_KEY | DSH 凭据引用名 |

隐私与发布边界

- 插件独立发布、独立运行、独立存储。
- 插件没有项目 URL、项目 API Key、配对码、能力文件或项目安装逻辑。
- 插件不会主动向外部项目同步资料。
- 插件摘要和分类只属于插件本地库。
- 如果个人项目希望使用这些资料，应由该项目在自己的服务端实现主动、只读同步；这不属于本插件的公共能力。

开发

npm install
npm test
npm run typecheck
npm pack --dry-run

npm test 会先清理并重建 lib/，防止删除过的旧功能残留在发布包中。

License

MIT