- 完善口径编辑、只读试运行、统一质量验证与执行语义指纹 - 增加可执行指标约束、有预算的主动调查和过程评测 - 提取发布检查、证据读取与起草服务,支持任务停止、重试和检查点恢复 - 增加版本传递影响分析,修复并发覆盖、敏感值遮罩、异常评分及页面状态问题 - 修复 SQLite 复合查询追溯和 microVM 可选依赖缺失处理 - 纳入当前设计文档及部署配置调整 验证:相关主回归 3822 项通过,4 项跳过、8 项预期失败;补充回归通过。 前端构建、文案检查及 git diff --check 通过。 全量检查仍有环境权限、PostgreSQL 可选依赖和既有部署配置、SQLite 文件基线差异导致的未通过项。
108 KiB
应用平台与助手按需查看:总方案
设计文档 · 草案,待拍板 · 2026-10-14
- 本文档只定方案,不含代码改动。第六部分「实施组织」在本文签字后另行审批,再开工。
- 代码位置按 main@fc002bd 标注,全部用
git show main:/git grep … main核对过。- 和《助手按需查看与口径账本》(
docs/design/copilot-look-and-caliber-ledger.md,下称「look 文档」)配套。本文不改 look 文档:
- 对它的修订写在 §2.9(L1–L4);
- 引用它的地方写作「look §x.y」。
- 文中出现的数据源名、表名、应用名、岗位名都是虚构的。本文不含本机开发环境的计数。
目录
- 摘要
- 第一部分 定位、理念与现状
- 第二部分 关键决定(A1–A8,L1–L4,X1–X4)
- 第三部分 规格
- 第四部分 界面
- 第五部分 助手按需查看(实施版)
- 第六部分 实施组织
- 第七部分 验证与验收
- 第八部分 风险与对策
- 第九部分 待拍板
- 附录 A 代码位置索引 · B 术语 · C 跨包接口契约 · D 核对方法
摘要
问题。 AgentLab 现在有两个面:
- 「问」:问数据,产出一次推理;
- 「建」:画布加发布,产出一份带版本的承诺。
承诺签出去之后,交到谁手里、怎么用,产品里没有对应的地方:
- 只想看数的人,要去记录页翻运行;
- 要在流程里批一步的人,只能在记录页的待审批页签里处理,而那是给搭建者看的;
- 要把结果写回外部系统,只能靠 MCP 或自定义工具,而它们没有读写语义,也不能访问内网。
定位。 应用不是新引擎,也不是嵌进来的低代码平台,而是已发布版本的使用面。产品从两个面变成三个面,三个面共用同一套对象:工作流版本、运行、证据、口径。
| 面 | 现在对应 | 产出 | 给谁 |
|---|---|---|---|
| 问 | 问数据 | 推理(探索运行) | 要答案的人 |
| 建 | 画布、发布 | 承诺(不可变版本) | 定口径、定流程的人 |
| 用(新) | 应用 | 使用承诺,产生生效 | 看数、办事的人 |
本方案做什么。
- 应用:看板、流程和两者混合,都是同一个对象模型——入口、视图、实例、待办、动作、询问。
- 流程:正式运行加待办。指派、会签、时限与升级、待办箱、通知、入站钩子。
- 动作:写外部系统。幂等、状态机、结果未知时对账,确认时看过的就是发出去的。
- 能力登记:把数据源、自定义工具、MCP、内置工具的描述和治理统一起来;登记的内网端点;密钥加密;外部读取的结果也能作证。
- 身份:三种模式 off / local / oidc,角色、组、应用授权、审计。默认 off,即今天的行为。
- 生成:从工作流版本确定性地派生应用,助手只负责润色。
- 助手按需查看:按 look 文档实施,四项全按推荐,并叠加四处修订。
- 修掉四个和不可回退决定冲突的现有缺陷(F1–F4,见 §1.6)。
已拍板:
- 范围是应用平台加 look,作为一份总方案;
- 先出设计文档,签字后实施;
- look §4 的近期四项全按推荐,并采纳修订 L1–L4。
待拍板:见第九部分,共 10 项,每项附推荐。
第一部分 定位、理念与现状
1.1 对象模型
| 概念 | 是什么 | 现有对应 | 要新增 |
|---|---|---|---|
| 入口 | 填表,发起一件事或一次查询 | 输入节点字段 → 正式运行(RunControl.tsx:242 FormalLauncher 已按版本生成表单) |
字段类型、受信组件、校验 |
| 视图 | 看数据、看结果 | 运行成果、报告文档、可点击证据(EvidenceDoc.tsx) |
绑定规则、印章(截至 / 口径 / 出具档位 / 来源) |
| 实例 | 一件正在办的事 | 一次正式运行:断点落盘,重启后还能接着等(runner.py:60 setup、:278 resume) |
来源、实例列表、发起人 |
| 待办 | 等某个人处理的一步 | 人工节点 + Approval 表(runner.py:821 _handle_updates) |
指派、待办箱、时限、升级、会签 |
| 动作 | 写回外部系统 | 调用工具节点 + 审批档位 | 写入能力、幂等、状态机、对账 |
| 询问 | 运行中向人要信息 | 人工节点(表单写死在配置里,human.py:31) |
agent 在受信组件范围内拟问题 |
几种应用的组成:
- 看板:入口(筛选条件)+ 视图;
- 审批流程:入口 + 实例 + 待办 + 动作 + 实例视图;
- 混合:比如在异常看板上点「发起处置」,进入一个流程。
流程引擎的核心已经有了:
- LangGraph 的检查点就是持久化的流程状态;
- runner 按「两次人工介入之间的一段」计时(
runner.py:717,等审批的时间不算); - 审批可以等很久,批完接着跑。
缺的是三件事:谁来处理、处理的人在哪里看到、超时了怎么办。
1.2 设计理念
前六条来自 look §2.1,后两条为本方案新增。方案里每个决定都要对得上。
| # | 理念 | 在本方案里怎么体现 |
|---|---|---|
| P1 | 照实说 | 印章写明截至何时、哪一版口径、哪一档出具、数据从哪来;版本错位、演练、结果未知都照实标出 |
| P2 | 留痕 | 来源记进封存范围;待办的每次回复、动作的每次发送都有记录;管理操作写审计 |
| P3 | 不挡生成 | 派生不靠模型;询问的表单不合规时退回静态表单,不中断运行 |
| P4 | 只读与遮罩 | 不可见的组件和遮罩值不出服务端;确认卡显示遮罩后的预览 |
| P5 | 一种说法 | 「已发布版本」由一个函数判定;一个表单渲染器;一份组件目录;一份能力登记 |
| P6 | 模板定骨架,agent 填关节 | 流程骨架在图里,人在应用里绑定;助手只负责润色 |
| P7 | 界面层不放逻辑 | 和「叙述层无算术」同一个道理:绑定只取已有的值,表达式禁止算术,逻辑全在图里 |
| P8 | 生效可查、可对账 | 写外部系统必须先留记录再发送;结果未知永不自动重发;确认时看过的就是发出去的 |
不可回退的决定(见路线图),本方案逐条守住,对照表在 §2.11:
- 叙述层无算术;
- 正式运行只能从发布的不可变版本发起,按 graph_hash 钉死;
- 口径升版是必须处置的事件;
- 没发布的图只能跑探索运行;
- 不上 Postgres,不做节点级锁,单进程 + SQLite。
1.3 不做什么
- 不让模型或用户写前端代码,界面上没有客户端逻辑。
- 界面不直接连业务系统,也不直接查库。所有数据都来自运行产物,所有写入都经过调用工具节点。
- 不做通用的 BPMN 建模器,不做像素级设计器。以后真要自由排布,可以把 Puck 一类的编辑器只当外壳接进来。
差异化不在组件多,而在三点:每个数都能追溯,每个动作都能查,每个版本都钉死。
1.4 现有零件
| 应用需要的 | 现有零件(main) |
|---|---|
| 从发布版本发起 | engine/launch.py:45 launch_run。正式运行只从 WorkflowVersion 快照取图;notes(:147)在同一事务、run.started 之前写入,在封存范围内 |
| 断点与恢复 | engine/runner.py:resume(:278)、continue_failed(:449)、_handle_updates(:821);engine/replay.py:once / ask、PROTOCOL = 2(:32) |
| 人工介入 | engine/nodes/human.py(approve / input / edit);engine/approval.py:60 read_decision(只认明确的批准);api/runs.py:525 approvals_router |
| 审批策略 | tools/trust.py:call_policy(:48)、run_snapshot(:84)、ask_gate(:171);tools/registry.py:98 call_is_dangerous / metadata["dangerous_if"] |
| 发布门禁 | engine/governance.py:lint_for_publish(:33)、publish_issues(:127);engine/autofix.py:700 _PLANNERS |
| 定时与通知 | scheduler/service.py:250 fire_once;scheduler/loop.py:114 tick(每 15 秒,:26);scheduler/webhook.py:四种格式、签名、send(:506) |
| 最近一次封存的运行 | scheduler/auto_compare.py:97 sealed_now;api/compare.py:100 pick_base |
| 证据与渲染 | engine/evidence.py:compose_doc(:2737)、render_metric(:691)、render_cell(:702);api/evidence.py:_sealed(:239)、_chain(:843);report_export/build.py(服务端渲染报告) |
| 表达式 | engine/expressions.py:AST 白名单(:455 根名字,:543 parse_expression,:692 eval_expression) |
| 密钥 | core/crypto.py:Fernet、enc:: 前缀、mask() |
| 字段语义 | data/catalog.py:「项」的形状 {value, source, status, note, reason},TABLE_FIELDS / COLUMN_FIELDS(:79、:81);审阅队列 |
| 遮罩 | data/engine.py:376 masked_columns;engine/masking.py:2806 mask_query_result |
| 从运行提取模板 | api/copilot.py:2496 /copilot/from-run(确定性:只保留实际执行的节点) |
1.5 和 look 文档、口径账本的关系
- look 是应用生成的地基。 系统一多,生成时就更不可能把所有能力预先塞进 system,只能先给概览,需要时再查看。
- 口径账本(look 第三部分):
- 应用是口径的又一类使用方,账本里多一条「口径 → 应用」的边;
- 动作是账本里唯一不能重算的一类记录;
- 应用里的「问」,就是把组合式问数限定在这个应用引用的口径里(账本那部分仍按 look §3.8 先做实验)。
1.6 main 上核实过的缺陷与冲突
| # | 事实 | 位置 | 影响与处置 |
|---|---|---|---|
| F1 | 正式运行只认当前发布版:run_version != workflow.published_version 一律拒绝 |
engine/launch.py:92 |
应用钉不住旧的发布版。改为接受「已发布且未退役」(A1) |
| F2 | 和不可回退决定冲突:continue_failed 收到 graph 时只校验拓扑,不看运行类别,用 _claim(..., graph=...) 改写 Run.graph,version_hash 不变;同一处还把 started_by 覆盖成接着跑的人 |
engine/runner.py:449–540、:519;api/runs.py:298 |
正式运行在不知不觉中不再等于它钉住的版本。正式运行带图接着跑一律拒绝;接着跑不再覆盖发起人(A4) |
| F3 | 口径升版的判定用 func.max(WorkflowVersion.version),草稿版本也算进去;而工作流每保存一次就生成一个草稿版本 |
engine/governance.py:613、:643 |
上游改一下画布,下游的正式运行就被逼着处置。改为只看已发布且未退役的版本(A1) |
| F4 | 删除工作流时版本级联删除 | db/models.py:513 |
应用钉着的版本、带生效记录的版本可能被删掉。这两种情况拒绝删除(A1) |
| F5 | 发布人、发布时间只记在工作流上;各版本只有 level |
db/models.py:506 |
每个版本补记发布人、发布时间、退役信息 |
| F6 | 运行没有来源字段:问数据和画布试跑都是「裸图 + 探索」,分不出来 | db/models.py:535 |
新增来源(X3) |
| F7 | 正式运行的信任快照里,所有 MCP 和自定义工具一律要审批;带这类工具的 agent 会停在节点半路 | tools/trust.py:84 |
流程跨系统升级会撞上 _stale_replay(F9)。根本办法是在能力登记里声明「只读」(A6) |
| F8 | 子工作流不带 checkpointer,里面的人工节点恢复时,整个子图从头重放 | engine/nodes/multi.py:610 |
流程应用里禁止这种接法(发布检查) |
| F9 | _stale_replay:断点是按旧重放协议写的,而节点在断点之后执行过工具或批过一次时,拒绝恢复;只豁免人工节点 |
engine/runner.py:1226 |
停在节点边界的人工审批是安全的,停在 agent 半路的不安全(A4) |
| F10 | 表达式的根名字是固定集合,允许算术 | engine/expressions.py:455 |
加 roots=、arithmetic=False 两个参数(A2) |
| F11 | 证据防伪按名字前缀认:name.startswith(QUERY_PREFIX) |
engine/nodes/tools.py:186、engine/nodes/llm.py:511、:874 |
外部读取要作证,得按「平台执行」这个身份认,不能按结果长得像不像(A6) |
| F12 | 没有任何鉴权:/api/artifacts/{id} 直接返回原文,证据路由都在 /api/runs/{run_id}/… 下 |
backend/app/main.py:151 只有 CORS 和 include_router |
鉴权挂在 include_router 的路由级依赖上(A7) |
| F13 | 自定义工具的 headers、MCP 的 env 明文存库、明文返回;MCP 的 http 地址不经 SSRF 检查,也不能配认证头 | tools/custom.py:127、tools/mcp_manager.py:18、db/models.py:447 |
加密、掩码、收口(A6) |
| F14 | WebhookDelivery.schedule_id 是非空外键,SQLite 改不了可空性 |
db/models.py:914 |
通用投递记录另建表(A4) |
| F15 | _INDEX_MIGRATIONS 只支持单列索引 |
db/base.py:225 |
扩成支持多列 |
| F16 | 导航有 8 项(components/CommandPalette.tsx:53),check-shell 要在 480px 高度下量 |
scripts/check-shell.mjs:187 |
只能加 1 项(§4.1) |
| F17 | 前端依赖很少:没有 JSON Schema 校验库,也没有图表库;后端锁文件里有 jsonschema 4.26.0 |
frontend/package.json、backend/requirements.lock:109 |
前端只校验目录规定的子集,图表自绘 SVG;后端以 jsonschema 复核为准 |
| F18 | look 文档引用的 copilot*.py 位置在 main 上没变;catalog.py、decode.ts、terms.ts 的位置变了 |
见 §5.5 | 附录 A 按 main 更新 |
第二部分 关键决定
每条都写四样:决定、理由(对应 §1.2 的理念)、否决的做法、代价。
2.1 A1 应用和应用版本是独立对象,钉住工作流版本
决定
- App 可变:名称、草稿、授权。AppVersion 不可变:
- spec(
agentlab.app/1)、钉住的版本(pins)、岗位与钩子的绑定、级别、spec_hash; - 只在发布时生成,草稿不进版本表。
- spec(
- 一个钉住项写作
{alias, workflow_id, version, graph_hash, level, use: view|entry|process}。 - 应用的级别取各钉住项里最低的那一级:全部是受管级,应用才算受管级。
- 哪些改动要发新版本:
- 改钉住项、改 spec、改岗位绑定:要发新版本;
- 改授权、改组成员:不发新版本,写审计。
- 钉住项升版是必须处置的事件:新应用版本把某个钉住项从 vN 升到 vM 时,必须为它选一种处置——recompute、dual 或 incomparable,记进
app_versions.dispositions。趋势类绑定按这个选择来画(§3.4)。 - 工作流版本可以退役(
POST /api/workflows/{id}/versions/{v}/retire):- 当前发布版不能退役;
- 退役时列出受影响的应用;
- 钉着被退役版本的应用标「需升级」:入口拒绝发起新实例,视图保留最后一次的数据并注明「钉住的版本已退役」,进行中的实例照常走完。
launch_run的改动:- 接受
level 不为空 且 retired_at 为空的版本; - 老数据
level 为空时,只认它等于published_version的情形; - 新增参数
expect_hash,应用发起时必须带上,和快照的graph_hash不一致就拒绝; - 新的拒绝码:
run_version_unpublished、run_version_retired、run_version_hash_mismatch。
- 接受
- 新增
published_versions(session, workflow_id):发起运行、口径升版的判定、子图钉版本、应用钉版本,都用这一个函数(修 F3)。 - 删除约束:工作流有应用钉着、或某个已发布版本有生效记录时,拒绝删除(409,列出原因)(修 F4)。
理由
- P2:承诺不可变;
- P5:「已发布版本」只有一种说法;
- 守住「正式运行只从发布的不可变版本、按 graph_hash 发起」,同时补上 F2 那个口子(见 A4)。
否决的做法
- 把界面写进图里:每改一次布局就成了新口径,graph_hash 跟着变;
- 内嵌低代码平台:有客户端逻辑,数字核对不了;
- 应用每保存一次就生成一个草稿版本:F3 已经说明这么做有害。
代价:使用者要理解两套版本(应用版本、工作流版本);升级时多一步处置。
2.2 A2 界面层不放逻辑:受信组件目录 + 服务端解析
决定
- 组件目录登记在后端(
app/apps/catalog.py)。每个组件登记:名称、版本、类别、props 的 JSON Schema、允许的绑定类型、服务端校验器、解析器。- 前端只有一张「名称 → 渲染器」的表;
- 前端不认识的组件,显示「此组件需要更新前端」(P1),不报错、不空白。
- 绑定是带类型的对象,不是模板。 值里不做插值;实例标题这类展示文字,只能按名字引用入口字段,由服务端拼。
- 可见性表达式用
parse_expression(expr, roots=APP_ROOTS, arithmetic=False),和画布校验、运行时是同一个解析器:- 根名字:
run、input、metric、instance、task、user、view; - 只允许比较、布尔运算、取值和
in; - 不可见的组件服务端不下发(P4)。
- 根名字:
- 表单统一用
agentlab.form/1(§3.3):JSON Schema 的一个子集,加x-widget、x-order。- 前端只校验这个子集;后端用 jsonschema 复核,以后端为准;
- 两边的错误格式一样:
{path, code, message}。
- 一份目录,四个使用方:应用页、人工节点表单、agent 拟的询问、助手生成。
- 开发者可以扩展:组件 + props schema + 校验器 + 前端渲染器;
- 模型只能从已登记的组件里挑。
- 格式参考 A2UI v1.0 的「目录」和「数据模型」概念,不引它的库,也不承诺兼容。
理由
- P4:隐藏的数据不出服务端;
- P5:只有一个求值器;
- P7、叙述层无算术:表达式里禁止算术。
否决的做法
- 客户端求值(json-render、amis 那类):两个求值器早晚会走样,还会把隐藏数据带到浏览器;
- 让模型输出 JSX 或 HTML。
代价:每加一个组件,前后端都要各登记一次;联动要往返服务端,交互没那么灵活。
2.3 A3 视图只读运行产物
决定
视图的数据有三种来源:
| 来源 | 取什么 | 规则 |
|---|---|---|
latest_sealed {pin, from} |
钉住版本、同一 graph_hash 最近一次成功且已封存的正式运行 | from 可以是 schedule:<id> 或 formal;用 sealed_now 判断是否封存完整;派生时优先绑定已有的定时任务 |
on_demand {pin, params, ttl_s, auto} |
按参数发起一次运行,结果缓存 | 缓存键见下;查活库的源必须设 TTL;默认点「刷新」才跑;每个应用有每日上限 |
instance |
实例自己的那次运行 | — |
on_demand 的细则:
- 缓存键 = sha256(graph_hash, 规范化后的输入, 上传源当前的 data_versions, 用到的能力版本);
- 查活库的源必须设 TTL:默认 600 秒,最多 86,400 秒;
- 同一个键在进程内只跑一份;
- 默认要点「刷新」才跑;只有声明了
auto而且没有缓存时,打开页面才自动发起。
印章由服务端算,每个视图都带:
| 项 | 内容 |
|---|---|
| 截至 | 运行结束时间、输入里的统计期、数据版本 |
| 口径 | 「工作流名 vN · 哈希前 8 位」,加上口径卡里的口径名和版本 |
| 出具档位 | 取 _issuance.tier |
| 来源 | 「定时任务『…』第 n 次」、「按需运行」或「本实例」 |
定时任务已经改跑新版本、应用还钉在旧版本时,照实标出来。
理由
- P1;
- 数字只来自封存的证据链(P2);
- 叙述层无算术。
否决的做法:视图直接查库(绕过口径和证据);在浏览器端缓存。
代价:按需运行要花 token 和时间。靠三样东西控制:点「刷新」才跑、同一个键只跑一份、每日上限。
2.4 A4 流程 = 正式运行 + 待办
决定
-
一次中断对应一条 Approval(给引擎)和一条 Task(给人)。
- Task 下挂若干条派给具体的人或组的记录(assignment)。
- 所有人的决定都经
task_service.respond处理;/api/approvals/{id}/decide和/api/runs/{id}/resume改成兼容的垫片。 - 升级时为存量的待审批补建 Task(派给任何人)。
-
人工节点新增配置(写在图里,属于流程语义;字段规格见 §3.7):
assignee:岗位、发起人、表达式或钩子;policy:any、all、quorum(m);due:ISO 8601 时长;on_timeout:提醒、升级或驳回;form/form_from;correlation。
-
图里只写岗位名,不写具体的人。
- 岗位到组或人的绑定放在 AppVersion 里;
- 人员变动只改组成员,不发新版本(写审计);
- 应用可以覆盖表单的外观(标题、顺序、控件),不能改数据约束。
-
会签(只用于审批模式):
all:全体同意才通过,任何一人驳回立即否决;quorum(m):m 人同意就通过;驳回的人数超过 n − m 即否决;- 派给组时,在待办打开那一刻展开成当时的成员(快照,写审计)。
- 汇总在待办服务这一层做,判定之后才调一次
run_manager.resume,引擎和重放都不改。 - 并发靠条件 UPDATE:assignment 从 pending 到 responded,task 从 pending 到 resolving,只有一个请求能抢到恢复。
-
超时:调度循环每一拍跑
tasks.tick,处理提醒、升级、驳回。永远不会自动批准。 -
待办箱:派给我的待办。关闭登录时,所有待办都算「我的」。
-
通知:
- 把
scheduler/webhook.py里的格式、签名、发送、脱敏抽到app/notify/;webhook.py照原名再导出,现有测试不动。 - 新增渠道表和通用投递表;定时任务的通知存储不迁移(F14,Q7)。
- 通知里只放标题、状态、链接,不放报告里的具体数字(沿用
webhook.py的规矩)。
- 把
-
入站签名钩子:
- 签名和出站的通用格式是同一套:
HMAC-SHA256(ts.body),时间窗 5 分钟,用Idempotency-Key去重; start:按入口发起实例,请求体按入口表单校验;signal:按correlation解决一条「等外部系统」的待办。
- 签名和出站的通用格式是同一套:
-
升级安全(F7、F8、F9):
- 发布检查拦三种接法:agent 半路需要审批(
process.wait_mid_agent)、子图里放人工节点(process.human_in_subgraph)、需要审批的工具放进 agent 的工具清单; - 动作确认放在调用工具节点的开头、
tool.start之前——按 F9 这是安全的; - 「结果未知」不在节点里等(A5);
_stale_replay只多豁免一种情况:调用工具节点在断点之后的每条tool.start都带action_key。这类节点发送前一定先查 ActionRecord,重复执行由数据库挡住;- 在
engine/replay.py写明规矩:以后改节点里 task 的调用顺序,就把 PROTOCOL 加一,并跑升级安全测试(§7.5)。
- 发布检查拦三种接法:agent 半路需要审批(
-
agent 拟的询问:
- 上游 agent 输出一份
agentlab.form/1,下游人工节点用form_from接住; - 等待发生在节点边界,不新增 agent 半路询问的工具;
- 运行时按目录校验,不合规就退回节点上的静态表单,并记一条警告(P3);
- 询问的正文用报告那一套
[[…]]标记渲染,裸数字照实标「无证据」,不拦。
- 上游 agent 输出一份
-
修 F2:
- 正式运行带图接着跑,一律拒绝(409,
formal_graph_locked); - 接着跑不再改
started_by,接着跑的人只记在run.resumed事件里。
- 正式运行带图接着跑,一律拒绝(409,
理由
- P2;
- P6:流程骨架在图里,人在应用里;
- 守住「不做节点级锁、单进程」。
否决的做法
- 引入 BPMN 引擎;
- 在引擎层做会签(一次挂起多个中断);
- 把具体的人写进图里;
- 给 agent 一个半路询问的工具(会撞上 F9)。
代价:人工节点的配置变多;组成员按快照展开,之后加入组的人不会补派。
2.5 A5 动作:写外部系统
决定
-
写入能力只能放在调用工具节点里。
build_tools(..., allow_write=False)默认拒绝写入能力,agent、协作节点的代码都不用动;- 只有调用工具节点传
allow_write=True; - 发布检查再拦一道(
action.write_in_agent)。
-
ActionRecord 是权威记录。
action_key = sha256(run_id, node_id, exec),exec取engine/evidence.py:224的next_exec;- 第 n 次发送的幂等键是
{action_key}:{attempt}; - 状态:pending → sent → confirmed | failed | unknown,另有 simulated(演练);
- 先写记录再发送,节点每次执行都先按
action_key查(流程图见 §3.8):
查到的状态 怎么做 confirmed 直接交回存下的回执,不再发 sent / unknown 不发 failed,且有人确认过要重发 attempt 加一后再发 -
按引用确认:看过的就是发出去的。
- 确认卡显示遮罩后的预览和
payload_hash; - 恢复时,节点重新渲染参数、重算哈希,和确认时的哈希对不上就拒绝发送;
- 动作确认不接受改参数(
args不理),要改就在上游的表单里改。
- 确认卡显示遮罩后的预览和
-
结果未知。
- 节点抛
ActionPending,运行收成 interrupted(挂起,不封存),发action.unknown; - 登记了查询能力的:调度循环每拍跑
actions.tick,带退避去查; - 没登记的:开一条核实待办,派给应用的 reconciler 岗位。选项是「已生效(填外部单号)」、「未生效,重新发送」、「未生效,放弃」;
- 核实之后,系统自动接着跑;
- 结果未知永远不会自动重发。
- 节点抛
-
环境。
- 正式运行走 prod;
- 探索运行走 test;端点没有 test 环境时走演练:不发请求,记 simulated,回执标
simulated: true(Q4)。
-
不新增运行类别。 运行类别说的是图从哪里来;写没写外部系统,是运行里发生的事,记成这次运行的生效记录。
理由
- P1;
- P8;
- 守住「不加锁」:幂等靠数据库记录,不靠锁。
否决的做法
- 在节点里等核实:会撞上 F9;
- 让引擎重试:会重复生效;
- 让前端直接调外部系统;
- 新增一类
action运行。
代价:多了一种挂起状态,定时任务通知的 _state_of(webhook.py:720)要能认出它。
2.6 A6 能力登记
决定
-
capabilities表 = 系统同步的部分 + 人工治理的叠加层。- 主键沿用图里工具的名字(
tools/registry.py:142build_tools的命名规则)。 - 系统同步:内置工具、数据源、自定义(http / python)、MCP。启动时同步一次,各对象增删改时同步;MCP 的
readOnlyHint只当「建议只读」,要人确认。 - 治理字段:
effect:read / write / dynamic;approval:inherit / confirm / none;unattended_write:是否允许无人值守写入;returns_schema;tabular:行的 JSON 指针和列映射;fields:按 JSON 指针写字段语义,沿用数据目录「项」的形状{value, source, status, note, reason},审阅队列照样可用;masked、credential_mode、lookup(查询能力)、endpoint_id。
- 主键沿用图里工具的名字(
-
登记的端点(endpoints)。
- 按 test / prod 两个环境分别存
base_url和认证头(加密); allow_intranet只能由管理员开,而且只有登记的端点能访问内网;开了也照样拦元数据地址和高危端口(net.py:17);- 模型给出的地址照旧走完整的 SSRF 检查(
net.py:98); - 绑定端点的 HTTP 能力只填路径模板,参数按路径段编码代入,模型拿不到任意 URL。
- 按 test / prod 两个环境分别存
-
凭据模式:
service和service_on_behalf。service_on_behalf用服务凭据,另带一个 AgentLab 签发的身份断言头:EdDSA JWT,5 分钟有效,aud写端点名,公钥在/api/auth/jwks;- 不存用户自己的 token(Q3):流程一等就是几天,会超过 token 的寿命;存刷新令牌会扩大泄露面。
-
审批跟着登记的效果走。
- 正式运行里:管理员声明为只读、审批策略为 none 的能力直接放行,其余照旧要审批——从根上修 F7;
- 探索运行沿用三档信任;
- 运行发起时,把用到的能力的治理快照放进
options["capabilities"],写进run.started,重放时用同一份。
-
发布时记下能力版本(
workflow_versions.capability_versions)。正式运行发起时如果有漂移只提醒、不拦,做法同数据目录漂移(launch.py:155CATALOG_DRIFT)。 -
密钥(修 F13):
- 自定义工具的 headers、MCP 的 env,值都加密,接口只回掩码;提交掩码值表示保持原值;
- 启动时把存量的明文加密一遍(
encrypt本身是幂等的); - MCP 的 http 地址要么绑定端点,要么过
assert_safe_url,并支持加密的认证头; - MCP 的 stdio(在服务器上执行命令)只有管理员能建。
-
端点读取的结果可以作证。
- 平台执行器按
tabular把响应落成和查询快照同一个形状的工件:{artifact, source, columns, rows, truncated, request};台账类型仍是query,编号进 Q1…。这样报告的单元格标记、整表标记、口径卡的取值、运行对比、可验证报告都不用改。 - 防伪:
- 只认登记表里标为「平台执行的端点读取」的名字(新函数
is_platform_query(name),替换 F11 那三处判断),不看结果长什么样; - 工件必须是本次运行落下的
endpoint_snapshot; - 外部响应的原文嵌在快照里面,伪造不了顶层字段;
- Python 自定义工具(用户代码在算)和 MCP(没有结构化回执)不算。
- 只认登记表里标为「平台执行的端点读取」的名字(新函数
- 平台执行器按
理由
- P5:能力只有一种说法;
- P4;
- P1:外部系统来的数字也有出处。
否决的做法
- 新增一个「连接器」概念(变成第四种说法);
- 新增一种证据类型:会波及运行对比、可验证报告、质询、复算、反方审稿好几处。
代价:端点的结果要先声明 tabular 才能作证;能力登记要人维护。
2.7 A7 身份
决定
-
三种模式(环境变量
AGENTLAB_AUTH_MODE优先于设置页):- off(默认):就是今天的行为。
X-Actor自报署名,所有人等同管理员,界面上挂横幅说明; - local:用户名 + 密码,用
hashlib.scrypt,不加依赖; - oidc:授权码 + PKCE,用
httpx和pyjwt的PyJWKClient;state、nonce、verifier 用 Fernet 加密后放进短时 cookie。
- off(默认):就是今天的行为。
-
会话:
- HttpOnly、SameSite=Lax 的会话 cookie,库里只存令牌的哈希;
- 闲置 12 小时、绝对 7 天过期;
- 非 GET 请求必须带
X-AgentLab-Request头,并校验 Origin; - 登录失败在进程内退避。
-
角色和授权:
- 角色 admin ⊇ builder ⊇ user;
- 组:本地建,或从 OIDC 的 groups 声明同步(同步来的只读);
- 应用授权:use、observe、manage。
-
接入方式:
actor_of(api/runs.py:28)搬到api/deps.py,改由中间件写 contextvar。开了登录,返回认证过的用户名,忽略请求头;关了登录,照旧解码X-Actor。各接口的签名都不用改;- 权限挂在
main.py的include_router(..., dependencies=[...])上;证据路由按run_id判断能不能读这次运行; - WebSocket 只给 builder 及以上用;user 角色的实例页改为轮询。
-
留痕:发起时的
run.origin记actor_verified;派给人的记录上记verified;管理类操作写审计表。 -
开了登录后,user 角色看到的数据一律遮罩:
- 查询快照按派生遮罩处理;
tool_snapshot的原文不给;视图一律遮罩; - 从这一刻起,遮罩对 user 角色就是边界。
data/engine.py里那句「在有身份体系之前,遮罩只减少暴露,不是安全边界」要改写;README 照实写清哪些角色能看到原值。
- 查询快照按派生遮罩处理;
-
引导与找回:
- 从 off 切到 local 时,必须在同一个请求里建出第一个管理员;
- 切到 oidc 时,至少配好一个管理员映射;
- 提供
python -m app.auth reset-admin。
理由
- P2;P4;
- 改动面最小:只动一个函数,再加路由级依赖。
否决的做法
- JWT 放 localStorage:WebSocket 要另想办法,还有 XSS 风险;
- 逐个接口加鉴权:改动大,容易漏;
- 只靠外部认证代理:拿不到 user 角色这一层的粒度。
代价:README「AgentLab 没有登录」那两段(README.md:43 起)要改写;多了一套设置和恢复流程。
2.8 A8 应用生成:先推导,再润色
决定
-
确定性派生
derive_app(workflow_version):图里的东西 派生成 入口字段 入口表单( input_schema(fields))人工节点 待办表单,岗位留空等人绑定 口径卡 指标块 报告节点 报告块 取数节点 表格 写入的调用工具节点 动作确认待办 + 动作状态 -
助手只润色:布局、文案、控件选择。走 L1 的可插拔生成过程,接上应用操作和应用检查。岗位绑定只能由人来做,助手只留空并给出提示。
-
「运行后做成应用」:
- 问数据回答上点「做成应用」→
/copilot/from-run(copilot.py:2496,新工作流记下来源); - → 在画布上发布;
- → 发布成功的弹窗里点「做成应用」→ 进入应用编辑。
- 运行详情页的「提取模板」(
RunDetailView.tsx:403)也接上同一条路。
- 问数据回答上点「做成应用」→
理由
- P6;
- P3:派生不靠模型,助手失败了也有可用的应用。
否决的做法:让助手从零生成整份 spec。
代价:派生规则要随节点类型维护。
2.9 L1–L4:对 look 文档的修订
L1 生成过程可插拔(修订 look §2.4 D9、§2.5.5)
api/copilot_gen.py 的循环只管四件事:读到 look 就停下、执行查看、接着写、计次数和上限。下面两样由调用方注入:
| 注入项 | 接口 | 说明 |
|---|---|---|
| Applier | apply(op) -> Applied{changed, forward}、landed()、continuing() |
look §2.5.5 的去重规则(add_edge 查重、同 id 的 add_node、plan 只留第一次)放在 GraphApplier 里;应用生成用 AppApplier |
| Checker | issues()、repair_request(issues, looks_text) |
图用 GraphChecker(现在的 _blocking_issues + _repair_request),应用用 AppChecker(§3.14) |
模型输出 {"op":"ask","question":…} 时,这一轮就结束,循环里不等用户回答。已经落地的改动照常交付,附上自查问题;用户的回答就是下一轮。
L2 从第一天起按类型标记(修订 look §2.5.2、§2.5.7、§2.11)
-
look 行:
{"op":"look","need":"…","targets":[{"kind":"table","source":"库 B","name":"refunds"}],"sources":["库 B"]}旧写法
tables:[{source, table}]也认,读进来时换成targets。 -
记录:
objects:[{kind:"table", …}, {kind:"capability", …}, {kind:"workflow_version", …}]。表类型的字段同 look §2.5.7 的sources[]。 -
这次实现三种对象:表、能力、工作流版本。口径以后再加(账本先做实验,look §3.8)。
-
否决:每加一种对象就加一个字段(
tables、calibers、ops…)。每加一种都要同时改协议、提示词、解码和存储格式,而meta.looks存下来之后再改就要做数据迁移。 -
代价:只查表的时候,模型每次多写一个
kind。
L3 「三样东西」做成接口(修订 look §2.4 D6)
每种可查看的对象都实现同一个 LookKind:
| 方法 | 作用 |
|---|---|
overview() |
概览,进 system,每个来源一行 |
index() |
目录,挑选失败时交回,每个对象一行 |
resolve(targets) |
按点名解析,认不出的记为「没找到」 |
pick(need) |
按需求挑选 |
detail(objects, budget) |
详情,受字数上限约束 |
- 挑选的提示词改成和对象类型无关,几种类型共用;
- 遮罩按类型各自处理:
| 类型 | 遮罩规矩 |
|---|---|
| 表 | 按 masked_columns,同 look D6 |
| 能力 | 遮罩字段不给示例值,凭据一律不给 |
| 工作流版本 | 不含任何密钥 |
L4 账本加上「生效」和「口径 → 应用」(修订 look §3.4.8)
- 不另建存储,只提供只读查询:
- ActionRecord 本身就带着工作流 id、版本、graph_hash、能力版本、
payload_hash、回执; - 「口径 → 应用」= 钉住这个版本的应用版本。
- ActionRecord 本身就带着工作流 id、版本、graph_hash、能力版本、
- 用在三处:发布弹窗、退役确认、版本列表。
- 召回(look §3.4.5)碰到生效记录时,只能标记并转人工,不能重算。
2.10 交叉决定 X1–X4
-
X1 「人」这一列写什么。 开了登录,各「人」列(
started_by、resolved_by、published_by等)一律写用户名(不可改);关了登录,照旧写自报的署名。认证与否另外记下(run.origin、task_assignments.verified、审计表),不靠给字符串加前缀来区分。 -
X2 只有一个表单渲染器。
components/SchemaForm.tsx用在四处:- 画布的发起表单:服务端把
input_fields换成input_schema,放进VersionDetailOut(api/workflows.py:228); - 人工节点;
- 待办;
- 应用入口。
它替换掉
RunControl.tsx:82的 FieldsForm(目前每个字段都是一个文本框)。输入节点的字段扩展出type、enum、format、description,没写类型的仍按字符串处理。 - 画布的发起表单:服务端把
-
X3 运行来源。
Run.origin_kind取值:值 含义 chat问数据 canvas画布试跑 launcher正式运行(手动) schedule定时任务 app_entry应用入口 app_view应用视图 app_backfill按新口径补算 hook外部系统触发 api接口 - 由
launch_run(origin=…)写成run.origin事件,放在notes里,在封存范围内; app_*和hook只能由服务端写,/api/runs收到客户端声明的这类来源一律拒绝;- 老运行这一列为空,界面写「来源未记录」。
- 由
-
X4 审批卡和画布解耦。 从
RunPanel.tsx:38的 ApprovalCard 抽出run/TaskCard.tsx:onResolved必填,内部调/api/tasks/{id}/respond;- 报告核对概况、反方审稿、双盲复算、质询都保留;
- ApprovalCard 只剩一层包装。
2.11 和不可回退决定的对照
| 不可回退的决定 | 冲突点 | 怎么化解 |
|---|---|---|
| 正式运行只从发布的不可变版本发起,按 graph_hash 钉死 | F2:带图接着跑改写正式运行;F1:只认当前版 | 正式运行禁止带图接着跑;放开到「已发布且未退役」,并核对 expect_hash |
| 口径升版是必须处置的事件 | F3:草稿被当成升版 | 只看已发布且未退役的版本;应用钉住项升版必须处置;退役也会逼出处置 |
| 叙述层无算术 | 视图里可能冒出算式和拼出来的数字 | 绑定只取已有的值;表达式禁止算术;趋势只把封存的指标排成一列、不算差值(环比放进口径卡);表格只排序、不出合计行;静态文字里有数字时警告,受管级应用报错 |
| 不上 Postgres、不做节点级锁、单进程 + SQLite | 会签并发、超时、钩子 | 全部用条件 UPDATE;调度、核实、钩子都在进程内循环;按需运行在进程内同一个键只跑一份 |
| 没发布的图只能跑探索运行 | 应用草稿预览、问数据 | 应用里的运行永远是钉住版本的正式运行(来源标 app_*);应用草稿只预览布局和派生结果,不发起运行;问数据时(意图为回答)查看结果里不列写入能力,运行时也只能走 test 或演练 |
第三部分 规格
3.1 数据模型
新表按领域分文件:db/models_identity.py、db/models_capabilities.py、db/models_apps.py、db/models_process.py,由 db/models.py 统一导入。这些文件在第 0 步「契约骨架」里一次写好,之后冻结(§6.4)。
3.1.1 新表
| 表 | 主要列 | 用途 |
|---|---|---|
users |
id、username(唯一、不可改)、display_name、email、role(admin / builder / user)、password_hash、oidc_issuer、oidc_subject(唯一)、disabled、last_login_at、created_by | 本地用户和 OIDC 用户 |
groups |
id、name(唯一)、label、source(local / oidc) | 组,用于岗位绑定和应用授权 |
group_members |
group_id、user_id、added_by | 组成员 |
auth_sessions |
token_hash(唯一)、user_id、expires_at、last_seen_at、revoked_at、ip、user_agent | 会话 |
audit_events |
at、actor、verified、action、subject_kind、subject_id、data | 管理类操作的留痕:登录方式、角色、组、授权、应用发布、端点、能力治理、退役 |
capabilities |
name(主键)、system、title、description、params_schema、returns_schema、tabular、effect_system(同步得出)、effect(治理后)、approval、unattended_write、fields、masked、credential_mode、endpoint_id、lookup、version、source_hash、synced_at、missing、updated_by | 能力登记(A6) |
endpoints |
id、name(唯一)、environments({test, prod}:base_url、headers 加密、allow_intranet、verify_tls)、idempotency_header、timeout_s、version |
登记的端点 |
apps |
id、name、description、icon、draft(spec 草稿)、published_version、status(active / archived)、created_by、updated_by | 应用 |
app_versions |
(app_id, version) 唯一、spec、spec_hash、pins、bindings(岗位、钩子、渠道)、level、dispositions、note、published_by、published_at | 不可变的应用版本 |
app_grants |
app_id、principal_kind(user / group / everyone)、principal、role(use / observe / manage)、granted_by | 应用授权 |
app_view_cache |
key(主键)、app_id、view_id、run_id、expires_at | 按需视图的缓存 |
app_hooks |
id、app_id、name、kind(start / signal)、entry_id、secret(加密)、enabled | 入站钩子 |
hook_receipts |
(hook_id, idem_key) 唯一、run_id、task_id、status、received_at | 钩子去重 |
tasks |
id、approval_id(唯一,可空:核实待办没有 Approval)、run_id、node_id、app_id、app_version、kind、title、form、policy、status、due_at、remind_at、on_timeout、escalation_level、correlation_key、outcome、resolved_by、resolved_at | 待办(§3.7) |
task_assignments |
id、task_id、principal_kind(user / group / anyone / hook)、principal、source(slot:x / initiator / expression / escalation / reassign)、status、response、responded_by、responded_at、verified | 派给谁、谁回复了什么 |
action_records |
id、action_key、attempt、idem_key(唯一)、run_id、node_id、exec_no、app_id、workflow_id、workflow_version、graph_hash、capability、capability_version、endpoint_id、environment、payload_hash、preview(遮罩后)、state、confirm_task_id、request_at、response_status、receipt、error、lookup_attempts、next_lookup_at、resolution | 生效记录,权威(§3.8) |
notify_channels |
id、name、scope(global / app / user)、owner_id、format、url(加密)、secret(加密)、events、enabled | 通知渠道 |
notify_deliveries |
id、channel_id、subject_kind、subject_id、event、run_id、task_id、status、http_status、attempts、error | 通用投递记录。定时任务的投递仍写 webhook_deliveries |
3.1.2 已有表的新列
按 _COLUMN_MIGRATIONS(db/base.py:134)补列,存量行一律为空:
| 表 | 新列 | 说明 |
|---|---|---|
runs |
origin_kind VARCHAR(20)、origin JSON、app_id VARCHAR(32)、app_version INTEGER |
存量为空,界面写「来源未记录」 |
workflow_versions |
published_at DATETIME、published_by VARCHAR(100)、retired_at DATETIME、retired_by VARCHAR(100)、retire_note TEXT、capability_versions JSON |
每个版本各自记发布和退役 |
workflows |
origin JSON |
从运行提取时的来源:run_id、对话、轮次 |
mcp_servers |
headers JSON(值加密)、endpoint_id VARCHAR(32) |
MCP http 的认证头和端点绑定 |
conversations |
app_id VARCHAR(32) |
应用编辑时助手对话归属哪个应用 |
3.1.3 索引与一次性迁移
索引:_INDEX_MIGRATIONS(db/base.py:225)扩成 (名, 表, (列…)),支持多列。新库在模型的 __table_args__ 里写同名的 Index。新增:
ix_runs_origin_kindix_runs_app_idix_runs_wf_ver_status (workflow_id, version, status):找钉住版本最近一次封存的运行ix_tasks_status_due (status, due_at)ix_assign_principal (principal_kind, principal, status)
启动时的一次性迁移(都幂等):
- 把自定义工具 headers、MCP env 里的明文加密;
- 同步能力登记;
- 为存量的待审批补建 Task(派给任何人)。
3.2 应用描述 agentlab.app/1
示例(虚构):
{
"format": "agentlab.app/1",
"name": "报销审批",
"description": "员工发起报销,财务会签后付款",
"icon": "receipt",
"pins": [
{"alias": "proc", "workflow_id": "wf_x", "version": 4, "graph_hash": "…", "use": "process"},
{"alias": "weekly", "workflow_id": "wf_y", "version": 7, "graph_hash": "…", "use": "view"}
],
"slots": {
"finance": {"label": "财务审批"},
"director": {"label": "总监"},
"reconciler": {"label": "动作核实"}
},
"entries": [{
"id": "apply", "label": "发起报销", "pin": "proc",
"form": {"$ref": "#/forms/apply"},
"map": {"amount": "form.amount", "applicant": "user.display_name"},
"instance_title": {"pattern": "{applicant} 的报销", "fields": ["applicant"]}
}],
"forms": {
"apply": {
"format": "agentlab.form/1", "type": "object", "required": ["amount"],
"properties": {"amount": {"type": "number", "title": "金额(元)", "minimum": 0}}
}
},
"task_ui": {"approve": {"title": "财务审批", "x-order": ["note"]}},
"views": {
"wk": {"source": {"kind": "latest_sealed", "pin": "weekly", "from": "schedule:sch_1"}},
"inst": {"source": {"kind": "instance"}}
},
"pages": [{
"id": "home", "title": "本周概览",
"body": [
{"id": "stamp", "type": "stamp", "bind": {"view": "wk"}},
{"id": "kpis", "type": "columns", "children": [
{"id": "gmv", "type": "metric", "props": {"label": "销售额"},
"bind": {"view": "wk", "metric": "kpi.gmv"}}
]},
{"id": "warn", "type": "notice", "props": {"text": "本期为降级出具"},
"visible": "run.tier != 'formal'", "scope": "wk"},
{"id": "new", "type": "entry_button", "props": {"entry": "apply"}},
{"id": "mine", "type": "instance_list", "props": {"entry": "apply", "who": "mine"}}
]
}],
"hooks": [{"name": "paid", "kind": "signal"}],
"notify": [{"channel": "ch_1", "events": ["task.opened", "action.unknown"]}]
}
| 顶层字段 | 说明 |
|---|---|
pins |
钉住的工作流版本。use: process 的版本,要按流程规则检查(§3.14) |
slots |
岗位,名字和图里人工节点的 assignee.slot 对得上。岗位绑定到人或组的那一份放在 app_versions.bindings,不进 spec:spec 可以导出,绑定是这一个部署自己的 |
entries |
入口:表单 + 字段映射(form.x、user.display_name、常量)。实例标题只能按名字引用入口字段,服务端拼 |
forms |
agentlab.form/1 表单 |
task_ui |
按人工节点覆盖待办的外观(标题、顺序、控件),不能改数据约束 |
views |
视图来源(§2.3) |
pages |
页面树:组件 + props + 绑定 + 可见性 |
hooks |
入站钩子声明;密钥放在 app_hooks |
notify |
通知订阅 |
3.3 表单 agentlab.form/1
JSON Schema 的一个子集。前后端按同一份子集校验,后端用 jsonschema 复核、以后端为准。
| 允许的 | 说明 |
|---|---|
顶层 type: object,properties、required |
只有一层;数组只能装枚举字符串(多选) |
字段 type:string / number / integer / boolean / array |
— |
title、description、default、readOnly |
— |
enum + x-enum-labels |
下拉、单选、多选 |
minimum、maximum、minLength、maxLength、maxItems |
— |
format:date / date-time / email / uri |
不支持 pattern:JS 和 Python 的正则语义不同,会出现前端放行、后端拒收(P5) |
x-widget |
text、textarea、number、integer、date、datetime、select、radio、multiselect、checkbox、principal(选人或组)、note(只读说明)、json(只给 builder) |
x-order |
字段顺序 |
- 错误格式统一为
{path, code, message},code 取required、type、enum、minimum、maximum、min_length、max_length、max_items、format; - 入口提交校验失败回 422,带
{errors:[…]}; - 输入节点的字段扩展出
type、enum、format、description,由input_schema(fields)转成这个格式;没写类型的按 string 处理,老图照常运行。
3.4 绑定类型
| 类型 | 写法 | 服务端怎么解析 | 证据 |
|---|---|---|---|
| 指标 | {view, metric:"节点.指标"} |
读口径卡(metric_set)工件,按 render_metric 渲染 |
{run_id, kind:metric, node, metric, eid},点开是指标链 |
| 趋势 | {view, series:"节点.指标", last:12} |
取同一来源最近 N 次封存运行的指标值。跨钉住版本时按处置来画:dual 画两条线;incomparable 在升版处断开并标注;recompute 只取新版本,可以按历次触发的输入补算(来源记 app_backfill) |
每个点各自有证据 |
| 单元格 | {view, cell:{node, row, col}} |
查询快照(含端点快照),按 render_cell 渲染,遮罩 |
单元格的 eid |
| 表格 | {view, query:{node, exec}} |
快照的列和行,遮罩后给出;只能排序 | 快照 |
| 报告 | {view, report:"节点"} |
报告的 doc_artifact | 逐段证据(EvidenceDoc) |
| 输入 | {view, input:"字段"} |
运行输入 | i: |
| 运行信息 | {view, run:"status"|"tier"|"finished_at"} |
运行记录 | — |
| 成果字段 | {view, output:"字段"} |
只允许两种:逐字取自某份报告(_evidence)的,或者不含数字的文本。其余被 app.binding_not_evidenced 拦下 |
同报告 |
| 待办 / 动作 | {task:"节点"} / {action:"节点"} |
本实例的待办、ActionRecord | 动作的回执和哈希 |
3.5 组件目录 v1
| 类别 | 组件 |
|---|---|
| 布局 | page、section、columns、tabs、divider |
| 展示 | stamp(印章)、metric(指标块)、series(趋势:折线或柱状,自绘 SVG)、table、chart(按表格的列画柱状或折线,不做聚合)、report、text(静态 Markdown;里面有数字时警告)、notice、field、status |
| 输入 | form(agentlab.form/1) |
| 流程 | entry_button、instance_list(我发起的 / 全部,按权限)、instance_header(状态、印章、发起人)、instance_timeline(服务端摘要,不下发原始事件)、task_list、task_form、signoffs(会签进度)、action_status(状态、环境、哈希前 8 位、回执) |
每个组件在目录里登记:props 的 JSON Schema、允许的绑定类型、服务端校验器、解析器、前端渲染器的名字。开发者扩展时四样都要给,缺一样启动就报错。
3.6 页面解析与视图模型 agentlab.view/1
请求:GET /api/apps/{id}/pages/{page}?instance=¶ms=
返回:
{
"format": "agentlab.view/1",
"app": {"id": "…", "name": "…", "version": 3, "level": "governed", "needs_upgrade": false},
"page": {"id": "home", "title": "本周概览"},
"sources": {
"wk": {"state": "ok", "run_id": "…", "stamp": {
"as_of": "…", "as_of_text": "截至 …",
"pin": "周销售 v7", "graph_hash": "3fa2c1d0",
"calibers": [{"name": "周销售口径", "version": "v3"}],
"tier": "formal", "tier_text": "正式出具",
"from": "定时任务「周一 10 点」第 14 次", "sealed": true}}
},
"tree": [
{"id": "gmv", "type": "metric", "props": {"label": "销售额"},
"data": {"text": "45.68 万元", "state": "ok",
"evidence": {"run_id": "…", "kind": "metric", "node": "kpi", "metric": "gmv", "eid": "ev:metric:…"}}}
],
"forms": {},
"problems": [{"component": "trend", "code": "view.source_empty", "message": "还没有可读的封存运行"}]
}
- 不可见的组件不出现在
tree里;遮罩值不出服务端。 - 解析失败的项照实放进
problems,不吞掉(P1)。 - 在进程内做 LRU 缓存,键是 (应用版本, 页面, 来源运行的 id 列表, 角色)。
- 点开指标的证据链,要新增
GET /api/runs/{run_id}/evidence/metrics/{node}/{metric},复用api/evidence.py里拼指标链的那部分。单元格和报告沿用现有的证据接口。
3.7 人工节点的新配置与待办状态机
人工节点新配置(写在图里)
| 字段 | 取值 | 说明 |
|---|---|---|
assignee |
{kind:"slot", slot:"finance"} / {kind:"initiator"} / {kind:"expression", expr:"input.manager"} / {kind:"hook", correlation:"…"} |
表达式只能取输入和变量,结果必须是用户名或组名 |
policy |
any(默认)/ all / {quorum: m} |
all 和 quorum 只用于审批模式 |
due |
ISO 8601 时长,如 PT4H、P2D |
从待办打开时算起 |
on_timeout |
{action:"remind", every:"PT1H"} / {action:"escalate", to_slot:"director"} / {action:"reject"} |
没有「自动批准」这个选项 |
form / form_from |
静态表单,或 "nodes.agent1.form" |
form_from 不合目录时退回 form,并记一条警告 |
correlation |
模板,如 "{{ input.order_id }}" |
只用于 kind: hook;入站 signal 按它找到待办 |
没有应用绑定的运行(画布、定时任务):岗位派给「任何人」,行为和今天一样。
待办的种类
approve、input、edit(人工节点);tool、code、dual_check(现有的几种中断);action_confirm(动作确认);reconcile(核实结果未知的动作);signal(等外部系统)。
种类看中断内容里的 kind 来定,不看 mode:工具审批的中断里没有 mode,所以 Approval.mode 一律是 approve。
状态机
Task: pending ──respond(凑齐)──► resolving ──resume 成功──► resolved
│ └──resume 失败──► pending(再试,写日志)
├──到期,驳回──► resolving ──► resolved(outcome=expired_reject)
├──运行被取消──► cancelled
└──到期,升级──► pending(加派一条,escalation_level+1)
Assignment: pending ──respond──► responded
└──改派 / 升级 / 汇总已判定──► withdrawn
汇总规则:
any:第一条回复就判定;all:全体同意才通过,任何一人驳回立即否决;quorum(m):同意数达到 m 即通过;驳回数超过 n − m 即否决。
判定后:在同一个事务里,用条件 UPDATE 把 Task 从 pending 改成 resolving,抢到的那个请求负责调 run_manager.resume,再把会签明细写进 human.resolved 事件。
3.8 动作:调用工具节点的写入流程
调用工具节点(能力 effect=write,allow_write=True)
1. 渲染参数(真值)→ payload_hash
2. 查 ActionRecord(action_key)
confirmed → 交回存下的回执,结束(不发)
sent / unknown → 抛 ActionPending(不发)
failed 且已确认重发 → attempt+1,继续
没有记录 → 继续
3. 需要确认时:中断,kind=action_confirm
(在 tool.start 之前,节点边界上,升级安全)
确认卡 = 遮罩后的预览 + payload_hash + 环境
恢复后:重算 payload_hash,与确认时的不一致 → 拒绝发送(节点失败,写清原因)
4. 写 ActionRecord(state=pending) 并提交
5. 环境:正式运行 → prod;探索运行 → test;没有 test → simulated(不发)
6. 发送(带幂等头 idem_key)→ state=sent 并提交
7. 2xx → confirmed(落回执工件)
4xx(429 除外)→ failed
超时、连接中断、5xx → unknown → 抛 ActionPending
ActionPending让运行收成 interrupted(挂起,不封存),发action.unknown。- 登记了
lookup的:actions.tick带退避去查(1、2、4…分钟,最多 12 次);查到就核实并自动接着跑,查满了还没结果就转核实待办。 - 没登记
lookup的:直接开核实待办,派给 reconciler 岗位;核实完由系统自动接着跑。 - 结果未知永远不自动重发;重发只能来自核实待办里的「未生效,重新发送」,幂等键带上
:attempt。
3.9 能力登记与端点
| 字段 | 说明 |
|---|---|
name |
图里工具的名字,沿用现有规则:内置名 / db_query__<源> / db_schema__<源> / 自定义工具名 / mcp:<服务>/<工具> |
system |
所属系统:数据源名、端点名、MCP 服务名、builtin |
effect_system / effect |
前者是同步时得出的(数据源可写时为 dynamic,内置工具按 ToolSpec.dangerous),后者是治理后的值;两者不一致时界面上标出来 |
approval |
inherit(跟三档信任)/ confirm(总要确认)/ none(只读能力在正式运行里免审批) |
returns_schema、tabular |
tabular = {rows:"/data/items", columns:{"单号":"/id", "金额":"/amount"}},声明了才能作证 |
fields |
{"/amount": {"label": {...项}, "unit": {...项}}},形状同数据目录的「项」 |
masked |
JSON 指针列表;查看、快照、视图都按它遮 |
credential_mode |
service / service_on_behalf |
lookup |
用来按幂等键查结果的能力名 |
version |
治理字段每改一次加一;运行固定的就是它 |
端点:
{name, environments:{test?, prod}, idempotency_header, timeout_s},每个环境有{base_url, headers(加密), allow_intranet, verify_tls};- 绑定端点的 HTTP 能力,config 改成
{endpoint, method, path, query, body},path里的参数逐段 URL 编码代入; - 没绑定端点的老 HTTP 工具照旧,地址整串过 SSRF 检查。
3.10 接口
| 前缀 | 接口 | 说明 |
|---|---|---|
/api/auth |
GET /me;POST /login、/logout;GET /oidc/start、/oidc/callback;GET,PUT /settings;POST /bootstrap;GET /jwks |
身份 |
/api/users、/api/groups、/api/audit |
增删改查、成员;审计只读 | 只给管理员 |
/api/apps |
列表、新建、详情;PATCH(改草稿);归档;POST /derive;POST /{id}/lint;POST /{id}/publish;GET /{id}/versions[/{v}];GET,PUT /{id}/grants;GET /{id}/pages/{page};POST /{id}/entries/{entry};GET /{id}/instances[/{run_id}];POST /{id}/views/{view}/refresh;GET /catalog |
应用 |
/api/tasks |
GET ?assigned=me|all&status=&app_id=;GET /count?mine=1;GET /{id};POST /{id}/respond {decision, values?, note?, payload_hash?};POST /{id}/reassign;POST /{id}/remind |
待办 |
/api/actions |
GET ?run_id&app_id&state;GET /{id} |
生效记录(核实走待办) |
/api/capabilities、/api/endpoints |
列表、详情;PUT /{name}/governance;端点增删改查;POST /{id}/test?env= |
能力治理 |
/api/hooks/{hook_id} |
POST:只认签名,不走会话 |
入站钩子;管理放在 /api/apps/{id}/hooks |
/api/notify |
渠道增删改查、测试;投递记录 | 通知 |
/api/ledger |
GET /workflow-versions/{wf}/{v}(钉住它的应用、生效计数、正式运行数);GET /effects?… |
账本(只读) |
/api/copilot |
新增 POST /app-stream(应用润色,SSE);/generate-stream、/generate、发布前修复、升级证据都改走 copilot_gen |
助手 |
/api/access-keys(已修订,2026-10 next-round 04 A1) |
服务账号与个人密钥的增删、轮换、撤销;请求记录;接口说明 | 访问密钥;Authorization: Bearer agl_…,按路由白名单放行 |
/api/apps/{id}/shares、/api/shares/*(已修订,2026-10 next-round 04 C2) |
建、列、撤销;公开的 GET /api/shares/page、/report.html(只认请求头 X-AgentLab-Share) |
分享链接 |
/api/apps/{id}/views/{view}/data(已修订,2026-10 next-round 04 A5) |
印章、清单哈希、口径卡指标的原值(遮罩的为 null) | 视图数据,给访问密钥用 |
改动的已有接口:
POST /api/runs:接收origin,客户端只能填 chat、canvas、launcher、api;POST /api/runs/{id}/continue:正式运行带graph回 409;/api/approvals/{id}/decide:改成垫片;- 新增
POST /api/workflows/{id}/versions/{v}/retire; VersionDetailOut加input_schema、retired_at、usage;DELETE /api/workflows/{id}加删除约束。
3.11 事件
新增到 core/events.py:11 的 EventType:
| 类别 | 事件 |
|---|---|
| 来源 | run.origin:发起时写进 notes,在封存范围内。数据包括 kind、app_id、app_version、spec_hash、entry 或 view、hook、actor、actor_verified、auth_mode |
| 待办 | task.opened、task.responded(谁、怎么决定的、第几人 / 共几人)、task.reassigned、task.reminded、task.escalated、task.expired、task.resolved、task.cancelled |
| 动作 | action.prepared(payload_hash、环境、遮罩后的预览)、action.sent、action.confirmed(回执)、action.failed、action.unknown、action.reconciled(谁、怎么核实的)、action.simulated |
| 助手流(SSE,不落运行事件) | look(L2 的形状)、ask、应用操作(app_add、app_update、app_remove、app_move)、应用的 final |
3.12 权限矩阵
关闭登录时下表全部放行,签批人是自报的署名,界面上挂横幅说明。
| 能做的事 | admin | builder | user |
|---|---|---|---|
| 问数据、助手 | ✓ | ✓ | 默认不能(Q2) |
| 编排、探索运行、发布(已发布级) | ✓ | ✓ | ✗ |
| 发布受管级、退役版本 | ✓ | Q8 | ✗ |
| 记录页(全部运行、审批)、运行的 WebSocket | ✓ | ✓ | ✗ |
| 数据源、数据目录、定时任务、知识库 | ✓ | ✓ | ✗ |
| 自定义工具(python;http 绑定端点) | ✓ | ✓ | ✗ |
| MCP stdio、端点和凭据、能力治理、模型接入 | ✓ | 只读 | ✗ |
| 应用:搭建、发布、绑定岗位、授权、钩子 | ✓ | 创建者或有 manage 授权 | ✗ |
| 应用:使用(入口、视图、自己的实例) | ✓ | ✓ | 有 use 授权 |
| 应用:看全部实例 | ✓ | ✓ | 有 observe 授权 |
| 运行、证据、工件(只读) | ✓ | ✓ | 只限有授权的应用视图运行,以及自己参与的实例(遮罩后) |
| 处理派给自己的待办、核实动作 | ✓ | ✓ | ✓ |
| 改派、催办 | ✓ | 有 manage 授权 | ✗ |
| 用户、组、登录方式、审计 | ✓ | ✗ | ✗ |
| 个人的通知渠道和偏好 | ✓ | ✓ | ✓ |
| 入站钩子 | 只认签名 | 只认签名 | 只认签名 |
| 访问密钥(已修订,2026-10 next-round 04 A1):服务账号、个人访问密钥 | 建服务账号、开关个人密钥、撤销任何人的 | 个人密钥(管理员开了才有) | 个人密钥(管理员开了才有);一律按使用者的权限、遮罩、接口白名单 |
| 分享链接(已修订,2026-10 next-round 04 C2):只读、不用登录的视图页 | 开关(缺省关)、建、撤销 | 有应用 manage 授权的建、撤销 | ✗ |
3.13 发布检查
挂接方式:
- 契约骨架在
lint_for_publish(governance.py:33)末尾加一个钩子列表EXTRA_LINTS; - 流程包、治理底座包各写自己的检查模块(
engine/lint_process.py、engine/lint_capabilities.py),不改 governance.py 的主循环; - 问题经现有的
flag(message, code, node_id, hard, field)记录,和其他检查同一种格式; - 应用检查放在
app/apps/lint.py。
工作流(新增)
| 编号 | 条件 | 级别 |
|---|---|---|
action.write_in_agent |
agent 或协作节点的工具清单里有写入能力,或视参数而定(dynamic)的写入能力;运行时也会拒 | 各级都报错 |
action.unattended_write |
写入节点设成不需确认,而这个能力不允许无人值守写入 | 已发布级警告,受管级报错 |
action.prod_missing |
写入能力绑定的端点没有 prod 环境 | 报错 |
action.reconcile_unplanned |
写入能力没有登记查询能力 | 警告(应用那边由 app.reconciler_unbound 拦) |
human.form_invalid |
人工节点的 form 不合目录 |
报错 |
human.due_invalid |
due 不是 ISO 8601 时长 |
报错 |
human.policy_mode |
all 或 quorum 用在补填、改稿模式 |
报错 |
human.escalate_slot |
on_timeout.escalate 没写升级给哪个岗位 |
报错 |
process.wait_mid_agent |
agent 的工具在正式运行快照下可能要审批 | 发布工作流时警告;被应用作为流程钉住时报错 |
process.human_in_subgraph |
子工作流里有人工节点 | 同上 |
process.code_network |
代码节点开了联网 | 警告 |
应用(全部新增)
| 编号 | 条件 | 级别 |
|---|---|---|
app.format、app.component_unknown、app.props_invalid |
格式、组件、props 不对 | 报错 |
app.pin_unpublished、app.pin_retired、app.pin_hash |
钉住的版本没发布、已退役、哈希对不上 | 报错 |
app.upgrade_policy |
钉住项相对上一个应用版本升了版,却没选处置 | 报错 |
app.binding_target_missing |
绑定的节点、指标、报告在钉住的版本里不存在 | 报错 |
app.binding_not_evidenced |
数字类组件绑定了没有证据的值 | 报错 |
app.expr_invalid、app.expr_arith、app.expr_root |
表达式不合法、用了算术、用了不认识的根名字 | 报错 |
app.text_number |
静态文字里有数字 | 已发布级警告,受管级报错 |
app.entry_form_mismatch、app.entry_unmapped_required |
入口表单和钉住版本的入口字段对不上;必填字段没映射 | 报错 |
app.slot_unbound |
流程应用的岗位没绑定 | 报错 |
app.reconciler_unbound |
有写入动作,既没有查询能力,也没绑定核实岗位 | 报错 |
app.process_unsafe |
流程钉住项有 process.* 问题 |
报错 |
app.hook_entry_missing |
钩子指向的入口不存在 | 报错 |
app.view_source_empty |
视图暂时没有可读的运行 | 警告 |
app.on_demand_ttl |
按需视图查活库却没设 TTL(派生时会给默认值) | 报错 |
app.acl_empty |
开了登录,却没有任何 use 授权 | 警告 |
app.notify_channel_missing |
引用的通知渠道不存在 | 警告 |
第四部分 界面
4.1 导航
- 只加一项「应用」(⌥9)。放在「编排」后面,其他项的快捷键都不变。导航定义在
components/CommandPalette.tsx:53,九项要通过 check-shell 在 480px 高度下的测量(check-shell.mjs:187);放不下,就在max-height: 520px时进一步收紧。 - 「应用」页内三个页签:待办、应用、我发起的。
- 徽标按来源分开、不重复计数:
- 「应用」上数应用里的待办;
- 「记录」上数非应用运行的审批(现有的 ApprovalBadge,
App.tsx:322)。
- 开了登录时,user 角色的导航只有「应用」和「设置(个人)」。
4.2 路由与页面
| 路由 | 页面 | 面 |
|---|---|---|
/apps |
应用首页:待办 / 应用 / 我发起的 | 使用面 |
/apps/inbox/:taskId |
待办详情(TaskCard) |
使用面 |
/apps/:appId、/apps/:appId/p/:pageId |
应用页 | 使用面 |
/apps/:appId/new/:entryId |
发起(入口表单) | 使用面 |
/apps/:appId/i/:runId |
实例页:状态、印章、时间线、待办、动作 | 使用面 |
/login |
登录 | 使用面 |
/apps/:appId/edit、/apps/:appId/edit/:section |
应用编辑:钉住项、派生、页面树、属性面板、预览、检查、发布(选处置)、岗位和授权、钩子、助手面板 | 搭建面 |
/tools/capabilities、/tools/endpoints |
能力登记、端点 | 搭建面 |
/settings/identity、/settings/notify、/settings/audit |
身份、通知渠道、审计 | 搭建面 |
路由照现有约定,带 id 和不带 id 各写一条显式路由(App.tsx:102 起)。
4.3 共享组件
| 组件 | 用在哪里 |
|---|---|
components/SchemaForm.tsx + lib/schemaForm.ts(子集校验) |
发起表单、待办、应用入口、询问 |
run/TaskCard.tsx(从 ApprovalCard 抽出) |
待办箱、实例页、记录页、画布、问数据 |
apps/ViewRenderer.tsx、apps/components/* |
应用页面,按目录名字渲染 |
apps/Stamp.tsx |
印章 |
apps/Series.tsx、apps/Chart.tsx(自绘 SVG) |
趋势、图表。动手前先按 dataviz 的规矩定配色和标记 |
components/PrincipalPicker.tsx |
岗位绑定、授权、改派 |
证据面板直接复用 EvidencePanel、EvidenceDoc、ResultTable。
4.4 文案与事件翻译
decode.ts 仍然是事件到文字唯一的翻译层,新增:
run.origin:来源标签;task.*、action.*;- 助手流里的
look、ask; - 旧的
context解码保留,新前端连老后端时用。
terms.ts 新增:
ORIGIN_LABEL:问数据、画布试跑、正式运行(手动)、定时任务、应用入口、应用视图、按新口径补算、外部系统触发、接口;TASK_TEXT;ACTION_STATE_LABEL:待发送、已发送、已生效、失败、结果未知、演练(未发送);CAPABILITY_TEXT:只读、写入、视参数而定;STAMP_TEXT:截至、口径、出具档位、来源;AUTH_TEXT、LOOK_TEXT。
按 look §2.6 删掉三条旧文案:「参考了 N 张表的字段」(terms.ts:3420)、「另有 N 张表只提供了表名」、「未能按需求挑选,已提供全部表名」(decode.ts:3052)。
使用面的文案写在 lib/termsApp.ts,契约骨架在 terms.ts 里加一行 export *,两个前端包不抢同一个文件。
check-copy 的键名白名单加上新配置键:on_timeout、form_from、assignee、unattended_write。
4.5 检查脚本
| 脚本 | 新增 / 更新 | 内容 |
|---|---|---|
check-apps.mjs |
新增 | 应用页、印章、点数字看证据、入口校验、实例页 |
check-inbox.mjs |
新增 | 会签进度、超时横幅、动作确认的哈希卡、核实待办 |
check-auth.mjs |
新增 | 登录、按角色收起的导航、401 跳登录、开登录时不出署名框 |
check-app-editor.mjs |
新增 | 钉住项、派生、检查、发布时选处置、助手流 |
check-capabilities.mjs |
新增 | 能力登记、端点、密钥掩码 |
check-shell |
更新 | 九项导航 |
check-decode、check-chat、check-stream |
更新 | 桩数据里的 context 换成 look |
check-runs、check-studio、check-publish |
更新 | 来源、人工节点新字段、退役和使用情况 |
check-all |
更新 | ORDER、ESTIMATE 加上新脚本 |
第五部分 助手按需查看(实施版)
5.1 采纳的决定
按 look §2.3–§2.10 实施,look §4 的近期四项全按推荐:
| 项 | 采纳 |
|---|---|
| D1 | 用逐行输出里的 look 操作,不用原生工具调用 |
| D6 | 遮罩规矩一并用到运行时的 db_schema__ 和 /schema 接口;运行时 agent 看到的目录因此少了遮罩列那部分,README 写明 |
| 前提 | feat/catalog-loop 已合进 main(6dbe4ad),已满足 |
| 上限 | LOOK_LIMIT = 3、REPAIR_LOOK_LIMIT = 1、LOOK_RESULT_CHARS = 12000;沿用 PICK_LIMIT = 12、CONTEXT_TABLE_LIMIT = 16、PICK_TIMEOUT_S = 20 |
在此之上叠加 L1–L4(§2.9)。
5.2 文件改动
| 文件 | 改动 |
|---|---|
data/schema_view.py(新) |
库概览、表目录、表详情(含遮罩),供 db_schema__、/schema 和 look 共用。从 copilot_context、introspect.describe_table(introspect.py:425)、catalog.render_table_notes 里抽出来 |
app/look/base.py(新) |
LookKind 协议、LookTarget、LookRecord、各项上限常量 |
app/look/tables.py、capabilities.py、versions.py(新) |
三种对象:表、能力、工作流版本 |
app/look/service.py(新) |
解析 targets;按类型挑选,挑不出就交回目录;字数上限;重复查看短路;产出记录。系统代为查看(look D5)也走这里 |
api/copilot_gen.py(新) |
L1 的循环,以及 GraphApplier、GraphChecker |
api/copilot_context.py |
改写成「概览 + 调用查看服务」;删掉 _modes(:223)、按 all / fallback 组装的部分和 listed |
api/copilot.py |
四个入口加 /app-stream,都改走生成过程;system_for 改成给概览;_tool_catalog(:75)不再列表名;删掉 _pick_need;_history_section(:459)读 meta.looks;_STREAM_PROTOCOL(:838)加 look 和 ask;节点手册补上人工节点和写入动作的新字段 |
tools/datasource.py、api/datasources.py |
db_schema__(datasource.py:681)和 /schema?table= 改用共用的表详情 |
providers/mock_model.py |
演示模型按脚本走一次 look |
5.3 每个入口给哪些对象类型
| 入口 | 可查看的对象 | 说明 |
|---|---|---|
画布(/generate-stream) |
表、能力 | — |
| 问数据(意图为回答) | 表、能力 | 只列只读能力,写入能力不出现在概览和查看结果里 |
| 发布前修复、升级证据 | 表 | 系统按要修的 SQL 点名查看(look D5) |
应用润色(/app-stream) |
工作流版本、能力 | 系统先代为查看钉住的版本,模型可以再查看 |
5.4 测试
- look §2.7 列的全部测试:重写
test_copilot_table_pick.py;更新目录影响、表结构截断、SQL 别名几项;新增 look 行解析、查看服务、生成过程、四个入口、历史、前端解码与文案。 - 另加:
- 三种对象类型对同一接口的一致性测试;
ask让这一轮结束;AppApplier的去重;- 旧写法
tables能被正确转换。
5.5 look 文档引用位置的更新
look 文档写的是当时的位置,下面这些在 main@fc002bd 上变了(其余 copilot.py、copilot_context.py 的位置没变):
| look 文档写的 | main 上 |
|---|---|
catalog.py:1152 resolve_table_name |
catalog.py:1234 |
catalog.py:2010 render_table_index |
catalog.py:2239(render_table_notes 在 :2225) |
engine.py:370 masked_columns |
data/engine.py:376 |
datasource.py:647 _make_schema_tool |
tools/datasource.py:681 |
decode.ts:3041 CONTEXT_FALLBACK_TEXT |
decode.ts:3052 |
decode.ts:3086 case 'model' |
decode.ts:3097(0 张表的说法在 :3102) |
terms.ts:2863「参考了 N 张表的字段」 |
terms.ts:3420(namesOnly 在 :3421) |
client.ts:638 聚类接口 |
client.ts:714 |
ChatPage.tsx:298「在画布里打开」 |
ChatPage.tsx:307(api.workflows.create) |
第六部分 实施组织
本部分在本文签字后另行审批,再执行。
6.1 流程
-
开分支。 从最新 main 开集成分支
feat/app-platform,各包用自己的 worktree 和分支。本文仍放在docs/design/下,不跟踪;要提交时先按附录 D 做匿名核对。 -
第 0 步:契约骨架。 由编排者亲自做,一次提交:
- 后端:
- §3.1 的全部模型和迁移(含多列索引);
- EventType 新增项;
engine/origin.py;api/deps.py(搬入actor_of,Principal、require_role先做成关闭登录时的实现);app/apps/spec.py(agentlab.app/1、agentlab.form/1的 pydantic 模型);- 组件目录的名字和 props schema;
- 新路由的桩(一律回 501,在
main.py登记); governance.EXTRA_LINTS;- 附录 C 里每个跨包函数的签名,桩里抛 NotImplementedError。
- 前端:
typesApp.ts;api/apps.ts、api/tasks.ts、api/auth.ts、api/capabilities.ts;SchemaForm、TaskCard的 props 接口和最简实现;App.tsx里的全部新路由(先挂占位页);terms.ts里export * from './termsApp'那一行。
- 后端:
-
构建。 一个 workflow,6 个包,每包一个完整的代理,并行。每个包交付:代码、测试、自己的检查脚本、README 片段、「契约偏差」清单。
-
统一复核。 一个复核代理读全部差异,对照这些项检查:
- P1–P8;
- 五条不可回退的决定;
- 附录 C 的契约;
- 文件归属;
- 文案规范;
- 遮罩与权限。
出各包的修正单,由各包自己改。
-
合并与集成修正。 编排者按 BE-1 → BE-3 → BE-2 → BE-4 → FE-5 → FE-6 的顺序合并,把桩换成真实现,接通
TaskCard、SchemaForm,按各包的片段汇总 README。 -
完整关口。 跑一次(§6.3)。
-
验收(第七部分),问用户之后再合 main。
6.2 六个包
| 包 | 范围 | 独占的文件(契约骨架之后) |
|---|---|---|
| BE-1 治理底座:身份 + 能力 | 三种登录模式、会话、CSRF、OIDC、角色、组、授权判定、审计、user 角色的遮罩;能力登记与同步、端点、密钥加密与掩码、SSRF、MCP 的认证、service_on_behalf、端点快照作证、build_tools(allow_write) |
api/deps.py、api/auth.py、api/identity.py、api/capabilities.py、api/tools.py、app/auth/*、tools/registry.py、tools/custom.py、tools/mcp_manager.py、tools/net.py、tools/trust.py、engine/toolcalls.py、engine/nodes/llm.py(只改作证那一处)、engine/compare.py(兼容端点快照)、engine/lint_capabilities.py、core/config.py、main.py 里中间件那几行 |
| BE-2 流程:待办、动作、钩子、通知 | 待办服务(打开、回复、会签汇总、tick、改派)、人工节点扩充、动作服务和调用工具节点的写入路径、ActionPending 挂起、核实、_stale_replay 的豁免、修 F2、app/notify/*、入站钩子、_state_of 认得挂起、流程检查;种子模板「报销审批(会签 + 写入)」 |
engine/runner.py、engine/replay.py(只改注释)、engine/nodes/human.py、engine/nodes/tools.py、engine/schema.py(人工节点和调用工具节点的配置校验)、engine/lint_process.py、app/process/*、app/notify/*、scheduler/*、api/runs.py、api/tasks.py、api/actions.py、api/hooks.py、api/notify.py、seed.py |
| BE-3 应用:对象、视图、派生、账本 | App / AppVersion、钉住项与升级处置、退役、published_versions、修 F1 / F3 / F4、launch_run(origin, expect_hash)、组件目录(后端)、表单与 input_schema、表达式加 roots / arithmetic、页面解析与视图模型、三种来源与缓存、印章、入口提交、实例、授权、应用检查、派生、应用操作、账本只读接口、指标证据链接口 |
engine/launch.py、engine/governance.py(只改口径升版的判定)、engine/expressions.py、api/workflows.py、api/evidence.py(只加一条路由)、api/apps.py、api/ledger.py、app/apps/* |
| BE-4 助手:按需查看 + 应用生成 | 第五部分全部;/app-stream;workflows.origin 的写入 |
api/copilot.py、api/copilot_context.py、api/copilot_gen.py、app/look/*、data/schema_view.py、tools/datasource.py、api/datasources.py、providers/mock_model.py |
| FE-5 使用面 | 应用首页、待办箱、应用页、发起页、实例页、登录页、按角色收起的导航、账户菜单、SchemaForm、TaskCard、视图渲染、印章、趋势与图表、待办心跳 |
pages/apps/*(除 edit/*)、pages/LoginPage.tsx、apps/*、components/SchemaForm.tsx、components/PrincipalPicker.tsx、run/TaskCard.tsx、App.tsx、components/CommandPalette.tsx、store/catalog.ts、components/ui.tsx、index.css、lib/termsApp.ts、api/apps.ts、api/tasks.ts、api/auth.ts、check-apps、check-inbox、check-auth、check-shell |
| FE-6 搭建面 | 应用编辑器;画布(人工节点、调用工具节点的新字段,发布弹窗里的退役和使用情况);记录页(来源、待办和动作事件、生效记录面板);工具页(能力、端点);设置页(身份、通知、审计);look 的界面;发起表单换成 SchemaForm;全部改用 TaskCard |
pages/apps/edit/*、canvas/*、pages/runs/*、pages/ToolsPage.tsx、pages/SettingsPage.tsx、run/decode.ts、run/RunControl.tsx、run/RunPanel.tsx、store/studio.ts、store/chat.ts、pages/ChatPage.tsx、lib/terms.ts、types.ts、api/capabilities.ts、check-app-editor、check-capabilities、check-copy、check-all 以及 §4.5 列的那些更新 |
每个包对外提供的函数见附录 C。
6.3 验证节奏
开发阶段先把基础功能做完,验证集中放到后面,不在 check-all 上耗时间。
| 阶段 | 谁 | 跑什么 | 不跑什么 |
|---|---|---|---|
| 构建 | 各包代理 | 后端:自己改到和新增的 pytest 文件(-n 8)。前端:tsc -b,自己新写的单项检查脚本各跑通一次 |
不跑 check-all;不反复跑全量 pytest |
| 交付前 | 各包代理 | 后端包:全量 pytest 一遍(-n 8)。前端包:tsc -b + check-copy |
check-all |
| 复核 | 复核代理 | 只读代码,对照清单 | 任何检查 |
| 合并接通后 | 编排者 | 完整关口一次:全量 pytest(-n auto)、tsc -b、check-copy、泄露扫描、check-all --stacks 2、另起一套开着 local 登录的服务跑 check-auth |
— |
| 修正轮 | 编排者 / 包代理 | 只重跑受影响的单项检查和相关测试;最后全量 pytest 一次 | check-all 只在合 main 前、而且修正动过前端时再跑一次 |
另外两条规矩:
- 不许用
git stash:所有 worktree 共用同一组 stash。要临时保存,用补丁文件; - 跑 check-all 要加锁(
/tmp/agentlab-fix/checkall.lock)。
6.4 冻结文件与跨包规则
db/models*.py、db/base.py、core/events.py、frontend/src/typesApp.ts在契约骨架之后冻结。要改,向编排者提,由编排者统一改。- 跨包只能调用附录 C 里列出的函数;要加新函数,记进「契约偏差」清单。
- 一个包的改动弄坏了已有测试,由这个包负责修。
- 依赖别的包运行时行为的测试,先用替身;集成阶段接上真实现,在集成修正里一并跑通。
6.5 验收的数据与模型
- V1–V3、V5:确定性的,用演示模型(Mock)加夹具:
- 虚构零售库
backend/tests/fixtures/acceptance/retail.py; - 假外部系统
backend/tests/fakes/fake_erp.py(新); - 假 OIDC
backend/tests/fakes/fake_oidc.py(新); - 不碰任何真实业务库。
- 虚构零售库
- V4(look 和应用润色)用真实模型:本机配置的助手模型、deepseek-v4.1-flash、glm-5.3。
- 需要开发库副本时,复制数据目录前先请你放行;
- 真实库名、表名只留在
/tmp,不进仓库。
第七部分 验证与验收
7.1 V1 定时任务上的看板应用
准备:
- 用上传表格建一个源(数据版本固定,结果可复现);
- 工作流:取数 → 口径卡 → 报告 → 成果,受管级发布 v1,配好定时任务;
- 从 v1 派生应用,发布,授权给 user 角色;
- 「立即运行」两次。
验收点:
- user 看到的印章写着「截至… / 口径 v1 · 哈希 / 正式出具 / 定时任务第 2 次」。
- 点数字能看到指标链,一路追到单元格;遮罩列已遮。
- 发布 v2、定时任务改跑 v2 之后,应用页面照实提示「钉在 v1」。
- 把应用钉住项升到 v2:
- 不选处置,被
app.upgrade_policy拦下; - 选 incomparable,趋势在升版处断开。
- 不选处置,被
- 退役:
- 退役 v2(当前版)被拒;
- 发布 v3 之后退役 v1,退役确认里列出受影响的应用。
- 可见性表达式写了算术,被
app.expr_arith拦下。
7.2 V2 审批流程应用,接一个假的外部系统
假外部系统:
- 认
Idempotency-Key,有查询接口; - 能注入四种情况:正常、写成功后超时、500、4xx;
- 浏览器验收时用
scripts/fake-erp.py起服务,作为登记端点(开allow_intranet,配 test 和 prod 两个环境)。
流程图:入口 → 读端点查额度(作证,编号 Q)→ 口径卡 → 人工节点(财务岗位,all,PT1H,超时升级给总监岗位)→ 写入付款(需要确认)→ 成果。
验收点:
| 场景 | 期望 |
|---|---|
| 两人都同意 | 流程恢复 |
| 其中一人驳回 | 走驳回分支;human.resolved 里带上会签明细 |
| 把时间拨过时限 | tasks.tick 升级给总监岗位,发出通知 |
| 动作确认 | 确认卡显示遮罩后的预览和哈希 |
| 确认之后上游状态被改动 | 哈希对不上,拒绝发送 |
| 在 sent 之后重启进程 | 收成「结果未知」 |
| 有查询能力 | 自动核实为已生效、自动接着跑,假外部系统只收到 1 次请求 |
| 去掉查询能力,走核实待办,选「未生效,重新发送」 | 第 2 次发送的幂等键带 :2 |
| 探索运行、端点没有 test 环境 | 走演练,假外部系统收到 0 次请求 |
| 入站 signal 钩子 | 能解决「等付款回调」的待办 |
| 重复投递 | 按幂等键去重 |
| 签名错误、超出时间窗 | 拒绝 |
7.3 V3 登录模式
- off:
X-Actor照常可用,界面上挂横幅。 - local:引导出第一个管理员,再建 builder 和 user,然后验:
- user 访问
/api/workflows得到 403; - user 读没有授权的运行和工件得到 403;
- user 读到的查询快照已遮罩;
- 伪造的
X-Actor被忽略,审计照实记录。
- user 访问
- oidc(
fake_oidc.py:discovery、授权、令牌、RS256 JWKS):- groups 声明能映射到 admin 和 builder;
- 同步过来的组成员只读;
- nonce、state 防重放。
reset-admin能找回管理员。
7.4 V4 助手按需查看
- look §2.8 的 9 个场景,加两个:
- 应用润色「首页先看指标再看报告,加一张按门店的表」:系统先代为查看 1 次钉住的版本,应用检查通过;
- 模型提出澄清问题,
ask结束这一轮。
- 每个场景记录:模型调用次数、查看次数、system 字数、第一个操作到达的时间、总用时、自查修正轮数。
7.5 V5 跨重放协议的升级安全
扩充 backend/tests/test_replay_side_effects.py,monkeypatch 把 PROTOCOL 改成 3:
| 停在哪里 | 期望 |
|---|---|
| 人工节点 | 能恢复 |
| agent 半路的审批 | 拒绝恢复;而且应用发布时已被 process.wait_mid_agent 拦下 |
| 写入节点开头等确认 | 能恢复,只发 1 次 |
| 结果未知 | 核实后接着跑,豁免生效,不重发 |
| 子图里的人工节点 | 发布时被 process.human_in_subgraph 拦下 |
7.6 回归
- F2:正式运行带图接着跑得到 409;接着跑之后
started_by不变。 - F3:上游只有草稿改动时,下游不被逼着处置。
- F4:删除被钉住的工作流得到 409。
- 存量待审批补建出 Task;老前端调
/api/approvals/{id}/decide仍然可用。 - 关闭登录时,现有的全部测试和检查脚本照常通过。
第八部分 风险与对策
| 风险 | 对策 |
|---|---|
| 范围大,6 个包合并时冲突 | 契约骨架 + 文件独占 + 附录 C 只列函数级契约;编排者按依赖顺序合并 |
| 开了登录,破坏现有检查和流程 | 默认 off,所有现有检查在 off 下跑;check-auth 另起一套服务 |
| SQLite 写入争用(tick、钩子、会签) | 事务尽量短,用条件 UPDATE;busy_timeout 已经是 5000 |
| 以后改重放协议,正在等的实例恢复不了 | 发布检查加 _stale_replay 豁免;replay.py 写明规矩;V5 测试进全量测试 |
| 对 user 角色来说,遮罩从「减少暴露」变成了边界 | 用 masking.py 的派生遮罩;user 角色不给 tool_snapshot 原文;README 照实写哪些角色看得到原值 |
| 按需视图花费失控 | 点「刷新」才跑;同一个键只跑一份;每个应用有每日上限 |
| 端点作证被误用 | 只认登记里「平台执行」的端点;工件类型和所属运行双重核对 |
| 自绘图表能力有限 | v1 只做折线和柱状,不做交互缩放 |
| 应用生成的质量 | 派生是确定性的,助手只润色,应用检查兜底,真实模型验收 |
| 单进程的容量 | 应用是第一个会带来多人并发的功能。「不上 Postgres」继续守,但验收时量出并发上限,写进 README |
第九部分 待拍板
已拍板的不再列:范围(应用平台 + look)、先出文档再实施、look §4 四项按推荐。
| # | 问题 | 推荐 | 理由 |
|---|---|---|---|
| Q1 | 导航怎么加 | 只加「应用」一项(⌥9),待办放在页内,徽标按来源分开 | F16:只放得下一项;待办是使用者视角,不该挤进记录页 |
| Q2 | 开登录后,user 角色能不能问数据 | 默认不能,给管理员一个开关 | 问数据能查任何接入的源,还没有按数据源的权限控制(P4) |
| Q3 | 凭据模式 | 服务凭据 + 身份断言,不存代用户的 token | 流程会等几天,超过 token 寿命;存刷新令牌会扩大泄露面 |
| Q4 | 探索运行写入、端点没有 test 环境时 | 演练(不发送,记 simulated) | 画布试跑不该被挡(P3),也不该碰生产系统;照实标「演练」(P1) |
| Q5 | 登录 | 只做通用 OIDC,留好适配器接口 | 飞书、企业微信、钉钉不是标准 OIDC,各要一套适配;先看实际需要 |
| Q6 | 待办通知 | 原理由:发送核心现成可用;SMTP 要另配服务器和退信处理。修订理由:Webhook 只能发到群,派给个人的待办没有触达个人的路;退信处理改为照实不追踪,不另起退信服务(理由写在 notify/mail.py 的模块说明) | |
| Q7 | 定时任务的通知存储 | 不迁移,新对象写通用投递表,两边共用发送核心 | F14:SQLite 改不了可空性,迁移要重建表,风险大于收益 |
| Q8 | 受管级发布、版本退役由谁做 | 只给 admin | 受管是最强的承诺,退役会影响正在用的应用 |
| Q9 | 会签 | any / all(一票否决)/ quorum(m) 都做 | 都在待办服务层汇总,引擎不用改,多做两种的成本很小 |
| Q10 | 端点读取的结果作证 | 纳入这次范围 | 外部系统来的数字也要有出处(P1);按查询快照的形状落,下游都不用改 |
附录 A 代码位置索引(main@fc002bd)
发起、版本、治理
| 位置 | 内容 |
|---|---|
backend/app/engine/launch.py:45 |
launch_run |
backend/app/engine/launch.py:92 |
只认当前发布版(F1) |
backend/app/engine/launch.py:147 |
notes:发起时定下的事件,在封存范围内 |
backend/app/engine/launch.py:155 |
CATALOG_DRIFT 提醒 |
backend/app/engine/governance.py:33 |
lint_for_publish |
backend/app/engine/governance.py:127 |
publish_issues |
backend/app/engine/governance.py:613、:643 |
unresolved_caliber_upgrades、func.max(WorkflowVersion.version)(F3) |
backend/app/engine/autofix.py:700 |
_PLANNERS |
backend/app/api/workflows.py:167 |
delete_workflow |
backend/app/api/workflows.py:228 |
VersionDetailOut |
backend/app/api/workflows.py:245 |
get_version |
backend/app/api/workflows.py:324 |
publish_workflow |
运行、断点、审批
| 位置 | 内容 |
|---|---|
backend/app/engine/runner.py:60 |
setup(启动时 running → interrupted) |
backend/app/engine/runner.py:181 |
start |
backend/app/engine/runner.py:278 |
resume |
backend/app/engine/runner.py:449、:519 |
continue_failed、覆盖 started_by(F2) |
backend/app/engine/runner.py:542 |
cancel |
backend/app/engine/runner.py:619、:717 |
_drive、每段的时长上限 |
backend/app/engine/runner.py:821 |
_handle_updates(中断 → Approval) |
backend/app/engine/runner.py:864 |
_finalize |
backend/app/engine/runner.py:1201 |
_approval_default |
backend/app/engine/runner.py:1226 |
_stale_replay(F9) |
backend/app/engine/runner.py:1314 |
_close_approvals |
backend/app/engine/replay.py:32 |
PROTOCOL = 2 |
backend/app/engine/nodes/human.py:31 |
表单是静态配置 |
backend/app/engine/approval.py:60 |
read_decision |
backend/app/engine/nodes/multi.py:610 |
run_subgraph(F8) |
backend/app/engine/evidence.py:224 |
next_exec |
backend/app/api/runs.py:28 |
actor_of |
backend/app/api/runs.py:298 |
continue_run |
backend/app/api/runs.py:525、:551、:595 |
approvals_router、list_approvals、decide |
工具、能力、安全
| 位置 | 内容 |
|---|---|
backend/app/tools/registry.py:26、:46 |
ToolContext、ToolSpec |
backend/app/tools/registry.py:98 |
call_is_dangerous |
backend/app/tools/registry.py:142 |
build_tools |
backend/app/tools/registry.py:278、:324 |
prepare_args、call_tool |
backend/app/tools/trust.py:48、:59、:84、:171 |
call_policy、asks_trustable、run_snapshot、ask_gate |
backend/app/tools/net.py:17、:20、:98、:157 |
_BLOCKED_PORTS、_is_private、assert_safe_url、safe_request |
backend/app/tools/custom.py:44、:127、:160、:183 |
schema_to_model、_run_http、_run_python、build_custom_tools |
backend/app/tools/mcp_manager.py:18、:211 |
_server_config、_keyed |
backend/app/tools/datasource.py:176、:205、:460、:681 |
_query_description、build_datasource_tools、_make_query_tool、_make_schema_tool |
backend/app/engine/nodes/tools.py:186;backend/app/engine/nodes/llm.py:511、:874 |
证据防伪按名字前缀认(F11) |
backend/app/engine/verify_agent.py:841 |
唯一的 mask_results=True |
backend/app/data/engine.py:376 |
masked_columns |
backend/app/engine/masking.py:2806 |
mask_query_result |
backend/app/data/catalog.py:79、:81、:335 |
TABLE_FIELDS、COLUMN_FIELDS、validate_notes |
backend/app/engine/expressions.py:455、:543、:692 |
根名字、parse_expression、eval_expression |
数据模型与迁移
| 位置 | 内容 |
|---|---|
backend/app/db/models.py:34 |
DataSource |
backend/app/db/models.py:447 |
McpServer |
backend/app/db/models.py:466 |
CustomTool |
backend/app/db/models.py:485 |
Workflow |
backend/app/db/models.py:506、:513 |
WorkflowVersion、级联删除(F4) |
backend/app/db/models.py:535 |
Run |
backend/app/db/models.py:609 |
Approval |
backend/app/db/models.py:803、:836 |
ConversationTurn、meta |
backend/app/db/models.py:846、:883、:914 |
Schedule、ScheduleFire、WebhookDelivery(F14) |
backend/app/db/base.py:134、:225、:231、:244 |
_COLUMN_MIGRATIONS、_INDEX_MIGRATIONS、_migrate、init_db |
backend/app/core/events.py:11 |
EventType |
backend/app/main.py:151 |
include_router |
backend/requirements.lock:109 |
jsonschema==4.26.0 |
调度与通知
| 位置 | 内容 |
|---|---|
backend/app/scheduler/service.py:32 |
ACTIVE_RUN(含 interrupted) |
backend/app/scheduler/service.py:172、:191、:250 |
input_fields、check_fields、fire_once |
backend/app/scheduler/loop.py:26、:114 |
节拍 15 秒、tick |
backend/app/scheduler/webhook.py:47、:48 |
FORMATS、EVENTS |
backend/app/scheduler/webhook.py:445、:506、:635、:720 |
build_request、send、notify_due、_state_of |
backend/app/scheduler/auto_compare.py:97 |
sealed_now |
backend/app/api/compare.py:100 |
pick_base |
证据与渲染
| 位置 | 内容 |
|---|---|
backend/app/engine/evidence.py:91 |
EvidenceEntry |
backend/app/engine/evidence.py:611、:691、:702 |
render_number、render_metric、render_cell |
backend/app/engine/evidence.py:851、:2737、:3025 |
build_catalog、compose_doc、verify_doc |
backend/app/api/evidence.py:239、:843 |
_sealed、_chain |
backend/app/report_export/build.py:224、:288、:307、:364 |
_render_block、render_body、build_report、render_html |
助手(look 文档引用的其余位置在 main 上没变,变了的见 §5.5)
| 位置 | 内容 |
|---|---|
backend/app/api/copilot.py:75、:134、:341、:371、:459 |
_tool_catalog、_datasource_context、GenerateIn、意图为回答的约定、_history_section |
backend/app/api/copilot.py:838、:878、:1004、:1090、:1192 |
_STREAM_PROTOCOL、_parse_op_line、_apply_op、_iter_ops、_SELF_CHECK_ROUNDS |
backend/app/api/copilot.py:1779、:1800、:2114、:2296、:2496 |
_repair_request、/generate-stream、assist_publish_fix、assist_upgrade、/from-run |
backend/app/api/copilot_context.py:108、:223、:249、:279、:427、:570、:599 |
PICK_SYSTEM、_modes、graph_tables、plan_context、挑表返回空被记成失败、op、section |
backend/app/api/governance.py:90 |
/exploratory-clusters |
backend/app/data/introspect.py:30、:425 |
_PREVIEW_COLUMNS、describe_table |
backend/app/seed.py:38、:358 |
TEMPLATES、seed_defaults |
前端
| 位置 | 内容 |
|---|---|
frontend/src/App.tsx:52、:102、:322 |
心跳、路由、ApprovalBadge |
frontend/src/components/CommandPalette.tsx:53 |
PAGES(导航) |
frontend/src/run/RunControl.tsx:82、:242 |
FieldsForm、FormalLauncher |
frontend/src/run/RunPanel.tsx:38 |
ApprovalCard |
frontend/src/store/catalog.ts:43 |
HEARTBEAT_MS |
frontend/src/store/studio.ts:1896 |
case 'context' |
frontend/src/run/decode.ts:3052、:3097 |
CONTEXT_FALLBACK_TEXT、case 'model' |
frontend/src/lib/terms.ts:3420、:3421 |
「参考了 N 张表的字段」「另有 N 张表只提供了表名」 |
frontend/src/pages/ChatPage.tsx:307 |
「在画布里打开」 |
frontend/src/pages/runs/RunDetailView.tsx:403 |
「提取模板」 |
frontend/src/api/client.ts:714、:811 |
聚类接口(没有调用方)、fromRun |
scripts/check-shell.mjs:187 |
480px 高度检查 |
附录 B 术语
| 术语 | 含义 |
|---|---|
| 应用 | 已发布工作流版本的使用面:入口、视图、实例、待办、动作、询问的组合 |
| 应用版本 | 应用发布时生成的不可变快照:spec、钉住项、岗位绑定、级别 |
| 钉住项 | 应用引用的某个工作流版本(带 graph_hash) |
| 入口 | 应用里发起一件事或一次查询的表单 |
| 视图 | 展示运行产物的区域;来源分最近封存、按需、本实例三种 |
| 印章 | 视图上的「截至 / 口径 / 出具档位 / 来源」 |
| 实例 | 应用里发起的一次正式运行,即一件正在办的事 |
| 待办 | 一次中断面向人的那一面;可以派给多人,按策略汇总 |
| 岗位 | 图里人工节点写的角色名;绑定到人或组在应用版本里做 |
| 会签 | 一条待办派给多人,按 all 或 quorum(m) 汇总 |
| 动作 | 调用工具节点对外部系统的一次写入 |
| 生效记录 | ActionRecord:动作的权威记录,带幂等键、状态、哈希、回执 |
| 结果未知 | 请求已发出、拿不到确定结果的状态;只能核实,永不自动重发 |
| 演练 | 探索运行里、端点没有 test 环境时的写入:不发送,照实记录 |
| 能力 | 图里任何一个可调用的工具,连同它的读写效果、参数、返回、语义、审批策略 |
| 端点 | 管理员登记的外部系统地址和凭据,分 test / prod 两个环境 |
| 退役 | 工作流版本不再接受新的正式运行;进行中的实例照常走完 |
| 运行来源 | 这次运行从哪里发起,记进封存范围 |
| 查看(look) | 助手在一轮里主动查看表、能力或工作流版本 |
| 三个面 | 问(推理)、建(承诺)、用(使用与生效) |
附录 C 跨包接口契约
契约骨架提交时,这些函数先写好签名,桩里抛 NotImplementedError。
| 提供方 | 函数 | 说明 |
|---|---|---|
| BE-1 | current_principal() -> Principal |
当前请求的身份:用户名、角色、组、是否经过认证、登录模式 |
| BE-1 | require_role(role) -> Depends |
路由级依赖 |
| BE-1 | can_read_run(principal, run) -> bool、can_read_artifact(principal, artifact_id) -> bool |
运行和工件的读权限 |
| BE-1 | get_capability(name) -> Capability | None |
能力登记(治理后的值) |
| BE-1 | capability_snapshot(spec) -> dict、capability_versions_for(spec) -> dict |
发起时的治理快照、发布时的能力版本 |
| BE-1 | is_platform_query(name) -> bool |
端点读取能不能作证(替换 F11 的三处判断) |
| BE-1 | endpoint_request(capability, args, *, environment, idem_key, on_behalf) -> EndpointResult |
平台执行器:发请求、落快照 |
| BE-1 | masked_paths(name) -> list[str] |
能力的遮罩字段 |
| BE-2 | task_service.open(approval) -> Task、respond(task_id, principal, decision, values, note, payload_hash)、tick(now)、reassign(...) |
待办 |
| BE-2 | action_service.prepare(...)、send(...)、reconcile(...)、tick(now) |
动作 |
| BE-2 | notify.send(channel, message) -> Outcome |
通知发送核心 |
| BE-2 | hooks.verify(hook, headers, body) -> HookRequest |
入站签名校验 |
| BE-3 | published_versions(session, workflow_id) -> list[WorkflowVersion] |
「已发布且未退役」的唯一说法 |
| BE-3 | start_entry(app_id, entry_id, values, principal) -> Run |
应用入口发起 |
| BE-3 | validate_form(form, values) -> list[FormError]、input_schema(fields) -> dict |
表单 |
| BE-3 | apply_app_op(spec, op) -> Applied、lint_app(app_version_draft) -> list[Issue]、derive_app(version) -> AppSpec |
应用操作、检查、派生 |
| BE-3 | describe_version(version) -> str |
给 look 的「工作流版本」详情 |
| BE-4 | 生成过程协议:generate(system, request, applier, checker, look_kinds) -> AsyncIterator[op] |
四个入口和 /app-stream 共用 |
| BE-4 | look 事件的形状(L2) | 前端解码依据 |
| FE-5 | SchemaForm props:{schema, value, onChange, errors, readOnly?} |
表单 |
| FE-5 | TaskCard props:{task, onResolved, compact?} |
待办卡 |
附录 D 核对方法
- 代码位置:全部用
git grep -n … main/git show main:<路径>取得,基准 main@fc002bd。工作区所在的分支比 main 旧,没有用它。 - 事实核对:F2、F3、F4 逐行读过 main 上的源码(
runner.py:449–540、governance.py:613–669、models.py:513)。 - 匿名:全文没有真实的数据源名、表名、主机名、部署地址;示例名都是虚构的。本文没有引用本机开发环境的计数。要提交前,再按泄露扫描的规则过一遍。
- look 文档:这次没有改动,写之前和写之后的 sha256 一致。
附录 E 实施中拍定的细节(2026-10-14)
用户没有逐条回复第九部分,Q1–Q10 一律按推荐执行。实施中又拍定了下面这些细节,和正文不一致的地方以这里为准。
| # | 细节 | 定法 | 理由 |
|---|---|---|---|
| D-a | 探索运行里,端点没有测试环境时 | 写入走演练;读取走生产 | 读不改外部系统;一律演练会让问数据用不了只登记了生产环境的端点。修正 §2.11「运行时也只能走 test 或演练」:这句只对写入成立 |
| D-b | 身份断言的主体 | sub = 运行发起人;确认动作的人放在 act 声明(RFC 8693) |
外部系统看到的是「谁发起的这件事」,确认人另外可查 |
| D-c | 开了 user_can_chat 时 user 的问数据运行 | 只能是探索运行、来源 chat;只允许 input、llm、agent、report、output、retrieve、transform、branch、metrics、merge 节点;agent 只能用数据源工具和只读内置工具;不能正式运行(正式运行只经应用入口);查询结果在工具边界先遮;WebSocket 按运行判读权限 | 没有按数据源的权限控制,只能把 user 能做的事收窄到「问」 |
| D-d | 对话归属 | 新建写 created_by;开登录后 user 只看、只改自己的对话;老对话只有 builder 以上可见 |
对话里有别人的问题和带数据的回答 |
| D-e | 应用编辑器的助手对话 | kind=app、app_id、created_by;按应用取或建;应用润色带历史 |
润色是多轮的 |
| D-f | 按新口径补算 | 只在钉住项升版且处置为 recompute 时可用;用旧版本最近 N 次封存运行的输入,以新版本逐个发起正式运行(来源 app_backfill),同一输入只补一次 | 让 recompute 的趋势真的有历史点,而不是只画新版本 |
| D-g | 钩子 | spec 里声明,app_hooks 按名字关联、只存密钥和启停;入站时按当前发布版的声明认 kind 和入口 |
一份声明,不在两处各存一份入口 |
| D-h | 助手润色的权限 | 只放行页面树的增删改移和页面标题;app_set 只放行 task_ui 和表单的外观键 |
A8「助手只润色」由服务端保证,不只靠提示词 |
| D-i | 能力字段语义的审阅 | 沿用数据目录「项」的状态;在能力登记下另开审阅队列,排序思路同数据目录 | 「同一种说法」:语义的确认方式和数据目录一致 |
| D-j | 按需视图的每日上限 | 设置项 apps.on_demand_daily_limit |
— |
| D-l | 登录设置 | 只经 /api/auth/settings 读写,通用设置接口不暴露、不能覆写 |
防止绕过引导和管理员映射检查 |
| D-m | 应用详情 | 只有 manage 能拿到草稿和岗位绑定 | 岗位绑定里有人和组的名单 |
| D-n | 删运行 | 有演练以外的生效记录的运行一律不能删(含强制删除);删工作流的阻挡也算上已退役版本的生效记录 | P8:生效记录是和外部系统对账的依据 |
| D-q | 子图固定版本 | 正式运行发起时,子图固定的版本必须已发布且未退役;发布检查先预读子工作流 | A1「已发布版本只有一种说法」延伸到子图 |
| D-r | 运行接口 | RunOut 带来源;按来源筛选(none = 来源未记录) |
X3 |
| D-s | 界面偏好 | 开登录且不是 admin 时只存本地 | 通用设置只给 admin 写 |
另外两条实施事实:
- 开发库在 17:46 被这个分支的代码跑过一次启动迁移,多了空表和可空列,只增不改,main 不受影响。时间早于代理开工,最可能是开发服务热重载。
- MCP 的 http 地址指向本机或内网的存量服务,升级后首次启动自动登记成开了内网访问的端点(
mcp-<服务名>)并绑定,写审计。之后新建的内网 MCP 须管理员先登记端点。