dsh-plugin-agentflow 0.2.3 → 0.3.1

package/README.md

@@ -80,7 +80,7 @@ CC19990113/dsh-plugin-agentflow
 
 ![深色](docs/images/canvas-dark.png)
 
-主题跟随 DSH：插件把当前主题拼进 iframe 地址，画布启动时按它初始化；手动切换只在本次会话内生效，DSH 重开时重新读配置。
+主题跟随 DSH：内联（`native`）模式下画布直接读宿主主题（`body[data-ds-dark-theme]` / `html.dark` / 系统偏好），切换时实时推送；`iframe` 回滚模式仍把主题拼进地址，画布启动时按它初始化。手动切换只在本次会话内生效，DSH 重开时重新读配置。
 
 ## 架构
 
@@ -88,16 +88,18 @@ CC19990113/dsh-plugin-agentflow
 DSH 桌面
 ├── 插件（index.js）
 │   ├── 工具：agentflow_list / agentflow_run
-│   ├── 客户端：侧边栏入口、设置页分区、画布 iframe
-│   └── 子进程：node runtime/server.mjs → 127.0.0.1:8791
+│   ├── 客户端：侧边栏入口、设置页分区、主视图画布
+│   │   ├── src/canvas   画布源码（构建时编进客户端 bundle）
+│   │   └── src/host     宿主桥：API 基地址 / 主题 / 样式注入
+│   └── 子进程：node runtime/server.mjs → 127.0.0.1:8791（只提供 API）
 │       ├── engine.mjs   纯 DAG 执行器
 │       ├── llm.mjs      调模型（只走 bridge）
-│       └── web/dist     画布前端
+│       └── web/dist     独立画布页面（iframe 回滚模式用）
 └── llm bridge（lib/bridge.js）
     └── 把 ctx.llm 暴露给引擎，模型调用始终在 DSH 进程内
 ```
 
-`runtime/` 是打包时从引擎仓库同步过来的副本（`npm run sync`），所以插件自带完整引擎，装完即用。
+`runtime/` 是打包时从引擎仓库同步过来的副本（`npm run sync`），所以插件自带完整引擎，装完即用。画布源码（`src/canvas/`）由同一次同步带来、构建时一起编进客户端 bundle：默认 `native` 模式下画布直接长在 DSH 主视图里，8791 只负责 API；配成 `iframe` 则回滚到嵌入 `web/dist` 独立页面的旧行为。
 
 ## 配置
 
@@ -106,6 +108,8 @@ DSH 桌面
 | 数据目录 | `~/.dsh/agent-flow-data` | 首次启动会自动从 `~/.dsh/agent-flow/data` 迁移 |
 | 后端端口 | `8791` | 可用 `agentflowPort` 插件配置改 |
 | 预设 profile | `desktop` | 用环境变量 `AGENTFLOW_PROFILE` 指定别的 profile |
+| `agentflowRenderMode` | `native` | 画布渲染方式：`native` 把画布编进客户端 bundle 直接渲染；`iframe` 回滚到嵌入独立画布页面 |
+| `agentflowUrl` | `http://127.0.0.1:8791` | `native` 下作为 API 基地址；`iframe` 下作为画布页面地址 |
 
 ## 限制
 
@@ -113,14 +117,17 @@ DSH 桌面
 - 运行态是全局的：跑图时切换画布，事件会被丢弃；「停止」不分画布
 - 验证跑图会真实调用模型，注意 token 消耗
 - 预设依赖 DSH profile 的 patch 机制，profile 结构变了要跟着调整
+- 宿主客户端运行时是 **React 18**；画布源码来自 React 19，但只使用两者共有的 API（不用 19-only API）
+- 画布样式靠 `.af-canvas` 作用域隔离（Tailwind 的 `:root` 变量收进容器内），不污染宿主页面
+- **`npm run sync` 会清空重建 `src/canvas/`**：为内联渲染做的适配改动会被引擎源码覆盖，改完需要重做
 
 ## 开发
 
 ```bash
-npm run build   # 构建客户端 bundle（lib/client.js）
-npm run sync    # 从 ~/.dsh/agent-flow 同步引擎到 runtime/
-npm run check   # 语法检查
-npm test        # 插件自测（83 项）
+npm run build   # 构建客户端 bundle（lib/client.js，含画布）
+npm run sync    # 从 ~/.dsh/agent-flow 同步引擎到 runtime/，并把画布源码同步到 src/canvas/
+npm run check   # 语法检查 + tsc --noEmit
+npm test        # 插件自测（152 项：bridge 83 + client bundle 69）
 ```
 
 引擎侧测试在 `~/.dsh/agent-flow/test`（85 项）。
@@ -130,9 +137,9 @@ npm test        # 插件自测（83 项）
 发布由 **GitHub Release 触发**，不在本地手动 `npm publish`：
 
 1. 升 `package.json`（和 `package-lock.json`）的版本号
-2. 打 tag 并创建 Release：`gh release create v0.2.3 --title "v0.2.3" --notes-file notes.md`
+2. 打 tag 并创建 Release：`gh release create v0.3.0 --title "v0.3.0" --notes-file notes.md`
 3. Release 发布后 [`.github/workflows/publish.yml`](.github/workflows/publish.yml) 自动执行：
-   `npm ci` → 语法检查 → 自测 → 构建客户端 → 校验提交的 `lib/client.js` 与源码构建一致 → 校验 tag 与 `package.json` 版本一致 → `npm publish --provenance`
+   `npm ci` → 语法检查 → 构建客户端 → 自测（含客户端 bundle 自测）→ 校验提交的 `lib/client.js` 与源码构建一致 → 校验 tag 与 `package.json` 版本一致 → `npm publish --provenance`
 
 需要仓库 secret `NPM_TOKEN`：npm granular token，权限选 `Read and write (publish and stage)`，并勾选 `Bypass two-factor authentication`。