智能体操作指南

入口、身份和统一登录

三个业务入口共用一套商事代理会话和租户边界。智能体不得为不同端创建另一套用户 ID、租户 ID 或角色。

微信/IAM 认证流程

1. 入口调用 POST /api/v1/commercial/auth/wechat/h5/start，带 surface=pc|admin|mobile。
2. 服务端生成一次性 session_token、client_state 和场景值，跳转 AI-OPC 社区/IAM 与授权中心 shouquan_new。
3. 授权回调后，前端只提交 code、client_state、scene 和本次 session_token 到 POST /api/v1/commercial/auth/platform-login。
4. 服务端校验场景、会话、有效期和签名，交换统一身份并签发商事代理 JWT；前端再调用 /auth/me。

PC 和管理后台在配置允许时可使用微信桌面扫码：/auth/wechat/qr/start、/auth/wechat/qr/poll、/auth/wechat/qr/cancel。二维码轮询和取消绑定发起端指纹，过期或确认后不能重放。生产环境禁止用户名/密码直登，也不要记录 token、授权 code 或密钥。

统一身份与角色

服务端以 IAM 返回的 subject_id 作为跨项目主体，以 tenant_ref（或规范化 OPC profile）确定租户。tenant_id、roles 和 scopes 均为服务端计算值，客户端不能追加或覆盖。

管理后台不会因为 surface=admin 自动授予管理员权限，IAM 回调必须明确携带管理员角色/权限；审批人不能审批自己发起的高风险操作。

智能体的标准运行链路

每一次商事意图都必须经过完整责任链，不允许智能体绕过策略校验、人工审批或回执对账。

“已提交”“处理中”“结果未知”“已完成”是不同状态。没有可核验回执时，智能体必须保留 processing/unknown 语义，不能把不确定结果说成成功。

能力与风险等级

登录后可通过 GET /api/v1/commercial/mcp/tools 获取当前能力清单。风险等级和副作用决定是否需要人工审批。

高风险工具申请会创建 operation 和 approval。审批绑定操作类型和 parameter_hash；字段变化必须生成新的幂等键并重新审批。

提案与审批方法

操作前检查

• 当前 JWT 有效、未撤销，且 tenant_id 与项目一致。
• project_id、entity_id、account_id 均属于当前租户。
• 高风险请求写明业务目的、金额/币种、对象、期限和责任人。
• 可重试写请求使用稳定 idempotency_key；同一键只允许同参数重放。
• 不把身份证、完整银行卡号、微信 token、授权 code 或密钥放入 prompt、日志或正文。
• 先读取当前状态和事实源，再决定是否重试；遇到 unknown 不重复扣款或发信。

推荐提案结构

{
  "name": "commercial.transaction.payment",
  "tenant_id": "从当前会话读取，不由用户输入覆盖",
  "project_id": "project-id",
  "entity_id": "entity-id",
  "account_id": "account-id",
  "arguments": {
    "amount": "12800.00",
    "currency": "CNY",
    "destination": "供应商账户引用",
    "purpose": "2026-09 园区运维服务费"
  },
  "idempotency_key": "payment-project-id-202609-001",
  "expected_risk_level": "L4",
  "requires_human_approval": true
}

提案返回 accepted 只代表接收和初步校验，不代表已付款。智能体要向用户说明 operation 编号、风险等级、待审批原因、参数摘要、有效期和下一步。

审批人的复核顺序

1. 核对项目、法律主体、账户和租户。
2. 核对金额、币种、收款方、用途、接收方和税务期间。
3. 确认发起人与审批人分离，审批仍在有效期内。
4. 核对 parameter_hash；参数变化时驳回原单并重新发起。
5. 明确批准或驳回，驳回写清原因；不要代替其他人操作。

服务端以 JWT 主体写入 approver_id，忽略客户端冒名字段。审批只能决定一次，过期或重复决定会返回冲突。

状态、幂等和异常处置

协同项目边界

五个项目通过统一身份、租户引用、操作编号和事件证据协同。商事代理是现实商业适配层，不是绕过其他系统的后门。

智能体不得绕过商事代理直接写 Naive 或数据库。跨项目调用必须保留 trace_id、operation_id、租户引用和来源系统，便于回放和审计。

安全红线与学习验收

学习与验收路径

1. 理解“提案—校验—审批—执行—沉淀”的责任链。
2. 在三个入口用微信/IAM 登录，确认同一 subject_id 和租户。
3. 只读查看能力和状态，练习区分 pending_approval、processing、unknown、succeeded。
4. 隔离租户中用固定幂等键重复提交，确认不重复建单。
5. 用两个账号演练审批分离、过期、驳回、冻结和释放。
6. 沙箱验证签名回调、Webhook 重放、Outbox redrive 和审计导出。
7. 通过生产预检、恢复演练、合同和 UAT 后再申请开放真实写能力。