mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-15 00:21:58 +00:00
ThearchyHelios
2714890d0d
README.zh-CN.md / README.md 只留：这是什么、为什么用它、主要功能（按领域一行一条，链到文档）、快速开始、部署、文档索引、 开发与测试、许可（原文不动）。原来的每一节按读者和任务分到 17 篇主题文档：ask-data、workflows、evidence、 data-sources（新增：接入数据库、只读保证、上传表格、跨库合并、遮罩列）、data-catalog、tools（新增：工具、审批档位、 能力登记、端点、网络规则——它们管所有工作流，不只应用）、apps、evaluation-and-ledger、schedules（含通知）、deployment、 configuration、postgresql-and-scaling、identity-and-security、architecture、development、upgrade-notes（按时间倒序， 每波先写要做的事）、faq。删掉的只有模块名（api/copilot_gen.py、chat/drive.py、data/schema_view.py）、重复的话和 「以前…现在…」的叙述；操作步骤、命令、配置名、限制、权限边界都有归宿。中文是原文，英文按新的中文写；英文里界面文字 只写英文名，开头注明界面目前只有简体中文，中文占位符换成英文占位符，中文数字的例子改成不依赖中文的说法。 数据剖析可以同时剖析 2–3 张表（baf23998）收进 data-catalog。 新增 scripts/check-docs.py：英文文档（README.md、docs/en/**）不许有中日韩字符和全角符号（代码块也算）， README、docs/**、deploy/README.md 的相对链接和锚点都要通，docs/zh-CN 与 docs/en 文件一一对应、标题层级相同。 中文提示里指向 README 章节的地方改指新文档：cluster/guard.py、cluster/version.py、db/base.py 两处报错， data/schema_view.py 文档串，.env.example 三处，scripts/prod.sh、scripts/test-postgres.sh，terms.ts 两处、 DataSourcesTab.tsx、check-manage.mjs 注释，deploy/README.md 三处链接。deploy/agentlab.env 未动。 验收：check-docs 0 问题（英文文档 18 个 0 处中文，相对链接 369 条 0 断链，18 对标题层级一致）；相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。
190 lines
13 KiB
Markdown
190 lines
13 KiB
Markdown
[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/<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` 是给人看的原话，可能会改。
|