Workflow AI Coding

Workflow AI Coding

Operating Rules

Treat the ReachAI platform repository and live API responses as the source of truth. Do not edit runtime_workflow or runtime_workflow_resource_binding rows directly. All graph and binding changes go through Workflow AI Coding REST endpoints under /api/workflows/.../ai-coding.

凡是写入 ReachAI 或展示给业务用户的名称、标题、描述、说明、System Prompt、节点名称、审计原因、进度和结果，默认使用清晰的简体中文。不要仅因 API、Schema 或字段名为英文就生成英文业务文案。Token、MCP、AI、Agent、Supervisor、Workflow、Tool、API、SDK 等熟知专业术语，以及 keySlug、toolName、代码、路径、枚举值、协议字段和技术标识可保留英文；必要时使用“中文名称（英文术语）”。不要翻译或改写技术标识。

Core mental model:

• GraphSpec is runtime semantics; canvas_json is layout only.
• Create projects and lays out canvas from GraphSpec; patch defaults layout.autoLayout=true. The layered policy uses LR flow, 88px inter-layer boundary gaps, 56px same-layer gaps, and cycle-safe component packing. Before reporting back, confirm canvas_json.nodes[].position is non-overlapping and aligned; do not patch GraphSpec only and skip canvas synchronization.
• START and END are Studio-only virtual canvas nodes. They never appear in GraphSpec nodes or edges.
• Every workflow must set graphSpec.entryNodeId to a real node id and list every terminal node in graphSpec.exitNodeIds.
• Workflow AI Coding updates the Working Copy until an explicit publish request is made.
• Workflow AI Coding may publish a validated Working Copy through POST /api/workflows/{workflowId}/ai-coding/publish; publish still runs release validation and creates an ACTIVE runtime_workflow_version.
• Always read GET .../context before patching or publishing. Use the latest workflow.updatedAt as baseRevision when saving and publishing.
• First-class resource bindings may be replaced only while the Workflow is DRAFT, through PUT .../resource-bindings with the latest baseRevision. They are immutable after the first publish.
• Node openness can be variant-specific. Read nodeTypes[].enabledVariants; for INTERACTION, only PRESENT_OUTPUT is currently open. Do not infer that COLLECT_INPUT, USER_CHOICE, CONFIRM_ACTION or other pause/resume variants are available merely because the INTERACTION type appears in the catalog.
• Default patch behavior is dryRun=true. Only set dryRun=false after validation passes.

Authentication: Workflow AI Coding endpoints use aiCodingKey only (no platform Bearer). Obtain the project-level key from ReachAI 项目详情 → AI Coding 接入秘钥. Send it on every request as header X-ReachAI-AiCoding-Key; do not put the key in generated URLs, scripts, logs, or browser runtime code. Missing key returns 401; invalid or disabled key returns 403. API base URL depends on deployment; use the base URL in the current project or task handoff context.

Do not use platform login cookies or Bearer tokens for /api/workflows/**/ai-coding/**.

Windows / PowerShell UTF-8 Requirements

When calling Workflow AI Coding APIs from Windows, prevent Chinese text from being stored as ????:

1. Prefer PowerShell 7+ (pwsh).

2. At the top of scripts, set UTF-8 explicitly:

   [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
   [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
   $OutputEncoding = [System.Text.UTF8Encoding]::new($false)

3. Write complex request bodies to standalone .json files saved as UTF-8.

4. Use curl.exe, not the PowerShell curl alias:

   curl.exe -X POST $url -H "X-ReachAI-AiCoding-Key: $AI_CODING_KEY" -H "Content-Type: application/json; charset=utf-8" --data-binary "@request.json"

5. If using Invoke-RestMethod, send UTF-8 bytes rather than a plain string body:

   $json = Get-Content .\request.json -Raw -Encoding utf8
   $bodyBytes = [System.Text.Encoding]::UTF8.GetBytes($json)
   Invoke-RestMethod -Method Post -Uri $url -ContentType "application/json; charset=utf-8" -Body $bodyBytes

6. Save generated script files as UTF-8. In Windows PowerShell 5.1, specify UTF-8 explicitly when writing files.

7. Do not inline JSON containing Chinese text directly in the command line.

Standard Workflow Loop

1. Optional create: POST /api/workflows/ai-coding/workflows
2. Read world: GET /api/workflows/{workflowId}/ai-coding/context
3. If an unbound DRAFT needs page scope, replace it once through PUT .../resource-bindings
4. Preview edits: POST /api/workflows/{workflowId}/ai-coding/patch with dryRun=true
5. Validate proposed graph: POST /api/workflows/{workflowId}/ai-coding/validate with mode=PROPOSED
6. Save draft: POST /api/workflows/{workflowId}/ai-coding/patch with dryRun=false and matching baseRevision
7. Debug:
   • POST .../run with dryRun=true first
   • then POST .../run with real input when safe
8. Inspect runs:
   • GET .../runs?limit=&days=
   • GET .../runs/{traceId}
9. Check release readiness: GET .../versions
10. Re-read context, then publish when release validation is valid: POST .../publish with the latest workflow.updatedAt as baseRevision
11. Report: changed nodes/edges, validation result, traceId, release readiness, published version, and any remaining issues

For any branch that returns structured business data, do not stop at an ANSWER that serializes the object as Markdown. Add a downstream display-only INTERACTION/PRESENT_OUTPUT node. Use list_card for list/page results, output_card/card/detail for one object, an explicit dataExpression such as nodeOutput.read_table, and presentation.mode=card_only or text_and_card. Browser acceptance must observe both the real ui.requested SSE event and the rendered card DOM.

Endpoint Map

Create workflow

POST /api/workflows/ai-coding/workflows

Required body fields:

• name
• keySlug (slug format enforced by platform)
• projectId
• projectCode (must match the registered project for projectId; comparison is case-insensitive)

Optional:

• description, workflowKind (default GENERAL), executionEngine (default GRAPH_SPEC)
• defaultModelInstanceId
• graphSpec, canvas, extra
• resourceBindings; required for PAGE_ASSISTANT
• reason (audit note)

Returns full WorkflowAiCodingContextResponse.

Example:

{
  "name": "订单页面助手",
  "keySlug": "orders-page-assistant",
  "projectId": 7,
  "projectCode": "orders",
  "workflowKind": "PAGE_ASSISTANT",
  "resourceBindings": [
    {
      "resourceType": "PAGE",
      "resourceKey": "orders.list",
      "bindingRole": "TARGET"
    }
  ],
  "reason": "为 AI Coding 创建初始草稿"
}

PAGE_ASSISTANT requires exactly one TARGET PAGE binding. Add other in-scope pages as RELATED bindings. Do not encode page ownership in extra or invent page keys.

Replace draft resource bindings

PUT /api/workflows/{workflowId}/ai-coding/resource-bindings

Use this only to repair or complete the resource scope of a DRAFT before its first publish. Send the latest context workflow.updatedAt as required baseRevision, plus the complete replacement resourceBindings list. PAGE_ASSISTANT still requires exactly one TARGET PAGE. The operation advances workflow.updatedAt; re-read context before any following save. Once status is ACTIVE, bindings are immutable and the platform rejects the request.