@sepveneto/dnde-agent 0.2.0-beta.9 → 0.2.1

package/README.md

@@ -1,17 +1,20 @@
 # `@sepveneto/dnde-agent`
 
-装修助手以一个独立自定义元素接入编辑器。Agent 实现来自
-`llm-agent`：Agents SDK 负责 Agent Loop、工具调用、流式输出和会话历史；
-本包只保留 Web Component 外壳、宿主 API 协议和业务工具适配。
+`@sepveneto/dnde-agent` 提供 Web Component 外壳和最小 Agent Runtime。运行时本身只有
+一个主 Agent；主 Agent 不持有任何 function tool，只通过 handoff 调度宿主提供的子
+Agent。
+
+本包同时公开版本化的编辑器 DSL，以及给宿主子 Agent 使用的 DSL 工具。具体业务角色、
+业务工具和编辑策略均由宿主定义。
 
 ## 接入
 
-宿主提供编辑器 API、业务工具和运行时上下文：
+宿主提供模型配置、编辑器 DSL API、子 Agent 和运行上下文：
 
 ```vue
 <dnd-agent
   :api="agentApi"
-  :tools="businessTools"
+  :sub-agents="subAgents"
   :context="getContext"
 ></dnd-agent>
 ```
@@ -31,112 +34,187 @@ register({
 })
 ```
 
+编辑器侧通过 `<mpd-editor :agent-sub-agents="subAgents">` 注入子 Agent。
+
+## Runtime 边界
+
+- 运行时只构造固定主 Agent `Diy Copilot`。
+- 主 Agent 的 `tools` 始终为空，只负责分诊和 handoff。
+- 子 Agent 由宿主定义，或直接注入已经构造好的 Agents SDK `Agent`。
+- 子 Agent 负责实际分析、业务查询和页面编辑。
+- 子 Agent 完成任务后通过 `transfer_back_to_main` 将控制权交还主 Agent。
+- 未提供匹配子 Agent 时，主 Agent 会说明当前能力不足，不会自行读取或修改页面。
+
+这种边界可确保业务权限、工具实现和具体编辑策略不进入 Agent Runtime。
+
 ## 宿主 API
 
+编辑器向 Runtime 提供查询、校验和应用 DSL 所需的能力；宿主需要将导出的 DSL 工具
+显式加入具体子 Agent 的 `tools`：
+
 ```ts
-interface AgentHostApi {
-  model?: {
-    baseURL?: string
-    model?: string
-    apiMode?: 'responses' | 'chat_completions'
-  }
-  editor?: {
-    getCurrentEditor: () => unknown | Promise<unknown>
-    getWidgets: () => unknown | Promise<unknown>
-    operateEditor: (operation: AgentEditorOperation) => unknown | Promise<unknown>
-  }
+import type { AgentHostApi } from '@sepveneto/dnde-agent'
+
+const agentApi: AgentHostApi = {
+  model: {
+    baseURL: 'http://localhost:4000/v1',
+    model: 'qwen3.6-plus',
+    apiMode: 'responses',
+  },
+  editor: {
+    getCurrentEditor: () => editor.getAgentEditor(),
+    getWidgets: () => editor.getCapabilities(),
+    validateDsl: dsl => editor.validateDsl(dsl),
+    applyDsl: dsl => editor.applyDsl(dsl),
+    undo: revision => editor.undo(revision),
+  },
 }
 ```
 
-默认带三个基于编辑器 API 的工具：`get_current_editor`、`get_widgets`、
-`editor_operator`。写操作和历史不可逆操作应先取得用户确认。
+`<mpd-editor>` 会自动注入这组编辑器 API，业务宿主通常只需配置 `model`。
+
+## 宿主子 Agent
+
+宿主直接使用 OpenAI Agents SDK 创建子 Agent，并将 `Agent[]` 传给编辑器：
+
+```ts
+import {
+  Agent,
+  createEditorDslTools,
+  type AgentSubAgent,
+} from '@sepveneto/dnde-agent'
+
+const editorTools = createEditorDslTools(agentApi)
+
+const pageAgent = new Agent({
+  name: 'Page Agent',
+  handoffDescription: '处理页面布局、组件编辑和业务数据查询。',
+  model: 'qwen3.6-plus',
+  instructions: [
+    '先调用 get_current_editor 和 get_widgets。',
+    '页面修改必须通过 apply_editor_dsl 提交完整、版本化的 DSL。',
+    '任务全部完成后调用 transfer_back_to_main 交还控制权。',
+    '需要用户补充信息时不要交还，等待用户回复后继续当前任务。',
+  ].join('\n'),
+  tools: [
+    ...editorTools,
+    queryProduct,
+    queryCoupon,
+  ],
+})
+
+const subAgents: AgentSubAgent[] = [pageAgent]
+```
+
+运行时会创建子 Agent 的轻量副本，并追加 `transfer_back_to_main` handoff；模型、工具、
+结构化输出和宿主原有的 `handoffs` 保持不变。子 Agent 完成任务后交还控制权，由主 Agent
+统一回复用户。
 
-### 初始化与增量修改
+只读子 Agent 不添加 `editorTools` 即可，不会自动获得文档修改能力。结构化输出等其它
+SDK 能力直接在创建 Agent 时配置 `outputType`。
 
-Agent 会先读取 `get_current_editor` 的快照，再结合用户当前消息、聊天记录和
-附件内容判断工作模式：
+## 编辑器 DSL
 
-- **初始化**：用户要求按清单、文档或整页需求从零创建页面，或明确要求重建；
-- **增量修改**：用户要求在现有页面上新增、编辑、删除或移动局部内容。
+Agent 不提供节点级增删改工具，而是将完整 DSL 作为一个受校验、可批量执行的操作批次：
 
-页面已有内容、但请求又像是一份完整清单时，Agent 会先向用户确认是否覆盖，
-不会自行清空页面。初始化和增量修改都可以通过同一个 `editor_operator` 写入，
-统一按普通编辑流程依次调用组件查询、业务工具和 `editor_operator`。初始化不会
-使用单独的子 Agent 或专用初始化工具。
+```ts
+interface EditorDsl {
+  dslVersion: '1.1'
+  baseRevision: number
+  scope: {
+    mode: 'style_only' | 'content_only' | 'layout_only' | 'any'
+    targets: string[]
+  }
+  operations: Array<
+    | {
+        op: 'add'
+        key: string
+        widget: string
+        placement?: {
+          afterUuid?: string
+          beforeUuid?: string
+          afterKey?: string
+          beforeKey?: string
+          group?: string
+        }
+        props?: Record<string, unknown>
+        style?: Record<string, unknown>
+        custom?: DslCustomOperation[]
+      }
+    | {
+        op: 'update'
+        uuid: string
+        props?: Record<string, unknown>
+        style?: Record<string, unknown>
+        custom?: DslCustomOperation[]
+      }
+    | {
+        op: 'delete'
+        uuid: string
+      }
+  >
+}
+```
 
-### 图片参考
+`baseRevision` 必须来自 `get_current_editor`。宿主在应用前校验 revision、组件能力、
+字段作用域；整批操作由编辑器原子执行。
 
-输入框支持多选和分批追加附件，包括 `.docx` 文档以及 JPG、PNG、WebP、BMP、
-TIFF、HEIC 图片；一次最多 6 个附件、总计不超过 20 MB。例如可以同时上传一份
-装修文档和一张参考图。文档会逐个转换为文本上下文，所有图片会作为多模态内容
-一起发送。图片上传后显示缩略图，Agent 会按以下顺序执行：
+### 公开 DSL 工具
 
-1. 解析图片的布局、层级、间距、比例、配色和组件关系，确定需要的组件角色及数量；
-2. 查询可用组件，结合组件功能描述和清单配置需求，先规划每个组件承载的内容；
-3. 整页组件和内容计划完成后，再查询业务数据、准备填充内容并调用 `editor_operator`。
+`createEditorDslTools(api)` 是可选导出，不会由 Runtime 自动注册。将返回值展开到某个
+子 Agent 自己的 `tools` 中后，该子 Agent 才会获得以下工具：
 
-图片中的业务数据不会被当作真实接口数据，商品等内容仍须通过宿主业务工具准备。
+| 工具 | 作用 |
+| --- | --- |
+| `get_current_editor` | 读取文档、选中节点和 revision |
+| `get_widgets` | 读取组件能力目录 |
+| `validate_editor_dsl` | 校验 DSL，不修改文档 |
+| `apply_editor_dsl` | 校验后一次性应用 DSL |
+| `undo_editor_dsl` | 按 revision 撤销最近一次 DSL 操作 |
 
-本地图片遵循千问 OpenAI 兼容接口的多模态格式：BFF 将图片转换为
-`data:image/<type>;base64,...`，与文本一起放入同一条用户消息。会话历史保存
-图片引用而不是 Base64，避免撑满浏览器 `localStorage`。例如把 `qwen3.6-plus`
-作为模型时，可以直接使用“参考这张图的布局设计首页”这类指令。包含图片的
-Qwen 对话会使用官方文档中的 Chat Completions 兼容格式；纯文本对话继续遵循
-宿主配置的 API 模式。
+也可以通过 `CreateEditorDslToolsOptions` 只注册需要的工具。不需要编辑器能力时，
+直接省略 `createEditorDslTools(api)`。
 
-图片输入格式参考千问官方文档：
-<https://help.aliyun.com/zh/model-studio/vision>。
+所有 DSL 类型，包括 `EditorDsl`、`DslOperation`、`DslValidationResult`，均从
+`@sepveneto/dnde-agent` 导出。
 
-### 添加组件时的业务数据
+## 业务工具
 
-`items` 通常是由业务 ID 查询并组装的复杂数据，不能交给模型生成。业务工具
-应把组装结果写入当前 Agent Run 的 Context，`editor_operator` 会在 `add`
-时自动注入，并在操作成功后一次性消费：
+业务工具属于宿主，由宿主挂到具体子 Agent 上。工具可以把需要跨工具共享的数据写入
+当前 Run 的 Context：
 
 ```ts
-const queryProduct = defineAgentTool({
+import { tool } from '@sepveneto/dnde-agent'
+
+const queryProduct = tool({
   name: 'query_product',
   description: '查询商品并准备添加到编辑器。',
-  parameters: z.object({ keyword: z.string() }),
-  async execute({ keyword }, toolContext) {
+  parameters: {
+    type: 'object',
+    properties: {
+      keyword: { type: 'string' },
+    },
+    required: ['keyword'],
+    additionalProperties: false,
+  },
+  strict: false,
+  async execute(input, runContext) {
+    const { keyword } = input as { keyword: string }
     const product = await api.product.search(keyword)
-    const items = await api.product.buildEditorItems([product.id])
-
-    // 只返回模型需要做决策的轻量信息。
-    toolContext.context.pendingItems = items
+    runContext.context.product = product
     return { id: product.id, name: product.name }
   },
 })
 ```
 
-模型随后只调用
-`editor_operator({ action: 'add', widget: 'product', target: '页面节点 UUID' })`。
-工具参数不包含 `items`；即使模型额外传入也会被移除。每次 Agent Run 都会
-创建独立的 Context，失败时保留待添加数据以支持同一轮重试，成功后清空。
-同一轮模型回复中的 function tools 会按调用顺序串行执行，保证前序工具写入的
-Context 在后续工具（例如 `editor_operator`）执行时已经可见。
-
-## 业务工具
-
-```ts
-import { defineAgentTool } from '@sepveneto/dnde-agent'
-import { z } from 'zod'
-
-const queryOrder = defineAgentTool({
-  name: 'query_order',
-  description: '查询订单状态',
-  parameters: z.object({ id: z.string() }),
-  async execute({ id }, context) {
-    return fetch(`/api/orders/${id}`).then(response => response.json())
-  },
-})
-```
+宿主初始 Context 会复制到当前 Run。模型请求走宿主代理或 BFF，浏览器侧不保存真实
+密钥。
 
-工具的 `execute` 在浏览器内运行，并可读取宿主通过 `context` 注入的只读上下文。
-模型请求走兼容 OpenAI 的宿主代理/BFF，浏览器侧不保存真实密钥。
+## 附件与会话
 
-## UI
+输入框支持多选附件，包括 `.docx`、JPG、PNG、WebP、BMP、TIFF 和 HEIC；一次最多
+6 个附件、总计不超过 20 MB。文档会转换为文本上下文，图片以千问 OpenAI 兼容的多模态
+格式发送。会话历史保存图片引用而不是 Base64。
 
-UI 保留原装修助手的悬浮按钮交互。展开后使用 `llm-agent` 的聊天视图：
-空状态示例、图片/文档附件、Markdown、reasoning、工具调用、数据事件、流式文本、停止生成和历史记录，
-全部位于 `dnd-agent` 的 Shadow DOM 内。
+聊天 UI、流式输出、reasoning、工具调用、停止生成和历史记录全部位于
+`<dnd-agent>` 的 Shadow DOM 内。

package/dist/{agent-D0iJXvAv.js → agent-B8UEh-Q5.js}

@@ -1,7 +1,7 @@
 var V = Object.defineProperty;
 var Q = (t, s, e) => s in t ? V(t, s, { enumerable: !0, configurable: !0, writable: !0, value: e }) : t[s] = e;
 var a = (t, s, e) => Q(t, typeof s != "symbol" ? s + "" : s, e);
-import { C as E, U as x, r as X, t as I, o as v, s as y, a as Z, w as A, i as q, e as ee, A as te, n as k, b as R, p as C, c as se, S as ie, d as ne, M as re, f as ae } from "./index-DiCtdOy1.js";
+import { C as E, U as x, r as X, t as I, o as v, s as y, a as Z, w as A, i as q, e as ee, A as te, n as k, b as R, p as C, c as se, S as ie, d as ne, M as re, f as ae } from "./index-BxIDwmiL.js";
 function oe(t) {
   return t ? !(typeof t == "object" && t && "constructor" in t && typeof t.constructor == "function" ? t.constructor.name : "").includes("ChatCompletions") : !0;
 }

package/dist/agentInstructions.d.ts

@@ -1,2 +1,13 @@
-export declare function buildAgentInstructions(): string;
+export declare const MAIN_AGENT_NAME = "Diy Copilot";
+export interface MainAgentInfo {
+    name: string;
+    description: string;
+}
+/**
+ * The main agent is a dispatcher only. It owns no function tools and cannot
+ * inspect or mutate the editor directly.
+ */
+export declare function buildMainAgentInstructions(options?: {
+    subAgents?: MainAgentInfo[];
+}): string;
 //# sourceMappingURL=agentInstructions.d.ts.map

package/dist/agentInstructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentInstructions.d.ts","sourceRoot":"","sources":["../src/agentInstructions.ts"],"names":[],"mappings":"AAAA,wBAAgB,sBAAsB,WAmBrC"}
+{"version":3,"file":"agentInstructions.d.ts","sourceRoot":"","sources":["../src/agentInstructions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,gBAAgB,CAAA;AAE5C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,aAAa,EAAE,CAAA;CACvB,UAuBP"}

package/dist/agents.d.ts

@@ -1,20 +1,19 @@
-import type { AgentToolDefinition } from './tool';
-import type { AgentHostApi } from './types';
 import { Agent } from '@openai/agents';
 export declare const DEFAULT_AGENT_MODEL = "qwen3.6-flash";
 export declare const DEFAULT_AGENT_BFF_URL = "http://localhost:4000/v1";
+/** A host-created OpenAI Agents SDK Agent. */
+export type AgentSubAgent = Agent<any, any>;
 export interface CreateAgentsOptions {
     model?: string;
-    api: AgentHostApi;
-    tools?: AgentToolDefinition[];
-    getContext?: () => Record<string, unknown>;
+    subAgents?: AgentSubAgent[];
 }
 /**
- * llm-agent 的 Agent 定义已迁移到这里。业务工具通过 options.tools 注入，
- * 编辑器能力通过 options.api 注入，Agent 本身不持有宿主状态。
+ * Build the runtime topology. The main agent is always a dispatcher with no
+ * function tools; only host-provided sub-agents can perform work.
  */
 export declare function createAgents(options: CreateAgentsOptions): {
-    agent: Agent<any, "text">;
-    agents: Agent<any, "text">[];
+    agent: Agent<unknown, "text">;
+    subAgents: Agent<any, any>[];
+    agents: (Agent<any, any> | Agent<unknown, "text">)[];
 };
 //# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,KAAK,EAAwB,YAAY,EAAsB,MAAM,SAAS,CAAA;AACrF,OAAO,EAAE,KAAK,EAAQ,MAAM,gBAAgB,CAAA;AAQ5C,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AAClD,eAAO,MAAM,qBAAqB,6BAA6B,CAAA;AAE/D,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,YAAY,CAAA;IACjB,KAAK,CAAC,EAAE,mBAAmB,EAAE,CAAA;IAC7B,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC3C;AAuLD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB;;;EAyBxD"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAW,MAAM,gBAAgB,CAAA;AAG/C,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AAClD,eAAO,MAAM,qBAAqB,6BAA6B,CAAA;AAG/D,8CAA8C;AAC9C,MAAM,MAAM,aAAa,GAAG,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;AAE3C,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,aAAa,EAAE,CAAA;CAC5B;AAmBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB;;;;EAyCxD"}

package/dist/editorDsl.d.ts

@@ -0,0 +1,25 @@
+import type { FunctionTool } from '@openai/agents';
+import type { AgentHostApi } from './types';
+export declare const GET_CURRENT_EDITOR_TOOL_NAME = "get_current_editor";
+export declare const GET_WIDGETS_TOOL_NAME = "get_widgets";
+export declare const VALIDATE_EDITOR_DSL_TOOL_NAME = "validate_editor_dsl";
+export declare const APPLY_EDITOR_DSL_TOOL_NAME = "apply_editor_dsl";
+export declare const UNDO_EDITOR_DSL_TOOL_NAME = "undo_editor_dsl";
+export interface CreateEditorDslToolsOptions {
+    /** Include the current editor snapshot query. Defaults to true. */
+    currentEditor?: boolean;
+    /** Include the widget capability catalog query. Defaults to true. */
+    widgets?: boolean;
+    /** Include deterministic DSL validation. Defaults to true. */
+    validate?: boolean;
+    /** Include revision-bound undo. Defaults to true. */
+    undo?: boolean;
+}
+/**
+ * Build the complete model-facing editor contract. These tools are intended
+ * for host-owned sub-agents; the main dispatcher never receives them.
+ */
+export declare function createEditorDslTools(api: AgentHostApi, options?: CreateEditorDslToolsOptions): FunctionTool<any, any, any>[];
+/** Convenience alias for hosts that refer to this contract as editor tools. */
+export declare const createEditorTools: typeof createEditorDslTools;
+//# sourceMappingURL=editorDsl.d.ts.map

package/dist/editorDsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorDsl.d.ts","sourceRoot":"","sources":["../src/editorDsl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,gBAAgB,CAAA;AAC9D,OAAO,KAAK,EAEV,YAAY,EAEb,MAAM,SAAS,CAAA;AAGhB,eAAO,MAAM,4BAA4B,uBAAuB,CAAA;AAChE,eAAO,MAAM,qBAAqB,gBAAgB,CAAA;AAClD,eAAO,MAAM,6BAA6B,wBAAwB,CAAA;AAClE,eAAO,MAAM,0BAA0B,qBAAqB,CAAA;AAC5D,eAAO,MAAM,yBAAyB,oBAAoB,CAAA;AAqH1D,MAAM,WAAW,2BAA2B;IAC1C,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAwCD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,EACjB,OAAO,GAAE,2BAAgC,GACxC,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAgG/B;AAED,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,6BAAuB,CAAA"}