AI-OPC 技能仓库智能体操作指南
项目：opcjinengcangku    版本：0.10.10    更新：2026-09-02

一、这是什么

技能仓库把业务目标变成带输入/输出 Schema、依赖、记忆、安全策略、测试、签名和版本的
Skill 制品，再经过编译、沙箱、审批、发布和受治理运行。公开页面的示例数据只用于学习，
服务端返回 blocked、unknown 或 503 时不能当作成功。

五项目职责
opcjinengcangku：技能目录、需求分流、编译/沙箱、发布、运行、记忆和反馈治理。
aiopcshequ：统一身份、主体/租户/工作空间、社区知识和空间能力。
bangong：办公任务、文档和审批等业务执行能力。
opcshangshi：商事主体、操作、交易和对账等受控能力。
opcdamoxing：模型、知识检索和 Harness Gateway 基础能力。

二、入口和登录

官网：/
PC 用户工作台：/pc/
PC 治理后台：/admin/
移动 H5/UniApp：/uniapp/

未登录可只读浏览公开技能和 readiness；需求、运行、记忆、通知和治理数据需要有效会话。
登录方式由 /web-api/v1/auth/platforms 返回：账号密码始终是回退方式；PC 微信扫码和移动
微信 H5/小程序/App 只有 ready 且完成真实凭据、回跳白名单、包签名和 UAT 后才可启用。
MFA_REQUIRED 时输入动态码；INVALID_MFA 后重新输入动态码。登录后确认用户名、租户、工作
空间均正确。浏览器只保存 HttpOnly 会话，不保存社区 refresh token 或 service token。

三、第一次调用（A0）

1. 进入 /pc/ 的“技能市场”，搜索并打开技能详情。
2. 阅读输入/输出契约、风险、数据等级、权限、依赖和 release 通道。
3. 点击调用；有 JSON Schema 时用表单，否则用 JSON。只提交契约规定的字段。
4. 点击“预检并执行”。服务端校验会话、租户/主体/工作空间、版本、readiness、数据授权、
   审批和幂等键。
5. 在“运行记录”查看 invocation 状态、版本、trace、结果和记忆命中。unknown、
   reconciliation_required、blocked_by_policy 都不是成功。
6. 对自己已结束的运行评分 1 到 5；评分形成指标样本，不会直接修改版本。

四、提交需求和三分流

在 PC“我的需求”或移动“需求”用业务语言说明目标、范围、输出、工作空间和数据授权，
不要写入密码、验证码、token 或完整敏感个人信息。

reuse：相似度达到默认 0.86，契约兼容且已有 active 版本，直接复用。
iterate：相似度达到默认 0.62 但需要补充能力，沿用既有 Skill ID 生成补丁版本。
create：没有合格候选或契约不兼容，创建新 Skill ID。

决策会记录 resolution_strategy、resolution_score、resolution_reason 和目标版本链。
常见状态为 received -> matched -> generation_requested -> generated -> compiled ->
staged/installed；失败或 rejected 必须阅读原因和 request ID。

五、技能包学习顺序

先看 metadata（skill_id、版本、owner、需求来源），再看 input_schema/output_schema，
然后看 tool_dependencies（服务、技能、版本范围和允许操作），再看 long_memory_binding
（空间、保留期、抽取规则、cross_skill_read、写入模式），最后检查 execution_flow、
test_cases、feedback_metric 和 security（A0-A4、D0-D4、权限、网络、沙箱、签名、幂等）。
编译器会拒绝缺字段、非法版本、循环依赖、签名不匹配和资源越界。

六、发布和治理

staged 是通过编译/签名等待治理的候选；canary 按选择器或百分比小范围放量；stable 是
默认稳定通道。先 staged，再 canary，观察成功率、延迟、策略阻断、unknown 和纠正率后
才晋级 stable。激活、暂停、回滚必须携带当前 fencing_token、原因和二次确认；成功后令牌
轮换，旧令牌拒绝。回滚优先恢复同通道上一版本。

A0：只读、无副作用，可按授权调用。
A1：低风险受限动作，显示授权和审计信息。
A2：创建/修改任务等业务写入，要求独立审批、幂等和补偿。
A3-A4：高风险或外部交易，要求更严格 MFA/双人复核和人工对账，默认不自动晋级。
审批人不能审核自己的提案；前端隐藏按钮不是安全边界，真正权限由 BFF、RBAC 和服务端校验。

七、记忆和反馈

记忆按 tenant、subject、workspace、技能和环境隔离。运行后候选是 pending_review，独立
审核通过后才能召回。cross_skill_read 必须在技能包显式授权，来源空间和 active release
仍需在同租户/主体/工作空间内。删除是服务端按范围软删除并留审计。

用户评分和纠错按窗口聚合；满足样本、阈值和连续窗口后才建立迭代提案，提案还要 shadow、
人工 review、编译、签名和发布。单个低分不会直接改版本或自动回滚。

八、移动端

底部导航：首页、技能、需求、待办、我的。技能页支持搜索、详情和 Schema/JSON 调用；需求
页显示 reuse/iterate/create 和编译时间线；待办页显示异常运行、需求和通知，治理事实不能
在移动端绕过职责分离直接裁决；我的页面显示工作空间、运行、反馈和已审核记忆。复杂 Schema
编辑、全量沙箱日志和批量治理请转 PC/管理后台。微信回调失败要从登录页重新发起，不能复用旧
oauth_code、client_state 或 scene。

九、角色边界

普通使用者：浏览、提交需求、调用 A0/A1、评分。
技能作者：创建/修改候选、发起编译，不能审核自己的提案。
审核员：审核技能、记忆和迭代，可批准发布。
发布运营：执行 staged/canary/stable、暂停和回滚。
安全/审计：只读审计、可按策略否决高风险操作。
系统管理员：租户、权限、基础设施和受限重放。

十、常用 BFF API

GET  /web-api/v1/auth/session
GET  /web-api/v1/auth/platforms
POST /web-api/v1/auth/login
POST /web-api/v1/auth/wechat/qr/start|poll|cancel
POST /web-api/v1/auth/wechat/h5/start
POST /web-api/v1/auth/platform-login
POST /web-api/v1/auth/logout
GET  /web-api/v1/skills
POST /web-api/v1/demands
POST /web-api/v1/demands/{id}/generate
POST /web-api/v1/runtime/resolve
POST /web-api/v1/runtime/dispatch
GET  /web-api/v1/runtime/invocations
POST /web-api/v1/memory/query
GET/POST /web-api/v1/notifications...
POST /web-api/v1/feedback/metrics
GET  /health/live
GET  /health/ready

写请求保留 X-CSRF-Token、X-Request-ID 和幂等语义；服务间 /api/v1 不应由浏览器直接调用。

十一、故障处理

401：重新登录并确认会话。
403：联系当前租户管理员申请最小权限。
503 或 blocked：查看 readiness、集成状态、blocking reason 和 request ID。
unknown 或 reconciliation_required：先查外部业务事实/对账，禁止盲目重试。
WEB_LOGIN_RATE_LIMITED：等待限速窗口，检查账号、MFA 和时钟。
WEB_SESSION_RESPONSE_INVALID：检查 IAM profile 与 tenant/workspace 绑定。
WEB_LOGIN_CONTEXT_MISMATCH：关闭旧微信授权页，从对应入口重新发起。
MODEL_PROVIDER_NOT_RELEASE_READY：模型审批/UAT/签名未完成，不能宣称生产可用。

排障时只提供时间、环境、技能版本、运行 ID、trace/request ID 和脱敏状态；不要提交密码、
cookie、token、二维码内容或敏感正文。

十二、上线检查

[ ] IAM login/profile/refresh/logout、MFA 和代表性账号 UAT 完成。
[ ] 每个技能具备 owner、需求来源、Schema、依赖锁、测试、风险和数据等级。
[ ] 编译报告、Ed25519 签名、digest 和 capability 合同已核对。
[ ] A2 以上完成独立审批、幂等、补偿和对账；A3/A4 保持人工刹车。
[ ] staged -> canary -> stable 和回滚已演练。
[ ] 记忆 retention、删除、跨技能授权和审核职责明确。
[ ] health/live=200 且 health/ready 的阻断项已由 owner 处理。
[ ] 微信渠道具备真实凭据、回跳白名单、签名和真机验收后才启用。
[ ] 生产 PostgreSQL、对象存储、KMS、OCI、OTLP、备份恢复和证据审批完成。

维护命令（受控环境）：
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

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