From c28fc336a2ceeaa5897dd417f275c2cb3d651926 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Fri, 16 Oct 2026 15:39:32 +0800 Subject: [PATCH] =?UTF-8?q?README=EF=BC=9A=E7=AC=AC=202=20=E6=B3=A2?= =?UTF-8?q?=E7=9A=84=E5=8D=87=E7=BA=A7=E8=AF=B4=E6=98=8E=EF=BC=88=E5=90=8E?= =?UTF-8?q?=E5=8F=B0=E6=8E=A2=E6=9F=A5=E4=B8=8E=E6=8E=A2=E6=9F=A5=E8=8C=83?= =?UTF-8?q?=E5=9B=B4=E3=80=81db=5Fschema=20=E7=9A=84=E6=A3=80=E7=B4=A2?= =?UTF-8?q?=E4=B8=8E=E6=8C=89=E9=9C=80=E5=8A=A0=E5=85=A5=E3=80=81=E5=B0=81?= =?UTF-8?q?=E5=AD=98=E5=90=8E=E6=AF=94=E5=AF=B9=E5=8F=A3=E5=BE=84=E3=80=81?= =?UTF-8?q?=E5=AF=BC=E5=87=BA=E5=AE=A1=E8=AE=A1=E4=B8=8E=E6=9D=A5=E6=BA=90?= =?UTF-8?q?=E9=93=BE=EF=BC=89=EF=BC=9B=E8=BA=AB=E4=BB=BD=E4=B8=8E=E6=9D=83?= =?UTF-8?q?=E9=99=90=E5=8A=A0=E3=80=8C=E8=AE=BF=E9=97=AE=E5=AF=86=E9=92=A5?= =?UTF-8?q?=E3=80=8D=E4=B8=80=E8=8A=82=E5=92=8C=20curl=20=E7=A4=BA?= =?UTF-8?q?=E4=BE=8B=EF=BC=9B=E6=95=B0=E6=8D=AE=E7=9B=AE=E5=BD=95=E5=8A=A0?= =?UTF-8?q?=E3=80=8C=E5=A4=A7=E5=BA=93=EF=BC=9A=E6=8E=A2=E6=9F=A5=E8=8C=83?= =?UTF-8?q?=E5=9B=B4=E4=B8=8E=E6=8C=89=E9=9C=80=E5=8A=A0=E5=85=A5=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/README.md b/README.md index d890233e..fcd95b8f 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,18 @@ http://127.0.0.1:8000 。前端产物不存在或比源码旧时才重新构建 取值，日期列写明排除了几个无效日期，所以升级后第一次重新剖析，这些表的目录各升一次版本。剖析设置的「抽样键值数」改叫 「核对键值数」（`DISTINCT … LIMIT` 取的不是随机样本）。 +**从旧版本升级（2026-10 下一轮第 2 波）**： + +- 探查结构改成后台任务（和同一个数据源的起草、剖析排队）。升级后每个数据源点一次「探查结构」，建立对象索引；老的表结构 + 在探查读完之前原样保留。超过 500 张表、又没设探查范围的库，第一次探查会被拒绝并说出命中了多少张，要先在「探查范围」里 + 设规则或调高上限（最多 2,000）。正式探查不再接受 `?schema=` 临时换 schema（一个数据源一个 schema），预览照旧可以。 +- 运行时的 `db_schema__` 不传表名时只列前 50 张，并说清另有多少张；可以用 `keyword` 检索，点名探查范围外的表会当场读结构、 + 加进范围（每次运行最多 8 张，留痕）。 +- 探索运行封存后会在后台比对已发布的口径，追加一条封存后事件 `ledger.matched`：时间线、可验证报告的「封存后追加」里 + 多出这一条，不在封存范围内。启动时补比最近 7 天的运行，跟着 `AGENTLAB_SCHEDULER` 开关。 +- 报告导出和可验证报告下载各记一条审计 `report.exported`。问数据发起的运行带上所在对话和轮次（`origin_ref`）， + 「在画布里打开」建的工作流记下来自哪一轮。 + --- ## 核心能力 @@ -416,6 +428,28 @@ cd backend && python -m app.auth reset-admin --username admin # 不给 --passw 原文、运行事件里的结果预览一律不给，工件按白名单给。对搭建者、管理员，以及未开启登录时的所有人，遮罩只减少暴露， 完整快照仍能按工件 id 取到。管理类操作（登录方式、用户和角色、组、端点、能力治理、应用发布、版本退役）写进审计。 +### 访问密钥 + +外部系统（门户、OA、BI）用访问密钥调接口，只在开了登录时生效： + +- **谁能持有**：服务账号（管理员在「设置 → 访问密钥」建，`svc-` 开头，没有口令、不能登录、不能被派待办）；个人访问密钥 + 要管理员打开开关（缺省关），本人在同一页建。密钥只在建、轮换时显示一次，库里只存哈希；到期必填（最长 365 天，缺省 90 天）， + 轮换时旧钥 24 小时后到期，撤销立刻失效，拥有者停用后一并失效。 +- **能做什么**：一律按使用者的权限算——只看得到授权给拥有者（或所在组、所有人）的应用，看到的数据一律遮罩，管理员的密钥也 + 一样。权限按接口白名单给（读应用和视图、发起入口、刷新视图、读待办、回复待办、读报告；新建时缺省只勾读的），白名单外的 + 接口一律 403。发起入口、刷新视图必须带 `Idempotency-Key`，外部系统超时重发不会多发起一个。回复待办只给个人密钥，只限审批、 + 补充输入、编辑稿件。每把密钥每分钟 120 次。 +- **留痕**：建、撤销、轮换、开关都写审计；每次请求记一条（保留 90 天）；用密钥发起的运行在 `run.origin` 里记是哪把密钥。 +- **视图数据**：`GET /api/apps/{app_id}/views/{view_id}/data` 给印章、清单哈希和口径卡指标的原值（遮罩的为 `null`），可以拿 + 清单哈希去对照可验证报告。完整的接口清单和错误码在「设置 → 访问密钥 → 接口说明」。 + +```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/ +``` + ## 能力登记与端点 「工具 → 能力」把内置工具、数据源、自定义工具、MCP 工具登记在一处，名字就是图里的工具名。启动时和各对象增删改时 @@ -478,6 +512,14 @@ cd backend && python -m app.auth reset-admin --username admin # 不给 --passw --- +### 大库：探查范围与按需加入 + +几千张表的库不必全部读进来。探查先建一份全库的对象索引（每种数据库一条字典查询：名字、类型、注释、估算行数），再按 +「探查范围」的规则（通配、排除优先，缺省最多 500 张、上限 2,000）读范围内的表；有数据目录的表、已发布模板写死 SQL 用到的 +表一律在范围内。助手查看和运行时的 `db_schema__` 先按需求检索（BM25，遮罩列只用列名），点名范围外的表会当场只读地读结构、 +加进范围并留痕。「表已不在」只在真删除时说，范围外、读不到结构、索引里从来没有，各自分开说。剖析得到的行数和日期范围也 +交给助手和 agent，附一句「只供写查询参考，不能作为回答里的数」，遮罩按当时的设置重滤。 + ### 助手按需查看 以前每一轮开始前，服务端按库的大小把表结构塞进助手的 system：说一句「你好」也要先挑表，再带着上万字的表结构去