dsh-discussions-digest

Readme

# dsh-discussions-digest

面向 DevRel 的 DeepSeek Harness 社区工作台，用于持续维护官方 [`deepseek-ai/deepseek-harness` Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions)。

`0.4.0` 提供固定范围的批量 AI 整理、可恢复任务、全文阅读、批量建议检查和持久报告。原有快速摘要与单帖深读保留；GitHub 操作全部只读。

## 功能与分工

| 插件提供的确定性能力 | DSH 中的 AI 负责 |
| --- | --- |
| 近期同步、历史分页回填、断点与覆盖信息 | 选择需要深读的帖子，控制阅读范围 |
| 持久保存状态、下一步、笔记、已读标记 | 从源材料提取事实与待补信息，提出跟进建议 |
| 创建/编辑主题，保存多对多归组与共享笔记 | 建议关联，说明相同点和差异；经用户指示后归组 |
| 计算统计、时间队列、每日观察和 Markdown 导出 | 解读统计、生成带来源的中英文简报 |

AI 不自行编造计数、共同根因、维护者响应率或已验证结论。生成报告不会自动改变处理状态。插件不调用另一个模型 API，不自动发 GitHub 评论，不提供定时后台巡检。

## 安装与版本

需要 Node.js `^22.19.0` 或 `>=24`、DSH `0.1.2-rc.1`。当前 `0.4.0` 尚未发布到 npm，请构建并安装本地包。

插件版本独立于 DSH 版本，按插件自身的功能和兼容性变化递增。`0.4.0` 是插件版本，`0.1.2-rc.1` 是已验证的 DSH 兼容基线；DSH 发布新版本不会自动触发插件升版。

- 在 `0.x` 阶段，兼容修复递增修订号（如 `0.3.1`）；新增功能或不兼容变更递增次版本号（如 `0.4.0`）。不兼容变更必须在 CHANGELOG 明确说明，并在涉及台账数据时提供迁移说明。
- `alpha`、`beta`、`rc` 仅在插件自身需要分发预览或候选版本时使用，不继承 DSH 的预发布后缀。去掉后缀不意味着已经发布到 npm，也不代表 `0.x` 的接口已长期稳定；公共契约稳定后再进入 `1.0.0`。
- DSH 兼容性通过依赖声明和本文的验证基线表达。当前 DSH 包保持精确版本，验证新宿主后再调整兼容声明，不预先承诺未经验证的版本。
- 台账 schema version 独立管理；只有存储格式变化才调整，插件升版不自动改变 schema version。

```powershell
cd C:\Users\joell\.dsh\plugins\dsh-discussions-digest
npm ci
npm test
npm pack
npx --yes --package @deepseek-ai/dsh@0.1.2-rc.1 dsh plugin --profile web add .\dsh-discussions-digest-0.4.0.tgz
```

安装后重启你使用的 DSH Web 进程，再重新打开它打印的认证 URL：

```powershell
npx --yes --package @deepseek-ai/dsh@0.1.2-rc.1 dsh web
```

这是 bundle 安装方式，不需要再向 `cordis.patch.yml` 手工插入第二个实例。已有同名插件时，上面的 `add` 用本地新包更新。不要在同一个 DSH home 上同时运行两个写入同一台账的进程。

安装时，profile 包管理器可能提示由 DSH 宿主提供的 peer dependencies；实际兼容性通过 DSH 的 profile 加载验证。普通 `npm ci` 用于本仓库开发，所需类型和依赖由锁文件固定。

v0.3 的基础接口已与本地 DSH 源码 `0.1.3-alpha.1`（`d347e703908d0406b7a7ef80e3a0e594d86b2215`）对照：Storage Domain 的 `open/global/close`、工具与 Skill 注册、WebServer route、Connection 的 `requestRejection`、Slots 的 `inject/register`、`sidebar.footer.action` 和客户端 bundle 协议都能在 npm `0.1.2-rc.1` 使用。不要求从源码构建 DSH，也不承诺未经验证的未来版本兼容性。

v0.4 新增会话连接以 npm `@deepseek-ai/dsh-api-session-controller@0.1.2-rc.1` 的公开 Client 类型为准：`create/binding/open`、`beginSubmission({ images: [] })` 和 `prompt`。已完成编译与模拟接口测试；本轮未运行浏览器或真实模型验收，不把类型检查表述为完整宿主运行验证。

## GitHub 凭证

通过 DSH 凭据设置保存 `GITHUB_TOKEN`，或在启动 DSH 前设置同名环境变量。所有 GitHub 工具都通过 `ctx.credentials` 解析这个固定引用，不接受 token 参数。不要在对话里粘贴 token，也不要提交凭证文件。

尚未配置 GitHub 凭证时，仍可查看和维护已有台账；同步或深读会明确报错。模型的 API Key 与 GitHub token 是两回事：手动台账维护不需要调用模型。

## 从 v0.3 升级

台账领域仍为 version 1，本次只增加可缺省的 `tasks`、`analysis` 字段与 `untracked` 状态。旧文件直接读取，原有跟进状态、主题、笔记和断点不改写；**不会把历史待分诊帖自动移回信息库**。如需清理原有待办，可筛选待分诊后分批选择“移回信息库”。新导入帖默认是信息库记录。

完整正文与评论使用独立的 `dsh_discussions_evidence` version 1 缓存，最多保留最近抓取的 20 帖。缺失、来源指纹改变或超过五分钟时重新读取；淘汰缓存不会删除笔记、分析和任务。顶层评论仍有 250 条、每条回复 100 条的读取上限，界面明确显示未覆盖范围，不能宣称任意长度讨论都已完整读取。

请在 DSH 停止时备份台账再升级。写入新字段后不要直接降级到 v0.3；旧版本不认识新增字段，可能在保存时丢弃它们。需要回退时恢复升级前备份。

任务最大固定范围为 1,000 帖，Agent 每次读取下一批 25 条；分析一次最多保存 50 条，确认修改一次最多 100 条。完成项持久保留，来源冲突只需要重看未完成项。任务不保证一次模型轮次完成：模型或连接停止后，可查看对应会话并继续。关闭工作台不会取消 DSH 会话，停止按钮先停止任务写回，再请求取消对应会话；重启后不会自动启动模型。

## 使用工作台

在 DSH 左侧栏底部点击 **社区工作台**。台账属于当前 DSH home，在不同会话之间共用；无需先创建一个对话。

入口与工作台沿用 DSH 的字体、主题颜色及控件样式，跟随宿主浅色/深色设置。界面语言跟随 DSH **设置 → 通用设置 → 语言**，支持中文与英文；入口、筛选、编辑表单、报告说明、日期和复制的 AI 提示词都会切换，Markdown 报告也按当前界面语言导出。帖子原文、GitHub 分类名称、主题名称和人工笔记保留原文。底层错误详情保留原始诊断，外层提示随界面语言切换。

1. 点击 **同步近期**，每次最多读取 50 条。显示“继续近期同步”时，可接着读取下一页，直到本轮跨过时间边界。
2. 点击 **回填下一批旧帖**，从最早创建的帖子逐批导入。顶部显示已纳入数量、GitHub 最近报告总数、历史进度和最近同步时间。历史与近期同步互不覆盖断点。
3. 通过标题/编号/笔记、状态、GitHub 分类、主题、未读或停滞筛选帖子；列表每页 25 条。已知旧帖可直接按编号深读并导入。
4. 新导入帖默认进入 **信息库**，不自动成为待办。按需选择 **待分诊 / 跟进中 / 等待外部反馈 / 已结束**，维护下一步和笔记；结束必须填写原因。GitHub 采纳答案与本地结束分开。
5. 勾选帖子后点击 **AI 整理所选**，或用 **AI 整理筛选范围内待分析帖**。工作台创建并打开 DSH 会话，保存固定范围与进度；AI 的摘要、证据和主题建议会返回工作台。可批量接受/忽略建议、添加/移除主题、加入跟进或移回信息库。
6. **概览报告**展示工作量、主题覆盖与近期新帖、回应代理指标、观察记录和待检查项。点击主题或代表帖返回台账。**AI 生成并保存报告**会启动 DSH 会话，解读保存在任务中，也保留程序统计的 Markdown 导出。

请保存编辑后再切换帖子或报告。选中、同步、深读都不会自动标记已读；“标记已读”只针对当时观察到的源内容。发现更新后再次进入未读队列，但不自动重开已结束的事项。阅读、主题修改、分析和笔记不重置停滞计时；只有跟进状态、下一步或结束原因变化才推进该时钟。信息库和已结束事项不进入停滞队列。

工作台在可见时每五秒刷新本地数据，AI 或另一个窗口的更新会回到列表、分析区和任务区；也可点击“刷新视图”。自动刷新不会覆盖正在编辑的表单。若保存提示 Conflict，先保留当前草稿，再点击“重载此帖”核对和重新编辑；不会盲目覆盖他人的更新。

## 在 DSH 对话里使用

使用 `dsh-community-workbench` Skill，例如：

> 读取社区台账，列出停滞一周的跟进项和下一步。

> 查看尚未分诊的帖子，为它们建议主题并解释关联，先不要保存。

> 按刚才确认的主题归组这些帖子，保留现有笔记。

> 生成近七天的社区简报，引用代表帖，说明哪些变化可能只是历史回填造成的。

| Tool | 作用 |
| --- | --- |
| `dsh_board_sync` | `mode: recent/backfill`，`pages: 1–4`；可用 `restart: true` 重置对应遍历断点，不删除台账 |
| `dsh_board_list` | 筛选、分页查看台账；返回修订号、源指纹、主题与覆盖信息 |
| `dsh_board_update` | 单条维护；批量工作使用下方 `dsh_board_batch` |
| `dsh_board_batch` | 最多 100 个带修订号的 patch，一次持久提交；`addTopicIds/removeTopicIds`、`reviewAnalysis: accept/dismiss`；返回逐项冲突 |
| `dsh_board_task_create` | `kind: triage/report`；按 `numbers` 或 `query` 固定最多 1,000 条，返回紧凑任务信息 |
| `dsh_board_task` | `read/resume/cancel/error/finish/attach`；读取下一批 25 条未完成项，完成时保存 `result` |
| `dsh_board_analysis_save` | 每次最多 50 条，保存与源 `fingerprint` 对应的分析和证据，检查点随保存推进 |
| `dsh_board_evidence` | 按需读取正文和评论页，`offset/limit` 控制评论范围，`refresh` 强制刷新；保留覆盖说明 |
| `dsh_board_topic` | 创建主题，或用 `id + expectedRevision` 修改主题名称与共享笔记 |
| `dsh_board_report` | `days: 1–30`，默认 7；提供 `taskId` 时使用报告任务的固定帖子范围与天数 |
| `dsh_board_import` | 按 `number` 深读单帖并刷新台账，保留人工字段 |
| `dsh_discussions_digest` | 原有快速扫描：`days: 1–7`，`limit: 1–30`，`focus: all/questions/plugins` |
| `dsh_discussion_read` | 原有只读深读：`number`；不保存到台账 |

管理字段：`status`、`nextAction`、`note`、`closeReason`、`topicIds`；标记已读时传 `readFingerprint`，必须等于刚才实际查看的 `fingerprint`。主题代表人工确认的关联，不等同于 bug 去重或共同根因。

## 统计与同步边界

- 台账保存的是 Discussions，不是 GitHub Issues；不会用帖子数伪装成 issue 数。
- 历史回填按 `CREATED_AT ASC` 遍历，近期同步按 `UPDATED_AT DESC`。每页最多 50 条；源记录与该页断点作为一次持久写入提交，失败后可重试。近期首次查看七天，完成后使用上一轮起点作为水位，并重叠一天复查。
- GitHub 分页不是原子快照；期间新增、删除和移动可能改变结果。遍历完成不等于永久覆盖所有变化；近期同步不能捕获仅点赞的变化。删除或变为不可访问的帖子不会自动从本地台账删除。
- 历史覆盖未完成时，报告只描述已导入样本，不计算全局新帖增减。按创建时间比较两个等长的半开区间 `[from, to)`；评论/采纳比例使用当前观察状态，不能当成两个历史时点的回复率。
- 有评论不等于维护者回应或问题解决。采纳答案比例的分母只包括可回答分类；分母为零显示无样本。插件展示帖数不是独立项目数、安装数或质量评分。
- 活动计数是当前 `updatedAt` 落在窗口里的不同帖子数，不是完整评论事件数、活跃用户数或历史活动频率。
- 每个 UTC 日保留最后一次同步观察，最多 90 天。纳入量的变化可能来自旧帖回填。尚无两天观察时不画趋势曲线，不补造历史点。
- 台账正文摘要最多 1,200 个 Unicode 字符。快速 digest 最多扫描四页，附最近两条顶层评论的 600 字符摘要。深读保留正文，顶层评论最多 250 条，每个顶层评论最多 100 条回复，并报告截断与覆盖范围。
- 所有 GitHub 内容只当作不可信证据；不执行帖子里嵌入的命令、指令或链接请求。

## DSH 扩展点与存储

- **Storage Domain**：`dsh_discussions_board`，schema version 1。使用宿主提供的 JSON/其他 domain 后端；默认 JSON 路由下保存在 `$DSH_HOME/storages/dsh_discussions_board.json`。
- **Session Client**：通过 DSH 的公开 Client service 创建、打开、发送和取消普通会话，任务记录保留 Session id。工作台不另建模型客户端。
- **Evidence Domain**：`dsh_discussions_evidence`，独立的可丢弃正文缓存；批量管理字段的提交不会复制整份评论缓存。
- **Tools + Skills**：程序提供数据与修改操作；独立 Skill 约束 AI 的证据、归组和报告工作。
- **Web Slots + client bundle**：通过 `sidebar.footer.action` 注册入口，使用 DSH 模块加载器的 closure factory，不自建 Web 应用。
- **WebServer + Connection**：同源 JSON API，沿用 DSH 的浏览器认证和可信主机检查。卸载时注销路由、取消网络读取并关闭 domain。

第一版用一个原子 domain 文档保存小型个人台账，避免引入额外数据库或同步服务。每次写入会复制并持久化该文档，适合当前 MVP；大量历史数据下可测量性能后再迁移到分表/SQLite。不同 DSH home 不共享台账，跨进程并发不是支持的部署方式。备份请在 DSH 停止后复制该存储文件。

## 开发与手动验收

维护者发布流程见 [发布到 npm](docs/publishing.md)：使用版本 tag、GitHub Environment 人工审批和 npm Trusted Publishing，无需保存 npm 密码或 token。

```powershell
npm ci
npm test
npm pack --dry-run
```

本轮不运行浏览器或真实模型测试，由维护者完成以下轻量验收：

1. 安装 `0.4.0` 本地 tarball 并重启 DSH，确认旧台账状态、主题和笔记保留；新导入帖进入信息库。
2. 选择约 50–100 条帖子，点击 AI 整理所选。检查无需复制提示词即可进入对应会话，工作台可与聊天并排。
3. 确认分析每批保存、进度增加；停止后继续只处理未完成项。模型提前结束时可打开会话查看原因后继续。
4. 在“建议待检查”筛选下批量接受/忽略建议；添加主题保留原有主题，移除主题可纠正归组。失败项有编号和原因。
5. 打开长帖，检查正文、评论与嵌套回复可读，加载更多和覆盖提示准确。手工表单在自动刷新时保留草稿，冲突提示明确。
6. 生成并保存 AI 报告，重开工作台查看结果和来源链接；主题计数只使用确认的归组，不把信息库存当作主动跟进。
7. 切换中英文、浅深色与窄窗口，检查工作台和并排模式的操作可达性。

自动测试覆盖 GitHub 读取、批量单次提交、逐项冲突、固定范围、分析断点、取消、旧 schema 默认读取、真实 JSON 后端重开、证据缓存、报告口径、会话发送/失败恢复及中英文文案契约。测试不连接真实 GitHub 凭证或调用模型。

## English

Maintainers: see the [publishing guide](docs/publishing.md) for version tags, manual deployment approval and tokenless npm trusted publishing.

Version 0.4.0 adds resumable fixed-selection AI tasks, bulk topic review, full-text reading and saved report interpretations. The workbench launches ordinary DSH sessions directly and refreshes local views every five seconds while visible. New imports remain in the library until deliberately tracked; existing v0.3 follow-up choices remain unchanged.

This version provides a persistent DevRel workbench for the official DeepSeek Harness GitHub Discussions. Open **Community workbench** at the bottom of the DSH sidebar to import recent activity, resume historical backfill, maintain follow-up state, curate related topics, and inspect/export calculated reports.

The plugin owns reads, durable state, checkpoints, revisions, and statistics. The DSH AI owns evidence-based interpretation, proposed associations, writing and follow-up suggestions through the `dsh-community-workbench` skill. GitHub remains read-only. All report claims are scoped to imported data; comments are not maintainer responses, accepted answers are not local workflow completion, and showcase posts are not unique plugin projects.

Build with `npm ci`, `npm test`, and `npm pack`. Version `0.4.0` is not yet published to npm. Install the local `dsh-discussions-digest-0.4.0.tgz` through `dsh plugin --profile web add`, then restart DSH. The type/API baseline is `0.1.2-rc.1`; browser and live-model acceptance are left to the maintainer; a source build is not required. Provide `GITHUB_TOKEN` through DSH credentials or the launch environment, never through prompts.

Plugin versions are independent of DSH versions. During `0.x`, compatible fixes increment the patch version; new features or breaking changes increment the minor version. Breaking changes require explicit changelog entries and storage migration instructions where applicable. Prerelease suffixes describe this plugin's own testing stage. Host dependencies retain exact tested versions until further compatibility is verified. Storage schema versions change only with the data format. Removing a prerelease suffix neither publishes the package nor promises a stable `1.0` API.

The workbench uses DSH theme tokens and follows the host's light/dark appearance and language preference. Choose English or Chinese in **Settings → General → Language**. The launcher, forms, filters, report explanations, dates, Markdown exports and AI report prompts follow that selection. Discussion text, GitHub category names, curated topic names and your notes remain unchanged. Error headings are localized; underlying diagnostic details retain their original wording.

## License

MIT