feat: macOS 构建支持 — agents/skills 预置 + 文档完善

BUILD.md

@@ -281,12 +281,174 @@ 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
 - **讨论区**：https://github.com/OpenAisec/Miko/discussions
 
 编译遇到问题时，请附上：
 1. 完整的错误日志
-2. 操作系统版本（`winver` 查看）
+2. 操作系统版本（`winver` / `sw_vers` 查看）
 3. 工具版本（`bun --version`、`rustc --version`）

README.md

@@ -9,7 +9,9 @@
 基于**黑板机制**实现多轮探测记忆，通过**探索模式**持续深挖目标，以**专注力系统**确保每个发现都被充分覆盖分析。**探索覆盖面清晰可见**，你可以随时指挥 Agent 横向扩展攻击面或纵向深度挖掘单点突破。支持**一键会话转项目**，让临时测试无缝演进为完整渗透项目。
 
 <p align="center">
-  <a href="https://github.com/OpenAisec/Miko/releases"><img src="https://img.shields.io/badge/⬇_下载便携版-Windows-FF7A00?style=for-the-badge" alt="下载便携版"></a>
+  <a href="https://github.com/OpenAisec/Miko/releases"><img src="https://img.shields.io/badge/⬇_下载便携版-Windows-FF7A00?style=for-the-badge" alt="下载 Windows 便携版"></a>
+  &nbsp;
+  <a href="https://github.com/OpenAisec/Miko/releases"><img src="https://img.shields.io/badge/⬇_下载DMG-macOS-FF7A00?style=for-the-badge" alt="下载 macOS DMG"></a>
   &nbsp;
   <a href="BUILD.md"><img src="https://img.shields.io/badge/📖_编译指南-Guide-gray?style=for-the-badge" alt="编译指南"></a>
 </p>
@@ -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`

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,