与 Agent 集成

内置 Agent 本身是个插件，与它的集成是双向的：

• 你增强它——投一份”技能”，Agent 就懂了你的领域知识、多了你的工具、甚至换上你定义的人格（走通用的插件间贡献点机制）；
• 它增强你——你的插件 UI 里可以直接借用 Agent 的 AI 通道，几行代码嵌一个”编辑点 AI”（内置公式小抄的公式微面板就是这么做的）。

本篇两个方向都讲透。

贡献点机制 30 秒版

任何插件都能在 manifest 里开放一个点（contributionPoints，点名必须带自己的 id 前缀）或向别人的点投稿（contributions，纯数据 ≤64KB）。点的 owner 决定数据语义；投稿方下线，数据整体退场。Agent 开放的点叫 xinghan.agent-anthropic/skills。

"contributes": {
  "contributions": [
    { "point": "xinghan.agent-anthropic/skills",
      "data": { /* 一份 AgentSkill,下详 */ } }
  ]
}

static 插件也能投（无进程、加载时宿主代注入）—— 纯知识型技能连后端都不用写。

一份技能长什么样

技能按渐进披露分层设计 —— Agent 不会把你的全部内容塞进每次对话，而是按需加载：

// 内置 formula-tips 插件的真实投稿(节选)
{
  "id": "formula-tips",
  "name": "公式小抄",
  "description": "公式微面板的函数速查与书写偏好",
  "instructions": "写公式时的偏好:优先用 IF/AND/OR 组合;日期差用 DATEDIF(开始, 结束, \"d\");文本拼接用 & 而不是 CONCAT;引用字段用 {字段名} 语法。输出只给公式本身。",
  "quickChips": ["写一个逾期天数公式（今天减截止日期）", "按金额分档"],
  "surfaces": ["micro-panel"],
  "scope": { "fieldType": "formula" }
}

各层职责：

层	字段	何时被 Agent 消费
L0 目录	description	恒在 —— 一句话说清”这个技能什么时候有用”，Agent 靠它决定要不要加载
L1 知识	instructions	按需加载 —— 语法、约定、示例的全量文本
L1.5 文档集	docs[]	instructions 保持短”路由页”，细则各自成篇，Agent 按需拉单篇（防知识膨胀成大杂烩）
L2 工具	tools[]	激活后挂载 —— 给模型的新工具（下详）

其余字段：

• surfaces —— 技能在哪生效：main-chat（主对话）/ micro-panel（字段旁的微面板，如公式输入框边上那个小 AI）/ automation-node；
• scope —— 作用域：不填=全局；fieldType 限定字段类型、nodeType 限定节点类型、nodeId 绑定具体表（做”表级人格”用，特异性最高）；
• quickChips —— 预置的一键提问，出现在对应界面里；
• persona —— 人格：{ text } 作为独立前置段进系统提示，配合 scope.nodeId 就是”这张表的专属 AI 人设”。同作用域多个投稿按特异性选取（nodeId > nodeType > 全局）。

投工具:声明是数据,执行回你的进程

工具声明是纯数据（跨进程投稿没法带函数），执行时 Agent 经宿主反代调回你的插件进程：

"tools": [
  { "name": "validate_formula",
    "description": "校验一段公式的语法,返回错误位置与修正建议",
    "inputSchema": {
      "type": "object",
      "properties": { "formula": { "type": "string" } },
      "required": ["formula"]
    },
    "effect": { "kind": "readonly" } }
]

插件后端挂执行端点（node 运行时）：

import { skillToolsMiddleware } from '@xinghan/plugin-sdk/server'

app.use(skillToolsMiddleware({
  validate_formula: async (args, req) => {
    const formula = String(args.formula ?? '')
    return checkFormula(formula)   // 返回可 JSON 序列化的结构化结果
  },
}))

四条执行纪律（都是契约，不是建议）：

• 返回 canonical 数据，别拼展示文案 —— 渲染归渲染；
• 抛错写给模型看：错误会收敛成 tool_result 的 isError，模型照着自纠，不会挂掉会话；
• v1 跨进程工具只放行 readonly：这是能力注入层强制的（执行请求不带写 token，声明成写也写不动）—— 要读表用 req.grant 建受限客户端；
• 工具名装配时自动加 <你的插件id>__ 前缀，不用担心和别的插件撞名。

能做出什么

组合这些原语的真实形态：

• 领域知识包（纯 static）：让 Agent 懂你行业的术语、约定、模板 —— 一个 manifest 就是一个”提示词专家包”；
• 查校工具：公式校验、数据质量检查 —— Agent 对话中随手调用；
• 表级人格：persona + scope.nodeId，给”客服工单表”配一个客服语气的专属助手；
• 微面板增强：surfaces: ["micro-panel"] + quickChips，出现在字段编辑旁的轻量 AI 里。

反向:在你的插件里借用 Agent 的 AI 能力

你的编辑器想要一个”编辑点 AI”（重写选中段落、生成公式、解释数据）？不用自己接模型 —— Agent 插件开放了微对话通道：无会话、不落库、流式返回，模型配置直接复用用户在 Agent 设置里配好的 provider。SDK 提供两层封装，按需选：

① 开箱面板:一行挂载

不想画 UI 就用现成的（✨按钮 + 弹出面板，自动跟宿主主题）：

import { mountMicroPanel } from '@xinghan/plugin-sdk/ui'

const panel = mountMicroPanel(el, {
  pluginId: 'vendor.excel-field',            // 必传:服务端按它记账限流
  context: () => editor.getDraftJson(),      // 局部上下文(函数求值,拿最新草稿)
  hints: 'excel 公式语法;只输出公式本身',      // 你的领域知识
  quickChips: ['求和行', '转置'],
  onApply: (text) => editor.applyToDraft(text),  // 只改草稿,落库归用户保存
})
// 卸载:panel.dispose()

② 裸通道:UI 完全自己画

ghost text、diff 预览这类深度定制用低层客户端：

import { createMicroClient, agentChannelAvailable } from '@xinghan/plugin-sdk/ui'

// 启动时探测:Agent 插件被禁用/未装就隐藏 AI 入口(优雅降级,别让用户点出报错)
if (await agentChannelAvailable()) {
  const client = createMicroClient({ pluginId: 'vendor.markdown' })
  const abort = client.run(
    { message: '改得更正式',
      context: editor.getSelectedParagraph(),
      hints: '重写自然段;保持 markdown 语法;只输出重写后的段落' },
    (ev) => {
      if (ev.type === 'text_delta') showGhostText(ev.text)
      if (ev.type === 'done') showApplyButton()
      if (ev.type === 'error') showError(ev.message)
    },
  )
}

一条贯穿的治理约束：AI 只产出文本,apply 只作用于草稿 —— 落库仍然是用户点保存。草稿态即治理，你不需要（也不该）替 AI 直接写库。

hints/context 怎么组才好用

内置公式面板是最佳实践范本，三条经验直接搬：

• 能引用的东西给全清单——context 里带本表全部字段名（跨表场景还带目标表可引用列）。模型不知道有什么字段就只能编；
• 函数/语法给完整签名，不只给名字——公式面板把 51 个函数的”签名+一句用途”全量放进 hints（约 500 token）。参数顺序、可选参数是模型最易幻觉的地方，只给名字必错一半；这点 token 花得值；
• 用户的半成品进 context——当前草稿 + 实时校验报错一起带上，并在 hints 里明说”在草稿基础上补全修正，别推倒重来”。用户写到一半求助是常态，推倒重来的 AI 没人爱用。

案例:Agent 插件对外开放的能力面

Agent 是”插件开放能力给其它插件”的最完整范本 —— 它对外的每一面都值得当模式参考：

开放面	形态	你怎么用
xinghan.agent-anthropic/skills	贡献点（manifest 静态投稿）	投知识/工具/人格，见上文
/plugins/xinghan.agent-anthropic/api/chat/micro/turn	HTTP 端点（同源绝对路径）	微对话 AI 通道，SDK 已封装
/plugins/xinghan.agent-anthropic/healthz	探活端点	agentChannelAvailable() 优雅降级
satellite:agent	卫星库（会话数据）	声明后可读 Agent 对话史（审计/分析类插件）

注意这四种形态正好是插件间协作的全部原语：贡献点收数据、HTTP 端点提供服务、探活撑降级、卫星库开数据面。你的插件要向生态开放能力时，照这个组合抄 —— 开自己的贡献点（contributionPoints，点名带你的 id 前缀）、在自己的 server 上开 API 端点（别的插件 iframe 同源可达 /plugins/<你的id>/…）、留一个 healthz。

范例对照

• formula-tips（plugins/marketplace/formula-tips/）—— 投稿方向的最小形态：纯知识 + quickChips；它的公式微面板同时也是借用方向的活例（micro-panel surface）。工具投稿（L2）暂无内置范例,按上文声明形状 + skillToolsMiddleware 组合即可。