# dsh-work-assistant
面向 DSH 的微信工作助理插件。自带微信机器人通道，将转发的消息解析为结构化工作项，维护优先级与提醒，并可将独立任务委派给单独会话执行。
通道、账本、知识库与提醒均在本包内实现，不依赖第三方 IM 插件。
---
## 背景
任务常以即时消息的形式下达：一条被 @ 的群消息、一句口头约定、一段转发的需求。这类信息缺少结构化记录，数小时后往往只剩模糊印象——知道有事要办，但记不清交付物、责任人与时限。
本插件用于填补这段间隙：把待处理的消息转发给微信机器人，由插件完成解析、登记、排序与后续跟进。
## 设计前提
微信官方机器人接口仅支持私聊，不提供群聊消息，也没有「被 @」这类事件。因此本插件不监听群聊，工作流为**主动转发**。
该限制源自平台能力，而非实现取舍：个人微信未开放群消息接口，逆向客户端违反服务条款并存在账号风险，不在本插件范围内。企业微信智能机器人可接收群内 @ 消息，如需该能力可另行实现渠道适配。
## 核心能力
| 能力 | 说明 |
| --- | --- |
| 登记 | 从消息中解析标题、期限、优先级与标签。寒暄、通知、已完成事项不登记；语义重复的消息合并为一条，并给出明确回执 |
| 排序 | 依据截止时间与执行状态计算紧急度（逾期优先，其次临近到期、进行中），不采用人工填写的优先级 |
| 提醒 | 每日摘要、逾期单列、安静时段抑制、每周复盘；提醒可推迟，推迟期间不重复打扰 |
| 委派 | 为独立任务创建单独会话，可指定模型、工作目录与权限档位；任务结束后回交报告 |
| 知识库 | 沉淀流程、口径、人员与关系，支持关键词检索；按日与闲置时段从对话中自动抽取 |
| 交付 | 将本地文件发送至微信，或挂载到指定工作项以便追溯 |
## 特色功能
### 单文件数据库
全部状态落在同一个 SQLite 文件内：工作项、副手会话、知识库、对话、人员关系、分析记录。没有外部数据库服务，也不需要单独配置连接。
| 表 | 内容 |
| --- | --- |
| `items` / `item_seq` | 工作项，以及按日递增的编号 |
| `assignments` / `assignment_seq` | 副手会话的状态与编号 |
| `kb_docs` / `kb_seq` | 知识库文档与按日编号 |
| `messages` | 对话原文，附带「是否已被分析」标记 |
| `entities` / `relations` | 人员档案与人物关系 |
| `analysis_runs` | 每次知识抽取的运行记录、耗时与结果 |
| `state` / `meta` | 运行状态与迁移标记 |
通过 Node 内置的 `node:sqlite` 访问，不引入数据库驱动。写入统一使用 `BEGIN IMMEDIATE`，连接设置 `busy_timeout` 与 WAL，多个进程同时写不会互相覆盖；结构版本记录在 `user_version`，升级时按版本迁移。检测到文件损坏（SQLite 错误码 11、26）时改名为 `.corrupt-<时间戳>` 后重建，锁竞争不会被误判为损坏。备份只需复制这一个文件。
### 知识库
知识库存放需要长期保留的内容：流程、口径、对外说法、方案要点。
- 每条笔记具备编号（如 `k-20261023-001`）、标题、标签、正文、来源与时间戳
- 检索支持关键词与标签，返回命中位置附近的片段，长文档无须整篇加载
- 写入时校验标题与正文非空，不产生空记录
- 模型侧提供 `kb_write`、`kb_search`、`kb_read`、`kb_list`；界面侧可搜索、可展开全文
### 人际分析与长期记忆
人员与关系单独建表，而不是混在知识库正文里。「某人是下属」这类信息需要能按人查、按关系查，写在段落里无法支持这种检索。
- `entities` 记录人员：姓名、归一化键、别名、类型（人 / 组织 / 本人）、备注、把握度、被提及次数、首次与最近出现时间
- `relations` 记录关系：八种闭合类型（同事、下属、上级、客户、合作方、朋友、家人、其他）、备注、证据原句、把握度
- 归一化会去掉空白与标点，「张 三」「张三」「张三。」合并为同一条档案
- 被提及次数累加，把握度取历史最高值，证据只保留材料中的原句（不超过 60 字），便于事后核对
- 「本人」节点只作为关系端点存在，不出现在联系人列表中
- 抽取由定时任务完成：每日固定时间一次，另有闲置触发（默认连续 30 分钟无对话）。单次材料上限 12000 字，包含最近 60 条消息、30 个工作项与 8 篇笔记，超出时优先保留最新内容
- 模型输出限定为 JSON；解析失败按失败处理并重试，不会把「没有读到人」记为成功；连续失败按 1、2、4 分钟递增退避，上限 60 分钟
- 已分析的消息写入标记，不重复送入模型，避免同一句话反复抬高提及次数
- 查询入口：`work_people` 按提及次数列出人员，`work_person` 查看单人档案及其全部关系
插件对业务口径、人员关系与历史往来的记忆是持久的：宿主重启、会话重建都不影响，下一次对话仍然认得此前出现过的人。
### 对话记忆
`messages` 表保存与助理之间的往来文本，按天与联系人归档。三个入口都可回看：微信侧栏的「对话」页签、整页仪表盘的对话记录、设置页的对话记录。升级到当前版本后首次启动时，会从既有会话事件日志中回填历史对话（仅执行一次，由 `meta` 表中的标记控制），工具调用、推理过程与运行时注入的内容不会被写入。
## 工作流
1. 在微信中看到待处理的消息时，将其转发给机器人。
2. 插件判断消息是否包含可执行事项。包含则登记为工作项，返回编号、标题、期限、优先级与当前排序位置；不包含则直接对话。
3. 工作项进入账本，按紧急度参与每日摘要与定期检查。
4. 需要他人配合的事项登记责任人，并约定跟进间隔。
5. 需要独立完成的任务可委派为副手会话，完成后回交报告。
### 交互示例
以下为示例，非真实记录：
```
用户：下周一把合同给法务，另外催一下老周的发票
助理：已登记两件：
w-20261023-001「合同给法务」，截止 10 月 27 日，优先级高
w-20261023-002「催老周的发票」，优先级普通
当前未完成共 6 件，上述两项分别排第 2、第 5
用户：这周完成了哪些
助理：本周完成 4 件，新增 3 件。其中一件已停滞一周：
「整理上季度报销」。是否需要拆分为可执行的步骤？
```
回复保持简短：微信场景下长文阅读率低，超过五行按要点拆分。
## 界面
**微信。** 主要入口。以自然语言交互，无需记忆命令。
**侧栏「对话」页签。** 列出全部助理会话，包含主会话与副手会话，显示运行状态与最近活动时间。选中后会话在主区打开，可查看推理过程并继续输入，与其他 DSH 会话行为一致。
**整页仪表盘。** 位于侧栏第 40 号入口，也可从设置页进入。包含关键指标（未完成、逾期、进行中、停滞超过一周）、优先级分布、近两周进出趋势、等待他人的事项、停滞最久的事项、可搜索与筛选的工作项清单、副手列表、人员与知识库、对话记录。
## 设计决策
**以工作项为中心，而非以任务条目为中心。** 记录对象是待办的事，包含期限、责任人、附件与来源，而非一条可勾选的列表项。
**优先级由系统计算，不要求人工填写。** 人工设定的优先级随时间失真；按截止时间与状态推导的排序在任意时刻都成立。只需表达「这件事急」，其余由系统判断。
**副手是独立会话，不是子任务。** 委派出去的会话拥有独立的模型、工作目录与权限，未获授权不得修改既有内容；结束后回交报告，说明改动、验证结果与遗留风险。
**零外部服务依赖。** 数据库使用 Node 内置的 `node:sqlite`，二维码由 `qrcode` 在本机渲染。整个插件只有一个运行时依赖，不需要额外部署数据库或消息队列。
**知识抽取主动进行，无需人工整理。** 人员与关系从日常对话中累积，而不是要求使用者先建一份通讯录。抽取是后台任务，与对话本身互不阻塞。
## 安装
从 npm 安装（推荐，装的是预构建产物，不需要本地编译）：
```bash
dsh plugin --profile <你的 profile> add dsh-work-assistant
```
改源码就用本地目录：
```bash
dsh plugin --profile <你的 profile> add -w link:<此目录的绝对路径>
```
也可以直接装 GitHub Release 上的 tarball。安装后重启宿主，插件会自动创建数据目录，默认位于 `~/.dsh/dsh-work-assistant/`。
在 DSH 的**设置**中新增「工作助理」页：扫码登录、查看状态、调整提醒时间、选择会话预设与模型均在此处。手机微信扫码后，将机器人添加为联系人；凭据仅保存在本机。
## 工具清单
共 23 个工具，参数与描述均为显式定义，不依赖宿主内部包。
| 分组 | 工具 |
| --- | --- |
| 账本 | `work_capture` `work_list` `work_update` `work_snooze` `work_digest` `work_review` |
| 知识库 | `kb_write` `kb_search` `kb_read` `kb_list` |
| 人员 | `work_people` `work_person` |
| 交付 | `work_send_file` `work_attach` `work_notify` |
| 委派 | `assign_create` `assign_list` `assign_inspect` `assign_send` `assign_stop` `assign_wait` `assign_report` |
| 跟进 | `work_assign` |
## 边界与已知限制
- **不读取群聊。** 微信官方机器人仅支持私聊，无 @ 事件，需手动转发。
- **对话记录仅保存文本。** 图片、语音与文件在记录中仅保留一句说明，原文件不入库。
- **同名人员会合并。** 存在两个同名联系人时，当前仅显示一份档案，待后续支持人工合并与拆分。
- **同一数据目录只由一个宿主驱动。** 两个宿主指向同一份数据库时不会互相覆盖，但要靠 `hosts` 表的心跳选出主实例：其余实例待命、不轮询不推送，主实例退出后 30 秒内自动接手。想让两边同时干活需为其中一个改 `stateDir`。
- **会话设置在下一条消息生效。** 预设、模型、推理强度等改动保存后只在关闭本轮之后重开会话，不影响正在进行的一轮；插件代码本身的改动仍需重启宿主。
## 许可
MIT。