@flowweave-ai/cli 0.1.4 → 0.3.0

package/README.md

@@ -5,22 +5,27 @@
 ```bash
 npm install -g @flowweave-ai/cli
 flowweave config init --base-url https://host.example/flowweave
+flowweave auth login
 flowweave health --ready
 ```
 
-配置只保存基础 URL 到 `~/.config/flowweave/config.json`（可由 `FLOWWEAVE_CONFIG_PATH` 覆盖）。当前平台不需要登录。
+配置只保存基础 URL 到 `~/.config/flowweave/config.json`（可由 `FLOWWEAVE_CONFIG_PATH` 覆盖）。登录会话单独保存到同目录的 `auth.json`（可由 `FLOWWEAVE_AUTH_PATH` 覆盖），文件权限为 `0600`，并且只会发送给登录时的同一平台地址。使用 `flowweave auth status` 检查当前身份，使用 `flowweave auth logout` 撤销服务端会话并删除本地文件。默认登录会隐藏密码输入；非交互环境使用 `--password-stdin`，不要把密码写进命令参数、脚本或日志。
 
-页面域命令包括 `node`、`node-directory`、`capability`、`environment`、`credential`、`flow`、`run`、`model` 和 `agent`。它们分别覆盖节点资产、能力仓库、终端环境、认证管理、流程编排、FlowRun、大模型配置与 Agent 工作台的常用原子操作。每个命令的 JSON 请求体与在线 OpenAPI 一致；运行 `flowweave <域> --help` 查看映射。
+页面域命令包括 `node`、`node-directory`、`capability`、`environment`、`credential`、`flow`、`run`、`schedule`、`model` 和 `agent`。它们分别覆盖节点资产、能力仓库、终端环境、网站认证条目、流程编排、FlowRun、周期调度、大模型配置与 Agent 工作台的常用原子操作。`credential` 管理网站凭据，不等于 `auth` 用户登录。每个命令的 JSON 请求体与在线 OpenAPI 一致；运行 `flowweave <域> --help` 查看映射。
 
 常用命令示例：
 
-`flowweave node-directory delete-many --id <directory-id> --id <directory-id> --dry-run`、`flowweave credential delete-many --id <credential-id> --id <credential-id>`、`flowweave environment publish <setup-session-id> --description '升级 Python 依赖'`、`flowweave agent file-delete <workspace-id> --path /runtime/workspace/project/report.md --path /runtime/workspace/project/output`、`flowweave run workspace-delete <run-id> --attempt <attempt-id> --path /runtime/workspace/project/result.txt`。
+`flowweave node-directory delete-many --id <directory-id> --id <directory-id> --dry-run`、`flowweave credential delete-many --id <credential-id> --id <credential-id>`、`flowweave environment publish <setup-session-id> --description '升级 Python 依赖'`、`flowweave agent file-delete <workspace-id> --path <workspace-api-returned-path>`、`flowweave run workspace-delete <run-id> --attempt <attempt-id> --path <attempt-workspace-api-returned-path>`。
 
 节点目录批量删除、Agent Workspace 文件树删除和 FlowRun 节点工作区删除都使用 JSON 数组请求体。重复传入 `--id` 或 `--path` 即可批量选择；先读取真实资源与路径，并用 `--dry-run` 核对 DELETE URL、范围 query 和请求体。FlowRun 工作目录删除使用 `flowweave run work-directory-delete <run-id> --attempt <attempt-id> --work-directory <directory-id>`。
 
 读取 FlowRun 中的记录使用 `flowweave run node <run-id> --node <node-run-id>`；只有用户明确要求时才能执行 `node-copy` 或 `node-delete`。暂停或恢复 Runtime 前，必须先读取 `run runtime`，将返回的 `generation` 与 session `row_version` 写入 `expected_generation`、`expected_session_row_version` 后传给 `run pause` 或 `run resume`。供应商上游余额/用量使用 `flowweave model usage <provider-id>`，它可能依赖该供应商的有效 API 凭据。
 
-`api`、`upload`、`ws` 是完整契约入口：任意当前或未来的 REST、multipart、WebSocket 原子接口均可直接调用，不需要等待 CLI 发布。`ws` 使用 Node 原生 WebSocket；当前公开 FlowWeave WebSocket 接口无需自定义请求头。写操作支持 `--dry-run`，并可使用 `-H 'Idempotency-Key: …'` 传入一次性幂等键。对于没有快捷命令的新接口，先运行 `flowweave openapi --paths`，再通过通用命令调用。
+周期任务使用 `schedule list/templates/occurrences/create/pause/resume/trigger/delete`。先用 `schedule templates` 读取可作为冻结母版的已就绪连续运行记录；创建请求必须使用在线 `FlowRunScheduleWrite` schema：只提交任务名称、母版 `source_flow_run_id` 和五段 `cron_expression`，节点、环境、输入和启动提示词均来自该记录的冻结母版。`schedule occurrences <schedule-id> --page 1 --page-size 10` 按需读取该调度的执行历史及其 FlowRun/NodeRun，而不预加载所有记录。暂停或恢复前从 `schedule list` 读取当前 `row_version`，再传入 `--expected-row-version`。手动触发会新增一次 occurrence，不会改写既有运行；删除生成的 FlowRun 不会删除调度，而有生成记录的调度删除会被平台拒绝。
+
+能力命令还支持受治理的 OpenHands Plugin Marketplace：`capability marketplace` 读取服务端固定到完整 commit 的公开目录；使用返回的 `source`、`commit`、`repo_path` 与插件名称调用 `capability marketplace-resolve --data-file ./marketplace-plugin.json`，随后读取 `capability plugin-resolution <resolution-id>`，并以当前 `state_version` 调用 `capability plugin-publish <resolution-id> --data '{"expected_state_version": 1}'`。自定义受信任 Marketplace 可先用 `capability marketplace-preview --data-file ./marketplace.json` 审阅目录。Agent Definition 只能以 UTF-8 `.md`/`.markdown` 的 OpenHands YAML frontmatter + Markdown 正文通过 `capability validate|import --type AGENT_DEFINITION --file <file>` 导入；Hook 已下线，新的 `--type HOOK` 导入会被明确拒绝。
+
+`api`、`upload`、`ws` 是完整契约入口：任意当前或未来的 REST、multipart、WebSocket 原子接口均可直接调用，不需要等待 CLI 发布。三者都会使用当前 `auth login` 会话；不得用 `--header` 手工传 Cookie。写操作支持 `--dry-run`，并可使用 `-H 'Idempotency-Key: …'` 传入一次性幂等键。对于没有快捷命令的新接口，先运行 `flowweave openapi --paths`，再通过通用命令调用。
 
 安装页面域 skill：
 

package/bin/flowweave.mjs

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import WebSocket from 'ws';
 
 const API_PREFIX = '/api/v1';
 const CONFIG_PATH = process.env.FLOWWEAVE_CONFIG_PATH
   || `${process.env.XDG_CONFIG_HOME || `${homedir()}/.config`}/flowweave/config.json`;
+const AUTH_PATH = process.env.FLOWWEAVE_AUTH_PATH || `${dirname(CONFIG_PATH)}/auth.json`;
+const SESSION_COOKIE = 'flowweave_session';
 
 class CliError extends Error {}
 
@@ -14,8 +18,9 @@ function usage() {
   return `用法：flowweave <命令> [选项]
 
 配置与发现：
-  config init --base-url <URL> [--force]    设置平台基础 URL（无需登录）
+  config init --base-url <URL> [--force]    设置平台基础 URL
   config show                               显示当前配置
+  auth <login|status|logout>                 登录、检查或退出平台用户会话
   health [--ready]                          健康检查
   openapi [--paths]                         查看在线 OpenAPI 契约
 
@@ -27,11 +32,12 @@ function usage() {
 页面域原子操作：
   node <list|get|create|update|delete> [ID] [--data JSON|--data-file FILE]
   node-directory <list|create|delete|delete-many> [ID] [--id ID ...]
-  capability <list|validate|commit|import> ...
+  capability <list|validate|commit|import|marketplace|marketplace-preview|marketplace-resolve|plugin-resolution|plugin-publish> ...
   environment <list|get|create|update|delete|setup|publish|stop|version-delete> ...
   credential <list|create|update|delete|delete-many> ...
   flow <list|get|create|update|validate|delete> ...
   run <list|get|start|delete|runtime|replace|pause|resume|cancel|complete|events|node|node-copy|node-delete|workspace-delete|work-directory-delete> ...
+  schedule <list|templates|occurrences|create|pause|resume|trigger|delete> ...
   model <list|create|update|delete|discover|usage|test|oauth-start|oauth-poll|oauth-status|oauth-revoke> ...
   agent <default|workspace|runtime|conversations|conversation|create|send|interrupt|resume|work-directories|work-directory-create|work-directory-delete|file-delete> ...
 
@@ -62,7 +68,7 @@ function positional(args) {
   const values = [];
   for (let index = 0; index < args.length; index += 1) {
     if (args[index].startsWith('--') || args[index] === '-H' || args[index] === '-q') {
-      if (!['--dry-run', '--raw', '--ready', '--paths', '--force'].includes(args[index])) index += 1;
+      if (!['--dry-run', '--raw', '--ready', '--paths', '--force', '--password-stdin'].includes(args[index])) index += 1;
     } else {
       values.push(args[index]);
     }
@@ -97,6 +103,35 @@ async function saveConfig(baseUrl, force) {
   return value;
 }
 
+async function loadAuth(baseUrl) {
+  let data;
+  try {
+    data = JSON.parse(await readFile(AUTH_PATH, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new CliError(`尚未登录 FlowWeave。请执行：flowweave auth login（${AUTH_PATH}）`);
+    }
+    throw new CliError(`无法读取 FlowWeave 登录会话 ${AUTH_PATH}：${error.message}`);
+  }
+  if (typeof data?.base_url !== 'string' || typeof data?.session_token !== 'string' || !data.session_token) {
+    throw new CliError(`登录会话 ${AUTH_PATH} 格式无效；请重新执行 flowweave auth login`);
+  }
+  if (normalizeBaseUrl(data.base_url) !== baseUrl) {
+    throw new CliError(`登录会话属于其他 FlowWeave 地址；请对 ${baseUrl} 重新执行 flowweave auth login`);
+  }
+  return data.session_token;
+}
+
+async function saveAuth(baseUrl, sessionToken) {
+  await mkdir(dirname(AUTH_PATH), { recursive: true, mode: 0o700 });
+  await writeFile(AUTH_PATH, `${JSON.stringify({ base_url: baseUrl, session_token: sessionToken }, null, 2)}\n`, { mode: 0o600 });
+  await chmod(AUTH_PATH, 0o600);
+}
+
+async function clearAuth() {
+  await rm(AUTH_PATH, { force: true });
+}
+
 function parseJson(value, source) {
   try { return JSON.parse(value); } catch (error) { throw new CliError(`${source} 必须是合法 JSON：${error.message}`); }
 }
@@ -131,12 +166,30 @@ function pathUrl(baseUrl, path, { raw = false, query = [] } = {}) {
 function headers(args) { return Object.fromEntries(pairs(optionValues(args, '-H').concat(optionValues(args, '--header')), ':', '--header').map(([name, value]) => [name.trim(), value.trim()])); }
 function queries(args) { return pairs(optionValues(args, '-q').concat(optionValues(args, '--query')), '=', '--query'); }
 
-async function request(method, path, args, { raw = false, body, form, query = [] } = {}) {
+function sessionTokenFrom(response) {
+  const values = typeof response.headers.getSetCookie === 'function'
+    ? response.headers.getSetCookie()
+    : [response.headers.get('set-cookie')].filter(Boolean);
+  for (const value of values) {
+    const match = new RegExp(`(?:^|;\\s*)${SESSION_COOKIE}=([^;]+)`).exec(value);
+    if (match) return match[1];
+  }
+  throw new CliError('登录响应没有返回 FlowWeave 会话 Cookie');
+}
+
+async function request(method, path, args, {
+  raw = false, body, form, query = [], authenticated = true, captureSession = false,
+} = {}) {
   const { baseUrl } = await loadConfig();
   const url = pathUrl(baseUrl, path, { raw, query: [...queries(args), ...query] });
   const requestBody = body === undefined ? await payload(args) : body;
   if (flag(args, '--dry-run')) return { method, url: url.toString(), payload: requestBody ?? form ?? null };
-  const requestHeaders = { Accept: 'application/json', ...headers(args) };
+  const suppliedHeaders = headers(args);
+  if (Object.keys(suppliedHeaders).some((name) => name.toLowerCase() === 'cookie')) {
+    throw new CliError('不要用 --header 传入 Cookie；请执行 flowweave auth login');
+  }
+  const requestHeaders = { Accept: 'application/json', ...suppliedHeaders };
+  if (authenticated) requestHeaders.Cookie = `${SESSION_COOKIE}=${await loadAuth(baseUrl)}`;
   let encoded;
   if (form) { encoded = form; } else if (requestBody !== undefined) { encoded = JSON.stringify(requestBody); requestHeaders['Content-Type'] ||= 'application/json'; }
   let response;
@@ -145,7 +198,79 @@ async function request(method, path, args, { raw = false, body, form, query = []
   let value;
   try { value = text ? JSON.parse(text) : { status: response.status }; } catch { value = { status: response.status, body: text }; }
   if (!response.ok) throw new CliError(`HTTP ${response.status}: ${JSON.stringify(value)}`);
-  return value;
+  return captureSession ? { value, sessionToken: sessionTokenFrom(response), baseUrl } : value;
+}
+
+async function promptText(label) {
+  if (!process.stdin.isTTY) throw new CliError(`${label.replace(/[:：]\s*$/, '')} 缺少值`);
+  const reader = createInterface({ input: process.stdin, output: process.stderr });
+  try { return (await reader.question(label)).trim(); } finally { reader.close(); }
+}
+
+async function promptSecret(label) {
+  if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function') {
+    throw new CliError('非交互环境请使用 --password-stdin 从标准输入传入密码');
+  }
+  process.stderr.write(label);
+  const wasRaw = process.stdin.isRaw;
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+  return new Promise((resolveSecret, reject) => {
+    let value = '';
+    const finish = (error) => {
+      process.stdin.off('data', onData);
+      process.stdin.setRawMode(Boolean(wasRaw));
+      process.stdin.pause();
+      process.stderr.write('\n');
+      if (error) reject(error); else resolveSecret(value);
+    };
+    const onData = (chunk) => {
+      for (const character of chunk) {
+        if (character === '\u0003') return finish(new CliError('已取消登录'));
+        if (character === '\r' || character === '\n') return finish();
+        if (character === '\u007f' || character === '\b') {
+          if (value) { value = value.slice(0, -1); process.stderr.write('\b \b'); }
+        } else {
+          value += character;
+          process.stderr.write('•');
+        }
+      }
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+async function passwordFrom(args) {
+  if (!flag(args, '--password-stdin')) return promptSecret('密码：');
+  let value = '';
+  for await (const chunk of process.stdin) value += String(chunk);
+  return value.replace(/\r?\n$/, '');
+}
+
+async function auth(args) {
+  const [action] = positional(args);
+  if (action === 'login') {
+    if (flag(args, '--dry-run')) throw new CliError('auth login 不支持 --dry-run，避免密码进入输出');
+    const username = (option(args, '--username') || await promptText('用户名：')).trim();
+    const password = await passwordFrom(args);
+    if (!username || !password) throw new CliError('用户名和密码不能为空');
+    const result = await request('POST', '/auth/login', args, {
+      body: { username, password }, authenticated: false, captureSession: true,
+    });
+    await saveAuth(result.baseUrl, result.sessionToken);
+    return { authenticated: true, auth_path: AUTH_PATH, user: result.value };
+  }
+  if (action === 'status') {
+    const user = await request('GET', '/auth/me', args);
+    return { authenticated: true, auth_path: AUTH_PATH, user };
+  }
+  if (action === 'logout') {
+    await request('POST', '/auth/logout', args, { body: {} });
+    await clearAuth();
+    return { authenticated: false, auth_path: AUTH_PATH };
+  }
+  throw new CliError('auth 支持 login|status|logout');
 }
 
 async function objectPayload(args, defaults = {}) {
@@ -209,6 +334,26 @@ async function nodeDirectory(args) {
 async function capability(args) {
   const [action, id] = positional(args);
   if (action === 'list') return request('GET', '/capabilities', args);
+  if (action === 'marketplace') {
+    if (id) throw new CliError('capability marketplace 不接受 ID');
+    return request('GET', '/plugin-marketplace-catalogs/openhands', args);
+  }
+  if (action === 'marketplace-preview') {
+    if (id) throw new CliError('capability marketplace-preview 不接受 ID');
+    return request('POST', '/plugin-marketplace-catalogs/preview', args);
+  }
+  if (action === 'marketplace-resolve') {
+    if (id) throw new CliError('capability marketplace-resolve 不接受 ID');
+    return request('POST', '/plugin-source-resolutions/marketplace', args);
+  }
+  if (action === 'plugin-resolution') {
+    if (!id) throw new CliError('capability plugin-resolution 需要 resolution ID');
+    return request('GET', `/plugin-source-resolutions/${id}`, args);
+  }
+  if (action === 'plugin-publish') {
+    if (!id) throw new CliError('capability plugin-publish 需要 resolution ID');
+    return request('POST', `/plugin-source-resolutions/${id}/publish`, args);
+  }
   if (action === 'validate' || action === 'import') {
     const type = option(args, '--type');
     const source = option(args, '--file');
@@ -225,7 +370,7 @@ async function capability(args) {
     if (!token) throw new CliError('capability commit 需要 --import-token');
     return request('POST', '/capability-imports', args, { body: { import_token: token } });
   }
-  throw new CliError('capability 支持 list|validate|commit|import');
+  throw new CliError('capability 支持 list|validate|commit|import|marketplace|marketplace-preview|marketplace-resolve|plugin-resolution|plugin-publish');
 }
 
 async function environment(args) {
@@ -332,6 +477,51 @@ async function run(args) {
   throw new CliError('run 支持 list|get|start|delete|runtime|replace|pause|resume|cancel|complete|events|node|node-copy|node-delete|workspace-delete|work-directory-delete');
 }
 
+async function schedule(args) {
+  const [action, id] = positional(args);
+  if (action === 'list') {
+    if (id) throw new CliError('schedule list 不接受 ID');
+    return request('GET', '/flow-run-schedules', args);
+  }
+  if (action === 'templates') {
+    if (id) throw new CliError('schedule templates 不接受 ID');
+    return request('GET', '/flow-run-schedule-templates', args);
+  }
+  if (action === 'create') {
+    if (id) throw new CliError('schedule create 不接受 ID');
+    return request('POST', '/flow-run-schedules', args);
+  }
+  if (!id) throw new CliError(`schedule ${action || ''} 需要调度 ID`);
+  if (action === 'occurrences') {
+    const page = option(args, '--page');
+    const pageSize = option(args, '--page-size');
+    const query = [];
+    if (page !== undefined) {
+      const value = Number(page);
+      if (!Number.isSafeInteger(value) || value < 1) throw new CliError('schedule occurrences 的 --page 必须为正整数');
+      query.push(['page', String(value)]);
+    }
+    if (pageSize !== undefined) {
+      const value = Number(pageSize);
+      if (!Number.isSafeInteger(value) || value < 1 || value > 100) throw new CliError('schedule occurrences 的 --page-size 必须为 1 到 100 的整数');
+      query.push(['page_size', String(value)]);
+    }
+    return request('GET', `/flow-run-schedules/${id}/occurrences`, args, { query });
+  }
+  if (action === 'pause' || action === 'resume') {
+    const expected = Number(option(args, '--expected-row-version'));
+    if (!Number.isSafeInteger(expected) || expected < 1) {
+      throw new CliError(`schedule ${action} 需要正整数 --expected-row-version`);
+    }
+    return request('PUT', `/flow-run-schedules/${id}/state`, args, {
+      body: { expected_row_version: expected, status: action === 'pause' ? 'PAUSED' : 'ACTIVE' },
+    });
+  }
+  if (action === 'trigger') return request('POST', `/flow-run-schedules/${id}/trigger`, args, { body: {} });
+  if (action === 'delete') return request('DELETE', `/flow-run-schedules/${id}`, args);
+  throw new CliError('schedule 支持 list|templates|occurrences|create|pause|resume|trigger|delete');
+}
+
 async function model(args) {
   const [action, id] = positional(args);
   if (action === 'list') return request('GET', '/model-providers', args);
@@ -424,6 +614,7 @@ async function websocket(args) {
   if (message && messageJson) throw new CliError('--message 与 --message-json 只能使用其中一个');
   if (messageJson) message = JSON.stringify(parseJson(messageJson, '--message-json'));
   if (flag(args, '--dry-run')) return { url: url.toString(), message: message || null, max_messages: maxMessages };
+  const sessionToken = await loadAuth(baseUrl);
   await new Promise((resolve, reject) => {
     let received = 0;
     let settled = false;
@@ -432,7 +623,7 @@ async function websocket(args) {
       settled = true;
       if (error) reject(error); else resolve();
     };
-    const socket = new WebSocket(url);
+    const socket = new WebSocket(url, { headers: { Cookie: `${SESSION_COOKIE}=${sessionToken}` } });
     socket.addEventListener('open', () => { if (message) socket.send(message); });
     socket.addEventListener('message', (event) => {
       const text = String(event.data);
@@ -456,7 +647,8 @@ async function main(argv) {
     if (action === 'init') { const baseUrl = option(args, '--base-url'); if (!baseUrl) throw new CliError('config init 需要 --base-url'); result = { config_path: CONFIG_PATH, base_url: await saveConfig(baseUrl, flag(args, '--force')) }; }
     else if (action === 'show') { const { baseUrl } = await loadConfig(); result = { config_path: CONFIG_PATH, base_url: baseUrl }; }
     else throw new CliError('config 支持 init|show');
-  } else if (command === 'health') result = request('GET', flag(args, '--ready') ? '/health/ready' : '/health', args, { raw: true });
+  } else if (command === 'auth') result = auth(args);
+  else if (command === 'health') result = request('GET', flag(args, '--ready') ? '/health/ready' : '/health', args, { raw: true, authenticated: false });
   else if (command === 'openapi') { result = request('GET', '/openapi.json', args, { raw: true }); if (flag(args, '--paths')) result = openapiPaths(await result); }
   else if (command === 'api') { const [method, path] = positional(args); if (!method || !path) throw new CliError('api 用法：api <method> <PATH>'); result = request(method.toUpperCase(), path, args, { raw: flag(args, '--raw') }); }
   else if (command === 'upload') result = upload(args);
@@ -468,6 +660,7 @@ async function main(argv) {
   else if (command === 'credential') result = credential(args);
   else if (command === 'flow') result = flow(args);
   else if (command === 'run') result = run(args);
+  else if (command === 'schedule') result = schedule(args);
   else if (command === 'model') result = model(args);
   else if (command === 'agent') result = agent(args);
   else throw new CliError(`未知命令：${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowweave-ai/cli",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "FlowWeave 平台命令行客户端",
   "type": "module",
   "bin": {
@@ -13,6 +13,9 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
   "scripts": {
     "test": "node --test test/*.test.mjs",
     "lint": "node --check bin/flowweave.mjs",