📝 docs: Consolidate specs directory, validate ACPX spec, and fix Gateway Async Init

.agent/rules/aep.md

@@ -0,0 +1,121 @@
+---
+paths:
+  - "**/aep/*.go"
+---
+
+# AEP v1 协议规范
+
+> hotplex-worker 对外暴露的统一 WebSocket 全双工通信协议
+> 参考文档：`docs/specs/Acceptance-Criteria.md` §AEP-001 ~ §AEP-030
+
+## Envelope 结构
+每条 AEP v1 消息必须包含以下字段：
+
+| 字段 | 类型 | 要求 |
+|------|------|------|
+| `id` | string | non-empty，消息唯一标识 |
+| `version` | string | 必须为 `aep/v1`，否则返回 `VERSION_MISMATCH` |
+| `session_id` | string | non-empty |
+| `seq` | int64 | 从 1 开始严格递增，同 session 内原子分配 |
+| `timestamp` | int64 | Unix ms，> 0 |
+| `event` | object | non-null，包含 `type` 字段 |
+| `priority` | string | 缺失默认为 `data`；`control` 跳过 backpressure |
+
+### 编解码约束
+```go
+// DecodeLine 必须验证所有必填字段
+func DecodeLine(line []byte) (*Envelope, error) {
+    dec := json.NewDecoder(bytes.NewReader(line))
+    dec.DisallowUnknownFields() // 拒绝未知字段
+    // ...
+}
+
+// EncodeLine 使用 json.Encoder，避免 []byte→string 复制
+func EncodeLine(w io.Writer, env *Envelope) error {
+    enc := json.NewEncoder(w)
+    return enc.Encode(env)
+}
+```
+
+## 消息类型
+
+### C→S（Client → Server）
+- `init`：握手，必须是 WS 连接建立后第一帧
+- `input`：用户任务，Session 繁忙时硬拒绝
+- `control`：terminate / delete
+- `ping`：心跳，回复 pong
+
+### S→C（Server → Client）
+- `init_ack`：握手响应
+- `state`：状态变更（created/running/idle/terminated）
+- `message.delta`：流式输出（text/code/image）
+- `message`：Turn 结束时完整消息聚合
+- `tool_call` / `tool_result`：Tool 调用通知（AUTONOMOUS 模式）
+- `done`：Turn 终止符
+- `error`：错误通知
+- `pong`：ping 响应
+- `control`：reconnect / throttle（Server 发起）
+
+## Seq 分配与去重
+```go
+// hub.NextSeq 原子分配，保证 session 内单调递增
+func (g *SeqGen) NextSeq(sessionID string) int64 {
+    g.mu.Lock()
+    defer g.mu.Unlock()
+    n := g.seq[sessionID]
+    g.seq[sessionID] = n + 1
+    return n
+}
+
+// message.delta 丢弃时不消耗 seq
+if !sent {
+    // seq 不递增，sessionDropped[sessionID] = true
+}
+```
+
+## Backpressure — 有界通道与 delta 丢弃
+```go
+// hub.broadcast 通道容量由 broadcastQueueSize 决定（默认 256）
+ch := make(chan *Envelope, cfg.BroadcastQueueSize)
+
+func SendToSession(sessionID string, env *Envelope) error {
+    if env.Event.Type == "message.delta" || env.Event.Type == "raw" {
+        // 非阻塞 select，通道满时静默丢弃
+        select {
+        case ch <- env:
+            return nil
+        default:
+            sessionDropped[sessionID] = true
+            return nil // 不返回错误
+        }
+    }
+    // 关键事件不可丢弃
+    ch <- env
+    return nil
+}
+```
+
+## 时序约束
+- Turn 开始：`state(running)` 必须是第一个 S→C event（seq=1）
+- Turn 结束：`done` 必须是最后一个 S→C event
+- `error` 必须在 `done` 之前
+- `tool_result.tool_call_id` 必须与对应 `tool_call.id` 匹配
+
+## Init 握手
+```go
+// performInit 必须在 30s 内完成
+ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+defer cancel()
+
+// 第一帧类型必须为 init
+if env.Event.Type != "init" {
+    return sendInitError(conn, "PROTOCOL_VIOLATION")
+}
+```
+
+## Worker 类型映射
+| Worker | 事件映射 |
+|--------|---------|
+| Claude Code | tool_use → tool_call |
+| OpenCode CLI | step_start → 提取 sessionID |
+| pi-mono (raw stdout) | 每行 stdout → 一条 message.delta |

.agent/rules/golang-style.md → .agent/rules/golang.md

@@ -3,7 +3,12 @@ paths:
   - "**/*.go"
 ---
 
-# Uber Go Style Guide
+# Go 编码规范
+
+> 合并自原 `go126.md`（Go 1.26 语言特性）+ `golang-style.md`（Uber Go Style Guide）
+> hotplex-worker 使用 Go 1.26，遵循 Uber Go Style Guide + 项目补充规则
+
+---
 
 ## 格式化
 - 行宽软限制 99 字符
@@ -50,3 +55,44 @@ paths:
   type Option func(*Config)
   func WithTimeout(d time.Duration) Option
   ```
+
+---
+
+## Go 1.26 语言特性
+
+## 默认生效（无需改代码）
+- **Green Tea GC**：GC overhead ↓ 10-40%，长驻进程直接受益
+- **Swiss Table Maps**：`make(map[K]V)` 使用新哈希表
+- **Container-Aware GOMAXPROCS**：自动适配容器 CPU 限制
+- **`io.ReadAll`**：2x faster，50% less allocation（Worker 输出流解析受益）
+- **`fmt.Errorf`**：分配减少，等价于 `errors.New`
+
+## 推荐使用
+- **`log/slog`**：标准库结构化日志，统一使用
+- **Generic Interfaces**：Worker 接口类型参数化（如 `Worker[T Event]`）
+- **`weak.Value`**：session metadata LRU 缓存
+- **`slices.Clone`**：slice 边界复制的标准方式
+- **`unique.Make`**：字符串驻留
+- **`new(expr)` 增强**：支持表达式初始化值，Worker 配置简化
+- **自引用泛型约束**：更灵活的泛型设计
+
+## Goroutine 泄漏检测（高优先级）
+- 实验性 profile：`runtime/pprof` 的 `goroutineleak` 类型
+- 启用：`GOEXPERIMENT=goroutineleakprofile`
+- 预期 **Go 1.27 默认启用**
+- **必须确保所有 goroutine 有 shutdown 路径**（ctx cancel / channel close / WaitGroup）
+
+## 构建优化
+```bash
+go build -pgo=auto ./cmd/gateway  # Profile-Guided Optimization
+```
+
+## 现代化工具
+```bash
+go fix ./...  # 自动现代化代码（go fix 完全重写，数十个 fixer）
+```
+
+## Flight Recorder（生产诊断）
+```bash
+go tool trace trace.out
+```

.agent/rules/metrics.md

@@ -0,0 +1,135 @@
+---
+paths:
+  - "**/metrics/*.go"
+---
+
+# 可观测性规范
+
+> Prometheus 指标、OTel Trace、日志格式
+> 参考：`docs/specs/Acceptance-Criteria.md` §OBS-001 ~ §OBS-010
+
+## 日志格式（OTel Log Data Model 兼容）
+
+```go
+// 所有日志必须为 JSON 格式
+log := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelInfo,
+}))
+
+slog.Info("session created",
+    "service.name", "hotplex-gateway",
+    "session_id", sessionID,
+    "trace_id", traceID,  // 若有 trace context
+)
+```
+
+### 必填字段
+| 字段 | 说明 |
+|------|------|
+| `timestamp` | ISO 8601 / Unix ms |
+| `level` | DEBUG / INFO / WARN / ERROR / FATAL |
+| `message` | 人类可读消息 |
+| `service.name` | 固定 `hotplex-gateway` |
+| `trace_id` | 若有 trace context |
+
+### 日志级别规范
+- **ERROR**：全量记录，不采样
+- **正常日志**：按配置 `sample_rate` 采样（例：10%）
+
+---
+
+## Prometheus 指标
+
+### 命名规范
+```
+<app_prefix>_<group>_<metric>_<unit_suffix>
+前缀固定 hotplex_
+```
+
+### 核心指标（API 层 — RED 方法）
+| 指标名 | 类型 | 说明 |
+|--------|------|------|
+| `hotplex_requests_total` | Counter | 请求总数 |
+| `hotplex_request_duration_seconds` | Histogram | 请求延迟 |
+| `hotplex_request_errors_total` | Counter | 错误总数，标签：error_code |
+
+### 核心指标（基础设施层 — USE 方法）
+| 指标名 | 类型 | 说明 |
+|--------|------|------|
+| `hotplex_sessions_active` | Gauge | 当前活跃 Session |
+| `hotplex_sessions_created_total` | Counter | 累计创建数 |
+| `hotplex_worker_crashes_total` | Counter | Worker 崩溃数，标签：worker_type, reason |
+| `hotplex_worker_memory_bytes` | Gauge | Worker 内存占用，标签：worker_type |
+| `hotplex_errors_total` | Counter | 所有错误，标签：component, error_code |
+| `hotplex_worker_duration_seconds` | Histogram | Worker 执行时长 |
+
+### 辅助指标
+```go
+// Backpressure
+hotplex_broadcast_queue_capacity  // 容量上限
+hotplex_broadcast_queue_depth    // 当前深度
+hotplex_messages_dropped_total   // 丢弃消息数
+
+// Pool
+hotplex_pool_total       // 全局 pool 总容量
+hotplex_pool_used        // 已用槽位
+hotplex_user_pool_used   // per-user pool，标签：user_id
+```
+
+---
+
+## OTel Span 创建与上下文注入
+
+### 每个 AEP 事件对应一个 Span
+```go
+func handleEvent(ctx context.Context, env *aep.Envelope) {
+    ctx, span := otel.Tracer("hotplex-gateway").Start(ctx, "aep."+env.Event.Type)
+    defer span.End()
+
+    span.SetAttributes(
+        attribute.String("session_id", env.SessionID),
+        attribute.Int64("seq", env.Seq),
+    )
+
+    // trace context 注入事件 metadata
+    if spanCtx := trace.SpanContextFromContext(ctx); spanCtx.IsValid() {
+        env.Metadata["trace_id"] = spanCtx.TraceID().String()
+        env.Metadata["span_id"] = spanCtx.SpanID().String()
+    }
+
+    handle(ctx, env) // 下游传播
+}
+```
+
+### Span 命名格式
+```
+aep.init        → init 握手
+aep.input       → 用户输入
+aep.message.delta → 流式输出片段
+aep.done        → Turn 结束
+aep.error       → 错误事件
+```
+
+### 尾部采样策略（Tail-based Sampling）
+- **ERROR trace**：100% 保留
+- **latency > 5s**：优先保留
+- **正常 trace**：1% 采样
+
+---
+
+## SLO 定义
+
+| SLO | 指标 | 目标 |
+|-----|------|------|
+| Session 创建成功率 | `hotplex_sessions_created_total` | ≥ 99.5% |
+| P99 延迟 | `hotplex_request_duration_seconds` P99 | < 5s |
+| Worker 可用性 | `1 - hotplex_worker_crashes_total/...` | ≥ 99% |
+| WAF 准确率 | 拒绝率/总请求 | > 99.9% |
+
+---
+
+## 告警原则
+- **症状告警**（非根因告警）
+- `HighSessionCreationFailureRate`：持续 5min 失败率 > 1%
+- `HighWorkerCrashRate`：崩溃率 > 1%
+- `HighLatency`：P99 > 5s 持续 5min