From 316c0e6f627cb8b268e4757b3798799c7f4df18d Mon Sep 17 00:00:00 2001
From: Kellyvv <noreply@github.com>
Date: Mon, 6 Apr 2026 06:49:38 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20merge=20=E8=BF=90=E8=A1=8C=E8=A6=81?=
 =?UTF-8?q?=E6=B1=82=20+=20=E5=BF=AB=E9=80=9F=E5=BC=80=E5=A7=8B=20+=20?=
 =?UTF-8?q?=E5=AE=89=E8=A3=85=E6=96=B9=E5=BC=8F=20into=20one=20=E5=BF=AB?=
 =?UTF-8?q?=E9=80=9F=E5=BC=80=E5=A7=8B=20section?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 115 +++++++++++-------------------------------------------
 1 file changed, 23 insertions(+), 92 deletions(-)

diff --git a/README.md b/README.md
index 28423c1..a5dbe0b 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
 
 <div align="center">
 
-[核心能力](#核心能力) · [内置 Skill](#内置-skill-示例) · [快速开始](#5-分钟快速开始) · [自定义 Skill](#自定义-skill) · [常见问题](#常见问题) · [后续计划](#后续计划)
+[核心能力](#核心能力) · [内置 Skill](#内置-skill-示例) · [快速开始](#快速开始) · [自定义 Skill](#自定义-skill) · [常见问题](#常见问题) · [后续计划](#后续计划)
 
 </div>
 
@@ -58,21 +58,14 @@ PhoneClaw 是一个运行在 iPhone 上的本地 AI Agent。它使用 Gemma 4 
 > "帮我算一下这段文字的 MD5"
 
 
-## 运行要求
+## 快速开始
 
-- macOS + Xcode 16 或更新版本
-- iOS 17.0 或更新版本
-- CocoaPods
-- 真机调试账号（Apple ID）
-
-模型建议：
+环境要求：macOS + Xcode 16，iOS 17+，CocoaPods，真机 + Apple ID
 
 | 模型 | 适用场景 |
 |------|---------|
-| Gemma 4 E2B | 更稳，更适合默认分发，A16 及以上 |
-| Gemma 4 E4B | 效果更强，但更吃内存，建议 iPhone 15 Pro 及以上 |
-
-## 5 分钟快速开始
+| Gemma 4 E2B | 更稳，适合默认分发，A16 及以上 |
+| Gemma 4 E4B | 效果更强，建议 iPhone 15 Pro 及以上 |
 
 ### 1. 克隆项目
 
@@ -87,61 +80,30 @@ cd phoneclaw
 pod install
 ```
 
-### 3. 可选：预下载模型到本地
+### 3. 选择模型安装方式
 
-默认推荐方式已经变成：
+**方案 A（推荐）— 空壳安装，手机端下载**
 
-1. 先通过 Xcode 把空壳 App 安装到手机
-2. 打开 App
-3. 进入 `模型设置 / Model Settings`
-4. 在手机上直接下载 `Gemma 4 E2B` 或 `Gemma 4 E4B`
+直接用 Xcode 把 App 安装到手机，打开后进入「模型设置」，在手机上直接下载 E2B 或 E4B。默认工程不会把 `Models/` 里的文件打入包，安装包更小，安装更快。
 
-只有你想把模型一起打包进 App 时，才需要在电脑上先下载到 `Models/` 目录。
+**方案 B — 打包 E2B 进 App**
 
-PhoneClaw 识别的目录名必须和下面保持一致。推荐先安装 Hugging Face CLI：
+1. 先在电脑下载模型到 `Models/gemma-4-e2b-it-4bit`（推荐用 Hugging Face CLI）：
 
 ```bash
 brew install hf
-# 或
-pip install -U "huggingface_hub"
-```
-
-只下载 E2B（推荐）：
-```bash
 mkdir -p ./Models/gemma-4-e2b-it-4bit
 hf download mlx-community/gemma-4-e2b-it-4bit --local-dir ./Models/gemma-4-e2b-it-4bit
 ```
 
-只下载 E4B：
-```bash
-mkdir -p ./Models/gemma-4-e4b-it-4bit
-hf download mlx-community/gemma-4-e4b-it-4bit --local-dir ./Models/gemma-4-e4b-it-4bit
-```
+2. 在 Xcode `Build Phases > Copy Bundle Resources` 里手动把模型目录加进去
+3. 修改 `LLM/MLXLocalLLMService.swift` 里的 `availableModels`，只保留要分发的模型
 
-两个都下载：
-```bash
-mkdir -p ./Models/gemma-4-e2b-it-4bit ./Models/gemma-4-e4b-it-4bit
-hf download mlx-community/gemma-4-e2b-it-4bit --local-dir ./Models/gemma-4-e2b-it-4bit
-hf download mlx-community/gemma-4-e4b-it-4bit --local-dir ./Models/gemma-4-e4b-it-4bit
-```
+> E2B 约 3.58 GB，E4B 约 5.22 GB。`Models/` 已在 `.gitignore` 中忽略，不会提交到仓库。
 
-下载完成后目录结构如下：
+**方案 C — 同时打包 E2B + E4B**
 
-```
-Models/
-├── gemma-4-e2b-it-4bit/
-│   ├── config.json
-│   ├── tokenizer.json
-│   ├── processor_config.json
-│   ├── chat_template.jinja
-│   ├── model.safetensors
-│   └── model.safetensors.index.json
-└── gemma-4-e4b-it-4bit/
-```
-
-> `Models/` 已在 `.gitignore` 中忽略，不会被提交到仓库。  
-> Hugging Face 模型页显示的仓库体积：E2B 约 3.58 GB，E4B 约 5.22 GB。  
-> 如果不想用 CLI，也可以直接从模型页面手动下载后放到对应目录。
+同上，两个模型目录都下载，并把两个 folder reference 都加回 `Copy Bundle Resources`。
 
 ### 4. 打开工程
 
@@ -149,27 +111,21 @@ Models/
 open PhoneClaw.xcworkspace
 ```
 
-> 不要打开 `.xcodeproj`，请始终打开 `.xcworkspace`
+> 请始终打开 `.xcworkspace`，不要打开 `.xcodeproj`
 
 ### 5. 配置签名并运行
 
-1. 在 Xcode 中选择 PhoneClaw target
-2. 打开 Signing & Capabilities
-3. 选择你的 Team
-4. 把 Bundle Identifier 改成你自己的唯一值
-5. 连接 iPhone，按 ⌘R
+1. 选择 PhoneClaw target → Signing & Capabilities
+2. 选择 Team，把 Bundle Identifier 改成你自己的唯一值
+3. 连接 iPhone，按 ⌘R
 
-首次安装后，如果系统要求信任开发者证书，请在手机里完成信任：设置 → 通用 → VPN 与设备管理 → 信任
+> 首次安装后如系统提示信任证书：设置 → 通用 → VPN 与设备管理 → 信任
 
 ### 6. 首次使用
 
-打开 App 后：
-
-- 右上角拼图按钮：Skill 管理
-- 右上角滑杆按钮：模型设置 / 系统提示词 / 权限
-- 如果当前是空壳安装，在模型设置页点击 `下载 / Download`
-
-建议先下载一个模型，再在权限页开启日历、提醒事项、通讯录，然后试试：
+- 右上角拼图：Skill 管理
+- 右上角滑杆：模型设置 / 系统提示词 / 权限
+- 空壳安装时，先在模型设置页下载模型，再开启权限，然后试试：
 
 ```
 这台手机的设备信息是什么
@@ -177,31 +133,6 @@ open PhoneClaw.xcworkspace
 帮我存一下王总的电话 13812345678
 ```
 
-## 默认安装方式与模型打包
-
-### 方案 A — 空壳安装，手机端下载模型
-
-这是当前默认推荐方式。
-
-优点：
-
-1. Xcode 安装包更小
-2. 电脑端首次安装更快
-3. 可以在手机里自由切换下载 E2B 或 E4B
-
-默认工程已经不会把 `Models/` 里的模型自动打进 App 包。安装后直接去配置页下载即可。
-
-### 方案 B — 只打包 E2B
-
-1. 保留 `Models/gemma-4-e2b-it-4bit`，移除 `Models/gemma-4-e4b-it-4bit`
-2. 在 Xcode 的 Project Navigator 里删除不用的模型 folder reference，选择 Remove Reference
-3. 在 PhoneClaw > Build Phases > Copy Bundle Resources 里手动把要打包的模型加回去，并确认只剩要分发的模型
-4. 修改 `LLM/MLXLocalLLMService.swift` 里的 `availableModels`，只保留实际会随 App 分发的模型（否则配置页仍然会显示不存在的选项）
-
-### 方案 C — 同时打包 E2B + E4B
-
-保留两个目录，并把两个模型 folder reference 都手动加回 `Copy Bundle Resources`。用户可在 App 的模型设置页里切换。
-
 ## 自定义 Skill
 
 新增一个 Skill 的最小成本方式，是在应用目录里增加一个 `SKILL.md`：