[English](../en/apps.md) | 简体中文 # 应用 这篇讲把已发布的工作流做成应用：怎么生成和发布、视图和印章、流程和待办、写外部系统，以及对外集成（入站钩子、访问密钥、分享链接）。给搭建者、管理员和用应用的人看。 ## 应用是什么 工作流发布出去之后，看数的人、办事的人在「应用」里用它。 - 应用不是新引擎，也不是嵌进来的低代码平台。每个数都来自固定版本封存的正式运行；每次发起，都是固定版本的一次正式运行。 - 界面层不放逻辑：绑定只取已有的值；可见条件只能比较、做布尔运算、取值和 `in`，没有算术。求值都在服务端，不可见的组件和遮罩值不出服务端。 - 应用另有三档授权：使用、查看全部实例、管理（见[身份、权限与安全](identity-and-security.md#角色与授权)）。 ## 生成一个应用 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`）。 - 驳回的处理和驳回出口见[工作流](workflows.md#驳回)。 ## 写外部系统 写入能力只能放在「调用工具」节点里。 - 先写生效记录，再发送。同一次执行发第 n 次的幂等键是 `{action_key}:{n}`。 - 确认卡显示遮罩后的预览和内容哈希。发送前重算哈希比对；确认之后上游变了，就拒发。 - 结果未知时，运行挂起，不封存。登记了查询能力的，自动按幂等键核实；没有的，开一条核实待办（已生效并填外部单号 / 未生效重新发送 / 未生效放弃）。 - 结果未知的写入永远不会自动重发。 - 正式运行写生产环境；探索运行写测试环境，没有测试环境时演练，不发请求。 - 有生效记录的运行不能删除。 端点怎么登记见[工具](tools.md#登记端点)。验收时可以用假的外部系统模拟各种结果（见[开发](development.md#验收用的假外部系统)）。 ## 填报登记与附件 填报登记的每次提交，是平台托管的记录表里的一行（`data/records/`，一个表版本一个 SQLite 文件，只许追加）。 - 写入只经「调用工具」节点的平台能力 `records_append`，同一次提交只落一行。 - 更正是追加一行并指向原行，原行不改。更正的那一行仍记原提交人（他照样看得见），动手更正的人记进动作记录和审计。 - 看板用 `db_query__<记录表>` 查。一次运行只看得到开始时已有的记录。 - 使用者逐行只看得到自己提交的（「记录列表」组件）；正式运行里的汇总是全量的。 - 表单只加可选字段时，在同一版本里加列；改类型、删字段、加必填字段时出新版本，旧记录照原样保留。看板查新一版时，旧版本只读，并入同一张 `records`（旧版本没有的字段、类型对不上的字段为空），各版本都按运行开始时的记录固定。 - 新一版发布之前已经发起、还在半路的实例，照常写完旧版本；之后发起的只写新一版。 - 记录表的写入全站一个接一个（多进程时是库里的锁），适合人工填报的频率，不适合每秒多次的高频写入。 - 表单里的附件先上传（`data/files/`，按内容哈希存、只读），提交时绑到这次运行。读得到那次运行或那一行记录的人才能下载。上传后 24 小时没提交的自动清理。 ## 按新口径补算 固定版本升版、处置选了「按新口径重算」时，管理者可以点「按新口径补算历史」： - 取旧版本在同一来源上最近几期的输入，用新版本逐个发起正式运行，来源记为按新口径补算。 - 同一输入算过的跳过。 - 有外部副作用的工作流（流程、人工节点、写外部系统）不补算。 ## 升级时流程实例怎么办 流程实例可能一等几天，中间升级是常态。 - 停在人工节点、停在写入节点开头等确认的实例，升级后都能继续。 - 写入结果未知的，核实后继续，不会重发。 - 停在 Agent 半路审批的实例，升级后无法继续。所以发布时 `process.wait_mid_agent` 会提醒；应用按流程引用这样的工作流时，直接拦下。 ## 个人应用 在蓝图上点「存成我的应用」，做出只给拥有者自己看的个人应用。 - 使用者要管理员在「设置 → 偏好设置」的「应用」一节里开启后才能建。 - 个人应用的图和使用者的问数据用同一份白名单。周期看板、异常处置（只看清单）这些模板的取数节点，就是查数据源的调用工具节点。 - 每次刷新是一次探索运行：查询结果在工具边界先遮罩，数据源一律只读，和按需视图共用每人每天的次数上限。 - 刷新和个人蓝图的试运行只有拥有者读得到：管理员、搭建者也看不到这些运行、证据、工件和附件，运行列表里不列。 - 管理员在应用列表里只看得到名称、拥有者、创建和更新时间，可以归档，看不到页面和蓝图。 - 个人应用没有入口表单，刷新不带附件。要随表单交附件，请「提交审核」，由搭建者做成正式应用。 共享蓝图可以读、改、试运行、出发布单：管理员都能做；搭建者限自己建的、自己管理的应用出自的蓝图（见[权限表](identity-and-security.md#权限表)）。 ## 对外集成 ### 入站钩子 - 在 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 天各提醒一次（开了登录时）。 ```bash 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//entries/ ``` ### 视图数据接口 `GET /api/apps/{app_id}/views/{view_id}/data` 返回印章、清单哈希和口径卡指标的原值（遮罩的为 `null`）。可以拿清单哈希去对照可验证报告。完整的接口清单和错误码在「设置 → 访问密钥 → 接口说明」。 ### 分享链接 要给没有账号的人看一个看板时，用分享链接。 1. 管理员在「设置 → 偏好设置」的「应用」一节打开「允许建分享链接」（缺省关）。 2. 能管理这个应用的人在应用编辑的「岗位与授权」里建分享链接。 - **看什么**：只看定时出数的视图（最近一次封存的正式运行）。可以选「始终最新」或「固定这一期」（建分享时的那一期）。按需视图、实例、入口表单不显示，也不会因为有人打开而发起运行。流程组件、报告正文换成说明块，正文和出处在「下载报告」里。 - **链接**：`/s#`。key 在 `#` 后面，不进服务器日志，也不随 Referer 带出去；库里只存哈希。到期必填，最长 90 天，可以撤销。撤销、到期、应用不再发布时，打开回 410 并写明原因。管理员关掉开关后，已有的分享链接也一并打不开。 - **留痕**：建、撤销写审计；打开只计次数。访问密钥调不了分享接口。 ### 嵌入门户 - 页面默认只能被本站嵌入：`frame-ancestors 'self'`，另加 `X-Frame-Options: SAMEORIGIN`。 - 同站的门户（同一个可注册域名下）要嵌整站时，把门户地址写进 `AGENTLAB_FRAME_ANCESTORS`，登录照常。 - 跨站的门户嵌整站不支持（浏览器不把会话 cookie 带进跨站的 iframe），请用分享链接。 - 分享页允许被哪些站点嵌，由 `AGENTLAB_EMBED_ORIGINS` 定；建分享时没勾「允许嵌入到别的站点」的那一条，在 iframe 里不显示内容。 ### 错误码 集成方要用的接口（应用、待办、工件、角色拒绝）的错误一律带机读码 `code`；`detail` 是给人看的原话，可能会改。