@migor/agentia 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -5,6 +5,109 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [0.9.2] - 2026-09-22
+
+> 本版主题（窗口 `0.9.1 → 0.9.2`）：**dev 面板的可读性** —— 模型正文按 Markdown 渲染、
+> 滚动分层（整页不滚、只滚该滚的那块）、长正文默认折叠。
+> **无破坏性变更**：框架公共 API 与脚手架模板形态逐字未变。
+
+### 新增 · dev 面板的正文 Markdown 渲染
+
+- **模型正文按 Markdown 渲染**（最终回复 + 对话视图的助手轮）：标题 / 粗斜体 / 行内码 /
+  围栏码（带语言标注）/ 列表 / 引用 / 分隔线 / 链接。此前是一整块 `<pre>` 纯文本，
+  长回复里的列表与代码块糊成一坨。
+- 解析器是**自己写的**（`packages/cli/src/markdown.ts`，纯逻辑、零依赖、带单测）：
+  引 `marked` + `DOMPurify` 等于把两份第三方产物塞进 dev 链路，而且它们**没法被本仓单测验证**；
+  这套子集不到 200 行，每条规则都有用例。安全前提是**按构造不产生 HTML** —— 解析器只产出
+  token 树（没有「HTML 透传」这一类），渲染层只准用 `createElement` / `textContent`
+  ⇒ 模型输出里的 `<script>` 只会是字面文本。链接协议过白名单（`http` / `https` / `mailto`），
+  不合法（`javascript:` 等）**整条降级成字面文本**（连 `[]()` 一起显示）。用户轮保持字面 ——
+  那是「我打的字」，按 Markdown 重排会像面板改过我的输入。
+
+### 变更 · 面板滚动分层：整页不滚，只滚该滚的那块
+
+- 此前右栏没有高度上限 ⇒ 内容一长就是**整页滚动**，而 `footer` 还粘在底部盖住内容。
+  现在改成应用外壳：`html/body` 卡 100vh、`body` 不滚；左栏页签固定、列表自己滚；
+  右栏**只有调用树是滚动区**（它随 span 数无界增长），回复 / 能力排行 / 用量固定在下方、
+  各有上限（回复很长时在**它自己那块**里滚，而不是把树推出屏幕）。
+- 窄屏（≤860px）回落成单列 + 整页滚动 —— 两栏并排在那个宽度下都不可用。
+
+### 变更 · 长消息折叠：明确的「展开 / 收起」
+
+- 超过 12 行或 1200 字符的正文默认折叠（卡 216px + 底部渐隐），下方左对齐一个
+  「展开全文（共 N 行）▾」按钮，展开后变「收起 ▴」。**短正文不挂控件**（挂一个是噪声）。
+- 判定走纯逻辑 `collapseDecision`（带单测）：按**行数 + 字符数**，不量像素 —— 像素阈值在
+  字体 / 缩放 / 窄屏下会漂，同一个回复在不同机器上折叠与否都不一样。展开态活在渲染之外
+  （面板每次全量重画，状态留在 DOM 里会被下一次重画合上）。
+
+### 修复
+
+- **CLI 套件里两条文件监视用例在全链下稳定假红**（`packages/cli/test/panel-logic.test.mjs`）：
+  夹具原来「**写一次**、然后轮询等满 15 秒」，而真 fs 的监视器**建立是异步的**（`fs.watch`
+  返回 ≠ 底下 FSEvents 流已开始投递）—— 那一次写整个漏掉时，**等多久都没用**。复现条件最后
+  定位到 **stdout 被管道捕获**（`verify-all.sh` 的 `out=$(bash -c …)` 与 CI 都是这么跑的）：
+  管道下稳定红、重定向到文件稳定绿；单跑套件也是绿的。改成 `writeUntilSeen`（反复写、直到
+  回调真的来，上限 15 秒）—— **断言没放宽**（那个路径仍必须触发一次回调，只是不再要求
+  「第一次写就被看见」），四条「不该触发」的负向用例一条未动。
+  ⚠️ **仅测试侧，无使用者可见行为**：生产里 dev 环**先建立监视、再对外服务**，不存在
+  「`watchTree()` 一返回用户就改文件」这个窗口。
+
+### 文档
+
+- `docs/usage-guide.md` §2.2：按使用者口吻补三段 —— Markdown 渲染口径（含协议白名单与
+  「用户轮保持字面」）、滚动三层各管一段、长正文折叠阈值与展开控件位置。
+- `docs/guards.md` §1.4：新增 `markdown.test.mjs` 一行（两条安全断言：按构造不产生 HTML、
+  链接协议白名单 + 两条反向验证），并把 `inspector.test.mjs` 那行的反向全覆盖**扩面**记上
+  （覆盖所有自建模块 + 四条页面级不变量）—— 是**扩面**，别读成「多了五条守卫」。
+- `docs/spec.md` §10 2026-09-22 **⑨**：本轮三处可读性改动的现场证据与修法，外加两条踩坑
+  （反向验证的变异体**必须能编译**，否则构建先失败、门禁空跑；对被格式化过的文件做 patch
+  时 `old_string` 用了格式化**前**的版本，靠「改完立刻回读」才发现）。
+- `docs/plans/2026-09-22-dev-debug-loop.md`：补本轮三处的落地记录。
+
+## [0.9.1] - 2026-09-22
+
+### 新增 · dev 面板的实时右栏（在飞就看得到调用树）
+
+- **右栏从「收尾才有」变成「一个个长出来」**：runner 订阅框架的增量记账出口
+  （`onTraceEvent`，0.8.3 已落地）逐笔 `POST /ingest-event` → 父进程**原样**广播
+  （SSE 的 `dev` 命名事件多一类 `trace-event`）→ 面板按 `seq` 折回一棵**临时**的树。
+  收尾那份整棵 trace 回来时**覆盖**它（缺的 span 由那份补齐）。纪律与框架同名出口一致：
+  **不保证送达**，所以刷新页面之后早先那些 span 不会回来（收尾那份会补）。
+  计划 §D7 的评审补充点名要求的那条（P1b 面板侧工作）这轮落地。
+  折回逻辑是**纯逻辑 + 单测**（`panel-logic.ts` 的 `applyTraceEvent`），e2e-dev 另有一条
+  「帧必须先于 run-done 到达，且折回逐字等于收尾的整棵 trace」的真进程断言。
+
+### 变更 · 工作目录选择器：文件可选、隐藏目录可达、`浏览…` 不再是开关
+
+- **文件也能选**：`GET /api/fs` 现在分三类回（`dirs` / `dotDirs` / `files`；文件有上限，
+  超限时回 `filesTruncated`）。点文件名 = 工作目录取它**所在的**目录 + prompt 为空时填文件名
+  （你已经写好的 prompt **一个字不动**）。旧形态只列目录 ⇒「让 agent 看某个文件」只能靠自己打名字。
+- **隐藏目录单列**（不再整批过滤）：`.git` / `~/x/.y` 这类目录以前**根本点不进去**
+  （`..` 只能退到它上面，进不去）。
+- **`浏览…` 不再当开关**：以前面板开着时再点一次只是把它关掉，于是「在输入框敲了路径 → 点浏览」
+  这个最自然的动作是**把面板关掉**。现在点它**总是**按输入框里的路径打开，点面板外面收起。
+
+### 修复
+
+- **跑完的回复被面板自己擦掉（端到端实测 17 ms）**：`run-done` 与「这条 trace 的收尾帧」
+  几乎同毫秒到达，而 `open()`（收尾帧触发的自动打开）**无条件**清回复 ⇒ 刚写上去的那句立刻没了，
+  表现是「run 完成了，但面板上没有回复」。现在按「这条 trace 是不是这段回复的主人」判
+  （`panel-logic.replyBelongsTo`）：打开**别的** run 的 trace 照样清（防张冠李戴），
+  打开**刚跑完那一轮**的不清。
+- **在飞的树被收尾帧骗成「已完成」**：`playTrace` 以前对根 span 没有 `endedAt` 的树也调
+  `finish()`（根被标成 `●` + 耗时），而在飞时那是**假事实**。现在根没结束就不收尾（留 `◌`）——
+  该分支只对「在飞 / 截断」的树生效，收尾的整棵 trace 行为逐字未变。
+
+### 文档
+
+- `docs/usage-guide.md` §2.2：补「右栏是实时的」（含两条边界）与工作目录的三个点击语义。
+- `docs/guards.md` §1.4：本轮在**既有三行**登记上扩面（`panel-logic.test.mjs` 增四组折回 / 归属 /
+  浏览目标 / 选文件后的 prompt，`inspector.test.mjs` 增三项 HTTP 面，`e2e-dev.ts` 增第 7-bis 步），
+  见该节 —— 是**扩面**不是新增行，别把它读成「多了五条守卫」。
+- `docs/plans/2026-09-22-dev-debug-loop.md`：§D7 那条评审补充标注 **P1b 已落地**（增量出口接线）。
+- `docs/spec.md` §10 2026-09-22 **⑧**：本轮三处体验缺陷的现场证据与修法（右栏实时 / 回复被擦 /
+  选择器），外加一条发版流程教训（反向验证脚本必须先 commit）。
+
 ## [0.9.0] - 2026-09-22
 
 > 本版主题（窗口 `0.8.3 → 0.9.0`）：**dev 调试环落地** —— `agentia dev` 从「`tsx watch` 跑你的
@@ -1143,7 +1246,9 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/retrychx/agentia/compare/v0.9.2...HEAD
+[0.9.2]: https://github.com/retrychx/agentia/releases/tag/v0.9.2
+[0.9.1]: https://github.com/retrychx/agentia/releases/tag/v0.9.1
 [0.9.0]: https://github.com/retrychx/agentia/releases/tag/v0.9.0
 [0.8.3]: https://github.com/retrychx/agentia/releases/tag/v0.8.3
 [0.8.2]: https://github.com/retrychx/agentia/releases/tag/v0.8.2

package/README.md

@@ -36,7 +36,7 @@ npm run dev                          # = agentia dev：本地 inspector 面板
 > 从不执行 main.ts —— 写错一侧会让 `npm run dev` 静默读不到 `.env` 而 `npm start` 读得到。
 > 真实环境变量优先（CI / docker / 命令行永远赢过文件），`loadEnvFile({ override: true })` 才反过来。
 
-> **版本**：`0.9.0`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
+> **版本**：`0.9.2`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
 > `file:../..` 指向本仓库而不是 npm 版本 —— 跑的是**工作区代码**，理由见
 > [`examples/README.md`](examples/README.md) 的「依赖说明」。
 

package/dist/AGENTS.md

@@ -131,11 +131,33 @@ npx agentia --version            # CLI 版本（= -v）
 |---|---|
 | **prompt** | 输入框 + `↑`/`↓` 调回历史（像 shell）。面板上「点一下 = 一次**真** run」 |
 | **能力** | 多选，缺省全选。收窄的是**菜单**（主 agent 仍在环里），不是「只可能调它」—— 别的能力 `tools` 里的显式引用仍能调到被排除的那个 |
-| **工作目录** | 目录选择器（`浏览…`）。**它是这个环的主控件**：任务型 agent 的 prompt 几乎不变，变的是目录 |
+| **工作目录** | 目录选择器（`浏览…`）。**它是这个环的主控件**：任务型 agent 的 prompt 几乎不变，变的是目录。三个点击语义：点**目录名**进去 / 点 `..` 上一层 / **点文件名** = 把它**所在的**目录当工作目录（prompt 为空时顺手把文件名填进去，你写好的话一个字不动）；`.git` 这类**隐藏目录**单列在选择器末尾（可达但靠后）。`浏览…` **总是**按输入框里的路径打开 —— 敲了路径再点它就是打开那个路径（不是「再点一次关掉」）；点面板外面收起 |
 | **多轮** | 跟能力走：`src/dev.config.ts` 里 `multiTurn: [...]` 声明哪些能力该多轮，混选时取 **OR** 且面板**标出来源**（`多轮·trip-planner`） |
 
 `npm run dev -- "你的问题"` 可以直接把第一句 prompt 带上（等价于启动后在输入框里敲）。
 
+**右栏是实时的（在飞就看得到）**：run 一开跑，右栏就从空树开始，**span 一个个长出来**
+（`◌` = 还没结束，`●` = 已结束），收尾时用**整棵 trace** 覆盖一遍。实现走框架的增量记账出口
+（`onTraceEvent`，0.8.3）：runner 订阅 → 逐笔 `POST /ingest-event` → 父进程广播 → 面板按 `seq` 折回。
+两条边界（与框架同名出口一致，都写在文档里以免被当成缺陷）：
+
+- **不保证送达**：SSE 断了就断了，没有重放。所以「在飞的那棵树」是**临时的** —— 刷新页面之后
+  早先那些 span 不会回来（收尾的整棵 trace 会补齐它们），**收尾那份永远覆盖在飞的这份**。
+- 它只影响「此刻看到什么」，**不影响 run 本身**，也不影响落盘的 trace（那是另一条缝）。
+
+**模型正文按 Markdown 渲染**（最终回复 + 对话视图的助手轮）：标题 / 粗斜体 / 行内码 / 围栏码 /
+列表 / 引用 / 分隔线 / 链接。解析器是本仓自己写的（零依赖），**只产出 token 树、不碰 HTML** ——
+模型输出里的 `<script>` 只会显示成字面文本；链接只认 `http` / `https` / `mailto`，其余协议
+（`javascript:` 等）**整条降级成字面文本**（连 `[]()` 一起显示）。你自己那一轮保持字面 ——
+那是你打的字，面板不改写它。
+
+**长正文默认折叠**：超过 12 行或 1200 字符的正文卡在 216px + 底部渐隐，下方左对齐一个
+「展开全文（共 N 行）▾」，展开后变「收起 ▴」。**短正文不挂控件**。
+
+**滚动分三层，各管一段**：整页**不滚**（输入条永远贴在底部，不会被内容推走）；左栏列表自己滚；
+右栏**只有调用树是滚动区** —— 它随 span 数无界增长，而回复 / 能力排行 / 用量固定在下方、
+各有上限（回复很长时在**它自己那块**里滚，不会把树挤出屏幕）。窄屏（≤860px）回落成单列 + 整页滚动。
+
 **为什么用 `agentia dev` 而不是 `tsx watch`**：`agentia dev` 自己 import 你的 `src/app.ts` 并驱动它，
 于是**它才是调用方**，四个输入才可能生效。它也**自己管文件监视**（不再叠一层 `tsx watch`）：
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const AGENTIA_VERSION = "0.9.0";
+export declare const AGENTIA_VERSION = "0.9.2";
 export type { Trace, Span, SpanEvent, SpanError, SpanId, SpanKind, SpanLink, SpanStatus, TraceId, TraceContext, TraceSink, TraceRecordEvent, CapabilityType, Usage, Score, } from './core/trace.js';
 export { attachScore, parseTraceparent } from './core/trace.js';
 export type { AgentTool, ApprovalDecision, JsonSchema, ModelClient, RecorderBackend, SchemaInput, SchemaType, ToolRunContext, TypedSchema, } from './core/tool.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export const AGENTIA_VERSION = '0.9.0';
+export const AGENTIA_VERSION = '0.9.2';
 export { attachScore, parseTraceparent } from './core/trace.js';
 export { validateJsonSchema } from './core/schema.js';
 export { combineSignals } from './core/abort.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/agentia",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。",
   "type": "module",
   "main": "dist/index.js",