第一天

到了已经快中午了，先在商业区找了家店吃点东西。宁海食府附近，选了个KFC——旅行的第一顿往往不是当地特色，而是你熟悉的连锁店，大概是舟山行的一个小注脚。

商业区挺热闹，李府食府门口有黄色花茎艺术雕塑。

下午去了长乔海洋国际旅游度假区。那天是阴天，云压得很低，园区建筑有欧式童话风格，塔楼、暖色外墙、修剪整齐的草坪。地方挺大，人不多，逛起来舒服。路上看到山坡上”浙江舟山群岛新区欢迎您”的红色大字。

园区内有港口，停泊着船只和起重机，水面开阔。

度假区建筑是欧式城堡风格，广场上有鲸鱼雕塑，入口有花坛。

从度假区出来，又绕到一个依山而建的营地。山脚下草坪开阔，搭了些帐篷和休闲设施，有人撑着伞在林间散步。舟山的山不高，但植被茂密，空气里是南方特有的潮润。

晚上的演出有点意思——观音主题的实景表演。舞台灯光打得很好，演员扮作观音形象，白衣素裹，两侧侍者持莲花灯，僧人列队，氛围肃穆又有些梦幻。

第二天

早起去了码头。海是灰蓝色的，不是那种旅游宣传片里的碧蓝，但更真实。码头的围栏上有创意涂鸦，渔船挂着国旗，斑马线延伸到海边——一个有人生活痕迹的港口。

退潮后的泥滩很有意思，满地小孔洞，小螃蟹和弹涂鱼在泥里钻来钻去，潮间带的生命力远比想象中旺盛。

下午路过宁波，去了趟天一阁。中国现存最古老的私人藏书楼，明代范钦建于嘉靖年间。阁名”天一”取自”天一生水”——以水克火，护佑藏书。

穿过月湖，先到的是天一阁外的文创街区。青瓦坡顶，灰色遮阳篷下是卖伴手礼的小店，门头上挂着”甬城纪念品”的招牌。阴天的光线下，老建筑的细节特别清楚。

天一阁本身不大，但园林极其精致。黛瓦翘角的墙上爬满藤蔓，石板地透着湿气。一株老朴树，枝干上长了青苔，旁边是棕榈和阔叶植物。园中一池碧水，假山叠石，树影入波，是典型的江南园林景致。

最后一站是园内的中国地方志珍藏馆。木质结构的老建筑，深红漆面有些斑驳，门楣上挂着匾额。里面陈列着全国各地的地方志和书画，与天一阁的藏书气质一脉相承。

关于照片

这次的照片都是用手机拍的，用小米 MiMo v2.5 看了每张照片的内容来识别场景——效果比预期的好，能认出具体的景点名称和建筑细节。照片本身没带 GPS 信息，所以没法用高德 API 反查定位，纯靠 AI 看图描述。

免责声明：本文涉及的 API Key 等敏感信息均已脱敏处理。实际使用请自行替换。

为什么需要扩展

Pi 的设计哲学是”最小核心 + 可插拔”——它本身只有最基本的 read/write/edit/bash 工具，但通过扩展机制，你可以给它加上任意能力：子代理、规划模式、持久记忆、权限保护、LSP 诊断……几乎 Claude Code 有的功能，Pi 都能通过扩展补上。

而且扩展是用 TypeScript 写的，本质上就是一个 npm 包。你甚至可以问 Pi 自己写一个扩展。

安装扩展

Pi 的扩展通过 pi install 命令安装：

1

pi install npm:@org/package-name

安装后需要在 Pi 交互界面中执行 /reload 让扩展生效。不改配置文件，不重启终端，非常干净。

查看已安装的扩展：

1

pi list

我装的扩展清单

🎯 Goal 模式 — 长期目标追踪

两个目标管理扩展，二选一即可：

1
2
3
4
5

# 方案 A：基础版
pi install npm:pi-agent-goal

# 方案 B：增强版（推荐，带 setup 访谈）
pi install npm:@qhn/pi-goal

@qhn/pi-goal 会在设置目标前先进行一个”访谈”——和用户对齐 outcome、完成标准、决策风格、ask-before 边界——然后再开始自主工作。体验上更接近 Claude Code 的 plan 模式。

注意两个扩展都注册了 /goal 命令，不要同时装。

🔒 权限保护 — 防误操作

1

pi install npm:@gotgenes/pi-permission-system

这个扩展给 Pi 加了一层权限门控。当模型要执行删除、覆盖等危险操作时，会先请求确认。适合在需要保护的代码库中使用，防止 AI 不小心把不该删的文件删了。

📋 Todo 浮动层

1

pi install npm:@juicesharp/rpiv-todo

在 Pi 界面中增加一个 todo 列表浮动层，由模型自己维护。多步任务时特别有用——模型可以看到还剩哪些步骤没做，不会跑偏。

📝 任务规划

1

pi install npm:@mjasnikovs/pi-task

确定性任务规划 + 规范编排。适合需要严格按步骤执行的场景，Pi 会先生成计划、再逐步执行、最后验证结果。支持将任务分解为可追踪的子任务。

🧠 持久记忆

1

pi install npm:@remnic/plugin-pi

让 Pi 拥有跨会话记忆能力。之前聊过的上下文、做过的工作会被记住，下次开启新会话时不需要重新交代背景。

🔧 其他推荐扩展

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 子代理
pi install npm:pi-subagents                # 并行/链式任务委派

# 联网能力
pi install npm:pi-web-access               # 联网搜索、GitHub 克隆、PDF/YouTube 提取

# 代码智能
pi install npm:pi-lens                     # LSP 实时代码反馈（lint、type-check）
pi install npm:@ff-labs/pi-fff             # 模糊文件/内容搜索
pi install npm:pi-simplify                 # 自动审查并简化新改代码

# 上下文管理
pi install npm:context-mode                # MCP 插件，压缩 context 省 98%

# 导航
pi install npm:@ayulab/pi-rewind           # 检查点导航
pi install npm:@quintinshaw/pi-dynamic-workflows  # Claude Code 式动态工作流

完整的配置结构

装完扩展后，~/.pi/agent/ 目录结构大概是这样的：

1
2
3
4
5
6
7
8
9
10
11
12
13

~/.pi/agent/
├── auth.json           # API Key 存储
├── models.json         # 自定义模型提供商
├── settings.json       # 全局设置
├── sessions/           # 会话记录
├── npm/                # 扩展包安装目录
│   └── node_modules/
│       ├── @qhn/pi-goal/
│       ├── @gotgenes/pi-permission-system/
│       ├── @juicesharp/rpiv-todo/
│       ├── @mjasnikovs/pi-task/
│       └── @remnic/plugin-pi/
└── trust.json          # 项目信任记录

自定义模型提供商配置

我用的 krill 示例（~/.pi/agent/models.json）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "providers": {
    "krill": {
      "name": "Krill API",
      "baseUrl": "https://api.krill-ai.com/codex/v1",
      "api": "openai-completions",
      "apiKey": "$KRILL_API_KEY",
      "models": [
        { "id": "deepseek-v4-flash", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "gpt-5.5", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "gpt-5.6-sol", "contextWindow": 256000, "maxTokens": 32768, "reasoning": true },
        { "id": "gpt-5.6-terra", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "gpt-5.6-luna", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "kimi-k2.7-code", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "gemini-3.1-pro-preview", "contextWindow": 1048576, "maxTokens": 32768 }
      ]
    }
  }
}

API Key 通过环境变量 KRILL_API_KEY 注入，或写到 auth.json：

1
2
3
4
5
6

{
  "krill": {
    "type": "api_key",
    "key": "your-api-key-here"
  }
}

tmux + Pi 后台工作流

Pi 配合 tmux 可以长时间在后台运行，适合做大任务：

1
2
3
4
5
6
7
8
9
10
11
12

# 启动
tmux new-session -d -s pi-session -c ~/project
tmux send-keys -t pi-session "pi --model krill/gpt-5.6-sol" Enter

# 发任务
tmux send-keys -t pi-session "你的任务描述" Enter

# 查看进度
tmux capture-pane -t pi-session -p -S -30 | tail -20

# 附着查看
tmux attach -t pi-session

建议在 ~/.tmux.conf 中加上 set -g extended-keys on，否则 Pi 的某些快捷键在 tmux 中会报 warning。

小技巧

1. 扩展不要一次装太多 — 每个扩展都会增加 context 开销。先装最需要的，不够再加
2. 两个 goal 扩展冲突 — 不要同时装 pi-agent-goal 和 @qhn/pi-goal，它们都注册了 /goal 命令。二选一
3. models.json 热重载 — 编辑完不需要重启 Pi，/model 或 --model 时会自动重新加载
4. API Key 别写死在 JSON 里 — 用 $ENV_VAR 引用环境变量，安全且方便切换
5. 多模型切换 — Pi 支持 Ctrl+L 快速切换模型，可以按任务类型切换（重任务用 Sol，轻量用 Luna）

资源

• 可以在 pi.dev/packages 查看完整扩展目录
• 也可以在 npm 搜索 keywords:pi-package 发现更多扩展
• 我的完整 Skill 配置文件：下载 pi-coding-agent-skill.md（Hermes Agent skill 格式，可放在 ~/.hermes/skills/ 下使用）

小结

Pi 的扩展生态远比我想象的成熟。从 goal 模式到子代理，从权限保护到持久记忆，大部分我想要的 Claude Code 功能都能通过扩展补上，而且安装过程极其简单——一行命令 + /reload 搞定。

如果你也在用 AI 编码助手，不妨试试 Pi + 扩展的组合，说不定会有惊喜。

刚好手头有一些第三方 API 额度，所以记录一下怎么给它配一个自定义（OpenAI 兼容）的模型提供商。

免责声明：本文涉及的 API Key 等敏感信息均已脱敏处理。

pi 的架构

pi 的模型管理分两层：

• 内置 provider — openai、anthropic、deepseek、openrouter、google 等几十个，开箱即用
• 自定义 provider — 通过 ~/.pi/agent/models.json 配置，支持 OpenAI 兼容接口

自定义配置的 schema 官方文档在 pi.dev/models。

配置步骤

1. 准备 API Key

把 API Key 写入环境变量（推荐，避免明文写在配置文件中）：

1
2

# ~/.zshrc
export KRILL_API_KEY=your_api_key_here

2. 创建 models.json

pi 的配置目录在 ~/.pi/agent/，创建 models.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "providers": {
    "krill": {
      "name": "Krill API",
      "baseUrl": "https://api.krill-ai.com/codex/v1",
      "api": "openai-completions",
      "apiKey": "$KRILL_API_KEY",
      "models": [
        { "id": "deepseek-v4-flash", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "deepseek-v4-pro", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "gpt-5.4", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "gpt-5.5", "contextWindow": 256000, "maxTokens": 32768 },
        { "id": "kimi-k2.7-code", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true },
        { "id": "gemini-3.1-pro-preview", "contextWindow": 1048576, "maxTokens": 32768 },
        { "id": "qwen3.7-plus", "contextWindow": 128000, "maxTokens": 16384 },
        { "id": "grok-4.5", "contextWindow": 131072, "maxTokens": 16384 }
      ]
    }
  }
}

关键字段说明：

3. 验证配置

1
2
3
4
5

# 列出所有模型
pi --list-models

# 输出中会看到 krill provider 和配置的模型列表
# Auth 列显示 yes 表示 API Key 已就绪

测试调用：

1

pi --provider krill --model deepseek-v4-flash --print "hello"

原理

pi 的模型加载流程：

1. 启动时读取 ~/.pi/agent/models.json
2. 合并内置 provider 和自定义 provider
3. 根据 apiKey 字段中的 $ENV_VAR 读取环境变量
4. 用 openai-completions API 模块创建 OpenAI 客户端
5. 请求时 baseURL 指向 model.baseUrl，model 参数传 model.id

所以只要是 OpenAI 兼容的接口——无论是 Krill、OpenRouter、还是本地跑的 vLLM、Ollama——都可以用同样的方式接入。

一点经验

• API Key 别写死在 JSON 里 — 用 $ENV_VAR 引用环境变量，安全且方便切换
• cost 字段不填也行 — 默认 0，不影响使用
• contextWindow 和 maxTokens — 按模型的实际能力填，不影响调用但对规划有帮助
• reasoning: true 开启思维链，适合 deepseek、kimi 等支持推理的模型
• 如果遇到 insufficient balance — 那是 API 提供商侧欠费了，检查账户余额就行

小结

pi 的自定义 provider 机制设计得很灵活，一个 models.json 就能接任意 OpenAI 兼容接口。这种”配置驱动”的方式比硬编码更干净，改模型只要改配置文件就行，不用动工具本身。

一层层剥开”AI 替代程序员”的叙事

1. 那些”AI 导致裁员”的新闻，经不起推敲

文章追踪了几个著名的案例：

这不是挑出来的特例。文章调查发现了一个普遍现象：

59% 的美国招聘经理承认，他们拿 AI 当裁员的借口，因为对股东说”AI 替代了人”比说”我们财务紧张”好听得多。

Forrester 的分析师说得很直白：“问他们有没有成熟的 AI 产品能顶上那些岗位，十有八九答案是没有，甚至还没开始做。”

2. “三明治”模型：为什么写代码从来不是瓶颈

文章提出了一个很好的框架——软件开发的”决定—执行—交付”三明治：

1
2
3
4
5
6
7

┌─────────────────────────┐
│    决定层 (Decide)       │  ← 理解需求、拆解问题、方案设计
├─────────────────────────┤
│    执行层 (Execute)      │  ← 写代码（AI 正在压缩的部分）
├─────────────────────────┤
│    交付层 (Deliver)      │  ← 测试、集成、部署、运维
└─────────────────────────┘

AI 压缩的是中间的”执行层”。但两端的”决定”和”交付”几乎没变。

一组关键数据：GitHub 上 10 万开发者的研究发现，AI 让代码产出提高了 8 倍，但最终发布只增加了 30%。这 30% vs 800% 的差距，就是人和 AI 之间不可替代的部分。

3. 为什么员工总数反而可能增加

这就回到了经济学的核心逻辑。不是简单的”写代码变快了所以不需要那么多人”，而是：

软件需求有高价格弹性。当软件变便宜了，市场会需要多得多的软件。

举个例子：

• 以前开发一个功能要 10 人月，成本 50 万，公司算不过账，不做了
• 现在 AI 辅助下只要 2 人月，成本 10 万，公司觉得划算，决定做
• 净效果：需要的人更多了

这个逻辑有个响亮的经济学名字——杰文斯悖论（Jevons’ Paradox）：

蒸汽机效率提高后，每吨煤能做的功变多了，但煤炭总消耗反而上升了——因为煤变”划算”了，大家用得更狠。

放到软件行业就是：AI 让每个工程师的产出变高，但市场对软件的总需求增长更快。

4. 历史不会撒谎

每一轮”技术替代人”的恐慌过后，事实都证明：技术不是替代人，而是重新定义人的工作内容，并且总需求在增长。

写在最后

这不是盲目乐观。文章也承认：即使总需求在增长，个体软件工程师的职业生涯可能会更动荡。 比如：

• 初级岗位可能减少，因为 AI 补了部分”执行”能力
• 纯”码代码”的岗位价值下降
• 但懂业务、能决策、能交付的人会更值钱

最让我有共鸣的是这句话：

AI 压缩了三明治的中间层，但两端的”决定”和”交付”几乎没有变化。而真正重要的是两端。

参考：Arvind Narayanan & Sayash Kapoor, “Why AI hasn’t replaced software engineers, and won’t”, AI Snake Oil, Jun 2026

项目发布一条龙

最频繁的工作就是给 Qx 项目做发布。从 v0.4.36 到现在的 v0.6.5，发布了几十个版本：

• 自动检测未提交的变更
• 更新版本号（package.json、Cargo.toml、tauri.conf.json 三处同步）
• 运行 tsc --noEmit 和 cargo check 验证编译
• 打 tag、推送到 GitHub
• 一条命令搞定，遇到网络波动会自动重试

另一个项目 Shelfy（Tauri 文件整理工具）也是同样的流程。后来还搞定了 Homebrew Cask 分发：brew tap mcxen/qx && brew install --cask mcxen/qx/qx。

frp 隧道和远程管理

需要在外面连回家里的 Mac，Hermes 帮我：

• 检查 frps 服务器（121.40.88.21）是否在线
• 配置 frpc 客户端，写好配置文件
• brew services start frpc 开机自启
• SSH 到远程 Linux 服务器执行各种运维命令

全程不需要手动编辑配置文件，自然语言描述需求就行。

qodercli 自动化

Qx 项目里很多代码改动是通过 qodercli（AI 编码 CLI）完成的，Hermes 负责在 tmux 里操作它：

• NSPanel 悬浮面板 – macOS 原生无焦点面板实现，这是 Qx 的核心交互
• 主题切换卡顿修复 – 排查 CSS 变量在暗黑模式下缺失的问题
• Markdown 渲染升级 – 从 react-markdown + shiki 换成更轻量的方案
• 流式输出卡死修复 – 重构 Rust 后端的流式处理逻辑
• 设置面板布局修复 – 导航项固定行高 + label 截断
• GitHub Actions 步骤进度 – 解析 CI 页面的 HTML 结构，显示真实的步骤完成情况

Memos MCP 服务器

自己搞了个 Memos 实例（121.40.88.21:12009），Hermes 帮我：

• 搭建 FastMCP 服务器（~/Documents/OpenSpring/memos-mcp/）
• 直接通过 API 读写 memo 笔记
• 搜索已有笔记做信息关联

博客维护

Hexo 博客（mcxen.github.io）的日常维护基本都是 Hermes 在跑：

• 写文章、整理内容
• HEIC 照片转 JPEG、图片放到 source/images/
• hexo generate + hexo deploy（走代理 7897）
• 自动给没有封面的文章选 Unsplash 关键词配封面
• RSS 全文订阅配置

网络工具和资源下载

• X/Twitter 视频 – 用 yt-dlp 下载指定推文视频
• 720yun 全景图 – 下载全景切片并合成为等距柱状投影图
• NAS 文件管理 – 通过 SMB 挂载飞牛 NAS（10.0.0.124），排查 macOS SMB 连接问题
• Cloudflare Pages – 部署静态站点，配置自定义域名

DevOps 和 CI

• Cloudflare Workers – 搭建战术终端风格的 Web 界面
• Caddy 反代 + ICP 备案 – 踩坑记录，跟阿里云和 Cloudflare 的 DNS 配置斗智斗勇
• GitHub Actions – 解析 CI 运行详情页的 HTML 结构，实现真实的步骤进度展示

小结

AI 助手已经从聊天玩具变成了真的能干活的生产力工具。从项目发布、代码重构、服务器配置到内容创作，基本上说”帮我搞一下”，它就能自己折腾出来。

最大的变化是：我现在遇到问题的第一反应不是去搜，而是让 Hermes 来处理。

这篇文章本身就是 Hermes 根据记忆和会话记录自动整理成文的。

本文涉及的所有敏感信息（IP、密码、Token、服务器配置等）均已脱敏处理。

什么是 Hermes Agent

Hermes Agent 是一个开源的 CLI AI 智能体，运行在终端里，能直接操控 macOS/Linux 系统——读写文件、执行命令、管理 git、调用 API、搜索网页。它不是”聊天机器人”，而是一个能动手干活的 AI 助手。

它有完整的工具链和技能系统，可以安装各种”技能”来扩展能力。支持多种大模型后端，我主要用 DeepSeek 和 mimo。

场景一：日常开发辅助

代码编写与调试

最常用的场景。Hermes 可以直接操作文件系统，理解项目结构后帮我写代码、修 bug。

我的 Qx 项目（Tauri 桌面应用，现在 v0.6.5）和 Shelfy 项目（文件整理工具），常见工作流：

1

写需求 -> 让 Hermes 分析现有代码 -> 生成代码实现 -> 检查编译 -> 修复错误 -> 提交 PR

遇到编译错误，直接把错误日志扔给它，它能逐层追溯、定位问题根因。

代码审查

PR 提交前用 Hermes 做自动审查——检查安全性、代码质量、风格一致性。发现问题后直接 inline comment 到 GitHub PR 上。

AI 编码 CLI 集成

Hermes 不只是自己写代码，还能操作其他 AI 编码工具。我用的 qodercli 就是通过 Hermes 在 tmux 里调度的：

• 把任务发给 qodercli
• 监控它的输出
• 需要时介入修正

这种”AI 操作 AI”的模式对复杂功能开发特别有效。

场景二：DevOps 与服务器管理

我有一台远程 Linux 服务器（frps）和一台飞牛 NAS。Hermes 通过 SSH 直连执行命令：

• 配置 frp 内网穿透，开机自启
• 检查服务状态、日志
• 安装和更新软件包
• 管理 Memos 自托管实例
• NAS 文件管理，SMB 挂载排查
• Cloudflare Pages 部署静态站点

不需要记命令参数，用自然语言描述需求就行。常用的 SSH 模式是 sshpass 加密码直连，避免交互式提示。

场景三：知识管理与笔记

我有自托管的 Memos 实例和 Obsidian 笔记库，Hermes 可以直接读写：

• 读到有价值的内容，让它记到 Memos
• 搜索已有笔记做信息关联
• 维护”记忆系统”——跨会话保持用户偏好、环境配置、项目约定

记忆系统是 Hermes 的特色功能。它会在每次对话时注入之前积累的知识，不用每次重复说”我的博客在哪”、”代理端口是多少”。

场景四：技能系统与自动化

Hermes 有”技能”（Skill）机制，预定义特定任务的工作流程。遇到重复性任务就打包成技能，下次直接复用。

我现在积累的技能包括：

• 项目发布：版本号同步、编译检查、打 tag、推送
• 博客维护：写文章、处理图片、生成部署
• Homebrew Cask 分发：给 Tauri 应用做 brew tap
• Tauri 发布流程：多文件版本号更新、CI 验证
• 系统诊断：快速检查磁盘、内存、网络状况
• 代码审查：安全扫描、质量门禁

把复杂流程封装成技能后，一句话就能启动一整套操作。

场景五：研究与信息获取

调研新技术、查 API 文档、找解决方案时：

• 搜索网页 + 提取页面内容 + 综合分析
• 读 arXiv 论文摘要
• 跟踪技术博客更新（blogwatcher）
• 跟踪 Polymarket 市场数据

它能把分散的信息合成一个完整的结论，比自己搜索效率高很多。

场景六：创意与内容

• 用 ComfyUI 生成图片、视频
• 生成 ASCII art
• 制作 SVG 信息图和架构图
• 用 Manim 做数学动画
• TouchDesigner 视觉创意

场景七：生活工具

• Apple Reminders – 通过 CLI 管理待办事项
• iMessage – 发送和接收消息
• 地图 – 地理编码、POI 搜索、路线规划
• 邮件 – Himalaya CLI 收发邮件

我的心得

用了一年，最深的体会是：

1. AI 助手的能力 = 工具链 x 模型智能。光有聪明的模型不够，能直接操作系统才是生产力。
2. 技能系统的价值被低估了。把重复工作打包成技能，比每次手写 prompt 高效得多。
3. 记忆系统让 AI 真正”认识”你。它知道你的项目结构、偏好、常用命令，不用每次从零开始。
4. 不完美，但在进步。长上下文仍有 token 耗尽的问题，复杂代码重构有时需要人工介入。但整体趋势是正向的。

这篇文章本身就是 Hermes 帮我写的，从记忆和会话记录中自动整理成文。

11:51 · 尾炉坑

从霞浦城区出来沿东海一号线南下，在长春镇的尾炉坑附近停下来拍了第一张。这条沿海公路是霞浦的景观大道，一边是山一边是海，弯道多、视野开阔。六月的福建已经热起来，但海风吹着还算舒服。

12:10 · 高罗拾光海岸营地

到 高罗海滩 了。这一带叫 GOL WAVE 高罗拾光海岸营地，是高罗沙滩的一个新开的露营和海滨运动综合体。有水上运动中心，还有一片很开阔的沙滩。沙滩上人不多，海浪平缓，适合下水。

12:22 · 细仔头岛 / 界石澳

继续往前到 细仔头岛 附近。这里是界石澳的一个小海湾，海水颜色比刚才深了一些，能看到远处岛礁轮廓。路边有几个观景台可以停车拍照。

13:13–13:58 · 大京沙滩

旅程的重头戏 — 大京沙滩。这是霞浦最长的沙滩，绵延数公里，沙质细腻、坡度平缓。我们在海鲜城停车场停好车，在沙滩上待了将近一个小时。

沙子很细，踩上去很舒服。正午的光线虽然硬，但海水在阳光下的颜色特别好看。

沙滩上有不少被海浪冲刷上来的贝壳和小石子。

15:41 · 闾峡村

离开大京继续南下，到达 闾峡村。这里是半岛东南端的一个渔村，附近有闾峡安澜侯宫。村子不大，房子沿着海岸线排开，码头边停着渔船。海水颜色在这一片变得更深更蓝。

16:14 · 里城村 / 北世

穿过闾峡继续走，经过里城村和北世一带。这一段的东海一号线拐进了内陆，两边是农田和村庄，偶尔能透过树丛看到海。

18:56 · 三沙古桶村

下午将近七点，到了 三沙镇古桶村。三沙是霞浦最热门的摄影点之一，古桶村一带沿海有大量的民宿和海景餐厅，许多都有漂亮的海上日落观景台。

19:04 · 虞公亭沙滩 — 日落

几分钟车程到 虞公亭沙滩，正好赶上日落。六月底的日落时间在七点左右，天空的颜色从金黄过渡到粉紫，映在海面上特别好看。虞公亭沙滩不大，但胜在人少安静。

20:57 · 霞浦城区 — 晚餐

天黑后回到霞浦城区，在 松港街道东吾路 一带找吃的。世纪锦园附近有很多临街的小吃和排挡，和前一晚一样去了新美味园那一带，吃海鲜、喝啤酒，结束了一天的海岸线行程。

次日 10:48 · 霞浦东关

第二天早上在霞浦城区逛了一会儿，东关一带是老城区，街边有菜市场和早点摊，游客少，生活气息很浓。

12:39 · 福鼎

返程往北开，中午到了 福鼎市。桐城街道洋垱小区一带是居民区，没什么景区，纯粹是路过歇脚。

实用信息

路线：霞浦城区 → 东海一号线南段 → 高罗 → 大京 → 闾峡 → 三沙 → 返程

东海一号线：霞浦最美的沿海公路，南起积石、北至三沙，沿途有多个观景台和停车点，海边风景很好，适合自驾慢慢开。

高罗海滩：免费开放，有水上运动项目可以玩。

大京沙滩：霞浦最长的沙滩，沙质细软，入口处有停车场（海鲜城停车场）。

闾峡：半岛东南端的安静渔村，适合拍渔船和海岸线。

三沙：摄影圣地，日落时分东壁、虞公亭一带是绝佳的拍摄点。

照片说明

本次行程的部分照片包含了 实况照片 (Live Photo)——鼠标悬停或手指长按即可看到动态画面。如果看不到动态效果，试试用电脑或手机上的浏览器查看。

几个月前我给 maps_client.py 接入了高德逆地理编码（reverse 命令），解决了中国地址只能到街道级的痛点。但 nearby 命令（周边POI搜索）一直用的 Overpass API（OpenStreetMap 数据），在中国小县城效果惨不忍睹。

之前在霞浦旅行时搜附近餐厅，霞浦松城 500m 范围内只返回了一家店，还因为 OSM 里 node + way 两条记录重复显示了三次。

方案：高德周边搜索 API

高德的 place/around 接口（周边POI查询）覆盖了中国全境的餐饮、住宿、医疗、购物等 46 个品类，数据质量远超 OpenStreetMap。

1

GET https://restapi.amap.com/v3/place/around?key=xxx&location=116.3974,39.9042&radius=1000&types=050000&offset=25

返回结构化 JSON，含店名、地址、电话、经纬度、距离、类型等字段。

实现

1. 品类映射

OpenStreetMap 和 高德 使用不同的分类体系。我需要把 maps_client.py 的 46 个品类逐一映射到高德的类型编码：

1
2
3
4
5
6
7
8
9
10
11

AMAP_TYPE_MAP = {
    "restaurant":        "050000",  # 餐饮服务
    "cafe":              "050500",  # 咖啡厅
    "bar":               "050700",  # 酒吧
    "hospital":          "090100",  # 综合医院
    "hotel":             "100000",  # 住宿服务
    "pharmacy":          "090300",  # 药店
    "bank":              "060500",  # 银行
    "park":              "110000",  # 公园景点
    # ... 共 46 个品类
}

2. 优先策略

nearby 命令现在的逻辑是：先试高德，失败回退 Overpass。AMAP_KEY 不存在时直接走旧路径，完全向后兼容。

1
2
3
4
5
6
7
8
9
10

def cmd_nearby(args):
    # ... 解析参数 ...

    # 先试高德（中国数据远好于 OSM）
    amap_places = amap_nearby(lat, lon, categories, radius, limit)
    if amap_places is not None:
        return print_json(amap_places)

    # 回退 Overpass (OSM)
    # ... 原有逻辑 ...

3. 配置持久化

Key 现在配置在 Hermes 的 config.yaml 里，脚本启动时自动读取。也可以通过环境变量传入。

效果

霞浦松城（26.888, 120.0118）附近 500m 搜餐厅：

之前（Overpass/OSM）

1

晨曦酒店 (387m)   ← 酒店被标成了餐厅

之后（高德）

1
2
3
4
5
6

互惠小吃店 (106m)
敖祖雄饼店·世纪锦园店 (107m)
长春炒肉糕·粽子·世纪锦园店 (108m)
渔米乡·酸菜鱼·水煮鱼·世纪锦园店 (108m)
新三峡鱼庄·霞浦天安小区店 (112m)
...

10 条结果，带地址和电话，距离精确到米。

配置方式

如果你也用 maps_client.py，配置高德 Key 很简单：

1

hermes config set env.AMAP_KEY "你的32位key"

之后 nearby 自动走高德，无需其他配置。没有 Key 时自动走 Overpass 旧路径，不影响海外使用。

更新内容

• maps_client.py v1.4.0
  • 新增 amap_nearby() — 高德周边搜索
  • 46 个品类映射到高德类型编码
  • 新增 AMAP_TYPE_MAP 常量表
  • 优先高德，失败回退 Overpass
  • 支持 AMAP_KEY 从 config.yaml 或环境变量读取
• maps skill v1.4.0
  • SKILL.md 更新配置说明和 China 覆盖文档

为什么选 Workers

简单原则：不要多一个服务器。GeekZip 本身在 GitHub Releases 上托管二进制，但需要一个好看的下载页。如果为了一个静态页面去配 Nginx/Caddy/Vercel，太重了。

Workers 的好处：

• 免费计划每天 10 万请求，个人项目用不完
• 全球边缘节点，延迟约等于 0
• 可以在 fetch handler 里直接代理 GitHub 下载，比静态 CDN 灵活
• 自定义域名绑定一行命令搞定

整体架构

1
2
3
4
5
6
7
8

用户 → z.xpai.uk
         ↓
    Cloudflare Edge
         ↓
    Worker (geekzip)
         ├── /  → 返回战术终端 HTML
         ├── /download/*  → 代理 GitHub Release 文件
         └── /api/releases → 转发 GitHub API

Worker 的代码结构很简单——一个 fetch() 函数根据路径分发：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === "/") {
      return new Response(HTML, {
        headers: { "content-type": "text/html;charset=UTF-8" }
      });
    }
    if (url.pathname.startsWith("/download/")) {
      // 代理下载
    }
    ...
  }
};

战术终端设计

风格参考了军用终端 UI 和 CRT 显示器的视觉效果。全部用纯 CSS 实现，没有图片。

字体

正文用 JetBrains Mono（等宽字体，编程感），标题用 Major Mono Display（粗犷的显示字体，军事感）。Google Fonts 加载：

1

<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&family=Major+Mono+Display&display=swap" rel="stylesheet">

单色调色盘

只用了绿色 #00ff95，通过透明度变化分出层次：

1
2
3
4
5
6

:root {
  --green: #00ff95;
  --green-dim: rgba(0,255,149,0.15);
  --green-mid: rgba(0,255,149,0.5);
  --border: rgba(0,255,149,0.2);
}

CRT 扫描线

用 repeating-linear-gradient 在 body::after 上绘制 2px 间隔的黑线，模拟老式 CRT 显示器的扫描线纹理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

body::after {
  content: '';
  position: fixed;
  inset: 0;
  background: repeating-linear-gradient(
    0deg,
    transparent,
    transparent 2px,
    rgba(0,0,0,0.08) 2px,
    rgba(0,0,0,0.08) 4px
  );
  pointer-events: none;
  z-index: 999;
}

再加一个径向渐变模拟 CRT 屏幕边缘的暗角：

1
2
3
4
5
6
7

body::before {
  background: radial-gradient(
    ellipse at center,
    transparent 60%,
    rgba(0,0,0,0.4) 100%
  );
}

四角作战标记

四个 <svg> 定位在页面的四个角，L 形线条，旋转/镜像组合：

1
2
3
4
5

<div class="corner corner-tl">
  <svg viewBox="0 0 28 28">
    <path d="M26,2 L26,10 M26,2 L18,2 M26,2 L2,26"/>
  </svg>
</div>

四个的变换分别是 scaleX(-1)、scaleY(-1)、scale(-1,-1)，形成一个封闭的”框”效果。

LED 脉冲指示灯

用 CSS animation 模拟三个状态指示灯（SYS、NET、DOCK），pulse 关键帧控制发光圆点的呼吸节奏：

1
2
3
4
5
6
7
8
9
10
11

.led-dot {
  width: 6px; height: 6px;
  border-radius: 50%;
  background: var(--green);
  box-shadow: 0 0 4px var(--green);
  animation: pulse 2s ease-in-out infinite;
}
@keyframes pulse {
  0%, 100% { opacity: 1; transform: scale(1); }
  50% { opacity: 0.3; transform: scale(0.8); }
}

DOCK 指示灯用 .off 类关掉（灰色），表示「当前未对接」。

按钮扫光动画

鼠标移入下载按钮时，一道高光从左侧扫过。用伪元素 ::before 实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

.dl-btn::before {
  content: '';
  position: absolute;
  top: 0; left: -100%;
  width: 100%; height: 100%;
  background: linear-gradient(
    90deg,
    transparent,
    rgba(0,255,149,0.08),
    transparent
  );
  transition: left 0.5s;
}
.dl-btn:hover::before {
  left: 100%;
}

CLI 命令框 + 闪烁光标

模拟终端输入效果，cursor 用 step-end 动画实现 blink：

1
2
3
4
5
6
7
8

.cli-box .cursor {
  display: inline-block;
  width: 7px; height: 14px;
  background: var(--green);
  animation: blink 1s step-end infinite;
  vertical-align: text-bottom;
}
@keyframes blink { 50% { opacity: 0; } }

操作日志

日志区域模拟终端输出，每行包含时间戳、等级标签和消息。等级用颜色区分：

• INFO → 半透明白
• OK → 亮绿
• WARN → 橙黄
• ERR → 红色

偶数列用 nth-child(even) 加微弱斑马纹，类似 TUI 日志查看器。

部署

使用 wrangler CLI，一条命令搞定：

1
2
3
4
5
6
7
8

# 安装 wrangler
npm install -g wrangler

# 登录（或用 API token 环境变量）
export CLOUDFLARE_API_TOKEN="cfat_xxxx"

# 部署并绑定自定义域名
wrangler deploy --domain z.xpai.uk

Worker 的路由配置在 wrangler.toml：

1
2
3

name = "geekzip"
main = "index.js"
compatibility_date = "2026-06-17"

下载代理

Worker 同时担任 GitHub Release 的下载代理。/download/GeekZip-macos-arm64.app.zip 会被转发到 https://github.com/mcxen/GeekZip/releases/latest/download/...，这样用户下载时走 Cloudflare 边缘节点，比直连 GitHub 快很多。

1
2
3
4
5
6
7
8
9
10

if (url.pathname.startsWith("/download/")) {
  const asset = url.pathname.slice(10);
  const gh = await fetch(
    "https://github.com/mcxen/GeekZip/releases/latest/download/" + asset,
    { headers: { "User-Agent": "GeekZip-Worker" } }
  );
  const hdrs = new Headers(gh.headers);
  hdrs.set("content-disposition", 'attachment; filename="' + asset + '"');
  return new Response(gh.body, { headers: hdrs });
}

踩坑记录

DNS 的问题

一开始把 go.opencode.ai 和 opencode.ai/zen/go/v1 搞混了，在 DNS 上浪费了不少时间。检查域名是否真的是公共 DNS 记录，可以直接 dig +short <domain> 验证。

透明代理 vs 显式代理

在 Ubuntu VM上试验时，iptables REDIRECT 把 443 流量导到代理的 redir-port，但代理看不到原始域名（只有 IP），导致路由失败。显式 HTTP CONNECT 代理更可靠。

Workers 自定义域名

wrangler deploy --domain 会自动处理 DNS 记录和 Workers Route 的绑定，不需要手动去 Cloudflare Dashboard 点。但需要注意 API Token 需要有 Workers 和 DNS 的权限。

最终效果

访问 https://z.xpai.uk 可以看到成品。整个页面不到 12KB（gzip 后 3.6KB），没有依赖任何框架或 UI 库，纯手写 CSS + Workers。代码在 GeekZip 仓库 的 workers/ 目录下。

我日常用的地图工具（maps_client.py）基于 OpenStreetMap 生态 —— Nominatim 做 geocode/reverse geocode，OSRM 算路径，Overpass 查 POI。这套组合在全球大部分地区够用，但在中国有个硬伤：

Nominatim 的中国地址数据极其稀疏。 输入一组经纬度，返回的往往只有街道名（如”玉清东街”），没有小区名、没有楼栋、没有 landmark。对于 “我在哪个小区附近” 这种日常需求，完全不可用。

方案：接入高德 Web 服务 API

高德开放平台提供 Web 服务 API，免费个人开发者每天 5000 次调用额度。regeo 接口（逆地理编码）直接返回：

• 格式化地址（省市区街道+地标）
• 小区/建筑物名称
• 周边 POI 列表（医院、学校、商场等）

接入成本极低：一个 HTTP GET 请求。

实现

1. 申请 Key

去 高德开放平台控制台 注册个人开发者 → 创建应用 → 添加 Web 服务 API 类型的 Key。不需要绑域名，不需要备案。

Key 是一串 32 位 hex 字符串，像这样：

1

5bcc282ebffd771255da0aca935b6636

2. API 调用

高德的 regeo 接口极其简单：

1

GET https://restapi.amap.com/v3/geocode/regeo?key=YOUR_KEY&location=116.3974,39.9042&output=json&extensions=all

返回示例（北京天安门）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "status": "1",
  "regeocode": {
    "formatted_address": "北京市东城区东华门街道天安门广场人民英雄纪念碑",
    "addressComponent": {
      "province": "北京市",
      "district": "东城区",
      "township": "东华门街道",
      "building": {"name": "天安门广场", "type": "风景名胜;公园广场;城市广场"}
    },
    "pois": [
      {"name": "人民英雄纪念碑", "type": "风景名胜;纪念馆", "distance": "54"},
      {"name": "天安门广场", "type": "风景名胜;公园广场", "distance": "117"},
      {"name": "毛主席纪念堂", "type": "风景名胜;纪念馆", "distance": "190"}
    ]
  }
}

对比 Nominatim 同一位置的返回：

1
2
3
4

{
  "display_name": "东长安街, 南池子社区, 东华门街道, 东城区, 北京市, 100010, 中国",
  "address": {"road": "东长安街", "suburb": "东华门街道", "city": "东城区"}
}

差距明显：Nominatim 只给到街道级，高德给到”人民英雄纪念碑” + 周边 5 个 POI。

3. 代码改动

在 maps_client.py 的 cmd_reverse 函数里，优先尝试 Amap，失败则回退 Nominatim：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

AMAP_REVERSE = "https://restapi.amap.com/v3/geocode/regeo"
AMAP_KEY = os.environ.get("AMAP_KEY")

def cmd_reverse(args):
    # ... 参数校验 ...

    # 先试高德
    if AMAP_KEY:
        try:
            params = {
                "key": AMAP_KEY,
                "location": f"{lon},{lat}",
                "output": "json",
                "extensions": "all",
                "radius": 1000,
            }
            data = http_get(AMAP_REVERSE, params=params, silent=True)
            if data.get("status") == "1" and data.get("regeocode"):
                regeo = data["regeocode"]
                # 提取小区名
                for poi in regeo.get("pois", [])[:10]:
                    if "住宅小区" in poi.get("type", ""):
                        community = poi["name"]
                # 输出结构化结果
                return print_json({...})
        except:
            pass  # 失败则 fall through

    # 回退 Nominatim
    return nominatim_reverse(lat, lon)

完整改动在 maps_client.py v1.3.0。Python stdlib 即可，零外部依赖。

4. 效果对比

青岛市区某点（36.07, 120.38）：

Nominatim（之前）

1

仅返回街道名，无小区信息

Amap/高德地图（之后）

1
2
3
4
5
6
7
8

山东省青岛市市南区香港中路街道华佗路中国人民解放军海军第九七一医院 · 在正一家园附近

周边 POI:
- 中国人民解放军海军第九七一医院 (226m)
- 闽江路52号小区 (87m)
- 正一家园 (126m) ← 小区级别
- 青岛市教育局 (177m)
- 府新大厦 (179m)

“在正一家园附近” —— 这才是日常问路需要的精度。

配置方式

设置环境变量即可启用：

1

export AMAP_KEY="你的32位key"

也可以写进 shell profile：

1

echo 'export AMAP_KEY="你的32位key"' >> ~/.zshrc

之后 maps_client.py reverse 纬度 经度 自动走高德，无需任何其他配置。

踩坑记录

1. Key 类型必须选 Web 服务 API

高德有多个产品线：JS API、Android SDK、iOS SDK、Web 服务 API。如果选了 JS API 或 SDK 类型的 key，调用 REST 接口会返回：

1

{"status": "0", "info": "USERKEY_PLAT_NOMATCH", "infocode": "10009"}

解决方法：在控制台重新创建一个”Web 服务 API”类型的 key。

2. 免费的够用

个人开发者免费额度 5000 次/天。对于个人工具使用，完全不可能用完 —— 一天手动查几十次已经很多了。

3. 非中国坐标自动回退

高德只覆盖中国地区。代码里做了 fallback：如果高德请求失败（网络超时、非中国坐标等），自动降级到 Nominatim，不影响海外使用。

总结

• 问题：Nominatim 中国数据稀疏，只能到街道级
• 方案：优先调用高德 Web 服务 API，失败回退 Nominatim
• 成效：小区级地址 + 周边 POI，零外部依赖
• 成本：免费（5000次/天），一行环境变量即可启用