aiox-core 5.0.0

package/docs/zh/architecture/adr/adr-hcs-health-check-system.md

@@ -0,0 +1,489 @@
+<!-- 翻译: zh-CN | 原文: /docs/architecture/adr/adr-hcs-health-check-system.md | 同步日期: 2026-02-22 -->
+
+# ADR: 健康检查系统架构
+
+**ADR ID:** ADR-HCS-001
+**状态:** 提议
+**创建日期:** 2025-12-30
+**作者:** @architect (Aria) 通过 @dev (Dex)
+**Story:** HCS-1 调研
+**决策者:** @architect、@po、技术负责人
+
+---
+
+## 背景
+
+AIOX 需要一个全面的健康检查系统，用于：
+
+1. **诊断问题** - 项目配置、环境和集成
+2. **启用自动修复** - 无需手动干预修复常见问题
+3. **跟踪技术债务** - 识别降级状态
+4. **提供可见性** - 通过仪表板了解整体项目健康状况
+5. **CI/CD 集成** - 持续健康监控
+
+### 问题陈述
+
+目前，开发者需要在多个领域手动诊断问题：
+
+- 框架配置漂移
+- 环境配置错误
+- MCP 集成损坏
+- 具有安全漏洞的过时依赖
+- IDE 配置不一致
+
+这导致：
+
+- 调试浪费时间
+- 团队间开发环境不一致
+- 静默失败后来表现为 bug
+- 安全漏洞未被发现
+
+### 需求
+
+1. **执行模式:** 手动、CI 定时、合并后、IDE 后台可选
+2. **检查域:** 项目一致性、本地环境、仓库、部署、服务
+3. **自动修复:** 分层方法（静默、提示、手动指南）
+4. **性能:** 快速模式 <10s，完整模式 <60s
+5. **可扩展性:** 支持项目特定的自定义检查
+6. **集成:** 复用 Story 3.11 质量仪表板组件
+
+---
+
+## 决策
+
+我们将实现一个**混合健康检查系统**，具有以下架构：
+
+### 核心架构决策
+
+#### 1. 执行模型: 手动优先 + CI 集成
+
+**决策:** 主要执行是手动（`*health-check` 命令），次要是定时 CI 集成。
+
+**理由:**
+
+- 遵循行业模式（Flutter doctor、Homebrew doctor、WP-CLI doctor）
+- 避免 pre-commit hooks 的工作流摩擦
+- Terraform 模式：检测与修复分离
+- Kubernetes 模式：后台持续监控
+
+**拒绝的替代方案:**
+
+- Pre-commit hooks：太慢（10-30s），开发者会用 `--no-verify` 跳过
+- 始终后台运行：复杂，性能问题
+- 仅 CI：对开发者无即时反馈
+
+#### 2. 检查架构: 混合（代码 + YAML）
+
+**决策:** 使用基于代码的检查实现核心功能，基于 YAML 的检查实现可扩展性。
+
+**理由:**
+
+- 代码提供性能和复杂逻辑能力
+- YAML 提供简单的项目特定自定义
+- WP-CLI 模式：核心检查 + `doctor.yml` 自定义检查
+- VS Code 模式：核心隔离 + 扩展灵活性
+
+**结构:**
+
+```
+.aiox-core/core/health-check/
+├── checks/           # JavaScript 核心检查（33 个检查）
+│   ├── project/
+│   ├── local/
+│   ├── repository/
+│   ├── deployment/
+│   └── services/
+└── ...
+
+.aiox/
+└── custom-checks.yaml  # 项目特定 YAML 检查
+```
+
+**拒绝的替代方案:**
+
+- 纯代码：对项目特定需求不可扩展
+- 纯 YAML：对复杂检查（如 npm audit）有限
+- 插件系统：对当前需求过度工程化
+
+#### 3. 自动修复: 三层安全模型
+
+**决策:** 实现三层自动修复，具有严格的安全规则。
+
+**层级:**
+
+1. **第 1 层（静默）:** 安全、可逆、仅框架操作
+2. **第 2 层（提示）:** 中等风险，需要用户确认
+3. **第 3 层（手动指南）:** 高风险，仅提供说明
+
+**理由:**
+
+- Terraform 模式：明确的 plan vs apply 分离
+- npm 模式：完整性检查 + 用户控制的恢复
+- VS Code 模式：安全的自动更新，危险的阻止
+- Git 模式：始终保留历史（reflog）
+
+**安全规则:**
+
+- 永不修改用户源代码
+- 永不触及凭据/secrets
+- 修改前始终创建备份
+- 永不推送到远程仓库
+
+**拒绝的替代方案:**
+
+- 两层（自动/手动）：缺少中等风险的中间地带
+- 无自动修复：失去无摩擦修复的机会
+- 激进自动修复：太危险，可能导致数据丢失
+
+#### 4. 仪表板集成: 共享组件
+
+**决策:** 创建扩展 Story 3.11 质量仪表板的共享组件库。
+
+**理由:**
+
+- DRY 原则：复用现有 Chart.js、Tailwind 设置
+- 一致 UX：仪表板间相同的视觉语言
+- 更快开发：不重建公共组件
+
+**集成结构:**
+
+```
+tools/
+├── shared-dashboard/     # 共享组件
+│   ├── components/
+│   │   ├── Card.jsx
+│   │   ├── Chart.jsx
+│   │   └── StatusBadge.jsx
+│   ├── hooks/
+│   │   ├── useMetrics.js
+│   │   └── useRealTime.js
+│   └── styles/
+│       └── tailwind-preset.js
+├── quality-dashboard/    # Story 3.11
+│   └── (扩展 shared)
+└── health-dashboard/     # HCS 仪表板
+    └── (扩展 shared)
+```
+
+**拒绝的替代方案:**
+
+- 复制组件：维护负担，不一致
+- 单体仪表板：太复杂，更新周期不同
+- 外部库：对内部工具过度
+
+#### 5. 检查优先级: 快速失败策略
+
+**决策:** 先执行 CRITICAL 检查，快速模式下关键失败时停止。
+
+**理由:**
+
+- Kubernetes 探针模式：liveness 问题快速失败
+- 性能优化：基础检查失败时不执行昂贵检查
+- 用户体验：阻塞问题快速反馈
+
+**执行顺序:**
+
+1. CRITICAL 检查（尽可能并行）
+2. HIGH 检查
+3. MEDIUM 检查
+4. LOW 检查
+5. INFO 检查（永不失败）
+
+**拒绝的替代方案:**
+
+- 始终全部执行：基础检查损坏时浪费时间
+- 随机顺序：体验不一致
+- 字母顺序：无逻辑优先级
+
+---
+
+## 后果
+
+### 正面
+
+1. **用户控制:** 手动优先方法尊重开发者工作流
+2. **安全:** 三层修复防止意外损坏
+3. **性能:** 并行执行和缓存满足时间目标
+4. **可扩展性:** 自定义 YAML 检查允许项目特定需求
+5. **可维护性:** 共享仪表板组件减少重复
+6. **行业对齐:** 遵循 Kubernetes、Terraform、npm 的成熟模式
+
+### 负面
+
+1. **初始复杂性:** 混合架构需要更多初始设置
+2. **文档负担:** 三层修复需要清晰文档
+3. **自定义检查学习曲线:** 团队需要学习检查 YAML 格式
+4. **仪表板依赖:** 健康仪表板阻塞于 Story 3.11 完成
+
+### 风险
+
+| 风险 | 概率 | 影响 | 缓解 |
+| --- | --- | --- | --- |
+| 自动修复造成损坏 | 低 | 高 | 严格黑名单，强制备份 |
+| 性能目标未达成 | 中 | 中 | 激进缓存，并行执行 |
+| 自定义检查太复杂 | 低 | 低 | 提供示例，限制检查类型 |
+| 仪表板范围蔓延 | 中 | 中 | 严格的共享组件边界 |
+
+---
+
+## 实施计划
+
+### 第 1 阶段: 核心引擎 (HCS-2, 5h)
+
+- 带并行执行的 HealthCheckEngine
+- 5 个域中的 33 个核心检查
+- 结果聚合和评分
+
+### 第 2 阶段: 自动修复 (HCS-2, 4h)
+
+- 备份管理器
+- 第 1、2、3 层 Healers
+- 修复日志持久化
+
+### 第 3 阶段: 报告 (HCS-2, 3h)
+
+- Markdown 报告生成器
+- 仪表板 JSON 导出
+- 控制台摘要输出
+
+### 第 4 阶段: 仪表板 (HCS-2, 4h)
+
+- 从 Story 3.11 提取共享组件
+- 健康特定组件（DomainCard、HealthScore）
+- 仪表板集成
+
+### 第 5 阶段: CI 集成 (HCS-3, 未来)
+
+- GitHub Actions 工作流
+- 定时健康监控
+- Slack/email 通知
+
+---
+
+## 考虑的替代方案
+
+### 替代方案 1: 基于 Pre-commit Hook
+
+**描述:** 通过 pre-commit hook 在每次提交时运行健康检查。
+
+**优点:**
+
+- 立即捕获问题
+- 在整个团队强制执行标准
+
+**缺点:**
+
+- 每次提交 10-30 秒延迟
+- 开发者用 `--no-verify` 跳过
+- 造成工作流摩擦
+
+**结论:** 拒绝 - 摩擦太大
+
+### 替代方案 2: 纯插件架构
+
+**描述:** 所有检查作为可加载插件（如 ESLint 规则）。
+
+**优点:**
+
+- 最大可扩展性
+- 易于添加/移除检查
+- 第三方检查生态系统
+
+**缺点:**
+
+- 对当前需求过度工程化
+- 插件兼容性问题
+- 更大维护负担
+
+**结论:** 拒绝 - 过度工程化
+
+### 替代方案 3: 仅实时 IDE 集成
+
+**描述:** 健康检查仅作为 IDE 扩展/后台进程运行。
+
+**优点:**
+
+- 实时反馈
+- 无需手动命令
+
+**缺点:**
+
+- 跨 IDE 实现复杂
+- 性能影响问题
+- 无 CI 集成
+- 不是所有开发者都用支持的 IDE
+
+**结论:** 拒绝 - 太有限，复杂
+
+### 替代方案 4: 外部工具 (doctor.js)
+
+**描述:** 使用现有开源健康检查框架。
+
+**优点:**
+
+- 无需开发
+- 社区支持
+
+**缺点:**
+
+- 无 AIOX 特定检查
+- 有限的自动修复能力
+- 对外部项目的依赖
+
+**结论:** 拒绝 - 不满足 AIOX 特定需求
+
+---
+
+## 参考
+
+### 行业研究来源
+
+1. **Kubernetes 健康探针**
+   - [Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/)
+   - 关键洞察：区分"活着"和"准备好服务"
+
+2. **Terraform 漂移检测**
+   - [Detecting and Managing Drift](https://developer.hashicorp.com/terraform/tutorials/state/resource-drift)
+   - 关键洞察：分离检测和修复
+
+3. **VS Code 扩展健康**
+   - [Extension Bisect](https://code.visualstudio.com/blogs/2021/02/16/extension-bisect)
+   - 关键洞察：隔离防止级联失败
+
+4. **npm/yarn 完整性**
+   - [Lockfile Integrity](https://medium.com/node-js-cybersecurity/lockfile-poisoning-and-how-hashes-verify-integrity-in-node-js-lockfiles)
+   - 关键洞察：加密验证 + 用户控制的恢复
+
+5. **CLI Doctor 模式**
+   - [Flutter Doctor](https://quickcoder.org/flutter-doctor/)
+   - [WP-CLI Doctor](https://github.com/wp-cli/doctor-command)
+   - 关键洞察：分类输出 + 可操作修复
+
+### 内部参考
+
+- [编码标准](../../framework/coding-standards.md)
+
+---
+
+## 决策记录
+
+| 日期 | 决策 | 作者 |
+| --- | --- | --- |
+| 2025-12-30 | 初始架构提案 | @architect 通过 @dev |
+
+---
+
+## 附录: 架构图
+
+### 系统概览
+
+```mermaid
+flowchart TB
+    subgraph User["用户交互"]
+        CLI["*health-check 命令"]
+        Dashboard["健康仪表板"]
+    end
+
+    subgraph Engine["健康检查引擎"]
+        Runner["检查执行器"]
+        Cache["结果缓存"]
+        Parallel["并行执行器"]
+    end
+
+    subgraph Checks["检查域"]
+        PC["项目一致性"]
+        LE["本地环境"]
+        RH["仓库健康"]
+        DE["部署"]
+        SI["服务"]
+    end
+
+    subgraph Healing["自动修复"]
+        T1["第 1 层: 静默"]
+        T2["第 2 层: 提示"]
+        T3["第 3 层: 手动指南"]
+        Backup["备份管理器"]
+    end
+
+    subgraph Output["输出"]
+        Report["Markdown 报告"]
+        JSON["JSON 导出"]
+        Console["控制台输出"]
+    end
+
+    CLI --> Runner
+    Runner --> Parallel
+    Parallel --> PC & LE & RH & DE & SI
+    PC & LE & RH & DE & SI --> Cache
+    Cache --> T1 & T2 & T3
+    T1 & T2 --> Backup
+    T1 & T2 & T3 --> Report & JSON & Console
+    JSON --> Dashboard
+```
+
+### 自动修复流程
+
+```mermaid
+flowchart TD
+    Issue["检测到问题"] --> Classify{"分类严重性"}
+
+    Classify -->|微小且可逆| T1["第 1 层: 静默修复"]
+    Classify -->|中等风险| T2["第 2 层: 提示用户"]
+    Classify -->|高风险/复杂| T3["第 3 层: 手动指南"]
+
+    T1 --> Backup["创建备份"]
+    T2 --> Confirm{"用户确认?"}
+
+    Backup --> Apply["应用修复"]
+    Confirm -->|是| Backup
+    Confirm -->|否| Skip["跳过"]
+
+    Apply --> Verify{"修复成功?"}
+    Verify -->|是| Log["记录成功"]
+    Verify -->|否| Rollback["从备份回滚"]
+
+    T3 --> Guide["显示说明"]
+    Guide --> UserAction["用户采取行动"]
+
+    Rollback --> Fail["报告失败"]
+```
+
+### 检查执行
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant CLI
+    participant Engine as 引擎
+    participant Cache as 缓存
+    participant Checks as 检查
+    participant Healer as 修复器
+    participant Reporter as 报告器
+
+    User->>CLI: *health-check --mode=quick
+    CLI->>Engine: run(mode='quick')
+
+    Engine->>Cache: 检查缓存
+    Cache-->>Engine: 缓存结果（如有）
+
+    Engine->>Checks: 执行 CRITICAL 检查（并行）
+    Checks-->>Engine: 结果
+
+    alt 关键失败
+        Engine->>Reporter: 生成错误报告
+        Reporter-->>User: 显示错误
+    else 所有关键通过
+        Engine->>Checks: 执行 HIGH 检查（并行）
+        Checks-->>Engine: 结果
+
+        Engine->>Healer: 应用第 1 层修复
+        Healer-->>Engine: 修复结果
+
+        Engine->>Reporter: 生成报告
+        Reporter-->>User: 显示摘要
+    end
+```
+
+---
+
+_此 ADR 作为 Story HCS-1 调研的一部分创建_

package/docs/zh/architecture/adr/adr-isolated-vm-decision.md

@@ -0,0 +1,70 @@
+<!-- 翻译: zh-CN | 原文: /docs/architecture/adr/adr-isolated-vm-decision.md | 同步日期: 2026-02-22 -->
+
+# ADR: isolated-vm 与 macOS 兼容性
+
+**状态:** 已取代
+**日期:** 2026-01-04
+**更新:** 2026-01-27
+**Story:** TD-6 - CI 稳定性和测试覆盖率改进
+**作者:** @devops (Gage)
+**取代者:** 移除依赖 (v3.11.0)
+
+## 更新 (2026-01-27)
+
+**决策已更改:** `isolated-vm` 已从依赖中**完全移除**。
+
+### 移除原因
+
+经过代码分析，我们发现 `isolated-vm` 实际上从未在代码库中使用。它是作为未来沙箱代码执行的占位符添加的，但从未实现。
+
+### 移除的好处
+
+1. **完全兼容 Node.js 18-24** 在所有平台（macOS、Linux、Windows）
+2. **依赖树减少 43 个包**
+3. **减少 6 个漏洞**（8 → 2）
+4. **不再有原生模块编译问题**
+5. **100% CI 矩阵覆盖**（12 种组合：3 个操作系统 × 4 个 Node 版本）
+
+### 更新的依赖
+
+| 包 | 之前 | 之后 | 最低 Node.js |
+| --- | --- | --- | --- |
+| `isolated-vm` | ^5.0.4 | **已移除** | N/A |
+| `commander` | ^14.0.1 | ^12.1.0 | >=18 |
+| `glob` | ^11.0.3 | ^10.4.4 | 14, 16, 18, 20, 22+ |
+
+---
+
+## 原始背景（历史记录）
+
+在 CI 测试期间，我们观察到使用 `isolated-vm` 时 macOS 上 Node.js 18.x 和 20.x 出现 SIGSEGV 崩溃。这影响了 CI 矩阵覆盖。
+
+## 原始调查发现
+
+### 受影响的配置
+
+| 平台 | Node 版本 | 状态 |
+| --- | --- | --- |
+| macOS ARM64 | 18.x | SIGSEGV 崩溃 |
+| macOS ARM64 | 20.x | SIGSEGV 崩溃 |
+| macOS ARM64 | 22.x | 正常 |
+| macOS x64 | 所有 | 正常 |
+| Ubuntu | 所有 | 正常 |
+| Windows | 所有 | 正常 |
+
+### 根本原因
+
+**GitHub Issue:** [laverdet/isolated-vm#424](https://github.com/laverdet/isolated-vm/issues/424) - "Segmentation fault on Node 20 macos arm64"
+
+问题是 `isolated-vm` 的原生绑定与 macOS 上 18.x 和 20.x 版本的 Node.js ARM64 构建之间存在已知的不兼容性。
+
+## 原始决策（现已取代）
+
+**保持当前 CI 矩阵排除** macOS + Node 18/20。
+
+此决策已被完全移除项目依赖中的 `isolated-vm` 所取代。
+
+## 参考
+
+- [isolated-vm#424 - Segmentation fault on Node 20 macos arm64](https://github.com/laverdet/isolated-vm/issues/424)
+- [isolated-vm releases](https://github.com/laverdet/isolated-vm/releases)