@agent-anvil-platform/sdk

agent-anvil Platform 插件前端的运行期共享 SDK。

主前端（宿主）把本包打进自己的 bundle 并在运行期提供实现；插件前端在构建期以裸包名 @agent-anvil-platform/sdk 引用并被 externalize，运行期由宿主注入。因此宿主与全部插件必须使用 API 兼容的同一版本，破坏性变更必须升 major。

安装

npm i @agent-anvil-platform/sdk

仓库内开发无需安装：本包是 agent-anvil-frontend 的 npm workspace 成员， npm install 后 node_modules/@agent-anvil-platform/sdk 会软链到 packages/sdk 源码目录。

导出内容

| 分类 | 导出 | |---|---| | HTTP | httpClient（axios 实例，统一 baseURL / 鉴权头 / 错误封装） | | 状态 | useAuthStore、useChatStore、useLeftPanelStore、useSidePanelStore（zustand） | | A2UI | a2ui 消息协议（宿主 ↔ 插件的跨界面通信） | | UI | PageContainer、SectionCard、StatusTag | | 类型 | 插件契约、Surface 契约等 TypeScript 类型声明 |

以根入口统一导入：

import { httpClient, useAuthStore, PageContainer } from '@agent-anvil-platform/sdk';

构建

npm run build      # vite build（ESM 产物）+ tsc -p tsconfig.build.json（.d.ts）
npm run dev        # watch 模式
npm run typecheck  # 仅类型检查

产物固定为 dist/index.mjs + dist/index.d.ts；react / react-dom / axios / zustand / antd / @ant-design/icons 均为 external，不打进产物。

发布

npm version <patch|minor|major>
npm publish          # prepublishOnly 自动执行 build；registry 取 publishConfig

发布后必须同批次把主前端与 8 个插件前端的依赖 range 升到同一版本， CI 的 sdk 单版本断言会拦截版本分叉。

权限契约（fail-closed）

useAuth（auth store）的权限判定默认拒绝，不再存在「权限集为空即放行」的 fail-open 逻辑：

• hasPermission(code)：permissionsLoaded === false（权限尚未下发完成）或权限集合不含 code 时一律返回 false；
• fetchPermissions()：登录态就绪后调用，请求 GET /api/user/permissions （httpClient baseURL 为 /api，SDK 内部路径写 /user/permissions）， 解包平台统一 R 信封 { code, msg, data }（code === '0' 为成功）下的 data.permissionCodes 与 data.accessiblePluginIds；
• 拉取失败或 code !== '0' 时按空权限集处理（拒绝一切），避免卡在加载态；
• 权限组件可订阅 permissionsLoaded 展示 loading，避免「加载完成前全部拒绝」的闪拒。