dsh-mishu 0.5.4 → 0.7.1

package/README.md

@@ -9,6 +9,7 @@
 [![Languages](https://img.shields.io/badge/lang-%E4%B8%AD%E6%96%87%20%7C%20English-orange)](#)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](tsconfig.json)
 [![No telemetry](https://img.shields.io/badge/telemetry-none-success)](docs/调研与设计.md#用户数据安全)
+[![DSH Plugin Hub](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/aicivilization/dsh-mishu)
 
 `提醒` `通知` `待办` `收件箱` `秘书` `GitHub` `邮件` `飞书` `Telegram` · `reminder` `notifications` `todo` `inbox` `triage` `secretary`
 
@@ -54,7 +55,9 @@
 
 同一封邮件的往来回复算一件事。你在邮件客户端里看过之后，对应的事项会自动关闭。
 
-**密码放在系统钥匙串**：macOS 钥匙串、Windows 凭据管理器、Linux 密钥环（Secret Service）。密码只在设置页输入一次，直接交给钥匙串，不写进任何文件，接口也从不返回它。没有钥匙串的电脑（比如没有桌面的 Linux 服务器），设置页会说明原因；账户照样能保存，密码改用环境变量 `DSH_MISHU_SECRET_MAIL_<编号>` 提供。
+**密码放在系统钥匙串**：macOS 钥匙串、Windows 凭据管理器、Linux 密钥环（Secret Service）。密码只在设置页输入一次，直接交给钥匙串，不写进任何文件，接口也从不返回它。没有钥匙串的电脑（比如没有桌面的 Linux 服务器），密码和 token 存进记事本目录里的 `secrets.json`：权限 600，只有你的系统账号能读，但没有加密，设置页会写明这一点和原因。
+
+**添加邮箱**：点"+ 添加邮箱"弹出向导。填了地址就自动选好服务商，显示去哪里开 IMAP、拿授权码，带"打开设置页"；授权码位数不对会提醒；"测试并保存"连得上才保存。
 
 ### 用法
 
@@ -62,17 +65,24 @@
 
 看板上方可以按来源筛选：全部、GitHub、邮件、交代。
 
-- **要你处理**：现在需要你的事。每张卡片写明**是什么、问题在哪、怎么办**（比如 CI 失败在哪个 job 的哪一步、上次成功是什么时候），主按钮直接打开该看的地方（"看失败日志""去关掉 Actions""去审查"），还有办完了、明天再说、忽略。
+- **要你处理**：现在需要你的事。卡片平时是收起的，只显示标题；点标题展开，一次只展开一张，点另一张时前一张自动收起。展开后写明**是什么、问题在哪、怎么办**（比如 CI 失败在哪个 job 的哪一步、上次成功是什么时候），主按钮直接打开该看的地方（"看失败日志""去关掉 Actions""去审查"），还有办完了、明天再说、忽略。
 - **我记着**：说过"明天再说"的事，以及还没到提醒时间的交代。底部可以直接交代新的事，填写时会实时显示小秘书理解成了什么。
-- **替你办了**：最近 7 天关掉的事，按理由分组。点"怎么回事"能看到它是什么、为什么关掉（附证据链接）、小秘书做了什么、来自哪几条通知。判错了就点"恢复"。
+- **替你办了**：最近 7 天关掉的事，按理由分组。展开一张卡片就能看到它是什么、为什么关掉（附证据链接）、小秘书做了什么、来自哪几条通知。判错了就点"恢复"。
 
 **+AI**：看不明白就点彩色的"+AI"。它会开一个新对话，把这件事的说明、链接和相关通知放进输入框（不会自动发送），你看过、补上自己的问题再按发送。看板上的每张卡片、顶部总结、来源报错、设置页里各邮箱服务商的开通说明都有这个按钮。对话里的 AI 可以用 `mishu_detail` 查一件事的完整记录；要改状态时会先问你。
 
 卡片可以拖动：拖到"替你办了"就是办完，拖到"我记着"就是明天再提醒，从"我记着"拖回"要你处理"就是现在处理。三栏之间的分隔条也能拖动调宽度，双击恢复等宽。
 
-**设置**：点页面顶部的"设置"：语言、各类别提前几天提醒、GitHub（开关、token 从哪来、测试连接、在 GitHub 上标已读的方式）、邮箱账户（添加、测试连接、现在收一次、编辑、删除）。飞书即将接入。
+**设置**：点页面顶部的"设置"，按秘书的活分成四块：① 它看哪里（GitHub、邮箱）；② 什么事要告诉你（哪些算急事、各类别提前几天）；③ 什么时候、怎么告诉你（主动提醒，见下）；④ 能替你办什么（在 GitHub 上标已读的方式；邮件一律只读）。最后是语言和密码存在哪。
+
+**主动提醒**：不用打开看板也能知道。
+- 每日简报：每天到点（默认 09:00）发一份"要你处理"和"快到期"的清单；没事就不发。
+- 急事立刻提醒：有人请你 review、@ 你、把事分配给你；会议邀请；你交代的事到了当天或已经过期。每件只提醒一次；刚打开提醒时，看板上已有的不算新消息。
+- 免打扰（默认 22:00 到 08:00）：这段时间不发，期间出现的急事等结束后一起发。
+- 时间按你浏览器所在的时区算，DSH 跑在别的时区的服务器上也不会错。
+- 发到：这台电脑的系统通知（macOS、Windows、Linux 桌面；服务器上没有），以及飞书群机器人（建一个只有你的群、加一个自定义机器人，把 Webhook 地址粘贴过来；支持签名校验）。飞书的地址和密钥当密码存；提醒内容会经过飞书的服务器。
 
-**重启 DSH**：页面顶部"设置"后面的按键。重装或升级插件后点它，桌面版会按正常方式退出（有任务在跑时会先问你），再自动打开。用 `dsh` 命令启动的 DSH 没法从页面重启（新的登录地址只会打印在那个终端里），按键会告诉你回终端按 Ctrl+C 再运行一次。Windows 和 Linux 桌面版的重启还没在真机上测过。
+**重启 DSH**：页面顶部"设置"后面的按键。重装或升级插件后点它，桌面版会按正常方式退出（有任务在跑时会先问你），再自动打开。用 dsh-vps 装在服务器上的 DSH，由 dsh-gate 网关托管：点了之后 DSH 正常退出，网关几秒内把它重新拉起，页面断开一会儿后自动刷新。直接用 `dsh` 命令启动的 DSH 没法从页面重启（新的登录地址只会打印在那个终端里），按键会告诉你回终端按 Ctrl+C 再运行一次。Windows 和 Linux 桌面版的重启还没在真机上测过。
 
 **文字命令**：
 
@@ -102,7 +112,7 @@ agent 可用的工具：`mishu_add`（交代，需要你审批）、`mishu_list`
 按顺序取，token 不写进任何文件：
 
 1. 环境变量（默认 `GITHUB_TOKEN`）
-2. 你在设置页填的 token：先拿到 GitHub 上检查，再存进系统钥匙串。要用 classic token，勾选 `notifications`（看私有仓库再勾 `repo`）；GitHub 的通知接口不认 fine-grained 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`
 
 ### 安装和配置
@@ -140,6 +150,13 @@ dsh plugin --profile <name> add dsh-mishu
 - Outlook / Hotmail：微软只允许 OAuth 登录 IMAP，暂不支持。
 - Windows 和 Linux 的钥匙串已经按各自系统的方式实现，但还没在真机上测过。
 
+### 收录渠道
+
+- [DSH Plugin Hub（dsh-plugin.org 社区插件市场）](https://dsh-plugin.org/plugins/aicivilization/dsh-mishu)
+- [awesome-dsh-plugin 精选列表](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+- dsh-plugin-shop 插件商店（每日自动收录）
+- 52DSH / tuofangzhe 插件目录（证据分级收录）
+
 ---
 
 ## English
@@ -180,7 +197,9 @@ Default warning times: documents 90 days, bills 3, birthdays 7, renewals 7, ever
 
 A thread of replies is one item. Once you read it in your mail client, its item closes by itself.
 
-**Passwords live in the system keychain**: the macOS Keychain, Windows Credential Manager or the Linux keyring (Secret Service). You type a password once on the settings page; it goes straight to the keychain, is never written to a file and is never returned by any endpoint. On a computer without one (a Linux server with no desktop, say), the settings page says why; accounts still save, and each password comes from the environment variable `DSH_MISHU_SECRET_MAIL_<id>`.
+**Passwords live in the system keychain**: the macOS Keychain, Windows Credential Manager or the Linux keyring (Secret Service). You type a password once on the settings page; it goes straight to the keychain, is never written to a file and is never returned by any endpoint. On a computer without one (a Linux server with no desktop, say), passwords and tokens go to `secrets.json` in the notebook directory: mode 600, readable by your system account only, but not encrypted, and the settings page says so and why.
+
+**Adding a mail account**: "+ Add a mail account" opens a short guide. The address picks the provider; it says where to turn on IMAP and get the app password, with a button that opens that page; it warns when the password has the wrong length; "Test and save" keeps only an account that connects.
 
 ### Usage
 
@@ -188,17 +207,26 @@ A thread of replies is one item. Once you read it in your mail client, its item
 
 Filter the board by source: All, GitHub, Mail, Noted.
 
-- **To handle**: what needs you now. Every card says **what it is, where the problem is and what to do** (for a failing CI: which job and step, when it last passed), and its main button opens the right place ("Open the failing log", "Turn off Actions", "Review it"), next to done, tomorrow and dismiss.
+- **To handle**: what needs you now. Cards stay folded and show only the title; click a title to unfold it — one at a time, so opening another folds the first. Unfolded, a card says **what it is, where the problem is and what to do** (for a failing CI: which job and step, when it last passed), and its main button opens the right place ("Open the failing log", "Turn off Actions", "Review it"), next to done, tomorrow and dismiss.
 - **Keeping for you**: things you put off until tomorrow, and things you told it that are not due for a reminder yet. Add a new one at the bottom, with a live preview of what was understood.
-- **Done for you**: what was closed in the last 7 days, grouped by reason. "What happened" shows what it was, why it was closed (with the evidence link), what the secretary did and which notifications it came from. Reopen any that are wrong.
+- **Done for you**: what was closed in the last 7 days, grouped by reason. Unfold a card to see what it was, why it was closed (with the evidence link), what the secretary did and which notifications it came from. Reopen any that are wrong.
 
 **+AI**: when something is unclear, press the colourful "+AI". It opens a new chat with the item's explanation, link and related notifications in the input box — unsent — so you can read it, add your question and press send. Every card, the summary, source errors and each mail provider's setup note have one. In that chat the AI can use `mishu_detail` to look an item up in full, and asks you before changing anything.
 
 Cards can be dragged: onto "Done for you" to mark done, onto "Keeping for you" to snooze until tomorrow, from "Keeping for you" back to "To handle" to handle it now. The dividers between the columns can be dragged too; double-click one to make the columns equal.
 
-**Settings**: the "Settings" tab at the top of the page: language, warning days per category, GitHub (on/off, where the token comes from, connection test, how to mark read), mail accounts (add, test, check now, edit, delete). Feishu / Lark is coming.
+**Settings**: the "Settings" tab at the top of the page: language, warning days per category, GitHub (on/off, where the token comes from, connection test, how to mark read), mail accounts (add, test, check now, edit, delete).
+
+The settings follow the secretary's job in four parts: 1. where it looks (GitHub, mail); 2. what to tell you about (what counts as urgent, warning days per category); 3. when and how to tell you (reminders, below); 4. what it may do for you (marking read on GitHub; mail is always read-only). Then language and where secrets are kept.
+
+**Reminders**, without opening the board:
+- Daily brief: at its time (09:00 by default) a list of what needs you and what is coming up; nothing is sent when there is nothing.
+- Urgent items right away: a review requested, a mention, an assignment; a meeting invitation; something you told it that is due today or overdue. Each is sent once; what is already on the board when reminders start is not news.
+- Quiet hours (22:00 to 08:00 by default): nothing is sent; urgent items from then come when they end.
+- Times follow your browser's time zone, so DSH on a server in another zone still gets them right.
+- Sent to this computer's notifications (macOS, Windows, a Linux desktop; a server has none) and to a Feishu / Lark group bot (a group of just you, a custom bot, its webhook address pasted in; signature verification supported). The bot's address and secret are kept like passwords; what reminders say passes through Feishu's servers.
 
-**Restart DSH**: the button after "Settings" at the top of the page. After reinstalling or upgrading plugins, click it: the desktop app quits the normal way (asking first if a task is running) and opens again. DSH started with the `dsh` command cannot be restarted from the page (its new sign-in address is printed only in that terminal), so the button tells you to press Ctrl+C there and run it again. Restarting the Windows and Linux desktop apps is not yet tested on real machines.
+**Restart DSH**: the button after "Settings" at the top of the page. After reinstalling or upgrading plugins, click it: the desktop app quits the normal way (asking first if a task is running) and opens again. On a server set up with dsh-vps, DSH runs under the dsh-gate gateway: DSH exits cleanly, the gateway starts it again within seconds, and the page reloads once it is back. DSH started directly with the `dsh` command cannot be restarted from the page (its new sign-in address is printed only in that terminal), so the button tells you to press Ctrl+C there and run it again. Restarting the Windows and Linux desktop apps is not yet tested on real machines.
 
 **Text commands**:
 
@@ -228,7 +256,7 @@ Tools for the agent: `mishu_add` (needs your approval), `mishu_list`, `mishu_det
 It uses, in order, and never writes a token to a file:
 
 1. an environment variable (default `GITHUB_TOKEN`)
-2. a token you paste on the settings page: checked with GitHub first, then kept in the system keychain. Use a classic token with the `notifications` scope (plus `repo` for private repositories); GitHub's notifications API does not take fine-grained tokens
+2. a token from "Sign in with GitHub" on the settings page (GitHub's device flow: it shows a code you enter at github.com/login/device, from a phone or another computer if you like), or one you paste: checked with GitHub first, then kept in the system keychain (in `secrets.json` without one). Use a classic token with the `notifications` scope (plus `repo` for private repositories); GitHub's notifications API does not take fine-grained tokens
 3. `gh auth token`: if the GitHub CLI is installed and you have run `gh auth login`. DSH started from the Dock or Start menu often gets a short PATH, so besides PATH the secretary looks for `gh` where Homebrew, `~/.local/bin`, winget and Scoop put it
 
 ### Install and configure