Table of Contents

我桌上常年蹲着一只 80×100 像素的小机器人。以前它只会散步和睡觉；现在，当我在另一个窗口里跑 ZCode 或 Claude Code 时，它头顶会亮起蓝色脉冲徽章——agent 在干活；任务结束时它蹦一下，徽章变绿。这篇文章记录了把它从”装饰品”打磨成”AI 工作流观测员”的四轮迭代。

PromptPal 是什么

PromptPal 是我写的一个 Windows 桌面应用：AI 提示词管理器 + 桌面宠物，DeepSeek 终端风配色，技术栈 Vue 3 + TypeScript + Pinia + Tauri 2（Rust）。核心能力：

• 提示词管理：卡片式增删改查、分类、收藏、使用次数统计，双击即复制
• 模板变量填空：内容里写 [风格] 或 {{主体}}，复制时弹填空框实时预览替换，还记住你上次填的值
• 社区数据源：网络搜索直接接 f/awesome-chatgpt-prompts（171k★）的真实数据集，jsDelivr → GitHub raw → 本地缓存 → 内置离线数据四级回退
• 快捷注入：Ctrl+Alt+P 全局呼出，搜索 + 回车复制，带变量的自动进填空流程
• CLI：终端里 pal 命令同样能选提示词、填变量、进剪贴板
• 云同步：Gitee 自动推送（改动后 60s 防抖）、启动时远端较新会询问拉取、推送前滚动备份最近 5 份

四轮迭代：每轮只解决一类问题

这个项目最近一个月里做了四轮集中迭代（v1.3 → v1.6），每一轮都有明确的主题，全部由 AI 辅助完成——后面会讲这套工作流本身。

轮次	主题	交付
v1.3	修地基	Claude API 三个 bug、真实数据源、统一存储层 + schema 迁移链、模板变量填空、Gitee 自动同步、CI
v1.4	造型与漫游	Shimeji 精灵图导入、渲染双通道、机器人锚定的全屏漫游
v1.5	效率三件套	ZIP 整包导入 + XML 语义映射、CLI 变量填空、使用统计面板
v1.6	灵动与联动	眼睛跟随鼠标、庆祝动画、感知三大 AI 代理的工作状态

v1.3 修地基：bug 是最好的入口

第一轮从三个真实 bug 开始：给 Anthropic Messages API 发了 role: 'system' 消息（该 API 只认顶层 system 字段，Claude 生成必 400）；SSE 流式解析里一个运算符优先级错误；连接测试硬编码 Bearer 头导致 Claude 永远测不通。修完 bug 顺手做了统一存储层（loadJson/saveJson + schema 版本迁移链——后来它被证明是整个项目最划算的投资）和 GitHub Actions CI。

v1.4 造型与漫游：一次类型检查揪出的三处暗病

用户（也就是我自己）想要”自定义桌宠造型”。调研了 GitHub 上的桌宠生态后选了最轻的路线：单张 Shimeji 精灵图导入——Shimeji 社区有海量现成形象包。渲染用 background-position 定时切帧，帧序列按 walk / idle / sleep 三个状态映射，配 4/8/12/16 fps。

这一轮有个意外收获：把桌宠的运动逻辑从 .vue 拆进 .ts 组合式函数后，tsc 第一次照进了这些代码，当场揪出三处历史暗病——currentMonitor() 调用方式错误（在非 1080p 屏幕上地面位置一直是错的）、setPosition 传裸对象碰巧能跑、以及一个组件挂载期的 TDZ 引用错误。

v1.5 三件套：让能力对齐到每个入口

第三轮补齐”能力不对齐”的欠账：主面板能变量填空了，终端 CLI 还只能复制原文——于是 Rust 和 Node 两端 CLI 都补上同规则的填空；Shimeji 包是散帧 PNG 而导入器只认拼好的长条——于是支持 ZIP 整包导入，自动解包、拼条、解析 conf XML（同时兼容 Group-Finity 日文和 Shimeji-ee 英文两种格式）自动配好三个状态的帧序列。实测导入一个 46 帧的皮卡丘包，walk=[1,2,3]、idle=[1]、sleep=[21] 全自动提取。加上一个纯展示的使用统计面板，v1.5 收官。

v1.6 灵动与联动：从装饰品到观测员

最近一轮做了两件事。灵动包：机器人的眼睛会跟随全局鼠标移动（复用穿透判定已有的光标轮询，零额外开销），复制成功和 agent 完成时原地小跳撒星星。代理联动是重头戏：为 ZCode、Claude Code、Codex 三个 agent 各写了一个 hook 安装器（设置面板一键接入/卸载），hook 进程把工作状态写进状态文件，桌宠每秒轮询——

• 你在 ZCode / Claude / Codex 里发任务 → 桌宠头顶亮起蓝色脉冲徽章
• 任务结束（Stop 事件）→ 绿色徽章 + 庆祝小跳 + ”✓ Agent done” 气泡
• 90 秒无事件自动回落，总开关关闭时行为与旧版完全一致

接入采用状态文件而不是本地 HTTP 端口：hook 是一次性进程，写文件最可靠，零防火墙弹窗，而且三个 agent 的 hook 格式虽然不同（ZCode/Claude 是 JSON，Codex 是 TOML），落点完全一致。

这套 AI 开发工作流本身

四轮迭代全部由 AI 辅助完成，但”让 AI 写代码”从来不是难点，难点是让 AI 的产出可以被信任。我固定的流程是五步：

1. 发散（brainstorming）：说清楚意图，AI 结合代码现状提功能包和方案对比，我拍板方向
2. 收敛（grilling）：AI 对设计做决策树拷问——每轮给出一组待决策点并附推荐答案，我只答 “a/b/c”，两轮下来 13 个实现级岔路全部落定
3. 规格（openspec）：生成 proposal / specs / design / tasks 四份工件，规格里每条需求都带可测的 scenario，严格模式校验通过后交给我审
4. 实现（apply）：按 tasks 分组推进，每组一个独立 commit（可单独 revert），tsc + build + 纯函数测试全绿才推送
5. 验收 + 归档：对照 spec 场景手测，通过后归档进主规格库

现在仓库的规格库里有 7 个能力、31 条 requirement。它的价值在第二次开发时才会显现：v1.6 做 agent 联动时，“精灵模式下徽章怎么显示”直接去查 pet-sprite-skin 的规格就知道边界在哪；v1.5 的 XML 解析器天生就知道要兼容两种格式，因为设计阶段就读过真实包的数据。

一个具体的例子：拷问环节有人会问”变量填空留空怎么办？“——答案被写成规格：留空的占位符保留原文，不替换成空串。这条后来避免了无数次”复制出去发现少了半句”的困惑。

Tauri 踩坑清单（都是真金白银换来的）

四轮下来积累的坑，每一条都在真实机器上炸过：

1. .vue 的 script 不被 tsc 检查（项目没上 vue-tsc）。类型错误要在运行时才炸——曾有一个 watch 引用了后文才解构的变量，TDZ 错误直接让桌宠窗口白屏。教训：组合式函数里代码块必须严格按依赖顺序排列。
2. Tauri 2 的 asset 协议默认关闭。convertFileSrc() 生成的 URL 会被拒——图片加载全部静默失败然后回落，看起来就是”功能没生效”。必须显式配置：

"security": {
  "csp": null,
  "assetProtocol": { "enable": true, "scope": ["$HOME/.promptpal/*"] }
}

而且改 tauri.conf.json 必须重启 tauri:dev——热更新对 Rust 侧配置无效。 3. 物理像素 vs 逻辑坐标。monitor.size() 返回物理像素，setPosition 吃逻辑坐标，混用会在 125%/150% 缩放的屏幕上把窗口定位到屏幕外（桌宠”消失”之谜）。用 size.toLogical(monitor.scaleFactor) 换算，cursorPosition() 同理。 4. 透明窗口会拦截整个矩形的鼠标事件，哪怕 90% 是透明的。解法是动态穿透：轮询全局光标位置，只在光标悬停在机器人本体上时 setIgnoreCursorEvents(false)，其余时间整窗穿透。 5. Shimeji 社区包是散帧 PNG（img/shime1..N.png），不是拼好的长条；conf XML 有日文原版和英文两种格式；帧引用普遍非连续（歩く = [1,2,1,3]）；ZIP 里旧包文件名常是乱码——按文件内容识别，别信文件名。 6. 在浏览器里测 Tauri 应用很香：dev server 直接打开面板页面，注入 localStorage 配置后刷新就能复现各种状态机问题，比反复重启 Tauri 快得多。

收尾

项目地址：github.com/Tai-Yng/PromptPal（开源，欢迎来看 specs 目录里的规格库——我个人认为它比代码更值得读）。四轮迭代共 20+ 个 commit，CI 从第一轮之后就没红过。

接下来如果继续，规格库里留了口：Shimeji 行为引擎（解析 conf 的频率/事件定义，让桌宠做真正的自主行为）、可视化帧网格编辑器、垂直漫游爬墙。不过眼下，它已经从一只装饰品变成了我桌面上唯一知道”AI 正在替我干什么”的东西——这只值 80×100 像素。