yuanflow-cli 0.1.6 → 0.1.7

package/README.md

@@ -35,6 +35,9 @@ yuanflow-cli works detail --platform douyin --target "https://v.douyin.com/xxx/"
 yuanflow-cli works download --platform douyin --target "https://v.douyin.com/xxx/" --region CN --format agent-json
 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 oss signed-url --key path/to/file.png --ttl-seconds 1800 --format agent-json
 yuanflow-cli list douyin
 ```
 
@@ -87,6 +90,31 @@ yuanflow-cli search users --platform instagram --keyword "nasa" --format agent-j
 
 Agent 不确定参数时先执行 `commands list`，再用 `schema works.douyin.detail` 或 `schema search.xiaohongshu.content` 查看参数。`--dry-run` 可预览请求映射，不发起真实接口请求，也不要求 token。
 
+### 自媒体知识库
+
+知识库能力独立于社媒 `/social` 接口，走 Yuan API 的 `/api/knowledge-base/docs` 和 `/atomic/agent-rules/navigate`：
+
+```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
+```
+
+Agent 应先查看 `knowledge docs`，再把用户需求整理成 `task_frame`，按接口返回的 `next_actions` 渐进查询。
+
+### OSS 原子能力
+
+OSS 能力独立封装为 `oss` 命令，用于临时上传、签名链接和对象复制：
+
+```bash
+yuanflow-cli oss temp-upload --file ./cover.png --content-type image/png --format agent-json
+yuanflow-cli oss signed-url --key path/to/file.png --ttl-seconds 1800 --method GET --format agent-json
+yuanflow-cli oss copy --source-key temp/cover.png --target-key final/cover.png --format agent-json
+```
+
+上传本地文件前必须确认用户授权，不能上传密钥、cookie、账号凭据或隐私文件。
+
 ## Skill 安装器
 
 ```bash

package/package.json

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

package/skills/yuanflow-skill/OSS/346/226/207/344/273/266/344/270/255/350/275/254/345/267/245/345/205/267/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: OSS文件中转工具
+description: 当用户需要把本地文件上传到 YuanFlow 临时 OSS、生成对象签名访问链接、复制 OSS 对象，或为自媒体工作流准备图片、音频、视频、文档中转链接时使用。
+---
+
+# OSS 文件中转工具
+
+这个 Skill 负责使用 YuanFlow 的 OSS 原子能力。它只处理文件中转、签名链接和对象复制，不负责社媒数据采集。
+
+## 环境判断
+
+1. 在 YuanFlow 主程序内，优先调用内置工具 `yuanflow_cli_call`。
+2. 在外部 Agent 中，如果本地有 `yuanflow-cli`，直接执行 CLI。
+3. 如果外部环境没有 CLI，再提示用户安装 `npm install -g yuanflow-cli`。
+
+不要要求用户手动填写 token。YuanFlow 主程序会注入认证 token；外部 CLI 使用 `YUANCHUANG_API_TOKEN`。
+
+## 能做什么
+
+- 上传本地图片、音频、视频、文档到临时 OSS。
+- 为已有 OSS 对象生成临时签名 URL。
+- 把一个 OSS 对象复制到另一个 key。
+- 为后续自媒体创作、发布、转写、封面处理等流程提供临时文件链接。
+
+## 命令
+
+### 临时上传
+
+```bash
+yuanflow-cli oss temp-upload \
+  --file ./cover.png \
+  --content-type image/png \
+  --format agent-json
+```
+
+可选参数：
+
+- `--filename`：指定上传文件名。
+- `--key`：指定 OSS 对象 key。
+- `--content-type`：MIME 类型，默认 `application/octet-stream`。
+
+### 生成签名链接
+
+```bash
+yuanflow-cli oss signed-url \
+  --key path/to/file.png \
+  --ttl-seconds 1800 \
+  --method GET \
+  --format agent-json
+```
+
+可选参数：
+
+- `--bucket`：指定 bucket。
+- `--ttl-seconds`：有效期，最大值由后端限制。
+- `--method`：`GET`、`PUT`、`HEAD`。
+
+### 复制对象
+
+```bash
+yuanflow-cli oss copy \
+  --source-key temp/cover.png \
+  --target-key final/cover.png \
+  --format agent-json
+```
+
+可选参数：
+
+- `--source-bucket`：源 bucket。
+- `--target-bucket`：目标 bucket。
+
+## YuanFlow 内置工具调用示例
+
+在 YuanFlow 主程序内，调用 `yuanflow_cli_call`，参数数组不要包含 token：
+
+```json
+{
+  "args": [
+    "oss",
+    "signed-url",
+    "--key",
+    "path/to/file.png",
+    "--ttl-seconds",
+    "1800",
+    "--format",
+    "agent-json"
+  ]
+}
+```
+
+## 安全边界
+
+- 上传本地文件前，先确认用户明确授权该文件路径。
+- 不上传密钥、cookie、账号凭据、配置文件、隐私文件。
+- 不把签名 URL 写入公开文档或长期日志。
+- 返回结果中优先说明 `bucket`、`key`、`expires_at`，只有用户确实需要访问链接时才展示 `signed_url`。
+- 在 YuanFlow 主程序中，如果工具策略限制本地文件上传，不要绕过限制，改为让用户通过受控上传入口完成。

package/skills/yuanflow-skill/SKILL.md

@@ -18,6 +18,8 @@ description: Use when the user asks about social-media API workflows, platform d
 - `作品下载综合工具/`
 - `综合搜索工具/`
 - `综合用户搜索工具/`
+- `自媒体知识库/`
+- `OSS文件中转工具/`
 
 ## 环境判断
 
@@ -113,6 +115,30 @@ description: Use when the user asks about social-media API workflows, platform d
 
 - `综合用户搜索工具`
 
+### 7. 走 `自媒体知识库`
+
+遇到下面这些需求，优先进入这个子 Skill：
+
+- 自媒体选题、开头钩子、脚本、文案、标题、改写、评分、剪辑建议、发布策略。
+- 用户明确要求查询 YuanFlow 自媒体知识库、方法包、规则方向。
+- 需要按照知识库 `next_actions` 渐进式查询方法论摘要。
+
+子 Skill 名称：
+
+- `自媒体知识库`
+
+### 8. 走 `OSS文件中转工具`
+
+遇到下面这些需求，优先进入这个子 Skill：
+
+- 上传图片、音频、视频、文档到临时 OSS。
+- 为已有 OSS 对象生成签名访问链接。
+- 复制 OSS 对象，或为其它自媒体流程准备文件中转链接。
+
+子 Skill 名称：
+
+- `OSS文件中转工具`
+
 ## 多需求时怎么处理
 
 如果用户一次提了多段流程，不要强行塞进一个子 Skill，按阶段拆开：

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

@@ -0,0 +1,103 @@
+---
+name: 自媒体知识库
+description: 当用户需要做自媒体选题、开头钩子、脚本、文案、标题、改写、评分、剪辑建议、发布策略，或明确要求查询 YuanFlow 自媒体知识库时使用。
+---
+
+# 自媒体知识库
+
+这个 Skill 负责使用 YuanFlow 的自媒体知识库原子能力。它和社媒数据采集、作品评论、作品下载是独立能力，不要混用接口。
+
+## 环境判断
+
+1. 在 YuanFlow 主程序内，优先调用内置工具 `yuanflow_cli_call`。
+2. 在外部 Agent 中，如果本地有 `yuanflow-cli`，直接执行 CLI。
+3. 如果外部环境没有 CLI，再提示用户安装 `npm install -g yuanflow-cli`。
+
+不要让用户手动提供 token。YuanFlow 主程序会注入认证 token；外部 CLI 使用 `YUANCHUANG_API_TOKEN`。
+
+## 能做什么
+
+适合以下任务：
+
+- 选题生成、选题分析。
+- 开头钩子、短视频脚本、口播脚本。
+- 自媒体文案、标题、内容改写。
+- 内容评分、复盘、优化建议。
+- 剪辑建议、发布策略、平台适配。
+
+当前公开方向包括：
+
+- `topic_generation`：选题生成。
+- `hook_generation`：开头钩子。
+- `script_generation`：脚本生成。
+- `topic_analysis`：选题分析。
+- `content_evaluation`：内容评分。
+- `copywriting`：文案创作。
+- `title_generation`：标题生成。
+- `rewrite`：内容改写。
+- `editing_strategy`：剪辑建议。
+- `publishing_strategy`：发布策略。
+
+## 推荐流程
+
+1. 先查看知识库公开目录：
+
+```bash
+yuanflow-cli knowledge docs --format agent-json
+```
+
+2. 把用户需求整理为 `task_frame`，再进入知识库：
+
+```bash
+yuanflow-cli knowledge entry \
+  --task-intent generate_script \
+  --output-format short_video_script \
+  --domain 自媒体运营 \
+  --content-goal "写一个面向创业者的短视频选题" \
+  --tone 清晰直接 \
+  --communication-mode 口播 \
+  --format agent-json
+```
+
+3. 读取返回结果里的 `next_actions`，继续调用 `packs`、`rules` 或 `rule-detail`。
+
+```bash
+yuanflow-cli knowledge rules \
+  --pack-code topic_pain_point_pack \
+  --task-intent generate_script \
+  --content-goal "写一个面向创业者的短视频选题" \
+  --format agent-json
+```
+
+4. 最后基于接口返回的公开规则摘要，完成创作、评估或优化。
+
+## YuanFlow 内置工具调用示例
+
+在 YuanFlow 主程序内，调用 `yuanflow_cli_call`，参数数组不要包含 token：
+
+```json
+{
+  "args": [
+    "knowledge",
+    "entry",
+    "--task-intent",
+    "generate_script",
+    "--output-format",
+    "short_video_script",
+    "--domain",
+    "自媒体运营",
+    "--content-goal",
+    "写一个面向创业者的短视频选题",
+    "--format",
+    "agent-json"
+  ]
+}
+```
+
+## 注意事项
+
+- 不要让 Agent 自己拼 SQL。
+- 不要使用 `/atomic/aliyun-db/query` 查询知识库内部表。
+- 不要把知识库核心方法论静态写入回复，只按接口返回内容使用。
+- 如果接口返回 `next_actions`，优先按它推荐的动作继续查询。
+- 如果用户只是在问“有什么知识库方向”，先用 `knowledge docs`。

package/src/agent-protocol.js

@@ -1,6 +1,8 @@
 import { listEndpoints } from './registry.js';
 import { listShortcuts } from './shortcuts.js';
 import { listCommentCommands } from './comment-collector.js';
+import { listKnowledgeCommands } from './knowledge-tools.js';
+import { listOssCommands } from './oss-tools.js';
 import { listSearchCommands, listWorkCommands } from './work-tools.js';
 
 const ERROR_MAP = [
@@ -86,9 +88,17 @@ export function buildCommandRegistry() {
   const commentCommands = listCommentCommands();
   const workCommands = listWorkCommands();
   const searchCommands = listSearchCommands();
-  return [...shortcuts, ...endpoints, ...commentCommands, ...workCommands, ...searchCommands].sort((left, right) =>
-    left.key.localeCompare(right.key),
-  );
+  const knowledgeCommands = listKnowledgeCommands();
+  const ossCommands = listOssCommands();
+  return [
+    ...shortcuts,
+    ...endpoints,
+    ...commentCommands,
+    ...workCommands,
+    ...searchCommands,
+    ...knowledgeCommands,
+    ...ossCommands,
+  ].sort((left, right) => left.key.localeCompare(right.key));
 }
 
 export function findCommandByKey(key) {
@@ -112,7 +122,8 @@ export function commandToSchema(command) {
     api: {
       method: command.method,
       socialPath: command.socialPath,
-      url: `/social${command.socialPath}`,
+      apiPath: command.apiPath,
+      url: command.apiPath || `/social${command.socialPath}`,
       queryParams: command.queryParams || [],
       requestBody: command.requestBody || null,
     },

package/src/atomic-request.js

@@ -0,0 +1,106 @@
+import { readFile } from 'node:fs/promises';
+import { readConfig } from './config.js';
+
+export async function callAtomic(path, options = {}) {
+  const config = await readConfig();
+  const baseUrl = cleanBaseUrl(options.baseUrl || config.baseUrl);
+  const token = options.token || process.env.YUANCHUANG_API_TOKEN || config.token || '';
+  const method = String(options.method || 'POST').toUpperCase();
+  const normalizedPath = normalizePath(path);
+  const url = new URL(normalizedPath, baseUrl);
+  const body = await resolveBody(options);
+
+  if (method === 'GET' && body && typeof body === 'object') {
+    for (const [key, value] of Object.entries(body)) {
+      if (value !== undefined && value !== null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+
+  if (options.dryRun) {
+    return {
+      dryRun: true,
+      method,
+      url: url.toString(),
+      headers: {
+        ...(token ? { Authorization: `Bearer ${maskToken(token)}` } : {}),
+      },
+      body: method === 'GET' ? undefined : body || {},
+    };
+  }
+
+  if (options.requiresToken !== false && !token) {
+    throw new Error('缺少 token。请设置 YUANCHUANG_API_TOKEN，或执行 yuanflow-cli config set-token <你的令牌>');
+  }
+
+  const response = await fetch(url, {
+    method,
+    headers: {
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      Accept: 'application/json',
+      ...(method === 'GET' ? {} : { 'Content-Type': 'application/json' }),
+    },
+    body: method === 'GET' ? undefined : JSON.stringify(body || {}),
+  });
+
+  const text = await response.text();
+  const payload = parseMaybeJson(text);
+  if (!response.ok) {
+    const message = typeof payload === 'object' ? JSON.stringify(payload) : text;
+    throw new Error(`请求失败：HTTP ${response.status} ${message}`);
+  }
+  return payload;
+}
+
+export async function readJsonFile(filePath) {
+  const raw = await readFile(filePath, 'utf8');
+  const payload = JSON.parse(raw);
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('JSON 文件内容必须是对象。');
+  }
+  return payload;
+}
+
+export function cleanBaseUrl(value) {
+  return (value || 'https://open.yuanchuangai.com').replace(/\/+$/, '');
+}
+
+function normalizePath(path) {
+  const normalized = String(path || '').trim();
+  if (!normalized.startsWith('/')) {
+    return `/${normalized}`;
+  }
+  return normalized;
+}
+
+async function resolveBody(options) {
+  if (options.json) {
+    return JSON.parse(options.json);
+  }
+  if (options.body) {
+    return options.body;
+  }
+  return {};
+}
+
+function parseMaybeJson(text) {
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function maskToken(token) {
+  if (!token) {
+    return '';
+  }
+  if (token.length <= 10) {
+    return '***';
+  }
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}

package/src/cli.js

@@ -17,6 +17,8 @@ import {
 } from './agent-protocol.js';
 import { findShortcut, listShortcuts } from './shortcuts.js';
 import { collectComments } from './comment-collector.js';
+import { getKnowledgeDocs, navigateKnowledge } from './knowledge-tools.js';
+import { copyObject, signedUrl, tempUpload } from './oss-tools.js';
 import {
   getWorkDetail,
   getWorkDownload,
@@ -68,6 +70,16 @@ export async function main(argv) {
     return;
   }
 
+  if (command === 'knowledge') {
+    await handleKnowledge(rest);
+    return;
+  }
+
+  if (command === 'oss') {
+    await handleOss(rest);
+    return;
+  }
+
   if (command === 'schema') {
     await handleSchema(rest);
     return;
@@ -93,6 +105,7 @@ async function handleCommands(args) {
       description: item.description,
       method: item.method,
       socialPath: item.socialPath,
+      apiPath: item.apiPath,
     }));
     await outputResult(
       createAgentSuccess('commands list', { commands }),
@@ -130,6 +143,7 @@ async function handleSchema(args) {
       kind: item.kind,
       method: item.method,
       socialPath: item.socialPath,
+      apiPath: item.apiPath,
     }));
     await outputResult(createAgentSuccess('schema list', { commands }), {
       ...options,
@@ -325,6 +339,47 @@ async function handleSearch(args) {
   });
 }
 
+async function handleKnowledge(args) {
+  const { positionals, options } = parseOptions(args);
+  const [action = 'docs'] = positionals;
+  if (action === 'docs') {
+    const result = await getKnowledgeDocs({ options });
+    await outputResult(result, options, {
+      command: 'knowledge docs',
+      meta: { endpoint: result.endpoint.path, kind: 'knowledge-base' },
+    });
+    return;
+  }
+  if (['entry', 'packs', 'rules', 'rule-detail', 'evaluate'].includes(action)) {
+    const result = await navigateKnowledge({ action, options });
+    await outputResult(result, options, {
+      command: `knowledge ${action}`,
+      meta: { endpoint: result.endpoint.path, kind: 'knowledge-base' },
+    });
+    return;
+  }
+  throw new Error('未知 knowledge 命令。用法：yuanflow-cli knowledge docs|entry|packs|rules|rule-detail|evaluate');
+}
+
+async function handleOss(args) {
+  const { positionals, options } = parseOptions(args);
+  const [action] = positionals;
+  let result;
+  if (action === 'temp-upload') {
+    result = await tempUpload({ options });
+  } else if (action === 'signed-url') {
+    result = await signedUrl({ options });
+  } else if (action === 'copy') {
+    result = await copyObject({ options });
+  } else {
+    throw new Error('未知 oss 命令。用法：yuanflow-cli oss temp-upload|signed-url|copy');
+  }
+  await outputResult(result, options, {
+    command: `oss ${action}`,
+    meta: { endpoint: result.endpoint.path, kind: 'oss-atomic' },
+  });
+}
+
 async function handleGeneratedCommand(platform, args) {
   if (!getPlatforms().includes(platform)) {
     throw new Error(`未知平台：${platform}。可用平台：${getPlatforms().join(', ')}`);
@@ -483,10 +538,14 @@ function printHelp() {
   yuanflow-cli works download --platform youtube --target "dQw4w9WgXcQ" --dry-run
   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 oss signed-url --key path/to/file.png --ttl-seconds 1800 --format agent-json
   yuanflow-cli list douyin
 
 说明：
-  所有请求都会调用 Yuan API 的 /social/*path，并使用 Authorization: Bearer <token>。
+  社媒请求调用 Yuan API 的 /social/*path；知识库和 OSS 原子能力调用 /api/* 或 /atomic/*。
+  需要鉴权的请求都会使用 Authorization: Bearer <token>。
   token 优先级：--token > YUANCHUANG_API_TOKEN > 本地 config.token。
   YuanFlow 主程序内使用时，token 由主程序认证系统注入，不需要手动配置。
   AI Agent 推荐使用 --format agent-json 获取稳定 JSON 外壳。

package/src/knowledge-tools.js

@@ -0,0 +1,175 @@
+import { callAtomic, readJsonFile } from './atomic-request.js';
+
+const KNOWLEDGE_NAVIGATE_PATH = '/atomic/agent-rules/navigate';
+const KNOWLEDGE_DOCS_PATH = '/api/knowledge-base/docs';
+
+export function listKnowledgeCommands() {
+  return [
+    {
+      key: 'knowledge.docs',
+      command: 'knowledge docs',
+      kind: 'knowledge-base',
+      description: '读取自媒体知识库公开目录、一级/二级方向和流程说明。',
+      method: 'GET',
+      apiPath: KNOWLEDGE_DOCS_PATH,
+      positionals: [],
+      options: commonOptions({ tokenRequired: false }),
+      requestBody: null,
+      returns: '返回知识库公开目录、能力方向和可用说明。',
+    },
+    knowledgeCommand('entry', '进入知识库，根据用户任务获取领域上下文、推荐能力和方法包。'),
+    knowledgeCommand('packs', '查看某类能力下的方法包。', [
+      { flag: '--capability-code', name: 'capabilityCode', required: false, label: '一级能力 code，例如 topic_generation。' },
+    ]),
+    knowledgeCommand('rules', '查看方法包下的规则方向。', [
+      { flag: '--pack-code', name: 'packCode', required: true, label: '方法包 code。' },
+    ]),
+    knowledgeCommand('rule-detail', '查看单条规则的公开摘要。', [
+      { flag: '--rule-code', name: 'ruleCode', required: true, label: '规则 code。' },
+    ]),
+    knowledgeCommand('evaluate', '获取内容评分维度和优化方向。'),
+  ];
+}
+
+export async function getKnowledgeDocs({ options }) {
+  const response = await callAtomic(KNOWLEDGE_DOCS_PATH, {
+    ...options,
+    method: 'GET',
+    requiresToken: false,
+  });
+  return {
+    ok: true,
+    action: 'docs',
+    endpoint: { method: 'GET', path: KNOWLEDGE_DOCS_PATH, kind: 'knowledge-base' },
+    response,
+  };
+}
+
+export async function navigateKnowledge({ action, options }) {
+  const taskFrame = await buildTaskFrame(options);
+  const params = buildParams(action, options);
+  const body = {
+    action: normalizeAction(action),
+    task_frame: taskFrame,
+    params,
+  };
+  const response = await callAtomic(KNOWLEDGE_NAVIGATE_PATH, {
+    ...options,
+    method: 'POST',
+    body,
+  });
+  return {
+    ok: true,
+    action: normalizeAction(action),
+    endpoint: { method: 'POST', path: KNOWLEDGE_NAVIGATE_PATH, kind: 'knowledge-base' },
+    request: { body },
+    response,
+  };
+}
+
+function knowledgeCommand(action, description, extraOptions = []) {
+  return {
+    key: `knowledge.${action}`,
+    command: `knowledge ${action}`,
+    kind: 'knowledge-base',
+    description,
+    method: 'POST',
+    apiPath: KNOWLEDGE_NAVIGATE_PATH,
+    positionals: [],
+    options: [
+      ...taskFrameOptions(),
+      ...extraOptions,
+      ...commonOptions(),
+    ],
+    requestBody: {
+      action: normalizeAction(action),
+      task_frame: '<由 task-frame 参数组装>',
+      params: '<由命令参数组装>',
+    },
+    returns: '返回当前知识库层级数据和 next_actions，Agent 应按 next_actions 继续查询。',
+  };
+}
+
+function taskFrameOptions() {
+  return [
+    { flag: '--task-intent', name: 'taskIntent', required: false, label: '任务意图，例如 generate_script、generate_copy、evaluate_content。' },
+    { 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: '--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 文件。' },
+  ];
+}
+
+function commonOptions({ tokenRequired = true } = {}) {
+  return [
+    { flag: '--extra', name: 'extra', required: false, label: 'JSON 字符串，会合并进 params。' },
+    { flag: '--format', name: 'format', required: false, label: 'Agent 调用时建议使用 agent-json。' },
+    { flag: '--dry-run', name: 'dryRun', required: false, label: `仅预览请求映射，不发起真实请求${tokenRequired ? '，也不要求 token' : ''}。` },
+  ];
+}
+
+async function buildTaskFrame(options) {
+  const fromFile = options.named?.['task-frame-file']
+    ? await readJsonFile(options.named['task-frame-file'])
+    : {};
+  return removeUndefined({
+    ...fromFile,
+    task_intent: pick(options, 'task-intent', fromFile.task_intent || 'general'),
+    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 || ''),
+    tone: pick(options, 'tone', fromFile.tone || ''),
+    communication_mode: pick(options, 'communication-mode', fromFile.communication_mode || ''),
+  });
+}
+
+function buildParams(action, options) {
+  const params = parseExtra(options.named?.extra);
+  const capabilityCode = cleanOptional(options.named?.['capability-code']);
+  const packCode = cleanOptional(options.named?.['pack-code']);
+  const ruleCode = cleanOptional(options.named?.['rule-code']);
+  if (capabilityCode) params.capability_code = capabilityCode;
+  if (packCode) params.pack_code = packCode;
+  if (ruleCode) params.rule_code = ruleCode;
+  if (action === 'rules' && !params.pack_code) {
+    throw new Error('缺少 --pack-code。');
+  }
+  if (action === 'rule-detail' && !params.rule_code) {
+    throw new Error('缺少 --rule-code。');
+  }
+  return params;
+}
+
+function normalizeAction(action) {
+  return action === 'rule-detail' ? 'rule_detail' : action;
+}
+
+function pick(options, key, fallback) {
+  return cleanOptional(options.named?.[key]) ?? cleanOptional(fallback);
+}
+
+function cleanOptional(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+  }
+  return value;
+}
+
+function removeUndefined(payload) {
+  return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
+}
+
+function parseExtra(value) {
+  if (!value) return {};
+  if (typeof value === 'object') return value;
+  try {
+    const parsed = JSON.parse(String(value));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}

package/src/oss-tools.js

@@ -0,0 +1,181 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { callAtomic } from './atomic-request.js';
+
+const OSS_TEMP_UPLOAD_PATH = '/atomic/oss/temp-upload';
+const OSS_SIGNED_URL_PATH = '/atomic/oss/signed-url';
+const OSS_COPY_PATH = '/atomic/oss/copy';
+
+export function listOssCommands() {
+  return [
+    {
+      key: 'oss.temp-upload',
+      command: 'oss temp-upload',
+      kind: 'oss-atomic',
+      description: '上传本地文件到 Yuan API 临时 OSS bucket，并返回对象 key 和临时访问信息。',
+      method: 'POST',
+      apiPath: OSS_TEMP_UPLOAD_PATH,
+      positionals: [],
+      options: [
+        { flag: '--file', name: 'file', required: true, label: '本地文件路径。' },
+        { flag: '--filename', name: 'filename', required: false, label: '上传时使用的文件名，默认取本地文件名。' },
+        { flag: '--key', name: 'key', required: false, label: '可选 OSS 对象 key。' },
+        { flag: '--content-type', name: 'contentType', required: false, label: '文件 MIME 类型，默认 application/octet-stream。' },
+        ...commonOptions(),
+      ],
+      requestBody: {
+        filename: '<filename>',
+        key: '<optional key>',
+        content_base64: '<base64>',
+        content_type: '<content-type>',
+      },
+      returns: '返回 bucket、key、url、signed_url、expires_at 等字段，字段以后端实际响应为准。',
+    },
+    {
+      key: 'oss.signed-url',
+      command: 'oss signed-url',
+      kind: 'oss-atomic',
+      description: '为已有 OSS 对象生成临时签名访问链接。',
+      method: 'POST',
+      apiPath: OSS_SIGNED_URL_PATH,
+      positionals: [],
+      options: [
+        { flag: '--key', name: 'key', required: true, label: 'OSS 对象 key。' },
+        { flag: '--bucket', name: 'bucket', required: false, label: '可选 bucket，不传则使用后端默认配置。' },
+        { flag: '--ttl-seconds', name: 'ttlSeconds', required: false, label: '签名有效期，最大 86400 秒。' },
+        { flag: '--method', name: 'method', required: false, label: '签名方法：GET、PUT、HEAD。' },
+        ...commonOptions(),
+      ],
+      requestBody: {
+        key: '<key>',
+        bucket: '<optional bucket>',
+        ttl_seconds: 1800,
+        method: 'GET',
+      },
+      returns: '返回签名 URL、过期时间和对象信息，字段以后端实际响应为准。',
+    },
+    {
+      key: 'oss.copy',
+      command: 'oss copy',
+      kind: 'oss-atomic',
+      description: '复制 OSS 对象到目标 key。',
+      method: 'POST',
+      apiPath: OSS_COPY_PATH,
+      positionals: [],
+      options: [
+        { flag: '--source-key', name: 'sourceKey', required: true, label: '源 OSS 对象 key。' },
+        { flag: '--target-key', name: 'targetKey', required: true, label: '目标 OSS 对象 key。' },
+        { flag: '--source-bucket', name: 'sourceBucket', required: false, label: '可选源 bucket。' },
+        { flag: '--target-bucket', name: 'targetBucket', required: false, label: '可选目标 bucket。' },
+        ...commonOptions(),
+      ],
+      requestBody: {
+        source_key: '<source-key>',
+        target_key: '<target-key>',
+        source_bucket: '<optional source bucket>',
+        target_bucket: '<optional target bucket>',
+      },
+      returns: '返回复制后的对象信息，字段以后端实际响应为准。',
+    },
+  ];
+}
+
+export async function tempUpload({ options }) {
+  const filePath = cleanOptional(options.named?.file || options.file);
+  if (!filePath) {
+    throw new Error('缺少 --file。');
+  }
+  const filename = cleanOptional(options.named?.filename) || path.basename(filePath);
+  const contentType = cleanOptional(options.named?.['content-type']) || 'application/octet-stream';
+  const body = {
+    filename,
+    content_base64: options.dryRun ? '<base64 omitted in dry-run>' : (await readFile(filePath)).toString('base64'),
+    content_type: contentType,
+    ...optionalField('key', options.named?.key),
+  };
+  const response = await callAtomic(OSS_TEMP_UPLOAD_PATH, {
+    ...options,
+    method: 'POST',
+    body,
+  });
+  return result('temp-upload', OSS_TEMP_UPLOAD_PATH, body, response);
+}
+
+export async function signedUrl({ options }) {
+  const key = cleanOptional(options.named?.key);
+  if (!key) {
+    throw new Error('缺少 --key。');
+  }
+  const body = {
+    key,
+    ...optionalField('bucket', options.named?.bucket),
+    ...optionalField('ttl_seconds', numberOrString(options.named?.['ttl-seconds'])),
+    ...optionalField('method', cleanOptional(options.named?.method) || 'GET'),
+  };
+  const response = await callAtomic(OSS_SIGNED_URL_PATH, {
+    ...options,
+    method: 'POST',
+    body,
+  });
+  return result('signed-url', OSS_SIGNED_URL_PATH, body, response);
+}
+
+export async function copyObject({ options }) {
+  const sourceKey = cleanOptional(options.named?.['source-key']);
+  const targetKey = cleanOptional(options.named?.['target-key']);
+  if (!sourceKey) {
+    throw new Error('缺少 --source-key。');
+  }
+  if (!targetKey) {
+    throw new Error('缺少 --target-key。');
+  }
+  const body = {
+    source_key: sourceKey,
+    target_key: targetKey,
+    ...optionalField('source_bucket', options.named?.['source-bucket']),
+    ...optionalField('target_bucket', options.named?.['target-bucket']),
+  };
+  const response = await callAtomic(OSS_COPY_PATH, {
+    ...options,
+    method: 'POST',
+    body,
+  });
+  return result('copy', OSS_COPY_PATH, body, response);
+}
+
+function commonOptions() {
+  return [
+    { flag: '--format', name: 'format', required: false, label: 'Agent 调用时建议使用 agent-json。' },
+    { flag: '--dry-run', name: 'dryRun', required: false, label: '仅预览请求映射，不发起真实请求，也不要求 token。' },
+  ];
+}
+
+function result(action, endpointPath, body, response) {
+  return {
+    ok: true,
+    action,
+    endpoint: { method: 'POST', path: endpointPath, kind: 'oss-atomic' },
+    request: { body },
+    response,
+  };
+}
+
+function optionalField(name, value) {
+  const cleaned = cleanOptional(value);
+  return cleaned === undefined ? {} : { [name]: cleaned };
+}
+
+function cleanOptional(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+  }
+  return value;
+}
+
+function numberOrString(value) {
+  const cleaned = cleanOptional(value);
+  if (cleaned === undefined) return undefined;
+  return /^-?\d+$/.test(String(cleaned)) ? Number(cleaned) : cleaned;
+}