npm - @fieldwangai/agentflow - Versions diffs - 0.1.134 → 0.1.136 - Mend

@fieldwangai/agentflow 0.1.134 → 0.1.136

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 (15) hide show

package/bin/lib/ui-server.mjs +405 -40
package/bin/lib/workflow-report.mjs +154 -9
package/builtin/web-ui/dist/assets/index-HdswcJWY.js +565 -0
package/builtin/web-ui/dist/assets/index-KIGufzQf.css +1 -0
package/builtin/web-ui/dist/index.html +2 -2
package/package.json +1 -1
package/skills/agentflow-cli/SKILL.md +3 -70
package/skills/agentflow-cli/agents/openai.yaml +2 -2
package/skills/agentflow-cli/scripts/agentflow-cli.mjs +24 -4
package/skills/agentflow-cli/scripts/workflow-report-client.mjs +68 -0
package/skills/agentflow-workflow-report/SKILL.md +100 -0
package/skills/agentflow-workflow-report/agents/openai.yaml +4 -0
package/skills/agentflow-workflow-report/references/protocol.md +558 -0
package/builtin/web-ui/dist/assets/index-CqXKONpd.js +0 -350
package/builtin/web-ui/dist/assets/index-QDDFbZ_T.css +0 -1

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

@@ -15,8 +15,8 @@
       href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0"
       rel="stylesheet"
     />
-    <script type="module" crossorigin src="/assets/index-CqXKONpd.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-QDDFbZ_T.css">
+    <script type="module" crossorigin src="/assets/index-HdswcJWY.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-KIGufzQf.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@fieldwangai/agentflow",
-  "version": "0.1.134",
+  "version": "0.1.136",
   "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",

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

@@ -1,6 +1,6 @@
 ---
 name: agentflow-cli
-description: Direct AgentFlow platform operation through a bundled token-backed CLI, without MCP. Use when Codex needs to list AgentFlow workspaces or flows, start or inspect runs, fetch display outputs, or read and report Workflow actions, artifacts, and global state through AgentFlow HTTP APIs using AGENTFLOW_TOKEN from env or .env. Default AgentFlow base URL is http://ai.mengma.bigo.inner/.
+description: Direct AgentFlow platform operation through a bundled token-backed CLI, without MCP. Use when Codex needs to list AgentFlow workspaces or flows, start or inspect runs, read graphs and logs, or fetch display outputs through AgentFlow HTTP APIs using AGENTFLOW_TOKEN from env or .env. Default AgentFlow base URL is http://ai.mengma.bigo.inner/.
 ---
 # AgentFlow CLI
@@ -118,72 +118,9 @@ Extract display outputs from a flow:
 node skills/agentflow-cli/scripts/agentflow-cli.mjs display-outputs --flow-id TestNodes --flow-source user
 ```
-Read the current materialized Workflow before making an incremental update:
+## Workflow reporting
-```bash
-node skills/agentflow-cli/scripts/agentflow-cli.mjs workflow-get \
-  --workflow tapd:1015046 \
-  --runtime-only
-```
-Report an action, its artifacts, and/or a global-state patch:
-```bash
-node skills/agentflow-cli/scripts/agentflow-cli.mjs workflow-report \
-  --workflow tapd:1015046 \
-  --file workflow-report.json \
-  --expected-revision 'runtime:replace-with-current-revision' \
-  --idempotency-key 'implementation-finished:android:issue-2:v1'
-```
-`workflow-report.json` uses one general model. Include at least one of `action`, `artifacts`, or `globalState`:
-```json
-{
-  "action": {
-    "key": "implementation-finished",
-    "title": "实现完成",
-    "detail": "Remote Config 拉取频控已实现",
-    "status": "done",
-    "group": "development",
-    "scope": "firebase-remote-config-fetch-control-android",
-    "platform": "android",
-    "issueKey": "issue-2",
-    "tags": ["remote-config"]
-  },
-  "artifacts": [
-    {
-      "key": "implementation-mr",
-      "type": "gitlab-mr",
-      "title": "Android 实现 MR",
-      "url": "https://git.example.test/group/project/-/merge_requests/123",
-      "scope": "action",
-      "status": "ready"
-    }
-  ],
-  "globalState": {
-    "mode": "merge",
-    "patch": {
-      "status": { "label": "开发中" },
-      "sections": {
-        "android": {
-          "title": "Android",
-          "fields": {
-            "owner": { "label": "负责人", "type": "user", "value": "alice" },
-            "tags": { "label": "Tag", "type": "chips", "value": ["remote-config"] },
-            "rules": { "label": "实现规则", "type": "list", "value": ["仅允许国家注册 listener"] }
-          }
-        }
-      }
-    },
-    "remove": []
-  }
-}
-```
-Artifact `scope` is `action` or `global`. Action-scoped artifacts appear with the timeline action; global artifacts appear in the related-artifacts area. Use stable `key` values so later reports update an existing item instead of duplicating it.
-Supported global-state field types are `text`, `user`, `chips`, `list`, and `link`. The model does not require Android/iOS sections; section and field keys are application-defined.
+The reusable transport lives in `scripts/workflow-report-client.mjs`. The CLI exposes it through `workflow-get`, `workflow-report`, and `workflow-artifact-publish`; their state model, extension contract, concurrency rules, and AI procedure belong to the separate [`agentflow-workflow-report`](../agentflow-workflow-report/SKILL.md) skill. Use that skill whenever reading or mutating Workflow state; do not reconstruct the protocol from this general CLI guide.
 ## Workflow
@@ -191,14 +128,10 @@ Supported global-state field types are `text`, `user`, `chips`, `list`, and `lin
 2. Use `list-workspace` or `list-flows` to discover targets.
 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.
-5. Before changing Workflow global state, call `workflow-get` and retain `snapshot.runtimeRevision`.
-6. Merge the intended semantic change into the current state; do not replace unrelated fields.
-7. Call `workflow-report` with `--expected-revision` and a stable `--idempotency-key`. If the API returns a revision conflict, fetch again, re-apply the intended patch, and retry once with a new revision.
 ## Failure Handling
 - If the CLI says the token is missing, ask the user to set `AGENTFLOW_TOKEN` in env or `.env`.
 - If the API returns 401/403, do not retry with a printed token. Ask the user to refresh the token.
 - If `run` fails because a flow is already running, call `status` and `list-run-by-workspace` before retrying.
-- If `workflow-report` returns a revision conflict, do not blindly overwrite remote state. Read the returned snapshot or call `workflow-get`, merge the intended fields, and retry with its revision.
 - If local debugging is needed, override `AGENTFLOW_BASE_URL`; otherwise keep the default internal URL.

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "AgentFlow CLI"
-  short_description: "Run flows and report Workflow state through AgentFlow APIs"
-  default_prompt: "Use $agentflow-cli to operate AgentFlow and report Workflow actions, artifacts, or global state with the bundled token-backed CLI."
+  short_description: "Operate AgentFlow workspaces, flows, runs, graphs, and logs"
+  default_prompt: "Use $agentflow-cli to inspect or operate AgentFlow with the bundled token-backed CLI."

package/skills/agentflow-cli/scripts/agentflow-cli.mjs CHANGED Viewed

@@ -2,6 +2,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createWorkflowReportClient } from "./workflow-report-client.mjs";
 const DEFAULT_BASE_URL = "http://ai.mengma.bigo.inner/";
 const DISPLAY_DEFINITION_KINDS = new Map([
@@ -42,6 +43,7 @@ Commands:
   sync-workspace --workspace <id>
   workflow-get --workflow tapd:<id> [--flow-id <id>] [--runtime-only]
   workflow-report --workflow tapd:<id> --file <report.json> [--expected-revision <revision>]
+  workflow-artifact-publish --workflow tapd:<id> --file <artifact.json>
 `;
 }
@@ -387,12 +389,13 @@ async function main() {
     const flowId = option(args, "flow-id") || option(args, "flow");
     const flowSource = option(args, "flow-source") || "user";
     const runtimeOnly = args["runtime-only"] === true || args.cached === true ? "1" : "";
-    printJson(await httpJson(args, `/api/workflows/state${query({
+    const client = createWorkflowReportClient({ baseUrl: normalizedBaseUrl(args), token: authToken(args) });
+    printJson(await client.getState({
       workflow: workflow.key,
       flowId,
       flowSource,
-      runtimeOnly,
-    })}`));
+      runtimeOnly: runtimeOnly === "1",
+    }));
     return;
   }
@@ -411,7 +414,24 @@ async function main() {
     if (idempotencyKey) body.idempotencyKey = idempotencyKey;
     if (flowId) body.flowId = flowId;
     if (flowSource) body.flowSource = flowSource;
-    printJson(await httpJson(args, "/api/workflows/report", { method: "POST", body }));
+    const client = createWorkflowReportClient({ baseUrl: normalizedBaseUrl(args), token: authToken(args) });
+    printJson(await client.report(body));
+    return;
+  }
+  if (command === "workflow-artifact-publish") {
+    const body = readJsonFile(option(args, "file"));
+    const workflow = workflowReferenceFromArgs(args, false) || parseWorkflowReference(body?.workflow?.key || "");
+    if (!workflow && !(body?.workflow?.namespace && body?.workflow?.id)) {
+      throw new Error("Missing workflow reference. Pass --workflow namespace:id or include workflow.namespace and workflow.id in the JSON file.");
+    }
+    if (workflow) body.workflow = workflow;
+    const flowId = option(args, "flow-id") || option(args, "flow");
+    const flowSource = option(args, "flow-source");
+    if (flowId) body.flowId = flowId;
+    if (flowSource) body.flowSource = flowSource;
+    const client = createWorkflowReportClient({ baseUrl: normalizedBaseUrl(args), token: authToken(args) });
+    printJson(await client.publishArtifact(body));
     return;
   }

package/skills/agentflow-cli/scripts/workflow-report-client.mjs ADDED Viewed

@@ -0,0 +1,68 @@
+function cleanBaseUrl(value) {
+  return String(value || "").trim().replace(/\/+$/, "");
+}
+function workflowQuery(params = {}) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === "") continue;
+    search.set(key, String(value));
+  }
+  const text = search.toString();
+  return text ? `?${text}` : "";
+}
+export function createWorkflowReportClient({ baseUrl, token, fetchImpl = globalThis.fetch } = {}) {
+  const origin = cleanBaseUrl(baseUrl);
+  const credential = String(token || "").trim();
+  if (!origin) throw new Error("Workflow Report client requires baseUrl");
+  if (!credential) throw new Error("Workflow Report client requires token");
+  if (typeof fetchImpl !== "function") throw new Error("Workflow Report client requires fetch");
+  const request = async (pathname, { method = "GET", body } = {}) => {
+    const url = new URL(pathname, `${origin}/`);
+    const headers = {
+      Accept: "application/json",
+      Authorization: `Bearer ${credential}`,
+      Cookie: `af_session=${encodeURIComponent(credential)}`,
+    };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    const response = await fetchImpl(url, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    let data = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = { text };
+    }
+    if (!response.ok) {
+      const message = data?.error || data?.message || text || `HTTP ${response.status}`;
+      const error = new Error(`${method} ${url.pathname} failed: ${message}`);
+      error.status = response.status;
+      error.data = data;
+      throw error;
+    }
+    return data;
+  };
+  return {
+    getState({ workflow, flowId = "", flowSource = "user", runtimeOnly = false } = {}) {
+      return request(`/api/workflows/state${workflowQuery({
+        workflow,
+        flowId,
+        flowSource,
+        runtimeOnly: runtimeOnly ? "1" : "",
+      })}`);
+    },
+    report(body = {}) {
+      return request("/api/workflows/report", { method: "POST", body });
+    },
+    publishArtifact(body = {}) {
+      return request("/api/workflow-artifacts/publish", { method: "POST", body });
+    },
+  };
+}

package/skills/agentflow-workflow-report/SKILL.md ADDED Viewed

@@ -0,0 +1,100 @@
+---
+name: agentflow-workflow-report
+description: Safely read, merge, and report AgentFlow Workflow actions, artifacts, producer-owned global state, and generic timeline projections through the AgentFlow CLI and HTTP protocol. Use when an AI agent or producer such as prd-flow needs to integrate Workflow reporting, publish progress or evidence, update globalState, assign version/sprint/milestone timeline membership, clear projections, or resolve revision and idempotency conflicts.
+---
+# AgentFlow Workflow Report
+Treat Workflow reporting as one canonical producer-adapter protocol. The producer reports facts through `POST /api/workflows/report`; AgentFlow alone materializes and returns `snapshot`. Do not introduce producer-specific write endpoints for new integrations.
+## Prerequisites
+Use the Workflow Report client bundled with the sibling `agentflow-cli` skill. The CLI is its command-line wrapper for AI, scripts, and local verification:
+```bash
+node skills/agentflow-cli/scripts/agentflow-cli.mjs <command> [options]
+```
+If the script is unavailable, install `agentflow-cli` beside this skill. Require `AGENTFLOW_TOKEN` or `AGENTFLOW_SESSION_TOKEN`; never print either token. Use `AGENTFLOW_BASE_URL` only when overriding the default service.
+Read [references/protocol.md](references/protocol.md) completely before implementing a producer, changing the report contract, constructing a payload, or answering questions about parameters, permissions, merge behavior, custom panels, and visible UI results.
+## Required sequence
+1. Resolve a canonical Workflow reference such as `tapd:1015046`. The report schema is producer-generic, but the current AgentFlow identity adapter accepts only the `tapd` namespace. Do not claim that arbitrary Workflow namespaces already work.
+2. Read the current materialized state and retain `snapshot.runtimeRevision`:
+```bash
+node skills/agentflow-cli/scripts/agentflow-cli.mjs workflow-get \
+  --workflow tapd:1015046 \
+  --runtime-only
+```
+3. Compute only the intended semantic update. Choose one stable lowercase `source` for the business adapter (for example `prd-flow` or `release-bot`). `agentflow-cli` is only transport and must not replace the real producer identity.
+4. Preserve unrelated `globalState` fields. Never infer or rewrite a producer's private schema.
+5. When timeline membership changes, derive the complete current `projections.timeline` array from producer state. Use `[]` to clear it.
+6. Write the payload to a JSON file and report it with the retained revision and a stable operation key:
+```bash
+node skills/agentflow-cli/scripts/agentflow-cli.mjs workflow-report \
+  --workflow tapd:1015046 \
+  --file workflow-report.json \
+  --expected-revision 'runtime:current-revision' \
+  --idempotency-key 'implementation-finished:android:issue-2:v1'
+```
+7. On HTTP 409, fetch the latest state, reapply the intended semantic update, and retry once with the new revision. Never send a client field named `snapshot`; use `observation.state` for a complete producer observation and treat returned `snapshot` as server output.
+## Report selection
+Include at least one capability:
+- `observation`: report the producer's complete current observation when it computes a deterministic workflow view.
+- `action`: report a stable progress or lifecycle event.
+- `artifacts`: attach evidence; use stable artifact keys.
+- `globalState`: merge producer-owned durable state or remove explicit paths.
+- `projections`: replace generic derived indexes used by AgentFlow dashboards.
+- `extensions`: report namespaced data for a registered specialized renderer, such as `extensions["prd-flow"].issues`.
+Map data to the visible page deliberately:
+- Global area: `observation.state`, incremental producer facts in `globalState`, and iteration membership in `projections.timeline`.
+- Action timeline: stable `action.key` plus Action-scoped `artifacts`.
+- Generic custom cards: use `globalState.sections` with built-in `text`, `user`, `chips`, `list`, and `link` field renderers.
+- Specialized custom area: use namespaced `extensions` only when built-in renderers cannot express the layout. Saving an extension does not create a UI by itself; currently only `extensions["prd-flow"]` has a registered AI Docs / Issues renderer.
+Use projection-only reports when the producer state is already current and only dashboard membership needs synchronization.
+For local Markdown or other content that must become a browser URL, publish it first with `workflow-artifact-publish` (`POST /api/workflow-artifacts/publish`), then use the returned Artifact in the same Workflow. Do not use `/api/prd-workflow/review-link` for new integrations.
+## Non-negotiable rules
+- Keep `schemaVersion` at `1` unless the server advertises another version.
+- Keep the runtime chain singular: producer adapter → Workflow Report client → AgentFlow. The Skill is guidance, not a transport hop.
+- Give every action a stable `key`.
+- Send a stable lowercase `source` on every report and Markdown publish. Action, idempotency, and Artifact identities are isolated by `source + key`; `globalState` and the complete timeline remain shared read-merge-write regions.
+- Give every timeline entry stable `kind` and `id` values.
+- Treat `dimensions` as opaque facets; do not hardcode Android, iOS, version, or prd-flow fields into AgentFlow state.
+- Treat `globalState` as the source of truth owned by the producer; treat projections as replaceable derived views.
+- Send the complete current timeline array whenever changing it. Omitting `projections` means no projection change.
+- Use `expectedRevision` for state or projection changes and a stable `idempotencyKey` for every logical operation.
+- Do not include credentials, tokens, cookies, or private environment values in actions, artifacts, state, projections, or logs.
+## Permissions and overwrite semantics
+- Treat the first authenticated reporter as owner when the Workflow has no collaboration record.
+- Allow owner and explicit editor writes. Treat explicit viewer, same-team viewer, share-link viewer, and admin review as read-only.
+- `observation.state` replaces the complete previous observation for the same `clientId`.
+- `globalState.patch` recursively merges objects; arrays and scalars replace; `null` and `remove` delete explicit paths.
+- Reusing an `action.key` updates the same semantic stage. Do not create a new key for refreshes or retries.
+- `projections.timeline` replaces the complete array. Read first and preserve entries outside the producer's ownership.
+- `extensions` recursively merge within valid namespaces; arrays and scalars replace, and `null` deletes producer-owned fields.
+- Publishing Markdown creates or updates a preview Artifact and review copy; it does not confirm a document or advance an Action.
+## Failure handling
+- Missing token: stop and ask the user to configure `AGENTFLOW_TOKEN`.
+- HTTP 401/403: stop; do not retry with a token printed in a command or answer.
+- HTTP 409: follow the single read-merge-retry sequence.
+- HTTP 400: fix the payload against the protocol reference; do not weaken validation.
+- Replayed idempotency key from the same `source`: accept `alreadyApplied: true` as success. Markdown publish returns the previously created preview instead of creating another copy.

package/skills/agentflow-workflow-report/agents/openai.yaml ADDED Viewed

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AgentFlow Workflow Report"
+  short_description: "Read and report Workflow state safely with a stable protocol"
+  default_prompt: "Use $agentflow-workflow-report to read the current Workflow, merge the intended update, and report it with revision and idempotency safeguards."