diff --git a/BUILD.md b/BUILD.md index 66ff8b6..2330220 100644 --- a/BUILD.md +++ b/BUILD.md @@ -281,6 +281,168 @@ bun run dev # 启动开发服务器，支持热重载 --- +--- + +## 🍎 macOS 构建 + +### 前提条件 + +| 工具 | 版本要求 | 安装方式 | +|------|---------|---------| +| **Bun** | >= 1.0 | `curl -fsSL https://bun.sh/install \| bash` | +| **Rust** | >= 1.80 | [https://rustup.rs/](https://rustup.rs/) | +| **Xcode Command Line Tools** | 最新 | `xcode-select --install` | + +### 验证环境 + +```bash +bun --version # 应显示 1.x.x +rustc --version # 应显示 1.80+ 或更高 +xcode-select -p # 应返回开发者工具路径 +``` + +### 编译步骤 + +#### 第 1 步：克隆仓库 + +```bash +git clone https://github.com/OpenAisec/Miko.git +cd Miko +``` + +#### 第 2 步：安装依赖 + +```bash +# 根目录 +bun install + +# Desktop +cd desktop +bun install + +# Adapters +cd ../adapters +bun install + +# 返回根目录 +cd .. +``` + +#### 第 3 步：执行打包脚本 + +```bash +cd desktop +./scripts/build-macos-arm64.sh +``` + +**预计耗时**：10-30 分钟（首次编译会下载 Rust 依赖） + +> **注意**：此脚本仅支持 Apple Silicon (arm64) 主机。如需 Intel (x64) 版本，请使用 CI 构建。 + +### 产物位置 + +编译成功后，产物位于： + +``` +desktop/build-artifacts/macos-arm64/ +``` + +该目录包含： +- `kimo.app` - macOS 应用包（已内置 agents/skills/tools） +- `kimo.dmg` - DMG 安装镜像 +- `BUILD_INFO.txt` - 构建信息 + +### 应用包内部结构 + +``` +kimo.app/ + Contents/ + MacOS/ + kimo # 主程序 + claude-sidecar # CLI/Server 组件 + CLAUDE_CONFIG_DIR/ # 便携数据目录（自动创建） + app-mode.json # 便携模式标识 + data/ + agents/ # 8 个预置 Agent + skills/ # 内置技能库 + tools/ # 安全工具 + YAML 配置 + Resources/ + dist/ # 前端静态资源 + icon.icns # 应用图标 +``` + +### 安装与测试 + +**方式一：DMG 安装（推荐）** + +1. 双击 `kimo.dmg` +2. 将 `kimo.app` 拖入 `Applications` 文件夹 +3. 从 Launchpad 或 Applications 启动 + +**方式二：直接运行** + +```bash +open desktop/build-artifacts/macos-arm64/kimo.app +``` + +> 首次启动如果提示"无法验证开发者"，前往 **系统设置 → 隐私与安全性**，点击"仍要打开"。 + +### 环境变量 + +| 变量 | 说明 | +|------|------| +| `SKIP_INSTALL=1` | 跳过 `bun install`（复用已安装依赖） | +| `SIGN_BUILD=1` | 启用签名构建（需要 Apple Developer 证书） | +| `PRESERVE_TAURI_TARGET=1` | 保留 Rust 编译缓存（增量构建更快） | +| `OPEN_OUTPUT=1` | 构建完成后在 Finder 中打开产物目录 | + +### macOS 常见问题 + +#### 问题 1：`xcode-select: error: command line tools are not installed` + +```bash +xcode-select --install +``` + +#### 问题 2：`error: failed to run custom build command (tauri-build)` + +**原因**：Xcode Command Line Tools 未安装或过期。 + +```bash +sudo rm -rf /Library/Developer/CommandLineTools +xcode-select --install +``` + +#### 问题 3：`codesign` 失败或 `command not found` + +确保 Xcode CLT 已安装： + +```bash +xcode-select -p +# 如果返回为空，执行： +xcode-select --install +``` + +#### 问题 4：`error: linking with cc failed` + +安装 Xcode 完整版或确保 CLT 的 C/C++ 工具链可用： + +```bash +sudo xcode-select --switch /Library/Developer/CommandLineTools +``` + +#### 问题 5：DMG 打开后应用闪退 + +macOS 对未签名应用有安全限制。执行： + +```bash +xattr -cr /Applications/kimo.app +``` + +或者前往 **系统设置 → 隐私与安全性**，允许运行。 + +--- + ## 📞 获取帮助 - **Issue 反馈**：https://github.com/OpenAisec/Miko/issues @@ -288,5 +450,5 @@ bun run dev # 启动开发服务器，支持热重载 编译遇到问题时，请附上： 1. 完整的错误日志 -2. 操作系统版本（`winver` 查看） +2. 操作系统版本（`winver` / `sw_vers` 查看） 3. 工具版本（`bun --version`、`rustc --version`） diff --git a/README.md b/README.md index d81853f..7d03c13 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,9 @@ 基于**黑板机制**实现多轮探测记忆，通过**探索模式**持续深挖目标，以**专注力系统**确保每个发现都被充分覆盖分析。**探索覆盖面清晰可见**，你可以随时指挥 Agent 横向扩展攻击面或纵向深度挖掘单点突破。支持**一键会话转项目**，让临时测试无缝演进为完整渗透项目。

- 下载便携版 + 下载 Windows 便携版 +   + 下载 macOS DMG   编译指南

@@ -44,12 +46,20 @@ ## 🚀 快速开始 -### 下载便携版（推荐） +### Windows 便携版（推荐） 1. 前往 [Releases](https://github.com/OpenAisec/Miko/releases) 下载最新版 `Miko-portable-win-x64.zip` 2. 解压到任意**可写目录**（避免 C:\Program Files） 3. 双击 `miko.exe` 启动 +### macOS DMG + +1. 前往 [Releases](https://github.com/OpenAisec/Miko/releases) 下载最新版 `kimo.dmg` +2. 双击打开 DMG，将 `kimo.app` 拖入 `Applications` +3. 从 Launchpad 或 Applications 启动 + +> 首次启动如果提示"无法验证开发者"，前往 **系统设置 → 隐私与安全性**，点击"仍要打开"。 + ### 首次配置 1. 打开设置 → API Keys @@ -87,8 +97,9 @@ - [Bun](https://bun.sh/) >= 1.0 - [Rust](https://www.rust-lang.org/) (cargo >= 1.80) - Windows: Visual Studio 2022 含 C++ 桌面开发工作负载 +- macOS: Xcode Command Line Tools (`xcode-select --install`) -#### 编译步骤 +#### Windows 编译 ```powershell # 克隆仓库 @@ -115,6 +126,25 @@ cd ..\desktop # desktop\build-artifacts\portable-win-x64\ ``` +#### macOS 编译 + +```bash +# 克隆仓库 +git clone https://github.com/OpenAisec/Miko.git +cd Miko + +# 安装依赖 +bun install +cd desktop && bun install && cd ../adapters && bun install && cd .. + +# 打包（仅支持 Apple Silicon） +cd desktop +./scripts/build-macos-arm64.sh + +# 产物位置 +# desktop/build-artifacts/macos-arm64/ +``` + ### 其他平台 - **MSI 安装包**: `.\scripts\build-windows-x64.ps1` diff --git a/desktop/scripts/build-macos-arm64.sh b/desktop/scripts/build-macos-arm64.sh index 2c37dc3..26feec5 100644 --- a/desktop/scripts/build-macos-arm64.sh +++ b/desktop/scripts/build-macos-arm64.sh @@ -281,7 +281,82 @@ sign_canonical_app_bundle() { codesign --verify --deep --strict --verbose=2 "${app_bundle}" } +# ── 预置 agents / skills / tools 到 .app 内部 ─────────────── +# 与 Windows 便携版 (build-portable-win.ps1) 的预置逻辑对齐： +# 在 .app/Contents/MacOS/ 下创建 CLAUDE_CONFIG_DIR/data/{agents,skills,tools}， +# 并写入 app-mode.json(mode=portable)，让 determine_startup_portable_dir 命中便携模式。 +# 这样新装的 macOS 用户开箱即有 agents 和 skills，无需手动复制。 +preseed_portable_data() { + local app_bundle="$1" + local app_exe_dir="${app_bundle}/Contents/MacOS" + local portable_cfg="${app_exe_dir}/CLAUDE_CONFIG_DIR" + local portable_data="${portable_cfg}/data" + + echo "[build-macos-arm64] Preseeding portable data into ${app_bundle}..." + + mkdir -p "${portable_data}/agents" "${portable_data}/skills" + + # app-mode.json → 触发 determine_startup_portable_dir 的便携判定 + echo '{"mode":"portable"}' > "${portable_cfg}/app-mode.json" + + # 内置 agents：只拷 protectedResources 白名单内的（与 Windows 脚本对齐） + local builtin_agents=( + 'security-explore' 'Explore' 'Plan' 'general-purpose' + 'verification' 'skill-creator-agent' 'skill-editor' 'statusline-setup' + ) + local agents_src="${REPO_ROOT}/data/agents" + local agents_dst="${portable_data}/agents" + for name in "${builtin_agents[@]}"; do + if [[ -f "${agents_src}/${name}.md" ]]; then + cp -f "${agents_src}/${name}.md" "${agents_dst}/${name}.md" + else + echo "[build-macos-arm64] WARN: agent def missing in source: ${name}.md" + fi + done + + # skills：全量拷（排除两个非真 skill 的产物目录，与 Windows 脚本对齐） + local skills_src="${REPO_ROOT}/data/skills" + local skills_dst="${portable_data}/skills" + local skill_exclude=('code-audit-workspace' 'php-deep-audit-workspace') + if [[ ! -d "${skills_src}" ]]; then + echo "[build-macos-arm64] ERROR: source skills dir missing: ${skills_src}" >&2 + exit 1 + fi + local skill_count=0 + for d in "${skills_src}"/*/; do + local dname + dname="$(basename "${d}")" + local skip=0 + for ex in "${skill_exclude[@]}"; do + if [[ "${dname}" == "${ex}" ]]; then skip=1; break; fi + done + if [[ ${skip} -eq 0 ]]; then + if [[ -f "${d}SKILL.md" ]]; then + cp -R "${d}" "${skills_dst}/${dname}" + ((skill_count++)) + else + echo "[build-macos-arm64] WARN: skipping skill without SKILL.md: ${dname}" + fi + fi + done + if [[ ${skill_count} -eq 0 ]]; then + echo "[build-macos-arm64] ERROR: no skills were copied from ${skills_src}" >&2 + exit 1 + fi + echo "[build-macos-arm64] Preseeded ${skill_count} skills, ${#builtin_agents[@]} agents" + + # tools：整目录拷（yaml + bin/darwin 二进制） + local tools_src="${REPO_ROOT}/data/tools" + if [[ -d "${tools_src}" ]]; then + cp -R "${tools_src}" "${portable_data}/tools" + echo "[build-macos-arm64] Preseeded tools catalog + binaries" + fi +} + if [[ -n "${LATEST_APP}" ]]; then + # 预置 agents/skills/tools 到 .app 内部（在签名前完成，签名会封印整个 bundle） + preseed_portable_data "${LATEST_APP}" + # Normalize the Tauri-produced app in place before copying it anywhere. # Without this, opening target/.../bundle/macos/Claude Code Haha.app directly # uses the executable's ad-hoc signing identifier instead of the app bundle id,