llm-api-gateway-cli 1.0.0

package/public/task-slash.js

@@ -0,0 +1,493 @@
+/**
+ * 任务页的斜杠指令（E 组：计划与审批 / 模型与请求参数 / 会话与用量 / 工作目录 / 手册）
+ *
+ * 与另外两端的口径对齐（见网关仓库 docs/SLASH-CLI-ALIGNMENT-20260916.md）：
+ *  · 字段名与网关 `js/slash.js`、CLI `lib/commands.js` 同一套：name / aliases / args /
+ *    needsArgs / group / capability / surfaces / help / examples / run；
+ *  · `capability`（能不能跑：local / api / fs）与 `surfaces`（在哪一端有意义）正交，
+ *    本文件里的指令 surfaces 一律 ['hub'] —— 它们依赖"有工作目录 + 有待审批的挂起运行"，
+ *    这两样只有任务页有：网关对话页没有工作目录，CLI REPL 的审批是同步 y/N；
+ *  · 输出一律纯文本（`print` 走 textContent），不做 Markdown 渲染：文件名等来自文件系统，
+ *    不该有机会变成 HTML；帮助表格因此排成对齐的列，而不是 Markdown 表格。
+ *
+ * 端内差异（与网关对话页的 R2 不同）：
+ *   未知的 `/xxx` **不会被当成普通消息发给模型**，而是提示"任务页没有这条指令，要当文本发就写 //xxx"。
+ *   理由：在任务页把 `/clear` 当任务描述发给编码 Agent 几乎不可能是本意；而 REPL 也是这个口径，
+ *   两端的 CLI 家族先保持一致。想原样发给模型，写 `//clear`。
+ *
+ * 另一个端内差异：`suggest('')` 这里返回**全部指令**（任务页有候选面板，敲一个 `/` 就该看见有哪些），
+ * 而 CLI 的 `lib/commands.js:suggest('')` 返回空（REPL 没有面板，敲 `/` 就糊一屏候选是噪音）。
+ * 同名的 `suggest()` 在两端的"输入体验"上不同，是**有意的**；表本身仍然只有一份。
+ *
+ * 指令表是手册页（/manual）与服务端 `/api/commands` 的**唯一出处**：`commandRows()` 输出的字段
+ * 与 `lib/commands.js:commandRows()` 对齐，手册页因此不会各抄一份清单（抄的那份一定会漂）。
+ *
+ * 这个文件不碰 DOM（只管"该做什么"），DOM 与事件留给 task.js：这样才能在 node 里直接测。
+ */
+(function (root, factory) {
+  root.TaskSlash = factory();
+})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  const CAPABILITIES = ['local', 'api', 'fs'];
+  const SURFACES = ['web', 'cli', 'hub'];
+
+  /** 按空白切分，支持双引号包住带空格的参数；引号未闭合 → 抛错（调用方转成指令错误） */
+  function tokenize(s) {
+    const out = [];
+    const raw = String(s == null ? '' : s);
+    let i = 0;
+    while (i < raw.length) {
+      while (i < raw.length && /\s/.test(raw[i])) i++;
+      if (i >= raw.length) break;
+      if (raw[i] === '"') {
+        const end = raw.indexOf('"', i + 1);
+        if (end < 0) throw new Error('引号没有闭合（带空格的参数用 " 包起来）');
+        out.push(raw.slice(i + 1, end));
+        i = end + 1;
+      } else {
+        let j = i;
+        while (j < raw.length && !/\s/.test(raw[j])) j++;
+        out.push(raw.slice(i, j));
+        i = j;
+      }
+    }
+    return out;
+  }
+
+  const usageLine = (c) => '/' + c.name + (c.args && c.args !== '—' ? ' ' + c.args : '');
+
+  /* ============================ 指令表 ============================ */
+
+  const COMMANDS = [
+    {
+      name: 'help',
+      aliases: ['?', 'h'],
+      args: '[指令名]',
+      group: '帮助',
+      capability: 'local',
+      surfaces: ['hub'],
+      help: '显示这份清单，或某条指令的用法',
+      examples: ['/help', '/help init'],
+      run: (ctx, argv) => helpText(argv[0], { surface: 'hub', hasFileSystem: ctx.hasFileSystem() }),
+    },
+    {
+      name: 'plan',
+      aliases: ['p'],
+      args: '[任务描述]',
+      group: '计划与审批',
+      capability: 'local',
+      surfaces: ['hub'],
+      help: '切到计划模式（模型只有只读工具，先出计划、不动文件）；带描述则立即按计划模式跑一轮',
+      examples: ['/plan', '/plan 先看下项目结构再给我改造方案'],
+      run: async (ctx, argv) => {
+        if (ctx.busy()) return '正在跑这一轮，先等它结束（或点「停止」）—— 切模式对已经在跑的这轮无效。';
+        ctx.setMode('plan');
+        const task = argv.join(' ').trim();
+        if (!task) return '已切到计划模式：这一轮模型只能读、不能写。看完计划后点「按计划开始执行」再动手。';
+        // 不 await：这一轮可能跑好几分钟，回执先给出来
+        ctx.send(task).catch(() => {});
+        return '已按计划模式开始这一轮（只读工具，不会改文件）。';
+      },
+    },
+    {
+      name: 'approve',
+      aliases: ['ok'],
+      args: '—',
+      group: '计划与审批',
+      capability: 'local',
+      surfaces: ['hub'],
+      help: '批准当前挂起的写入（等同卡片上的「批准」按钮）',
+      examples: ['/approve'],
+      run: async (ctx) => {
+        if (ctx.busy()) return '正在跑这一轮，等它停下来再批准（或者点「停止」）。';
+        if (!ctx.pending()) return '当前没有待批准的写入。';
+        ctx.decide(true).catch(() => {});
+        return '已批准，继续跑。';
+      },
+    },
+    {
+      name: 'reject',
+      aliases: ['no'],
+      args: '—',
+      group: '计划与审批',
+      capability: 'local',
+      surfaces: ['hub'],
+      help: '拒绝当前挂起的写入（等同卡片上的「拒绝」按钮）',
+      examples: ['/reject'],
+      run: async (ctx) => {
+        if (ctx.busy()) return '正在跑这一轮，等它停下来再拒绝（或者点「停止」）。';
+        if (!ctx.pending()) return '当前没有待批准的写入。';
+        ctx.decide(false).catch(() => {});
+        return '已拒绝这次写入。';
+      },
+    },
+    {
+      name: 'mode',
+      aliases: [],
+      args: '[manual|auto|plan]',
+      group: '计划与审批',
+      capability: 'local',
+      surfaces: ['hub'],
+      help: '查看或切换审批模式（手动 / 自动 / 计划）—— 与页面上的模式按钮同一实现',
+      examples: ['/mode', '/mode auto'],
+      run: (ctx, argv) => {
+        const want = String(argv[0] || '').toLowerCase();
+        if (!want) return '当前模式：' + ctx.mode() + '\n用法：/mode manual|auto|plan（切模式不影响已经在跑的这一轮）';
+        return '已切到' + ctx.setMode(want) + '模式。';
+      },
+    },
+    {
+      name: 'model',
+      aliases: [],
+      args: '[模型名]',
+      group: '模型与请求参数',
+      capability: 'fs',            // 写进磁盘上的配置文件（PUT /api/settings）
+      surfaces: ['hub'],
+      help: '查看可选模型或切换当前模型（只能从网关 /v1/models 拉到的列表里选，与设置面板同一项）',
+      examples: ['/model', '/model deepseek-v4-pro'],
+      run: async (ctx, argv) => {
+        const want = argv.join(' ').trim();
+        const list = typeof ctx.models === 'function' ? ctx.models() : [];
+        if (!want) {
+          return [
+            '当前模型：' + (ctx.model() || '（未指定，用服务端默认）'),
+            list.length
+              ? '可选（来自网关 /v1/models，只能选、不能填）：\n' + list.map((m) => '  ' + m).join('\n')
+              : '还没拿到模型列表：先在设置面板点「刷新模型」。',
+            '用法：/model <模型名>（与设置面板里的「模型」同一项）',
+          ].join('\n');
+        }
+        // 与设置面板同一口径：只认列表里的名字（当前值例外 —— 它可能是继承下来的旧配置）
+        const hit = list.find((m) => String(m).toLowerCase() === want.toLowerCase()) || null;
+        const isCurrent = String(ctx.model() || '').toLowerCase() === want.toLowerCase();
+        if (!hit && !isCurrent) {
+          if (!list.length) throw new Error('没有拿到模型列表，不能手填模型名；先在设置面板点「刷新模型」');
+          throw new Error('模型不在网关返回的列表里：' + want + '\n可选：' + list.join(' / '));
+        }
+        const next = hit || want;
+        await ctx.setModel(next);
+        return '模型已切换为 ' + next + '（设置已存盘，下一步生效）。';
+      },
+    },
+    {
+      name: 'cost',
+      aliases: [],
+      args: '—',
+      group: '会话与用量',
+      capability: 'api',           // 单价口径在服务端（GET /api/cost → lib/pricing.js）
+      surfaces: ['hub'],
+      help: '查看这条任务累计 token 与费用粗估（口径与 CLI 的 /cost 同一份单价表）',
+      examples: ['/cost'],
+      run: async (ctx) => ctx.cost(),
+    },
+    {
+      name: 'resume',
+      aliases: [],
+      args: '[任务id]',
+      group: '会话与用量',
+      capability: 'fs',            // 任务记录在磁盘上（/api/tasks）
+      surfaces: ['hub'],
+      help: '切到另一条已保存的任务（不带参数列出最近任务）—— 等同于点侧边栏',
+      examples: ['/resume', '/resume 5f2c1a9e-...'],
+      run: async (ctx, argv) => {
+        const id = String(argv[0] || '').trim();
+        const list = ctx.tasks();
+        if (!id) {
+          if (!list.length) return '还没有已保存的任务（侧边栏「＋ 新任务」可以开一条）。';
+          const rows = list.slice(0, 10).map((t) =>
+            '  ' + t.id + '  ' + (t.title || '新任务') + '  ' + (t.workDir || '—') + '  ' + fmtTime(t.updatedAt));
+          return '最近的任务：\n' + rows.join('\n') + '\n用 /resume <任务id> 切过去（也可以直接点侧边栏）。';
+        }
+        const t = list.find((x) => x.id === id);
+        if (!t) return '找不到任务 ' + id + '（用 /resume 不带参数列出最近的任务）。';
+        await ctx.switchTask(id);
+        return '已切换到「' + (t.title || '新任务') + '」。';
+      },
+    },
+    {
+      name: 'stop',
+      aliases: [],
+      args: '—',
+      group: '会话与用量',
+      capability: 'local',
+      surfaces: ['hub'],
+      help: '停止正在跑的这一轮（等同页面上的「停止」按钮；后台其它任务不受影响）',
+      examples: ['/stop'],
+      run: (ctx) => {
+        if (!ctx.busy()) return '当前没有在跑的这一轮（停止只作用于这条任务正在跑的那一轮）。';
+        ctx.stop();
+        return '已请求停止这一轮（后台其它任务不受影响）。';
+      },
+    },
+    {
+      name: 'files',
+      aliases: ['ls'],
+      args: '[子路径]',
+      group: '工作目录',
+      capability: 'fs',
+      surfaces: ['hub'],
+      help: '列出工作目录（或其中某个子目录）里的文件',
+      examples: ['/files', '/files src'],
+      run: async (ctx, argv) => {
+        const r = await ctx.listFiles(argv[0] || '');
+        return r;
+      },
+    },
+    {
+      name: 'cwd',
+      aliases: ['pwd'],
+      args: '[路径]',
+      group: '工作目录',
+      capability: 'fs',
+      surfaces: ['hub'],
+      help: '查看当前工作目录；带路径则校验后切换过去',
+      examples: ['/cwd', '/cwd D:\\proj\\demo'],
+      run: async (ctx, argv) => {
+        const target = argv.join(' ').trim();
+        if (!target) return '当前工作目录：' + (ctx.workDir() || '（未选择）');
+        const abs = await ctx.switchDir(target);
+        return '已切换工作目录：' + abs;
+      },
+    },
+    {
+      name: 'init',
+      aliases: [],
+      args: '[--force]',
+      group: '工作目录',
+      capability: 'fs',
+      surfaces: ['hub'],
+      help: '在工作目录里生成 AGENTS.md（项目约定骨架）；已存在时不覆盖，除非加 --force',
+      examples: ['/init', '/init --force'],
+      run: async (ctx, argv) => {
+        const r = await ctx.init(argv.indexOf('--force') >= 0);
+        if (!r.written) return `已经有 ${r.rel} 了，没有动它（要重写骨架就 /init --force）。用 /instructions 看现在的内容。`;
+        return `${r.existed ? '已重新生成' : '已生成'} ${r.rel}（${r.bytes} 字节）。把「怎么跑测试」这类规矩补进去，模型下次开工就会先读它。`;
+      },
+    },
+    {
+      name: 'instructions',
+      aliases: ['memory'],
+      args: '—',
+      group: '工作目录',
+      capability: 'fs',
+      surfaces: ['hub'],
+      help: '显示这个工作目录注入给模型的项目记忆（AGENTS.md / CLAUDE.md）',
+      examples: ['/instructions'],
+      run: async (ctx) => ctx.instructions(),
+    },
+    {
+      name: 'manual',
+      aliases: [],
+      args: '—',
+      group: '手册',
+      capability: 'local',
+      surfaces: ['hub'],
+      help: '打开操作手册页（任务页操作全流程 + 三端斜杠指令对照）',
+      examples: ['/manual'],
+      run: (ctx) => {
+        const url = ctx.manualUrl();
+        if (typeof ctx.openManual === 'function') ctx.openManual(url);
+        return '操作手册：' + url + '\n（任务页操作全流程 + 三端斜杠指令对照；页面上也可以直接访问这个地址）';
+      },
+    },
+  ];
+
+  /** 时间戳 → 人能读的一行（/resume 列任务用；拿不到就老实写 —） */
+  function fmtTime(ts) {
+    if (!ts) return '—';
+    try {
+      return new Date(ts).toLocaleString();
+    } catch {
+      return '—';
+    }
+  }
+
+  /** 自检：名字/别名唯一、capability/surfaces 合法、必填字段齐全、run 是函数 */
+  function assertRegistry(registry) {
+    const list = registry || COMMANDS;
+    const seen = new Map();
+    list.forEach((c) => {
+      if (!c || !c.name) throw new Error('指令表：存在没有 name 的条目');
+      if (CAPABILITIES.indexOf(c.capability) < 0) throw new Error('/' + c.name + ' 的 capability 非法：' + c.capability);
+      if (!Array.isArray(c.surfaces) || !c.surfaces.length) throw new Error('/' + c.name + ' 的 surfaces 必须非空');
+      c.surfaces.forEach((s) => {
+        if (SURFACES.indexOf(s) < 0) throw new Error('/' + c.name + ' 的 surface 非法：' + s);
+      });
+      if (!c.group) throw new Error('/' + c.name + ' 缺少 group');
+      if (typeof c.run !== 'function') throw new Error('/' + c.name + ' 缺少 run()');
+      [c.name].concat(c.aliases || []).forEach((n) => {
+        const k = String(n).toLowerCase();
+        if (seen.has(k)) throw new Error('指令名冲突：/' + k + ' 属于 /' + seen.get(k) + ' 与 /' + c.name);
+        seen.set(k, c.name);
+      });
+    });
+    return true;
+  }
+
+  function findCommand(name, registry) {
+    const key = String(name == null ? '' : name).toLowerCase();
+    return (registry || COMMANDS).find(
+      (c) => c.name.toLowerCase() === key || (c.aliases || []).some((a) => String(a).toLowerCase() === key)
+    ) || null;
+  }
+
+  /** 端内可用性：任务页只跑 surfaces 含 hub 的指令；fs 类要求服务端放行了本机文件访问 */
+  function isAvailable(cmd, opts) {
+    const o = opts || {};
+    if (!cmd) return false;
+    if (!(cmd.surfaces || ['hub']).includes(o.surface || 'hub')) return false;
+    if (cmd.capability === 'fs' && !o.hasFileSystem) return false;
+    return true;
+  }
+
+  function available(opts) {
+    return (opts && opts.registry ? opts.registry : COMMANDS).filter((c) => isAvailable(c, opts));
+  }
+
+  /**
+   * 前缀候选：主名优先，其次别名。
+   * 空前缀返回**全部可用指令**（按表顺序＝分组顺序）—— 任务页输入框只敲一个 `/` 时就该看见全貌，
+   * 这正是"指令看起来不全"的老毛病：以前返回空数组，面板直接关掉（见文件头「端内差异」）。
+   */
+  function suggest(prefix, opts) {
+    const p = String(prefix == null ? '' : prefix).toLowerCase();
+    if (!p) return available(opts);
+    const scored = [];
+    available(opts).forEach((c) => {
+      const name = c.name.toLowerCase();
+      let score = -1;
+      if (name === p) score = 0;
+      else if (name.startsWith(p)) score = 1;
+      else if ((c.aliases || []).some((a) => String(a).toLowerCase().startsWith(p))) score = 2;
+      if (score >= 0) scored.push({ c, score, name });
+    });
+    scored.sort((a, b) => a.score - b.score || a.name.localeCompare(b.name));
+    return scored.map((s) => s.c);
+  }
+
+  /**
+   * 解析一行输入。返回：
+   *   { isCommand:false }                                普通任务
+   *   { isCommand:false, escaped:true, text:'/x' }       `//x` → 当普通任务发出去
+   *   { isCommand:false, unknownSlash:true, name:'x' }   看着像指令但不认识（**不发给模型**，提示用 //）
+   *   { isCommand:true, cmd, name, argv }                命中
+   *   { isCommand:true, error, matches }                 引号未闭合 / 名字不完整
+   */
+  function parseSlash(text, opts) {
+    const raw0 = String(text == null ? '' : text);
+    if (/^\s*\/\//.test(raw0)) return { isCommand: false, escaped: true, text: raw0.trim().slice(1) };
+    const raw = raw0.replace(/^\s*／/, '/');
+    const m = raw.match(/^\s*\/([A-Za-z][A-Za-z0-9_-]*)/);
+    if (!m) return { isCommand: false };
+    const name = m[1].toLowerCase();
+    let argv;
+    try {
+      argv = tokenize(raw.slice(m[0].length));
+    } catch (e) {
+      return { isCommand: true, name, argv: [], error: (e && e.message) || '参数解析失败' };
+    }
+    const cmd = findCommand(name, (opts && opts.registry) || COMMANDS);
+    if (cmd) {
+      if (!isAvailable(cmd, opts)) {
+        return { isCommand: true, cmd, name, argv, error: cmd.capability === 'fs' ? '这条指令需要本机文件访问，当前服务未放行' : '这条指令不在任务页' };
+      }
+      return { isCommand: true, cmd, name, argv };
+    }
+    const near = suggest(name, opts);
+    if (near.length) return { isCommand: true, name, argv, error: '指令名不完整，请补全', matches: near };
+    return { isCommand: false, unknownSlash: true, name };
+  }
+
+  /* ============================ 帮助（纯文本，对齐列） ============================ */
+
+  function helpText(one, opts) {
+    if (one) {
+      const cmd = findCommand(one, (opts && opts.registry) || COMMANDS);
+      if (!cmd) return '没有这条指令：/' + String(one).replace(/^\//, '') + '（用 /help 看全部）';
+      const lines = [
+        usageLine(cmd) + '    ' + cmd.help,
+        '  别名：' + ((cmd.aliases || []).length ? cmd.aliases.map((a) => '/' + a).join(' ') : '—'),
+        '  能力：' + cmd.capability + (cmd.capability === 'fs' ? '（需要工作目录）' : '（本页即可）'),
+      ];
+      if ((cmd.examples || []).length) lines.push('  示例：' + cmd.examples.join('　'));
+      return lines.join('\n');
+    }
+    const list = available(opts);
+    const width = Math.max.apply(null, list.map((c) => usageLine(c).length));
+    const groups = [];
+    list.forEach((c) => {
+      if (!groups.includes(c.group)) groups.push(c.group);
+    });
+    const rows = [];
+    groups.forEach((g) => {
+      rows.push('  ' + g);
+      list.filter((c) => c.group === g).forEach((c) => rows.push('    ' + usageLine(c).padEnd(width) + '  ' + c.help));
+    });
+    return [
+      '任务页的斜杠指令（只影响这个页面，不发模型）：',
+      rows.join('\n'),
+      '',
+      '输入 / 弹全部候选（↑↓ 选择 · Tab 补全 · Enter 执行 · Esc 关闭）。',
+      '完整手册（含三端对照与操作流程）：/manual',
+      '想把这些字面发给模型，写成 //xxx（例：//plan 就是让它自己规划）。',
+    ].join('\n');
+  }
+
+  /** 机器可读的指令行（手册页 / 服务端 /api/commands 用；字段与 lib/commands.js:commandRows() 对齐） */
+  function commandRows(registry) {
+    return (registry || COMMANDS).map((c) => ({
+      name: c.name,
+      aliases: (c.aliases || []).slice(),
+      args: c.args || '—',
+      usage: usageLine(c),
+      help: c.help,
+      group: c.group,
+      capability: c.capability,
+      surfaces: (c.surfaces || []).slice(),
+    }));
+  }
+
+  /* ============================ 执行 ============================ */
+
+  /**
+   * 执行一条指令。命中与否都返回 { handled }，调用方据此决定还要不要走 /api/task。
+   * ctx 需要：setMode(mode) send(text) pending() decide(approved) workDir() mode() stop()
+   *           listFiles(sub) switchDir(p) init(force) instructions()
+   *           model() setModel(name) cost() tasks() switchTask(id) manualUrl() [openManual(url)]
+   *           print(kind, text) hasFileSystem()
+   */
+  async function runSlash(parsed, ctx) {
+    if (!parsed) return { handled: false };
+    // 未知指令要先拦：它在解析结果里是 isCommand:false（因为它不是指令），
+    // 但**绝不能**因此落回"当普通任务发出去"那条路 —— 这正是端内差异所在。
+    if (parsed.unknownSlash) {
+      ctx.print('warn', '任务页没有 /' + parsed.name + ' 这条指令（用 /help 看现有的）。\n要让模型看到这段文字，写成 //' + parsed.name + '。');
+      return { handled: true, ok: false };
+    }
+    if (!parsed.isCommand) return { handled: false };
+    if (parsed.error) {
+      ctx.print('warn', parsed.error + ((parsed.matches || []).length ? '\n候选：' + parsed.matches.map((c) => usageLine(c).split(' ')[0]).join('　') : ''));
+      return { handled: true, ok: false };
+    }
+    const cmd = parsed.cmd;
+    if (cmd.capability === 'fs' && typeof ctx.hasFileSystem === 'function' && !ctx.hasFileSystem()) {
+      ctx.print('warn', '这条指令需要本机文件访问，当前服务未放行（服务没有绑定在本机地址）。');
+      return { handled: true, ok: false };
+    }
+    try {
+      const out = await cmd.run(ctx, parsed.argv || []);
+      if (typeof out === 'string' && out) ctx.print('ok', out);
+      return { handled: true, ok: true, name: cmd.name };
+    } catch (e) {
+      const msg = e && e.message ? e.message : String(e);
+      ctx.print('error', msg + '\n用法：' + usageLine(cmd) + ((cmd.examples || []).length ? '　例：' + cmd.examples[0] : ''));
+      return { handled: true, ok: false, error: e };
+    }
+  }
+
+  assertRegistry(COMMANDS);
+
+  return {
+    CAPABILITIES, SURFACES, COMMANDS, tokenize, usageLine, findCommand,
+    isAvailable, available, suggest, parseSlash, helpText, commandRows, runSlash, assertRegistry,
+  };
+});