dsh-crossterm 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # dsh-crossterm 变更记录
 
+## 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,15 @@ 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.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。
 
 ## 一、安装与卸载
 

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.0'
 
 /** 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,6 +240,7 @@ 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 = []
   for (const [remote, text] of docs) {
     try {

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.0",
   "description": "DSH 跨终端互联：同一账号下的多个 DSH 终端/进程互发邮件与文件（主题内联、正文落盘，收件方自己读）",
   "type": "module",
   "main": "./lib/index.js",