小秘书 AIcivilization/dsh-mishu

dsh-mishu

DSH Plugin Hub

提醒 通知 待办 收件箱 秘书 GitHub 邮件 飞书 Telegram · reminder notifications todo inbox triage secretary

中文 · English

DSH 小秘书，DeepSeek Harness（dsh）插件。 替你盯着 GitHub 通知，也记住你交代的事（账单、续费、证件到期、生日）。它会查清楚哪些事已经结束、替你关掉，只把真要你处理的留给你。

支持 macOS / Windows / Linux，界面中英双语。设计见 docs/调研与设计.md，需求全景见 docs/需求清单.md。

能做什么

GitHub 通知：每 15 分钟拉一次全部未读通知，查对象现在的状态再判断，不看通知文字。

| 理由码 | 意思 |
| merged / closed | PR 已合并，或 issue / PR 已关闭 |
| recovered | 同一工作流在同一分支上后来通过了 |
| superseded | 旧版本 tag 失败了，但后面的 main 或更新的 tag 已经通过 |
| ref-gone | 失败的那个分支已经删了 |
| fork-upstream-schedule | fork 没有自己的提交，却在跑上游的定时任务，失败通知全是噪音；合成一件事：关掉这个 fork 的 Actions |
| ci-failing | 最近一次还是失败，交给你 |
| review-requested / mentioned / assigned / your-pr / commit-comment | 交给你 |

几十条通知会合并成「事项」：同一工作流在同一分支上的失败算一件事，同一个 fork 的噪音也算一件事。

手动交代：在任何 DSH 对话里说一句，比如「护照 2027 年 3 月 10 日到期」或「每月 15 号交房租」。模型会整理出日期、重复方式和提前多久提醒，DSH 弹出审批卡片让你核对，你同意了才存。到了提醒那天，它出现在待处理里。你说办了，这一期就关闭，下一期按周期自动出现。

默认提前量：证件 90 天，账单 3 天，生日纪念日 7 天，续费续保 7 天，其他 1 天。

邮件：在设置页添加邮箱（QQ、163、126、Gmail、iCloud，或自己填 IMAP 服务器），小秘书定时看收件箱里最近的未读邮件。只读：以只读方式打开收件箱，只看发件人、收件人、标题和几个邮件头，不读正文，也不会把邮件标成已读。

| 理由码 | 意思 |
| mail-to-you | 直接写给你、没有群发或自动发送标记的邮件，可能在等你回复 |
| mail-invite | 会议或日程邀请，等你回应 |
| mail-bill | 标题里有账单、还款、缴费、续费、发票之类的字眼（哪怕是群发的） |
| mail-newsletter / mail-automated | 群发邮件、系统自动邮件：折叠起来，不打扰你 |
| mail-code / mail-github / mail-cc | 验证码、GitHub 通知邮件（GitHub 来源已经在管）、只是抄送你 |

同一封邮件的往来回复算一件事。你在邮件客户端里看过之后，对应的事项会自动关闭。

密码放在系统钥匙串：macOS 钥匙串、Windows 凭据管理器、Linux 密钥环（Secret Service）。密码只在设置页输入一次，直接交给钥匙串，不写进任何文件，接口也从不返回它。没有钥匙串的电脑（比如没有桌面的 Linux 服务器），密码和 token 存进记事本目录里的 secrets.json：权限 600，只有你的系统账号能读，但没有加密，设置页会写明这一点和原因。
添加邮箱：点「+ 添加邮箱」弹出向导。填了地址就自动选好服务商，显示去哪里开 IMAP、拿授权码，带「打开设置页」；授权码位数不对会提醒；「测试并保存」连得上才保存。

用法

看板：点 DSH 左侧栏的「小秘书」，打开整页看板。顶部是一句话总结和四个数字（要你处理、7 天内到期、今天替你关掉、待你核对），下面分三栏：

看板上方可以按来源筛选：全部、GitHub、邮件、交代。

- 要你处理：现在需要你的事。每张卡片写明是什么、问题在哪、怎么办（比如 CI 失败在哪个 job 的哪一步、上次成功是什么时候），主按钮直接打开该看的地方（「看失败日志」「去关掉 Actions」「去审查」），还有办完了、明天再说、忽略。
- 我记着：说过「明天再说」的事，以及还没到提醒时间的交代。底部可以直接交代新的事，填写时会实时显示小秘书理解成了什么。
- 替你办了：最近 7 天关掉的事，按理由分组。点「怎么回事」能看到它是什么、为什么关掉（附证据链接）、小秘书做了什么、来自哪几条通知。判错了就点「恢复」。

+AI：看不明白就点彩色的「+AI」。它会开一个新对话，把这件事的说明、链接和相关通知放进输入框（不会自动发送），你看过、补上自己的问题再按发送。看板上的每张卡片、顶部总结、来源报错、设置页里各邮箱服务商的开通说明都有这个按钮。对话里的 AI 可以用 mishu_detail 查一件事的完整记录；要改状态时会先问你。

卡片可以拖动：拖到「替你办了」就是办完，拖到「我记着」就是明天再提醒，从「我记着」拖回「要你处理」就是现在处理。三栏之间的分隔条也能拖动调宽度，双击恢复等宽。

设置：点页面顶部的「设置」：语言、各类别提前几天提醒、GitHub（开关、token 从哪来、测试连接、在 GitHub 上标已读的方式）、邮箱账户（添加、测试连接、现在收一次、编辑、删除）。飞书即将接入。

重启 DSH：页面顶部「设置」后面的按键。重装或升级插件后点它，桌面版会按正常方式退出（有任务在跑时会先问你），再自动打开。用 dsh-vps 装在服务器上的 DSH，由 dsh-gate 网关托管：点了之后 DSH 正常退出，网关几秒内把它重新拉起，页面断开一会儿后自动刷新。直接用 dsh 命令启动的 DSH 没法从页面重启（新的登录地址只会打印在那个终端里），按键会告诉你回终端按 Ctrl+C 再运行一次。Windows 和 Linux 桌面版的重启还没在真机上测过。

文字命令：

/mishu 简报：要处理的、快到了的、最近替你关掉了什么 /mishu 同步 立刻同步一次 GitHub /mishu 完成 12 把 #12 标为完成（还有：忽略 12、恢复 12） /mishu 已关闭 最近 3 天关掉的事项和理由 /mishu 交代 你交代过、还在进行的事 /mishu 停止 3 交代 #3 以后不再提醒

英文命令也能用：sync、done、dismiss、reopen、closed、series、stop、help。

agent 可用的工具：mishu_add（交代，需要你审批）、mishu_list、mishu_detail、mishu_update、mishu_stop。

不会做的事

- 默认不在 GitHub 上标已读。markRead 默认是 shadow：只记下「如果打开，会把哪些通知标成已读」，一条也不真标。核对过 /mishu 已关闭 后，再改成 on。还在待处理里的事项，永远不会被标已读。
- 通知文字不会触发任何动作。只看查到的状态。
- 你改过的状态，不会被同样的证据改回去。只有来源出现更新的动态，才会重新判断。
- 你重新打开一件被规则关掉的事，算一次纠正。一条规则关掉的事项满 10 件、被纠正的比例超过 20%，这条规则就降级：之后它的结论只给你看，不再自动关闭。
- 不动你的邮箱。只读打开，不读正文，不标已读，不删不移，不发信。

GitHub token

按顺序取，token 不写进任何文件：

1. 环境变量（默认 GITHUB_TOKEN）
2. 在设置页「用 GitHub 登录」拿到的 token（GitHub 设备登录：显示一个登录码，你在 github.com/login/device 输入并授权，手机或别的电脑上都行），或者你粘贴的 token：先拿到 GitHub 上检查，再存进系统钥匙串（没钥匙串时存进 secrets.json）。要用 classic token，勾选 notifications（看私有仓库再勾 repo）；GitHub 的通知接口不认 fine-grained token
3. gh auth token：装了 GitHub CLI，并运行过 gh auth login 就行。从 Dock、开始菜单启动的 DSH 拿到的 PATH 往往很短，所以小秘书除了 PATH，还会去 Homebrew、~/.local/bin、winget、Scoop 等常见安装位置找 gh

安装和配置

dsh plugin --profile <name> add dsh-mishu

在 profile 的 cordis.patch.yml 里可以覆盖配置：

- id: dsh-mishu
name: dsh-mishu
config:
home: ~/.mishu # 记事本目录，在 DSH 之外 language: auto # auto（跟系统语言）/ zh / en github: enabled: true intervalMinutes: 15 tokenEnv: GITHUB_TOKEN useGhCli: true markRead: shadow # off / shadow / on
markReadReasons: [merged, closed, recovered, superseded, ref-gone]
leadDays: { document: 90, bill: 3, birthday: 7, renewal: 7, other: 1 }
upcomingDays: 30 # 简报里"快到了"往后看多少天记事本位于 ~/.mishu/mishu.db（SQLite），只存元数据和简短备注，不存邮件正文和 token。在 macOS / Linux 上，这个目录只有你本人能读写。卸载插件不会删它。

还没做

- 推送到手机（渠道还没定）。现在简报只能在 DSH 里看。
- 规则认不出的通知（unclassified）先直接交给你，还没接模型。
- 飞书；邮件里的「你发出去没人回」「你答应别人的事」（要读已发送文件夹）。
- Outlook / Hotmail：微软只允许 OAuth 登录 IMAP，暂不支持。
- Windows 和 Linux 的钥匙串已经按各自系统的方式实现，但还没在真机上测过。

收录渠道

- DSH Plugin Hub（dsh-plugin.org 社区插件市场）
- awesome-dsh-plugin 精选列表
- dsh-plugin-shop 插件商店（每日自动收录）
- 52DSH / tuofangzhe 插件目录（证据分级收录）

一个 DeepSeek Harness（dsh）的秘书插件。 它盯着你的 GitHub 通知，也记住你告诉它的那些带日期的事（账单、续费、证件到期、生日）。它会检查哪些事已经了结，并替你关掉，只把真正需要你处理的事留在列表上。

支持 macOS、Windows 和 Linux。会说中文和英文。

它做什么

GitHub 通知：每 15 分钟拉取一次全部未读通知，逐条按它所指对象的当前状态判断，绝不看通知文字。

| 原因 | 含义 |
| merged / closed | PR 已合并，或 issue / PR 已关闭 |
| recovered | 同一个工作流后来在同一分支上通过了 |
| superseded | 旧发布 tag 失败了，但此后 main 或更新的 tag 已通过 |
| ref-gone | 失败的分支已被删除 |
| fork-upstream-schedule | 一个没有自己提交的 fork 在跑父仓库的定时工作流；每次失败都是噪音，合并成一条：关掉这个 fork 的 Actions |
| ci-failing | 最新一次运行仍然失败；交给你 |
| review-requested / mentioned / assigned / your-pr / commit-comment | 交给你 |

几十条通知会合并成几条事项：同一个工作流在同一分支上的所有失败算一条，同一个 fork 的所有噪音算一条。

你告诉它的事：在任何 DSH 聊天里说「我的护照 2027-03-10 到期」或「每月 15 号交房租」。模型会算出日期、重复方式和提前多久提醒你；DSH 会弹出一张审批卡，写明它到底理解成了什么，你不批准就什么都不保存。到了提醒那天，这件事会出现在你的列表上。你说做完了，这一次就关闭，下一次按自己的节奏出现。

默认提前提醒时间：证件 90 天，账单 3 天，生日 7 天，续费 7 天，其他 1 天。

邮件：在设置页添加一个邮箱（QQ、163、126、Gmail、iCloud，或你自己的 IMAP 服务器），秘书会看收件箱里最近的未读邮件。只读：收件箱以只读方式打开；只读发件人、收件人、主题和几个头部字段——从不读正文——也不会把任何邮件标为已读。

| 原因 | 含义 |
| mail-to-you | 直接写给你的，没有群发或自动化的标记；可能有人在等你 |
| mail-invite | 会议或日历邀请，等你答复 |
| mail-bill | 主题提到账单、付款、续费或发票（群发邮件也算） |
| mail-newsletter / mail-automated | 群发或自动邮件，折叠收起 |
| mail-code / mail-github / mail-cc | 验证码、GitHub 通知邮件（GitHub 来源里就有）、只是抄送你的邮件 |

一串回复算一条。你在邮件客户端里读过之后，对应条目会自动关闭。

密码存在系统钥匙串里：macOS Keychain、Windows Credential Manager 或 Linux keyring（Secret Service）。你在设置页输入一次密码，它直接进钥匙串，不写进文件，任何接口都不会返回。在没有钥匙串的机器上（比如没有桌面的 Linux 服务器），密码和 token 存到笔记本目录下的 secrets.json：权限 600，只有你的系统账户能读，但不加密，设置页会说明这一点和原因。

添加邮件账户：「+ Add a mail account」会打开一份简短指南。地址决定服务商；指南说明在哪里开启 IMAP、怎么获取应用专用密码，并附一个按钮直接打开那个页面；密码长度不对会给出警告；「Test and save」只保留能连上的账户。

使用

看板：点 DSH 左侧栏的「Secretary」，打开整页看板。顶部是一句总结和四个数字（待处理、7 天内到期、今日关闭、待复核）。下面是三列：

按来源筛选看板：All、GitHub、Mail、Noted。

- 待处理：现在需要你处理的事。每张卡片都写明这是什么、问题出在哪、该怎么做（比如 CI 失败：哪个 job、哪个 step，上次通过是什么时候），主按钮直接打开对应位置（「Open the failing log」「Turn off Actions」「Review it」），旁边是完成、明天、忽略。
- 为你保留：你推迟到明天的事，以及你告诉它、还没到提醒时间的事。在底部新增一条，输入时会实时预览它理解到的内容。
- 已为你完成：最近 7 天关闭的事，按原因分组。「What happened」显示它原来是什么、为什么关闭（附证据链接）、秘书做了什么、来自哪些通知。关错的可以重新打开。

+AI：有不清楚的地方，点彩色的「+AI」。它会新开一个聊天，把条目的说明、链接和相关通知放进输入框——不发送——你可以先读，补上你的问题再按发送。每张卡片、总结、来源错误、每个邮件服务商的设置说明都有这个按钮。在那个聊天里，AI 可以用 mishu_detail 查条目的完整信息，改动任何东西之前都会先问你。
卡片可以拖动：拖到「Done for you」标记完成，拖到「Keeping for you」暂缓到明天，从「Keeping for you」拖回「To handle」立即处理。列与列之间的分隔线也能拖；双击分隔线，各列等宽。

设置：页面顶部的「Settings」标签页：语言、每个类别的预警天数、GitHub（开/关、token 从哪来、连接测试、怎么标记已读）、邮件账户（添加、测试、立即检查、编辑、删除）。飞书 / Lark 即将支持。

重启 DSH：页面顶部「Settings」后面的按钮。重装或升级插件后点它：桌面应用按正常方式退出（有任务在跑会先询问），然后重新打开。用 dsh-vps 搭的服务器上，DSH 跑在 dsh-gate 网关下：DSH 干净退出，网关几秒内把它拉起来，页面在它回来后自动刷新。直接用 dsh 命令启动的 DSH 无法从页面重启（新的登录地址只打印在那个终端里），所以按钮会提示你在终端按 Ctrl+C，再重新运行。Windows 和 Linux 桌面应用的重启还没在真机上测过。

文本命令：

/mishu brief: what needs you, what is coming up, what was closed for you
/mishu sync sync GitHub now
/mishu done 12 mark #12 done (also: dismiss 12, reopen 12)
/mishu closed items closed in the last 3 days, with reasons
/mishu series things you told me that are still in play
/mishu stop 3 stop reminding series #3

中文命令也支持：同步、完成、忽略、恢复、已关闭、交代、停止、帮助。

给智能体用的工具：mishu_add（需要你批准）、mishu_list、mishu_detail、mishu_update、mishu_stop。

它不会做的事

- 默认不在 GitHub 上标记任何已读。 markRead 初始为 shadow：它记录下自己会标记哪些通知为已读，但一条都不碰。看过 /mishu closed 之后，再切到 on。仍在你清单上的条目永远不会被标记已读。
- 通知文本永远不触发动作。 只有核实过的状态才会。
- 你自己的决定不会被同一份证据推翻。 只有源头上出现更新的活动，才会重新提出这个问题。
- 重新打开某条被规则关闭的条目，算一次纠正。 一条规则关闭过至少 10 个条目、且被纠正的比例超过 20%，就会被降级：此后它的结论只展示给你看，不再关闭条目。
- 它不碰你的邮箱。 只读：不读正文、不标记已读、不删除不移动、不发送。

GitHub token

它按以下顺序取用，且从不把 token 写进文件：

1. 环境变量（默认 GITHUB_TOKEN）
2. 在设置页点「Sign in with GitHub」拿到的 token（走 GitHub 的设备流程：页面显示一个验证码，你在 github.com/login/device 输入即可，用手机或另一台电脑都行），也可以自己粘贴一个：先交给 GitHub 校验，再存进系统钥匙串（没有钥匙串时存进 secrets.json）。用 classic token，勾上 notifications 权限（访问私有仓库再加 repo）；GitHub 的通知 API 不接受 fine-grained token
3. gh auth token：前提是装了 GitHub CLI，并且跑过 gh auth login。从 Dock 或开始菜单启动 DSH 时，PATH 往往很短，所以秘书除了查 PATH，还会去 Homebrew、~/.local/bin、winget 和 Scoop 的安装位置找 gh

安装与配置

dsh plugin --profile <name> add dsh-mishu

在配置档的 cordis.patch.yml 里覆盖设置（完整示例见中文部分，键名相同）。language 可选 auto（跟随系统语言）、zh 或 en。

笔记本是 ~/.mishu/mishu.db（SQLite）。里面只存元数据和短笔记，绝不存邮件正文或 token。在 macOS 和 Linux 上，只有你能读写这个目录。卸载插件时，这个目录会保留。

还没做的

- 推送到手机（推送渠道还没定）。目前简报只出现在 DSH 里。
- 规则认不出的通知（unclassified）直接交给你，还没有模型来分诊。
- 飞书 / Lark；邮件里的「你发了没人回」和「你答应过的事」（需要 Sent 文件夹）。
- Outlook / Hotmail：微软只允许 IMAP 走 OAuth，暂不支持。
- Windows 和 Linux 的钥匙串按各自系统的文档实现，但还没在真机上测过。

Development · 开发

npm install
npm test # node:test runs the TypeScript directly (Node ≥ 22.18); the time zone is pinned in tests/setup.ts
npm run build
npm run record # record a real, read-only sync of your own account into tests/fixtures/local/

Test data · 测试数据

- The committed tests use a made-up GitHub account built in tests/fixtures/synthetic.ts (example-org, upstream-org, demo-*): a fork running its parent's schedules, superseded release tags, recovered failures, a deleted branch, a red feature branch, a bot comment on a commit, PRs and issues in every state.
- 仓库里的测试只用编造的账号（tests/fixtures/synthetic.ts），覆盖所有规则要处理的情况。
- npm run record writes a recording of your own account to tests/fixtures/local/. Git ignores that folder; never commit it. When it exists, npm test also checks it (every notification judged, every closure has a known reason); when it does not, those checks are skipped.
- npm run record 录下的是你自己账号的真实数据，放在 tests/fixtures/local/，git 会忽略这个目录，绝不提交。本机有这份数据时，npm test 会多跑一组检查；没有就跳过。

src/core/ notebook, items, things you tell it, GitHub rules, brief, board, i18n — node: built-ins only, no DSH imports src/core/github/ client（REST）→ facts（当前状态）→ rules（纯函数）→ sync（折叠进 items） src/dsh/ 插件外壳：配置、定时器、/mishu、智能体工具、审批门禁、看板 API src/client/ 浏览器端：左侧栏入口和看板页面（React，由 scripts/build-client.mjs 打包）

在单独的配置档里测试：先 npm pack，再执行 dsh plugin --profile mishu-test add ./dsh-mishu-x.y.z.tgz，并把 home 设为 ~/.mishu-test。