hotplex AGENTS.md

HotPlex 项目知识库

最后更新: 2026-08-25 · 分支: main · 版本: v1.50.0 · 提交: c97fdff6

---

约定与规范

必须遵守

• Mutex: 显式 mu 字段，不嵌入，不传指针
• 错误: Err 前缀（哨兵）、Error 后缀（自定义）、fmt.Errorf("%w") 包装
• 日志: log/slog JSON handler（key 一律 snake_case，sloglint 强制 no-mixed-args）
• 测试: testify/require、table-driven、t.Parallel()、单模块 ≤5s（-count=1 -race -shuffle=on）、禁止 time.Sleep 等待异步结果（改用 require.Eventually 或 channel 信号）
• Worker 注册: init() + worker.Register() 模式
• Worker 接口变更: 同步更新全部 adapter、测试 mock、internal/worker/noop 与 registry_test；新增能力须明确其在 CLI、单例和 RPC Worker 上的语义
• AEP wire contract: 修改 pkg/events 的 Kind、Data 或 JSON tag 时，同步更新 Go SDK、三种示例 SDK、docs/reference/{aep-protocol,events}.md 与双向协议测试；新增字段必须向后兼容
• 持久化输入: Gateway 负责 accept → ACK → Worker 投递，execution 只保存 SHA-256 payload 指纹，绝不保存 prompt、metadata 值、凭证或原始 Worker 错误
• 数据库迁移: SQLite 与 PostgreSQL migration 必须成对新增；同步补 migration 与跨实例/条件更新测试，禁止只修一套方言
• 关闭顺序: signal → cancel ctx → tracing → hub → bridge → sessionMgr → HTTP
• 服务重启: 必须使用 hotplex service restart 原子指令，禁止手动拆分 stop && sleep && start（仅二进制替换场景需手动 stop 等待）
• 非 main 分支 push: 非 main 分支本地验证通过后直接 commit + push，无需询问用户确认
• Git Hooks: clone 后必须安装 hooks（底层目标为 make hooks；pre-commit 跑 gofmt + golangci-lint，pre-push 跑完整质量门禁），禁止跳过；rtk 可用时执行 rtk proxy make hooks，不可用时执行原生 make hooks 并说明回退原因
• RTK 未过滤执行例外：以下规则仅适用于执行环境中可用 rtk（可用 command -v rtk 或 rtk --version 确认）。make docs-lint、make quality、make build、make hooks 存在输出解析失败记录；rtk 可用时必须分别通过 rtk proxy make docs-lint、rtk proxy make quality、rtk proxy make build、rtk proxy make hooks 执行，以保留原始诊断输出。rtk 不可用时，允许执行对应的原生 make 命令，但必须说明未经过 RTK 过滤与统计；不得因本规则擅自安装 RTK。

反模式（禁止）

• ❌ sync.Mutex 嵌入或传指针
• ❌ math/rand 用于加密
• ❌ Shell 执行（仅允许 claude 二进制）
• ❌ 硬编码路径分隔符
• ❌ 直接使用 POSIX 信号
• ❌ 用 sed/awk 插入或修改源码行（缩进不可控，必须用 Edit 工具）

代码编辑规则

• Edit 工具优先：修改源码必须使用 Edit 工具，禁止用 sed -i 插入或修改代码行
• Edit 匹配失败时：重新 Read 文件获取精确内容，用精确字符串重试 Edit；扩大上下文使其唯一
• Go 文件 tab 缩进：Go 项目使用 tab 缩进（gofmt 标准）。使用 Edit 工具时，old_string 必须从 Read 输出中直接复制原文（保留 tab），禁止手敲空格缩进。Edit 匹配失败时先用 cat -A 确认实际空白字符
• sed 适用场景：仅限非代码操作（config 快速替换、日志过滤等简单唯一 token 替换）