插件应用 SDK（platform-plugin）

目录名：sdk/platform-plugin 用途：应用型平台插件（应用桌面 iframe）——注册 platform_plugins[]、launch_token、知识同步、内嵌助手、plugin_invoke。

代码包：go/（Go）、js/（TypeScript）、contracts/、templates/starter/。

对话型能力（消息里调 API、不注册 platform_plugins）见 agent-capability，不在本目录注册流程内。

关联：

• 产品规格.md §4.2.4（平台插件模块）
• 工作区能力包.md（工作智能体联网、http_request）
• 技能组成规范.md（对话中如何调用业务 API）
• host-embed/SDK契约.md（插件内嵌助手）
• 智能体调用知识文档的方式.md（知识如何进入对话）
• 并列 SDK：appsdk · host-embed · agent-capability · 本目录

1. 选型（与 agent-capability 的分工）

只有应用桌面 iframe 型插件才用 platform_plugins[] + 本目录代码包。勿把「识脸、画图、调业务 API」一律注册成应用桌面插件——那类需求见 agent-capability。

| | 插件工具（agent-capability） | 插件应用（本目录） | |--|-----------------------------------|------------------------| | 用户场景 | 在 消息 里对工作智能体说话 | 在 应用 桌面打开完整 Web | | 注册 platform_plugins | 否 | 是 | | 文档 | agent-capability | 本文 + sdk/README.md |

1.2 应用型平台插件（示例：组织架构）

1. 在 mindlink.json 注册 platform_plugins[]（entry_base_url、upstream_url 等）。
2. 用户从 应用桌面 打开；Cadau 签发 launch_token，iframe 加载你的 Web。
3. 可选：同步 知识文档 供工作区智能体检索；在插件页 内嵌助手（embed widget）。

范例：plugins/hr/（官方人力资源 + 知识同步 + plugin_invoke）；plugins/email/（邮件，IMAP/SMTP）；plugins/camera/（摄像头，人脸识别考勤、安防与录像回放）。用户说明见 help/product-features/platform-hr.md、platform-email.md、platform-camera.md。打开插件时，Cadau 壳上的操作助手使用工作区 默认应用助手（工作智能体）；产品界面其它模块仍用帮助智能体。

1.3 既要界面，又要在消息里用上插件能力

可同时组合（当前实现），不是一条 platform_plugins 注册自动搞定全部：

插件同步的知识会被 对话检索 注入；不会自动把插件 REST 注册为 agent tool，也 不会把 skills/ 目录自动变成技能中心条目——须按 §7.5 安装。若要在消息里「执行识脸接口」，仍须技能 + http_request（或未来 MCP）。

1.4 决策树

需要应用桌面里的完整 Web 界面？
  ├─ 否 → agent-capability：能力服务 + 技能 + 联网能力包
  └─ 是 → 应用型平台插件：platform_plugins + sdk/platform-plugin/go*
        ├─ 还要背景说明进对话？→ knowledge/ 同步（§7）
        ├─ 还要程序性操作手册？→ skills/ 随发 → 安装到技能中心（§7.5）
        └─ 还要消息里调外部 HTTP API？→ 再加技能 + 联网能力包

2. 分工（应用型平台插件）

Cadau 不提供完整业务 SDK（如组织架构 CRUD）；插件自建业务 API，数据键使用 workspace_id，无独立登录。

专业应用放到 其它服务器、与工作区 自建应用 如何分工：设计稿 两种应用运行时（待实施，不以该稿覆盖本文已上线行为）。

打开的填写弹层必须让应用助手 认出并回填（§6.2），这是平台能力，不是某一应用的特例。

3. 接入流程

sequenceDiagram
  participant U as 用户
  participant ML as Cadau
  participant P as 平台插件

  U->>ML: 应用桌面打开插件
  ML->>ML: POST launch → launch_token
  ML->>P: iframe entry_url?launch_token=…
  P->>ML: GET /platform-plugins/session
  P->>P: 可选 SyncKnowledgeFromDir
  P->>ML: POST /platform-plugins/embed-token
  P->>ML: 加载 /embed/mindlink-widget.min.js
  U->>ML: 在插件内与助手对话（含已同步知识）

1. 在 mindlink.json 注册 platform_plugins[]（module_id、entry_base_url、upstream_url 等）。
2. 插件入口读取 launch_token，调用 GET /api/v1/platform-plugins/session 验身。
3. 插件将 knowledge/*.md 同步到 Cadau（见 §5）。
4. 有填写弹层：上报 plugin_ui_changed + 实现 fill_open_form（见 §6.1）。
5. 可选：签发 embed-token，在插件页嵌入 Cadau 助手。

4. SDK 包

第三方开发入口：[../../../sdk/README.md](/docs/sdk-overview)

范例：plugins/hr/（官方人力资源插件 + 知识同步 + plugin_invoke）。旧组织架构范例已并入该插件。用户说明：help/product-features/platform-hr.md；知识：plugins/hr/knowledge/。

5. 工作区数据命名空间（共用 Cadau 库）

官方推荐插件业务数据落在 Cadau 同一数据库，按工作区隔离：

• Cadau 在 创建工作区 与 launch/session 时幂等 Ensure。
• 插件在 GET /platform-plugins/session 响应中读取 data_namespace，自行迁移业务表。
• 插件进程需能访问同一 DATABASE_URL（Postgres）或同一主机上的 SQLite 路径（Docker 开发请挂载 RUNTIME_DIR 或改用 Postgres）。

第三方仍可自建独立库（仅 workspace_id 行隔离）；与命名空间方案可并存。

6. 智能体操作插件（plugin_invoke）

所有平台插件应提供：

1. operations.json（或配置 operations_url）：操作名、描述、mutates、min_role、dangerous、参数 schema。
2. POST /api/agent/invoke：校验 Cadau 签发的 plugin_invoke 短时 JWT（非 launch_token），执行业务并返回 JSON。
3. 有填写弹层时：fill_open_form（mutates: false）+ iframe 上报当前界面（§6.1）。无弹层的纯只读应用可省略。

帮助智能体与工作智能体均可调用工具 plugin_invoke（帮助侧仅此工具）。写操作默认 min_role=admin；dangerous=true 须用户确认后 confirm=true。调用写入 plugin_invoke_audit。

6.1 认正在填的单（必接）

用户在应用里打开 填写弹层 / 抽屉 / 草稿 时，Cadau 壳上的应用助手必须：

1. 问「当前界面」时点明这张单，不要只说页签。
2. 无特殊说明时，自然语言操作默认针对当前界面（当前应用、页签、已打开的填写弹层）。用户不必点名「这张单」；补字段写回当前草稿并立刻显示。form 可省略，宿主按当前弹层回填。
3. 未说「保存 / 创建 / 提交 / 办结」前，不要调用会立刻写入系统的创建/更新操作。

这是 平台约定，与是否人力资源无关。字段级契约见 [contracts/API.md §3.2](/docs/sdk-platform-api)。

React 参考：plugins/hr/app/PluginUiSurface.tsx（复制后改 moduleId）。最小可跑：templates/starter/（含草稿示例）。

关闭弹层时 dialog 传空字符串。查看-only 弹层设 readonly: true，助手只点明标题、不填表。

检查清单：

• [ ] 打开/改/关草稿都会 postPluginUiChanged（关时 dialog=""）
• [ ] operations.json 含 fill_open_form（mutates: false）
• [ ] invoke 返回 ui_action: "fill_form"，且不写业务表
• [ ] listenHostPluginFormFill 把 fields 写进当前打开的输入框
• [ ] 知识文档写明：对应用助手说字段会写回当前草稿（不必点名单据）；没说保存前不入库

6.2 扩展工作流节点（workflow_steps）

插件可在同一份 operations.json 中声明 workflow_steps，把领域自动节点挂进流程设计器（仅当该插件已启用时出现在目录中）：

{
  "module_id": "compliance",
  "operations": [{ "name": "workflow_load_check_items", "mutates": false, "min_role": "member" }],
  "workflow_steps": [
    {
      "type": "compliance.load_check_items",
      "label": "加载检查标准",
      "description": "从合规检查项读取评分依据",
      "color": "#0891b2",
      "kind": "auto",
      "operation": "workflow_load_check_items",
      "config_hint": "可选 phases；检查项来自流程设置绑定的调查问卷"
    }
  ]
}

自动节点约定返回：

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

• rubric：写入实例评分/上传依据；元素必须符合平台 RubricItem 契约。加载类节点必填。
• variables：合并进实例变量（扁平键）。写回类节点（如人力资源「确认用人需求」）可只返回 variables。
• ok: false 时可带 error 文案；勿返回形状不合规的清单条目。

等待节点（kind: wait）约定返回：

{ "ok": true, "pending": true, "variables": { } }

或已结束：{ "ok": true, "pending": false, "outcome": "pass", "variables": { } }。恢复：POST /api/v1/platform-plugins/workflows/plugin-wait/complete（launch 会话鉴权）。设计器对 wait 拉通过/不通过出线；试走主路径走 pass。

实现真值（插件 SDK）：字段表与响应约定见 [sdk/platform-plugin/contracts/API.md §3.3](/docs/sdk-platform-api)；Go/TS 类型 RubricItem / WorkflowLoadRubricResult。产品/引擎侧摘要见 workflow.json-v1.md §检查项清单契约。

参考实现：plugins/compliance/lib/workflowOps.ts 的 toRubric。其它领域加载节点应输出同一形状，即可直接接核心「上传证据」「自动评分」。

Cadau：GET /workspaces/{id}/workflows/step-catalog 合并核心目录与已启用插件的 workflow_steps。

6.3 发起审批：把单据快照写进流程

从插件 提交即审批（用人需求、入离调、报销等）时，调用 POST /platform-plugins/workflows/start，在 variables.approval_doc 带上办理人要看的全文。引擎提到实例载荷，审批页直接渲染；不会再向插件拉取单据。禁止只传 id / 标题再让人跳回应用。

import { withApprovalDoc } from "@mindlink/plugin-sdk";

await client.startWorkflow({
  definition_id,
  title: "提交用人需求 · YR-2026-0001",
  variables: withApprovalDoc(
    { staffing_req_id },
    {
      title: "用人需求 YR-2026-0001",
      fields: [
        { label: "申请人", value: "陈晨" },
        { label: "申请部门", value: "职能支持" },
      ],
      tables: [{ title: "明细", columns: ["部门", "岗位", "人数"], rows: [["职能支持", "财务专员", "1"]] }],
    },
  ),
});

短单（无明细表）可用 fieldListApprovalDoc("入职办理", [["姓名", "陈晨"], ["工号", "E001"]])。Go：Client.StartWorkflow、WithApprovalDoc、FieldListApprovalDoc。

自动节点 invoke 也可返回顶层 approval_doc（流程中才生成的单据）。契约与字段表见 [contracts/API.md §2.4](/docs/sdk-platform-api)。

7. 知识文档：真源在插件，检索走 Cadau

与规范库：政府/行业法规、跨插件共用的管理制度与理论真源见产品 §3.2.2 与 [规范库.md](/docs/mech-standards)。本节 API 仅覆盖各插件自己的 操作说明（plugin-{module_id}/），不要把法规全文只 sync 进某一插件主题当作全工作区真源。

读规范库（已实现）：GET /platform-plugins/standards、…/{id}、…/{id}/content（Bearer launch_token，仅已发布且生效中）；Go Client.ListStandards / JS listStandards。

与资料库：共用表格/表单模板见产品 §3.2.3 与 [资料库.md](/docs/mech-assets)。

读资料库（已实现）：GET /platform-plugins/assets、…/{id}、…/{id}/file（Bearer launch_token，仅已发布）；Go Client.ListAssets / JS listAssets；文件为二进制流。

调用工作区大模型（已实现）：POST /platform-plugins/ai/json（Bearer launch_token）→ 用工作区配置的模型返回结构化 JSON 文本；Go Client.AIJSON / JS client.aiJSON；契约见 [sdk/platform-plugin/contracts/API.md](/docs/sdk-platform-api) §2.2.3。

7.1 原则

• Markdown 文件保存在插件项目（如 knowledge/guide.md），随插件发版。
• 对话检索仍用 Cadau 工作区知识机制（两层 index.json + 按问题匹配），不改为插件自建向量库。
• 同步后写入运行时目录 plugin-{module_id}/，并在工作区根 index.json 注册主题；工作区智能体（含插件内嵌助手）对话时自动注入。
• 插件 sync API 仅同步 Markdown 正文；工作区知识中的图片/短视频等富媒体由 Cadau 产品侧管理，不经 knowledge/sync 上传。

7.2 API（Bearer launch_token）

Go 便捷方法：

synced, err := mindlinkplugin.SyncKnowledgeFromDir(ctx, client, "./knowledge")

7.3 本地开发可选：卷挂载

同机 Docker 可将插件 knowledge/ 挂载到 Cadau 运行时对应路径，免同步；生产与多机部署仍推荐 API 同步。

7.4 工作区大模型（结构化 JSON，非对话）

应用型插件若要在自己的业务 UI里做短时智能（例如根据规范正文生成问卷、按部门职能推荐编制），应调用 Cadau：

POST /api/v1/platform-plugins/ai/json
Authorization: Bearer <launch_token>

• 模型与密钥：使用当前工作区已配置的大模型；插件不直连厂商、不持有 API Key。
• 入参：system + user（提示词）；出参：{ "text": "<JSON 字符串>" }。
• 与内嵌助手的区别：§8 的 embed 是用户在插件页里对话；本接口是插件后端一次性结构化生成，无聊天会话。
• 未配置模型：返回不可用错误；插件应有规则/模板兜底（见 HR / 合规插件）。
• SDK：

const text = await client.aiJSON(
  "你是……只输出 JSON：{\"items\":[...]}",
  JSON.stringify({ context: "…" }),
);
const data = JSON.parse(text);

text, err := client.AIJSON(ctx, system, user)

明细与长度限制（Unicode 字符：system≤3.2 万、user≤40 万）见 [sdk/platform-plugin/contracts/API.md](/docs/sdk-platform-api) §2.2.3。业务侧（如合规问卷）可再设更严的正文合计上限并提示分批。

7.5 插件随发技能（工作区技能中心）

应用型插件除了 knowledge/（背景材料）外，还可在仓库内携带 技能包：教智能体 怎么做 一类插件领域操作（步骤、映射、调用 plugin_invoke / 规范库 / 资料库等）。技能正文契约见 技能组成规范.md。

7.5.1 与知识、联网技能的分工

| | 插件知识（§7） | 插件随发技能（本节） | §1.1 联网技能 | |--|-------------------|-------------------------|-------------------| | 用户说法 | 操作说明、领域背景 | 可复现的操作手册 | 调外部 HTTP API 的手册 | | 仓库位置 | knowledge/*.md | skills/{slug}/SKILL.md（+ references/ 等） | 任意；常只在技能中心维护 | | 进入工作区 | knowledge/sync → plugin-{module_id}/ | 安装进技能中心（按 slug 幂等） | 手工创建 / 导入 / 目录安装 | | 对话用法 | 检索注入背景 | 触发说明召回 / /技能 | 同左 + http_request |

7.5.2 仓库目录约定

plugins/{module_id}/
  knowledge/                 # §7 同步
  skills/
    {slug}/
      SKILL.md               # 必填：frontmatter name/description + 操作正文
      references/            # 可选：长说明、列映射、样例指针
        seed-fingerprint.txt # 推荐：内容指纹，供升级比对
  samples/                   # 可选：与技能对照的样板文件（不必进技能 zip）

• slug：稳定标识（小写连字符），安装与升级均按此幂等，勿随意改名。
• 作者镜像：插件仓内 skills/ 便于发版与评审；运行时真源可以是 Cadau 后端嵌入包（官方插件常用），或与仓内目录保持字节级同步。
• 不要把技能正文只放进 knowledge/ 指望同步——知识检索 不会替代技能中心召回。

7.5.3 安装与升级（必守产品口径）

1. 作用域：安装目标是 工作区技能中心；区内智能体 默认可召回。
2. 禁止：静默把技能写进某一只智能体的「可用技能」收窄列表；勿在文案里引导「绑定到某某智能体」作为安装步骤。
3. 首次安装：建议在用户 打开该插件（应用桌面进入模块）时，由 可管理成员 确认后再 seed；「暂不」只跳过提示，不妨碍日后再次提示或升级。
4. 内容升级：用内容指纹（如 references/seed-fingerprint.txt）比对；已安装且指纹落后时，再次打开插件可 静默升级 技能正文与附属文件（无需清浏览器、无需重装）。
5. 权限：seed / 升级须工作区 可管理成员；普通成员可打开插件，但不替全区装技能。

7.5.4 宿主侧接口（通用）

用户登录鉴权（与 launch 同属 §1 用户态；不是 launch_token）：

后端注册：官方插件在 init 中 skillfromchat.RegisterPluginSkillBundle(...)，将 skills/{slug}/ 嵌入 backend/internal/skillfromchat/bundled/。首期范例：module_id=compliance → practice-checklist-to-pack。

响应与字段见 [sdk/platform-plugin/contracts/API.md](/docs/sdk-platform-api) §1.3；机制稿 [合规实践检查表转机读包.md](/docs/mech-check-pack)。

第三方插件在未把包嵌入 Cadau 前，可：

• 提供可下载的技能 zip，引导管理员用技能中心 导入；或
• 向 Cadau 发版侧贡献 embed 注册（与合规相同路径）。

7.5.5 检查清单

• [ ] skills/{slug}/SKILL.md 含清晰 适用 / 不适用 触发说明
• [ ] 稳定 slug；升级靠内容指纹，不靠改 slug
• [ ] 打开插件时：未装 → 确认安装；已装落后 → 静默升级
• [ ] 成功文案写「技能中心 / 区内智能体可召回」，不写「已绑定某智能体」
• [ ] 与 knowledge/、plugin_invoke、规范库/资料库只读 API 的职责不混用

8. 插件内智能体问答

1. 在工作区创建或选择 「我的智能体」，记下 user_agent_id。
2. 插件调用 POST /platform-plugins/embed-token（body：user_agent_id）。
3. 前端加载 {Cadau 站点}/embed/mindlink-widget.min.js，传入 auth.token、workspace_id、user_agent_id（见 host-embed/SDK契约.md）。

助手会使用 工作区知识（含已同步的插件知识），无需插件自行实现 RAG。

9. 安全与 CSP

• 插件响应需设置 frame-ancestors，允许 Cadau Web 源 iframe 嵌入（如 http://localhost:8080）。
• launch_token 有效期约 15 分钟；Cadau 壳在过期前约 2 分钟会静默重新签发，并向 iframe postMessage { type: "mindlink:launch_token", launch_token, expires_at }（同时刷新网关 Cookie）。插件须写入 sessionStorage（见 JS SDK listenHostLaunchToken），用户无需退回应用桌面。
• 若宿主登录已失效或续签失败，插件 API 会 401，此时再从应用桌面重新打开。
• 知识写入限 工作区 owner/admin（与插件业务「可管理」角色一致）。
• 智能体写操作走 plugin_invoke JWT + min_role / dangerous 确认，并记入审计表。

9.1 跟随宿主主题

Cadau Web 打开平台插件时：

1. 在入口 URL 附加 ?theme=light|dark（已解析「系统」模式后的生效主题）。
2. 宿主主题变化时向 iframe postMessage：

{ "source": "mindlink", "type": "mindlink:theme", "theme": "dark" }

插件应设置 document.documentElement.dataset.theme，并用与宿主一致的 CSS 变量（见 client/web 的 --bg / --card / --primary 等）。官方范例：plugins/hr/app/HostThemeSync.tsx。

宿主还会在启动令牌即将过期时推送：

{ "source": "mindlink", "type": "mindlink:launch_token", "launch_token": "…", "expires_at": "…" }

插件须更新本地存的启动令牌（listenHostLaunchToken / sessionStorage），否则带旧 Bearer 的请求会先于新 Cookie 被拒。

热重载或 API 401 时，插件可主动请求续签（source 必须为 mindlink-plugin）：

{ "source": "mindlink-plugin", "type": "mindlink:request_launch_token" }

JS SDK：requestHostLaunchToken()。宿主还会推送：

插件 → 宿主（当前栏目，供 Cadau 小屏顶栏显示栏目名）：

{ "source": "mindlink-plugin", "type": "mindlink:plugin_tab_changed", "module_id": "hr", "tab": "recruit", "title": "用人需求" }

插件 → 宿主（填写弹层，§6.1）：

{ "source": "mindlink-plugin", "type": "mindlink:plugin_ui_changed", "module_id": "my-plugin", "dialog": "draft", "dialog_title": "示例草稿", "form": {}, "field_hints": "名称", "readonly": false }

Cookie / 存储勿混用：网关 Cookie ml_plugin_gw、插件 origin Cookie ml_plugin_launch、前端 sessionStorage 键 ml_plugin_launch_token（见 [sdk/platform-plugin/contracts/API.md](../contracts/API.md) §3.4）。

10. 本地联调

见 deploy/plugin-dev-platform/README.md（Cadau Docker 8080/8082）与 plugins/hr/README.md。

典型步骤：

1. 启动 Cadau Docker 栈。
2. plugins/hr 配置 .env（含可选 MINDLINK_USER_AGENT_ID、MINDLINK_DATABASE_URL / MINDLINK_JWT_SECRET）。
3. run.cmd 启动插件（本机 3011，经 Cadau /p/hr/ 反代）。
4. 8080 登录 → 工作区 → 应用 → 打开 人力资源 → 同步知识 → 使用内嵌助手或对话中 plugin_invoke。

插件网关（推荐）

公网鉴权（C+D）：

插件前端调用自有 API 须用 相对路径 或 JS SDK 的 resolvePluginAPI() + createAuthorizedFetch()（自动带 Bearer 与 credentials: "include"）。

11. 实现对照