dsh-agentone 0.5.44 → 1.0.2

package/README.md

@@ -63,6 +63,29 @@ lark-cli / ccpg-cli 状态探测。
   每个会话基线加载，project 级指令优先）；幂等不重复注入，用户已有语言
   偏好或删除标记块后不再介入（本机只做一次决策，记录于
   `$DSH_HOME/agentone/language-default.json`）。
+- **飞书云盘资料夹（侧边栏 tab）**：注册 better-sidebar「飞书云盘」页签，
+  iframe 直嵌飞书网页版（飞书不设 frame-ancestors，spike 实测），页面交互
+  全部是飞书官方 Web UI。寻址（`lib/drive.js`）：打开时用 lark-cli 在
+  「我的空间」根目录找到（没有则创建）`AgentOne` 文件夹并缓存 token
+  （改名不影响、被删自动重建）；设置页「云盘」tab 支持初始化/重新定位/
+  粘贴链接收养其他文件夹（`POST /agentone/api/drive/home/resolve`）。
+  独立 dsh 未装 better-sidebar 时静默不注册该页签。
+  内容变化时自动刷新：服务端对根清单算指纹（`GET /agentone/api/drive/rev`，10s 节流），
+  页签 ready 后每 8s 轮询，指纹变了才重挂载 iframe。用户正在云盘里浏览时不硬刷新
+  （重载会回到根视图）：顶部弹蓝色横幅「云盘内容有更新 / 立即刷新」，右下角常驻
+  「刷新」胶囊同步变蓝；焦点离开云盘后下一拍自动应用。点胶囊/横幅立即刷新并重新寻址。
+- **启用云盘（默认启用）**：设置页「云盘」tab 的「启用云盘」开关。AgentOne 文件夹是
+  用户与 AI **共享的工作目录**——AI 可以读取使用里面的资料，也可以把飞书云文档存进去。
+  插件做两件事（`lib/archive.js`）：在 `$DSH_HOME/AGENTS.md` 注入受标记管理的指令块
+  （每会话基线加载，**只告知能力**——可以查/存、在哪查/存；目标指向 `drive.json` 而
+  不写 token），并把技能装到 `$DSH_HOME/skills/agentone-drive/`
+  （`SKILL.md` + `scripts/drive.mjs`：`list` 查看内容（只读不创建）、按「项目或应用」
+  查找或创建子文件夹、重复保存同一文档不重复移动、缺权限时给中文自助指引）。
+  默认启用，只有用户明确停用过才关闭（落盘 `enabled:false`）；停用时撤销指令块与
+  技能目录。同名技能目录不是本插件创建时拒绝覆盖，开关状态也不改动；历史版本的
+  `agentone-drive-archive` 目录带归属标记时升级自动清理。
+  **不承诺「自动保存」**——插件做不到替模型执行，是否读/存由模型按任务判断；
+  用户可见文案统一用「可以读取 / 可以存进」，不用「自动保存」「归档」等说法。
 - **首启引导**：dsh 首次启动弹出平台登录引导（order -50，早于官方
   「添加 API Key」），登录一次即跳过官方密钥引导；暗色主题适配。
 

package/lib/archive.js

@@ -0,0 +1,322 @@
+// 「启用云盘」：把飞书云盘的 AgentOne 文件夹变成用户与 AI 共享的工作目录
+// （设置页「云盘」开关，默认启用）。AI 可以**读取使用**里面的资料，也可以把
+// 飞书云文档存进去。
+//
+// 措辞红线（产品决策）：不存在「AI 自动保存」——插件做不到替模型执行保存；全局
+// 指令只**告知能力**（可以读、可以存）与入口，是否执行由模型在任务中判断。
+// 所以用户可见文案一律用「可以读取 / 可以存进」，不用「自动保存/自动归档」。
+//
+// 分两个半区配合，缺一不可：
+//   A. 能力告知 —— 在 $DSH_HOME/AGENTS.md 注入受标记管理的指令块（dsh 官方
+//      agent-instructions 机制每会话基线加载），告诉模型「可以查/存、在哪查/存」。
+//      块里只写「目标由 drive.json 决定」，不写 token —— 用户重新定位/收养
+//      文件夹后不必重写指令。
+//   B. 操作手册 —— 把技能（SKILL.md + scripts/drive.mjs）装到
+//      $DSH_HOME/skills/agentone-drive/，承载具体命令（列目录/读取/保存）、
+//      子文件夹规则与重复保存的判断；指令块只指路，细节按需加载。
+//
+// 开关默认**启用**：这是产品默认行为，普通用户不必先找到并看懂开关。只有用户
+// 明确停用过才关闭（落盘 enabled:false）；启用 → 注入指令 + 装技能；停用 → 撤销两者。
+// 同名技能目录不是本插件创建时（foreign）拒绝安装，绝不覆盖用户文件；
+// 历史版本装过的旧技能目录（agentone-drive-archive）带归属标记时顺带清理。
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { driveCachePath } from './drive.js';
+import { resolveDshHome, storeDir } from './store.js';
+
+export const ARCHIVE_MARKER_BEGIN = '<!-- dsh-agentone:drive-archive begin -->';
+export const ARCHIVE_MARKER_END = '<!-- dsh-agentone:drive-archive end -->';
+export const ARCHIVE_SKILL_SLUG = 'agentone-drive';
+export const ARCHIVE_SKILL_VERSION = '1.2.0';
+/** 历史版本用过的技能目录名：升级时带归属标记的顺带清理，避免技能列表出现新旧两份。 */
+export const LEGACY_SKILL_SLUGS = ['agentone-drive-archive'];
+const PREF_FILE = 'archive.json';
+/** 技能目录归属标记：只有带这个文件的同名目录才允许被本插件改写/删除。 */
+const MANAGED_FILE = '.agentone-managed.json';
+const SKILL_SOURCE_DIR = new URL('../skills/agentone-drive/', import.meta.url);
+
+function prefPath(config) {
+  return join(storeDir(config), PREF_FILE);
+}
+
+async function statOrNull(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function readTextOrNull(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function writeFileAtomic(path, text, { mode = 0o644, dirMode = 0o755 } = {}) {
+  await mkdir(dirname(path), { recursive: true, mode: dirMode });
+  // 随机后缀：同毫秒内两次写同一路径时 tmp 名不撞（互斥链之外的兜底）
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  await writeFile(tmp, text, { mode, flag: 'w' });
+  await rename(tmp, path);
+}
+
+/**
+ * 归档写入互斥链：启动收敛（syncArchiveFeature）与设置页切换（setArchiveEnabled）
+ * 可能并发，两边都会写 AGENTS.md 与技能文件；不串行化会出现同名 tmp 互撞
+ * （rename ENOENT）和「一半新一半旧」的中间态。与 store.js 的凭据写链同思路。
+ */
+let archiveWriteChain = Promise.resolve();
+function serialized(operation) {
+  const next = archiveWriteChain.then(operation, operation);
+  archiveWriteChain = next.catch(() => {});
+  return next;
+}
+
+/** 读「启用云盘」开关。默认**启用**（普通用户不必先找到并看懂开关）；只有明确
+ *  停用过（落盘 `enabled: false`）才关闭，文件缺失/损坏都按默认启用处理。 */
+export async function loadArchivePref(config) {
+  try {
+    const data = JSON.parse(await readFile(prefPath(config), 'utf8'));
+    return { enabled: data?.enabled !== false, updated_at: data?.updated_at || null };
+  } catch {
+    return { enabled: true, updated_at: null };
+  }
+}
+
+export function saveArchivePref(config, { enabled }) {
+  const body = {
+    schema_version: 1,
+    enabled: enabled === true,
+    updated_at: new Date().toISOString(),
+  };
+  return writeFileAtomic(prefPath(config), `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+}
+
+/**
+ * 归档功能的作用域根：显式 dshHome（多 profile / 测试）优先，否则 $DSH_HOME。
+ * 指令块与技能都必须落在 dsh 真正加载指令/技能的那棵树里；显式传入是为了让
+ * storeDir 被改写的调用方（含测试）不会误改真实用户目录。
+ */
+function archiveHome(config) {
+  return config?.dshHome || resolveDshHome();
+}
+
+/**
+ * 作用域一致性守卫：开关/缓存落在 storeDir，指令块/技能落在 dsh 主目录——两者
+ * 必须是同一棵树（storeDir = <dshHome>/agentone）。调用方只隔离 storeDir 而不改
+ * dshHome（测试与隔离环境就是这样）时，按全局开关去写真实主目录只会污染用户
+ * 文件（事故：默认启用后，某测试进程把真实 ~/.dsh/AGENTS.md 的指令块写成了
+ * 临时目录里的 drive.json 路径）。此类跨树写入一律拒绝。
+ */
+function scopeConsistent(config) {
+  return resolve(storeDir(config)) === resolve(join(archiveHome(config), 'agentone'));
+}
+
+/**
+ * 在进入异步链**之前**同步冻结作用域（dshHome + storeDir 都落成显式值）。
+ * 链体可能在调用方还原 DSH_HOME 之后才执行（fire-and-forget 启动收敛正如此）；
+ * 若链内再解析 env，就会出现「守卫按临时目录放行、写入按真实目录落盘」的撕裂
+ * ——第二次事故正是这样把真实 AGENTS.md 写成了另一个临时路径。冻结后守卫与
+ * 写入看到的是同一组确定性路径。
+ */
+function freezeScope(config) {
+  return { ...config, dshHome: archiveHome(config), storeDir: storeDir(config) };
+}
+
+/** 云盘技能的本机目录（与平台技能同一 skills 根，dsh 会话据此加载技能）。 */
+export function archiveSkillDir(config) {
+  return join(archiveHome(config), 'skills', ARCHIVE_SKILL_SLUG);
+}
+
+/**
+ * AGENTS.md 里的「启用云盘」规则块（只指路，不写 token）。
+ * 注意措辞口径（产品决策）：不写「自动保存」这类承诺——插件做不到替模型执行；
+ * 指令只**告知能力**（可以读、可以存）与入口，是否执行由模型在任务中判断。
+ */
+export function archiveInstructionBlock({ driveCachePath: cachePath }) {
+  return [
+    ARCHIVE_MARKER_BEGIN,
+    '- 云盘（dsh-agentone 已启用）：飞书云盘的 AgentOne 文件夹是本机与 AI 共享的工作目录，',
+    '  你可以读取使用里面的资料，也可以把飞书云文档（文档 / 表格 / 多维表格 / 幻灯片）',
+    '  存进去，子文件夹按「项目或应用」自动创建。',
+    '- 需要参考资料、或用户提到云盘里的资料时，可用 agentone-drive 技能查看与读取；',
+    '  交付文档或用户要求保存/整理文档时，可用它存进对应的项目文件夹。',
+    `- 文件夹地址以 \`${cachePath}\` 的 \`agentone_folder\` 为准；读不到就先让用户在`,
+    '  「设置 → 云盘」点「初始化 / 重新定位」。命令与重复保存的判断见 agentone-drive 技能。',
+    '- 到「设置 → 云盘」停用开关即可取消。',
+    ARCHIVE_MARKER_END,
+  ].join('\n');
+}
+
+/**
+ * 按开关同步 AGENTS.md 指令块。永不触碰标记块以外的内容；标记块残缺（只有
+ * 头或只有尾）时宁可不动，避免把用户文件截断。
+ */
+export async function applyArchiveInstructions({ agentsPath, cachePath, enabled, log = console }) {
+  const content = (await readTextOrNull(agentsPath)) ?? '';
+  const begin = content.indexOf(ARCHIVE_MARKER_BEGIN);
+  const end = content.indexOf(ARCHIVE_MARKER_END);
+  const hasBegin = begin >= 0;
+  const hasEnd = end >= 0;
+  if (hasBegin !== hasEnd || (hasBegin && end < begin)) {
+    log.warn?.(`[dsh-agentone] ${agentsPath} 的归档指令标记不完整，已跳过（请手动清理该块）`);
+    return 'malformed';
+  }
+  if (!enabled) {
+    if (!hasBegin) return 'absent';
+    const stripped = content.slice(0, begin) + content.slice(end + ARCHIVE_MARKER_END.length);
+    const next = stripped.replace(/\n{3,}/g, '\n\n').replace(/^\s*\n/, '').replace(/\s+$/, '');
+    await writeFileAtomic(agentsPath, next ? `${next}\n` : '');
+    return 'removed';
+  }
+  const block = archiveInstructionBlock({ driveCachePath: cachePath });
+  if (hasBegin) {
+    const current = content.slice(begin, end + ARCHIVE_MARKER_END.length);
+    if (current === block) return 'present';
+    await writeFileAtomic(agentsPath, content.slice(0, begin) + block + content.slice(end + ARCHIVE_MARKER_END.length));
+    return 'updated';
+  }
+  const next = content.trim() ? `${content.replace(/\s+$/, '')}\n\n${block}\n` : `${block}\n`;
+  await writeFileAtomic(agentsPath, next);
+  return 'applied';
+}
+
+/**
+ * 安装/更新云盘技能。返回 'installed' | 'current' | 'foreign'。
+ * 'foreign' = 同名目录存在但不是本插件创建的（用户自己的技能），拒绝覆盖。
+ */
+export async function installArchiveSkill(config, log = console) {
+  const dir = archiveSkillDir(config);
+  const existing = await statOrNull(dir);
+  if (existing && (!existing.isDirectory() || existing.isSymbolicLink())) {
+    log.warn?.(`[dsh-agentone] 技能路径 ${dir} 不是普通目录，跳过云盘技能安装`);
+    return 'foreign';
+  }
+  if (existing && !(await statOrNull(join(dir, MANAGED_FILE)))) {
+    log.warn?.(`[dsh-agentone] 技能目录 ${dir} 不是本插件创建的，跳过云盘技能安装`);
+    return 'foreign';
+  }
+  const template = await readFile(new URL('SKILL.md', SKILL_SOURCE_DIR), 'utf8');
+  const script = await readFile(new URL('scripts/drive.mjs', SKILL_SOURCE_DIR), 'utf8');
+  const rendered = template
+    .replaceAll('{{DRIVE_SCRIPT}}', join(dir, 'scripts', 'drive.mjs'))
+    .replaceAll('{{DRIVE_CACHE}}', driveCachePath(config));
+  const files = [
+    ['SKILL.md', rendered, 0o644],
+    [join('scripts', 'drive.mjs'), script, 0o644],
+    [MANAGED_FILE, `${JSON.stringify({
+      schema_version: 1, managed_by: 'dsh-agentone', slug: ARCHIVE_SKILL_SLUG, version: ARCHIVE_SKILL_VERSION,
+    }, null, 2)}\n`, 0o600],
+  ];
+  let changed = false;
+  for (const [relative, text, mode] of files) {
+    const path = join(dir, relative);
+    if ((await readTextOrNull(path)) === text) continue;
+    await writeFileAtomic(path, text, { mode });
+    changed = true;
+  }
+  return changed ? 'installed' : 'current';
+}
+
+/** 删除一个「本插件创建的」技能目录（带归属标记才删）。返回 'removed' | 'absent' | 'foreign'。 */
+async function removeManagedSkillDir(dir, log) {
+  const existing = await statOrNull(dir);
+  if (!existing) return 'absent';
+  if (!existing.isDirectory() || existing.isSymbolicLink() || !(await statOrNull(join(dir, MANAGED_FILE)))) {
+    log.warn?.(`[dsh-agentone] 技能目录 ${dir} 不是本插件创建的，跳过云盘技能卸载`);
+    return 'foreign';
+  }
+  await rm(dir, { recursive: true, force: true });
+  return 'removed';
+}
+
+/** 卸载云盘技能。返回 'removed' | 'absent' | 'foreign'（非本插件目录不动）。 */
+export function removeArchiveSkill(config, log = console) {
+  return removeManagedSkillDir(archiveSkillDir(config), log);
+}
+
+/** 清理历史版本的旧技能目录（agentone-drive-archive 等）：只删带归属标记的。 */
+export async function removeLegacyArchiveSkills(config, log = console) {
+  const results = [];
+  for (const slug of LEGACY_SKILL_SLUGS) {
+    results.push(await removeManagedSkillDir(join(archiveHome(config), 'skills', slug), log));
+  }
+  return results;
+}
+
+function agentsPath(config) {
+  return join(archiveHome(config), 'AGENTS.md');
+}
+
+/**
+ * 切换「启用云盘」开关（设置页）。启用时先装技能再写指令——技能装不上（foreign）
+ * 就不改开关、不写指令，避免留下「指令让 AI 用不存在的技能」的半截状态。
+ */
+export function setArchiveEnabled(config, enabled, log = console) {
+  const scoped = freezeScope(config);
+  return serialized(async () => {
+    // 跨树写入守卫：storeDir 与 dsh 主目录不一致（隔离环境/测试）时拒绝，见 scopeConsistent 注释
+    if (!scopeConsistent(scoped)) {
+      log.warn?.('[dsh-agentone] 存储目录与 dsh 主目录不在同一棵树，跳过「启用云盘」开关写入');
+      return { ok: false, error: '存储目录与 dsh 主目录不一致，已跳过「启用云盘」的写入；请检查插件配置' };
+    }
+    const cachePath = driveCachePath(scoped);
+    if (enabled) {
+      const skill = await installArchiveSkill(scoped, log);
+      if (skill === 'foreign') {
+        return { ok: false, error: '本机技能目录里已存在同名技能「agentone-drive」，'
+          + '且不是本插件创建的，无法自动替换；请先移除或改名后重试' };
+      }
+      await saveArchivePref(scoped, { enabled: true });
+      await removeLegacyArchiveSkills(scoped, log).catch(() => {});
+      const instructions = await applyArchiveInstructions({
+        agentsPath: agentsPath(scoped), cachePath, enabled: true, log,
+      });
+      log.info?.(`[dsh-agentone] 已启用云盘（技能 ${skill}，指令 ${instructions}）`);
+      return { ok: true, enabled: true, skill, instructions };
+    }
+    await saveArchivePref(scoped, { enabled: false });
+    const skill = await removeArchiveSkill(scoped, log);
+    await removeLegacyArchiveSkills(scoped, log).catch(() => {});
+    const instructions = await applyArchiveInstructions({
+      agentsPath: agentsPath(scoped), cachePath, enabled: false, log,
+    });
+    log.info?.(`[dsh-agentone] 已停用云盘（技能 ${skill}，指令 ${instructions}）`);
+    return { ok: true, enabled: false, skill, instructions };
+  });
+}
+
+/** 启动时按落盘开关收敛状态（用户在别处改过 AGENTS.md / 技能目录也能对齐）。 */
+export function syncArchiveFeature(config, log = console) {
+  const scoped = freezeScope(config);
+  return serialized(async () => {
+    // 跨树写入守卫：隔离环境（storeDir 单独指定、dshHome 是真实主目录）不得写真实
+    // 用户的 AGENTS.md / skills；生产配置两者天然同树，不受影响。
+    if (!scopeConsistent(scoped)) {
+      log.warn?.('[dsh-agentone] 存储目录与 dsh 主目录不在同一棵树，跳过云盘开关收敛');
+      return { enabled: false, skill: 'scope_mismatch', instructions: 'scope_mismatch' };
+    }
+    const pref = await loadArchivePref(scoped);
+    // 旧版本装过的技能目录（agentone-drive-archive）一律清理，避免新旧两份并存
+    await removeLegacyArchiveSkills(scoped, log).catch(() => {});
+    if (!pref.enabled) {
+      const skill = await removeArchiveSkill(scoped, log);
+      const instructions = await applyArchiveInstructions({
+        agentsPath: agentsPath(scoped), cachePath: driveCachePath(scoped), enabled: false, log,
+      });
+      return { enabled: false, skill, instructions };
+    }
+    const skill = await installArchiveSkill(scoped, log);
+    if (skill === 'foreign') return { enabled: true, skill, instructions: 'skill_conflict' };
+    const instructions = await applyArchiveInstructions({
+      agentsPath: agentsPath(scoped), cachePath: driveCachePath(scoped), enabled: true, log,
+    });
+    return { enabled: true, skill, instructions };
+  });
+}