RMDC系统设计文档 整体转换为SKILL

1-AgentSkills/developing-watchdog/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: developing-watchdog
+description: Guides development of rmdc-watchdog edge agent module including K8S operations, MQTT messaging, authorization management, and node/agent coordination. Use when implementing watchdog features, adding K8S actions, modifying heartbeat logic, or debugging authorization flows. Keywords: watchdog, edge-agent, k8s-operator, mqtt, authorization, heartbeat, node, agent.
+argument-hint: "<feature-type>: k8s-action | heartbeat | mqtt-handler | node-comm | auth-flow"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Edit
+  - Write
+---
+
+# Developing rmdc-watchdog
+
+rmdc-watchdog 是部署在项目环境的边缘代理，职责包括：二级授权中心、K8S操作代理、指令接收执行、监控数据上报。
+
+## 动态上下文注入
+
+```bash
+# 查看项目结构
+!`ls -la rmdc-watchdog/internal/`
+
+# 查找现有Handler实现
+!`grep -rn "func.*Handler" rmdc-watchdog/internal/handler/`
+
+# 查找MQTT消息路由
+!`grep -n "case\|switch" rmdc-watchdog/internal/service/message_router.go`
+```
+
+## Plan
+
+根据 `$ARGUMENTS` 确定开发类型：
+
+| 类型 | 产物 | 影响模块 |
+|------|------|----------|
+| k8s-action | `pkg/k8s/client.go`, `service/k8s_service.go` | exchange-hub指令定义 |
+| heartbeat | `handler/heartbeat_handler.go`, `service/auth_service.go` | watchdog-agent同步修改 |
+| mqtt-handler | `service/mqtt_service.go`, `service/message_router.go` | exchange-hub Topic契约 |
+| node-comm | `service/node_service.go` | watchdog-node API同步 |
+| auth-flow | `service/auth_service.go`, `dao/auth_dao.go` | project-management授权契约 |
+
+**决策点**：
+1. 是否新增MQTT消息类型？→ 需同步 exchange-hub
+2. 是否修改心跳结构？→ 需同步 watchdog-agent
+3. 是否修改K8S指令参数？→ 需同步 octopus-operator
+
+## Verify
+
+- [ ] TOTP验证逻辑：一级(8位/30分钟/SHA256) vs 二级(6位/30秒/SHA1)
+- [ ] K8S操作边界：仅允许审计过的操作(logs/exec/scale/restart/delete/get/apply)
+- [ ] MQTT Topic格式：`wdd/RDMC/{command|message}/{up|down}/{project_id}`
+- [ ] 时间戳校验：|now - timestamp| < 5分钟
+- [ ] Node通信：HTTP + Tier-Two TOTP认证
+- [ ] 执行结果上报：包含 command_id, status, exit_code, output, duration
+
+```bash
+# 验证编译
+!`cd rmdc-watchdog && go build ./...`
+
+# 验证单元测试
+!`cd rmdc-watchdog && go test ./internal/... -v`
+```
+
+## Execute
+
+### 添加新K8S操作
+
+1. 在 `pkg/k8s/client.go` 添加K8S API方法
+2. 在 `internal/service/k8s_service.go` 的 switch 添加 case
+3. 更新 `K8sExecCommand` 结构（如需新参数）
+4. 同步更新 exchange-hub 指令下发定义
+
+### 添加新指令类型
+
+1. 在 `message_router.go` 添加路由分支
+2. 创建对应 Handler 和 Service
+3. 同步更新 exchange-hub 指令下发
+
+### 修改心跳逻辑
+
+1. 修改 `auth_service.go` 的 `VerifyHeartbeat`
+2. 同步修改 watchdog-agent 心跳发送
+3. 更新 DTO 结构
+
+## Pitfalls
+
+1. **TOTP层级混淆**：一级授权(project-management↔watchdog)与二级授权(watchdog↔agent/node)使用不同参数
+2. **时间偏移未处理**：授权文件需计算 `timeOffset = now - firstAuthTime`
+3. **Node离线未检测**：转发主机指令前需 `CheckHostOnline(host_id)`
+4. **日志截断遗漏**：业务故障日志仅回传最近300行
+5. **密钥公网传输**：tier_one_secret/tier_two_secret 必须通过配置文件离线部署，禁止MQTT传输
+6. **响应TOTP缺失**：双向验证要求服务端返回TOTP供客户端校验
+7. **心跳间隔不一致**：watchdog→exchange-hub 5秒；agent/node→watchdog 10秒（默认）
+
+## Reference
+
+- [状态机](reference/state-machine.md)
+- [MQTT Topics](reference/mqtt-topics.md)
+- [API端点](reference/api-endpoints.md)
+- [安全机制](reference/security-mechanisms.md)