代码提交

This commit is contained in:
董宏凯 committed 2026-08-30 01:25:20 +08:00
1 parent 4ac7bc21cd
commit 17cf849361
110 files changed
+17007 -518

No files matched your search

@@ -0,0 +1,287 @@
"""Workflow data sources and HTTP credentials.
Write-only secrets: the DSN (or the credential header blob) is accepted on
create/update, encrypted immediately, and never returned. Reads expose only a
masked target so an operator can tell two sources apart.
Shared sources (``ownerId`` null) are admin-only; a regular user may manage
their own.
"""
from __future__ import annotations
import json
from typing import Any
from urllib.parse import urlsplit
from fastapi import APIRouter, HTTPException, Request
from pydantic import BaseModel, Field
from app.gateway.deps import get_current_user, get_optional_user_from_request
from app.gateway.workflow_audit import audit_workflow
from deerflow.config.app_config import get_app_config
from deerflow.workflows.security.secret_box import SecretKeyMissingError, secrets_available
from deerflow.workflows.security.sql_policy import assert_read_only, assert_tables_allowed
router = APIRouter(prefix="/api/workflows/data-sources", tags=["workflow-data-sources"])
_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"})
class DataSourceCreate(BaseModel):
name: str = Field(min_length=1, max_length=191)
description: str = ""
kind: str = Field(default="sql", pattern="^(sql|http)$")
dsn: str | None = None
headers: dict[str, str] | None = None
base_url: str = Field(default="", max_length=2048, alias="baseUrl")
allowed_methods: list[str] = Field(default_factory=list, alias="allowedMethods")
max_rows: int = Field(default=1000, ge=1, le=100_000, alias="maxRows")
allowed_tables: list[str] = Field(default_factory=list, alias="allowedTables")
enabled: bool = True
shared: bool = False
model_config = {"populate_by_name": True}
class QueryBody(BaseModel):
statement: str = Field(min_length=1)
class DataSourceUpdate(BaseModel):
name: str | None = Field(default=None, min_length=1, max_length=191)
description: str | None = None
dsn: str | None = None
headers: dict[str, str] | None = None
base_url: str | None = Field(default=None, max_length=2048, alias="baseUrl")
allowed_methods: list[str] | None = Field(default=None, alias="allowedMethods")
max_rows: int | None = Field(default=None, ge=1, le=100_000, alias="maxRows")
allowed_tables: list[str] | None = Field(default=None, alias="allowedTables")
enabled: bool | None = None
model_config = {"populate_by_name": True}
def _require_enabled() -> None:
if not get_app_config().workflows.enabled:
raise HTTPException(status_code=503, detail="Workflow Studio is disabled")
def _store(request: Request):
store = getattr(request.app.state, "workflow_data_source_store", None)
if store is None:
raise HTTPException(status_code=503, detail="Workflow data source store not available")
return store
async def _is_admin(request: Request) -> bool:
user = await get_optional_user_from_request(request)
return user is not None and getattr(user, "system_role", None) == "admin"
def _normalise_http_metadata(
base_url: str,
allowed_methods: list[str],
) -> tuple[str, list[str]]:
target = base_url.strip()
try:
parsed = urlsplit(target)
except ValueError as exc:
raise HTTPException(status_code=400, detail="HTTP 接口地址格式无效") from exc
if (
parsed.scheme not in {"http", "https"}
or not parsed.netloc
or parsed.username is not None
or parsed.password is not None
or parsed.query
or parsed.fragment
):
raise HTTPException(
status_code=400,
detail="HTTP 接口地址必须是无凭据、无查询参数的 http(s) 地址",
)
normalised_methods: list[str] = []
for raw_method in allowed_methods:
method = str(raw_method).strip().upper()
if method not in _HTTP_METHODS:
raise HTTPException(status_code=400, detail=f"不支持的 HTTP 方法:{method}")
if method not in normalised_methods:
normalised_methods.append(method)
if not normalised_methods:
raise HTTPException(status_code=400, detail="至少选择一种 HTTP 方法")
return target, normalised_methods
def _normalise_headers(headers: dict[str, str] | None) -> dict[str, str]:
normalised: dict[str, str] = {}
for raw_name, raw_value in (headers or {}).items():
name = str(raw_name).strip()
value = str(raw_value)
if not name or any(char in name + value for char in "\r\n"):
raise HTTPException(status_code=400, detail="HTTP 请求头格式无效")
normalised[name] = value
return normalised
def _secret_from(kind: str, dsn: str | None, headers: dict[str, str] | None) -> str:
if kind == "http":
return json.dumps({"headers": _normalise_headers(headers)}, ensure_ascii=False)
if not dsn:
raise HTTPException(status_code=400, detail="SQL 数据源需要提供 dsn")
if "://" not in dsn:
raise HTTPException(status_code=400, detail="dsn 格式无效")
return dsn
@router.get("")
async def list_data_sources(request: Request) -> dict[str, Any]:
_require_enabled()
user_id = await get_current_user(request)
rows = await _store(request).list_sources(owner_id=user_id)
return {"dataSources": rows, "secretsEncryptionAvailable": secrets_available()}
@router.post("")
async def create_data_source(request: Request, body: DataSourceCreate) -> dict[str, Any]:
_require_enabled()
user_id = await get_current_user(request)
is_admin = await _is_admin(request)
if body.shared and not is_admin:
raise HTTPException(status_code=403, detail="仅管理员可创建共享数据源")
secret = _secret_from(body.kind, body.dsn, body.headers)
base_url = ""
allowed_methods: list[str] = []
if body.kind == "http":
base_url, allowed_methods = _normalise_http_metadata(
body.base_url,
body.allowed_methods,
)
try:
created = await _store(request).create_source(
{
"name": body.name,
"description": body.description,
"kind": body.kind,
"dsn": secret,
"base_url": base_url,
"allowed_methods": allowed_methods,
"max_rows": body.max_rows,
"allowed_tables": body.allowed_tables,
"enabled": body.enabled,
"owner_id": None if body.shared else user_id,
"created_by": user_id,
}
)
except SecretKeyMissingError as exc:
raise HTTPException(
status_code=503,
detail={
"code": "WORKFLOW_RESOURCE_MISSING",
"message": "服务端未配置 WORKFLOW_SECRET_KEY,无法安全保存连接信息",
},
) from exc
audit_workflow("data_source.create", user_id=user_id, dataSourceId=created["id"], kind=body.kind, shared=body.shared)
return created
async def _owned(request: Request, source_id: str) -> dict[str, Any]:
row = await _store(request).get_source(source_id)
if row is None:
raise HTTPException(status_code=404, detail="数据源不存在")
user_id = await get_current_user(request)
if row.get("owner_id") == user_id:
return row
if await _is_admin(request):
return row
raise HTTPException(status_code=403, detail="无权操作该数据源")
async def _visible(request: Request, source_id: str) -> dict[str, Any]:
row = await _store(request).get_source(source_id)
if row is None:
raise HTTPException(status_code=404, detail="数据源不存在")
user_id = await get_current_user(request)
if row.get("owner_id") in (user_id, None):
return row
if await _is_admin(request):
return row
raise HTTPException(status_code=403, detail="无权查看该数据源")
@router.get("/{source_id}")
async def get_data_source(request: Request, source_id: str) -> dict[str, Any]:
_require_enabled()
return await _visible(request, source_id)
@router.post("/{source_id}/introspect")
async def introspect_data_source(request: Request, source_id: str) -> dict[str, Any]:
"""Return the configured table allowlist only — never sample rows."""
_require_enabled()
row = await _visible(request, source_id)
tables = list(row.get("allowed_tables") or [])
return {
"dataSourceId": row["id"],
"kind": row.get("kind"),
"tables": [{"name": name} for name in tables],
"schemas": [],
}
@router.post("/{source_id}/validate-query")
async def validate_data_source_query(request: Request, source_id: str, body: QueryBody) -> dict[str, Any]:
"""Validate SQL against the read-only policy without executing it."""
_require_enabled()
row = await _visible(request, source_id)
try:
statement = assert_read_only(body.statement)
assert_tables_allowed(statement, list(row.get("allowed_tables") or []))
except Exception as exc: # noqa: BLE001
from deerflow.workflows.errors import WorkflowError
if isinstance(exc, WorkflowError):
raise HTTPException(status_code=400, detail=exc.to_body().model_dump(by_alias=True)) from exc
raise
audit_workflow("data_source.validate_query", user_id=await get_current_user(request), dataSourceId=source_id)
return {"ok": True, "statement": statement}
@router.put("/{source_id}")
async def update_data_source(request: Request, source_id: str, body: DataSourceUpdate) -> dict[str, Any]:
_require_enabled()
row = await _owned(request, source_id)
payload = body.model_dump(exclude_unset=True, by_alias=False)
kind = str(row.get("kind") or "sql")
if body.dsn is not None or body.headers is not None:
payload["dsn"] = _secret_from(kind, body.dsn, body.headers)
payload.pop("headers", None)
if kind == "http":
base_url, allowed_methods = _normalise_http_metadata(
body.base_url if body.base_url is not None else str(row.get("base_url") or ""),
body.allowed_methods
if body.allowed_methods is not None
else list(row.get("allowed_methods") or []),
)
payload["base_url"] = base_url
payload["allowed_methods"] = allowed_methods
else:
payload.pop("base_url", None)
payload.pop("allowed_methods", None)
try:
updated = await _store(request).update_source(source_id, payload)
except SecretKeyMissingError as exc:
raise HTTPException(status_code=503, detail="服务端未配置 WORKFLOW_SECRET_KEY") from exc
if updated is None:
raise HTTPException(status_code=404, detail="数据源不存在")
audit_workflow("data_source.update", user_id=await get_current_user(request), dataSourceId=source_id)
return updated
@router.delete("/{source_id}")
async def delete_data_source(request: Request, source_id: str) -> dict[str, Any]:
_require_enabled()
await _owned(request, source_id)
deleted = await _store(request).delete_source(source_id)
audit_workflow("data_source.delete", user_id=await get_current_user(request), dataSourceId=source_id)
return {"deleted": deleted}
@@ -0,0 +1,186 @@
"""iframe embedding support: origin allowlist + short-lived signed tickets.
Scope, stated plainly: a ticket proves *"this workflow may be embedded by this
origin, for this user, right now"*. It is **not** an API credential — embedded
pages still authenticate their API calls with the normal session, exactly like
the rest of the app's iframe surfaces. What the ticket adds is an explicit
origin decision that can be audited, plus the ``frame-ancestors`` value the host
should send.
Tickets are stateless HS256 JWTs (so any worker can verify them) with a 60s
default TTL. Single-use is enforced best-effort per process via a replay cache;
the short TTL is the real protection.
"""
from __future__ import annotations
import hashlib
import logging
import os
import time
from typing import Any
from urllib.parse import urlparse
import jwt
from fastapi import APIRouter, HTTPException, Request
from pydantic import BaseModel, Field
from app.gateway.deps import get_current_user
from deerflow.config.app_config import get_app_config
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/workflows/embed", tags=["workflow-embed"])
_ALGORITHM = "HS256"
_AUDIENCE = "workflow-embed"
_replay_cache: dict[str, float] = {}
_REPLAY_CACHE_MAX = 4096
class TicketRequest(BaseModel):
workflow_id: str = Field(alias="workflowId")
origin: str
model_config = {"populate_by_name": True}
class VerifyRequest(BaseModel):
ticket: str
origin: str | None = None
def _signing_key() -> str:
for name in ("WORKFLOW_SECRET_KEY", "DEERFLOW_SECRET_KEY", "JWT_SECRET_KEY"):
value = os.environ.get(name)
if value and value.strip():
return hashlib.sha256(value.strip().encode("utf-8")).hexdigest()
raise HTTPException(
status_code=503,
detail={
"code": "WORKFLOW_EMBED_TICKET_INVALID",
"message": "服务端未配置签名密钥,无法签发嵌入票据",
},
)
def _normalize_origin(raw: str) -> str:
parsed = urlparse(raw.strip())
if not parsed.scheme or not parsed.netloc:
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_EMBED_ORIGIN_DENIED", "message": "origin 格式无效"},
)
return f"{parsed.scheme.lower()}://{parsed.netloc.lower()}"
def _assert_origin_allowed(origin: str) -> str:
cfg = get_app_config().workflows.embed
normalized = _normalize_origin(origin)
allowed = {_normalize_origin(o) for o in cfg.allowed_origins if o.strip()}
if not allowed:
raise HTTPException(
status_code=403,
detail={
"code": "WORKFLOW_EMBED_ORIGIN_DENIED",
"message": "未配置任何允许的嵌入来源(workflows.embed.allowed_origins)",
},
)
if normalized not in allowed:
logger.warning("workflow embed origin denied: %s", normalized)
raise HTTPException(
status_code=403,
detail={"code": "WORKFLOW_EMBED_ORIGIN_DENIED", "message": "该来源不允许嵌入"},
)
return normalized
def _prune_replay_cache(now: float) -> None:
for key, expiry in list(_replay_cache.items()):
if expiry <= now:
_replay_cache.pop(key, None)
if len(_replay_cache) > _REPLAY_CACHE_MAX:
_replay_cache.clear()
@router.post("/tickets")
async def issue_ticket(request: Request, body: TicketRequest) -> dict[str, Any]:
cfg = get_app_config().workflows
if not cfg.enabled:
raise HTTPException(status_code=503, detail="Workflow Studio is disabled")
user_id = await get_current_user(request)
origin = _assert_origin_allowed(body.origin)
definitions = getattr(request.app.state, "workflow_store", None)
if definitions is None:
raise HTTPException(status_code=503, detail="Workflow store not available")
definition = await definitions.get_definition(body.workflow_id, include_draft=False)
if definition is None:
raise HTTPException(status_code=404, detail="工作流不存在")
if definition.get("owner_id") != user_id:
raise HTTPException(status_code=403, detail={"code": "WORKFLOW_FORBIDDEN", "message": "无权嵌入该工作流"})
now = int(time.time())
ttl = cfg.embed.ticket_ttl_seconds
payload = {
"aud": _AUDIENCE,
"sub": user_id,
"wf": body.workflow_id,
"org": origin,
"iat": now,
"exp": now + ttl,
"jti": hashlib.sha256(f"{user_id}{body.workflow_id}{origin}{now}".encode()).hexdigest()[:32],
}
ticket = jwt.encode(payload, _signing_key(), algorithm=_ALGORITHM)
logger.info(
"workflow embed ticket issued workflow=%s user=%s origin=%s ttl=%ss",
body.workflow_id,
user_id,
origin,
ttl,
)
return {
"ticket": ticket,
"expiresIn": ttl,
"origin": origin,
"frameAncestors": sorted({_normalize_origin(o) for o in cfg.embed.allowed_origins if o.strip()}),
}
@router.post("/verify")
async def verify_ticket(body: VerifyRequest) -> dict[str, Any]:
cfg = get_app_config().workflows
if not cfg.enabled:
raise HTTPException(status_code=503, detail="Workflow Studio is disabled")
try:
payload = jwt.decode(body.ticket, _signing_key(), algorithms=[_ALGORITHM], audience=_AUDIENCE)
except jwt.PyJWTError as exc:
raise HTTPException(
status_code=401,
detail={"code": "WORKFLOW_EMBED_TICKET_INVALID", "message": "票据无效或已过期"},
) from exc
if body.origin and _normalize_origin(body.origin) != payload.get("org"):
raise HTTPException(
status_code=403,
detail={"code": "WORKFLOW_EMBED_ORIGIN_DENIED", "message": "票据与当前来源不匹配"},
)
now = time.time()
_prune_replay_cache(now)
jti = str(payload.get("jti") or "")
if jti and jti in _replay_cache:
raise HTTPException(
status_code=401,
detail={"code": "WORKFLOW_EMBED_TICKET_INVALID", "message": "票据已被使用"},
)
if jti:
_replay_cache[jti] = float(payload.get("exp") or now + 60)
return {
"ok": True,
"workflowId": payload.get("wf"),
"userId": payload.get("sub"),
"origin": payload.get("org"),
"expiresAt": payload.get("exp"),
}
@@ -0,0 +1,236 @@
"""Workflow node-type and resource catalog APIs (phase 1)."""
from __future__ import annotations
from typing import Any
from fastapi import APIRouter, HTTPException, Request
from app.gateway.deps import get_current_user, get_local_provider
from deerflow.config.app_config import get_app_config
from deerflow.persistence.workflows import WorkflowStore
from deerflow.workflows.schemas import ALL_NODE_TYPES
router = APIRouter(prefix="/api/workflows", tags=["workflow-resources"])
_NODE_META: dict[str, dict[str, str]] = {
"start": {"label": "开始", "category": "control"},
"output": {"label": "输出", "category": "control"},
"agent": {"label": "智能体", "category": "ai"},
"skill": {"label": "技能", "category": "ai"},
"http": {"label": "HTTP", "category": "data"},
"sql_read": {"label": "SQL 只读", "category": "data"},
"code": {"label": "代码", "category": "data"},
"transform": {"label": "模板/转换", "category": "data"},
"condition": {"label": "条件", "category": "control"},
"merge": {"label": "合并", "category": "control"},
"human_input": {"label": "人工介入", "category": "control"},
"subworkflow": {"label": "子工作流", "category": "control"},
"loop": {"label": "循环", "category": "control"},
}
def _require_enabled() -> None:
if not get_app_config().workflows.enabled:
raise HTTPException(status_code=503, detail="Workflow Studio is disabled")
def _get_store(request: Request) -> WorkflowStore:
store = getattr(request.app.state, "workflow_store", None)
if store is None:
raise HTTPException(status_code=503, detail="Workflow store not available")
return store
async def _resolve_creator_names(user_ids: set[str]) -> dict[str, str]:
"""Resolve resource-owner ids to short display names, best-effort.
The workflow catalog is a small display projection over the agent and
skill stores. Those stores intentionally retain immutable owner ids for
access control; this resolver exposes a friendly creator name without
changing that ownership model. If an account has since disappeared, the
stable id remains a useful audit fallback.
"""
if not user_ids:
return {}
try:
provider = get_local_provider()
except Exception: # noqa: BLE001
return {user_id: user_id for user_id in user_ids}
names: dict[str, str] = {}
for user_id in user_ids:
try:
user = await provider.get_user(user_id)
except Exception: # noqa: BLE001
user = None
email = getattr(user, "email", None) if user is not None else None
if isinstance(email, str) and email:
names[user_id] = email.split("@", 1)[0] or user_id
else:
names[user_id] = user_id
return names
def _creator_label(owner_id: object, creator_names: dict[str, str]) -> str:
"""Return the catalog label for a user-owned or built-in resource."""
if owner_id is None or not str(owner_id).strip():
return "系统内置"
owner_key = str(owner_id)
return creator_names.get(owner_key, owner_key)
@router.get("/node-types")
async def list_node_types(request: Request) -> dict[str, Any]:
_require_enabled()
await get_current_user(request)
items = []
for node_type in ALL_NODE_TYPES:
meta = _NODE_META.get(node_type, {"label": node_type, "category": "other"})
items.append({"type": node_type, **meta})
return {"nodeTypes": items}
@router.get("/resources/agents")
async def list_agent_resources(request: Request) -> dict[str, Any]:
_require_enabled()
user_id = await get_current_user(request)
agent_store = getattr(request.app.state, "agent_store", None)
agents: list[dict[str, Any]] = []
if agent_store is not None:
try:
if hasattr(agent_store, "list_visible"):
rows = await agent_store.list_visible(user_id)
elif hasattr(agent_store, "list_all"):
rows = await agent_store.list_all()
else:
rows = []
creator_names = await _resolve_creator_names({str(row["user_id"]) for row in rows or [] if row.get("user_id") is not None})
agent_ids = [str(row.get("id") or row.get("agent_id") or "") for row in rows or []]
extras_by_agent: dict[str, dict[str, Any]] = {}
if hasattr(agent_store, "get_extras_for"):
extras_by_agent = await agent_store.get_extras_for([agent_id for agent_id in agent_ids if agent_id])
keyword = request.query_params.get("keyword", "").strip().casefold()
for row in rows or []:
agent_id = str(row.get("id") or row.get("agent_id") or "")
name = str(row.get("name") or agent_id)
description = str(row.get("description") or "")
if keyword and keyword not in f"{agent_id} {name} {description}".casefold():
continue
cached_skills = (extras_by_agent.get(agent_id) or {}).get("skills") or []
agents.append(
{
"agentId": agent_id,
"name": name,
"description": description,
"skills": [str(skill) for skill in cached_skills],
"createdBy": _creator_label(row.get("user_id"), creator_names),
}
)
except Exception: # noqa: BLE001
agents = []
return {"agents": agents}
@router.get("/resources/skills")
async def list_skill_resources(request: Request) -> dict[str, Any]:
_require_enabled()
user_id = await get_current_user(request)
skills: list[dict[str, Any]] = []
try:
from deerflow.skills import get_or_new_skill_storage
skill_store = getattr(request.app.state, "skill_store", None)
ownership_by_name: dict[str, dict[str, Any]] = {}
if skill_store is not None and hasattr(skill_store, "list_visible"):
records = await skill_store.list_visible(user_id)
ownership_by_name = {str(record["name"]): record for record in records if record.get("name")}
creator_names = await _resolve_creator_names({str(record["owner_user_id"]) for record in ownership_by_name.values() if record.get("owner_user_id") is not None})
storage = get_or_new_skill_storage()
for skill in storage.load_skills(enabled_only=True) or []:
name = getattr(skill, "name", None)
if not name:
continue
record = ownership_by_name.get(str(name), {})
skills.append(
{
"skillId": name,
"name": name,
"description": getattr(skill, "description", "") or "",
# Workflow direct-skill execution remains opt-in. Older
# Skill definitions do not advertise this capability and
# are therefore correctly shown as agent-only resources.
"callable": bool(getattr(skill, "callable", False)),
"createdBy": _creator_label(record.get("owner_user_id"), creator_names),
}
)
except Exception: # noqa: BLE001
skills = []
return {"skills": skills}
@router.get("/resources/data-sources")
async def list_data_source_resources(request: Request) -> dict[str, Any]:
_require_enabled()
user_id = await get_current_user(request)
store = getattr(request.app.state, "workflow_data_source_store", None)
if store is None:
return {"dataSources": []}
rows = await store.list_sources(owner_id=user_id)
return {
"dataSources": [
{
"id": row["id"],
"dataSourceId": row["id"],
"name": row["name"],
"description": row.get("description") or "",
"kind": row.get("kind"),
"engine": row.get("driver") or "",
"baseUrl": row.get("base_url") or "",
"maskedTarget": row.get("masked_target"),
"enabled": row.get("enabled"),
"readOnly": row.get("kind") == "sql",
"allowedMethods": row.get("allowed_methods") or [],
"allowedTables": row.get("allowed_tables") or [],
}
for row in rows
if row.get("enabled", True)
]
}
@router.get("/resources/credentials")
async def list_credential_resources(request: Request) -> dict[str, Any]:
"""Read-only credential directory: ids and labels only.
HTTP credentials are ``http``-kind data sources; the encrypted header blob
is resolved exclusively by the run executor. This endpoint must never
return headers, tokens, DSNs or ciphertext — a 404-free catalog so the
canvas credential picker does not fail the whole resource panel.
"""
_require_enabled()
user_id = await get_current_user(request)
store = getattr(request.app.state, "workflow_data_source_store", None)
if store is None:
return {"credentials": []}
rows = await store.list_sources(owner_id=user_id, include_shared=True)
return {
"credentials": [
{
"credentialId": row["id"],
"name": row["name"],
"type": "http_headers",
"sourceKind": "http",
}
for row in rows
if str(row.get("kind") or "") == "http" and row.get("enabled", True)
]
}
@router.get("/resources/subworkflows")
async def list_subworkflow_resources(request: Request) -> dict[str, Any]:
_require_enabled()
await get_current_user(request)
store = _get_store(request)
return {"subworkflows": await store.list_published_summaries()}
@@ -0,0 +1,700 @@
"""Workflow run APIs: start / inspect / cancel / resume / retry / events / SSE stream."""
from __future__ import annotations
import asyncio
import json
import logging
from datetime import UTC, datetime
from typing import Any
from fastapi import APIRouter, HTTPException, Query, Request
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field
from app.gateway.deps import get_current_user, get_optional_user_from_request
from app.gateway.workflow_audit import audit_workflow
from deerflow.config.app_config import get_app_config
from deerflow.persistence.workflow_events.base import WorkflowEventStore
from deerflow.persistence.workflow_runs.base import WorkflowRunStore
from deerflow.workflows.runtime.sink import envelope_from_row
from deerflow.workflows.schema_validation import schema_issues
from deerflow.workflows.schemas import WorkflowGraph
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/workflows", tags=["workflow-runs"])
_TERMINAL_STATUSES = ("completed", "failed", "cancelled")
_TERMINAL_EVENTS = ("run.completed", "run.failed", "run.cancelled")
_REPLAY_PAGE = 200
_DB_POLL_SECONDS = 0.8
_LIVE_WAIT_SECONDS = 0.25
_HEARTBEAT_SECONDS = 15.0
_STREAM_DEADLINE_SECONDS = 60 * 60
class StartRunBody(BaseModel):
version_id: str | None = Field(default=None, alias="versionId")
inputs: dict[str, Any] = Field(default_factory=dict)
# 独立 Coze 工作流页早期使用 input/target;保留兼容入口,内部仍只使用 inputs。
input: dict[str, Any] | None = None
target: str | None = None
idempotency_key: str | None = Field(default=None, alias="idempotencyKey", max_length=128)
model_config = {"populate_by_name": True}
def resolved_inputs(self) -> dict[str, Any]:
return self.inputs if self.inputs or self.input is None else self.input
class ResumeRunBody(BaseModel):
resume_token: str = Field(alias="resumeToken")
node_id: str | None = Field(default=None, alias="nodeId")
action: str = "submit"
values: dict[str, Any] = Field(default_factory=dict)
# 兼容独立页的 ResumeRunRequest:payload/message。
payload: dict[str, Any] | None = None
message: str | None = None
model_config = {"populate_by_name": True}
def resolved_values(self) -> dict[str, Any]:
return self.values if self.values or self.payload is None else self.payload
# ── shared plumbing ─────────────────────────────────────────────────────
def _cfg():
return get_app_config().workflows
def _require_enabled() -> None:
if not _cfg().enabled:
raise HTTPException(status_code=503, detail="Workflow Studio is disabled")
def _runs(request: Request) -> WorkflowRunStore:
store = getattr(request.app.state, "workflow_run_store", None)
if store is None:
raise HTTPException(status_code=503, detail="Workflow run store not available")
return store
def _events(request: Request) -> WorkflowEventStore:
store = getattr(request.app.state, "workflow_event_store", None)
if store is None:
raise HTTPException(status_code=503, detail="Workflow event store not available")
return store
def _definitions(request: Request):
store = getattr(request.app.state, "workflow_store", None)
if store is None:
raise HTTPException(status_code=503, detail="Workflow store not available")
return store
def _nudge(request: Request) -> None:
dispatcher = getattr(request.app.state, "workflow_dispatcher", None)
if dispatcher is not None:
dispatcher.nudge()
async def _is_admin(request: Request) -> bool:
user = await get_optional_user_from_request(request)
return user is not None and getattr(user, "system_role", None) == "admin"
async def _authorized_run(request: Request, run_id: str) -> dict[str, Any]:
run = await _runs(request).get_run(run_id)
if run is None:
raise HTTPException(status_code=404, detail={"code": "WORKFLOW_RUN_NOT_FOUND", "message": "运行不存在"})
user_id = await get_current_user(request)
if run.get("owner_id") != user_id and not await _is_admin(request):
raise HTTPException(status_code=403, detail={"code": "WORKFLOW_FORBIDDEN", "message": "无权访问该运行"})
return run
def _public_run(run: dict[str, Any]) -> dict[str, Any]:
"""Run view for HTTP clients: no lease internals, no resume token."""
return {
"id": run["id"],
"runId": run["id"],
"workflowId": run["workflow_id"],
"versionId": run["workflow_version_id"],
"status": run["status"],
"ownerId": run["owner_id"],
"input": run.get("input") or {},
"output": run.get("output"),
"error": run.get("error"),
"pendingInput": run.get("pending_input"),
"attempt": run.get("attempt"),
"retryOfRunId": run.get("retry_of_run_id"),
"startedAt": run.get("started_at"),
"finishedAt": run.get("finished_at"),
"createdAt": run.get("created_at"),
"updatedAt": run.get("updated_at"),
# The run row's counter holds the last seq handed out by the event log
# (the event store bumps it in the insert transaction); 0 = no events.
"lastSeq": int(run.get("next_event_seq") or 0),
}
# ── start / list / get / cancel / resume ────────────────────────────────
@router.post("/{workflow_id}/runs")
async def start_run(request: Request, workflow_id: str, body: StartRunBody) -> dict[str, Any]:
_require_enabled()
user_id = await get_current_user(request)
if str(body.target or "").strip().lower() == "draft":
# Never silently fall back to the published version when the client
# thinks it is exercising the draft — draft snapshots need the explicit
# test-run API (not built yet).
raise HTTPException(
status_code=422,
detail={
"code": "WORKFLOW_DRAFT_RUN_UNSUPPORTED",
"message": "暂不支持运行草稿,请先发布或指定 versionId",
},
)
definitions = _definitions(request)
definition = await definitions.get_definition(workflow_id, include_draft=False)
if definition is None:
raise HTTPException(status_code=404, detail="工作流不存在")
if definition.get("owner_id") != user_id and not await _is_admin(request):
raise HTTPException(status_code=403, detail={"code": "WORKFLOW_FORBIDDEN", "message": "无权运行该工作流"})
version_id = body.version_id
if not version_id:
versions = await definitions.list_versions(workflow_id)
if not versions:
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_VERSION_NOT_FOUND", "message": "工作流尚未发布任何版本"},
)
version_id = versions[0]["id"]
version = await definitions.get_version(version_id)
if version is None or version.get("workflow_id") != workflow_id:
raise HTTPException(status_code=404, detail={"code": "WORKFLOW_VERSION_NOT_FOUND", "message": "版本不存在"})
graph = WorkflowGraph.model_validate(version.get("graph") or {})
inputs = body.resolved_inputs()
missing = [key for key in (graph.input_schema.get("required") or []) if inputs.get(str(key)) in (None, "")]
if missing:
raise HTTPException(
status_code=400,
detail={
"code": "WORKFLOW_INPUT_INVALID",
"message": f"缺少必填输入:{'、'.join(str(m) for m in missing)}",
"details": {"missing": missing},
},
)
# Full JSON Schema pass so type/enum/nested mistakes fail here with a
# structured 400 instead of surfacing mid-run as a node error.
schema_errors = schema_issues(inputs, graph.input_schema or {})
if schema_errors:
raise HTTPException(
status_code=400,
detail={
"code": "WORKFLOW_INPUT_INVALID",
"message": "输入不符合 schema:" + ";".join(e["message"] for e in schema_errors[:3]),
"details": {"errors": schema_errors},
},
)
runs = _runs(request)
active = [r for r in await runs.list_runs(owner_id=user_id, limit=200) if r["status"] in ("queued", "running")]
if len(active) >= _cfg().max_concurrent_runs_per_user:
raise HTTPException(
status_code=429,
detail={
"code": "WORKFLOW_LIMIT_EXCEEDED",
"message": f"同时运行的工作流已达上限({_cfg().max_concurrent_runs_per_user})",
},
)
# Scope the idempotency key per workflow so two workflows can share a client key.
key = f"{workflow_id}:{body.idempotency_key}" if body.idempotency_key else None
run, created = await runs.create_run(
{
"workflow_id": workflow_id,
"workflow_version_id": version_id,
"owner_id": user_id,
"input": inputs,
"idempotency_key": key,
"context": {"depth": 0},
}
)
if created:
await _events(request).append(
run_id=run["id"],
workflow_id=workflow_id,
version_id=version_id,
event_type="run.created",
payload={"inputs": inputs},
)
audit_workflow("run.start", user_id=user_id, workflowId=workflow_id, runId=run["id"], versionId=version_id)
_nudge(request)
return {**_public_run(run), "created": created}
@router.get("/{workflow_id}/runs")
async def list_workflow_runs(
request: Request,
workflow_id: str,
status: str | None = None,
limit: int = Query(default=50, ge=1, le=200),
offset: int = Query(default=0, ge=0),
) -> dict[str, Any]:
_require_enabled()
user_id = await get_current_user(request)
owner = None if await _is_admin(request) else user_id
rows = await _runs(request).list_runs(workflow_id=workflow_id, owner_id=owner, status=status, limit=limit, offset=offset)
return {"runs": [_public_run(r) for r in rows], "hasMore": len(rows) >= limit}
@router.get("/runs/{run_id}")
async def get_run(request: Request, run_id: str) -> dict[str, Any]:
_require_enabled()
run = await _authorized_run(request, run_id)
node_runs = await _runs(request).list_node_runs(run_id, current_only=True)
return {
**_public_run(run),
"nodeRuns": [
{
"nodeId": r["node_id"],
"nodeType": r["node_type"],
"status": r["status"],
"attempt": r["attempt"],
"iteration": r["iteration"],
"durationMs": r["duration_ms"],
"error": r["error"],
"startedAt": r["started_at"],
"finishedAt": r["finished_at"],
}
for r in node_runs
],
}
@router.get("/runs/{run_id}/artifacts")
async def list_run_artifacts(request: Request, run_id: str) -> dict[str, Any]:
_require_enabled()
await _authorized_run(request, run_id)
rows = await _runs(request).list_artifacts(run_id)
return {
"artifacts": [
{
"artifactId": r["id"],
"nodeId": r["node_id"],
"name": r["name"],
"mimeType": r["mime_type"],
"sizeBytes": r["size_bytes"],
"preview": r["preview"],
}
for r in rows
]
}
# ── artifact content / download ─────────────────────────────────────────
_PREVIEW_MAX_BYTES = 256 * 1024
_TEXT_MIME_PREFIXES = ("text/", "application/json", "application/javascript", "application/x-yaml", "application/xml", "application/csv")
def _is_textual(mime_type: str) -> bool:
return (mime_type or "").lower().startswith(_TEXT_MIME_PREFIXES)
def _read_prefix(path: str, limit: int) -> tuple[bytes, bool]:
"""Read up to ``limit + 1`` bytes; the extra byte detects truncation."""
with open(path, "rb") as handle:
data = handle.read(limit + 1)
return data[:limit], len(data) > limit
def _file_exists(path: str) -> bool:
import os
return bool(path) and os.path.isfile(path)
async def _authorized_artifact(request: Request, run_id: str, artifact_id: str) -> dict[str, Any]:
"""Run-level authorization first, then artifact-must-belong-to-run.
The file path is resolved exclusively from the registered artifact row —
clients address artifacts by id and can never pass a sandbox path in.
"""
await _authorized_run(request, run_id)
artifact = await _runs(request).get_artifact(run_id, artifact_id)
if artifact is None:
raise HTTPException(
status_code=404,
detail={"code": "WORKFLOW_ARTIFACT_NOT_FOUND", "message": "制品不存在"},
)
return artifact
@router.get("/runs/{run_id}/artifacts/{artifact_id}")
async def get_run_artifact_content(request: Request, run_id: str, artifact_id: str) -> dict[str, Any]:
"""Size-bounded text preview for file cards; binaries stay download-only."""
from starlette.concurrency import run_in_threadpool
from deerflow.workflows.events import artifact_kind
_require_enabled()
artifact = await _authorized_artifact(request, run_id, artifact_id)
mime = str(artifact.get("mime_type") or "application/octet-stream")
kind = artifact_kind(mime)
base = {
"artifactId": artifact["id"],
"name": artifact["name"],
"kind": kind,
"mimeType": mime,
"sizeBytes": artifact.get("size_bytes"),
}
path = str(artifact.get("path") or "")
file_ok = bool(path) and await run_in_threadpool(_file_exists, path)
if file_ok:
raw, truncated = (b"", False)
if _is_textual(mime):
raw, truncated = await run_in_threadpool(_read_prefix, path, _PREVIEW_MAX_BYTES)
return {
**base,
"text": raw.decode("utf-8", errors="replace"),
"truncated": truncated,
"source": "file",
}
return {
**base,
"binary": True,
"downloadUrl": f"/api/workflows/runs/{run_id}/artifacts/{artifact_id}/download",
"source": "file",
}
preview = artifact.get("preview")
if preview:
return {**base, "text": str(preview), "truncated": True, "source": "preview"}
raise HTTPException(
status_code=404,
detail={"code": "WORKFLOW_ARTIFACT_CONTENT_UNAVAILABLE", "message": "制品内容不可用(文件已过期)"},
)
@router.get("/runs/{run_id}/artifacts/{artifact_id}/download")
async def download_run_artifact(request: Request, run_id: str, artifact_id: str):
from urllib.parse import quote
from starlette.concurrency import run_in_threadpool
from starlette.responses import FileResponse, Response
_require_enabled()
artifact = await _authorized_artifact(request, run_id, artifact_id)
mime = str(artifact.get("mime_type") or "application/octet-stream")
name = str(artifact.get("name") or artifact_id)
disposition = f"attachment; filename*=UTF-8''{quote(name)}"
path = str(artifact.get("path") or "")
if path and await run_in_threadpool(_file_exists, path):
return FileResponse(path, media_type=mime, headers={"Content-Disposition": disposition})
preview = artifact.get("preview")
if preview:
return Response(
content=str(preview),
media_type=mime if _is_textual(mime) else "text/plain",
headers={"Content-Disposition": disposition},
)
raise HTTPException(
status_code=404,
detail={"code": "WORKFLOW_ARTIFACT_CONTENT_UNAVAILABLE", "message": "制品文件已过期,无法下载"},
)
@router.post("/runs/{run_id}/cancel")
async def cancel_run(request: Request, run_id: str) -> dict[str, Any]:
_require_enabled()
run = await _authorized_run(request, run_id)
if run["status"] in _TERMINAL_STATUSES:
return {**_public_run(run), "cancelled": False}
updated = await _runs(request).request_cancel(run_id)
if updated is None:
raise HTTPException(
status_code=409,
detail={"code": "WORKFLOW_RUN_CONFLICT", "message": "当前状态无法取消"},
)
await _events(request).append(
run_id=run_id,
workflow_id=run["workflow_id"],
version_id=run["workflow_version_id"],
event_type="run.cancel_requested",
payload={},
)
_nudge(request)
audit_workflow("run.cancel", user_id=await get_current_user(request), runId=run_id, workflowId=run["workflow_id"])
return {**_public_run(updated), "cancelled": True}
@router.post("/runs/{run_id}/resume")
async def resume_run(request: Request, run_id: str, body: ResumeRunBody) -> dict[str, Any]:
_require_enabled()
run = await _authorized_run(request, run_id)
if run["status"] != "awaiting_input":
raise HTTPException(
status_code=409,
detail={"code": "WORKFLOW_RUN_NOT_RESUMABLE", "message": "运行当前不在等待人工输入"},
)
pending = run.get("pending_input") or {}
node_id = body.node_id or str(pending.get("nodeId") or "")
if not node_id:
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_HUMAN_INPUT_INVALID", "message": "缺少 nodeId"},
)
runs = _runs(request)
# Single conditional update: token validation + payload write + token
# consumption + status flip all in one statement, so two concurrent resume
# requests with the same token cannot interleave — exactly one succeeds and
# the loser gets 409 without ever touching the run.
resumed = await runs.resume_with_payload(
run_id,
body.resume_token,
{
"nodeId": node_id,
"action": body.action,
"values": body.resolved_values(),
**({"message": body.message} if body.message else {}),
},
context=dict(run.get("context") or {}),
)
if resumed is None:
raise HTTPException(
status_code=409,
detail={"code": "WORKFLOW_RESUME_TOKEN_INVALID", "message": "恢复令牌无效或已被使用"},
)
await _events(request).append(
run_id=run_id,
workflow_id=run["workflow_id"],
version_id=run["workflow_version_id"],
event_type="run.resumed",
payload={"nodeId": node_id, "action": body.action},
node_id=node_id,
)
_nudge(request)
audit_workflow("run.resume", user_id=await get_current_user(request), runId=run_id, nodeId=node_id)
return _public_run(resumed)
@router.post("/runs/{run_id}/retry", status_code=201)
async def retry_run(request: Request, run_id: str) -> dict[str, Any]:
"""Start a new run from a failed one.
Completed node outputs are copied onto the new run so the engine resumes
from the first unfinished node. If there is nothing to replay, the new run
is a full replay of the same version and inputs, still marked
``retry_of_run_id``.
"""
_require_enabled()
run = await _authorized_run(request, run_id)
if run["status"] != "failed":
raise HTTPException(
status_code=409,
detail={"code": "WORKFLOW_RUN_NOT_RETRYABLE", "message": "只有失败的运行可以重试"},
)
user_id = await get_current_user(request)
runs = _runs(request)
active = [r for r in await runs.list_runs(owner_id=user_id, limit=200) if r["status"] in ("queued", "running")]
if len(active) >= _cfg().max_concurrent_runs_per_user:
raise HTTPException(
status_code=429,
detail={
"code": "WORKFLOW_LIMIT_EXCEEDED",
"message": f"同时运行的工作流已达上限({_cfg().max_concurrent_runs_per_user})",
},
)
context = dict(run.get("context") or {})
context.pop("resume_payload", None)
context["retry_of_run_id"] = run_id
new_run, _created = await runs.create_run(
{
"workflow_id": run["workflow_id"],
"workflow_version_id": run["workflow_version_id"],
"owner_id": user_id,
"input": run.get("input") or {},
"retry_of_run_id": run_id,
"context": context,
}
)
for row in await runs.list_node_runs(run_id, current_only=True):
if row.get("status") != "completed":
continue
await runs.record_node_run(
{
"run_id": new_run["id"],
"node_id": row["node_id"],
"node_type": row.get("node_type") or "unknown",
"status": "completed",
"attempt": 1,
"iteration": int(row.get("iteration") or 0),
"output": row.get("output"),
"duration_ms": row.get("duration_ms"),
"is_current": True,
}
)
await _events(request).append(
run_id=new_run["id"],
workflow_id=new_run["workflow_id"],
version_id=new_run["workflow_version_id"],
event_type="run.created",
payload={"retryOfRunId": run_id, "inputs": new_run.get("input") or {}},
)
_nudge(request)
audit_workflow("run.retry", user_id=user_id, runId=new_run["id"], retryOfRunId=run_id)
return {**_public_run(new_run), "created": True}
# ── events / SSE ────────────────────────────────────────────────────────
@router.get("/runs/{run_id}/events")
async def list_run_events(
request: Request,
run_id: str,
after: int = Query(default=0, ge=0),
after_seq: int | None = Query(default=None, alias="after_seq", ge=0),
limit: int = Query(default=_REPLAY_PAGE, ge=1, le=1000),
) -> dict[str, Any]:
_require_enabled()
await _authorized_run(request, run_id)
cursor = after_seq if after_seq is not None else after
rows = await _events(request).list_after(run_id, after_seq=cursor, limit=limit)
return {"events": [envelope_from_row(r) for r in rows], "lastSeq": rows[-1]["seq"] if rows else cursor}
def _frame(payload: dict[str, Any]) -> str:
body = json.dumps(payload, ensure_ascii=False, separators=(",", ":"), default=str)
return f"id: {payload.get('seq', 0)}\nevent: {payload.get('event', 'message')}\ndata: {body}\n\n"
def _replay_cursor(request: Request, after: int) -> int:
"""``Last-Event-ID`` wins over ``?after=``; invalid headers fall back."""
raw = request.headers.get("last-event-id")
if raw:
try:
return max(0, int(str(raw).strip()))
except (TypeError, ValueError):
pass
return after
@router.get("/runs/{run_id}/stream")
async def stream_run(
request: Request,
run_id: str,
after: int = Query(default=0, ge=0),
after_seq: int | None = Query(default=None, alias="after_seq", ge=0),
) -> StreamingResponse:
"""Replay from ``after`` then tail live.
The database is authoritative for ordering: live frames whose ``seq`` we have
not yet replayed are held back and picked up by the next DB poll, so a
reconnecting client never sees a gap or an out-of-order ``seq``.
``Last-Event-ID`` takes priority over ``after``.
"""
_require_enabled()
run = await _authorized_run(request, run_id)
events = _events(request)
runs = _runs(request)
hub = getattr(request.app.state, "workflow_live_hub", None)
cursor_start = _replay_cursor(request, after_seq if after_seq is not None else after)
async def generator():
cursor = cursor_start
live_queue = hub.subscribe(run_id) if hub is not None else None
loop = asyncio.get_running_loop()
deadline = loop.time() + _STREAM_DEADLINE_SECONDS
next_poll = 0.0
last_beat = loop.time()
try:
while loop.time() < deadline:
if await request.is_disconnected():
return
if loop.time() >= next_poll:
while True:
rows = await events.list_after(run_id, after_seq=cursor, limit=_REPLAY_PAGE)
if not rows:
break
for row in rows:
yield _frame(envelope_from_row(row))
cursor = max(cursor, int(row["seq"]))
last_beat = loop.time()
if row["event_type"] in _TERMINAL_EVENTS:
return
if len(rows) < _REPLAY_PAGE:
break
current = await runs.get_run(run_id)
if current is None:
return
if current["status"] in _TERMINAL_STATUSES:
# Terminal state with no terminal event (e.g. a crash
# before the event landed): synthesise a closing frame
# so the client is never left hanging.
yield _frame(
{
"schemaVersion": "1.0",
"runId": run_id,
"workflowId": current["workflow_id"],
"versionId": current["workflow_version_id"],
"seq": cursor,
"event": f"run.{current['status']}",
"timestamp": datetime.now(UTC).isoformat(),
"data": {
"status": current["status"],
"output": current.get("output"),
"error": current.get("error"),
"synthesised": True,
},
}
)
return
next_poll = loop.time() + _DB_POLL_SECONDS
if live_queue is not None:
try:
event = await asyncio.wait_for(live_queue.get(), timeout=_LIVE_WAIT_SECONDS)
except TimeoutError:
event = None
if event is not None and int(event.get("seq") or 0) > cursor:
yield _frame(event)
cursor = int(event["seq"])
last_beat = loop.time()
if event.get("event") in _TERMINAL_EVENTS:
return
else:
await asyncio.sleep(_LIVE_WAIT_SECONDS)
if loop.time() - last_beat >= _HEARTBEAT_SECONDS:
yield ": heartbeat\n\n"
last_beat = loop.time()
finally:
if live_queue is not None and hub is not None:
hub.unsubscribe(run_id, live_queue)
return StreamingResponse(
generator(),
media_type="text/event-stream",
headers={
"Cache-Control": "no-cache, no-transform",
"Connection": "keep-alive",
"X-Accel-Buffering": "no",
"X-Workflow-Run-Status": run["status"],
},
)
@@ -0,0 +1,351 @@
"""Studio facade: camelCase DTOs for the standalone Coze canvas page.
Four endpoints in front of the standard workflow store:
GET /api/workflows/{id}/studio-document
PUT /api/workflows/{id}/studio-draft
POST /api/workflows/{id}/studio-validate
POST /api/workflows/{id}/studio-publish
Design contract (docs/WORKFLOW_STUDIO_COZE_FRONTEND_ADAPTATION_ZH.md §3-§4):
- One workflow, two documents. ``canvasSchemaJson`` is an opaque Coze canvas
saved for editing; ``executionGraph`` is the WorkflowGraph v1.0 the runtime
executes. Both land in the SAME CAS update, so they can never disagree on
revision.
- The facade only maps DTO naming and delegates to the standard store /
validator / publish service — it never forks versioning logic.
- Publishing a workflow whose draft has no valid execution graph is a 400, not
a silent empty-graph publish.
"""
from __future__ import annotations
import json
from hashlib import sha256
from typing import Any
from fastapi import APIRouter, HTTPException, Request
from pydantic import BaseModel, Field
from app.gateway.deps import get_current_user
from app.gateway.workflow_audit import audit_workflow
from app.gateway.workflow_resource_checks import build_resource_catalog, make_resource_checker
from deerflow.config.app_config import get_app_config
from deerflow.persistence.workflows import (
WorkflowDraftConflictError,
WorkflowNotFoundError,
WorkflowStore,
)
from deerflow.workflows.schemas import WorkflowGraph
from deerflow.workflows.validator import validate_workflow_graph
router = APIRouter(prefix="/api/workflows", tags=["workflow-studio"])
# Canvas document guards: it is stored and replayed as an opaque document, so
# the only checks are size / JSON shape / depth / obvious credential keys.
_CANVAS_MAX_CHARS = 2_000_000
_CANVAS_MAX_DEPTH = 64
_CANVAS_SECRET_KEYS = frozenset(
{
"authorization",
"proxy-authorization",
"cookie",
"x-api-key",
"apikey",
"api_key",
"secret",
"client_secret",
"password",
"dsn",
"access_token",
"refresh_token",
"resumetoken",
"resume_token",
}
)
class StudioDraftBody(BaseModel):
expected_revision: int = Field(alias="expectedRevision", ge=0)
# Canvas may arrive as a JSON string or an embedded object; both are
# canonicalised to compact JSON text before storage.
canvas_schema_json: Any = Field(default=None, alias="canvasSchemaJson")
execution_graph: dict[str, Any] = Field(alias="executionGraph")
model_config = {"populate_by_name": True}
class StudioValidateBody(BaseModel):
execution_graph: dict[str, Any] | None = Field(default=None, alias="executionGraph")
model_config = {"populate_by_name": True}
class StudioPublishBody(BaseModel):
expected_revision: int | None = Field(default=None, alias="expectedRevision", ge=0)
change_note: str = Field(default="", alias="changeNote", max_length=2000)
model_config = {"populate_by_name": True}
def _require_enabled() -> None:
if not get_app_config().workflows.enabled:
raise HTTPException(status_code=503, detail="Workflow Studio is disabled")
def _get_store(request: Request) -> WorkflowStore:
store = getattr(request.app.state, "workflow_store", None)
if store is None:
raise HTTPException(status_code=503, detail="Workflow store not available")
return store
async def _load_owned(request: Request, workflow_id: str) -> dict[str, Any]:
"""Owner or admin only — the studio edits the draft, so read == write."""
from app.gateway.routers.workflows import _load_owned as _standard_load_owned
return await _standard_load_owned(request, workflow_id, write=True)
def _limits() -> dict[str, int]:
cfg = get_app_config().workflows
return {
"system_max_steps": cfg.max_steps,
"system_max_loop_iterations": cfg.max_loop_iterations,
"system_max_parallelism": cfg.max_parallelism,
}
def _parse_canvas(raw: Any) -> str:
"""Validate + canonicalise the canvas document into compact JSON text."""
if raw is None or raw == "":
return "{}"
if isinstance(raw, str):
text = raw
try:
document = json.loads(text)
except json.JSONDecodeError as exc:
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_CANVAS_INVALID", "message": "画布 JSON 无法解析"},
) from exc
elif isinstance(raw, dict):
document = raw
else:
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_CANVAS_INVALID", "message": "画布必须是 JSON 对象或 JSON 字符串"},
)
text = json.dumps(document, ensure_ascii=False, separators=(",", ":"))
if len(text) > _CANVAS_MAX_CHARS:
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_CANVAS_INVALID", "message": f"画布文档超过 {_CANVAS_MAX_CHARS} 字符上限"},
)
offending = _find_secret_key(document, 0)
if offending:
raise HTTPException(
status_code=400,
detail={
"code": "WORKFLOW_CANVAS_INVALID",
"message": f"画布中出现凭据类字段 {offending},请改用凭据引用",
"field": offending,
},
)
return text
def _find_secret_key(node: Any, depth: int) -> str | None:
if depth > _CANVAS_MAX_DEPTH:
return "<max-depth-exceeded>"
if isinstance(node, dict):
for key, value in node.items():
name = str(key).strip().lower()
if name in _CANVAS_SECRET_KEYS and value not in (None, "", {}, []):
return str(key)
found = _find_secret_key(value, depth + 1)
if found:
return found
elif isinstance(node, list):
for item in node:
found = _find_secret_key(item, depth + 1)
if found:
return found
return None
def _studio_issues(issues: list[Any]) -> list[dict[str, Any]]:
out: list[dict[str, Any]] = []
for issue in issues:
body = issue.model_dump(by_alias=True)
details = body.get("details") or {}
out.append(
{
"code": body.get("code"),
"nodeId": body.get("nodeId"),
"field": details.get("field") if isinstance(details, dict) else None,
"message": body.get("message"),
}
)
return out
async def _validate_with_resources(request: Request, workflow_id: str, raw_graph: dict[str, Any], user_id: str) -> list[Any]:
catalog = await build_resource_catalog(request, user_id=user_id)
checker = make_resource_checker(catalog, config=get_app_config().workflows, current_workflow_id=workflow_id)
return validate_workflow_graph(raw_graph, resource_checker=checker, **_limits())
@router.get("/{workflow_id}/studio-document")
async def get_studio_document(request: Request, workflow_id: str) -> dict[str, Any]:
_require_enabled()
definition = await _load_owned(request, workflow_id)
store = _get_store(request)
graph = definition.get("draft_graph") or {}
versions = await store.list_versions(workflow_id)
return {
"workflowId": definition["id"],
"name": definition.get("name"),
"description": definition.get("description") or "",
"status": definition.get("status"),
"draftRevision": int(definition.get("draft_revision") or 0),
"publishedVersionId": versions[0]["id"] if versions else None,
# Canvas stays an opaque JSON document (string); never null.
"canvasSchemaJson": definition.get("draft_canvas_schema") or "{}",
"executionGraph": graph,
"inputSchema": graph.get("inputSchema") or graph.get("input_schema") or {"type": "object", "properties": {}},
"outputSchema": graph.get("outputSchema") or graph.get("output_schema") or {"type": "object", "properties": {}},
"updatedAt": definition.get("updated_at"),
}
@router.put("/{workflow_id}/studio-draft")
async def put_studio_draft(request: Request, workflow_id: str, body: StudioDraftBody) -> dict[str, Any]:
_require_enabled()
await _load_owned(request, workflow_id)
store = _get_store(request)
user_id = await get_current_user(request)
try:
WorkflowGraph.model_validate(body.execution_graph)
except Exception as exc: # noqa: BLE001 - surface pydantic as 400
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_SCHEMA_INVALID", "message": f"执行图不符合 WorkflowGraph v1.0: {exc}"},
) from exc
canvas_text = _parse_canvas(body.canvas_schema_json)
try:
saved = await store.save_studio_draft(
workflow_id,
expected_revision=body.expected_revision,
graph=body.execution_graph,
canvas_schema=canvas_text,
updated_by=user_id,
)
except WorkflowDraftConflictError as exc:
raise HTTPException(
status_code=409,
detail={
"code": "WORKFLOW_DRAFT_CONFLICT",
"message": "草稿版本冲突,请刷新后重试或另存副本",
"currentRevision": exc.current_revision,
},
) from exc
except WorkflowNotFoundError as exc:
raise HTTPException(status_code=404, detail="工作流不存在") from exc
audit_workflow("workflow.studio_draft", user_id=user_id, workflowId=workflow_id, revision=saved.get("draft_revision"))
return {"revision": int(saved.get("draft_revision") or 0), "updatedAt": saved.get("updated_at")}
@router.post("/{workflow_id}/studio-validate")
async def studio_validate(request: Request, workflow_id: str, body: StudioValidateBody | None = None) -> dict[str, Any]:
_require_enabled()
definition = await _load_owned(request, workflow_id)
user_id = await get_current_user(request)
graph = (body.execution_graph if body and body.execution_graph is not None else definition.get("draft_graph")) or {}
try:
issues = await _validate_with_resources(request, workflow_id, graph, user_id)
except Exception as exc: # noqa: BLE001 - unparsable graph is a validation result, not a 500
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_SCHEMA_INVALID", "message": f"图结构无效: {exc}"},
) from exc
valid = not issues
graph_hash = None
if valid:
try:
graph_hash = WorkflowGraph.model_validate(graph).graph_hash()
except Exception: # noqa: BLE001
valid = False
return {"valid": valid, "issues": _studio_issues(issues), "graphHash": graph_hash}
@router.post("/{workflow_id}/studio-publish")
async def studio_publish(request: Request, workflow_id: str, body: StudioPublishBody | None = None) -> dict[str, Any]:
_require_enabled()
definition = await _load_owned(request, workflow_id)
store = _get_store(request)
user_id = await get_current_user(request)
body = body or StudioPublishBody()
graph_raw = definition.get("draft_graph") or {}
if not graph_raw or not (graph_raw.get("nodes") or []):
raise HTTPException(
status_code=400,
detail={
"code": "WORKFLOW_SCHEMA_INVALID",
"message": "草稿没有可发布的执行图(只有画布文档不能发布)",
},
)
try:
issues = await _validate_with_resources(request, workflow_id, graph_raw, user_id)
except Exception as exc: # noqa: BLE001
raise HTTPException(
status_code=400,
detail={"code": "WORKFLOW_SCHEMA_INVALID", "message": f"图结构无效: {exc}"},
) from exc
if issues:
raise HTTPException(
status_code=400,
detail={
"code": "WORKFLOW_SCHEMA_INVALID",
"message": "发布校验未通过",
"issues": _studio_issues(issues),
},
)
if body.expected_revision is not None and body.expected_revision != definition.get("draft_revision"):
raise HTTPException(
status_code=409,
detail={
"code": "WORKFLOW_DRAFT_CONFLICT",
"message": "发布前草稿版本已变化",
"currentRevision": definition.get("draft_revision"),
},
)
graph = WorkflowGraph.model_validate(graph_raw)
canvas_text = str(definition.get("draft_canvas_schema") or "{}")
canvas_hash = sha256(canvas_text.encode("utf-8")).hexdigest()
version = await store.publish_version(
workflow_id,
graph=graph.model_dump(by_alias=True),
graph_hash=graph.graph_hash(),
published_by=user_id,
change_note=body.change_note,
canvas_schema_hash=canvas_hash,
)
audit_workflow(
"workflow.studio_publish",
user_id=user_id,
workflowId=workflow_id,
versionId=version.get("id"),
graphHash=graph.graph_hash(),
)
return {
"versionId": version.get("id"),
"versionNumber": version.get("version_number"),
"publishedAt": version.get("published_at"),
}
@@ -0,0 +1,313 @@
"""Workflow definition / draft / publish API (phase 1 — no execution yet)."""
from __future__ import annotations
from hashlib import sha256
from typing import Any
from fastapi import APIRouter, HTTPException, Query, Request
from pydantic import BaseModel, Field
from app.gateway.deps import get_current_user, get_optional_user_from_request
from app.gateway.workflow_audit import audit_workflow
from app.gateway.workflow_resource_checks import build_resource_catalog, make_resource_checker
from deerflow.config.app_config import get_app_config
from deerflow.persistence.workflows import (
WorkflowDraftConflictError,
WorkflowNotFoundError,
WorkflowStore,
)
from deerflow.workflows.schemas import WorkflowGraph
from deerflow.workflows.validator import validate_workflow_graph
router = APIRouter(prefix="/api/workflows", tags=["workflows"])
class WorkflowCreateRequest(BaseModel):
name: str = Field(default="未命名工作流", min_length=1, max_length=255)
description: str = ""
graph: dict[str, Any] | None = None
class WorkflowPatchRequest(BaseModel):
name: str | None = Field(default=None, min_length=1, max_length=255)
description: str | None = None
class DraftPutRequest(BaseModel):
expected_revision: int = Field(alias="expectedRevision", ge=0)
graph: dict[str, Any]
model_config = {"populate_by_name": True}
class PublishRequest(BaseModel):
change_note: str = Field(default="", alias="changeNote")
expected_revision: int | None = Field(default=None, alias="expectedRevision")
model_config = {"populate_by_name": True}
class ValidateRequest(BaseModel):
graph: dict[str, Any] | None = None
def _get_store(request: Request) -> WorkflowStore:
store = getattr(request.app.state, "workflow_store", None)
if store is None:
raise HTTPException(status_code=503, detail="Workflow store not available")
return store
def _require_enabled() -> None:
cfg = get_app_config().workflows
if not cfg.enabled:
raise HTTPException(status_code=503, detail="Workflow Studio is disabled")
async def _current_user_id(request: Request) -> str:
return await get_current_user(request)
def _can_access(definition: dict[str, Any], user_id: str, *, write: bool = False) -> bool:
# Phase 1: owner-only. Shared/org ACLs land later.
owner = definition.get("owner_id")
if owner == user_id:
return True
# Auth disabled environments often use "default" / anonymous — still owner-scoped.
if write:
return False
return False
async def _load_owned(request: Request, workflow_id: str, *, write: bool = False) -> dict[str, Any]:
store = _get_store(request)
user_id = await _current_user_id(request)
definition = await store.get_definition(workflow_id, include_draft=True)
if definition is None:
raise HTTPException(status_code=404, detail="工作流不存在")
if not _can_access(definition, user_id, write=write):
# Soft admin bypass for list/read when system_role=admin
user = await get_optional_user_from_request(request)
if user is not None and getattr(user, "system_role", None) == "admin" and not write:
return definition
if user is not None and getattr(user, "system_role", None) == "admin" and write:
return definition
raise HTTPException(status_code=403, detail="无权访问该工作流")
return definition
def _limits() -> dict[str, int]:
cfg = get_app_config().workflows
return {
"system_max_steps": cfg.max_steps,
"system_max_loop_iterations": cfg.max_loop_iterations,
"system_max_parallelism": cfg.max_parallelism,
}
@router.get("")
async def list_workflows(
request: Request,
include_archived: bool = Query(False, alias="includeArchived"),
status: str | None = None,
) -> dict[str, Any]:
_require_enabled()
store = _get_store(request)
user_id = await _current_user_id(request)
user = await get_optional_user_from_request(request)
is_admin = user is not None and getattr(user, "system_role", None) == "admin"
rows = await store.list_definitions(
owner_id=None if is_admin else user_id,
status=status,
include_archived=include_archived,
)
if is_admin:
# Still hide other users' drafts from non-explicit admin listing? Phase 1: admin sees all.
pass
else:
rows = [r for r in rows if r.get("owner_id") == user_id]
return {"workflows": rows}
@router.post("")
async def create_workflow(request: Request, body: WorkflowCreateRequest) -> dict[str, Any]:
_require_enabled()
store = _get_store(request)
user_id = await _current_user_id(request)
created = await store.create_definition(
{
"name": body.name,
"description": body.description,
"owner_id": user_id,
"draft_graph": body.graph,
}
)
audit_workflow("workflow.create", user_id=user_id, workflowId=created["id"])
return created
@router.get("/{workflow_id}")
async def get_workflow(request: Request, workflow_id: str) -> dict[str, Any]:
_require_enabled()
return await _load_owned(request, workflow_id, write=False)
@router.patch("/{workflow_id}")
async def patch_workflow(request: Request, workflow_id: str, body: WorkflowPatchRequest) -> dict[str, Any]:
_require_enabled()
await _load_owned(request, workflow_id, write=True)
store = _get_store(request)
updated = await store.update_definition(
workflow_id,
body.model_dump(exclude_unset=True),
)
if updated is None:
raise HTTPException(status_code=404, detail="工作流不存在")
return updated
@router.delete("/{workflow_id}")
async def archive_workflow(request: Request, workflow_id: str) -> dict[str, Any]:
_require_enabled()
await _load_owned(request, workflow_id, write=True)
store = _get_store(request)
archived = await store.archive_definition(workflow_id)
if archived is None:
raise HTTPException(status_code=404, detail="工作流不存在")
audit_workflow("workflow.archive", user_id=await _current_user_id(request), workflowId=workflow_id)
return archived
@router.post("/{workflow_id}/copy")
async def copy_workflow(request: Request, workflow_id: str) -> dict[str, Any]:
_require_enabled()
definition = await _load_owned(request, workflow_id, write=False)
store = _get_store(request)
user_id = await _current_user_id(request)
created = await store.create_definition(
{
"name": f"{definition.get('name') or '未命名工作流'} 副本",
"description": definition.get("description") or "",
"owner_id": user_id,
"draft_graph": definition.get("draft_graph"),
}
)
audit_workflow("workflow.copy", user_id=user_id, workflowId=created["id"], sourceWorkflowId=workflow_id)
return created
@router.put("/{workflow_id}/draft")
async def put_draft(request: Request, workflow_id: str, body: DraftPutRequest) -> dict[str, Any]:
_require_enabled()
await _load_owned(request, workflow_id, write=True)
store = _get_store(request)
user_id = await _current_user_id(request)
try:
# Light structural parse so obviously broken drafts fail early; full publish
# checks run on /validate and /publish.
WorkflowGraph.model_validate(body.graph)
except Exception as exc: # noqa: BLE001 — surface pydantic as 400
raise HTTPException(status_code=400, detail=f"图结构无效: {exc}") from exc
try:
return await store.save_draft(
workflow_id,
expected_revision=body.expected_revision,
graph=body.graph,
updated_by=user_id,
)
except WorkflowDraftConflictError as exc:
raise HTTPException(
status_code=409,
detail={
"code": "WORKFLOW_DRAFT_CONFLICT",
"message": "草稿版本冲突,请刷新后重试或另存副本",
"currentRevision": exc.current_revision,
},
) from exc
except WorkflowNotFoundError as exc:
raise HTTPException(status_code=404, detail="工作流不存在") from exc
@router.post("/{workflow_id}/validate")
async def validate_workflow(request: Request, workflow_id: str, body: ValidateRequest | None = None) -> dict[str, Any]:
_require_enabled()
definition = await _load_owned(request, workflow_id, write=False)
graph = (body.graph if body and body.graph is not None else definition.get("draft_graph")) or {}
issues = validate_workflow_graph(graph, **_limits())
return {
"ok": len(issues) == 0,
"issues": [i.model_dump(by_alias=True) for i in issues],
"graphHash": WorkflowGraph.model_validate(graph).graph_hash() if not issues else None,
}
@router.post("/{workflow_id}/publish")
async def publish_workflow(request: Request, workflow_id: str, body: PublishRequest | None = None) -> dict[str, Any]:
_require_enabled()
definition = await _load_owned(request, workflow_id, write=True)
body = body or PublishRequest()
if body.expected_revision is not None and body.expected_revision != definition.get("draft_revision"):
raise HTTPException(
status_code=409,
detail={
"code": "WORKFLOW_DRAFT_CONFLICT",
"message": "发布前草稿版本已变化",
"currentRevision": definition.get("draft_revision"),
},
)
graph_raw = definition.get("draft_graph") or {}
# Same resource/permission checks as the studio facade (§5.3): the standard
# publish path must not accept graphs referencing invisible agents or
# forbidden resources.
catalog = await build_resource_catalog(request, user_id=await _current_user_id(request))
checker = make_resource_checker(catalog, config=get_app_config().workflows, current_workflow_id=workflow_id)
issues = validate_workflow_graph(graph_raw, resource_checker=checker, **_limits())
if issues:
raise HTTPException(
status_code=400,
detail={
"code": "WORKFLOW_SCHEMA_INVALID",
"message": "发布校验未通过",
"issues": [i.model_dump(by_alias=True) for i in issues],
},
)
graph = WorkflowGraph.model_validate(graph_raw)
store = _get_store(request)
user_id = await _current_user_id(request)
canvas_text = str(definition.get("draft_canvas_schema") or "{}")
version = await store.publish_version(
workflow_id,
graph=graph.model_dump(by_alias=True),
graph_hash=graph.graph_hash(),
published_by=user_id,
change_note=body.change_note,
canvas_schema_hash=sha256(canvas_text.encode("utf-8")).hexdigest(),
)
audit_workflow(
"workflow.publish",
user_id=user_id,
workflowId=workflow_id,
versionId=version.get("id"),
graphHash=graph.graph_hash(),
)
return version
@router.get("/{workflow_id}/versions")
async def list_versions(request: Request, workflow_id: str) -> dict[str, Any]:
_require_enabled()
await _load_owned(request, workflow_id, write=False)
store = _get_store(request)
return {"versions": await store.list_versions(workflow_id)}
@router.get("/{workflow_id}/versions/{version_id}")
async def get_version(request: Request, workflow_id: str, version_id: str) -> dict[str, Any]:
_require_enabled()
await _load_owned(request, workflow_id, write=False)
store = _get_store(request)
version = await store.get_version(version_id)
if version is None or version.get("workflow_id") != workflow_id:
raise HTTPException(status_code=404, detail="版本不存在")
return version
@@ -0,0 +1,368 @@
"""Minimal Coze Studio workflow_api compatibility layer (phase 1).
Internal services always use DeerFlow draft DTOs. This module only translates
request/response shapes for the standalone canvas page: ``/canvas`` replies
with the Coze playground envelope and ``/save`` persists the Coze canvas into
``save_studio_draft`` without letting it anywhere near ``WorkflowGraph``
validation (the canvas is an opaque editing document; the executable graph is
compiled client-side and saved via the studio facade).
"""
from __future__ import annotations
import json
from typing import Any
from fastapi import APIRouter, HTTPException, Request
from pydantic import BaseModel, Field
from app.gateway.deps import get_current_user, get_optional_user_from_request
from app.gateway.routers.workflow_studio import _parse_canvas
from deerflow.config.app_config import get_app_config
from deerflow.persistence.workflows import (
WorkflowDraftConflictError,
WorkflowNotFoundError,
WorkflowStore,
)
router = APIRouter(prefix="/api/workflow_api", tags=["workflow-coze-compat"])
# Playground 启动还会打这些 Coze 壳接口;缺了它们画布和节点资源都不会挂载。
chrome_router = APIRouter(tags=["workflow-coze-compat"])
_DEFAULT_SPACE: dict[str, Any] = {
"id": "1",
"space_id": 1,
"name": "默认空间",
"description": "",
# SpaceType.Personal = 1;Playground 找不到个人空间会去调 space/save。
"space_type": 1,
"space_mode": 0,
"icon_uri": "",
"icon_url": "",
"owner_id": "1",
"owner_user_id": "1",
"role_type": 1,
"has_permission": True,
}
# Coze playground node_template_list payload. The standalone canvas maps
# DeerFlow node kinds onto these StandardNodeType ids (see the frontend's
# node-catalog.ts); entries keep the Coze field names (node_type / icon_url /
# color) so the playground's template list renders without adaptation.
_COZE_NODE_TEMPLATES: list[dict[str, Any]] = [
{"node_type": "1", "name": "开始", "icon_url": "", "color": "#5C62FF", "desc": "工作流入口,定义输入参数"},
{"node_type": "2", "name": "结束", "icon_url": "", "color": "#5C62FF", "desc": "工作流出口,汇总输出"},
{"node_type": "3", "name": "大模型", "icon_url": "", "color": "#5C62FF", "desc": "调用智能体处理任务", "support_batch": 1},
{"node_type": "5", "name": "代码", "icon_url": "", "color": "#00B2B2", "desc": "在沙箱中执行代码", "support_batch": 0},
{"node_type": "8", "name": "选择器", "icon_url": "", "color": "#00B2B2", "desc": "按条件分支执行", "support_batch": 0},
{"node_type": "9", "name": "工作流", "icon_url": "", "color": "#00B83E", "desc": "调用已发布子工作流", "support_batch": 1},
{"node_type": "13", "name": "输出", "icon_url": "", "color": "#5C62FF", "desc": "定义输出字段", "support_batch": 0},
{"node_type": "15", "name": "文本处理", "icon_url": "", "color": "#3071F2", "desc": "模板/文本转换", "support_batch": 0},
{"node_type": "18", "name": "问答", "icon_url": "", "color": "#3071F2", "desc": "人工介入确认", "support_batch": 0},
{"node_type": "21", "name": "循环", "icon_url": "", "color": "#00B2B2", "desc": "循环执行子图", "support_batch": 0},
{"node_type": "32", "name": "变量聚合", "icon_url": "", "color": "#00B2B2", "desc": "合并多分支变量", "support_batch": 0},
{"node_type": "43", "name": "查询数据", "icon_url": "", "color": "#F2B600", "desc": "SQL 只读查询", "support_batch": 0},
{"node_type": "45", "name": "HTTP 请求", "icon_url": "", "color": "#3071F2", "desc": "调用外部接口", "support_batch": 0},
]
_COZE_NODE_CATEGORIES: list[dict[str, Any]] = [
{"name": "", "node_type_list": ["3", "9"]},
{"name": "业务逻辑", "node_type_list": ["5", "8", "21", "32"]},
{"name": "输入&输出", "node_type_list": ["1", "2", "13"]},
{"name": "组件", "node_type_list": ["15", "18", "45"]},
{"name": "数据库", "node_type_list": ["43"]},
]
# Mirrors the standalone page's built-in empty canvas (start → end), used when
# a workflow has never been opened in the Coze editor.
_DEFAULT_CANVAS_SCHEMA = json.dumps(
{
"nodes": [
{
"id": "100001",
"type": "1",
"meta": {"position": {"x": 0, "y": 0}},
"data": {"outputs": [{"type": "string", "name": "", "required": True}]},
},
{
"id": "900001",
"type": "2",
"meta": {"position": {"x": 1000, "y": 0}},
},
],
"edges": [{"sourceNodeID": "100001", "targetNodeID": "900001"}],
},
ensure_ascii=False,
)
class CozeCreateRequest(BaseModel):
name: str = Field(default="未命名工作流")
description: str = ""
graph: dict[str, Any] | None = None
class CozeCanvasRequest(BaseModel):
workflow_id: str | None = Field(default=None, alias="workflowId")
workflow_id_snake: str | None = Field(default=None, alias="workflow_id")
model_config = {"populate_by_name": True}
def resolved_id(self) -> str | None:
return self.workflow_id or self.workflow_id_snake
class CozeSaveRequest(BaseModel):
workflow_id: str | None = Field(default=None, alias="workflowId")
workflow_id_snake: str | None = Field(default=None, alias="workflow_id")
expected_revision: int | None = Field(default=None, alias="expectedRevision")
expected_revision_snake: int | None = Field(default=None, alias="expected_revision")
# Coze posts the canvas as a JSON string under ``schema``.
schema_: str | dict[str, Any] | None = Field(default=None, alias="schema")
graph: str | dict[str, Any] | None = None
data: dict[str, Any] | None = None
model_config = {"populate_by_name": True}
def resolved_id(self) -> str | None:
return self.workflow_id or self.workflow_id_snake
def resolved_revision(self) -> int | None:
if self.expected_revision is not None:
return self.expected_revision
return self.expected_revision_snake
def resolved_canvas(self) -> str | dict[str, Any] | None:
if self.schema_ is not None:
return self.schema_
if isinstance(self.graph, (str, dict)):
return self.graph
if self.data is not None:
for key in ("schema", "graph"):
value = self.data.get(key)
if isinstance(value, (str, dict)):
return value
return self.data
return None
def _require_enabled() -> None:
if not get_app_config().workflows.enabled:
raise HTTPException(status_code=503, detail="Workflow Studio is disabled")
def _get_store(request: Request) -> WorkflowStore:
store = getattr(request.app.state, "workflow_store", None)
if store is None:
raise HTTPException(status_code=503, detail="Workflow store not available")
return store
def _canvas_schema_text(definition: dict[str, Any]) -> str:
raw = definition.get("draft_canvas_schema")
if isinstance(raw, str) and raw.strip() not in ("", "{}", "null"):
return raw
if isinstance(raw, dict) and raw:
return json.dumps(raw, ensure_ascii=False)
return _DEFAULT_CANVAS_SCHEMA
def _to_coze_canvas(definition: dict[str, Any], *, is_published: bool = False) -> dict[str, Any]:
owner = str(definition.get("owner_id") or "1")
return {
"code": 0,
"msg": "success",
"data": {
"workflow": {
"workflow_id": definition["id"],
"space_id": "1",
"name": definition.get("name"),
"desc": definition.get("description") or "",
"schema_json": _canvas_schema_text(definition),
"status": 1,
"collaborator_mode": "Open",
"creator": {"user_id": owner, "nickname": owner},
"is_published": is_published,
},
"vcs_data": {"can_edit": True},
"db_data": {"status": 1},
"operation_info": {},
"is_bind_agent": False,
"workflow_version": "1",
},
}
async def _load_owned_definition(request: Request, store: WorkflowStore, workflow_id: str, user_id: str) -> dict[str, Any]:
definition = await store.get_definition(workflow_id, include_draft=True)
if definition is None:
raise HTTPException(status_code=404, detail="工作流不存在")
if definition.get("owner_id") == user_id:
return definition
user = await get_optional_user_from_request(request)
if user is not None and getattr(user, "system_role", None) == "admin":
return definition
raise HTTPException(status_code=403, detail="无权访问该工作流")
def _coze_ok(data: dict[str, Any]) -> dict[str, Any]:
return {"code": 0, "msg": "success", "data": data}
def _account_payload(user: Any, user_id: str) -> dict[str, Any]:
email = str(getattr(user, "email", "") or "")
nickname = email.split("@", 1)[0] if email else user_id
return {
"user_id_str": user_id,
"user_id": user_id,
"nickname": nickname,
"name": nickname,
"email": email,
"avatar_url": "",
"login_status": "logined",
}
async def _require_studio_user(request: Request) -> tuple[str, Any]:
_require_enabled()
user_id = await get_current_user(request)
if not user_id:
raise HTTPException(status_code=401, detail="未登录")
user = await get_optional_user_from_request(request)
return user_id, user
def _space_list_payload() -> dict[str, Any]:
return {
"has_personal_space": True,
"bot_space_list": [_DEFAULT_SPACE],
"team_space_num": 0,
"max_team_space_num": 10,
"recently_used_space_list": [],
}
@chrome_router.api_route("/api/passport/account/info/v2/", methods=["GET", "POST"])
async def coze_account_info(request: Request) -> dict[str, Any]:
user_id, user = await _require_studio_user(request)
return _coze_ok(_account_payload(user, user_id))
@chrome_router.api_route("/api/space/list", methods=["GET", "POST"])
async def coze_space_list(request: Request) -> dict[str, Any]:
await _require_studio_user(request)
payload = _space_list_payload()
# developer_api.SpaceList 把列表放在顶层;playground v2 读 data。
return {"code": 0, "msg": "success", "data": payload, **payload}
@chrome_router.api_route(
"/api/playground_api/space/list",
methods=["GET", "POST", "PUT", "PATCH"],
)
@chrome_router.api_route(
"/api/playground_api/space/list/",
methods=["GET", "POST", "PUT", "PATCH"],
)
async def coze_playground_space_list(request: Request) -> dict[str, Any]:
await _require_studio_user(request)
return _coze_ok(_space_list_payload())
@chrome_router.api_route(
"/api/playground_api/space/save",
methods=["GET", "POST"],
)
async def coze_playground_space_save(request: Request) -> dict[str, Any]:
await _require_studio_user(request)
return _coze_ok({"id": _DEFAULT_SPACE["id"], "check_not_pass": False})
@chrome_router.api_route("/api/bot/get_type_list", methods=["GET", "POST"])
async def coze_model_type_list(request: Request) -> dict[str, Any]:
await _require_studio_user(request)
return _coze_ok({"model_list": []})
@router.post("/create")
async def coze_create(request: Request, body: CozeCreateRequest) -> dict[str, Any]:
_require_enabled()
store = _get_store(request)
user_id = await get_current_user(request)
created = await store.create_definition(
{
"name": body.name,
"description": body.description,
"owner_id": user_id,
}
)
return {"code": 0, "msg": "success", "data": {"workflow_id": created["id"]}}
@router.post("/canvas")
async def coze_canvas(request: Request, body: CozeCanvasRequest) -> dict[str, Any]:
_require_enabled()
workflow_id = body.resolved_id()
if not workflow_id:
raise HTTPException(status_code=400, detail="workflow_id required")
store = _get_store(request)
user_id = await get_current_user(request)
definition = await _load_owned_definition(request, store, workflow_id, user_id)
versions = await store.list_versions(workflow_id)
return _to_coze_canvas(definition, is_published=bool(versions))
@router.post("/save")
async def coze_save(request: Request, body: CozeSaveRequest) -> dict[str, Any]:
_require_enabled()
workflow_id = body.resolved_id()
if not workflow_id:
raise HTTPException(status_code=400, detail="workflow_id required")
canvas_raw = body.resolved_canvas()
if canvas_raw is None or canvas_raw == "" or canvas_raw == {}:
raise HTTPException(status_code=400, detail="schema required")
canvas_text = _parse_canvas(canvas_raw)
store = _get_store(request)
user_id = await get_current_user(request)
definition = await _load_owned_definition(request, store, workflow_id, user_id)
expected = body.resolved_revision()
if expected is None:
expected = int(definition.get("draft_revision") or 0)
try:
await store.save_studio_draft(
workflow_id,
expected_revision=expected,
# The execution graph is owned by the studio facade; the Coze save
# only persists the canvas, so the current graph passes through.
graph=definition.get("draft_graph") or {},
canvas_schema=canvas_text,
updated_by=user_id,
)
except WorkflowDraftConflictError as exc:
raise HTTPException(
status_code=409,
detail={
"code": "WORKFLOW_DRAFT_CONFLICT",
"currentRevision": exc.current_revision,
},
) from exc
except WorkflowNotFoundError as exc:
raise HTTPException(status_code=404, detail="工作流不存在") from exc
return {"code": 0, "msg": "success", "data": {}}
@router.post("/node_template_list")
async def coze_node_template_list(request: Request) -> dict[str, Any]:
_require_enabled()
await get_current_user(request)
# Coze playground envelope: data.template_list / cate_list (§ workflow-playground-context).
return {
"code": 0,
"msg": "success",
"data": {
"template_list": _COZE_NODE_TEMPLATES,
"cate_list": _COZE_NODE_CATEGORIES,
"plugin_api_list": [],
"plugin_category_list": [],
},
}