diff --git a/docs/en-US/workflow-graph.md b/docs/en-US/workflow-graph.md index 15e9981a..46ae5c62 100644 --- a/docs/en-US/workflow-graph.md +++ b/docs/en-US/workflow-graph.md @@ -34,7 +34,39 @@ Saved workflows can be bound to a role under **Role Management**. When `workflow --- -## 3. Execution model (read this before configuring) +## 3. Natural-language Draft Generation + +The Workflows page provides a **Create from natural language** entry point. After a user describes a security operations goal, CyberStrikeAI generates an editable draft and returns a structured audit result: + +- Draft generation does not save, dry-run, or execute tools automatically. +- The server endpoint is `POST /api/workflows/generate-draft`, protected by `workflow:write`. +- The response includes `graph`, `meta`, `capabilities`, `audit`, and `stats`; after applying the draft to the canvas, normal save validation still runs. +- High-risk language such as executing scripts, isolating hosts, blocking, deleting, or exploitation is marked as `high_risk` and defaults to HITL approval or `requires_human_confirmation`. +- Tool capabilities are matched against the available tool list; unmatched capabilities fall back to Agent draft nodes and are surfaced in `audit.missing_fields` / `audit.assumptions`. +- If server generation is unavailable, the frontend uses a local deterministic fallback and still returns an editable draft with risk notes. + +Example request: + +```http +POST /api/workflows/generate-draft +Content-Type: application/json + +{ + "prompt": "Scan target assets for open ports, create a vulnerability task when critical ports are found, ask the owner for approval, and output a report", + "options": { + "include_objective": true, + "allow_schedule": false, + "allow_high_risk": false + }, + "available_tools": [ + { "key": "nmap", "name": "nmap", "enabled": true } + ] +} +``` + +--- + +## 4. Execution model (read this before configuring) The engine executes the workflow as a **directed graph**, starting from the **Start** node and following edges to downstream nodes. @@ -116,7 +148,7 @@ Agent B still receives Agent A’s output even when a condition node lies betwee --- -## 4. Template syntax +## 5. Template syntax ### 4.1 Basic format @@ -198,7 +230,7 @@ Field bindings can read ordinary fields such as `output` or `message`, and also --- -## 5. Node types and configuration +## 6. Node types and configuration ### 5.1 Start @@ -318,7 +350,7 @@ Optional node for an end summary template (less common in role-bound flows). --- -## 6. Edge configuration +## 7. Edge configuration Select an **edge** to configure its **condition** in the right panel. @@ -335,7 +367,7 @@ If no edge condition is set: --- -## 7. Full example: passing Agent output across a condition +## 8. Full example: passing Agent output across a condition ### 7.1 Graph structure @@ -384,7 +416,7 @@ Start → Agent (initial value) → Condition → Agent (transform) → Output --- -## 8. Bind to a role and run +## 9. Bind to a role and run ### 8.1 Bind in Role Management @@ -414,7 +446,7 @@ If no Output node is reached or no branch matches, `outputs` may be empty and th --- -## 9. Debugging, dry-run, and replay +## 10. Debugging, dry-run, and replay ### 9.1 Safe dry-run @@ -487,7 +519,7 @@ Token and cost metrics depend on whether the underlying model/Agent events repor --- -## 10. Validation before save +## 11. Validation before save On save, the system checks: @@ -510,7 +542,7 @@ On save, the system checks: --- -## 11. Troubleshooting +## 12. Troubleshooting | Symptom | Likely cause | Fix | |---------|--------------|-----| @@ -526,7 +558,7 @@ On save, the system checks: --- -## 12. Best practices +## 13. Best practices 1. **Meaningful names**: Use descriptive output variable names (`scan_result`, `parsed_targets`) instead of reusing `agent_result` everywhere. 2. **Prefer `outputs` for cross-node data**: If a condition, tool, or HITL node might sit in between, use named variables. @@ -539,7 +571,7 @@ On save, the system checks: --- -## 13. Code references (for developers) +## 14. Code references (for developers) | Module | Path | |--------|------| diff --git a/docs/zh-CN/workflow-graph.md b/docs/zh-CN/workflow-graph.md index e383c967..4e3bb060 100644 --- a/docs/zh-CN/workflow-graph.md +++ b/docs/zh-CN/workflow-graph.md @@ -34,7 +34,39 @@ --- -## 三、执行模型(先理解再配置) +## 三、自然语言生成草稿 + +工作流页面提供 **用自然语言创建** 入口。用户描述一句安全作业目标后,平台会生成一个可编辑草稿,并返回结构化审计结果: + +- 只生成草稿,不会自动保存、试运行或真实执行工具。 +- 服务端接口为 `POST /api/workflows/generate-draft`,权限为 `workflow:write`。 +- 生成结果包含 `graph`、`meta`、`capabilities`、`audit` 和 `stats`,前端应用到画布后仍走现有保存校验。 +- 高风险语义(执行脚本、隔离、封禁、删除、利用等)会标记 `high_risk`,并默认插入 HITL 审批或 `requires_human_confirmation`。 +- 工具能力按已有工具列表匹配;未匹配到时降级为 Agent 草稿,并在 `audit.missing_fields` / `audit.assumptions` 中提示需要补配置。 +- 如果服务端生成不可用,前端会使用本地确定性兜底生成器,继续给出可编辑草稿和风险提示。 + +示例请求: + +```http +POST /api/workflows/generate-draft +Content-Type: application/json + +{ + "prompt": "对目标资产做端口扫描,如果发现高危端口就创建漏洞任务并通知负责人审批,最后输出报告", + "options": { + "include_objective": true, + "allow_schedule": false, + "allow_high_risk": false + }, + "available_tools": [ + { "key": "nmap", "name": "nmap", "enabled": true } + ] +} +``` + +--- + +## 四、执行模型(先理解再配置) 工作流按 **有向图** 执行,引擎从 **开始** 节点出发,沿连线依次运行下游节点。 @@ -116,7 +148,7 @@ outputs["你填的变量名"] = 节点输出内容 --- -## 四、模板语法 +## 五、模板语法 ### 4.1 基本格式 @@ -198,7 +230,7 @@ jq({{outputs.scan}}, ".severity") == "high" --- -## 五、节点类型与配置 +## 六、节点类型与配置 ### 5.1 开始(start) @@ -318,7 +350,7 @@ HITL 等待信息会记录: --- -## 六、连线配置 +## 七、连线配置 选中 **连线** 后,右侧可配置 **连线条件**。 @@ -335,7 +367,7 @@ HITL 等待信息会记录: --- -## 七、完整示例:跨条件节点传递 Agent 输出 +## 八、完整示例:跨条件节点传递 Agent 输出 ### 7.1 流程结构 @@ -384,7 +416,7 @@ HITL 等待信息会记录: --- -## 八、绑定角色并运行 +## 九、绑定角色并运行 ### 8.1 在角色管理中绑定 @@ -414,7 +446,7 @@ workflow_policy: auto --- -## 九、调试、试运行与复盘 +## 十、调试、试运行与复盘 ### 9.1 安全试运行(dry-run) @@ -487,7 +519,7 @@ token 与成本是否存在取决于底层模型/Agent 事件是否上报 usage --- -## 十、保存前校验规则 +## 十一、保存前校验规则 保存时系统会自动检查: @@ -510,7 +542,7 @@ token 与成本是否存在取决于底层模型/Agent 事件是否上报 usage --- -## 十一、排错指南 +## 十二、排错指南 | 现象 | 可能原因 | 处理建议 | |------|----------|----------| @@ -526,7 +558,7 @@ token 与成本是否存在取决于底层模型/Agent 事件是否上报 usage --- -## 十二、最佳实践 +## 十三、最佳实践 1. **命名规范**:为每个需要被引用的节点设置有意义的输出变量名,如 `scan_result`、`parsed_targets`,避免都叫 `agent_result`。 2. **跨节点传参优先用 `outputs`**:只要中间可能插入条件、工具、审批节点,就应用命名变量。 @@ -539,7 +571,7 @@ token 与成本是否存在取决于底层模型/Agent 事件是否上报 usage --- -## 十三、相关代码位置(开发者参考) +## 十四、相关代码位置(开发者参考) | 模块 | 路径 | |------|------|