Initial TrueGrowth source import

openspec/changes/archive/2026-04-29-add-agent-image-understanding/proposal.md

@@ -0,0 +1,51 @@
+# Change: 为文本与 Agent 增加图片理解能力
+
+## Why
+
+当前项目中的图片与视频生成链已经支持多供应商协议路由，但文本与 Agent 链路仍然只把图片作为“存在附件”或“占位符说明”处理，没有真正把图片内容发送给上游模型。
+这导致用户在聊天抽屉、AI 分析、Agent 工具规划等场景中，无法直接让模型“看图理解”，也无法在保持现有多供应商路由的前提下，安全地区分哪些文本模型支持图片输入、哪些不支持。
+
+## What Changes
+
+- 为文本协议绑定增加“支持图片输入”的能力声明
+- 在聊天抽屉文本发送链中，将附件图片按多模态消息内容发送，而不是统一丢弃
+- 在 Agent / `ai_analyze` 链中，将参考图片作为真实图片内容发送，而不是仅传占位符文本
+- 第一阶段仅覆盖当前最稳定的两类文本协议：
+  - `openai.chat.completions`
+  - `google.generateContent`
+- 为不支持图片输入的文本绑定增加显式保护，避免把图片内容发送给纯文本模型
+- 保持现有文本、图片、视频的 provider routing 结构不变，不在本变更中引入新的上传协议或文件存储后端
+
+## Impact
+
+- Affected specs:
+  - `agent-image-understanding`
+- Affected code:
+  - `packages/drawnix/src/services/chat-service.ts`
+  - `packages/drawnix/src/services/agent/agent-executor.ts`
+  - `packages/drawnix/src/components/ai-input-bar/workflow-converter.ts`
+  - `packages/drawnix/src/services/canvas-operations/ai-analyze.ts`
+  - `packages/drawnix/src/mcp/tools/ai-analyze.ts`
+  - `packages/drawnix/src/services/provider-routing/*`
+  - `packages/drawnix/src/utils/gemini-api/*`
+
+## Scope
+
+### Included In This Change
+
+- 聊天抽屉中的附件图片进入文本消息
+- Agent 默认执行链中的参考图片进入文本消息
+- `ai_analyze` 工作流与画布分析场景中的参考图片进入文本消息
+- 绑定级图片输入能力控制
+
+### Not Included In This Change
+
+- Gemini Files API 大文件上传
+- OpenAI `responses` 协议接入
+- 新增文件持久化后端或服务端中转
+- 文本模型能力的自动远程探测
+
+## Relationship To Existing Changes
+
+- 本变更建立在 `add-provider-protocol-routing` 的文本协议绑定与运行时规划之上
+- 本变更复用 `add-ai-input-paste-images` 已经建立的输入图片获取链路，但扩展其在文本/Agent 场景中的消费方式