# 需求追踪 (requirements-trace.md)

逐条对应原始需求。标记：✅ 已实现（等待 UI 走查） / ⚠️ 有工程折衷 / 🔜 后续。

## 1. UI + IDE：事件流 waterfall

| 需求 | 实现 | 位置 |
| --- | --- | --- |
| 侧边栏「新建会话/添加工作区/搜索」下方新增图标 | ⚠️ shipped 壳层在“新建会话按钮下的浏览区”**没有可加插的槽位**：`sidebar.workspaces` 是 single（占领=重写整个会话浏览区，违背"不遮蔽 shipped UI"）。采用官方可加性座席 **`sidebar.footer.action`**（设置旁，wide 模式显示"插件工作室"+拼图图标）。如需严格位置，可改走 `sidebar` 整列接管（不推荐，需自行重现会话列表）。 | client/10-shell.js |
| 拼图简笔画图标 | Lucide puzzle 路径，SVG 内联 | client/00-util.js `__PuzzleIcon` |
| 进入专属「事件流」UI 子界面 | 面板第一个 tab「事件流」 | client/20-waterfall.js |
| 滚动的 Event 树——发生了什么 | `internal/dispatch` 全量捕获，环形缓存；列表秒级刷新（400ms 轮询，Host→Client 无公开推送通道） | host/10-event-capture.js |
| 过滤器 | 文本搜索 + 模式过滤（emit/waterfall/serial/parallel/bail/bus）+ 分类芯片（agent/tools/llm/session/workflow…）+ 实时/暂停 | client/20-waterfall.js |
| 默认 500 的缓存限制 | `state.json.cap`=500，UI 可调 50–10000，超限截断，仅内存 | host/10, host/30 |
| 不具备持久化 | ring 每次进程重启清零；无任何落盘 | — |

## 2a. 事件与插件一览表

| 需求 | 实现 |
| --- | --- |
| 事件类型 + 插件输入/输出信息 | typert 反射（服务成员/事件签名/JSDoc）→「事件目录」表 + 插件矩阵 |
| 反射思考 | 用真实反射机制 `typert.listPackages()`（比字符串猜测更强） |
| 图的方式展现 | SVG 二列关系图（事件 ↔ 插件连线 —— studio 插件为精确监听边，系统插件显示装载/接口） |

## 2b. 插件包组合

| 需求 | 实现 |
| --- | --- |
| 持久化的事件插件一览表关系 | catalog.json（插件）/ annotations.json（事件表头注释）/ sets.json（组合） |
| set of plugins：组合代名 + 插件集合 | 组合 = 名称 + members（plugin 或嵌套 set） |
| 允许嵌套 | `{kind:'set'}` 成员 + 环检测 + 递归 flatten |

## 3. 插件管理

| 需求 | 实现 |
| --- | --- |
| 插件备选：可持久化文件位置 | `<storeRoot>/catalog.json`（+ installed/ 目录） |
| 模式预设：动态插件模式 | 工作室即"动态插件模式"主机：插件不依赖 session-create 迭代，全部经目录管理。 |
| "安装插件"：github → 内化为备选 | `shell git clone` → `installed/<slug>` → 记录到目录；模块导入经 `loader.create` |
| "写改插件"：写插件放在管理位置 | plugins 列表 + 开发包（dev-packages，含本地文件镜像） |
| 卸载（带警告，连带更新插件包） | 移除确认框；同时清理组合中的引用 |
| 监控 & 更改启动状态（绿/红） | 动态插件：已启动绿/未启动红；系统分区：active+enabled 绿，否则红（loader 可启停） |
| 系统插件 / 动态插件分区 | 两个独立区块（loader entries / studio catalog） |
| 插件组合启动状态（全启绿/全停红/部分黄） | `setStatus`：started/total → 颜色 |
| 记录启停情形，下次 webUI 启动询问恢复 | `state.json.lastSnapshot` + 启动 diff → 面板横幅"恢复/忽略" |

## 4. 插件开发（低代码）

| 需求 | 实现 |
| --- | --- |
| 插件包 = 若干监听插件 | 开发包(package) → listeners[ ] |
| 下拉菜单：hook 了什么 | 事件下拉（datalist：typert 反射 ∪ annotations），例：工具调用→执行前、llm/stream→每次模型调用前后 |
| 选完智能推断监听到的东西 | 按签名/注释解析参数名+说明，自动填参数行（可编辑） |
| 旁边 code switch | 每个监听器有"code"开关：预设 ↔ 生成代码（`ctx.on('evt', async (a,b) => {…})`） |
| 回转预设失败 → 风险提示 + 确认清掉避免崩溃 | 解析失败弹确认：清空代码返回预设 or 保留继续 |
| 代码编辑器 + 函数体 | textarea 编辑器（Tab 缩进、行感、模板插入） |
| ctx.get(…) 调用模板（持久化配置） | `ctx-templates.json`，编辑器上方下拉插入 | 
| 整个插件包持久化 & 对应本地开发文件 | dev-packages.json（权威） + dev-packages/<id>/（manifest.json + listeners/*.js 镜像） |
| 集成：推到 3 变成插件集 | 「推送为插件」→ catalog.create（监听包→ listener 插件；触发器包→ trigger 插件） |

## 被动监控实验（触发器验证）

- 触发器包：间隔秒数 + 脚本（可用 ctx/emit/console），emit 的事件 x 进入事件流（mode=bus）。
- 「被动监控」：N 秒窗口 → 实时列出监控窗口内捕获的事件（bus + DSH 真实事件），
  验证"触发器让事件被正确触发"。能力受沙箱限制：真 DSH 事件只能由真实服务触发
  （如 llm 调用/工具执行），触发器直接"凭空 emit 事件"走工作室 bus（见 architecture §3）。