应用平台契约骨架:新表(身份、能力与端点、应用、待办与生效记录、通知)与迁移(补列、多列索引),运行来源与新事件类型,「人」的唯一入口 api/deps.py(关登录时行为不变),应用描述与表单的形状、受信组件目录 v1,各包跨包函数的签名桩,新路由登记,发布门禁的扩展钩子 EXTRA_LINTS;前端接口约定 typesApp.ts、各接口文件、SchemaForm / TaskCard 的 props 与最简实现、应用相关路由与占位页

This commit is contained in:
ThearchyHelios
2026-10-14 17:53:40 +08:00
parent fc002bd3b3
commit 220fd0e365
59 changed files with 2364 additions and 16 deletions
+6
View File
@@ -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"])
+14
View File
@@ -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()
+6
View File
@@ -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"])
+6
View File
@@ -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"])
+116
View File
@@ -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)
+6
View File
@@ -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"])
+6
View File
@@ -0,0 +1,6 @@
"""用户、组、审计(BE-1,只给管理员)。设计文档 §3.10。"""
from __future__ import annotations
from fastapi import APIRouter
router = APIRouter(prefix="/api", tags=["identity"])
+6
View File
@@ -0,0 +1,6 @@
"""账本(BE-3,只读):工作流版本被哪些应用钉住、生效计数;生效记录查询。设计文档 §2.9 L4。"""
from __future__ import annotations
from fastapi import APIRouter
router = APIRouter(prefix="/api/ledger", tags=["ledger"])
+6
View File
@@ -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"])
+2 -10
View File
@@ -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):
+6
View File
@@ -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"])
+14
View File
@@ -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 新建)
"""
+88
View File
@@ -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}
+15
View File
@@ -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")
+9
View File
@@ -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")
+16
View File
@@ -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
+29
View File
@@ -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")
+14
View File
@@ -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")
+21
View File
@@ -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")
+150
View File
@@ -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:<id> | 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)
+30
View File
@@ -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")
+40
View File
@@ -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 实现")
+5
View File
@@ -0,0 +1,5 @@
"""能力登记与登记的端点(A6,docs/design/app-platform-and-look.md §2.6、§3.9)。BE-1 实现。
- registry.py 能力的同步、治理、快照、作证判定、遮罩字段
- endpoints.py 端点的增删改查、环境、平台执行器(BE-1 新建)
"""
+69
View File
@@ -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")
+21
View File
@@ -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 / 成本累计
+29 -6
View File
@@ -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:
+39
View File
@@ -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,
)
+112
View File
@@ -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)
+82
View File
@@ -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)
+97
View File
@@ -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)
+143
View File
@@ -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)
+20
View File
@@ -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
+36
View File
@@ -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}}
+8
View File
@@ -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、按类型挑选、交回目录、字数上限、重复查看短路、产出记录
"""
+100
View File
@@ -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)
+16
View File
@@ -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)
+10
View File
@@ -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")
+1
View File
@@ -0,0 +1 @@
"""流程:待办、动作、入站钩子(A4、A5,docs/design/app-platform-and-look.md §2.4、§2.5、§3.7、§3.8)。BE-2 实现。"""
+31
View File
@@ -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")
+28
View File
@@ -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")
+40
View File
@@ -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")
+18
View File
@@ -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() {
<Route path="/knowledge/:tab/:id" element={<KnowledgePage />} />
<Route path="/schedules" element={<SchedulesPage />} />
<Route path="/schedules/:id" element={<SchedulesPage />} />
{/* 应用:固定路径(inbox)写在 /apps/:appId 前面,读的人一眼看出它不是应用 id */}
<Route path="/apps" element={<AppsHome />} />
<Route path="/apps/inbox/:taskId" element={<TaskPage />} />
<Route path="/apps/:appId" element={<AppPage />} />
<Route path="/apps/:appId/p/:pageId" element={<AppPage />} />
<Route path="/apps/:appId/new/:entryId" element={<EntryPage />} />
<Route path="/apps/:appId/i/:runId" element={<InstancePage />} />
<Route path="/apps/:appId/edit" element={<AppEditor />} />
<Route path="/apps/:appId/edit/:section" element={<AppEditor />} />
<Route path="/login" element={<LoginPage />} />
{/* 数据源搬到了顶级「数据」页;旧书签和各处「去设置 → 数据源」的链接还在 */}
<Route path="/settings/datasources" element={<Navigate to="/data" replace />} />
<Route path="/settings" element={<SettingsPage />} />
+55
View File
@@ -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<ComponentCatalog>('/apps/catalog', opts),
list: (opts?: RequestOptions) => get<{ items: AppSummary[] }>('/apps', opts),
get: (id: string, opts?: RequestOptions) => get<AppDetail>(at(id), opts),
create: (body: { name: string; description?: string; spec?: AppSpec }) => post<AppDetail>('/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<AppDetail>(at(id), body),
archive: (id: string) => post<AppDetail>(`${at(id)}/archive`),
lint: (id: string) => post<{ issues: LintIssue[]; level: string | null }>(`${at(id)}/lint`),
publish: (id: string, body: { note?: string; dispositions?: Record<string, Disposition> }) =>
post<PublishResult>(`${at(id)}/publish`, body),
versions: (id: string) => get<{ items: AppVersionRow[] }>(`${at(id)}/versions`),
version: (id: string, v: number) => get<AppVersionRow & { spec: AppSpec; bindings: AppBindings }>(`${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<string, unknown> }, opts?: RequestOptions) =>
get<ViewModel>(`${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<string, unknown>) =>
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<InstanceRow & { view: ViewModel }>(`${at(id)}/instances/${encodeURIComponent(runId)}`),
/** 按需视图:发起一次运行(或命中缓存) */
refreshView: (id: string, view: string, params?: Record<string, unknown>) =>
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}`),
}
+32
View File
@@ -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<Principal>('/auth/me', opts),
login: (body: { username: string; password: string }) => post<Principal>('/auth/login', body),
logout: () => post<void>('/auth/logout'),
/** OIDC:浏览器整页跳转到这里 */
oidcStartUrl: (next?: string) => `/api/auth/oidc/start${qs({ next })}`,
settings: () => get<{ mode: AuthMode; env_locked: boolean; oidc: Record<string, any>; user_can_chat: boolean }>(
'/auth/settings'),
saveSettings: (body: { mode?: AuthMode; oidc?: Record<string, any>; user_can_chat?: boolean;
bootstrap?: { username: string; password: string; display_name?: string } }) => put<any>('/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<UserRow>('/users', body),
updateUser: (id: string, body: { display_name?: string; email?: string; role?: Role; disabled?: boolean;
password?: string }) => patch<UserRow>(`/users/${encodeURIComponent(id)}`, body),
groups: () => get<{ items: GroupRow[] }>('/groups'),
createGroup: (body: { name: string; label?: string }) => post<GroupRow>('/groups', body),
setMembers: (id: string, members: string[]) => put<GroupRow>(`/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)}`),
}
+37
View File
@@ -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<CapabilityRow>(`/capabilities/${encodeURIComponent(name)}`),
/** 改治理字段(effect / approval / unattended_write / returns_schema / tabular / fields / masked /
* credential_mode / endpoint_id / lookup),带上读到的 version 做乐观锁 */
govern: (name: string, body: Partial<CapabilityRow> & { version: number }) =>
put<CapabilityRow>(`/capabilities/${encodeURIComponent(name)}/governance`, body),
sync: () => post<{ changed: number }>('/capabilities/sync'),
}
export const endpoints = {
list: () => get<{ items: EndpointRow[] }>('/endpoints'),
create: (body: Omit<EndpointRow, 'id' | 'version'>) => post<EndpointRow>('/endpoints', body),
update: (id: string, body: Partial<EndpointRow> & { version: number }) =>
patch<EndpointRow>(`/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<NotifyChannelRow>('/notify/channels', body),
updateChannel: (id: string, body: Record<string, any>) => patch<NotifyChannelRow>(`/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)}`),
}
+16
View File
@@ -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,
}
/**
+26
View File
@@ -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<Task>(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<Task>(`${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<ActionRecordRow>(`/actions/${encodeURIComponent(id)}`),
}
+48
View File
@@ -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<string, unknown>
onChange: (value: Record<string, unknown>) => 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 (
<div>
{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 (
<div key={key} className="mb-2.5">
<label className="label" htmlFor={id}>{field.title ?? key}</label>
<input
id={id}
className="field"
readOnly={readOnly || field.readOnly}
value={value[key] == null ? '' : String(value[key])}
onChange={(e) => onChange({ ...value, [key]: e.target.value })}
/>
{error && <p className="mt-1 text-xs text-[var(--err)]">{error.message}</p>}
</div>
)
})}
</div>
)
}
+3
View File
@@ -4869,3 +4869,6 @@ export const VERIFY_SETTING_TEXT = {
saveInvalid: '核查设置中有无效值,请修正后再保存',
},
}
// 应用平台使用面的文案(FE-5 维护)。调用方照旧从 lib/terms 导入
export * from './termsApp'
+12
View File
@@ -0,0 +1,12 @@
/**
* 应用平台使用面的文案(应用首页、应用页、发起、实例、待办、登录)。规矩同 terms.ts 开头的术语表:
* 「固定版本」不写钉住;「运行」不写跑;「服务端」不写后端;批准 / 驳回;……
*
* terms.ts 末尾 `export * from './termsApp'`:调用方照旧从 lib/terms 导入。搭建面的文案写在 terms.ts。
*/
export const APP_TEXT = {
nav: '应用',
title: '应用',
pending: '这一页正在建设',
}
+13
View File
@@ -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 (
<div className="flex h-full flex-col">
<PageHeader icon={<LayoutGrid size={14} />} title={APP_TEXT.title} />
<EmptyState title={APP_TEXT.pending} />
</div>
)
}
+13
View File
@@ -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 (
<div className="flex h-full flex-col">
<PageHeader icon={<LayoutGrid size={14} />} title={APP_TEXT.title} />
<EmptyState title={APP_TEXT.pending} />
</div>
)
}
+13
View File
@@ -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 (
<div className="flex h-full flex-col">
<PageHeader icon={<LayoutGrid size={14} />} title={APP_TEXT.title} />
<EmptyState title={APP_TEXT.pending} />
</div>
)
}
+13
View File
@@ -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 (
<div className="flex h-full flex-col">
<PageHeader icon={<LayoutGrid size={14} />} title={APP_TEXT.title} />
<EmptyState title={APP_TEXT.pending} />
</div>
)
}
+13
View File
@@ -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 (
<div className="flex h-full flex-col">
<PageHeader icon={<LayoutGrid size={14} />} title={APP_TEXT.title} />
<EmptyState title={APP_TEXT.pending} />
</div>
)
}
+13
View File
@@ -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 (
<div className="flex h-full flex-col">
<PageHeader icon={<LayoutGrid size={14} />} title={APP_TEXT.title} />
<EmptyState title={APP_TEXT.pending} />
</div>
)
}
@@ -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 (
<div className="flex h-full flex-col">
<PageHeader icon={<LayoutGrid size={14} />} title={APP_TEXT.title} />
<EmptyState title={APP_TEXT.pending} />
</div>
)
}
+31
View File
@@ -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 (
<div className="rounded-md border bg-panel p-3">
<p className="text-sm font-medium">{task.title}</p>
{task.can_respond && (
<div className="mt-2 flex gap-2">
<button type="button" className="btn btn-primary"
onClick={async () => onResolved(await api.tasks.respond(task.id, { decision: 'approve' }))}>批准</button>
<button type="button" className="btn"
onClick={async () => onResolved(await api.tasks.respond(task.id, { decision: 'reject' }))}>驳回</button>
</div>
)}
</div>
)
}
+502
View File
@@ -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<string, any>
}
// ---------------------------------------------------------------------------
// 表单 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<string, FormField>
'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<string, string>
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<string, any>
export interface AppComponent {
id: string
type: string
props?: Record<string, any>
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<string, { label: string }>
entries: AppEntry[]
forms: Record<string, FormSchema>
task_ui: Record<string, Record<string, any>>
views: Record<string, { source: AppViewSource }>
pages: AppPage[]
hooks: { name: string; kind: 'start' | 'signal'; entry?: string | null }[]
notify: { channel: string; events: string[] }[]
}
/** 岗位绑定到人或组(不进 spec,存在应用版本的 bindings 里) */
export interface AppBindings {
slots: Record<string, { kind: 'user' | 'group'; name: string }[]>
hooks?: Record<string, any>
channels?: Record<string, any>
}
export interface CatalogComponent {
name: string
label: string
category: 'layout' | 'display' | 'input' | 'process'
version: number
children: boolean
bindings: string[]
props: Record<string, any>
}
export interface ComponentCatalog {
version: number
categories: Record<string, string>
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<string, Disposition>
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<string, any>
/** 服务端解析好的数据;形状随组件而定(metric:{text, state, evidence};table:{columns, rows, masked}……) */
data?: Record<string, any> | 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<string, ViewSourceState>
tree: ViewNode[]
forms: Record<string, FormSchema>
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<string, any>
assignments: TaskAssignment[]
/** 当前用户能不能回复这一条 */
can_respond: boolean
outcome: Record<string, any> | 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<string, any>
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<string, any> | null
receipt: Record<string, any> | null
error: string | null
resolution: Record<string, any> | 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<string, any>
returns_schema: Record<string, any> | null
tabular: { rows: string; columns: Record<string, string> } | null
effect_system: CapabilityEffect
effect: CapabilityEffect | null
approval: 'inherit' | 'confirm' | 'none'
unattended_write: boolean
fields: Record<string, Record<string, any>>
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<string, string>
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<string, number>
versions?: Record<string, number>
}
export interface LookEvent {
op: 'look'
id: string
by: 'model' | 'system'
need: string
status: 'ok' | 'index' | 'failed'
reason?: string
elapsed_ms: number
objects: LookObject[]
}