SouTan/agent_manage_center_api
Watch
3
0
Fork
You've already forked agent_manage_center_api
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
21 commits 2 branches 0 tags 487 KiB
  • Java 100%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
liuser 1cd0bcd812 修改部署方式和版本记录说明文档，删除没用的文档
2026-10-29 14:46:05 +08:00
docs 修改部署方式和版本记录说明文档，删除没用的文档 2026-10-29 14:46:05 +08:00
nscode-business 智能体关联增加按照租户名、hermes别名查询功能 2026-10-19 14:34:59 +08:00
.gitignore Add .gitignore aligned with yuanzhou_api and untrack IDE/build artifacts. 2026-09-17 19:01:04 +08:00
pom.xml 启动类 AgentManageCenterApplication → com.mvker.MainApplication（并补了 MainServletInitializer） 2026-10-09 15:27:31 +08:00
README.md 修改部署方式和版本记录说明文档，删除没用的文档 2026-10-29 14:46:05 +08:00
version.md 修改部署方式和版本记录说明文档，删除没用的文档 2026-10-29 14:46:05 +08:00

README.md

agent_manage_center_api · 智能体管理中心后端

基于能碳同栈：qlcloud-core / qlcloud-middleware（@PortalApplication），Java 8 / Boot 2.7。

能力

模块 来源
登录 / getInfo / getRouters / 用户角色菜单等 qlcloud-core
一键管理、系统管理、系统监控、系统工具 qlcloud-core + sys_* 表
租户 / 用户 / 智能体映射 tenant_info / tenant_user / agent_info / agent_relation
Hermes Dashboard 平台 admin 代登 HermesDashboardAdminClient（hermes.dashboard.*：login → cookie → ticket / profiles / STT / 下载）
服务端 TUI 消息网关 HermesAgentChatGateway + HermesTuiGatewayClient（AMC 持有 WS，浏览器不连 TUI）
管理端对话 BFF /business/agentChat/*（需登录；超管可选智能体）
外部开放对话 /open/agentChat/*（@AuthIgnore；tenantCode + bizUserId → chatToken）

Dashboard 本身只有单一 admin；租户与业务用户仅存在于本管理中心映射表。

Phase-1 对话契约（现行 · 消息代理）

浏览器 / 能碳 BFF 不再拿 wsUrl/ticket 直连 Hermes TUI。chatToken 只留在业务 BFF（方案 B）。

开放接口 X-Agent-Chat-Token

  1. POST /open/agentChat/auth { tenantCode, bizUserId, agentId? } → { chatToken, ttlSeconds, agent, agents[] }
  2. 会话与消息（sessionId = Hermes 持久化 stored id；路径 new 表示懒创建）：
方法 路径 说明
GET /open/agentChat/sessions?agentId= 列会话
POST /open/agentChat/sessions 创建 { agentId, title? }
POST /open/agentChat/sessions/{storedId}/open resume + 历史
DELETE /open/agentChat/sessions/{storedId}?agentId= 删除
POST /open/agentChat/sessions/{sessionId}/messages 发消息 + SSE（JSON 或 multipart）
POST /open/agentChat/audio/transcribe STT（不变）
GET /open/agentChat/files/download?path= 拿附件（不变）

SSE：Content-Type: text/event-stream；事件名 delta / interim / complete / status / error。
附件：JSON attachments[]（kind/contentBase64/dataUrl）或 multipart files；AMC 侧映射 image.attach_bytes / file.attach。

未绑定智能体时明确报错，不发明默认智能体。

管理端 /business/agentChat/*

与上表同名能力（登录态，无 chatToken 头）；另有 GET /context、POST /agents。

Legacy（暂保留，勿作为新接入）

POST …/ws-handoff 仍返回 wsUrl/ticket，供现有 @souta/agent-chat-ui / yuanzhou_ui 直连 TUI；新接入请用 sessions/messages。

工程结构（与能碳同构）

路径 说明
根 pom.xml 父工程 agent-manage-center-api-base（packaging=pom）
nscode-business/ 业务模块，artifactId=agent-manage-center-api
com.mvker.MainApplication 启动类（@PortalApplication）
业务小包 nscode-business/target/agent-manage-center-api.jar
依赖目录 nscode-business/target/lib/*.jar

运行

cd agent_manage_center_api
# 改好 nscode-business/src/main/resources/application*.yml
mvn clean package -Dmaven.test.skip=true
java -cp "nscode-business/target/agent-manage-center-api.jar;nscode-business/target/lib/*" com.mvker.MainApplication --spring.profiles.active=dev
# http://127.0.0.1:9960

默认库：agent_manage_center（需已有 qlcloud sys_* 表；可用能碳库结构初始化）。
业务 Flyway：nscode-business/src/main/resources/flyway（classpath:flyway，与能碳一致）。库内已登记 qlcloud Core 版本，启动不会重复执行 jar 内 V1.x。

登录账号与库内 sys_user 一致（如 admin）。前端：agent_manage_center_ui → 代理 9960。

外部宿主如何对接 AMC（Spring Boot Starter）

宿主不要手写 Controller 去调 /open/agentChat/*。当前标准依赖是 Spring Boot Starter（内置 HTTP 客户端、按用户缓存 chatToken、可选注册管理端/大屏/配置路由）。

项 值
源码仓 https://forgejo.bingjun360.com/SouTan/amcc-agent-chat-spring-boot-starter
Maven 坐标 com.soutan:amcc-agent-chat-spring-boot-starter
制品仓库 Nexus https://nexus.bingjun360.com（已不再走 Forgejo Maven / npm）
SNAPSHOT 拉取 https://nexus.bingjun360.com/repository/maven-snapshots/
Release 拉取 https://nexus.bingjun360.com/repository/maven-releases/
前端包 @souta/agent-chat-ui → https://nexus.bingjun360.com/repository/npm-public/
Java 包名 com.mvker.amcc.*（与 Maven groupId 无关）
适用 Spring Boot 2.7.x / Java 8（与能碳、本服务同栈）

说明：

  • 能碳现行：amcc.starter.version=1.0.0-SNAPSHOT（snapshots 仓）；正式版发到 maven-releases。
  • Forgejo 组织 SouTan 只作源码托管。旧文档里的 Forgejo Maven（…/api/packages/SouTan/maven）、adminUser 包路径、com.souta:amcc-agent-chat-client 均已废弃。
  • Starter 是 Spring Boot 自动配置组件，不是「无 Spring 的纯 HTTP jar」。
  • chatToken 只留在宿主 JVM（方案 B），不要返回给浏览器。
  • 同机部署时 amc.base-url 用 http://127.0.0.1:9960，避免会 302 的域名。
  • 详细发版步骤见 docs/amcc与agent-chat-ui依赖发布.md。

1. Maven 引入

父 POM（版本 + 仓库；repository.id 与 settings.xml 的 <server><id> 一致）：

<properties>
  <!-- 能碳现行 SNAPSHOT；正式版改为 x.y.z 并改用 maven-releases -->
  <amcc.starter.version>1.0.0-SNAPSHOT</amcc.starter.version>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.soutan</groupId>
      <artifactId>amcc-agent-chat-spring-boot-starter</artifactId>
      <version>${amcc.starter.version}</version>
    </dependency>
  </dependencies>
</dependencyManagement>

<repositories>
  <repository>
    <id>nexus-bj-snapshots</id>
    <url>https://nexus.bingjun360.com/repository/maven-snapshots/</url>
    <releases><enabled>false</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
  <repository>
    <id>nexus-bj-releases</id>
    <url>https://nexus.bingjun360.com/repository/maven-releases/</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>false</enabled></snapshots>
  </repository>
</repositories>

业务模块：

<dependency>
  <groupId>com.soutan</groupId>
  <artifactId>amcc-agent-chat-spring-boot-starter</artifactId>
</dependency>

本机 ~/.m2/settings.xml（拉取若已匿名可读可省略；发布必须配账号，<id> 与上面 repository / deploy 的 repositoryId 一致）：

<servers>
  <server>
    <id>nexus-bj-snapshots</id>
    <username>你的Nexus用户名</username>
    <password>你的Nexus密码或令牌</password>
  </server>
  <server>
    <id>nexus-bj-releases</id>
    <username>你的Nexus用户名</username>
    <password>你的Nexus密码或令牌</password>
  </server>
</servers>

前端（宿主 .npmrc）：

@souta:registry=https://nexus.bingjun360.com/repository/npm-public/

pnpm add @souta/agent-chat-ui@0.2.2
# 或 npm i @souta/agent-chat-ui@0.2.2

2. application.yml

amc:
  enabled: true
  base-url: http://127.0.0.1:9960          # 勿带尾斜杠；生产填 AMC 基址
  tenant-code: your-tenant-code            # 对应本服务 tenant_info.tenant_code
  connect-timeout-ms: 5000
  read-timeout-ms: 30000
  long-read-timeout-ms: 120000
  token-refresh-skew-seconds: 120          # chatToken 提前刷新余量；可省略（视为 0）
  # sse-read-timeout-ms: 320000            # 可省略
  bff:
    manage-enabled: true                   # 注册管理端 /business/agentChat/*
    dashboard-enabled: true                # 注册大屏 /dashboard/agentChat/messages
    config-enabled: true                   # 注册智能体配置 /system/agentConfig/*
    legacy-ws-handoff: false               # legacy；默认关
    # path-prefix: /business/agentChat
    # dashboard-path-prefix: /dashboard
    # config-path-prefix: /system/agentConfig

amc.enabled=true 时，连接项（base-url / tenant-code / 三个超时）必须显式填写，Starter 不会用 Java 默认值静默兜底。

3. 自动注册的 HTTP（默认开）

路由用 RouterFunction 注册，避免宿主 componentScan("com.mvker") 时再扫出一份 @RestController。

开关 默认前缀 用途
amc.bff.manage-enabled /business/agentChat 管理端对话：context / sessions / SSE messages / 转写 / 下载
amc.bff.dashboard-enabled /dashboard 大屏：POST …/agentChat/messages（SSE）
amc.bff.config-enabled /system/agentConfig 智能体绑定 CRUD + profiles
amc.bff.legacy-ws-handoff （默认关） 管理端 …/ws-handoff、大屏 …/hermes/ws-handoff

管理端路径对齐 @souta/agent-chat-ui transport（与上文开放接口同名能力；无 chatToken 头）。

JSON 成功体默认原样返回；需要宿主信封（如能碳 R）时实现 AmcJsonResponseWrapper。SSE 与文件下载不包信封。

4. 宿主必做 / 可选 SPI

SPI 是否必须 作用
AmcBizUserResolver 开管理端时必须 当前登录用户 → AMC bizUserId
AmcDashboardUserResolver 开大屏时必须 场景键（如 unicode）→ 大屏业务用户 id
AmcConfigUserDirectory 配置页要展示姓名/部门时建议 本地用户资料；新增绑定时提供 userName
AmcJsonResponseWrapper 可选 成功 JSON 包装（能碳包成 R.ok）
AmcExceptionTranslator 可选 默认抛 AmcAgentChatAccessException；能碳转成 BusinessException
AmcPermissionGate 可选 对话/配置权限门闩；默认放行

classpath 有 Spring Security 且 principal 是数字时，Starter 可提供默认 AmcBizUserResolver；能碳这类 LoginUser 必须自己实现。

最小示例（管理端对话）：

@Configuration
public class AmcHostConfiguration {

  @Bean
  public AmcBizUserResolver amcBizUserResolver() {
    return () -> SecurityUtils.getUserId(); // 换成宿主取当前用户 id 的方式
  }
}

能碳参考：yuanzhou_api/.../amc/starter/YuanzhouAmcConfiguration（R 包装、大屏用户、配置用户目录）以及 YuanzhouAmcDashboardSecurity（大屏路径 permitAll：qlcloud 的 @AuthIgnore 扫不到 Starter 的 RouterFunction）。

前端仍用 @souta/agent-chat-ui，transport 打宿主路径（如 /business/agentChat/*），不要直连 AMC。

5. 发布新版本到 Nexus

账号只放本机 settings.xml / npm 登录态，不要写进仓库。源码仍推 Forgejo；制品只发 Nexus。

cd amcc-agent-chat-spring-boot-starter
mvn -q clean package source:jar -DskipTests

REM SNAPSHOT（版本号须带 -SNAPSHOT）
mvn deploy:deploy-file -DgroupId=com.soutan -DartifactId=amcc-agent-chat-spring-boot-starter -Dversion=1.0.0-SNAPSHOT -Dpackaging=jar -Dfile=target/amcc-agent-chat-spring-boot-starter-1.0.0-SNAPSHOT.jar -Dsources=target/amcc-agent-chat-spring-boot-starter-1.0.0-SNAPSHOT-sources.jar -DgeneratePom=true -DrepositoryId=nexus-bj-snapshots -Durl=https://nexus.bingjun360.com/repository/maven-snapshots/

REM 正式版（无 -SNAPSHOT；repositoryId / url 换成 releases）
REM mvn deploy:deploy-file ... -Dversion=1.0.1 -DrepositoryId=nexus-bj-releases -Durl=https://nexus.bingjun360.com/repository/maven-releases/

前端 @souta/agent-chat-ui 发到 Nexus npm hosted，宿主从 npm-public 拉取（步骤见发布笔记）。

源码推送：https://forgejo.bingjun360.com/SouTan/amcc-agent-chat-spring-boot-starter.git。
不要对能碳 / 本服务父工程点 Lifecycle 的 deploy（那是 qlcloud 旧私服流程，不是本 Starter）。