// HotPlex 项目架构和代码健康深度审计 — **立即调用此 skill 进行**：架构分析、代码质量审查、SOLID/DRY 合规检查、并发/性能审计、安全扫描、非功能分析、代码健康度改进、模块质量评估。**专为 HotPlex Gateway 多层架构优化**（WebSocket/Session/Worker/Messaging），自动创建 GitHub Issue 和验收标准。增量式模块分析 + 跨会话进度追踪 + 优先级排序 = **最有效的 /loop 循环执行工具**，适用于大型 Go 代码库的系统性审计。
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | hotplex-arch-analyzer |
| description | HotPlex 项目架构、代码健康和性能优化深度审计 — **立即调用此 skill 进行**：架构分析、代码质量审查、SOLID/DRY 合规检查、并发安全审计、**性能优化识别**（热路径分配、锁竞争、sync.Pool、JSON 编码开销）、安全扫描、非功能分析、代码健康度改进、模块质量评估、存量 issue 审计与清理。**专为 HotPlex Gateway 多层架构优化**（WebSocket/Session/Worker/Messaging），内建 HotPlex 热路径性能模式库（WritePump、Hub 广播、Streaming Card、Worker stdio、Event Store），自动创建/验证 GitHub Issue。增量式模块分析 + 存量 issue 审计 + 跨会话进度追踪 + 优先级排序 = **最有效的 /loop 循环执行工具**，适用于大型 Go 代码库的系统性审计。**当提到**：性能分析、性能优化、瓶颈定位、延迟优化、内存分配、锁竞争、pprof、benchmark、热路径优化、吞吐量提升 — 即使没有明确说"架构分析"也应使用此 skill。 |
架构分析是复杂且易出错的工作 — 容易遗漏重要问题、产生误报、或浪费时间在低价值发现上。此 skill 通过以下方式解决这些问题：
渐进式分析 — 每次 2-3 个方面，避免信息过载，让每个发现都经过深思熟虑
智能优先级 — 自动优先分析最少审计模块，确保覆盖均衡
置信度 + ROI 分诊 — 过滤误报和低价值发现，只创建高影响力 issue
存量 Issue 审计 — 当 open issues 超过阈值时，自动切换为审计模式：核实、关闭、更正
持久化进度 — 跨会话追踪，支持 /loop 连续执行，不会丢失工作
HotPlex 专用优化 — 针对 Gateway 多层架构的特殊模式定制
核心设计：每次调用 = 一个分析周期在一个模块上覆盖2-3 个方面。专为 /loop 设计 — 重复调用在 4 个深度阶段中渐进覆盖所有模块 × 所有方面。
状态持久化在 .claude/arch-analysis/progress.json — 跨会话重启存活，启用 /loop 连续性。
手动执行的问题：
使用 /loop 的好处：
推荐 /loop 设置：
/loop 10m /hotplex-arch-analyzer
这每 10 分钟运行一次分析，适合大型代码库的渐进式分析。调整间隔基于代码库大小和分析深度需求。
本文档使用渐进式信息披露 — 快速开始只需阅读工作流概览和步骤 1-3。详细参考材料（模块发现、分析方面、进度文件模式）在后面供需要时查阅。
快速路径（新用户）：
深度路径（经验用户）：
每次调用遵循两种模式之一，由**步骤 1.5（模式检测）**决定：
分析模式（默认）：
加载进度 → 选择模块 → 选择方面 → 深度分析 → 分诊 → 去重检查 → 创建/更新 Issue → 更新进度 → 报告
审计模式（open issues ≥ 阈值时激活）：
加载进度 → 选择 Issue → 验证代码 → 分类处理 → 更新进度 → 报告
为什么需要双模式：分析模式持续发现新问题，但问题积累后会降低团队信任度和审查效率。审计模式定期清理存量 issue，关闭误报、更正偏差，保持 issue backlog 的健康。两个模式交替运行，既不停止分析，也不让 issue 失控。
读取 .claude/arch-analysis/progress.json。
如果未找到 — 运行初始化：
每次调用开始时，检查是否应该进入审计模式：
# 获取当前 open architecture issues 数量
OPEN_COUNT=$(gh issue list --label "architecture" --state open --json number --limit 200 | python3 -c "import json,sys; print(len(json.load(sys.stdin)))")
echo "Open architecture issues: $OPEN_COUNT"
决策规则（按优先级）：
审计与分析的交替：当 open issues 在阈值附近波动时，审计和分析交替执行。每审计一轮后检查：如果 open issues 仍 ≥ 30 → 继续审计；否则切回分析模式。
为什么阈值是 30：经验表明，超过 30 个 open issues 时：
优先级（第一个匹配胜出）：
analysis_count == 0 — 从未分析，最高优先级analysis_count — 最少覆盖每个模块在 4 个阶段中有 12 个方面。从 aspects_pending 中选择 2-3 个：
对于每个选定的方面，读取目标模块中的所有源文件（包括 _test.go）。
为什么读取所有文件：架构问题往往跨文件显现 — 只看单个文件会遗漏耦合模式、重复逻辑、或不一致的错误处理。
分析特定方面时，读取 references/analysis-checklist.md 中的相应部分，以获取要检查的内容的详细清单。清单提供了要验证的具体项目 — 将其用作指南，而非强制性逐项清单。
分析产出标准：每个发现必须包含四个要素：
file.go:line_range 引用（通常 2-3 个文件位置提供充分上下文）为什么需要代码片段：没有代码示例的发现难以理解和实施。片段让问题立即可操作，无需审查者重新阅读源代码。
每个发现必须包含一个最小的代码示例，演示问题和修复方向。这使得问题可立即操作，无需重新阅读源代码。
好的片段 — 显示问题模式和提议的替代方案：
// 当前：静默错误丢失
if err != nil {
log.Error("failed", "err", err)
return nil // 调用者不知道这失败了
}
// 提议：带上下文传播
if err != nil {
return fmt.Errorf("handleMessage: %w", err)
}
太冗长 — 不要粘贴整个函数。提取重要的 5-15 行模式。 太模糊 — 不要写"重构使用接口"而不显示接口签名。
对于结构/设计发现（SOLID、DRY），显示提议的接口或类型分解：
// 提议的提取
type MessagePipeline interface {
Parse(ctx context.Context, raw any) (*ParsedMessage, error)
Filter(ctx context.Context, msg *ParsedMessage) (bool, error)
Route(ctx context.Context, msg *ParsedMessage) error
}
严重性级别：Critical（数据丢失 / 安全 / 死锁）> High（可靠性 / 性能）> Medium（可维护性 / DRY）> Low（风格 / 命名 / 次要）
如果方面没有产生真正的发现，则跳过 — 不要制造问题。
为什么分诊很重要：未经分诊的分析会产生大量误报和低价值发现，浪费审查时间并降低对架构分析的信任。通过评估置信度和 ROI，只创建真正重要的问题。
在创建 issue 之前，通过两个过滤器对每个发现进行分诊：
评估您对这是真正问题而非误报的确定性程度：
| 级别 | 标准 | 行动 |
|---|---|---|
| 高 | 多个代码引用确认问题；模式明确；可用具体示例轻松演示 | 创建 issue |
| 中 | 单个实例但模式清晰；匹配众所周知的反模式；中等代码证据 | 创建 issue（在 issue 中注明置信度） |
| 低 | 推测性；可能是有意的设计；代码证据不足；需要更深入的调查以确认 | 丢弃（在进度中记为"观察到但不可操作"） |
为什么丢弃低置信度发现：它们浪费审查者时间，并降低对架构分析过程的信任。在进度中记录它们以便后续重新分析时重新评估。
评估修复每个发现的投入产出比 — 这决定是否值得花费工程时间：
| 维度 | 问题要问 |
|---|---|
| 修复投入 | 要更改的代码行？回归风险？是否需要架构更改？ |
| 修复后影响 | 它会解锁其他改进吗？减少 bug 表面积吗？提高可测试性吗？ |
| 延迟影响 | 它会进一步衰减吗？阻止其他工作吗？导致生产问题吗？ |
ROI 分类和行动：
为什么 ROI 比严重性更重要：一个 Low 严重性但高 ROI 的问题（如简单的 DRY 重构）比 High 严重性但低 ROI 的问题（如需要重写的大型重构）更值得优先处理。
分诊后，将发现组织到 issue 中：
为什么需要去重：长期运行的分析器容易对同一模块重复创建 issue，尤其是：
去重检查确保：每个真实问题只有一个 issue，避免审查疲劳和重复工作。
第一步：按模块搜索现有 issue
# 搜索当前模块相关的所有 open architecture issues
gh issue list --label "architecture" --state open \
--json number,title,body,createdAt \
--limit 200 | python3 -c "
import json, sys
issues = json.load(sys.stdin)
module = '$MODULE' # 当前模块，如 internal/gateway
module_short = module.split('/')[-1] # 如 gateway
for i in issues:
title = i['title'].lower()
body = (i.get('body') or '').lower()
if module in title or module in body or module_short in title:
print(f\"{i['number']}: {i['title'][:80]}\")
"
同时检查进度文件：读取 progress.json 中当前模块的 issues_created 数组，获取该模块历史上创建的所有 issue 编号（含已关闭的），用于语义匹配。
第二步：语义重叠检测
对第一步返回的每个相关 issue，读取其 body，与本周期发现逐一比较：
| 比较维度 | 检查方法 |
|---|---|
| 文件重叠 | 本发现引用的文件是否在已有 issue 的 Key files 中出现 |
| 位置重叠 | 行号范围是否有交集（±50 行容差，考虑代码变动） |
| 方面重叠 | 是否覆盖同一分析方面（如都是 error-handling） |
| 问题模式 | 描述的问题模式是否本质相同（如"静默吞掉错误"vs"错误未传播"= 同一问题） |
重叠判定规则：
第三步：判定与处理
对每个发现，给出以下判定之一：
| 判定 | 条件 | 处理方式 |
|---|---|---|
| new | 无任何重叠，全新发现 | 进入步骤 5 正常创建 |
| duplicate | 与已有 issue 描述完全相同的问题 | 跳过创建，进度中记录 |
| subsumed | 本发现是已有 issue 的子集或特殊情况 | 更新已有 issue，添加此发现为补充 |
| supersedes | 本发现更全面，已有 issue 是其子集 | 扩展已有 issue 的标题和内容 |
| related | 相关但独立，共享部分代码但根本原因不同 | 创建新 issue，引用已有 issue |
第四步：执行处理
findings_dropped 中记录：{"finding": "name", "reason": "Duplicate of issue N — <overlap reason>"}gh issue comment <EXISTING_NUMBER> --body "$(cat <<'EOF'
arch-analysis (cycle N, <aspect>): 补充发现。
#### <finding-name>
**Location**: \`file.go:line_range\`
**问题**: <简述 — 2-3 句>
**代码片段**:
\`\`\`go
<5-10 行代码>
\`\`\`
**补充说明**: <此发现如何与原 issue 关联>
EOF
)"
Related: issue N当发现可能与多个已有 issue 相关时，按以下优先级匹配：
将此周期中经过步骤 4.8 判定为 new 或 related 的发现合并到一个 GitHub issue 中。被判定为 duplicate/subsumed/supersedes 的发现已在步骤 4.8 中处理，不进入此步骤。
为什么合并而不是拆分：相关问题放在一个 issue 中提供上下文 — 审查者可以看到模式的完整图景，实施者可以在一次 PR 中解决相关问题，减少上下文切换。
重要的格式规则：
# 数字：GitHub 将 #1 解释为 issue 引用。使用描述性标题或基于 bullet 的编号#### finding-name 或 - **Finding Name**: 作为子标题，永远不要用 #### 1. Title格式规则：避免 # 数字（GitHub 会解析为 issue 引用），使用 #### finding-name 作为子标题，写"cycle N"而不是"cycle #N"（#N 会被 GitHub 解析为 issue 引用）。
Issue 结构：Background → Finding Summary → Findings（含 Severity/Confidence/ROI/Location/Current Pattern/Proposed Fix/AC）→ Implementation Priority → Out of Scope → Verification。完整模板和 AC 撰写指南见 references/issue-template.md。
标题格式：<type>(<module>): <scope> — 类型：refactor / fix / perf / security / chore
标签映射：Critical → P1，High → P2，Medium/Low → P3
如果没有值得 issue 的发现，跳过创建并在进度中注明。
更新 .claude/arch-analysis/progress.json：
analysis_countaspects_coveredissues_createdfindings_dropped（带原因）last_analyzed 时间戳total_cyclesrecent_activity 日志（保留最后 20 个）输出包含进度矩阵的简洁摘要：
## Analysis Cycle N Complete
**Module**: `internal/<module>` (分析通过 M)
**Aspects**: <aspect1>, <aspect2>
**Findings**: X Critical, Y High, Z Medium, W Low
**Issue**: <issue URL 或"跳过 — 无可操作发现">
### Coverage Matrix
| Module | Ph1 | Ph2 | Ph3 | Ph4 | Issues | Status |
|--------|-----|-----|-----|-----|--------|--------|
| gateway | 3/3 | 2/3 | — | — | 2 | 进行中 |
| session | 3/3 | 3/3 | 2/2 | — | 3 | Ph3 完成 |
| messaging | 1/3 | — | — | — | 1 | Ph1 已开始 |
| ... | | | | | | |
### Stats
- 总周期：N
- 总 issues：M
- 完全覆盖的模块：A/总计
- **下一个目标**：`internal/<next-module>` (analysis_count=N, Phase P 待处理)
覆盖矩阵给出了每个模块在 4 个阶段中位置的快速可视化。使用 n/3（或 Ph3/4 的 n/2）格式进行中的阶段，— 表示未开始，✓ 表示完成。
当步骤 1.5 决定进入审计模式时，执行 5 步审计流程替代分析模式（步骤 2-7）。
审计流程概览：选择审计目标 → 逐个验证代码现状 → 判定处理（fixed/invalid/outdated/valid/duplicate）→ 更新进度 → 审计报告。
每次审计 3-5 个 issue，优先从未审计过的最旧 issue 开始，同模块 issue 放在一起审计。
完整审计步骤（含 bash 命令、判定表、处理操作、进度更新、报告格式）见 references/audit-mode.md。
主要来源：CLAUDE.md STRUCTURE 部分 — 如果存在，使用记录的模块边界。
后备：扫描 internal/、pkg/、cmd/ 目录。每个带有 .go 文件的子目录 = 一个模块。
分组紧密耦合的子包：
messaging/slack/ + messaging/feishu/ → 作为子模块在 messaging 下分析worker/claudecode/ + worker/opencodeserver/ + worker/pi/ → 在 worker 下的子模块cli/checkers/ + cli/onboard/ → 在 cli 下的子模块父模块（messaging、worker、cli）获得自己的分析通过，涵盖共享代码（bridge、接口、基本类型）。
internal/gateway — WebSocket hub, conn, handler, bridge, API
internal/session — 状态机, store, pool, key derivation
internal/messaging — 平台适配器, bridge, interaction, STT
internal/messaging/slack — Slack Socket Mode 适配器
internal/messaging/feishu — Feishu WS 适配器
internal/worker — 基础 worker, proc manager
internal/worker/opencodeserver — OCS 单例 + worker
internal/config — Viper 配置, 热重载
internal/agentconfig — Agent 个性/上下文加载器
internal/security — JWT, SSRF, 路径安全, 命令白名单
internal/admin — Admin API 处理器
internal/aep — AEP v1 编解码器
internal/cli — Checker 注册表, onboard 向导
internal/skills — Skills 发现
internal/metrics — Prometheus 计数器
internal/tracing — OpenTelemetry 设置
pkg/events — AEP 包络 + 事件类型
cmd/hotplex — Cobra CLI 入口点
12 个方面跨 4 个阶段。每个阶段更深入 — 阶段 1 是结构性的，阶段 4 是细粒度的。
| # | 方面 | 重点 |
|---|---|---|
| 1 | SOLID | SRP 违规、接口隔离、依赖倒置、开/闭 |
| 2 | DRY | 模块内的重复逻辑、值得提取的跨模块模式 |
| 3 | 耦合 | 导入图、循环依赖、稳定依赖原则 |
| # | 方面 | 重点 |
|---|---|---|
| 4 | 错误处理 | 静默失败、错误吞咽、哨兵错误、包装一致性 |
| 5 | 并发 | 竞争条件、互斥锁排序、goroutine 生命周期、通道泄漏 |
| 6 | 资源管理 | 连接/文件/goroutine 泄漏、defer 清理、关闭路径 |
| # | 方面 | 重点 | 参考 |
|---|---|---|---|
| 7 | 性能 | 热路径、不必要的分配、N+1 模式、缓冲区重用 | references/performance-patterns.md |
| 8 | 可扩展性 | 在 10x/100x 负载下的单点故障、瓶颈 | references/performance-patterns.md |
| # | 方面 | 重点 |
|---|---|---|
| 9 | 安全 | 输入验证缺口、注入风险、认证/授权绕过 |
| 10 | 可观测性 | 结构化日志缺口、指标覆盖、跟踪跨度 |
| 11 | 可测试性 | DI 覆盖、可模拟性、错误路径的测试缺口 |
| 12 | 代码质量 | 圈复杂度、上帝对象、死代码、命名一致性 |
阶段 1（架构与设计）优先：因为结构性问题影响所有后续代码。在修复 SOLID/DRY 违规后再优化性能，避免在错误设计上浪费时间。
阶段 2（可靠性）其次：并发和错误处理问题是常见的生产故障根源。修复它们可以提高系统稳定性。
阶段 3（性能与规模）第三：只有在架构稳定和可靠性问题解决后才优化。过早优化是万恶之源。
阶段 4（安全与质量）最后：这些是"卫生因素" — 重要但通常不阻塞功能。在最后阶段确保代码库健康。
为什么每次 2-3 个方面：更多方面会导致表面分析。更少方面虽然深度更好，但需要更多调用才能覆盖。2-3 个方面是深度和速度的最佳平衡。
以下详细内容已提取到 references/ 目录，按需读取：
| 文件 | 内容 | 何时读取 |
|---|---|---|
references/issue-template.md | 完整 issue bash 模板 + 标题/标签格式 + AC 撰写指南 | 创建 issue 前（步骤 5） |
references/audit-mode.md | 审计模式完整流程（5 步 + bash 命令 + 判定表） | 进入审计模式时（步骤 1.5） |
references/analysis-checklist.md | 12 个方面的详细分析清单（含 HotPlex 性能专项） | 深度分析时（步骤 4） |
references/performance-patterns.md | HotPlex 热路径性能模式 + 通用 Go 反模式 + 检测方法论 + 验证手段 | 分析 aspect 7-8（Performance/Scalability）时 |
references/progress-and-metrics.md | 进度文件 schema + 边缘情况 + 成功指标 + 持续改进 | 需要查阅 schema 或调优时 |
references/troubleshooting.md | 9 个常见陷阱及解决方案 | 遇到问题或结果不理想时 |
进度文件关键字段：findings_dropped 跟踪分诊丢弃和去重判为 duplicate 的发现。audited_issues 跟踪已审计 issue 避免重复审计。完整 schema 见 references/progress-and-metrics.md。
健康指标速查：Issue 创建率 60-80%，有效率 ≥70%，审计回收率 10-30%，去重拦截率 10-25%。详细指标和调整建议见 references/progress-and-metrics.md。