From 5b020219bf62e44398644e1863a31502433ae696 Mon Sep 17 00:00:00 2001 From: 0x7b Date: Sat, 25 Jul 2026 10:22:17 +0800 Subject: [PATCH] feat: add macOS build support with agents/skills preseeding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add preseed_portable_data() to build-macos-arm64.sh: injects builtin agents, skills, and tools into the .app bundle's CLAUDE_CONFIG_DIR, mirroring the Windows portable build (build-portable-win.ps1) - Update BUILD.md with comprehensive macOS build guide: prerequisites, build steps, output structure, env vars, and troubleshooting - Update README.md: add macOS DMG download badge, macOS quick start, and macOS source build instructions The preseeding step runs before code signing so the entire bundle (including injected data) gets sealed. On first launch, determine_startup_portable_dir() detects app-mode.json and enters portable mode automatically — users get agents/skills/tools out of the box without manual setup. --- BUILD.md | 164 ++++++++++++++++++++++++++- README.md | 36 +++++- desktop/scripts/build-macos-arm64.sh | 75 ++++++++++++ 3 files changed, 271 insertions(+), 4 deletions(-) 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,