Changelog¶

All notable changes to HermesX are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased] - v2.4.0-dev¶

发布状态：本段记录最新已发布基线（v2.3.0）之后的当前分支变更。它们在 v2.4.0 正式发布前不是稳定发布承诺。

Added¶

供应链产物 — 新增 Dependabot（Go/npm/GitHub Actions/Docker）、CodeQL 安全分析、CycloneDX SBOM workflow，以及 release artifact provenance attestation
Egress 拒绝事件审计 — SecureTransport 被拒绝的出站请求现在以 egress.denied 写入 audit_logs；/admin/v1/egress/blocked-log 返回持久化审计事件
Helm 生产加固控制 — chart 支持敏感 env 引用已有 Secret、可配置 ServiceAccount、Pod/Container security context、只读根文件系统 + /tmp emptyDir、可选 NetworkPolicy
维护者与安全响应文档 — 新增 CODEOWNERS、MAINTAINERS 和明确安全响应目标
Admin Usage Aggregation API — GET /admin/v1/usage?tenant_id=&granularity=daily|monthly&from=&to= 端点，按租户聚合 Token 用量及成本
K8s Job 沙箱模式 — SANDBOX_MODE=k8s-job 通过 Kubernetes Job API 执行工具代码，无需特权容器或 DinD，兼容 GKE Autopilot / EKS Fargate
预置可观测性栈 — Grafana Dashboard JSON（7 面板）、Prometheus 告警规则（5 条）、OTel Collector 配置、docker-compose.observability.yml 一键部署
Redis/MinIO 备份脚本 — scripts/redis-backup.sh（BGSAVE + S3）、scripts/minio-backup.sh（mc mirror）、scripts/dr-test.sh（灾难恢复验证）
Eino 0.9 Agent 主链 — 接入 native provider model、AgenticMessage blocks、TurnLoop checkpoint resume、PG/MySQL checkpoint store；/v1/agent/chat 支持 include_agentic_blocks 调试输出

Breaking¶

SaaS-only 产品形态 — 对外入口收敛为 hermesx saas-api、HTTP API、内嵌 WebUI 和 SaaS Docker/Helm/K8s 部署；旧本地助手命令、gateway 运行时、quickstart 栈、分离前端容器和非 SaaS Dockerfile 不再是受支持接口
发布产物收口 — Release/CI 产物仅构建 Linux SaaS 服务二进制；唯一发布镜像为 Dockerfile.saas，镜像默认命令为 saas-api 并内置 webui/dist 到 /static
代码执行沙箱默认拒绝宿主机执行 — execute_code 未设置 SANDBOX_MODE 时返回错误；生产推荐 SANDBOX_MODE=k8s-job，local 模式仅允许显式本地 SaaS 开发 opt-in 且生产环境变量不为 production

Fixed¶

API Key 生成安全性 — generateRawKey() 从 panic 改为返回 (string, error)，rand.Read 失败时返回 HTTP 500 而非进程崩溃
Agent Chat 失败持久化 — /v1/agent/chat 仅在 agent 成功后写入 user/assistant turn；运行失败或流式错误不会留下半写消息、重复 resume user turn 或 token 统计脏状态
Agent Chat 同 session 并发 — 同一 tenant/session 的请求在 handler 层串行执行，避免消息、checkpoint 和 token 统计双写
Workflow Agent 默认路径 — agent_task 默认 executor 从旧 AIAgent 切到 EinoAgentExecutor，与 API 共用 RunConversationTurnLoopSafe 主链

Security¶

BrowserBackend SecretResolver 集成 — BrowserBackend.Connect(ctx context.Context, tctx *ToolContext) error 新接口；凭据优先通过 SecretResolver 解析，降级到 os.Getenv；所有 20 个调用点已更新；browser_impl.go 消除 os 包依赖
Admin DI 可注入安全组件 — APIServerConfig 新增可选注入字段 LeakScanner、CanaryDetector、PolicyStore；nil-guard 保护，向后兼容
HTTP redirect 绕过防护 (#37) — agent.go CheckRedirect hook 新增 egress.ValidateRedirectTarget 校验；拒绝 Location 指向 loopback/私有/CGNAT/link-local IP 的重定向
RLS FORCE 加固 (#27) — migration 109：execution_receipts 补 FORCE ROW LEVEL SECURITY；migration 110：egress_rules 补 ENABLE + FORCE RLS + tenant_isolation_egress_rules 策略（USING + WITH CHECK）
MCP SamplingHandler 安全门禁 (#47) — NewSamplingHandlerWithSafety(client, interceptor) 在 LLM 调用前后分别执行 interceptor.CheckInput / CheckOutput；被拦截请求返回 JSON-RPC error -32000
Linter 合规 (#44) — osv_check.go init() 中的 OSV_ENDPOINT 公开端点 os.Getenv 已添加 //nolint:forbidigo 注解

Docs¶

README 定位重写 — 将 HermesX 叙事收敛为 Agent-first Runtime Control Plane，补充受众、三大支柱、最小 demo、能力矩阵和发布状态分层
Agent-first 架构概览 — 新增 docs/AGENT_FIRST_ARCHITECTURE.md，说明 runtime、control plane、workflow、governance 边界
版本口径对齐 — README、OpenAPI、Enterprise Readiness 统一为当前文档/API 基线 v2.4.0-dev，最新已发布基线 v2.3.0
RBAC 角色数量一致性 — 更新仍描述旧五角色模型的文档，使其与 platform/security/billing/ops 等治理角色保持一致

[2.3.0] - 2026-05-20¶

公共 README 发布状态说明引用的最新已发布基线。

SaaS Cron Scheduler — 分布式定时任务执行引擎。

Added¶

SaaS Cron Scheduler — 基于 gocron + Redis 分布式锁的多 Pod 定时任务执行引擎
internal/scheduler/ 包：SaasScheduler、syncOnce、execute、execWithTenant
PG 轮询同步：每 30s 从 cron_jobs 表读取启用任务，自动注册/更新/移除 gocron 调度
幂等执行：ON CONFLICT (cron_job_id, scheduled_at) DO NOTHING 防止重复执行
Redis 分布式锁：redislock.WithTries(1) 无重试竞争，失败 Pod 跳过
执行结果投递：ResultDeliverer 接口将结果推送回用户来源平台（Telegram/Discord/Slack 等）
生命周期上下文：Scheduler 持有独立 ctx/cancelFunc，gocron 任务通过 baseCtx() 获取实时上下文
cron_job_runs 表 — 执行记录持久化，含 status、duration_ms、result、error、pod_id
RLS 写入策略（Migration 105） — cron_job_runs 表的 INSERT/UPDATE/DELETE 策略，通过 current_setting('app.current_tenant') 校验
SECURITY DEFINER 函数（Migration 106） — scheduler_cleanup_stale_runs() 跨租户清理超时运行记录

Fixed¶

Executor RLS 绕过 — 所有 scheduler 写操作通过 execWithTenant() 在事务内设置 SET LOCAL app.current_tenant，兼容 FORCE RLS
Shutdown 时序 — cronScheduler.Stop() 在 syncCancel() 之前执行，确保运行中任务先排空再取消上下文
gocron 任务上下文过期 — 使用 s.baseCtx() 闭包替代同步时捕获的上下文，防止 fire 时上下文已过期
CronJobStore 错误类型 — Get/Update/Delete 返回统一的 store.ErrNotFound 而非 fmt.Errorf

Changed¶

cleanupStaleRuns 从直接 SQL UPDATE 改为调用 scheduler_cleanup_stale_runs($1) SECURITY DEFINER 函数

[2.2.0] - 2026-05-14¶

Security hardening, bootstrap stabilization, and supply-chain improvements.

Added¶

IP-level rate limiting for POST /admin/v1/bootstrap, with matching Nginx limits for WebUI and production load-balancer entrypoints.
Cross-replica bootstrap idempotency via bootstrap_state in PostgreSQL (ON CONFLICT DO NOTHING + RETURNING id sentinel).
Session titles for SaaS chat sessions, surfaced in the WebUI conversation sidebar.
internal/store/pg unit tests: compile-time interface assertions, bootstrap idempotency logic, and SQL shape validation for scopes (COALESCE) and ON CONFLICT idempotency.
OpenAPI spec corrections: title/version/contact updated to HermesX v2.2.0; 11 missing routes added (/health/live, /health/ready, /metrics, /v1/agent/chat, /v1/gdpr/cleanup-minio, all /admin/v1/* endpoints); paths now accurate at 33+ documented routes.

Fixed¶

PostgreSQL API key persistence now writes and reads scopes, allowing admin API keys to satisfy RequireScope("admin").
Release workflow now builds with Go 1.25 and generates checksums for hermesx-* artifacts.
Documentation now reflects the actual React WebUI stack and v2.2.0 baseline.
WebUI security headers (CSP, HSTS, X-Frame-Options), URL encoding, auth retry on 401, and N+1 query eliminated in session list.

Changed¶

HasScope compatibility policy documented: empty Scopes = legacy key granted non-admin access; admin scope always requires explicit grant. New keys carry explicit scopes.
Memory Curator.deduplicateEntries: Phase 1 now O(n) exact-key dedup via map; Phase 2 content-similarity scan limited to key-unique set (m ≤ n), resolving O(n²) worst case at MaxMemories > 100.

Security¶

GitHub Actions supply-chain hardening: actions/checkout, actions/setup-go, and softprops/action-gh-release all pinned to full commit SHA.
Bootstrap endpoint now enforces 5 RPM IP rate limit at application layer, Nginx WebUI layer, and production LB layer.

[2.0.0] - 2026-05-08¶

Major release: complete rebrand from Hermes to HermesX, combined with enterprise hardening Phase 1.

Added¶

ExecutionReceipt API: auditable tool invocation records with idempotency deduplication and trace correlation
execution receipts are created by the internal tool execution path via DispatchWithReceipt()
GET /v1/execution-receipts — list with pagination and filters (auditor role)
GET /v1/execution-receipts/{id} — get by ID (auditor role)
Prometheus business metrics: 11+ custom metrics covering HTTP requests, LLM completions, tool executions, rate limiting, and store operations
MiniMaxi Anthropic API mode: Anthropic API-compatible mode via MiniMaxi provider, including stress test validation
auditor RBAC role: read-only access to audit logs and execution receipts
Full OpenAPI specification: 22 documented endpoints with schemas, tags, and security schemes, available at GET /v1/openapi
Production Docker compose: docker-compose.prod.yml with PostgreSQL 16, Redis 7 (AOF + LRU), MinIO, OTel Collector, and Jaeger
Enterprise demo script: 11-step ./examples/enterprise-saas-demo/demo.sh walkthrough
Backup/restore scripts: scripts/backup/backup.sh (pg_dump + gzip, 7-day retention) and scripts/backup/restore.sh (single-transaction restore)

Changed¶

Project name: Hermes → HermesX — independent enterprise agent platform
Binary name: hermes → hermesx
Entry point: cmd/hermes/ → cmd/hermesx/
GitHub repository: https://github.com/Colin4k1024/hermesx.git
All internal references: package imports, variable names, comments, log messages, and environment variables updated from hermes/HERMES to hermesx/HERMESX
Configuration files: docker-compose.yml, .env.example, and CI workflow files updated
Documentation: all docs reflect HermesX branding and v2.0.0 version

Fixed¶

CI RLS pool URL replacement: corrected credential substitution for hermesx_test in CI environment (was failing lint and integration tests)
API key tenant boundary: tenant derivation is now strictly from credential context; body-supplied tenant_id only honored for admin role callers
generateRawKey() hardening: explicit panic on crypto/rand.Read failure (previously silently returned partial key)

Refactored¶

Complete codebase rebrand: hermes → hermesx across all source files, test files, configs, and scripts

Docs¶

ARCHITECTURE.md: system architecture overview with component diagram and data flows
SECURITY_MODEL.md: threat model, authentication chain, RLS, and sandbox isolation
RBAC_MATRIX.md: 5 roles × 10 resources permission matrix
ENTERPRISE_READINESS.md: Phase 1 enterprise readiness assessment — 12 capability areas with evidence
STRESS_TEST_REPORT.md: MiniMaxi Anthropic API mode stress test results
Expanded DEPLOYMENT.md: environment variable reference, Prometheus metrics table, backup/restore procedures, horizontal scaling guidelines, security hardening checklist, and rollback strategy