dsh-agentone 0.5.44 → 1.0.2

package/skills/agentone-drive/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: agentone-drive
+description: 使用飞书云盘的 AgentOne 文件夹：查看和读取里面的资料，或把飞书云文档（文档 / 表格 / 多维表格 / 幻灯片）保存进去并按「项目或应用」建子文件夹。当需要查共享资料、读取云盘文件夹内容，或把新做的/已有的飞书文档统一存进云盘时使用。
+version: 1.2.0
+---
+
+# AgentOne 云盘文件夹 / agentone-drive
+
+飞书云盘的 AgentOne 文件夹是本机用户与 AI 共享的工作目录：既能**查资料、取材料**，
+也能**把文档存进去**。文件夹由 dsh-agentone 插件维护（设置 → 云盘），本技能只按约定
+调用脚本，不自己拼 lark-cli 命令。
+
+## 说法（对用户）
+
+用「云盘里的资料」「存进云盘」「已经存好了」这类日常说法，不要用「归档」「归位」
+「落库」等用户可能看不懂的词。
+
+## 文件夹规则
+
+- 根文件夹：`{{DRIVE_CACHE}}` 里 `agentone_folder` 的 token（脚本自己读，不要手抄 token）。
+- 子文件夹：`<项目或应用>`（只有这一层，不按日期切分），保存时自动创建，查看时不创建。
+- 只管理云文档（docx / sheet / base / slides）；普通附件上传用 lark-cli 的
+  `drive +upload`，不要用本技能。
+
+## 一：查看/读取云盘里的资料
+
+```bash
+node "{{DRIVE_SCRIPT}}" list                      # 看根文件夹里有什么（各项目文件夹）
+node "{{DRIVE_SCRIPT}}" list --project "项目或应用" # 看某个项目文件夹里的文档
+```
+
+输出 `{ok:true, files:[{name,type,token,url}...], has_more}`。`has_more:true` 表示还有
+更多（一页 200 条），需要翻页时直接用 lark-cli 的 `api GET /open-apis/drive/v1/files`。
+拿到 token/url 后按类型读取：
+
+- 在线文档：`lark-cli docs +fetch --url <url>`
+- 表格 / 多维表格：`lark-cli` 的 sheets / base 命令
+- 普通文件：`lark-cli drive +download --file-token <token>`
+
+## 二：新建文档时直接存进项目文件夹
+
+先取子文件夹 token，再在创建时指定父文件夹，文档一步到位、无需二次移动：
+
+```bash
+FOLDER=$(node "{{DRIVE_SCRIPT}}" resolve-folder --project "项目或应用" --token-only)
+lark-cli docs +create --title "标题" --content @body.xml --parent-token "$FOLDER"
+```
+
+表格 / 多维表格 / 幻灯片：先用 `lark-cli drive +import --file x.xlsx --type sheet`
+生成云文档，再按下节存进去。
+
+## 三：把已经存在的文档存进去
+
+```bash
+node "{{DRIVE_SCRIPT}}" archive --token <文档 token 或链接> --type docx --project "项目或应用"
+```
+
+输出 JSON：`{ok:true, archived:true|false, folder_token, folder_url, path}`。
+`archived:false` 表示该文档已经在目标文件夹里（重复调用安全，不会重复移动）。
+
+## 约定
+
+- **把飞书链接给用户时，一律在链接后追加 `?lang=zh-CN`**（脚本输出的链接已自动带）。
+  原因：宿主的内嵌浏览器是独立登录会话，界面语言可能默认英文；`?lang=zh-CN` 会被
+  飞书改写成该会话的语言偏好。`docs +create` 等 lark-cli 命令返回的链接不带参数，要自己补。
+- `--project` 取当前任务所属的项目名或应用名；**同一个项目/应用固定用同一个名字**，
+  文档才会聚在同一个文件夹里。保存时拿不准就省略，脚本会放进「未分类」，不要自创层级。
+- 已经存进去的文档不要重复移动；同一次任务里只存一次。
+- 脚本返回 `{ok:false, error}` 时，把 `error` 原文（已是中文）告诉用户，不要重试
+  超过一次；提示里出现「请先在 dsh 设置 → 云盘 初始化文件夹」时，先请用户完成
+  初始化再继续。

package/skills/agentone-drive/scripts/drive.mjs

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+// AgentOne 云盘文件夹助手（随 dsh-agentone 的 agentone-drive 技能安装到本机技能目录）。
+//
+// 职责：这个文件夹是用户与 AI 共享的工作目录——
+//   list           查看里面有什么（只读，绝不创建）；
+//   resolve-folder 取「<项目或应用>」子文件夹 token（没有则创建）；
+//   archive        把一篇飞书云文档存进该子文件夹（已在则不动，重复调用安全）。
+// 目标文件夹来自插件维护的 drive.json（设置 → 云盘），本脚本不接收文件夹 token 参数。
+//
+// 输出契约：成功 → stdout JSON {ok:true,...} 退出码 0；失败 → stdout
+// {"ok":false,"error":"<中文>"} 退出码 1。--token-only 只打印 token，失败时
+// 改为 stderr + 退出码 1（避免把错误 JSON 当成 token 用进命令行）。
+// 飞书原始英文错误只进 stderr（日志侧），stdout 永远是中文。
+import { execFile } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+const DEFAULT_STORE_DIR = join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'agentone');
+const DEFAULT_CACHE = join(DEFAULT_STORE_DIR, 'drive.json');
+const LARK_BIN = process.platform === 'win32' ? 'lark-cli.cmd' : 'lark-cli';
+const LIST_PAGE_SIZE = 200;
+
+const USAGE = `用法：
+  node drive.mjs list [--project "项目或应用"] [--drive-cache <路径>]
+  node drive.mjs resolve-folder --project "项目或应用" [--token-only] [--drive-cache <路径>]
+  node drive.mjs archive --token <文档 token 或链接> [--type docx] [--project "项目或应用"]
+
+说明：AgentOne 云盘文件夹的查看与保存。list 只查看不创建；保存进
+「<项目或应用>」子文件夹（自动创建）。
+`;
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) { out._.push(token); continue; }
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) { out[key] = true; continue; }
+    out[key] = next;
+    i += 1;
+  }
+  return out;
+}
+
+function compareVersion(a, b) {
+  const left = a.split('.').map(Number);
+  const right = b.split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff) return diff;
+  }
+  return 0;
+}
+
+/** GUI 宿主 PATH 贫瘠（launchd 的 /usr/bin:/bin）时的兑底目录，口径同插件 proc.js。 */
+function fallbackDirs() {
+  const home = homedir();
+  const dirs = [];
+  try {
+    const versions = readdirSync(join(home, '.nvm/versions/node'))
+      .filter((v) => /^v?\d/.test(v))
+      .sort((a, b) => compareVersion(a.replace(/^v/, ''), b.replace(/^v/, '')));
+    if (versions.length) dirs.push(join(home, '.nvm/versions/node', versions[versions.length - 1], 'bin'));
+  } catch {
+    // 没有 nvm：走后面的通用目录
+  }
+  dirs.push(
+    join(home, '.local/bin'), '/opt/homebrew/bin', '/usr/local/bin',
+    join(home, 'Library', 'pnpm'), join(home, 'Library', 'pnpm', 'bin'), join(home, '.local', 'share', 'pnpm'),
+  );
+  return dirs;
+}
+
+function childEnv() {
+  const path = [...fallbackDirs(), process.env.PATH || ''].filter(Boolean).join(delimiter);
+  return { ...process.env, PATH: path };
+}
+
+function runLark(args) {
+  return new Promise((resolve, reject) => {
+    execFile(LARK_BIN, args, {
+      env: childEnv(), timeout: 120_000, maxBuffer: 16 * 1024 * 1024,
+      windowsHide: true, shell: process.platform === 'win32',
+    }, (error, stdout, stderr) => {
+      if (error?.code === 'ENOENT') {
+        reject(new Error('未找到 lark-cli，请先在 dsh 设置 → CLI 里安装并完成飞书授权'));
+        return;
+      }
+      resolve({ stdout: String(stdout || ''), stderr: String(stderr || ''), failed: Boolean(error) });
+    });
+  });
+}
+
+/** 缺权限/授权失效给出可自助的中文动作，其余只给中性提示（原文进 stderr）。 */
+function larkErrorText(error = {}) {
+  const missing = Array.isArray(error.missing_scopes) ? error.missing_scopes : [];
+  if (error.subtype === 'missing_scope' || error.code === 99991679 || missing.length) {
+    return '你的飞书授权里还没有云盘权限，请到 dsh 设置 → 云盘 点「重新授权」后重试';
+  }
+  if (error.type === 'authorization') {
+    return '飞书授权已失效，请到 dsh 设置 → 云盘 重新授权后重试';
+  }
+  return '飞书接口调用失败，请稍后重试';
+}
+
+/** lark-cli 的 {ok, data|error} 壳解析（口径同插件 lib/drive.js）。 */
+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) {
+      const error = data.error || {};
+      process.stderr.write(`[archive] lark error: ${JSON.stringify(error)}\n`);
+      throw new Error(larkErrorText(error));
+    }
+    return data.data ?? {};
+  }
+  return data ?? {};
+}
+
+async function larkJson(args) {
+  const { stdout, stderr, failed } = await runLark(args);
+  const text = stdout.trim();
+  if (!text) {
+    if (failed) {
+      const reason = stderr.trim().split('\n')[0] || '';
+      process.stderr.write(`[archive] lark failed: ${reason}\n`);
+      throw new Error('飞书命令执行失败，请稍后重试');
+    }
+    throw new Error('飞书命令没有返回内容，请稍后重试');
+  }
+  return parseLarkJson(text);
+}
+
+async function readRootFolder(cachePath) {
+  let data;
+  try {
+    data = JSON.parse(await readFile(cachePath, 'utf8'));
+  } catch {
+    throw new Error('还没有找到云盘文件夹，请先在 dsh 设置 → 云盘 点「初始化 / 重新定位」');
+  }
+  const folder = data?.agentone_folder;
+  if (!folder?.token) {
+    throw new Error('云盘文件夹记录里没有可用文件夹，请先在 dsh 设置 → 云盘 重新定位');
+  }
+  return { token: String(folder.token), url: String(folder.url || ''), name: String(folder.name || 'AgentOne') };
+}
+
+async function listFolder(folderToken) {
+  const data = await larkJson([
+    'api', 'GET', '/open-apis/drive/v1/files',
+    '--params', JSON.stringify({ folder_token: folderToken, page_size: LIST_PAGE_SIZE }),
+    '--format', 'json',
+  ]);
+  return data;
+}
+
+/**
+ * 给飞书链接带上中文界面参数。宿主的内嵌浏览器是按账号分区的独立会话
+ * （persist:dsh-platform-…），locale cookie 跟云盘页签不共用、可能是英文；
+ * `?lang=zh-CN` 会被飞书网关消费并改写该分区的 locale cookie（口径同
+ * lib/drive.js 的 withChineseLocale，脚本自包含故复制一份）。
+ */
+function withChineseLocale(raw) {
+  const url = String(raw || '').trim();
+  if (!url) return url;
+  try {
+    // 只探测、不重建：URL.toString() 会把路径里的非 ASCII 百分号编码，改变
+    // 返回给用户的链接字形；这里保持原样，仅在 hash 前追加参数。
+    const parsed = new URL(url);
+    if (parsed.searchParams.has('lang')) return url;
+    const hash = parsed.hash || '';
+    const base = hash ? url.slice(0, url.length - hash.length) : url;
+    return `${base}${parsed.search ? '&' : '?'}lang=zh-CN${hash}`;
+  } catch {
+    return url;
+  }
+}
+
+function folderUrl(root, token, raw) {
+  if (raw) return withChineseLocale(raw);
+  try {
+    return withChineseLocale(`${new URL(root.url).origin}/drive/folder/${token}`);
+  } catch {
+    return '';
+  }
+}
+
+/** 只查找不创建（读取路径专用）：返回 {token,url,name} 或 null。 */
+async function findFolder(parent, name) {
+  const listed = await listFolder(parent.token);
+  const hit = (Array.isArray(listed.files) ? listed.files : [])
+    .find((item) => item?.type === 'folder' && item?.name === name);
+  return hit ? { token: String(hit.token), url: folderUrl(parent, hit.token, hit.url), name } : null;
+}
+
+async function findOrCreateFolder(root, parent, name) {
+  const hit = await findFolder(parent, name);
+  if (hit) return hit;
+  const created = await larkJson([
+    'drive', '+create-folder', '--name', name, '--folder-token', parent.token, '--format', 'json',
+  ]);
+  const token = created.folder_token || created.token;
+  if (!token) throw new Error(`创建子文件夹「${name}」失败：飞书未返回文件夹标识，请稍后重试`);
+  return { token: String(token), url: folderUrl(root, token, created.url), name };
+}
+
+/** 子目录名净化：去掉路径分隔符与控制字符，避免在云盘里造出意外的层级。 */
+function sanitizeName(value) {
+  const cleaned = String(value || '')
+    .replace(/[\\/:*?"<>|\u0000-\u001f]/g, '-')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^[.\-\s]+/, '')
+    .slice(0, 40)
+    .trim();
+  return cleaned || '未分类';
+}
+
+async function resolveTarget(root, project) {
+  // 只按「项目/应用」分组一层：同一项目的产物聚在一个目录里，便于按项目找，
+  // 也不引入按时间切分的层级（用户明确要求不要日期层）。
+  const groupName = sanitizeName(project);
+  const group = await findOrCreateFolder(root, root, groupName);
+  return { ...group, path: `${root.name}/${groupName}` };
+}
+
+function report(root, target) {
+  // 输出的链接一律带 ?lang=zh-CN：AI 会把这些链接直接给用户，在宿主内嵌浏览器
+  // （独立会话）里打开时界面语言才不会被该分区的 locale cookie 重置成英文。
+  return {
+    folder_token: target.token,
+    folder_url: withChineseLocale(target.url),
+    path: target.path,
+    root_url: withChineseLocale(root.url),
+  };
+}
+
+async function resolveFolderCommand(args) {
+  const root = await readRootFolder(args['drive-cache'] || DEFAULT_CACHE);
+  const target = await resolveTarget(root, args.project);
+  if (args['token-only']) return { tokenOnly: target.token };
+  return { ok: true, ...report(root, target) };
+}
+
+async function archiveCommand(args) {
+  const root = await readRootFolder(args['drive-cache'] || DEFAULT_CACHE);
+  let fileToken = String(args.token || '').trim();
+  let fileType = String(args.type || '').trim().toLowerCase();
+  if (!fileToken || fileToken === 'true') throw new Error('缺少 --token（文档 token 或飞书链接）');
+  if (/^https?:\/\//i.test(fileToken)) {
+    const info = await larkJson(['drive', '+inspect', '--url', fileToken, '--format', 'json']);
+    fileToken = String(info.obj_token || info.token || '');
+    fileType = fileType || String(info.obj_type || info.type || '').toLowerCase();
+    if (!fileToken) throw new Error('无法从链接解析出文档标识，请改用文档 token 重试');
+  }
+  const target = await resolveTarget(root, args.project);
+  // 只翻第一页判断「是否已归档」：命中则不动（幂等）；漏判时移动到自己所在的
+  // 目录同样无副作用，不为此翻完整个目录。
+  const listed = await listFolder(target.token);
+  const archived = !(Array.isArray(listed.files) ? listed.files : []).some((item) => item?.token === fileToken);
+  if (archived) {
+    await larkJson([
+      'drive', '+move', '--file-token', fileToken, '--type', fileType || 'file',
+      '--folder-token', target.token, '--format', 'json',
+    ]);
+  }
+  return { ok: true, archived, ...report(root, target) };
+}
+
+/**
+ * 列出文件夹里的内容（读取路径，绝不创建）。不带 --project 列根文件夹；
+ * 带 --project 只列该子文件夹（不存在返回空列表，不新建）。
+ */
+async function listCommand(args) {
+  const root = await readRootFolder(args['drive-cache'] || DEFAULT_CACHE);
+  let folder = root;
+  let path = root.name;
+  if (args.project !== undefined) {
+    const groupName = sanitizeName(args.project);
+    const found = await findFolder(root, groupName);
+    if (!found) {
+      return { ok: true, folder_token: '', folder_url: '', path: `${root.name}/${groupName}`, files: [], has_more: false };
+    }
+    folder = { ...found, url: found.url || root.url };
+    path = `${root.name}/${groupName}`;
+  }
+  const listed = await listFolder(folder.token);
+  const files = (Array.isArray(listed.files) ? listed.files : []).map((item) => ({
+    name: item?.name || '',
+    type: item?.type || '',
+    token: item?.token || '',
+    url: withChineseLocale(item?.url),
+  }));
+  return {
+    ok: true, folder_token: folder.token, folder_url: withChineseLocale(folder.url), path,
+    files, has_more: Boolean(listed.has_more),
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+  if (!command || args.help) {
+    process.stdout.write(USAGE);
+    return null;
+  }
+  if (command === 'list') return listCommand(args);
+  if (command === 'resolve-folder') return resolveFolderCommand(args);
+  if (command === 'archive') return archiveCommand(args);
+  throw new Error(`未知子命令：${command}（可用：list、resolve-folder、archive）`);
+}
+
+main().then((result) => {
+  if (!result) return;
+  if (result.tokenOnly) {
+    process.stdout.write(`${result.tokenOnly}\n`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}).catch((error) => {
+  const message = error?.message || '保存失败，请稍后重试';
+  if (process.argv.includes('--token-only')) {
+    process.stderr.write(`保存失败：${message}\n`);
+  } else {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: message })}\n`);
+  }
+  process.exitCode = 1;
+});