yuanflow-cli 0.1.7 → 0.1.9

package/README.md

@@ -36,7 +36,7 @@ yuanflow-cli works download --platform douyin --target "https://v.douyin.com/xxx
 yuanflow-cli search content --platform xiaohongshu --keyword "美妆" --format agent-json
 yuanflow-cli search users --platform instagram --keyword "nasa" --format agent-json
 yuanflow-cli knowledge docs --format agent-json
-yuanflow-cli knowledge entry --task-intent generate_script --content-goal "写一个创业者短视频选题" --format agent-json
+yuanflow-cli knowledge entry --output-format short_video_script --domain 自媒体运营 --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
 yuanflow-cli oss signed-url --key path/to/file.png --ttl-seconds 1800 --format agent-json
 yuanflow-cli list douyin
 ```
@@ -96,12 +96,12 @@ Agent 不确定参数时先执行 `commands list`，再用 `schema works.douyin.
 
 ```bash
 yuanflow-cli knowledge docs --format agent-json
-yuanflow-cli knowledge entry --task-intent generate_script --output-format short_video_script --domain 自媒体运营 --content-goal "写一个创业者短视频选题" --format agent-json
-yuanflow-cli knowledge rules --pack-code topic_pain_point_pack --task-intent generate_script --content-goal "写一个创业者短视频选题" --format agent-json
-yuanflow-cli knowledge rule-detail --rule-code some_rule_code --task-intent generate_script --content-goal "写一个创业者短视频选题" --format agent-json
+yuanflow-cli knowledge entry --output-format short_video_script --domain 自媒体运营 --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
+yuanflow-cli knowledge rules --pack-code topic_pain_point_pack --output-format short_video_script --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
+yuanflow-cli knowledge rule-detail --rule-code some_rule_code --output-format short_video_script --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
 ```
 
-Agent 应先查看 `knowledge docs`，再把用户需求整理成 `task_frame`，按接口返回的 `next_actions` 渐进查询。
+Agent 应先查看 `knowledge docs`，再把用户需求整理成 `task_frame`，按接口返回的 `next_actions` 渐进查询。v2 接口不要求 `task_intent`；旧字段仅保留兼容。`packs`、`rules` 的 `data` 可能直接是数组，Agent 不应假设固定对象结构，应优先读取 `next_actions` 继续下钻。
 
 ### OSS 原子能力
 
@@ -115,6 +115,14 @@ yuanflow-cli oss copy --source-key temp/cover.png --target-key final/cover.png -
 
 上传本地文件前必须确认用户授权，不能上传密钥、cookie、账号凭据或隐私文件。
 
+### 生图技能
+
+`生图技能` 随 npm 包安装到 Skill bundle。YuanFlow 主程序内优先使用受控工具 `yuanflow_image_request`，自动注入当前用户 token 并缓存返回图片。
+
+- 生成图片：`/v1/images/generations`，主模型 `gpt-image-2-c`，备用模型 `gpt-image-2`，请求体使用 `prompt`。
+- 编辑图片：`/v1/images/edits`，必须使用 multipart/form-data 上传本地图片文件。
+- `gpt-image-2-c` 通常返回 URL，`gpt-image-2` 通常返回 `b64_json`；两种返回都应缓存后再展示。
+
 ## Skill 安装器
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "YuanFlow API CLI and skill installer for supported AI coding agents.",
   "type": "module",
   "license": "MIT",

package/skills/yuanflow-skill/SKILL.md

@@ -20,12 +20,13 @@ description: Use when the user asks about social-media API workflows, platform d
 - `综合用户搜索工具/`
 - `自媒体知识库/`
 - `OSS文件中转工具/`
+- `生图技能/`
 
 ## 环境判断
 
 执行本 Skill 前，先判断当前运行环境：
 
-1. 如果当前 Agent 可用 YuanFlow 内置工具，例如 `yuanflow_cli_call` 或 `yuanflow_gateway_request`，优先使用 YuanFlow 内置工具。不要要求用户安装 npm，也不要要求用户配置 token。
+1. 如果当前 Agent 可用 YuanFlow 内置工具，例如 `yuanflow_cli_call`、`yuanflow_gateway_request` 或 `yuanflow_image_request`，优先使用 YuanFlow 内置工具。不要要求用户安装 npm，也不要要求用户配置 token。
 2. 如果当前不在 YuanFlow 内，且本地可执行 `yuanflow-cli --help`，使用本地 CLI。
 3. 如果当前不在 YuanFlow 内，且本地没有 `yuanflow-cli`，再提示用户安装 `npm install -g yuanflow-cli`。
 
@@ -139,6 +140,18 @@ description: Use when the user asks about social-media API workflows, platform d
 
 - `OSS文件中转工具`
 
+### 9. 走 `生图技能`
+
+遇到下面这些需求，优先进入这个子 Skill：
+
+- 生成图片、画图、出图、做海报、生成视觉素材。
+- 编辑图片、修改本地图片、基于已有图片做变化。
+- 调用 YuanFlow 内置图片生成或图片编辑接口。
+
+子 Skill 名称：
+
+- `生图技能`
+
 ## 多需求时怎么处理
 
 如果用户一次提了多段流程，不要强行塞进一个子 Skill，按阶段拆开：

package/skills/yuanflow-skill//347/224/237/345/233/276/346/212/200/350/203/275/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: 生图技能
+description: Use when the user asks to generate images, create pictures, make posters or visual assets, edit images, modify local pictures, or call YuanFlow image generation/edit APIs.
+---
+
+# 生图技能
+
+当用户提到生成图片、画图、出图、做海报、生成视觉素材、编辑图片或修改本地图片时，优先使用本 Skill。
+
+## YuanFlow 内置环境
+
+如果当前 Agent 可用 `yuanflow_image_request`，优先使用该受控工具。它会自动注入当前用户 token，并把接口返回的 URL 或 base64 图片缓存为可预览资源。
+
+生成图片：
+
+```json
+{
+  "mode": "generate",
+  "model": "gpt-image-2-c",
+  "prompt": "一张写实产品图：白色马克杯放在木桌上，自然光",
+  "size": "1024x1024"
+}
+```
+
+编辑图片：
+
+```json
+{
+  "mode": "edit",
+  "model": "gpt-image-2-c",
+  "prompt": "把杯子改成红色，保持背景不变",
+  "image_path": "D:\\path\\to\\source.png"
+}
+```
+
+## 接口顺序
+
+生成图片只走 `/v1/images/generations`，请求体使用 `prompt`：
+
+1. 主模型：`gpt-image-2-c`
+2. 备用模型：`gpt-image-2`
+
+只有主模型请求失败或返回失败时，才切换到备用模型。不要使用 `gpt-image`、`doubao-生图` 或 chat completions/responses 端点作为本 Skill 的生图路径。
+
+编辑图片只走 `/v1/images/edits`。编辑模式必须使用 `multipart/form-data` 上传本地图片文件，不能用 JSON 直接传图片路径。
+
+已确认返回差异：
+
+- `gpt-image-2-c` 通常返回图片 URL。
+- `gpt-image-2` 通常返回 `b64_json` 图片数据。
+- 两种返回都需要缓存成本地资源，并在最终回复中给出可显示的图片链接。
+
+## 外部 Agent 或手工调用
+
+生成图片请求示例：
+
+```bash
+curl https://open.yuanchuangai.com/v1/images/generations \
+  -H "Authorization: Bearer $YUAN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-image-2-c",
+    "prompt": "一张写实产品图：白色马克杯放在木桌上，自然光"
+  }'
+```
+
+如果主模型失败，把 `model` 改为 `gpt-image-2` 后重试。
+
+编辑图片请求示例：
+
+```bash
+curl https://open.yuanchuangai.com/v1/images/edits \
+  -H "Authorization: Bearer $YUAN_API_KEY" \
+  -F "model=gpt-image-2-c" \
+  -F "prompt=把杯子改成红色，保持背景不变" \
+  -F "image=@D:/path/to/source.png"
+```
+
+## 输出要求
+
+- 返回图片 URL 时，先缓存图片，再回复缓存后的可预览 URL。
+- 返回 `b64_json` 时，先解码保存为图片文件，再回复缓存后的可预览 URL。
+- 用户未指定保存目录时，使用 YuanFlow 程序资源缓存目录。
+- 回复中不要暴露 token、Authorization header 或完整鉴权配置。

package/skills/yuanflow-skill//350/207/252/345/252/222/344/275/223/347/237/245/350/257/206/345/272/223/SKILL.md

@@ -50,10 +50,10 @@ yuanflow-cli knowledge docs --format agent-json
 
 ```bash
 yuanflow-cli knowledge entry \
-  --task-intent generate_script \
   --output-format short_video_script \
   --domain 自媒体运营 \
   --content-goal "写一个面向创业者的短视频选题" \
+  --target-audience 创业者 \
   --tone 清晰直接 \
   --communication-mode 口播 \
   --format agent-json
@@ -64,8 +64,9 @@ yuanflow-cli knowledge entry \
 ```bash
 yuanflow-cli knowledge rules \
   --pack-code topic_pain_point_pack \
-  --task-intent generate_script \
+  --output-format short_video_script \
   --content-goal "写一个面向创业者的短视频选题" \
+  --target-audience 创业者 \
   --format agent-json
 ```
 
@@ -80,14 +81,14 @@ yuanflow-cli knowledge rules \
   "args": [
     "knowledge",
     "entry",
-    "--task-intent",
-    "generate_script",
     "--output-format",
     "short_video_script",
     "--domain",
     "自媒体运营",
     "--content-goal",
     "写一个面向创业者的短视频选题",
+    "--target-audience",
+    "创业者",
     "--format",
     "agent-json"
   ]
@@ -100,4 +101,6 @@ yuanflow-cli knowledge rules \
 - 不要使用 `/atomic/aliyun-db/query` 查询知识库内部表。
 - 不要把知识库核心方法论静态写入回复，只按接口返回内容使用。
 - 如果接口返回 `next_actions`，优先按它推荐的动作继续查询。
+- v2 接口不要求 `task_intent`；旧字段只作为兼容字段，不要在新调用里默认填写。
+- `packs`、`rules` 的 `data` 可能直接是数组，不要假设固定 `{ packs: [] }` 或 `{ rules: [] }` 结构。
 - 如果用户只是在问“有什么知识库方向”，先用 `knowledge docs`。

package/src/agent-protocol.js

@@ -29,12 +29,27 @@ const ERROR_MAP = [
     retryable: false,
     test: (message) => message.includes('HTTP 401') || message.includes('HTTP 403'),
   },
+  {
+    code: 'UPSTREAM_CONFIG_ERROR',
+    exitCode: 4,
+    retryable: false,
+    test: (message) => message.includes('原子能力主站令牌未配置'),
+  },
   {
     code: 'UPSTREAM_ERROR',
     exitCode: 4,
     retryable: true,
     test: (message) => /HTTP 5\d\d/.test(message),
   },
+  {
+    code: 'UPSTREAM_ROUTE_MISSING',
+    exitCode: 4,
+    retryable: false,
+    test: (message) =>
+      message.includes('Invalid URL') ||
+      message.includes('接口返回了前端 HTML 页面') ||
+      message.includes('接口返回了非 JSON 内容'),
+  },
   {
     code: 'NETWORK_ERROR',
     exitCode: 5,

package/src/atomic-request.js

@@ -45,11 +45,22 @@ export async function callAtomic(path, options = {}) {
   });
 
   const text = await response.text();
+  const contentType = response.headers.get('content-type') || '';
   const payload = parseMaybeJson(text);
   if (!response.ok) {
     const message = typeof payload === 'object' ? JSON.stringify(payload) : text;
     throw new Error(`请求失败：HTTP ${response.status} ${message}`);
   }
+  if (options.expectJson !== false) {
+    assertJsonResponse({
+      contentType,
+      method,
+      path: normalizedPath,
+      status: response.status,
+      payload,
+      text,
+    });
+  }
   return payload;
 }
 
@@ -95,6 +106,34 @@ function parseMaybeJson(text) {
   }
 }
 
+function assertJsonResponse({ contentType, method, path, status, payload, text }) {
+  if (payload !== null && typeof payload === 'object') {
+    return;
+  }
+  const preview = compactPreview(text);
+  const isHtml = looksLikeHtml(text) || contentType.toLowerCase().includes('text/html');
+  if (isHtml) {
+    throw new Error(
+      `接口返回了前端 HTML 页面，不是结构化 JSON。请检查云端接口是否已部署或路径是否正确：HTTP ${status} ${method} ${path}。返回预览：${preview}`,
+    );
+  }
+  throw new Error(
+    `接口返回了非 JSON 内容。请检查云端接口是否已部署或路径是否正确：HTTP ${status} ${method} ${path}。返回预览：${preview}`,
+  );
+}
+
+function looksLikeHtml(text) {
+  const normalized = String(text || '').trim().toLowerCase();
+  return normalized.startsWith('<!doctype') || normalized.startsWith('<html') || normalized.includes('<html');
+}
+
+function compactPreview(text) {
+  return String(text || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 160);
+}
+
 function maskToken(token) {
   if (!token) {
     return '';

package/src/cli.js

@@ -539,7 +539,7 @@ function printHelp() {
   yuanflow-cli search content --platform xiaohongshu --keyword "美妆" --dry-run
   yuanflow-cli search users --platform instagram --keyword "nasa" --dry-run
   yuanflow-cli knowledge docs --dry-run
-  yuanflow-cli knowledge entry --task-intent generate_script --content-goal "写一个创业者短视频选题" --format agent-json
+  yuanflow-cli knowledge entry --output-format short_video_script --domain 自媒体运营 --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
   yuanflow-cli oss signed-url --key path/to/file.png --ttl-seconds 1800 --format agent-json
   yuanflow-cli list douyin
 

package/src/knowledge-tools.js

@@ -92,10 +92,11 @@ function knowledgeCommand(action, description, extraOptions = []) {
 
 function taskFrameOptions() {
   return [
-    { flag: '--task-intent', name: 'taskIntent', required: false, label: '任务意图，例如 generate_script、generate_copy、evaluate_content。' },
+    { flag: '--task-intent', name: 'taskIntent', required: false, label: '兼容旧字段；v2 接口不要求填写。' },
     { flag: '--output-format', name: 'outputFormat', required: false, label: '输出格式，例如 short_video_script、social_post、any。' },
     { flag: '--domain', name: 'domain', required: false, label: '内容领域。' },
     { flag: '--content-goal', name: 'contentGoal', required: false, label: '具体创作或评估目标。' },
+    { flag: '--target-audience', name: 'targetAudience', required: false, label: '目标受众，例如 创业者、宝妈、普通用户。' },
     { flag: '--tone', name: 'tone', required: false, label: '语气风格。' },
     { flag: '--communication-mode', name: 'communicationMode', required: false, label: '表达方式，例如 口播、图文、文章。' },
     { flag: '--task-frame-file', name: 'taskFrameFile', required: false, label: '读取 task_frame JSON 文件。' },
@@ -116,10 +117,11 @@ async function buildTaskFrame(options) {
     : {};
   return removeUndefined({
     ...fromFile,
-    task_intent: pick(options, 'task-intent', fromFile.task_intent || 'general'),
+    task_intent: pick(options, 'task-intent', fromFile.task_intent),
     output_format: pick(options, 'output-format', fromFile.output_format || 'any'),
     domain: pick(options, 'domain', fromFile.domain || '自媒体运营'),
     content_goal: pick(options, 'content-goal', fromFile.content_goal || ''),
+    target_audience: pick(options, 'target-audience', fromFile.target_audience || ''),
     tone: pick(options, 'tone', fromFile.tone || ''),
     communication_mode: pick(options, 'communication-mode', fromFile.communication_mode || ''),
   });