@migor/agentia 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [Unreleased]
+
+## [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：新增五条守卫登记（见该节）。
+- `docs/plans/2026-09-22-dev-debug-loop.md`：§D7 那条评审补充标注 **P1b 已落地**。
+- `docs/spec.md` §10 2026-09-22 ⑦：本轮三个缺陷的现场证据与修法（含「同一条事实两个表面」的第 N 个影子）。
+
 ## [0.9.0] - 2026-09-22
 
 > 本版主题（窗口 `0.8.3 → 0.9.0`）：**dev 调试环落地** —— `agentia dev` 从「`tsx watch` 跑你的
@@ -1143,7 +1186,8 @@
 首个公开发布：`@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.1...HEAD
+[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.1`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
 > `file:../..` 指向本仓库而不是 npm 版本 —— 跑的是**工作区代码**，理由见
 > [`examples/README.md`](examples/README.md) 的「依赖说明」。
 

package/dist/AGENTS.md

@@ -131,11 +131,20 @@ 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（那是另一条缝）。
+
 **为什么用 `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.1";
 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.1';
 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.1",
   "description": "面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。",
   "type": "module",
   "main": "dist/index.js",