@lark-base-open/base-database-cli 1.4.0 → 1.4.5

package/skills/lark-base-database/references/agent-tool-design.md

@@ -0,0 +1,181 @@
+# 面向 Agent 的函数与参数设计
+
+写或修改 Database Function、Mutation、FaaS 的函数说明和参数声明前读取本文；`check` 或 `deploy` 返回 `functionHints` 时回到本文自查。执行、权限与返回协议仍以 [Database Function](database-function.md)、[Mutation](mutations.md)、[FaaS](faas.md) 为准。
+
+[外部 Agent](../SKILL.md#术语) 看不到页面源码，只根据函数 `name`、`description` 和服务端按参数声明生成的 `inputSchema`、`parameters[]` 选择函数并填写参数。目标是调用者一次选对函数、一次填对参数。
+
+## 原则、判定与默认路径
+
+| 原则 | 判定 | 默认路径 | 例外 |
+| --- | --- | --- | --- |
+| 函数可区分 | 调用者能否在相邻函数间选对 | 函数 `description` 写用途、何时用、何时不用及改用哪个相邻函数 | 没有易混淆的相邻函数时写明适用边界，不列无关函数 |
+| 说明业务含义与来源 | 只看声明能否填出值 | `name` 稳定可读；`description` 写对象、单位、取值步骤与空值效果 | 不知道值从哪里来时请用户或作者补充，不猜函数 |
+| 固定选项结构化 | 选项是否由作者限定且固定 | 写标准 `enum`，Page 复用 CLI 生成的类型和选项常量 | 动态值用只读字典或查询函数取得，在 `description` 说明调用步骤；`DISTINCT` 只含已使用值，不代表全部选项 |
+| ID 与显示名分开 | 参数接受记录 ID 还是名称 | `description` 写先调哪个已开放函数、取哪个返回字段 | 同名多条时让用户选择，不用标题代替 ID |
+| 条件约束可判定 | 必填是否依赖另一个参数 | FaaS 用 `oneOf` 分支表达条件必填，每个顶层属性都有 `description` | 分支表达不清时拆成多个函数；跨字段业务关系（如日期先后）留给 handler 校验 |
+| 空值效果明确 | 缺失、`null`、空串是否同义 | 按真实执行语义说明；Mutation 可选参数缺失或 `null` 表示跳过写入 | 清空使用声明中明确的 `clear`，不把 `null` 写成清空 |
+| 错误可修复 | 调用者能否定位参数并判断是否已执行 | 未执行的错误返回非 0 码和按模板写的 `msg` | 已完成或已受理时遵循[结果与错误](#结果与错误) |
+
+## 平台检查与提示
+
+`check` 和 Preview `deploy` 在本地拒绝：SQL `meta.params[]`、Mutation `spec.params[]` 缺少 `name` 或 `description`、`name` 重复或不符合 `^[A-Za-z][A-Za-z0-9_]{0,63}$`；`enum` 为空、重复、含 `null` 或类型与参数 `kind` 不一致；FaaS `inputSchema` 顶层不是 `object`，或某个顶层属性缺少 `description`。保存到服务端时，有可证明的绑定域才会用当前 Catalog 检查 `enum` 是否在字段的选项范围内。
+
+函数级 `description` 缺失、为空白或去除首尾空白后少于 8 个字符只是提示；参数描述仍必须非空，少于 8 个字符只是提示，不阻断发布；平台不比较 `description` 与 `name`，也不判断自然语言质量。参数绑定关联记录或选项字段时，服务端在 `deploy` 结果的 `functionHints` 中提示补充取值方式。提示消失不代表语义正确，仍按下文自检。
+
+`enum_unchecked` 表示本次分析未取得足够的 Catalog 域证据，不表示声明的选项错误。例如 `$1 IS NULL OR 字段.name = $1` 的可选筛选会保守地不给域证明。默认核对真实字段选项、参数绑定与业务语义，保留正确的 `enum` 和查询；确有不一致时修正声明，不以消除提示为由改掉筛选或空值语义。
+
+服务端从参数声明生成命名对象 `inputSchema`；未声明 `enum` 的选项参数在有绑定证据时获得选项摘要前缀，记录 ID 参数的说明使用作者原文。作者写明业务含义和取值步骤，不手写 SQL 或 Mutation 的 Schema。
+
+## 函数说明：何时用、何时不用
+
+函数级 `description` 写四件事：用途、何时用、何时不用、此时改用哪个相邻函数。相邻函数指同站点中参数或用途相近、容易被误选的函数。
+
+反例：两个函数都只写“查询休假”，调用者无法区分。
+
+```json
+{"name":"listLeaveByIntent","description":"查询休假"}
+```
+
+正例：
+
+```json
+{"name":"listLeaveByIntent","description":"按休假意向筛选全部填报。用于“谁需要休假”这类按意向的问题；要看某个报备周期的全部填报时不用本函数，改用 listTeamLeave（只读）"}
+```
+
+## 示例
+
+示例 ID 为占位值，实际使用时以 Catalog 和真实查询结果替换。
+
+### 记录 ID 与分页（Database Function）
+
+反例：只有类型，调用者会猜标题、`null` 或分页单位。
+
+```json
+{"name":"listTeamLeave","description":"查看团队休假填报","meta":{"params":[{"name":"periodId","kind":"TEXT","description":"周期"},{"name":"offset","kind":"INT","description":"偏移"}]}}
+```
+
+正例：`meta.params` 的声明顺序对应 `$1`、`$2`。
+
+```json
+{"name":"listTeamLeave","description":"查看指定报备周期的团队休假填报；按意向筛选时改用 listLeaveByIntent（只读）","meta":{"params":[{"name":"periodId","kind":"TEXT","description":"报备周期记录ID；先调用 listPeriods，从返回 rows[].period_id 选择，不传周期标题；null 不表示全部"},{"name":"offset","kind":"INT","description":"跳过的记录数，第一页传 0，每页固定 200 条，下一页递增 200"}]}}
+```
+
+外部 Agent 的调用请求体：
+
+```json
+{"params":{"periodId":"recExample123","offset":0}}
+```
+
+### 固定选项写 enum
+
+`deploy` 结果的 `functionHints` 出现“绑定选项字段”（`bound to option field`）提示时，判断选项是否由作者限定且固定：固定则依据提示核实选项并写入 `enum`，再重新 `deploy`；会变化则不写 `enum`，在 `description` 写清获取有效值的步骤。提示标记 `truncated` 或域不完整时，先取得并核实作者所需的完整选项，不能把提示中的样本当作全部选项。
+
+反例：自然语言名单不能提供机器约束。
+
+```json
+{"name":"intentName","kind":"TEXT","description":"休假意向，只能是不休假或需要休假"}
+```
+
+正例：`enum` 必须在绑定字段的选项范围内，服务端照抄进 `inputSchema`；CLI 同时生成 Page 可引用的 `DatabaseFunctionParameterOptions` 常量。数组参数（`TEXT[]` 或 Mutation `list: true`）的 `enum` 约束每个元素。
+
+```json
+{"name":"intentName","kind":"TEXT","enum":["不休假","需要休假"],"description":"本次报备的休假意向，按用户明确选择填写"}
+```
+
+workspace 运行 `contracts generate`（声明变化后再生成）与 `check` 后，在 Page 的 src 目录直接引用生成文件，不另写一份选项：
+
+<!-- example: workspace-agent-inputs -->
+```ts
+import { invokeDatabaseFunction } from '@lark-base-open/base-database-app-sdk/page';
+import { DatabaseFunctionParameterOptions } from './generated/function-inputs';
+
+const intentOptions = DatabaseFunctionParameterOptions.listLeaveByIntent.intentName;
+type IntentName = (typeof intentOptions)[number];
+export const loadByIntent = (intentName: IntentName) =>
+  invokeDatabaseFunction('listLeaveByIntent', { intentName });
+```
+
+示例中的函数 ID 和参数名必须与本地声明一致。SQL 和 FaaS 的输入类型同时进入生成的 `DatabaseFunctionInputMap`；Mutation 可从同源选项常量取字面量联合类型，workspace 使用命名对象调用。classic 示例分支和参数形态统一按[Function 调用契约](development.md#function-调用契约)判定。
+
+### 属性说明与条件必填（FaaS）
+
+反例：属性没有说明，所有字段可选，无法区分创建与关闭。
+
+```json
+{"type":"object","properties":{"action":{"type":"string"},"title":{"type":"string"},"start":{"type":"string"},"periodId":{"type":"string"}},"additionalProperties":false}
+```
+
+正例：`oneOf` 的两个分支分别声明 create 与 close 的必填项；日期先后和最长天数由 handler 校验，`pattern` 只约束格式，不能证明日期有效。
+
+```json
+{
+  "type": "object",
+  "description": "创建报备周期或关闭已有周期",
+  "properties": {
+    "action": {"type": "string", "enum": ["create", "close"], "description": "create 创建周期；close 关闭指定周期的填报"},
+    "title": {"type": "string", "minLength": 1, "description": "create 时必填，报备周期的业务名称"},
+    "start": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "create 时必填，开始日期 YYYY-MM-DD，按站点时区解释"},
+    "end": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "create 时必填，结束日期不早于开始日期，单期最多 180 天"},
+    "periodId": {"type": "string", "description": "close 时必填；先调用 listPeriods，从 rows[].period_id 选择记录 ID"}
+  },
+  "required": ["action"],
+  "additionalProperties": false,
+  "oneOf": [
+    {"type": "object", "properties": {"action": {"type": "string", "enum": ["create"]}}, "required": ["title", "start", "end"]},
+    {"type": "object", "properties": {"action": {"type": "string", "enum": ["close"]}}, "required": ["periodId"]}
+  ]
+}
+```
+
+### 可选参数跳过写入（Mutation）
+
+反例：把 Mutation 参数的 `null` 写成清空。
+
+```json
+{"name":"remark","kind":"TEXT","required":false,"description":"填报备注，null 清空备注"}
+```
+
+正例：其余表、`set` 和 `precondition` 按 [Mutation](mutations.md) 声明。
+
+```json
+{"name":"remark","kind":"TEXT","required":false,"description":"填报备注；缺失或 null 跳过写入并保留原值；清空需使用作者提供的 clear 操作"}
+```
+
+```json
+{"params":{"recordId":"recExample123","remark":null}}
+```
+
+FaaS 底层记录接口的 `null` 清空语义不适用于 Mutation 参数。写入成功后仍检查 `record_not_found` 和 `ignored_fields`。
+
+## 结果与错误
+
+已写入部分记录或已受理任务时返回 `code=0`，在 data 中保留已完成 ID/任务 ID、状态、未完成步骤及恢复提示；code=0 不代表全部完成。确定未执行或全部失败时可返回非零业务码；结果未知时也可用非零码，但 msg 必须明确结果未知和先核对，不能声称未执行。未知结果先有限回读，不盲目重试。具体 FaaS 消费正例见[页面消费部分完成结果](faas.md#页面消费部分完成结果)。
+
+### FaaS 错误 msg
+
+平台错误默认使用固定英文段标签，无 locale 切换。作者业务错误正文不由平台翻译，可沿用业务语言；为方便 Agent 处理，建议使用下列英文段标签。参数、选项、权限或前置条件不满足而未执行时，返回非 0 `code`。外部 Agent 通过 `lark-cli api` 调用时只看到 `msg`，看不到 `data`。
+
+```text
+<Reason>. Parameter: <JSON Pointer> (received <redacted value>). Fix: <correction>; Candidates: <up to 3 values>. Executed: no. Retry: retry after fixing.
+```
+
+```json
+{"code":40001,"msg":"结束日期早于开始日期. Parameter: /params/end (received \"2027-01-10\"). Fix: 结束日期不早于 2027-02-20，单期最多 180 天. Executed: no. Retry: retry after fixing."}
+```
+
+- `msg` 原样到达调用方，整条不超过 500 字；只回显调用方本次传入的值（不超过 64 字），不写查询语句、堆栈或内部错误原文。
+- 作者可用任意非 0 业务码区分错误。外部调用入口的顶层码固定为平台的函数业务错误码，作者码放在 `data.error.upstream_code`；平台在 `msg` 末尾追加 `Business code:` 与 `LogID:`，作者不写 LogID。
+- 返回 500 或抛出未捕获异常时，调用方只看到固定的安全文案和 LogID。
+- 能用 `inputSchema` 表达的约束交给平台校验，handler 只写跨字段业务规则。
+
+## 写完自检
+
+1. 函数 `description` 写清用途、何时用、何时不用及改用哪个相邻函数。
+2. 每个参数（FaaS 为每个顶层属性）都有稳定的 `name` 和非空白 `description`。
+3. `description` 写清业务含义、单位与来源；收到过短提示后补充实质内容，不为凑长度写重复文字。
+4. 关联 ID 写明来源函数与返回字段；分页写明起点、步长与停止条件。
+5. 固定选项用 `enum` 且位于真实绑定字段的选项范围；动态取值写进 `description`，不以样本冒充全部选项。
+6. 条件必填用 `oneOf` 分支或拆分函数表达，跨字段业务规则由 handler 校验。
+7. 缺失、`null`、空串、空数组的效果写准确，Mutation 的跳过与 `clear` 分开。
+8. 未执行的错误按 msg 模板写清参数、修正与重试；部分写入或结果未知不让调用方自动重发。
+9. `check`/`deploy` 的错误先修复，`functionHints` 逐条按本文核对。

package/skills/lark-base-database/references/agent-tools.md

@@ -0,0 +1,103 @@
+# 外部 Agent 工具
+
+## 使用场景
+
+站点成员不打开页面，而是在飞书对话或自己的本地 Agent 中用自然语言，让 Agent 查询或操作站点数据。这类[外部 Agent](../SKILL.md#术语)默认可以使用本站点的全部 Database Function、Mutation、FaaS 和 AI Function；工程根目录可选的 `agent-tools.json` 声明其中哪些不向外部 Agent 开放。AI Function 的 key 也可写入 exclude。文件缺席或 `exclude` 为空时全部开放。
+
+## 判定
+
+原则：外部 Agent 替站点成员直接完成业务，开放的是能独立完成一件业务的函数。
+
+判定：函数只在页面流程或 FaaS 内部作为一个步骤使用，单独调用没有业务意义或会产生误导，例如提交前的校验、开发排查用的诊断查询，写入 `exclude`；成员能理解并直接使用的查询和写入保持开放。
+
+默认：拿不准时保持开放。误排除会让外部 Agent 缺少完成业务所需的能力；函数返回的数据是否允许成员看到，由权限设计决定，不由是否排除决定。
+
+例如任务管理站点：
+
+| 函数 | 用途 | 策略 |
+| --- | --- | --- |
+| `database-functions/listTasks` | 成员查看任务列表 | 开放 |
+| `mutations/createTask` | 成员新建任务 | 开放 |
+| `database-functions/checkTaskQuota` | 页面提交前校验成员的任务额度 | 排除 |
+| `database-functions/debugTaskStats` | 开发排查统计口径的诊断查询 | 排除 |
+
+```json
+{ "exclude": ["checkTaskQuota", "debugTaskStats"] }
+```
+
+`exclude` 中写函数目录名（functionId），必须是本工程已有的函数，且不能重复。`check` 与 `deploy` 使用同一校验函数和本地全部 Database Function、Mutation、FaaS、AI Function ID 集合，不因本次跳过 AI 同步而改变；不存在的 ID 均报 `AGENT_TOOLS_INVALID` 并列出合法 ID。当前声明仅支持 `exclude`，不支持 `include`。
+
+执行 `base-database-cli check` 校验声明，在 `agentTools.tools` 与 `agentTools.exclude` 中核对本地计划。准备跳过 AI 同步时，先执行 `base-database-cli check --skip-ai-functions`，再执行 `base-database-cli deploy --skip-ai-functions`：本地 AI ID 仍合法，但本次本地计划不包含这些 AI 的排除项，也不将其列入本地开放清单；两条命令均提示“AI Function 本次未同步，相关 agent-tools 配置未生效”。本地文件保留原声明，后续正常同步 AI 时排除项重新生效。跳过 AI 不解析其配置内容。
+
+远端已有 AI 仍按既有保留规则处理：策略接口整体替换 exclude，为避免意外重新开放函数，部署会查询远端 AI 清单，并继续提交其中已有 AI 的本地排除项；只有远端尚不存在的 AI 排除项被省略。该查询失败时继续沿用停止部署的规则，不猜测远端状态。本地计划不代表已发布开放清单。正式版开放能力按[调用站点函数](#调用站点函数)读取实时清单；Prod 继续提升 Preview 快照，不重新读取本地策略。
+
+业务能力说明与安装引导统一按[交付结果](release.md#交付结果)。
+
+**exclude 不是权限控制**：Agent OpenAPI 默认对所有人隐藏并拒绝被排除的函数，不限制页面入口、旧入口与 FaaS 回调；站点管理者仅在显式携带 `includeInternal=true` 时可通过 OpenAPI 调试。敏感数据和业务访问控制按[权限设计](permission-design.md)在执行侧落实，不能靠排除隐藏。
+
+## 发布
+
+声明随 `site.zip` 保存，`pull` 恢复，并计入 Preview 制品的输入指纹；修改后须重新发布 Preview，再按原有流程确认 Prod。Preview 部署在更新函数后写入草稿开放策略，随后上传制品；Prod 提升已校验的 Preview 制品，不读取本地声明。
+
+策略写入失败会停止部署。旧服务端明确不支持该接口时，文件缺席且没有 exclude 的工程可继续部署并保留远端原策略；存在文件时需升级服务端或移除文件。
+
+策略写入与源码上传不是原子操作。中途失败时，草稿策略与远端源码包可能暂不一致；保留本地工程并核对失败阶段，不盲目重试结果未知的写入。此时从旧源码包 `pull` 后直接部署，可能把排除清单恢复为空，应先恢复预期声明再重新部署。
+
+## 调用站点函数
+
+外部 Agent 与验收时的命令行调用都使用原生 `lark-cli api`，不使用 `+site-func-*` 等 shortcut；本地工程内用 `base-database-cli lark-cli -- api` 加相同路径，沿用工程 profile。`env` 默认 `prod`；`preview` 的准入与 Page/OpenAPI 差异见[权限边界](permission-design.md#preview-与-prod-准入)。
+
+| 步骤 | 命令 | 读取 |
+| --- | --- | --- |
+| 发现 | `lark-cli api GET /open-apis/base/v3/sites/<app-token>/functions --params '{"apiVersion":2,"env":"prod"}' --as user` | `functions[]` 的 `name`、`description`、`functionType`、`schemaStatus`、`statusHint`；`hasMore` 为 true 时带 `pageToken` 继续 |
+| 说明 | `lark-cli api GET /open-apis/base/v3/sites/<app-token>/functions/<function-id> --params '{"env":"prod"}' --as user` | `data.function` 的 `inputSchema`、`parameters[]`、`requestExample`、`replacePaths`、`callCommand`；Mutation 还读取 `outputSchema` 了解返回字段名称和类型 |
+| 调用 | 按 `callCommand`：`lark-cli api POST /open-apis/base/v3/sites/<app-token>/functions/<function-id>/invoke --params '{"env":"prod"}' --data @body.json --as user` | 顶层业务码与 `data` |
+
+列表请求始终携带 `apiVersion=2`，包括翻页、`env=preview` 或 `includeInternal=true`；检查响应 `data.apiVersion` 为数字 `2` 后再使用列表，未回写 `2` 时，通过同站点的 `skillCommand`（`GET /open-apis/base/v3/sites/<app-token>/skill`）读取 SKILL.md 清单，逐个读取函数的实时说明后再调用，不把该列表响应视为空清单。
+
+原则：参数以服务端实时返回的说明为准，Skill、函数索引和历史会话不保存参数 Schema。仅站点管理者做开发期验证时可在列表、说明和调用的 `--params` 中显式加 `"includeInternal":true` 访问页面专用内部函数；外部 Agent 默认不带。
+
+判定与默认路径：
+
+- 调用前读取该函数的最新说明，按 `inputSchema` 构造 `{"params":{…}}`，参数按 `name` 传对象，不按位置传数组。`requestExample` 中 `replacePaths` 指向的值是占位，替换为真实值后再调用，不把示例 ID 当成真实记录。
+- `parameters[]` 中的 `reference` 表示参数是某张表的记录 ID，`valueHint` 是作者写的取值步骤，`optionSummary` 是有界的选项提示而非完整选项集合；取值按作者说明先调用相应只读函数，不从字段名或表名猜测调用顺序。
+- 写入类函数每次调用前重新读取说明；同一身份、站点、环境和版本下紧邻的只读调用可复用刚读到的说明，调用失败或说明变化后重新读取。
+
+`schemaStatus` 不是 `ready` 时：
+
+| 状态 | 处理 |
+| --- | --- |
+| `missing` | FaaS 未声明输入 Schema；按函数 `description` 判断，无法确定参数时停止并说明 |
+| `needs_upgrade` | 函数仍使用旧的位置参数声明，没有可用的参数说明；不猜值、不调用，告知用户需由函数作者升级 CLI、补齐参数 `name`/`description` 后重新发布，调用方升级或重试无效 |
+| `unavailable` | 函数依赖的字段或固定选项已变化，或在当前表结构下无法通过校验；按 `statusHint` 告知需作者修复后重新发布，不重试 |
+
+错误处理：
+
+- 业务码非 0 时 lark-cli 只输出 stderr 的错误信封，不输出 `data`。平台生成的 `error.message` 默认英文：开头为原因，`Parameter:` 给出相对请求体的 JSON Pointer（如 `/params/periodId`）和 `(received ...)`，`Fix:` 给出修正方式，`Candidates:` 最多 3 个候选，`Executed: no` 表示未执行，`Retry:` 给出重试条件，`LogID:` 位于末尾。按 `Fix:` 和 `Retry:` 处理；重试值为 `retry after fixing`、`do not retry`、`retry later`、`retry after publishing` 或 `retry after access is granted`，不表示自动重试。作者 name/description、收到值和 FaaS 业务错误正文保持原语言；FaaS 业务错误末尾由平台追加 `Business code:` 与 `LogID:`。
+- `code=9499`（Bad Request）通常是请求本身不合法：核对 `--params` 与 `--data` 是否为合法 JSON、参数值类型是否与 `inputSchema` 一致（数字不写成字符串、对象不写成 JSON 字符串）。
+- `code=0` 不等于全部完成：Mutation 检查 `record_not_found` 和 `ignored_fields`，任务查询检查 `data.status` 是否为 `failed`/`cancelled` 及 `errCode`/`errMessage`。
+- 写入或 AI 任务失败、超时或结果未知时不自动重发；先用只读函数核对实际结果，再决定是否需要用户确认后重试。权限不足不换路径绕过。
+
+## 安装到本地 Agent
+
+站点 Skill 提供这个已发布站点的业务函数发现与调用说明，供外部 Agent 使用。`agent-tools skill install` 安装它；`skill install` 安装用于开发和发布应用的通用 `lark-base-database` Skill，两者用途不同。
+
+Prod 交付回复中的业务能力说明与完整 handoff 按[交付结果](release.md#交付结果)提供；本节说明安装方式。
+
+判定：`installation.available` 表示正式版 Skill 当前可获取；Preview 或读取失败时为 false。安装接口固定取 `prod`，不支持安装 Preview，也不授予 Prod 发布或调用权限。
+
+默认路径：开发者使用 `nextAction.externalAgent.installation.command`；未取得该字段时，在包含 `base-database.jsonc` 的工程目录执行：
+
+```bash
+base-database-cli agent-tools skill install
+```
+
+Prod 成员安装命令由 CLI 交付块生成。完整交付条件与回复写法见[交付结果](release.md#交付结果)；不要自行拼装或改写成员消息。
+
+成员无需打开工程目录，可在任意目录执行 `base-database-cli agent-tools skill install --site <站点链接或 token>`。命令使用当前 lark-cli 用户登录态，返回的站点能力仍按该成员自己的访问权限决定。成员安装摘要存放在用户级 CLI 状态目录，不写入站点工程；摘要用于识别同名 Skill 的站点来源，不参与工程 Preview 过期判断。仅有 Preview 的站点不能用此命令安装。
+
+成员使用 `--site` 安装时，若目标目录中已有另一个站点的同名 Skill，安装器会按站点 token 哈希加短后缀并提示新名称；同一站点重装会覆盖其已记录的安装。未被 CLI 摘要识别的同名目录仍按普通已存在目录处理，用户可先核对目标再显式使用 `--force`。
+
+默认安装到 Codex；`--target codex|agents|claude|all` 与 `--dir <path>` 的目标目录语义同 `skill install`，`--dir` 指定 skills 根目录。站点更新后，成员重复执行 `--site` 安装命令即可更新同一站点已记录的安装；未被摘要识别的目录仍需核对目标，并在用户授权下使用 `--force`。工程安装（不带 `--site`）如目标目录已存在，无论是否保存过摘要，都须先核对目标，并在用户授权下加 `--force` 重新安装。
+
+安装成功后，按[调用站点函数](#调用站点函数)分页读取实时列表，确认 `data.apiVersion=2`，只从 `agentTool=true` 的函数中选一个真实只读函数，读取其最新说明后实际调用并核对业务结果；仅列表未回写 `2` 时改从同站点 Skill 清单选择，再读取实时说明和调用。无可用只读函数则说明自检未完成，不用写入或 AI 函数代替。本地文件写入、客户端发现、远端调用分别报告实际验证结果。