# AI-OPC 技能仓库智能体操作指南

> 适用项目：`opcjinengcangku`（AI-OPC 版本化技能仓库）  
> 文档版本：0.10.10  ·  更新日期：2026-09-02  ·  阅读对象：业务使用者、技能作者、审核员、发布运营和系统管理员

本指南把“提出一个业务目标”到“得到可审计结果”的完整路径拆成可操作步骤。页面上的示例数据仅用于认识界面；只有服务端返回 `success`、`active` 或明确的真实运行状态，才算实际完成。当前环境如果显示 `blocked` 或 `503`，请按“故障与阻断处理”章节处理，不要把演示数据当成生产能力。

## 1. 先认识五项目协同关系

五个项目共享社区统一身份、租户、主体、工作空间和 Harness 合同；技能仓库负责把业务能力编排成版本化、可验证的智能体技能。

| 项目 | 在智能体链路中的职责 | 常用入口 |
| --- | --- | --- |
| `opcjinengcangku` | 技能目录、需求分流、编译/沙箱、发布、运行、记忆和反馈治理 | 本站、`/pc/`、`/admin/`、`/uniapp/` |
| `aiopcshequ` | 统一用户身份、主体/租户/工作空间、社区知识和空间能力 | `https://aiopcshequ.yizhangkj.com/` |
| `bangong` | 办公任务、文档和审批等业务执行能力 | `https://bangong.yizhangkj.com/`（以实际部署域名为准） |
| `opcshangshi` | 商事主体、操作、交易和对账等受控业务能力 | 以商事项目部署域名为准 |
| `opcdamoxing` | 模型、知识检索和 Harness Gateway 等基础能力 | 以模型基座部署域名为准 |

跨项目调用由服务端连接器完成。浏览器和移动端只使用同源 Web BFF 会话，不保存社区 refresh token、Harness service token 或供应商密钥。

## 2. 入口与首次登录

### 2.1 三个业务入口

- **官网**：`/`，了解平台闭环和公开技能。
- **PC 用户工作台**：`/pc/`，检索技能、提交需求、调用和反馈。
- **PC 治理后台**：`/admin/`，审核候选、查看编译证据、发布/暂停/回滚和处理记忆治理。
- **移动 H5/UniApp**：`/uniapp/`，浏览技能、快速调用、提需求、处理待办和查看运行记录。

公开技能和 readiness 可以在未登录状态下只读查看；需求、运行、记忆、通知和治理数据必须登录后按当前主体和工作空间读取。

### 2.2 登录方式

1. 在工作台点击“登录”，先勾选用户协议和隐私政策。
2. 根据当前环境选择账号密码或微信方式：
   - PC 可在 `wechat_desktop_qr.ready=true` 时使用微信扫码；二维码由服务端创建、轮询和撤销。
   - 移动 H5 使用一次性 OAuth code；小程序/App 使用平台短期 code。三种移动渠道默认关闭，只有完成真实 AppID、回跳白名单、签名和真机验收后才能启用。
   - 微信方式不可用时，使用账号密码继续登录；不要反复刷新二维码或把二维码内容复制到外部工具。
3. 如果服务端返回 `MFA_REQUIRED`，输入身份验证器动态码或恢复码；`INVALID_MFA` 后只需重新输入动态码。
4. 登录成功后确认顶部显示正确的用户名、租户和工作空间。会话不完整（缺少 `workspace_id` 等字段）会被拒绝，这是保护措施。

统一登录的安全边界：浏览器只接收 HttpOnly、SameSite 会话 cookie；非幂等请求由同源 CSRF 校验保护。退出登录后，需求、运行和记忆投影会立即清空。

## 3. 五分钟完成第一次调用

下面以公开的 A0 只读技能为例。A0 表示无业务副作用，并不代表可以绕过身份、租户或数据授权检查。

1. 进入 `/pc/`，打开“技能市场”，用关键词或业务域筛选。
2. 打开技能详情，先读完**输入/输出契约、风险等级、数据等级、权限、依赖和 release 通道**。
3. 点击“调用”。有可识别的 JSON Schema 时使用表单；复杂或动态契约使用 JSON 模式。严格填写必填字段，不要增加契约外字段。
4. 点击“预检并执行”。服务端依次校验会话、租户/主体/工作空间、技能版本、下游 readiness、数据授权、审批和幂等键。
5. 在“运行记录”查看 `invocation` 状态、技能版本、trace、结果摘要、错误和记忆命中数。`unknown`、`reconciliation_required`、`blocked_by_policy` 都不是成功。
6. 对已结束且属于自己的运行评分 1-5 分。评分只形成指标样本，不会直接修改技能版本。

示例输入（仅用于说明结构，实际字段以技能详情的 Schema 为准）：

```json
{
  "workspace_id": "workspace-demo"
}
```

## 4. 从业务需求生成技能

### 4.1 提交需求

在 PC 的“我的需求”或移动端“需求”页，用业务语言描述目标、范围、期望输出和数据授权。例如：

```text
汇总本周工作空间内已授权的任务和会议，生成一份带来源引用的周报；只读取 D0 数据，不发送通知。
```

提交前确认：

- 目标工作空间正确，不能用文字参数替换服务端绑定的租户/主体/工作空间。
- 选择的风险上限与实际副作用一致；需要创建、修改、付款、通信或提交外部表单时，应明确写出。
- 不在需求文本中放密码、验证码、access token、银行卡号或完整个人敏感信息。
- 需要重复提交时沿用客户端幂等语义，先刷新原需求，不要盲目连点。

### 4.2 理解三分流结果

服务端会在生成前持久化一个不可变决策：

| 决策 | 什么时候发生 | 使用者下一步 |
| --- | --- | --- |
| `reuse`（直接复用） | 相似度达到复用阈值（默认 0.86），契约兼容且已有 active 版本 | 查看目标版本和授权，直接调用或安装 |
| `iterate`（补丁迭代） | 相似度达到匹配阈值（默认 0.62），但需要补充能力 | 查看现有版本链和差异，等待生成/编译/审核 |
| `create`（新建技能） | 没有合格候选，或输入输出契约不兼容 | 由技能作者完善候选包，再走编译和发布 |

详情中的 `resolution_score`、`resolution_reason` 和目标版本链是审计事实。不要为了“新建一个名字”绕过 `iterate`，这样会制造平行技能和不可维护依赖。

### 4.3 跟踪需求时间线

常见状态顺序为：`received` → `matched` → `generation_requested` → `generated` → `compiled` → `staged`/`installed`。失败或拒绝状态必须查看原因和 request ID；只有服务端明确返回下一步动作时才继续生成。

## 5. 技能包学习卡

技能包遵循 `opc.ai/v1` 的 `Skill` 合同。最小可学习结构如下：

```json
{
  "apiVersion": "opc.ai/v1",
  "kind": "Skill",
  "metadata": {
    "skill_id": "community.space.catalog.read",
    "skill_name": "社区空间目录读取",
    "version": "1.0.0",
    "owner": "opc-community",
    "market_demand_source": {"type": "seed", "reference_id": "example"}
  },
  "spec": {
    "intent": {"goal": "read_authorized_spaces", "entities": ["space"]},
    "entry_prompt": {"system": "只返回已授权事实，不得猜测。", "user_template": "读取空间目录。"},
    "input_schema": {"type": "object", "required": ["workspace_id"]},
    "output_schema": {"type": "object", "required": ["spaces"]},
    "tool_dependencies": [],
    "long_memory_binding": {
      "mode": "dedicated",
      "memory_space_id": "auto:skill",
      "memory_retention_policy": {"days": 180, "deletion": "tenant_request"},
      "memory_extract_rule": {"allow": ["space_preference"], "deny": ["credential", "payment_data"]},
      "cross_skill_read": [],
      "write_mode": "append_reviewed"
    },
    "execution_flow": [{"id": "return", "type": "return"}],
    "test_cases": [{"id": "normal", "input": {"workspace_id": "w-demo"}, "expected": {"status": "pass"}}],
    "feedback_metric": {"window": "7d", "metrics": ["success_rate", "policy_block_rate"]}
  },
  "security": {
    "risk_level": "A0",
    "side_effects": "none",
    "data_classes": ["D0"],
    "permissions": ["community.space.read"],
    "network": {"mode": "deny_all", "allowlist": []},
    "sandbox": {"cpu_seconds": 10, "memory_mb": 256, "filesystem": "ephemeral"},
    "signing": {"required": true, "algorithm": "Ed25519"},
    "idempotency": "required"
  }
}
```

学习和审查时按这个顺序读：

1. `metadata`：身份、版本、owner 和需求来源是否可追溯。
2. `input_schema`/`output_schema`：调用者能提供什么、技能承诺返回什么。
3. `tool_dependencies`：依赖哪个项目、哪个技能和哪个版本范围，是否存在循环或越权写入。
4. `long_memory_binding`：记忆空间、保留期、允许抽取的类别、跨技能读取授权和写入模式。
5. `execution_flow`/`test_cases`：执行顺序、失败分支、边界样例和幂等要求。
6. `security`：风险、数据等级、权限、网络、沙箱、签名和副作用。

编译器还会校验依赖图、Schema 完整性、签名制品、版本兼容和资源边界。缺失字段、非法版本、直接/传递循环或签名不匹配会在进入运行时前失败关闭。

## 6. 发布与版本治理

### 6.1 发布通道

- `staged`：通过编译和签名后的候选，等待治理激活。
- `canary`：按租户、主体、工作空间或百分比小范围放量。
- `stable`：默认稳定版本，供未命中 canary 选择器的请求使用。

同一技能和环境可以同时有 stable 与 canary。调用先匹配 canary，未命中选择器或百分比桶自动回退 stable。新 stable 晋级会关闭同版本对应的 canary。

### 6.2 激活、暂停、回滚

发布运营在 `/admin/` 的“发布中心”执行操作：

1. 核对候选 digest、签名、编译报告、依赖和审批证据。
2. 先 staged，再 canary；观察成功率、延迟、策略阻断、unknown 和纠正率。
3. 激活、暂停、回滚都必须携带服务端返回的当前 `fencing_token`、操作原因和二次确认。token 成功后立即轮换，旧 token 会被拒绝。
4. 回滚优先恢复同通道上一版本；首个 canary 才回退到 stable anchor。不要直接删除仍被运行或对账引用的版本。

### 6.3 风险等级与审批

| 等级 | 典型含义 | 基线处理 |
| --- | --- | --- |
| A0 | 只读、无业务副作用 | 可由普通使用者调用，但仍需授权和数据等级检查 |
| A1 | 低风险受限动作 | 按策略显示授权和审计信息 |
| A2 | 创建/修改任务、业务写入 | 独立审批、幂等和必要的补偿技能 |
| A3-A4 | 高风险、外部交易或敏感操作 | 强制更严格审批、MFA/双人复核和人工对账；默认不自动晋级 |

审批人不能审核自己提交的提案。前端按钮的隐藏/禁用只是体验层，真正权限由 BFF、RBAC、租户边界和服务端职责分离校验执行。

## 7. 记忆、反馈与持续学习

### 7.1 专属记忆

记忆按 `tenant_id`、`subject_id`、`workspace_id`、技能和环境隔离。运行后的候选先是 `pending_review`，只有独立审核主体接受后才可召回。

- 在 PC“专属记忆”或移动“我的”中选择技能并输入业务上下文查询。
- 召回只返回已审核、符合数据等级和 retention 策略的记录；公开 `/memory/query` 不允许任意跨技能参数。
- `cross_skill_read` 必须在技能包中显式声明，来源空间、来源版本和授权范围都要满足同租户/主体/工作空间边界。
- 记忆删除是按范围软删除并留审计，不要用“清空浏览器缓存”代替服务端删除。

### 7.2 反馈迭代

用户评分、纠错和运行指标进入按窗口聚合的评估。达到样本数、阈值和连续窗口条件后，系统创建迭代提案；提案仍需历史调用 shadow 回放、人工 review、重新编译、签名和发布。

反馈不会直接把 `1.0.0` 改写成新版本，也不会因为单个低分自动回滚。发现敏感泄露、越权或错误外部写入时，应立即暂停 release 并保留 trace、制品和审计证据。

## 8. 移动端操作要点

UniApp H5 使用底部五项导航：**首页、技能、需求、待办、我的**。

- **技能**：搜索、打开详情、按 Schema 表单或 JSON 调用；A2 以上必须先看副作用和审批状态。
- **需求**：提交业务目标，查看 `reuse/iterate/create` 分流和编译时间线。
- **待办**：查看异常运行、进行中需求、未读通知；治理角色可看到待审核事实，但移动端不绕过职责分离直接裁决。
- **我的**：确认工作空间、运行记录、反馈和已审核记忆，支持退出。
- H5 微信回调成功后会消费一次性 code 并清理 URL 中的 `oauth_code`、`client_state`、`scene` 等参数；若回跳失败，重新从登录页发起，不要重复使用旧 URL。

移动端首发不承载复杂 Schema 编辑、全量沙箱日志检索或批量治理；这些操作转到 PC/管理后台。

## 9. 角色操作边界

| 操作 | 普通使用者 | 技能作者 | 审核员 | 发布运营 | 安全/审计 | 系统管理员 |
| --- | --- | --- | --- | --- | --- | --- |
| 浏览公开/授权技能 | 是 | 是 | 是 | 是 | 是 | 是 |
| 提交需求、调用 A0/A1、评分 | 是 | 是 | 是 | 是 | 只读 | 是 |
| 创建候选、发起编译 | 否 | 是 | 是 | 是 | 只读 | 是 |
| 查看脱敏编译报告 | 自有需求 | 是 | 是 | 是 | 是 | 是 |
| 审核技能、记忆、迭代 | 否 | 不得审核本人 | 是 | 按策略 | 是 | 是 |
| staged/canary 发布 | 否 | 否 | 可批准 | 是 | 可否决 | 是 |
| stable 激活、暂停、回滚 | 否 | 否 | 需审批 | 是 | 安全暂停 | 是 |
| 全局审计、Outbox 重放、租户权限 | 否 | 否 | 否 | 受限 | 只读/受限 | 是 |

每次治理裁决都应能追溯 `actor`、角色、租户、对象、前后 digest、原因、trace 和时间。

## 10. API 快速参考（同源 BFF）

浏览器调用前缀为 `/web-api/v1`；服务间 `/api/v1` 需要短期服务身份，不应从前端直接调用。

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/web-api/v1/auth/session` | 当前会话和工作空间身份 |
| `GET` | `/web-api/v1/auth/platforms` | 登录方式 readiness（不返回密钥） |
| `POST` | `/web-api/v1/auth/login` | 账号密码登录 |
| `POST` | `/web-api/v1/auth/wechat/qr/start\|poll\|cancel` | PC 微信二维码生命周期 |
| `POST` | `/web-api/v1/auth/wechat/h5/start` | 发起移动 H5 OAuth |
| `POST` | `/web-api/v1/auth/platform-login` | 用一次性平台 code 换 WebSession |
| `POST` | `/web-api/v1/auth/logout` | 撤销当前会话 |
| `GET` | `/web-api/v1/skills`、`/web-api/v1/skills/{id}/versions/{version}` | 技能目录和详情 |
| `POST` | `/web-api/v1/demands`、`/web-api/v1/demands/{id}/generate` | 提交需求和继续生成 |
| `POST` | `/web-api/v1/runtime/resolve`、`/web-api/v1/runtime/dispatch` | 解析版本、预检并运行 |
| `GET` | `/web-api/v1/runtime/invocations` | 当前范围内运行记录 |
| `POST` | `/web-api/v1/memory/query` | 召回已审核记忆 |
| `GET/POST` | `/web-api/v1/notifications`、`/web-api/v1/notifications/{id}/read` | 通知和已读回执 |
| `POST` | `/web-api/v1/feedback/metrics` | 用户评分/有限反馈 |
| `GET` | `/health/live`、`/health/ready` | 存活和就绪状态 |

写请求必须保留 `X-CSRF-Token`、`X-Request-ID` 和幂等语义；服务端返回的 `request_id` 是排障主线。

## 11. 故障与阻断处理

| 页面状态/错误 | 含义 | 处理 |
| --- | --- | --- |
| `401` / “需要登录” | 没有有效 WebSession | 重新登录，确认租户/工作空间；不要复制他人 cookie |
| `403` / “无权限” | 角色或租户范围不允许 | 联系该租户管理员申请最小权限 |
| `503` / `blocked` | readiness、迁移、签名、下游或生产证据未就绪 | 打开“集成与能力”或 `/health/ready`，记录 blocking reason 和 request ID |
| `unknown` / `reconciliation_required` | 外部操作结果未知，不能安全重试 | 先查 provider/业务事实和对账，再按运行手册补偿 |
| `WEB_LOGIN_RATE_LIMITED` | 登录尝试超过限速 | 等待窗口恢复；检查账号、MFA 和时钟，不要并发重试 |
| `WEB_SESSION_RESPONSE_INVALID` | 登录响应缺少必要身份字段 | 联系管理员检查 IAM 投影和 tenant/workspace 绑定 |
| `WEB_LOGIN_CONTEXT_MISMATCH` | 微信 state/scene/回调上下文不一致 | 关闭旧页面，从对应入口重新发起授权 |
| `MODEL_PROVIDER_NOT_RELEASE_READY` | 模型 provider 尚未通过审批/UAT/签名门禁 | 不能把 mock 或技术探针结果宣称为生产模型能力 |

排障时提供：站点入口、环境、租户/工作空间（可脱敏）、操作时间、技能版本、运行 ID、trace/request ID 和完整错误状态。不要提交密码、二维码内容、cookie、token 或敏感业务正文。

## 12. 上线前检查清单

- [ ] 社区 IAM 登录、profile、refresh、logout 和代表性账号/MFA UAT 完成。
- [ ] 每个技能有 owner、需求来源、输入/输出 Schema、依赖锁、测试样例和风险/数据等级。
- [ ] 编译报告、Ed25519 签名、不可变 digest 和 capability 合同已核对。
- [ ] A2 以上技能完成独立审批、幂等、补偿和对账演练；A3/A4 保持人工刹车。
- [ ] 先 staged，再 canary，观察连续指标窗口后才晋级 stable；回滚路径已演练。
- [ ] 记忆 retention、删除、跨技能读取和审核职责已明确；敏感数据不进入编译 fixture。
- [ ] `health/live=200` 且 `health/ready` 的 blocking reason 已被 owner 处理；HTTP 200 不等于业务能力 ready。
- [ ] 微信 H5/小程序/App 只有在真实凭据、回跳白名单、包签名和真机验收完成后启用。
- [ ] 生产数据库、对象存储、KMS、OCI、OTLP、备份恢复和证据清单已获审批。

## 13. 维护命令（运维人员）

以下命令只在受控服务器和经过授权的虚拟环境中执行：

```bash
opc-skill-worker compile --dry-run
opc-skill-worker outbox --dry-run
opc-skill-worker retention
opc-skill-worker feedback
opc-skill-worker embedding
opc-skill-migrate check
```

`--dry-run` 只查看队列，不改变状态；Outbox 没有配置真实 sink 时保持 `pending` 是预期行为。生产迁移、备份恢复、密钥轮换和真实 provider 对账必须由对应 owner/DBA 按审批单执行。

## 14. 术语速查

- **Skill**：带 Schema、依赖、记忆和安全策略的可执行能力制品。
- **Harness**：跨项目统一的 dispatch、operation、fact 和事件合同。
- **Web BFF**：面向浏览器/移动端的同源后端门面，负责会话、CSRF、RBAC 和租户边界。
- **Release**：某个技能版本在 staged/canary/stable 通道上的可控指针。
- **fencing token**：防止旧客户端并发覆盖新发布状态的单调令牌。
- **Memory candidate**：运行后提取、尚未独立审核的记忆候选。
- **readiness**：依赖、迁移、签名、能力和生产证据均满足后的可执行状态。

最后原则：先确认身份和范围，再确认版本和风险，最后执行调用；任何不确定结果都保留事实、停止盲目重试并走对账或人工审批。