@h-ai/cli 0.1.0-alpha.41 → 0.1.0-alpha.42

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.41",
+  "version": "0.1.0-alpha.42",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -34,7 +34,7 @@
     "ora": "^9.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.7.0",
-    "@h-ai/core": "0.1.0-alpha.41"
+    "@h-ai/core": "0.1.0-alpha.42"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/templates/base/package.json.hbs

@@ -1,6 +1,6 @@
 {
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.41",
+  "version": "0.1.0-alpha.42",
   "private": true,
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",
   "keywords": ["hai", {{#unless isSvelteOnlyApp}}"sveltekit", {{/unless}}"svelte5", "{{appType}}"],

package/templates/skills/hai-ai/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: hai-ai
-description: "Use when: using @h-ai/ai for LLM calls, tools, MCP, streaming, memory/context, RAG, audio, A2A, or the AI client. 当需求涉及 AI 对话、工具、Audio、会话、知识库或 AI 客户端时使用。"
+description: "Use when: using @h-ai/ai for LLM calls, tools, MCP, streaming, memory/context, RAG, image generation, text-to-image, GPT Image, Gemini Image, Qwen Image, Seedream, audio, A2A, or the AI client. 当需求涉及 AI 对话、工具、文生图、Audio、会话、知识库或 AI 客户端时使用。"
 ---
 
 # hai-ai — @h-ai/ai 快速指南
 
-`@h-ai/ai` 统一提供 LLM、工具、MCP、Embedding、Memory、Retrieval/RAG、Knowledge、Context、File、Rerank、Audio 与 A2A 能力。
+`@h-ai/ai` 统一提供 LLM、工具、MCP、Embedding、Memory、Retrieval/RAG、Knowledge、Context、File、Rerank、Image、Audio 与 A2A 能力。
 
 > 详细 API 表、错误码与长示例见同目录 `reference.md`。只有需要完整契约或边界用例时再读取，避免把长参考塞进上下文。
 
@@ -13,7 +13,7 @@ description: "Use when: using @h-ai/ai for LLM calls, tools, MCP, streaming, mem
 
 | 项目 | 契约 |
 | --- | --- |
-| 能力 | LLM/流式生成、结构化 Tool、MCP、Embedding、Memory、RAG/Knowledge、Context、Audio、A2A |
+| 能力 | LLM/流式生成、结构化 Tool、MCP、Embedding、Memory、RAG/Knowledge、Context、Image、Audio、A2A |
 | 适用场景 | 服务端 AI 对话、Agent 工具链、知识问答、长期记忆、语音交互和 Agent-to-Agent；浏览器通过 client/API 代理 |
 | 输入 | `AIConfigInput`、消息/文本/音频、Zod Tool schema、`objectId/sessionId/scope`、`AbortSignal` |
 | 输出 | 领域操作返回 `HaiResult<T>`；流式 API 返回 `AsyncIterable`；Tool 返回 `ToolMessage`；客户端传输可能抛异常 |
@@ -22,7 +22,7 @@ description: "Use when: using @h-ai/ai for LLM calls, tools, MCP, streaming, mem
 ## 使用边界
 
 - `ai.tools`、`ai.stream` 是纯函数能力，无需 `ai.init()`。
-- `ai.llm`、`ai.embedding`、`ai.memory`、`ai.retrieval`、`ai.rag`、`ai.knowledge`、`ai.context`、`ai.audio`、`ai.a2a` 需要先 `await ai.init(...)`。
+- `ai.llm`、`ai.embedding`、`ai.memory`、`ai.retrieval`、`ai.rag`、`ai.knowledge`、`ai.context`、`ai.image`、`ai.audio`、`ai.a2a` 需要先 `await ai.init(...)`。
 - 未初始化 reldb/vecdb 时，`ai.init()` 使用进程内临时 Store，适合 LLM-only 与本地原型；数据在 `ai.close()` 或进程退出后丢失。
 - reldb 与 vecdb 均已初始化时自动使用持久化 DB Provider；生产 Memory/Context/Persona/Knowledge 应使用该路径或自定义 `AIStoreProvider`。
 - 浏览器端不要直接调用 Node-only 能力；通过 `@h-ai/api-client` 或应用自定义 API/SSE endpoint 代理。
@@ -124,6 +124,7 @@ memory:
 | Context 重置 | `await manager.reset({ preserveSystemPrompt?, cancelActiveTurn?, waitForMemoryTasks? })` | 异步：终止活动生成、清空消息/摘要/轮次，默认保留系统提示词 |
 | 语音识别 | `ai.audio.transcribe` / `transcribeStream` | 完整音频返回 `HaiResult`；持续音频输入用 `AudioInputStream` 流式返回临时文本 |
 | 语音合成 | `ai.audio.synthesize` / `synthesizeStream` | `text` 可为字符串或 `AsyncIterable<string>`（可接 LLM 文本流边生成边合成） |
+| 图片生成 | `ai.image.generate({ prompt, size?, model?, referenceImages? })` | 可选参考图使用字节 + MIME；Provider 协议和临时 URL 下载由模块内部处理 |
 | A2A | `ai.a2a.registerExecutor/handleRequest` | 延迟初始化 SDK handler |
 
 ## LLM + 工具调用
@@ -316,6 +317,38 @@ for await (const event of ai.audio.synthesizeStream({ text: { id: 'seg-1', text:
 - 平台不支持的输入方式（如 OpenAI/MiMo 的持续音频输入）会抛 `AUDIO_UNSUPPORTED_INPUT`，不伪装成实时。
 - 浏览器/移动端经 `@h-ai/serv` 统一语音 WebSocket 入口访问；客户端用已登录 HTTP 请求获取短期一次性 ticket，`@h-ai/ai/client` 通过 `audio.getTicket` 建连，不把 IAM access token 放入 URL。浏览器客户端区分正常结束、取消（`AUDIO_CANCELLED`）与 `end` 前异常断连（`AUDIO_CONNECTION_FAILED`）；服务端 error 帧保留领域错误码，`synthesize` 不返回未完成的部分音频。
 
+## 文生图（Image）
+
+`ai.image` 只暴露稳定的提示词、模型别名、像素尺寸、可选参考图和图片字节；OpenAI、Google、Qwen、Seedream 与 Pollinations 的请求结构、鉴权、响应解析和临时 URL 下载均封装在内部 Provider。
+
+```yaml
+image:
+  models:
+    - { id: free, provider: pollinations, model: zimage }
+    - { id: openai, provider: openai, model: gpt-image-2 }
+    - { id: google, provider: google, model: gemini-3.1-flash-image-preview }
+    - { id: qwen, provider: qwen, model: qwen-image-2.0-pro }
+    - { id: seedream, provider: seedream, model: doubao-seedream-5-0-260128 }
+  generateModel: free
+```
+
+```ts
+const image = await ai.image.generate({
+  prompt: '水墨风格的未来城市，清晨薄雾',
+  size: { width: 1024, height: 1024 },
+  referenceImages: [{ data: referenceBytes, mimeType: 'image/png' }],
+})
+if (!image.success) return image
+await saveImage(image.data.images[0].data, image.data.images[0].mimeType)
+```
+
+- `Pollinations` 提供可免费起步的开发额度，但仍需 API key；不要把“免费额度”描述为匿名或无限调用。
+- 应用应通过 `core.init({ configDir: './config' })` 加载 `_core.yml` / `_ai.yml`，再以 `core.config.validate('ai', AIConfigSchema)` 校验并传给 `ai.init`；不要在启动代码中重复拼装模型、端点和超时，也不要传入 `logging` 覆盖 `_core.yml`。
+- Pollinations 的 HTTP 402 表示账户余额或该 API Key 的预算耗尽；401 是密钥无效，403 是权限或模型访问被拒。诊断日志记录厂商、模型、状态、上游错误码和请求 ID，不记录密钥、提示词或图片内容。
+- Qwen 等返回的临时图片 URL 会在 Provider 内立即下载，公共结果不泄漏易过期 URL。
+- 参考图统一使用 `{ data: Uint8Array, mimeType: 'image/...' }`；不要把厂商 URL、multipart 或 Base64 结构泄漏到业务层。
+- Provider 请求/响应格式变更时，先更新契约测试，再修改实现。
+
 
 ## SvelteKit API 端点模式
 

package/templates/skills/hai-ai/reference.md

@@ -184,6 +184,19 @@ const result = await ai.rag.query('核心架构是什么？', {
 - 资源上限：`audio.maxAudioBytes`（默 10 MiB）、`audio.maxStreamDurationMs`（默 5 分钟）；所有请求支持 `signal: AbortSignal` 打断。
 - Provider 为内部实现，不从根入口导出；不支持的输入方式招 `AUDIO_UNSUPPORTED_INPUT`，不伪装实时。取消 → `AUDIO_CANCELLED`，超时 → `AUDIO_TIMEOUT`，连接失败或 `end` 前异常断连 → `AUDIO_CONNECTION_FAILED`。浏览器客户端（`@h-ai/ai/client`）严格区分正常结束 / 取消 / 异常断连：取消招 `AUDIO_CANCELLED`、`end` 前断连招 `AUDIO_CONNECTION_FAILED`、服务端 error 帧保留其领域错误码，`synthesize` 不把未完成的部分音频当作成功返回。
 
+## Image
+
+| 方法 | 返回 | 说明 |
+| --- | --- | --- |
+| `generate(request)` | `Promise<HaiResult<GenerateImageResult>>` | 文本提示词 → 一张或多张已下载的图片字节 |
+
+- 请求：`GenerateImageRequest { prompt, model?, size?: { width, height }, referenceImages?: ReferenceImage[], signal? }`；`ReferenceImage` 为 `{ data: Uint8Array, mimeType: string }`。
+- 返回：`GenerateImageResult { images: Array<{ data: Uint8Array, mimeType, width?, height? }> }`。
+- 模型配置：`image.models: [{ id, provider: 'openai'|'google'|'qwen'|'seedream'|'pollinations', model, apiKey?, baseUrl?, workspaceId?, timeout? }]`；`image.generateModel` 选择默认模型别名。
+- 凭据优先使用模型项 `apiKey`，否则回退 `HAI_AI_IMAGE_<PROVIDER>_API_KEY` 或厂商标准环境变量。
+- 厂商差异由内部 Provider 消化：OpenAI/Pollinations 的 multipart edits、Google `inlineData`、Qwen/Seedream 的 Data URL 参考图，以及各家 Base64、临时 URL 或二进制响应均归一为图片字节。
+- Google 只接受其文档列出的宽高比；Qwen/Seedream 还可能对总像素与边长有限制。业务应提供厂商支持的尺寸预设，不要假设任意像素组合都可用。
+
 ## LLM 结构化输出
 
 `ai.llm.generateObject({ schema, messages, model?, systemPrompt?, maxRepairs?, signal? })`：按 Zod schema 约束模型输出（json_schema）并解析为对象，解析/校验失败自动带错误提示重试（默 1 次）。适用于“是否为问题/意图分类/置信度”等需要稳定结构结果的场景，避免手写 `JSON.parse`。
@@ -210,6 +223,7 @@ A2A 服务端 SDK handler 在注册 executor 时延迟创建；远端客户端
 | `hai:ai:010-012` | 初始化：`NOT_INITIALIZED` / `CONFIGURATION_ERROR` / `INIT_IN_PROGRESS` |
 | `hai:ai:020-033` | Rerank / File |
 | `hai:ai:050-059` | Audio：`AUDIO_INVALID_REQUEST` / `MODEL_NOT_FOUND` / `PROVIDER_NOT_FOUND` / `UNSUPPORTED_INPUT` / `UPSTREAM_ERROR` / `PROTOCOL_ERROR` / `CONNECTION_FAILED` / `TIMEOUT` / `INPUT_TOO_LARGE` / `CANCELLED` |
+| `hai:ai:060-065` | Image：`IMAGE_INVALID_REQUEST` / `MODEL_NOT_FOUND` / `PROVIDER_NOT_FOUND` / `UPSTREAM_ERROR` / `PROTOCOL_ERROR` / `CANCELLED` |
 | `hai:ai:100-107` | LLM / 历史记录 |
 | `hai:ai:200-204` | MCP |
 | `hai:ai:300-302` | Embedding |