Agnes Harness 前端插件教程：为Web工作台定制业务面板（完整示例）-平芜编程栈

【免费下载链接】agnes-harness

Agnes Harness: A pluggable agent harness for Forward Deployed Engineering (FDE). Built for trust. Made for the real world.

项目地址：https://gitcode.com/gh_mirrors/ag/agnes-harness

点击查看免费下载

Agnes Harness 前端插件教程：只需一个声明文件加几行 ESM 代码，就能在 Agnes Harness 的 Web 工作台里挂上你自己的业务面板，替换内置侧栏、读取后端服务数据，并支持无刷新版本更新与一键停用回滚。下面用仓库自带的client-panel完整示例带你从零走一遍。

一、先搞懂：前端面板插件是什么 🧩

Agnes Harness 的工作台界面由一组**插槽（Slot）**组成，比如侧栏区域ui:sidebar。前端插件做的事情很简单：

通过 package.json 里的agnes.clientDescriptors声明一个浏览器模块描述符；
浏览器加载后调用你的apply(ctx, config)函数，你用ctx.slots.register()把组件挂进指定插槽；
插槽是单例类型时，优先级数值越低越优先，示例用priority: -1替换内置侧栏。

插件被禁用或删除时，注册会自动撤销，内置界面立即恢复——你不需要写任何"卸载清理"代码。

二、面板插件包的完整目录结构

官方教程推荐直接复用示例包 examples/packages/client-panel/v1/，它的结构如下：

client-panel/v1/ ├── package.json # 声明插件行与客户端描述符 ├── index.mjs # 包入口，转发 main 导出 └── extensions/main/ ├── agnes.client.json # 浏览器描述符：入口、样式、插槽、公开配置 ├── index.mjs # 后端行（示例中为空实现） └── client/ ├── index.js # 真正在浏览器里执行的 ESM └── index.css # 面板样式

两个关键声明文件：

package.json 中agnes.plugins声明后端 Cordis 行（如ext:examples/client-panel/main），agnes.clientDescriptors用相同的rowId把描述符绑定到这一行；
agnes.client.json 的client字段：

{ "client": { "entry": "./client/index.js", "styles": ["./client/index.css"], "slots": ["ui:sidebar"], "publicConfig": { "label": "Agnes client module demo · v1" } } }

⚠️ 注意：publicConfig只放随包发布的公开展示元数据，不是后端运行时配置，更不能放凭据、token 或 secret。client 入口必须是浏览器可直接执行的原生 ESM，且不能引用包外的本地模块。

三、最小板面代码：5 行搞定面板替换

浏览器入口 client/index.js 核心只有几行：

export function apply(ctx, config) { ctx.slots.register( 'ui:sidebar', () => config?.publicConfig?.label ?? 'Agnes client module demo · v1', { priority: -1 }, ) }

再配一段 index.css 控制外观（示例用 CSS 变量--agnes-border、--agnes-bg-card等自适应工作台主题）。把它替换成你的业务组件即可——返回 React 组件、纯文本或函数都行，工作台会处理渲染边界与错误隔离。

给生产面板的三点建议：

选择合适的插槽，不要假设未公开区域可被替换，也不要依赖工作台私有的 DOM/CSS 结构；
需要 React 等第三方库时，把它打包进独立可加载的产物，而不是依赖运行时 import；
样式尽量复用工作台的 CSS 变量，保持与整体皮肤一致。

四、安装、信任与启用：三步命令

从仓库根目录，用隔离实例执行（详见安装指南）：

node packages/cli/dist/local/agnes.mjs package inspect file:./examples/packages/client-panel/v1 node packages/cli/dist/local/agnes.mjs install file:./examples/packages/client-panel/v1

安装会展示预览并请求确认：核对包 ID、版本、来源、内容哈希与能力声明后，用预览中的真实哈希执行信任与启用：

node packages/cli/dist/local/agnes.mjs package trust @agnes-examples/client-panel INTEGRITY CAPABILITY_HASH node packages/cli/dist/local/agnes.mjs package enable @agnes-examples/client-panel

也可以在 Web 里完成同一流程：设置 → 插件管理 → 从来源安装 → 检查/安装 → 启用。启用确认会绑定当前的完整性哈希与能力哈希，全部通过后才激活。

完整流程见前端插件专题文档，插件生命周期管理见插件安装与更新指南。

五、进阶：让面板读到后端业务数据 🔌

纯展示面板只能算"皮肤"。要让面板显示真实业务状态，需要同一信任行上同时注册后端服务，示例见 examples/packages/client-service-panel/v1/：

后端 index.mjs 用ctx.services.register()注册panel.version查询服务，带kind: query、输入/输出 Schema、超时与结果大小上限；
描述符的services字段显式列出浏览器允许调用的服务名白名单；
前端 client/index.js 通过ctx.agnes.services.call('panel.version', {})发起受限调用，链路是：浏览器 → 同源 BFF → 身份与状态校验 → 行服务授权 → 你的 handler。

两个实践要点：

查询调用需要当前会话，启用插件前先在 Web 里配置好模型并选中会话；
services能力默认不在本地开发策略上限里，需要按全栈集成文档在隔离试验实例的 profile 中显式放行，不要为绕过报错而私自修改日常实例。

前后端联动、更新回滚与撤销授权的完整细节见全栈插件教程。

六、更新与停用：验证无刷新与自动恢复 🚀

无刷新更新：安装启用 v1 后，通过 Web 管理或 TUI 选择同包 ID 的 v2 源码，面板标签应更新为v2；
双端一致性：全栈插件更新后，前端标签和后端返回值要同时反映新版本，只看前端标签不能证明后端已切换；
停用回滚：禁用插件后，内置侧栏必须立即恢复。由于面板可能替换管理导航，建议保持一个终端就绪，随时用 shell 命令禁用兜底；
回滚：package rollback PACKAGE_ID后目标版本处于未信任未启用状态，仍需重新核对哈希、信任并启用。

需要留意：包desired=enabled、后端行就绪、浏览器加载成功是三个独立阶段。浏览器关闭、脚本/CSS 获取失败、插槽未授权或apply抛错都会阻止前端激活，请在"每行实际状态"里确认，而不是只看启用开关。

七、常见问题速查 🛠️

现象	可能原因	排查方向
启用后面板没出现	前端加载失败/插槽未授权	检查每行 actual 状态与浏览器控制台
面板显示`unavailable`	无当前会话或服务被拒	确认会话已选中、`services`白名单与策略上限
更新后仍显示旧版本	热更新被拒、触发了整树重建	检查操作记录与快照保留状态
依赖缺失安装失败	未打包为可移植的不可变快照	产物需自包含，本地深层路径不算

官方还准备了自动化校验命令覆盖示例 ESM、Cordis 绑定、插槽清理与更新失败处理（见 frontend.md 的 Verification 一节）。

结语

一套package.json+agnes.client.json+ 几行 ESM，你就拥有了一个可安装、可信任、可无刷新更新、可一键回滚的 Web 工作台业务面板。建议从 client-panel 示例起步，跑通后再对照 client-service-panel 示例接入业务数据，逐步把"能看"升级为"能干活"。

延伸阅读：插件开发总览 · 后端工具教程 · Web 工作台指南 · 皮肤定制