教程 · 2026年11月15日实测
apfel AI 教程
60 秒内从你 Mac 自带的 AI 拿到第一个回答。接着是它擅长的 11 个任务,每个都能直接复制粘贴并附有真实输出,最后坦白列出它做不到的事。
本页内容:共 15 节
60 秒拿到第一个回答
你需要一台 Apple Silicon Mac(M1 或更新机型),运行 macOS 26 Tahoe 或更高版本,并在 系统设置 > Apple Intelligence 与 Siri 中打开 Apple Intelligence。前两项用一行命令就能检查:
sw_vers -productVersion && uname -m
27.0.1
arm64版本号为 26 或更高、架构为 arm64,就说明可以开始了。用 Homebrew 安装 apfel。不需要 Xcode,不需要账号,也不需要 API 密钥:
brew install apfel问出你的第一个问题:
apfel "In one sentence: what can a small on-device language model do for me?"
A small on-device language model can help you perform tasks like text translation, summarization, and data analysis directly on your device.这个回答来自你 Mac 上的 Apple 模型。没有任何数据发往服务器,也没有花一分钱。
如果失败了: 问问 apfel 模型是否就绪:
apfel --model-info | grep -E 'available|context'
├ available: yes
├ context: 4096 tokens如果显示 available: no,请在系统设置中打开 Apple Intelligence,并等待模型下载完成(安装指南说模型有 3 到 4 GB)。Mac 的系统语言和 Siri 语言必须是同一种受支持的语言。模型不可用时,apfel 以退出码 5 退出。
下一步: 看下面的任务。每个任务开头都写明两分钟后你能得到什么。
1. 向你的 Mac 打听它自己
2 分钟后你将拥有: 关于磁盘、CPU 和内存的大白话答案,直接来自你早就熟悉的命令。
当终端命令吐出一大堆数字时,我想要一句话的答案,这样我就能不翻 man 手册直接行动。
把任意命令的输出用管道传给 apfel,再说出你想知道什么:
df -h | apfel "which volume is fullest, one sentence"
/dev/disk3s1 is the fullest volume, with 630Gi used.ps aux | sort -k 3 -nr | head -5 | awk '{print $11, $3"%"}' | apfel "which app is using the most CPU, one sentence"
`/System/Library/CoreServices/RemoteManagement/screensharingd.bundle/Contents/MacOS/screensharingd` is using the most CPU.输入要尽量短:先用 head、awk 和 grep 过滤,再交给 apfel。模型一次只能读几千个词,代码还要更少(见局限)。
如果失败了: 有些命令把内容写到 stderr,而管道不会传递 stderr。apfel 会提示你:piped input was empty - if the command prints to stderr, try: command 2>&1 | apfel。
下一步: 同样的技巧也适用于 git log、lsof、pmset -g batt、日志文件,以及任何输出文本的东西。
2. 修正你复制的任何文本
2 分钟后你将拥有: 一条命令,在任何应用里都能修正剪贴板内容的语法。
当我在 Slack、Mail 或浏览器里随手写了一条消息时,我想要不打开别的应用就把它润色好,这样我就能几秒钟内粘贴回去。
先复制一段文本,然后运行中间那一行。pbpaste 读取剪贴板,pbcopy 把结果写回去:
printf 'can u send me the slides from yesterdays meeting i lost them' | pbcopy
pbpaste | apfel "Rewrite the text above with correct grammar and spelling. Reply with the rewritten text only." | pbcopy
pbpaste
Can you send me the slides from yesterday’s meeting? I lost them.为什么要写“the text above”:apfel 会把管道传入的文本放在前面,你的指令放在后面(源码)。如果用简短的指令 "fix grammar and spelling, reply with the corrected text only",模型会去回复这条消息,而不是修正它,回答是 Could you let me know which meeting you're referring to?。在我们的测试中,明确指出要处理的是哪段文本,问题就解决了。
如果失败了: 发送前先读一遍结果。小模型有时会改变原意:我们让它把这句话翻译成德语时,它把“Can you send me”变成了“Can I send you”。
下一步: 把中间那一行做成 shell 别名,或者放进快捷指令的“运行 Shell 脚本”操作里,再给它配一个键盘快捷键。
3. 读取收据、PDF 和脚本
2 分钟后你将拥有: 关于图片、扫描版 PDF 或脚本的答案,在你的 Mac 上借助 Apple 的文字识别读取。
当下载文件夹里冒出一张收据、一份扫描件或一个陌生文件时,我想要从中拿到我需要的那一条信息,这样我就能不打开它就归档。
用 -f 附加文件。我们做了一张测试用的收据图片(receipt.png),内容如下:
CAFE APFEL
2x Melange 9.80
1x Sachertorte 7.90
1x Apfelstrudel 6.50
TOTAL EUR 24.20
14.11.2026 21:14apfel -f receipt.png "What is the total? Just the amount."
24.20把同一张收据存成纯图片 PDF 也能用,因为 apfel 会对扫描页面做文字识别:
apfel -f receipt.pdf "What is the total? Just the amount."
24.20任何文本文件也都可以,比如一个 shell 脚本:
apfel -f apfel-demos/gitsum "What does this script do? Two sentences."
This script summarizes recent Git activity by summarizing the last N commits, grouping related changes, and generating a concise report. It uses Apple Intelligence to format the output, and optionally copies the summary to the clipboard.这个脚本在第 6 个任务里就能拿到。附加多个文件用 -f a.txt -f b.txt。
如果失败了: 退出码 4 表示文件太长,模型放不下(见局限)。退出码 3 表示被 Apple 的安全过滤器拦截了;文件提取指南建议这种情况下加上 --permissive。
4. 把一句大白话变成 shell 命令
2 分钟后你将拥有: 你怎么也想不起来的那条命令,只输出命令本身,方便直接复制。
当我忘了 find、du 或 tar 的参数时,我想要用一句普通的话换来命令,这样我就能不离开终端。
--code 只输出代码,不带解释:
apfel --code "one find command that lists files larger than 100MB in my home folder"
find /Users/yourusername/home -type f -size +100M参数是对的,但模型编了一个文件夹。你的主文件夹是 ~(这里应为:find ~ -type f -size +100M)。
apfel --code "a python function that removes duplicates from a list but keeps the order"
def remove_duplicates_preserve_order(lst):
seen = set()
result = []
for item in lst:
if item not in seen:
seen.add(item)
result.append(item)
return result每条命令运行前都要先读一遍。 在我们的测试中,模型也给出过错误的命令。要它列出“当前文件夹里最大的 10 个文件”,它输出了 ls -lh | head -n 10,列出的是前 10 个条目,而不是最大的。要它“显示开放的端口”,它建议用 netstat -tuln | grep LISTEN,这用的是 Linux 的参数,在 macOS 上什么也不输出。在 Mac 上,用 lsof -iTCP -sTCP:LISTEN -n -P 才能列出端口。
下一步: 第 6 个任务里的 cmd 演示脚本封装了这个功能,并且在运行任何命令(-x)或复制命令(-c)之前都会先征求你的同意。
5. 拿到脚本可以放心使用的 JSON
2 分钟后你将拥有: 从杂乱文本中提取出的结构化数据,以 JSON 输出,并且始终符合你的 schema。
当我需要从邮件和笔记里提取姓名、数字或日期时,我想要字段而不是成段的文字,这样我就能直接交给 jq、电子表格或脚本。
把一个 JSON Schema 保存为 contact.schema.json:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"city": { "type": "string" },
"phone": { "type": "string" }
},
"required": ["name", "city", "phone"]
}然后用 --schema 通过管道传入文本。apfel 会约束模型,让输出一定是符合该 schema 的合法 JSON:
echo "Hi, I am Maria Lopez from Vienna, call me on +43 660 1234567" | apfel --schema contact.schema.json "Extract the contact" | jq .
{
"name": "Maria Lopez",
"city": "Vienna",
"phone": "+43 660 1234567"
}返回的键按照你在 schema 中声明的顺序排列。
想让任何回答都以带元数据的 JSON 返回,用 -o json:
apfel -o json "Translate to German: apple" | jq -r .content
Apfel处理整份列表用 --batch:每条记录输入一行 JSON,输出一行结果,每条记录都在全新的会话中处理。下面是一个文本文件里的三条商品评价:
cat reviews.txt
Love it, works offline and it is fast.
Crashes every time I open a PDF.
It is okay, it does the job.
jq -Rc '{custom_id: (input_line_number|tostring), prompt: ("Classify the sentiment of this review as positive, negative or neutral. Reply with one word. Review: " + .)}' reviews.txt | apfel --batch | jq -r '"\(.custom_id) \(.status) \(.content)"'
1 ok Positive
2 ok Negative
3 ok Neutral
apfel: batch: 3 records, 3 ok, 0 failedjq -R 把每一行变成一条记录;最后一行是 apfel 输出到 stderr 的汇总。某条记录失败时会得到 status: "error",批处理会继续进行。
如果失败了: apfel 只支持 JSON Schema 的一个子集(对象、字符串、枚举、数字、布尔值、数组、本地 $ref)。遇到不支持的关键字(例如 pattern)时,apfel 以退出码 2 停止并指出该关键字;完整列表见 API 兼容性文档。
6. 让日常自动化:git、语音和现成脚本
2 分钟后你将拥有: 一份最近工作的总结、一台在长任务完成时开口提醒你的 Mac,以及八个现成的 AI shell 脚本。
当我切换任务或等待构建时,我想要一些能解释、能播报的小自动化,这样我就能不用一直盯着终端。
在任意 git 仓库里,总结一下你做了什么:
git log --oneline -10 | apfel "summarize what I have been working on, two sentences"
I've been updating star counts to 6,608 and refining ISO datetimes with timezone handling in the Article JSON-LD. Additionally, I've implemented the apfel AI tutorial and redesigned the pre-header with a centered line about the project.让 Mac 在任务完成时说出来。把回答用管道传给 say,再用 && 把你的长时间命令放在它前面:
apfel "tell me cheerfully that my build just finished, one short sentence, no emoji" | say测试用的 Mac 没有声音输出,所以我们改为把语音录到文件里(| say -o build-done.aiff,102,880 字节的音频)。它说的那句话是 Your build is finished, and I'm glad you asked!。
apfel 还自带八个演示脚本。把它们写入一个文件夹:
apfel --demos
apfel: wrote 9 demo files to /Users/arthurficial/work/apfel-i18n-video-2026-11-15/tut/apfel-demos
• cmd
• explain
• gitsum
• mac-narrator
• naming
• oneliner
• port
• wtd测试中我们比较喜欢的一个:
./apfel-demos/naming "function that retries HTTP requests with exponential backoff"
retryExponentialBackoff | exponential_retry_backoff | exponential delay retry
retryWithExponentialBackoff | exponential_retry_http_backoff | HTTP retry with delay
backoffRetryHTTP | exponential_http_retry | retry with exponential pause并不是每个演示在我们的运行中都表现良好:oneliner "count unique IP addresses in access.log" 撞上了长度限制,输出了一条残缺的命令;explain 则凭空加了一条并不存在的错误信息。演示 README 列出了全部八个脚本。
7. 免费运行你的 OpenAI 代码
2 分钟后你将拥有: 一个支持 OpenAI Chat Completions API 的本地服务器,现有的 SDK 代码可以直接跑在你的 Mac 上,不必再调用付费的云端模型。
当我用 OpenAI SDK 做原型时,我想要一个免费的本地端点,这样我就能在没有密钥、没有账单、不外传数据的情况下开发和测试。
在一个终端标签页里启动服务器:
apfel --serve
apfel server v1.18.0
├ endpoint: http://127.0.0.1:11434
├ model: apple-foundationmodel
├ cors: disabled
├ origin: localhost only (http://127.0.0.1, http://localhost, http://[::1])
├ token: none
├ health: public
├ max concurrent: 5
├ debug: off
└ ready
Endpoints:
POST http://127.0.0.1:11434/v1/chat/completions
GET http://127.0.0.1:11434/v1/models
GET http://127.0.0.1:11434/health
2026-11-15T13:39:31+0100 info Hummingbird: [HummingbirdCore] Server started and listening on 127.0.0.1:11434在第二个标签页里,像调用 OpenAI 一样调用它:
curl -s http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"apple-foundationmodel","messages":[{"role":"user","content":"Say hello to my terminal in five words."}]}' | jq -r '.choices[0].message.content'
Hello, terminal.官方的 OpenAI Python SDK 无需任何改动就能用,只有 base URL 和模型名不同。保存为 hello.py:
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="unused")
reply = client.chat.completions.create(
model="apple-foundationmodel",
messages=[{"role": "user", "content": "Give me three names for a coffee shop run by robots."}],
)
print(reply.choices[0].message.content)python3 -m venv venv && ./venv/bin/pip -q install openai
./venv/bin/python hello.py
1. RoboBrew
2. CogCafé
3. Circuit Sip服务器只监听你自己的 Mac(127.0.0.1),并拒绝来自其他源网页的请求。如果要向局域网开放,请加上 token:apfel --serve --host 0.0.0.0 --token-auto(服务器安全指南)。
如果失败了: Connection refused 表示服务器没有运行。Embeddings 和旧的 /v1/completions 端点会返回 HTTP 501,因为端侧模型不提供这些功能。
下一步: 维护者为 VS Code Copilot(仅聊天)、opencode、Zed 以及 Node.js、Ruby、PHP 等另外六种语言写了配置文档。这些我们没有为本页重新测试。
8. 用 MCP 给它配上工具
2 分钟后你将拥有: 模型通过一个 Model Context Protocol 工具读取实时网页并做出总结。
当答案就在某个网页上时,我想要模型自己去抓取,这样我就能拿到总结,不用来回复制文本。
安装 apfel-mcp 工具集,它们专为小上下文窗口设计:
brew install Arthur-Ficial/tap/apfel-mcp用 --mcp 接入一个工具,然后提问。-q 会隐藏工具的原始输出:
apfel -q --mcp $(which apfel-mcp-url-fetch) "Summarize https://apfel.franzai.com/ in 3 bullets"
- **Purpose**: apfel is a Swift 6.3 tool that wraps Apple’s on-device LLM (part of macOS 26’s Apple Intelligence) and exposes it via a CLI, HTTP server, and interactive chat with context management.
- **Features**: It handles terminal commands, JSON output, file attachments, real token counting, and context trimming (4,096 or 8,192 tokens depending on hardware), while converting OpenAI tool schemas to Apple’s native format.
- **Technical details**: Built using the FoundationModels framework, it runs on Apple Silicon’s Neural Engine and GPU without network or cloud dependencies, and is open-source under MIT license.同一个包里还有 apfel-mcp-ddg-search(网页搜索)、apfel-mcp-search-and-fetch 和 apfel-mcp-fs(读取本地文件)。任何 MCP 服务器都可以用:本地脚本路径或 https:// URL 均可。
带多个具名参数的工具同样可用。下面是 apfel 仓库里的计算器(mcp/calculator/server.py):模型带着两个参数调用 multiply,apfel 执行它,模型再给出结果:
apfel --mcp ./server.py "What is 15 times 27?"
mcp: /Users/arthurficial/work/apfel-i18n-video-2026-11-15/tut/./server.py - add, subtract, multiply, divide, sqrt, power, round_number
tool: multiply({"a": 15, "b": 27}) = 405
15 times 27 is 405.tool: 这一行是 apfel 在向你展示它执行的调用。在 apfel 1.18.0 之前,模型看不到参数名,只能靠猜,所以像这样的调用会失败(issue #555,已在 pull request #556 中修复)。如果你在这里看到 invalid arguments,请用 brew upgrade apfel 升级。
9. 用聊天测试提示词
2 分钟后你将拥有: 一个在终端里进行、能记住你前面说过什么的对话。
当我在为脚本打磨提示词时,我想要快速试几轮对话,这样我就能在自动化之前先看看模型的反应。
apfel --chat
Apple Intelligence · on-device LLM · apfel v1.18.0
────────────────────────────────────────────────────────
Type 'quit' to exit.
you› My name is Franz. I live in Vienna.
ai› Hello, Franz. It's nice to meet you. I'm here to help with any questions or tasks you might have. How can I assist you today?
you› Suggest one thing I could do there this weekend. One sentence.
ai› You could visit the Kunsthistorisches Museum to explore its impressive collection of art and artifacts.
you› What is my name?
ai› Your name is Franz.
you› quit
Goodbye.用 -s 加一个角色设定,例如 apfel --chat -s "You are a patient Python tutor"。当长对话超出上下文窗口时,apfel 默认会丢弃最早的几轮;其他策略见上下文指南。想要带按钮的窗口界面,请看 apfel-chat。
10. 让服务器在后台常驻
2 分钟后你将拥有: 一个登录时自动启动的兼容 OpenAI 的服务器,随时在端口 11434 待命。
当我 Mac 上的工具每天都要用这个本地端点时,我想要它一直开着,这样我就能不再手动启动它。
brew services start apfel
==> Successfully started `apfel` (label: sh.brew.apfel)
curl -s http://127.0.0.1:11434/health | jq -c '{status, model_available, context_window}'
{"status":"ok","model_available":true,"context_window":4096}
brew services stop apfel
Stopping `apfel`... (might take a while)
==> Successfully stopped `apfel` (label: sh.brew.apfel)端口、token 或 MCP 服务器等设置都通过环境变量配置,例如 APFEL_PORT=8080 brew services start apfel。完整列表见后台服务指南。
11. 基于 apfel 的应用
2 分钟后你将拥有: 同一个端侧模型,装进窗口、菜单栏或快捷键里,适合更喜欢应用而不是终端的你。
这些应用出自同一批维护者(见 README 中的“apfel tree”)。我们在 2026年11月15日确认了每个安装名称在 Homebrew 中都存在;但我们没有为本页测试这些应用本身。
| 应用 | 用途 | 安装 |
|---|---|---|
| apfel-chat | 聊天应用,支持流式回答、语音和图像分析 | brew install Arthur-Ficial/tap/apfel-chat |
| apfel-clip | 在菜单栏对剪贴板内容执行操作:总结、翻译、改写 | brew install Arthur-Ficial/tap/apfel-clip |
| apfel-quick | 按下快捷键,提问,拿到答案,关掉 | brew install Arthur-Ficial/tap/apfel-quick |
| apfelpad | 记事本,AI 就是你写进单元格里的一个公式 | brew install Arthur-Ficial/tap/apfelpad |
| apfel-mcp | 为小上下文窗口量身定制的 MCP 工具(第 8 个任务) | brew install Arthur-Ficial/tap/apfel-mcp |
| apfel-run | 带有保存配置和 MCP 服务器列表的 apfel | brew install Arthur-Ficial/tap/apfel-run |
| apfel-tag | 为通过管道传入的任何文本生成标签、主题和情绪 | brew install Arthur-Ficial/tap/apfel-tag |
| apfel-gui | 调试窗口:请求、MCP 消息、语音 | brew install Arthur-Ficial/tap/apfel-gui |
局限与坦诚的回答
apfel 让你用上 Apple 的端侧模型。README 给出的参数量约为 30 亿(3B),远小于 ChatGPT 或 Claude 背后的云端模型。它擅长简短、聚焦的文本任务。以下是我们实际碰到的、或文档中写明的局限。
上下文窗口很小。 问题加回答必须装进 4,096 个 token(macOS 26 以及 M1、M2 Mac),或 8,192 个 token(运行 macOS 27、内存 12 GB 及以上的 M3 或更新机型)(README)。apfel --model-info 会显示你的窗口大小。apfel 自己的 README 就已经放不下了。发送前先数一数:
apfel --count-tokens -f README.md "summarize in 3 bullets"
8272/3584 tokens (over budget)
prompt=7, README.md=8258
apfel -f README.md "summarize in 3 bullets"; echo "exit code: $?"
error: [context overflow] Input exceeds the model's context window: the input is 8264 tokens, the window is 4096 tokens. Shorten the conversation history.
exit code: 43,584 是 4,096 的窗口减去为回答预留的 512 个 token。这份 README 大约有 3,000 个英文单词,但 Markdown 和代码每个词都要消耗很多 token。长文件要分段输入(head -c 6000 file),一次一节。
它不知道今天的日期。 它会随便编一个:
apfel "What is today's date?"
Today's date is October 27, 2024.
apfel -s "Today is $(date '+%B %d, %Y')." "What is today's date? One sentence."
Today's date is November 15, 2026.它需要的任何事实,都写进提示词里给它。除非你接入一个 MCP 工具,否则它无法联网。
它有时会错,而且错得很自信。 前面你已经看到了:第 4 个任务里错误的 shell 命令,第 2 个任务里意思被翻转的翻译。凡是重要的内容,都要核对。
Apple 的安全过滤器可能会拦截无害的文本。 这时 apfel 以退出码 3 停止,并显示 The request was blocked by Apple's safety guardrails。换个说法,或者在创意写作和文档场景下加上 --permissive;安全护栏文档说明了它会改变什么。在为本页做的运行中,我们没有遇到拦截。
每次运行的回答都不一样。 这里的输出都是各运行一次得到的真实结果,你得到的措辞会有所不同。想让回答更稳定、更可复现,用 --temperature 0;apfel 不保证不同运行之间或 macOS 更新前后输出完全一致(稳定性政策)。
速度: 在我们的运行中,大多数回答在 1 到 2 秒内返回。借助 MCP 工具总结网页用了 8 秒。
硬性要求: 仅限 Apple Silicon,macOS 26 或更新版本,打开 Apple Intelligence,并使用 --model-info 列出的 15 种语言之一。Intel Mac 无法运行。
出问题时怎么办
apfel 用退出码报告问题,方便脚本做出反应。在命令之后立刻运行 echo $? 查看。
| 退出码或错误 | 含义 | 怎么办 |
|---|---|---|
2 |
参数或选项错误 | 参数要放在提示词前面;apfel --help 会列出全部参数 |
3 |
请求被 Apple 的安全过滤器拦截 | 换个说法,或加上 --permissive |
4 |
输入太长,超出上下文窗口 | 少发一些文本;用 apfel --count-tokens 检查 |
5 |
模型不可用 | 打开 Apple Intelligence,等待下载完成,让 Mac 与 Siri 的语言一致 |
6 |
模型繁忙或触发了速率限制 | 稍等后重新运行,或加上 --retry |
Connection refused |
端口 11434 上没有服务器 | 启动 apfel --serve 或 brew services start apfel |
| HTTP 501 | 端侧模型不提供的端点(embeddings、/v1/completions) |
改用 /v1/chat/completions |
piped input was empty |
命令把内容写到了 stderr | command 2>&1 \| apfel "..." |
还是解决不了?到 GitHub 搜索或提交一个 issue。
谁做的、怎么测的
apfel 免费且开源(MIT 许可证),是 Franz Enzenhofer 的 franzai 项目。它由 Franz 与他的 AI 助手 Arthur Ficial 共同维护,本教程也出自 Arthur Ficial 之手。由于本页是 apfel 的开发者自己写的,我们把看到的每一次失败都列了出来,而不是略过不提。
测试方法: 2026年11月15日,我们在一台 MacBook Air M2(24 GB)、macOS 27.0.1(build 26A434)上运行了本页的每一条命令。我们使用的是 GitHub release 中经过签名的 apfel 1.18.0 二进制文件(与 Homebrew tap 安装的是同一个文件),在真实的终端会话中运行,并原样复制输出。本页的第一版(2026年11月14日,apfel 1.16.0)展示过第 8 个任务中的多参数工具 bug;1.18.0 修复了它,所以我们为这一版重新运行了每条命令。第一次输出出错的地方,我们把错误输出保留在页面上并加以说明。仅有的重跑都只是为了得到无需修改的回答:有一次网页总结里出现了长破折号,而本站不显示这种符号,所以我们重新运行,保留了第三次的结果。语音示例是通过把音频写入文件来验证的,因为测试用的 Mac 没有声音输出。演示脚本由 apfel 1.18.0 的 apfel --demos 生成。
其他人对 apfel 的评价: Show HN 帖子(2026年4月3日,743 分)、Better Stack 的指南、GIGAZINE 的文章,以及 danilchenko.dev 上的上手评测。
资料来源: apfel README、CLI 参考、安装指南、演示脚本、apfel 与 Apple 的 fm 对比以及 issue 跟踪器,均于 2026年11月15日查阅。