前言¶
在 DeepSeek Harness（DSH）里做智能体工作流时，常会希望模型能用到你已通过订阅获得的内容。知识星球（zsxq）的帖子多在 App 内，正文又常藏在 docx、PDF 等附件里，历史内容难以全文检索；若要在电脑上阅读或交给 Agent 处理，往往只能手工导出。社区插件 dsh-plugin-zsxq 把「同步帖子与附件 → 抽取正文与图片 → 建索引 → 检索」放在 DSH 侧完成，数据落在本地目录，纯 JavaScript 实现，README 写明不依赖 Python、外部服务或遥测。
这是什么¶
dsh-plugin-zsxq 由维护者 zhangcaiqian 发布，在 SkillHub 目录 中归类为「工作流」。当前 npm 包版本为 0.1.0（见仓库 package.json），许可证 MIT。插件向 DSH Agent 暴露七个类型化工具，用于初始化知识库、校验 Cookie、同步、重建索引与检索；可选搭配 companion skill（仓库 README 中的安装示例为 github:zhangcaiqian/zsxq-skill）约定分类、摘要与引文等 enrichment 流程。
核心功能¶
下面按 README 中可核对的能力简述。
同步与抽取¶
一次同步可覆盖当天、指定日期、整月、条数或话题标签等模式（由 zsxq_sync 的 mode 等参数控制）。同步会拉取帖子与附件，对 docx 抽取段落与内嵌图片，对 PDF 抽取页文本（含 CJK，via bundled CMaps）与页图 PNG；帖子内图片保留远程签名 URL；带 inline_article_url 的文章帖会将 HTML 转为纯文本。音频类附件以下载为主，README 标明转录不在范围内。
本地检索与 Agent 工具¶
在本地 index.json 上支持关键词、标签、频道、分类、日期等检索。七项工具职责如下（是否与磁盘交互见 README 表格）：
| Tool | 作用 |
|---|---|
zsxq_init |
创建数据目录与 config.json 模板 |
zsxq_doctor |
校验 Cookie、汇报可达星球、检查索引健康 |
zsxq_list_channels |
列出已配置频道 |
zsxq_status |
文章/引文数量、索引陈旧度、同步状态 |
zsxq_search |
在本地索引上检索 |
zsxq_sync |
同步帖子、附件与抽取文本，按 topic id 去重 |
zsxq_rebuild_index |
重建 INDEX.md、index.json 及各类 by-* 索引 |
README 中的安全约束包括：count 上限 30（更大分页会被知识星球 API 拒绝）；整月 refresh 需显式 confirmDestructive 且仅单频道，会删除该月本地文件（含 enrichment）；依赖 .synced_ids 保证同步幂等。
数据布局¶
默认数据根目录为 $DSH_HOME/zsxq-kb，可通过配置项 dataDir 或环境变量 ZSXQ_BASE_DIR 覆盖。典型结构：
<dataDir>/
├── config.json
├── channels/<channel>/<YYYY>/<MM>/<DD>/<title>.md
├── assets/...
├── data/raw/...
└── index/...
config.json 含 Cookie 与 channels 映射，README 要求勿提交版本库、勿贴入聊天或 Issue。
安装与启用¶
安装后需重启 DSH（插件模块不支持热加载）。官方 README 给出的命令如下。
# npm（推荐）
dsh plugin --profile web add dsh-plugin-zsxq
# 或从 GitHub 源码安装
dsh plugin --profile web add github:zhangcaiqian/dsh-plugin-zsxq
# 本地开发时 link
dsh plugin --profile web add link:/path/to/dsh-plugin-zsxq
DSH Desktop 用户可从 Settings → Plugins 安装；若用 CLI，需将 DSH_HOME 指向桌面版 harness 目录，否则插件会装到另一 profile。
可选 companion skill（用于 enrichment 约定，非必需）：
dsh plugin --profile web add github:zhangcaiqian/zsxq-skill
package.json 声明 DSH 引擎范围为 >=0.2.0-rc.2 等区间，Node >=20。
可在 profile 的 cordis.patch.yml 中配置插件行 zsxq-tools，例如：
- id: zsxq-tools
name: dsh-plugin-zsxq
config:
dataDir: /Users/you/knowledge-base
可调字段还包括 requestIntervalMs（默认 1500）、syncTimeoutMs（默认 900000）、indexTimeoutMs（默认 120000）。
典型用法¶
按 README Quick start，建议顺序如下。
-
让 Agent 执行初始化：例如说明「initialize the zsxq knowledge base」，对应
zsxq_init，在默认或已配置的dataDir下创建channels、assets、data、index及config.json模板。 -
配置 Cookie：在浏览器登录 wx.zsxq.com，开发者工具 Network 中筛选
api.zsxq.com，从请求头复制完整Cookie，写入数据目录下的config.json：
{ "zsxq_cookie": "zsxq_access_token=…; abtest_env=product", "channels": {}, "tag_to_category": {} }
Cookie 约一个月失效时工具可能返回 HTTP 401（ZSXQ_COOKIE_EXPIRED），需重新复制并覆盖。可用 zsxq_doctor 做一次真实 API 校验且不回显 Cookie。
-
选择要同步的星球：经
zsxq_doctor确认账号可达的星球后，在config.json的channels中填入name、group_id、default_scope等。 -
同步：例如「sync today’s posts」→
zsxq_sync，mode=today。 -
enrichment、索引与检索：由 Agent 按 skill 或工具说明填写
topic_category、摘要、.quotes.md等，再「rebuild the index」→zsxq_rebuild_index，检索示例为「search the knowledge base for …」→zsxq_search。
适用场景与注意¶
适合已在 DSH 中使用 Agent、且长期订阅多个知识星球、希望把付费内容沉淀为本地 Markdown 并做全文检索的开发者或个人用户。插件在当前 DSH 进程权限下运行，会向知识星球 API 发起请求并读写本地目录；安装前宜自行查看 GitHub 源码 与 MIT 许可证，确认 Cookie 与数据路径符合你的安全策略。
SkillHub 为社区插件目录，与 DeepSeek / 幻方无 README 所述的官方从属关系；DSH 生态奉行「一切皆插件」，本插件是工作流类扩展之一。截至资料抓取时，GitHub 仓库星标约为 1。
结尾¶
dsh-plugin-zsxq 把订阅内的帖子与附件同步到自选本地目录，完成 docx/PDF 抽取与索引检索，便于在 DSH 里用 Agent 整理与查询知识星球内容。目录页：https://www.skillhub.cn/plugins/zhangcaiqian/dsh-plugin-zsxq；源码与文档：https://github.com/zhangcaiqian/dsh-plugin-zsxq。
