自己的键鼠,自己的 Hub:一个开源轻量替代方案
TL;DR
复杂系统级项目交给 AI Agent 构建,靠的不是更聪明的单条 prompt,而是两层提示词结构:一份可演进的整体提示词(规格书)承载规格与纪律,一套微调提示词承载决策与纠偏,中间由验证闭环把两者串成活的循环。本文以一个协议逆向 + 原生 C++/Win32 的托盘工具(全程 AI Agent 交付)为案例,给出整体提示词的六个设计、微调提示词的五种句式与三条验证纪律。
只想要可操作的最小闭环,三步就够:
- 写一份规格书当整体提示词——约束先行、需求编号、验收量化、范围外显式列清;
- 日常用五种句式发微调——给现象、拍板带降级、划边界、一词放行、把踩坑回灌进规格书;
- 每步跑固定验证清单——让 Agent 自证、你实机确认,再把结论写回规格书。
三步对应的展开在第四、六、七节。
一、背景:一个全程由 AI Agent 交付的项目
厂商自带的键鼠工具往往臃肿、功能受限,换个设备就得重新适应一套交互。这个项目想做的,是一个轻量、可定制、能替代厂商 hub 的开源工具:给 MCHOSE A7 Pro 鼠标和 EWEADN X87 键盘写一个常驻 Windows 托盘的管理工具——实时电量、DPI/回报率切换、键盘灯效、低电量通知、恢复出厂。技术上要逆向两套私有 HID 协议,用原生 C++17 / Win32 自绘界面,交付单个绿色 exe。
这个项目从第一行需求到最终交付,代码全部由 AI Agent 写的。我全程只做三件事:拍板决策、实机确认、纠偏微调。最终成果:23 个 commit、约 2000 行的主程序、两份协议逆向笔记、一份设备能力采集档案,/W4 零警告编译、无第三方运行库依赖。
项目连同这套方法论一起开源——目的是让每个人都能照着它,给自己的鼠标键盘定制属于自己的 Hub。本文不讨论 HID 协议细节,只讨论提示词思路:整体提示词怎么搭、微调提示词怎么发、两者怎么配合把一个有硬件风险的系统级项目安全落地。
二、问题:为什么”边做边聊”撑不起系统级项目
多数人使用 AI Agent 写代码的默认姿势是对话式即兴指挥:想到哪说到哪,错了就重说。这对脚本和小型页面有效,但面对”协议逆向 + 硬件写入 + 系统级 C++“这类项目,会撞上三堵墙。
第一堵:失忆。 Agent 每个会话醒来都是空白的。昨天敲定的”配置放 exe 同目录”、上周确认的”回报率只做 1K 三档”,它今天全不知道。对话历史不是可靠的记忆——上下文一长,早期结论就被挤出去了。
第二堵:过度发挥。 Agent 天生倾向于”顺手多做一点”。你不画线,它就替你画——通常画在最不该投入的地方。本项目中途就有过这个苗头:改键、宏、逐键灯效这些”看起来该有”的功能,每一项都会把协议面扩大到没有实测支撑的区域。
第三堵:完成定义模糊。 Agent 说”完成了”的标准是”代码能跑”,使用者的标准是”三档 DPI 缩放下绘制与命中一致”。不对齐这个定义,验收就成了每天的扯皮。
三堵墙指向同一个结论:单条 prompt 解决不了结构问题。问题不在措辞,在于缺少持久的规格、清晰的边界和客观的完成定义。
三、核心方法:两层提示词 + 一个闭环
解法是一个刻意简单的模型。提示词分两层,各司其职:
| 层 | 形态 | 职责 | 更新频率 |
|---|---|---|---|
| 整体提示词 | 一份可版本化的规格书文档 | 定义目标、约束、功能、验收、范围外 | 每个里程碑修订一次 |
| 微调提示词 | 对话里的短指令 | 纠偏、拍板、放行、给现象 | 每次交互 |
外加一个闭环:Agent 自证(脚本化验证)→ 人实机确认 → 把结论回灌进规格书。
关键认知是:整体提示词不是”一句话需求”,而是项目的持久上下文——它就是 Agent 的全部记忆。规格书写得越像工程文档,交付物就越像工程师的作品;写得越像愿望清单,交付物就越像 demo。
下面按”整体提示词怎么写 → 怎么用 → 微调怎么发 → 闭环怎么转”的顺序展开。
四、整体提示词:把需求文档当成主提示词来写
本项目的整体提示词就是 需求分析与实现方法.md。它能撑起整个项目,靠的是六个设计。
1. 约束先行,功能在后。 开篇不是功能列表,是一页”定位与约束”表:平台(Win10/11 x64、托盘常驻、免管理员)、形态(单 exe、/MT 静态链接、零第三方依赖)、技术栈(C++17/Win32、HID + Direct2D + WinRT Toast)、运行约束(单实例、消息驱动、日志不落盘)。约束比功能重要——功能决定做什么,约束决定怎么做以及什么算错。“免 VC++ 运行库”这一条约束,直接决定了编译参数、依赖审计方式和验收清单。
2. 功能需求编号化。 每条需求有 ID(如 FR-M7、NFR-13)。好处在微调时立刻显现:说”NFR-13 的内存目标超了”,Agent 精确知道在说哪条,不需要复述上下文。编号还让”完成/未完成”可清点——本项目最后”待做项清零”就是逐条销号的过程。
3. 决策点显式化。 规格书里留一组编号决策(D4 配置位置、D5 分发形态、D6 键盘电量粒度、D7 改键是否进 MVP),每个决策列选项和取舍。使用者只需拍板”D4 选目录便携模式”,Agent 负责把决策落进所有相关章节。决策权在人,展开工作在 Agent——这个分工写进文档结构里,而不是每次靠口头解释。
4. 内部矛盾显式修正。 规格书初稿有 7 处自相矛盾(例如”单线程”与”异步 I/O”冲突、“免管理员”与”配置写 Program Files”冲突)。发现后不是默默改掉,而是列成修正清单留档。对 Agent 来说,矛盾的规格等于随机的规格——它会任意挑一边执行,而且每次可能挑不同的边。
5. 验收标准与功能同权重。 有独立的验收章节和测试矩阵:/W4 零警告、dumpbin 无 VC 运行库依赖、100%/150%/200% 三档 DPI 下界面居中且绘制与命中一致。没有验收标准的提示词,Agent 会把”能编译”当成”做完了”——这正是第三堵墙的解法。
6. 范围外清单。 改键、宏、逐键灯效、自动更新……明确写”不做,且不视为欠账”。这一条直接回应第二堵墙:清单不画,Agent 就替你画。
这套结构可以抽成一个可复用的规格书目录模板。新项目照着填,就能得到一份”工程文档味”足够、Agent 拿到就能干活的整体提示词:
# <项目名> 需求分析与实现方法(整体提示词)
## 1. 定位与约束平台 / 形态 / 技术栈 / 运行约束。约束先于功能,每条写清"这意味着什么、违反了算错"。
## 2. 设备 / 环境事实已实测确认的硬件能力、协议字段、环境前提。区分「已实机验证」与「待验证」。
## 3. 功能需求(编号)每条一个 ID(FR-xx),写清行为与边界。
## 4. 非功能需求(编号)性能、内存、依赖、兼容等,同样编号(NFR-xx),可清点。
## 5. 决策点(编号)每个待拍板决策列选项 + 取舍(D-xx),留空给人拍板,Agent 负责落实到各章节。
## 6. 里程碑与准入准出按阶段切(P0/P1/…),每阶段只写本阶段目标 + 产出物 + 准出条件。
## 7. 验收清单客观、可脚本化核对的完成定义,与功能同权重。
## 8. 范围外清单明确"不做,且不视为欠账",逐项列名。
## 9. 关键坑(改代码前必读)把踩过的坑固化成一句话规则,持续追加。其中”关键坑”那一节是整个模板的收口——它在”验证闭环”部分细说。
五、整体提示词的执行:阶段化推进
有了规格书,执行还要切阶段。本项目分成 P0 能力采集 → P0.5 界面冻结 → P1 骨架 → P2 设备接入 → P3/P4 功能页 → P5–P8 收尾。每次进入新阶段,提示词只包含本阶段目标 + 产出物 + 准出条件,不把后续阶段的细节提前灌进去——规格书是全景,阶段提示词是当前视野,两者分工。
两个阶段的设计值得单独说明。
P0 只写探针,不写主程序。 阶段指令是:“先枚举设备、验证协议字段,产出设备能力表;每验证一个字段固化一个探针工具。“结果是 hid_probe、mouse_probe、kb_probe、rawkbd 这一批一次性小程序先于主程序存在。探针是 Agent 的实机眼睛:它编译运行探针、读输出、写结论,比让它凭协议文档直接写功能可靠得多。协议事实(电量偏移、帧格式、通道选择)全部实测确认后,才允许进入 P1。
P0.5 把界面设计单独冻结。 原因是 Direct2D 为立即模式绘制、“版式即代码”,没有声明式样式层,设计不能滞后于编码。阶段指令明确:“P0.5 产出线框、状态矩阵、视觉规格、交互时序四项,作为 P1 准入条件。“这一节后来确实救了场——P6 发现布局硬编码偏移时,有冻结稿可对照,Agent 才能快速定位”坐标系没集中管理”的根因,而不是逐处瞎调数字。
六、微调提示词:五种句式
日常交互是另一层。开发过程中高频出现的微调提示词,归纳下来是五种句式。
1. 现象反馈式——给现象,不给方案
“大部分 UI 位置偏移,不居中。”
注意没有说”把坐标重构一下”。Agent 排查后的结论是:真实问题不是渲染错位,而是布局硬编码(键盘页三滚轮整体偏左 31px、绘制与命中各写一套数字)。它给出的方案是建立 UiLayout 统一坐标源 + DrawTextAligned 对齐修正。描述症状,让 Agent 当医生;直接开药方,它就只当药剂师——而药方可能是错的,现象永远是对的。
2. 决策拍板式——短句决策,让 Agent 展开
“配置位置用目录便携模式(exe 同目录 config\,只读降级 %LOCALAPPDATA%)。” “键盘电量做到百分比;若只有 4 档就按档位映射并标注’约’。”
拍板要带默认行为 + 降级路径,不要只说”要便携”。Agent 拿到这种指令,能直接落成实现细节(原子写入、.bak 回退、schemaVersion)并同步文档。
3. 边界指令式——限定操作范围,尤其在敏感时刻
“待做功能只留下低电量提醒气泡、恢复出厂设置。修改所有文档和需要修改的地方,不要改代码。”
这是一次范围收敛操作:两项功能刚验收完,最不需要的就是 Agent 顺手”优化”代码引入回归。句式是做什么 + 不许做什么 + 影响面。同理常用的还有一句:“测完把用户原设置写回。”
4. 放行确认式——短到只有一个词
“do it”
对死代码清理(任务栏角标方案,hub.cpp 减 112 行)这类 Agent 已识别、已列方案、风险低的操作,一个词放行即可。前提是 Agent 先给出了改动清单和验证方案。没见过清单就不要放行。
5. 规则固化式——把踩坑回灌进整体提示词
这是五种里最重要的一种,也是闭环的收口。项目里每个大坑被踩平后,都会被写成一句话规则,加进规格书的”关键坑(改代码前必读)“章节:
- 空响应被当成 0% 电量 → “写前必读整包,读失败禁止任何写操作”
- 关灯效被截断成涟漪扩散 → “UI 哨兵值不等于设备值,下发前必须转换”
- 只写 X 轴导致校验误报 → “设备有联动语义时,校验逻辑必须知道”
resource.h中文注释吞掉#define→ “资源头文件保持纯 ASCII”
于是整体提示词是活的:它带着一路踩坑的疤痕进入后续每个会话。微调提示词的最高境界不是纠错,而是让同一个错误永远不需要纠第二次。
五种句式连同另外三条高频指令,汇总如下:
| 场景 | 实际提示词(示意) | 为什么有效 |
|---|---|---|
| 界面偏移 | “大部分 UI 位置偏移,不居中” | 只给现象,逼出根因诊断 |
| 技术决策 | “D4 用目录便携模式,只读降级 %LOCALAPPDATA%” | 决策 + 降级路径一次给全 |
| 范围收敛 | “待做只留低电量提醒和恢复出厂,只改文档不改代码” | 目标收敛 + 操作边界 |
| 死代码清理 | “do it” | 前提:Agent 已列清单与验证方案 |
| 踩坑回灌 | “把这条写进’改代码前必读’” | 错误只犯一次 |
| 测试纪律 | “把 lowBattery 临时改 90 触发,测完改回 15” | 操作可逆性显式化 |
| 协议存疑 | “此归属未实机证伪,先标注待验证” | 允许 Agent 承认不确定 |
| 文档同步 | “改完代码后 README 与需求文档同步更新” | 防止文档腐烂 |
七、验证闭环:让 Agent 自证
微调不能靠信任,要靠闭环。Agent 说”完成了”不算完成——本项目每次改动后的验证清单是固定四条,直接写在规格书里:
/W4零警告编译;dumpbin /dependents确认无 VC 运行库依赖;RCDATA资源可读出且尺寸格式正确(438 × 390 RGBA);- 100% / 150% / 200% 三档缩放下界面居中、绘制与命中一致。
三条配套纪律同时写进去:
- 探针先行:改协议相关代码前,先用探针工具实测字段,不凭文档推断;
- 可逆操作:测 DPI 切换、灯效写入这类会改用户设备状态的功能,测完必须写回原设置;写配置前自动备份,失败回滚;
- 校验脚本化:文档改动跑结构校验(表格列数一致、无 HTML 实体残留、代码块成对),不靠肉眼。
验证清单还有一个副作用:它把”完成”的定义客观化了,微调时不用争论”这算不算好”,只用对照行不行。
至此闭环才转得起来:清单让 Agent 自证 → 人实机确认 → 规则固化式把结论回灌进规格书。两层提示词是骨架,验证闭环是血液循环。
八、三个最容易踩的误区
1. 整体提示词写成功能愿望单。 “做一个很酷的键鼠管理工具”这种提示词,Agent 会给出一个看起来很酷、处处是坑的 demo。约束、验收、范围外三样缺一不可——它们占提示词一半篇幅是正常的。
2. 纠错时只说”你错了”。 “这里不对,重新做”是最低效的微调。给出现象 + 复现步骤 + 期望行为,修正一次到位的概率高得多。从本项目的过程看,现象式反馈的返工明显少于指令式——因为给出的方案经常是错的,而现象永远是对的。
3. 不做范围收敛,项目无限膨胀。 本项目中途做过一次正式的范围收敛:把改键、Y 轴独立 DPI、宏、自动更新等整批划入”已确认不做”,并要求 Agent 把口径同步到所有文档。收敛之后项目很快到达”无待做项”状态。个人项目最大的风险不是做不完,是永远”还差一点”——而 Agent 永远愿意再做一点,画线只能靠人。
九、总结
这套方法的本质是把软件工程里早已存在的东西——规格说明书、变更管理、验收测试、回归防线——重新组织成提示词的两层结构:整体提示词承载规格与纪律,微调提示词承载决策与纠偏,验证闭环承载信任。
Agent 不需要使用者把话说得玄乎。它需要的是:明确的边界、可验证的完成定义、及时的拍板,以及把踩过的坑变成规则的耐心。做到这四点,协议逆向、Win32 自绘、硬件写入这类硬活,都可以交给它完成。
需要说明的适用边界:本文结论来自单个项目(N=1)的完整实践,对 Web 前端、数据管道等领域的普适性未做对照验证;但两层提示词与验证闭环的结构本身不依赖具体技术栈,读者可按自身项目裁剪。
代码、协议笔记和那份充当整体提示词的需求文档都在仓库里,欢迎参考——照着它,你也可以为自己的键鼠做一个 Hub。
支持与分享
如果这篇文章对你有帮助,欢迎分享给更多人或打赏支持!
Hyper Threading




