# OPC 商事代理：智能体操作指南

版本：2026.09  
适用对象：Hermes Agent、OPC 大模型工具编排人员、项目运营人员、审批人、管理员和集成工程师

## 1. 先读这份指南

OPC 商事代理是 AI-OPC 体系面向现实商业世界的受控编排层。它把项目、法律主体、账户、交易、税务台账和商务通信连接起来，但不替代工商、银行、支付、财税、法律或审计机构。

本指南的核心原则只有一句话：**智能体可以理解和起草，系统负责约束，授权自然人负责决定，现实服务商负责执行，平台负责留下证据。**

生产环境必须满足真实合同、生产凭据、沙箱 UAT、恢复演练和发布审批等前置条件。未满足条件时，写能力应保持阻断或转人工代办；文档中的示例不会触达真实外部服务。

## 2. 入口、身份和统一登录

### 2.1 三个业务入口

| 入口 | 地址 | 主要使用者 | 能力 |
| --- | --- | --- | --- |
| PC 用户端 | `/pc/` | 项目运营人员 | 项目、主体、账户、收付款、通信、税务台账和操作状态 |
| PC 管理后台 | `/admin/` | 合规、财务和管理员 | 集成状态、Outbox、冻结/释放、审计查询和导出 |
| 移动 H5 | `/uniapp/` | 审批人和移动值守人员 | 待审批、批准/驳回和关键异常查看 |

三个入口都使用同一套商事代理会话和租户边界。不要在不同入口创建或拼接另一套用户 ID、租户 ID 或角色。

### 2.2 微信认证流程

正式登录通过 AI-OPC 社区/IAM 与授权中心（`shouquan_new`）完成：

1. 用户在对应入口选择微信授权。
2. 前端调用 `POST /api/v1/commercial/auth/wechat/h5/start`，并带上 `surface=pc|admin|mobile`。
3. 服务端生成一次性 `session_token`、`client_state` 和场景值，跳转到受信任的授权中心。
4. 授权中心回调后，前端只提交 `code`、`client_state`、`scene` 和本次 `session_token` 到 `POST /api/v1/commercial/auth/platform-login`。
5. 服务端向社区 IAM 交换统一身份，校验场景、会话、有效期和签名后签发商事代理 JWT。
6. 前端把会话保存在会话存储中，调用 `/auth/me` 验证后再加载业务数据。

PC 和管理后台在配置允许时还可以使用微信桌面扫码：

- `POST /api/v1/commercial/auth/wechat/qr/start`
- `POST /api/v1/commercial/auth/wechat/qr/poll`
- `POST /api/v1/commercial/auth/wechat/qr/cancel`

二维码轮询和取消绑定发起端指纹；过期、取消或确认后不能重放。不要把二维码 token、IAM access token、exchange code 写入日志、URL 分享或业务字段。

生产环境禁止用户名/密码直登。`POST /api/v1/commercial/auth/login` 仅用于受控开发调试，公网或生产调用会被拒绝。微信授权状态只在当前会话有效，浏览器禁止会话存储时应提示用户修复浏览器设置并重新发起，不要退回临时账号。

### 2.3 统一身份字段和角色

服务端以 IAM 返回的 `subject_id` 作为用户主体，以 `tenant_ref`（或规范化的 OPC profile）确定租户。前端和智能体应把以下字段视为只读：

- `subject_id`：跨项目统一用户主体标识。
- `tenant_id`：商事数据隔离边界；每次写操作都必须在该租户内。
- `roles`：角色集合；不能由客户端自行追加。
- `scopes`：接口权限集合；由服务端从会话角色计算。

商事代理内置角色与权限：

| 角色 | 权限 | 使用边界 |
| --- | --- | --- |
| `commercial_operator` | `commercial:read`、`commercial:write` | 建档、发起操作和读取本租户事实 |
| `commercial_approver` | `commercial:read`、`commercial:approve` | 查看审批并作出批准/驳回决定 |
| `commercial_admin` | 以上全部及 `commercial:admin` | 冻结/释放、Outbox、集成状态、审计查询/导出 |

管理后台不会因为 `surface=admin` 自动授予管理员权限。只有 IAM 回调明确携带管理员角色/权限时，服务端才会加入 `commercial_admin`；审批人不能审批自己发起的高风险操作。

## 3. 智能体的标准运行链路

每一次商事意图都按下面的顺序处理，不允许跳步：

```text
用户目标/Agent 提案
    -> 规范化参数（主体、项目、金额、币种、收款方）
    -> 校验租户、权限、项目归属和业务约束
    -> 生成参数哈希与幂等键
    -> L1/L2 本地记录，或 L3/L4 进入 pending_approval
    -> 授权自然人复核对象、参数、影响和有效期
    -> approved / rejected / frozen
    -> 生产 gate 通过后交给 Naive/持牌服务商
    -> webhook 验签、轮询校对和异常处置
    -> operation、业务台账、Outbox 和审计链沉淀
```

“已提交”“处理中”“结果未知”“已完成”是不同状态。上游没有可核验回执时，智能体必须保留 `unknown`/`processing` 语义，不能为了给用户一个确定答案而改写成成功。

## 4. 可调用能力与风险等级

能力清单可在登录后通过 `GET /api/v1/commercial/mcp/tools` 获取。当前恢复运行时的能力如下：

| 工具 | 风险 | 副作用 | 智能体正确用法 |
| --- | --- | --- | --- |
| `commercial.project.upsert` | L1 | local | 先建立项目引用；同租户内 `project_ref` 幂等更新 |
| `commercial.legal_entity.create` | L4 | legal | 只提交申请，等待独立审批；不得声称已完成登记 |
| `commercial.account.open` | L4 | legal | 校验主体和币种后提交开户申请，等待审批与服务商回执 |
| `commercial.transaction.collect` | L2/L3 | local/payment | 小额本地收款可入账；超过阈值或涉及外部支付时进入审批 |
| `commercial.transaction.payment` | L4 | payment | 必须由授权自然人批准；金额、收款方、用途变化要重新审批 |
| `commercial.communication.send` | L3 | communication | 内容、接收方和模板固定后再申请审批；默认不直发 |
| `commercial.tax_ledger.upsert` | L2 | local | 归集事实和凭证，不等同于自动报税或税务意见 |

高风险工具的申请接口会创建 `operation` 和 `approval`。审批参数绑定操作类型和 `parameter_hash`；任何字段变化都应生成新的幂等键并重新审批。

## 5. 操作前检查清单

智能体在提出工具调用前，应逐项确认：

- 已通过微信/IAM 登录，当前 JWT 未过期、未撤销，`tenant_id` 与用户当前项目一致。
- `project_id`、`entity_id`、`account_id` 均属于当前租户；跨租户引用应停止并提示人工处理。
- 高风险请求包含明确的业务目的、金额/币种、对象、期限和责任人，不使用自然语言猜测关键字段。
- 每个可重试写请求都有稳定的 `idempotency_key`；同一键只允许同一组参数重放。
- 不把身份证、银行卡完整号码、微信 access token、授权 code 或密钥放入 prompt、日志或通信正文。
- 先读取当前状态和事实源，再决定是否重试；遇到 `unknown` 不盲目重复扣款或重复发信。

## 6. 推荐的提案格式

智能体内部可以用如下结构向编排层传递意图，再由服务端 API 生成正式 operation。示例只读、不会直接执行：

```json
{
  "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”解释为已付款；它只表示系统接收并完成了初步校验。

### 6.1 审批人的复核顺序

审批人进入 `/uniapp/` 或 `/pc/` 的审批视图后，按以下顺序复核：

1. 项目、法律主体和账户是否属于当前租户，名称与业务上下文是否一致。
2. 金额、币种、收款方、用途、通信接收方和税务期间是否完整且符合授权限额。
3. 操作发起人是否与审批人分离，审批是否仍在有效期内。
4. 展示的 `parameter_hash` 是否与拟执行参数绑定；参数有变化时驳回原单并重新发起。
5. 明确选择 `approved` 或 `rejected`，驳回必须写清原因；不要代替其他人操作。

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

## 7. 状态、幂等和异常处置

### 7.1 状态语义

| 状态 | 含义 | Agent 应答 |
| --- | --- | --- |
| `pending_approval` | 已建单，等待独立审批 | 告知审批编号和待办，不执行重试 |
| `approved` | 审批通过，等待执行或回执 | 展示批准时间和参数摘要 |
| `processing` | 已交给执行层，尚未得到最终结果 | 轮询/等待回执，不能宣称完成 |
| `succeeded` | 有可核验的成功回执 | 引用 operation、receipt、trace_id |
| `rejected` | 人工驳回 | 展示原因，修改意图后生成新键 |
| `expired` | 审批或会话超时 | 重新发起，不复用旧 code/token |
| `frozen` | 管理员冻结写能力或操作 | 停止重试，联系管理员 |
| `unknown` | 上游结果不确定 | 转异常对账队列，禁止重复副作用 |

### 7.2 常见错误与处理

| 错误码/现象 | 处理 |
| --- | --- |
| `WEB_AUTH_DISABLED` | 当前环境关闭 Web 认证，联系运维，不切换临时账号 |
| `WECHAT_CONTEXT_REQUIRED`、`WECHAT_EXCHANGE_EXPIRED` | 清理本次授权状态，重新从入口发起微信登录 |
| `ADMIN_AUTHORIZATION_REQUIRED` | 当前 IAM 身份没有管理员授权，使用正确的管理员账号 |
| `SELF_APPROVAL_FORBIDDEN` | 更换独立审批人，不能绕过分离控制 |
| `OPERATION_IDEMPOTENCY_CONFLICT` | 检查业务参数；参数不同必须生成新幂等键 |
| `AUTH_REVOKED` 或 401 | 清理会话并重新授权，先确认没有并发标签页覆盖会话 |
| `*_SIGNATURE_INVALID` | 停止接收/重试，检查签名密钥、原始请求体和时钟 |
| `unknown` / webhook 缺失 | 不重复扣款或发送，进入对账和人工处置 |

## 8. 三个协同项目的边界

| 系统 | 在闭环中的职责 | 交接重点 |
| --- | --- | --- |
| OPC 大模型（`opcdamoxing`） | Hermes Agent、多智能体和 FastGPT 智识库 | 只生成结构化提案；通过受控 Harness/MCP 能力调用 |
| AI-OPC 社区（`aiopcshequ`） | 社区用户、租户、项目上下文和统一 IAM | 提供 `subject_id`、角色、租户引用和微信授权上下文 |
| OPC Office（`bangong`） | 任务、文档、会议、审批和通知 | Office 审批事件必须签名并带幂等键 |
| Naive/持牌服务商 | 工商、银行、支付、财税和通信执行 | 只接受签名请求；Webhook 验签、防重放、轮询对账 |

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

## 9. 安全与合规红线

- 禁止 AI 完全自治设立企业、开户、付款、报税、开票或发送正式商务承诺。
- 禁止用客户端传入的 `tenant_id`、`approver_id`、`actor_id` 覆盖服务端会话主体。
- 禁止跨租户读取或拼接项目、主体、账户和交易；出现 404/权限异常时不能猜测资源 ID。
- 禁止复用已消费的微信 code、client state、二维码 token 或审批单。
- 禁止把开发 mock、未签合同或未完成 UAT 的结果展示为生产成功。
- 禁止公开 API token、签名密钥、完整收款账户、个人信息和未脱敏回执。
- 所有事实数据以服务端 operation、Webhook、轮询和审计链为准；模型输出仅是解释，不是证据。

## 10. 学习路径与验收

建议按以下顺序学习和演练：

1. 在官网了解“AI 提案—策略校验—人工审批—持牌执行—事实沉淀”的责任链。
2. 使用微信/IAM 登录三个入口，确认同一身份的 `subject_id` 和租户边界一致。
3. 只读调用能力清单和项目/操作列表，练习区分 `pending_approval`、`processing`、`unknown` 和 `succeeded`。
4. 在隔离租户中创建项目，使用固定幂等键重复提交，确认重放不产生重复 operation。
5. 用两个不同账号演练高风险操作与审批分离，再演练过期、驳回、冻结和释放。
6. 在沙箱中验证签名回调、Webhook 重放冲突、Outbox redrive 和审计导出。
7. 通过生产预检、恢复演练、合同和 UAT 证据后，才申请开放真实写能力。

相关入口：

- 官网：`https://opcshangshi.yizhangkj.com/`
- PC 用户端：`https://opcshangshi.yizhangkj.com/pc/`
- 管理后台：`https://opcshangshi.yizhangkj.com/admin/`
- 移动 H5：`https://opcshangshi.yizhangkj.com/uniapp/`
- 能力清单（登录后）：`GET /api/v1/commercial/mcp/tools`
- 健康状态：`GET /health/live`、`GET /health/ready`

本指南是操作和学习材料，不构成法律、税务、审计、投资或支付建议。生产配置、权限和服务商合同优先于示例内容。