AgentLab/docs/zh-CN/apps.md

English | 简体中文

应用

这篇讲把已发布的工作流做成应用：怎么生成和发布、视图和印章、流程和待办、写外部系统，以及对外集成（入站钩子、访问密钥、分享链接）。给搭建者、管理员和用应用的人看。

应用是什么

工作流发布出去之后，看数的人、办事的人在「应用」里用它。

• 应用不是新引擎，也不是嵌进来的低代码平台。每个数都来自固定版本封存的正式运行；每次发起，都是固定版本的一次正式运行。
• 界面层不放逻辑：绑定只取已有的值；可见条件只能比较、做布尔运算、取值和 in，没有算术。求值都在服务端，不可见的组件和遮罩值不出服务端。
• 应用另有三档授权：使用、查看全部实例、管理（见身份、权限与安全）。

生成一个应用

1. 在画布上发布工作流，在发布成功的提示里点「做成应用」。也可以在问数据的回答上点「做成应用」：先把这次运行提取成工作流（只保留实际执行的步骤），在画布上发布，再从发布成功的提示进来。
2. 系统按这一版确定性地派生出应用草稿，不调模型：
   • 入口字段生成表单；
   • 口径卡生成指标块，报告生成报告块，取数节点生成表格；
   • 人工节点生成待办，岗位留空等人绑定；
   • 写外部系统的调用工具节点生成动作确认和动作状态；
   • 视图优先绑定已有的定时任务。
3. 在应用编辑里调整：页面树和属性面板、按草稿预览（不发起运行）、检查。右侧的助手只能润色布局、文案和控件，改不了固定的版本、入口映射和表单的数据约束。
4. 绑定岗位到人或组（流程类应用必须绑定），设置授权、入站钩子和通知订阅，然后发布。

固定的工作流版本比上一版应用新时，发布时要为它选一种处置：「按新口径重算」「两版并列」「前后不可比」。

能做哪几类应用

类型	用到的能力
数据看板	视图读定时任务最近一次封存的正式运行：印章、指标块、多期趋势（按升版处置画）、表格、折线 / 柱状图、报告
参数化报表	入口表单发起一次正式运行，在实例页看结果；或者页面上的参数表单按需运行并缓存
审批流程	待办派给岗位 / 发起人 / 表达式算出的人，任一人 / 全体 / 至少 m 人，时限与升级，待办箱、「我发起的」
写回外部系统	调用工具节点写登记的端点，确认卡是遮罩后的预览和内容哈希，结果未知转人工核实
外部系统触发 / 回调	签名的入站钩子：发起实例，或者回调「等外部系统」的那一步
混合	看板上发起处置流程，最后写回系统

视图与印章

每个视图带一枚印章，写明：

• 截至何时（含统计期、数据版本）；
• 哪一版口径（工作流名 vN · 哈希前 8 位，加口径卡的口径名和版本）；
• 哪一档出具；
• 数据从哪来（定时任务「…」第 n 次 / 按需运行 / 本实例）。

定时任务已改跑新版本、应用还固定在旧版本时，印章照实写明。

视图读「最近一次封存」时，只认定时任务、应用入口、按需视图、画布或版本页上的「正式运行」、入站钩子和访问密钥发起的正式运行。按口径出具、补算出来的运行不会顶替看板上的数。

按需视图：

• 默认点「刷新」才运行。
• 同一组参数在进程里同时只运行一份。
• 查活库的视图必须设时效。
• 每个应用每天有次数上限（设置项 apps.on_demand_daily_limit，默认 200）。

流程与待办

• 一次中断对应一条审批（给引擎）和一条待办（给人）。所有人的决定经待办服务汇总，凑齐了才恢复一次运行。
• 图里只写岗位名；岗位绑定到人或组在应用里做。没有应用的运行（画布、定时任务）派给任何人。
• 老接口 /api/approvals/{id}/decide、/api/runs/{id}/resume 照旧可用。
• 时限由调度循环每 15 秒检查一次。调度关着（AGENTLAB_SCHEDULER=0）时，不提醒、不升级、不自动核实。
• 开了登录时，应用入口和待办表单里的选人控件按候选池核对（缺省是能用这个应用的人），池外的名字回 422（principal）。
• 驳回的处理和驳回出口见工作流。

写外部系统

写入能力只能放在「调用工具」节点里。

• 先写生效记录，再发送。同一次执行发第 n 次的幂等键是 {action_key}:{n}。
• 确认卡显示遮罩后的预览和内容哈希。发送前重算哈希比对；确认之后上游变了，就拒发。
• 结果未知时，运行挂起，不封存。登记了查询能力的，自动按幂等键核实；没有的，开一条核实待办（已生效并填外部单号 / 未生效重新发送 / 未生效放弃）。
• 结果未知的写入永远不会自动重发。
• 正式运行写生产环境；探索运行写测试环境，没有测试环境时演练，不发请求。
• 有生效记录的运行不能删除。

端点怎么登记见工具。验收时可以用假的外部系统模拟各种结果（见开发）。

填报登记与附件

填报登记的每次提交，是平台托管的记录表里的一行（data/records/，一个表版本一个 SQLite 文件，只许追加）。

• 写入只经「调用工具」节点的平台能力 records_append，同一次提交只落一行。
• 更正是追加一行并指向原行，原行不改。更正的那一行仍记原提交人（他照样看得见），动手更正的人记进动作记录和审计。
• 看板用 db_query__<记录表> 查。一次运行只看得到开始时已有的记录。
• 使用者逐行只看得到自己提交的（「记录列表」组件）；正式运行里的汇总是全量的。
• 表单只加可选字段时，在同一版本里加列；改类型、删字段、加必填字段时出新版本，旧记录照原样保留。看板查新一版时，旧版本只读，并入同一张 records（旧版本没有的字段、类型对不上的字段为空），各版本都按运行开始时的记录固定。
• 新一版发布之前已经发起、还在半路的实例，照常写完旧版本；之后发起的只写新一版。
• 记录表的写入全站一个接一个（多进程时是库里的锁），适合人工填报的频率，不适合每秒多次的高频写入。
• 表单里的附件先上传（data/files/，按内容哈希存、只读），提交时绑到这次运行。读得到那次运行或那一行记录的人才能下载。上传后 24 小时没提交的自动清理。

按新口径补算

固定版本升版、处置选了「按新口径重算」时，管理者可以点「按新口径补算历史」：

• 取旧版本在同一来源上最近几期的输入，用新版本逐个发起正式运行，来源记为按新口径补算。
• 同一输入算过的跳过。
• 有外部副作用的工作流（流程、人工节点、写外部系统）不补算。

升级时流程实例怎么办

流程实例可能一等几天，中间升级是常态。

• 停在人工节点、停在写入节点开头等确认的实例，升级后都能继续。
• 写入结果未知的，核实后继续，不会重发。
• 停在 Agent 半路审批的实例，升级后无法继续。所以发布时 process.wait_mid_agent 会提醒；应用按流程引用这样的工作流时，直接拦下。

个人应用

在蓝图上点「存成我的应用」，做出只给拥有者自己看的个人应用。

• 使用者要管理员在「设置 → 偏好设置」的「应用」一节里开启后才能建。
• 个人应用的图和使用者的问数据用同一份白名单。周期看板、异常处置（只看清单）这些模板的取数节点，就是查数据源的调用工具节点。
• 每次刷新是一次探索运行：查询结果在工具边界先遮罩，数据源一律只读，和按需视图共用每人每天的次数上限。
• 刷新和个人蓝图的试运行只有拥有者读得到：管理员、搭建者也看不到这些运行、证据、工件和附件，运行列表里不列。
• 管理员在应用列表里只看得到名称、拥有者、创建和更新时间，可以归档，看不到页面和蓝图。
• 个人应用没有入口表单，刷新不带附件。要随表单交附件，请「提交审核」，由搭建者做成正式应用。

共享蓝图可以读、改、试运行、出发布单：管理员都能做；搭建者限自己建的、自己管理的应用出自的蓝图（见权限表）。

对外集成

入站钩子

• 在 spec 里按名字声明钩子：发起实例，或回调待办（「等外部系统」那一步）。
• 在应用编辑里生成密钥，只显示一次。
• 外部系统向 /api/hooks/{钩子 id} 发签名请求：带 X-AgentLab-Timestamp 和 X-AgentLab-Signature: sha256=HMAC-SHA256(密钥, "时间戳." + 请求体)；时间窗 5 分钟；Idempotency-Key 必填。
• 钩子做什么，以应用当前发布版的声明为准。没发布或已停用的钩子，请求拒收。

访问密钥

外部系统（门户、OA、BI）用访问密钥调接口。只在开了登录时生效。

谁能持有

• 服务账号：管理员在「设置 → 访问密钥」建，svc- 开头；没有口令，不能登录，不能被派待办。
• 个人访问密钥：要管理员打开开关（缺省关），本人在同一页建。
• 密钥只在建、轮换时显示一次，库里只存哈希。到期必填：最长 365 天，缺省 90 天。
• 轮换时旧钥 24 小时后到期；撤销立刻失效；拥有者停用后一并失效。

能做什么

• 一律按使用者的权限算：只看得到授权给拥有者（或所在组、所有人）的应用，看到的数据一律遮罩。管理员的密钥也一样。
• 权限按接口白名单给：读应用和视图、发起入口、刷新视图、读待办、回复待办、读报告。新建时缺省只勾读的；白名单外的接口一律 403。
• 发起入口、刷新视图必须带 Idempotency-Key，外部系统超时重发不会多发起一个。
• 回复待办只给个人密钥，只限审批、补充输入、编辑稿件。
• 每把密钥每分钟 120 次。

留痕

• 建、撤销、轮换、开关都写审计；每次请求记一条，保留 90 天。
• 用密钥发起的运行，在 run.origin 里记是哪把密钥。
• 访问密钥到期前 7 天、1 天各提醒一次（开了登录时）。

curl -H "Authorization: Bearer agl_…" https://agentlab.example/api/auth/me
curl -H "Authorization: Bearer agl_…" -H "Idempotency-Key: order-20261016-001" \
     -H "Content-Type: application/json" -d '{"input": {…}}' \
     https://agentlab.example/api/apps/<app_id>/entries/<entry_id>

视图数据接口

GET /api/apps/{app_id}/views/{view_id}/data 返回印章、清单哈希和口径卡指标的原值（遮罩的为 null）。可以拿清单哈希去对照可验证报告。完整的接口清单和错误码在「设置 → 访问密钥 → 接口说明」。

分享链接

要给没有账号的人看一个看板时，用分享链接。

1. 管理员在「设置 → 偏好设置」的「应用」一节打开「允许建分享链接」（缺省关）。
2. 能管理这个应用的人在应用编辑的「岗位与授权」里建分享链接。

• 看什么：只看定时出数的视图（最近一次封存的正式运行）。可以选「始终最新」或「固定这一期」（建分享时的那一期）。按需视图、实例、入口表单不显示，也不会因为有人打开而发起运行。流程组件、报告正文换成说明块，正文和出处在「下载报告」里。
• 链接：/s#<key>。key 在 # 后面，不进服务器日志，也不随 Referer 带出去；库里只存哈希。到期必填，最长 90 天，可以撤销。撤销、到期、应用不再发布时，打开回 410 并写明原因。管理员关掉开关后，已有的分享链接也一并打不开。
• 留痕：建、撤销写审计；打开只计次数。访问密钥调不了分享接口。

嵌入门户

• 页面默认只能被本站嵌入：frame-ancestors 'self'，另加 X-Frame-Options: SAMEORIGIN。
• 同站的门户（同一个可注册域名下）要嵌整站时，把门户地址写进 AGENTLAB_FRAME_ANCESTORS，登录照常。
• 跨站的门户嵌整站不支持（浏览器不把会话 cookie 带进跨站的 iframe），请用分享链接。
• 分享页允许被哪些站点嵌，由 AGENTLAB_EMBED_ORIGINS 定；建分享时没勾「允许嵌入到别的站点」的那一条，在 iframe 里不显示内容。

错误码

集成方要用的接口（应用、待办、工件、角色拒绝）的错误一律带机读码 code；detail 是给人看的原话，可能会改。