打印设计插件包

同一个包提供两个代码入口和一个样式入口：

• @canvas-components/print-design-plugin/native：原生组件注册表，供 Canvas/HTML 打印端使用，不加载 React。
• @canvas-components/print-design-plugin/react：左侧菜单、元素创建、右侧属性与数据编辑配置；同时包含原生注册表，供 React 设计器使用。
• @canvas-components/print-design-plugin/style.css：React 插件的专用界面样式，使用设计器时由宿主显式导入。

在 React 设计器中使用

从包根导入样式；只导入 /react 不会自动加载插件面板样式。一个应用入口导入一次即可，独立打印服务只使用 /native，不需要 CSS。

import "@canvas-components/print-design-plugin/style.css";
import { ReactPrintDesign } from "@canvas-components/react-print-design";
import { builtinPrintDesignPlugins } from "@canvas-components/print-design-plugin/react";

export function PrintEditor() {
  return (
    <div style={{ height: 720 }}>
      <ReactPrintDesign
        componentRegistry={builtinPrintDesignPlugins.componentRegistry}
        componentFactories={builtinPrintDesignPlugins.componentFactories}
        componentMenu={builtinPrintDesignPlugins.componentMenu}
        propertySections={builtinPrintDesignPlugins.propertySections}
        contextMenus={builtinPrintDesignPlugins.contextMenus}
        tools={builtinPrintDesignPlugins.tools}
        pluginCatalog={builtinPrintDesignPlugins.pluginCatalog}
      />
    </div>
  );
}

第三方组件通过 registerPrintDesignPluginPackages 与内置注册表合并，再将返回的同名字段传给设计器；独立打印端使用同版本的 componentRegistry。完整接入示例见当前版本示例。

AI 对话插件

AI 对话位于本包的 src/ai-chat/，由宿主按需装配；未装配时设计器不显示 AI 按钮。按钮位于全屏按钮旁，右侧对话面板默认收起。输入框按 Enter 发送，Shift+Enter 换行；下方的更多按钮旁可切换当前模型和思考程度，未获取模型列表时模型选择器显示空列表。底部输入框的“更多 AI 设置”打开固定高度的配置对话框：左侧选择“基础配置”“外观配置”或“历史对话”，右侧显示内容。“基础配置”可维护多个连接，每个连接独立保存 Base URL、API Key、当前模型、思考程度和获取到的模型列表；修改 URL 或密钥后需重新获取列表。思考程度提供默认、低、中、高选项；默认时不向模型服务发送 reasoning_effort。“历史对话”可选择已有会话，删除时需要再次确认。旧版单连接配置会在读取时转换。

画布选中图层或组件时，输入框上方显示当前选中元素的名称与可读文本摘要。可从 Chat 的目标卡片中单独移除元素，不改变画布选区；移除项不会进入本轮选区摘要或 Agent 的 get_selection 结果。发送消息会把保留项的页面 ID 和元素 ID 作为本轮 Agent 的修改目标；模型通过 get_element 读取完整内容后再修改，聊天记录仍只显示用户输入的原文。画布选区改变后，Chat 目标会按新的选区重置。

import { createPrintDesignAiChatPlugin } from "@canvas-components/print-design-plugin/react";

<ReactPrintDesign
  aiChatPlugin={createPrintDesignAiChatPlugin({
    defaultConfig: {
      baseUrl: "https://example.com/v1",
      model: "example-model",
    },
  })}
/>;

默认连接器使用 OpenAI 兼容的 /v1/models 和 /v1/chat/completions，并通过核心包的 createPrintDesignAgentApi 将读取文档、选区和编辑命令作为模型工具提供。Agent 可列出已注册组件、读取默认模板，并基于组件工厂创建表格等插件元素；表格插入行列和合并单元格复用组件命令。其他协议可通过 provider 选项替换。模型配置使用浏览器 Web Crypto 加密后保存在 IndexedDB；非 HTTPS 且非 localhost 的页面只能在本次会话中使用自定义模型配置。浏览器端内置的 API Key 会随前端代码交付，无法作为产品方秘密密钥；默认配置适合填入公开地址和模型，密钥由使用者在浏览器中自行填写。

宿主配置 pluginAuthoring: createBrowserPluginAuthoring() 后，Agent 可先调用 get_plugin_structure 获取目录约定，再向 create_plugin_archive 提交源码。每份归档只含一个组件，源码必须包含 src/native.js 和 src/react.js；可增加 src/ 下的 .js 共享文件，并使用标准 ESM 导入。原生入口只依赖核心包；React 入口除创建器和菜单外，必须通过 propertySections 注册右侧配置面板，fields 中至少包含一个与元素字段对应的组件专属配置项。dist/、package.json、manifest.json 由浏览器生成，Agent 不提交这些路径。浏览器检查 JavaScript 语法、配置面板与导入路径，校验 ZIP 摘要，再将产物保存在 IndexedDB；下载按钮从本地存储读取 ZIP，不请求打包服务器。下载不等于安装或发布。插件列表的“导入插件包”用于本机安装，允许导入清单标记为不可再分发的 ZIP；“上传到共享库”用于共享发布，仍要求插件包允许再分发。

在新对话中升级已生成插件时，Agent 可调用 list_plugin_sources 查找包标识及最新版本，再调用 get_plugin_source 读取浏览器本地保存的原始源码。修改后仍通过 create_plugin_archive 生成新 ZIP。浏览器关闭或页面刷新后，已保存的下载卡片仍可从 IndexedDB 取回 ZIP。

“外观配置”分类可填写面板的最小、最大、当前宽度（像素）。拖动面板分隔条会更新当前宽度并独立保存到本地存储；首次宽度可由 createPrintDesignAiChatPlugin({ panelWidths: { min: 280, max: 640, current: 360 } }) 指定。AI 标题行与属性面板标题行使用相同高度。

对话历史只保存在当前浏览器的 IndexedDB，不包含 API Key；点击“新对话”开始独立会话。用户消息位于右侧，AI 回复位于左侧并显示生成时使用的模型名称。内置 OpenAI 兼容提供方流式展示思考和正文；思考区域限高滚动，流式界面仅保留最近的思考文本，回复完成后可展开查看全文。自定义提供方可实现可选的 stream 接口，不实现时继续使用 complete。src/ai-chat/index.ts 是插件入口，types.ts 定义宿主协议，model/ 管理多连接配置及旧版迁移，providers/ 放模型连接，persistence/ 分别管理加密模型配置、面板宽度和历史会话，hooks/ 管理会话状态，components/ 放对话、虚拟列表及配置对话框。新增模型提供方、消息能力或配置导航项时分别在对应目录扩展。

插件编写指南

按项目安装的 @canvas-components/print-design 版本选择指南，当前核心包为 0.1.10：

• 人工编写指南：组件模型、Agent 接入、右侧属性、工具和宿主接入。
• AI 编写指南：任务输入、实现顺序和交付检查。
• 可编译组件与工具示例；其他版本见指南索引。

供 Agent 创建的第三方组件需要注册完整的 componentFactories；只有要让 Agent 发现并调用组件专用命令时，才在工厂中声明可选的 agentCommands，并在原生组件中实现对应的 commands.execute。

当前复杂组件提供的专用 Agent 命令如下。其他组件的常规字段通过 get_component_template、get_element 和 update_element 编辑。

| 组件 | 专用命令 | | -------------- | ----------------------------------------------------------- | | 表格 | insert-row、insert-column、merge-body、merge-header | | 透视表 | move-field、remove-field | | 甘特图 | insert-task、update-task、remove-task | | 图表 | set-categories、set-series | | 流程图、列表 | insert-item、update-item、remove-item | | 网格、坐标网格 | resize-grid、set-cell | | 图形 | set-polygon-points、set-curve-points、set-path-points | | 连接线 | set-endpoint、set-waypoints | | 图片 | set-crop、clear-crop | | 画笔 | append-stroke、remove-stroke |

src/plugins/ 下每种内置组件一个目录，例如 text/、table/、pivot-table/。每个目录的 native.ts 声明原生输出能力，menu.ts 声明左侧菜单入口和预设，factory.ts 创建默认元素，properties.ts 可声明右侧属性分组，react.ts 汇合创建器与编辑能力；包入口只负责汇总与注册。新增组件时先建独立目录，再将其加入两个入口的清单。

组件实现按实际职责放入 data/、layout/、rendering/、interaction/，测试与实现同目录；无需的子目录可以省略。表格插件的具体划分见 src/plugins/table/README.md，整体约定见插件化计划。

组件专属的绘制、数据、分页和交互逻辑由本包各插件目录实现。print-design 核心只负责通用文档模型、分页、Canvas/HTML 调度和组件注册分发；核心默认组件注册表为空，未注册的组件会明确报错。复杂字段控件可复用 react-print-design 的通用能力。核心包不反向依赖本包或 React。