feat(story-2-7): agent health monitoring via Temporal native API

- Implement GET /v1/agents, /v1/agents/{name}, /v1/agents/summary via
  DiscoverTaskQueues + DescribeTaskQueue (AC1, AC2, AC6)
- Implement GET /v1/task-queues replacing Story 2-2 placeholder (AC3)
- AC4 heartbeat provided natively by Temporal Worker SDK
- AC5 health detection: 30-second poller window in DescribeTaskQueue
- AC7 OpenAPI spec updated: Agents/TaskQueues tags, paths, schemas

Code review fixes:
- H1: GetAgentStatus uses mux.Vars(r)["name"] instead of raw URL slice
- H2: Add agent_handler_test.go (12 tests: determineAgentStatus table-driven,
  nil client guards, JSON field name validation)
- H3: DescribeTaskQueue queries both ACTIVITY and WORKFLOW poller types
- M1: File List updated with 7 previously undocumented changed files
- M2: Rename AdminHandler var ah -> adminH in router.go to avoid shadowing
- M3: task_queue_test.go adds 30-second health window boundary tests
- M4: LastUpdateTime uses time.Time{} zero value on query failure
- L1: Remove outdated POST /v1/agents/heartbeat architecture diagram
- L2: Align Dev Notes AC7 status with Tasks [x] completion

Closes: Story 2-7

Author: zhaojing1987

api/openapi.yaml

@@ -65,6 +65,10 @@ tags:
     description: 审计日志 - 查询系统审计事件
   - name: Health
     description: 健康检查和监控 - 系统状态、指标、版本信息
+  - name: Agents
+    description: Agent 发现与健康监控 - 基于 Temporal Task Queue 实时状态
+  - name: Task Queues
+    description: Task Queue 列表与 Worker 计数 - Temporal 原生数据
 
 security:
   - bearerAuth: []
@@ -1004,6 +1008,84 @@ paths:
                     type: string
                     example: "2026-01-15T10:00:00Z"
 
+  # ==================== Agents ====================
+  /v1/agents:
+    get:
+      summary: 列出所有 Agent
+      description: |
+        返回所有已知 Task Queue 的 Agent 健康状态。
+        通过 Temporal `DiscoverTaskQueues` 发现 Task Queue，再用 `DescribeTaskQueue` 查询实时 poller 数据。
+      operationId: listAgents
+      tags: [Agents]
+      responses:
+        '200':
+          description: Agent 列表
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListAgentsResponse'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /v1/agents/summary:
+    get:
+      summary: 获取 Agent 汇总统计
+      description: 返回跨所有 Task Queue 的健康状态聚合数据，适用于监控仪表板。
+      operationId: getAgentsSummary
+      tags: [Agents]
+      responses:
+        '200':
+          description: 汇总统计
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentsSummaryResponse'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /v1/agents/{name}:
+    get:
+      summary: 获取单个 Agent 状态
+      description: 通过 Task Queue 名称查询指定 Agent 的实时 Temporal Worker 状态。
+      operationId: getAgentStatus
+      tags: [Agents]
+      parameters:
+        - name: name
+          in: path
+          required: true
+          description: Agent 名称（即 Task Queue 名称）
+          schema:
+            type: string
+            example: linux-amd64
+      responses:
+        '200':
+          description: Agent 状态详情
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ==================== Task Queues ====================
+  /v1/task-queues:
+    get:
+      summary: 列出所有 Task Queue
+      description: 返回所有已知 Task Queue 及其实时 Worker 数量与健康状态（Temporal 原生数据）。
+      operationId: listTaskQueues
+      tags: [Task Queues]
+      responses:
+        '200':
+          description: Task Queue 列表
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListTaskQueuesResponse'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
 components:
   securitySchemes:
     bearerAuth:
@@ -1048,6 +1130,124 @@ components:
         default: 20
 
   schemas:
+    # ========== Agent Schemas ==========
+    AgentResponse:
+      type: object
+      description: 单个 Agent（Task Queue）的健康状态
+      properties:
+        name:
+          type: string
+          example: linux-amd64
+        pollers:
+          type: integer
+          description: Task Queue 上的 Worker 总数
+          example: 3
+        healthy_pollers:
+          type: integer
+          description: 30 秒内有活动的健康 Worker 数量
+          example: 3
+        task_backlog:
+          type: integer
+          format: int64
+          description: 待处理任务数量
+          example: 0
+        status:
+          type: string
+          enum: [healthy, degraded, unavailable]
+          description: |
+            健康状态：
+            - `healthy`：≥50% Worker 在 30 秒内活跃
+            - `degraded`：>0 但 <50% Worker 健康
+            - `unavailable`：无 Worker 或查询失败
+          example: healthy
+        last_update_time:
+          type: string
+          format: date-time
+          example: "2026-03-06T10:30:00Z"
+
+    ListAgentsResponse:
+      type: object
+      properties:
+        agents:
+          type: array
+          items:
+            $ref: '#/components/schemas/AgentResponse'
+        total_count:
+          type: integer
+          example: 3
+        timestamp:
+          type: string
+          format: date-time
+          example: "2026-03-06T10:30:01Z"
+
+    TaskQueueResponse:
+      type: object
+      description: Task Queue 实时状态（与 AgentResponse 结构相同，语义为队列视角）
+      properties:
+        name:
+          type: string
+          example: web-servers
+        pollers:
+          type: integer
+          example: 2
+        healthy_pollers:
+          type: integer
+          example: 1
+        task_backlog:
+          type: integer
+          format: int64
+          example: 5
+        status:
+          type: string
+          enum: [healthy, degraded, unavailable]
+          example: degraded
+        last_update_time:
+          type: string
+          format: date-time
+          example: "2026-03-06T10:29:00Z"
+
+    ListTaskQueuesResponse:
+      type: object
+      properties:
+        task_queues:
+          type: array
+          items:
+            $ref: '#/components/schemas/TaskQueueResponse'
+        total_count:
+          type: integer
+          example: 2
+        timestamp:
+          type: string
+          format: date-time
+          example: "2026-03-06T10:30:01Z"
+
+    AgentsSummaryResponse:
+      type: object
+      description: 跨所有 Task Queue 的聚合健康统计
+      properties:
+        total_queues:
+          type: integer
+          example: 5
+        healthy_queues:
+          type: integer
+          example: 3
+        degraded_queues:
+          type: integer
+          example: 1
+        unavailable_queues:
+          type: integer
+          example: 1
+        total_pollers:
+          type: integer
+          example: 12
+        healthy_pollers:
+          type: integer
+          example: 10
+        timestamp:
+          type: string
+          format: date-time
+          example: "2026-03-06T10:30:01Z"
+
     # ========== Workflow Schemas ==========
     SubmitWorkflowRequest:
       type: object

docs/guides/cmdb-integration.md

@@ -1,10 +1,18 @@
 # CMDB 集成指南
 
-> ⚠️ **历史文档警告** (更新于 2025-12-29)  
-> 本文档描述的 Agent 注册/心跳机制已废弃（ADR-0007 之前的架构）。  
-> **当前架构：** Agent 通过 Temporal Worker 自动连接，无需注册 API。  
-> **CMDB 集成：** 现在通过 `server-groups.yaml` 文件进行服务器组映射。  
-> **参考文档：** [ADR-0008](../adr/0008-temporal-as-internal-service.md) | [Server Groups 指南](./server-groups.md)
+> ❌ **本文档已废弃 — 请勿参考实施** (更新于 2025-12-29)
+>
+> 本文档描述的 `ServerGroupProvider` 接口、`InMemoryProvider`、`FileProvider` 以及 Agent 注册 API **从未被实现**。
+>
+> **根本原因：** Story 2.3 于 2025-12-29 根据 [ADR-0008](../adr/0008-temporal-as-internal-service.md) 取消。
+> `pkg/provider/` 目录不存在，`ServerGroupProvider` 接口从未创建。
+>
+> **当前架构（实际已实现）：**
+> - Agent 通过 Temporal Worker 自动注册，无需任何注册 API
+> - Agent 健康监控使用 Temporal 原生 `DescribeTaskQueue` API（见 `internal/api/agent_handler.go`）
+> - 服务器组映射通过 runs-on 和 Task Queue 直接对应（见 ADR-0008）
+>
+> **参考文档：** [ADR-0008](../adr/0008-temporal-as-internal-service.md) | [Story 2.2](../sprint-artifacts/2-2-server-group-task-queue-mapping.md)
 
 ## 概述
 

docs/sprint-artifacts/1-10-schedule-api-implementation.md

@@ -2160,14 +2160,16 @@ open http://localhost:8233
 - ✅ 修复问题5: 添加Schedule数量限制检查（100/workflow）
 - ✅ 修复问题6-8: 补充4个集成测试（覆盖AC3/4/6/10）
 - ✅ 修复问题9: 优化ListAllSchedules性能（避免不必要的Describe调用）
+- ✅ 修复问题10 (2026-03-06): `Manager.ListByWorkflow/Get/List/Pause/Resume/Update/Trigger/Delete` 无 nil 守卫，`temporalClient=nil` 时直接 dereference 导致 panic；添加 `checkTemporalClient()` helper，所有 Temporal 操作前统一守卫，单元测试从 3/5 提升至 **5/5 PASS**
 
 ### File List
 
 **核心实现文件:**
-- `internal/server/schedule/manager.go` (580行) - Schedule业务逻辑层
+- `internal/server/schedule/manager.go` (~610行) - Schedule业务逻辑层
   - Create/List/ListByWorkflow/Get/Update/Pause/Resume/Trigger/Delete
   - Cron验证、Schedule数量限制、参数合并逻辑
   - convertFromDescription/convertFromListEntry辅助函数
+  - `checkTemporalClient()` nil 守卫（2026-03-06 修复）
 - `internal/api/schedule_handler.go` (589行) - Schedule REST API层
   - 9个HTTP handlers（Create/List/Get/Update/Delete/Pause/Resume/Trigger）
   - Request/Response类型定义、错误处理
@@ -2427,7 +2429,7 @@ err := handle.Update(ctx, client.ScheduleUpdateOptions{
 - ✅ 错误反馈增强：YAML 验证错误显示详细字段级错误
 
 **测试覆盖:**
-- ✅ 单元测试：5个测试函数 (manager_simple_test.go) - 3/5通过
+- ✅ 单元测试：5个测试函数 (manager_simple_test.go) - **5/5通过**（2026-03-06 nil守卫修复后全部通过）
 - ✅ 集成测试：11个测试场景 - **6/11通过 (55%)**
   - ✅ INT-001: CreateSchedule
   - ✅ INT-002: PauseResumeSchedule
@@ -2487,6 +2489,21 @@ Temporal Server 1.29.1 + Go SDK v1.38.0 存在向后兼容性问题：
 - [ ] 重新运行集成测试验证修复
 - [ ] 可选：实现Memo fallback机制作为永久compatibil层
 
+**问题2: `Manager` 方法 nil pointer panic（已修复 2026-03-06）**
+
+**症状:** `TestManager_Create_WorkflowExists` panic — `invalid memory address or nil pointer dereference`
+
+**根本原因:**
+`ListByWorkflow`（及其他8个方法）在第一行直接调用 `m.temporalClient.ScheduleClient()`，无 nil 检查。
+测试刻意传入 `nil` temporalClient 来验证workflow存在性检查，在进入 Temporal 操作前被 panic 打断。
+
+**修复:**
+- 新增 `checkTemporalClient() error` helper method
+- 在 `Create/List/ListByWorkflow/Get/Pause/Resume/Update/Trigger/Delete` 共9处 Temporal 操作前统一调用
+- `Create` 中守卫位置在 workflow 存在性检查之后，确保 "workflow not found" 优先于 "temporal client not initialized"
+
+**验证:** `manager_simple_test.go` 全部 **5/5 PASS**（修复前 3/5）
+
 ---
 
 ### 未完成项（Post-MVP）

docs/sprint-artifacts/2-2-server-group-task-queue-mapping.md

@@ -1227,15 +1227,16 @@ Claude Sonnet 4.5
 - `pkg/dsl/validator_runs_on_test.go` - runs-on 验证测试 (210 行)
 
 **修改文件:**
-- `pkg/dsl/semantic_validator.go` - 添加 ValidateTaskQueueName + validateRunsOn (~90 行新增)
-- `pkg/temporal/workflow.go` - 添加防御性 runs-on 检查 (~12 行新增)
+- `pkg/dsl/semantic_validator.go` - 添加 ValidateTaskQueueName + validateRunsOn；提取 taskQueueNameRegex 为包级 var；validateRunsOn 改委托 ValidateRunsOn（支持表达式语法）(~105 行新增)
+- `pkg/dsl/task_queue_validator_test.go` - Matrix 表达式语法测试用例 (+3 用例)
+- `pkg/temporal/workflow.go` - 添加 buildChildWorkflowOptions 含默认 360min 超时；防御性 runs-on 检查 (~26 行新增)
 - `README.md` - 更新多服务器示例 (~15 行修改)
 - `docs/sprint-artifacts/sprint-status.yaml` - 状态更新
 - `docs/sprint-artifacts/2-2-server-group-task-queue-mapping.md` - 本文件
 
 **Story 1.9 新增 (Task Queue API):**
-- `internal/api/taskqueue_handler.go` - Task Queue 查询 API (150 行)
-- `internal/api/router.go` - 注册路由 (~2 行新增)
+- `internal/api/workflow_handler.go` - `ListTaskQueues` 占位实现（位于此文件末尾，完整实现待 Story 2.7）
+- `internal/api/router.go` - 注册路由 (~3 行新增，H3 修复)
 
 **总计:** ~1131 新增代码行 (含测试), ~32 修改行
 
@@ -1269,3 +1270,10 @@ Claude Sonnet 4.5
 - ✅ MEDIUM-1 (M1): 消除 `ValidateRunsOn` 与 `ValidateTaskQueueName` 的重复逻辑，前者现委托后者 (validator_runs_on.go)；`ValidateTaskQueueName` 长度检查提前至 regex 前 (semantic_validator.go)
 - ✅ MEDIUM-2/LOW-1 (M2/L1): 删除误导性注释 "当前只支持单 Job" 及随机 map 迭代 for-loop (workflow_handler.go)
 - ✅ MEDIUM-3 (M3): 文档化连续双连字符命名行为及警告 (docs/guides/server-groups.md)
+
+**代码审查修复 (2026-03-06):**
+- ✅ HIGH (H1): 修复 `SemanticValidator.validateRunsOn` 直接调用 `ValidateTaskQueueName` 而非 `ValidateRunsOn`，导致 Matrix 表达式语法 (`${{ matrix.server }}`) 在 API 验证时被错误拒绝；现委托 `ValidateRunsOn` 以支持 AC5.1 (semantic_validator.go)
+- ✅ MEDIUM (M1): 修正文件列表误报——`taskqueue_handler.go` 从未创建，`ListTaskQueues` 实际位于 `workflow_handler.go` 末尾
+- ✅ MEDIUM (M2): 将 `ValidateTaskQueueName` 内 `regexp.MustCompile` 提取为包级变量，消除高频调用的重复编译 (semantic_validator.go)
+- ✅ LOW (L1): 为 `TestSemanticValidator_ValidateRunsOn` 补充3个 Matrix 表达式语法测试用例 (task_queue_validator_test.go)
+- ✅ LOW (L2): 子工作流增加 `WorkflowExecutionTimeout`，`TimeoutMinutes=0` 时使用默认 360 分钟，防止无限等待 (workflow.go)