# 工具与用途

工具展示由连接用途、读写 scope 和用户业务角色共同决定。选择用途不会提升权限。

## 用途选择

| 用途 | 典型能力 |
| --- | --- |
| 日常工作（默认） | 待办、收集表、申请与进度 |
| 表单与流程设计 | 定义、草稿、校验与提案 |
| 数据分析 | 字典、查询、审计查询与导出 |
| 系统管理 | 组织、岗位、Agent 与流程管理 |

日常工作目前最多 15 个工具，包含已批准操作执行器。只读连接可能看到更少工具，应以 tools/list 为准，不再支持已删除的兼容别名。

## 收集表办理链路

### 只读准备与预校验

`startable_flows({flowRef, formData?})` 和 `get_collection({collectionId, formData?})` 可携带部分填写值，返回 `prepared`：精确字段与规则、版本引用、后台预填/计算后的 `data`、身份上下文、可编辑字段名、`valid` 和 `issues`。省略 formData 时也可获取初始预填值。收集表已结束时保留提交快照，不重新预填。

准备不会提交数据或创建人工确认请求。不完整表单返回校验问题；当前采用遇到首个问题即返回的校验策略，不保证一次列出全部错误。正式提交仍重新校验。网页可使用认证接口 `POST /api/forms/prepare`，请求为 `{formRef, data}`。

### 操作状态契约

确认请求和操作查询保留原有字段，并增加 `operation` 对象：`contractVersion`、`operationId`、`state`、`terminal`、`nextAction` 和 `safeToReplay`。`nextAction` 为 `review`（待人工确认）、`poll`（等待执行）、`reconcile`（结果未知，需核对）或 `none`。`safeToReplay` 不会自动授权重放；失败也可能已产生副作用。不要自动新建替代操作。

设计工作室与外部 MCP 共用工具策略目录，但并非开放所有同名权限：设计页不提供收集表关闭等管理操作。工具输入结构仍以 MCP `tools/list` 为准。


1. `fillable_collections`：发现当前身份可填的表。
2. `get_collection`：获取 Schema、已有填写与浏览器链接。
3. `fill_collection`：提交字段类型正确的完整 formData。
4. 在浏览器核对返回的 approvalUrl。
5. 系统批准后自动执行；AI 可用 `execute_approved_operation` 查询原始 operation_id 的结果，不要创建替代请求。
6. 核对结果，不要只凭“已批准”判断提交完成。

申请批准前及正式提交时，都会检查必填、字段类型、填写范围、状态与截止时间。

## 流程办理链路

用 `startable_flows` 发现流程，`initiate` 发起，`my_todo` 查询待办，`act_on_task` 处理任务，`instance_progress` 跟踪，`act_on_instance` 重新提交或撤回。写操作遵循同一确认机制。

## 字段类型

文本保持为文本，尤其是带前导零的手机号。数字字段传数字，多选传数组，区间和明细表遵循 Schema 对象结构。不要给电话号码加入实际的引号字符来“强制字符串”。

## 设计与管理

### 草稿模拟与连接权限

`get_draft` 在 `kind: "flow"` 时支持 `simulation: {rev, formData, formRev?, decisions?}`。rev 必须与当前流程草稿一致；默认使用绑定的已发布表单，指定 formRev 可模拟该修订的表单草稿。模拟不提交数据、不发通知、不执行外部服务。AI 设计预览区也提供“模拟草稿”入口。

“已连接的 AI 应用 → 连接权限”可收紧工具和资源范围，立即生效且不扩大原有角色与 OAuth 授权。资源按未带版本的 `flow:flow.xxx`、`form:form.xxx` 或 `collection:UUID`、`instance:UUID` 配置。流程范围可办理关联实例，读取流程时包含绑定表单；直接访问表单草稿仍需表单授权。启用资源限制会拒绝全局发现和组织管理；启用限制但留空表示全部拒绝。已批准操作在执行前重新检查原参数权限。

浏览器“AI 设计 → 模拟草稿”可直接试填字段和明细行，选择已发布绑定表单或当前表单草稿，并为审批节点选择模拟同意/拒绝。结果显示状态与事件轨迹，技术详情可展开查看。这是单场景验证，不会自动穷举所有路径。

可将当前试填和审批决定“暂存当前场景”，命名后继续调整输入，最多暂存 10 个场景并批量模拟。弹窗关闭或切换表单来源后不保留这些临时场景。覆盖报告显示实际经过的节点、有向连线和未覆盖部分，不等同于所有条件、输入组合或执行路径已验证。每个场景最多 1000 次节点转移和 100 次审批动作，达到上限标记未完成；外部服务和等待状态仍停止模拟。

MCP `get_draft` 可传 `simulationBatch: {rev, formRev?, scenarios: [{name, formData, decisions?}]}`（与 `simulation` 二选一）。输入校验失败按场景返回错误；修订冲突或权限错误使整批失败，不混用不同草稿修订。

表单预检返回最多 100 项校验错误，明细列包含行路径，便于 AI 一次修正多项字段问题；预检不是提交。

### 只读流程模拟

设计用途的 `definitions` 支持 `simulation: {formData, decisions?}`，同时指定 `kind: "flow"`、`defId` 和版本。需要流程管理员权限。使用当前组织和真实引擎解析路由与审批人；`decisions` 按审批节点 ID 指定 `approve` 或 `reject`，默认全部同意。遇到外部服务、等待状态或步数上限即停止，不执行定时器、外部调用，也不创建实例。浏览器在“字段与校验”页试填后可点击“模拟已发布流程”。模拟不是实际审批，也不保证未来组织变化后的结果。

### 异步操作结果事件

管理员通过 `webhook` 显式订阅 `operation.succeeded`、`operation.failed`、`operation.unknown`、`operation.rejected`、`operation.expired`。操作事件不使用 `flowFilter`。空事件列表仍只接收原有流程终态事件。

状态标记与投递队列在同一事务入库，复用签名和重试机制。接收端验证 `x-sanctris-signature`，按 `payload.eventId` 去重。`payload.operation` 包含状态和业务引用，不包含表单内容、确认参数或令牌。投递为至少一次，重试有上限；这不是外部 AI 客户端自动支持的推送协议，需要自有服务接收。结果未知时核对业务记录，禁止自动重放。

### 设计工作区与接入诊断

设计会话保留本次触及的多份表单和流程，预览区可切换，刷新后仍保留。旧会话只能迁移此前保存的最后一份产物。

“已连接的 AI 应用”可展开查看按当前角色与授权用途过滤的工具列表。它只诊断授权，不证明客户端连通；业务对象权限和人工确认仍会在执行时检查。

草稿修改经过校验和提案。即使连接请求管理用途，业务操作仍受角色限制。工具不可见时按需要重新授权用途，不要调用旧别名或借用其他身份。