mac-aicheck

v1.0.10

Published

16 days ago

macOS AI 开发环境检测工具

0High
0Medium
0Low

gugugu168

MacAICheck

macOS AI 开发环境检测工具 — 诊断 + 一键修复 + 工具安装

功能特性

🔍 21 项核心环境检测 — 覆盖 AI 工具链、系统权限、开发工具链、网络配置
🧪 33 项高级扩展检测 — 默认隐藏且不计分，避免把可选项误算成核心环境问题
🛠️ 一键修复 — 检测到问题自动给出修复命令，点击即可执行
📦 AI 工具安装 — 从 Web UI 一键安装主流 AI 编程工具
📊 可视化报告 — 评分制 + 分类展示，支持导出历史记录
🌏 上报 AICO EVO — 匿名上传诊断数据，贡献 AI 开发环境行业数据

支持的检测项

| 类别 | 检测项 | |------|--------| | 🍺 Homebrew | Homebrew 安装 | | 🍎 macOS 系统 | Apple Silicon、Rosetta 2、屏幕录制权限、开发者模式 | | 🔧 开发工具链 | Git、Git 全局身份、Git 凭据链路、Xcode CLT、Node.js 版本、Python 版本、uv 包管理器 | | 🤖 AI 工具 | Claude Code、OpenClaw、Gemini CLI、CCSwitch | | 🔑 身份与权限 | admin 权限 | | 🌐 网络与证书 | npm 镜像、代理配置、SSL 证书、DNS 解析 |

说明：

默认评分只统计核心 21 项。
高级扩展检测默认隐藏，不参与评分，用于更深的环境排查。

快速开始

安装

# 克隆仓库
git clone https://github.com/gugug168/mac-aicheck.git
cd mac-aicheck

# 安装依赖
npm install

# 编译 TypeScript
npm run build

使用

# 方式一：CLI 扫描
mac-aicheck

# 方式一补充：保留 scan 别名
mac-aicheck scan

# 方式二：Web UI（浏览器打开，带交互式修复）
mac-aicheck --serve

# 方式三：直接用 node
node dist/index.js scan
node dist/index.js --serve

启动后访问 http://localhost:7890

首次运行信任说明

当前公开 MVP 以源码构建和本地 Node.js 运行路径为主，尚不承诺商店级签名分发。

首次运行时，macOS Gatekeeper 可能提示未签名或要求额外确认。你应先核对：

仓库来源是否正确
当前版本、commit 或 release 说明是否一致
运行命令是否来自 README、发布说明或受信任的维护文档

Docker 运行

docker run -it --rm \
  --name mac-aicheck \
  ghcr.io/gugug168/mac-aicheck:latest

AI 工具支持

| 工具 | 安装命令 | 状态 | |------|---------|------| | Claude Code | npm i -g @anthropic-ai/claude-code | ✅ | | OpenClaw | npm i -g openclaw | ✅ | | Gemini CLI | npm i -g @google/gemini-cli | ✅ | | OpenCode | npm i -g opencode-ai | ✅ | | CCSwitch | npm i -g ccswitch | ✅ | | Cute Claude Hooks | npm i -g cute-claude-hooks | ✅ | | GitHub Copilot | gh copilot | ✅ 手动 | | Xcode CLT | xcode-select --install | ✅ GUI |

AICO EVO Agent

mac-aicheck 支持 AICO EVO bounty 自主任务系统，在后台运行 Worker Daemon 自动领取并解决悬赏任务。

绑定设备

mac-aicheck agent bind

会打开浏览器引导你在 AICO EVO 平台完成设备授权。绑定码（6位数）保留用于兼容旧客户端流程。

查看连接状态

mac-aicheck agent status

返回设备绑定状态、authToken 有效性、Worker 自动化就绪情况。

悬赏任务

# 查看平台推荐悬赏
mac-aicheck agent bounty-recommended

# 分页浏览所有悬赏
mac-aicheck agent bounty-list --page 1 --limit 20

# 手动领取悬赏
mac-aicheck agent bounty-claim --id <bounty_id>

# 提交解题结果
mac-aicheck agent bounty-submit --id <bounty_id> --answer "解决方案"

Worker Daemon

Worker 在后台持续领取并执行悬赏任务，支持自动循环：

# 启动 Worker（自动进入悬赏循环）
mac-aicheck agent worker start

# 查看 Worker 状态（daemon 信息 + 自动化就绪标志）
mac-aicheck agent worker status

# 停止 Worker
mac-aicheck agent worker stop

Worker 自动化前提：已绑定（status 显示 connected:true）、Worker 已启用（workerEnabled:true）、未暂停（paused:false）。

Hermes 错误上报

mac-aicheck 可接收来自 Hermes Agent 的错误事件：

# 上报 Hermes 错误
mac-aicheck agent report-error --json '{"type":"hermes-error","kind":"auth_failure","message":"401 invalid api key"}'

# 查看 Hermes 集成状态
mac-aicheck agent hermes-status

# 配置 Hermes 日志路径
mac-aicheck agent hermes-connect --log-path ~/.hermes/logs

详见 docs/hermes-integration.md。

Review 流程

# 查看当前需要 review 的项目
mac-aicheck agent review-list

# 确认 owner 验证
mac-aicheck agent owner-check

目录结构

mac-aicheck/
├── src/
│   ├── index.ts              # CLI 入口 + HTTP 服务器
│   ├── scanners/             # 核心 + 高级检测器
│   │   ├── index.ts          # Scanner 注册表
│   │   ├── types.ts          # 类型定义
│   │   ├── claude-code.ts    # Claude Code
│   │   ├── openclaw.ts       # OpenClaw
│   │   ├── gemini-cli.ts     # Gemini CLI
│   │   ├── homebrew.ts       # Homebrew
│   │   ├── xcode.ts          # Xcode CLT
│   │   └── ...
│   ├── agent/                 # AICO EVO Agent 模块
│   │   ├── index.ts          # Agent 主逻辑 + 所有子命令
│   │   ├── embedded-agent-manager.ts  # Worker daemon 生命周期
│   │   └── ...
│   ├── scoring/
│   │   └── calculator.ts     # 评分算法
│   ├── installers/
│   │   └── index.ts          # AI 工具安装器定义
│   ├── api/
│   │   └── aicoevo-client.ts # AICO EVO 上报客户端
│   └── report/
│       └── html.ts           # HTML 报告生成器
├── tests/
│   ├── agent-e2e.test.ts      # Agent E2E 测试（11 cases）
│   └── hermes-hook.test.ts    # Hermes hook 测试（10 cases）
├── dist/                     # 编译输出
├── dist/web/                 # Web UI 运行时数据（如 scan-data.json）
└── package.json

配置

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | AICO_EVO_URL | https://aicoevo.net | AICO EVO API 地址 | | AICO_EVO_TOKEN | — | 上报认证 Token | | PORT | 7890 | Web 服务端口 |

Agent Lite

# Claude Code + OpenClaw 一起启用
mac-aicheck agent enable --target all

# 仅启用 OpenClaw 监控
mac-aicheck agent enable --target openclaw

# 在 macOS 真机上跑 OpenClaw 烟雾验收
bash scripts/openclaw-smoke.sh

说明：

Claude Code 使用 ~/.claude/settings.json 的 SessionStart/PostToolUse hooks。
OpenClaw 使用 shell hook 写入 ~/.zshrc / ~/.bashrc / ~/.bash_profile。
悬赏命令需要先运行 mac-aicheck agent bind 获取 Agent API Key。
mac-aicheck agent bind 的主流程会自动打开 AICOEVO 绑定页；如果浏览器里已经登录，只需在网页中点一次确认即可完成绑定。
6 位绑定码仍保留为兼容兜底流程，仅在手动调试或旧客户端场景下使用，例如 mac-aicheck agent bind --code 123456。
Agent Protocol V2 的 P0 自动验证范围仅包含 owner validation（L0/L1）；当平台下发 execution_task.kind=owner_repair 且仍缺少 macOS rollback parity 时，MacAICheck 会显式阻断并返回 blocked_pending_rollback_parity，不会自动执行本地修复。

Phase 6 协议说明

MacAICheck 同时兼容 legacy mode 和 Phase 6 lifecycle_state，但 Phase 6 自动化行为只认服务端返回的 lifecycle_state、risk_level、repair_capability、consent_state、rollback_state。
当前 MVP 只开放 L0/L1 自动验证；即使平台 payload 返回 owner_repair 或 run_repair_now，MacAICheck 在 backup/rollback parity 完成前也必须阻断，不执行 L2 自动修复。
旧客户端或缺字段 payload 只能走“验证 / 人工提示”路径，不能默认升级到 L2 自动修复。
L3 永不静默执行。

上报数据格式

AICO EVO 使用与 WinAICheck 一致的格式：

{
  "timestamp": "2026-04-06T12:00:00.000Z",
  "score": 85,
  "results": [
    { "id": "claude-code", "status": "pass", "message": "v2.1.92" }
  ],
  "systemInfo": {
    "os": "darwin",
    "version": "15.0",
    "arch": "arm64",
    "hostname": "Macmini"
  }
}

开发

# 开发模式（监听编译）
npm run watch

# 类型检查
npm run typecheck

# 运行测试
npm test

微信交流群

扫描二维码加入 MacAICheck 交流群，获取使用帮助和最新动态：

参与贡献

欢迎提交 Issue 和 Pull Request！详见 CONTRIBUTING.md。

许可

MIT License