dsh-crossterm 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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
+
+### 共享收件箱里也放一份说明
+- 新常量 `INBOX_README_FILE = '_说明.md'`、`RULES_VERSION = 2`（`lib/cloud/layout.js`），
+  `buildPaths()` 增 `inboxReadmeFile`（`<账号>/shared/<设备>/inbox/_说明.md`）；
+  新增 `inboxReadmeMarkdown()`，`ensureRules()` 一并写入（只在缺失时写，不覆盖）。
+- 说明内容：这个文件夹是什么、谁写谁取（别的设备写信封、本机中转站每 `relayIntervalMs` 取）、
+  信封 JSON 格式（`id/from/to/subject/text/files/createdAt`）、注意事项
+  （别手工删改信封、`_` 开头的都是系统文件会被跳过、收件人找不到就留件不消费、附件按 `<mailId>/<文件名>` 存）。
+- `lib/cloud/relay.js` 新增并导出 `isEnvelopeFile(name)`：只把 **`.json` 且不以 `_` 开头、非 `.tmp`/隐藏文件**
+  当信封；`poll()` 改用它过滤 —— 否则 `_说明.md` 会被当成信封反复解析失败、记 failed。
+- 探针：`probe-layout-rules.mjs` 扩到 **26 项全 PASS**（含三份文档位置与收件箱说明内容）；
+  新增 `probe-inbox-readme.mjs` **17 项全 PASS**（说明不被当信封、正常信封仍投递并归档到 `done/`、
+  失败留件、第二轮不重复投递）；`probe-cloud-home.mjs` 断言改为「收件箱只剩系统说明」后 **42 项全 PASS**。
+
 ## 0.5.0 — 2026-10-19
 
 ### 云端规则写进云端本身：账号规则放在大文件夹下，设备规则放在账号文件夹下

package/README.md

@@ -23,17 +23,18 @@ A 终端看不到 B 终端里有哪个会话、在干什么，也没法把一条
 | 跨设备 | 经云端总线，在多台机器的 DSH 之间互发邮件与文件 | `term_cloud` |
 | 跨账号 | 预留位：后续用于跨账号互通，当前不挂工具 | — |
 
-**本版更新（0.5.0）**
-
-- **云端规则写进云端本身**：账号规则放云端大文件夹下 `/dsh/_规则-账号.md`，
-  同账号多设备规则放账号文件夹下 `/dsh/<账号>/_规则-设备.md`，
-  由插件在建目录时自动生成（已存在不覆盖），任何设备打开云盘就能看到这套规则。
-- 账号规则涵盖：目录约定、账号名来源、管理员与成员（第一个进云的设备是 `ownerDevice`）、跨账号预留；
-  设备规则涵盖：每台设备目录、`shared/<设备>/{inbox,done,files}` 收发、会话字节增量备份与
-  `_session.json` 水位、中转站轮询与按收件人投递、冲突与并发。
-- `ensureLayout()` 返回值新增 `rulesVersion` / `rulesWritten`；缓存命中时也会补写缺失的规则文档，
-  升级后不用手动清 `layout.json`。
-- 探针 `probe-layout-rules.mjs` 23 项全 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.5.0'
+export const VERSION = '0.6.1'
 
 /** DSH 的家目录：与宿主其它状态（sessions / profiles）同一个根，多终端天然共享 */
 export function dshHome() {

package/lib/cloud/layout.js

@@ -12,10 +12,11 @@ export const DEFAULT_HOME = 'dsh'
 export const ACCOUNT_FILE = '_account.json'
 export const DEVICE_FILE = '_device.json'
 export const INBOX_FILE = '_inbox.json'
-/** 规则文档（自动生成，手改会被覆盖）：账号规则放大文件夹下，设备规则放账号文件夹下 */
+/** 规则文档（自动生成，手改会被覆盖）：账号规则放大文件夹下，设备规则放账号文件夹下，收件箱说明放共享收件箱里 */
 export const ACCOUNT_RULES_FILE = '_规则-账号.md'
 export const DEVICE_RULES_FILE = '_规则-设备.md'
-export const RULES_VERSION = 1
+export const INBOX_README_FILE = '_说明.md'
+export const RULES_VERSION = 2
 const CACHE_MS = 10 * 60 * 1000
 
 /** 目录名净化：去掉路径分隔符/控制字符/中文等非 ASCII（云盘接口对特殊字符不友好） */
@@ -48,6 +49,7 @@ export function buildPaths({ home = DEFAULT_HOME, account = 'default', deviceId
     inboxFile: `${deviceRoot}/${INBOX_FILE}`,
     accountRulesFile: `${base}/${ACCOUNT_RULES_FILE}`,
     deviceRulesFile: `${accountDir}/${DEVICE_RULES_FILE}`,
+    inboxReadmeFile: `${deviceRoot}/inbox/${INBOX_README_FILE}`,
   }
 }
 
@@ -190,6 +192,46 @@ export function deviceRulesMarkdown({ account = 'default', device = 'device', ro
 `
 }
 
+/** 云端共享收件箱说明（放在 shared/<设备>/inbox/ 里） */
+export function inboxReadmeMarkdown({ account = 'default', device = 'device', version = '', at = iso() } = {}) {
+  return `# 云端共享收件箱 · 说明
+
+本文件夹是设备 \`${device}\` 的**云端收件箱**：同账号下别的设备发给它的消息/文件先落在这里，
+再由这台设备的「云端中转站」定时取走，按**收件人（会话名）**投递到本机会话。
+
+## 谁写、谁取
+
+- **写**：别的设备发信时写一个 \`<mailId>.json\` 信封（附件在 \`../files/<mailId>/\`）。
+- **取**：本机中转站每 \`relayIntervalMs\`（默认 20 s）扫一次，投递成功后把信封搬去 \`../done/\`，再删这里的原件。
+
+## 信封格式
+
+\`\`\`json
+{
+  "id": "m-<时间戳>-<随机>",
+  "from": { "nodeId": "…", "name": "…" },
+  "to": "<会话名 或 完整 sessionId 或 8 位短号>",
+  "subject": "主题",
+  "text": "正文",
+  "files": [{ "name": "文件名", "size": 1234 }],
+  "createdAt": 1792385549000
+}
+\`\`\`
+
+## 注意
+
+- **别手工删/改** \`*.json\` 信封：投递与否以本机状态为准，删掉就等于丢信。
+- 以 \`_\` 开头的文件（本说明、\`_inbox.json\` 等）是系统文件，中转站会跳过，不当作信封。
+- 收件人找不到（会话不存在）时信封**留在云端不消费**，不会丢；本机把会话打开/建好后下一轮自动投递。
+- 附件按 \`<mailId>/<文件名>\` 存放；重名以云端最后写入为准。
+- 想从别的设备发信：\`term_cloud action="send" toDevice="<设备>" to="<会话名>" text="…"\`。
+
+## 版本
+
+规则版本 v${RULES_VERSION} · 设备 \`${device}\` · 账号 \`${account}\` · 由插件${version ? ` ${version}` : ''} 于 ${at} 生成
+`
+}
+
 /** 只在缺失时写规则文档；失败只记日志，不影响目录建立 */
 export async function ensureRules(pan, paths, info = {}) {
   const { log = () => {}, account = 'default', device = 'device', role = 'member', version = '' } = info
@@ -198,18 +240,24 @@ export async function ensureRules(pan, paths, info = {}) {
     [paths.accountRulesFile, accountRulesMarkdown({ account, device, version })],
     [paths.deviceRulesFile, deviceRulesMarkdown({ account, device, role, version })],
   ]
+  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 }
 }
 
 /**
@@ -220,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)
@@ -315,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/cloud/relay.js

@@ -28,6 +28,10 @@ function saveState(file, state) {
 
 const isTmp = (name) => /\.tmp$/.test(name) || name.startsWith('.')
 
+/** 只处理信封 json：跳过 .tmp / 隐藏文件 / 以 _ 开头的系统说明（如 _说明.md、_inbox.json） */
+export const isEnvelopeFile = (name) =>
+  /\.json$/i.test(name) && !isTmp(name) && !String(name).startsWith('_')
+
 function parseEnvelope(text) {
   const j = JSON.parse(text)
   const to = Array.isArray(j.to) ? j.to : j.to || j.toSession || j.recipient || ''
@@ -84,7 +88,7 @@ export function createRelay({ pan, getLayout, localDir, stateFile, deliver, log
         stats.at = Date.now()
         return { ...stats, error: `列收件箱失败 errno=${list.errno}` }
       }
-      const files = (list.list || []).filter((f) => f.isdir === 0 && !isTmp(f.server_filename))
+      const files = (list.list || []).filter((f) => f.isdir === 0 && isEnvelopeFile(f.server_filename))
       stats.scanned = files.length
       stats.delivered = 0
       stats.failed = 0

package/package.json

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