@migor/cli 0.9.2 → 0.9.4

package/dist/native-pick.js

@@ -0,0 +1,168 @@
+/**
+ * OS 原生文件夹选择器（dev 面板「工作目录」控件的「用系统选择器…」路径）。
+ *
+ * 为什么存在：浏览器**拿不到**用户所选文件夹的绝对路径（`<input webkitdirectory>` 只给
+ * 相对路径、File System Access API 只给 handle.name），而 dev 环要的就是绝对路径。
+ * 但 CLI 是本机进程 —— 它可以替用户拉起 OS 原生的目录选择框，把选中的绝对路径拿回来。
+ * `/api/fs` 的「浏览…」目录浏览器是这条路的**降级**（命令缺失 / 平台不支持时用）。
+ *
+ * ⚠️ **绝不能在 e2e / CI 里真触发**：osascript / zenity 会弹出**真对话框**把流水线挂死。
+ * 所以本模块的「平台 → 命令候选」「取消判定」「输出归一化」全是纯函数（带单测），
+ * 真正 spawn 的 `pickFolderNative()` 只由 dev 钩子在用户点击时调用。
+ *
+ * 防孤儿：选择框是用户可能要放着想一会儿的东西（**不设**超时），但 dev 进程退出时
+ * 必须收掉 —— 否则留下一个没人看的 osascript 对话框孤儿。在飞的子进程登记在模块级
+ * `active` 里，dev.ts 收尾时调 `killActivePickers()`。
+ */
+import { spawn, spawnSync } from 'node:child_process';
+const MACOS_PICKER = {
+    command: 'osascript',
+    args: ['-e', 'POSIX path of (choose folder with prompt "选择 agent 的工作目录")'],
+};
+const WINDOWS_PICKER = {
+    command: 'powershell',
+    args: [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Add-Type -AssemblyName System.Windows.Forms; ' +
+            '$d = New-Object System.Windows.Forms.FolderBrowserDialog; ' +
+            "if ($d.ShowDialog() -eq 'OK') { $d.SelectedPath }",
+    ],
+};
+const LINUX_PICKERS = [
+    ['zenity', { command: 'zenity', args: ['--file-selection', '--directory'] }],
+    ['kdialog', { command: 'kdialog', args: ['--getexistingdirectory'] }],
+];
+/**
+ * 「平台 → 命令候选」的纯解析（**导出为单测用**；`has` = 该命令在 PATH 上可用）。
+ *
+ * darwin / win32 的候选是确定的（osascript / powershell 是系统自带），不需要探测；
+ * linux 没有系统级唯一答案，按 zenity → kdialog 顺序探测，都没有 ⇒ `null`
+ * （调用方翻译成 501 + 可读报错）。
+ */
+export function resolvePicker(platform, has) {
+    if (platform === 'darwin')
+        return MACOS_PICKER;
+    if (platform === 'win32')
+        return WINDOWS_PICKER;
+    if (platform === 'linux') {
+        for (const [cmd, candidate] of LINUX_PICKERS) {
+            if (has(cmd))
+                return candidate;
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * 「这次退出算不算用户取消」的纯判定（**导出为单测用**）。
+ *
+ * 三个平台三种取消信号：
+ * - darwin：osascript 取消 = 退出码非 0 + stderr 带 **错误码 `(-128)`** —— AppleScript 的
+ *   「用户取消」错误码恒为 -128、**不随系统语言本地化**；文案（"User canceled"）才是
+ *   本地化的那部分，只当兜底匹配（非英文系统上只认文案会把「取消」误判成失败 ⇒ 501）。
+ * - win32：`ShowDialog()` 不是 OK 就什么都不打印（退出码 0）；powershell 自身出错会写
+ *   stderr —— 所以判「**两个流都空**」而不是只看退出码，否则真错误会被误报成「取消」；
+ * - linux：zenity / kdialog 取消 = 退出码 1、**无输出**；而「没有 DISPLAY」这类真错误
+ *   会往 stderr 写一句 —— 同样落「两个流都空即取消」。
+ * - 被 signal 杀掉（dev 进程退出时 `killActivePickers` 收编）一律视同取消。
+ */
+export function isCancel(platform, code, signal, stderr, stdout) {
+    if (signal !== null)
+        return true;
+    if (platform === 'darwin') {
+        return code !== 0 && (stderr.includes('(-128)') || /user canceled/i.test(stderr));
+    }
+    return stdout.trim().length === 0 && stderr.trim().length === 0;
+}
+/**
+ * 选中输出的归一化（**导出为单测用**）：空输出 ⇒ `null`（取消）。
+ *
+ * 两个坑：
+ * - 尾部换行 / `\r\n`（powershell）要去掉，但**只去尾部** —— 路径含空格、非 ASCII
+ *   都要原样扛住；
+ * - macOS 的 osascript `POSIX path of` 输出**带尾斜杠**（`/Users/x/`），要归一掉
+ *   （面板会拿它与 `/api/fs` 列出的路径拼接比对）；根目录 `/` 是唯一例外，不能归一成空串。
+ */
+export function normalizePickedPath(platform, stdout) {
+    const trimmed = stdout.replace(/[\r\n]+$/, '');
+    if (trimmed.length === 0)
+        return null;
+    if (platform === 'darwin' && trimmed.endsWith('/')) {
+        return trimmed.replace(/\/+$/, '') || '/';
+    }
+    return trimmed;
+}
+/** 在飞的选择框子进程 —— dev 进程退出时由 `killActivePickers()` 收编，不留 osascript 孤儿 */
+const active = new Set();
+/**
+ * 收掉所有还挂着的原生选择框（dev 收尾 / 进程退出时调用）。
+ * 被杀掉的子进程在 `pickFolderNative` 那边走「视同取消」（resolve null）——
+ * 那时进程本就要没了，没人会读这个值，但**不许挂着一个永不 settle 的 Promise**。
+ */
+export function killActivePickers() {
+    for (const child of active) {
+        try {
+            child.kill();
+        }
+        catch {
+            /* 已经退出了 */
+        }
+    }
+}
+/** linux 上的命令探测（`which` 是事实标准；探测本身失败就当没有） */
+function hasCommand(cmd) {
+    try {
+        return spawnSync('which', [cmd], { stdio: 'ignore' }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 拉起 OS 原生目录选择框，返回用户选中的**绝对路径**；用户取消返回 `null`。
+ *
+ * 平台不支持或命令缺失时**抛错**（消息可读，并指向降级路径「浏览…」）——
+ * 调用方（dev 钩子）把它翻译成 501。
+ *
+ * **不设超时**：用户可能把对话框放着想一会儿；进程退出由 `killActivePickers()` 收编。
+ */
+export function pickFolderNative() {
+    const picker = resolvePicker(process.platform, hasCommand);
+    if (picker === null) {
+        return Promise.reject(new Error(process.platform === 'linux'
+            ? '找不到 zenity / kdialog —— 原生文件夹选择器不可用，请改用面板的「浏览…」'
+            : `这个平台（${process.platform}）没有原生文件夹选择器 —— 请改用面板的「浏览…」`));
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(picker.command, picker.args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        active.add(child);
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (c) => {
+            stdout += c.toString('utf8');
+        });
+        child.stderr.on('data', (c) => {
+            stderr += c.toString('utf8');
+        });
+        child.on('error', (e) => {
+            active.delete(child);
+            // 命令缺失（ENOENT）也走这条路 —— 与「平台不支持」同一条可读口径
+            reject(new Error(`原生文件夹选择器起不来（${picker.command}：${e.message}）—— 请改用面板的「浏览…」`));
+        });
+        child.on('close', (code, signal) => {
+            active.delete(child);
+            if (isCancel(process.platform, code, signal, stderr, stdout)) {
+                resolve(null);
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`原生文件夹选择器失败（${picker.command} 退出 code=${code}）：` +
+                    `${stderr.trim() || '无输出'} —— 请改用面板的「浏览…」`));
+                return;
+            }
+            resolve(normalizePickedPath(process.platform, stdout));
+        });
+    });
+}

package/dist/panel-logic.js

@@ -24,6 +24,23 @@ export function normalizeToolSources(selected, all) {
 export function capabilityBadge(selected, all) {
     return `${selected.length}/${all.length}`;
 }
+/**
+ * 渲染前丢掉**已失效**的 token（能力被删 / runner 重启后菜单变了）。不过滤徽标就说谎：
+ * 分子里混着菜单上已不存在的名字 ⇒ `4/3`。空集返回空数组（「回落全选」是**调用方**的
+ * 规则），且保留入参顺序 —— 过滤不重排，排序是 `normalizeToolSources` 发送前的活。
+ */
+export function filterSelected(selected, all) {
+    const known = new Set(all);
+    return [...new Set(selected)].filter((s) => known.has(s));
+}
+/**
+ * 一条 run 的「已选来源」显示口径（`null` = 全量，与 `RunNote.toolSources` 同义）。
+ * **两处共用一份**：run 列表第三行与 `run-start` 提示条 —— 各写一份就会出现「同一组
+ * 能力两个说法」，而面板的纪律是「显示的就是生效的那份」。
+ */
+export function formatToolSources(sources) {
+    return sources === null ? '全量' : sources.join(',');
+}
 /**
  * 多轮开关的初始值。
  *
@@ -187,6 +204,21 @@ export function mergeConversation(messages, runs, sessionId) {
     }
     return turns;
 }
+/**
+ * 对话视图出不出现。三条**都**满足才显示，不做空壳：① dev 环在场且可用（只读面板没有
+ * 输入条 ⇒ 没有多轮）；② 多轮开着（单轮不写会话文件）；③ 会话文件读得到（工程没配
+ * `SessionStore` 时它是 null）。缺一条就只剩空壳 —— 那比不显示更糟：用户以为对话跑丢了。
+ */
+export function chatViewVisible(dev, multiTurn, session) {
+    return dev?.available === true && multiTurn && session !== null;
+}
+/**
+ * 对话轮折叠态的键：**必须混进 sessionId**。清空对话换 id 后下标从 0 重来，
+ * 只用下标当键会把旧会话第 0 轮的展开态套到新会话第 0 轮上（张冠李戴）。
+ */
+export function turnKey(sessionId, index) {
+    return `turn:${sessionId}:${index}`;
+}
 // ---------- CLI 侧记账（面板发出去的东西，CLI 自己记一笔） ----------
 /**
  * 往 notes 表里记一条，并**按插入序**把表压在 `max` 以内。

package/dist/templates/package.json

@@ -9,10 +9,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@migor/agentia": "^0.9.2"
+    "@migor/agentia": "^0.9.4"
   },
   "devDependencies": {
-    "@migor/cli": "^0.9.2",
+    "@migor/cli": "^0.9.4",
     "tsx": "^4.19.0",
     "typescript": "^7.0.2",
     "@types/node": "^22.0.0"

package/dist/templates/src/app.ts

@@ -78,6 +78,9 @@ export async function createAgentApp(opts: CreateAgentAppOptions = {}): Promise<
       // 里声明 `{ provide: '<能力 token>', useClass: Xxx, deps: ['WORKDIR'] }`
       // （discover 自动注册的 provider **没有 deps**，所以要注入的能力得从 discover 挪到显式
       // providers；同一个 token 混用不会重复收集菜单）。
+      // ⚠️ 若同时用 src/registry.ts（那里也有一份 `WORKDIR = process.cwd()`）：
+      // 同 token **后注册覆盖先注册**，registry 的 providers 必须排在**这份之前**，
+      // 否则面板喂进来的 workdir 会被 process.cwd() 静默顶掉。
       { provide: 'WORKDIR', useValue: opts.workdir ?? PROJECT_ROOT },
       // 例子：把工作目录注入给 read-file 工具（脚手架自带的第二个能力，
       // 也是「面板上的文件夹选择器真的生效」的那个接线）

package/dist/templates/src/dev.config.ts

@@ -36,5 +36,10 @@ export default {
    * 面板上「点一下就跑一次真 agent」，而真 agent 真花钱 —— 一个跑偏的循环就是一张账单。
    * 这里可以按工程调；调小更安全，调大更放得开。
    * 例：budget: { maxCostUsd: 5, maxTotalTokens: 1_000_000 },
+   *
+   * ⚠️ 覆盖关系：runner 把这份预算以 **run 级选项**传给框架，而框架的规则是
+   * run 级**优先于** createApp 应用级 ⇒ 你在 `src/app.ts` 的 createApp 里自配的
+   * `maxCostUsd` / `maxTotalTokens` 在 dev 环会被这里（或缺省值）压回去。
+   * 想改 dev 环的预算就在这里的 `budget` 字段改，别去 app.ts 里找。
    */
 };

package/dist/templates/src/registry.ts

@@ -7,6 +7,11 @@ import type { Provider } from '@migor/agentia';
 export const providers: Provider[] = [
   // 「工作目录」以**值**注入给需要它的能力（消费方式见 src/tools/read-file/index.ts）。
   // 想改成固定路径 / 从环境变量取，改这一行即可 —— 这是显式装配路线的意义。
+  //
+  // ⚠️ 与 src/app.ts 里那份 `WORKDIR` 是**二选一**的关系，混用时**顺序承重**：
+  // createApp 对同 token 是「后注册覆盖先注册」—— 把这份 providers 拼在 app.ts 那份
+  // **之后**，dev 面板喂进来的 workdir 会被这里的 `process.cwd()` 静默顶掉。
+  // 要混用就让本注册表排在前（让 app.ts 的值赢），否则只留一边。
   { provide: 'WORKDIR', useValue: process.cwd() },
   // @agentia:entries
   // @agentia:entries-end

package/dist/templates/src/session-store.ts

@@ -31,6 +31,9 @@ export class FileSessionStore implements SessionStore {
     mkdirSync(dirname(this.file), { recursive: true });
     // 原子写：先写同目录的临时文件再 rename。直接覆写的话，进程在写一半时被杀
     // 会留下半截 JSON，下一次 load 直接抛 —— 整段历史因为一次崩溃而不可读。
+    // ⚠️ 这只保**单进程**内的写完整：tmp 路径固定是 `${file}.tmp`，两个进程同时
+    // append 会在 rename 上竞态、丢一边。dev 环是单进程 runner，无此问题；要多进程
+    // 共享这份文件，契约要求调用方自行串行化（与 SessionStore 的 append-only 约定一致）。
     const tmp = `${this.file}.tmp`;
     writeFileSync(tmp, JSON.stringify({ sessions: all }, null, 2), 'utf8');
     renameSync(tmp, this.file);
@@ -38,8 +41,14 @@ export class FileSessionStore implements SessionStore {
 
   /**
    * 读整份文件。文件不存在 = 还没有历史（空）。
-   * 解析失败**响亮报错**而不是当作空历史 —— 静默当成空会把「历史读不出来」
-   * 伪装成「这是第一轮」，然后下一轮 append 再把它覆盖掉：整段对话无声消失。
+   *
+   * 解析失败**抛错**而不是当作空历史 —— 静默当成空会把「历史读不出来」伪装成
+   * 「这是第一轮」，然后下一轮 append 再把它覆盖掉：整段对话无声消失。
+   *
+   * ⚠️ 但要如实说清楚这个错误会走到哪：框架在 run 期间会**刻意吞掉**会话侧的异常
+   * （辅助动作不击穿 run），所以这里的抛错不会把 run 打崩、也不会直接可见。
+   * 真正的可见性出口是 dev runner **启动期**的那次探测：它主动 `load()` 一次，
+   * 把原因送上 warning 通道（面板顶部可见）—— 所以别把这里的抛错改成静默。
    */
   private readAll(): Record<string, MessageParam[]> {
     let raw: string;

package/dist/templates/src/tools/read-file/index.ts

@@ -1,15 +1,23 @@
-import { readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { resolve, sep } from 'node:path';
 import { Tool } from '@migor/agentia';
 
+/** 目录清单的输出上限（条）。截断会在输出里**明示** —— 静默少给等于让模型以为目录里没有 */
+const LIST_LIMIT = 200;
+
 /**
- * 读取**工作目录**下的一个文本文件（相对路径）。
+ * 工作目录的一对工具：**先看有什么（list_files）→ 再读（read_file）**。
  *
  * 它是脚手架自带的第二个能力，作用是把「工作目录」这条线**接通**：
  * `agentia dev` 的面板上有「工作目录」控件，而只有当**某个能力真的消费它**时，
  * 那个控件才有可观测的效果。做法就是这里 —— 根由 DI 注入（`WORKDIR`），
  * 不在代码里写死。见 app.ts 的 providers。
  *
+ * 为什么是一对而不是只有 read_file：换了目录之后，模型既不知道自己此刻在哪个目录、
+ * 也不知道里面有什么（run 的 prompt 不会变）⇒ 只能瞎猜文件名，行为看起来「没变」。
+ * `list_files` 输出的**第一行就是工作目录的绝对路径** —— 那是模型「知道自己在哪」
+ * 的通道；列出来的名字则回答「里面有什么」。
+ *
  * 换成别的形态（把 `workdir` 换成某个 API 的 baseUrl、某个数据目录）完全一样：
  * 值从构造器进来，方法里用 `this.root`。
  */
@@ -33,7 +41,41 @@ export default class ReadFileTool {
   }
 
   @Tool({
-    description: '读取工作目录下的一个文本文件（给相对路径，如 README.md）',
+    description:
+      '列出工作目录（或其中一个相对子目录）的内容：先看这里有什么，再用 read_file 读具体文件。' +
+      '输出第一行是当前工作目录的绝对路径 —— 换过目录后用它确认自己此刻在哪个目录下工作。',
+    schema: {
+      type: 'object',
+      properties: {
+        dir: { type: 'string', description: '相对工作目录的子目录路径（缺省 = 工作目录本身）' },
+      },
+      additionalProperties: false,
+    },
+    strict: true,
+  })
+  // 目录名带 `/` 后缀（一眼可辨），目录在前、文件在后。越界判定复用 safeResolve ——
+  // 读目录也是读，同一道闸。输出有上限，截断**明示**（不许静默少给）。
+  async list_files(input: { dir?: string }): Promise<string> {
+    const abs = safeResolve(this.root, input.dir ?? '.');
+    const entries = await readdir(abs, { withFileTypes: true });
+    const names = entries
+      .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+      .sort((a, b) => {
+        const dirA = a.endsWith('/') ? 0 : 1;
+        const dirB = b.endsWith('/') ? 0 : 1;
+        return dirA - dirB || a.localeCompare(b);
+      });
+    const lines = [`工作目录：${this.root}`];
+    if (input.dir !== undefined && input.dir !== '.') lines.push(`所列目录：${abs}`);
+    lines.push(...names.slice(0, LIST_LIMIT));
+    if (names.length > LIST_LIMIT) {
+      lines.push(`（还有 ${names.length - LIST_LIMIT} 条未列出 —— 输出截断在 ${LIST_LIMIT} 条）`);
+    }
+    return lines.join('\n');
+  }
+
+  @Tool({
+    description: '读取工作目录下的一个文本文件（给相对路径，如 README.md）；不知道文件名时先用 list_files 看',
     schema: {
       type: 'object',
       properties: { rel: { type: 'string', description: '相对工作目录的文件路径' } },
@@ -45,6 +87,7 @@ export default class ReadFileTool {
   // 方法名 = 模型看到的工具名 ⇒ 与其余模板一律 snake_case（doc_reviewer / note_writer …）。
   // 顺带解掉一个坑：这里若叫 readFile，就与上面 import 进来的 readFile 同名 ——
   // 方法体内 `this.readFile(...)` 会变成自我递归，而裸写 `readFile(...)` 读的是 import 的那个。
+  // 分工：list_files 负责「先看有什么」，这里负责「读这个具体文件」。
   async read_file(input: { rel: string }): Promise<string> {
     return readFile(safeResolve(this.root, input.rel), 'utf8');
   }
@@ -59,6 +102,10 @@ export default class ReadFileTool {
  * ⚠️ 两端都归一化再比：`root` 由调用方给（可能带尾斜杠），而下面判越界用的是
  * **字符串前缀** —— `resolve(root) + sep` 不归一化时会是 `/a/b//`，于是每一次调用
  * 都误报越界。归一化放在函数内部（不只依赖构造器）：本函数是导出的，调用方可能不止一个。
+ *
+ * ⚠️ 已知边界：**不解 realpath** —— 工作目录**内**的符号链接可以指到目录外。
+ * 它防的是「模型乱给相对路径跑出工作目录」，不是一道安全边界（read-only，危害有限）；
+ * 真要拿它当边界用（比如可写工具），先在这里补 realpath 比较。
  */
 export function safeResolve(root: string, rel: string): string {
   const base = resolve(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/cli",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Agentia 框架命令行工具：create 脚手架 + g 能力生成 + dev 本地可观测面板（trace inspector）",
   "type": "module",
   "bin": {