跳转至

Hermes 纯聊天智能体（ACK 部署）

在阿里云 ACK 上常驻运行 Hermes 运行时（纯文本、0 工具），对外人设为 江苏图现人工智能 Agent，并由 图现 Chat（chat.tuxianai.com）做同源流式对话。

资产 路径
聊天前端 src/chat/
Hermes 配置 deploy/hermes/config.chat-only.yaml
人设 SOUL（硬规则） deploy/hermes/SOUL.md
记忆 MEMORY / USER deploy/hermes/memories/
生图 Skills deploy/hermes/skills/（主图/详情/影棚 + 五平台）
Hermes K8s deploy/hermes/k8s/（ConfigMap 挂载 SOUL/MEMORY）
Chat K8s deploy/k3s/base/chat-frontend/
Secret 模板 deploy/ACK/secrets.example/hermes-secrets.yaml
公网域名 https://chat.tuxianai.com（Ingress → chat-frontend，/v1 由 Nginx 反代 Hermes）

原理

机制 作用
SOUL.md 系统提示槽位 #1：强制「江苏图现人工智能 Agent」身份
memories/MEMORY.md + USER.md 会话注入项目事实与用户偏好；memory 工具仍禁用防改写
platform_toolsets.api_server: [] ACK 网关入口 0 工具（集群主路径）
platform_toolsets.cli: [] CLI 入口同样纯聊天
agent.disabled_toolsets 全局再剥一层，防止误配回流工具

不要写 hermes-cli / hermes-api-server 复合工具集——那会重新打开全量工具。空列表 [] 才是官方纯聊天写法。

ACK 部署步骤

0. 前置

  • kubectl 已指向 ACK（$env:KUBECONFIG = "$env:USERPROFILE\.kube\ack-harness-config"）
  • 仓库根 .env 已配置 ACR_*
  • 本机可 docker pull / nerdctl pull（用于同步官方镜像到 ACR）

1. 填写密钥（仓库根 .env，勿提交）

# LLM（OpenAI 兼容；示例为 DeepSeek）
HERMES_OPENAI_API_KEY=sk-xxxxxxxx
HERMES_OPENAI_BASE_URL=https://api.deepseek.com

# 对外 API 鉴权（≥8 字符；客户端 Authorization: Bearer <此值>）
HERMES_API_SERVER_KEY=请替换为足够长的随机串
# 可选
HERMES_API_SERVER_CORS_ORIGINS=*

也可用通用名 OPENAI_API_KEY / OPENAI_BASE_URL（make ack-secrets 会回退读取）。

模型名默认在 ConfigMap 中为 deepseek-chat，可按提供商修改 deploy/hermes/k8s/configmap.yaml 后重新 ack-deploy。

2. 推送 Hermes 镜像到 ACR

ACK 节点通常无法直连 Docker Hub，需先同步官方镜像：

make ack-push-hermes
# 等价：powershell -File deploy/ACK/scripts/push-hermes-image.ps1

将 nousresearch/hermes-agent:latest → <ACR>/<namespace>/hermes-agent:latest。

若本机 docker pull Docker Hub 超时，可任选：

  1. 配置 Docker 镜像加速后再执行 make ack-push-hermes
  2. 在能访问 Docker Hub 的机器上 pull + tag + push 到同一 ACR 路径
  3. ACK 控制台「镜像仓库」→ 创建镜像同步（Docker Hub → 个人 ACR，仓库名 hermes-agent）

3. 生成 Secret 并部署

make ack-deploy
# 会执行 create-secrets.ps1（写入 harness-hermes-secrets）+ kubectl apply -k deploy/ACK

首次或改镜像后建议：

kubectl rollout restart deployment/hermes -n harness-app
kubectl get pods -n harness-app -l app=hermes -w

4. 构建并推送 Chat 前端

make ack-push-chat-frontend
make ack-deploy
kubectl rollout restart deployment/chat-frontend -n harness-app

5. DNS / Ingress

主机 后端
chat.tuxianai.com chat-frontend:80（页面 + /v1 → Hermes）

将 chat.tuxianai.com 的 A 记录指向 Ingress SLB 公网 IP。先用 HTTP 验证；TLS 另配。

浏览器打开：http://chat.tuxianai.com

会话归属（JWT + 映射表）

Chat 需用户短信登录（与画布同一 JWT）。backend 表 chat_sessions 仅存 user_id ↔ hermes_session_id：

API 说明
GET/POST /api/user/chat/sessions 列/建会话归属
GET /api/user/chat/sessions/{id}/messages 验归属后代查 Hermes
流式 /v1/chat/completions 仍走 Chat Nginx→Hermes；请求带 X-Hermes-Session-Id + X-Hermes-User-Id

backend 需配置 HERMES_API_BASE_URL / HERMES_API_SERVER_KEY（见 src/backend/.env.example）。ACK Ingress 已将 chat.tuxianai.com/api 指到 backend。

6. 验证（0 工具 + 流式聊天）

健康检查（经 Chat Nginx 反代）：

curl http://chat.tuxianai.com/health

流式聊天 API（密钥由 Nginx 注入，浏览器同源调用无需带 Bearer）：

curl -N http://chat.tuxianai.com/v1/chat/completions `
  -H "Content-Type: application/json" `
  -d '{"model":"hermes-agent","stream":true,"messages":[{"role":"user","content":"只用一句话介绍你自己"}]}'

集群内确认工具集（可选）：

kubectl exec -n harness-app deploy/hermes -- hermes tools list --platform api_server
# 期望：全部 ✗ disabled，或无启用工具

本地开发 Chat 页

# 需本机已跑 Hermes gateway（API_SERVER_ENABLED=true，端口 8642）
# 在 src/chat/.env 写入 HERMES_API_SERVER_KEY=...
make chat-dev
# 浏览器 http://localhost:5178

套用图现人设（本机 CLI）

Windows 配置目录多为 %LOCALAPPDATA%\hermes\：

Copy-Item deploy\hermes\config.chat-only.yaml "$env:LOCALAPPDATA\hermes\config.yaml"
Copy-Item deploy\hermes\SOUL.md "$env:LOCALAPPDATA\hermes\SOUL.md"
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\hermes\memories" | Out-Null
Copy-Item deploy\hermes\memories\MEMORY.md "$env:LOCALAPPDATA\hermes\memories\MEMORY.md"
Copy-Item deploy\hermes\memories\USER.md "$env:LOCALAPPDATA\hermes\memories\USER.md"
# 新开 hermes chat / 重启 gateway 后生效

硬规则摘要：自称江苏图现人工智能 Agent；不提原厂公司；不答底层模型；服务范围限本项目图现产品。

修改 SOUL / MEMORY / skills 源文件后执行：

powershell -File deploy/ACK/scripts/sync-hermes-identity.ps1
kubectl apply -k deploy/hermes/k8s
kubectl rollout restart deployment/hermes -n harness-app

生图 Skills：tuxian-main-image / tuxian-detail-image / tuxian-virtual-studio / tuxian-ecommerce-platforms（京东·淘宝·拼多多·抖音·小红书）。platform_toolsets 仅开放 skills。

本机 CLI 对照（可选）

Windows 原生安装的配置路径多为：

%LOCALAPPDATA%\hermes\config.yaml（不是 ~\.hermes\）

Copy-Item deploy\hermes\config.chat-only.yaml "$env:LOCALAPPDATA\hermes\config.yaml"
hermes tools list --platform cli
hermes tools list --platform api_server

恢复工具能力

  1. 清空或收紧 agent.disabled_toolsets。
  2. 将 platform_toolsets.api_server / cli 改为需要的集合。
  3. kubectl rollout restart deployment/hermes -n harness-app。

常见问题

现象 处理
ImagePullBackOff / ACR not found 镜像尚未进 ACR：在可访问 Docker Hub 的环境执行 make ack-push-hermes，或用 ACR「镜像同步」把 nousresearch/hermes-agent:latest 同步为 <namespace>/hermes-agent:latest，然后 kubectl rollout restart deployment/hermes -n harness-app
Pod 不 Ready /health 失败 查日志：kubectl logs -n harness-app deploy/hermes；确认 Secret 中 OPENAI_* 与 API_SERVER_KEY 已填
401 Bearer 必须等于 HERMES_API_SERVER_KEY
仍出现工具调用 确认 ConfigMap 含 api_server: []；升级 Hermes 镜像；exec 内跑 tools list
密钥进了 git 立刻轮换 Key；只放根 .env / deploy/ACK/secrets/（已 gitignore）

与本仓库关系

  • 清单挂在 deploy/ACK/kustomization.yaml → ../hermes/k8s，随 make ack-deploy 一并下发。
  • 不改画布 / backend 业务代码；仅增加独立 hermes Deployment + Ingress 主机。