docs: merge 运行要求 + 快速开始 + 安装方式 into one 快速开始 section
This commit is contained in:
Kellyvv committed
1 parent
696bafaf73
commit
316c0e6f62
1 file changed
+23
-92
@@ -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`：
|
||||
|
||||
Reference in new issue
Block a user