dsh-crossterm 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # dsh-crossterm 变更记录
 
+## 0.6.2 — 2026-10-19
+
+### 插件页：插件名/简介/组件表/更新日志
+- 插件改名：`locale/zh.json` 的 `meta.title` 从「跨会话」改为 **跨端互通**（英文 `CrossTerm`），
+  `meta.description` 写成插件级简介（跨会话/跨终端/跨设备/云端中转与备份，一句话说清）。
+  **四个业务组件名不变**：跨会话 / 跨终端 / 跨设备 / 跨账号。
+- `cordis.patch.yml` 结构变化：原来第一行用裸包名 `dsh-crossterm` 承担「跨会话」，
+  现在拆成两行 —— 第一行 `dsh-crossterm/parts/session`（跨会话），**末尾新增裸包名行**
+  `dsh-crossterm`（`config.part: ui`，不挂任何工具，只承载浏览器半端的配置卡片与插件标题）。
+  原因：`dsh-client-modules` 只对裸包名行加载 client bundle（`locatePkgJson()` 对子路径行返回
+  undefined），而插件页顶部标题与裸包名行共用同一份 locale meta，二者无法分成两个名字；
+  把裸行放到组件列表末尾，前四行仍是四个业务组件。
+- `lib/index.js`：`PARTS` 增 `ui`，`PART_LABEL.ui = '入口（插件卡片）'`；`ui` 不映射任何工具
+  （`TOOL_PART` 里没有它，`buildTools()` 过滤后为空），所以不会重复注册工具。
+- `lib/web.js` 新增 `GET /crossterm/api/about`：返回 `title` / `description` / `components[]`
+  （读 `parts/*.manifest.json`，与组件行显示同源）/ `changelog`（读包内 `CHANGELOG.md` 最近 3 节）。
+  导出 `aboutOf` 供探针使用。
+- `client/client.js`：卡片标题改用 `about.title`；展开后依次显示 **插件简介**、
+  **包含的组件（名称 + 简介两列表格）**，底部新增可折叠 **更新日志**（点按钮展开，等宽字体、可滚动）。
+- 探针 `F:\dsh\001X\crossterm-work\probe-about.mjs`：7 项全 PASS（标题、简介、四组件顺序与简介、
+  更新日志含本版且不超长、版本一致、缓存命中）。
+
+## 0.6.1 — 2026-10-19
+
+### 修：旧布局缓存挡住了新增的云端文档
+- 症状：0.5.0 / 0.6.0 升级后，云盘里看不到 `_规则-账号.md`、`_规则-设备.md`、`inbox/_说明.md`，
+  `status.home.layout.rulesVersion` 也还是老值 —— 文档写着「命中缓存会自动补写」，实际没补。
+- 根因：`ensureLayout()` 命中缓存时直接沿用 `cached.paths`，而路径是**算出来的**（`buildPaths()`）。
+  旧版缓存里没有 `accountRulesFile` / `deviceRulesFile` / `inboxReadmeFile` 三个字段，
+  `ensureRules()` 拿到 `undefined` 就跳过，随后仍把 `rulesVersion` 标成最新 —— 等于自己认定「已写」。
+- 修法（`lib/cloud/layout.js`）：
+  - 命中缓存时用 `buildPaths()` 按 `home / account / deviceId` **重新算路径**，缓存只负责存 `account`、`role`、`ensuredAt` 这类状态；
+  - `ensureRules()` 返回 `{ written, failed }`，路径缺失或上传失败都计入 `failed`；
+  - 只有 `failed === 0` 才把 `rulesVersion` 抬到 `RULES_VERSION` 并写回缓存，否则保持 0，下次 `ensure` 继续重试；
+  - 缓存新增 `home` 字段，非默认 `cloudHome` 也能重建路径。
+- 探针 `F:\dsh\001X\crossterm-work\probe-layout-stale-cache.mjs`：**12 项全 PASS**
+  （旧缓存→重算路径→补写三份文档→写回新缓存；第二次不重复上传；上传失败时 `rulesVersion` 不冒充最新）。
+  回归：`probe-layout-rules.mjs` 26 PASS、`probe-cloud-home.mjs` 42 PASS、`probe-inbox-readme.mjs` 17 PASS。
+
 ## 0.6.0 — 2026-10-19
 
 ### 共享收件箱里也放一份说明

package/README.md

@@ -12,7 +12,7 @@ A 终端看不到 B 终端里有哪个会话、在干什么，也没法把一条
 
 ## 零、简介与本版更新（每次发版重写这一节）
 
-**插件名称**：`dsh-crossterm` ｜ **插件简介**：DSH 跨终端互联 —— 同一账号下的多个 DSH 终端/进程互发邮件与文件（主题内联、正文落盘，收件方自己读）。
+**插件名称**：`dsh-crossterm`（插件页显示 **跨端互通**）｜ **插件简介**：同一 DSH 账号下的会话、终端、设备之间互通 —— 特征码链、内联邮件、云端中转站与自动备份。
 
 **四个组件（插件页里就是这四个开关，名称与简介来自各自的 manifest）**
 
@@ -23,15 +23,17 @@ A 终端看不到 B 终端里有哪个会话、在干什么，也没法把一条
 | 跨设备 | 经云端总线，在多台机器的 DSH 之间互发邮件与文件 | `term_cloud` |
 | 跨账号 | 预留位：后续用于跨账号互通，当前不挂工具 | — |
 
-**本版更新（0.6.0）**
+> 插件页里还会多出一行 **跨端互通**（组件列表最后一行）：它是「入口行」，裸包名加载浏览器半端，
+> 承载插件标题与配置卡片，不挂任何工具。浏览器 client 半端只认裸包名行，所以这一行没法省。
 
-- **共享收件箱里也带一份说明**：`/dsh/<账号>/shared/<设备>/inbox/_说明.md` 由插件自动生成，
-  打开云盘就知道这个收件箱是干什么的 —— 谁写谁取、信封 JSON 格式、`_` 开头的系统文件会被跳过、
-  别手工删改信封、收件人找不到就留件不消费、附件怎么存。
-- `lib/cloud/relay.js` 新增 `isEnvelopeFile()`：只把 `.json` 且不以 `_` 开头、非 `.tmp`/隐藏文件当信封，
-  所以说明文件不会被反复解析失败、也不影响正常投递与 `done/` 归档。
-- `RULES_VERSION` 升到 2，升级后命中旧缓存会自动补写这份新说明。
-- 探针：`probe-layout-rules.mjs` 26 项、`probe-inbox-readme.mjs` 17 项、`probe-cloud-home.mjs` 42 项全 PASS。
+**本版更新（0.6.2）**
+
+- **插件页终于像个插件了**：插件改名 **跨端互通**（原来叫「跨会话」，看起来像只管会话），
+  并写上了插件级简介；四个业务组件名保持不变。
+- 配置卡片里新增：**插件简介**、**包含的组件（名称 + 简介两列表格）**、底部可折叠 **更新日志**
+  （直接读包内 `CHANGELOG.md`，展开就能看最近三版改了什么）。
+- 数据来自新接口 `GET /crossterm/api/about`（组件名与简介读 `parts/*.manifest.json`，与组件行同源）。
+- 上一版（0.6.1）的内容仍在：旧布局缓存不再挡住云端规则文档与 `inbox/_说明.md`。
 
 ## 一、安装与卸载
 

package/client/client.js

@@ -63,6 +63,23 @@ window.__ModuleLoader__.load({
 				fontSize: 12,
 			},
 			msg: { fontSize: 12, opacity: 0.8, whiteSpace: "pre-wrap", wordBreak: "break-word" },
+			intro: { lineHeight: 1.6, opacity: 0.85 },
+			sectionTitle: { fontWeight: 600, fontSize: 12, opacity: 0.7 },
+			comp: { display: "grid", gridTemplateColumns: "max-content 1fr", gap: "4px 12px" },
+			compName: { fontWeight: 600 },
+			compDesc: { opacity: 0.75, lineHeight: 1.5 },
+			log: {
+				whiteSpace: "pre-wrap",
+				fontSize: 11.5,
+				lineHeight: 1.55,
+				opacity: 0.85,
+				maxHeight: 240,
+				overflow: "auto",
+				background: "rgba(128,128,128,.09)",
+				borderRadius: 8,
+				padding: "8px 10px",
+				fontFamily: "ui-monospace, Consolas, monospace",
+			},
 			switchOn: {
 				width: 34,
 				height: 18,
@@ -176,6 +193,8 @@ window.__ModuleLoader__.load({
 			const [busy, setBusy] = React.useState("");
 			const [msg, setMsg] = React.useState("");
 			const [devices, setDevices] = React.useState(null);
+			const [about, setAbout] = React.useState(null);
+			const [showLog, setShowLog] = React.useState(false);
 
 			const load = React.useCallback(() => {
 				call("/crossterm/api/status")
@@ -205,6 +224,16 @@ window.__ModuleLoader__.load({
 				if (open && !devices) void loadDevices();
 			}, [open, devices, loadDevices]);
 
+			// 插件自述与更新日志（0.6.2）：只读一次，读不到就退回内置文案
+			React.useEffect(() => {
+				if (!open || about) return;
+				call("/crossterm/api/about")
+					.then((data) => {
+						if (data && data.ok) setAbout(data);
+					})
+					.catch(() => {});
+			}, [open, about]);
+
 			const onCheck = async () => {
 				setBusy("check");
 				setMsg("正在检查更新…");
@@ -344,7 +373,7 @@ window.__ModuleLoader__.load({
 					h(
 						"div",
 						null,
-						h("div", { style: S.title }, `dsh-crossterm ${version}`),
+						h("div", { style: S.title }, `${(about && about.title) || "跨端互通"} ${version}`),
 						h("div", { style: S.sub }, subtitle),
 					),
 					// h("span", { style: S.chevron }, open ? "\u2303" : "\u2304"),
@@ -354,6 +383,26 @@ window.__ModuleLoader__.load({
 					h(
 						"div",
 						{ style: S.body },
+						about && about.description ? h("div", { style: S.intro }, about.description) : null,
+						about && about.components && about.components.length
+							? h(
+								"div",
+								null,
+								h("div", { style: S.sectionTitle }, "包含的组件"),
+								h(
+									"div",
+									{ style: S.comp },
+									...about.components.map((c) =>
+										h(
+											React.Fragment,
+											{ key: c.part },
+											h("div", { style: S.compName }, c.name),
+											h("div", { style: S.compDesc }, c.description || "—"),
+										),
+									),
+								),
+							)
+							: null,
 						h(FriendlyRow, { label: "当前版本", value: status ? `v${status.version}${mode === "link" ? "（源码 link:）" : ""}` : "" }),
 						h(FriendlyRow, {
 							label: "当前终端",
@@ -438,6 +487,18 @@ window.__ModuleLoader__.load({
 							h("button", { style: S.btn, onClick: onBackupNow, disabled: busy !== "" }, busy === "backup" ? "备份中…" : "备份会话"),
 						),
 						msg ? h("div", { style: S.msg }, msg) : null,
+						about && about.changelog
+							? h(
+								"div",
+								{ style: { display: "flex", flexDirection: "column", gap: 8 } },
+								h("div", null, h(
+									"button",
+									{ style: S.btn, onClick: () => setShowLog((v) => !v) },
+									showLog ? "收起更新日志" : "更新日志",
+								)),
+								showLog ? h("div", { style: S.log }, about.changelog) : null,
+							)
+							: null,
 					),
 			);
 		}

package/cordis.patch.yml

@@ -8,8 +8,10 @@
 #   dsh plugin --profile desktop remove dsh-crossterm
 #
 # 每个 insert 行在 DSH「插件 → dsh-crossterm → 包含的组件」里是一行组件，可单独开关。
-# 四行指向同一个包，只是走不同子路径：
+# 五行指向同一个包，只是走不同子路径：
 #
+#   dsh-crossterm                入口：插件页配置卡片（浏览器半端）+ 全插件简介/更新日志，
+#                                不挂任何工具（config.part: ui）
 #   dsh-crossterm/parts/session  跨会话：term_link / term_unlink / term_broadcast / term_inbox / term_config
 #   dsh-crossterm/parts/terminal 跨终端：term_whoami / term_list / term_send / term_send_files
 #   dsh-crossterm/parts/device   跨设备：term_cloud（云端总线同步）
@@ -18,15 +20,19 @@
 # 组件名来自 package.json 的 exports 映射：
 #   "./parts/session/package.json" -> "./parts/session.manifest.json"
 # 每个组件显示自己的中文名，实际加载的仍是 lib/index.js，靠 config.part 决定挂哪组工具。
-# 四个组件在同一 DSH 进程里共用一份总线实例：心跳只起一次，云同步只在 device 组件启用
+#
+# 为什么入口行放在最后：浏览器的 client 半端只对「裸包名」行生效（dsh-client-modules 的
+# locatePkgJson 对子路径行直接返回 undefined），而插件页顶部标题与裸包名行共用同一份
+# locale/zh.json 的 meta —— 插件叫「跨端互通」、四个业务组件叫跨会话/跨终端/跨设备/跨账号，
+# 只能让裸包名行单独做入口，且排在组件列表末尾，四个组件仍是列表里的前四行。
+#
+# 五个组件在同一 DSH 进程里共用一份总线实例：心跳只起一次，云同步只在 device 组件启用
 # 且 config.json 里 cloudEnabled=true 时才跑。安装/改动后需重启对应的 DSH 进程。
 # ============================================================================
 
 - insert:
     - id: crossterm-session
-      # 第一行用裸包名：浏览器的 client 半端只对「裸包名」行生效，
-      # 插件页里的配置卡片就挂在这一行上。名字仍由 locale/zh.json 的 meta.title 提供。
-      name: dsh-crossterm
+      name: dsh-crossterm/parts/session
       config:
         part: session
     - id: crossterm-terminal
@@ -40,4 +46,10 @@
     - id: crossterm-account
       name: dsh-crossterm/parts/account
       config:
-        part: account
+        part: account
+    - id: crossterm-ui
+      # 裸包名：浏览器 client 半端只认这一行，插件页配置卡片挂在这里。
+      # 也是插件页顶部标题/简介的来源（locale/zh.json 的 meta）。
+      name: dsh-crossterm
+      config:
+        part: ui

package/lib/bus.js

@@ -22,7 +22,7 @@ import os from 'node:os'
 import path from 'node:path'
 import crypto from 'node:crypto'
 
-export const VERSION = '0.6.0'
+export const VERSION = '0.6.2'
 
 /** DSH 的家目录：与宿主其它状态（sessions / profiles）同一个根，多终端天然共享 */
 export function dshHome() {

package/lib/cloud/layout.js

@@ -242,17 +242,22 @@ export async function ensureRules(pan, paths, info = {}) {
   ]
   if (paths.inboxReadmeFile) docs.push([paths.inboxReadmeFile, inboxReadmeMarkdown({ account, device, version })])
   const written = []
+  let failed = 0
   for (const [remote, text] of docs) {
     try {
+      if (!remote) { failed += 1; continue }
       if (await pan.exists(remote)) continue
       await pan.putBuffer(Buffer.from(text, 'utf8'), remote)
       written.push(remote)
       log(`云端规则已写入：${remote}`)
     } catch (e) {
+      failed += 1
       log(`写云端规则失败 ${remote}：${(e && e.message) || String(e)}`)
     }
   }
-  return { written }
+  // 收件箱说明算一份必须存在的文档：缺少它的旧路径缓存不能冒充「规则已是最新」
+  if (!paths.inboxReadmeFile) failed += 1
+  return { written, failed }
 }
 
 /**
@@ -263,18 +268,29 @@ export async function ensureLayout({ pan, cfg = {}, device = {}, cacheFile, forc
   const nodeId = sanitize(device.nodeId || 'device')
   const cached = readCache(cacheFile)
   if (!force && cached && cached.deviceId === nodeId && Date.now() - Number(cached.at || 0) < CACHE_MS && cached.paths) {
+    // 路径是「算出来的」而不是状态：升级后新增的路径（规则文档、收件箱说明）必须重新算，
+    // 直接沿用旧缓存的 paths 会让 ensureRules 拿到 undefined、规则永远写不出去。
+    const paths = buildPaths({
+      home: cached.home || cfg.cloudHome || DEFAULT_HOME,
+      account: cached.account || cached.paths.account || 'default',
+      deviceId: nodeId,
+    })
+    const state = { ...cached, home: cached.home || cfg.cloudHome || DEFAULT_HOME, paths }
     if (Number(cached.rulesVersion || 0) < RULES_VERSION) {
-      await ensureRules(pan, cached.paths, {
+      const r = await ensureRules(pan, paths, {
         log,
-        account: cached.account,
+        account: state.account,
         device: nodeId,
-        role: cached.role,
+        role: state.role,
         version: device.version || '',
       })
-      cached.rulesVersion = RULES_VERSION
-      writeCache(cacheFile, cached)
+      if (!r.failed) {
+        state.rulesVersion = RULES_VERSION
+        state.rulesWritten = r.written
+        writeCache(cacheFile, state)
+      }
     }
-    return { ...cached, cached: true, ensuredAt: cached.at }
+    return { ...state, cached: true, ensuredAt: cached.at }
   }
 
   const who = await resolveAccount(pan, cfg, log)
@@ -358,9 +374,12 @@ export async function ensureLayout({ pan, cfg = {}, device = {}, cacheFile, forc
     deviceId: nodeId,
     account: who.account,
     accountSource: who.source,
+    home: cfg.cloudHome || DEFAULT_HOME,
     role,
-    rulesVersion: RULES_VERSION,
+    // 有文档没写成功就不要把版本号标上去，下次 ensure 还会重试
+    rulesVersion: rules.failed ? 0 : RULES_VERSION,
     rulesWritten: rules.written,
+    rulesFailed: rules.failed,
     paths,
     created,
     accountInfo,

package/lib/index.js

@@ -1315,10 +1315,11 @@ const TOOL_PART = {
   term_cloud: 'device',
 }
 
-const PARTS = ['all', 'session', 'terminal', 'device', 'account']
+const PARTS = ['all', 'ui', 'session', 'terminal', 'device', 'account']
 
 const PART_LABEL = {
   all: '全部组件',
+  ui: '入口（插件卡片）',
   session: '跨会话',
   terminal: '跨终端',
   device: '跨设备',

package/lib/web.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { spawn } from 'node:child_process'
 import { VERSION, readConfig, writeConfig } from './bus.js'
 import { createPan } from './cloud/pan.js'
@@ -11,6 +12,8 @@ import { runSetup } from './cloud/setup.js'
 
 const PKG = 'dsh-crossterm'
 const NPM_REGISTRIES = ['https://registry.npmmirror.com', 'https://registry.npmjs.org']
+// 包根目录：lib/web.js 的上一级（README.md / CHANGELOG.md / locale / parts 都在这里）
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 
 let installed = false
 let setupRunning = false
@@ -263,6 +266,63 @@ function statusOf(term) {
   }
 }
 
+/**
+ * 插件自述（0.6.2）：插件标题/简介 + 四个组件的名称与简介 + 最近几版更新日志。
+ * 卡片（浏览器半端）与插件页顶部共用 locale/zh.json 的 meta，这里读同一份文件，
+ * 保证「插件页怎么显示」和「卡片里怎么显示」永远一致。
+ */
+const PART_ORDER = [
+  { part: 'session', fallback: '跨会话' },
+  { part: 'terminal', fallback: '跨终端' },
+  { part: 'device', fallback: '跨设备' },
+  { part: 'account', fallback: '跨账号' },
+]
+
+let aboutCache = null
+
+function readChangelog(maxSections = 3, maxChars = 6000) {
+  try {
+    const text = fs.readFileSync(path.join(ROOT, 'CHANGELOG.md'), 'utf8')
+    const chunks = text.split(/^## /m)
+    const head = chunks.shift() || ''
+    const picked = chunks.slice(0, maxSections).map((c) => '## ' + c.trim())
+    const body = picked.join('\n\n')
+    const out = body || head.trim()
+    return out.length > maxChars ? out.slice(0, maxChars) + '\n…' : out
+  } catch {
+    return ''
+  }
+}
+
+function aboutOf() {
+  if (aboutCache && aboutCache.version === VERSION) return aboutCache
+  let meta = {}
+  try {
+    const doc = JSON.parse(fs.readFileSync(path.join(ROOT, 'locale', 'zh.json'), 'utf8'))
+    meta = (doc && doc.meta) || {}
+  } catch { /* ignore */ }
+  const components = PART_ORDER.map((item) => {
+    let doc = {}
+    try {
+      doc = JSON.parse(fs.readFileSync(path.join(ROOT, 'parts', `${item.part}.manifest.json`), 'utf8'))
+    } catch { /* ignore */ }
+    return {
+      part: item.part,
+      name: doc.name || item.fallback,
+      description: doc.description || '',
+    }
+  })
+  aboutCache = {
+    name: PKG,
+    version: VERSION,
+    title: meta.title || PKG,
+    description: meta.description || '',
+    components,
+    changelog: readChangelog(),
+  }
+  return aboutCache
+}
+
 /**
  * 只注册一次；行被关闭时随 fiber 一起注销，重新启用会再注册。
  */
@@ -281,6 +341,19 @@ export function registerWeb(ctx, term, log) {
             handler: (req, res) => json(res, 200, statusOf(term)),
           }),
         )
+        disposers.push(
+          webCtx.webServer.register({
+            kind: 'exact',
+            path: '/crossterm/api/about',
+            handler: (req, res) => {
+              try {
+                json(res, 200, { ok: true, ...aboutOf() })
+              } catch (error) {
+                json(res, 200, { ok: false, message: String((error && error.message) || error) })
+              }
+            },
+          }),
+        )
         disposers.push(
           webCtx.webServer.register({
             kind: 'exact',
@@ -525,4 +598,4 @@ export function registerWeb(ctx, term, log) {
 }
 
 // 只给探针用：把内部小工具导出来，宿主运行时不依赖这些导出
-export { decodeOutput, runtimeTools, looksMissingCommand, updateErrorText }
+export { decodeOutput, runtimeTools, looksMissingCommand, updateErrorText, aboutOf }

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Cross-session",
-    "description": "Link the sessions inside this terminal: chain codes, inline mail, inbox"
+    "title": "CrossTerm",
+    "description": "Connect sessions, terminals and devices of one DSH account: chain codes, inline mail, a cloud relay and automatic backups. Four components, each with its own switch."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "跨会话",
-    "description": "同一终端里的多个会话之间互通：特征码链、内联邮件、收件箱"
+    "title": "跨端互通",
+    "description": "同一 DSH 账号下的会话、终端、设备之间互通：特征码链、内联邮件、云端中转站与自动备份。四个组件可单独开关。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-crossterm",
-  "version": "0.6.0",
-  "description": "DSH 跨终端互联：同一账号下的多个 DSH 终端/进程互发邮件与文件（主题内联、正文落盘，收件方自己读）",
+  "version": "0.6.2",
+  "description": "跨端互通：同一 DSH 账号下的会话、终端、设备之间互通 —— 特征码链、内联邮件、云端中转站与自动备份",
   "type": "module",
   "main": "./lib/index.js",
   "exports": {