@migor/cli 0.9.1 → 0.9.3

package/dist/markdown.js

@@ -0,0 +1,262 @@
+/**
+ * 面板的 **Markdown 最小渲染器** —— 纯逻辑、零 DOM、零依赖。
+ *
+ * 为什么自己写而不引 `marked` / `markdown-it`：
+ * - **零运行时依赖是本 CLI 的硬承诺**（`package.json` 里没有 `dependencies`）。为了面板把一份
+ *   解析器 + 一份消毒器（DOMPurify 之类）塞进 dist，等于在 dev 链路里引入两个第三方供应链面，
+ *   而它们的产物**没法被本仓的单测验证**（我们只能验「我写的那部分」）。
+ * - 面板只需要**模型正文**这一种输入可读：标题 / 粗体 / 斜体 / 行内码 / 围栏码 / 列表 /
+ *   引用 / 分隔线 / 链接。这套子集手写不到 200 行，且**每条规则都能配一条单测**。
+ * - 最要紧的是**它按构造不产生 HTML**：返回值是一棵 token 树（`MdBlock` / `MdInline`），
+ *   没有任何「原样透传的 HTML」这一类。页面的渲染器只准用 `createElement` + `textContent`
+ *   把它变成 DOM ⇒ **模型输出里的 `<script>` 只会是字面文本**，不存在「忘了转义」这条路径。
+ *
+ * ⚠️ 本文件**不许碰 DOM**（不出现 `document` / `window`）—— 它要在 Node 里被直接 import 做单测。
+ *
+ * 支持的子集（刻意不做的都在「不做」里）：
+ * - 块：`#` 标题（1–6 级）、围栏码块（``` / ~~~，带语言标注）、无序/有序列表（**一层**）、
+ *   引用（合并成一段正文）、`---` 分隔线、段落
+ * - 行内：行内码、`**粗**`、`*斜*`、`[文字](链接)`、`<https://…>` 自动链接
+ *
+ * 不做（都是刻意的，不是漏）：
+ * - **不做 HTML 透传**（安全前提，见上）
+ * - 不做表格 / 任务列表 / 嵌套列表 / 脚注 / 数学 —— 面板是调试视图，不是文档站
+ * - 不做 setext 标题（`===` 下划线式）—— 与分隔线歧义大、收益小
+ * - 不做图片（`![]()`）—— 面板**不去外网取图**：一次 run 的正文不该触发网络请求
+ * - 不做**词内** `_` 强调（`read_file_tool` 原样显示）—— 与 CommonMark 同口径，见 `parseInline`
+ */
+/**
+ * 链接协议白名单。**这是安全边界，不是风格选择**：
+ * 模型输出里的 `[点我](javascript:alert(1))` 若被渲染成可点链接，面板就成了 XSS 的跳板
+ * （`href` 是唯一一处「我们主动写进属性」的值 —— 文本全走 `textContent` 是安全的，
+ * 属性不是）。不合法 ⇒ 这一条**整个降级成字面文本**（连 `[]()` 都照原样显示），
+ * 使用者一眼看得出「这里有个链接我没渲染」，而不是看到一个空链接或点不动的链接。
+ */
+export function isSafeHref(href) {
+    // 允许 http/https/mailto；**不允许** javascript: / data: / vbscript: / file: 等
+    return /^(https?:|mailto:)/i.test(href.trim());
+}
+const FENCE = /^\s{0,3}(`{3,}|~{3,})\s*([^\s`]*)/;
+const HEADING = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const HR = /^\s{0,3}([-*_])(?:\s*\1){2,}\s*$/;
+const QUOTE = /^\s{0,3}>\s?(.*)$/;
+const UL = /^(\s*)([-*+])\s+(.*)$/;
+const OL = /^(\s*)(\d{1,9})[.)]\s+(.*)$/;
+const BLANK = /^\s*$/;
+/** 「单词字符」：`_` 的词内排除用它判边界（与 CommonMark 的 intraword 规则同口径） */
+const WORD_CHAR = /[A-Za-z0-9_]/;
+/** 下标可能越界（`text[-1]` / `text[len]` 都是 `undefined`）⇒ 越界一律当「不是单词字符」 */
+function isWordChar(ch) {
+    return ch !== undefined && WORD_CHAR.test(ch);
+}
+/**
+ * 把一段 Markdown 文本解析成块序列。
+ *
+ * 三条与「真 Markdown」不同但**刻意**的口径：
+ * - 缩进 ≥2 空格的续行归上一条列表项（列表只解析**一层**：更深一层当正文，不递归建树）；
+ * - 未闭合的围栏码块吃掉到文末（**不静默丢内容** —— 模型被截断时最常见的就是这个形态）；
+ * - 引用（`>`）合并成**一段正文**（面板里引用几乎总是模型在引日志，逐行建块只会更碎）。
+ */
+export function parseMarkdown(text) {
+    const src = String(text ?? '').replace(/\r\n?/g, '\n');
+    const lines = src.split('\n');
+    const blocks = [];
+    let i = 0;
+    let para = [];
+    const flushPara = () => {
+        if (para.length === 0)
+            return;
+        const joined = para.join('\n').trim();
+        para = [];
+        if (joined)
+            blocks.push({ type: 'p', inline: parseInline(joined, 0) });
+    };
+    while (i < lines.length) {
+        const line = lines[i];
+        // —— 围栏码块 ——
+        const fence = FENCE.exec(line);
+        if (fence) {
+            flushPara();
+            const marker = fence[1][0];
+            const min = fence[1].length;
+            const lang = fence[2] ?? '';
+            const body = [];
+            i++;
+            while (i < lines.length) {
+                const cur = lines[i];
+                const close = new RegExp(`^\\s{0,3}${marker === '`' ? '`' : '~'}{${min},}\\s*$`);
+                if (close.test(cur)) {
+                    i++;
+                    break;
+                }
+                body.push(cur);
+                i++;
+            }
+            blocks.push({ type: 'code', lang, text: body.join('\n') });
+            continue;
+        }
+        // —— 空行：段落到此为止 ——
+        if (BLANK.test(line)) {
+            flushPara();
+            i++;
+            continue;
+        }
+        // —— 分隔线（必须在列表之前判：`---` 也是无序列表的标记） ——
+        if (HR.test(line)) {
+            flushPara();
+            blocks.push({ type: 'hr' });
+            i++;
+            continue;
+        }
+        // —— 标题 ——
+        const h = HEADING.exec(line);
+        if (h) {
+            flushPara();
+            blocks.push({
+                type: 'h',
+                level: h[1].length,
+                inline: parseInline(h[2].trim(), 0),
+            });
+            i++;
+            continue;
+        }
+        // —— 引用：连续 `>` 行合成一段 ——
+        if (QUOTE.test(line)) {
+            flushPara();
+            const quoted = [];
+            while (i < lines.length && QUOTE.test(lines[i])) {
+                quoted.push(QUOTE.exec(lines[i])[1]);
+                i++;
+            }
+            const joined = quoted.join('\n').trim();
+            blocks.push({ type: 'quote', inline: parseInline(joined, 0) });
+            continue;
+        }
+        // —— 列表（无序 / 有序，各收一段连续的） ——
+        const ul = UL.exec(line);
+        const ol = olAt(line);
+        if (ul || ol) {
+            flushPara();
+            const ordered = ol !== null;
+            const items = [];
+            while (i < lines.length) {
+                const cur = lines[i];
+                const m = ordered ? olAt(cur) : UL.exec(cur);
+                if (m) {
+                    items.push(parseInline(m[3].trim(), 0));
+                    i++;
+                    continue;
+                }
+                // 续行：缩进 ≥2 且不是新的一条 ⇒ 并进上一项
+                if (items.length > 0 && /^\s{2,}\S/.test(cur) && !BLANK.test(cur)) {
+                    const last = items[items.length - 1];
+                    last.push(...parseInline(cur.trim(), 0));
+                    i++;
+                    continue;
+                }
+                break;
+            }
+            blocks.push({ type: 'list', ordered, items });
+            continue;
+        }
+        // —— 其余：段落（连续非空行合并，行内换行保留） ——
+        para.push(line.trim());
+        i++;
+    }
+    flushPara();
+    return blocks;
+}
+/** 有序列表标记（`1.` / `1)`），返回与 UL 同形的三组：缩进 / 标记 / 正文 */
+function olAt(line) {
+    const m = OL.exec(line);
+    return m ? m : null;
+}
+/**
+ * 行内解析。`depth` 是**递归上限**：`**a *b* c**` 这类嵌套只展开到第 3 层，
+ * 再深就按字面留着 —— 递归无上限时，一条构造出来的正文就能把面板卡死。
+ */
+export function parseInline(text, depth) {
+    const out = [];
+    let buf = '';
+    let i = 0;
+    const pushText = () => {
+        if (buf)
+            out.push({ type: 'text', text: buf });
+        buf = '';
+    };
+    while (i < text.length) {
+        const c = text[i];
+        // 行内码：`...`（不跨行；两端各去掉一个空格 —— 与 CommonMark 同款）
+        if (c === '`') {
+            const end = text.indexOf('`', i + 1);
+            if (end > i + 1) {
+                pushText();
+                let inner = text.slice(i + 1, end);
+                if (inner.startsWith(' ') && inner.endsWith(' ') && inner.trim())
+                    inner = inner.slice(1, -1);
+                out.push({ type: 'code', text: inner });
+                i = end + 1;
+                continue;
+            }
+        }
+        // 链接：[文字](地址) —— 地址不过白名单就整条降级成字面文本（见 isSafeHref）
+        if (c === '[') {
+            const m = /^\[([^\]]*)\]\(([^)\s]*)\)/.exec(text.slice(i));
+            if (m) {
+                const raw = text.slice(i, i + m[0].length);
+                const href = m[2].trim();
+                if (isSafeHref(href)) {
+                    pushText();
+                    out.push({ type: 'link', href, text: m[1].trim() });
+                }
+                else {
+                    buf += raw; // 字面保留（连 []() 一起）—— 让使用者看见「这里有个链接我没渲染」
+                }
+                i += m[0].length;
+                continue;
+            }
+        }
+        // 自动链接：<https://…>（裸的 `<` 一律当文本 —— 这正是「不做 HTML 透传」的落点）
+        if (c === '<') {
+            const m = /^<(https?:\/\/[^\s>]+)>/.exec(text.slice(i));
+            if (m) {
+                pushText();
+                out.push({ type: 'link', href: m[1], text: m[1] });
+                i += m[0].length;
+                continue;
+            }
+        }
+        // 强调：**粗** / *斜*（`__` / `_` 同义）
+        if (c === '*' || c === '_') {
+            const strong = text.startsWith(c + c, i);
+            const mark = strong ? c + c : c;
+            const end = text.indexOf(mark, i + mark.length);
+            if (end > i + mark.length) {
+                const inner = text.slice(i + mark.length, end);
+                /**
+                 * `_` 的**词内排除**（CommonMark 的 intraword 规则）：两侧只要有一边紧贴单词字符，
+                 * 就不构成强调。
+                 *
+                 * 没有这条，`read_file_tool` 会被切成 `read` + <em>file</em> + `tool`、
+                 * `src/my_dir/my_file.ts` 同理 —— 而面板渲染的正是**模型正文**，标识符是那里最常见的东西。
+                 * 单下划线（`read_file`）本来就不配对、不受影响；真正被切开的是有两个及以上 `_` 的标识符。
+                 *
+                 * ⚠️ `*` **不做**这条限制：CommonMark 里 `a*b*c` **就是** `a<em>b</em>c`。
+                 * 只修 `_`、不修 `*`，是照口径修，不是照直觉修。
+                 */
+                const intraword = c === '_' && (isWordChar(text[i - 1]) || isWordChar(text[end + mark.length]));
+                if (!intraword && inner.trim() && !inner.startsWith(' ') && !inner.endsWith(' ')) {
+                    pushText();
+                    const children = depth < 3 ? parseInline(inner, depth + 1) : [{ type: 'text', text: inner }];
+                    out.push(strong ? { type: 'strong', children } : { type: 'em', children });
+                    i = end + mark.length;
+                    continue;
+                }
+            }
+        }
+        buf += c;
+        i++;
+    }
+    pushText();
+    return out;
+}

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` 以内。
@@ -381,3 +413,35 @@ export function promptAfterFilePick(current, name) {
         return { prompt: current, filled: false };
     return { prompt: name, filled: true };
 }
+// ---------- ③ 消息折叠：长正文默认收起，短的不加控件 ----------
+/**
+ * 超过这么多行就默认折叠。12 行是「一屏大致读得完」的量级 —— 面板右栏在 1223px 下正文行高
+ * 约 18px，12 行 ≈ 216px，正好是不把调用树挤出去的上限。
+ */
+export const COLLAPSE_MAX_LINES = 12;
+/** 单行长正文的兜底阈值：一行 2000 字符（模型不换行时很常见）同样该收起来 */
+export const COLLAPSE_MAX_CHARS = 1200;
+/**
+ * 「这段正文要不要折叠」。**判定是纯逻辑** —— 渲染层只管按结果挂控件，
+ * 不自己量高度（量高度依赖布局与字体，单测里量不出来，等于把规则藏进浏览器）。
+ *
+ * 为什么不按像素量：像素阈值在字体/缩放/窄屏下会漂，同一个回复在不同机器上折叠与否都不一样；
+ * 行数 + 字符数是**输入本身的属性**，可复现、可断言。
+ *
+ * `hint` 是给展开控件用的文案（面板拿它当按钮标题，再加个 caret）；不折叠时是空串 ——
+ * **短消息上挂一个「展开」是噪声**，所以控件只在真的长时出现。
+ */
+export function collapseDecision(text, opts = {}) {
+    const t = String(text ?? '');
+    const lines = t.length === 0 ? 0 : t.split('\n').length;
+    const chars = t.length;
+    const maxLines = opts.maxLines ?? COLLAPSE_MAX_LINES;
+    const maxChars = opts.maxChars ?? COLLAPSE_MAX_CHARS;
+    const collapsed = lines > maxLines || chars > maxChars;
+    const hint = collapsed
+        ? lines > 1
+            ? `展开全文（共 ${lines} 行）`
+            : `展开全文（共 ${chars} 字符）`
+        : '';
+    return { collapsed, lines, chars, hint };
+}

package/dist/templates/package.json

@@ -9,10 +9,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@migor/agentia": "^0.9.1"
+    "@migor/agentia": "^0.9.3"
   },
   "devDependencies": {
-    "@migor/cli": "^0.9.1",
+    "@migor/cli": "^0.9.3",
     "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;