dsh-agentone 1.0.0 → 1.0.3

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;
+}

package/lib/index.js

@@ -34,6 +34,10 @@ import { applyPlatformModel, removePlatformModel } from './model.js';
 import { installPlatformSkill, listPlatformSkills, removePlatformSkill } from './skill.js';
 import { applyPlatformSkillhub, removePlatformSkillhub } from './skillhub.js';
 import { createProfilePlugins, validatePackage, PROTECTED_PACKAGES } from './profile-plugins.js';
+import {
+  createDriveService, withChineseLocale, describeDrivePermission, parseLarkJson, loadDriveCache,
+} from './drive.js';
+import { loadArchivePref, setArchiveEnabled, syncArchiveFeature } from './archive.js';
 import { isDesktopHost } from './desktop.js';
 import { createDefaultsSync } from './defaults-sync.js';
 import { canonicalSkillSlug, localSkillState } from './skill-state.js';
@@ -691,6 +695,42 @@ export function apply(ctx, config) {
       `dsh-agentone: route ${path}`,
     );
 
+    // 飞书云盘寻址（/agentone/api/drive/*）共享的 lark-cli 门与服务实例。
+    // 门返回非 null 表示不可用（state 给前端渲染引导），为 null 才继续寻址。
+    // withLatest=false：门是热路径（tab 每次打开都过），不查 npm latest。
+    const driveGate = async () => {
+      const detail = await probeCliDetail('lark-cli', { withLatest: false })
+        .then(withCliUpgradeGuard).catch(() => null);
+      if (!detail || detail.state === 'missing') return { state: 'cli_missing' };
+      if (detail.unconfigured) return { state: 'cli_unconfigured' };
+      if (detail.state !== 'authorized') return { state: 'cli_unauthorized' };
+      return null;
+    };
+    const driveService = createDriveService({
+      run: (args, options) => runCliTool('lark-cli', args, options),
+    });
+
+    /**
+     * 「云盘没权限」的第四态：前三态只管装/配/授权，已授权但缺云盘 scope 时
+     * 寻址会抛 LarkError。这里把它映射成独立 state + 责任方（用户可自助重新
+     * 授权 / 只能管理员开通），而不是把 lark-cli 的英文原文当 502 丢给用户。
+     * 返回 null 表示不是权限问题（按普通失败处理）。
+     */
+    const drivePermissionState = async (error) => {
+      const mapped = await describeDrivePermission(error, {
+        // auth scopes：应用侧已开通的 scope 清单（输出无 ok 壳，parseLarkJson
+        // 会原样返回对象）；失败时 describeDrivePermission 按可自助处理。
+        runAppScopes: async () => {
+          const { stdout } = await runCliTool('lark-cli', ['auth', 'scopes', '--json']);
+          return parseLarkJson(stdout)?.userScopes || null;
+        },
+      });
+      if (mapped) {
+        log?.info?.(`[dsh-agentone] drive permission gap: ${mapped.state} (${mapped.missing_scopes.join(',') || 'unspecified'})`);
+      }
+      return mapped;
+    };
+
     register('/agentone/', (request, response) => {
       if (request.method !== 'GET') {
         response.writeHead(405, { allow: 'GET' });
@@ -1548,6 +1588,121 @@ export function apply(ctx, config) {
       }
     });
 
+    register('/agentone/api/drive/home', async (request, response) => {
+      if (request.method !== 'GET') {
+        response.writeHead(405, { allow: 'GET' });
+        response.end();
+        return;
+      }
+      try {
+        // lark-cli 三态门与 CLI 页同口径（missing / unconfigured / unauthorized），
+        // 前端按 state 渲染引导；寻址细节见 lib/drive.js 头注释。
+        const gate = await driveGate();
+        if (gate) {
+          sendJson(response, 200, gate);
+          return;
+        }
+        const folder = await driveService.resolveAgentOneFolder({ config });
+        // 带上中文界面参数：缓存里可能是修复前存的裸链接，统一在出口补
+        sendJson(response, 200, { state: 'ready', ...folder, url: withChineseLocale(folder.url) });
+      } catch (error) {
+        const permission = await drivePermissionState(error);
+        if (permission) {
+          sendJson(response, 200, permission);
+          return;
+        }
+        log?.warn?.(`[dsh-agentone] drive home failed: ${error?.message || error}`);
+        sendJson(response, 502, { error: '获取云盘文件夹失败，请稍后重试' });
+      }
+    });
+
+    register('/agentone/api/drive/home/resolve', async (request, response) => {
+      if (request.method !== 'POST') {
+        response.writeHead(405, { allow: 'POST' });
+        response.end();
+        return;
+      }
+      try {
+        const gate = await driveGate();
+        if (gate) {
+          sendJson(response, 200, gate);
+          return;
+        }
+        const body = await readJsonBody(request);
+        const adoptUrl = String(body.adopt_url || '').trim().slice(0, 1000);
+        const folder = await driveService.resolveAgentOneFolder({ config, force: true, adoptUrl });
+        sendJson(response, 200, { state: 'ready', ...folder, url: withChineseLocale(folder.url) });
+      } catch (error) {
+        const permission = await drivePermissionState(error);
+        if (permission) {
+          sendJson(response, 200, permission);
+          return;
+        }
+        log?.warn?.(`[dsh-agentone] drive resolve failed: ${error?.message || error}`);
+        sendJson(response, 502, { error: '定位云盘文件夹失败，请稍后重试' });
+      }
+    });
+
+    // 归档开关：AI 产出的飞书云文档是否自动归入云盘文件夹。
+    // 开 = 注入 AGENTS.md 指令块 + 安装归档技能；关 = 撤销两者。
+    register('/agentone/api/drive/archive', async (request, response) => {
+      if (request.method === 'GET') {
+        try {
+          const pref = await loadArchivePref(config);
+          sendJson(response, 200, { enabled: pref.enabled });
+        } catch (error) {
+          log?.warn?.(`[dsh-agentone] read archive pref failed: ${error?.message || error}`);
+          sendJson(response, 502, { error: '读取归档开关失败，请稍后重试' });
+        }
+        return;
+      }
+      if (request.method !== 'POST') {
+        response.writeHead(405, { allow: 'GET, POST' });
+        response.end();
+        return;
+      }
+      try {
+        const body = await readJsonBody(request);
+        const result = await setArchiveEnabled(config, body.enabled === true, log);
+        if (!result.ok) {
+          // 同名技能目录被用户占用：不改开关，明确告知处理方式
+          sendJson(response, 409, { error: result.error });
+          return;
+        }
+        sendJson(response, 200, { enabled: result.enabled });
+      } catch (error) {
+        log?.warn?.(`[dsh-agentone] set archive failed: ${error?.message || error}`);
+        sendJson(response, 502, { error: '设置归档开关失败，请稍后重试' });
+      }
+    });
+
+    // 云盘页签自动刷新：轮询根清单指纹（10s 节流缓存，多个客户端共享）。
+    // 指纹直接用 drive.json 缓存的 token，不做可用性探测（省一次 API 调用）；
+    // 缓存缺失 / lark-cli 不可用 / 任何失败都返回 rev:null，前端按「未知，不动」。
+    let driveRevCheckedAt = 0;
+    let driveRevValue = null;
+    register('/agentone/api/drive/rev', async (request, response) => {
+      if (request.method !== 'GET') {
+        response.writeHead(405, { allow: 'GET' });
+        response.end();
+        return;
+      }
+      try {
+        if (Date.now() - driveRevCheckedAt >= 10_000) {
+          driveRevCheckedAt = Date.now();
+          const cache = await loadDriveCache(config);
+          const token = cache?.agentone_folder?.token;
+          driveRevValue = token ? await driveService.fingerprintFolder(token) : null;
+        }
+        sendJson(response, 200, { rev: driveRevValue });
+      } catch (error) {
+        // 失败同样走 10s 节流（时间戳已前移），rev 归 null 让前端静默不动
+        driveRevValue = null;
+        log?.warn?.(`[dsh-agentone] drive rev failed: ${error?.message || error}`);
+        sendJson(response, 200, { rev: null });
+      }
+    });
+
     register('/agentone/api/plan', async (request, response) => {
       if (request.method !== 'GET') {
         response.writeHead(405, { allow: 'GET' });
@@ -1643,6 +1798,10 @@ export function apply(ctx, config) {
     ensureLanguageDefault(config, log).catch((error) => {
       log.warn(`[dsh-agentone] language default check failed: ${error?.message || error}`);
     });
+    // 云盘归档开关落盘在 storeDir：启动按开关收敛（用户改过 AGENTS.md / 技能目录也对齐）
+    syncArchiveFeature(config, log).catch((error) => {
+      log.warn(`[dsh-agentone] drive archive sync failed: ${error?.message || error}`);
+    });
     (async () => {
       // 托管实例先把 Hub 注入的凭据落盘，再走既有的「已登录」启动流程。
       await bootstrapInstanceCredentials(config, log).catch((error) => {