English | 简体中文

这些文档面向把 @jason-huang/infinite-canvas-agent 接入真实项目的开发者，记录公共 API、状态 所有权、容量模型、失败语义、扩展点和迁移方法。npm 包不包含教材、课程生成服务或部署文档。

阅读路径

任务 先读 然后读
评估架构是否适合产品 架构与不变量 Core Runtime
渐进接入老项目 旧项目迁移 可运行项目
控制大图、视频和解码压力 缓存与资产 Core Runtime
保存 Document、History 或 Blob 持久化 API Reference
接入有容量限制的桌面 SQLite/媒体存储 Node 存储适配层 持久化
让自己的 Agent 操作画布 Agent 接入 API Reference
查找导出、默认值和错误 API Reference 对应专题文档

能力地图

宿主 UI / 输入事件 / 宿主 Agent
                    |
              CanvasCommand[]
                    |
               CommandBus ------ Undo / Redo
                    |
              revision commit
                    |
              DocumentStore ----- Persistence
                    |
               SpatialIndex
                    |
 Camera -> Bounds -> WorkingSet
                    |
             ResourcePool / LOD
                    |
               RendererPort
             /               \
        Canvas2D         Konva / 自定义实现

状态所有权

状态 是否持久 所有者 恢复方式
节点 ID、bounds、payload、assetIds 是 DocumentStore 加载 Snapshot
Undo/Redo transactions 可选 CommandBus 只在相同 revision 恢复
原始资产与 manifest 是 AssetStore 加载持久存储
Camera、选区、面板 宿主决定 宿主 UI 重建或恢复偏好
Konva Node、DOM、Bitmap、Texture 否 Renderer / ResourcePool 从 Document/Asset 重建
Prompt、Provider、模型 Key 不属于包 接入宿主 宿主安全策略

验证状态

  • API 已实现：类型与代码存在。
  • 测试通过：测试环境验证了契约与已知边界。
  • 浏览器 Demo 通过：真实浏览器操作过相应路径。
  • 发布门禁通过：类型、测试、构建、泄漏扫描和隔离安装全部通过。
  • 已发布：Registry 已能查询并安装该版本。

这些状态不能互相替代。

双语维护规则

  • docs/*.md 是英文默认文档。
  • docs/zh-CN/*.md 是简体中文本地化。
  • examples/projects/*/README.md 英文默认，README.zh-CN.md 中文。
  • 公共 API、默认值或失败语义改变时，同一变更必须更新两种语言。
  • pnpm docs:check 校验两种语言的本地链接。