dsh-crossterm 0.3.34 → 0.3.36

package/README.md

@@ -226,6 +226,24 @@ dsh plugin --profile desktop remove dsh-crossterm
 | `DSH_CROSSTERM_NAME` | 本终端的显示名（多开时区分） |
 | `DSH_CROSSTERM_AUTODELIVER` | `0/false/off/no` = 只进收件箱不自动注入；`1/true/on/yes` = 强制自动注入 |
 
+### 一键配置云盘（0.3.35，挂记事本）
+
+跨机器互通有两条路：共享目录（把 `busDir` 指到 `\\nas\dsh-bus` 之类，最简单），或走自己的网盘云端目录。走网盘时**账号由你自己配**，插件只认本机这两个文件：
+
+    <DSH_HOME>\crossterm\baidu-app.json    { appKey, appSecret, redirectUri }
+    <DSH_HOME>\crossterm\baidu-auth.json   { appKey, accessToken, refreshToken, expiresAt, ... }
+
+一键流程（密钥不经过聊天，只在记事本里输入）：
+
+1. 对助手说「配置云盘」，或直接调 `term_cloud action="setup"`；插件页卡片在「未连接」状态也有 **配置云盘** 按钮。
+2. 插件写出模板并用**记事本**打开 `baidu-app.json` —— 把开放平台应用的 AppKey / AppSecret 填进引号。
+   `redirectUri` 默认 `http://127.0.0.1:19388/oauth/callback`，必须和开放平台「回调地址」完全一致。
+3. 保存并关闭记事本 → 插件校验 → 起本地回调 → 自动打开浏览器授权页 → 拿到 code 换 token → 写 `baidu-auth.json` → 打开 `cloudEnabled` 并启动同步。
+4. 浏览器没能回调时：`term_cloud action="setup" code="<授权 URL 里的 code>"` 手动收口；失败输出里也会带一条手动授权链接。
+5. 重复执行是安全的：已授权且 appKey 没变时直接返回 `step: "already"`，不会再弹记事本。
+
+> 插件、npm 包、B 机安装包**都不携带任何凭证**；换机器要各自配自己的。
+
 ### 手动 / 自动注入开关（三层）
 
 | 层 | 开关 | 粒度 |

package/client/client.js

@@ -198,6 +198,37 @@ window.__ModuleLoader__.load({
 				}
 			};
 
+			const onSetupCloud = async () => {
+				setBusy("setup");
+				setMsg("正在打开记事本…把 AppKey / AppSecret 填进引号里，保存并关闭记事本");
+				try {
+					const data = await call("/crossterm/api/cloud/setup", "POST");
+					setMsg((data && data.message) || "已开始配置");
+					if (!(data && data.ok)) {
+						setBusy("");
+						return;
+					}
+					// 记事本关闭后会打开浏览器授权，这里每 3 秒看一次状态，最多等 2 分钟
+					for (let i = 0; i < 40; i += 1) {
+						await new Promise((resolve) => setTimeout(resolve, 3000));
+						const fresh = await call("/crossterm/api/status");
+						if (fresh && fresh.cloud) {
+							setStatus(fresh);
+							if (fresh.cloud.configured) {
+								setMsg("云盘已配置，云同步已开启");
+								setBusy("");
+								return;
+							}
+						}
+					}
+					setMsg("还没等到授权完成：如果记事本或浏览器还开着，按提示填完保存关闭即可，授权结束后同步会自动打开");
+				} catch (error) {
+					setMsg("配置失败：" + String((error && error.message) || error));
+				} finally {
+					setBusy("");
+				}
+			};
+
 			const version = status ? "v" + status.version : "";
 			const mode = status && status.install ? status.install.mode : "";
 			const cloud = (status && status.cloud) || {};
@@ -251,7 +282,8 @@ window.__ModuleLoader__.load({
 										: "—",
 								),
 								status
-									? h(
+									? cloud.configured
+										? h(
 											"button",
 											{
 												style: cloud.running ? S.switchOn : S.switchOff,
@@ -260,15 +292,24 @@ window.__ModuleLoader__.load({
 													void onToggleCloud();
 												},
 												disabled: busy !== "",
-												title: !cloud.configured
-													? "还没配置云盘，点击查看说明"
-													: cloud.running
-														? "点击关闭云同步"
-														: "点击开启云同步",
-												"aria-label": !cloud.configured ? "云盘未配置" : cloud.running ? "云同步开启中" : "云同步已关闭",
+												title: cloud.running ? "点击关闭云同步" : "点击开启云同步",
+												"aria-label": cloud.running ? "云同步开启中" : "云同步已关闭",
 											},
 											h("span", { style: cloud.running ? S.knobOn : S.knobOff }),
 										)
+										: h(
+											"button",
+											{
+												style: S.btn,
+												onClick: (event) => {
+													event.stopPropagation();
+													void onSetupCloud();
+												},
+												disabled: busy !== "",
+												title: "打开记事本填 AppKey / AppSecret，然后浏览器授权",
+											},
+											busy === "setup" ? "等待授权…" : "配置云盘",
+										)
 									: null,
 							),
 						),

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.3.34'
+export const VERSION = '0.3.36'
 
 /** DSH 的家目录：与宿主其它状态（sessions / profiles）同一个根，多终端天然共享 */
 export function dshHome() {

package/lib/cloud/setup.js

@@ -0,0 +1,306 @@
+// 一键配置云盘：模板 → 记事本 → 校验 → 浏览器授权 → 落 token
+//
+// 设计目标（对应 README「云端配置」与 AGENTS 第 9 条待办）：
+//   1. 第一次跑：把 baidu-app.json 模板写到数据目录，用记事本打开让用户填 AppKey / AppSecret；
+//   2. 用户保存并关闭记事本后，这里自动校验并起本地回调服务器（默认 127.0.0.1:19388/oauth/callback）；
+//   3. 自动打开浏览器授权页，拿到 code 后换 access/refresh token，写 baidu-auth.json；
+//   4. 调用方（term_cloud setup）再把 config.json 的 cloudEnabled 打开。
+// 全程只写本机文件，不上传任何凭证。
+import fs from 'node:fs'
+import http from 'node:http'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+const DEFAULT_REDIRECT = 'http://127.0.0.1:19388/oauth/callback'
+const TOKEN_URL = 'https://openapi.baidu.com/oauth/2.0/token'
+const AUTHORIZE_URL = 'https://openapi.baidu.com/oauth/2.0/authorize'
+
+const TEMPLATE_HELP = [
+  '把百度开放平台应用的 AppKey / AppSecret 填到下面两个字段的引号里，保存后关闭记事本，插件会自动继续。',
+  'redirectUri 必须和开放平台「应用信息 → 回调地址」完全一致；默认 http://127.0.0.1:19388/oauth/callback。',
+  '这是你自己的账号：这两个值只会写在本机这个文件里，插件不会把它上传到任何地方，也不会放进安装包。',
+  '填好后关闭记事本即可；关掉记事本但没填，重新调 term_cloud setup 会再打开。',
+]
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf8')
+}
+
+/** 模板：空字段 + 说明，用户名下第一眼就能看懂要填什么 */
+function ensureTemplate(appFile) {
+  if (fs.existsSync(appFile)) return { created: false }
+  writeJson(appFile, {
+    _说明: TEMPLATE_HELP,
+    appKey: '',
+    appSecret: '',
+    redirectUri: DEFAULT_REDIRECT,
+  })
+  return { created: true }
+}
+
+/** 校验 app 文件：两个字段都得是填好的真值（模板里的空串/占位符不算） */
+function readApp(appFile) {
+  const raw = readJson(appFile)
+  if (!raw || typeof raw !== 'object') return { ok: false, detail: `读不出 ${appFile}（不是合法 JSON）` }
+  const appKey = String(raw.appKey || '').trim()
+  const appSecret = String(raw.appSecret || '').trim()
+  const redirectUri = String(raw.redirectUri || '').trim() || DEFAULT_REDIRECT
+  const placeholder = (v) => !v || /^(your|填写|appkey|appsecret|xxx|todo)/i.test(v) || v.includes('填')
+  if (placeholder(appKey)) return { ok: false, detail: 'appKey 还没填（打开记事本填好再保存）', appFile }
+  if (placeholder(appSecret)) return { ok: false, detail: 'appSecret 还没填（打开记事本填好再保存）', appFile }
+  let url
+  try {
+    url = new URL(redirectUri)
+  } catch {
+    return { ok: false, detail: `redirectUri 不是合法 URL：${redirectUri}` }
+  }
+  if (url.hostname !== '127.0.0.1' && url.hostname !== 'localhost') {
+    return { ok: false, detail: `redirectUri 必须指向本机（当前 ${redirectUri}）；百度要求回调能落到本机才能自动收 code` }
+  }
+  return { ok: true, appKey, appSecret, redirectUri: url.toString() }
+}
+
+/** 用记事本打开模板文件，等用户关掉（或超时） */
+function openNotepad(file, timeoutMs, log) {
+  return new Promise((resolve) => {
+    if (process.platform !== 'win32') {
+      resolve({ opened: false, detail: '当前不是 Windows，请手动编辑这个文件后重跑：' + file })
+      return
+    }
+    let child
+    try {
+      child = spawn('notepad.exe', [file], { stdio: 'ignore', windowsHide: false })
+    } catch (error) {
+      resolve({ opened: false, detail: '打不开记事本：' + String((error && error.message) || error) })
+      return
+    }
+    if (log) log('已用记事本打开 ' + file + '，填好 AppKey/AppSecret 后保存并关闭')
+    let done = false
+    const finish = (r) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      resolve(r)
+    }
+    const timer = setTimeout(() => finish({ opened: true, closed: false }), Math.max(5000, timeoutMs || 300000))
+    child.on('error', (error) => finish({ opened: false, detail: '记事本启动失败：' + String((error && error.message) || error) }))
+    child.on('close', () => finish({ opened: true, closed: true }))
+  })
+}
+
+function openBrowser(url, log) {
+  const opts = { stdio: 'ignore', detached: true, windowsHide: true }
+  try {
+    if (process.platform === 'win32') spawn('cmd', ['/c', 'start', '', url], opts).unref()
+    else if (process.platform === 'darwin') spawn('open', [url], opts).unref()
+    else spawn('xdg-open', [url], opts).unref()
+  } catch (error) {
+    if (log) log('打开浏览器失败：' + String((error && error.message) || error) + '，请手动访问授权链接')
+    return false
+  }
+  return true
+}
+
+function authorizeUrl(app, state) {
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: app.appKey,
+    redirect_uri: app.redirectUri,
+    scope: 'basic,netdisk',
+    display: 'page',
+    state,
+  })
+  return `${AUTHORIZE_URL}?${params.toString()}`
+}
+
+async function exchange(app, code) {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: String(code).trim(),
+    client_id: app.appKey,
+    client_secret: app.appSecret,
+    redirect_uri: app.redirectUri,
+  })
+  const res = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  })
+  const text = await res.text()
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch {
+    data = { raw: text }
+  }
+  return { status: res.status, data }
+}
+
+function saveAuth(authFile, app, data) {
+  const out = {
+    appKey: app.appKey,
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresIn: data.expires_in,
+    expiresAt: Date.now() + (Number(data.expires_in) || 0) * 1000,
+    scope: data.scope,
+    updatedAt: new Date().toISOString(),
+  }
+  writeJson(authFile, out)
+  return out
+}
+
+function htmlPage(title, body) {
+  return `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font-family:system-ui;padding:40px;line-height:1.6"><h2>${title}</h2>${body}</body>`
+}
+
+/** 起本地回调服务器等 code（超时自动关掉，不占端口） */
+function waitForCode(app, { log, timeoutMs }) {
+  return new Promise((resolve) => {
+    const url = new URL(app.redirectUri)
+    const port = Number(url.port || 80)
+    const expectPath = url.pathname || '/oauth/callback'
+    const state = 'dshcrossterm' + Date.now().toString(36)
+    let settled = false
+    const finish = (r) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try {
+        server.close()
+      } catch {
+        /* ignore */
+      }
+      resolve(r)
+    }
+    const server = http.createServer(async (req, res) => {
+      let u
+      try {
+        u = new URL(req.url, `http://${url.host}`)
+      } catch {
+        res.writeHead(400).end('bad request')
+        return
+      }
+      if (u.pathname !== expectPath) {
+        res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' }).end(htmlPage('404', '<p>这不是授权回调地址。</p>'))
+        return
+      }
+      const code = u.searchParams.get('code')
+      const err = u.searchParams.get('error')
+      if (!code) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(htmlPage('授权失败', `<pre>${u.search.replace(/&/g, '&amp;')}</pre>`))
+        finish({ ok: false, detail: '授权回调没有 code：' + (err || u.search) })
+        return
+      }
+      if (log) log('收到授权回调，正在换 token')
+      const { status, data } = await exchange(app, code)
+      if (data && data.access_token) {
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(htmlPage('授权成功', '<p>可以关闭这个页面了，回到 DSH 看结果。</p>'))
+        finish({ ok: true, data, status })
+      } else {
+        res.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(htmlPage('换 token 失败', `<pre>${JSON.stringify(data).replace(/</g, '&lt;')}</pre>`))
+        finish({ ok: false, detail: `换 token 失败 HTTP ${status}：${JSON.stringify(data)}` })
+      }
+    })
+    server.on('error', (error) => finish({ ok: false, detail: `本地回调服务器起不来（端口 ${port} 被占用？）：${String((error && error.message) || error)}` }))
+    const timer = setTimeout(() => finish({ ok: false, detail: `等了 ${Math.round((timeoutMs || 180000) / 1000)} 秒没收到授权回调，已放弃（端口 ${port} 已释放）` }), Math.max(30000, timeoutMs || 180000))
+    const target = authorizeUrl(app, state)
+    // 先记下来：即使端口起不来，调用方也能把链接给用户手动打开
+    waitForCode.lastUrl = target
+    server.listen(port, url.hostname === 'localhost' ? '127.0.0.1' : url.hostname, () => {
+      if (log) log(`回调服务器已起 127.0.0.1:${port}${expectPath}，正在打开浏览器授权`)
+      openBrowser(target, log)
+    })
+  })
+}
+
+/**
+ * 跑整套一键配置。
+ * @param {object} cfg      readConfig() 的结果（用到 busDir / baiduAppFile / baiduAuthFile）
+ * @param {object} opts     { code?: 手动授权码, notepad?: 是否开记事本, timeoutMs?, log? }
+ */
+export async function runSetup(cfg, opts = {}) {
+  const appFile = cfg.baiduAppFile || path.join(cfg.busDir, 'baidu-app.json')
+  const authFile = cfg.baiduAuthFile || path.join(cfg.busDir, 'baidu-auth.json')
+  const log = typeof opts.log === 'function' ? opts.log : null
+  const steps = []
+  waitForCode.lastUrl = ''
+
+  // 0) 已经授权过且 appKey 没变：直接当成功（重复调用不会反复弹记事本）
+  const existingAuth = readJson(authFile)
+  const existingApp = readJson(appFile)
+  if (existingAuth && existingAuth.refreshToken && existingAuth.appKey && existingApp && existingAuth.appKey === String(existingApp.appKey || '').trim() && opts.force !== true) {
+    steps.push('已授权（复用现有 token）')
+    return { ok: true, step: 'already', appFile, authFile, scope: existingAuth.scope || '', steps }
+  }
+
+  // 1) 模板
+  const tpl = ensureTemplate(appFile)
+  if (tpl.created) {
+    steps.push('已生成模板 ' + appFile)
+    if (log) log('已生成云盘配置模板：' + appFile)
+  }
+
+  // 2) 记事本（只有字段没填时才开）
+  let app = readApp(appFile)
+  if (!app.ok && opts.notepad !== false) {
+    const r = await openNotepad(appFile, opts.notepadTimeoutMs || 300000, log)
+    if (!r.opened) return { ok: false, step: 'notepad', detail: r.detail, appFile, authFile, steps }
+    steps.push(r.closed ? '记事本已关闭' : '记事本仍开着')
+    if (!r.closed) {
+      return {
+        ok: false,
+        step: 'notepad-open',
+        detail: '记事本还开着：填好 appKey / appSecret 后保存并关闭，再调一次 term_cloud setup 继续',
+        appFile,
+        authFile,
+        steps,
+      }
+    }
+    app = readApp(appFile)
+  }
+  if (!app.ok) return { ok: false, step: 'validate', detail: app.detail, appFile, authFile, steps }
+  steps.push('已读到 appKey ' + app.appKey.slice(0, 4) + '…（' + app.redirectUri + '）')
+
+  // 3) 授权：手动 code 优先，否则起本地回调
+  let data
+  if (opts.code) {
+    const r = await exchange(app, opts.code)
+    if (!r.data || !r.data.access_token) {
+      return { ok: false, step: 'exchange', detail: `换 token 失败 HTTP ${r.status}：${JSON.stringify(r.data)}`, appFile, authFile, steps }
+    }
+    data = r.data
+    steps.push('用手动 code 换到 token')
+  } else {
+    const r = await waitForCode(app, { log, timeoutMs: opts.timeoutMs || 180000 })
+    if (!r.ok) {
+      return { ok: false, step: 'oauth', detail: r.detail, authorizeUrl: waitForCode.lastUrl || '', appFile, authFile, steps }
+    }
+    data = r.data
+    steps.push('浏览器授权成功')
+  }
+
+  const saved = saveAuth(authFile, app, data)
+  steps.push('已写入 ' + authFile)
+  return {
+    ok: true,
+    step: 'done',
+    appFile,
+    authFile,
+    scope: saved.scope || '',
+    expiresAt: saved.expiresAt,
+    steps,
+  }
+}

package/lib/index.js

@@ -36,6 +36,7 @@ import {
 import { deriveNameFromFile, findTranscript } from './names.js'
 import { createPan } from './cloud/pan.js'
 import { createCloud } from './cloud/sync.js'
+import { runSetup } from './cloud/setup.js'
 import { registerWeb } from './web.js'
 
 const PLUGIN = 'dsh-crossterm'
@@ -1616,13 +1617,26 @@ function buildTools(term, agent, part = 'all') {
 
   const cloud = defineTool({
     name: 'term_cloud',
-    description: '云总线同步：查看/开启/关闭本机总线与云端目录的镜像同步，或立刻同步一次。跨设备互通靠它把邮件、收件箱、链、链接、在线状态搬到云端。',
+    description: '云总线同步：查看/开启/关闭本机总线与云端目录的镜像同步，或立刻同步一次；setup 可一键配置自己的云盘（弹出记事本填 AppKey/AppSecret → 浏览器授权 → 自动开启同步）。',
     parameters: {
-      action: { type: 'string', enum: ['status', 'start', 'stop', 'once'], description: 'status=查看状态；start=开启（本进程内生效）；stop=关闭；once=立刻同步一次' },
+      action: { type: 'string', enum: ['status', 'start', 'stop', 'once', 'setup'], description: 'status=查看状态；start=开启（本进程内生效）；stop=关闭；once=立刻同步一次；setup=一键配置自己的云盘' },
+      code: { type: 'string', description: '仅 setup 用：授权回调 URL 里的 code（浏览器没自动回调时手动粘贴）；不填则插件自己起本地回调等待' },
     },
     output: {
       schema: { type: 'json' },
       render: textRender((v) => {
+        if (v && v.setup) {
+          const s = v.setup
+          const lines = []
+          lines.push(s.ok ? `云盘配置：成功${s.step === 'already' ? '（已有授权，直接复用）' : '（已拿到新 token，云同步已开启）'}` : `云盘配置：未完成（${s.step || '未知'}）：${s.detail || ''}`)
+          if (s.appFile) lines.push(`应用配置：${s.appFile}`)
+          if (s.authFile) lines.push(`授权文件：${s.authFile}`)
+          if (s.scope) lines.push(`授权范围：${s.scope}`)
+          if (s.expiresAt) lines.push(`到期时间：${new Date(s.expiresAt).toISOString()}`)
+          if (s.authorizeUrl) lines.push(`手动授权链接：${s.authorizeUrl}`)
+          if (Array.isArray(s.steps) && s.steps.length) lines.push(`过程：${s.steps.join(' → ')}`)
+          return lines.join('\n')
+        }
         if (!v || !v.ok) return errorText('云同步失败：')(v)
         const s = v.status || {}
         const lines = [
@@ -1641,6 +1655,17 @@ function buildTools(term, agent, part = 'all') {
       try {
         if (action === 'start') term.enableCloud()
         else if (action === 'stop') term.disableCloud()
+        else if (action === 'setup') {
+          const ret = await runSetup(term.cfg, {
+            code: typeof args?.code === 'string' && args.code.trim() ? args.code.trim() : '',
+            log: (line) => void term.warn(line),
+          })
+          if (!ret.ok) return { ok: false, detail: ret.detail || '云盘配置未完成', setup: ret }
+          await writeConfig({ cloudEnabled: true })
+          term.cfg = readConfig()
+          term.enableCloud()
+          return { ok: true, status: term.cloud ? term.cloud.status() : undefined, setup: ret }
+        }
         else if (action === 'once') {
           const c = term.cloud || term.enableCloud()
           const result = await c.once()

package/lib/web.js

@@ -4,12 +4,14 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { spawn } from 'node:child_process'
-import { VERSION } from './bus.js'
+import { VERSION, readConfig, writeConfig } from './bus.js'
+import { runSetup } from './cloud/setup.js'
 
 const PKG = 'dsh-crossterm'
 const NPM_REGISTRIES = ['https://registry.npmmirror.com', 'https://registry.npmjs.org']
 
 let installed = false
+let setupRunning = false
 
 function json(res, code, data) {
   const body = JSON.stringify(data)
@@ -127,9 +129,28 @@ async function latestVersion() {
   throw new Error(last || 'unknown')
 }
 
+// 子进程输出解码：中文 Windows 控制台默认 CP936（GBK），直接当 UTF-8 读会变成 ����。
+// 先按整段 UTF-8 严格解码，失败再退回 GBK；顺带清掉 ANSI 控制符与 \r 进度残留。
+function decodeOutput(buffer) {
+  if (!buffer || buffer.length === 0) return ''
+  let text
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(buffer)
+  } catch {
+    try {
+      text = new TextDecoder('gbk').decode(buffer)
+    } catch {
+      text = buffer.toString('utf8')
+    }
+  }
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '').replace(/\r/g, '\n')
+}
+
 function run(cmd, args, cwd) {
   return new Promise((resolve) => {
-    let out = ''
+    const chunks = []
+    let size = 0
     let child
     try {
       child = spawn(cmd, args, {
@@ -142,16 +163,34 @@ function run(cmd, args, cwd) {
       return
     }
     const push = (chunk) => {
-      out += String(chunk)
-      if (out.length > 20000) out = out.slice(-20000)
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8')
+      chunks.push(buf)
+      size += buf.length
+      // 只留最后 64 KB，免得长日志把内存和卡片撑爆
+      while (size > 65536 && chunks.length > 1) size -= chunks.shift().length
     }
     child.stdout && child.stdout.on('data', push)
     child.stderr && child.stderr.on('data', push)
-    child.on('error', (error) => resolve({ code: -1, out: out + String((error && error.message) || error) }))
-    child.on('close', (code) => resolve({ code, out }))
+    child.on('error', (error) =>
+      resolve({ code: -1, out: decodeOutput(Buffer.concat(chunks)) + String((error && error.message) || error) }),
+    )
+    child.on('close', (code) => resolve({ code, out: decodeOutput(Buffer.concat(chunks)) }))
   })
 }
 
+// 更新失败时给人的提示：命令找不到就明说，别把一行乱码甩到卡片上
+function updateErrorText(result) {
+  const raw = (result.out || '').trim()
+  if (!raw) {
+    return `自动更新没跑起来（dsh 退出码 ${result.code}）：本机找不到可用的 dsh 命令，请在命令行手动执行 dsh plugin add ${PKG}@latest，然后重启 DSH`
+  }
+  const tail = raw.slice(-1200)
+  if (/not recognized|不是内部或外部命令|无法将.{0,12}项识别|command not found|ENOENT/i.test(raw)) {
+    return `${tail}\n\n提示：PATH 里没有 dsh 命令，请在命令行手动执行 dsh plugin add ${PKG}@latest，然后重启 DSH`
+  }
+  return tail
+}
+
 function statusOf(term) {
   const cfg = term.cfg || {}
   const info = profileInfo(cfg.busDir)
@@ -190,6 +229,7 @@ function statusOf(term) {
  * 只注册一次；行被关闭时随 fiber 一起注销，重新启用会再注册。
  */
 export function registerWeb(ctx, term, log) {
+  if (typeof log !== 'function') log = () => {}
   if (installed) return
   installed = true
   try {
@@ -258,6 +298,42 @@ export function registerWeb(ctx, term, log) {
             },
           }),
         )
+        disposers.push(
+          webCtx.webServer.register({
+            kind: 'exact',
+            path: '/crossterm/api/cloud/setup',
+            handler: (req, res) => {
+              if (setupRunning) {
+                json(res, 200, { ok: false, running: true, message: '配置流程已经在进行中（看任务栏里的记事本）' })
+                return
+              }
+              const cfg = term.cfg
+              setupRunning = true
+              void (async () => {
+                try {
+                  const r = await runSetup(cfg, { log: (line) => void log(line) })
+                  if (r.ok) {
+                    await writeConfig({ cloudEnabled: true })
+                    term.cfg = readConfig()
+                    term.enableCloud()
+                    log(`cloud setup: ${r.step === 'already' ? '已有授权，直接复用' : '授权完成，云同步已开启'}`)
+                  } else {
+                    log(`cloud setup: 停在 ${r.step || 'unknown'} — ${r.detail || ''}`)
+                  }
+                } catch (error) {
+                  log('cloud setup 失败：' + String((error && error.message) || error))
+                } finally {
+                  setupRunning = false
+                }
+              })()
+              json(res, 200, {
+                ok: true,
+                running: true,
+                message: '已打开记事本：把 AppKey / AppSecret 填进引号里，保存并关闭记事本，浏览器会自动打开授权页',
+              })
+            },
+          }),
+        )
         disposers.push(
           webCtx.webServer.register({
             kind: 'exact',
@@ -284,7 +360,7 @@ export function registerWeb(ctx, term, log) {
                 message:
                   result.code === 0
                     ? '已更新，重启 DSH 后生效'
-                    : (result.out || `dsh 退出码 ${result.code}`).slice(-1200),
+                    : updateErrorText(result),
               })
             },
           }),

package/package.json

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