@flowweave-ai/cli 0.4.0 → 0.5.0

package/README.md

@@ -13,6 +13,10 @@ flowweave health --ready
 
 页面域命令包括 `node`、`node-directory`、`capability`、`event-trigger`、`environment`、`credential`、`flow`、`run`、`schedule`、`model` 和 `agent`。它们分别覆盖节点资产、能力仓库、运行事件触发器、终端环境、网站认证条目、流程编排、FlowRun、周期调度、大模型配置与 Agent 工作台的常用原子操作。`credential` 管理网站凭据，不等于 `auth` 用户登录。每个命令的 JSON 请求体与在线 OpenAPI 一致；运行 `flowweave <域> --help` 查看映射。
 
+工作区浏览支持按需详情、增量目录、受授权的 Git 历史/提交/Diff 与创建普通文件或目录：使用 `agent workspace-details [--full-index]|workspace-directory|workspace-git-repositories|workspace-git-log|workspace-git-commit|workspace-git-diff|workspace-entry-create` 处理顶层 Agent Workspace；在 FlowRun 节点范围内使用对应的 `run workspace-* <run-id> --attempt <attempt-id>`。`--full-index` 只在用户确实需要完整索引时使用，默认优先按目录读取。Git 操作只接受由工作区 API 返回的 `repository_path`、commit 和文件路径，不能从本地或显示名称猜测。`agent hydration|head` 与 `run hydration|head` 读取会话原生状态；它们不修改 Conversation。
+
+连续自动记录的可移植初始配置使用 `run automatic-config-export <parent-run-id> --data-file ./.tmp/export.json` 和 `run automatic-config-import <parent-run-id> --data-file ./.tmp/import.json`。导出只接受已读取的连续记录 ID；导入会创建记录，先 dry-run 审阅格式版本、起始节点与节点计划。遇到明确的原生完成动作未投影时，才可在读取当前 Attempt 后使用 `run reconcile-runtime-completion <attempt-id> --data '{"expected_state_version": 3}'`；该操作必须携带当前状态版本，不能用来猜测或强制完成运行。
+
 常用命令示例：
 
 `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>`。
@@ -21,7 +25,7 @@ flowweave health --ready
 
 读取 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 凭据。
 
-周期任务使用 `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 不会删除调度，而有生成记录的调度删除会被平台拒绝。
+周期任务使用 `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 不会删除调度，而有生成记录的调度删除会被平台拒绝。环境发布现在会返回 `202`：发布后读取对应 Environment，等待新版本进入 `READY`，不要重复提交同一 Setup Session。
 
 能力命令还支持受治理的 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 使用受控表单参数：`capability validate --type HOOK --file ./hook.md --hook-name <name> --hook-event <event> --hook-mode <PROMPT|SCRIPT>`；可选 `--hook-description` 与工具事件的 `--hook-matcher` 会被编译为 OpenHands 原生 `hook_config`，不能提交任意 Hook JSON。
 

package/bin/flowweave.mjs

@@ -37,10 +37,10 @@ function usage() {
   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> ...
+  run <list|get|start|delete|runtime|replace|pause|resume|cancel|complete|events|node|node-copy|node-delete|workspace-details|workspace-directory|workspace-git-repositories|workspace-git-log|workspace-git-commit|workspace-git-diff|workspace-entry-create|workspace-delete|work-directory-delete|hydration|head|automatic-config-export|automatic-config-import|reconcile-runtime-completion> ...
   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> ...
+  agent <default|workspace|runtime|conversations|conversation|create|send|interrupt|resume|work-directories|work-directory-create|work-directory-delete|workspace-details|workspace-directory|workspace-git-repositories|workspace-git-log|workspace-git-commit|workspace-git-diff|workspace-entry-create|file-delete|hydration|head> ...
 
 所有写入操作都可加 --dry-run 仅查看最终请求。运行 flowweave <命令> --help 查看该命令说明。`;
 }
@@ -453,6 +453,56 @@ async function flow(args) {
   throw new CliError('flow 支持 list|get|create|update|validate|delete');
 }
 
+function workspaceScope(args) {
+  const bindingId = option(args, '--binding');
+  const workDirectoryId = option(args, '--work-directory');
+  return [
+    ...(bindingId ? [['binding_id', bindingId]] : []),
+    ...(workDirectoryId ? [['work_directory_id', workDirectoryId]] : []),
+  ];
+}
+
+function workspaceDirectoryQuery(args) {
+  const parentPath = option(args, '--parent-path');
+  const cursor = option(args, '--cursor');
+  const limit = option(args, '--limit');
+  const query = workspaceScope(args);
+  if (parentPath) query.push(['parent_path', parentPath]);
+  if (cursor) query.push(['cursor', cursor]);
+  if (limit !== undefined) {
+    const value = Number(limit);
+    if (!Number.isSafeInteger(value) || value < 1 || value > 250) {
+      throw new CliError('workspace-directory 的 --limit 必须为 1 到 250 的整数');
+    }
+    query.push(['limit', String(value)]);
+  }
+  return query;
+}
+
+function workspaceDetailsQuery(args) {
+  return [
+    ...workspaceScope(args),
+    ...(flag(args, '--full-index') ? [['full_index', 'true']] : []),
+  ];
+}
+
+function workspaceGitQuery(args, { commit = false, path = false } = {}) {
+  const repositoryPath = option(args, '--repository-path');
+  if (!repositoryPath) throw new CliError('工作区 Git 操作需要 --repository-path');
+  const query = [['repository_path', repositoryPath], ...workspaceScope(args)];
+  if (commit) {
+    const value = option(args, '--commit');
+    if (!value) throw new CliError('工作区 Git 提交操作需要 --commit');
+    query.push(['commit', value]);
+  }
+  if (path) {
+    const value = option(args, '--path');
+    if (!value) throw new CliError('工作区 Git Diff 操作需要 --path');
+    query.push(['path', value]);
+  }
+  return query;
+}
+
 async function run(args) {
   const [action, id] = positional(args);
   if (action === 'list') return request('GET', '/flow-runs', args);
@@ -465,7 +515,17 @@ async function run(args) {
     });
     return request('POST', `/flows/${flowId}/runs`, args, { body });
   }
+  if (action === 'reconcile-runtime-completion') {
+    if (!id) throw new CliError('run reconcile-runtime-completion 需要 Attempt ID');
+    return request('POST', `/node-attempts/${id}/reconcile-runtime-completion`, args, { body: await objectPayload(args) });
+  }
   if (!id) throw new CliError(`run ${action || ''} 需要 FlowRun ID`);
+  if (action === 'automatic-config-export') {
+    return request('POST', `/flow-runs/${id}/automatic-runs/config-exports`, args, { body: await objectPayload(args) });
+  }
+  if (action === 'automatic-config-import') {
+    return request('POST', `/flow-runs/${id}/automatic-runs/config-imports`, args, { body: await objectPayload(args) });
+  }
   if (action === 'node' || action === 'node-copy' || action === 'node-delete') {
     const nodeRunId = option(args, '--node');
     if (!nodeRunId) throw new CliError(`run ${action} 需要 --node <node-run-id>`);
@@ -474,20 +534,48 @@ async function run(args) {
     if (action === 'node-copy') return request('POST', `${path}/copy`, args, { body: await objectPayload(args) });
     return request('DELETE', path, args);
   }
+  const attemptId = option(args, '--attempt');
+  const workspaceBase = attemptId
+    ? `/flow-runs/${id}/node-attempts/${attemptId}/agent-sessions`
+    : null;
+  if (['workspace-details', 'workspace-directory', 'workspace-git-repositories', 'workspace-git-log', 'workspace-git-commit', 'workspace-git-diff', 'workspace-entry-create'].includes(action)) {
+    if (!workspaceBase) throw new CliError(`run ${action} 需要 --attempt <attempt-id>`);
+    if (action === 'workspace-details') {
+      return request('GET', `${workspaceBase}/workspace`, args, { query: workspaceDetailsQuery(args) });
+    }
+    if (action === 'workspace-directory') {
+      return request('GET', `${workspaceBase}/workspace/directory`, args, { query: workspaceDirectoryQuery(args) });
+    }
+    if (action === 'workspace-git-repositories') {
+      return request('GET', `${workspaceBase}/workspace/git/repositories`, args, { query: workspaceScope(args) });
+    }
+    if (action === 'workspace-git-log') {
+      return request('GET', `${workspaceBase}/workspace/git/log`, args, { query: workspaceGitQuery(args) });
+    }
+    if (action === 'workspace-git-commit') {
+      return request('GET', `${workspaceBase}/workspace/git/commit`, args, { query: workspaceGitQuery(args, { commit: true }) });
+    }
+    if (action === 'workspace-git-diff') {
+      return request('GET', `${workspaceBase}/workspace/git/diff`, args, { query: workspaceGitQuery(args, { commit: true, path: true }) });
+    }
+    if (action === 'workspace-entry-create') {
+      return request('POST', `${workspaceBase}/workspace/entries`, args, { body: await objectPayload(args), query: workspaceScope(args) });
+    }
+  }
+  if (action === 'hydration' || action === 'head') {
+    if (!workspaceBase) throw new CliError(`run ${action} 需要 --attempt <attempt-id>`);
+    const bindingId = option(args, '--binding');
+    if (!bindingId) throw new CliError(`run ${action} 需要 --binding <binding-id>`);
+    return request('GET', `${workspaceBase}/${bindingId}/${action}`, args);
+  }
   if (action === 'workspace-delete') {
-    const attemptId = option(args, '--attempt');
     const paths = optionValues(args, '--path');
     if (!attemptId || !paths.length) {
       throw new CliError('run workspace-delete 需要 FlowRun ID、--attempt 和至少一个 --path');
     }
-    const bindingId = option(args, '--binding');
-    const workDirectoryId = option(args, '--work-directory');
     return request('DELETE', `/flow-runs/${id}/node-attempts/${attemptId}/agent-sessions/workspace/entries`, args, {
       body: { paths },
-      query: [
-        ...(bindingId ? [['binding_id', bindingId]] : []),
-        ...(workDirectoryId ? [['work_directory_id', workDirectoryId]] : []),
-      ],
+      query: workspaceScope(args),
     });
   }
   if (action === 'work-directory-delete') {
@@ -512,7 +600,7 @@ async function run(args) {
   if (action === 'cancel') return request('POST', `/flow-runs/${id}/cancel`, args, { body: {} });
   if (action === 'complete') return request('POST', `/flow-runs/${id}/complete`, args, { body: {} });
   if (action === 'events') return request('GET', `/flow-runs/${id}/events`, 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');
+  throw new CliError('run 支持 list|get|start|delete|runtime|replace|pause|resume|cancel|complete|events|node|node-copy|node-delete|workspace-details|workspace-directory|workspace-git-repositories|workspace-git-log|workspace-git-commit|workspace-git-diff|workspace-entry-create|workspace-delete|work-directory-delete|hydration|head|automatic-config-export|automatic-config-import|reconcile-runtime-completion');
 }
 
 async function schedule(args) {
@@ -597,26 +685,43 @@ async function agent(args) {
     if (!binding) throw new CliError('agent work-directory-delete 需要工作目录 ID');
     return request('DELETE', `${base}/work-directories/${binding}`, args);
   }
+  if (action === 'workspace-details') {
+    return request('GET', `${base}/workspace`, args, { query: workspaceDetailsQuery(args) });
+  }
+  if (action === 'workspace-directory') {
+    return request('GET', `${base}/workspace/directory`, args, { query: workspaceDirectoryQuery(args) });
+  }
+  if (action === 'workspace-git-repositories') {
+    return request('GET', `${base}/workspace/git/repositories`, args, { query: workspaceScope(args) });
+  }
+  if (action === 'workspace-git-log') {
+    return request('GET', `${base}/workspace/git/log`, args, { query: workspaceGitQuery(args) });
+  }
+  if (action === 'workspace-git-commit') {
+    return request('GET', `${base}/workspace/git/commit`, args, { query: workspaceGitQuery(args, { commit: true }) });
+  }
+  if (action === 'workspace-git-diff') {
+    return request('GET', `${base}/workspace/git/diff`, args, { query: workspaceGitQuery(args, { commit: true, path: true }) });
+  }
+  if (action === 'workspace-entry-create') {
+    return request('POST', `${base}/workspace/entries`, args, { body: await objectPayload(args), query: workspaceScope(args) });
+  }
   if (action === 'file-delete') {
     const paths = optionValues(args, '--path');
     if (!paths.length) throw new CliError('agent file-delete 至少需要一个 --path <runtime-path>');
-    const bindingId = option(args, '--binding');
-    const workDirectoryId = option(args, '--work-directory');
     return request('DELETE', `${base}/workspace/entries`, args, {
       body: { paths },
-      query: [
-        ...(bindingId ? [['binding_id', bindingId]] : []),
-        ...(workDirectoryId ? [['work_directory_id', workDirectoryId]] : []),
-      ],
+      query: workspaceScope(args),
     });
   }
   if (action === 'create') return request('POST', `${base}/conversations`, args);
   if (!binding) throw new CliError(`agent ${action || ''} 需要会话 binding ID`);
   if (action === 'conversation') return request('GET', `${base}/conversations/${binding}`, args);
+  if (action === 'hydration' || action === 'head') return request('GET', `${base}/conversations/${binding}/${action}`, args);
   if (action === 'send') return request('POST', `${base}/conversations/${binding}/messages`, args);
   if (action === 'interrupt') return request('POST', `${base}/conversations/${binding}/interrupt`, args, { body: {} });
   if (action === 'resume') return request('POST', `${base}/conversations/${binding}/resume`, args, { body: {} });
-  throw new CliError('agent 支持 default|workspace|runtime|conversations|conversation|create|send|interrupt|resume|work-directories|work-directory-create|work-directory-delete|file-delete');
+  throw new CliError('agent 支持 default|workspace|runtime|conversations|conversation|create|send|interrupt|resume|work-directories|work-directory-create|work-directory-delete|workspace-details|workspace-directory|workspace-git-repositories|workspace-git-log|workspace-git-commit|workspace-git-diff|workspace-entry-create|file-delete|hydration|head');
 }
 
 async function upload(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowweave-ai/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "FlowWeave 平台命令行客户端",
   "type": "module",
   "bin": {