智能体
操作指南

01 / ECOSYSTEM

先认识五项目协同关系

技能仓库是能力编排和治理中心；统一身份、业务域和模型基座由其他项目提供。跨项目调用始终经过服务端连接器，前端不会持有服务凭证。

02 / START HERE

入口与首次登录

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

03 / FIRST RUN

五分钟完成第一次调用

以公开的 A0 只读技能为例。A0 没有业务副作用，但仍受身份、租户、数据等级和 readiness 约束。

1. 进入 PC“技能市场”，按关键词或业务域筛选并打开详情。
2. 阅读输入/输出契约、风险等级、数据等级、权限、依赖和 release 通道。
3. 点击“调用”。有 JSON Schema 时用结构化表单，否则使用 JSON 模式，只提交契约规定字段。
4. 点击“预检并执行”，等待服务端完成会话、范围、版本、readiness、审批和幂等校验。
5. 在“运行记录”查看 invocation 状态、技能版本、trace、结果摘要和记忆命中数。
6. 对自己已结束的运行评分 1-5 分；评分进入指标样本，不会直接修改技能版本。

{
  "workspace_id": "workspace-demo"
}

04 / DEMAND LOOP

从业务需求生成技能

提交前写清楚目标

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

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

• 确认工作空间和风险上限，不能用文字参数覆盖服务端绑定的租户/主体/工作空间。
• 创建、修改、付款、通信或提交外部表单等副作用必须明确写出。
• 不要在需求文本中放密码、验证码、access token、银行卡号或完整个人敏感信息。
• 重复提交先刷新原需求，不要并发连点；客户端和服务端都保留幂等语义。

理解三分流

决策会持久化 resolution_strategy、resolution_score、resolution_reason 和目标版本链。常见时间线为 received → matched → generation_requested → generated → compiled → staged/installed。

05 / SKILL PACKAGE

技能包学习卡

技能包遵循 opc.ai/v1 的 Skill 合同。学习时先理解“输入和承诺”，再检查“依赖和边界”，最后验证“证据和反馈”。

{
  "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": {
    "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", "cross_skill_read": []},
    "execution_flow": [{"id": "return", "type": "return"}],
    "test_cases": [{"id": "normal", "expected": {"status": "pass"}}]
  },
  "security": {"risk_level": "A0", "side_effects": "none", "data_classes": ["D0"], "idempotency": "required"}
}

06 / GOVERNANCE

发布、版本与审批

1. 在管理后台核对候选 digest、签名、编译报告、依赖和审批证据。
2. 先 staged，再 canary；观察成功率、延迟、策略阻断、unknown 和纠正率。
3. 激活、暂停、回滚必须提交当前 fencing_token、原因并二次确认；成功后 token 立即轮换。
4. 回滚优先恢复同通道上一版本；不要删除仍被运行或对账引用的版本。

风险等级

07 / MEMORY & FEEDBACK

用记忆和反馈让技能持续学习

专属记忆

• 记忆按 tenant_id、subject_id、workspace_id、技能和环境隔离。
• 运行后的候选先是 pending_review，独立审核接受后才可召回。
• cross_skill_read 必须在技能包显式授权，来源空间、版本和范围仍需同租户/主体/工作空间。
• 删除是服务端按范围软删除并留审计，清理浏览器缓存不会删除服务端记忆。

反馈迭代

评分、纠错和运行指标按窗口聚合。达到样本数、阈值和连续窗口后才创建迭代提案；提案还要经过 shadow 回放、人工 review、重新编译、签名和发布。单个低分不会直接改版本或自动回滚。

08 / MOBILE

移动端操作要点

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

微信回调失败要从登录页重新发起，不能复用旧 oauth_code、client_state 或 scene。复杂 Schema 编辑、全量沙箱日志和批量治理转到 PC/管理后台。

09 / ROLES

角色操作边界

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

10 / API QUICK REFERENCE

同源 BFF API 快速参考

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

11 / TROUBLESHOOTING

故障与阻断处理

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

12 / RELEASE CHECK

上线前检查清单

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