应用嵌入清单

在应用中嵌入 PRAXO-CORE 前使用本清单。先按工作风险选择对应档位，而不是一开始 要求跑完整个仓库测试矩阵。

所有应用

• 固定已发布包版本，并记录升级路径。
• Provider 凭据和租户数据保留在框架之外。
• 显式配置模型端点，生产环境不依赖隐藏默认值。
• 定义明确的工具范围，尽可能默认拒绝。
• 增加一个拒绝检查，证明被拒绝的调用没有副作用。
• 为 Agent 循环配置超时、取消和优雅退出。
• 将事件转发到应用的可观测性流水线。
• 工具输出和模型输出都视为不可信。

只读应用

适用于搜索、检索、摘要和 Workspace 检查。

• 只允许应用暴露的读取工具。
• 使用有根文件访问，拒绝绝对路径和 .. 逃逸。
• 不暴露 Shell、包安装或无限制网络工具。
• 记录工具名和结果，不记录敏感参数。
• 测试提示注入产生的写入请求会被拒绝。

示例：只读 Workspace Agent。

有副作用应用

当 Agent 可以创建、更新、删除、发送或支付时使用本档。

• 每个效果都需要应用拥有的授权。
• 在效果边界使用幂等键或操作键。
• Checkpoint 只是恢复提示，不是效果已提交的证明。
• 对破坏性或外部可见操作增加审批。
• Middleware 或审批修改后，对最终参数重新授权。
• 未知结果不要盲目重试；先查询权威状态。
• 分别记录完成和效果验证。
• 保留意图、尝试、审批、结果和失败的审计链。

参见身份与策略和长时操作。可运行的 Python 与 TypeScript 示例 language/python/examples/service-auth 与 language/typescript/examples/service-auth 展示了 HMAC 身份校验、租户允许列表，以及不可用时 fail closed 的外部策略决策服务。

高风险或多租户应用

适用于多租户、特权操作或安全相关效果的生产系统。

• 认证调用方并传递已验证 principal；忽略模型提供的角色。
• 存储、Policy、Checkpoint 和事件按租户隔离。
• 在 OS 或 Sandbox 层隔离 Shell、文件和网络执行。
• 必需身份、Policy 或安全服务不可用时失败关闭。
• 在应用拥有的存储中持久化审批和撤销。
• 将执行权威与 Agent 运行时分离。
• 定义取消、恢复和升级的操作手册。
• 记录部署边界和剩余风险。

参见安全模型和隔离。

Core 职责

Core 提供 Agent 循环、模型/工具契约、Policy hook、事件、Checkpoint、Streaming、 取消和可选 Adapter。它不提供：

• 真实身份或租户签发；
• 策略决策服务；
• 持久审批或效果账本；
• 工作流引擎或 worker lease；
• 网络或进程隔离；
• exactly-once；
• 生产模型或 Provider 保证。

反模式

• 只添加 Policy，没有允许列表。
• 把当前 API 的空工具范围当作拒绝所有工具。
• 把 Checkpoint 当事务。
• 超时后不查询权威状态就重试。
• 记录原始凭据、租户数据或工具参数。
• 假设 Go 示例可在所有语言 SDK 中原样运行。
• 将 fixture 或离线配方当作生产证据。

复制合适的测试

使用消费者测试模板，只将匹配风险档位的检查复制到应用仓库。

评审时保留

记录包版本、模型端点类别、工具范围、Policy 负责人、审批模型、Checkpoint 存储、 事件目的地、隔离边界以及实际运行的测试。注明精确 revision 和环境。