@sepveneto/dnde-agent 0.2.0-beta.1 → 0.2.0-beta.10

package/README.md

@@ -41,9 +41,9 @@ interface AgentHostApi {
     apiMode?: 'responses' | 'chat_completions'
   }
   editor?: {
-    getCurrentEditor(): unknown | Promise<unknown>
-    getWidgets(): unknown | Promise<unknown>
-    operateEditor(operation: AgentEditorOperation): unknown | Promise<unknown>
+    getCurrentEditor: () => unknown | Promise<unknown>
+    getWidgets: () => unknown | Promise<unknown>
+    operateEditor: (operation: AgentEditorOperation) => unknown | Promise<unknown>
   }
 }
 ```
@@ -51,6 +51,90 @@ interface AgentHostApi {
 默认带三个基于编辑器 API 的工具：`get_current_editor`、`get_widgets`、
 `editor_operator`。写操作和历史不可逆操作应先取得用户确认。
 
+### 初始化与增量修改
+
+Agent 会先读取 `get_current_editor` 的快照，再结合用户当前消息、聊天记录和
+附件内容判断工作模式：
+
+- **初始化**：用户要求按清单、文档或整页需求从零创建页面，或明确要求重建；
+- **增量修改**：用户要求在现有页面上新增、编辑、删除或移动局部内容。
+
+页面已有内容、但请求又像是一份完整清单时，Agent 会先向用户确认是否覆盖，
+不会自行清空页面。初始化和增量修改都可以通过同一个 `editor_operator` 写入，
+统一按普通编辑流程依次调用组件查询、业务工具和 `editor_operator`。初始化不会
+使用单独的子 Agent 或专用初始化工具。
+
+### 图片参考
+
+输入框支持多选和分批追加附件，包括 `.docx` 文档以及 JPG、PNG、WebP、BMP、
+TIFF、HEIC 图片；一次最多 6 个附件、总计不超过 20 MB。例如可以同时上传一份
+装修文档和一张参考图。文档会逐个转换为文本上下文，所有图片会作为多模态内容
+一起发送。图片上传后显示缩略图，Agent 会按以下顺序执行：
+
+1. 解析图片的布局、层级、间距、比例、配色和组件关系，确定需要的组件角色及数量；
+2. 查询可用组件，结合组件功能描述和清单配置需求，先规划每个组件承载的内容；
+3. 整页组件和内容计划完成后，再查询业务数据、准备填充内容并调用 `editor_operator`。
+
+图片、文档等参考附件可以辅助布局，包括层级、间距、比例、配色和组件关系。
+模型不参与数据选择、直填或拼装，只负责根据意图调用宿主工具。本项目的
+`query_internal_routes` 是内部路由意图工具：模型只传入页面名称、路由名称或
+路径关键词，宿主匹配 `entry.dialog` 的 `H5Entry` 静态路由，将结果写入
+`context.internalRoutes`，并把匹配路由准备到 `context.pendingItems`。
+`editor_operator` 后续自动注入宿主机准备好的数据，模型不得改写、推断或自行
+生成路由及其它填充数据。应用名称、卡券品牌、会员直充分类、落地页、商品、
+价格等接口动态内容不能从参考附件中提取或作为候选，只能根据用户当前请求中的
+需求清单并通过宿主业务工具获取或准备。所有填充内容都必须来自需求清单或宿主
+工具写入的 Context；清单中没有提供的内容不能从参考附件、模型推测或既有经验
+中补全，缺少必要内容时应先询问用户。参考附件中出现品牌信息不构成指定或授权。
+数据准备边界不影响编辑器 DSL 工具的正常调用：模型仍必须调用
+`get_current_editor` 读取页面、调用 `get_widgets` 查询组件，并通过
+`editor_operator` 添加、编辑、删除或移动节点。意图工具和业务工具只负责准备
+数据，不能替代编辑器 DSL 操作。
+`editor_operator` 的 add 操作只注入宿主工具写入 `pendingItems` 的数据。模型
+不可提交 `changes`：名称、跳转类型、分类等纯静态配置也不能通过 changes
+填充。静态配置白名单和路由查询只用于判断当前任务是否需要参考附件，不作为
+页面填充值来源。宿主内部的 changes 仍会经过组件 `agent.update`，不会由 DSL
+直接合并到节点数据。
+
+本地图片遵循千问 OpenAI 兼容接口的多模态格式：BFF 将图片转换为
+`data:image/<type>;base64,...`，与文本一起放入同一条用户消息。会话历史保存
+图片引用而不是 Base64，避免撑满浏览器 `localStorage`。例如把 `qwen3.6-plus`
+作为模型时，可以直接使用“参考这张图的布局设计首页”这类指令。包含图片的
+Qwen 对话会使用官方文档中的 Chat Completions 兼容格式；纯文本对话继续遵循
+宿主配置的 API 模式。
+
+图片输入格式参考千问官方文档：
+<https://help.aliyun.com/zh/model-studio/vision>。
+
+### 添加组件时的业务数据
+
+`items` 通常是由业务 ID 查询并组装的复杂数据，不能交给模型生成。业务工具
+应把组装结果写入当前 Agent Run 的 Context，`editor_operator` 会在 `add`
+时自动注入，并在操作成功后一次性消费：
+
+```ts
+const queryProduct = defineAgentTool({
+  name: 'query_product',
+  description: '查询商品并准备添加到编辑器。',
+  parameters: z.object({ keyword: z.string() }),
+  async execute({ keyword }, toolContext) {
+    const product = await api.product.search(keyword)
+    const items = await api.product.buildEditorItems([product.id])
+
+    // 只返回模型需要做决策的轻量信息。
+    toolContext.context.pendingItems = items
+    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
@@ -73,5 +157,5 @@ const queryOrder = defineAgentTool({
 ## UI
 
 UI 保留原装修助手的悬浮按钮交互。展开后使用 `llm-agent` 的聊天视图：
-空状态示例、Markdown、reasoning、工具调用、数据事件、流式文本、停止生成和历史记录，
+空状态示例、图片/文档附件、Markdown、reasoning、工具调用、数据事件、流式文本、停止生成和历史记录，
 全部位于 `dnd-agent` 的 Shadow DOM 内。

package/dist/{agent-BP3wmmgT.js → agent-I4tbZfvO.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-B_cPI3XS.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-hugwYSU_.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

@@ -0,0 +1,2 @@
+export declare function buildAgentInstructions(): string;
+//# sourceMappingURL=agentInstructions.d.ts.map

package/dist/agentInstructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentInstructions.d.ts","sourceRoot":"","sources":["../src/agentInstructions.ts"],"names":[],"mappings":"AAAA,wBAAgB,sBAAsB,WAmDrC"}

package/dist/agents.d.ts

@@ -15,5 +15,6 @@ export interface CreateAgentsOptions {
  */
 export declare function createAgents(options: CreateAgentsOptions): {
     agent: Agent<any, "text">;
+    agents: Agent<any, "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,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,KAAK,EAAQ,MAAM,gBAAgB,CAAA;AAG5C,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;AA4JD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB;;EA2BxD"}
+{"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;AAmLD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB;;;EAyBxD"}

package/dist/composables/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useFile';
+//# sourceMappingURL=index.d.ts.map

package/dist/composables/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/composables/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/dist/composables/useFile.d.ts

@@ -0,0 +1,12 @@
+import type { Ref } from 'vue';
+import type { AgentUploadedFile } from '../services';
+export declare function useFile(fileInput: Readonly<Ref<HTMLInputElement | null>>, getBaseURL: () => string): {
+    list: import("vue").ShallowRef<AgentUploadedFile[], AgentUploadedFile[]>;
+    uploading: Ref<boolean, boolean>;
+    error: Ref<string, string>;
+    selectFile: () => void;
+    handleFileChange: (event: Event) => Promise<void>;
+    reset: () => void;
+    remove: (name: string) => void;
+};
+//# sourceMappingURL=useFile.d.ts.map

package/dist/composables/useFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFile.d.ts","sourceRoot":"","sources":["../../src/composables/useFile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAWpD,wBAAgB,OAAO,CACrB,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC,EACjD,UAAU,EAAE,MAAM,MAAM;;;;;8BAuBe,KAAK;;mBAVtB,MAAM;EA6E7B"}

package/dist/editorContext.d.ts

@@ -0,0 +1,26 @@
+import type { AgentEditorOperation, EditorAgentContext } from './types';
+/**
+ * Create isolated editor/business state for one Agent Run.
+ *
+ * Host context is copied in as read-only starting data. `pendingItems` is
+ * always reset so data prepared by a previous turn cannot leak into this one.
+ */
+export declare function createEditorAgentContext(initial?: Record<string, unknown>): EditorAgentContext;
+export interface PreparedEditorOperation {
+    operation: AgentEditorOperation;
+    /** Items reserved for this add operation; cleared only after success. */
+    pendingItems?: unknown[];
+    error?: string;
+}
+/**
+ * Remove any model-produced items and, for add operations, inject the data
+ * prepared by a business tool for this run.
+ */
+export declare function prepareEditorOperation(input: unknown, context: EditorAgentContext): PreparedEditorOperation;
+export declare function editorOperationSucceeded(result: unknown): boolean;
+/**
+ * Consume pending items only after the editor confirms success. A failed
+ * operation keeps them available for a corrected retry in the same Run.
+ */
+export declare function completeEditorOperation(context: EditorAgentContext, prepared: PreparedEditorOperation, result: unknown): void;
+//# sourceMappingURL=editorContext.d.ts.map

package/dist/editorContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorContext.d.ts","sourceRoot":"","sources":["../src/editorContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,SAAS,CAAA;AAEhB;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,kBAAkB,CAKpB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,oBAAoB,CAAA;IAC/B,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,EAAE,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,kBAAkB,GAC1B,uBAAuB,CAoCzB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CASjE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,uBAAuB,EACjC,MAAM,EAAE,OAAO,GACd,IAAI,CAGN"}