oms-agent

OMS 智能助手前端组件库：在 OMS 页面内提供悬浮入口与对话面板，可结合当前页面 URL、选点内容向 Agent 后端提问（如「这个节点在哪个文件？」、「数据从哪个接口来？」）。

安装

在 OMS 项目根目录执行：

npm install @apdesign/oms-agent

npm 7+ 会自动安装未满足的 peer：react、react-dom、@ai-sdk/react、ai。OMS 使用 React 18.x（如 18.3.1）即可。

若出现 Invalid hook call 或 recentlyCreatedOwnerStacks：请删除 node_modules 和 package-lock.json 后重新 npm install，确保全项目只有一份 React。

依赖

• React 18+、react-dom、@ai-sdk/react、ai（peer，由宿主项目提供；npm install @apdesign/oms-agent 时 npm 7+ 会一并安装未满足的 peer）
• 需单独部署 Agent 后端服务（提供 POST /api/agent/query），参见下方「后端」说明

使用

1. 引入样式（入口处一次）

import "@apdesign/oms-agent/style.css";

2. 在布局中挂载组件

import { useMemo } from "react";
import {
  OmsAgentWidget,
  useElementInspector,
  collectRuntimeContext,
  omsBridge,
} from "@apdesign/oms-agent";

function Layout() {
  const {
    isInspecting,
    selectedElement,
    startInspecting,
    stopInspecting,
    clearSelection,
  } = useElementInspector();
  const runtimeContext = useMemo(
    () => collectRuntimeContext(omsBridge, selectedElement),
    [selectedElement],
  );

  return (
    <>
      {/* 原有 OMS 内容 */}
      <OmsAgentWidget
        inspecting={isInspecting}
        onClearSelection={clearSelection}
        onStartInspecting={startInspecting}
        onStopInspecting={stopInspecting}
        selectedElement={selectedElement}
      />
    </>
  );
}

3. 配置 Agent 后端地址

• 与前端同源时：在构建工具中把 /api 代理到 Agent 服务（如 http://localhost:3030）即可。
• 跨域时：在 OMS 入口或 HTML 中设置 window.__OMS_AGENT_API_BASE__ = 'https://your-agent.example.com'（可在入口用你的构建环境变量赋值）。

后端

需单独运行 Agent 服务（本仓库内为 Node + Express），提供 /api/agent/query，并使用 OMS 源码索引做检索。索引可在 CI/本机通过 OMS_REPO_ROOT=/path/to/oms npm run build:index 生成，部署时通过 CODE_INDEX_PATH 指定索引文件路径。详见仓库内 INTEGRATION.md。

发布到私有 npm

1. 确保 .npmrc 中 registry 指向目标源（包名为 @apdesign/oms-agent）。
2. 执行 npm publish（会先执行 prepublishOnly 自动执行 build:lib，再发布 dist-lib 与 README）。