更新RMDC系统的模块SKILL

2026-02-02 15:06:28 +08:00
parent 93624efdab
commit a02ac14481
89 changed files with 8101 additions and 2417 deletions
--- a/1-AgentSkills/managing-observability/SKILL.md
+++ b/1-AgentSkills/managing-observability/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: managing-observability
+description: "Guides observability implementation including structured logging, metrics, tracing, and audit log alignment for RMDC system. Triggered when adding log statements, defining metrics, implementing traces, or ensuring audit compliance. Keywords: structured log, metrics, trace, audit, Prometheus, OpenTelemetry, rmdc-audit-log."
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+argument-hint: "$ARGUMENTS: <aspect> [module] — aspect: logging|metrics|tracing|audit"
+---
+
+# managing-observability
+
+## 概述
+本 Skill 指导 RMDC 系统的可观测性实现，确保日志、指标、追踪与审计的一致性。
+
+## 动态上下文注入
+
+### 查找日志调用
+!`grep -rn "log\.\(Info\|Error\|Warn\|Debug\)" --include="*.go" | head -20`
+
+### 查找审计相关代码
+!`grep -rn "audit\|Audit\|AuditLog" --include="*.go" | head -20`
+
+---
+
+## Plan（规划阶段）
+
+### 可观测性维度
+| 维度 | 工具 | 对齐模块 |
+|:---|:---|:---|
+| 日志 | 结构化日志 | rmdc-audit-log |
+| 指标 | Prometheus | - |
+| 追踪 | OpenTelemetry | - |
+| 审计 | PostgreSQL | rmdc-audit-log |
+
+### 决策点
+- [ ] 日志级别是否合适？
+- [ ] 是否需要添加审计记录？
+- [ ] 指标命名是否符合规范？
+- [ ] trace_id 是否正确传递？
+
+---
+
+## Verify（验证清单）
+
+### 日志规范检查
+- [ ] 使用结构化日志格式
+- [ ] 包含 request_id / trace_id
+- [ ] 敏感信息已脱敏
+- [ ] 日志级别正确
+
+### 审计对齐检查
+- [ ] 关键操作有审计记录
+- [ ] 审计字段完整（who/when/what/where）
+- [ ] 审计记录不可篡改
+- [ ] 与 rmdc-audit-log 格式一致
+
+### 验证命令
+```bash
+# 检查日志调用规范
+grep -rn "log\." --include="*.go" | grep -v "WithFields" | head -20
+
+# 检查审计记录
+grep -rn "AuditLog\|audit" --include="*.go" | head -20
+```
+
+---
+
+## Execute（执行步骤）
+
+### 添加结构化日志
+```go
+import log "github.com/sirupsen/logrus"
+
+log.WithFields(log.Fields{
+    "user_id":    userID,
+    "action":     "login",
+    "request_id": requestID,
+}).Info("用户登录成功")
+```
+
+### 添加审计记录
+```go
+auditLog.Record(AuditEntry{
+    UserID:     userID,
+    Action:     "UPDATE_USER",
+    ResourceID: targetUserID,
+    Details:    changes,
+    Timestamp:  time.Now(),
+    IP:         clientIP,
+})
+```
+
+### 添加 Prometheus 指标
+```go
+var loginCounter = prometheus.NewCounterVec(
+    prometheus.CounterOpts{
+        Name: "rmdc_user_auth_login_total",
+        Help: "Total number of login attempts",
+    },
+    []string{"status"},
+)
+
+// 使用
+loginCounter.WithLabelValues("success").Inc()
+```
+
+---
+
+## Pitfalls（常见坑）
+
+1. **日志泄露敏感信息**：密码、Token、身份证号等未脱敏直接打印。
+2. **审计字段缺失**：无法追溯操作人（user_id）或操作内容（details）。
+3. **日志级别滥用**：DEBUG 日志在生产环境大量输出影响性能。
+4. **审计记录可被删除**：审计表需要设置写保护，禁止 DELETE/UPDATE。
+5. **trace_id 未传递**：跨服务调用时未将 trace_id 传递到下游，无法串联请求链路。
+6. **指标命名不规范**：未遵循 `模块_资源_动作_单位` 格式。
+
+---
+
+## 相关文件
+| 用途 | 路径 |
+|:---|:---|
+| 日志格式 | [reference/log-format.md](reference/log-format.md) |
+| 指标命名 | [reference/metrics-naming.md](reference/metrics-naming.md) |
+| 审计对齐 | [reference/audit-alignment.md](reference/audit-alignment.md) |