oms-agent

OMS 智能助手前端组件库，当前聚焦两项核心能力：

• 业务问答：基于知识库回答业务问题，后续可接入产品文档、向量数据库与 RAG 检索链路。
• 自动执行：基于 page-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）
• 需单独部署 oms-agent 后端服务，提供：
  • POST /api/business-qa/query：业务问答
  • POST /api/business-qa/query/stream：业务问答流式 SSE
  • POST /api/page-agent/chat/completions：page-agent 代理

使用

1. 样式（默认随包入口一起加载）

从 @apdesign/oms-agent 引入组件时，库产物会侧链加载 entry.css，在常见前端打包工具（Vite、Webpack 等）下一般不需要再写 import "@apdesign/oms-agent/style.css"。若宿主的打包配置无法解析包内的 .css 侧链，可继续显式引入：

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

2. 在布局中挂载组件

import { OmsAgentWidget } from "@apdesign/oms-agent";

function Layout() {
  return (
    <>
      {/* 原有 OMS 内容 */}
      <OmsAgentWidget apiBase="https://oms-agent.example.com" />
    </>
  );
}

• 推荐在测试/线上环境直接通过 apiBase 显式指定后端服务地址。
• 若未传 apiBase，组件会继续尝试读取 window.__OMS_AGENT_API_BASE__，再退回到同源 /api。

3. 配置 Agent 后端地址

• 推荐方式：直接传 apiBase，例如 https://your-agent.example.com
• 与前端同源时：也可以不传 apiBase，在构建工具中把 /api 代理到 Agent 服务（如 http://localhost:3030）
• 兼容方式：在 OMS 入口或 HTML 中设置 window.__OMS_AGENT_API_BASE__ = 'https://your-agent.example.com'

后端

需单独运行 Agent 服务（本仓库内为 Node + Express）：

• 业务问答通过 /api/business-qa/query/stream 走后端真实流式 SSE；/api/business-qa/query 继续保留为兼容用的一次性 JSON 接口。
• 自动执行通过 /api/page-agent/chat/completions 代理到上游模型服务，前端不直接暴露密钥。

流式接口说明

• POST /api/business-qa/query/stream
• 请求体：

{ "question": "这个页面当前主要在处理什么业务？" }

• 响应类型：text/event-stream
• 事件内容：AI SDK 的 UIMessageChunk SSE，当前至少会包含：
  • message-metadata：附带 sources
  • text-start
  • 一个或多个 text-delta
  • text-end
• 前端 business 模式已默认消费该流式接口；若上游模型因额度或参数限制无法正常流式返回，后端会自动回退为知识检索摘要，并仍以 SSE 的 text-delta 形式输出。

LLM 配置建议

• 若当前 OpenRouter 配额较紧，建议优先使用：
  • LLM_MODEL=openrouter/auto
  • LLM_MAX_TOKENS=512
• 这样可以降低因模型价格或 max_tokens 过高导致的 402 / credits 不足报错概率。

当前版本已移除开发自查、选点、源码索引检索等链路，后续可在业务问答服务内接入向量数据库与 RAG。

更多关于业务问答知识架构、文档格式与后续替换向量库的说明，见 KNOWLEDGE.md。 更多关于后端独立部署、鉴权模式与版本/知识更新边界的说明，见 DEPLOYMENT.md。

发布到私有 npm

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