工具与用途

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

用途选择

日常工作目前最多 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 应用”可展开查看按当前角色与授权用途过滤的工具列表。它只诊断授权，不证明客户端连通；业务对象权限和人工确认仍会在执行时检查。

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