Files
AgentLab/docs/design/app-platform-and-look.md
T
ThearchyHelios 9d8b41430e 完善口径管理、主动调查与后台任务,修复通用问题
- 完善口径编辑、只读试运行、统一质量验证与执行语义指纹
- 增加可执行指标约束、有预算的主动调查和过程评测
- 提取发布检查、证据读取与起草服务,支持任务停止、重试和检查点恢复
- 增加版本传递影响分析,修复并发覆盖、敏感值遮罩、异常评分及页面状态问题
- 修复 SQLite 复合查询追溯和 microVM 可选依赖缺失处理
- 纳入当前设计文档及部署配置调整

验证:相关主回归 3822 项通过,4 项跳过、8 项预期失败;补充回归通过。
前端构建、文案检查及 git diff --check 通过。
全量检查仍有环境权限、PostgreSQL 可选依赖和既有部署配置、SQLite 文件基线差异导致的未通过项。
2026-11-06 17:14:45 +08:00

108 KiB
Raw Blame History

应用平台与助手按需查看:总方案

设计文档 · 草案,待拍板 · 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 或自定义工具,而它们没有读写语义,也不能访问内网。

定位。 应用不是新引擎,也不是嵌进来的低代码平台,而是已发布版本的使用面。产品从两个面变成三个面,三个面共用同一套对象:工作流版本、运行、证据、口径。

面 现在对应 产出 给谁
问 问数据 推理(探索运行) 要答案的人
建 画布、发布 承诺(不可变版本) 定口径、定流程的人
用(新) 应用 使用承诺,产生生效 看数、办事的人

本方案做什么。

  1. 应用:看板、流程和两者混合,都是同一个对象模型——入口、视图、实例、待办、动作、询问。
  2. 流程:正式运行加待办。指派、会签、时限与升级、待办箱、通知、入站钩子。
  3. 动作:写外部系统。幂等、状态机、结果未知时对账,确认时看过的就是发出去的。
  4. 能力登记:把数据源、自定义工具、MCP、内置工具的描述和治理统一起来;登记的内网端点;密钥加密;外部读取的结果也能作证。
  5. 身份:三种模式 off / local / oidc,角色、组、应用授权、审计。默认 off,即今天的行为。
  6. 生成:从工作流版本确定性地派生应用,助手只负责润色。
  7. 助手按需查看:按 look 文档实施,四项全按推荐,并叠加四处修订。
  8. 修掉四个和不可回退决定冲突的现有缺陷(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;
    • 只在发布时生成,草稿不进版本表。
  • 一个钉住项写作 {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 流程 = 正式运行 + 待办

决定

  1. 一次中断对应一条 Approval(给引擎)和一条 Task(给人)。

    • Task 下挂若干条派给具体的人或组的记录(assignment)。
    • 所有人的决定都经 task_service.respond 处理;/api/approvals/{id}/decide 和 /api/runs/{id}/resume 改成兼容的垫片。
    • 升级时为存量的待审批补建 Task(派给任何人)。
  2. 人工节点新增配置(写在图里,属于流程语义;字段规格见 §3.7):

    • assignee:岗位、发起人、表达式或钩子;
    • policy:any、all、quorum(m);
    • due:ISO 8601 时长;
    • on_timeout:提醒、升级或驳回;
    • form / form_from;
    • correlation。
  3. 图里只写岗位名,不写具体的人。

    • 岗位到组或人的绑定放在 AppVersion 里;
    • 人员变动只改组成员,不发新版本(写审计);
    • 应用可以覆盖表单的外观(标题、顺序、控件),不能改数据约束。
  4. 会签(只用于审批模式):

    • all:全体同意才通过,任何一人驳回立即否决;
    • quorum(m):m 人同意就通过;驳回的人数超过 n − m 即否决;
    • 派给组时,在待办打开那一刻展开成当时的成员(快照,写审计)。
    • 汇总在待办服务这一层做,判定之后才调一次 run_manager.resume,引擎和重放都不改。
    • 并发靠条件 UPDATE:assignment 从 pending 到 responded,task 从 pending 到 resolving,只有一个请求能抢到恢复。
  5. 超时:调度循环每一拍跑 tasks.tick,处理提醒、升级、驳回。永远不会自动批准。

  6. 待办箱:派给我的待办。关闭登录时,所有待办都算「我的」。

  7. 通知:

    • 把 scheduler/webhook.py 里的格式、签名、发送、脱敏抽到 app/notify/;webhook.py 照原名再导出,现有测试不动。
    • 新增渠道表和通用投递表;定时任务的通知存储不迁移(F14,Q7)。
    • 通知里只放标题、状态、链接,不放报告里的具体数字(沿用 webhook.py 的规矩)。
  8. 入站签名钩子:

    • 签名和出站的通用格式是同一套:HMAC-SHA256(ts.body),时间窗 5 分钟,用 Idempotency-Key 去重;
    • start:按入口发起实例,请求体按入口表单校验;
    • signal:按 correlation 解决一条「等外部系统」的待办。
  9. 升级安全(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)。
  10. agent 拟的询问:

    • 上游 agent 输出一份 agentlab.form/1,下游人工节点用 form_from 接住;
    • 等待发生在节点边界,不新增 agent 半路询问的工具;
    • 运行时按目录校验,不合规就退回节点上的静态表单,并记一条警告(P3);
    • 询问的正文用报告那一套 [[…]] 标记渲染,裸数字照实标「无证据」,不拦。
  11. 修 F2:

    • 正式运行带图接着跑,一律拒绝(409,formal_graph_locked);
    • 接着跑不再改 started_by,接着跑的人只记在 run.resumed 事件里。

理由

  • P2;
  • P6:流程骨架在图里,人在应用里;
  • 守住「不做节点级锁、单进程」。

否决的做法

  • 引入 BPMN 引擎;
  • 在引擎层做会签(一次挂起多个中断);
  • 把具体的人写进图里;
  • 给 agent 一个半路询问的工具(会撞上 F9)。

代价:人工节点的配置变多;组成员按快照展开,之后加入组的人不会补派。

2.5 A5 动作:写外部系统

决定

  1. 写入能力只能放在调用工具节点里。

    • build_tools(..., allow_write=False) 默认拒绝写入能力,agent、协作节点的代码都不用动;
    • 只有调用工具节点传 allow_write=True;
    • 发布检查再拦一道(action.write_in_agent)。
  2. 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 加一后再发
  3. 按引用确认:看过的就是发出去的。

    • 确认卡显示遮罩后的预览和 payload_hash;
    • 恢复时,节点重新渲染参数、重算哈希,和确认时的哈希对不上就拒绝发送;
    • 动作确认不接受改参数(args 不理),要改就在上游的表单里改。
  4. 结果未知。

    • 节点抛 ActionPending,运行收成 interrupted(挂起,不封存),发 action.unknown;
    • 登记了查询能力的:调度循环每拍跑 actions.tick,带退避去查;
    • 没登记的:开一条核实待办,派给应用的 reconciler 岗位。选项是「已生效(填外部单号)」、「未生效,重新发送」、「未生效,放弃」;
    • 核实之后,系统自动接着跑;
    • 结果未知永远不会自动重发。
  5. 环境。

    • 正式运行走 prod;
    • 探索运行走 test;端点没有 test 环境时走演练:不发请求,记 simulated,回执标 simulated: true(Q4)。
  6. 不新增运行类别。 运行类别说的是图从哪里来;写没写外部系统,是运行里发生的事,记成这次运行的生效记录。

理由

  • P1;
  • P8;
  • 守住「不加锁」:幂等靠数据库记录,不靠锁。

否决的做法

  • 在节点里等核实:会撞上 F9;
  • 让引擎重试:会重复生效;
  • 让前端直接调外部系统;
  • 新增一类 action 运行。

代价:多了一种挂起状态,定时任务通知的 _state_of(webhook.py:720)要能认出它。

2.6 A6 能力登记

决定

  1. capabilities 表 = 系统同步的部分 + 人工治理的叠加层。

    • 主键沿用图里工具的名字(tools/registry.py:142 build_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。
  2. 登记的端点(endpoints)。

    • 按 test / prod 两个环境分别存 base_url 和认证头(加密);
    • allow_intranet 只能由管理员开,而且只有登记的端点能访问内网;开了也照样拦元数据地址和高危端口(net.py:17);
    • 模型给出的地址照旧走完整的 SSRF 检查(net.py:98);
    • 绑定端点的 HTTP 能力只填路径模板,参数按路径段编码代入,模型拿不到任意 URL。
  3. 凭据模式:service 和 service_on_behalf。

    • service_on_behalf 用服务凭据,另带一个 AgentLab 签发的身份断言头:EdDSA JWT,5 分钟有效,aud 写端点名,公钥在 /api/auth/jwks;
    • 不存用户自己的 token(Q3):流程一等就是几天,会超过 token 的寿命;存刷新令牌会扩大泄露面。
  4. 审批跟着登记的效果走。

    • 正式运行里:管理员声明为只读、审批策略为 none 的能力直接放行,其余照旧要审批——从根上修 F7;
    • 探索运行沿用三档信任;
    • 运行发起时,把用到的能力的治理快照放进 options["capabilities"],写进 run.started,重放时用同一份。
  5. 发布时记下能力版本(workflow_versions.capability_versions)。正式运行发起时如果有漂移只提醒、不拦,做法同数据目录漂移(launch.py:155 CATALOG_DRIFT)。

  6. 密钥(修 F13):

    • 自定义工具的 headers、MCP 的 env,值都加密,接口只回掩码;提交掩码值表示保持原值;
    • 启动时把存量的明文加密一遍(encrypt 本身是幂等的);
    • MCP 的 http 地址要么绑定端点,要么过 assert_safe_url,并支持加密的认证头;
    • MCP 的 stdio(在服务器上执行命令)只有管理员能建。
  7. 端点读取的结果可以作证。

    • 平台执行器按 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 身份

决定

  1. 三种模式(环境变量 AGENTLAB_AUTH_MODE 优先于设置页):

    • off(默认):就是今天的行为。X-Actor 自报署名,所有人等同管理员,界面上挂横幅说明;
    • local:用户名 + 密码,用 hashlib.scrypt,不加依赖;
    • oidc:授权码 + PKCE,用 httpx 和 pyjwt 的 PyJWKClient;state、nonce、verifier 用 Fernet 加密后放进短时 cookie。
  2. 会话:

    • HttpOnly、SameSite=Lax 的会话 cookie,库里只存令牌的哈希;
    • 闲置 12 小时、绝对 7 天过期;
    • 非 GET 请求必须带 X-AgentLab-Request 头,并校验 Origin;
    • 登录失败在进程内退避。
  3. 角色和授权:

    • 角色 admin ⊇ builder ⊇ user;
    • 组:本地建,或从 OIDC 的 groups 声明同步(同步来的只读);
    • 应用授权:use、observe、manage。
  4. 接入方式:

    • actor_of(api/runs.py:28)搬到 api/deps.py,改由中间件写 contextvar。开了登录,返回认证过的用户名,忽略请求头;关了登录,照旧解码 X-Actor。各接口的签名都不用改;
    • 权限挂在 main.py 的 include_router(..., dependencies=[...]) 上;证据路由按 run_id 判断能不能读这次运行;
    • WebSocket 只给 builder 及以上用;user 角色的实例页改为轮询。
  5. 留痕:发起时的 run.origin 记 actor_verified;派给人的记录上记 verified;管理类操作写审计表。

  6. 开了登录后,user 角色看到的数据一律遮罩:

    • 查询快照按派生遮罩处理;tool_snapshot 的原文不给;视图一律遮罩;
    • 从这一刻起,遮罩对 user 角色就是边界。data/engine.py 里那句「在有身份体系之前,遮罩只减少暴露,不是安全边界」要改写;README 照实写清哪些角色能看到原值。
  7. 引导与找回:

    • 从 off 切到 local 时,必须在同一个请求里建出第一个管理员;
    • 切到 oidc 时,至少配好一个管理员映射;
    • 提供 python -m app.auth reset-admin。

理由

  • P2;P4;
  • 改动面最小:只动一个函数,再加路由级依赖。

否决的做法

  • JWT 放 localStorage:WebSocket 要另想办法,还有 XSS 风险;
  • 逐个接口加鉴权:改动大,容易漏;
  • 只靠外部认证代理:拿不到 user 角色这一层的粒度。

代价:README「AgentLab 没有登录」那两段(README.md:43 起)要改写;多了一套设置和恢复流程。

2.8 A8 应用生成:先推导,再润色

决定

  1. 确定性派生 derive_app(workflow_version):

    图里的东西 派生成
    入口字段 入口表单(input_schema(fields))
    人工节点 待办表单,岗位留空等人绑定
    口径卡 指标块
    报告节点 报告块
    取数节点 表格
    写入的调用工具节点 动作确认待办 + 动作状态
  2. 助手只润色:布局、文案、控件选择。走 L1 的可插拔生成过程,接上应用操作和应用检查。岗位绑定只能由人来做,助手只留空并给出提示。

  3. 「运行后做成应用」:

    • 问数据回答上点「做成应用」→ /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、回执;
    • 「口径 → 应用」= 钉住这个版本的应用版本。
  • 用在三处:发布弹窗、退役确认、版本列表。
  • 召回(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_kind
  • ix_runs_app_id
  • ix_runs_wf_ver_status (workflow_id, version, status):找钉住版本最近一次封存的运行
  • ix_tasks_status_due (status, due_at)
  • ix_assign_principal (principal_kind, principal, status)

启动时的一次性迁移(都幂等):

  1. 把自定义工具 headers、MCP env 里的明文加密;
  2. 同步能力登记;
  3. 为存量的待审批补建 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=&params=

返回:

{
  "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 流程

  1. 开分支。 从最新 main 开集成分支 feat/app-platform,各包用自己的 worktree 和分支。本文仍放在 docs/design/ 下,不跟踪;要提交时先按附录 D 做匿名核对。

  2. 第 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' 那一行。
  3. 构建。 一个 workflow,6 个包,每包一个完整的代理,并行。每个包交付:代码、测试、自己的检查脚本、README 片段、「契约偏差」清单。

  4. 统一复核。 一个复核代理读全部差异,对照这些项检查:

    • P1–P8;
    • 五条不可回退的决定;
    • 附录 C 的契约;
    • 文件归属;
    • 文案规范;
    • 遮罩与权限。

    出各包的修正单,由各包自己改。

  5. 合并与集成修正。 编排者按 BE-1 → BE-3 → BE-2 → BE-4 → FE-5 → FE-6 的顺序合并,把桩换成真实现,接通 TaskCard、SchemaForm,按各包的片段汇总 README。

  6. 完整关口。 跑一次(§6.3)。

  7. 验收(第七部分),问用户之后再合 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 定时任务上的看板应用

准备:

  1. 用上传表格建一个源(数据版本固定,结果可复现);
  2. 工作流:取数 → 口径卡 → 报告 → 成果,受管级发布 v1,配好定时任务;
  3. 从 v1 派生应用,发布,授权给 user 角色;
  4. 「立即运行」两次。

验收点:

  • 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 被忽略,审计照实记录。
  • 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 待办通知 只用 Webhook 的四种格式,不做邮件 已修订(2026-10,next-round/00-总方案.md X12、04 B2):加邮件——SMTP 可选、口令加密存、只确认交给了邮件服务器、退信不追踪(照实写);个人邮件渠道只发到账号邮箱;默认发给待办处理人由管理员开关、缺省关 原理由:发送核心现成可用;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 须管理员先登记端点。