diff --git a/backend/app/api/actions.py b/backend/app/api/actions.py new file mode 100644 index 00000000..56116157 --- /dev/null +++ b/backend/app/api/actions.py @@ -0,0 +1,6 @@ +"""生效记录(BE-2,只读;核实走待办)。设计文档 §3.8、§3.10。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api/actions", tags=["actions"]) diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py new file mode 100644 index 00000000..00248e7d --- /dev/null +++ b/backend/app/api/apps.py @@ -0,0 +1,14 @@ +"""应用(BE-3):增删改查、派生、检查、发布、版本、授权、页面解析、入口、实例、视图刷新、组件目录。设计文档 §3.10。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api/apps", tags=["apps"]) + + +@router.get("/catalog") +async def get_catalog() -> dict: + """受信组件目录 v1。前端按名字找渲染器;助手生成时给模型看同一份。""" + from app.apps.catalog import catalog_payload + + return catalog_payload() diff --git a/backend/app/api/auth.py b/backend/app/api/auth.py new file mode 100644 index 00000000..2c10f09f --- /dev/null +++ b/backend/app/api/auth.py @@ -0,0 +1,6 @@ +"""身份接口(BE-1):/me、登录、登出、OIDC、登录方式设置、引导第一个管理员、JWKS。设计文档 §3.10。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api/auth", tags=["auth"]) diff --git a/backend/app/api/capabilities.py b/backend/app/api/capabilities.py new file mode 100644 index 00000000..454d6728 --- /dev/null +++ b/backend/app/api/capabilities.py @@ -0,0 +1,6 @@ +"""能力登记与端点(BE-1):/api/capabilities、/api/endpoints。设计文档 §3.9、§3.10。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api", tags=["capabilities"]) diff --git a/backend/app/api/deps.py b/backend/app/api/deps.py new file mode 100644 index 00000000..5e163eb5 --- /dev/null +++ b/backend/app/api/deps.py @@ -0,0 +1,116 @@ +"""请求里的「人」:身份与权限的唯一入口(docs/design/app-platform-and-look.md §2.7、附录 C)。 + +登录方式三种:off(默认,今天的行为)、local、oidc。各接口不直接碰请求头或会话,只问这里: +- actor_of(header):记在各「人」列上的名字。关登录时照旧解码 X-Actor(自报署名);开了登录返回认证过的 + 用户名,请求头一律不看——这样各接口的签名一个都不用改; +- current_principal():完整身份(用户名、角色、组、是否认证过、登录方式),中间件按请求写进 contextvar; +- require_role(role):挂在 main.py 的 include_router(..., dependencies=[...]) 上的路由级依赖; +- can_read_run / can_read_artifact:运行、工件的读权限(user 角色只能读有授权的应用视图运行、自己参与的实例)。 + +关登录时:所有人等同 admin、全部放行,行为和加这一层之前一模一样(界面上挂横幅说明)。 + +开登录(local / oidc)的实现由 app/auth/ 提供:会话、中间件、OIDC、引导第一个管理员。这个模块只定接口。 +""" +from __future__ import annotations + +from contextvars import ContextVar +from dataclasses import dataclass, field +from typing import Any +from urllib.parse import unquote + +#: 登录方式 +AUTH_MODES = ("off", "local", "oidc") +#: 角色由高到低 +ROLE_RANK = {"user": 1, "builder": 2, "admin": 3} + + +@dataclass(frozen=True) +class Principal: + """这次请求是谁。 + + username:开登录时是认证过的用户名(不可改);关登录时是自报的署名,可能为空。 + verified:是不是认证过的身份。关登录时恒为 False——审计、派给人的记录、run.origin 照实记。 + """ + + username: str | None + role: str = "admin" + display_name: str | None = None + user_id: str | None = None + groups: tuple[str, ...] = field(default_factory=tuple) + verified: bool = False + mode: str = "off" + + def at_least(self, role: str) -> bool: + return ROLE_RANK.get(self.role, 0) >= ROLE_RANK.get(role, 99) + + +#: 中间件按请求写入(app/auth/)。没写(关登录、测试直接调函数)时为 None +_principal: ContextVar[Principal | None] = ContextVar("agentlab_principal", default=None) + + +def set_principal(principal: Principal | None) -> Any: + """中间件用:写入这次请求的身份,返回 token 供 reset。""" + return _principal.set(principal) + + +def reset_principal(token: Any) -> None: + _principal.reset(token) + + +def auth_mode() -> str: + """当前的登录方式。环境变量 AGENTLAB_AUTH_MODE 优先于设置页(app/auth/ 实现读取与缓存)。""" + from app.auth import current_mode + + return current_mode() + + +def decode_actor(header: str | None) -> str | None: + """请求头 X-Actor 里的署名(设置页填的那个),没填就是 None。 + + 浏览器的请求头只能是 Latin-1:中文署名原样放进去,fetch 直接抛错、整个请求 + 发不出去。所以前端按 encodeURIComponent 编码后发,这里解回来;老客户端发的 + 纯 ASCII 署名解码前后一样。 + """ + value = unquote((header or "").strip()).strip() + return value[:100] or None + + +def actor_of(header: str | None) -> str | None: + """记在各「人」列上的名字。开了登录:认证过的用户名,请求头不看;关登录:解码 X-Actor。""" + principal = _principal.get() + if principal is not None and principal.mode != "off": + return principal.username + return decode_actor(header) + + +def current_principal() -> Principal: + """这次请求的完整身份。关登录(或中间件没写)时:等同 admin、未认证。""" + principal = _principal.get() + if principal is not None: + return principal + return Principal(username=None, role="admin", verified=False, mode="off") + + +def actor_verified() -> bool: + return current_principal().verified + + +def require_role(role: str) -> Any: + """路由级依赖:至少是 role。关登录时放行。开登录时:没登录 401,角色不够 403(app/auth/ 实现)。""" + from app.auth import role_dependency + + return role_dependency(role) + + +async def can_read_run(principal: Principal, run: Any) -> bool: + """能不能读这次运行(证据、事件、工件)。关登录或 builder 以上:能。user:有授权的应用视图运行、自己参与的实例。""" + from app.auth import run_readable + + return await run_readable(principal, run) + + +async def can_read_artifact(principal: Principal, artifact_id: str) -> bool: + """能不能读这件工件:它属于的某次运行能读就能读。""" + from app.auth import artifact_readable + + return await artifact_readable(principal, artifact_id) diff --git a/backend/app/api/hooks.py b/backend/app/api/hooks.py new file mode 100644 index 00000000..344b4676 --- /dev/null +++ b/backend/app/api/hooks.py @@ -0,0 +1,6 @@ +"""入站钩子(BE-2):POST /api/hooks/{hook_id},只认签名、不走会话。设计文档 §2.4。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api/hooks", tags=["hooks"]) diff --git a/backend/app/api/identity.py b/backend/app/api/identity.py new file mode 100644 index 00000000..14abefa0 --- /dev/null +++ b/backend/app/api/identity.py @@ -0,0 +1,6 @@ +"""用户、组、审计(BE-1,只给管理员)。设计文档 §3.10。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api", tags=["identity"]) diff --git a/backend/app/api/ledger.py b/backend/app/api/ledger.py new file mode 100644 index 00000000..df7a2da9 --- /dev/null +++ b/backend/app/api/ledger.py @@ -0,0 +1,6 @@ +"""账本(BE-3,只读):工作流版本被哪些应用钉住、生效计数;生效记录查询。设计文档 §2.9 L4。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api/ledger", tags=["ledger"]) diff --git a/backend/app/api/notify.py b/backend/app/api/notify.py new file mode 100644 index 00000000..fd3b4780 --- /dev/null +++ b/backend/app/api/notify.py @@ -0,0 +1,6 @@ +"""通知渠道与投递记录(BE-2)。设计文档 §2.4、§3.10。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api/notify", tags=["notify"]) diff --git a/backend/app/api/runs.py b/backend/app/api/runs.py index fc6c44dd..153d8b98 100644 --- a/backend/app/api/runs.py +++ b/backend/app/api/runs.py @@ -4,7 +4,6 @@ import asyncio import contextlib from datetime import datetime from typing import Any -from urllib.parse import unquote from fastapi import APIRouter, Depends, Header, HTTPException, Query, WebSocket, WebSocketDisconnect from pydantic import BaseModel, Field @@ -12,6 +11,8 @@ from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession from app.api.coded import CodedHTTPException +# 「人」的唯一入口搬到了 api/deps.py(开登录时返回认证过的用户名)。别处照旧从这里导入 actor_of +from app.api.deps import actor_of # noqa: F401 from app.core.bus import bus from app.db.base import SessionLocal, get_session from app.db.models import Approval, Artifact, Run, RunEvent @@ -25,15 +26,6 @@ from app.engine.runner import run_manager router = APIRouter(prefix="/api/runs", tags=["runs"]) -def actor_of(header: str | None) -> str | None: - """请求头 X-Actor 里的署名(设置页填的那个),没填就是 None。 - - 浏览器的请求头只能是 Latin-1:中文署名原样放进去,fetch 直接抛错、整个请求 - 发不出去。所以前端按 encodeURIComponent 编码后发,这里解回来;老客户端发的 - 纯 ASCII 署名解码前后一样。 - """ - value = unquote((header or "").strip()).strip() - return value[:100] or None class StartRunIn(BaseModel): diff --git a/backend/app/api/tasks.py b/backend/app/api/tasks.py new file mode 100644 index 00000000..c73a26e6 --- /dev/null +++ b/backend/app/api/tasks.py @@ -0,0 +1,6 @@ +"""待办(BE-2):列表、计数、详情、回复、改派、催办。设计文档 §3.7、§3.10。""" +from __future__ import annotations + +from fastapi import APIRouter + +router = APIRouter(prefix="/api/tasks", tags=["tasks"]) diff --git a/backend/app/apps/__init__.py b/backend/app/apps/__init__.py new file mode 100644 index 00000000..f6a8fdba --- /dev/null +++ b/backend/app/apps/__init__.py @@ -0,0 +1,14 @@ +"""应用:已发布工作流版本的使用面(docs/design/app-platform-and-look.md 第二、三部分)。 + +模块分工(BE-3 实现,契约见设计文档附录 C): +- spec.py 应用描述 agentlab.app/1、表单 agentlab.form/1 的形状 +- catalog.py 受信组件目录 v1 +- versions.py 「已发布且未退役」的唯一说法、退役 +- forms.py 表单校验、输入节点字段 → 表单 +- entries.py 应用入口发起实例 +- ops.py 应用操作(助手润色、编辑器共用) +- lint.py 应用的发布检查(app.*) +- derive.py 从工作流版本确定性派生应用 +- describe.py 给助手查看用的「工作流版本」详情 +- resolve.py 页面解析与视图模型 agentlab.view/1(BE-3 新建) +""" diff --git a/backend/app/apps/catalog.py b/backend/app/apps/catalog.py new file mode 100644 index 00000000..28c5bc65 --- /dev/null +++ b/backend/app/apps/catalog.py @@ -0,0 +1,88 @@ +"""受信组件目录 v1(docs/design/app-platform-and-look.md §2.2、§3.5)。 + +一份目录,四个使用方:应用页、人工节点表单、agent 拟的询问、助手生成。模型只能从这里挑组件;前端只有一张 +「名字 → 渲染器」的表,遇到不认识的组件显示「此组件需要更新前端」,不报错、不空白。 + +每个组件登记:名字、中文名、类别、版本、props 的 JSON Schema、允许的绑定种类、能不能有子组件。 +服务端校验器和解析器由 app/apps/ 的实现按名字注册(BE-3);开发者扩展组件时,目录项、校验器、解析器、前端渲染器 +四样都要给,缺一样启动即报错(check_registry)。 +""" +from __future__ import annotations + +from typing import Any + +CATEGORIES = ("layout", "display", "input", "process") +CATEGORY_LABEL = {"layout": "布局", "display": "展示", "input": "输入", "process": "流程"} + + +def _props(**properties: Any) -> dict[str, Any]: + return {"type": "object", "additionalProperties": False, "properties": properties} + + +_TEXT = {"type": "string", "maxLength": 200} +_LONG = {"type": "string", "maxLength": 4000} + +COMPONENTS: list[dict[str, Any]] = [ + # ---- 布局 ---- + {"name": "page", "label": "页面", "category": "layout", "version": 1, "children": True, "bindings": [], + "props": _props(title=_TEXT)}, + {"name": "section", "label": "分区", "category": "layout", "version": 1, "children": True, "bindings": [], + "props": _props(title=_TEXT, description=_LONG)}, + {"name": "columns", "label": "分栏", "category": "layout", "version": 1, "children": True, "bindings": [], + "props": _props(count={"type": "integer", "minimum": 1, "maximum": 4})}, + {"name": "tabs", "label": "页签", "category": "layout", "version": 1, "children": True, "bindings": [], + "props": _props(labels={"type": "array", "items": _TEXT, "maxItems": 8})}, + {"name": "divider", "label": "分隔线", "category": "layout", "version": 1, "children": False, "bindings": [], + "props": _props()}, + # ---- 展示 ---- + {"name": "stamp", "label": "印章", "category": "display", "version": 1, "children": False, + "bindings": ["run"], "props": _props(compact={"type": "boolean"})}, + {"name": "metric", "label": "指标块", "category": "display", "version": 1, "children": False, + "bindings": ["metric", "cell"], "props": _props(label=_TEXT, unit=_TEXT, conv=_TEXT)}, + {"name": "series", "label": "趋势", "category": "display", "version": 1, "children": False, + "bindings": ["series"], "props": _props(label=_TEXT, chart={"enum": ["line", "bar"]})}, + {"name": "table", "label": "表格", "category": "display", "version": 1, "children": False, + "bindings": ["query"], "props": _props(title=_TEXT, columns={"type": "array", "items": _TEXT}, + sort={"type": "string"}, limit={"type": "integer", "minimum": 1})}, + {"name": "chart", "label": "图表", "category": "display", "version": 1, "children": False, + "bindings": ["query"], "props": _props(title=_TEXT, chart={"enum": ["line", "bar"]}, x=_TEXT, + y={"type": "array", "items": _TEXT, "maxItems": 4})}, + {"name": "report", "label": "报告", "category": "display", "version": 1, "children": False, + "bindings": ["report"], "props": _props(title=_TEXT)}, + {"name": "text", "label": "文字", "category": "display", "version": 1, "children": False, "bindings": [], + "props": _props(markdown=_LONG)}, + {"name": "notice", "label": "提示", "category": "display", "version": 1, "children": False, "bindings": [], + "props": _props(text=_LONG, tone={"enum": ["info", "warn", "error"]})}, + {"name": "field", "label": "字段", "category": "display", "version": 1, "children": False, + "bindings": ["input", "output", "run"], "props": _props(label=_TEXT)}, + {"name": "status", "label": "状态", "category": "display", "version": 1, "children": False, + "bindings": ["run"], "props": _props(label=_TEXT)}, + # ---- 输入 ---- + {"name": "form", "label": "表单", "category": "input", "version": 1, "children": False, "bindings": [], + "props": _props(form={"type": "string"}, submit_label=_TEXT)}, + # ---- 流程 ---- + {"name": "entry_button", "label": "发起按钮", "category": "process", "version": 1, "children": False, + "bindings": [], "props": _props(entry={"type": "string"}, label=_TEXT)}, + {"name": "instance_list", "label": "实例列表", "category": "process", "version": 1, "children": False, + "bindings": [], "props": _props(entry={"type": "string"}, who={"enum": ["mine", "all"]}, + limit={"type": "integer", "minimum": 1, "maximum": 200})}, + {"name": "instance_header", "label": "实例概况", "category": "process", "version": 1, "children": False, + "bindings": [], "props": _props()}, + {"name": "instance_timeline", "label": "实例进度", "category": "process", "version": 1, "children": False, + "bindings": [], "props": _props()}, + {"name": "task_list", "label": "待办列表", "category": "process", "version": 1, "children": False, + "bindings": [], "props": _props(scope={"enum": ["mine", "instance"]})}, + {"name": "task_form", "label": "待办表单", "category": "process", "version": 1, "children": False, + "bindings": ["task"], "props": _props()}, + {"name": "signoffs", "label": "会签进度", "category": "process", "version": 1, "children": False, + "bindings": ["task"], "props": _props()}, + {"name": "action_status", "label": "动作状态", "category": "process", "version": 1, "children": False, + "bindings": ["action"], "props": _props(label=_TEXT)}, +] + +BY_NAME: dict[str, dict[str, Any]] = {c["name"]: c for c in COMPONENTS} + + +def catalog_payload() -> dict[str, Any]: + """GET /api/apps/catalog 的返回:组件目录 + 类别名。助手生成时也给模型看这一份(只给名字、中文名、props、绑定)。""" + return {"version": 1, "categories": CATEGORY_LABEL, "components": COMPONENTS} diff --git a/backend/app/apps/derive.py b/backend/app/apps/derive.py new file mode 100644 index 00000000..0fcb0cca --- /dev/null +++ b/backend/app/apps/derive.py @@ -0,0 +1,15 @@ +"""从工作流版本确定性派生应用(A8):不靠模型,助手失败了也有可用的应用(P3)。 + +入口字段 → 入口表单;人工节点 → 待办(岗位留空等人绑定);口径卡 → 指标块;报告 → 报告块;取数节点 → 表格; +写入的调用工具节点 → 动作确认待办 + 动作状态。 +""" +from __future__ import annotations + +from typing import Any + +from sqlalchemy.ext.asyncio import AsyncSession + + +async def derive_app(session: AsyncSession, workflow_id: str, version: int, *, name: str | None = None) -> dict[str, Any]: + """返回一份 agentlab.app/1 spec(未发布的草稿)。""" + raise NotImplementedError("BE-3") diff --git a/backend/app/apps/describe.py b/backend/app/apps/describe.py new file mode 100644 index 00000000..d6bbf575 --- /dev/null +++ b/backend/app/apps/describe.py @@ -0,0 +1,9 @@ +"""给助手查看(look 的 workflow_version 类型)用的工作流版本详情:入口字段、人工节点、口径卡指标、报告、 +取数节点、写入动作,以及版本、级别、哈希。不含任何密钥(L3)。""" +from __future__ import annotations + +from typing import Any + + +def describe_version(version: Any, *, workflow_name: str) -> str: + raise NotImplementedError("BE-3") diff --git a/backend/app/apps/entries.py b/backend/app/apps/entries.py new file mode 100644 index 00000000..caa866ec --- /dev/null +++ b/backend/app/apps/entries.py @@ -0,0 +1,16 @@ +"""应用入口:按入口表单校验 → 映射成钉住版本的运行输入 → 发起正式运行(来源 app_entry / hook)。""" +from __future__ import annotations + +from typing import Any + + +async def start_entry(app_id: str, entry_id: str, values: dict[str, Any], principal: Any, *, + origin_kind: str = "app_entry", hook: str | None = None) -> Any: + """发起一个实例,返回 Run。校验失败抛 FormRejected(errors);应用需升级(钉住的版本已退役)时拒绝。""" + raise NotImplementedError("BE-3") + + +class FormRejected(Exception): + def __init__(self, errors: list[dict[str, Any]]) -> None: + super().__init__("表单没有通过校验") + self.errors = errors diff --git a/backend/app/apps/forms.py b/backend/app/apps/forms.py new file mode 100644 index 00000000..e779ea82 --- /dev/null +++ b/backend/app/apps/forms.py @@ -0,0 +1,29 @@ +"""表单 agentlab.form/1:校验和输入节点字段的转换(§3.3)。 + +前端只校验同一份子集(lib/schemaForm.ts);这里用 jsonschema 复核,以这里为准。错误格式两边一样:{path, code, message}。 +""" +from __future__ import annotations + +from typing import Any, TypedDict + + +class FormError(TypedDict): + path: str + code: str + message: str + + +def validate_form_schema(form: Any) -> list[str]: + """表单本身合不合目录(只用允许的 type / format / x-widget,没有 pattern……)。返回问题说明,空表示合规。""" + raise NotImplementedError("BE-3") + + +def validate_form(form: dict[str, Any], values: Any) -> list[FormError]: + """按表单校验一份填写的值。""" + raise NotImplementedError("BE-3") + + +def input_schema(fields: list[dict[str, Any]]) -> dict[str, Any]: + """输入节点的 fields(name / required / default / description / example,以及新增的 type / enum / format)→ + agentlab.form/1。没写 type 的按 string。""" + raise NotImplementedError("BE-3") diff --git a/backend/app/apps/lint.py b/backend/app/apps/lint.py new file mode 100644 index 00000000..d25f8533 --- /dev/null +++ b/backend/app/apps/lint.py @@ -0,0 +1,14 @@ +"""应用的发布检查(§3.13 的 app.* 编号)。问题格式同 engine/schema.py 的 ValidationIssue: +{message, level: error|warning, code, path}。path 指向 spec 里的位置(如 pages[0].body[2].bind)。 +""" +from __future__ import annotations + +from typing import Any + +from sqlalchemy.ext.asyncio import AsyncSession + + +async def lint_app(session: AsyncSession, spec: dict[str, Any], bindings: dict[str, Any], *, + previous: Any | None = None, dispositions: dict[str, str] | None = None) -> list[dict[str, Any]]: + """检查一份待发布的应用。previous 是上一个应用版本(判断钉住项升版要不要处置)。""" + raise NotImplementedError("BE-3") diff --git a/backend/app/apps/ops.py b/backend/app/apps/ops.py new file mode 100644 index 00000000..b3c4960d --- /dev/null +++ b/backend/app/apps/ops.py @@ -0,0 +1,21 @@ +"""应用操作:编辑器和助手润色共用(L1 的 AppApplier 调这里)。 + +操作(一行一个 JSON): + {"op":"app_add","parent":"<组件 id>|<页面 id>","index":0,"component":{...}} + {"op":"app_update","id":"<组件 id>","props":{...},"bind":{...},"visible":"..."} + {"op":"app_remove","id":"<组件 id>"} + {"op":"app_move","id":"<组件 id>","parent":"...","index":0} + {"op":"app_page","page":{"id","title"}} 新增或改页面标题 + {"op":"app_set","path":"entries|views|forms|slots|task_ui","key":"…","value":{...}} +""" +from __future__ import annotations + +from typing import Any + +# 落地结果和图操作共用一个形状(L1 的 Applier 接口) +from app.look.base import Applied # noqa: F401 + + +def apply_app_op(spec: dict[str, Any], op: dict[str, Any]) -> Applied: + """把一个应用操作应用到 spec(原地修改)。认不出、目标不存在的返回 Applied(False, False, problem)。""" + raise NotImplementedError("BE-3") diff --git a/backend/app/apps/spec.py b/backend/app/apps/spec.py new file mode 100644 index 00000000..d882d277 --- /dev/null +++ b/backend/app/apps/spec.py @@ -0,0 +1,150 @@ +"""应用描述 agentlab.app/1 与表单 agentlab.form/1 的结构(docs/design/app-platform-and-look.md §3.2–§3.4)。 + +这里只管「形状」:pydantic 认得出字段、类型、必填。语义检查(钉住的版本存不存在、绑定的节点在不在、表达式合不合法、 +数字有没有证据……)在 app/apps/lint.py,编号见设计文档 §3.13。 + +界面层不放逻辑(P7):绑定是带类型的对象,不是模板;可见性表达式只能用 APP_ROOTS 里的根名字,禁止算术, +由 engine/expressions.py 和画布校验、运行时同一个解析器求值,服务端求值、不可见的不下发。 +""" +from __future__ import annotations + +from typing import Any, Literal + +from pydantic import BaseModel, ConfigDict, Field + +APP_FORMAT = "agentlab.app/1" +FORM_FORMAT = "agentlab.form/1" +VIEW_FORMAT = "agentlab.view/1" + +#: 可见性表达式能用的根名字(engine/expressions.py 的 roots=) +APP_ROOTS = frozenset({"run", "input", "metric", "instance", "task", "user", "view"}) + +#: 绑定的种类:bind 对象里出现哪个键就是哪种(§3.4) +BINDING_KINDS = ("metric", "series", "cell", "query", "report", "input", "run", "output", "task", "action") + +#: 钉住项的用途。process 的版本按流程规则检查(process.*) +PIN_USES = ("view", "entry", "process") + +#: 视图来源 +SOURCE_KINDS = ("latest_sealed", "on_demand", "instance") + +#: 钉住项升版的处置(同口径升版,engine/governance.py 的 UPGRADE_POLICIES) +DISPOSITIONS = ("recompute", "dual", "incomparable") + +#: 表单控件(agentlab.form/1 的 x-widget) +FORM_WIDGETS = ( + "text", "textarea", "number", "integer", "date", "datetime", "select", "radio", "multiselect", "checkbox", + "principal", "note", "json", +) +#: 表单字段能用的 type +FORM_TYPES = ("string", "number", "integer", "boolean", "array") +#: 表单字段能用的 format。不支持 pattern:JS 和 Python 的正则语义不同,会出现前端放行、后端拒收 +FORM_FORMATS = ("date", "date-time", "email", "uri") +#: 表单校验错误的 code +FORM_ERROR_CODES = ("required", "type", "enum", "minimum", "maximum", "min_length", "max_length", "max_items", "format") + + +class _Strict(BaseModel): + model_config = ConfigDict(extra="forbid", populate_by_name=True) + + +class Pin(_Strict): + alias: str + workflow_id: str + version: int + graph_hash: str + level: str | None = None + use: Literal["view", "entry", "process"] = "view" + + +class Slot(_Strict): + label: str + + +class InstanceTitle(_Strict): + """实例标题:只能按名字引用入口字段,由服务端拼。例:{"pattern": "{applicant} 的报销", "fields": ["applicant"]}""" + + pattern: str + fields: list[str] = Field(default_factory=list) + + +class Entry(_Strict): + id: str + label: str + pin: str + # 内联的 agentlab.form/1,或 {"$ref": "#/forms/<名字>"} + form: dict[str, Any] + # 入口字段 ← 表单值 / 当前用户 / 常量:{"amount": "form.amount", "applicant": "user.display_name", "kind": "'报销'"} + map: dict[str, str] = Field(default_factory=dict) + instance_title: InstanceTitle | None = None + + +class ViewSource(_Strict): + kind: Literal["latest_sealed", "on_demand", "instance"] + pin: str | None = None + # latest_sealed:schedule: | formal + from_: str | None = Field(default=None, alias="from") + # on_demand:参数表单(agentlab.form/1 或 $ref)、缓存时效、打开页面时是否自动发起 + params: dict[str, Any] | None = None + ttl_s: int | None = None + auto: bool = False + + +class View(_Strict): + source: ViewSource + + +class Component(_Strict): + id: str + type: str + props: dict[str, Any] = Field(default_factory=dict) + # 带类型的绑定(BINDING_KINDS 之一),不是模板 + bind: dict[str, Any] | None = None + # 可见性表达式(APP_ROOTS,禁止算术) + visible: str | None = None + # 可见性表达式里 run / metric / input 指的是哪个视图 + scope: str | None = None + children: list[Component] = Field(default_factory=list) + + +class Page(_Strict): + id: str + title: str + body: list[Component] = Field(default_factory=list) + + +class Hook(_Strict): + name: str + kind: Literal["start", "signal"] + entry: str | None = None + + +class NotifySub(_Strict): + channel: str + events: list[str] = Field(default_factory=list) + + +class AppSpec(_Strict): + format: Literal["agentlab.app/1"] = "agentlab.app/1" + name: str + description: str = "" + icon: str = "app" + pins: list[Pin] = Field(default_factory=list) + slots: dict[str, Slot] = Field(default_factory=dict) + entries: list[Entry] = Field(default_factory=list) + forms: dict[str, dict[str, Any]] = Field(default_factory=dict) + # 按人工节点 id 覆盖待办的外观(标题、x-order、x-widget),不能改数据约束 + task_ui: dict[str, dict[str, Any]] = Field(default_factory=dict) + views: dict[str, View] = Field(default_factory=dict) + pages: list[Page] = Field(default_factory=list) + hooks: list[Hook] = Field(default_factory=list) + notify: list[NotifySub] = Field(default_factory=list) + + +def parse_spec(data: Any) -> AppSpec: + """按形状解析一份 spec;形状不对抛 pydantic.ValidationError(lint 把它翻成 app.format)。""" + return AppSpec.model_validate(data) + + +def empty_spec(name: str) -> dict[str, Any]: + return AppSpec(name=name).model_dump(mode="json", by_alias=True) diff --git a/backend/app/apps/versions.py b/backend/app/apps/versions.py new file mode 100644 index 00000000..0c43a360 --- /dev/null +++ b/backend/app/apps/versions.py @@ -0,0 +1,30 @@ +"""「已发布且未退役」的工作流版本:发起正式运行、口径升版判定、子图钉版本、应用钉版本都用这一个说法(P5,A1)。 + +以前三处各有各的判断:发起只认当前发布版(launch.py:92,F1),口径升版取 max(version) 把草稿也算进去(F3)。 +""" +from __future__ import annotations + +from typing import Any + +from sqlalchemy.ext.asyncio import AsyncSession + + +def is_published(version: Any, *, current: int | None = None) -> bool: + """这一版能不能被使用:level 不为空且没退役。level 为空的老数据,只认它就是 current(当前发布版)的情形。""" + raise NotImplementedError("BE-3") + + +async def published_versions(session: AsyncSession, workflow_id: str) -> list[Any]: + """这个工作流全部「已发布且未退役」的版本(WorkflowVersion),按版本号升序。""" + raise NotImplementedError("BE-3") + + +async def latest_published(session: AsyncSession, workflow_id: str) -> Any | None: + """最新的「已发布且未退役」的版本;没有就是 None。口径升版的判定用它(替换 governance.py 的 func.max)。""" + raise NotImplementedError("BE-3") + + +async def retire_version(session: AsyncSession, workflow_id: str, version: int, *, actor: str | None, + note: str | None) -> dict[str, Any]: + """退役一个版本。当前发布版不能退(409)。返回 {retired, affected_apps: [...]};写审计。""" + raise NotImplementedError("BE-3") diff --git a/backend/app/auth/__init__.py b/backend/app/auth/__init__.py new file mode 100644 index 00000000..7dde381f --- /dev/null +++ b/backend/app/auth/__init__.py @@ -0,0 +1,40 @@ +"""身份的实现(docs/design/app-platform-and-look.md §2.7):登录方式、会话、中间件、OIDC、引导与找回。 + +api/deps.py 只定接口,这里给实现。契约骨架阶段只有关登录(off)的行为:全部放行、等同 admin。 +开登录(local / oidc)由 BE-1 补齐:会话 cookie、中间件写 contextvar、角色依赖、运行与工件的读权限。 +""" +from __future__ import annotations + +import os +from typing import Any + +from fastapi import Depends + + +def current_mode() -> str: + """当前的登录方式:环境变量 AGENTLAB_AUTH_MODE 优先;没设时读设置(BE-1 实现),默认 off。""" + mode = (os.environ.get("AGENTLAB_AUTH_MODE") or "").strip().lower() + return mode if mode in ("off", "local", "oidc") else "off" + + +def role_dependency(role: str) -> Any: + """至少是 role 的路由级依赖。关登录时放行。""" + + async def _check() -> None: + if current_mode() == "off": + return None + raise NotImplementedError("开登录时的角色检查由 BE-1 实现") + + return Depends(_check) + + +async def run_readable(principal: Any, run: Any) -> bool: + if current_mode() == "off": + return True + raise NotImplementedError("开登录时的运行读权限由 BE-1 实现") + + +async def artifact_readable(principal: Any, artifact_id: str) -> bool: + if current_mode() == "off": + return True + raise NotImplementedError("开登录时的工件读权限由 BE-1 实现") diff --git a/backend/app/capabilities/__init__.py b/backend/app/capabilities/__init__.py new file mode 100644 index 00000000..f5729061 --- /dev/null +++ b/backend/app/capabilities/__init__.py @@ -0,0 +1,5 @@ +"""能力登记与登记的端点(A6,docs/design/app-platform-and-look.md §2.6、§3.9)。BE-1 实现。 + +- registry.py 能力的同步、治理、快照、作证判定、遮罩字段 +- endpoints.py 端点的增删改查、环境、平台执行器(BE-1 新建) +""" diff --git a/backend/app/capabilities/registry.py b/backend/app/capabilities/registry.py new file mode 100644 index 00000000..295a953c --- /dev/null +++ b/backend/app/capabilities/registry.py @@ -0,0 +1,69 @@ +"""能力登记的对外接口(附录 C,BE-1 提供)。 + +契约骨架阶段的默认行为和今天一致:is_platform_query 仍按数据源查询工具的名字前缀认,其余接口未实现。 +""" +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + +from sqlalchemy.ext.asyncio import AsyncSession + + +@dataclass(frozen=True) +class EndpointResult: + status: int | None + #: 响应体(解析后的 JSON 或文本) + body: Any + #: 按 tabular 落成的查询快照形状的工件 id(声明了 tabular 的读取才有) + snapshot_artifact: str | None = None + #: 网络层没拿到确定结果(超时、连接中断) + unknown: bool = False + error: str | None = None + environment: str = "prod" + + +async def sync_all(session: AsyncSession) -> int: + """把内置工具、数据源、自定义工具、MCP 同步进 capabilities。返回变动的行数。启动时和各对象增删改时调。""" + raise NotImplementedError("BE-1") + + +async def get_capability(session: AsyncSession, name: str) -> Any | None: + """一行能力登记(db.models_capabilities.Capability),没有就是 None。""" + raise NotImplementedError("BE-1") + + +def effective_effect(capability: Any) -> str: + """治理后的效果:effect 为空时按 effect_system。""" + raise NotImplementedError("BE-1") + + +async def capability_snapshot(session: AsyncSession, tool_names: list[str]) -> dict[str, Any]: + """运行发起时用到的能力的治理快照:{名字: {effect, approval, unattended_write, version, endpoint_id, masked}}。 + 写进 Run.options["capabilities"],恢复和重放用同一份。""" + raise NotImplementedError("BE-1") + + +async def capability_versions_for(session: AsyncSession, tool_names: list[str]) -> dict[str, int]: + """发布时记下的能力版本:{名字: version}。""" + raise NotImplementedError("BE-1") + + +def is_platform_query(name: str) -> bool: + """这个工具的结果能不能当查询快照作证(替换 nodes/tools.py、nodes/llm.py 里按名字前缀的判断,F11)。 + 认的是「平台执行」这个身份:数据源查询工具,和登记里声明了 tabular、绑定端点、由平台执行的读取。""" + from app.tools.datasource import QUERY_PREFIX + + return name.startswith(QUERY_PREFIX) + + +async def endpoint_request(session: AsyncSession, capability: Any, args: dict[str, Any], *, environment: str, + idem_key: str | None = None, on_behalf: str | None = None, + run_id: str | None = None, node_id: str | None = None) -> EndpointResult: + """平台执行器:按登记的端点发请求(只认登记的 base_url,参数按路径段编码代入),声明了 tabular 的读取落快照。""" + raise NotImplementedError("BE-1") + + +def masked_paths(capability: Any) -> list[str]: + """能力的遮罩字段(JSON 指针)。""" + raise NotImplementedError("BE-1") diff --git a/backend/app/core/events.py b/backend/app/core/events.py index b23b4936..71a1c231 100644 --- a/backend/app/core/events.py +++ b/backend/app/core/events.py @@ -84,6 +84,27 @@ class EventType(StrEnum): # 封存核对只覆盖 manifest_seq 之前的事件,追加它不影响 verify;封存的报告文档一个字都不改 EVIDENCE_JUDGED = "evidence.judged" + # 应用平台(docs/design/app-platform-and-look.md §3.11) + # 运行来源:发起时写进 launch_run 的 notes,在封存范围内(engine/origin.py) + RUN_ORIGIN = "run.origin" + # 待办:一次中断面向人的那一面(app/process/tasks.py) + TASK_OPENED = "task.opened" + TASK_RESPONDED = "task.responded" # 谁、怎么决定的、第几人 / 共几人 + TASK_REASSIGNED = "task.reassigned" + TASK_REMINDED = "task.reminded" + TASK_ESCALATED = "task.escalated" + TASK_EXPIRED = "task.expired" + TASK_RESOLVED = "task.resolved" + TASK_CANCELLED = "task.cancelled" + # 动作:写外部系统(app/process/actions.py)。prepared 带 payload_hash、环境、遮罩后的预览 + ACTION_PREPARED = "action.prepared" + ACTION_SENT = "action.sent" + ACTION_CONFIRMED = "action.confirmed" + ACTION_FAILED = "action.failed" + ACTION_UNKNOWN = "action.unknown" + ACTION_RECONCILED = "action.reconciled" + ACTION_SIMULATED = "action.simulated" + # 其他 LOG = "log" USAGE = "usage" # token / 成本累计 diff --git a/backend/app/db/base.py b/backend/app/db/base.py index 3bc178cc..109864f8 100644 --- a/backend/app/db/base.py +++ b/backend/app/db/base.py @@ -218,13 +218,35 @@ _COLUMN_MIGRATIONS: list[tuple[str, str, str]] = [ ("catalog_draft_tasks", "chunks_done", "INTEGER"), # 复核后:逐表的日志(模型提议的有效记录条件没有收下的原因)。存量任务回填 NULL,接口给空列表 ("catalog_draft_tasks", "log", "JSON"), + # 应用平台(docs/design/app-platform-and-look.md §3.1.2)。新表由 create_all 建;这些是已有表的新列,存量一律 NULL: + # 运行的来源未记录、版本的发布人和退役没记过、MCP 没有认证头、对话不属于任何应用 + ("runs", "origin_kind", "VARCHAR(20)"), + ("runs", "origin", "JSON"), + ("runs", "app_id", "VARCHAR(32)"), + ("runs", "app_version", "INTEGER"), + ("workflow_versions", "published_at", "DATETIME"), + ("workflow_versions", "published_by", "VARCHAR(100)"), + ("workflow_versions", "retired_at", "DATETIME"), + ("workflow_versions", "retired_by", "VARCHAR(100)"), + ("workflow_versions", "retire_note", "TEXT"), + ("workflow_versions", "capability_versions", "JSON"), + ("workflows", "origin", "JSON"), + ("mcp_servers", "headers", "JSON DEFAULT '{}'"), + ("mcp_servers", "endpoint_id", "VARCHAR(32)"), + ("conversations", "app_id", "VARCHAR(32)"), ] -#: 迁移补上的列要建的索引:(索引名, 表, 列)。create_all 不碰已有的表,表上新列的索引也就不会建。 -#: 索引名照 NAMING_CONVENTION 取,和新库 create_all 建出来的同名,IF NOT EXISTS 才不会重复建 -_INDEX_MIGRATIONS: list[tuple[str, str, str]] = [ +#: 迁移补上的列要建的索引:(索引名, 表, 列或多列)。create_all 不碰已有的表,表上新列的索引也就不会建。 +#: 索引名照 NAMING_CONVENTION 取(多列的照模型 __table_args__ 里写的名字),和新库 create_all 建出来的同名, +#: IF NOT EXISTS 才不会重复建 +_INDEX_MIGRATIONS: list[tuple[str, str, str | tuple[str, ...]]] = [ # 定时任务的触发历史按它找这个任务发起的运行 ("ix_runs_schedule_id", "runs", "schedule_id"), + # 应用平台:按来源、按应用筛运行;按工作流、版本、状态找钉住版本最近一次封存的运行 + ("ix_runs_origin_kind", "runs", "origin_kind"), + ("ix_runs_app_id", "runs", "app_id"), + ("ix_runs_wf_ver_status", "runs", ("workflow_id", "version", "status")), + ("ix_conversations_app_id", "conversations", "app_id"), ] @@ -235,10 +257,11 @@ def _migrate(conn) -> None: # pragma: no cover - 同步回调 cols = {row[1] for row in conn.execute(text(f"PRAGMA table_info({table})"))} if cols and column not in cols: conn.execute(text(f"ALTER TABLE {table} ADD COLUMN {column} {ddl}")) - for name, table, column in _INDEX_MIGRATIONS: + for name, table, columns in _INDEX_MIGRATIONS: + wanted = (columns,) if isinstance(columns, str) else columns cols = {row[1] for row in conn.execute(text(f"PRAGMA table_info({table})"))} - if column in cols: - conn.execute(text(f"CREATE INDEX IF NOT EXISTS {name} ON {table} ({column})")) + if all(c in cols for c in wanted): + conn.execute(text(f"CREATE INDEX IF NOT EXISTS {name} ON {table} ({', '.join(wanted)})")) async def init_db() -> None: diff --git a/backend/app/db/models.py b/backend/app/db/models.py index f341e89a..2fc80af8 100644 --- a/backend/app/db/models.py +++ b/backend/app/db/models.py @@ -461,6 +461,9 @@ class McpServer(Base, TimestampMixin): tools_cache: Mapped[list[Any]] = mapped_column(default=list) # 最近一次连接的时刻和耗时(status / last_error 只有结论,没有「何时、多快」) last_check: Mapped[dict[str, Any] | None] = mapped_column(default=None) + # http 传输的认证头(值经 core/crypto 加密,接口只回掩码);或者绑定一个登记的端点(app/capabilities) + headers: Mapped[dict[str, Any]] = mapped_column(default=dict) + endpoint_id: Mapped[str | None] = mapped_column(String(32), default=None) class CustomTool(Base, TimestampMixin): @@ -497,6 +500,8 @@ class Workflow(Base, TimestampMixin): # 正式运行默认解析到这个版本;为空表示还没发布过 published_version: Mapped[int | None] = mapped_column(Integer, default=None) published_by: Mapped[str | None] = mapped_column(String(100), default=None) + # 从运行提取来的工作流记下来源:{"run_id", "conversation_id"?, "turn_id"?}(/copilot/from-run)。手建的为空 + origin: Mapped[dict[str, Any] | None] = mapped_column(default=None) versions: Mapped[list["WorkflowVersion"]] = relationship( back_populates="workflow", cascade="all, delete-orphan", lazy="selectin" @@ -523,6 +528,15 @@ class WorkflowVersion(Base, TimestampMixin): # 从这一版发起正式运行时和当前的比,有变化只提醒、不拦。没发布过、或者是加这一列之前发布的为空——不知道 # 当时是哪一版,不提醒 catalog_versions: Mapped[dict[str, Any] | None] = mapped_column(default=None) + # 这一版是谁、什么时候发布的(工作流上的 published_by 只记最近一次)。存量为空 + published_at: Mapped[datetime | None] = mapped_column(default=None) + published_by: Mapped[str | None] = mapped_column(String(100), default=None) + # 退役:不再接受新的正式运行,进行中的实例照常走完。当前发布版不能退役(app/apps/versions.py) + retired_at: Mapped[datetime | None] = mapped_column(default=None) + retired_by: Mapped[str | None] = mapped_column(String(100), default=None) + retire_note: Mapped[str | None] = mapped_column(Text, default=None) + # 发布时这一版用到的能力的治理版本:{能力名: version}。正式运行发起时有漂移只提醒、不拦 + capability_versions: Mapped[dict[str, Any] | None] = mapped_column(default=None) workflow: Mapped[Workflow] = relationship(back_populates="versions") @@ -534,6 +548,8 @@ class WorkflowVersion(Base, TimestampMixin): class Run(Base, TimestampMixin): __tablename__ = "runs" + # 找钉住版本最近一次封存的运行(应用的视图、口径对比)。存量库由 db/base.py 的 _INDEX_MIGRATIONS 补建 + __table_args__ = (Index("ix_runs_wf_ver_status", "workflow_id", "version", "status"),) id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) workflow_id: Mapped[str | None] = mapped_column( @@ -583,6 +599,12 @@ class Run(Base, TimestampMixin): options: Mapped[dict[str, Any]] = mapped_column(default=dict) # 发起它的定时任务,手动发起的为空。不设外键:定时任务删掉之后,运行记录照旧是追溯凭证,来源 id 留着 schedule_id: Mapped[str | None] = mapped_column(String(32), default=None, index=True) + # 运行来源(engine/origin.py 的 ORIGIN_KINDS):chat / canvas / launcher / schedule / app_entry / app_view / + # app_backfill / hook / api。发起时由 launch_run 写,同时记一条 run.origin 事件进封存范围。存量为空:来源未记录 + origin_kind: Mapped[str | None] = mapped_column(String(20), default=None, index=True) + origin: Mapped[dict[str, Any] | None] = mapped_column(default=None) + app_id: Mapped[str | None] = mapped_column(String(32), default=None, index=True) + app_version: Mapped[int | None] = mapped_column(Integer, default=None) events: Mapped[list["RunEvent"]] = relationship( back_populates="run", cascade="all, delete-orphan" @@ -789,6 +811,8 @@ class Conversation(Base, TimestampMixin): ForeignKey("workflows.id", ondelete="CASCADE"), default=None, index=True ) archived: Mapped[bool] = mapped_column(default=False) + # 应用编辑时助手对话归属的应用(kind=app)。其余为空 + app_id: Mapped[str | None] = mapped_column(String(32), default=None, index=True) # 列表按活跃度排。不能用 updated_at —— 改个标题就会把这条顶到最前面, # 而用户对"最近聊过的"的预期是按说话时间排,不是按编辑时间 last_active_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, index=True) @@ -931,3 +955,18 @@ class WebhookDelivery(Base): attempts: Mapped[int] = mapped_column(Integer, default=0) error: Mapped[str | None] = mapped_column(Text, default=None) created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) + + +# -------------------------------------------------------------------------- +# 应用平台(docs/design/app-platform-and-look.md §3.1):按领域分文件,这里统一导入, +# 让 init_db 的 create_all 和其他模块 `from app.db.models import ...` 都认得到 +# -------------------------------------------------------------------------- + +from app.db.models_apps import ( # noqa: E402,F401 + App, AppGrant, AppHook, AppVersion, AppViewCache, HookReceipt, +) +from app.db.models_capabilities import Capability, Endpoint # noqa: E402,F401 +from app.db.models_identity import AuditEvent, AuthSession, Group, GroupMember, User # noqa: E402,F401 +from app.db.models_process import ( # noqa: E402,F401 + ActionRecord, NotifyChannel, NotifyDelivery, Task, TaskAssignment, +) diff --git a/backend/app/db/models_apps.py b/backend/app/db/models_apps.py new file mode 100644 index 00000000..255251e7 --- /dev/null +++ b/backend/app/db/models_apps.py @@ -0,0 +1,112 @@ +"""应用(应用平台 A1–A3,docs/design/app-platform-and-look.md §2.1–§2.3、§3.1–§3.6)。 + +App 可变(名称、草稿、授权);AppVersion 不可变,只在发布时生成:spec(agentlab.app/1)、钉住的工作流版本(pins)、 +岗位与钩子的绑定(bindings)、级别(取各钉住项里最低的那一级)、spec_hash、钉住项升版的处置(dispositions)。 +授权(app_grants)和组成员不进版本,改动写审计。 +""" +from __future__ import annotations + +from datetime import datetime +from typing import Any + +from sqlalchemy import ForeignKey, Integer, String, Text, UniqueConstraint +from sqlalchemy.orm import Mapped, mapped_column + +from app.db.base import Base, TimestampMixin, UTCDateTime, new_id, utcnow + +#: 应用授权:use 能用(入口、视图、自己的实例);observe 另能看全部实例;manage 能搭建、发布、改派 +GRANT_ROLES = ("use", "observe", "manage") + + +class App(Base, TimestampMixin): + __tablename__ = "apps" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + name: Mapped[str] = mapped_column(String(200)) + description: Mapped[str] = mapped_column(Text, default="") + icon: Mapped[str] = mapped_column(String(40), default="app") + # 编辑中的 spec(agentlab.app/1),发布前随便改;发布时冻结成一个 AppVersion + draft: Mapped[dict[str, Any]] = mapped_column(default=dict) + # 草稿里的岗位、钩子、通知渠道绑定(发布时一并冻结进 AppVersion.bindings) + draft_bindings: Mapped[dict[str, Any]] = mapped_column(default=dict) + published_version: Mapped[int | None] = mapped_column(Integer, default=None) + status: Mapped[str] = mapped_column(String(20), default="active") # active | archived + created_by: Mapped[str | None] = mapped_column(String(100), default=None) + updated_by: Mapped[str | None] = mapped_column(String(100), default=None) + + +class AppVersion(Base): + __tablename__ = "app_versions" + __table_args__ = (UniqueConstraint("app_id", "version"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + app_id: Mapped[str] = mapped_column(ForeignKey("apps.id", ondelete="CASCADE"), index=True) + version: Mapped[int] = mapped_column(Integer) + spec: Mapped[dict[str, Any]] = mapped_column(default=dict) + spec_hash: Mapped[str] = mapped_column(String(64)) + # [{alias, workflow_id, version, graph_hash, level, use}],和 spec.pins 一致(冗余存一份便于反查) + pins: Mapped[list[Any]] = mapped_column(default=list) + # {"slots": {岗位: [{kind: user|group, name}]}, "hooks": {...}, "channels": {...}} + bindings: Mapped[dict[str, Any]] = mapped_column(default=dict) + level: Mapped[str] = mapped_column(String(20), default="published") # published | governed + # 钉住项相对上一个应用版本升了版时选的处置:{alias: "recompute" | "dual" | "incomparable"} + dispositions: Mapped[dict[str, Any]] = mapped_column(default=dict) + note: Mapped[str] = mapped_column(Text, default="") + published_by: Mapped[str | None] = mapped_column(String(100), default=None) + published_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) + + +class AppGrant(Base): + __tablename__ = "app_grants" + __table_args__ = (UniqueConstraint("app_id", "principal_kind", "principal", "role"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + app_id: Mapped[str] = mapped_column(ForeignKey("apps.id", ondelete="CASCADE"), index=True) + principal_kind: Mapped[str] = mapped_column(String(20)) # user | group | everyone + principal: Mapped[str] = mapped_column(String(100), default="") + role: Mapped[str] = mapped_column(String(20), default="use") + granted_by: Mapped[str | None] = mapped_column(String(100), default=None) + created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) + + +class AppViewCache(Base): + """按需视图的缓存。key = sha256(graph_hash, 规范化后的输入, data_versions, 能力版本)。""" + + __tablename__ = "app_view_cache" + + key: Mapped[str] = mapped_column(String(64), primary_key=True) + app_id: Mapped[str] = mapped_column(String(32), index=True) + view_id: Mapped[str] = mapped_column(String(100)) + run_id: Mapped[str] = mapped_column(String(32)) + created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) + expires_at: Mapped[datetime | None] = mapped_column(default=None) + + +class AppHook(Base, TimestampMixin): + """入站钩子。start:按入口发起实例;signal:按 correlation 解决一条「等外部系统」的待办。""" + + __tablename__ = "app_hooks" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + app_id: Mapped[str] = mapped_column(ForeignKey("apps.id", ondelete="CASCADE"), index=True) + name: Mapped[str] = mapped_column(String(100)) + kind: Mapped[str] = mapped_column(String(20)) # start | signal + entry_id: Mapped[str | None] = mapped_column(String(100), default=None) + secret: Mapped[str] = mapped_column(Text) # 密文 + enabled: Mapped[bool] = mapped_column(default=True) + + +class HookReceipt(Base): + """入站请求按 Idempotency-Key 去重的记录。""" + + __tablename__ = "hook_receipts" + __table_args__ = (UniqueConstraint("hook_id", "idem_key"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + hook_id: Mapped[str] = mapped_column(ForeignKey("app_hooks.id", ondelete="CASCADE"), index=True) + idem_key: Mapped[str] = mapped_column(String(200)) + run_id: Mapped[str | None] = mapped_column(String(32), default=None) + task_id: Mapped[str | None] = mapped_column(String(32), default=None) + status: Mapped[str] = mapped_column(String(20)) # accepted | rejected + detail: Mapped[str | None] = mapped_column(Text, default=None) + received_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) diff --git a/backend/app/db/models_capabilities.py b/backend/app/db/models_capabilities.py new file mode 100644 index 00000000..282db6c0 --- /dev/null +++ b/backend/app/db/models_capabilities.py @@ -0,0 +1,82 @@ +"""能力登记与登记的端点(应用平台 A6,docs/design/app-platform-and-look.md §2.6、§3.9)。 + +capabilities 一行 = 图里一个可调用的工具(主键就是图里写的工具名),分两层: +- 系统同步:内置工具、数据源、自定义工具、MCP 启动时和各自增删改时同步进来(effect_system、params_schema、 + source_hash、synced_at、missing); +- 人工治理:effect、approval、unattended_write、returns_schema、tabular、fields、masked、credential_mode、lookup、 + endpoint_id。每改一次 version 加一,运行发起时把用到的能力的治理快照固定下来(Run.options["capabilities"])。 + +endpoints 是管理员登记的外部系统:按环境(test / prod)存 base_url 和认证头(值加密)。只有登记的端点能开内网访问; +模型给出的任意地址照旧走 tools/net.py 的完整 SSRF 检查。 +""" +from __future__ import annotations + +from datetime import datetime +from typing import Any + +from sqlalchemy import Integer, String, Text +from sqlalchemy.orm import Mapped, mapped_column + +from app.db.base import Base, TimestampMixin, new_id + +#: 能力对外部世界的效果。dynamic:同一个工具看这一次的参数定(可写数据源上的 db_query__:查询只读、DML 是写) +EFFECTS = ("read", "write", "dynamic") +#: 审批:inherit 跟三档信任;confirm 总要确认;none 只读能力在正式运行里免审批 +APPROVALS = ("inherit", "confirm", "none") +#: 凭据:service 服务凭据;service_on_behalf 服务凭据 + AgentLab 签发的身份断言(不存用户自己的 token) +CREDENTIAL_MODES = ("service", "service_on_behalf") + + +class Capability(Base, TimestampMixin): + __tablename__ = "capabilities" + + name: Mapped[str] = mapped_column(String(200), primary_key=True) + # 所属系统:数据源名、端点名、MCP 服务名、builtin、custom + system: Mapped[str] = mapped_column(String(100), default="") + title: Mapped[str] = mapped_column(String(200), default="") + description: Mapped[str] = mapped_column(Text, default="") + params_schema: Mapped[dict[str, Any]] = mapped_column(default=dict) + returns_schema: Mapped[dict[str, Any] | None] = mapped_column(default=None) + # 端点返回落成表格:{"rows": "/data/items", "columns": {"单号": "/id", "金额": "/amount"}}。声明了才能作证 + tabular: Mapped[dict[str, Any] | None] = mapped_column(default=None) + # 同步时得出的效果(数据源可写为 dynamic,内置工具按 ToolSpec.dangerous,MCP 的 readOnlyHint 只当建议) + effect_system: Mapped[str] = mapped_column(String(20), default="dynamic") + # 治理后的效果;为空表示还没人确认过,按 effect_system 算 + effect: Mapped[str | None] = mapped_column(String(20), default=None) + approval: Mapped[str] = mapped_column(String(20), default="inherit") + unattended_write: Mapped[bool] = mapped_column(default=False) + # 返回字段的语义,按 JSON 指针:{"/amount": {"label": 项, "unit": 项, ...}},「项」的形状同数据目录 + # (data/catalog.py:{value, source, status, note, reason, updated_at}) + fields: Mapped[dict[str, Any]] = mapped_column(default=dict) + # 遮罩字段(JSON 指针);查看、快照、视图都按它遮 + masked: Mapped[list[Any]] = mapped_column(default=list) + credential_mode: Mapped[str] = mapped_column(String(30), default="service") + endpoint_id: Mapped[str | None] = mapped_column(String(32), default=None) + # 按幂等键查写入结果用的能力名(结果未知时自动核实) + lookup: Mapped[str | None] = mapped_column(String(200), default=None) + version: Mapped[int] = mapped_column(Integer, default=1) + source_hash: Mapped[str | None] = mapped_column(String(64), default=None) + synced_at: Mapped[datetime | None] = mapped_column(default=None) + # 来源已经删掉了(数据源、自定义工具、MCP 工具不在了)。不删行:运行和发布记录还引用它的版本 + missing: Mapped[bool] = mapped_column(default=False) + updated_by: Mapped[str | None] = mapped_column(String(100), default=None) + + +class Endpoint(Base, TimestampMixin): + """登记的外部系统。 + + environments = {"test": {...}, "prod": {...}},每个环境: + base_url、headers(值经 core/crypto 加密,接口只回掩码)、allow_intranet(只有管理员能开)、verify_tls。 + 正式运行走 prod;探索运行走 test,没有 test 时演练(不发送,记 simulated)。 + """ + + __tablename__ = "endpoints" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + name: Mapped[str] = mapped_column(String(100), unique=True) + description: Mapped[str] = mapped_column(Text, default="") + environments: Mapped[dict[str, Any]] = mapped_column(default=dict) + idempotency_header: Mapped[str] = mapped_column(String(100), default="Idempotency-Key") + timeout_s: Mapped[int] = mapped_column(Integer, default=20) + version: Mapped[int] = mapped_column(Integer, default=1) + updated_by: Mapped[str | None] = mapped_column(String(100), default=None) diff --git a/backend/app/db/models_identity.py b/backend/app/db/models_identity.py new file mode 100644 index 00000000..67a7638c --- /dev/null +++ b/backend/app/db/models_identity.py @@ -0,0 +1,97 @@ +"""身份:用户、组、会话、审计(应用平台 A7,docs/design/app-platform-and-look.md §2.7、§3.1)。 + +登录方式有三种:off(默认,今天的行为:没有登录,X-Actor 自报署名)、local(用户名 + 密码)、oidc。 +off 下这些表都是空的,任何接口都不读它们——关登录时的行为必须和加这些表之前一模一样。 + +username 一经建立就不改:各「人」列(runs.started_by、approvals.resolved_by、workflows.published_by……)开了登录 +就写它,改名会让历史记录对不上人。要换叫法改 display_name。 +""" +from __future__ import annotations + +from datetime import datetime +from typing import Any + +from sqlalchemy import ForeignKey, Index, String, Text, UniqueConstraint +from sqlalchemy.orm import Mapped, mapped_column + +from app.db.base import Base, TimestampMixin, UTCDateTime, new_id, utcnow + +#: 角色由高到低:admin ⊇ builder ⊇ user +ROLES = ("admin", "builder", "user") + + +class User(Base, TimestampMixin): + __tablename__ = "users" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + username: Mapped[str] = mapped_column(String(100), unique=True) + display_name: Mapped[str] = mapped_column(String(100), default="") + email: Mapped[str | None] = mapped_column(String(200), default=None) + role: Mapped[str] = mapped_column(String(20), default="user") + # local 模式:hashlib.scrypt 的结果(含盐和参数);OIDC 用户为空 + password_hash: Mapped[str | None] = mapped_column(Text, default=None) + oidc_issuer: Mapped[str | None] = mapped_column(String(300), default=None) + # (issuer, subject) 认一个 OIDC 用户;只看 subject 会把两个身份源里同号的人当成一个 + oidc_subject: Mapped[str | None] = mapped_column(String(200), default=None) + disabled: Mapped[bool] = mapped_column(default=False) + last_login_at: Mapped[datetime | None] = mapped_column(default=None) + created_by: Mapped[str | None] = mapped_column(String(100), default=None) + + __table_args__ = (UniqueConstraint("oidc_issuer", "oidc_subject"),) + + +class Group(Base, TimestampMixin): + """组:岗位绑定、应用授权都可以落到组上。source=oidc 的由登录时按 groups 声明同步,界面上只读。""" + + __tablename__ = "groups" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + name: Mapped[str] = mapped_column(String(100), unique=True) + label: Mapped[str] = mapped_column(String(100), default="") + source: Mapped[str] = mapped_column(String(20), default="local") # local | oidc + + +class GroupMember(Base): + __tablename__ = "group_members" + __table_args__ = (UniqueConstraint("group_id", "user_id"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + group_id: Mapped[str] = mapped_column(ForeignKey("groups.id", ondelete="CASCADE"), index=True) + user_id: Mapped[str] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True) + added_by: Mapped[str | None] = mapped_column(String(100), default=None) + created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) + + +class AuthSession(Base): + """登录会话。库里只存令牌的 sha256,令牌本身只在 HttpOnly cookie 里。""" + + __tablename__ = "auth_sessions" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + token_hash: Mapped[str] = mapped_column(String(64), unique=True) + user_id: Mapped[str] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True) + created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) + expires_at: Mapped[datetime] = mapped_column(UTCDateTime) + last_seen_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) + revoked_at: Mapped[datetime | None] = mapped_column(default=None) + ip: Mapped[str | None] = mapped_column(String(64), default=None) + user_agent: Mapped[str | None] = mapped_column(String(300), default=None) + + +class AuditEvent(Base): + """管理类操作的留痕:登录方式、角色、组、授权、应用发布、端点、能力治理、版本退役。 + + verified 记这一条的操作人是不是认证过的身份(off 模式下是自报的署名,记 False)。 + """ + + __tablename__ = "audit_events" + __table_args__ = (Index("ix_audit_events_subject", "subject_kind", "subject_id"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, index=True) + actor: Mapped[str | None] = mapped_column(String(100), default=None) + verified: Mapped[bool] = mapped_column(default=False) + action: Mapped[str] = mapped_column(String(60)) + subject_kind: Mapped[str] = mapped_column(String(40)) + subject_id: Mapped[str | None] = mapped_column(String(64), default=None) + data: Mapped[dict[str, Any]] = mapped_column(default=dict) diff --git a/backend/app/db/models_process.py b/backend/app/db/models_process.py new file mode 100644 index 00000000..cf973f24 --- /dev/null +++ b/backend/app/db/models_process.py @@ -0,0 +1,143 @@ +"""流程:待办、派给谁、生效记录、通知(应用平台 A4、A5,docs/design/app-platform-and-look.md §2.4、§2.5、§3.7、§3.8)。 + +一次中断对应一条 Approval(给引擎)和一条 Task(给人)。Task 下挂若干条 TaskAssignment:派给具体的人或组, +按 policy(any / all / quorum)汇总后才恢复运行。核实待办(kind=reconcile)没有 Approval,approval_id 为空。 + +ActionRecord 是写外部系统的权威记录:先写记录再发送;节点每次执行都先按 action_key 查,已生效的不再发, +结果未知的永不自动重发。 +""" +from __future__ import annotations + +from datetime import datetime +from typing import Any + +from sqlalchemy import ForeignKey, Index, Integer, String, Text +from sqlalchemy.orm import Mapped, mapped_column + +from app.db.base import Base, TimestampMixin, UTCDateTime, new_id, utcnow + +#: 待办的种类。人工节点三种 + 现有的几种中断 + 动作确认、核实、等外部系统 +TASK_KINDS = ("approve", "input", "edit", "tool", "code", "dual_check", "action_confirm", "reconcile", "signal") +#: pending 等人;resolving 已凑齐、正在恢复运行(条件 UPDATE 抢到的那个请求负责);resolved / cancelled / expired 终态 +TASK_STATUSES = ("pending", "resolving", "resolved", "cancelled", "expired") +#: 动作状态。simulated:探索运行里端点没有 test 环境时的演练,不发送 +ACTION_STATES = ("pending", "sent", "confirmed", "failed", "unknown", "simulated") + + +class Task(Base, TimestampMixin): + __tablename__ = "tasks" + __table_args__ = (Index("ix_tasks_status_due", "status", "due_at"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + approval_id: Mapped[str | None] = mapped_column(String(32), default=None, unique=True) + run_id: Mapped[str] = mapped_column(ForeignKey("runs.id", ondelete="CASCADE"), index=True) + node_id: Mapped[str | None] = mapped_column(String(64), default=None) + app_id: Mapped[str | None] = mapped_column(String(32), default=None, index=True) + app_version: Mapped[int | None] = mapped_column(Integer, default=None) + kind: Mapped[str] = mapped_column(String(20), default="approve") + title: Mapped[str] = mapped_column(String(300), default="") + # agentlab.form/1;没有表单的(批准 / 驳回)为空 + form: Mapped[dict[str, Any] | None] = mapped_column(default=None) + # {"kind": "any"} | {"kind": "all"} | {"kind": "quorum", "m": 2} + policy: Mapped[dict[str, Any]] = mapped_column(default=lambda: {"kind": "any"}) + status: Mapped[str] = mapped_column(String(20), default="pending", index=True) + due_at: Mapped[datetime | None] = mapped_column(default=None) + remind_at: Mapped[datetime | None] = mapped_column(default=None) + # {"action": "remind" | "escalate" | "reject", "every"?: ISO 时长, "to_slot"?: 岗位}。没有「自动批准」 + on_timeout: Mapped[dict[str, Any] | None] = mapped_column(default=None) + escalation_level: Mapped[int] = mapped_column(Integer, default=0) + # 等外部系统(kind=signal)时,入站 signal 按它找到这条待办 + correlation_key: Mapped[str | None] = mapped_column(String(200), default=None, index=True) + # 判定结果:{"decision": ..., "values": ..., "signoffs": [...]} + outcome: Mapped[dict[str, Any] | None] = mapped_column(default=None) + resolved_by: Mapped[str | None] = mapped_column(String(100), default=None) + resolved_at: Mapped[datetime | None] = mapped_column(default=None) + + +class TaskAssignment(Base): + __tablename__ = "task_assignments" + __table_args__ = (Index("ix_assign_principal", "principal_kind", "principal", "status"),) + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + task_id: Mapped[str] = mapped_column(ForeignKey("tasks.id", ondelete="CASCADE"), index=True) + principal_kind: Mapped[str] = mapped_column(String(20)) # user | group | anyone | hook + principal: Mapped[str] = mapped_column(String(100), default="") + # 从哪来:slot:<岗位> | initiator | expression | escalation | reassign + source: Mapped[str] = mapped_column(String(40), default="") + status: Mapped[str] = mapped_column(String(20), default="pending") # pending | responded | withdrawn + response: Mapped[dict[str, Any] | None] = mapped_column(default=None) + responded_by: Mapped[str | None] = mapped_column(String(100), default=None) + responded_at: Mapped[datetime | None] = mapped_column(default=None) + # 回复人是不是认证过的身份(off 模式下是自报署名,记 False) + verified: Mapped[bool] = mapped_column(default=False) + created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) + + +class ActionRecord(Base, TimestampMixin): + __tablename__ = "action_records" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + # sha256(run_id, node_id, exec);同一次执行第 n 次发送的幂等键是 f"{action_key}:{attempt}" + action_key: Mapped[str] = mapped_column(String(64), index=True) + attempt: Mapped[int] = mapped_column(Integer, default=1) + idem_key: Mapped[str] = mapped_column(String(80), unique=True) + run_id: Mapped[str] = mapped_column(ForeignKey("runs.id", ondelete="CASCADE"), index=True) + node_id: Mapped[str] = mapped_column(String(64)) + exec_no: Mapped[int] = mapped_column(Integer, default=1) + app_id: Mapped[str | None] = mapped_column(String(32), default=None, index=True) + workflow_id: Mapped[str | None] = mapped_column(String(32), default=None, index=True) + workflow_version: Mapped[int | None] = mapped_column(Integer, default=None) + graph_hash: Mapped[str | None] = mapped_column(String(64), default=None) + capability: Mapped[str] = mapped_column(String(200)) + capability_version: Mapped[int | None] = mapped_column(Integer, default=None) + endpoint_id: Mapped[str | None] = mapped_column(String(32), default=None) + environment: Mapped[str] = mapped_column(String(20), default="prod") # prod | test | simulated + payload_hash: Mapped[str] = mapped_column(String(64)) + # 遮罩后的预览(确认卡上给人看的那一份) + preview: Mapped[dict[str, Any] | None] = mapped_column(default=None) + state: Mapped[str] = mapped_column(String(20), default="pending", index=True) + confirm_task_id: Mapped[str | None] = mapped_column(String(32), default=None) + request_at: Mapped[datetime | None] = mapped_column(default=None) + response_status: Mapped[int | None] = mapped_column(Integer, default=None) + # 回执:外部单号等,原文落工件,这里存 {artifact, summary} + receipt: Mapped[dict[str, Any] | None] = mapped_column(default=None) + error: Mapped[str | None] = mapped_column(Text, default=None) + lookup_attempts: Mapped[int] = mapped_column(Integer, default=0) + next_lookup_at: Mapped[datetime | None] = mapped_column(default=None) + # 核实结论:{"by": ..., "how": "lookup" | "manual", "outcome": "confirmed" | "not_applied" | "resend" | "abandon", "external_id"?} + resolution: Mapped[dict[str, Any] | None] = mapped_column(default=None) + + +class NotifyChannel(Base, TimestampMixin): + """通知渠道。格式、签名、发送同定时任务的 Webhook(四种:generic / feishu / wecom / dingtalk)。""" + + __tablename__ = "notify_channels" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + name: Mapped[str] = mapped_column(String(100)) + scope: Mapped[str] = mapped_column(String(20), default="global") # global | app | user + owner_id: Mapped[str | None] = mapped_column(String(32), default=None) + format: Mapped[str] = mapped_column(String(20), default="generic") + url: Mapped[str] = mapped_column(Text) # 密文 + secret: Mapped[str | None] = mapped_column(Text, default=None) # 密文 + events: Mapped[list[Any]] = mapped_column(default=list) + enabled: Mapped[bool] = mapped_column(default=True) + + +class NotifyDelivery(Base): + """通用投递记录。定时任务的投递仍写 webhook_deliveries(schedule_id 非空,SQLite 改不了可空性)。""" + + __tablename__ = "notify_deliveries" + + id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) + channel_id: Mapped[str] = mapped_column(ForeignKey("notify_channels.id", ondelete="CASCADE"), index=True) + subject_kind: Mapped[str] = mapped_column(String(20)) # task | run | action + subject_id: Mapped[str] = mapped_column(String(32)) + event: Mapped[str] = mapped_column(String(40)) + run_id: Mapped[str | None] = mapped_column(String(32), default=None) + task_id: Mapped[str | None] = mapped_column(String(32), default=None) + status: Mapped[str] = mapped_column(String(20)) + http_status: Mapped[int | None] = mapped_column(Integer, default=None) + attempts: Mapped[int] = mapped_column(Integer, default=0) + error: Mapped[str | None] = mapped_column(Text, default=None) + created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow) diff --git a/backend/app/engine/governance.py b/backend/app/engine/governance.py index 79dab048..53ca06fe 100644 --- a/backend/app/engine/governance.py +++ b/backend/app/engine/governance.py @@ -29,6 +29,23 @@ UPGRADE_POLICIES = {"recompute", "dual", "incomparable"} UPGRADE_POLICY_LABELS = {k: option_label("upgrade_policy", k) for k in ("recompute", "dual", "incomparable")} +#: 发布门禁的扩展检查(应用平台 §3.13):各包把自己的检查登记在这里,不改下面的主循环。 +#: 每个检查的签名:check(spec, flag, *, level, strict) -> None,flag 同 lint_for_publish 里的那个 +#: (message, code=, node_id=, hard=, field=)。登记见 engine/lint_process.py、engine/lint_capabilities.py +EXTRA_LINTS: list[Callable[..., None]] = [] + + +def _load_extra_lints() -> None: + """导入各包的检查模块(它们导入时把自己登记进 EXTRA_LINTS)。还没建的模块跳过。""" + import importlib + + for name in ("app.engine.lint_process", "app.engine.lint_capabilities"): + try: + importlib.import_module(name) + except ModuleNotFoundError as e: + if e.name != name: + raise + def lint_for_publish(spec: GraphSpec, *, level: str, checkers: Mapping[str, Any] | None = None, providers: list[Any] | None = None) -> ValidationResult: @@ -110,6 +127,9 @@ def lint_for_publish(spec: GraphSpec, *, level: str, checkers: Mapping[str, Any] _lint_evidence(spec, flag, strict=strict) _lint_sql(spec, flag, checkers) + _load_extra_lints() + for check in EXTRA_LINTS: + check(spec, flag, level=level, strict=strict) if providers is not None: from app.engine.provider_refs import issues as provider_issues diff --git a/backend/app/engine/origin.py b/backend/app/engine/origin.py new file mode 100644 index 00000000..ed18efb6 --- /dev/null +++ b/backend/app/engine/origin.py @@ -0,0 +1,36 @@ +"""运行来源:这次运行从哪里发起(docs/design/app-platform-and-look.md §2.10 X3)。 + +以前运行表上只有 schedule_id:问数据和画布试跑都是「裸图 + 探索」,分不出来;应用发起的运行更无从说起。 +来源由 launch_run(origin=…) 写进 Run.origin_kind / Run.origin,同时作为 run.origin 事件放进 notes——发起时就定下、 +在封存范围内,事后改不了。 + +客户端(POST /api/runs)只能声明 CLIENT_ORIGINS 里的几种;app_*、hook、schedule 只能由服务端写,客户端声明一律拒绝: +否则谁都能把一次画布试跑说成「应用入口发起的」。 +""" +from __future__ import annotations + +from typing import Any + +#: 全部来源。顺序即界面上筛选的顺序 +ORIGIN_KINDS = ( + "chat", # 问数据 + "canvas", # 画布试跑 + "launcher", # 正式运行(手动,画布或版本页上的「正式运行」) + "schedule", # 定时任务 + "app_entry", # 应用入口 + "app_view", # 应用视图(按需运行) + "app_backfill", # 钉住项按 recompute 升版后,按历次触发的输入补算 + "hook", # 外部系统经入站钩子触发 + "api", # 直接调接口,没说是哪 +) + +#: 客户端在 POST /api/runs 里能声明的来源 +CLIENT_ORIGINS = ("chat", "canvas", "launcher", "api") + + +def origin_note(kind: str, **data: Any) -> dict[str, Any]: + """run.origin 事件的数据:kind 加上调用方给的字段(app_id、app_version、spec_hash、entry / view、hook、 + actor、actor_verified、auth_mode……),值为 None 的不写。""" + if kind not in ORIGIN_KINDS: + raise ValueError(f"不认识的运行来源:{kind}") + return {"kind": kind, **{k: v for k, v in data.items() if v is not None}} diff --git a/backend/app/look/__init__.py b/backend/app/look/__init__.py new file mode 100644 index 00000000..de6b99ad --- /dev/null +++ b/backend/app/look/__init__.py @@ -0,0 +1,8 @@ +"""助手按需查看(look 文档第二部分 + 总方案 L1–L4,docs/design/app-platform-and-look.md 第五部分)。BE-4 实现。 + +- base.py LookKind 接口、targets / 记录的形状、上限常量、生成过程的注入接口(Applier / Checker) +- tables.py 表(库概览、表目录、表详情,含遮罩;与 db_schema__、/schema 共用 data/schema_view.py) +- capabilities.py 能力(只给操作名、参数、返回字段、读写、要不要确认;不给地址和凭据) +- versions.py 工作流版本(应用润色时看钉住的版本;app/apps/describe.py) +- service.py 解析 targets、按类型挑选、交回目录、字数上限、重复查看短路、产出记录 +""" diff --git a/backend/app/look/base.py b/backend/app/look/base.py new file mode 100644 index 00000000..62b7e134 --- /dev/null +++ b/backend/app/look/base.py @@ -0,0 +1,100 @@ +"""查看的接口与形状(L2、L3),以及生成过程的注入接口(L1)。前端解码(run/decode.ts)按这里的形状认 look 事件。 + +look 行(模型输出): + {"op":"look","need":"…","targets":[{"kind":"table","source":"库 B","name":"refunds"}],"sources":["库 B"]} + 旧写法 tables:[{source, table}] 也认,读进来换成 targets(kind=table)。 + +look 事件(发给前端、存进 meta.looks): + {"op":"look","id":"L1","by":"model"|"system","need":"…","status":"ok"|"index"|"failed","reason"?, + "elapsed_ms":…,"objects":[{"kind":"table","source":…,"source_id":…,"named":[…],"picked":[…],"joined":[…], + "missing":[…],"total":…,"explored"?:…,"catalog_tables":…,"schema_synced_at":…,"catalog_versions":{…}}, + {"kind":"capability","named":[…],"missing":[…],"versions":{…}}, + {"kind":"workflow_version","named":[…],"missing":[…]}]} +""" +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Any, Protocol, TypedDict + +#: 这一版实现的对象类型(口径以后再加:账本先做实验,look §3.8) +LOOK_KINDS = ("table", "capability", "workflow_version") + +LOOK_LIMIT = 3 # 起草阶段每轮最多查看几次 +REPAIR_LOOK_LIMIT = 1 # 自查修正阶段另给几次 +LOOK_RESULT_CHARS = 12_000 # 一次查看结果的字数上限 +PICK_LIMIT = 12 # 挑选最多挑几个;候选不超过这个数时不挑、全给(沿用) +CONTEXT_TABLE_LIMIT = 16 # 一次查看最多给几张表的详情(含中间表,沿用) +PICK_TIMEOUT_S = 20 # 挑选时限(沿用) + + +class LookTarget(TypedDict, total=False): + kind: str # LOOK_KINDS 之一 + source: str # 表:库名;能力:所属系统;工作流版本:工作流名 + name: str # 表名 / 能力名 / "v3" + + +@dataclass +class LookResult: + text: str + record: dict[str, Any] + + +class LookKind(Protocol): + """每种可查看的对象都实现同一组方法(L3)。遮罩按类型各自处理。""" + + kind: str + + async def overview(self) -> list[str]: + """概览:进 system,每个来源一行。""" + ... + + async def index(self, sources: list[str] | None) -> str: + """目录:挑选失败时交回,每个对象一行。""" + ... + + async def resolve(self, targets: list[LookTarget]) -> tuple[list[Any], list[LookTarget]]: + """按点名解析:(认出的对象, 没找到的点名)。""" + ... + + async def pick(self, need: str, sources: list[str] | None) -> tuple[list[Any], str | None]: + """按需求挑选:(挑出的对象, 失败原因)。返回空列表且原因为 None 表示「按这个需求没有相关的」。""" + ... + + async def detail(self, objects: list[Any], budget: int) -> tuple[str, dict[str, Any]]: + """详情文字(受字数上限约束)和这一类的记录块(objects[] 里的一项)。""" + ... + + +# ---- 生成过程的注入接口(L1):循环只管「读到 look 停下、执行、接着写、计次数」,落地和自查由调用方注入 ---- + + +@dataclass +class Applied: + changed: bool + forward: bool = True + problem: str | None = None + + +class Applier(Protocol): + def apply(self, op: dict[str, Any]) -> Applied: ... + + def landed(self) -> list[str]: + """已经落地的对象 id(接着写的提示里列出来,提醒模型不要重复)。""" + ... + + def continuing(self) -> None: + """进入「接着写」:之后和已落地完全相同的操作忽略、不转发(look §2.5.5)。""" + ... + + +class Checker(Protocol): + async def issues(self) -> list[dict[str, Any]]: ... + + def repair_request(self, issues: list[dict[str, Any]], looks_text: str) -> str: ... + + +@dataclass +class LookBudget: + limit: int = LOOK_LIMIT + used: int = 0 + seen: set[str] = field(default_factory=set) diff --git a/backend/app/main.py b/backend/app/main.py index ba7dade7..ed539576 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -12,6 +12,12 @@ from app.api import ( artifacts, bundle, catalog, compare, conversations, copilot, datasources, evidence, governance, inquiry, knowledge, runs, sandbox, schedules, settings as settings_api, source_versions, table_imports, tools, whatif, workflows, ) +# 应用平台(docs/design/app-platform-and-look.md)。权限按 §3.12 在这里挂路由级依赖(api/deps.require_role), +# 关登录时全部放行 +from app.api import ( + actions as actions_api, apps as apps_api, auth as auth_api, capabilities as capabilities_api, hooks as hooks_api, + identity as identity_api, ledger as ledger_api, notify as notify_api, tasks as tasks_api, +) from app.api.coded import CodedHTTPException, coded_handler from app.core.config import settings from app.db.base import init_db @@ -147,6 +153,16 @@ for router in ( source_versions.router, catalog.router, datasources.router, + # 应用平台 + auth_api.router, + identity_api.router, + capabilities_api.router, + apps_api.router, + tasks_api.router, + actions_api.router, + hooks_api.router, + notify_api.router, + ledger_api.router, ): app.include_router(router) diff --git a/backend/app/notify/__init__.py b/backend/app/notify/__init__.py new file mode 100644 index 00000000..64ab1e09 --- /dev/null +++ b/backend/app/notify/__init__.py @@ -0,0 +1,10 @@ +"""通知的发送核心(附录 C,BE-2 提供)。从 scheduler/webhook.py 抽出:四种格式、签名、发送、脱敏; +webhook.py 照原名再导出,定时任务的通知存储不迁移(F14)。新对象(待办、实例、动作)写 notify_deliveries。""" +from __future__ import annotations + +from typing import Any + + +async def send(channel: Any, message: dict[str, Any]) -> Any: + """按渠道的格式发一条通知。message = {title, status, lines: [...], links: [(文字, 地址)]},不含报告里的具体数字。""" + raise NotImplementedError("BE-2") diff --git a/backend/app/process/__init__.py b/backend/app/process/__init__.py new file mode 100644 index 00000000..c77618f6 --- /dev/null +++ b/backend/app/process/__init__.py @@ -0,0 +1 @@ +"""流程:待办、动作、入站钩子(A4、A5,docs/design/app-platform-and-look.md §2.4、§2.5、§3.7、§3.8)。BE-2 实现。""" diff --git a/backend/app/process/actions.py b/backend/app/process/actions.py new file mode 100644 index 00000000..0aa29b10 --- /dev/null +++ b/backend/app/process/actions.py @@ -0,0 +1,31 @@ +"""动作服务:写外部系统(附录 C,BE-2 提供)。ActionRecord 是权威记录:先写记录再发送,结果未知永不自动重发。""" +from __future__ import annotations + +from datetime import datetime +from typing import Any + + +class ActionPending(Exception): + """写入的结果未知(或已发出、等核实)。runner 把运行收成 interrupted(挂起,不封存),等核实后接着跑。""" + + def __init__(self, action_id: str, message: str = "写入的结果未知,等待核实") -> None: + super().__init__(message) + self.action_id = action_id + + +def action_key(run_id: str, node_id: str, exec_no: int) -> str: + """sha256(run_id, node_id, exec)。同一次执行第 n 次发送的幂等键是 f"{action_key}:{attempt}"。""" + import hashlib + + return hashlib.sha256(f"{run_id}\x1f{node_id}\x1f{exec_no}".encode()).hexdigest() + + +async def reconcile(action_id: str, principal: Any, *, outcome: str, external_id: str | None = None, + note: str | None = None) -> dict[str, Any]: + """核实:outcome ∈ confirmed | not_applied_resend | not_applied_abandon。核实后系统自动接着跑。""" + raise NotImplementedError("BE-2") + + +async def tick(now: datetime | None = None) -> int: + """调度循环每一拍:对登记了 lookup 的结果未知动作带退避地查询。""" + raise NotImplementedError("BE-2") diff --git a/backend/app/process/hooks.py b/backend/app/process/hooks.py new file mode 100644 index 00000000..86aa8677 --- /dev/null +++ b/backend/app/process/hooks.py @@ -0,0 +1,28 @@ +"""入站签名钩子(附录 C,BE-2 提供)。签名同出站通用格式:HMAC-SHA256(f"{ts}." + body),时间窗 5 分钟, +Idempotency-Key 去重。start 按入口发起实例;signal 按 correlation 解决一条「等外部系统」的待办。""" +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + +#: 签名时间窗(秒) +WINDOW_S = 300 + + +@dataclass(frozen=True) +class HookRequest: + hook_id: str + kind: str + idem_key: str + payload: dict[str, Any] + + +class HookRejected(Exception): + def __init__(self, message: str, *, status_code: int = 401) -> None: + super().__init__(message) + self.status_code = status_code + + +def verify(secret: str, headers: dict[str, str], body: bytes) -> None: + """签名不对、时间窗外抛 HookRejected。""" + raise NotImplementedError("BE-2") diff --git a/backend/app/process/tasks.py b/backend/app/process/tasks.py new file mode 100644 index 00000000..54a0a61c --- /dev/null +++ b/backend/app/process/tasks.py @@ -0,0 +1,40 @@ +"""待办服务(附录 C,BE-2 提供)。 + +一次中断对应一条 Approval(给引擎)和一条 Task(给人)。所有人的决定都经 respond:按 policy 汇总,凑齐后在同一个 +事务里用条件 UPDATE 把 Task 从 pending 改成 resolving,抢到的请求负责调 run_manager.resume。引擎和重放都不改。 +""" +from __future__ import annotations + +from datetime import datetime +from typing import Any + +from sqlalchemy.ext.asyncio import AsyncSession + + +class TaskRefused(Exception): + """回复不被接受:不是派给你的、已经处理过了、哈希对不上……status_code 照 HTTP 语义(403 / 409 / 422)。""" + + def __init__(self, message: str, *, status_code: int = 409, code: str | None = None) -> None: + super().__init__(message) + self.status_code = status_code + self.code = code + + +async def open_task(session: AsyncSession, approval: Any) -> Any: + """为一条新的 Approval 建 Task 和派给谁(按人工节点配置 + 应用版本的岗位绑定)。runner._handle_updates 调。""" + raise NotImplementedError("BE-2") + + +async def respond(task_id: str, principal: Any, *, decision: Any, values: dict[str, Any] | None = None, + note: str | None = None, payload_hash: str | None = None) -> dict[str, Any]: + """一个人的回复。返回 {task, resolved: bool, run?}。""" + raise NotImplementedError("BE-2") + + +async def reassign(task_id: str, principal: Any, *, to: list[dict[str, str]], note: str | None = None) -> Any: + raise NotImplementedError("BE-2") + + +async def tick(now: datetime | None = None) -> int: + """调度循环每一拍:提醒、升级、超时驳回(永不自动批准)。返回处理的条数。""" + raise NotImplementedError("BE-2") diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 1f1c2d2c..dddfb205 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -20,6 +20,14 @@ import { KnowledgePage } from './pages/KnowledgePage' import { SettingsPage } from './pages/SettingsPage' import { SchedulesPage } from './pages/schedules/SchedulesPage' import { NotFound } from './pages/NotFound' +// 应用平台:使用面(FE-5)、搭建面的应用编辑(FE-6) +import { AppsHome } from './pages/apps/AppsHome' +import { AppPage } from './pages/apps/AppPage' +import { EntryPage } from './pages/apps/EntryPage' +import { InstancePage } from './pages/apps/InstancePage' +import { TaskPage } from './pages/apps/TaskPage' +import { AppEditor } from './pages/apps/edit/AppEditor' +import { LoginPage } from './pages/LoginPage' import { Logo } from './components/Logo' import { CommandPalette, PAGES, ShortcutHelp, flushThemePref, openShortcutHelp, toggleCommandPalette, toggleNotify, @@ -121,6 +129,16 @@ export default function App() { } /> } /> } /> + {/* 应用:固定路径(inbox)写在 /apps/:appId 前面,读的人一眼看出它不是应用 id */} + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> {/* 数据源搬到了顶级「数据」页;旧书签和各处「去设置 → 数据源」的链接还在 */} } /> } /> diff --git a/frontend/src/api/apps.ts b/frontend/src/api/apps.ts new file mode 100644 index 00000000..d61c7938 --- /dev/null +++ b/frontend/src/api/apps.ts @@ -0,0 +1,55 @@ +/** + * 应用的接口(/api/apps、/api/ledger),挂在 api.apps 上。形状见 typesApp.ts(应用平台的接口约定)。 + * + * 请求函数从 ./http 导入,不要从 ./client 导入(循环导入,见 http.ts 开头)。 + * 入口提交校验失败回 422,ApiError 的 body 里带 {errors: FormError[]}。 + */ +import type { + AppBindings, AppDetail, AppGrant, AppSpec, AppSummary, AppVersionRow, ComponentCatalog, Disposition, InstanceRow, + LintIssue, PublishResult, ViewModel, +} from '../typesApp' +import { get, patch, post, put, qs, type RequestOptions } from './http' + +const at = (id: string) => `/apps/${encodeURIComponent(id)}` + +export const apps = { + catalog: (opts?: RequestOptions) => get('/apps/catalog', opts), + list: (opts?: RequestOptions) => get<{ items: AppSummary[] }>('/apps', opts), + get: (id: string, opts?: RequestOptions) => get(at(id), opts), + create: (body: { name: string; description?: string; spec?: AppSpec }) => post('/apps', body), + /** 从工作流版本确定性派生一份应用草稿(不落库),编辑器拿去预览 / 新建 */ + derive: (body: { workflow_id: string; version: number; name?: string }) => + post<{ spec: AppSpec }>('/apps/derive', body), + /** 改草稿:spec、岗位绑定、名称等,只带改了的字段 */ + update: (id: string, body: { name?: string; description?: string; icon?: string; draft?: AppSpec; + draft_bindings?: AppBindings }) => patch(at(id), body), + archive: (id: string) => post(`${at(id)}/archive`), + lint: (id: string) => post<{ issues: LintIssue[]; level: string | null }>(`${at(id)}/lint`), + publish: (id: string, body: { note?: string; dispositions?: Record }) => + post(`${at(id)}/publish`, body), + versions: (id: string) => get<{ items: AppVersionRow[] }>(`${at(id)}/versions`), + version: (id: string, v: number) => get(`${at(id)}/versions/${v}`), + grants: (id: string) => get<{ items: AppGrant[] }>(`${at(id)}/grants`), + setGrants: (id: string, items: AppGrant[]) => put<{ items: AppGrant[] }>(`${at(id)}/grants`, { items }), + /** 页面解析:服务端解析好的视图模型(不可见的组件不下发,遮罩值不出服务端) */ + page: (id: string, page: string, params?: { instance?: string; params?: Record }, opts?: RequestOptions) => + get(`${at(id)}/pages/${encodeURIComponent(page)}${qs({ + instance: params?.instance, params: params?.params ? JSON.stringify(params.params) : undefined, + })}`, opts), + /** 发起一个实例 */ + start: (id: string, entry: string, values: Record) => + post<{ run_id: string; title: string }>(`${at(id)}/entries/${encodeURIComponent(entry)}`, { values }), + instances: (id: string, params?: { who?: 'mine' | 'all'; entry?: string; status?: string; limit?: number }) => + get<{ items: InstanceRow[] }>(`${at(id)}/instances${qs(params)}`), + instance: (id: string, runId: string) => get(`${at(id)}/instances/${encodeURIComponent(runId)}`), + /** 按需视图:发起一次运行(或命中缓存) */ + refreshView: (id: string, view: string, params?: Record) => + post<{ run_id: string; cached: boolean }>(`${at(id)}/views/${encodeURIComponent(view)}/refresh`, { params: params ?? {} }), +} + +export const ledger = { + /** 一个工作流版本被哪些应用钉住、生效记录数、正式运行数 */ + version: (workflowId: string, version: number) => + get<{ apps: { app_id: string; name: string; app_version: number }[]; effects: number; formal_runs: number }>( + `/ledger/workflow-versions/${encodeURIComponent(workflowId)}/${version}`), +} diff --git a/frontend/src/api/auth.ts b/frontend/src/api/auth.ts new file mode 100644 index 00000000..95ad3125 --- /dev/null +++ b/frontend/src/api/auth.ts @@ -0,0 +1,32 @@ +/** + * 身份的接口(/api/auth、/api/users、/api/groups、/api/audit),挂在 api.auth / api.identity 上。形状见 typesApp.ts。 + * 开登录时:没登录的请求回 401(前端跳 /login),角色不够回 403。关登录时 /me 恒为 mode='off'。 + */ +import type { AuditRow, AuthMode, GroupRow, Principal, Role, UserRow } from '../typesApp' +import { del, get, patch, post, put, qs, type RequestOptions } from './http' + +export const auth = { + me: (opts?: RequestOptions) => get('/auth/me', opts), + login: (body: { username: string; password: string }) => post('/auth/login', body), + logout: () => post('/auth/logout'), + /** OIDC:浏览器整页跳转到这里 */ + oidcStartUrl: (next?: string) => `/api/auth/oidc/start${qs({ next })}`, + settings: () => get<{ mode: AuthMode; env_locked: boolean; oidc: Record; user_can_chat: boolean }>( + '/auth/settings'), + saveSettings: (body: { mode?: AuthMode; oidc?: Record; user_can_chat?: boolean; + bootstrap?: { username: string; password: string; display_name?: string } }) => put('/auth/settings', body), +} + +export const identity = { + users: () => get<{ items: UserRow[] }>('/users'), + createUser: (body: { username: string; display_name?: string; email?: string; role: Role; password?: string }) => + post('/users', body), + updateUser: (id: string, body: { display_name?: string; email?: string; role?: Role; disabled?: boolean; + password?: string }) => patch(`/users/${encodeURIComponent(id)}`, body), + groups: () => get<{ items: GroupRow[] }>('/groups'), + createGroup: (body: { name: string; label?: string }) => post('/groups', body), + setMembers: (id: string, members: string[]) => put(`/groups/${encodeURIComponent(id)}/members`, { members }), + deleteGroup: (id: string) => del(`/groups/${encodeURIComponent(id)}`), + audit: (params?: { subject_kind?: string; subject_id?: string; limit?: number }) => + get<{ items: AuditRow[] }>(`/audit${qs(params)}`), +} diff --git a/frontend/src/api/capabilities.ts b/frontend/src/api/capabilities.ts new file mode 100644 index 00000000..b0a9e676 --- /dev/null +++ b/frontend/src/api/capabilities.ts @@ -0,0 +1,37 @@ +/** + * 能力登记、端点、通知渠道的接口(/api/capabilities、/api/endpoints、/api/notify),挂在 api.capabilities / + * api.endpoints / api.notify 上。形状见 typesApp.ts。端点和渠道的密钥只回掩码;提交掩码值表示保持原值。 + */ +import type { CapabilityRow, EndpointRow, NotifyChannelRow } from '../typesApp' +import { del, get, patch, post, put, qs, type RequestOptions } from './http' + +export const capabilities = { + list: (params?: { system?: string; effect?: string; q?: string }, opts?: RequestOptions) => + get<{ items: CapabilityRow[] }>(`/capabilities${qs(params)}`, opts), + get: (name: string) => get(`/capabilities/${encodeURIComponent(name)}`), + /** 改治理字段(effect / approval / unattended_write / returns_schema / tabular / fields / masked / + * credential_mode / endpoint_id / lookup),带上读到的 version 做乐观锁 */ + govern: (name: string, body: Partial & { version: number }) => + put(`/capabilities/${encodeURIComponent(name)}/governance`, body), + sync: () => post<{ changed: number }>('/capabilities/sync'), +} + +export const endpoints = { + list: () => get<{ items: EndpointRow[] }>('/endpoints'), + create: (body: Omit) => post('/endpoints', body), + update: (id: string, body: Partial & { version: number }) => + patch(`/endpoints/${encodeURIComponent(id)}`, body), + remove: (id: string) => del(`/endpoints/${encodeURIComponent(id)}`), + test: (id: string, env: 'test' | 'prod') => + post<{ ok: boolean; status: number | null; message: string }>(`/endpoints/${encodeURIComponent(id)}/test${qs({ env })}`), +} + +export const notify = { + channels: () => get<{ items: NotifyChannelRow[] }>('/notify/channels'), + createChannel: (body: { name: string; scope: string; owner_id?: string | null; format: string; url: string; + secret?: string | null; events: string[] }) => post('/notify/channels', body), + updateChannel: (id: string, body: Record) => patch(`/notify/channels/${encodeURIComponent(id)}`, body), + removeChannel: (id: string) => del(`/notify/channels/${encodeURIComponent(id)}`), + testChannel: (id: string) => post<{ ok: boolean; message: string }>(`/notify/channels/${encodeURIComponent(id)}/test`), + deliveries: (params?: { channel_id?: string; limit?: number }) => get<{ items: any[] }>(`/notify/deliveries${qs(params)}`), +} diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 6827f719..3e40b162 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -23,6 +23,11 @@ import { inquiry } from './inquiry' import { schedules } from './schedules' import { whatif } from './whatif' import { reportExport } from './reportExport' +// 应用平台:各自的接口文件,这里只挂上去 +import { apps, ledger } from './apps' +import { actions, tasks } from './tasks' +import { auth, identity } from './auth' +import { capabilities, endpoints, notify } from './capabilities' // 请求层搬到了 http.ts(见那边的说明)。原先从这里导出的照旧从这里导出,调用方不用改; // 请求函数也一并转出,给不在 api/ 下、又想直接发请求的地方用。api/ 下的命名空间文件请直接从 http.ts 导入 @@ -832,6 +837,17 @@ export const api = { inquiry, whatif, reportExport, + + // ---- 应用平台(typesApp.ts 是接口约定) ---- + apps, + ledger, + tasks, + actions, + auth, + identity, + capabilities, + endpoints, + notify, } /** diff --git a/frontend/src/api/tasks.ts b/frontend/src/api/tasks.ts new file mode 100644 index 00000000..f49a879c --- /dev/null +++ b/frontend/src/api/tasks.ts @@ -0,0 +1,26 @@ +/** + * 待办与生效记录的接口(/api/tasks、/api/actions),挂在 api.tasks / api.actions 上。形状见 typesApp.ts。 + * 回复被拒(不是派给你的、已处理过、哈希对不上)回 403 / 409 / 422,ApiError.message 是服务端的中文说明。 + */ +import type { ActionRecordRow, Task, TaskRespond } from '../typesApp' +import { get, post, qs, type RequestOptions } from './http' + +const at = (id: string) => `/tasks/${encodeURIComponent(id)}` + +export const tasks = { + list: (params?: { assigned?: 'me' | 'all'; status?: string; app_id?: string; run_id?: string; limit?: number }, + opts?: RequestOptions) => get<{ items: Task[] }>(`/tasks${qs(params)}`, opts), + /** 导航徽标:派给我的、待处理的待办数(按来源分:应用里的 / 不属于应用的) */ + count: (opts?: RequestOptions) => get<{ mine: number; apps: number; other: number }>('/tasks/count?mine=1', opts), + get: (id: string, opts?: RequestOptions) => get(at(id), opts), + respond: (id: string, body: TaskRespond) => post<{ task: Task; resolved: boolean }>(`${at(id)}/respond`, body), + reassign: (id: string, body: { to: { kind: 'user' | 'group'; name: string }[]; note?: string }) => + post(`${at(id)}/reassign`, body), + remind: (id: string) => post<{ sent: number }>(`${at(id)}/remind`), +} + +export const actions = { + list: (params?: { run_id?: string; app_id?: string; state?: string; limit?: number }) => + get<{ items: ActionRecordRow[] }>(`/actions${qs(params)}`), + get: (id: string) => get(`/actions/${encodeURIComponent(id)}`), +} diff --git a/frontend/src/components/SchemaForm.tsx b/frontend/src/components/SchemaForm.tsx new file mode 100644 index 00000000..5cb674ad --- /dev/null +++ b/frontend/src/components/SchemaForm.tsx @@ -0,0 +1,48 @@ +/** + * 表单渲染器:agentlab.form/1(应用平台 §3.3,X2「只有一个表单渲染器」)。 + * + * 用在四处:画布和版本页的发起表单(替换 RunControl 的 FieldsForm)、人工节点、待办、应用入口。 + * 前端只校验目录规定的子集(lib/schemaForm.ts),后端复核、以后端为准;两边的错误格式都是 {path, code, message}。 + * + * 契约骨架里的最简实现:每个字段一个文本框。控件、校验、错误展示由 FE-5 补齐,props 不变。 + */ +import type { FormError, FormSchema } from '../typesApp' + +export interface SchemaFormProps { + schema: FormSchema + value: Record + onChange: (value: Record) => void + /** 服务端(422)或本地校验出的错误,按 path 挂到字段下面 */ + errors?: FormError[] + readOnly?: boolean + /** Mod+Enter 提交 */ + onSubmit?: () => void + /** 控件 id 的前缀,同一页有多份表单时避免撞 id */ + idPrefix?: string +} + +export function SchemaForm({ schema, value, onChange, errors, readOnly, idPrefix = 'sf' }: SchemaFormProps) { + const order = schema['x-order'] ?? Object.keys(schema.properties) + return ( +
+ {order.filter((k) => schema.properties[k]).map((key) => { + const field = schema.properties[key] + const id = `${idPrefix}-${key}` + const error = errors?.find((e) => e.path === key) + return ( +
+ + onChange({ ...value, [key]: e.target.value })} + /> + {error &&

{error.message}

} +
+ ) + })} +
+ ) +} diff --git a/frontend/src/lib/terms.ts b/frontend/src/lib/terms.ts index 2d6d030b..b16c6b43 100644 --- a/frontend/src/lib/terms.ts +++ b/frontend/src/lib/terms.ts @@ -4869,3 +4869,6 @@ export const VERIFY_SETTING_TEXT = { saveInvalid: '核查设置中有无效值,请修正后再保存', }, } + +// 应用平台使用面的文案(FE-5 维护)。调用方照旧从 lib/terms 导入 +export * from './termsApp' diff --git a/frontend/src/lib/termsApp.ts b/frontend/src/lib/termsApp.ts new file mode 100644 index 00000000..e62b8c5d --- /dev/null +++ b/frontend/src/lib/termsApp.ts @@ -0,0 +1,12 @@ +/** + * 应用平台使用面的文案(应用首页、应用页、发起、实例、待办、登录)。规矩同 terms.ts 开头的术语表: + * 「固定版本」不写钉住;「运行」不写跑;「服务端」不写后端;批准 / 驳回;…… + * + * terms.ts 末尾 `export * from './termsApp'`:调用方照旧从 lib/terms 导入。搭建面的文案写在 terms.ts。 + */ + +export const APP_TEXT = { + nav: '应用', + title: '应用', + pending: '这一页正在建设', +} diff --git a/frontend/src/pages/LoginPage.tsx b/frontend/src/pages/LoginPage.tsx new file mode 100644 index 00000000..08082067 --- /dev/null +++ b/frontend/src/pages/LoginPage.tsx @@ -0,0 +1,13 @@ +/** 登录页(开登录时)(契约骨架里的占位页,FE-5 实现) */ +import { LayoutGrid } from 'lucide-react' +import { EmptyState, PageHeader } from '../components/ui' +import { APP_TEXT } from '../lib/terms' + +export function LoginPage() { + return ( +
+ } title={APP_TEXT.title} /> + +
+ ) +} diff --git a/frontend/src/pages/apps/AppPage.tsx b/frontend/src/pages/apps/AppPage.tsx new file mode 100644 index 00000000..3bbd92ab --- /dev/null +++ b/frontend/src/pages/apps/AppPage.tsx @@ -0,0 +1,13 @@ +/** 应用页:按服务端解析好的视图模型渲染(契约骨架里的占位页,FE-5 实现) */ +import { LayoutGrid } from 'lucide-react' +import { EmptyState, PageHeader } from '../../components/ui' +import { APP_TEXT } from '../../lib/terms' + +export function AppPage() { + return ( +
+ } title={APP_TEXT.title} /> + +
+ ) +} diff --git a/frontend/src/pages/apps/AppsHome.tsx b/frontend/src/pages/apps/AppsHome.tsx new file mode 100644 index 00000000..ded4d2be --- /dev/null +++ b/frontend/src/pages/apps/AppsHome.tsx @@ -0,0 +1,13 @@ +/** 应用首页:待办 / 应用 / 我发起的(契约骨架里的占位页,FE-5 实现) */ +import { LayoutGrid } from 'lucide-react' +import { EmptyState, PageHeader } from '../../components/ui' +import { APP_TEXT } from '../../lib/terms' + +export function AppsHome() { + return ( +
+ } title={APP_TEXT.title} /> + +
+ ) +} diff --git a/frontend/src/pages/apps/EntryPage.tsx b/frontend/src/pages/apps/EntryPage.tsx new file mode 100644 index 00000000..84f9c5ec --- /dev/null +++ b/frontend/src/pages/apps/EntryPage.tsx @@ -0,0 +1,13 @@ +/** 发起:入口表单(契约骨架里的占位页,FE-5 实现) */ +import { LayoutGrid } from 'lucide-react' +import { EmptyState, PageHeader } from '../../components/ui' +import { APP_TEXT } from '../../lib/terms' + +export function EntryPage() { + return ( +
+ } title={APP_TEXT.title} /> + +
+ ) +} diff --git a/frontend/src/pages/apps/InstancePage.tsx b/frontend/src/pages/apps/InstancePage.tsx new file mode 100644 index 00000000..040c006d --- /dev/null +++ b/frontend/src/pages/apps/InstancePage.tsx @@ -0,0 +1,13 @@ +/** 实例页:状态、印章、进度、待办、动作(契约骨架里的占位页,FE-5 实现) */ +import { LayoutGrid } from 'lucide-react' +import { EmptyState, PageHeader } from '../../components/ui' +import { APP_TEXT } from '../../lib/terms' + +export function InstancePage() { + return ( +
+ } title={APP_TEXT.title} /> + +
+ ) +} diff --git a/frontend/src/pages/apps/TaskPage.tsx b/frontend/src/pages/apps/TaskPage.tsx new file mode 100644 index 00000000..961c6895 --- /dev/null +++ b/frontend/src/pages/apps/TaskPage.tsx @@ -0,0 +1,13 @@ +/** 待办详情(契约骨架里的占位页,FE-5 实现) */ +import { LayoutGrid } from 'lucide-react' +import { EmptyState, PageHeader } from '../../components/ui' +import { APP_TEXT } from '../../lib/terms' + +export function TaskPage() { + return ( +
+ } title={APP_TEXT.title} /> + +
+ ) +} diff --git a/frontend/src/pages/apps/edit/AppEditor.tsx b/frontend/src/pages/apps/edit/AppEditor.tsx new file mode 100644 index 00000000..3a2c8361 --- /dev/null +++ b/frontend/src/pages/apps/edit/AppEditor.tsx @@ -0,0 +1,13 @@ +/** 应用编辑:固定版本、派生、页面树、属性面板、预览、检查、发布、岗位与授权、钩子、助手(契约骨架里的占位页,FE-6 实现) */ +import { LayoutGrid } from 'lucide-react' +import { EmptyState, PageHeader } from '../../../components/ui' +import { APP_TEXT } from '../../../lib/terms' + +export function AppEditor() { + return ( +
+ } title={APP_TEXT.title} /> + +
+ ) +} diff --git a/frontend/src/run/TaskCard.tsx b/frontend/src/run/TaskCard.tsx new file mode 100644 index 00000000..3ca75b86 --- /dev/null +++ b/frontend/src/run/TaskCard.tsx @@ -0,0 +1,31 @@ +/** + * 待办卡(应用平台 X4):从 RunPanel 的 ApprovalCard 抽出,和画布状态解耦——onResolved 必填,内部调 /api/tasks/{id}/respond。 + * + * 用在待办箱、实例页、记录页、画布、问数据。报告核对概况、反方审稿、双盲复算、质询、动作确认的哈希卡、核实选项、 + * 会签进度都在这里。契约骨架里只有最简实现,FE-5 补齐,props 不变。 + */ +import { api } from '../api/client' +import type { Task } from '../typesApp' + +export interface TaskCardProps { + task: Task + /** 回复成功之后(凑齐了、或这个人的那一票记下了)。调用方决定刷新列表还是跳转 */ + onResolved: (result: { task: Task; resolved: boolean }) => void + compact?: boolean +} + +export function TaskCard({ task, onResolved }: TaskCardProps) { + return ( +
+

{task.title}

+ {task.can_respond && ( +
+ + +
+ )} +
+ ) +} diff --git a/frontend/src/typesApp.ts b/frontend/src/typesApp.ts new file mode 100644 index 00000000..3ac45a5e --- /dev/null +++ b/frontend/src/typesApp.ts @@ -0,0 +1,502 @@ +/** + * 应用平台的前后端接口约定(docs/design/app-platform-and-look.md 第三部分)。 + * + * 契约骨架之后冻结:要改,向编排者提,由编排者统一改,前后端同时对齐。字段名和后端返回一字不差。 + */ + +// --------------------------------------------------------------------------- +// 身份(§2.7、§3.10) +// --------------------------------------------------------------------------- + +export type AuthMode = 'off' | 'local' | 'oidc' +export type Role = 'admin' | 'builder' | 'user' + +/** GET /api/auth/me。关登录时 mode='off'、role='admin'、verified=false、username 为自报署名(可能为空) */ +export interface Principal { + mode: AuthMode + username: string | null + display_name: string | null + role: Role + groups: string[] + verified: boolean + /** 开登录后 user 角色能不能问数据(Q2,管理员开关) */ + user_can_chat?: boolean +} + +export interface UserRow { + id: string + username: string + display_name: string + email: string | null + role: Role + disabled: boolean + source: 'local' | 'oidc' + last_login_at: string | null + created_at: string +} + +export interface GroupRow { + id: string + name: string + label: string + source: 'local' | 'oidc' + members: string[] +} + +export interface AuditRow { + id: string + at: string + actor: string | null + verified: boolean + action: string + subject_kind: string + subject_id: string | null + data: Record +} + +// --------------------------------------------------------------------------- +// 表单 agentlab.form/1(§3.3) +// --------------------------------------------------------------------------- + +export type FormWidget = + | 'text' | 'textarea' | 'number' | 'integer' | 'date' | 'datetime' | 'select' | 'radio' | 'multiselect' + | 'checkbox' | 'principal' | 'note' | 'json' + +export interface FormField { + type: 'string' | 'number' | 'integer' | 'boolean' | 'array' + title?: string + description?: string + default?: unknown + readOnly?: boolean + enum?: (string | number)[] + 'x-enum-labels'?: string[] + minimum?: number + maximum?: number + minLength?: number + maxLength?: number + maxItems?: number + format?: 'date' | 'date-time' | 'email' | 'uri' + items?: { type: 'string'; enum?: string[] } + 'x-widget'?: FormWidget +} + +export interface FormSchema { + format?: 'agentlab.form/1' + type: 'object' + title?: string + required?: string[] + properties: Record + 'x-order'?: string[] +} + +/** 前后端同一种错误格式 */ +export interface FormError { + path: string + code: 'required' | 'type' | 'enum' | 'minimum' | 'maximum' | 'min_length' | 'max_length' | 'max_items' | 'format' + message: string +} + +// --------------------------------------------------------------------------- +// 应用描述 agentlab.app/1(§3.2、§3.4、§3.5) +// --------------------------------------------------------------------------- + +export type PinUse = 'view' | 'entry' | 'process' +export type Disposition = 'recompute' | 'dual' | 'incomparable' + +export interface AppPin { + alias: string + workflow_id: string + version: number + graph_hash: string + level?: string | null + use: PinUse +} + +export interface AppEntry { + id: string + label: string + pin: string + form: FormSchema | { $ref: string } + map: Record + instance_title?: { pattern: string; fields: string[] } | null +} + +export interface AppViewSource { + kind: 'latest_sealed' | 'on_demand' | 'instance' + pin?: string | null + from?: string | null + params?: FormSchema | { $ref: string } | null + ttl_s?: number | null + auto?: boolean +} + +/** 绑定:出现哪个键就是哪种(metric / series / cell / query / report / input / run / output / task / action) */ +export type AppBinding = { view?: string } & Record + +export interface AppComponent { + id: string + type: string + props?: Record + bind?: AppBinding | null + visible?: string | null + scope?: string | null + children?: AppComponent[] +} + +export interface AppPage { + id: string + title: string + body: AppComponent[] +} + +export interface AppSpec { + format: 'agentlab.app/1' + name: string + description?: string + icon?: string + pins: AppPin[] + slots: Record + entries: AppEntry[] + forms: Record + task_ui: Record> + views: Record + pages: AppPage[] + hooks: { name: string; kind: 'start' | 'signal'; entry?: string | null }[] + notify: { channel: string; events: string[] }[] +} + +/** 岗位绑定到人或组(不进 spec,存在应用版本的 bindings 里) */ +export interface AppBindings { + slots: Record + hooks?: Record + channels?: Record +} + +export interface CatalogComponent { + name: string + label: string + category: 'layout' | 'display' | 'input' | 'process' + version: number + children: boolean + bindings: string[] + props: Record +} + +export interface ComponentCatalog { + version: number + categories: Record + components: CatalogComponent[] +} + +// --------------------------------------------------------------------------- +// 应用对象(§3.1、§3.10) +// --------------------------------------------------------------------------- + +export type AppLevel = 'published' | 'governed' +export type GrantRole = 'use' | 'observe' | 'manage' + +export interface AppSummary { + id: string + name: string + description: string + icon: string + status: 'active' | 'archived' + published_version: number | null + level: AppLevel | null + /** 钉住的版本被退役:入口拒发新实例 */ + needs_upgrade: boolean + /** 当前用户在这个应用里的待办数 */ + pending_tasks: number + /** 当前用户的授权(关登录时为 manage) */ + my_role: GrantRole | null + updated_at: string +} + +export interface AppDetail extends AppSummary { + draft: AppSpec + draft_bindings: AppBindings + created_by: string | null +} + +export interface AppVersionRow { + version: number + spec_hash: string + level: AppLevel + pins: AppPin[] + dispositions: Record + note: string + published_by: string | null + published_at: string +} + +export interface AppGrant { + principal_kind: 'user' | 'group' | 'everyone' + principal: string + role: GrantRole +} + +/** 发布检查的一条问题(app.* / action.* / human.* / process.*) */ +export interface LintIssue { + message: string + level: 'error' | 'warning' + code: string + path?: string | null + node_id?: string | null +} + +export interface PublishResult { + ok: boolean + version?: number + issues: LintIssue[] + /** 钉住项相对上一版升了版、需要选处置的:[{alias, from, to}] */ + needs_disposition?: { alias: string; from: number; to: number }[] +} + +// --------------------------------------------------------------------------- +// 页面解析 agentlab.view/1(§3.6) +// --------------------------------------------------------------------------- + +export interface Stamp { + as_of: string | null + as_of_text: string + pin: string + graph_hash: string + calibers: { name: string; version: string }[] + tier: 'formal' | 'degraded' | 'withheld' | null + tier_text: string + from: string + sealed: boolean + /** 照实标出的错位:定时任务已改跑新版本、应用还钉在旧版本,等 */ + notes?: string[] +} + +export interface ViewSourceState { + state: 'ok' | 'empty' | 'running' | 'stale' | 'error' + run_id: string | null + stamp: Stamp | null + message?: string +} + +/** 一个数、一格、一个指标的出处:点开走证据接口 */ +export interface ViewEvidence { + run_id: string + kind: 'metric' | 'cell' | 'report' | 'input' | 'query' + eid?: string + node?: string + metric?: string + seg?: string + artifact?: string +} + +export interface ViewNode { + id: string + type: string + props: Record + /** 服务端解析好的数据;形状随组件而定(metric:{text, state, evidence};table:{columns, rows, masked}……) */ + data?: Record | null + children?: ViewNode[] +} + +export interface ViewModel { + format: 'agentlab.view/1' + app: { id: string; name: string; version: number; level: AppLevel; needs_upgrade: boolean } + page: { id: string; title: string } + pages: { id: string; title: string }[] + sources: Record + tree: ViewNode[] + forms: Record + problems: { component: string; code: string; message: string }[] +} + +export interface InstanceRow { + run_id: string + title: string + entry_id: string | null + status: string + started_by: string | null + created_at: string + finished_at: string | null + pending_tasks: number + tier?: string | null +} + +// --------------------------------------------------------------------------- +// 待办(§3.7) +// --------------------------------------------------------------------------- + +export type TaskKind = + | 'approve' | 'input' | 'edit' | 'tool' | 'code' | 'dual_check' | 'action_confirm' | 'reconcile' | 'signal' +export type TaskStatus = 'pending' | 'resolving' | 'resolved' | 'cancelled' | 'expired' +export type TaskPolicy = { kind: 'any' } | { kind: 'all' } | { kind: 'quorum'; m: number } + +export interface TaskAssignment { + id: string + principal_kind: 'user' | 'group' | 'anyone' | 'hook' + principal: string + source: string + status: 'pending' | 'responded' | 'withdrawn' + responded_by: string | null + responded_at: string | null + /** 回复的决定(approve / reject / 提交的值),会签进度用 */ + decision?: string | null + verified: boolean +} + +export interface Task { + id: string + approval_id: string | null + run_id: string + node_id: string | null + app_id: string | null + app_name?: string | null + app_version: number | null + workflow_name?: string | null + kind: TaskKind + title: string + form: FormSchema | null + policy: TaskPolicy + status: TaskStatus + due_at: string | null + escalation_level: number + /** 给人看的上下文:人工节点的 message / context / draft / reports,工具审批的参数,动作确认的预览等(原样来自中断内容) */ + payload: Record + assignments: TaskAssignment[] + /** 当前用户能不能回复这一条 */ + can_respond: boolean + outcome: Record | null + resolved_by: string | null + resolved_at: string | null + created_at: string +} + +export interface TaskRespond { + decision: 'approve' | 'reject' | 'submit' | 'confirmed' | 'not_applied_resend' | 'not_applied_abandon' + values?: Record + note?: string + /** 动作确认:确认卡上显示的哈希,原样带回 */ + payload_hash?: string + /** 核实「已生效」时填的外部单号 */ + external_id?: string +} + +// --------------------------------------------------------------------------- +// 动作(§3.8) +// --------------------------------------------------------------------------- + +export type ActionState = 'pending' | 'sent' | 'confirmed' | 'failed' | 'unknown' | 'simulated' + +export interface ActionRecordRow { + id: string + run_id: string + node_id: string + app_id: string | null + capability: string + environment: 'prod' | 'test' | 'simulated' + state: ActionState + attempt: number + payload_hash: string + preview: Record | null + receipt: Record | null + error: string | null + resolution: Record | null + created_at: string + updated_at: string +} + +// --------------------------------------------------------------------------- +// 能力与端点(§3.9) +// --------------------------------------------------------------------------- + +export type CapabilityEffect = 'read' | 'write' | 'dynamic' + +export interface CapabilityRow { + name: string + system: string + title: string + description: string + params_schema: Record + returns_schema: Record | null + tabular: { rows: string; columns: Record } | null + effect_system: CapabilityEffect + effect: CapabilityEffect | null + approval: 'inherit' | 'confirm' | 'none' + unattended_write: boolean + fields: Record> + masked: string[] + credential_mode: 'service' | 'service_on_behalf' + endpoint_id: string | null + lookup: string | null + version: number + missing: boolean + synced_at: string | null + updated_by: string | null +} + +export interface EndpointEnv { + base_url: string + /** 值只回掩码;提交掩码值表示保持原值 */ + headers: Record + allow_intranet: boolean + verify_tls: boolean +} + +export interface EndpointRow { + id: string + name: string + description: string + environments: { test?: EndpointEnv; prod?: EndpointEnv } + idempotency_header: string + timeout_s: number + version: number +} + +// --------------------------------------------------------------------------- +// 通知(§2.4) +// --------------------------------------------------------------------------- + +export interface NotifyChannelRow { + id: string + name: string + scope: 'global' | 'app' | 'user' + owner_id: string | null + format: 'generic' | 'feishu' | 'wecom' | 'dingtalk' + /** 只回主机名 */ + url_host: string + signed: boolean + events: string[] + enabled: boolean +} + +// --------------------------------------------------------------------------- +// 运行来源(§2.10 X3)与助手查看(§2.9 L2) +// --------------------------------------------------------------------------- + +export type OriginKind = + | 'chat' | 'canvas' | 'launcher' | 'schedule' | 'app_entry' | 'app_view' | 'app_backfill' | 'hook' | 'api' + +export interface LookObject { + kind: 'table' | 'capability' | 'workflow_version' + source?: string + source_id?: string + named: string[] + picked?: string[] + joined?: string[] + missing: string[] + total?: number + explored?: number + catalog_tables?: number + schema_synced_at?: string | null + catalog_versions?: Record + versions?: Record +} + +export interface LookEvent { + op: 'look' + id: string + by: 'model' | 'system' + need: string + status: 'ok' | 'index' | 'failed' + reason?: string + elapsed_ms: number + objects: LookObject[] +}