@migor/agentia 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -5,7 +5,64 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
-## [Unreleased]
+## [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
 
@@ -44,9 +101,12 @@
 ### 文档
 
 - `docs/usage-guide.md` §2.2：补「右栏是实时的」（含两条边界）与工作目录的三个点击语义。
-- `docs/guards.md` §1.4：新增五条守卫登记（见该节）。
-- `docs/plans/2026-09-22-dev-debug-loop.md`：§D7 那条评审补充标注 **P1b 已落地**。
-- `docs/spec.md` §10 2026-09-22 ⑦：本轮三个缺陷的现场证据与修法（含「同一条事实两个表面」的第 N 个影子）。
+- `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
 
@@ -1186,7 +1246,8 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.9.1...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

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.1`（`@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

@@ -145,6 +145,19 @@ npx agentia --version            # CLI 版本（= -v）
   早先那些 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.1";
+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.1';
+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.1",
+  "version": "0.9.2",
   "description": "面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。",
   "type": "module",
   "main": "dist/index.js",