dsh-mishu 0.5.0 → 0.5.1

package/README.md

@@ -54,7 +54,7 @@
 
 同一封邮件的往来回复算一件事。你在邮件客户端里看过之后，对应的事项会自动关闭。
 
-**密码放在系统钥匙串**：macOS 钥匙串、Windows 凭据管理器、Linux 密钥环（Secret Service）。密码只在设置页输入一次，直接交给钥匙串，不写进任何文件，接口也从不返回它。没有钥匙串的电脑，可以改用环境变量 `DSH_MISHU_SECRET_MAIL_<编号>`。
+**密码放在系统钥匙串**：macOS 钥匙串、Windows 凭据管理器、Linux 密钥环（Secret Service）。密码只在设置页输入一次，直接交给钥匙串，不写进任何文件，接口也从不返回它。没有钥匙串的电脑（比如没有桌面的 Linux 服务器），设置页会说明原因；账户照样能保存，密码改用环境变量 `DSH_MISHU_SECRET_MAIL_<编号>` 提供。
 
 ### 用法
 
@@ -97,10 +97,11 @@ agent 可用的工具：`mishu_add`（交代，需要你审批）、`mishu_list`
 
 ### GitHub token
 
-mishu 自己不保存 token。按顺序取：
+按顺序取，token 不写进任何文件：
 
 1. 环境变量（默认 `GITHUB_TOKEN`）
-2. `gh auth token`：装了 GitHub CLI，并运行过 `gh auth login` 就行
+2. 你在设置页填的 token：先拿到 GitHub 上检查，再存进系统钥匙串。要用 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`
 
 ### 安装和配置
 
@@ -177,7 +178,7 @@ 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. Without a keychain, use 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), the settings page says why; accounts still save, and each password comes from the environment variable `DSH_MISHU_SECRET_MAIL_<id>`.
 
 ### Usage
 
@@ -220,10 +221,11 @@ Tools for the agent: `mishu_add` (needs your approval), `mishu_list`, `mishu_det
 
 ### GitHub token
 
-mishu never stores a token. It uses, in order:
+It uses, in order, and never writes a token to a file:
 
 1. an environment variable (default `GITHUB_TOKEN`)
-2. `gh auth token`: if the GitHub CLI is installed and you have run `gh auth login`
+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
+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
 

package/lib/client.js

@@ -64,6 +64,8 @@ var settingsApi = {
   load: (lang) => post("/settings", { lang }),
   save: (lang, settings) => post("/settings/save", { lang, settings }),
   testGithub: (lang) => post("/github/test", { lang }),
+  saveToken: (lang, token) => post("/github/token/save", { lang, token }),
+  deleteToken: (lang) => post("/github/token/delete", { lang }),
   saveMail: (lang, account, password) => post("/mail/save", { lang, account, password }),
   testMail: (lang, account, password) => post("/mail/test", { lang, account, password }),
   deleteMail: (lang, id) => post("/mail/delete", { lang, id }),
@@ -147,6 +149,16 @@ var zh = {
   sToken: "Token",
   sTokenEnv: (name) => `\u4ECE\u73AF\u5883\u53D8\u91CF ${name} \u8BFB\u53D6`,
   sTokenGh: "\u7528 GitHub CLI\uFF08gh\uFF09\u767B\u5F55\u7684\u8D26\u53F7\uFF0Ctoken \u5728\u7CFB\u7EDF\u94A5\u5319\u4E32\u91CC",
+  sTokenKeychain: "\u4F60\u5728\u8FD9\u91CC\u586B\u7684 token\uFF0C\u5B58\u5728\u7CFB\u7EDF\u94A5\u5319\u4E32\u91CC",
+  sTokenPaste: "\u586B\u4E00\u4E2A GitHub token",
+  sTokenHow: "\u7528 classic token\uFF0C\u52FE\u9009 notifications\uFF1B\u8981\u770B\u79C1\u6709\u4ED3\u5E93\u518D\u52FE repo\u3002GitHub \u7684\u901A\u77E5\u63A5\u53E3\u4E0D\u8BA4 fine-grained token\u3002token \u53EA\u5B58\u8FDB\u7CFB\u7EDF\u94A5\u5319\u4E32\uFF0C\u4E0D\u5199\u8FDB\u4EFB\u4F55\u6587\u4EF6\u3002",
+  sTokenNew: "\u53BB GitHub \u751F\u6210\uFF08\u6743\u9650\u5DF2\u52FE\u597D\uFF09",
+  sTokenSave: "\u68C0\u67E5\u5E76\u4FDD\u5B58",
+  sTokenSaved: (login) => `\u4FDD\u5B58\u597D\u4E86\uFF0C\u8D26\u53F7 ${login}`,
+  sTokenReplace: "\u6362\u4E00\u4E2A token",
+  sTokenRemove: "\u79FB\u9664 token",
+  sTokenRemoveConfirm: "\u4ECE\u94A5\u5319\u4E32\u91CC\u79FB\u9664\u8FD9\u4E2A token\uFF1F",
+  sTokenNoKeychain: (env, why) => `\u8FD9\u53F0\u7535\u8111\u6CA1\u6709\u53EF\u7528\u7684\u7CFB\u7EDF\u94A5\u5319\u4E32\uFF08${why}\uFF09\uFF0Ctoken \u6CA1\u6CD5\u4FDD\u5B58\u3002\u53EF\u4EE5\u5728\u542F\u52A8 DSH \u7684\u73AF\u5883\u91CC\u8BBE\u7F6E ${env}\uFF0C\u518D\u91CD\u542F DSH\u3002`,
   sTest: "\u6D4B\u8BD5\u8FDE\u63A5",
   sTesting: "\u6B63\u5728\u6D4B\u8BD5\u2026",
   sGithubOk: (login) => `\u8FDE\u4E0A\u4E86\uFF0C\u8D26\u53F7 ${login}`,
@@ -160,7 +172,8 @@ var zh = {
   sMail: "\u90AE\u7BB1",
   sMailPrivacy: "\u53EA\u8BFB\uFF1A\u5C0F\u79D8\u4E66\u7528\u53EA\u8BFB\u65B9\u5F0F\u6253\u5F00\u6536\u4EF6\u7BB1\uFF0C\u53EA\u770B\u53D1\u4EF6\u4EBA\u3001\u6536\u4EF6\u4EBA\u3001\u6807\u9898\u548C\u51E0\u4E2A\u90AE\u4EF6\u5934\uFF0C\u4E0D\u8BFB\u6B63\u6587\uFF0C\u4E5F\u4E0D\u4F1A\u628A\u90AE\u4EF6\u6807\u6210\u5DF2\u8BFB\u3002",
   sSecretsAt: (kind) => `\u5BC6\u7801\u4FDD\u5B58\u5728\uFF1A${kind}\uFF08\u52A0\u5BC6\u4FDD\u5B58\uFF0C\u4E0D\u5199\u8FDB\u4EFB\u4F55\u6587\u4EF6\uFF09`,
-  sSecretsNone: "\u8FD9\u53F0\u7535\u8111\u4E0A\u6CA1\u627E\u5230\u53EF\u7528\u7684\u7CFB\u7EDF\u94A5\u5319\u4E32\uFF0C\u6CA1\u6CD5\u4FDD\u5B58\u5BC6\u7801\u3002\u53EF\u4EE5\u6539\u7528\u73AF\u5883\u53D8\u91CF\uFF0C\u540D\u5B57\u89C1\u6BCF\u4E2A\u8D26\u6237\u4E0B\u9762\u3002",
+  sSecretsNone: (why) => `\u8FD9\u53F0\u7535\u8111\u4E0A\u6CA1\u6709\u53EF\u7528\u7684\u7CFB\u7EDF\u94A5\u5319\u4E32\uFF1A${why}\u3002\u5BC6\u7801\u4E0D\u4F1A\u88AB\u4FDD\u5B58\uFF1B\u8D26\u6237\u7167\u6837\u80FD\u4FDD\u5B58\uFF0C\u5BC6\u7801\u7528\u73AF\u5883\u53D8\u91CF\u63D0\u4F9B\uFF0C\u53D8\u91CF\u540D\u5199\u5728\u6BCF\u4E2A\u8D26\u6237\u4E0B\u9762\u3002`,
+  sPasswordTestOnly: "\u6CA1\u6709\u94A5\u5319\u4E32\uFF1A\u8FD9\u91CC\u586B\u7684\u53EA\u7528\u6765\u6D4B\u8BD5\u8FDE\u63A5\uFF0C\u4E0D\u4F1A\u4FDD\u5B58",
   secretKinds: { macos: "macOS \u94A5\u5319\u4E32", windows: "Windows \u51ED\u636E\u7BA1\u7406\u5668", linux: "Linux \u5BC6\u94A5\u73AF\uFF08Secret Service\uFF09", memory: "\u5185\u5B58\uFF08\u6D4B\u8BD5\u7528\uFF09" },
   sNoAccounts: "\u8FD8\u6CA1\u6709\u6DFB\u52A0\u90AE\u7BB1\u3002",
   sAddAccount: "+ \u6DFB\u52A0\u90AE\u7BB1",
@@ -180,7 +193,7 @@ var zh = {
   sSince: "\u53EA\u770B\u6700\u8FD1\u51E0\u5929\u7684\u672A\u8BFB\u90AE\u4EF6",
   sEnabled: "\u542F\u7528",
   sMailOk: (n) => `\u8FDE\u4E0A\u4E86\uFF0C\u6700\u8FD1\u6709 ${n} \u5C01\u672A\u8BFB\u90AE\u4EF6`,
-  sEnvHint: (name) => `\u6CA1\u6709\u94A5\u5319\u4E32\u65F6\uFF0C\u53EF\u4EE5\u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF ${name}`,
+  sEnvHint: (name) => `\u6CA1\u6709\u627E\u5230\u5BC6\u7801\u3002\u70B9\u300C\u7F16\u8F91\u300D\u91CD\u65B0\u586B\u4E00\u6B21\uFF1B\u8FD9\u53F0\u7535\u8111\u6CA1\u6709\u94A5\u5319\u4E32\u7684\u8BDD\uFF0C\u5728\u542F\u52A8 DSH \u7684\u73AF\u5883\u91CC\u8BBE\u7F6E ${name}=\u6388\u6743\u7801\uFF0C\u518D\u91CD\u542F DSH\u3002`,
   sNeverChecked: "\u8FD8\u6CA1\u6536\u8FC7",
   sFeishu: "\u98DE\u4E66",
   sComing: "\u5373\u5C06\u63A5\u5165",
@@ -260,6 +273,16 @@ var en = {
   sToken: "Token",
   sTokenEnv: (name) => `Read from the environment variable ${name}`,
   sTokenGh: "The account the GitHub CLI (gh) is signed in to; the token stays in the system keychain",
+  sTokenKeychain: "The token you pasted here, kept in the system keychain",
+  sTokenPaste: "Paste a GitHub token",
+  sTokenHow: "Use a classic token with the notifications scope, plus repo for private repositories. GitHub's notifications API does not take fine-grained tokens. The token goes to the system keychain only, never to a file.",
+  sTokenNew: "Create one on GitHub (scopes pre-ticked)",
+  sTokenSave: "Check and save",
+  sTokenSaved: (login) => `Saved; signed in as ${login}`,
+  sTokenReplace: "Use another token",
+  sTokenRemove: "Remove token",
+  sTokenRemoveConfirm: "Remove this token from the keychain?",
+  sTokenNoKeychain: (env, why) => `No usable system keychain on this computer (${why}), so the token cannot be saved. Set ${env} in the environment DSH starts from, then restart DSH.`,
   sTest: "Test connection",
   sTesting: "Testing\u2026",
   sGithubOk: (login) => `Connected as ${login}`,
@@ -273,7 +296,8 @@ var en = {
   sMail: "Mail",
   sMailPrivacy: "Read-only: the secretary opens your inbox read-only and looks at sender, recipients, subject and a few headers only. It never reads bodies and never marks mail read.",
   sSecretsAt: (kind) => `Passwords are kept in: ${kind} (encrypted, never written to a file)`,
-  sSecretsNone: "No usable system keychain on this computer, so passwords cannot be saved. Use the environment variable shown under each account instead.",
+  sSecretsNone: (why) => `No usable system keychain on this computer: ${why}. Passwords are not saved; you can still save accounts and give each password through the environment variable shown under it.`,
+  sPasswordTestOnly: "No keychain: used only to test the connection, not saved",
   secretKinds: { macos: "the macOS Keychain", windows: "Windows Credential Manager", linux: "the Linux keyring (Secret Service)", memory: "memory (tests)" },
   sNoAccounts: "No mail account yet.",
   sAddAccount: "+ Add a mail account",
@@ -293,7 +317,7 @@ var en = {
   sSince: "Only look at unread mail from the last \u2026 days",
   sEnabled: "Enabled",
   sMailOk: (n) => `Connected; ${n} unread messages recently`,
-  sEnvHint: (name) => `Without a keychain, set the environment variable ${name}`,
+  sEnvHint: (name) => `No password found. Click Edit and enter it again; if this computer has no keychain, set ${name}=<app password> in the environment DSH starts from, then restart DSH.`,
   sNeverChecked: "Not checked yet",
   sFeishu: "Feishu / Lark",
   sComing: "Coming soon",
@@ -366,6 +390,7 @@ function MishuSettings({ lang, locale, openChat: openChat2 }) {
   const [lead, setLead] = (0, import_react2.useState)({});
   const [githubTest, setGithubTest] = (0, import_react2.useState)();
   const [confirmOn, setConfirmOn] = (0, import_react2.useState)(false);
+  const [pasting, setPasting] = (0, import_react2.useState)(false);
   const [editing, setEditing] = (0, import_react2.useState)();
   const take = (result, saved) => {
     if (result.ok) {
@@ -426,15 +451,27 @@ function MishuSettings({ lang, locale, openChat: openChat2 }) {
       ] }),
       /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "mishu-row-explain", children: [
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "mishu-row-label", children: t.sToken }),
-        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: token.found ? "" : "mishu-danger", children: token.found ? token.from === "env" ? t.sTokenEnv(view.github.tokenEnv) : t.sTokenGh : token.text })
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: token.found ? "" : "mishu-danger", children: token.found ? token.from === "env" ? t.sTokenEnv(view.github.tokenEnv) : token.from === "keychain" ? t.sTokenKeychain : t.sTokenGh : token.text })
       ] }),
-      /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "mishu-actions", children: [
+      token.found ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "mishu-actions", children: [
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("button", { type: "button", className: "mishu-btn", onClick: () => {
           setGithubTest(t.sTesting);
           void settingsApi.testGithub(locale()).then((r) => setGithubTest(r.ok ? t.sGithubOk(r.login) : `${t.failed}${r.message}`));
         }, children: t.sTest }),
+        token.from === "env" || pasting ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("button", { type: "button", className: "mishu-btn", onClick: () => setPasting(true), children: t.sTokenReplace }),
+        token.from === "keychain" ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("button", { type: "button", className: "mishu-btn mishu-btn-quiet", onClick: () => {
+          if (window.confirm(t.sTokenRemoveConfirm)) void settingsApi.deleteToken(locale()).then((r) => {
+            setGithubTest(void 0);
+            take(r);
+          });
+        }, children: t.sTokenRemove }) : null,
         githubTest === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "mishu-hint", children: githubTest })
-      ] }),
+      ] }) : null,
+      !token.found || pasting ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(TokenForm, { view, lang, locale, onSaved: (next, login) => {
+        setPasting(false);
+        setGithubTest(t.sTokenSaved(login));
+        take({ ok: true, view: next });
+      }, onCancel: token.found ? () => setPasting(false) : void 0 }) : null,
       /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("label", { className: "mishu-field", children: [
         t.sMarkRead,
         /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("select", { value: view.settings.markRead, onChange: (e) => {
@@ -461,7 +498,7 @@ function MishuSettings({ lang, locale, openChat: openChat2 }) {
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { className: "mishu-panel", children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h2", { children: t.sMail }),
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "mishu-hint", children: t.sMailPrivacy }),
-      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: view.secrets.available ? "mishu-hint" : "mishu-hint mishu-warn", children: view.secrets.available ? t.sSecretsAt(secretKind) : t.sSecretsNone }),
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: view.secrets.available ? "mishu-hint" : "mishu-hint mishu-warn", children: view.secrets.available ? t.sSecretsAt(secretKind) : t.sSecretsNone(view.secrets.why ?? secretKind) }),
       view.accounts.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "mishu-empty", children: t.sNoAccounts }) : view.accounts.map((account) => /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
         AccountRow,
         {
@@ -485,6 +522,45 @@ function MishuSettings({ lang, locale, openChat: openChat2 }) {
     ] })
   ] });
 }
+function TokenForm({ view, lang, locale, onSaved, onCancel }) {
+  const t = TEXT[lang];
+  const [token, setToken] = (0, import_react2.useState)("");
+  const [busy, setBusy] = (0, import_react2.useState)(false);
+  const [message, setMessage] = (0, import_react2.useState)();
+  if (!view.secrets.available) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "mishu-hint mishu-warn", children: t.sTokenNoKeychain(view.github.tokenEnv, view.secrets.why ?? "") });
+  }
+  const save = async () => {
+    setBusy(true);
+    setMessage(void 0);
+    const r = await settingsApi.saveToken(locale(), token);
+    setBusy(false);
+    if (r.ok) {
+      setToken("");
+      onSaved(r.view, r.login);
+    } else {
+      setMessage(r.message);
+    }
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "mishu-add", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("label", { className: "mishu-field", children: [
+      t.sTokenPaste,
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("input", { type: "password", value: token, autoComplete: "off", spellCheck: false, placeholder: "ghp_\u2026", onChange: (e) => {
+        setToken(e.target.value);
+        setMessage(void 0);
+      } })
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "mishu-hint", children: t.sTokenHow }),
+    message === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "mishu-preview mishu-danger", children: message }),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "mishu-actions", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("button", { type: "button", className: "mishu-btn", onClick: () => window.open(view.github.newTokenUrl, "_blank", "noopener"), children: t.sTokenNew }),
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("button", { type: "button", className: "mishu-btn primary", disabled: busy || token.trim() === "", onClick: () => {
+        void save();
+      }, children: busy ? t.sTesting : t.sTokenSave }),
+      onCancel === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("button", { type: "button", className: "mishu-btn", onClick: onCancel, children: t.sCancel })
+    ] })
+  ] });
+}
 function AccountRow({ account, lang, locale, openChat: openChat2, onEdit, onView }) {
   const t = TEXT[lang];
   const [busy, setBusy] = (0, import_react2.useState)(false);
@@ -578,11 +654,12 @@ function AccountForm({ draft, view, lang, locale, openChat: openChat2, onDone })
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("label", { className: "mishu-field", children: [
       t.sPassword,
-      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("input", { type: "password", value: password, autoComplete: "new-password", placeholder: existing ? t.sPasswordKeep : "", onChange: (e) => {
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("input", { type: "password", value: password, autoComplete: "new-password", placeholder: existing && view.secrets.available ? t.sPasswordKeep : "", onChange: (e) => {
         setPassword(e.target.value);
         setMessage(void 0);
       } })
     ] }),
+    view.secrets.available ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "mishu-hint mishu-warn", children: t.sPasswordTestOnly }),
     custom ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "mishu-row", children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("label", { className: "mishu-field", children: [
         t.sHost,
@@ -603,7 +680,10 @@ function AccountForm({ draft, view, lang, locale, openChat: openChat2, onDone })
         t.sEnabled
       ] })
     ] }),
-    message === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: `mishu-preview ${message.ok ? "" : "mishu-danger"}`, children: message.text }),
+    message === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: `mishu-preview ${message.ok ? "" : "mishu-danger"}`, children: [
+      message.text,
+      message.ok || !preset.supported ? null : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(AskAI, { topic: { kind: "mail-setup", preset: preset.id, error: message.text }, lang, locale, openChat: openChat2, compact: true })
+    ] }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "mishu-actions", children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("button", { type: "button", className: "mishu-btn", disabled: busy || !preset.supported, onClick: () => {
         void test();
@@ -1160,6 +1240,8 @@ var STYLES = `
 .mishu-field input,.mishu-field select{font:inherit;font-size:13px;color:${TEXT2};background:${LAYER2};border:1px solid ${LINE_STRONG};border-radius:6px;padding:4px 6px;width:100%}
 .mishu-row{display:grid;grid-template-columns:1fr 1fr;gap:6px}
 .mishu-preview{white-space:pre-wrap;font-size:12px;background:${LAYER2};border-radius:6px;padding:6px 8px;margin:4px 0 6px;color:${TEXT2}}
+.mishu-preview.mishu-danger{color:${DANGER}}
+.mishu-add>.mishu-hint{margin-bottom:8px}
 .mishu-title{display:flex;align-items:center;gap:14px;flex-wrap:wrap}
 .mishu-tabs{display:flex;gap:2px;background:${LAYER1};border-radius:8px;padding:2px}
 .mishu-tabs button{font:inherit;font-size:13px;color:${MUTED};background:transparent;border:0;border-radius:6px;padding:3px 12px;cursor:pointer}

package/lib/core/ask.js

@@ -125,8 +125,8 @@ export function buildAsk(store, request, options) {
         case 'mail-setup': {
             const preset = presetById(request.preset);
             return zh
-                ? `我想让小秘书只读地查看我的「${preset.label.zh}」收件箱，需要开通 IMAP 并拿到客户端授权码（或应用专用密码）。请一步步教我怎么做，包括在网页上点哪里、要注意什么。\n\n小秘书给的说明：${preset.howTo.zh}\nIMAP 服务器：${preset.host || '（自己填）'}:${preset.port}`
-                : `I want my secretary to read my ${preset.label.en} inbox (read-only), which needs IMAP turned on and an app password. Walk me through it step by step, including where to click and what to watch out for.\n\nThe secretary's note: ${preset.howTo.en}\nIMAP server: ${preset.host || '(enter your own)'}:${preset.port}`;
+                ? `我想让小秘书只读地查看我的「${preset.label.zh}」收件箱，需要开通 IMAP 并拿到客户端授权码（或应用专用密码）。请一步步教我怎么做，包括在网页上点哪里、要注意什么。\n\n小秘书给的说明：${preset.howTo.zh}\nIMAP 服务器：${preset.host || '（自己填）'}:${preset.port}${lines('\n测试连接时报错：', request.error)}`
+                : `I want my secretary to read my ${preset.label.en} inbox (read-only), which needs IMAP turned on and an app password. Walk me through it step by step, including where to click and what to watch out for.\n\nThe secretary's note: ${preset.howTo.en}\nIMAP server: ${preset.host || '(enter your own)'}:${preset.port}${lines('\nThe connection test said: ', request.error)}`;
         }
     }
 }

package/lib/core/exec.js

@@ -0,0 +1,68 @@
+/**
+ * Running the few helper programs the secretary uses (`security`,
+ * `secret-tool`, PowerShell, `gh`).
+ *
+ * An app started from the Dock, the Start menu or a service manager often
+ * gets a short PATH that misses where package managers put programs, so a
+ * program installed with Homebrew, winget or `~/.local/bin` looks missing.
+ * `findProgram` looks on PATH first, then in those usual places.
+ */
+import { execFile } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { posix, win32 } from 'node:path';
+/** The usual install places of command-line programs, after PATH. */
+export function usualDirs({ platform = process.platform, env = process.env, home = homedir() } = {}) {
+    if (platform === 'win32') {
+        const join = win32.join;
+        const local = env.LOCALAPPDATA ?? join(home, 'AppData', 'Local');
+        return [
+            join(env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0'),
+            join(env.ProgramFiles ?? 'C:\\Program Files', 'GitHub CLI'),
+            join(local, 'Programs', 'GitHub CLI'),
+            join(local, 'Microsoft', 'WinGet', 'Links'),
+            join(home, 'scoop', 'shims'),
+            join(env.ProgramData ?? 'C:\\ProgramData', 'chocolatey', 'bin'),
+        ];
+    }
+    const join = posix.join;
+    const common = ['/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', join(home, '.local', 'bin'), join(home, 'bin')];
+    return platform === 'darwin'
+        ? ['/opt/homebrew/bin', ...common, '/opt/local/bin']
+        : [...common, '/snap/bin', '/home/linuxbrew/.linuxbrew/bin', join(home, '.linuxbrew', 'bin')];
+}
+/** The full path of a program, or `undefined` when it is not installed anywhere we know of. */
+export function findProgram(name, where = {}) {
+    const platform = where.platform ?? process.platform;
+    const env = where.env ?? process.env;
+    const path = platform === 'win32' ? win32 : posix;
+    const pathDirs = (env.PATH ?? env.Path ?? '').split(path.delimiter).filter(Boolean);
+    const names = platform === 'win32' && !/\.\w+$/.test(name) ? [`${name}.exe`, `${name}.cmd`] : [name];
+    for (const dir of [...pathDirs, ...usualDirs(where)]) {
+        for (const file of names) {
+            const full = path.join(dir, file);
+            try {
+                accessSync(full, platform === 'win32' ? constants.F_OK : constants.X_OK);
+                return full;
+            }
+            catch {
+                // not here
+            }
+        }
+    }
+    return undefined;
+}
+/** Run a program; `input` goes to its stdin (secrets never go on the command line). Never rejects. */
+export function runProgram(file, args, input, timeout = 15_000) {
+    return new Promise((resolve) => {
+        const child = execFile(file, args, { timeout, windowsHide: true, maxBuffer: 1 << 20 }, (error, stdout, stderr) => {
+            const code = error === null ? 0 : typeof error.code === 'number' ? error.code : 1;
+            const result = { code, stdout: String(stdout), stderr: String(stderr) };
+            if (error !== null && typeof error.code !== 'number')
+                result.failure = error.message;
+            resolve(result);
+        });
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(input ?? '');
+    });
+}

package/lib/core/github/client.js

@@ -89,6 +89,16 @@ export class GitHubClient {
     user() {
         return this.get('/user');
     }
+    /** Whether this token may read notifications (fine-grained tokens get 403). */
+    async canReadNotifications() {
+        const url = `${API}/notifications?per_page=1`;
+        const { status, body } = await this.raw('GET', url);
+        if (status >= 200 && status < 300)
+            return true;
+        if (status === 403 || status === 404)
+            return false;
+        throw new GitHubError(status, url, body?.message ?? 'request failed');
+    }
     repo(fullName) {
         return this.get(`/repos/${fullName}`);
     }

package/lib/core/github/token.js

@@ -0,0 +1,79 @@
+/**
+ * Where the GitHub token comes from, in this order:
+ *
+ *   1. the environment variable named in the config (GITHUB_TOKEN)
+ *   2. a token you pasted on the settings page, kept in the system keychain
+ *   3. the GitHub CLI (`gh auth token`), which keeps its own in the keychain
+ *
+ * A token is never written to the notebook or a file.
+ */
+import { findProgram, runProgram } from "../exec.js";
+import { bi, MishuError } from "../i18n.js";
+import { GitHubClient, GitHubError } from "./client.js";
+/** The keychain entry for a token pasted on the settings page. */
+export const GITHUB_SECRET = 'github';
+/** Opens GitHub's "new classic token" page with the two scopes ticked. */
+export const NEW_TOKEN_URL = 'https://github.com/settings/tokens/new?scopes=notifications,repo&description=DSH%20mishu';
+/** `ghPath` is for tests: a fixed path, or `null` for "not installed". */
+export async function resolveGithubToken(options) {
+    const { envName, useGhCli, secrets } = options;
+    const fromEnv = envName === '' ? undefined : process.env[envName]?.trim();
+    if (fromEnv)
+        return { token: fromEnv, from: 'env' };
+    const stored = await secrets?.get(GITHUB_SECRET).catch(() => undefined);
+    if (stored)
+        return { token: stored, from: 'keychain' };
+    const none = bi(envName === '' ? '没有 GitHub token' : `没有 GitHub token（环境变量 ${envName} 是空的，钥匙串里也没有存）`, envName === '' ? 'no GitHub token' : `no GitHub token (environment variable ${envName} is empty and none is saved in the keychain)`);
+    const paste = bi('在小秘书的设置页填一个 token', 'paste a token on the secretary\'s settings page');
+    if (!useGhCli)
+        return { error: bi(`${none.zh}。${paste.zh}。`, `${none.en}. ${cap(paste.en)}.`) };
+    const gh = options.ghPath === undefined ? findProgram('gh') : options.ghPath ?? undefined;
+    if (gh === undefined) {
+        return {
+            error: bi(`${none.zh}，这台电脑上也没找到 GitHub CLI（gh）。${paste.zh}，或者装上 gh 后运行 gh auth login。`, `${none.en}, and the GitHub CLI (gh) is not installed on this computer. ${cap(paste.en)}, or install gh and run gh auth login.`),
+        };
+    }
+    const r = await runProgram(gh, ['auth', 'token'], undefined, 5000);
+    const token = r.stdout.trim();
+    if (r.code === 0 && token !== '')
+        return { token, from: 'gh' };
+    const why = (r.stderr.trim() || r.failure || `exit ${r.code}`).split('\n')[0].slice(0, 200);
+    return {
+        error: bi(`${none.zh}，gh 也没给出 token（${why}）。运行 gh auth login 登录，或者${paste.zh}。`, `${none.en}, and gh gave no token (${why}). Run gh auth login, or ${paste.en}.`),
+    };
+}
+function cap(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+/**
+ * Check a pasted token with GitHub, then keep it in the keychain. It must
+ * read notifications, which only classic tokens with the `notifications`
+ * scope can (fine-grained tokens cannot reach that API).
+ */
+export async function saveGithubToken(secrets, raw, fetch) {
+    const token = raw.trim();
+    if (!/^[\w-]{20,255}$/.test(token)) {
+        throw new MishuError(bi('这不像 GitHub token：应该是一串没有空格的字母数字，classic token 以 ghp_ 开头', 'That does not look like a GitHub token: it should be letters and digits without spaces; classic tokens start with ghp_'));
+    }
+    const status = await secrets.status();
+    if (!status.available)
+        throw new MishuError(bi(`没法保存：${status.why.zh}`, `Cannot save it: ${status.why.en}`));
+    const gh = new GitHubClient({ token, ...fetch === undefined ? {} : { fetch } });
+    let login;
+    try {
+        login = (await gh.user()).login;
+    }
+    catch (error) {
+        if (error instanceof GitHubError && error.status === 401)
+            throw new MishuError(bi('GitHub 不认这个 token（可能填错了、过期了或被撤销了）', 'GitHub does not accept this token (mistyped, expired or revoked)'));
+        throw error;
+    }
+    if (!await gh.canReadNotifications()) {
+        throw new MishuError(bi(`这个 token 属于 ${login}，但读不了通知。GitHub 的通知接口只认 classic token：生成时勾选 notifications（要看私有仓库再勾 repo）。`, `This token belongs to ${login} but cannot read notifications. GitHub's notifications API only takes classic tokens: tick notifications when you create it (and repo for private repositories).`));
+    }
+    await secrets.set(GITHUB_SECRET, token);
+    return { login };
+}
+export async function deleteGithubToken(secrets) {
+    await secrets.delete(GITHUB_SECRET);
+}

package/lib/core/index.js

@@ -2,10 +2,8 @@
  * mishu core — everything that does not depend on DSH.
  * Nothing under `src/core` may import DSH; `tests/boundary.test.ts` enforces it.
  */
-import { execFile } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { bi } from "./i18n.js";
 export { buildAsk, detailText } from "./ask.js";
 export { buildBoard, buildDetail } from "./board.js";
 export { renderBrief, renderClosed, renderMatter, reasonLabel, sortOpen } from "./brief.js";
@@ -13,6 +11,7 @@ export { GitHubClient, GitHubError } from "./github/client.js";
 export { gatherFacts, Lookups, parseCheckSuiteTitle } from "./github/facts.js";
 export { CLOSING_REASONS, judge } from "./github/rules.js";
 export { syncGithub } from "./github/sync.js";
+export { deleteGithubToken, GITHUB_SECRET, NEW_TOKEN_URL, resolveGithubToken, saveGithubToken } from "./github/token.js";
 export { bi, decode, detectLang, errorText, LANGS, MishuError, pick } from "./i18n.js";
 export { addSeries, describeActiveSeries, describeSeries, resolveSeries, stopSeries, tickManual, upcoming, } from "./manual.js";
 export { DEFAULT_DEMOTION, isActive, isDemoted, setStatusByUser, snoozeByUser } from "./matters.js";
@@ -23,6 +22,7 @@ export { MAIL_PRESETS, presetById, secretAccount } from "./mail/account.js";
 export { ImapFetcher } from "./mail/imap.js";
 export { judgeMail } from "./mail/rules.js";
 export { describeMailError, MAIL_SOURCE, mailReportKey, syncMail } from "./mail/sync.js";
+export { findProgram } from "./exec.js";
 export { MemorySecrets, secretEnvName, secretFromEnv, systemSecrets } from "./secrets.js";
 export { deleteMailAccount, effectiveSettings, mailAccounts, saveMailAccount, saveSettings } from "./settings.js";
 export const DEFAULT_HOME = '~/.mishu';
@@ -38,28 +38,3 @@ export function mishuPaths(home) {
     const root = expandHome(home);
     return { root, db: join(root, 'mishu.db') };
 }
-/**
- * A GitHub token without storing one: the named environment variable, else
- * the GitHub CLI (`gh auth token`, which reads the system credential store).
- */
-export async function resolveGithubToken(envName, useGhCli) {
-    const fromEnv = envName === '' ? undefined : process.env[envName]?.trim();
-    if (fromEnv)
-        return { token: fromEnv, from: 'env' };
-    if (!useGhCli)
-        return { error: bi(`没有 GitHub token：环境变量 ${envName} 是空的`, `no GitHub token: environment variable ${envName} is empty`) };
-    return new Promise((resolve) => {
-        execFile('gh', ['auth', 'token'], { timeout: 5000, windowsHide: true }, (error, stdout) => {
-            const token = stdout?.trim();
-            if (error !== null || !token) {
-                const why = error?.message ?? 'empty output';
-                resolve({
-                    error: bi(`没有 GitHub token：环境变量 ${envName} 是空的，gh auth token 也没拿到（${why}）。先运行 gh auth login，或设置 ${envName}`, `no GitHub token: environment variable ${envName} is empty and gh auth token failed (${why}). Run gh auth login, or set ${envName}`),
-                });
-            }
-            else {
-                resolve({ token, from: 'gh' });
-            }
-        });
-    });
-}

package/lib/core/mail/account.js

@@ -9,7 +9,7 @@ import { bi, MishuError } from "../i18n.js";
 export const MAIL_PRESETS = [
     {
         id: 'qq', label: bi('QQ 邮箱', 'QQ Mail'), host: 'imap.qq.com', port: 993, secure: true, supported: true,
-        howTo: bi('在 QQ 邮箱网页版：设置 → 账号 → 开启「IMAP/SMTP 服务」，按提示生成授权码。这里填授权码，不是 QQ 密码。', 'In QQ Mail on the web: Settings → Account → turn on "IMAP/SMTP" and generate an authorization code. Enter that code here, not your QQ password.'),
+        howTo: bi('在 QQ 邮箱网页版：设置 → 账号与安全 → 安全设置（旧版界面是 设置 → 账户），开启「IMAP/SMTP 服务」，按提示验证后生成 16 位授权码。这里填授权码，不是 QQ 密码；改过 QQ 密码后，旧授权码会失效。', 'In QQ Mail on the web: Settings → Account and Security → Security (Settings → Account in the older layout), turn on "IMAP/SMTP", verify, and generate a 16-character authorization code. Enter that code here, not your QQ password; changing your QQ password expires old codes.'),
     },
     {
         id: '163', label: bi('网易 163 邮箱', 'NetEase 163'), host: 'imap.163.com', port: 993, secure: true, supported: true,
@@ -53,8 +53,10 @@ export function resolveAccount(input, id) {
     if (!preset.supported)
         throw new MishuError(bi(`${preset.label.zh}暂时不支持：${preset.howTo.zh}`, `${preset.label.en} is not supported yet: ${preset.howTo.en}`));
     const host = preset.id === 'custom' ? String(input.host ?? '').trim() : preset.host;
-    if (!/^[\w.-]+$/.test(host))
-        throw new MishuError(bi('IMAP 服务器地址不对', 'invalid IMAP server'));
+    // A name with a dot (imap.example.com), a full IPv4 address, or localhost; a bare number is a port typed in the wrong box.
+    if (!/^[\w-]+(\.[\w-]+)+$/.test(host) && host !== 'localhost' || /^\d+$/.test(host)) {
+        throw new MishuError(bi(`IMAP 服务器地址不对：${host || '（空）'}，应该像 imap.example.com`, `invalid IMAP server: ${host || '(empty)'}; it should look like imap.example.com`));
+    }
     const port = preset.id === 'custom' ? Number(input.port ?? 993) : preset.port;
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new MishuError(bi('端口要是 1 到 65535 的整数', 'the port must be a whole number from 1 to 65535'));

package/lib/core/mail/sync.js

@@ -8,15 +8,18 @@
  */
 import { applyVerdict, closeReadElsewhere } from "../fold.js";
 import { bi } from "../i18n.js";
+import { presetById } from "./account.js";
 import { judgeMail } from "./rules.js";
 export const MAIL_SOURCE = 'mail';
 /** A connection or login failure, said so a person knows what to fix. */
 export function describeMailError(error, account) {
     const raw = error.responseText ?? error.message ?? String(error);
     const auth = /auth|login|password|credential|AUTHENTICATIONFAILED|LOGIN failed/i.test(raw);
-    return auth
-        ? bi(`登录失败：服务器不接受这个用户名或密码（${raw}）。多数邮箱要填客户端授权码或应用专用密码，不是网页登录密码。`, `Login failed: the server rejected the user name or password (${raw}). Most providers need an app password, not your web password.`)
-        : bi(`连接 ${account.host}:${account.port} 失败：${raw}`, `Could not reach ${account.host}:${account.port}: ${raw}`);
+    if (!auth)
+        return bi(`连接 ${account.host}:${account.port} 失败：${raw}`, `Could not reach ${account.host}:${account.port}: ${raw}`);
+    const preset = presetById(account.preset);
+    const howTo = preset.id === 'custom' ? undefined : preset.howTo;
+    return bi(`登录失败：服务器不接受这个用户名或密码（${raw}）。多数邮箱要先开启 IMAP，再填客户端授权码或应用专用密码，不是网页登录密码。${howTo === undefined ? '' : `\n${preset.label.zh}：${howTo.zh}`}`, `Login failed: the server rejected the user name or password (${raw}). Most providers need IMAP turned on and an app password, not your web password.${howTo === undefined ? '' : `\n${preset.label.en}: ${howTo.en}`}`);
 }
 export function mailReportKey(accountId) {
     return `mail.lastSync.${accountId}`;

package/lib/core/secrets.js

@@ -10,17 +10,26 @@
  * stored under the service name "dsh-mishu". When no keychain is available,
  * `secretFromEnv` is the documented fallback.
  */
-import { execFile } from 'node:child_process';
+import { findProgram, runProgram } from "./exec.js";
+import { bi } from "./i18n.js";
 export const SERVICE = 'dsh-mishu';
-function run(file, args, input) {
-    return new Promise((resolve) => {
-        const child = execFile(file, args, { timeout: 15_000, windowsHide: true, maxBuffer: 1 << 20 }, (error, stdout, stderr) => {
-            const code = error === null ? 0 : typeof error.code === 'number' ? error.code : 1;
-            resolve({ code, stdout: String(stdout), stderr: String(stderr) });
-        });
-        child.stdin?.end(input ?? '');
-    });
+/** A helper program, found by full path so a short PATH does not hide it. */
+class Helper {
+    name;
+    path;
+    constructor(name) { this.name = name; }
+    find() {
+        this.path ??= findProgram(this.name);
+        return this.path;
+    }
+    async run(args, input) {
+        const path = this.find();
+        if (path === undefined)
+            return { code: 127, stdout: '', stderr: '', failure: `${this.name} not found` };
+        return runProgram(path, args, input);
+    }
 }
+const detail = (r) => (r.stderr.trim() || r.failure || `exit ${r.code}`).slice(0, 300);
 /** Accounts are plain ids we choose ("mail:3"); refuse anything else so they are safe in every helper. */
 function checkAccount(account) {
     if (!/^[\w:.-]{1,80}$/.test(account))
@@ -32,32 +41,47 @@ function checkSecret(secret) {
 }
 class MacKeychain {
     kind = 'macos';
-    async available() { return (await run('security', ['help'])).code === 0 || (await run('security', ['list-keychains'])).code === 0; }
+    security = new Helper('security');
+    async status() {
+        const r = await this.security.run(['list-keychains']);
+        if (r.code === 0)
+            return { available: true };
+        return { available: false, why: bi(`macOS 钥匙串用不了（${detail(r)}）`, `the macOS Keychain is not usable (${detail(r)})`) };
+    }
     async get(account) {
         checkAccount(account);
-        const r = await run('security', ['find-generic-password', '-s', SERVICE, '-a', account, '-w']);
+        const r = await this.security.run(['find-generic-password', '-s', SERVICE, '-a', account, '-w']);
         return r.code === 0 ? r.stdout.replace(/\n$/, '') : undefined;
     }
     async set(account, secret) {
         checkAccount(account);
         checkSecret(secret);
         // `-w` last: security prompts twice and reads both answers from stdin.
-        const r = await run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', account, '-l', `${SERVICE} ${account}`, '-w'], `${secret}\n${secret}\n`);
+        const r = await this.security.run(['add-generic-password', '-U', '-s', SERVICE, '-a', account, '-l', `${SERVICE} ${account}`, '-w'], `${secret}\n${secret}\n`);
         if (r.code !== 0)
             throw new Error(`Keychain refused to save the password (${r.stderr.trim() || r.code})`);
     }
     async delete(account) {
         checkAccount(account);
-        await run('security', ['delete-generic-password', '-s', SERVICE, '-a', account]);
+        await this.security.run(['delete-generic-password', '-s', SERVICE, '-a', account]);
     }
 }
 const PS_PRELUDE = '[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime];$v=New-Object Windows.Security.Credentials.PasswordVault;';
 class WindowsVault {
     kind = 'windows';
+    powershell = new Helper('powershell');
     ps(script, input) {
-        return run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', PS_PRELUDE + script], input);
+        return this.powershell.run(['-NoProfile', '-NonInteractive', '-Command', PS_PRELUDE + script], input);
+    }
+    async status() {
+        if (this.powershell.find() === undefined) {
+            return { available: false, why: bi('没找到 Windows PowerShell（powershell.exe），小秘书靠它使用 Windows 凭据管理器', 'Windows PowerShell (powershell.exe) was not found; the secretary uses it to reach Windows Credential Manager') };
+        }
+        const r = await this.ps('exit 0');
+        if (r.code === 0)
+            return { available: true };
+        return { available: false, why: bi(`Windows 凭据管理器用不了（${detail(r)}）`, `Windows Credential Manager is not usable (${detail(r)})`) };
     }
-    async available() { return (await this.ps('exit 0')).code === 0; }
     async get(account) {
         checkAccount(account);
         const r = await this.ps(`try{$c=$v.Retrieve('${SERVICE}','${account}');$c.RetrievePassword();[Console]::Out.Write($c.Password)}catch{exit 3}`);
@@ -77,31 +101,55 @@ class WindowsVault {
 }
 class SecretTool {
     kind = 'linux';
-    async available() { return (await run('secret-tool', ['--version'])).code === 0; }
+    tool = new Helper('secret-tool');
+    async status() {
+        if (this.tool.find() === undefined) {
+            return {
+                available: false,
+                why: bi('没找到 secret-tool。Debian/Ubuntu 装 libsecret-tools（sudo apt install libsecret-tools），Fedora 装 libsecret（sudo dnf install libsecret），Arch 装 libsecret', 'secret-tool was not found. Install libsecret-tools on Debian/Ubuntu (sudo apt install libsecret-tools), libsecret on Fedora (sudo dnf install libsecret) or Arch'),
+            };
+        }
+        // A lookup that finds nothing exits 1 quietly; a missing keyring service complains on stderr.
+        const r = await this.tool.run(['lookup', 'service', SERVICE, 'account', 'probe']);
+        if (r.code === 0 || (r.code === 1 && r.stderr.trim() === '' && r.failure === undefined))
+            return { available: true };
+        return {
+            available: false,
+            why: bi(`secret-tool 连不上钥匙串服务（${detail(r)}）。要在桌面会话里运行着 GNOME Keyring 或 KWallet；没有桌面的服务器上一般没有`, `secret-tool cannot reach a keyring service (${detail(r)}). It needs GNOME Keyring or KWallet running in a desktop session; servers without a desktop usually have none`),
+        };
+    }
     async get(account) {
         checkAccount(account);
-        const r = await run('secret-tool', ['lookup', 'service', SERVICE, 'account', account]);
+        const r = await this.tool.run(['lookup', 'service', SERVICE, 'account', account]);
         return r.code === 0 && r.stdout !== '' ? r.stdout.replace(/\n$/, '') : undefined;
     }
     async set(account, secret) {
         checkAccount(account);
         checkSecret(secret);
-        const r = await run('secret-tool', ['store', '--label', `${SERVICE} ${account}`, 'service', SERVICE, 'account', account], secret);
+        const r = await this.tool.run(['store', '--label', `${SERVICE} ${account}`, 'service', SERVICE, 'account', account], secret);
         if (r.code !== 0)
             throw new Error(`Secret Service refused to save the password (${r.stderr.trim() || r.code})`);
     }
     async delete(account) {
         checkAccount(account);
-        await run('secret-tool', ['clear', 'service', SERVICE, 'account', account]);
+        await this.tool.run(['clear', 'service', SERVICE, 'account', account]);
     }
 }
-/** For tests: secrets in memory only. */
+/** For tests: secrets in memory only; `unavailable` plays a machine without a keychain. */
 export class MemorySecrets {
     kind = 'memory';
     map = new Map();
-    async available() { return true; }
-    async get(account) { return this.map.get(account); }
-    async set(account, secret) { checkAccount(account); checkSecret(secret); this.map.set(account, secret); }
+    unavailable;
+    constructor(unavailable) { this.unavailable = unavailable; }
+    async status() { return this.unavailable === undefined ? { available: true } : { available: false, why: this.unavailable }; }
+    async get(account) { return this.unavailable === undefined ? this.map.get(account) : undefined; }
+    async set(account, secret) {
+        checkAccount(account);
+        checkSecret(secret);
+        if (this.unavailable !== undefined)
+            throw new Error(this.unavailable.en);
+        this.map.set(account, secret);
+    }
     async delete(account) { this.map.delete(account); }
 }
 /** The keychain of the platform this runs on. */

package/lib/core/settings.js

@@ -9,6 +9,7 @@ import { MishuError, bi } from "./i18n.js";
 import { resolveAccount, secretAccount } from "./mail/account.js";
 import { MAIL_SOURCE } from "./mail/sync.js";
 import { CATEGORIES } from "./recur.js";
+import { secretFromEnv } from "./secrets.js";
 const SETTINGS_KEY = 'settings';
 const ACCOUNTS_KEY = 'mail.accounts';
 const NEXT_ID_KEY = 'mail.nextId';
@@ -56,7 +57,9 @@ export function mailAccounts(store) {
 /**
  * Add (no id) or update an account. A new password, when given, goes to the
  * keychain before the account is saved, so a failed keychain write leaves
- * nothing half-saved.
+ * nothing half-saved. Without a usable keychain the password is not kept
+ * anywhere: the account is saved and reads it from the environment variable
+ * shown on the settings page (`secretEnvName`).
  */
 export async function saveMailAccount(store, secrets, input, password, now) {
     const accounts = mailAccounts(store);
@@ -65,9 +68,10 @@ export async function saveMailAccount(store, secrets, input, password, now) {
         throw new MishuError(bi(`没有 #${input.id} 这个邮箱账户`, `there is no mail account #${input.id}`));
     const id = existing?.id ?? (store.get(NEXT_ID_KEY) ?? 1);
     const account = resolveAccount({ ...existing, ...input }, id);
-    if (password !== undefined && password !== '')
+    const keychain = (await secrets.status()).available;
+    if (keychain && password !== undefined && password !== '')
         await secrets.set(secretAccount(id), password);
-    else if (existing === undefined && await secrets.get(secretAccount(id)) === undefined) {
+    else if (keychain && existing === undefined && await secrets.get(secretAccount(id)) === undefined && secretFromEnv(secretAccount(id)) === undefined) {
         throw new MishuError(bi('新邮箱要填密码（授权码）', 'a new account needs its password (app password)'));
     }
     store.set(ACCOUNTS_KEY, existing === undefined ? [...accounts, account] : accounts.map(a => (a.id === id ? account : a)));

package/lib/dsh/api.js

@@ -9,7 +9,7 @@
  * travel inward: they go straight to the keychain, and no endpoint ever
  * returns one.
  */
-import { addDays, addSeries, buildAsk, buildBoard, buildDetail, dayOf, deleteMailAccount, describeMailError, MishuError, describeSeries, detectLang, errorText, GitHubClient, MAIL_PRESETS, mailReportKey, resolveGithubToken, resolveSeries, saveMailAccount, saveSettings, secretAccount, secretEnvName, setStatusByUser, snoozeByUser, stopSeries, tickManual, } from "../core/index.js";
+import { addDays, addSeries, bi, buildAsk, buildBoard, buildDetail, dayOf, deleteGithubToken, deleteMailAccount, describeMailError, MishuError, describeSeries, detectLang, errorText, GitHubClient, MAIL_PRESETS, mailReportKey, NEW_TOKEN_URL, resolveSeries, saveGithubToken, saveMailAccount, saveSettings, secretAccount, secretEnvName, setStatusByUser, snoozeByUser, stopSeries, tickManual, } from "../core/index.js";
 import { resolveAccount } from "../core/mail/account.js";
 export const API_BASE = '/api/dsh-mishu';
 class ApiError extends Error {
@@ -82,14 +82,8 @@ export function apiHandlers(runtime, clock = Date.now) {
     /** Everything the settings page shows. No secret is ever included. */
     const settingsView = async (lang) => {
         const store = need(lang);
-        const token = await resolveGithubToken(runtime.config.github.tokenEnv, runtime.config.github.useGhCli);
-        let available = false;
-        try {
-            available = await runtime.secrets.available();
-        }
-        catch {
-            available = false;
-        }
+        const token = await runtime.githubToken();
+        const secrets = await runtime.secrets.status().catch((error) => ({ available: false, why: bi(error.message, error.message) }));
         const accounts = await Promise.all(runtime.accounts().map(async (a) => ({
             ...a,
             hasPassword: (await runtime.mailPassword(a.id)) !== undefined,
@@ -102,9 +96,10 @@ export function apiHandlers(runtime, clock = Date.now) {
             github: {
                 tokenEnv: runtime.config.github.tokenEnv,
                 token: 'error' in token ? { found: false, text: token.error[lang] } : { found: true, from: token.from },
+                newTokenUrl: NEW_TOKEN_URL,
                 lastSync: store.get('github.lastSync') ?? null,
             },
-            secrets: { kind: runtime.secrets.kind, available },
+            secrets: { kind: runtime.secrets.kind, available: secrets.available, ...secrets.available ? {} : { why: secrets.why[lang] } },
             accounts,
             presets: MAIL_PRESETS.map(p => ({ id: p.id, label: p.label[lang], host: p.host, port: p.port, secure: p.secure, supported: p.supported, howTo: p.howTo[lang] })),
         };
@@ -187,6 +182,7 @@ export function apiHandlers(runtime, clock = Date.now) {
                 ...ask.id === undefined ? {} : { id: Number(ask.id) },
                 ...ask.accountId === undefined ? {} : { accountId: Number(ask.accountId) },
                 ...ask.preset === undefined ? {} : { preset: String(ask.preset) },
+                ...typeof ask.error === 'string' && ask.error !== '' ? { error: ask.error.slice(0, 1000) } : {},
             };
             const prompt = buildAsk(need(lang), request, { now: clock(), lang, markRead: runtime.settings().markRead, accounts: runtime.accounts() });
             return { prompt };
@@ -200,12 +196,22 @@ export function apiHandlers(runtime, clock = Date.now) {
         },
         '/github/test': async (body) => {
             const lang = langOf(body);
-            const token = await resolveGithubToken(runtime.config.github.tokenEnv, runtime.config.github.useGhCli);
+            const token = await runtime.githubToken();
             if ('error' in token)
                 throw new ApiError(token.error[lang]);
             const user = await new GitHubClient({ token: token.token }).user();
             return { login: user.login, from: token.from };
         },
+        /** A pasted token: checked with GitHub, then kept in the keychain only. */
+        '/github/token/save': async (body) => {
+            const lang = langOf(body);
+            const { login } = await saveGithubToken(runtime.secrets, typeof body.token === 'string' ? body.token : '');
+            return { login, view: await settingsView(lang) };
+        },
+        '/github/token/delete': async (body) => {
+            await deleteGithubToken(runtime.secrets);
+            return { view: await settingsView(langOf(body)) };
+        },
         '/mail/save': async (body) => {
             const lang = langOf(body);
             const account = await saveMailAccount(need(lang), runtime.secrets, accountInput(body.account), password(body), clock());

package/lib/dsh/runtime.js

@@ -60,11 +60,15 @@ export class Runtime {
         }
         return secretFromEnv(secretAccount(id));
     }
+    /** The GitHub token: environment, then the keychain, then the GitHub CLI. */
+    githubToken() {
+        return resolveGithubToken({ envName: this.config.github.tokenEnv, useGhCli: this.config.github.useGhCli, secrets: this.secrets });
+    }
     async syncGithubNow(store) {
         const settings = this.settings();
         if (!settings.githubEnabled)
             return;
-        const token = await resolveGithubToken(this.config.github.tokenEnv, this.config.github.useGhCli);
+        const token = await this.githubToken();
         if ('error' in token) {
             const report = { at: Date.now(), notifications: 0, opened: 0, closed: 0, wouldMarkRead: 0, markedRead: 0, checkFailures: 0, apiCalls: 0, error: token.error };
             store.set('github.lastSync', report);

package/lib/types/core/ask.d.ts

@@ -28,6 +28,7 @@ export type AskRequest = {
 } | {
     kind: 'mail-setup';
     preset: string;
+    error?: string;
 };
 export interface AskOptions {
     now: number;

package/lib/types/core/exec.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Running the few helper programs the secretary uses (`security`,
+ * `secret-tool`, PowerShell, `gh`).
+ *
+ * An app started from the Dock, the Start menu or a service manager often
+ * gets a short PATH that misses where package managers put programs, so a
+ * program installed with Homebrew, winget or `~/.local/bin` looks missing.
+ * `findProgram` looks on PATH first, then in those usual places.
+ */
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** Node's own message when the program could not start or was killed. */
+    failure?: string;
+}
+interface Where {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}
+/** The usual install places of command-line programs, after PATH. */
+export declare function usualDirs({ platform, env, home }?: Where): string[];
+/** The full path of a program, or `undefined` when it is not installed anywhere we know of. */
+export declare function findProgram(name: string, where?: Where): string | undefined;
+/** Run a program; `input` goes to its stdin (secrets never go on the command line). Never rejects. */
+export declare function runProgram(file: string, args: string[], input?: string, timeout?: number): Promise<RunResult>;
+export {};

package/lib/types/core/github/client.d.ts

@@ -131,6 +131,8 @@ export declare class GitHubClient {
     user(): Promise<{
         login: string;
     }>;
+    /** Whether this token may read notifications (fine-grained tokens get 403). */
+    canReadNotifications(): Promise<boolean>;
     repo(fullName: string): Promise<RepoInfo>;
     pull(apiUrl: string): Promise<PullInfo>;
     issue(apiUrl: string): Promise<IssueInfo>;

package/lib/types/core/github/token.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where the GitHub token comes from, in this order:
+ *
+ *   1. the environment variable named in the config (GITHUB_TOKEN)
+ *   2. a token you pasted on the settings page, kept in the system keychain
+ *   3. the GitHub CLI (`gh auth token`), which keeps its own in the keychain
+ *
+ * A token is never written to the notebook or a file.
+ */
+import { type Bi } from '../i18n.ts';
+import type { SecretStore } from '../secrets.ts';
+import { type FetchLike } from './client.ts';
+/** The keychain entry for a token pasted on the settings page. */
+export declare const GITHUB_SECRET = "github";
+/** Opens GitHub's "new classic token" page with the two scopes ticked. */
+export declare const NEW_TOKEN_URL = "https://github.com/settings/tokens/new?scopes=notifications,repo&description=DSH%20mishu";
+export type TokenSource = 'env' | 'keychain' | 'gh';
+export type TokenResult = {
+    token: string;
+    from: TokenSource;
+} | {
+    error: Bi;
+};
+/** `ghPath` is for tests: a fixed path, or `null` for "not installed". */
+export declare function resolveGithubToken(options: {
+    envName: string;
+    useGhCli: boolean;
+    secrets?: SecretStore;
+    ghPath?: string | null;
+}): Promise<TokenResult>;
+/**
+ * Check a pasted token with GitHub, then keep it in the keychain. It must
+ * read notifications, which only classic tokens with the `notifications`
+ * scope can (fine-grained tokens cannot reach that API).
+ */
+export declare function saveGithubToken(secrets: SecretStore, raw: string, fetch?: FetchLike): Promise<{
+    login: string;
+}>;
+export declare function deleteGithubToken(secrets: SecretStore): Promise<void>;

package/lib/types/core/index.d.ts

@@ -2,7 +2,6 @@
  * mishu core — everything that does not depend on DSH.
  * Nothing under `src/core` may import DSH; `tests/boundary.test.ts` enforces it.
  */
-import { type Bi } from './i18n.ts';
 export { buildAsk, detailText, type AskRequest } from './ask.ts';
 export { buildBoard, buildDetail, type BoardCard, type BoardData, type CardAction, type DoneGroup, type MatterDetail } from './board.ts';
 export type { CardExplain } from './explain.ts';
@@ -11,6 +10,7 @@ export { GitHubClient, GitHubError, type FetchLike, type Notification } from './
 export { gatherFacts, Lookups, parseCheckSuiteTitle, type Facts } from './github/facts.ts';
 export { CLOSING_REASONS, judge, type Explain, type Verdict } from './github/rules.ts';
 export { syncGithub, type GithubSyncReport, type MarkReadMode } from './github/sync.ts';
+export { deleteGithubToken, GITHUB_SECRET, NEW_TOKEN_URL, resolveGithubToken, saveGithubToken, type TokenResult, type TokenSource } from './github/token.ts';
 export { bi, decode, detectLang, errorText, LANGS, MishuError, pick, type Bi, type Lang } from './i18n.ts';
 export { addSeries, describeActiveSeries, describeSeries, resolveSeries, stopSeries, tickManual, upcoming, type ResolvedSeries, type SeriesInput, } from './manual.ts';
 export { DEFAULT_DEMOTION, isActive, isDemoted, setStatusByUser, snoozeByUser, type DemotionPolicy } from './matters.ts';
@@ -21,7 +21,8 @@ export { MAIL_PRESETS, presetById, secretAccount, type MailAccount, type MailFet
 export { ImapFetcher } from './mail/imap.ts';
 export { judgeMail } from './mail/rules.ts';
 export { describeMailError, MAIL_SOURCE, mailReportKey, syncMail, type MailSyncReport } from './mail/sync.ts';
-export { MemorySecrets, secretEnvName, secretFromEnv, systemSecrets, type SecretStore } from './secrets.ts';
+export { findProgram } from './exec.ts';
+export { MemorySecrets, secretEnvName, secretFromEnv, systemSecrets, type SecretStatus, type SecretStore } from './secrets.ts';
 export { deleteMailAccount, effectiveSettings, mailAccounts, saveMailAccount, saveSettings, type Defaults, type UserSettings } from './settings.ts';
 export declare const DEFAULT_HOME = "~/.mishu";
 /** `~` and `~/…` expand to the home directory on every platform. */
@@ -30,13 +31,3 @@ export declare function mishuPaths(home: string): {
     root: string;
     db: string;
 };
-/**
- * A GitHub token without storing one: the named environment variable, else
- * the GitHub CLI (`gh auth token`, which reads the system credential store).
- */
-export declare function resolveGithubToken(envName: string, useGhCli: boolean): Promise<{
-    token: string;
-    from: 'env' | 'gh';
-} | {
-    error: Bi;
-}>;

package/lib/types/core/mail/sync.d.ts

@@ -8,7 +8,7 @@
  */
 import { type Bi } from '../i18n.ts';
 import type { MishuStore } from '../store.ts';
-import type { MailAccount, MailFetcher } from './account.ts';
+import { type MailAccount, type MailFetcher } from './account.ts';
 export declare const MAIL_SOURCE = "mail";
 export interface MailSyncReport {
     at: number;
@@ -19,7 +19,7 @@ export interface MailSyncReport {
     error?: Bi;
 }
 /** A connection or login failure, said so a person knows what to fix. */
-export declare function describeMailError(error: unknown, account: Pick<MailAccount, 'host' | 'port'>): Bi;
+export declare function describeMailError(error: unknown, account: Pick<MailAccount, 'host' | 'port' | 'preset'>): Bi;
 export declare function mailReportKey(accountId: number): string;
 export declare function syncMail(options: {
     store: MishuStore;

package/lib/types/core/secrets.d.ts

@@ -10,20 +10,30 @@
  * stored under the service name "dsh-mishu". When no keychain is available,
  * `secretFromEnv` is the documented fallback.
  */
+import { type Bi } from './i18n.ts';
 export declare const SERVICE = "dsh-mishu";
+/** Whether secrets can be kept here, and if not, why and what to do. */
+export type SecretStatus = {
+    available: true;
+} | {
+    available: false;
+    why: Bi;
+};
 export interface SecretStore {
     /** Where secrets go, for the settings page ("macOS 钥匙串"). */
     readonly kind: 'macos' | 'windows' | 'linux' | 'memory';
-    available(): Promise<boolean>;
+    status(): Promise<SecretStatus>;
     get(account: string): Promise<string | undefined>;
     set(account: string, secret: string): Promise<void>;
     delete(account: string): Promise<void>;
 }
-/** For tests: secrets in memory only. */
+/** For tests: secrets in memory only; `unavailable` plays a machine without a keychain. */
 export declare class MemorySecrets implements SecretStore {
     readonly kind: "memory";
     private readonly map;
-    available(): Promise<boolean>;
+    private readonly unavailable;
+    constructor(unavailable?: Bi);
+    status(): Promise<SecretStatus>;
     get(account: string): Promise<string | undefined>;
     set(account: string, secret: string): Promise<void>;
     delete(account: string): Promise<void>;

package/lib/types/core/settings.d.ts

@@ -9,7 +9,7 @@ import type { MarkReadMode } from './github/sync.ts';
 import { type Lang } from './i18n.ts';
 import { type MailAccount } from './mail/account.ts';
 import { type Category } from './recur.ts';
-import type { SecretStore } from './secrets.ts';
+import { type SecretStore } from './secrets.ts';
 import type { MishuStore } from './store.ts';
 export interface Defaults {
     language: 'auto' | Lang;
@@ -30,7 +30,9 @@ export declare function mailAccounts(store: MishuStore): MailAccount[];
 /**
  * Add (no id) or update an account. A new password, when given, goes to the
  * keychain before the account is saved, so a failed keychain write leaves
- * nothing half-saved.
+ * nothing half-saved. Without a usable keychain the password is not kept
+ * anywhere: the account is saved and reads it from the environment variable
+ * shown on the settings page (`secretEnvName`).
  */
 export declare function saveMailAccount(store: MishuStore, secrets: SecretStore, input: Partial<MailAccount>, password: string | undefined, now: number): Promise<MailAccount>;
 /** Remove an account, its keychain entry, and close what is still open from it. */

package/lib/types/dsh/runtime.d.ts

@@ -4,7 +4,7 @@
  * what you set on the settings page on top), the keychain, and one sync of
  * every source at a time.
  */
-import { type Defaults, type Lang, type MailAccount, type MailFetcher, type MailSyncReport, type MishuStore, type SecretStore } from '../core/index.ts';
+import { type Defaults, type Lang, type MailAccount, type MailFetcher, type MailSyncReport, type MishuStore, type SecretStore, type TokenResult } from '../core/index.ts';
 import type { MishuConfig } from './config.ts';
 interface Logger {
     info(message: string): void;
@@ -27,6 +27,8 @@ export declare class Runtime {
     brief(lang?: Lang): string;
     /** The password for an account: keychain first, then the documented environment variable. */
     mailPassword(id: number): Promise<string | undefined>;
+    /** The GitHub token: environment, then the keychain, then the GitHub CLI. */
+    githubToken(): Promise<TokenResult>;
     private syncGithubNow;
     /** One account; the result is also kept as its last report. */
     syncMailAccount(account: MailAccount): Promise<MailSyncReport | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mishu",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "DSH secretary (小秘书) for DeepSeek Harness (dsh): watches GitHub notifications and the dated things you tell it (bills, renewals, documents, birthdays), closes what is already resolved, and keeps a short list of what actually needs you. Bilingual (中文 / English), macOS / Windows / Linux. · DSH 小秘书：提醒、通知、待办、消息、收件箱、秘书。GitHub 通知按当前状态分诊，交代一句就记下到期和周期事项。",
   "type": "module",
   "main": "lib/index.js",