dsh-tiddlywiki 0.28.13 → 0.29.0

package/src/host/routes-session.ts

@@ -73,8 +73,16 @@ export interface SessionRouteDeps {
  * renders all three. `set` persists a choice, or clears it with `undefined`.
  */
 export interface SessionScopeFace {
-  /** Current choice + what it resolves to (and why, when it cannot serve). */
-  get: (sessionId: string) => { scope?: string; resolved?: { id: string; label: string }; reason?: string }
+  /**
+   * Current choice + what it resolves to (and why, when it cannot serve).
+   *
+   * `mode` is the registry mode (v0.29.0): without it a client cannot tell
+   * "`resolved` is the answer because there is only one wiki" (single install →
+   * keep the old DOM) from "`resolved` is the DEFAULT wiki this session's tools
+   * actually act on" (multi → its links must open THAT wiki, not whichever one
+   * the GUI happens to be focused on).
+   */
+  get: (sessionId: string) => { scope?: string; resolved?: { id: string; label: string }; reason?: string; mode?: string }
   /** Point the session at a wiki, or clear the choice with `undefined`. */
   set: (sessionId: string, wikiId: string | undefined) => Promise<void>
 }

package/src/host/routes.ts

@@ -195,6 +195,17 @@ export interface RouteDeps {
   uiDefaults: (req: IncomingMessage) => UiDefaultsPublic
   /** Absolute folder of the targeted wiki. */
   getWikiPath: (req: IncomingMessage) => string
+  /**
+   * Why this request names a knowledge base that cannot serve it (v0.29.0).
+   *
+   * Returns an actionable sentence when `?wiki=<id>` names a REGISTERED but
+   * STOPPED wiki, `undefined` otherwise (no selector / running / unknown id).
+   * Routes that already 503 on a missing client use it to NAME the wiki; the
+   * ones whose accessors have a harmless-looking fallback (config, wiki path,
+   * seed status) MUST check it first, or they answer with ANOTHER wiki's data —
+   * the silent-wrong-wiki class this hook exists to close.
+   */
+  targetProblem?: (req: IncomingMessage) => string | undefined
   /**
    * After a pull moved HEAD: restart the running wikis whose content actually
    * changed, and report their ids (v0.28.0). `changedFiles` are
@@ -572,8 +583,33 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
    */
   const twProxyAbsoluteBase = (req: IncomingMessage): string | undefined => absoluteHostBase(req.headers.host, TW_PROXY_PATH)
 
+  /**
+   * 503 when `?wiki=<id>` names a REGISTERED but STOPPED knowledge base (v0.29.0).
+   *
+   * Before this, such a request fell through to the DEFAULT wiki — the settings
+   * page said 「正在配置：books」 and then synced/restarted/uploaded into the work
+   * wiki, silently. `deps.targetProblem` is the single place that knows the
+   * difference between "unknown id" (still falls back: stale bookmark) and
+   * "known but not running" (must refuse), so every route that can act asks it.
+   */
+  const refuseStoppedTarget = (req: IncomingMessage, res: ServerResponse): boolean => {
+    const problem = deps.targetProblem?.(req)
+    if (problem === undefined) return false
+    json(res, { ok: false, error: problem }, 503)
+    return true
+  }
+
+  /**
+   * The 503 body for "no running wiki behind this request": names the wiki when
+   * the request asked for one that is stopped, otherwise the historical text.
+   */
+  const notRunning = (req: IncomingMessage): string => deps.targetProblem?.(req) ?? 'wiki service is not running'
+
   const handleStatus = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     if (rejectNonRead(req, res)) return
+    // A `?wiki=` that names a stopped wiki must not answer with ANOTHER wiki's
+    // path/git/note defaults (the settings page's 状态 row reads exactly this).
+    if (refuseStoppedTarget(req, res)) return
     const view = deps.server(req)?.status() ?? { status: 'stopped' as const, wikiPath: deps.getWikiPath(req), logs: [] }
     const gitSummary = await cachedGitStatus(req)
     json(res, {
@@ -656,7 +692,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       }
       const client = deps.getClient(req)
       if (client === undefined) {
-        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        json(res, { ok: false, error: notRunning(req) }, 503)
         return
       }
       const title = typeof body.title === 'string' && body.title.trim().length > 0 ? body.title.trim() : timestampTitle()
@@ -700,7 +736,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
       const body = JSON.parse(await readBody(req)) as { title?: unknown; tag?: unknown; tags?: unknown; text?: unknown; expectedModified?: unknown; expectedRevision?: unknown; force?: unknown }
       const client = deps.getClient(req)
       if (client === undefined) {
-        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        json(res, { ok: false, error: notRunning(req) }, 503)
         return
       }
       const title = typeof body.title === 'string' && body.title.trim().length > 0 ? body.title.trim() : timestampTitle()
@@ -738,7 +774,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     if (rejectNonRead(req, res)) return
     const client = deps.getClient(req)
     if (client === undefined) {
-      json(res, { ok: false, error: 'wiki service is not running' }, 503)
+      json(res, { ok: false, error: notRunning(req) }, 503)
       return
     }
     try {
@@ -767,7 +803,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     if (rejectNonRead(req, res)) return
     const client = deps.getClient(req)
     if (client === undefined) {
-      json(res, { ok: false, error: 'wiki service is not running' }, 503)
+      json(res, { ok: false, error: notRunning(req) }, 503)
       return
     }
     try {
@@ -800,7 +836,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     if (rejectNonRead(req, res)) return
     const client = deps.getClient(req)
     if (client === undefined) {
-      json(res, { ok: false, error: 'wiki service is not running' }, 503)
+      json(res, { ok: false, error: notRunning(req) }, 503)
       return
     }
     try {
@@ -861,7 +897,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     if (rejectNonRead(req, res)) return
     const client = deps.getClient(req)
     if (client === undefined) {
-      json(res, { ok: false, error: 'wiki service is not running' }, 503)
+      json(res, { ok: false, error: notRunning(req) }, 503)
       return
     }
     try {
@@ -923,6 +959,9 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
   const handleRestart = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
       if (rejectCrossSiteWrite(req, res, ['POST'])) return
+      // Sync is a repository/folder operation on the target wiki's path: without
+      // this check a stopped `?wiki=` would pull+commit+push the DEFAULT repo.
+      if (refuseStoppedTarget(req, res)) return
       if (!beginMutation('restart')) {
         json(res, { ok: false, error: '另一个重启/同步正在进行中，请稍候' }, 429)
         return
@@ -955,6 +994,9 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
    *  UI reflects the pulled files instead of looking stale. */
   const handleSync = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     if (rejectCrossSiteWrite(req, res, ['POST'])) return
+    // Same reason as /restart: the folder comes from the target, and a stopped
+    // `?wiki=` used to fall back to the DEFAULT wiki's repository.
+    if (refuseStoppedTarget(req, res)) return
     if (!beginMutation('sync')) {
       json(res, { ok: false, error: '另一个重启/同步正在进行中，请稍候' }, 429)
       return
@@ -1048,6 +1090,7 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
   const handleUpload = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
       if (rejectCrossSiteWrite(req, res, ['POST'])) return
+      if (refuseStoppedTarget(req, res)) return
       const buf = await readBodyBuffer(req)
       // Name comes from ?name= (URL-encoded) or the X-Filename header.
       const url = new URL(req.url ?? '/', 'http://127.0.0.1')

package/src/host/seed-wechat-docs.ts

@@ -29,7 +29,7 @@ export const WECHAT_DOCS_MARKER_TITLE = '$:/plugins/dsh-tiddlywiki/seed-wechat-d
  * registry's `content` declaration re-exports the same constant, so the
  * v0.22.0 content-hash bookkeeping guards exactly these bytes).
  */
-export const WECHAT_DOCS_TEXT = "# 微信公众号发布：换机器还原指南\n\n> **这是可选功能，默认关闭，需要额外安装。** 插件本体**不含**它：真正干活的是仓库\n> `tools/wechat/` 下的 opencli adapter + Browser Bridge 浏览器扩展。**不安装／不开启，\n> 插件的其他功能完全不受影响**（不注入发布相关提示词、不往 wiki 写发布规范文档）。\n>\n> 目的：在**另一台机器**上无缝还原「TiddlyWiki 笔记 → 微信公众号」的发布能力。\n> 本机（开发机）已验证全程可跑；本文按顺序照做即可复现。\n>\n> 关键结论先讲：**整套发布走浏览器自动化，不依赖公众号服务端 API**——因为\n> 2025-07 起官方已回收个人主体账号的「发布能力」接口权限（详见 §5）。\n\n---\n\n## 0. 它是可选功能：需要什么、不影响什么\n\n| | 说明 |\n|---|---|\n| **默认状态** | **关闭**（`wechat.enabled` 默认 `false`） |\n| **开启方式** | DSH 设置 →「TiddlyWiki 知识库」→「可选功能：微信公众号发布」→ 勾选 → 保存配置 |\n| **开启后有什么变化** | ① 注入提示词多一行「发布前先读发布元数据规范」；② 启动时把该规范文档写进 wiki（同名不覆盖）。**仅此两项**——不会安装任何东西、不会启用任何后台服务 |\n| **不开启会怎样** | 提示词里没有发布相关文字；wiki 里不会出现「发布元数据规范」；其他功能一切照旧 |\n| **插件会替你做安装吗** | **不会**。opencli 与浏览器扩展必须你手动装（见 §1–§2）——这属于插件外部的工具链 |\n| **要额外装什么** | ① opencli（npm 包）② Browser Bridge 浏览器扩展 ③ 浏览器登录公众号 |\n| **凭据如何保存** | 不保存任何凭据：复用浏览器已有登录态（cookie）。脚本不接触 AppSecret |\n\n> 一句话：**开关只控制「插件要不要配合这个流程」，不负责装工具链。**\n\n---\n\n## 1. 一分钟总览\n\n```\nTiddlyWiki 笔记（tiddler）\n   │  标题\n   ▼\nDSH 的 POST /dsh-tiddlywiki/render        ← TW 自己渲染成语义 HTML（含代码高亮）\n   │  纯语义 HTML（无内联样式）\n   ▼\nwechat-html.js  decorate()                ← 补内联样式（微信唯一认的形式）\n   │  带内联样式的 HTML\n   ▼\nopencli + Browser Bridge 扩展             ← 驱动你已登录的浏览器\n   │  填标题/作者/摘要 + insertHTML 写正文 + 传图 + 设封面 + 存草稿\n   ▼\n公众号草稿箱（mp.weixin.qq.com）\n   │  （可选 --publish）\n   ▼\n点「发表」→ ⚠️ 管理员扫码确认 → 发布成功\n```\n\n**一条命令**（在第二台机器上，装好后）：\n\n```bash\nopencli weixin publish-note \"笔记标题\" --trace retain-on-failure -f json\n```\n\n---\n\n## 1. 需要安装/准备的东西\n\n按顺序做；**最后一步才是打开插件里的开关**（开关只影响提示词与文档，装不上工具链）。\n\n| # | 项目 | 怎么装 | 验证 |\n|---|---|---|---|\n| 1 | **Node.js ≥ 22** | 官网安装包 | `node -v` |\n| 2 | **DSH** + **dsh-tiddlywiki 插件** | 本仓库的插件（含 wiki） | `curl http://127.0.0.1:3080/dsh-tiddlywiki/status` |\n| 3 | **opencli** | `npm install -g @jackwener/opencli` | `opencli --version` |\n| 4 | **Browser Bridge 扩展** | 见 §2（二选一） | `opencli doctor` 显示 `Extension: connected` |\n| 5 | **Chrome/Edge + 公众号登录** | 浏览器登录 mp.weixin.qq.com | 能进后台首页 |\n| 6 | **本仓库的 adapter** | `node tools/wechat/install-wechat-adapters.mjs` | 脚本自检输出 ✔ |\n| 7 | **打开插件开关** | 设置 →「TiddlyWiki 知识库」→「可选功能：微信公众号发布」勾选 → 保存配置 | 提示词预览里出现「发布元数据规范」一行 |\n\n> **opencli 版本建议 ≥ 1.8.7**（本方案在该版本实测通过；1.7.x 的 `browser`\n> 子命令语法不同，且内置 weixin adapter 不完整）。\n>\n> **新版 npm 的 allowScripts 机制会拦 opencli 的 postinstall 脚本**（安装时打\n> warning）：**无害，可忽略**——postinstall 只装 bash/zsh/fish 补全（Windows 用不上），\n> adapters 随 npm 包自带，功能不受影响。\n>\n> 第 7 步之前，插件不会注入任何发布相关提示词、也不会往 wiki 写「发布元数据规范」。\n> 也就是说：**没装好工具链时开关可以一直关着，不影响任何其他功能。**\n\n### 自动化的终点：草稿箱（2026-09-17 与用户确认的策略）\n\n**adapter 负责到「草稿落盘」为止**：填标题/作者/摘要、写正文、传图、设封面、存草稿。\n**发表由人工在后台完成**——点「发表」时平台会弹确认对话框（原创声明、作者、留言\n设置等）以及最后的管理员扫码；原创声明涉及账号权益，人工点最稳妥。`--publish`\n选项保留（best-effort：点「发表」后轮询等扫码），但**不处理中途弹窗**，遇到弹窗\n会一直等到超时。\n\n---\n\n## 2. 安装 Browser Bridge 扩展（关键前置）\n\n扩展**不在 npm 包里**，必须单独装。二选一：\n\n**方式 A — Chrome Web Store（推荐）**\n1. 打开 https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk\n2. 点「添加至 Chrome」\n\n**方式 B — GitHub Releases（Web Store 打不开时）**\n1. 到 https://github.com/jackwener/opencli/releases 下载 `opencli-extension-v*.zip`\n2. 解压到某个固定目录\n3. 浏览器打开 `chrome://extensions` → 开启右上角「开发者模式」\n4. 点「加载已解压的扩展程序」→ 选择解压出的目录\n\n> ⚠️ GitHub 的 ext release **经常落后于 Web Store**（2026-09-17 实测只到\n> `ext-v1.0.21`，Web Store 已是 1.0.24）。**扩展版本以 Chrome Web Store 为准**；\n> GitHub 方式只作 Web Store 打不开时的离线兜底。\n\n**验证**：\n\n```bash\nopencli doctor\n# 期望： [OK] Daemon: running ...\n#        [OK] Extension: connected (vX.Y.Z)\n#        [OK] Connectivity: connected\n#        Everything looks good!\n```\n\n若报 `Extension: not connected`：确认浏览器在运行、扩展已启用；再 `opencli daemon stop` 后重跑 `opencli doctor`（daemon 会自动重启）。\n\n---\n\n## 3. 装 adapter 并试跑\n\n```bash\ncd <本仓库>\nnode tools/wechat/install-wechat-adapters.mjs\n```\n\n脚本会把 `tools/wechat/*.js` 复制到 `~/.opencli/clis/weixin/`（Windows：`C:\\Users\\<你>\\.opencli\\clis\\weixin\\`）。\n这些是**私有 adapter**，放在该目录即可被 opencli 自动发现，**无需任何构建**。\n\n然后：\n\n```bash\n# ① 先干跑：只做 TW 渲染 + 排版装饰，导出预览，不碰微信\nopencli weixin publish-note \"某篇笔记标题\" --preview ./out --trace retain-on-failure\n\n#    → 用浏览器打开 ./out.html 肉眼确认排版\n#    （注意：--preview 仍会继续执行发布流程；只想预览时看文件即可，或 Ctrl-C）\n\n# ② 真发到草稿箱\nopencli weixin publish-note \"某篇笔记标题\" --trace retain-on-failure -f json\n\n# ③ 带封面（公众号封面必填，否则草稿显示\"内容不完整\"）\nopencli weixin publish-note \"某篇笔记标题\" --cover ./cover.png --trace retain-on-failure -f json\n\n# ④ 直接发表（⚠️ 会真发文章，需管理员扫码）\nopencli weixin publish-note \"某篇笔记标题\" --publish --trace retain-on-failure -f json\n\n# ⑤ 正文多图（v0.23.2+）：TW 笔记内嵌 [img[...]] 经 /render 变成 data URI，\n#    publish-note 传不了（微信存草稿时过滤非 mmbiz 图）——用 publish-note-imgs：\nopencli weixin publish-note-imgs \"某篇笔记标题\" --images <图片目录> --trace retain-on-failure -f json\nopencli weixin publish-note-imgs \"某篇笔记标题\" --images \"01.png|02.png|03.png\" -f json\n#    · --images 传目录时按文件名排序 = 正文图片出现顺序（封面图排第一）\n#    · 也可用 | 分隔的路径列表精确指定顺序\n#    · 流程：先逐张上传 CDN → 按 DOM 顺序重写正文 src → insertHTML → 选封面 → 存草稿\n#    · 发表前同样读 pub-state / no-publish（只告警不阻断），--publish 可直接发表\n```\n\n### 3.6 在 TiddlyWiki 里点按钮发布（v0.23.3，日常推荐）\n\n不想敲命令时，用**笔记工具栏的「发布到公众号」按钮**（嵌入式 TW 面板、右侧栏 tab、原生编辑弹窗里都在）：\n\n1. 设置页勾选「可选功能：微信公众号发布」并保存 → 重启 dsh web 后，启动 seed 会把按钮插件\n   `$:/plugins/dsh/wechat-publish` 写进 wiki（老 wiki 也可在设置页「初始化」区单独写它）。\n2. 打开任意笔记 → 工具栏点「发布到公众号」→ 按钮**先预检**（opencli 跑不跑得起来、adapter 缺哪些文件），\n   再弹确认框（自动列出 `no-publish` / `pub-state` 警告）→ 点「开始存草稿」。\n3. 宿主进程起一个**后台任务**，覆盖层每 2 秒显示状态与日志尾部。**只到草稿箱为止，不自动发表。**\n\n按钮背后的三条路由（同源；写操作有方法 + CSRF 守卫；`wechat.enabled` 关着时一律 403）：\n\n| 路由 | 方法 | 作用 |\n|---|---|---|\n| `/dsh-tiddlywiki/wechat/ready` | GET | 预检：`opencli --version` 能否跑通、adapter 缺哪些文件 |\n| `/dsh-tiddlywiki/wechat/publish` | POST | 起任务（body `{title, adapter?}`）；单并发，第二次调用 409 |\n| `/dsh-tiddlywiki/wechat/publish/status` | GET | 轮询任务（`?id=`；不带 id 取最新/正在跑的那个） |\n\n可配项（设置页目前只暴露 `enabled`，其余写进配置 tiddler\n`$:/plugins/dsh-tiddlywiki/config` 的 `wechat` 块，保存即生效）：\n\n| 键 | 默认 | 说明 |\n|---|---|---|\n| `wechat.enabled` | `false` | 总开关；关着时按钮不写入、三条路由 403 |\n| `wechat.adapter` | `publish-note` | 换成 `publish-note-imgs` 走正文内嵌多图（需该 adapter 已装） |\n| `wechat.command` | `opencli` | CLI 路径（装了别名、不在 PATH 时用） |\n| `wechat.token` | 空 | 非空时要求请求头 `x-wechat-publish-token`（按钮会自动带上） |\n| `wechat.dsn` | 空 | adapter 回连 DSH 的基址；留空按请求端口推导 `http://127.0.0.1:<端口>/dsh-tiddlywiki` |\n| `wechat.endpoint` | 空 | **只被 TW 侧读**：覆盖按钮请求的基址（默认 `location.origin + /dsh-tiddlywiki`）；反向代理/远程访问场景用 |\n\n⚠️ 宿主用 **`--title-file`**（v0.23.3 新增参数）把标题经 UTF-8 文件交给 adapter：标题不进 argv，\n否则 Windows 上 `opencli` 的 `.cmd` shim 会把 `&`/`|`/`^` 当命令分隔符，中文标题还会被 cmd 的\n代码页解码成乱码。位置参数 `<title>` 照旧可用（两者都给时位置参数优先）。\n⚠️ 按钮**不替你发表**：发表要管理员扫码（§4.2），请在公众号后台点「发表」。\n\n---\n\n## 3.5 发布元数据（重要：避免重发/误发）\n\nwiki 里既有**早已发布**的文章，也有**明确不能发**的内容。没有记录，agent 只能猜——\n要么重复发已上线的，要么把不该发的推出去。\n\n**规范全文在 wiki 里**：笔记「**发布元数据规范**」（随插件 seed 分发，`dsh-docs` 标签，\n开机自动写入；也可手动跑 `npx tsx tools/wechat/seed-publish-spec-now.mts` 立即写入）。\n注入给 agent 的系统提示词里只有一句指针（slim 预算只剩几十字符，放不下全文）。\n\n### 字段（自定义字段，不是标签）\n\n| 字段 | 含义 | 示例 |\n|---|---|---|\n| `pub-state` | 能不能发 | `draft` / `published` / `excluded` |\n| `pub-platform` | 最近发布的平台（多平台逗号分隔） | `wechat` |\n| `pub-wechat-at` | 公众号发表时间 | `2026-09-17 15:30` |\n| `pub-wechat-title` | 发表时的标题（**仅当与 TW 标题不同才写**） | `中年失业自救指南` |\n| `pub-wechat-url` | 发表后的链接 | `https://mp.weixin.qq.com/s/xxx` |\n| `pub-note` | 备注 | `删改后重发过一版` |\n\n**没有 `pub-state` = 未知状态**，应当当作「需要人确认」，而不是「可以随便发」。\n\n标签 `no-publish` 是给人看的镜像（TW 界面一眼可见、可筛）；`pub-state: excluded` 给\nagent 程序化判断。**两者应一致，冲突时以字段为准。**\n\n### ⚠️ 命名冲突（别占用）\n\n实测本 wiki 里这三个名字**已被占用**，方案特意避开：\n\n- `publish` / `publishyear` 字段 → Obsidian 导入的**书籍**条目用作「出版社 / 出版年」\n  （值形如「新世界出版社」「2011-09-01」）。\n- `发布记录` 标签 → 本插件自己的**版本发布说明**。\n\n### 发布前检查：只告警，不阻断\n\n`publish-note` 会读 `pub-state` / `no-publish`，命中就打印醒目警告，**然后继续执行**\n（2026-09-17 明确选定的策略）。`--force` 只改措辞，不改变行为：\n\n```\n⚠️ 「某篇」已发布过（平台 wechat）。这可能是重复发布——确认无误再继续；确实要重发请加 --force。\n```\n\n### 回写（agent 负责）\n\n发布成功后，命令的 `detail` 里会带一句**建议回写值**，例如：\n\n```\n建议回写：pub-state=published, pub-platform=wechat, pub-wechat-at=\"2026-09-17 17:50\"\n```\n\nagent 据此用 `tiddlywiki_put` 写回（**不传 `tags` 就保留原标签**，只补 `fields`）：\n\n```\ntiddlywiki_put(title=\"某篇\", text=<原正文>, fields={\"pub-state\":\"published\", \"pub-platform\":\"wechat\", \"pub-wechat-at\":\"...\"})\n```\n\n> ⚠️ 用工具时 `text` 会被覆盖，**务必带上原正文**。别像我一样用裸 REST PUT 只发一段\n> 文字——那会把笔记正文清空（真实踩过，靠 git 恢复）。\n\n### 存量回填\n\n早于本规范、来源可辨（`source-path` 含「公众号」）的文章，用脚本回填：\n\n```bash\n# 默认 dry-run，只打印将改什么\nnode tools/wechat/backfill-publish-state.mjs\n\n# 确认后真写\nnode tools/wechat/backfill-publish-state.mjs --write\n\n# 指定标题 / 平台 / 匹配子串\nnode tools/wechat/backfill-publish-state.mjs --title \"打工记\" --title \"鱼\" --write\nnode tools/wechat/backfill-publish-state.mjs --match 公众号 --platform wechat --write\n```\n\n脚本纪律（**请勿改成「只写字段」的裸 PUT**）：每条都先 GET **完整** tiddler（含\ntext/tags/type/created），**只添加** `pub-*` 字段后整体写回；已有 `pub-state` 的跳过\n（幂等）；正文为空的跳过（宁可不动）；**发表时间无法考证就留空，不编造**。\n\n---\n\n## 4. ⚠️ 三个必须知道的坑\n\n### 4.1 所有命令都要带 `--trace retain-on-failure`\n\n不带会对 `mp.weixin.qq.com` 稳定报：\n\n```\nNavigation rejected\n```\n\n**实测**：trace 开 → 5/5 成功；trace 关 → 8/8 失败。这是 opencli 1.8.7 的 bug\n（源码里 trace 只做录像，理论上不该影响导航）。已试过无效的绕法：\n`--site-session ephemeral`、`--keep-tab false`、`--window foreground/background`、\n重置标签页、重启 daemon。**唯一有效就是加 trace。**\n\n### 4.2 发表必须管理员扫码（无法自动化）\n\n后台点「发表」后，微信要求**管理员微信扫码确认**。这不是技术能绕开的账号安全机制。\n所以「一键发布」的真实含义是：\n\n> agent/脚本 完成素材、排版、上传、填表、进草稿箱 —— **你只需扫一次码**。\n\n`--publish` 会自动点「发表」并在终端提示你扫码，然后轮询结果（默认等 180s，\n可用 `--timeout` 调整）。\n\n### 4.3 「发表」≠「群发」（别搞混）\n\n| 操作 | 推送粉丝 | 占群发额度 | 需要扫码 |\n|---|---|---|---|\n| **发表**（本方案默认） | 否（仅生成永久链接） | 否，不限次数 | 是 |\n| **群发** | 是 | 个人订阅号 1 天 1 次 | 是 |\n\n两者都要扫码 → 默认选**不吃额度**的「发表」。\n\n### 4.4 发表阶段的确认弹窗 adapter 不处理（v0.23.x 现状）\n\n`publishDraft` 点完「发表」后**只轮询成功信号**，不会点任何平台弹窗。发表链路上\n还有：原创声明/作者/留言设置等**确认对话框**（2026-09-17 人工发表实测必经）与最后\n的管理员扫码。所以**推荐流程到草稿箱为止**（见 §1），发表环节人工做；`--publish`\n只是 best-effort，遇到弹窗会卡到超时。排错见 §8。\n\n---\n\n## 5. 为什么不用官方 API（背景，避免走回头路）\n\n公众号发布的服务端链路是 `access_token → draft/add → freepublish/submit`。但：\n\n- **2025 年 7 月起，官方回收「发布能力」接口对个人主体、企业未认证、不支持认证账号的调用权限**\n  （[发布能力文档](https://developers.weixin.qq.com/doc/subscription/guide/product/publish.html) 原文注）。\n  个人主体无法做微信认证 → `freepublish/submit` 不可用。\n- 草稿箱 `draft/add` 文档未列该限制，但 48001 / `api unauthorized` 是常见返回。\n- 即便可用，还叠加：**本机公网出口 IP 必须加入 API IP 白名单**（否则 61004/40164）、\n  封面 `thumb_media_id` 必须是**永久素材**、正文图片必须是 `media/uploadimg` 产出的\n  mmbiz 地址（外链图被过滤）。\n\n**而后台网页端从未受影响**——这是所有个人号日常发文的方式。所以本方案驱动网页端。\n\n---\n\n## 6. 文件清单（本方案包含什么）\n\n```\ntools/wechat/\n├── wechat-html.js      # 排版装饰器：语义 HTML → 内联样式 HTML（主题表在这里改）\n├── weixin-flow.js      # 浏览器流程：登录检测/填表/写正文/传图/设封面/存草稿/发表\n├── create-article.js   # 命令：从本地 HTML 文件建草稿（可选发表）\n├── publish-note.js     # 命令：从 TW 笔记建草稿（主入口，含 --preview；单图 --cover）\n├── publish-note-imgs.js # 命令：多图版——正文内嵌 data URI 图全部上传 CDN 再发布\n└── install-wechat-adapters.mjs  # 一键安装到 ~/.opencli/clis/weixin/\n```\n\n装到本机后对应 `~/.opencli/clis/weixin/` 下的同名文件。\n改排版只需改 `tools/wechat/wechat-html.js` 里的 `ELEMENT_STYLES`，重跑安装脚本即可。\n\n---\n\n## 7. 技术实现要点（改代码前必读）\n\n### 7.1 正文写入必须用 `insertHTML`，不能用 `insertText`\n\n微信编辑器是 **ProseMirror**。`document.execCommand('insertHTML', …)` 保留内联样式；\n`insertText` 会把 HTML/Markdown 当**字面文本**（opencli 内置的 `weixin create-draft`\n就是这样——实测后台 digest 里 `# 一级标题` 和 `**加粗**` 的符号原样保留）。\n\n### 7.2 图片上传必须用 DataTransfer，不能用 `page.setFileInput`\n\n`page.setFileInput` 依赖 CDP 的 `Page.fileChooserOpened` 事件，本机（opencli 1.8.7 +\n扩展 v1.0.24 + Edge）**稳定失败**：\n\n```\nPage.fileChooserOpened not received within 5s\n```\n\n（[issue #1582](https://github.com/jackwener/OpenCLI/issues/1582) 显示扩展/CLI 版本不匹配确有历史问题。）\n\n**绕过办法**——在页面上下文用 DataTransfer 直接把 File 塞进 `input.files`：\n\n```js\nconst bin = atob(base64)\nconst arr = new Uint8Array(bin.length)\nfor (let i = 0; i < bin.length; i++) arr[i] = bin.charCodeAt(i)\nconst file = new File([arr], 'cover.png', { type: 'image/png' })\nconst dt = new DataTransfer()\ndt.items.add(file)\ninput.files = dt.files\ninput.dispatchEvent(new Event('change', { bubbles: true }))\n```\n\n实测图片真的上了 `mmbiz.qpic.cn`。**代价：字节要以 base64 穿过 evaluate → 单图限 8MB。**\n\n### 7.3 微信编辑器会剥 `<style>` 和 class，只认内联 `style`\n\n实测：注入 `<style>h1{color:red}</style>` → `hasStyleTag: false`；\n注入 `style=\"font-size:20px\"` → 原样保留。\n而 **TiddlyWiki 的 `/render` 输出零内联样式**（纯语义 HTML + class）——\n这正是需要 `wechat-html.js` 装饰器的原因。\n\n### 7.4 轮询里绝不能读 `document.body.innerText`（v0.23.0 实测踩坑）\n\n微信编辑器 DOM 极大，读一次 `body.innerText` **强制整页 layout，实测单次 evaluate\n≈17 秒**。早期 `saveDraft` / `publishDraft` 的轮询用它找成功提示，8 次轮询把整个命令\n拖过 210s 超时——**最坑的是草稿其实已经保存成功**，用户看到的是超时失败（假阴性）。\n\n现在只查少量 toast 节点（`.weui-desktop-toast` / `.weui-desktop-msg` / `#js_save_success`）\n和 URL，都是 O(1) 操作。修复后 `saveDraft` 从 **137 秒降到 3.9 秒**。\n\n`scripts/verify-wechat-adapters.mjs` 有回归守门（已反向验证：塞回去即红）。\n\n### 7.5 其他踩过的坑\n\n- 图片下拉必须**按文案**点「本地上传」：用 `items[0]` 点完 file input 仍不可见。\n- 正文是编辑器页**最后一个** `contenteditable`。\n- 回读校验必须**忽略所有空白**：编辑器 innerText 会在块级元素间插空白、把空格转 nbsp，\n  直接用原始字符串比对必假阴性。\n- 保存按钮的文案兜底**特意不含「发表/发布」**，防止误点发布。\n- 草稿列表显示「图文内容不完整」**只表示缺封面**，不代表写入失败。\n- `<pre>` 内的 `<code>` 不能套用行内代码样式（粉底 + 内边距会很难看），\n  `wechat-html.js` 里用 `preDepth` 特判。\n\n---\n\n## 8. 排错\n\n| 现象 | 原因 / 处理 |\n|---|---|\n| `Navigation rejected` | 忘了 `--trace retain-on-failure` |\n| `AUTH_REQUIRED` / 提示登录 | 浏览器里 `mp.weixin.qq.com` 登录态过期 → 重新扫码登录 |\n| `Extension: not connected` | 扩展没装/没启用，或浏览器没运行 → 见 §2 |\n| `Page.fileChooserOpened not received` | 不应再出现（已改用 DataTransfer）；若出现说明源码被改回 setFileInput |\n| 找不到笔记 | tiddler 标题要**完全精确**（含空格/标点）；`opencli weixin publish-note \"标题\"` |\n| `/render 返回 HTTP 404` | 标题不存在；先用 `tiddlywiki_search` 或 TW 面板确认 |\n| 无法连接 DSH | `--dsn` 默认 `http://127.0.0.1:3080/dsh-tiddlywiki`；DSH 没跑或端口不同就改它 |\n| 草稿显示「内容不完整」 | 缺封面 → 传 `--cover`（或用 publish-note-imgs 从正文第一张自动设） |\n| 图片没上传 | 单图 > 8MB（DataTransfer 限制）→ 先压缩 |\n| 发表卡住超时 | 没扫码，或扫码没完成 → 调大 `--timeout`；若卡在原创声明/留言等确认弹窗 → 推荐流程本就到草稿箱为止，到后台人工点发表（见 §1、§4.4） |\n| `stale page identity` | 命令执行中标签页被手工关闭/导航了。**草稿不丢**——重开编辑页续作：`https://mp.weixin.qq.com/cgi-bin/appmsg?t=media/appmsg_edit_v2&action=edit&type=77&appmsgid=<id>&idx=0&token=<token>`（token 用 `opencli browser wx eval 'location.href.match(/token=(\\d+)/)[1]'` 从后台首页取） |\n| 封面警告「设置失败」但草稿其实有封面 | 已知**误报**（校验时机太早）；以草稿箱实际显示为准（2026-09-17 实测：`list_ex` 接口 `cover` 字段已是 mmbiz 地址）。v0.23.2 起改为轮询校验 |\n| 用 eval 诊断后台状态时读到「未实名」「未设置头像和名称」等提示 | ⚠️ 后台 DOM 里常残留**不可见的历史 toast 节点**——查询必须过滤可见性（`offsetHeight > 0`），勿把残留文案当实时状态（2026-09-17 踩过：据此误判账号被平台拦截，实际账号正常并成功发表含原创声明）。同理，判断原创声明是否生效以草稿箱/发表记录为准，勿只看侧栏文案 |\n| 需要核实草稿是否落盘 | 后台 ajax：`/cgi-bin/appmsg?action=list_ex&type=77&orderby=create_time&token=<token>&f=json&begin=0&count=5`（在 mp.weixin.qq.com 页面上下文执行；`cover`/`digest`/`update_time` 一目了然）；发表记录：`/cgi-bin/appmsgpublish?sub=list&...&f=json`（`publish_page.publish_list[].publish_info` 里是 JSON 字符串，含 `content_url`） |\n\n---\n\n## 9. 安全与隐私\n\n- **不存任何公众号凭据**：全程复用浏览器已有登录态（cookie），脚本不接触 AppSecret。\n- **不落盘密钥**：adapter 只读本地图片路径，不写任何 token。\n- **低频使用**：不做规避风控的行为伪装；默认走「发表」（不推送粉丝、不占额度）。\n- wiki 里的配置 tiddler 与本方案无关——本方案零配置。\n\n---\n\n## 10. 参考\n\n- [opencli](https://github.com/jackwener/opencli) — 把网站变成 CLI，复用浏览器登录态\n- [微信「发布能力」文档（2025-07 权限回收）](https://developers.weixin.qq.com/doc/subscription/guide/product/publish.html)\n- [微信「新增草稿」draft/add](https://developers.weixin.qq.com/doc/subscription/api/draftbox/draftmanage/api_draft_add.html)\n- [微信服务端 API 调用说明（IP 白名单）](https://developers.weixin.qq.com/doc/subscription/guide/dev/api/)\n- 设计文档：`docs/plans/2026-09-17-wechat-publish-design.md`\n"
+export const WECHAT_DOCS_TEXT = "# 微信公众号发布：换机器还原指南\n\n> **这是可选功能，默认关闭，需要额外安装。** 插件本体**不含**它：真正干活的是仓库\n> `tools/wechat/` 下的 opencli adapter + Browser Bridge 浏览器扩展。**不安装／不开启，\n> 插件的其他功能完全不受影响**（不注入发布相关提示词、不往 wiki 写发布规范文档）。\n>\n> 目的：在**另一台机器**上无缝还原「TiddlyWiki 笔记 → 微信公众号」的发布能力。\n> 本机（开发机）已验证全程可跑；本文按顺序照做即可复现。\n>\n> 关键结论先讲：**整套发布走浏览器自动化，不依赖公众号服务端 API**——因为\n> 2025-07 起官方已回收个人主体账号的「发布能力」接口权限（详见 §5）。\n\n---\n\n## 0. 它是可选功能：需要什么、不影响什么\n\n| | 说明 |\n|---|---|\n| **默认状态** | **关闭**（`wechat.enabled` 默认 `false`） |\n| **开启方式** | DSH 设置 →「TiddlyWiki 知识库」→「可选功能：微信公众号发布」→ 勾选 → 保存配置 |\n| **开启后有什么变化** | ① 注入提示词多一行「发布前先读发布元数据规范」；② 启动时把该规范文档写进 wiki（同名不覆盖）。**仅此两项**——不会安装任何东西、不会启用任何后台服务 |\n| **不开启会怎样** | 提示词里没有发布相关文字；wiki 里不会出现「发布元数据规范」；其他功能一切照旧 |\n| **插件会替你做安装吗** | **不会**。opencli 与浏览器扩展必须你手动装（见 §1–§2）——这属于插件外部的工具链 |\n| **要额外装什么** | ① opencli（npm 包）② Browser Bridge 浏览器扩展 ③ 浏览器登录公众号 |\n| **凭据如何保存** | 不保存任何凭据：复用浏览器已有登录态（cookie）。脚本不接触 AppSecret |\n\n> 一句话：**开关只控制「插件要不要配合这个流程」，不负责装工具链。**\n\n---\n\n## 1. 一分钟总览\n\n```\nTiddlyWiki 笔记（tiddler）\n   │  标题\n   ▼\nDSH 的 POST /dsh-tiddlywiki/render        ← TW 自己渲染成语义 HTML（含代码高亮）\n   │  纯语义 HTML（无内联样式）\n   ▼\nwechat-html.js  decorate()                ← 补内联样式（微信唯一认的形式）\n   │  带内联样式的 HTML\n   ▼\nopencli + Browser Bridge 扩展             ← 驱动你已登录的浏览器\n   │  填标题/作者/摘要 + insertHTML 写正文 + 传图 + 设封面 + 存草稿\n   ▼\n公众号草稿箱（mp.weixin.qq.com）\n   │  （可选 --publish）\n   ▼\n点「发表」→ ⚠️ 管理员扫码确认 → 发布成功\n```\n\n**一条命令**（在第二台机器上，装好后）：\n\n```bash\nopencli weixin publish-note \"笔记标题\" --trace retain-on-failure -f json\n```\n\n---\n\n## 1. 需要安装/准备的东西\n\n按顺序做；**最后一步才是打开插件里的开关**（开关只影响提示词与文档，装不上工具链）。\n\n| # | 项目 | 怎么装 | 验证 |\n|---|---|---|---|\n| 1 | **Node.js ≥ 22** | 官网安装包 | `node -v` |\n| 2 | **DSH** + **dsh-tiddlywiki 插件** | 本仓库的插件（含 wiki） | `curl http://127.0.0.1:3080/dsh-tiddlywiki/status` |\n| 3 | **opencli** | `npm install -g @jackwener/opencli` | `opencli --version` |\n| 4 | **Browser Bridge 扩展** | 见 §2（二选一） | `opencli doctor` 显示 `Extension: connected` |\n| 5 | **Chrome/Edge + 公众号登录** | 浏览器登录 mp.weixin.qq.com | 能进后台首页 |\n| 6 | **本仓库的 adapter** | `node tools/wechat/install-wechat-adapters.mjs` | 脚本自检输出 ✔ |\n| 7 | **打开插件开关** | 设置 →「TiddlyWiki 知识库」→「可选功能：微信公众号发布」勾选 → 保存配置 | 提示词预览里出现「发布元数据规范」一行 |\n\n> **opencli 版本建议 ≥ 1.8.7**（本方案在该版本实测通过；1.7.x 的 `browser`\n> 子命令语法不同，且内置 weixin adapter 不完整）。\n>\n> **新版 npm 的 allowScripts 机制会拦 opencli 的 postinstall 脚本**（安装时打\n> warning）：**无害，可忽略**——postinstall 只装 bash/zsh/fish 补全（Windows 用不上），\n> adapters 随 npm 包自带，功能不受影响。\n>\n> 第 7 步之前，插件不会注入任何发布相关提示词、也不会往 wiki 写「发布元数据规范」。\n> 也就是说：**没装好工具链时开关可以一直关着，不影响任何其他功能。**\n\n### 自动化的终点：草稿箱（2026-09-17 与用户确认的策略）\n\n**adapter 负责到「草稿落盘」为止**：填标题/作者/摘要、写正文、传图、设封面、存草稿。\n**发表由人工在后台完成**——点「发表」时平台会弹确认对话框（原创声明、作者、留言\n设置等）以及最后的管理员扫码；原创声明涉及账号权益，人工点最稳妥。`--publish`\n选项保留（best-effort：点「发表」后轮询等扫码），但**不处理中途弹窗**，遇到弹窗\n会一直等到超时。\n\n---\n\n## 2. 安装 Browser Bridge 扩展（关键前置）\n\n扩展**不在 npm 包里**，必须单独装。二选一：\n\n**方式 A — Chrome Web Store（推荐）**\n1. 打开 https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk\n2. 点「添加至 Chrome」\n\n**方式 B — GitHub Releases（Web Store 打不开时）**\n1. 到 https://github.com/jackwener/opencli/releases 下载 `opencli-extension-v*.zip`\n2. 解压到某个固定目录\n3. 浏览器打开 `chrome://extensions` → 开启右上角「开发者模式」\n4. 点「加载已解压的扩展程序」→ 选择解压出的目录\n\n> ⚠️ GitHub 的 ext release **经常落后于 Web Store**（2026-09-17 实测只到\n> `ext-v1.0.21`，Web Store 已是 1.0.24）。**扩展版本以 Chrome Web Store 为准**；\n> GitHub 方式只作 Web Store 打不开时的离线兜底。\n\n**验证**：\n\n```bash\nopencli doctor\n# 期望： [OK] Daemon: running ...\n#        [OK] Extension: connected (vX.Y.Z)\n#        [OK] Connectivity: connected\n#        Everything looks good!\n```\n\n若报 `Extension: not connected`：确认浏览器在运行、扩展已启用；再 `opencli daemon stop` 后重跑 `opencli doctor`（daemon 会自动重启）。\n\n---\n\n## 3. 装 adapter 并试跑\n\n```bash\ncd <本仓库>\nnode tools/wechat/install-wechat-adapters.mjs\n```\n\n脚本会把 `tools/wechat/*.js` 复制到 `~/.opencli/clis/weixin/`（Windows：`C:\\Users\\<你>\\.opencli\\clis\\weixin\\`）。\n这些是**私有 adapter**，放在该目录即可被 opencli 自动发现，**无需任何构建**。\n\n然后：\n\n```bash\n# ① 先干跑：只做 TW 渲染 + 排版装饰，导出预览，不碰微信\nopencli weixin publish-note \"某篇笔记标题\" --preview ./out --trace retain-on-failure\n\n#    → 用浏览器打开 ./out.html 肉眼确认排版\n#    （注意：--preview 仍会继续执行发布流程；只想预览时看文件即可，或 Ctrl-C）\n\n# ② 真发到草稿箱\nopencli weixin publish-note \"某篇笔记标题\" --trace retain-on-failure -f json\n\n# ③ 带封面（公众号封面必填，否则草稿显示\"内容不完整\"）\nopencli weixin publish-note \"某篇笔记标题\" --cover ./cover.png --trace retain-on-failure -f json\n\n# ④ 直接发表（⚠️ 会真发文章，需管理员扫码）\nopencli weixin publish-note \"某篇笔记标题\" --publish --trace retain-on-failure -f json\n\n# ⑤ 正文多图（v0.23.2+）：TW 笔记内嵌 [img[...]] 经 /render 变成 data URI，\n#    publish-note 传不了（微信存草稿时过滤非 mmbiz 图）——用 publish-note-imgs：\nopencli weixin publish-note-imgs \"某篇笔记标题\" --images <图片目录> --trace retain-on-failure -f json\nopencli weixin publish-note-imgs \"某篇笔记标题\" --images \"01.png|02.png|03.png\" -f json\n#    · --images 传目录时按文件名排序 = 正文图片出现顺序（封面图排第一）\n#    · 也可用 | 分隔的路径列表精确指定顺序\n#    · 流程：先逐张上传 CDN → 按 DOM 顺序重写正文 src → insertHTML → 选封面 → 存草稿\n#    · 发表前同样读 pub-state / no-publish（只告警不阻断），--publish 可直接发表\n```\n\n### 3.6 在 TiddlyWiki 里点按钮发布（v0.23.3，日常推荐）\n\n不想敲命令时，用**笔记工具栏的「发布到公众号」按钮**（嵌入式 TW 面板、右侧栏 tab、原生编辑弹窗里都在）：\n\n1. 设置页勾选「可选功能：微信公众号发布」并保存 → 重启 dsh web 后，启动 seed 会把按钮插件\n   `$:/plugins/dsh/wechat-publish` 写进 wiki（老 wiki 也可在设置页「初始化」区单独写它）。\n2. 打开任意笔记 → 工具栏点「发布到公众号」→ 按钮**先预检**（opencli 跑不跑得起来、adapter 缺哪些文件），\n   再弹确认框（自动列出 `no-publish` / `pub-state` 警告）→ 点「开始存草稿」。\n3. 宿主进程起一个**后台任务**，覆盖层每 2 秒显示状态与日志尾部。**只到草稿箱为止，不自动发表。**\n\n按钮背后的三条路由（同源；写操作有方法 + CSRF 守卫；`wechat.enabled` 关着时一律 403）：\n\n| 路由 | 方法 | 作用 |\n|---|---|---|\n| `/dsh-tiddlywiki/wechat/ready` | GET | 预检：`opencli --version` 能否跑通、adapter 缺哪些文件 |\n| `/dsh-tiddlywiki/wechat/publish` | POST | 起任务（body `{title, adapter?}`）；单并发，第二次调用 409 |\n| `/dsh-tiddlywiki/wechat/publish/status` | GET | 轮询任务（`?id=`；不带 id 取最新/正在跑的那个） |\n\n可配项（设置页目前只暴露 `enabled`，其余写进配置 tiddler\n`$:/plugins/dsh-tiddlywiki/config` 的 `wechat` 块，保存即生效）：\n\n| 键 | 默认 | 说明 |\n|---|---|---|\n| `wechat.enabled` | `false` | 总开关；关着时按钮不写入、三条路由 403 |\n| `wechat.adapter` | `publish-note` | 换成 `publish-note-imgs` 走正文内嵌多图（需该 adapter 已装） |\n| `wechat.command` | `opencli` | CLI 路径（装了别名、不在 PATH 时用） |\n| `wechat.token` | 空 | 非空时要求请求头 `x-wechat-publish-token`（按钮会自动带上） |\n| `wechat.dsn` | 空 | adapter 回连 DSH 的基址；留空按请求端口推导 `http://127.0.0.1:<端口>/dsh-tiddlywiki` |\n| `wechat.endpoint` | 空 | **只被 TW 侧读**：覆盖按钮请求的基址（默认 `location.origin + /dsh-tiddlywiki`）；反向代理/远程访问场景用 |\n\n⚠️ 宿主用 **`--title-file`**（v0.23.3 新增参数）把标题经 UTF-8 文件交给 adapter：标题不进 argv，\n否则 Windows 上 `opencli` 的 `.cmd` shim 会把 `&`/`|`/`^` 当命令分隔符，中文标题还会被 cmd 的\n代码页解码成乱码。位置参数 `<title>` 照旧可用（两者都给时位置参数优先）。\n⚠️ 按钮**不替你发表**：发表要管理员扫码（§4.2），请在公众号后台点「发表」。\n\n---\n\n## 3.5 发布元数据（重要：避免重发/误发）\n\nwiki 里既有**早已发布**的文章，也有**明确不能发**的内容。没有记录，agent 只能猜——\n要么重复发已上线的，要么把不该发的推出去。\n\n**规范全文在 wiki 里**：笔记「**发布元数据规范**」（随插件 seed 分发，`dsh-docs` 标签，\n开机自动写入；也可手动跑 `npx tsx tools/wechat/seed-publish-spec-now.mts` 立即写入）。\n注入给 agent 的系统提示词里**只有一句指针**（规范全文太长，不适合放进每个会话都要付的常驻预算 —— v0.29.0 把 slim 从 ~1.9KB 瘦到 ~1.0KB 之后依然如此，指针就够了：需要时 Agent 会去读那篇笔记）。\n\n### 字段（自定义字段，不是标签）\n\n| 字段 | 含义 | 示例 |\n|---|---|---|\n| `pub-state` | 能不能发 | `draft` / `published` / `excluded` |\n| `pub-platform` | 最近发布的平台（多平台逗号分隔） | `wechat` |\n| `pub-wechat-at` | 公众号发表时间 | `2026-09-17 15:30` |\n| `pub-wechat-title` | 发表时的标题（**仅当与 TW 标题不同才写**） | `中年失业自救指南` |\n| `pub-wechat-url` | 发表后的链接 | `https://mp.weixin.qq.com/s/xxx` |\n| `pub-note` | 备注 | `删改后重发过一版` |\n\n**没有 `pub-state` = 未知状态**，应当当作「需要人确认」，而不是「可以随便发」。\n\n标签 `no-publish` 是给人看的镜像（TW 界面一眼可见、可筛）；`pub-state: excluded` 给\nagent 程序化判断。**两者应一致，冲突时以字段为准。**\n\n### ⚠️ 命名冲突（别占用）\n\n实测本 wiki 里这三个名字**已被占用**，方案特意避开：\n\n- `publish` / `publishyear` 字段 → Obsidian 导入的**书籍**条目用作「出版社 / 出版年」\n  （值形如「新世界出版社」「2011-09-01」）。\n- `发布记录` 标签 → 本插件自己的**版本发布说明**。\n\n### 发布前检查：只告警，不阻断\n\n`publish-note` 会读 `pub-state` / `no-publish`，命中就打印醒目警告，**然后继续执行**\n（2026-09-17 明确选定的策略）。`--force` 只改措辞，不改变行为：\n\n```\n⚠️ 「某篇」已发布过（平台 wechat）。这可能是重复发布——确认无误再继续；确实要重发请加 --force。\n```\n\n### 回写（agent 负责）\n\n发布成功后，命令的 `detail` 里会带一句**建议回写值**，例如：\n\n```\n建议回写：pub-state=published, pub-platform=wechat, pub-wechat-at=\"2026-09-17 17:50\"\n```\n\nagent 据此用 `tiddlywiki_put` 写回（**不传 `tags` 就保留原标签**，只补 `fields`）：\n\n```\ntiddlywiki_put(title=\"某篇\", text=<原正文>, fields={\"pub-state\":\"published\", \"pub-platform\":\"wechat\", \"pub-wechat-at\":\"...\"})\n```\n\n> ⚠️ 用工具时 `text` 会被覆盖，**务必带上原正文**。别像我一样用裸 REST PUT 只发一段\n> 文字——那会把笔记正文清空（真实踩过，靠 git 恢复）。\n\n### 存量回填\n\n早于本规范、来源可辨（`source-path` 含「公众号」）的文章，用脚本回填：\n\n```bash\n# 默认 dry-run，只打印将改什么\nnode tools/wechat/backfill-publish-state.mjs\n\n# 确认后真写\nnode tools/wechat/backfill-publish-state.mjs --write\n\n# 指定标题 / 平台 / 匹配子串\nnode tools/wechat/backfill-publish-state.mjs --title \"打工记\" --title \"鱼\" --write\nnode tools/wechat/backfill-publish-state.mjs --match 公众号 --platform wechat --write\n```\n\n脚本纪律（**请勿改成「只写字段」的裸 PUT**）：每条都先 GET **完整** tiddler（含\ntext/tags/type/created），**只添加** `pub-*` 字段后整体写回；已有 `pub-state` 的跳过\n（幂等）；正文为空的跳过（宁可不动）；**发表时间无法考证就留空，不编造**。\n\n---\n\n## 4. ⚠️ 三个必须知道的坑\n\n### 4.1 所有命令都要带 `--trace retain-on-failure`\n\n不带会对 `mp.weixin.qq.com` 稳定报：\n\n```\nNavigation rejected\n```\n\n**实测**：trace 开 → 5/5 成功；trace 关 → 8/8 失败。这是 opencli 1.8.7 的 bug\n（源码里 trace 只做录像，理论上不该影响导航）。已试过无效的绕法：\n`--site-session ephemeral`、`--keep-tab false`、`--window foreground/background`、\n重置标签页、重启 daemon。**唯一有效就是加 trace。**\n\n### 4.2 发表必须管理员扫码（无法自动化）\n\n后台点「发表」后，微信要求**管理员微信扫码确认**。这不是技术能绕开的账号安全机制。\n所以「一键发布」的真实含义是：\n\n> agent/脚本 完成素材、排版、上传、填表、进草稿箱 —— **你只需扫一次码**。\n\n`--publish` 会自动点「发表」并在终端提示你扫码，然后轮询结果（默认等 180s，\n可用 `--timeout` 调整）。\n\n### 4.3 「发表」≠「群发」（别搞混）\n\n| 操作 | 推送粉丝 | 占群发额度 | 需要扫码 |\n|---|---|---|---|\n| **发表**（本方案默认） | 否（仅生成永久链接） | 否，不限次数 | 是 |\n| **群发** | 是 | 个人订阅号 1 天 1 次 | 是 |\n\n两者都要扫码 → 默认选**不吃额度**的「发表」。\n\n### 4.4 发表阶段的确认弹窗 adapter 不处理（v0.23.x 现状）\n\n`publishDraft` 点完「发表」后**只轮询成功信号**，不会点任何平台弹窗。发表链路上\n还有：原创声明/作者/留言设置等**确认对话框**（2026-09-17 人工发表实测必经）与最后\n的管理员扫码。所以**推荐流程到草稿箱为止**（见 §1），发表环节人工做；`--publish`\n只是 best-effort，遇到弹窗会卡到超时。排错见 §8。\n\n---\n\n## 5. 为什么不用官方 API（背景，避免走回头路）\n\n公众号发布的服务端链路是 `access_token → draft/add → freepublish/submit`。但：\n\n- **2025 年 7 月起，官方回收「发布能力」接口对个人主体、企业未认证、不支持认证账号的调用权限**\n  （[发布能力文档](https://developers.weixin.qq.com/doc/subscription/guide/product/publish.html) 原文注）。\n  个人主体无法做微信认证 → `freepublish/submit` 不可用。\n- 草稿箱 `draft/add` 文档未列该限制，但 48001 / `api unauthorized` 是常见返回。\n- 即便可用，还叠加：**本机公网出口 IP 必须加入 API IP 白名单**（否则 61004/40164）、\n  封面 `thumb_media_id` 必须是**永久素材**、正文图片必须是 `media/uploadimg` 产出的\n  mmbiz 地址（外链图被过滤）。\n\n**而后台网页端从未受影响**——这是所有个人号日常发文的方式。所以本方案驱动网页端。\n\n---\n\n## 6. 文件清单（本方案包含什么）\n\n```\ntools/wechat/\n├── wechat-html.js      # 排版装饰器：语义 HTML → 内联样式 HTML（主题表在这里改）\n├── weixin-flow.js      # 浏览器流程：登录检测/填表/写正文/传图/设封面/存草稿/发表\n├── create-article.js   # 命令：从本地 HTML 文件建草稿（可选发表）\n├── publish-note.js     # 命令：从 TW 笔记建草稿（主入口，含 --preview；单图 --cover）\n├── publish-note-imgs.js # 命令：多图版——正文内嵌 data URI 图全部上传 CDN 再发布\n└── install-wechat-adapters.mjs  # 一键安装到 ~/.opencli/clis/weixin/\n```\n\n装到本机后对应 `~/.opencli/clis/weixin/` 下的同名文件。\n改排版只需改 `tools/wechat/wechat-html.js` 里的 `ELEMENT_STYLES`，重跑安装脚本即可。\n\n---\n\n## 7. 技术实现要点（改代码前必读）\n\n### 7.1 正文写入必须用 `insertHTML`，不能用 `insertText`\n\n微信编辑器是 **ProseMirror**。`document.execCommand('insertHTML', …)` 保留内联样式；\n`insertText` 会把 HTML/Markdown 当**字面文本**（opencli 内置的 `weixin create-draft`\n就是这样——实测后台 digest 里 `# 一级标题` 和 `**加粗**` 的符号原样保留）。\n\n### 7.2 图片上传必须用 DataTransfer，不能用 `page.setFileInput`\n\n`page.setFileInput` 依赖 CDP 的 `Page.fileChooserOpened` 事件，本机（opencli 1.8.7 +\n扩展 v1.0.24 + Edge）**稳定失败**：\n\n```\nPage.fileChooserOpened not received within 5s\n```\n\n（[issue #1582](https://github.com/jackwener/OpenCLI/issues/1582) 显示扩展/CLI 版本不匹配确有历史问题。）\n\n**绕过办法**——在页面上下文用 DataTransfer 直接把 File 塞进 `input.files`：\n\n```js\nconst bin = atob(base64)\nconst arr = new Uint8Array(bin.length)\nfor (let i = 0; i < bin.length; i++) arr[i] = bin.charCodeAt(i)\nconst file = new File([arr], 'cover.png', { type: 'image/png' })\nconst dt = new DataTransfer()\ndt.items.add(file)\ninput.files = dt.files\ninput.dispatchEvent(new Event('change', { bubbles: true }))\n```\n\n实测图片真的上了 `mmbiz.qpic.cn`。**代价：字节要以 base64 穿过 evaluate → 单图限 8MB。**\n\n### 7.3 微信编辑器会剥 `<style>` 和 class，只认内联 `style`\n\n实测：注入 `<style>h1{color:red}</style>` → `hasStyleTag: false`；\n注入 `style=\"font-size:20px\"` → 原样保留。\n而 **TiddlyWiki 的 `/render` 输出零内联样式**（纯语义 HTML + class）——\n这正是需要 `wechat-html.js` 装饰器的原因。\n\n### 7.4 轮询里绝不能读 `document.body.innerText`（v0.23.0 实测踩坑）\n\n微信编辑器 DOM 极大，读一次 `body.innerText` **强制整页 layout，实测单次 evaluate\n≈17 秒**。早期 `saveDraft` / `publishDraft` 的轮询用它找成功提示，8 次轮询把整个命令\n拖过 210s 超时——**最坑的是草稿其实已经保存成功**，用户看到的是超时失败（假阴性）。\n\n现在只查少量 toast 节点（`.weui-desktop-toast` / `.weui-desktop-msg` / `#js_save_success`）\n和 URL，都是 O(1) 操作。修复后 `saveDraft` 从 **137 秒降到 3.9 秒**。\n\n`scripts/verify-wechat-adapters.mjs` 有回归守门（已反向验证：塞回去即红）。\n\n### 7.5 其他踩过的坑\n\n- 图片下拉必须**按文案**点「本地上传」：用 `items[0]` 点完 file input 仍不可见。\n- 正文是编辑器页**最后一个** `contenteditable`。\n- 回读校验必须**忽略所有空白**：编辑器 innerText 会在块级元素间插空白、把空格转 nbsp，\n  直接用原始字符串比对必假阴性。\n- 保存按钮的文案兜底**特意不含「发表/发布」**，防止误点发布。\n- 草稿列表显示「图文内容不完整」**只表示缺封面**，不代表写入失败。\n- `<pre>` 内的 `<code>` 不能套用行内代码样式（粉底 + 内边距会很难看），\n  `wechat-html.js` 里用 `preDepth` 特判。\n\n---\n\n## 8. 排错\n\n| 现象 | 原因 / 处理 |\n|---|---|\n| `Navigation rejected` | 忘了 `--trace retain-on-failure` |\n| `AUTH_REQUIRED` / 提示登录 | 浏览器里 `mp.weixin.qq.com` 登录态过期 → 重新扫码登录 |\n| `Extension: not connected` | 扩展没装/没启用，或浏览器没运行 → 见 §2 |\n| `Page.fileChooserOpened not received` | 不应再出现（已改用 DataTransfer）；若出现说明源码被改回 setFileInput |\n| 找不到笔记 | tiddler 标题要**完全精确**（含空格/标点）；`opencli weixin publish-note \"标题\"` |\n| `/render 返回 HTTP 404` | 标题不存在；先用 `tiddlywiki_search` 或 TW 面板确认 |\n| 无法连接 DSH | `--dsn` 默认 `http://127.0.0.1:3080/dsh-tiddlywiki`；DSH 没跑或端口不同就改它 |\n| 草稿显示「内容不完整」 | 缺封面 → 传 `--cover`（或用 publish-note-imgs 从正文第一张自动设） |\n| 图片没上传 | 单图 > 8MB（DataTransfer 限制）→ 先压缩 |\n| 发表卡住超时 | 没扫码，或扫码没完成 → 调大 `--timeout`；若卡在原创声明/留言等确认弹窗 → 推荐流程本就到草稿箱为止，到后台人工点发表（见 §1、§4.4） |\n| `stale page identity` | 命令执行中标签页被手工关闭/导航了。**草稿不丢**——重开编辑页续作：`https://mp.weixin.qq.com/cgi-bin/appmsg?t=media/appmsg_edit_v2&action=edit&type=77&appmsgid=<id>&idx=0&token=<token>`（token 用 `opencli browser wx eval 'location.href.match(/token=(\\d+)/)[1]'` 从后台首页取） |\n| 封面警告「设置失败」但草稿其实有封面 | 已知**误报**（校验时机太早）；以草稿箱实际显示为准（2026-09-17 实测：`list_ex` 接口 `cover` 字段已是 mmbiz 地址）。v0.23.2 起改为轮询校验 |\n| 用 eval 诊断后台状态时读到「未实名」「未设置头像和名称」等提示 | ⚠️ 后台 DOM 里常残留**不可见的历史 toast 节点**——查询必须过滤可见性（`offsetHeight > 0`），勿把残留文案当实时状态（2026-09-17 踩过：据此误判账号被平台拦截，实际账号正常并成功发表含原创声明）。同理，判断原创声明是否生效以草稿箱/发表记录为准，勿只看侧栏文案 |\n| 需要核实草稿是否落盘 | 后台 ajax：`/cgi-bin/appmsg?action=list_ex&type=77&orderby=create_time&token=<token>&f=json&begin=0&count=5`（在 mp.weixin.qq.com 页面上下文执行；`cover`/`digest`/`update_time` 一目了然）；发表记录：`/cgi-bin/appmsgpublish?sub=list&...&f=json`（`publish_page.publish_list[].publish_info` 里是 JSON 字符串，含 `content_url`） |\n\n---\n\n## 9. 安全与隐私\n\n- **不存任何公众号凭据**：全程复用浏览器已有登录态（cookie），脚本不接触 AppSecret。\n- **不落盘密钥**：adapter 只读本地图片路径，不写任何 token。\n- **低频使用**：不做规避风控的行为伪装；默认走「发表」（不推送粉丝、不占额度）。\n- wiki 里的配置 tiddler 与本方案无关——本方案零配置。\n\n---\n\n## 10. 参考\n\n- [opencli](https://github.com/jackwener/opencli) — 把网站变成 CLI，复用浏览器登录态\n- [微信「发布能力」文档（2025-07 权限回收）](https://developers.weixin.qq.com/doc/subscription/guide/product/publish.html)\n- [微信「新增草稿」draft/add](https://developers.weixin.qq.com/doc/subscription/api/draftbox/draftmanage/api_draft_add.html)\n- [微信服务端 API 调用说明（IP 白名单）](https://developers.weixin.qq.com/doc/subscription/guide/dev/api/)\n- 设计文档：`docs/plans/2026-09-17-wechat-publish-design.md`\n"
 
 /** Write the doc + marker (ONE-SHOT when `force` is false). */
 export async function seedWechatDocs(client: TiddlyWebClient, opts?: { force?: boolean }): Promise<boolean> {

package/src/host/session-scope.ts

@@ -145,7 +145,22 @@ export async function writeSessionScopes(state: SessionScopeState, file: string
 export async function setSessionScope(sessionId: string, wikiId: string | undefined, file: string = defaultSessionScopeFile()): Promise<void> {
   if (!isSafeSessionId(sessionId)) throw new Error(`会话 id 非法：${JSON.stringify(sessionId)}`)
   if (wikiId !== undefined && !isSafeWikiId(wikiId)) throw new Error(`知识库 id 非法：${JSON.stringify(wikiId)}`)
-  const existing = await readFile(file, 'utf8').catch(() => '')
+  /**
+   * 读失败 ≠ 没有文件（铁律 #3）。
+   *
+   * Only ENOENT may be treated as "no scope file yet". Any other error
+   * (EACCES/EBUSY, a Windows file lock, or losing the race against a concurrent
+   * `writeSessionScopes` tmp+rename) used to collapse into `''` — and because the
+   * next lines are a read-modify-WRITE of the whole file, that silently dropped
+   * every OTHER session's knowledge-base scope. Throwing keeps the file intact
+   * and surfaces the failure to the selector instead.
+   */
+  let existing = ''
+  try {
+    existing = await readFile(file, 'utf8')
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+  }
   const parsed = existing.length > 0 ? (parseState(existing).state ?? { version: SESSION_SCOPE_VERSION, sessions: {} }) : { version: SESSION_SCOPE_VERSION, sessions: {} }
   const pruned = pruneScopes(parsed, Date.now())
   if (wikiId === undefined) delete pruned.sessions[sessionId]

package/src/host/tools-attach.ts

@@ -29,7 +29,7 @@ export function attachTool(env: ToolEnv) {
   // ── tiddlywiki_attach ────────────────────────────────────────────────────
   return defineTool({
     name: 'tiddlywiki_attach',
-    description: '把一个本机文件或公网 http(s) 地址存成 wiki 的二进制附件 tiddler（图片 / PDF / 压缩包等，type + base64 正文，随 wiki 进 git）。可选把附件嵌入/链接进某篇笔记。这是 agent 唯一能写入二进制附件的途径。',
+    description: '把一个本机文件或公网 http(s) 地址存成 wiki 的二进制附件 tiddler（图片 / PDF / 压缩包等，type + base64 正文，随 wiki 进 git）。可选把附件嵌入/链接进某篇笔记。**同名已有条目默认拒绝写入**（避免静默覆盖既有笔记；确认要覆盖才传 `force: true`，tags 与自定义字段仍会保留）。这是 agent 唯一能写入二进制附件的途径。',
     parameters: {
       title: { type: 'string', description: '附件 tiddler 标题（同时决定其在 wiki 里的名字）', required: true },
       path: { type: 'string', description: '本机绝对路径（与 url 二选一）' },

package/src/host/wiki-farm.ts

@@ -101,20 +101,65 @@ export function wikiIdFromRequest(req: { url?: string | undefined }): string | u
 /**
  * Which runtime does this request target?
  *
- *   `?wiki=<id>` naming a RUNNING wiki → that one
- *   anything else (no selector, unknown id, wiki not running)
- *                                       → the farm's default runtime
+ *   `?wiki=<id>` naming a RUNNING wiki                    → that one
+ *   `?wiki=<id>` naming a REGISTERED wiki that is STOPPED  → UNDEFINED (refuse)
+ *   no selector, or an UNKNOWN id                          → the farm's default
  *
- * An unknown id falls back instead of 404ing on purpose: the selector comes
- * from links the user may have bookmarked, and a stale one must not strand them
- * on a broken editor. It also means `?wiki=` can never be used to reach a wiki
- * that is not running — starting one is an explicit action, not a side effect
- * of a GET.
+ * TWO FALLBACKS, TWO DIFFERENT REASONS (v0.29.0)
+ * ----------------------------------------------
+ * An UNKNOWN id falls back instead of 404ing on purpose: the selector comes from
+ * links the user may have bookmarked, and a stale one must not strand them on a
+ * broken editor. It also means `?wiki=` can never be used to START a wiki —
+ * starting one is an explicit action, not a side effect of a GET.
+ *
+ * A REGISTERED but not-running id must NOT fall back. It used to, and the
+ * failure was silent and destructive: the settings page ("正在配置：books")
+ * wrote the books patch into the DEFAULT wiki's config tiddler, the quick-note
+ * card listed stopped wikis and then saved into the default one, and
+ * `/admin/info?wiki=<stopped>` rewrote the default wiki's `tiddlywiki.info`.
+ * The named wiki is unambiguously known here, so there is nothing to guess:
+ * callers get `undefined` and answer 503 with the wiki named (see
+ * `stoppedWikiFromRequest` for the message). This is the same answer the
+ * `/tw/<id>/` proxy already gave (it resolves LAST, exactly so a named-but-
+ * stopped wiki cannot be proxied to whoever happens to be the default).
  */
 export function targetRuntimeFor<T extends WikiRuntime>(farm: WikiFarm<T> | undefined, req: { url?: string | undefined }): T | undefined {
+  if (farm === undefined) return undefined
+  const id = wikiIdFromRequest(req)
+  if (id === undefined) return farm.defaultRuntime()
+  const runtime = farm.runtime(id)
+  if (runtime !== undefined) return runtime
+  // Registered but stopped → refuse (never act on a different knowledge base).
+  if (farm.registry.wikis.some((entry) => entry.id === id)) return undefined
+  return farm.defaultRuntime()
+}
+
+/**
+ * The REGISTERED wiki a request names which is not running — the reason a
+ * request-scoped target resolved to `undefined` (v0.29.0).
+ *
+ * Exists so every 503 can NAME the knowledge base and tell the user what to do,
+ * instead of the generic "wiki service is not running" that made the old silent
+ * fallback look like a success. Returns `undefined` when the request names no
+ * wiki, names a running one, or names an unknown id (that last case still falls
+ * back to the default by design — see `targetRuntimeFor`).
+ */
+export function stoppedWikiFromRequest<T extends WikiRuntime>(farm: WikiFarm<T> | undefined, req: { url?: string | undefined }): WikiEntry | undefined {
+  if (farm === undefined) return undefined
   const id = wikiIdFromRequest(req)
-  if (id === undefined) return farm?.defaultRuntime()
-  return farm?.runtime(id) ?? farm?.defaultRuntime()
+  if (id === undefined) return undefined
+  if (farm.runtime(id) !== undefined) return undefined
+  return farm.registry.wikis.find((entry) => entry.id === id)
+}
+
+/**
+ * The sentence every refusal carries (v0.29.0).
+ *
+ * Exported so the host wiring and the verification harness cannot drift apart on
+ * what a user reads — the guard asserts this text appears in the 503 body.
+ */
+export function stoppedWikiMessage(entry: WikiEntry): string {
+  return `知识库「${entry.label}」当前没有运行：先在「知识库」菜单里启动它再试`
 }
 
 /**

package/src/host/wiki-instance.ts

@@ -482,11 +482,18 @@ export class WikiInstance {
       // stale snapshot loses every write still queued (v0.19.0).
       const drained = await flushPendingWrites(seedClient, this.tiddlersDir)
       if (!drained) this.log('seed writes may not have been flushed before restart')
-      if (!this.disposed) await this.server.restart()
+      // v0.29.0: `this.restart()` (drainThenStop) rather than a bare
+      // `server.restart()` — see the pluginAdded branch below for why the boot
+      // path may no longer contain a single un-drained restart.
+      if (!this.disposed) await this.restart()
     } else if (pluginAdded) {
       // tiddlywiki.info is written directly by us (no TW flush to wait for),
-      // but TW only loads the plugin at boot.
-      if (!this.disposed) await this.server.restart()
+      // but TW only loads the plugin at boot. The SEEDS that just ran DID go
+      // through TW's REST API, though, so their writes may still sit in the
+      // syncer queue — restart via `this.restart()`, which drains first
+      // (v0.29.0: this used to be a bare `server.restart()`, i.e. the one
+      // restart path outside `drainThenStop()` that rule #1 forbids).
+      if (!this.disposed) await this.restart()
     }
     // Apply the configured UI language (e.g. "zh-Hans"): enable the bundled
     // language plugin in tiddlywiki.info.languages + restart once so TW loads
@@ -496,7 +503,9 @@ export class WikiInstance {
       try {
         const code = uiLang.trim()
         const changed = await ensureLanguage(this.wikiPath, this.options.twRoot(), code)
-        if (changed && !this.disposed) await this.server.restart()
+        // Same drain rule as above (v0.29.0): enabling a language plugin means a
+        // restart, and a restart with a non-empty syncer queue loses writes.
+        if (changed && !this.disposed) await this.restart()
         // Pin the active language tiddler so TW's UI actually switches.
         // v0.24.2: conditional — an identical body still rewrites
         // `$__language.txt.meta`'s created/modified on EVERY startup, and two
@@ -526,7 +535,11 @@ export class WikiInstance {
     try {
       await this.server.start()
       if (this.disposed) {
-        await this.server.stop().catch(() => undefined)
+        // Route the abort through drainStop() too (v0.29.0): the child is fresh
+        // here so there is nothing meaningful to flush, but keeping a SINGLE
+        // stop path is what lets the guard script assert "no bare stop/restart
+        // anywhere in this file" instead of maintaining an allow-list.
+        await this.drainStop().catch(() => undefined)
         return
       }
       await this.config.load(this.client())

package/src/index.ts

@@ -36,7 +36,7 @@ import {
   type WikiLocation,
 } from './host/wiki-location.ts'
 import { WikiInstance } from './host/wiki-instance.ts'
-import { WikiFarm, resolveAgentScope, targetRuntimeFor } from './host/wiki-farm.ts'
+import { WikiFarm, resolveAgentScope, stoppedWikiFromRequest, stoppedWikiMessage, targetRuntimeFor } from './host/wiki-farm.ts'
 import { defaultSessionScopeFile, isSafeSessionId, readSessionScopes, setSessionScope } from './host/session-scope.ts'
 import { installSplitSkill } from './host/skill-install.ts'
 import {
@@ -201,7 +201,7 @@ export {
 } from './host/wiki-registry.ts'
 export { WikiInstance, type WikiInstanceBase, type WikiInstanceOptions } from './host/wiki-instance.ts'
 export { isInsidePath, pathComparisonKey } from './host/path-key.ts'
-export { WikiFarm, targetRuntimeFor, wikiIdFromRequest, resolveAgentScope, type AgentScope, type FarmChange, type WikiFarmOptions, type WikiRuntime } from './host/wiki-farm.ts'
+export { WikiFarm, targetRuntimeFor, stoppedWikiFromRequest, stoppedWikiMessage, wikiIdFromRequest, resolveAgentScope, type AgentScope, type FarmChange, type WikiFarmOptions, type WikiRuntime } from './host/wiki-farm.ts'
 export {
   SESSION_SCOPE_MAX_AGE_MS,
   SESSION_SCOPE_VERSION,
@@ -771,6 +771,19 @@ export function apply(ctx: HostCtx, rawConfig: TiddlywikiConfig = {}): void {
      * selector (and an unknown id falls back instead of 404ing).
      */
     const target = (req: IncomingMessage): WikiInstance | undefined => targetRuntimeFor(farm, req)
+    /**
+     * Why this request cannot be served (v0.29.0): set when `?wiki=<id>` names a
+     * REGISTERED but STOPPED knowledge base. `targetRuntimeFor` deliberately
+     * returns undefined for that case instead of falling back to the default wiki
+     * (an unknown id still falls back — a stale bookmark must not 404), so every
+     * route that either 503s on a missing client or has a harmless-looking
+     * fallback (config / wiki path / prompt / status) can say WHICH wiki is down
+     * and what to do, instead of quietly acting on a different one.
+     */
+    const targetProblem = (req: IncomingMessage): string | undefined => {
+      const entry = stoppedWikiFromRequest(farm, req)
+      return entry === undefined ? undefined : stoppedWikiMessage(entry)
+    }
     const fallbackUi = WikiInstance.uiDefaultsFrom(config)
     const fallbackWechat = normalizeWechatConfig(config.wechat)
     /** Used only while nothing runs: base defaults, no wiki tiddler to read. */
@@ -811,6 +824,7 @@ export function apply(ctx: HostCtx, rawConfig: TiddlywikiConfig = {}): void {
       noteDefaults: (req) => ({ tag: target(req)?.noteTag() ?? config.note.tag }),
       uiDefaults: (req) => target(req)?.uiDefaults() ?? fallbackUi,
       getWikiPath: (req) => target(req)?.path ?? defaultPath(),
+      targetProblem,
       // Same helper as the agent tool (one implementation, two callers): a pull
       // can change several knowledge bases that share one repository.
       restartAffected: (_req, dir, changedFiles) => restartAffectedWikis({ farm: () => farm, repoRootOf: (d) => repos.repoRootOf(d) }, dir, changedFiles),
@@ -827,6 +841,11 @@ export function apply(ctx: HostCtx, rawConfig: TiddlywikiConfig = {}): void {
             ...(scopeId !== undefined ? { scope: scopeId } : {}),
             ...(resolution.entry !== undefined ? { resolved: { id: resolution.entry.id, label: resolution.entry.label } } : {}),
             ...(resolution.reason !== undefined ? { reason: resolution.reason } : {}),
+            // v0.29.0: the client needs to know whether "resolved" is a real
+            // answer (multi: this session's tools act on THAT wiki, so its cards'
+            // links must open it) or just the single install's only wiki (keep
+            // the pre-multi DOM, which renders no wiki attribute at all).
+            mode: farm?.registry.mode ?? 'single',
           }
         },
         set: async (sessionId: string, wikiId: string | undefined) => {
@@ -870,6 +889,7 @@ export function apply(ctx: HostCtx, rawConfig: TiddlywikiConfig = {}): void {
       server: (req) => target(req)?.server,
       getClient: (req) => target(req)?.client(),
       getWikiPath: (req) => target(req)?.path ?? defaultPath(),
+      targetProblem,
       twRoot: resolveTwRoot,
       config: (req) => target(req)?.config ?? idleConfig,
       // A settings-page save may change prompt.*: re-register the section (no