dsh-agentone 0.5.44 → 1.0.2

package/lib/client.js

@@ -281,6 +281,311 @@ window.__ModuleLoader__.load({
       );
     }
 
+    // ==drive-tab-begin==
+    // 飞书云盘侧边栏 tab：iframe 直嵌飞书网页版（飞书不设 frame-ancestors，
+    // 2026-10-13 spike 实测）。寻址走 /agentone/api/drive/home——host 侧用
+    // lark-cli 找到/创建用户的「我的空间/AgentOne」文件夹（folder token 每
+    // 用户独立，不能平台级写死，见 lib/drive.js）。页面交互（上传/下载/
+    // 整理）全部是飞书官方 Web UI，本组件只管「落到正确层级」+ 引导三态
+    // + 内容自动刷新（轮询 /api/drive/rev 清单指纹，变了重挂载 iframe）
+    // + 右下角手动刷新按钮（跨域 iframe 收不到事件，也调不了 reload）。
+    // better-sidebar 未装（独立 dsh 用户）时 ctx.get 取不到服务，静默不注册。
+    const DRIVE_TAB_ID = 'agentone:feishu-drive';
+    const DRIVE_HOME_API = '/agentone/api/drive/home';
+
+    // 寻址响应 → 组件相位（纯函数，测试直接覆盖）。
+    const DRIVE_GATE_STATES = [
+      'cli_missing', 'cli_unconfigured', 'cli_unauthorized',
+      'drive_scope_missing', 'drive_app_forbidden',
+    ];
+
+    function driveHomePhase(ok, body) {
+      const data = body && typeof body === 'object' ? body : {};
+      if (ok && data.state === 'ready' && data.url) {
+        return { kind: 'ready', url: data.url, name: data.name || 'AgentOne' };
+      }
+      if (ok && DRIVE_GATE_STATES.includes(data.state)) {
+        return {
+          kind: 'gate',
+          state: data.state,
+          missingScopes: Array.isArray(data.missing_scopes) ? data.missing_scopes : [],
+          appMissingScopes: Array.isArray(data.app_missing_scopes) ? data.app_missing_scopes : [],
+        };
+      }
+      return { kind: 'error', message: data.error || '云盘文件夹加载失败，请重试' };
+    }
+
+    const DRIVE_GATE_TEXT = {
+      // 首次使用要走一次飞书设备流授权（弹窗里扫码/确认），这层提示必须写明
+      cli_unauthorized: '云盘页签需要 lark-cli 的飞书授权才能定位你的「AgentOne」文件夹。首次使用请到 AgentOne 设置页点「去授权」，用手机飞书扫码确认后回来点「重试」。',
+      cli_missing: '本机还没有安装 lark-cli，无法定位云盘文件夹。请先在 AgentOne 设置页的「CLI」页签安装，再回来点「重试」。',
+      cli_unconfigured: 'lark-cli 还没有完成飞书应用初始化。请先在 AgentOne 设置页的「CLI」页签完成初始化（需要扫码/确认一次），再回来点「重试」。',
+    };
+
+    const scopeList = (scopes) => (scopes.length ? `（缺少：${scopes.join('、')}）` : '');
+
+    /** 三态之外的权限缺口文案：分清「用户重新授权能修」与「只能找管理员」。 */
+    function driveGateText(phase) {
+      if (phase.state === 'drive_scope_missing') {
+        return '你的飞书授权里还没有云盘权限' + scopeList(phase.missingScopes)
+          + '。请到 AgentOne 设置页 →「云盘」点「重新授权」，扫码确认后回来点「重试」。';
+      }
+      if (phase.state === 'drive_app_forbidden') {
+        return '飞书应用本身还没有开通云空间权限' + scopeList(phase.appMissingScopes.length ? phase.appMissingScopes : phase.missingScopes)
+          + '，重新授权解决不了。请联系管理员在飞书开放平台为应用开通云空间权限并发布版本，然后回来点「重试」。';
+      }
+      return DRIVE_GATE_TEXT[phase.state] || '云盘暂时不可用，请稍后点「重试」。';
+    }
+
+    const DRIVE_REV_API = '/agentone/api/drive/rev';
+    const DRIVE_REV_POLL_MS = 8000;
+    const DRIVE_REFRESH_TITLE = '刷新云盘内容';
+    const DRIVE_STALE_TITLE = '云盘内容有更新，点击刷新';
+
+    function FeishuDriveTab() {
+      const [phase, setPhase] = React.useState({ kind: 'loading' });
+      const [retryTick, setRetryTick] = React.useState(0);
+      const [reloadTick, setReloadTick] = React.useState(0);
+      const [stale, setStale] = React.useState(false);
+      React.useEffect(() => {
+        let cancelled = false;
+        setPhase({ kind: 'loading' });
+        fetch(DRIVE_HOME_API)
+          .then(async (resp) => driveHomePhase(resp.ok, await resp.json().catch(() => null)))
+          .then((next) => { if (!cancelled) setPhase(next); })
+          .catch(() => { if (!cancelled) setPhase({ kind: 'error', message: '网络异常，请重试' }); });
+        return () => { cancelled = true; };
+      }, [retryTick]);
+
+      // 自动刷新：iframe 跨域收不到飞书内部事件，只能宿主侧轮询根清单指纹
+      // （/drive/rev，服务端 10s 节流）——子文件夹里增删文档会 bump 它在根
+      // 清单中的 modified_time（真机实测），指纹一变就重挂载 iframe。首拍只
+      // 做基线不重载；rev 为 null（CLI 不可用/资料夹未初始化）按「未知」不动；
+      // 页面隐藏时跳过这一拍，省无谓的请求。
+      // 重挂载会回到根视图（跨域读不到也恢复不了用户在飞书里点开的层级），
+      // 所以检测到用户正浏览云盘（焦点在 iframe 内，activeElement 跨域可读）
+      // 时不硬拽——只点亮刷新按钮提示「有更新」，基线不前移；焦点离开后
+      // 下一拍自动应用。
+      React.useEffect(() => {
+        if (phase.kind !== 'ready') return undefined;
+        let baseline = null;
+        let stopped = false;
+        const timer = setInterval(() => {
+          if (typeof document !== 'undefined' && document.hidden) return;
+          fetch(DRIVE_REV_API)
+            .then(async (resp) => (resp.ok ? await resp.json().catch(() => null) : null))
+            .then((body) => {
+              if (stopped || !body || typeof body.rev !== 'string' || !body.rev) return;
+              if (baseline === null) {
+                baseline = body.rev;
+                return;
+              }
+              if (body.rev === baseline) return;
+              const browsing = typeof document !== 'undefined' && document.activeElement
+                && document.activeElement.tagName === 'IFRAME';
+              if (browsing) {
+                setStale(true);
+                return;
+              }
+              baseline = body.rev;
+              setStale(false);
+              setReloadTick((t) => t + 1);
+            })
+            .catch(() => {});
+        }, DRIVE_REV_POLL_MS);
+        return () => { stopped = true; clearInterval(timer); };
+      }, [phase.kind === 'ready' ? phase.url : '']);
+
+      // 手动刷新：立即重载 iframe 并重新寻址（资料夹被重新定位/收养过也能跟上）；
+      // 寻址失败保留当前画面不打断
+      const refreshDrive = () => {
+        setStale(false);
+        setReloadTick((t) => t + 1);
+        fetch(DRIVE_HOME_API)
+          .then(async (resp) => driveHomePhase(resp.ok, await resp.json().catch(() => null)))
+          .then((next) => { if (next.kind === 'ready') setPhase(next); })
+          .catch(() => {});
+      };
+
+      if (phase.kind === 'loading') {
+        return React.createElement('div', {
+          style: { padding: '24px', textAlign: 'center', color: 'var(--dsw-alias-label-secondary, #57606a)', fontSize: '13px' },
+        }, '正在定位你的飞书云盘文件夹…');
+      }
+      if (phase.kind === 'ready') {
+        // 不设 sandbox：飞书登录态依赖真实第三方 cookie 上下文（spike 实测
+        // 无 sandbox 时登录页可渲染、登录后云盘可用）。key 随 reloadTick 变化
+        // 即重挂载 = 重载（跨域 iframe 不能调 contentWindow.location.reload）。
+        // 用户浏览中时刷新被推迟：顶部横幅 + 胶囊按钮变色双提示（见上面轮询注释）。
+        const refreshTitle = stale ? DRIVE_STALE_TITLE : DRIVE_REFRESH_TITLE;
+        const banner = React.createElement('div', {
+          key: 'stale-banner',
+          style: {
+            position: 'absolute', top: '0', left: '0', right: '0', zIndex: '1',
+            display: 'flex', alignItems: 'center', justifyContent: 'center', gap: '8px',
+            padding: '6px 10px', fontSize: '12px',
+            background: 'rgba(47, 111, 235, 0.92)', color: '#fff',
+            boxShadow: '0 1px 4px rgba(0,0,0,0.12)',
+          },
+        }, '云盘内容有更新',
+          React.createElement('button', {
+            type: 'button',
+            onClick: refreshDrive,
+            style: {
+              border: '1px solid rgba(255,255,255,.7)', borderRadius: '6px', padding: '1px 10px',
+              fontSize: '12px', cursor: 'pointer',
+              background: 'rgba(255,255,255,.16)', color: '#fff',
+            },
+          }, '立即刷新'));
+        const frame = React.createElement('iframe', {
+          key: `drive-frame-${reloadTick}`,
+          src: phase.url,
+          title: '飞书云盘',
+          style: {
+            border: 'none', width: '100%', height: '100%', minHeight: '320px',
+            background: '#fff', display: 'block',
+          },
+        });
+        const pill = React.createElement('button', {
+          type: 'button',
+          title: refreshTitle,
+          'aria-label': refreshTitle,
+          onClick: refreshDrive,
+          style: {
+            position: 'absolute', right: '12px', bottom: '12px', zIndex: '1',
+            display: 'inline-flex', alignItems: 'center', gap: '5px',
+            height: '28px', padding: '0 12px',
+            border: stale ? 'none' : '1px solid rgba(47, 111, 235, 0.28)',
+            borderRadius: '14px', cursor: 'pointer', fontSize: '12px',
+            background: stale ? '#2f6feb' : '#eaf1fe',
+            color: stale ? '#fff' : '#2f6feb',
+            boxShadow: '0 1px 5px rgba(0,0,0,.18)',
+          },
+        }, React.createElement('svg', {
+          viewBox: '0 0 24 24', width: '14', height: '14', 'aria-hidden': 'true', focusable: 'false',
+        }, React.createElement('path', {
+          d: 'M17.65 6.35A7.95 7.95 0 0 0 12 4a8 8 0 1 0 7.73 10h-2.08A6 6 0 1 1 12 6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z',
+          fill: 'currentColor',
+        })),
+          React.createElement('span', null, stale ? '有更新，刷新' : '刷新'));
+        return React.createElement('div', {
+          style: { position: 'relative', width: '100%', height: '100%', minHeight: '320px' },
+        }, ...(stale ? [banner] : []), frame, pill);
+      }
+      const text = phase.kind === 'gate' ? driveGateText(phase) : phase.message;
+      const center = {
+        padding: '28px 20px', textAlign: 'center', color: 'var(--dsw-alias-label-secondary, #57606a)',
+        fontSize: '13px', lineHeight: '1.7',
+      };
+      const btnPrimary = {
+        padding: '7px 18px', fontSize: '13px', borderRadius: '9px', border: 'none', cursor: 'pointer',
+        background: '#2f6feb', color: '#fff', marginRight: '8px',
+      };
+      const btnGhost = { ...btnPrimary, background: 'var(--dsw-alias-fill-secondary, #f2f3f5)', color: 'var(--dsw-alias-label-primary, #3c434d)' };
+      return React.createElement('div', { style: center },
+        React.createElement('p', { style: { margin: '0 0 16px' } }, text),
+        React.createElement('button', { style: btnPrimary, onClick: () => setRetryTick((t) => t + 1) }, '重试'),
+        phase.kind === 'gate'
+          ? React.createElement('button', {
+              style: btnGhost,
+              onClick: () => window.open('/agentone/', '_blank', 'noopener'),
+            }, '打开设置页')
+          : null);
+    }
+
+    function feishuDriveTabDescriptor() {
+      return {
+        id: DRIVE_TAB_ID,
+        title: () => '飞书云盘',
+        description: () => '进入你的飞书云盘「AgentOne」文件夹，资料的上传与管理都在飞书界面内完成',
+        order: 80,
+        single: true,
+        // 飞书风格云盘实心图标（用户提供的 云盘.svg，viewBox 1024）
+        icon: (size) => React.createElement('svg', {
+          viewBox: '0 0 1024 1024', width: size, height: size,
+          'aria-hidden': 'true', focusable: 'false',
+        }, React.createElement('path', {
+          d: 'M778.581333 374.101333C766.976 237.226667 651.946667 129.706667 512 129.706667s-254.976 107.52-266.581333 244.394666c-93.184 27.989333-160.768 114.005333-160.768 216.064 0 124.586667 101.034667 225.621333 225.621333 225.621334h404.138667c124.586667 0 225.621333-101.034667 225.621333-225.621334-0.341333-102.058667-68.266667-188.074667-161.450667-216.064z m-128.341333 209.237334c-22.869333 21.845333-62.122667 49.834667-117.418667 58.709333-11.264 1.706667-22.186667 2.730667-32.768 2.730667-72.704 0-126.293333-37.888-142.336-50.858667-18.090667-14.677333-21.162667-41.301333-6.485333-59.392 14.677333-18.090667 41.301333-21.162667 59.392-6.485333 11.605333 9.557333 53.930667 39.253333 108.885333 30.72 35.498667-5.802667 60.416-25.258667 72.021334-36.181334 17.066667-16.042667 43.690667-15.36 59.733333 1.365334 16.725333 16.384 16.042667 43.349333-1.024 59.392z',
+          fill: '#635DF7',
+          opacity: '.7',
+        })),
+        component: () => React.createElement(FeishuDriveTab),
+      };
+    }
+
+    // 设置页（/agentone/ 子框架，web 走 iframe、桌面壳走 srcdoc）里点「打开云盘」
+    // 时，经 postMessage 让宿主页这边的我们把页签开出来；开不了就回 ok:false，
+    // 页面自己退回「新窗口打开飞书链接」。srcdoc 子框架 origin 为 'null'。
+    const DRIVE_OPEN_MESSAGE = 'agentone:open-feishu-drive';
+    const DRIVE_OPEN_RESULT = 'agentone:open-feishu-drive:result';
+
+    function isDriveOpenRequest(data) {
+      return Boolean(data && typeof data === 'object' && data.type === DRIVE_OPEN_MESSAGE);
+    }
+
+    function driveMessageTrusted(origin) {
+      return !origin || origin === 'null' || origin === window.location.origin;
+    }
+
+    /** 当前 dsh 会话 id（openTab 的 scope 用；取不到就让服务自己决定）。 */
+    function currentDshSessionId() {
+      try {
+        const raw = window.localStorage.getItem('dsh.sessions.current');
+        const current = raw ? JSON.parse(raw) : null;
+        return (current && current.sessionId) || null;
+      } catch {
+        return null;
+      }
+    }
+
+    // 注册并返回 disposer。走 cordis 软依赖 inject（与同宿主 dsh-ccpg-canvasui
+    // 注册侧边栏 tab 同口径）：better-sidebar 未装时回调不执行——独立 dsh
+    // 用户静默无页签；装了则等 betterSidebar 真正 provide 后再注册。
+    // 不能用同步 ctx.get：client fiber 的激活顺序不保证 better-sidebar 先就绪，
+    // 那个窗口里取到 null 会静默跳过且永不重试（真机事故：侧边栏找不到云盘入口）。
+    function registerFeishuDriveTab(ctx) {
+      if (typeof ctx.inject !== 'function') return () => {};
+      return ctx.inject(['betterSidebar'], (scope) => {
+        const sidebar = scope.betterSidebar;
+        if (!sidebar || typeof sidebar.registerTab !== 'function') return;
+        const openDriveTab = () => {
+          const sessionId = currentDshSessionId();
+          // better-sidebar 0.25 openTab 契约：{type,…} + ({sessionId}) scope
+          sidebar.openTab({ type: DRIVE_TAB_ID, title: '飞书云盘' }, sessionId ? { sessionId } : undefined);
+          return true;
+        };
+        const onMessage = (event) => {
+          if (!isDriveOpenRequest(event.data) || !driveMessageTrusted(event.origin)) return;
+          let ok = false;
+          try {
+            ok = openDriveTab();
+          } catch {
+            ok = false;
+          }
+          const target = event.origin && event.origin !== 'null' ? event.origin : '*';
+          try {
+            event.source?.postMessage({ type: DRIVE_OPEN_RESULT, ok }, target);
+          } catch {
+            /* 回执失败不影响已打开/未打开的事实 */
+          }
+        };
+        // 老宿主/测试沙箱可能没有 addEventListener：消息桥是增强，缺了就只注册页签
+        const canListen = typeof window.addEventListener === 'function';
+        if (canListen) window.addEventListener('message', onMessage);
+        const register = () => sidebar.registerTab(feishuDriveTabDescriptor());
+        if (typeof scope.effect !== 'function') {
+          register();
+          return;
+        }
+        scope.effect(register, 'dsh-agentone: feishu-drive tab');
+        if (canListen) {
+          scope.effect(() => () => window.removeEventListener('message', onMessage),
+            'dsh-agentone: feishu-drive open bridge');
+        }
+      });
+    }
+    // ==drive-tab-end==
+
     // ── 设置导航图标（workbench_fill）─────────────────────────────────────
     // dsh 设置弹窗的导航图标由 shell（ui-settings-general）按 section id 硬编码，
     // 注册项没有 icon 选项（仅 models/agent-presets/plugins 有专用图标，其余一律
@@ -333,6 +638,8 @@ window.__ModuleLoader__.load({
 
     function apply(ctx) {
       setupNavIcon();
+      // 飞书云盘侧边栏 tab（better-sidebar 缺失时内部静默跳过）
+      registerFeishuDriveTab(ctx);
       ctx.slots.inject('settings.section', () =>
         ctx.slots.register(
           {

package/lib/defaults-sync.js

@@ -259,7 +259,17 @@ export function createDefaultsSync({ config, profiles, credentials, log, interva
     promise.finally(() => manualOperations.delete(promise)).catch(() => {});
     return promise;
   }
-  return { sync, manualOperation, snapshot: () => structuredClone(state),
+  // 快照是 /api/status（5s 轮询）与 defaults/status 的下发边界：description
+  // （技能包全文，几百字/条）只在展示层被引用，而新版页面已彻底不渲染——
+  // 在出口剥掉，轮询不再背着几十 KB 死重；内部 state 保持完整
+  const snapshot = () => {
+    const clone = structuredClone(state);
+    for (const list of [clone.skills, clone.plugins]) {
+      for (const entry of list || []) delete entry.description;
+    }
+    return clone;
+  };
+  return { sync, manualOperation, snapshot,
     reset() { stop(); profiles.setPolicy([]); state = { source: null, revision: null,
       checked_at: null, user_id: null, error: null, running: false, skills: [], plugins: [] }; },
     dispose() { disposed = true; stop(); return Promise.allSettled([inFlight, ...manualOperations.keys()]); },

package/lib/drive.js

@@ -0,0 +1,289 @@
+// 飞书云盘「AgentOne」文件夹寻址（host 半区）。
+//
+// 侧边栏「飞书云盘」tab 的页面本体是飞书官方 Web UI（iframe 直嵌，飞书
+// 不设 frame-ancestors——2026-10-13 spike 实测），插件只负责把用户落到
+// 正确的层级：他的「我的空间 / AgentOne」根目录。iframe 加载的文件夹 URL
+// 带每用户独立的 folder token（fldcn…），无法平台级写死，所以打开 tab 时
+// 经本模块用 lark-cli 寻址：
+//   1. 本地缓存的 folder token 校验仍可用 → 直接用（用户改文件夹名不
+//      影响，token 不变）；
+//   2. 失效则按名字在「我的空间」根目录翻页找；
+//   3. 找不到才创建（发生在用户点开云盘 tab / 设置页点初始化的明确意图
+//      之下，不是后台自动写）。
+// 设置页还支持「收养」：用户粘贴任意云盘文件夹链接，inspect 解出 token
+// 校验可访问后作为文件夹（resolve 的 adoptUrl 路径）。
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { storeDir } from './store.js';
+
+export const AGENTONE_FOLDER_NAME = 'AgentOne';
+const DRIVE_CACHE_FILE = 'drive.json';
+// 根目录翻页上限（每页 200）：正常根目录远不会到 2000 项；超出宁可报错
+// 也不新建——「找不到就建」在翻页盲区会造成两个同名文件夹分裂。
+const MAX_LIST_PAGES = 10;
+const LIST_PAGE_SIZE = 200;
+
+/**
+ * lark-cli JSON 输出解析。typed 命令与 `api` 子命令统一包 {ok, identity,
+ * data} 壳（ok=false 时 error 带结构化原因）；解析失败与 ok=false 一律抛
+ * LarkError —— 上层的用户可见文案由 classifyMissingScopes 决定，不把
+ * lark-cli 的英文原文丢给用户。
+ */
+export class LarkError extends Error {
+  constructor(payload = {}) {
+    const raw = payload.message || payload.hint || '';
+    // message 只进日志/排查；用户可见文案由路由层按 kind 生成
+    super(`飞书接口调用失败${raw ? `：${raw}` : ''}`);
+    this.name = 'LarkError';
+    this.type = payload.type || '';
+    this.subtype = payload.subtype || '';
+    this.code = payload.code ?? null;
+    this.missingScopes = Array.isArray(payload.missing_scopes) ? payload.missing_scopes : [];
+  }
+
+  /** 令牌缺 scope（可自助重新授权）；99991679 是 lark-cli 的 missing_scope 码。 */
+  get isScopeMissing() {
+    return this.subtype === 'missing_scope' || this.code === 99991679 || this.missingScopes.length > 0;
+  }
+}
+
+export function parseLarkJson(text) {
+  let data;
+  try {
+    data = JSON.parse(String(text || '').trim());
+  } catch {
+    throw new Error('飞书命令返回解析失败，请稍后重试');
+  }
+  if (data && typeof data === 'object' && !Array.isArray(data) && 'ok' in data) {
+    if (data.ok === false) {
+      throw new LarkError(data.error || {});
+    }
+    return data.data ?? {};
+  }
+  return data ?? {};
+}
+
+/** 在一页文件列表里精确匹配指定名字的文件夹（同名文件不算）。 */
+export function pickFolder(files, name) {
+  return (Array.isArray(files) ? files : []).find(
+    (item) => item?.type === 'folder' && item?.name === name,
+  ) || null;
+}
+
+/**
+ * 缺权限时分责任方——这是「云盘没权限」闭环的关键分支：
+ *   - 应用已开通该 scope、只是当前令牌没授 → 用户点「重新授权」即可自助解决；
+ *   - 应用本身没开通 → 重新授权也拿不到，只能管理员去开放平台开通并发布版本。
+ * appScopes 传 null（查不到）时按「用户可自助」处理，文案里保留管理员兜底路径。
+ */
+export function classifyMissingScopes({ missingScopes = [], appScopes = null } = {}) {
+  const missing = (Array.isArray(missingScopes) ? missingScopes : []).filter(Boolean);
+  const enabled = Array.isArray(appScopes) ? appScopes : null;
+  const appMissing = enabled ? missing.filter((scope) => !enabled.includes(scope)) : [];
+  return {
+    state: appMissing.length > 0 ? 'drive_app_forbidden' : 'drive_scope_missing',
+    missingScopes: missing,
+    appMissingScopes: appMissing,
+  };
+}
+
+/**
+ * 把 LarkError 映射成用户可见的权限缺口状态；不是权限问题返回 null。
+ * runAppScopes 注入（生产侧跑 `lark-cli auth scopes --json` 取应用已开通清单）：
+ * 拿不到清单时按「用户可自助」处理，文案里保留管理员兜底路径。
+ */
+export async function describeDrivePermission(error, { runAppScopes } = {}) {
+  if (!(error instanceof LarkError)) return null;
+  if (!error.isScopeMissing && error.type !== 'authorization') return null;
+  let appScopes = null;
+  if (typeof runAppScopes === 'function') {
+    try {
+      appScopes = await runAppScopes();
+    } catch {
+      appScopes = null;
+    }
+  }
+  const verdict = classifyMissingScopes({ missingScopes: error.missingScopes, appScopes });
+  return {
+    state: verdict.state,
+    missing_scopes: verdict.missingScopes,
+    app_missing_scopes: verdict.appMissingScopes,
+  };
+}
+
+/** 寻址缓存路径。归档技能/指令块要把它交给 AI，故对外导出。 */
+export function driveCachePath(config) {
+  return join(storeDir(config), DRIVE_CACHE_FILE);
+}
+
+/** 读寻址缓存。损坏（截断/手改）不抛出：移开并返回 null，走重新寻址。 */
+export async function loadDriveCache(config) {
+  const path = driveCachePath(config);
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+  try {
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== 'object') throw new Error('not a drive cache');
+    return data;
+  } catch {
+    await rm(path, { force: true }).catch(() => {});
+    return null;
+  }
+}
+
+/** 写寻址缓存（tmp + rename 原子替换，0600——token 即文件夹地址，按凭据对待）。 */
+export async function saveDriveCache(config, cache) {
+  const dir = storeDir(config);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const path = driveCachePath(config);
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tmp, JSON.stringify(cache, null, 2) + '\n', { mode: 0o600, flag: 'w' });
+  await rename(tmp, path);
+}
+
+/**
+ * 给飞书链接带上中文界面参数。飞书 Web 套件按 `locale` cookie 决定界面语言，
+ * 而 `?lang=…` 会被网关消费并改写该 cookie（实测 zh-CN/en-US 双向生效）；
+ * 桌面壳内嵌 webview 里这个 cookie 常是 en-US，界面就成了英文。iframe 跨域
+ * 改不了 cookie，只能在 URL 上带参数——链接经登录跳转也保留该参数。
+ */
+export function withChineseLocale(url) {
+  const raw = String(url || '').trim();
+  if (!raw) return raw;
+  try {
+    const parsed = new URL(raw);
+    if (!parsed.searchParams.has('lang')) parsed.searchParams.set('lang', 'zh-CN');
+    return parsed.toString();
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * 寻址服务。run(args, options) → { stdout } 为 lark-cli 执行器（注入以便
+ * 测试；生产侧绑定 proc.runCliTool('lark-cli', …)——PATH shim、桌面壳自带
+ * Node、超时与中文错误包装都在那一层）。
+ */
+export function createDriveService({ run }) {
+  const listFolder = async (folderToken, pageSize, pageToken = '') => {
+    const params = { page_size: pageSize };
+    if (folderToken) params.folder_token = folderToken;
+    if (pageToken) params.page_token = pageToken;
+    const { stdout } = await run([
+      'api', 'GET', '/open-apis/drive/v1/files',
+      '--params', JSON.stringify(params),
+      '--format', 'json',
+    ]);
+    return parseLarkJson(stdout);
+  };
+
+  const service = {
+    /** 根目录翻页找「AgentOne」文件夹；遍历完没找到返回 null。 */
+    async findAgentOneFolder(name = AGENTONE_FOLDER_NAME) {
+      let pageToken = '';
+      for (let page = 0; page < MAX_LIST_PAGES; page += 1) {
+        const data = await listFolder('', LIST_PAGE_SIZE, pageToken);
+        const hit = pickFolder(data.files, name);
+        if (hit) {
+          return { token: hit.token, url: hit.url || '', name: hit.name };
+        }
+        if (!data.has_more || !data.page_token) return null;
+        pageToken = data.page_token;
+      }
+      throw new Error(
+        `云盘根目录条目过多（超过 ${MAX_LIST_PAGES * LIST_PAGE_SIZE} 项），无法确认「${name}」文件夹是否存在，请先在飞书中整理根目录后再试`,
+      );
+    },
+
+    async createAgentOneFolder(name = AGENTONE_FOLDER_NAME) {
+      const { stdout } = await run([
+        'drive', '+create-folder', '--name', name, '--format', 'json',
+      ]);
+      const data = parseLarkJson(stdout);
+      const token = data.folder_token || data.token;
+      if (!token) throw new Error('创建文件夹失败：飞书未返回文件夹标识，请稍后重试');
+      return { token, url: data.url || '', name: data.name || name };
+    },
+
+    /** 校验 token 仍指向可列出的文件夹（列一页子项试探）。任何失败→false。 */
+    async folderUsable(token) {
+      try {
+        await listFolder(String(token || ''), 1);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    /**
+     * 文件夹首页清单指纹（token+modified_time+name 排序哈希，排序保证与
+     * 返回顺序无关）。给云盘页签做自动刷新：往子文件夹里增删文档会 bump 该
+     * 子文件夹在父清单中的 modified_time（2026-10-13 真机实测
+     * 1791876629 → 1791876675），因此**根清单指纹**即可覆盖一层深度的
+     * 变化——项目文件夹正是这一层。失败向上抛，由路由层兜底成 rev:null。
+     */
+    async fingerprintFolder(token) {
+      const data = await listFolder(String(token || ''), LIST_PAGE_SIZE);
+      const files = Array.isArray(data.files) ? data.files : [];
+      const canonical = files
+        .map((item) => `${item?.token || ''}:${item?.modified_time || ''}:${item?.name || ''}`)
+        .sort()
+        .join('|');
+      return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+    },
+
+    /**
+     * 收养用户指定的文件夹链接（…/drive/folder/…）：inspect 解出底层
+     * token（wiki 链也会解包），非文件夹/解不出即拒，再校验可访问。
+     */
+    async adoptFolder(url) {
+      const raw = String(url || '').trim();
+      if (!/^https?:\/\//.test(raw)) {
+        throw new Error('请粘贴完整的飞书文件夹链接（以 https:// 开头）');
+      }
+      const { stdout } = await run([
+        'drive', '+inspect', '--url', raw, '--format', 'json',
+      ]);
+      const data = parseLarkJson(stdout);
+      const token = data.obj_token || data.token;
+      const type = String(data.obj_type || data.type || '').toLowerCase();
+      if (!token || (type && type !== 'folder')) {
+        throw new Error('该链接不是有效的云盘文件夹链接，请使用「…/drive/folder/…」链接');
+      }
+      if (!(await service.folderUsable(token))) {
+        throw new Error('无法访问该文件夹：它可能已被删除，或你没有访问权限');
+      }
+      return { token, url: data.url || raw, name: data.title || data.name || '' };
+    },
+
+    /**
+     * 完整寻址。adoptUrl 优先（设置页「使用此文件夹」）；否则缓存有效→
+     * 缓存，force（设置页「重新定位」）跳过缓存；失效→按名找→找不到建。
+     * 结果落盘缓存。注意：创建只发生在本函数，且必然先有「按名找不到」。
+     */
+    async resolveAgentOneFolder({ config, force = false, adoptUrl = '' } = {}) {
+      if (adoptUrl) {
+        const adopted = await service.adoptFolder(adoptUrl);
+        await saveDriveCache(config, { agentone_folder: adopted });
+        return adopted;
+      }
+      const cache = await loadDriveCache(config);
+      const cached = cache?.agentone_folder;
+      if (!force && cached?.token && (await service.folderUsable(cached.token))) {
+        return cached;
+      }
+      const found = await service.findAgentOneFolder();
+      const folder = found || (await service.createAgentOneFolder());
+      await saveDriveCache(config, { agentone_folder: folder });
+      return folder;
+    },
+  };
+  return service;
+}