平台插件 REST API 契约

Base URL：{Cadau 站点}/api/v1 版本：0.1（与 Cadau 后端 platform_plugin_*.go 一致）

适用范围：下文 REST 与 platform_plugins[] 注册仅用于 应用桌面 iframe 型插件。对话里让工作智能体调业务 API（识脸、画图等）请用 技能 + 联网能力包，见 ../../agent-capability/README.md 与 ../README.md。

---

0. 注册与插件网关

在 Cadau mindlink.json → platform_plugins[] 注册（示例 registration.example.json）：

{
  "module_id": "my-plugin",
  "display_name": "我的插件",
  "entry_base_url": "/p/my-plugin/",
  "upstream_url": "http://127.0.0.1:3010",
  "enabled": true
}

网关请求路径（浏览器 → Cadau Web → 后端 → upstream）：

GET /p/my-plugin/api/health

→ 反代到 {upstream_url}/api/health（路径前缀 /p/my-plugin 会被剥掉）。

无 upstream 时：仅 entry_base_url 指向你的公网/独立 URL，Cadau 不代理静态页与插件 API。

实现对照：backend/internal/platformplugin/proxy.go；Web Nginx location /p/ → 后端。

---

1. Cadau 侧（用户已登录）

1.1 列出已注册插件

GET /platform-plugins
Authorization: Bearer {用户 access_token}

响应 items[]：module_id, display_name, suite, icon, entry_base_url, enabled（内网 upstream_url 不返回给客户端）

1.2 启动插件

POST /workspaces/{workspace_id}/platform-plugins/{module_id}/launch
Authorization: Bearer {用户 access_token}

响应：

1.3 插件随发技能（安装到工作区技能中心）

应用型插件可在仓库携带 skills/{slug}/（见 platform-plugin §7.5）。安装进 工作区技能中心 使用 用户登录 鉴权，不是 launch_token。

产品口径：按 slug 幂等写入技能中心；区内智能体默认可召回；不要在 seed 时改写各智能体的可用技能收窄配置。

GET /workspaces/{workspace_id}/platform-plugins/{module_id}/skills
Authorization: Bearer {用户 access_token}

响应：

无已注册随发技能时返回 skills: []（仍 200）。

POST /workspaces/{workspace_id}/platform-plugins/{module_id}/skills/seed
Authorization: Bearer {用户 access_token}
Content-Type: application/json

{ "slug": "practice-checklist-to-pack" }

• 须 可管理成员。
• slug 可选；省略则安装/升级该模块全部已注册随发技能。
• 响应：{ "ok": true, "module_id", "results": [ { slug, created, upgraded, skipped, skill_id, name, fingerprint } ] }。
• 未知 module_id/slug（无注册包）→ 404。

实现：backend/internal/skillfromchat/plugin_skill_seed.go（RegisterPluginSkillBundle）；合规注册见同包 compliance_practice_seed.go；作者镜像：plugins/compliance/skills/。

---

2. 插件侧（Bearer launch_token）

以下接口 无需 Cadau 用户 Cookie，仅需：

Authorization: Bearer {launch_token}

2.1 校验会话

GET /platform-plugins/session

响应：

{
  "module_id": "my-plugin",
  "module_display_name": "我的插件",
  "user_id": "uuid",
  "user_display_name": "张三",
  "workspace_id": "uuid",
  "workspace_name": "研发团队",
  "member_role": "admin",
  "expires_at": "2026-07-02T10:00:00Z",
  "data_namespace": {
    "kind": "postgres_schema",
    "location": "ws_…",
    "schema": "ws_…"
  }
}

data_namespace：工作区插件数据隔离（Postgres schema 或 SQLite 文件路径/DSN）。Launch 响应同样包含该字段。

智能体调用插件：工具 plugin_invoke → Cadau 签发短时 JWT（knd=plugin_invoke）→ 插件 POST /api/agent/invoke。操作清单见插件 operations.json（或配置 operations_url）。

错误码：plugin_launch_invalid（过期或无效）、plugin_disabled、forbidden

2.1.1 工作区成员（绑定账号用）

GET /platform-plugins/workspace-members

Bearer launch_token。返回当前工作区成员简表（user_id、display_name、email、member_role），供插件绑定员工档案、任命插件内角色。任意工作区成员可读。

2.2 知识文档

路径均相对于插件主题目录 plugin-{module_id}/（Cadau 自动维护索引）。

列出

GET /platform-plugins/knowledge/items

读取

GET /platform-plugins/knowledge/content?path=guide.md

写入（需 member_role 为 owner/admin）

PUT /platform-plugins/knowledge/content
Content-Type: application/json

{
  "path": "guide.md",
  "content": "# 标题\n\n正文…",
  "title": "入门指南",
  "summary": "一句话摘要，供检索匹配",
  "tags": ["标签1", "标签2"]
}

删除（需 owner/admin）

DELETE /platform-plugins/knowledge/content?path=guide.md

批量同步（需 owner/admin）

POST /platform-plugins/knowledge/sync
Content-Type: application/json

{
  "documents": [
    { "path": "a.md", "content": "…", "title": "A" },
    { "path": "b.md", "content": "…", "title": "B" }
  ]
}

响应：{ "ok": true, "synced": ["a.md","b.md"], "count": 2, "theme_dir": "plugin-my-plugin" }

范围：插件知识同步为 Markdown 正文（path + content）。工作区知识里的图片/短视频等富媒体由 Cadau 产品侧管理，不经本 sync API 上传。

2.2.1 规范库只读（工作区法规与管理标准）

真源与发布流见产品 §3.2.2 / docs/core-mechanisms/规范库.md。插件仅可读 已发布且生效中 的条目。

GET /platform-plugins/standards
GET /platform-plugins/standards?tag=hr
GET /platform-plugins/standards/{standardId}
GET /platform-plugins/standards/{standardId}/content

鉴权：Authorization: Bearer <launch_token>（与知识 API 相同）。

2.2.2 资料库只读（工作区模板与表格）

真源与发布流见产品 §3.2.3 / docs/core-mechanisms/资料库.md。插件仅可读 已发布 条目；/file 返回二进制文件流。

GET /platform-plugins/assets
GET /platform-plugins/assets?tag=hr
GET /platform-plugins/assets/{assetId}
GET /platform-plugins/assets/{assetId}/file

鉴权：Authorization: Bearer <launch_token>（与知识 API 相同）。

2.2.3 工作区大模型（结构化 JSON）

插件不要自带模型 API Key。需要「根据正文生成问卷 / 推荐编制」等短时结构化结果时，经本接口使用当前工作区已配置的大模型。

与「插件内嵌助手对话」（§2.3 embed）不同：本接口是服务端一次性 system+user → JSON 文本，无会话态。

POST /platform-plugins/ai/json
Authorization: Bearer <launch_token>
Content-Type: application/json

{
  "system": "你是……只输出一个 JSON 对象：{...}",
  "user": "{ \"context\": \"…\" }"
}

响应：

{ "text": "{ \"…\": \"模型返回的 JSON 字符串（可能仍带说明文字，调用方应解析/清洗）\" }" }

官方用法参考：plugins/hr 编制智能推荐、plugins/compliance 按规范生成调查问卷。

2.3 内嵌助手令牌

POST /platform-plugins/embed-token
Content-Type: application/json

{
  "user_agent_id": "uuid",
  "app_id": "my-plugin",
  "ttl_seconds": 3600
}

响应与 POST /user-agents/{id}/embed-token 类似：access_token、token_type、expires_in、expires_at、workspace_id、user_agent_id、app_id、permanent、record_id

随后前端加载 {Cadau}/embed/mindlink-widget.min.js 并 init（见嵌入 SDK 契约）。

---

3. 插件自有 HTTP 约定（推荐）

iframe 会话：前端将 launch_token 存入 sessionStorage，后续请求带 Authorization: Bearer …。插件自有 API 路径请用相对路径或 resolvePluginAPI()，以兼容 Cadau 同源网关 /p/{module_id}/。

3.3 扩展工作流节点与清单契约（workflow_steps / rubric）

插件可在同一份 operations.json 中声明 workflow_steps，把领域自动节点挂进流程设计器（仅当该插件已启用时出现在目录中）。引擎到达该步时调用 POST /api/agent/invoke（与 plugin_invoke 同一入口）。

{
  "module_id": "my-plugin",
  "operations": [
    { "name": "workflow_load_checklist", "mutates": false, "min_role": "member" }
  ],
  "workflow_steps": [
    {
      "type": "my-plugin.load_checklist",
      "label": "加载材料清单",
      "description": "写入实例 rubric，供上传证据 / 自动评分使用",
      "color": "#0891b2",
      "kind": "auto",
      "operation": "workflow_load_checklist",
      "config_hint": "可选 phases"
    }
  ]
}

成功响应（加载类节点）：

{ "ok": true, "rubric": [ /* RubricItem[] */ ], "variables": { } }

• rubric：写入实例，供核心节点 上传证据（human.upload）与 自动评分（llm.score）消费；必须符合下表 RubricItem。
• variables：合并进实例变量（扁平键）。
• 失败：{ "ok": false, "error": "用户可见说明", "rubric": [] }。

#### RubricItem（清单条目 · 实现真值）

与后端 backend/internal/standards.RubricItem、SDK 类型 RubricItem（Go / TS）对齐。其它领域（入职材料、培训确认等）加载节点须输出同一形状，勿另起字段名。

参考实现：plugins/compliance 的 workflow_load_check_items → toRubric。产品侧说明见 docs/core-mechanisms/workflow.json-v1.md §检查项清单契约；机制指南见 ../README.md §6.1。

3.1 宿主 ↔ 插件 postMessage

3.2 Cookie / 存储命名（勿混用）

---

4. 安全响应头（插件服务）

Content-Security-Policy: frame-ancestors 'self' http://localhost:8080 http://127.0.0.1:8080

生产环境替换为客户 Cadau Web 源。Go SDK：mindlinkplugin.FrameAncestorsCSP(...)。

---

5. 错误体

{
  "error": "用户可见说明",
  "code": "machine_code",
  "request_id": "…"
}

常见 code：unauthorized, plugin_launch_invalid, forbidden, validation_error, not_found