dsh-crossterm 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # dsh-crossterm 变更记录
 
+## 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

@@ -23,15 +23,18 @@ A 终端看不到 B 终端里有哪个会话、在干什么，也没法把一条
 | 跨设备 | 经云端总线，在多台机器的 DSH 之间互发邮件与文件 | `term_cloud` |
 | 跨账号 | 预留位：后续用于跨账号互通，当前不挂工具 | — |
 
-**本版更新（0.6.0）**
-
-- **共享收件箱里也带一份说明**：`/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.1）**
+
+- **修：旧布局缓存把新增的云端文档挡住了**。0.5.0 / 0.6.0 说「命中旧缓存会自动补写」，实际没补 ——
+  云盘里根本没有 `_规则-账号.md`、`_规则-设备.md`、`inbox/_说明.md`。
+- 根因：`ensureLayout()` 命中缓存时直接沿用 `cached.paths`，而路径是 `buildPaths()` **算出来的**；
+  旧缓存没有 `accountRulesFile` / `deviceRulesFile` / `inboxReadmeFile` 三个字段，`ensureRules()` 拿到 `undefined`
+  就跳过，还照样把 `rulesVersion` 标成最新。
+- 修法：命中缓存时按 `home / account / deviceId` 重新算路径；`ensureRules()` 返回 `{ written, failed }`，
+  **只有 `failed === 0` 才把 `rulesVersion` 抬上去**，否则保持 0 下次继续重试。
+- 探针 `probe-layout-stale-cache.mjs` 12 项全 PASS（旧缓存→重算→补写三份文档→写回新缓存；
+  第二次不重复上传；上传失败时不冒充最新），回归 26 + 42 + 17 项全 PASS。
+- 上一版（0.6.0）的内容仍在：共享收件箱里的 `_说明.md`、中转站 `isEnvelopeFile()` 只认 `.json` 信封。
 
 ## 一、安装与卸载
 

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.1'
 
 /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crossterm",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "DSH 跨终端互联：同一账号下的多个 DSH 终端/进程互发邮件与文件（主题内联、正文落盘，收件方自己读）",
   "type": "module",
   "main": "./lib/index.js",