前言¶
用 DeepSeek Harness（DSH）做项目时，会话会落在本机 harness 的 sessions 目录里。若要把这些对话沉淀成可检索的知识，常见做法是手工整理 Markdown 再上传到 RAG 知识库；官方只读插件 @wxg-prc-cpg/dsh-weknora 提供了从 WeKnora 检索的能力，但没有写入侧。维护者 AAAlenwow 的 dsh-weknora-archive（GitHub：AAAlenwow/dsh-weknora-archive，社区目录分类为「记忆」）是 host 端插件，负责把 DSH 会话增量归档进你自托管的 WeKnora 知识库，并在 v0.4.0 起用轮询解析状态做「真实入库」核验，可选生成本地 three.js 入库星图报告。
下面介绍插件定位、工具能力、安装配置与典型用法。
这是什么¶
dsh-weknora-archive 是 DSH 的写入侧互补插件：扫描本机会话 → 解压与提取对话 → 启发式总结（可选 LLM 精炼）→ 按标题去重后上传到 WeKnora → 在观察窗口内轮询文档解析状态，写入仅含元数据的 archive-manifest.json。当前版本 0.4.0，许可证 MIT，要求 Node >=24.0、DSH >=0.1.7-alpha.1，profile 为 web。
会话数据只发往你配置的 WeKnora 实例；API key 经 redactConfig() 脱敏，不写入日志或工具结果。
核心功能¶
与官方只读插件的关系¶
| 方向 | 插件 | 能力 |
|---|---|---|
| 读 | @wxg-prc-cpg/dsh-weknora |
4 个检索工具 |
| 写 | dsh-weknora-archive |
归档、上传、状态核验、本地报告 |
v0.4.0 重点¶
- 真实入库状态闭环：HTTP 上传成功不等于入库成功。上传后按返回的文档 id 在
parseObservationMs窗口内轮询解析状态，归档清单中记为completed/parsing/failed；窗口内未完成记parsing，不高报为成功。 archive-manifest.json：每次运行原子写入~/.dsh/plugin-data/dsh-weknora-archive/reports/（可通过reportDir配置），只含标题、状态、项目、KB id 等元数据，不含会话正文、API 地址或密钥。weknora_archive_visualize：把清单渲染为自包含的本地 three.js「知识入库星图」HTML（内嵌 three.js，无 CDN、file://可直接打开）。WebGL 不可用或系统prefers-reduced-motion时降级为静态报告；报告失败只告警，不影响归档。设WEKNORA_ARCHIVE_VISUALIZATION=false可关闭。
工具一览¶
工具名前缀默认 weknora_archive，可通过 toolPrefix 修改。
| 工具 | 说明 |
|---|---|
weknora_archive_auto |
扫描本机所有 DSH 项目，按项目名匹配/新建知识库并增量归档；已归档跳过；单项目失败不影响其余；适合定时任务；支持 project_keyword、dry_run |
weknora_archive_session |
归档指定项目会话：定位目录 → 解压 → 提取 → 总结 → 标题去重上传；库不存在则按项目名新建；首次附 00_项目总览.md；支持 dry_run |
weknora_archive_status |
只读：本机会话项目与会话数、目标库已归档文档及解析状态 |
weknora_archive_list_knowledge_bases |
只读：列出凭据可见的知识库 |
weknora_archive_create_knowledge_base |
新建知识库（新库可能需在 WeKnora 端配置 embedding，否则解析失败） |
weknora_archive_visualize |
只读：将最近一次或指定归档清单渲染为本地星图 HTML，不上传、不改归档状态 |
安装与启用¶
插件通过 DSH 官方插件机制安装。README 给出的命令如下（将 /path/to/dsh-weknora-archive 换成本地插件目录路径）：
node "/Applications/DSH Desktop.app/Contents/Resources/app/node_modules/@deepseek-ai/dsh/lib/bin.js" \
plugin --profile web add /path/to/dsh-weknora-archive
Linux 或其他安装路径下，应使用本机 DSH 对应的 bin.js 路径，参数含义不变：plugin --profile web add 指向插件 bundle 目录。
配置走 bundle 自带的 cordis.patch.yml，默认从环境变量读取，key 不落地、不入库。常用项如下。
| 字段 | 环境变量 | 说明 |
|---|---|---|
baseUrl |
WEKNORA_ARCHIVE_BASE_URL |
WeKnora 部署地址 |
apiKey |
WEKNORA_ARCHIVE_API_KEY |
具备写入/摄取能力的 scoped API key |
knowledgeBaseId |
WEKNORA_ARCHIVE_KB_ID |
可选；缺省按项目名自动匹配/新建 |
sessionsDir |
WEKNORA_ARCHIVE_SESSIONS_DIR |
可选；缺省探测 <harness>/sessions |
embeddingModelId |
WEKNORA_ARCHIVE_EMBEDDING_MODEL_ID |
强烈建议：自动新建库时携带的 embedding 模型 id，不设则新库文档易 parse_status=failed |
reportDir |
WEKNORA_ARCHIVE_REPORT_DIR |
归档清单目录，默认 ~/.dsh/plugin-data/dsh-weknora-archive/reports |
parseObservationMs |
WEKNORA_ARCHIVE_PARSE_OBSERVATION_MS |
上传后观察解析的时间窗，默认 60000 |
visualization |
WEKNORA_ARCHIVE_VISUALIZATION |
设 false 跳过清单/报告生成 |
LLM 精炼需 llmBaseUrl、llmApiKey、llmModel 三者同时配置才开启；失败回退启发式总结，不影响归档。启发式总结不足约 200 字符时不发模型请求。
WeKnora 侧认证头为 X-API-Key（非 Bearer）；若 API 与插件内置路由不一致，需按实际部署调整 lib/client.js。
典型用法¶
单项目归档或预览¶
在 DSH 对话中让智能体调用 weknora_archive_session；先加 dry_run 可预览将上传的标题与目标库，确认后再正式归档。
全机增量与定时无人值守¶
调用 weknora_archive_auto（不带 dry_run）。去重按知识库内文档标题判定，重复执行幂等。
README 推荐的每日提醒配方：在 DSH 建定时提醒（例如 22:00），prompt 示例：
调用 weknora_archive_auto 工具（不要带 dry_run），把返回的汇总原样转告我；有失败项目的列出失败原因。
若修改过 toolPrefix，提醒里的工具名需改用对应前缀（如 my_prefix_auto）。
查看入库与星图¶
weknora_archive_status：核对本机项目与会话、库内文档解析状态。weknora_archive_visualize：打开生成的自包含 HTML，查看带真实解析状态的入库星图。
本地单测（无需网络与凭证）：
npm test
适用场景与注意¶
适合：已在自托管 WeKnora 上跑 RAG，希望把 DSH 各项目会话自动沉淀到按项目划分知识库、并区分「已上传」与「已解析入库」的开发者。
务必注意：
- 插件以当前 DSH 进程权限运行，安装前应阅读源码与 MIT 许可证，确认凭据与 sessions 目录访问范围可接受。
- 新建库的 embedding 可能在 WeKnora 端单独配置；PUT 接口会静默丢弃 embedding 字段，务必设置
WEKNORA_ARCHIVE_EMBEDDING_MODEL_ID或在服务端补全。 - 正在运行的会话可能解压失败会被跳过，下次归档可补上。
- 总结默认为启发式抽取；配置
llm*后仅为精炼，总结文本会发往你指定的模型服务商。 - 社区插件目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本插件为社区维护条目。
结尾¶
dsh-weknora-archive 把 DSH 会话增量写入自托管 WeKnora，并用解析状态轮询与本地归档清单、可选 three.js 星图，补齐官方只读检索插件之外的写入与核验链路。进一步说明与配置表见 GitHub README：
- 目录页：https://www.skillhub.cn/plugins/AAAlenwow/dsh-weknora-archive
- 仓库：https://github.com/AAAlenwow/dsh-weknora-archive
