npm - @fieldwangai/agentflow - Versions diffs - 0.1.159 → 0.1.162 - Mend

@fieldwangai/agentflow 0.1.159 → 0.1.162

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (118) hide show

package/builtin/web-ui/dist/index.html CHANGED Viewed

@@ -30,8 +30,8 @@
       @keyframes af-app-loading-slide { from { transform: translateX(-115%); } to { transform: translateX(250%); } }
       @media (prefers-reduced-motion: reduce) { .af-app-loading__track span { width: 100%; animation: none; } }
     </style>
-    <script type="module" crossorigin src="/assets/index-CdEQWRrp.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-B9ppXv7e.css">
+    <script type="module" crossorigin src="/assets/index-BeUfNQRL.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-5uJFccdX.css">
   </head>
   <body>
     <div id="root">

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@fieldwangai/agentflow",
-  "version": "0.1.159",
+  "version": "0.1.162",
   "description": "Orchestration system for long-running complex agent tasks using Cursor, OpenCode, Claude Code, or Codex as execution backends",
   "type": "module",
   "main": "bin/agentflow.mjs",
@@ -40,6 +40,7 @@
     "bin",
     "agents",
     "skills",
+    "shared",
     "builtin/nodes",
     "builtin/pipelines",
     "builtin/web-ui/dist",
@@ -49,6 +50,7 @@
     "test": "node --test test/*.test.mjs",
     "postinstall": "node bin/ensure-workspace-reference.mjs",
     "build:web-ui": "cd builtin/web-ui && npm install && npm run build",
+    "build:agentflow-cli-skill-runtime": "node scripts/build-agentflow-cli-skill-runtime.mjs",
     "build:website": "cd website && npm install && npm run build",
     "dev": "AGENTFLOW_DEV=1 node bin/agentflow.mjs ui",
     "dev:web": "cd builtin/web-ui && npm run dev",
@@ -68,5 +70,8 @@
     "ora": "^9.3.0",
     "sharp": "^0.34.5",
     "update-notifier": "^7.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
   }
 }

package/reference/flow-control-capabilities.md CHANGED Viewed

@@ -33,21 +33,45 @@
 ---
-## 3. 图必须是 DAG（无环）
+## 3. 图必须是 DAG（无环），重复执行用 control_while
 Workspace 运行计划做拓扑排序，**遇到环直接抛 `Workspace run graph contains a cycle`**，整次运行失败。
 因此：
 - **禁止**从下游节点连边回到上游节点。
-- 「检查 → 修复 → 复检」要**向前展开**成多个节点，而不是回流成环。
-- 需要「反复重试直到达标」时，把循环放进**单个节点内部**——`agent_subAgent` 的 body 里让 agent 自己迭代，或 `tool_nodejs` 的脚本里自己 while 循环。
+- 「检查 → 修复 → 复检」涉及不同角色时要**向前展开**成多个节点，而不是回流成环。
+- 同一个确定性动作需要反复推进时，用 `control_while`。它在单节点状态机里重复 step 命令，
+  父图仍是 DAG；`continue` 继续、`wait` 暂停且不跑下游、`done` 放行下游、`fail` 失败。
+step 的 stdout 必须严格是一个 JSON 对象：
+```json
+{"decision":"continue|wait|done|fail","state":{},"summary":"本轮摘要"}
+```
+循环上下文通过 `AGENTFLOW_WHILE_STATE`、绝对轮次 `AGENTFLOW_WHILE_ITERATION`、
+`AGENTFLOW_WHILE_MAX_ITERATIONS`、`AGENTFLOW_WHILE_TIMEOUT_MS` 和稳定的逐轮
+`AGENTFLOW_WHILE_IDEMPOTENCY_KEY` 注入。外部写操作应尽量把该幂等键传给目标 API。stdout
+留给决策对象，普通进度写 stderr。`maxIterations` 默认 20，`timeout` 默认 30m，二者在
+`wait` 后恢复时继续累计；checkpoint 同时保留 state、history、已用执行时间和下一轮编号。
+输入变化会重置 checkpoint，指纹匹配但 checkpoint 损坏时会拒绝恢复，避免静默重放副作用。
 旧版用于成环的 `control_anyOne` / `control_toBool` / `control_agent_toBool` / `control_interval_loop` 均已下线。
 ---
-## 4. 展示结果（Display）
+## 4. 子流程（Subflow）
+可复用的一段节点拓扑用 `flow.input`、`flow.subflow` 和 `flow.call` 表达。子流程内部继续使用
+标准 AgentFlow 节点与边，父流程只连接调用节点的契约引脚；禁止跨边界直接连内部节点。
+每次调用拥有独立 `callFrameId`，内部事件同时带 `parentNodeId` 和 `subflowId`。禁止递归调用。
+当前第一版不支持子流程内部 `wait/deferred`，遇到会明确失败；可恢复调用栈补齐后再开放。
+---
+## 5. 展示结果（Display）
 把产出槽连到 `display_*` 节点的 `content` 输入即可在画布上渲染：
@@ -66,7 +90,7 @@ Workspace 运行计划做拓扑排序，**遇到环直接抛 `Workspace run grap
 ---
-## 5. 工具节点与 Agent 节点选型
+## 6. 工具节点与 Agent 节点选型
 **核心原则：能用工具节点确定性执行的，不要用 agent_subAgent。**
@@ -76,7 +100,7 @@ Workspace 运行计划做拓扑排序，**遇到环直接抛 `Workspace run grap
 | 向用户展示结果 | **display_\*** | 专用展示节点 |
 | 需要 AI 理解上下文、做判断、生成内容 | **agent_subAgent** | 需要 LLM 推理能力 |
-### 5.1 tool_nodejs 直接执行模式（推荐）
+### 6.1 tool_nodejs 直接执行模式（推荐）
 在 instance 中设置 `script` 字段，运行时**跳过 AI 直接 spawn 命令**：
@@ -99,7 +123,7 @@ write_summary:
 - **成败判定**：以脚本进程 **exit code** 为准（0 = success，非 0 = failed）。
 - **stdout → result**：脚本 stdout 直接作为 result 槽位内容，纯文本即可。**不要用 JSON 封装 stdout。**
-### 5.2 判断标准
+### 6.2 判断标准
 问自己：**"这个步骤的行为是否完全由输入决定，不需要 AI 推理？"**
@@ -108,7 +132,7 @@ write_summary:
 - **否** → 用 `agent_subAgent`
   - 例：根据需求撰写文档、分析代码并提出修改方案、理解上下文后做决策
-### 5.3 `script` 与 `body` 的职责（必须遵守）
+### 6.3 `script` 与 `body` 的职责（必须遵守）
 | 字段 | 职责 | 有 `script` 时 | 无 `script` 时 |
 |------|------|---------------|---------------|
@@ -137,7 +161,7 @@ bad_example:
     调用 API 获取数据，解析 JSON，提取关键字段保存到文件
 ```
-### 5.4 常见误用
+### 6.4 常见误用
 | 用户需求 | 错误做法 | 正确做法 |
 |----------|----------|----------|
@@ -146,7 +170,7 @@ bad_example:
 | 注入密钥 | 写死在 flow 里 | `tool_set_run_env` 或运行时环境变量 |
 | 复杂 AI 推理/生成 | tool_nodejs + body 写自然语言 | agent_subAgent（需 LLM 能力时必须用 agent） |
-### 5.5 节点单一职责（必须遵守）
+### 6.5 节点单一职责（必须遵守）
 **每个节点只做一件事，工作内容保持专注和专一。**
@@ -167,17 +191,18 @@ bad_example:
 ---
-## 6. 常见流程模式
+## 7. 常见流程模式
 1. **线性链**：Run → A → B → … → display
 2. **条件分支**：… → provide_bool → **control_if** → next1 连分支A、next2 连分支B（true 走 output-0，false 走 output-1）
-3. **并行**：同一个 output 扇出到多个下游节点，无依赖的分支会并行执行，各自往下走
-4. **检查 → 修复 → 复检**：向前排成 检查节点 → 修复节点 → 复检节点 → control_if（通过走后续，不通过走汇报节点）。**不要连回上游**
-5. **批量任务**：拆解节点产出 `- [ ]` 清单 → 执行节点在内部逐项推进 → control_if 按完成情况分支
+3. **控制扇出**：同一个 output 扇出到多个下游节点；当前 Workspace 运行时按拓扑序串行执行
+4. **单步收敛**：Run → control_while（重复同一 step）→ 下游；wait 时停在 While
+5. **检查 → 修复 → 复检**：不同角色向前排成多个节点。**不要连回上游**
+6. **批量任务**：拆解节点产出清单 → control_while 每轮推进一项 → done 后汇总
 ---
-## 7. Edge 与 Handle 注意点
+## 8. Edge 与 Handle 注意点
 - **Fan-out 允许，Fan-in 禁止**：一个 output handle 可连多个 input（扇出），但**一个 input handle 只允许一条入边**（禁止扇入）。同一 `target + targetHandle` 不得出现在多条 edge 中——运行时仅取首条匹配，其余静默丢失。若需替换连线，先删旧边再加新边。
 - **禁止回流边**：任何从下游连回上游的边都会让运行计划判定成环，整次运行失败。
@@ -188,6 +213,6 @@ bad_example:
 ---
-## 8. 图与 USER_PROMPT 的读写一致性
+## 9. 图与 USER_PROMPT 的读写一致性
 ${USER_PROMPT} 中描述的「读取」「写入」应与图中的 **handler 节点**（input/output 通过 edge 连接的节点）对应：描述的每项「读」应有节点的 input 入边，每项「写」应有节点的 output 出边。详见 [flow-prompt-handler-check.md](./flow-prompt-handler-check.md)。

package/shared/slot-types.js ADDED Viewed

@@ -0,0 +1,58 @@
+const SLOT_TYPE_ALIASES = new Map([
+  ["文本", "text"],
+  ["str", "text"],
+  ["string", "text"],
+  ["文件", "file"],
+  ["path", "file"],
+  ["节点", "node"],
+  ["flow", "node"],
+  ["control", "node"],
+  ["boolean", "bool"],
+  ["布尔", "bool"],
+  ["object", "json"],
+]);
+/**
+ * Lossless assignments that do not need an adapter node.
+ * JSON can always be serialized as text; text cannot safely become JSON
+ * without parsing and validation, so the reverse direction is deliberately
+ * absent.
+ */
+const LOSSLESS_ASSIGNMENTS = new Set([
+  "json>text",
+]);
+export const SLOT_TYPE_COLORS = Object.freeze({
+  text: "#2196f3",
+  file: "#4caf50",
+  node: "#ff9800",
+  bool: "#9c27b0",
+  json: "#00bcd4",
+  image: "#ec407a",
+  any: "#9e9e9e",
+});
+export function normalizeSlotType(type) {
+  const raw = String(type ?? "").trim().toLowerCase();
+  return SLOT_TYPE_ALIASES.get(raw) || raw || "node";
+}
+export function slotTypeCompatibility(sourceType, targetType) {
+  const source = normalizeSlotType(sourceType);
+  const target = normalizeSlotType(targetType);
+  if (!source || !target) return { compatible: false, kind: "incompatible", source, target };
+  if (source === "any" || target === "any") return { compatible: true, kind: "any", source, target };
+  if (source === target) return { compatible: true, kind: "exact", source, target };
+  if (LOSSLESS_ASSIGNMENTS.has(`${source}>${target}`)) {
+    return { compatible: true, kind: "lossless", source, target };
+  }
+  return { compatible: false, kind: "incompatible", source, target };
+}
+export function areSlotTypesCompatible(sourceType, targetType) {
+  return slotTypeCompatibility(sourceType, targetType).compatible;
+}
+export function getSlotTypeColor(type) {
+  return SLOT_TYPE_COLORS[normalizeSlotType(type)] || "#9e9e9e";
+}

package/skills/agentflow-author-flow/SKILL.md CHANGED Viewed

@@ -1,16 +1,89 @@
 ---
 name: agentflow-author-flow
-description: Legacy Pipeline authoring is retired. Redirect new AgentFlow creation and editing requests to the Workspace Graph skill and server-side Workspace preview.
+description: Create an AgentFlow from a user's idea, iterate in a private runnable Draft Workspace, show the preview URL, test and inspect outputs, then publish the approved graph and explicitly configure Scheduled Run activation. Use for end-to-end requests such as “创建一个流程”, “给我 Preview”, “试运行并动态修改”, “发布这个 Flow”, “配置定时运行”, “make a temporary flow”, or “run it on a schedule”.
 ---
-# Legacy Pipeline Authoring（已下线）
+# AgentFlow Flow Lifecycle
-旧的 Flow/Pipeline (`flow.yaml` + `control_start/control_end`) 执行功能已经下线。此 skill 不再创建、发布或执行新的 Pipeline。
+Orchestrate the complete authoring lifecycle. Use `agentflow-flow-dsl` for graph structure,
+`agentflow-node-dsl` when deterministic custom code is needed, and `agentflow-cli` for Draft,
+execution, publication, and schedule operations. Read those selected Skills completely before acting.
-新任务统一使用：
+## Required lifecycle
-- `agentflow-workspace-graph`：创建或修改 `workspace.flow.js`
-- `agentflow-cli workspace-preview`：上传到服务器临时 Workspace，打开所见即所得画布
-- Workspace 页面中的 `Run` / `Scheduled Run`：执行 Workspace 图
+1. Check `agentflow-cli config`. Require authorization and `localRuntime.available: true`. If
+   authorization is missing, run `agentflow-cli auth start`, return the URL to the user, and run
+   `auth complete` after approval; never ask the user to paste a personal Token. The Runtime is
+   bundled with the Skill; if unavailable, update/reinstall the SkillHub package instead of
+   installing an npm CLI.
+2. Translate the user's idea into a local `workspace.flow.js`. Search the remote node catalog before
+   creating a custom node package.
+3. Run DSL lint, then layout. Do not upload an invalid or unreadable graph.
+4. Create a private runnable Draft:
-历史 `flow.yaml` 仅用于读取、迁移和审计，不得作为新功能的实现目标。不要调用 `agentflow apply`、`/api/flow/run` 或创建 `control_start/control_end`。
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs draft-create \
+  --file <flowDir> --ttl-seconds 7200
+```
+Add `--with-dependencies` when `<flowDir>/nodes/` exists. Return the Draft URL to the user. A Draft
+is hidden from the formal Flow list, writable in the Workspace UI, and runnable. Its Scheduled Run
+nodes are always suppressed and cannot trigger real Cron jobs.
+5. Test the intended Run or Scheduled Run entry manually with `draft-run`. Inspect returned display
+   outputs; use run status and logs for failures or long-running work. Obtain confirmation before a
+   test that calls an external service or has business side effects.
+6. Keep the revision returned by every Draft mutation. Apply feedback to the same Draft. If the user
+   edited in the UI, pull the Draft before changing a stale local DSL:
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs draft-pull \
+  --draft-id <draft-id> --output <flowDir> --replace
+```
+   Then edit locally, lint/layout again, and update against that exact revision:
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs draft-update \
+  --draft-id <draft-id> \
+  --base-revision <last-revision> \
+  --file <flowDir>
+```
+On a revision conflict, stop and pull before reapplying the intended change; never overwrite UI
+edits with a stale local graph. Repeat preview and execution until the user accepts the actual
+output. Do not treat lint, Mock data, or a visual-only preview as production-equivalent acceptance.
+7. Before publication, state the exact Draft ID, target Flow ID, destination, and schedule mode. Wait
+   for explicit confirmation. Publication defaults to personal space and scheduling disabled.
+8. Promote the exact tested Draft:
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs draft-publish \
+  --draft-id <draft-id> \
+  --flow-id <flow-id> \
+  --target-space personal \
+  --schedule disabled
+```
+Use `--schedule enabled` only when the user explicitly wants automatic execution. Promotion is
+create-only; do not replace an existing Flow without a separate explicit decision.
+9. When scheduling is enabled, verify the returned schedule and run `schedule-list --flow-id
+   <flow-id>`. Report it as armed only when `enabled: true`, status is not invalid/error, and
+   `nextRunAt` is present. Include Cron, timezone, overlap policy, and next run time in the handoff.
+## Schedule changes after publication
+Use `schedule-enable`, `schedule-disable`, or `schedule-set`; do not republish the whole graph merely
+to flip an operational switch. Use `schedule-run-now` for a manual verification of the scheduled
+entry. Re-read `schedule-list` after every mutation.
+## Safety gates
+- Keep read-only `workspace-preview` for sharing only. It cannot run or save; use a Draft for review
+  plus execution.
+- Never activate Draft schedules. Draft configuration is design data only.
+- Do not embed tokens, passwords, cookies, or local absolute paths in DSL or node packages.
+- Do not claim external integrations are ready from Mock execution. Require the user's real account,
+  network, credentials, and downstream evidence.
+- If the user requests publication but has not reviewed the Draft output, stop at the Draft and ask
+  for confirmation.

package/skills/agentflow-author-flow/agents/openai.yaml CHANGED Viewed

@@ -1,4 +1,4 @@
 interface:
-  display_name: "AgentFlow Flow Authoring"
-  short_description: "Generate, preview, confirm, and publish AgentFlow flows"
-  default_prompt: "Use $agentflow-author-flow to generate a local AgentFlow, open its platform-style preview, and publish it after I confirm."
+  display_name: "AgentFlow 流程创作"
+  short_description: "创建、预览、试运行、修改、发布并配置定时 Flow"
+  default_prompt: "使用 $agentflow-author-flow 把我的想法做成可运行 Draft，和我一起修改；确认后再发布，并按我的选择配置定时运行。"

package/skills/agentflow-cli/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: agentflow-cli
-description: Direct AgentFlow operation through a bundled token-backed CLI, without MCP. Use when Codex needs to search, publish, install, or synchronize versioned node packages; pull or publish portable Workspace DSL flows; upload previews; run or inspect Workspace graphs; or read logs and display outputs through AgentFlow HTTP APIs using AGENTFLOW_TOKEN from env or .env.
+description: Direct AgentFlow operation through a bundled browser-authorized CLI, without MCP or npm. Use when Codex needs to authorize AgentFlow access, create, update, run, or publish temporary Workspace drafts; search, publish, install, or synchronize versioned node packages; pull or publish portable Workspace DSL flows; manage scheduled runs; upload read-only previews; run or inspect Workspace graphs; or read logs and display outputs through AgentFlow HTTP APIs.
 ---
 # AgentFlow CLI
@@ -52,21 +52,44 @@ For other SkillHub-supported agents, change the agent name:
 skillhub install agentflow-cli --global --agent claude-code
 ```
-After installation, configure only the direct API token. Do not add an MCP server for this skill.
+After installation, authorize the CLI through the AgentFlow browser page. Do not add an MCP server for this skill.
+The Skill already includes the version-matched local Runtime used for Workspace DSL parsing,
+lint/layout, and node-package operations. Do not install an npm package or put `agentflow` on
+`PATH`. `AGENTFLOW_PACKAGE_ROOT` and `--agentflow-package-root` are development overrides only.
-Install or update the `@fieldwangai/agentflow` CLI as the local runtime and keep `agentflow` on
-`PATH`. The bundled skill intentionally does not copy AgentFlow's parser/runtime modules. It locates
-the runtime from an explicit `--agentflow-package-root`, `AGENTFLOW_PACKAGE_ROOT`, the current
-project's `node_modules`, or the `agentflow` executable on `PATH`.
-Verify both token and runtime discovery before local DSL or node-package work:
+Verify both authorization and runtime discovery before local DSL or node-package work:
 ```bash
 node <skill-dir>/scripts/agentflow-cli.mjs config
 ```
-Require `localRuntime.available: true`. Pure remote reporting commands can still run without a local
-runtime, but package creation, installation, Flow pull/publish, and Workspace graph parsing cannot.
+Require `localRuntime.available: true`. A normal SkillHub installation resolves
+`<skill-dir>/runtime`; if it does not, reinstall or update `agentflow-cli` from SkillHub rather than
+installing a separate CLI package. Pure remote reporting commands can still run without a local
+Runtime, but package creation, installation, Flow pull/publish, and Workspace graph parsing cannot.
+## Browser authorization
+When `config` reports `hasToken: false`, do not ask the user to paste a token. Start a non-blocking
+authorization and return its `verificationUrl`:
+```bash
+node <skill-dir>/scripts/agentflow-cli.mjs auth start
+```
+The user opens the URL, logs in to AgentFlow if necessary, reviews the requested access, and clicks
+Allow. After the user says authorization is complete, exchange the pending one-time request:
+```bash
+node <skill-dir>/scripts/agentflow-cli.mjs auth complete
+node <skill-dir>/scripts/agentflow-cli.mjs auth status
+```
+`auth start` never prints the secret device code. `auth complete` saves a separate CLI credential in
+`~/.agentflow/auth.json` with owner-only permissions; it never copies the browser cookie. Use
+`AGENTFLOW_AUTH_FILE` only for isolated automation or tests. Revoke the CLI Session and clear its
+local profile with `auth logout`. Do not send the authorization URL to anyone except the requesting
+user; although it contains no access token, it represents an active approval request.
 ## Configuration
@@ -75,10 +98,12 @@ The CLI reads configuration in this order:
 1. CLI flags: `--base-url`, `--token`
 2. Environment variables: `AGENTFLOW_BASE_URL`, `AGENTFLOW_TOKEN`, `AGENTFLOW_SESSION_TOKEN`
 3. Env files: `AGENTFLOW_ENV_FILE`, then `.env`, `.agentflow.env`, then `~/.agentflow.env`
+4. Browser-authorized profile: `~/.agentflow/auth.json`
 Default base URL: `http://ai.mengma.bigo.inner/`.
-Required token: `AGENTFLOW_TOKEN` or `AGENTFLOW_SESSION_TOKEN`. Never print the token in the final answer or logs.
+For CI or service accounts, `AGENTFLOW_TOKEN` or `AGENTFLOW_SESSION_TOKEN` overrides the saved
+profile. Never print any token in the final answer or logs.
 Example `.env`:
@@ -104,16 +129,14 @@ List flows:
 node <skill-dir>/scripts/agentflow-cli.mjs list-flows
 ```
-For a package used only in the current local checkout, use the packaged AgentFlow CLI (the
-Node DSL workflow is documented in `agentflow-node-dsl`):
+Validate and lay out Workspace DSL with the same bundled CLI:
 ```bash
-agentflow marketplace list --json
-agentflow marketplace publish-node ./my-node --json
-agentflow validate MyFlow --json
+node <skill-dir>/scripts/agentflow-cli.mjs dsl-lint --file <flowDir>
+node <skill-dir>/scripts/agentflow-cli.mjs dsl-layout --file <flowDir>
 ```
-These commands copy a package only into the current workspace marketplace.
+Add `--all` to `dsl-layout` only for a new graph or an explicitly requested full rearrangement.
 To distribute a complete package directory (including `scripts/`, `templates/`, or assets) through
 an AgentFlow server, use the token-backed commands. The CLI packs the directory as ZIP; `index.mjs`
@@ -158,8 +181,8 @@ import myNode from "marketplace:my_node@1.0.0";
 const result = myNode("My node", { input: "value" });
 ```
-Run `agentflow flow dsl lint <flowDir>` with that workspace as the current project before publishing
-the flow. `publish-flow` also checks that the server contains every exact imported version before it
+Run the bundled `dsl-lint` command with that workspace as `--workspace-root` before publishing the
+flow. `publish-flow` also checks that the server contains every exact imported version before it
 writes the Flow. Do not unpack ZIPs by hand or copy only `index.mjs`; relative package files are part
 of the node's versioned content.
@@ -169,7 +192,8 @@ Publish a new local Flow after the user has reviewed it:
 node <skill-dir>/scripts/agentflow-cli.mjs publish-flow \
   --flow-id release-check \
   --file .workspace/agentflow/pipelines/release-check/flow.yaml \
-  --target-space personal
+  --target-space personal \
+  --schedule disabled
 ```
 When the reviewed code Flow contains `nodes/`, publish the Flow and all complete package directories
@@ -180,6 +204,7 @@ node <skill-dir>/scripts/agentflow-cli.mjs publish-flow \
   --flow-id release-check \
   --file .workspace/agentflow/pipelines/release-check \
   --target-space personal \
+  --schedule disabled \
   --with-dependencies
 ```
@@ -188,7 +213,7 @@ and rewrites relative node imports only in the upload payload. It never edits lo
 `workspace.flow.js`. Without `--with-dependencies`, `publish-flow` continues to reject Flow directories
 that contain `nodes/` or `workspace.nodes.json` rather than silently dropping them.
-Destinations are `personal`, `workspace`, and `team`. `team` creates a workspace Flow and shares it as editor with the current account's active team. Publishing is create-only by default. If the exact Flow already exists, stop and ask whether to update it; only after explicit confirmation rerun with `--replace`. Replacement first reads the server revision and submits it with the update.
+Destinations are `personal`, `workspace`, and `team`. `team` creates a workspace Flow and shares it as editor with the current account's active team. `publish-flow` defaults to `--schedule disabled`; use `enabled` only after explicit confirmation, and reserve `preserve` for migrations. Publishing is create-only by default. If the exact Flow already exists, stop and ask whether to update it; only after explicit confirmation rerun with `--replace`. Replacement first reads the server revision and submits it with the update.
 Read one flow graph:
@@ -249,6 +274,82 @@ This is for visual review only. It does not publish a formal Flow/Pipeline or
 create schedules. The returned temporary project is hidden from the normal
 Flow list and must not be treated as a durable source of truth.
+## Runnable Workspace drafts
+For the review-and-test loop, use a Draft instead of the read-only Preview. A Draft is private to
+the token owner, hidden from the formal Flow list, writable in the Workspace UI, runnable, and
+automatically removed after its TTL. Scheduled Run nodes may be present, but Draft saves never arm
+real schedules.
+Create one after DSL lint and layout:
+```bash
+node <skill-dir>/scripts/agentflow-cli.mjs draft-create \
+  --file .workspace/agentflow/pipelines/<flow-id> \
+  --ttl-seconds 7200
+```
+If the Flow contains local `nodes/`, add `--with-dependencies`; this uploads the complete immutable
+packages before creating the Draft. Reuse the returned Draft and URL while iterating:
+```bash
+node <skill-dir>/scripts/agentflow-cli.mjs draft-pull \
+  --draft-id <draft-id> \
+  --output .workspace/agentflow/pipelines/<flow-id> \
+  --replace
+node <skill-dir>/scripts/agentflow-cli.mjs draft-update \
+  --draft-id <draft-id> \
+  --base-revision <revision-from-create-update-or-pull> \
+  --file .workspace/agentflow/pipelines/<flow-id>
+node <skill-dir>/scripts/agentflow-cli.mjs draft-run \
+  --draft-id <draft-id> \
+  --run-node-id <run-node-id> \
+  --input topic=hello
+```
+`draft-update` resets previous runtime output unless `--keep-runtime` is passed. It requires the
+revision returned by the preceding create, update, or pull and rejects stale updates. If the user
+edited the Draft in the UI, run `draft-pull` before changing the local DSL; do not retry a 409 with
+an invented or freshly fetched revision against an unrefreshed local file.
+After the user explicitly approves the tested Draft, promote that exact graph. Scheduling defaults
+to disabled; choose `enabled` only after the user asked to activate it:
+```bash
+node <skill-dir>/scripts/agentflow-cli.mjs draft-publish \
+  --draft-id <draft-id> \
+  --flow-id <flow-id> \
+  --target-space personal \
+  --schedule disabled
+```
+Promotion is create-only and keeps the Draft until TTL expiry for recovery. `--schedule enabled`
+enables every Scheduled Run entry and fails when the Draft has none. `--schedule preserve` retains
+the graph values and is for advanced migrations, not the normal confirmation flow.
+## Scheduled Run operations
+Manage published Workspace schedules explicitly:
+```bash
+node <skill-dir>/scripts/agentflow-cli.mjs schedule-list --flow-id <flow-id>
+node <skill-dir>/scripts/agentflow-cli.mjs schedule-enable \
+  --flow-id <flow-id> --schedule-node-id <node-id>
+node <skill-dir>/scripts/agentflow-cli.mjs schedule-disable \
+  --flow-id <flow-id> --schedule-node-id <node-id>
+node <skill-dir>/scripts/agentflow-cli.mjs schedule-set \
+  --flow-id <flow-id> --schedule-node-id <node-id> \
+  --enabled true --cron "0 8 * * *" --timezone Asia/Shanghai --overlap-policy skip
+node <skill-dir>/scripts/agentflow-cli.mjs schedule-run-now \
+  --flow-id <flow-id> --schedule-node-id <node-id>
+```
+After publishing or changing a schedule, require `enabled`, `lastStatus`, and `nextRunAt` in the
+returned schedule state before reporting it as armed. Draft schedule configuration is visible and
+editable but returns `suppressed: true` and never gets a `nextRunAt` registration.
 Run a Workspace graph:
 ```bash
@@ -306,14 +407,18 @@ The only admin write exception is audited version-membership repair. Read its st
 ## Workflow
-1. Check token availability with `config`.
+1. Check authorization with `config`. If missing, use `auth start`, give the URL to the user, then
+   run `auth complete` only after the user approves it.
 2. Use `list-workspace` or `list-flows` to discover Flow/Pipeline targets only. Use `node-package-search` before creating a new code node. Use `publish-flow` only after a local Flow has passed validation and the user has confirmed the preview.
-3. Use `run` to start the flow. If the task needs the generated page/text, inspect returned `displayOutputs` or call `display-outputs`.
-4. Use `status`, `list-run-by-workspace`, and `logs` when a run is active, failed, or needs debugging.
+3. For a new user-authored Flow, prefer `draft-create` → `draft-run`/`draft-update` → explicit user confirmation → `draft-publish`. Keep `workspace-preview` for read-only sharing.
+4. Use `run` to start a published flow. If the task needs the generated page/text, inspect returned `displayOutputs` or call `display-outputs`.
+5. Use `status`, `list-run-by-workspace`, and `logs` when a run is active, failed, or needs debugging. Use `schedule-list` after every schedule mutation or scheduled publish.
 ## Failure Handling
-- If the CLI says the token is missing, ask the user to set `AGENTFLOW_TOKEN` in env or `.env`.
+- If authorization is missing, use `auth start` and return the URL. Do not ask the user to paste a
+  personal Token into the conversation. Use environment Tokens only for non-interactive CI or
+  service accounts.
 - If `publish-flow` returns 409, do not add `--replace` automatically. Ask the user to confirm updating the existing Flow.
 - If team publishing says no active team is assigned, keep the local draft and ask the user to choose personal/workspace or have an admin assign the account to a team.
 - If the API returns 401/403, do not retry with a printed token. Ask the user to refresh the token.

package/skills/agentflow-cli/agents/openai.yaml CHANGED Viewed

@@ -1,4 +1,4 @@
 interface:
   display_name: "AgentFlow CLI"
-  short_description: "Search packages and operate portable AgentFlow workspaces"
-  default_prompt: "Use $agentflow-cli to search node packages and operate a portable AgentFlow workspace."
+  short_description: "Draft, test, publish, and schedule AgentFlow workspaces"
+  default_prompt: "Use $agentflow-cli to create a runnable Draft, test it, publish it after confirmation, and manage its schedule."