Agent Surface

Agent Surface 标准

Agent Surface 是一项可被自动化调用的公共能力契约。现有运行时以 Capability 为基础，将同一 操作投影到 Open Platform API、MCP 和内核 Agent；三个调用面都会回到同一 HTTP 业务路径。

当前运行时契约

当前 Capability / PluginCapability 已强制或校验以下字段：稳定 ID、HTTP 方法、公开 /api/v1 路径、scope、英文摘要、mutating 与可选 destructive。插件公开能力还必须镜像一个 已声明的非 raw route，公开 alias 保留原 route 的 auth 和 permission。

MCP 当前提供的是通用工具输入结构：params、query、body 和写操作的 idempotencyKey。它尚未从 Capability metadata 生成领域 JSON Schema；工具调用仍由原始 route 的验证器负责校验。

新增能力的设计标准

以下是新增可自动化操作的评审标准。其中输入/输出 schema、审批等级和审计摘要目前需要在 route 实现、测试与插件自身文档中共同维护，尚未成为 manifest 的强制元数据：

项目	要求
稳定 ID	小写、命名空间化，例如 service.lifecycle.suspend
HTTP 映射	方法、/api/v1 路径和其镜像的插件内部 route
授权	route guard、权限和可选 refined scope；不得扩大原 route 权限
输入与输出	结构化字段、约束和稳定 problem code；不得依赖模型解析展示文案
变更语义	正确标记 mutating、destructive，并定义幂等与重试行为
用户影响	明确目标资源、预期结果、失败后恢复方式和敏感信息脱敏规则
审计	使用现有审计 API 写入 action、resource、resourceId 和不含秘密的 meta

约束

1. 只公开已有、经过授权的业务操作；不能用 Surface 暴露内部 helper。
2. 变更操作必须经 Idempotency-Key 安全重试。销毁、扣费、停机和批量动作应拆分预览与提交。
3. 不接受“任意命令”或把自然语言直接传进基础设施执行器。
4. 凭证、密码、私钥和完整支付信息不能出现在工具结果、审批文本或审计 meta。

提交前用测试 Agent Surface的清单验证。将 schema、审批等级和审计摘要升级为 Capability 的可执行 metadata 是后续契约版本的工作，不能假装它已由当前运行时强制。