工具
快来分享你的内容吧～
- 10-15 11:07前言 近期GitHub开源项目REA（Reverse Engineer Anything）短时间斩获17万星标，登顶GitHub Trending。它作为MCP服务端，把Ghidra、IDA、Hopper等逆向工具封装成AI Agent可调用接口，让Cursor、Claude Code等AI智能体自动完成二进制逆向分析。工具能力强大，但存在明确法律边界，仅可用于授权范围内的安全研究。查看全文czheng：⚠️ 免责声明本文仅为开源项目技术科普，仅供学习交流。逆向工程有严格法律边界，未经著作权人书面许可，禁止逆向商业闭源软件，禁止用于破解、盗版、盗用逻辑等行为，相关法律责任由使用者自行承担。REA 输出结果存在 AI 幻觉，所有逆向结论务必人工复核；涉密文件禁止接入云端大模型。评论区不讨论破解相关内容。642分享
10-13 17:00·后端开发大家好，我是不会喷火的小火龙。 过去大半年，“Vibe Coding”成了技术圈讨论最多的词。 几句自然语言 Prompt，十分钟就能让 AI 搓出一个界面漂亮、能跑能点的原型。那种即时出成果的快感，确实让人很难再适应纯手写代码的节奏。 但如果试着用这套方式，从零打磨一个跨多个业务模块、需要长期维护的真实项目，大概率很快就会遇到现实瓶颈： 代码行数超过两三千行，上下文窗口变大之后，AI 开始自相矛查看全文加油鸭：太棒了！把 Vibe Coding 从“爽感玩具”升级为可持续工程实践，这份深度思考和开源贡献超有价值！635分享- 09-20 10:42·后端最近把自己开源的 重构了一遍。 做这个 Skill 的原因一直没变。 现在用 Codex、Claude Code 做项目，写代码已经越来越省事。问题慢慢跑到了另外一边：项目做久以后，Agent 开始忘，文档开始乱，方案改过几轮没人记得，代码写完了也不知查看全文加油鸭：太棒了！把项目状态管理得这么清晰又实用，这份重构思路既有深度又超接地气，为 Vibe Coding 项目提供了真正可持续的协作骨架！91015分享
- 09-08 14:11·后端开发
- 08-30 14:50·后端开发
08-28 15:54·人工智能DeepSeek Harness（dsh）是由 DeepSeek AI 开发的开源 agent harness（智能体框架）。总结Windows系统下如何安装，方便各位开发者使用。查看全文CRZZX：刚刚对比测试了一下，同样接入deepseek-v4模型，同样的提示词，作比较复杂的任务，dsh不如codex一根，效率差的有点多，前者要等好久才能搞定任务，起码有三十多分钟，codex十几分钟就搞定了，初步测试😂452分享- 08-28 13:51·后端开发
- 08-05 10:48·云兮导航: https://www.xd
总在找刚才复制的东西，我给 Mac 做了个「剪巢」
我用 Mac 时，经常会被一件小事打断：**明明刚复制过的东西，转头又得找一遍。** 比如复制了一段代码，准备切回编辑器，中途又顺手复制了一个链接。等按下 `⌘V`，代码没了，链接来了。 只好回去翻网页、翻聊天记录。东西倒也没真丢，就是得再找一次。好不容易接上的思路，也跟着断了一下。 一次两次无所谓，碰多了，我就想：能不能把复制过的东西先留住，需要时叫出来，直接接着用？ 于是，我做了 **剪巢**。 它是一个待在 Mac 菜单栏里的剪贴板历史工具：把复制过的文字、图片、文件引用存在本地，想用时按快捷键，搜一下，选中回车，就能贴回刚才的输入位置。 不用注册账号，也不用先整理分类。正常复制就行，需要它的时候再打开。  *本文配图使用演示内容，图内保留了「演示」标识。* 源码和安装包已经放到 GitHub，**免费使用，MIT 协议开源**： **[项目主页](https://github.com/fenfeicn/jianchao) · [下载安装包](https://github.com/fenfeicn/jianchao/releases/latest)** 下面就聊聊，它具体替我省了哪些麻烦。 ## 找到那段代码以后，回车就能用 我最在意的，其实不是历史里能存多少条，而是找到以后，能不能顺手用上。 正在编辑器里写东西，想找回刚才那段代码，我希望整个过程是这样的： **点好输入位置 → 按 `⌥⌘V` → 搜关键词 → 选中 → 回车。** 剪巢会收起面板，回到刚才的应用，尝试直接粘贴。首次使用需要按引导开启系统权限，之后就不用每次再点复制、切窗口、按粘贴了。 如果要用的就在眼前，面板打开后还可以按 `⌘1` 到 `⌘9`，使用当前列表的前九条。先搜过关键词的话，数字对应的就是搜索结果。 这个小地方对我挺有用。有时只是在两三段内容之间来回搬，手不用离开键盘，事情就能接着做。 当然，也有只想把内容先拿出来的时候。比如还没决定发到哪个窗口，或者某个软件不接受直接粘贴。这时按 `⌘Return`，只把内容放回剪贴板，之后自己按 `⌘V` 就行。 默认呼出快捷键是 `⌥⌘V`，跟已有习惯冲突的话，可以在设置里改。 ## 找图片，还是让眼睛来比较快 文字还能靠关键词找，图片就不一样了。 有时候想找一张聊天里复制过的图，只记得大概长什么样。让我从一串文件名里认出来，确实有点为难。 所以剪巢的图片历史会显示缩略图，选中后在右边直接预览。扫一眼，就知道是不是那张。  想看得更清楚，可以点击图片，或者按 `⌘Y` 放大查看。找参考图、截图，或者把一张图换个地方再发一次，都不用先另存到桌面。 微信、QQ 这类应用里的单张图片，只要复制时提供了可读取的图片数据或文件，剪巢就会尽量保存图片本身，减少临时文件失效带来的问题。具体还要看来源应用交给剪贴板的内容。 不过，**从 Finder 复制的文件和多文件记录，保存的是原文件引用**。原文件移动或删除后，记录可能失效；它不能代替文件备份。 ## 长内容不用从头读，先找要看的那一处 还有一种复制，内容虽然找回来了，人却不想看了。 一大段代码、一长串接口返回，铺满整个预览。我只是想确认某个字段，结果又得从头往下翻。 现在选中一条文字后，按 `⌘F`，就能在当前内容里查找。关键词会高亮，`⌘G` 找下一个，`⇧⌘G` 回到上一个。长文本也会自动显示行号，方便定位；复制内容时，行号不会一起带走。  这两个搜索，我一般分开用：上面的搜索框找“哪一条”，预览里的查找找“这一条的哪里”。 比如先搜「订单」，找到那段接口内容，再在里面找具体字段，比重新打开原来的页面省心。 预览里目前只做查找，没有加编辑和替换。真要改代码或文案，我还是更习惯把它贴回编辑器。 ## 常用的留一份，记不住的按日期找 有些内容，今天复制完就不会再用了。有些却隔三差五都要找一次，比如一条命令、一句常用回复，或者一段固定格式的文字。 后一种，我会直接收藏。 选中后按 `⌘D`，以后去收藏里找就好，不用等它被新记录一点点挤下去。  另一种情况也很常见：我记不住具体内容，但记得“应该是昨天复制的”。 那就先看昨天。 剪巢支持今天、昨天、近七天、近三十天和自定义日期范围，也能和关键词、内容类型一起筛选。比如只看昨天复制的图片，范围一下就小了很多。  不是每次都得想起一个准确的关键词。有时候，“昨天”“是张图”，已经够用了。 ## 我希望它每天都能用，也每天都看得顺眼 剪贴板工具有点特殊：它平时没什么存在感，但一天可能会打开很多次。 所以我挺在意这个小窗口的样子。文字能不能一眼看清，列表和预览会不会挤在一起，切换时顺不顺手，都会影响我下次愿不愿意再叫出它。 现在的布局是左边找内容，右边看预览。背景用了 macOS 原生材质，橙色用来提示选中和重点操作，正文尽量保持清楚。支持跟随系统，也可以固定浅色或深色。  我想要的感觉是：打开时舒服，拿完东西就走。动画轻一点，别让粘贴一句话也要等半天。 它只待在菜单栏，不占 Dock 位置。应用图标是几张叠起来的纸和一枚橙色小夹子，菜单栏里则用单色图标。名字叫「剪巢」，也就是给这些零零散散的内容找个落脚的地方。 ## 留多久、占多少地方，自己决定 历史能找回东西，也会越积越多。尤其是图片，我不希望用着用着，才发现一个小工具占了一大块磁盘。 新安装默认保留 **30 天、最多 5,000 条，空间预算 500 MB**。想留得久一些，可以延长到半年、一年，也可以选不按时间清理；条数最高两万，空间最高 5 GB。  “不按时间清理”仍然受条数和空间上限约束。收藏受到保护，不会按普通历史的规则自动清掉；如果收藏占满预算，应用会停止新增记录。 清理时，可以只清空普通历史，保留收藏。要连收藏一起删，再用需要确认的「删除全部」。真正重要的资料，还是建议存到文档或文件里。 另外，复制过的东西不一定都想留下。 剪巢没有账号、没有云同步，不会自动上传剪贴内容。**当前数据以明文保存在本地，没有加密，也不会自动识别所有敏感内容。** 所以我也留了暂停记录和「跳过下一次」：临时不想记录，就让它歇一会儿。可以暂停十五分钟，也可以等自己手动恢复；锁屏时同样会暂停，暂停期间的内容不会补录。  ## 装好后，花一分钟试一下 如果你也常常被“刚才复制的那个呢”打断，可以下载试试： **[前往 GitHub 下载剪巢](https://github.com/fenfeicn/jianchao/releases/latest)** 安装很简单： 1. 下载并打开 DMG，把剪巢拖进「应用程序」。 2. 推出安装镜像，从「应用程序」里打开剪巢。 3. 看完首次说明，点击「开始记录」。它会从这时开始保存，无法找回安装前已经被覆盖的内容。 4. 想用回车直接粘贴，按「设置 → 通用」里的引导开启系统权限，再按提示重新启动。 当前安装包尚未完成 Apple 公证，首次打开可能被系统拦截。确认下载来源后，可按提示到「系统设置 → 隐私与安全」中允许打开，无需关闭系统安全检查。粘贴权限入口在不同系统中可能叫「辅助功能」或「设备控制和数据访问」，跟随应用内引导即可。 然后，打开一个普通文本编辑器，依次复制三句话： > 第一杯咖啡 > > 第二杯咖啡 > > 第三杯咖啡 点好输入位置，按 `⌥⌘V`，搜「第一杯」，选中回车。 第一杯回来了，就会用了。 日常先记住这几个按键就够： | 想做什么 | 快捷键 | | --- | --- | | 呼出剪巢 | `⌥⌘V`，可修改 | | 选择并直接粘贴 | 上下方向键选择，`Return` | | 只复制，稍后自己粘贴 | `⌘Return` | | 使用当前列表前九条 | `⌘1`—`⌘9` | | 收藏或取消收藏 | `⌘D` | | 在当前预览中查找 | `⌘F` | | 退出查找／关闭面板 | `Esc`，逐层关闭 | 除呼出快捷键外，表里的操作都在剪巢面板获得焦点时使用。预览查找展开时，回车用于跳到下一个匹配。某个应用不接受直接粘贴的话，可以先用「只复制」，再自行粘贴。 当前版本为 **0.3.6**，安装包同时包含 Apple Silicon 和 Intel 架构，最低系统要求为 macOS 14。目前完整实机验证是在 macOS 27 的 Apple Silicon 设备上完成的，macOS 15、26 和 Intel 设备的体验，也欢迎大家反馈。 --- 我做剪巢，就是想少一点重复找东西，多一点顺着思路把事情做完的时间。 如果它也帮你找回了一段代码、一张图，或者一句刚被覆盖的话，那这个小工具就算帮上忙了。 我是 **hck**。用着哪里不顺手，欢迎到 [GitHub 提 Issue](https://github.com/fenfeicn/jianchao/issues)，或者发邮件到 **87975531@qq.com**。告诉我系统版本、在哪个应用里、做了什么操作，比一句“不能用”更方便定位问题。截图或举例时，记得避开自己的隐私内容。 希望下次再问“刚才复制的那个呢”，我们都不用回去翻聊天记录了。
REA | 爆火GitHub 17万星标，MCP服务端，AI Agent自动逆向二进制程序
## 前言 近期GitHub开源项目REA（Reverse Engineer Anything）短时间斩获17万星标，登顶GitHub Trending。它作为MCP服务端，把Ghidra、IDA、Hopper等逆向工具封装成AI Agent可调用接口，让Cursor、Claude Code等AI智能体自动完成二进制逆向分析。工具能力强大，但存在明确法律边界，仅可用于授权范围内的安全研究。  ## GitHub爆火REA：17万星标的AI逆向工具，大模型自动分析二进制 最近GitHub一个逆向工程开源项目REA（Reverse Engineer Anything，逆向一切）快速出圈，短时间收获17万星标，成为安全与AI Agent圈讨论热点。很多人误以为它是一款全新反编译引擎，实际上REA更像一座**桥梁**，打通大模型与传统逆向工具。 项目仓库：`morluto/rea`，MIT协议，2026年4月创建，10月迎来爆发式增长。核心定位是**MCP服务端**，将Ghidra、Hopper、IDA等经典逆向工具封装成标准化工具能力，直接对接Cursor、Claude Code这类AI编码Agent。使用者无需手动在逆向软件中点来点去，可让AI自主规划并执行逆向任务。 ### ✨ 核心能力 REA无需源码，支持17类文件逆向：原生二进制、APK、JS/Electron程序、HAR抓包文件等。 整套自动化逆向流程： 1. 自动调用底层逆向引擎，执行静态反编译，提取伪代码、函数、字符串与调用关系； 2. 支持动态行为观测、内存读取、IPC和网络协议追踪； 3. 由大模型整合信息，输出带证据的分析结论，甚至生成参考复刻代码，并主动标注分析短板。 分工逻辑很清晰：**AI负责思考、规划、解读伪代码；Ghidra/IDA负责底层二进制拆解**，两者配合完成逆向。 ### 🛠️ 快速上手安装 **前置依赖** Node.js 22.19+/24.11+/26+；底层逆向引擎三选一（免费推荐Ghidra；Hopper、IDA为商业软件，需自备授权）；APK分析额外安装JDK+JADX。 > REA不会自动下载Ghidra/IDA，需要本地提前安装并配置环境变量。 体验推荐用npx直接运行，无需全局安装： ```bash # 引导安装，自动注册至Cursor / Claude Code npx rea-agents setup # 环境自检 npx -y @morluto/rea doctor # 启动MCP服务，供AI Agent连接 npx -y @morluto/rea mcp ``` 全局长期使用： ```bash npm install --global rea-agents rea setup rea doctor rea mcp ``` CLI直接分析文件（不调用AI）： ```bash rea decompile /path/to/your_binary 0x100003f20 rea analyze /path/to/target.apk ``` 安装完成重启AI Agent，MCP自动注册，即可直接对话调用REA。 ### ⚖️ 重点：合法使用边界 依据《计算机软件保护条例》第十七条：软件合法复制品所有人，**为学习研究软件设计思想原理，可实施逆向**。但场景有严格限制。 ✅ 合法使用场景 - 自己拥有完整版权的程序，用于漏洞自查、逻辑审计； - 获得著作权人书面授权，开展安全审计、兼容性开发； - 恶意样本威胁情报、安全研究（禁止传播恶意程序）； - 软件互操作、开发兼容插件； - CTF竞赛、教学靶机学习； - 开源二进制审计，校验编译产物和源码一致性。 ❌ 严禁使用场景 - 逆向商业软件破解激活、DRM，制作注册机、盗版； - 未经许可提取算法逻辑直接商用； - 逆向竞品游戏、App用于不正当竞争； - 利用逆向成果实施入侵、爬虫、服务器攻击； - 逆向带有NDA保密协议的软件； - 公开发布逆向得到的密钥、核心算法。 ### ⚠️ 风险与局限 1. **AI幻觉**：REA只提取伪代码，AI的分析结论会存在幻觉，**所有结果必须人工复核**。加壳、高强度混淆程序，分析效果会大幅下降。 2. **数据安全**：二进制、反编译内容会进入大模型上下文，**涉密内部文件禁止接入云端大模型**，只能搭配本地大模型使用。 3. **商业工具版权**：Hopper、IDA是付费软件，REA不提供授权，使用盗版逆向工具本身违规。 ### 📌 小结 REA最大价值是**降低逆向工程的操作门槛**，把大量重复手动逆向操作交给AI Agent自动调度。对安全研究员、逆向学习者而言是高效辅助工具。 但工具本身没有善恶，门槛降低同时也带来版权滥用风险。使用REA务必守住法律底线，仅在授权场景内使用，同时不能完全信任AI输出，人工复核必不可少。 > 项目地址：[https://github.com/morluto/rea](https://github.com/morluto/rea)
从 0 到 1 可持续 Vibe Coding：我做了一个 harness 工程的开发工作流 Skill
大家好，我是不会喷火的小火龙。 过去大半年，“Vibe Coding”成了技术圈讨论最多的词。 几句自然语言 Prompt，十分钟就能让 AI 搓出一个界面漂亮、能跑能点的原型。那种即时出成果的快感，确实让人很难再适应纯手写代码的节奏。 但如果试着用这套方式，从零打磨一个跨多个业务模块、需要长期维护的真实项目，大概率很快就会遇到现实瓶颈： - 代码行数超过两三千行，上下文窗口变大之后，AI 开始自相矛盾，甚至顺手把之前写好的核心逻辑当成废弃代码重构掉； - 数据表结构全凭 AI 自由发挥，字段缺少约束，加个小功能发现表关联全是乱的，修一个 Bug 反而引爆三个新 Bug； - 屏幕上“暂时能跑”看着很美，底层架构却脆弱，前期省下的编码时间，后期要加倍以排错和返工的形式还回去。 很多开发者折腾到最后忍不住觉得：“AI 只能写写玩具，一碰复杂工程就抓瞎。” 可持续的 Vibe Coding，关键在于分工：人负责规划、架构、约束与最终验收，AI 则在明确的工程化护栏内负责高效执行。标准流程可以参考鱼皮哥的文章 [Vibe Coding 项目开发流程](https://ai.codefather.cn/library/2010974706717888514) 为了解决 AI 容易偏离预期的问题，我结合自己的踩坑经验与工程实践，最近多次迭代并开源了一个开发流 skill：[vibe-workflow](https://github.com/sz-xiaohuolong/vibe-workflow)。它把一套原本需要人肉反复提醒的开发纪律，沉淀成了 AI 可以遵守的规则。 这篇文章主要梳理从 0 到 1 推进一个 Vibe Coding 项目的具体心法，并介绍 `vibe-workflow` 是如何在关键节点起到护栏作用的，后面会在实践过程中持续更新迭代。 --- ## 一、规划比写代码重要：别给 AI 一个模糊的大 Prompt 很多 Vibe Coding 出现偏差，往往在敲下第一句 Prompt 时就已经埋下了隐患。 比如直接对 AI 说：“帮我做一个类似 Notion 的记事本，要有分类、标签和搜索。” 这是一个典型的模糊大 Prompt。AI 收到之后会立刻开始写代码，但在它的逻辑里缺少阶段和优先级。它可能会直接引入三个重型第三方编辑器库，同时实现没有经过验证的复杂树形目录，最后连基础的文本保存都会报错。 模糊的指令很容易产生边界不清的复杂工程。 在让 AI 动代码之前，先把四件事明确下来很有必要： 1. 核心用户路径：用户进入产品后，最核心的一条闭环操作到底是什么； 2. 技术栈与架构选型：为什么选这个框架，状态怎么管理，前后端如何通信； 3. 不做清单（Out-of-scope）：第一版明确不做什么，比做什么更重要，砍掉不必要的衍生需求，只保留核心闭环； 4. 可测试的验收标准：怎样才算做完，比如“创建后刷新页面不丢失”、“空输入提交有明确拦截提示”。 在 `vibe-workflow` 的设计中，这一步被固定为 Thinking 与 Planning 流程。 当提出一个新想法时，工具会先拦截 AI 盲目写代码的冲动。如果需求模糊，它会主动通过提问梳理不做清单与边界条件；在方案没有经过结构化确认之前，在规则层面限制编码权限，避免前期沉没成本过大。 --- ## 二、领域建模：先定数据骨架，再画页面 初学 Vibe Coding 容易陷入的一个误区是视觉优先。 让 AI 一口气生成了十几个页面，界面做得很丰富，返回的数据全是 mock 假数据。等到准备接入真实后端时，才发现数据表结构混乱，底层实体关系根本支撑不了业务流转，只能推倒重来。 数据结构是业务的基石，长期可维护的项目，推导顺序通常是： 业务对象 ➔ 实体关系 ➔ 数据约束（主外键/唯一/索引）➔ 表结构与迁移 ➔ API 接口 ➔ 页面与交互 需要梳理清楚： - 核心实体有哪些，是一对多还是一对一； - 主键、唯一键和外键关系在哪里； - 状态字段如何流转，是否需要软删除； - 数据库变更必须有明确的迁移（Migration）脚本，能从零执行，也能安全回滚。 在 `vibe-workflow` 的规则里，对 AI 设定了明确的代码边界：只要涉及数据结构的调整，必须先写 Migration 迁移和约束校验，不能在未更新数据层的前提下先行拼凑业务代码。同时限制在 UI 组件里直接写 SQL 或越权查库，保持系统底层的整洁。 --- ## 三、上下文工程：给每一个新 AI 会话准备项目说明 使用 Agent 编程常会遇到类似困扰： 昨天聊得好好的，今天新建一个会话窗口，AI 记不住之前的约定；或者写着写着，AI 突然改变了原有的目录规范。 因为 AI 只了解当前窗口里的临时上下文，并不天然理解项目的完整历史。 解决这个问题的关键是做好上下文工程（Context Engineering），核心载体就是项目根目录下的 AGENTS.md。 ### 1. 打造清晰的 AGENTS.md AGENTS.md 规定了 AI 在当前仓库里的行为规范，它不需要重复抄写全部需求，而是明确规则边界： - 项目定位与架构约束：核心目录分别放什么，依赖方向怎样流向； - 权威文档优先级：当代码与需求冲突时以哪份文档为准，避免随意猜测； - 操作规范：哪些核心公共文件未获明确指令不得修改，不随意做无关的大重构； - 完成标准：什么样的状态才算任务结束，比如测试通过、文档同步。 ### 2. 闭环的轻量文档治理 代码会随迭代频繁变动，但核心架构决策需要沉淀在 `docs/` 目录下（如 `docs/architecture.md`、`docs/database.md`）。 在 `vibe-workflow` 中，内置了 `$vibe-workflow init` 命令。接管新项目或旧仓库时，它会自动审计当前工程，提取事实源并建立规则基线。 隔天开启全新会话时，执行 `$vibe-workflow 从仓库事实恢复当前软件项目`，它会自动依据 Git 状态、现有测试用例和文档恢复任务进度，不再依赖零散的聊天记录。  --- ## 四、控制工作边界：最小纵向切片与熔断机制 尽量避免对 AI 下达“帮我把这个系统完善一下”这类大指令。 这种黑盒指令往往会导致 AI 在几十个文件里同时做修改，最后留下难以定位的问题。 可持续的推进方式是采用最小纵向切片（Minimal Vertical Slice）： - 每次只给 AI 指派一个边界清晰的小闭环，比如“只实现登录接口的频率限制，不改动响应格式”； - 尽量拆成小批次的改动，避免一次性合并过大范围的代码； - 审查修改一行权限校验代码，通常比审查十处文案更重要。 同时，在流程中设立熔断机制很有必要。 在实际开发中，容易遇到 AI 陷入反复修改的死循环：为了修一个报错改了 A 文件，导致 B 文件报错，改了 B 文件又导致 A 文件报错。 在 `vibe-workflow` 的 Building 阶段，设定了一条规则：如果连续 3 次尝试遇到同类失败，或者出现破坏已有稳定功能的倾向，Agent 必须立即停止盲改，主动保存当前现场并向开发者汇报原因。 这个机制能确保即使出现调试偏差，影响范围也能被控制在当次的小切片之内。 --- ## 五、Harness 护栏：代码能跑不等于任务完成 围绕 AI 建立的这套工程体系，通常被称为 Harness（工程护栏）。 它由几道防线共同组成： 项目规则（AGENTS.md）+ 结构化任务切片 + 类型系统 + Linter 规范检查 + 自动化测试套件 + 人工最终审查 有了这套护栏，开发者的重心也相应转移：从单纯手动编写语法，转向把控产品方向、系统架构、上下文管理与最终审查。 在 `vibe-workflow` 的生命周期里，一条明确原则是：完成声明必须跟着证据走。 如下图所示，这是 `vibe-workflow` 在项目推进中运行的 7 阶段工程闭环：  在 Testing 阶段，Agent 汇报完成时需要交出对应的检查依据：哪些单测通过了、在运行环境下的响应如何。如果没有配置真实运行环境，则明确列出未经验证的缺口。 同时，遇到较重型的决策时，`vibe-workflow` 可以调度专项工具配合使用： - 需要严苛梳理需求、做全量规划时，可以委派给 gstack 的 autoplan； - 需要严格执行测试驱动开发、拆解细分切片时，可以调度 Superpowers； - 无论外部扩展各自擅长哪块，整体的范围把控、事实记录与下一步决策，依然保留在 `vibe-workflow` 的主流程中。 如下表所示，两种模式在核心维度上的差异很直观： | 对比维度 | 传统放养式 Vibe Coding | vibe-workflow 护栏开发流 | |:---|:---|:---| | 需求把控 | 模糊大 Prompt，想到哪写到哪 | 明确核心路径与不做清单 | | 架构设计 | 视觉优先，页面先行，数据模型混乱 | 数据优先，严格先写迁移与模型约束 | | 会话切换 | 换会话易失忆，依赖聊天历史推断 | 自动从 Git 与仓库事实恢复上下文 | | 编码推进 | 动辄修改几十个文件，难以排查 | 最小纵向切片，连续失败 3 次自动熔断 | | 验收标准 | 只要屏幕暂时能跑就算完成 | 完成声明必须携带测试与运行证据 | | 外部协作 | 多套扩展互相抢占流程、反复提问 | 统一主线管理，按需调度专项能力 | | 最终结果 | 容易形成代码坏味道，后期重构成本高 | 结构清晰、适合长期迭代的工程项目 | --- ## 六、实操：如何把这套工作流接入你的项目 把这套开发流应用到日常开发中，步骤相对直接。 ### 1. 安装扩展 确保本地的开发环境（如 Claude Code 或支持相关规范的 Agent 工具）就绪后，在终端执行以下命令： ```bash npx skills add sz-xiaohuolong/vibe-workflow ``` 安装完成后，该 Skill 就挂载到了 Agent 环境中。 ### 2. 接管与恢复项目的两条核心指令 在实际使用中，比较常用的指令有两条： - 场景 A：接管新项目或既有代码库 刚克隆了一个项目，或者准备把已有仓库纳入规范管理时，在对话中输入： ```text $vibe-workflow init 审计当前仓库，沿用已有文档和构建入口，报告待澄清的事实。 ``` AI 会通读仓库，梳理技术栈、目录规范与现有规则，建立起清晰的开发基线。 - 场景 B：跨会话继续之前的进度 开启新的聊天窗口时，不需要复制之前冗长的聊天记录，直接输入： ```text $vibe-workflow 从仓库事实恢复当前软件项目，并核验下一个待执行的任务。 ``` AI 会检视 Git 状态、当前未完成的切片文档以及测试结果，定位接下来需要处理的任务。 ### 3. 上手建议 初次使用时，建议选一个范围清晰、验收条件明确的小需求来跑一遍闭环： 观察它在动手前是否协助确认好了边界，写代码时是否只修改约定的文件，汇报结果时是否能够对应具体的测试用例。 跑顺几次之后，开发过程会更加可控。 --- ## 写在最后 AI 编程改变了代码生产的节奏，但软件工程本身的基本规律依然在起作用。 现在的关键在于：能不能拆解出清晰的领域模型、能不能制定出合理的工程护栏，以及能不能有效驾驭 AI 工具推进项目。 做好规划与边界约束，让每一部分改动都走在可验证的轨道上，才能真正发挥 AI 编程的长期复利。 --- > 我是小火龙，一个持续在 GitHub 等开源社区挖掘真正好用、能打的高价值项目，同时记录自己用 AI 搓工具、做产品、踩坑填坑全过程的独立开发者。如果今天这篇对你有启发，欢迎关注公众号[小火龙AI 手记](https://mp.weixin.qq.com/s/D5K0hCxLT4U6UWxDypOdvw)，我们下篇见。
学习开源项目时我们应该画哪些图？
大家好，我是不会喷火的小火龙。 刚开始深入看开源项目的时候，我经历过两个极端。 一个是纯靠肉眼硬看。连着翻了三天，几万行代码从头看到尾，自以为搞懂了，合上电脑脑子里依然是一团浆糊。 另一个是把精力全花在画图的排版上。打开 Draw.io，花了一整个下午在画布上拖方块、微调对齐像素、挑选各种莫兰迪配色，画出一张五颜六色的庞大架构图。结果第二天回头看，自己都找不到核心的调用链路在哪里。 后来我才明白，画图真正的价值是帮大脑把复杂的调用和数据流降维，理清骨架，而不是做图表美化。 关键在于什么阶段、带着什么目的、选什么工具、画什么图。 这篇文章把这件事梳理清楚：工具怎么选、常见问题对应什么图、拿到项目按什么顺序画，以及几个容易踩坑的地方。 --- ## 一、工具选型：Mermaid、draw.io、Excalidraw、SVG 各自的边界 很多人问我画图该用什么工具，我的建议是不同场景用不同的工具，不用强求某一款。 ### Mermaid：代码化与版本管理首选 Mermaid 用纯文本语法生成图表，天然支持 Git 版本管理，和 Markdown 完美融合。GitHub 的 README 里直接写 Mermaid 代码就能直接渲染。 它的优势在于修改极快：调整一张图只需要改几行文本，不用打开任何独立的图形编辑器，也特别适合让 AI 帮我们生成初稿。 适合场景：API 调用流程图、Agent 状态执行循环、时序图（Sequence Diagram）、README 技术流程文档。 ### draw.io：正式架构与工业级排版 draw.io（diagrams.net）完全免费开源，组件库非常全，自带 AWS、GCP、Azure 和 K8s 的官方图标集。它的连线锚点吸附精准，支持复杂的多层对齐。当你需要画一张正式的技术方案图或论文架构图时，它最稳妥。 适合场景：微服务架构图、云原生与 K8s 部署拓扑、技术方案设计图、PPT 汇报图。 ### Excalidraw：讨论方案与直观教学的手绘白板 Excalidraw 的手绘质感能降低心理门槛。画出来的线条带着手绘感，不会让人觉得是不可更改的最终定稿，反而能鼓励大家提出修改建议。 适合场景：早期技术方案讨论、团队白板脑暴、教程里的直观概念解释图。 ### SVG：矢量控制与极简图形 SVG 本质是 XML 代码，可以精准控制每一个节点与路径，无限放大不会模糊，文件体积极小。 适合场景：极简矢量插画、高质量技术信息图、Logo 与技术图标。 ### AI 生图：概念隐喻与视觉呈现 如果不需要精确的技术细节，只是想表达某种技术概念的反差或情绪隐喻，用 Midjourney 或 GPT-4o 生图效率最高。 适合场景：技术博客与公众号封面、宏观概念反差插画。 如下表所示，我把常见的开发场景与推荐的绘图工具整理成了对照表： | 开发场景 | 推荐工具 | 选型理由 | |:---|:---|:---| | API 调用流程 | Mermaid | 纯文本代码化，Git 可版本控制，AI 生成方便 | | Agent 执行流程 | Mermaid | 状态循环与条件分支表达清晰 | | UML 时序图 | Mermaid | 语法简洁，`sequenceDiagram` 原生支持强 | | 微服务架构图 | draw.io | 组件库全，锚点吸附准，适合复杂拓扑 | | 云 / K8s 架构 | draw.io | 内置各云厂商与 K8s 官方图标 | | 论文系统架构 | draw.io / SVG | 矢量导出，排版精度容易对齐 | | 方案讨论草稿 | Excalidraw | 手绘风格心理门槛低，方便随时修改 | | 教程解释图 | Excalidraw | 风格柔和，降低读者的理解门槛 | | README 技术流程 | Mermaid | 直接在 Markdown 中渲染，无需上传图片文件 | | PPT 高质量信息图 | SVG / draw.io | 矢量无损缩放，支持精细排版 | | 博客 / 公众号封面 | AI 生图 | 视觉冲击力强，易于传达情绪 | | 概念视觉 | AI 生图 | 适合抽象概念的隐喻呈现 | | 极简矢量插画 | SVG | 代码可控，文件体积极小 | | Logo / Icon | SVG | 矢量无限缩放，保持视觉规范统一 | --- ## 二、问题驱动：想搞清楚什么问题，就画什么图 画图容易犯的错误是把静态依赖、动态调用和部署环境全揉在一张图里，箭头到处穿插，最后画成一张谁也看不懂的蜘蛛网。 画图的核心是问题驱动：心里有什么疑问，就画什么图去回答。 工程中常见的核心问题，可以按照从宏观到微观分为四个层次。如图所示：  下面挑几个最常用的具体拆解： **系统架构图**回答项目整体是干什么的。重点标出前端、后端、AI 模块、数据库、消息中间件以及第三方外部服务的边界，让人一眼看清系统的大致构成。 **模块图与组件图**回答项目由哪些模块组成。重点是标清每个模块的单一职责，以及模块之间的单向依赖关系。 **调用链图**回答一个请求穿透了哪些代码。从 Controller 到 Service，再到数据访问层，梳理出入口到出口的调用路径。 **时序图**回答不同对象之间的调用顺序。谁先发起调用、返回什么、是同步等待还是异步通知，时序图最适合表达这类时序关系。 **数据流图**回答数据从哪里来、到哪里去。顺着请求参数，看它在内存里被转换成了什么对象、通过消息队列发送了什么格式、最终持久化到了数据库的哪些字段。 **状态图**回答核心对象的状态迁移规则。比如订单从待支付到已支付、已发货的生命周期，或者 Agent 记忆提取时的添加、更新、删除判定。 **Agent Workflow 图**回答 AI Agent 怎么循环运转。LLM 推理、工具选择、执行反馈、记忆读写、条件路由，这些用带有判断条件的状态图画出来最为直观。  --- ## 三、实战闭环：学习开源项目的 6 步画图 SOP 拿到一个陌生的开源项目，具体可以按下面这 6 步来画。如图所示：  ### Step 1：跑起来项目，画系统架构图 这是第一步。先别扎进源码，顺着 README 的 QuickStart 把 Demo 跑通一遍，感受一下输入输出和交互方式。 项目跑起来后，画一张粗粒度的系统架构图：前端在哪、后端在哪、用了什么数据库、调了哪些第三方接口。这张图不需要任何代码细节，把黑盒变成灰盒即可。 ### Step 2：看 README 和目录结构，画模块图 不深入具体文件，只看一级目录名和项目文档说明。弄清楚项目分了几个主要模块、各模块负责什么业务、它们之间的大致依赖方向。 画出来的模块图应该能解答一个问题：如果后续要改某个功能，应该去哪个目录下找。 ### Step 3：选一个核心功能，画业务流程图 在所有功能中，选出最常用的一条主线（Happy Path）。比如电商项目选下单支付，Agent 项目选用户提问到输出回复，知识库项目选文档解析到检索召回。 画出纯业务视角的流转步骤：从哪里触发、经历几个阶段、产生什么结果。这一步暂时不涉及具体的代码和类名。 ### Step 4：从入口开始追踪源码，画调用链或时序图 找到入口函数（比如 Controller 接口或 CLI 命令），顺着刚才挑出的业务主线单向跟读代码。 这里有个关键原则：只跟正常流程的主干，先忽略异常重试、参数兜底和日志打印。把一条请求流经的关键类和方法串联起来。涉及多个对象协同的，画时序图往往更清楚。 ### Step 5：分析关键参数与消息传递，画数据流图 把目光从代码调用转移到数据本身。请求携带的入参是什么结构，在中间层被解组成什么对象，有没有通过消息管道流转，最终落盘时的表结构是怎样的。 数据流图能帮我们理清核心业务实体在整个系统里的流动全貌。 ### Step 6：遇到复杂结构按需补图 前 5 步已经能帮我们掌握系统的大致脉络。遇到某些局部复杂度高的模块，再针对性补充： - 数据库表关联较多，补一张 ER 图 - 类继承和接口抽象层级较深，补一张类图 - 实体状态迁移规则较多，补一张状态图 - 涉及智能体自主决策，补一张 Agent Workflow 流程图 - 涉及上线部署和容器编排，补一张部署架构图 举个例子，如图所示，一个典型的 AI Agent 循环执行图如下：  Agent 的核心机制包含推理、判断、工具调用、观察反馈与再次推理。这类包含循环与条件分支的结构，用状态图能够把每一次跳转的条件表达得清晰明了。 --- ## 四、画架构图容易踩的 3 个坑 很多经验丰富的工程师画出来的图线条不多，但表达很精准。他们通常会注意避开这几个常见误区： ### 1. 试图在一张图里展示所有细节 如果一张图在 30 秒内没办法让读者看明白核心逻辑，说明它的信息量过载了。 不少人画图习惯把所有技术栈图标全摆上去，每个方块之间拉满箭头，最终变成一张庞杂的连线网。好的架构图通常是做减法的结果，画出来的模块越克制，沟通成本越低。 ### 2. 第一版图就塞入大量分支逻辑 第一版架构图最好只关注标准的正常流程。 如果一上来就把重试策略、熔断降级、权限校验、日志打点全画进去，主干流程就会被杂音淹没。先把正常主干画清晰，有需要再为复杂的边缘逻辑单独画子图。 ### 3. 脱离源码之后图无法自解释 判断一张图是否清晰的标准很简单：不看源码的情况下，把图拿给同组的工程师看，对方能不能在短时间内看懂业务逻辑和流转顺序。 如果必须边看图边翻源码才能明白箭头在表达什么，说明图上的职责边界或数据流向还没有梳理到位。 --- ## 写在最后 画图本身并不是目的，通过画图建立对系统的全局理解才是目的。 代码细节随时可以让 AI 协助编写或查找，但能把复杂系统抽象为清晰结构的能力，是工程师长期积累下来的关键基本功。 下次看一个陌生的开源项目时，可以先别急着逐行读代码。先问自己当前最需要弄清楚什么问题，选好合适的工具，把那张对应的图画出来。 --- > 我是小火龙，一个持续在 GitHub 等开源社区挖掘真正好用、能打的高价值项目，同时记录自己用 AI 搓工具、做产品、踩坑填坑全过程的独立开发者。如果今天这篇对你有启发，欢迎关注公众号「**[小火龙AI 手记](https://mp.weixin.qq.com/s/u_bHjYo00gbDJUk8bTkrdA)**」，我们下篇见。
Project Vibe Spec 大升级：我想解决 Vibe Coding 项目越写越乱的问题
> 开源地址：[github.com/dnwwdwd/project-vibe-spec](https://github.com/dnwwdwd/project-vibe-spec)如果对你有用，GitHub 上点个 Star 是最实在的支持 ⭐ 最近把自己开源的 `project-vibe-spec` 重构了一遍。 做这个 Skill 的原因一直没变。 现在用 Codex、Claude Code 做项目，写代码已经越来越省事。问题慢慢跑到了另外一边：项目做久以后，Agent 开始忘，文档开始乱，方案改过几轮没人记得，代码写完了也不知道到底验证到什么程度。 这种问题对 Vibe Coding 用户影响尤其大。 很多人不会逐行 Review 代码，我自己做一些项目时也不会每次把几百上千行 diff 从头看到尾。我更容易确认的是页面有没有做对、流程是不是我想要的、数据语义有没有问题、最后能不能跑。 一旦项目做几个月，光靠聊天记录就撑不住了。 这一轮 Agent 记得为什么这么改，换个 Session 可能就不知道了。PRD 还写着旧方案，代码已经跑到第三版。某个功能之前只做了 POC，过几轮以后 Agent 开始把它当成正式能力。数据库里多了一张表，几个月后没人知道当时为什么拆。 还有一种很常见。Agent 改完代码以后直接告诉你"已完成"，结果测试没跑，UI 没打开，migration 没验证，Windows 也没测。 我之前写 `project-vibe-spec`，主要就是在补这些东西。 ## 旧版已经能管需求，但有点重 之前的 Project Vibe Spec 已经有一套比较完整的流程。 一个需求进来以后，会经过需求确认、REQ、方案决策、实现、测试、Progress 更新。数据库、migration、权限、安全、公开 API 这种不太好回退的改动，还要求先讨论方案，再让 Agent 动代码。 这套流程用了以后，项目确实没那么容易失控。 但它自己也慢慢长胖了。 `SKILL.md` 里面要规定需求怎么分类、什么算跨模块、什么时候建 REQ、什么时候写 DEC、数据库什么时候要确认、Progress 怎么更新、哪些文档一起改、最后怎么验收。项目自己的 `AGENTS.md` 也容易继续往里面塞规则。 时间一长，Agent 接一个很小的任务，也可能先读一堆跟当前工作没关系的内容。文档都在，Agent 的上下文反而越来越重。 ## 现在项目上下文拆成了四层 新版大概是这个结构： ```text AGENTS.md ↓ 判断当前任务应该读什么 DOCUMENT_MAP.md ↓ 找到项目现在认可的文档 PRD / PDD / Design / Flow / DEC ↓ 保存产品、技术、设计和决策 REQ / Bug / Progress ↓ 记录当前正在推进的工作 ``` `AGENTS.md` 现在会尽量保持轻。里面放仓库边界、安全规则、任务路由、高风险操作和通用验证要求。 比如： ```text 修改产品行为 → 读产品文档和相关 REQ 修改 UI → 读设计规范和对应产品规则 修改数据库 → 读技术设计和 DEC 修改 Agent / MCP / 检索 → 读技术设计和业务流程 修 Bug → 读 Bug 记录和受影响模块规则 ``` 表结构、接口字段、当前开发进度、某个功能的详细需求，不继续往根 `AGENTS.md` 里堆。Agent 改哪块，再加载哪块的上下文。 ## DOCUMENT_MAP.md 现在会告诉 Agent 哪份文档能信 这个改动看起来不大，我自己挺在意。 项目做久以后，仓库里经常会出现这种文件： ```text old-design.md architecture-v2.md architecture-final.md prd-new.md some-spike.md ``` 人还能根据名字和 Git 历史猜一下。Agent 可能全部读进去，然后旧方案、新方案、实验记录一起进上下文。 新版的 `DOCUMENT_MAP.md` 会给文档标状态： ```text 现行 参考 缺失 不适用 ``` 例如： ```text 产品事实 docs/product/spec.md 现行 旧版产品设计 docs/archive/product-v1.md 参考 UI Design 缺失 Desktop 架构 docs/desktop-architecture.md 现行 ``` 至少 Agent 进项目以后知道当前应该看哪一份。 ## init 也整个重写了 旧版 `init` 主要围绕 PRD/PDD 和项目总进度工作。 现在执行： ```text $project-vibe-spec init ``` Agent 会先把仓库过一遍。它会检查 `AGENTS.md`、`CLAUDE.md`、README、docs、需求、设计、DEC、Progress、测试、构建配置、schema、migration、部署脚本和一部分实际代码。先弄清楚项目已经有什么，再决定缺什么。 假设一个项目已经用了： ```text specs/product.md architecture/backend.md docs/design-system.md adr/ ``` 新版不会再硬生生补： ```text docs/PRD.md docs/PDD.md docs/UI_GUIDE.md Decisions/ ``` `DOCUMENT_MAP.md` 里直接记现有路径： ```text 产品事实 → specs/product.md 技术事实 → architecture/backend.md 设计规范 → docs/design-system.md 架构决策 → adr/ ``` 跑 `init`，更接近给现有仓库做一次整理和审计。 ## 没有 PRD，就先记没有 以前为了把结构补齐，很容易生成一堆空模板。`PRD.md` 有了，`PDD.md` 有了，`UI_GUIDE.md` 也有了，里面没有多少能指导 Agent 的内容。 这轮把这个行为改掉了。 项目没有 PRD，可以直接记： ```text 产品事实：缺失 ``` 没有设计规范，而且项目根本没有 UI，也可以记： ```text 设计规范：不适用 ``` 后面开发真的需要产品规则，再补 PRD。模板现在只在项目缺这份信息、同时后续工作又需要它的时候才创建。 ## 历史功能也不用补几十个 REQ 一个已经做了几个月的项目第一次跑 init，如果硬套需求台账，很容易一次性生成很多历史 REQ。项目里已经有十几个功能，就补十几个需求记录。这些文件看起来规范，之后基本没人维护。 现在已有功能直接进入"当前实现基线"。 例如： ```text Agent Loop 已验证 PDF 解析 已实现待验证 多模态 PDF 已通过（POC） ``` 从这次初始化往后，新需求和还在推进的大任务再进入 REQ。需求台账里留下来的，基本都是后面还会继续看的内容。 ## "代码已经写了"单独变成一个状态 这次加了一个状态： ```text 已实现待验证 ``` 现在 Progress 有这些状态： ```text 已验证 已实现待验证 已通过（POC） 进行中 待开发 待拆分需求 待澄清 不纳入 ``` 加这个状态就是因为 Coding Agent 太容易把代码完成和功能完成混在一起。 仓库里已经有实现，只能说明代码存在。测试没跑完，就写"已实现待验证"。只验证过一个 Demo，就写"已通过（POC）"。有对应测试、构建结果或者真实用户路径验证以后，再写"已验证"。 对于不太看代码的人，这个区分比多一份技术文档有用得多。至少你问 Agent"这个功能做完没有"，它不能只因为搜到了代码就回答完成。 ## 数据库这种改动我还是卡得很死 这轮删了不少文档负担，但数据库规则没放松。 Agent 想加表、加字段、改索引、迁历史数据、删数据或者改 ORM schema，还是先调查。我要看到这个字段表示什么，谁写，谁读，旧数据怎么办，能不能为空，有没有唯一约束，需要什么索引，上线怎么迁，失败以后怎么处理。方案确认以后再改。 Vibe Coding 里面，数据库被连续改错几轮，比一个按钮颜色错了麻烦得多。这块宁愿多一次确认。 ## 这版对不 Review 代码的人有什么用 Project Vibe Spec 解决不了所有代码质量问题。竞态条件、慢 SQL、隐藏的安全问题、边界异常，该测还是得测，该 Review 还是得 Review。 我更关心的是另一个问题。 很多 Vibe Coding 项目做着做着，用户已经不知道项目现在是什么状态了。 需求当时怎么确认的？Agent 为什么用了这个方案？这个实现是临时的还是正式的？POC 后来有没有进正式版本？文档和代码现在该信哪个？哪些地方写完了还没测？下一次开新 Session 从哪里继续？ 这些信息如果全在聊天记录里，换个 Agent、换个工具或者隔一个月回来，很容易断。 新版 Project Vibe Spec 会尽量把这些信息留在仓库里。以后无论用 Claude Code 还是 Codex，Agent 先从 `AGENTS.md` 进入，根据任务找到 `DOCUMENT_MAP.md` 里的现行文档，再读对应的需求、决策和进度。 聊天记录可以丢，项目自己的状态还能接着用。 这次重构完以后，Project Vibe Spec 少了一些"必须创建什么文件"的规定，多了一套让 Agent 找到当前可信信息的办法。对大量用 Agent 写代码、又不会每次认真 Review 全部 diff 的开发方式，这比继续加几十条规范有用。 如果这套思路对你有帮助，去 GitHub 点个 Star 吧：[github.com/dnwwdwd/project-vibe-spec](https://github.com/dnwwdwd/project-vibe-spec) ⭐
告别 Agent 研发失控：vibe-workflow 实战指南
## 本节重点 用 Cursor、Claude Code 或 Antigravity 写代码时，很多同学都有过类似的体会：让 Agent 写个独立的辅助脚本或单文件 demo，通常很顺手；但如果把它放进一个现有的多文件项目里做多轮迭代，往往很容易失控。比如顺手改掉没让它动的基础库、改错一个地方后进入反复修补的死循环，或者换个对话窗口就把之前的设计细节忘光。 这篇文章介绍我开发的开源 Agent Skill —— vibe-workflow，以及它在微信小程序 moneyRecord（清新记账）中的实际用法。 本文主要包含四部分内容： - 分析 Coding Agent 在多文件项目中失控的常见原因； - vibe-workflow 的状态机与四条核心约束； - 以 moneyRecord 小程序 v0.2.0（月度预算与每日走势图）为例，看需求冻结、垂直切片到自动化验证的完整流程； - 在自己的项目中接入 vibe-workflow 的配置方法。 前置条件：有基本的 Git 使用经验，日常用过至少一款 AI 编程工具。 ## 一、为什么 Coding Agent 容易把项目改崩？ 在多轮需求开发中，Agent 常见的问题主要有四类： ### 1. 范围膨胀（Scope Creep） 让 Agent 把某个保存按钮改成异步提交，打开 Git Diff 却发现它顺带重构了全局请求封装，甚至把原本做好的异常处理删掉了。给 Agent 编码权限，很容易被模型理解为可以随意调整业务和架构范围。 ### 2. 反复修补 遇到报错或单测失败时，Agent 的第一反应往往是就地加补丁：第 10 行报空就加一层判断，第 25 行受影响又补一个容错。几轮交互下来，Token 耗费不少，底层设计越来越乱，最初的问题依然没解决。 ### 3. 上下文随会话丢失 聊天窗口的上下文有限，一旦会话被压缩或者新开对话，模型就失去了之前的上下文。哪怕重新粘贴 Prompt，它也很难准确还原上一轮为什么这么设计、哪些模块已经测通。 ### 4. 虚假完成 模型经常在回复里宣称“所有功能均已实现并通过测试”，但实际运行或者跑单测时往往直接报错。没有真实的命令输出做佐证，模型的口头确认并不能作为交付依据。 这些问题的根源，通常不在于模型单点写代码的能力，而在于开发过程缺少生命周期管理和工程约束。如果不能把确定性的流程规范和模型自身的生成能力结合起来，Agent 的多轮产出就很难稳定。 ## 二、vibe-workflow 的机制与核心约束 vibe-workflow 是一个生命周期编排器（Orchestrator）。它用一套状态机把需求澄清、规格编写、架构设计、分步实现与测试验证串联起来，约束 Agent 在每一步的动作边界。 ```text REQUIREMENTS_FROZEN (需求冻结) ↓ SPECIFIED (行为规格) ↓ DESIGNED (架构设计) ↓ PLANNED (实施计划) ↓ BUILDING (垂直切片实现) ↓ VERIFYING (证据验收) ↓ READY_TO_SHIP (就绪发布) ↓ RELEASED (正式归档) ``` 在这个流程中，有四条核心规则： ### 1. 需求必须先冻结，实现细节可委派 项目或版本在写代码前，必须满足： ```text Requirement Status == FROZEN Open Questions == None Current Release ID exists Acceptance Goals are testable ``` 只要还有未确定的需求疑问，或者状态未标记为 FROZEN，Agent 就必须停下来，不能直接生成业务代码。产品的边界由人决定，具体实现细节才由 Agent 负责。 ### 2. 仓库是唯一记忆，聊天只是临时通道 不把设计方案和任务进度留在聊天记录里，而是统一保存在代码仓库的 `docs/vibe/` 目录下。 新开会话或切换窗口时，Agent 只需要读取 `docs/vibe/PROJECT.md` 和 `docs/vibe/PROGRESS.md`，就能获取当前状态，不需要依赖人工手动同步聊天上下文。 ### 3. 普通修改自主推进，关键事项走决策门禁 私有函数命名、小文件重构、本地单测等日常编码由 Agent 自行决定。但如果涉及产品范围调整、公共接口兼容性变动、数据库结构迁移、安全策略以及最终发布，Agent 必须停下来给出方案，等待人工明确确认。 ### 4. 没有新鲜的验证证据，不得声称完成 任务完成的判断标准只有一条：终端实际执行的测试命令或检查输出。必须有当前轮次跑通的测试日志，且覆盖既定的验收目标，才能把状态流转到完成。 此外还有一项熔断规则：如果 Agent 就同一报错连续修补 3 次仍未解决，或者改好一处导致其他两处出现新错误，必须停止打补丁，记录当前断点，重新审视架构或方案后再继续。 ## 三、实战：微信记账小程序 moneyRecord 以正在开发的微信原生记账小程序 `moneyRecord` 为例。在 v0.1.0 跑通基础记账与分类后，我们通过 vibe-workflow 推进 v0.2.0 的月度预算与收支趋势分析功能。 ### 1. 需求冻结与目标定义 (`PROJECT_BRIEF.md`) 在 `docs/vibe/releases/v0.2.0/PROJECT_BRIEF.md` 中，我们把本期范围和排除项写清楚，并将状态置为 FROZEN： ```markdown ## Requirement Control - Requirement Status: FROZEN - Current Release: v0.2.0 - Approved By: User ## In Scope (v0.2.0) - [x] 月度预算管理: 支持设置、修改或关闭月度预算限额；本地持久化。 - [x] 首页预算进度展示: 首页汇总卡片展示进度条、剩余预算、已用百分比。 - [x] 超支提醒机制: 预算超支时进度条呈现珊瑚红并标注“超支 ¥XXX”。 - [x] 每日收支趋势图表: 统计页新增基于 Canvas 2D 的每日收支趋势图。 ## Out of Scope - 分类独立子预算 - 年报与跨年度对比 - 多账户管理 ## Acceptance Goals | Goal ID | 可观察目标 | 验证方式 | |---|---|---| | GOAL-201 | 用户可成功设置月度预算，首页即时展示剩余预算与已用进度条 | 查看首页卡片渲染与数据 | | GOAL-202 | 当月支出未超预算时进度条为清新绿色；超支时变红并计算差额 | 录入超预算数据检查状态机 | | GOAL-203 | 统计页准确绘制当月每日收支趋势图表，柱状高度与金额匹配 | 自动化单测计算趋势聚合数据 | | GOAL-204 | 切换统计月份时，趋势图与每日数据自动同步更新 | 切换历史月份核对 | ## Open Questions - None ``` 明确了 Out of Scope 之后，Agent 就不会擅自去写多账户或分类子预算相关的逻辑。列出 GOAL-201 到 204，也让后续验收有了具体的比对标准。 ### 2. 行为规格与设计先行 (`SPEC.md` 与 `TECH_DESIGN.md`) 编码前先定义关键状态和计算规则。比如针对预算监控，在规格中先写明状态机： ```javascript const BUDGET_STATUS = { HEALTHY: 'HEALTHY', // 已用 < 80% (绿色) WARNING: 'WARNING', // 80% <= 已用 <= 100% (橙色) OVER_BUDGET: 'OVER_BUDGET'// 已用 > 100% (红色，计算超支差额) }; ``` 同时在架构设计中规定：UI 层不直接处理聚合，按日汇总的数据逻辑全部收敛到 `utils/recordService.js`，图表渲染使用微信原生的 Canvas 2D 接口。 ### 3. 垂直切片拆解 (`IMPLEMENTATION_PLAN.md`) 不一次性修改所有模块，而是把任务拆成 4 个垂直切片： - Slice 2.1: 预算存储与每日数据聚合服务（`storage.js`, `recordService.js`, `date.js`）。 - Slice 2.2: 预算设置界面与首页卡片联动（`pages/settings/*`, `pages/index/*`）。 - Slice 2.3: 统计页趋势分析与 Canvas 2D 图表渲染（`pages/stats/*`）。 - Slice 2.4: 自动化单测编写与集成验证。 每做完一个切片，Agent 都在 `docs/vibe/PROGRESS.md` 中打钩更新，这样无论中途被打断还是换窗口，接手时都能看到当前进度： ```markdown - [x] Slice 2.1: 预算底层服务与日趋势聚合 (storage.js, recordService.js, date.js) - [x] Slice 2.2: 预算管理界面与超支监控 (settings/*, index/*, record/*) - [x] Slice 2.3: 统计页收支趋势分析与 Canvas 2D 图表 (stats/*) - [x] Slice 2.4: 自动化测试与 v0.2.0 验证 (tests/test_v2.js, VERIFICATION.md, TECH_DESIGN.md) ``` ### 4. 验证与证据记录 (`VERIFICATION.md`) 写完功能后，在终端执行测试： ```bash node tests/test_core.js && node tests/test_v2.js ``` 输出真实的测试结果： ```text --- 开始测试 Slice 1 核心模块 --- ✓ utils/calc.js 测试通过 ✓ utils/date.js 测试通过 ✓ utils/icons.js 测试通过 ✓ utils/categoryService.js 测试通过 ✓ utils/recordService.js 核心领域逻辑测试全部通过！ ======================================== 🎉 自动化测试 100% 通过！ --- 开始测试 v0.2.0 预算与趋势分析模块 --- ✓ dateUtil.getDaysInMonth 测试通过 ✓ storage.js 预算存取测试通过 ✓ recordService.getBudgetStatus 状态机与超支计算测试通过 ✓ recordService.getMonthDailyTrend 每日趋势聚合测试通过 ================================================ 🎉 v0.2.0 自动化测试 100% 全部通过！ ``` 把这些输出记录到 `docs/vibe/releases/v0.2.0/VERIFICATION.md`，确认 4 个 Acceptance Goal 都通过后，状态才正式更新为 `READY_TO_SHIP`。  ## 四、在现有项目中接入 vibe-workflow 将这套流程加入现有项目通常只需要三个步骤： ### 1. 在根目录配置 `AGENTS.md` 在项目根目录创建 `AGENTS.md`，让 Agent 进入工作区时先阅读基础规则： ```markdown # Agent Instructions ## Workflow & Governance 本项目遵循 `vibe-workflow` 软件生命周期管理规范。 ### 核心规则 1. **Constitution**: - 工程开始前必须冻结需求（Requirement Status == FROZEN, Open Questions == None）。 - What to build is frozen. How to build it is delegated. - 不得静默改变产品范围；产品变化必须经过明确的人类决策。 - Repository is memory. Chat is conversation. - 没有 fresh verification evidence，不得声称完成。 2. **事实源**: - 项目总览与索引: `docs/vibe/PROJECT.md` - 当前执行进度: `docs/vibe/PROGRESS.md` - 当前 Release 需求基线: `docs/vibe/releases/<release-id>/PROJECT_BRIEF.md` - 当前架构事实: `docs/vibe/TECH_DESIGN.md` ``` ### 2. 建立 `docs/vibe/` 目录与基础文档 在 `docs/vibe/` 目录下放置两个核心文件： - `PROJECT.md`：记录项目定位、当前版本与测试命令： ```markdown # Project - Project Name: 你的项目名 - Current Release: v0.1.0 - Quality Profile: Standard - Supported Commands: npm test / npm run dev ``` - `PROGRESS.md`：记录当前执行切片与任务状态： ```markdown # Progress - Current Release: v0.1.0 - Current Workflow State: REQUIREMENTS_FROZEN - Operational Status: ACTIVE - Current Slice: None - Next Task: 编写 SPEC.md 行为规范 ``` ### 3. 日常开发指令 配置完成后，日常给 Agent 发指令时就可以按流程推进： - 开新需求时：“按照 vibe-workflow 规范，为我们规划 v0.3.0 的需求基线 `PROJECT_BRIEF.md`，列出需要我确认的问题。” - 新窗口继续工作时：“先读 `docs/vibe/PROJECT.md` 和 `docs/vibe/PROGRESS.md`，确认当前进度后继续执行下一个切片。” 这样可以让 Agent 始终围绕既定的切片和测试目标推进，减少无谓的来回试错。 ## 五、总结与仓库地址 使用 AI 辅助编程，工具的生成速度很快，但如果缺少约束，规模稍大就会带来返工成本。vibe-workflow 的出发点，就是通过需求冻结、仓库持久化记录、垂直切片和测试证据链，把开发过程固定在可控的轨道里。 如果你在开发中也遇到过 Agent 随意改代码或遗忘上下文的问题，欢迎尝试这个工作流。 已在 GitHub 开源： 👉 **https://github.com/sz-xiaohuolong/vibe-workflow** 觉得对你有帮助的话，欢迎去 GitHub 点个 Star 支持一下。也欢迎提交 issue 或 PR，一起交流 Agent 工程化落地的经验。
开发了一个 Agent Skill：把 Vibe Coding 从「想到哪写到哪」，变成可恢复、可验证、可持续迭代的工作流
> 欢迎 Star、体验与贡献： 👉开源地址：https://github.com/sz-xiaohuolong/vibe-workflow ## 背景 先说结论：AI 已经很会写代码了，但「会写」不等于「会把项目做完」 这两年，我越来越频繁地使用 Codex、Claude Code 这类 Coding Agent 做真实项目。 刚开始的时候，体验确实很爽： > 「帮我做一个录音软件。」 几分钟后，目录有了，页面有了，代码也有了。 但项目一旦从 Demo 进入真实开发，问题很快就会出现。 比如： - 需求还没有想清楚，Agent 已经开始搭架构、写代码； - 开发到一半随口说一句「顺便加个功能」，整个版本范围开始漂移； - 新开一个会话，Agent 不知道昨天做到哪里，只能重新猜； - 修一个 Bug 连续 Patch 多次，修 A 坏 B，代码越来越乱； - 代码写完了，但测试没跑、Build 没过，Agent 仍然告诉你「Done」； - v0.1、v0.2、v0.3 的文档混在一起，旧需求重新污染当前上下文； - 你只是让它改一个小功能，它却顺手碰了 Schema、权限甚至外部服务。 这些问题的共同点不是： > **AI 不会写代码。** 而是： > **AI 缺少一套能够约束「什么时候做什么、什么时候必须停、什么才算完成」的软件工程工作流。** 于是我做了 **Vibe Workflow**。 ## 1. Vibe Workflow 是什么？ Vibe Workflow 是一个 **Agent Lifecycle Orchestrator Skill**。 它的职责不是重新发明一套 TDD、Debugging 或 Code Review 教程，而是站在这些专业能力之上，负责整个项目的生命周期编排。 我给它定了一个很简单的边界： > **Grill Me 负责确认做什么；Vibe Workflow 负责可靠地把它做出来。** 换句话说： ```text 模糊想法 ↓ Grill Me / Requirement Clarification ↓ 冻结需求 ↓ Vibe Workflow ↓ SPEC ↓ Technical Design ↓ Implementation Plan ↓ Build ↓ Verify ↓ Review ↓ Ship ↓ Maintain ↺ ``` Vibe Workflow 可以作为统一入口。 如果它发现当前需求还没有冻结，就会停止工程活动，并把需求澄清路由给 `grill-me` 或等价能力；需求满足工程入口条件后，再继续后面的 SPEC、设计和实现。 这也是我最希望它解决的问题： > **让用户不需要自己记「现在该调用哪个 Skill」，而是让 Workflow 根据项目状态完成编排。** *** ## 2. 为什么我不想再用「一个超级 Prompt」管理项目？ 很多 Vibe Coding 工作流最后都会变成一段越来越长的提示词： ```text 先读需求 → 再设计 → 再编码 → 记得测试 → 不要乱改 → 遇到 Bug 要分析 → 记得更新文档 → 记得 Git Commit → ... ``` 问题在于，Prompt 越长，并不代表工程越可靠。 真正稳定的软件项目，需要的是： - 状态； - 事实源； - 决策关卡； - 可恢复的进度； - 清晰的版本边界； - 可验证的完成证据； - 按需加载的上下文； - 专业 Skill 之间的编排。 所以 Vibe Workflow 的核心思路不是： > **给 Agent 更多指令。** 而是： > **给 Agent 一个可以运行的软件工程 Harness。** *** ## 3. 整体架构：三层，而不是一个 Skill 包打天下 我把整个体系分成三层。 ```mermaid flowchart TD A["用户想法 / 新版本需求"] --> B["Requirement Layer"] B --> C["Grill Me / Requirement Clarification"] C --> D["Frozen Requirement Baseline"] D --> E["Orchestration Layer"] E --> F["Vibe Workflow"] F --> G["Capability Layer"] G --> H["Brainstorming"] G --> I["Writing Plans"] G --> J["TDD"] G --> K["Systematic Debugging"] G --> L["Code Review"] G --> M["Verification"] ``` #### 第一层：Requirement 负责把模糊想法问清楚，并冻结当前 Release 的产品范围。 #### 第二层：Vibe Workflow 负责判断： 1. 当前处于什么状态？ 2. 下一步应该做什么？ 3. 哪些动作允许 Agent 自主完成？ 4. 哪些事情必须等待人类确认？ 5. 应该调用哪个专业 Skill？ 6. 结果应该写回哪个项目事实源？ #### 第三层：专业能力 例如 Superpowers 中的： - `brainstorming` - `writing-plans` - `test-driven-development` - `systematic-debugging` - `requesting-code-review` - `verification-before-completion` Vibe Workflow 不复制它们。 它只负责： > **When to invoke what, and where the result becomes durable project state.** ## 4. 第一条铁律：工程开始之前，需求必须冻结 这是整个 Skill 最核心的设计。 新项目或新 Release 想进入 SPEC、技术设计或 Build，至少要满足： ```text Requirement Status == FROZEN Open Questions == None Current Release ID exists Acceptance Goals are testable ``` 如果没有满足，就不能因为用户说了一句： > 「直接做吧。」 Agent 就开始脑补需求。 在 Vibe Workflow 里： > **授权实现，不等于授权定义产品范围。** 我把这条原则总结成了一句话： > **What to build is frozen. How to build it is delegated.** 「做什么」必须由人确认。 但「怎么实现」尽量交给 Agent 自己解决。 例如这些通常不需要反复问用户： - 内部函数叫什么； - helper 怎么拆； - 私有接口怎么组织； - 测试文件放在哪里； - 沿用现有项目规范时，目录怎么安排。 而这些必须经过 Human Decision Gate： - 产品范围变化； - Requirement Change； - Public API Breaking Change； - Database Schema / Migration； - 权限与安全模型； - 破坏性操作； - 新的外部付费服务； - Push、PR、Publish、Deploy、Release。 这解决了两个极端： > 既不让 Agent 擅自替你做产品经理，也不让它为了一个变量名来问你三遍。 ## 5. 一个项目不是一次 Prompt，而是多个 Release 真实项目一定会迭代。 比如： ```text Project ├── v0.1 ├── v0.2 ├── v0.3 └── v1.0 ``` 所以 Vibe Workflow 把 **Release** 作为主要生命周期单位。 每个版本都走一次完整但可裁剪的工程流程： ```mermaid flowchart LR A["REQUIREMENTS_FROZEN"] --> B["SPECIFIED"] B --> C["DESIGNED"] C --> D["PLANNED"] D --> E["BUILDING"] E --> F["VERIFYING"] F --> G["REVIEWING"] G --> H["READY_TO_SHIP"] H --> I["RELEASED"] ``` 这意味着： - v0.1 有自己的冻结需求和 SPEC； - v0.2 有自己的冻结需求和 SPEC； - v0.3 也一样。 不会把所有版本一直追加在同一份 PRD 后面。 ## 6. 为什么我用 SPEC，而不是继续堆一套大而全 PRD？ 我希望 Agent 看到的是明确、可实现、可验证的产品行为。 所以在这个体系里： #### `PROJECT_BRIEF` 负责回答： > **这个 Release 到底要做什么？** 包括： - Problem - Target User - Core Scenario - In Scope - Out of Scope - Constraints - Acceptance Goals - Requirement Status #### `SPEC` 负责回答： > **被冻结的需求，具体应该表现成什么行为？** 例如： ```text REQ-003 Start Recording AC-007 点击开始录音后进入 recording 状态。 AC-008 录制失败时必须显示明确错误，不能静默失败。 ``` 因此，`SPEC` 不是另一份重复 PRD。 它更像： > **冻结需求面向工程实现和测试的 Effective Spec。** ## 7. 历史版本和当前事实必须分开 这是我在长期使用 Coding Agent 后越来越重视的一点。 - 如果把所有东西都当成「Living Document」，历史会被不断改写。 - 如果把所有东西都按版本复制，Agent 又会被历史上下文淹没。 所以 Vibe Workflow 将文档分成两类。 ### Released Artifacts：保存当时发生了什么 例如： ```text docs/vibe/releases/v0.2/ ├── PROJECT_BRIEF.md ├── CHANGE.md ├── SPEC.md ├── IMPLEMENTATION_PLAN.md └── VERIFICATION.md ``` Release 完成后，历史 Artifact 原则上封存。 ### Living Documents：描述项目现在是什么样 例如： ```text docs/vibe/ ├── PROJECT.md ├── TECH_DESIGN.md └── PROGRESS.md ``` 重大架构变化则通过： ```text docs/vibe/decisions/ ``` 持续记录。 这个模型可以概括成： > **Released artifacts preserve history. Living documents describe current truth.** ## 8. `PROGRESS.md`：让 Agent 真正支持「明天继续」 很多人说 Agent 有记忆。 但对软件工程来说，我更相信： > **Repository is memory. Chat is conversation.** 聊天是瞬时的。 仓库才是持久状态。 所以 `PROGRESS.md` 在 Vibe Workflow 里非常重要。 它负责记录： ```text Current Release Current Requirement Baseline Current Workflow State Current Slice Current Task Last Stable Commit Completed Tasks Verification Evidence Known Bugs Blockers Open Decisions Next Task ``` 这样今天关闭 Codex，明天重新打开，只需要： ```text $vibe-workflow 继续当前软件项目，并从仓库事实恢复正确状态。 ``` Agent 会根据 Git、代码、测试和项目文档恢复当前状态，而不是靠聊天记忆猜。 ## 9. Context Governor：不是上下文越多越好 这是我认为 Vibe Coding 很容易被忽略的一点。 很多时候，我们会下意识地认为： > 「多给 Agent 一些上下文，总不会错。」 但长期项目里，大量历史信息本身就是噪声。 所以 Vibe Workflow 默认遵循： > **Minimal Sufficient Context** 例如当前任务只是「实现删除录音」，它应该优先读取： ```text AGENTS.md PROGRESS.md 当前 Release 的 Effective SPEC 对应 REQ / AC TECH_DESIGN 的相关部分 当前 Task 相关代码 相关测试 ``` 而不是默认读取： ```text 全部历史 Release 全部 Bug 全部 Decision 整个 Git History 整个仓库 ``` 目标不是让 Agent「知道所有事情」。 而是让它： > **知道完成当前任务所必需的事情。** ## 10. Tiny / Bounded / Architectural：复杂任务严谨，简单任务不官僚 工程流程一旦做重，很容易走向另一个极端： > 改一个按钮文案，也要写 5 份设计文档。 所以 Vibe Workflow 会同时判断： ```text Task Type + Task Complexity ``` 任务类型包括： ```text NEW_PROJECT FEATURE BUG REFACTOR SPIKE REQUIREMENT_CHANGE ``` 复杂度包括： ```text Tiny Bounded Architectural ``` 例如： | 请求 | 分类 | 处理方式 | | ------------------- | ----------------------- | ------------------------------ | | 「把 Start 改成 Record」 | FEATURE + Tiny | 精确修改、验证，不生成完整设计文档 | | 「增加删除录音」 | FEATURE + Bounded | Acceptance + Task Plan + Tests | | 「增加多设备云同步」 | FEATURE + Architectural | 需求冻结 + 设计决策 + 完整计划 | 我很喜欢这句话： > **Complex tasks are rigorous. Simple tasks are not bureaucratic.** *** ## 11. Decision Gate：风险不是看改了多少行代码 一个改动只有 1 行，也可能非常危险。 例如： ```text isAdmin = true ``` 所以风险不能简单通过「代码量」判断。 Vibe Workflow 会优先检查： - Product - Schema - Security - Destructive Operation - External Service - Shipping 等 Decision Gate。 特别是 Schema 这类改变，不能出现： ```text Agent： “为了实现功能，我顺手给 users 表加了两个字段。” ``` 而应该先： ```text Investigate ↓ Proposal ↓ Options / Trade-offs ↓ Recommendation ↓ Explicit Human Approval ↓ Migration ↓ Verification ``` **调查完成，不等于获得执行授权。** *** ## 12. Circuit Breaker：AI 最危险的不是第一次写错，而是连续自信地写错 这一点我特别想做进 Skill。 典型 Vibe Coding Bug 修复流程： ```text 改一个参数 ↓ 没好 ↓ 再改一个参数 ↓ 又坏一个地方 ↓ 再 Patch ↓ 代码越来越乱 ``` Vibe Workflow 加入了 Circuit Breaker。 当出现： - 同类失败连续 3 次； - 修 A 坏 B/C； - 底层架构假设失效； - 修改范围持续扩大； 就必须： ```text STOP PATCHING ↓ Preserve Last Known Good State ↓ Record Debug Snapshot ↓ Operational Status = REPLAN_REQUIRED ↓ Systematic Debugging / Redesign / Replan ``` 它会区分： > **Retry** 和： > **Replan** 不是所有失败都值得「再试一下」。 *** ## 13. Verification 和 Shipping 必须「两权分立」 这是另一个我非常坚持的设计。 ```text Verification Status = 客观证据说明了什么 Shipping Authorization = 人类是否允许执行发布动作 ``` 比如： > 「测试来不及跑了，先发，我承担风险。」 这是一个合法的业务决定。 但它不能把： ```text UNVERIFIED ``` 改写成： ```text VERIFIED ``` 在 Vibe Workflow 中： > **人可以接受风险，但不能修改事实。** 没有 fresh verification evidence，就不能声称： ```text DONE FIXED VERIFIED READY_TO_SHIP ``` 同时，Push、PR、Publish、Deploy、Release 仍然需要明确的人类授权。 *** ## 14. Build 也不是「读完 SPEC，然后一次性写完整项目」 我更希望开发循环是这样的： ```mermaid flowchart TD A["Select Next Task"] --> B["Assemble Task Context"] B --> C["Inspect Existing Code / Tests"] C --> D["RED：先看到正确失败"] D --> E["Minimal Implementation"] E --> F["GREEN"] F --> G["Refactor"] G --> H["Task Verification"] H --> I["Inspect Diff / Review"] I --> J["Commit"] J --> K["Update PROGRESS"] K --> L["Next Task"] ``` 每个版本内部还可以继续拆： ```text Project ↓ Release ↓ Phase（可选） ↓ Vertical Slice ↓ Task ``` 尽量按照可运行、可测试、可提交的 **Vertical Slice** 推进，而不是先把所有数据库写完、再把所有后端写完、最后一起调试。 *** ## 15. Bug 不应该重新走完整产品流程 如果只是普通 Bug： ```text Bug Report ↓ Reproduce ↓ Evidence ↓ Root Cause ↓ Regression Test ↓ Fix ↓ Verify ``` 但如果调查后发现： > 不是实现错了，而是 SPEC 本身定义错了。 那么： ```text BUG ↓ REQUIREMENT_CHANGE ``` 必须重新经过 Requirement Change Gate。 这可以避免 Agent 为了「修 Bug」偷偷改产品定义。 *** ## 16. 它不是 Superpowers 的替代品，而是编排层 Vibe Workflow 当前已经为专业 Skill 预留了明确的路由。 例如： | 场景 | 推荐能力 | | ------------------------ | ---------------------------------------------- | | Requirement 不完整 | \`grill-me\` 或等价 Requirement Clarification | | Architectural Design | \`superpowers:brainstorming\` | | 多步骤 Implementation Plan | \`superpowers:writing-plans\` | | Feature / Bug / Refactor | \`superpowers:test-driven-development\` | | Bug / Test Failure | \`superpowers:systematic-debugging\` | | 重要 Task / Feature | \`superpowers:requesting-code-review\` | | 完成声明之前 | \`superpowers:verification-before-completion\` | 这也是整个 Skill 的定位： > **Vibe Workflow 负责生命周期；专业 Skill 负责专业动作。** *** ## 17. Before vs After：几个最典型的使用场景 | 场景 | 普通 Coding Agent | Vibe Workflow | | ------------- | --------------- | ---------------------------------------- | | 模糊需求让它「直接做」 | 开始脑补产品和架构 | Requirement Gate 未通过，先澄清并冻结 | | 开发中说「顺便加云同步」 | 直接开始加功能 | 识别 Requirement Change，等待明确决策 | | 改一个按钮文案 | 可能过度规划 | Tiny Task，最小修改 + 验证 | | 想改数据库 Schema | 顺手写 migration | Schema Gate：调查 → 提案 → 人类批准 → 执行 | | Bug 连续修 3 次失败 | 继续 Patch | Circuit Breaker → \`REPLAN\_REQUIRED\` | | 新开会话继续项目 | 依赖旧聊天上下文 | 从 Repository + Git + PROGRESS 恢复 | | 代码写完但没测试 | 「Done」 | 保持 \`UNVERIFIED\` | | 老板说「先发布」 | 可能把发布当验证完成 | Shipping Authorization 与 Verification 分离 | ## 18. 这个 Skill 自己也做了测试 我不希望它只是： > 「一篇看起来很完整的软件工程 Prompt。」 所以仓库里专门保留了 Skill 行为测试： ```text tests/ ├── scenarios.md ├── rubric.md ├── validate_skill.sh └── results/ ``` 当前 V0.1 README 中记录了： - 4 类 control / candidate wording micro-tests； - 20 个批准场景； - 5 个独立审查回归场景。 测试重点不是某个函数返回值，而是 Agent 在压力下是否真的遵守工作流。 例如： - 用户催促时会不会绕过 Requirement Gate？ - Tiny Task 会不会被过度文档化？ - Schema Change 会不会偷跑？ - 连续失败后是否会触发熔断？ - 没有 Fresh Evidence 时会不会假装完成？ - 当前版本是否只读取当前 Effective SPEC，而不是把所有历史版本塞进 Context？ *** ## 19. 如何安装？ 当前仓库已经可以作为 Codex Agent Skill 直接安装。 ### 方式一：在 Codex 中安装 把下面这句话发送给 Codex： ```text 请使用 $skill-installer 从 https://github.com/sz-xiaohuolong/vibe-workflow/tree/main/skills/vibe-workflow 安装这个 Skill ``` ### 方式二：使用 Codex 内置安装脚本 ```bash python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \ --repo sz-xiaohuolong/vibe-workflow \ --path skills/vibe-workflow ``` 安装后，从下一轮会话开始使用： ```text $vibe-workflow 继续当前软件项目，并从仓库事实恢复正确状态。 ``` 对于一个需求还没有冻结的新项目，也可以直接从 `$vibe-workflow` 进入；它会根据 Requirement Gate 判断是否需要先调用 `grill-me` 或等价的需求澄清能力。 ## 20. 如何使用？ 安装完成、从下一轮会话开始后，Vibe Workflow 主要有三类用法。 1）**新项目从零开始。** 对一个需求还没有冻结的新项目，直接对 Codex 说： ```text $vibe-workflow 我想做一个录音软件 ``` 它会先检查 Requirement Gate：需求未冻结就暂停工程活动，先路由到 `grill-me` 或等价的需求澄清能力；需求冻结后再自动进入 SPEC、设计、Build、Verify、Review、Ship 的后续流程。 2）**继续昨天的项目。** 每天开始工作时说： ```text $vibe-workflow 继续当前软件项目，并从仓库事实恢复正确状态。 ``` Agent 会根据 Git、代码、测试和 `PROGRESS.md` 恢复当前状态，而不是靠聊天记忆猜。 3）**日常迭代与 Bug 修复。** 新增功能就把需求说清楚，交给 Workflow 走一次 Release 流程；修 Bug 就直接描述现象，它会走「Reproduce → Root Cause → Regression Test → Fix → Verify」；想改 Schema 或发布，它会先触发对应的 Decision Gate，等你明确授权后再执行。 使用上记住三句话即可： > **你确认做什么，实现交给 Agent；发布与破坏性操作必须你点头；没有验证证据，Agent 不能说 Done。** ## 21. 哪些人可能适合用它？ 如果你只是让 AI： > 「帮我写一个正则表达式。」 那你大概率不需要它。 但如果你在做下面这些事情，它可能会比较有价值： #### 个人开发者 使用 Codex / Coding Agent 从 0 到 1 做真实项目，希望几周、几个月后仍然能继续维护。 #### Vibe Coding 重度用户 已经发现「生成代码很快，但控制代码熵和需求漂移越来越难」。 #### Agent 工程实践者 希望把 Requirement、Design、Plan、Build、Verification、Release 变成 Agent 可执行的生命周期。 #### 多 Agent / 多 Skill 使用者 已经安装多个专业 Skill，但缺少一个统一的 Lifecycle Orchestrator 来判断什么时候应该调用谁。 #### 长期维护项目 需要跨会话、跨 Release、跨 Bug 修复持续迭代，而不是只做一次性 Demo。 ## 22. 我对 Vibe Coding 的一个判断 我现在越来越觉得： > **Coding Agent 的能力越强，Workflow 反而越重要。** 模型弱的时候，人需要告诉它每一步怎么写。 模型越来越强之后，真正重要的问题开始变成： - 它有没有跑偏？ - 它有没有偷偷扩大范围？ - 它读取的是不是正确上下文？ - 它现在到底在 v0.2 还是 v0.3？ - 它为什么说完成？ - 这次修改有没有证据？ - 哪些事情应该自己决定？ - 哪些事情必须停下来问人？ - 新会话能不能无损继续昨天的工作？ 换句话说： > **AI 编码的瓶颈，正在从「Code Generation」逐渐转向「Engineering Control」。** Vibe Workflow 就是我对这个问题的一次尝试。 它不是为了让 Agent 一次生成更多代码。 而是为了让一个项目经历： ```text 10 个 Task → 50 个 Task → 3 个 Release → 多次 Bug 修复 → 多次新会话 ``` 之后，依然保持： > **可理解、可恢复、可验证、可迭代。** *** ## 23. 写在最后 这个项目目前还是 V0.1。 我更希望它未来变成一个真正经过真实项目不断压测和修正的工作流，而不是继续往 `SKILL.md` 里堆规则。 我给它保留了几条一直不会变的原则： > **Repository is memory. Chat is conversation.** > **What to build is frozen. How to build it is delegated.** > **Minimal sufficient context.** > **Complex tasks are rigorous. Simple tasks are not bureaucratic.** > **Evidence before completion.** 如果你也在使用 Codex、研究 Agent Skill、Vibe Coding、Harness Engineering，欢迎拿真实项目来试一试。 如果它对你有帮助，也欢迎给项目一个 ⭐ Star。 GitHub： [**https://github.com/sz-xiaohuolong/vibe-workflow**](https://github.com/sz-xiaohuolong/vibe-workflow "https://github.com/sz-xiaohuolong/vibe-workflow") 也欢迎通过 Issue 提出： - 你遇到的 Vibe Coding 失控场景； - 当前 Workflow 没覆盖到的边界； - 哪些 Gate 太重； - 哪些规则还不够严格； - 哪些真实场景应该加入下一轮行为测试。 > **之后我也会用这个 Skill 做出更多的产品与大家分享心路历程。** ### 参考与致谢 这个 Skill 的设计过程中参考了多种公开的软件工程、Agent Skill 和 Vibe Coding 实践，包括： - 鱼皮哥的Vibe Coding知识库：[AI 编程零基础入门教程 Vibe Coding ](https://ai.codefather.cn/library/2010994846520700929 "https://ai.codefather.cn/library/2010994846520700929") - 吃遍全国汉堡的文章：[如何从0到1 Vibe Coding 一个项目，并长期维护](https://www.codefather.cn/post/2077996578576056322) - Superpowers：用于 Brainstorming、Planning、TDD、Systematic Debugging、Verification 等专业能力的组合思路 - project-vibe-spec：[https://github.com/dnwwdwd/project-vibe-spec](https://github.com/dnwwdwd/project-vibe-spec "https://github.com/dnwwdwd/project-vibe-spec")
Windows安装deepseek-harness教程（踩坑版）
DeepSeek Harness（`dsh`）是由 [DeepSeek AI](https://deepseek.com/) 开发的开源 agent harness（智能体框架）。近期2026年8月刚刚推出，DeepSeek Harness 目前处于 _开发者预览_ 阶段，正在快速迭代。未来将出现破坏兼容性的变更。 在此阶段，我尝试在本机已有nodejs环境下安装启动过程中 deepseek-harness 会报很多错误，存在一定的门槛，故总结踩坑流程，方便我们 Agent 开发者能够顺利安装使用。 以下按步骤说明即可顺利运行。 一、卸载原有nodejs，安装pnpm =================== 1. 卸载原有nodejs ------------- 如果本机已经有nodejs，那么需要在控制面板找到nodejs图标，选择卸载。以前如果设置过相关环境变量，也可以已删除，毕竟已经没用了。保持纯净性。 2. 安装pnpm --------- `deepseek-harness` 官方推荐使用 `pnpm` 来管理依赖。`pnpm` 可以更好地处理项目复杂的依赖结构，有时能绕过 npm 自身的某些问题。 打开 PowerShell 命令行，执行以下命令接口下载： ```bash Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression ```  （如果后续powershell爆红可改用cmd，下载用powershell即可） `deepseek-harness` 的官方文档明确要求 Node.js 版本为 **^22.19.0** **或** **>=24.0.0**。因此，安装完先执行以下命令查看当前nodejs是否符合标准： ```bash pnpm env list ``` 默认都是支持的，无需自己再额外安装：  至此，pnpm安装完成。 二、拉取deepseek-harness源码并启动 ========================= deepseek官方提供了两种本地启动方式：  这里使用源码配置的方式，原因是更可控，也方便后续进行源码阅读和学习。 首先拉取代码到本地，然后进入目录（由于是从GitHub上拉取代码，故可能需要科学上网才能流畅下载）： ```bash git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness ```  紧接着按照依赖： ```bash pnpm env use --global 26.8.1 （选择上方显示的nodejs 版本） pnpm install ```   然后就是重点，安装依赖然后启动。 这里先说结论，不要按照官方提供的命令直接运行，一般都会报错，直接按照以下命令依次执行才可成功： ```bash # 1. 清理（首次或构建失败后必须） pnpm run clean # 2. host 阶段：先生成类型，再打包 pnpm exec tsc -b tsconfig.host.json pnpm exec tsdown --env.DSH_BUILD_FACE host # 3. client 阶段：依赖 host 生成的 typert 注册表 pnpm exec tsc -b tsconfig.client.json pnpm exec tsdown --env.DSH_BUILD_FACE client # 4. 前端 pnpm run build:web ``` 每一步耐心等待几秒到几十秒执行完依次执行即可。 至于原理，这里我参考了文章，有写为何如此做：[DeepSeek Harness 实战：从零安装到跑起 Web UI 的全流程避坑指南 - 新科技观察员 - 博客园](https://www.cnblogs.com/deli007/p/22700480#commentform) 总结如下：  然后就可以启动： ```bash pnpm dsh web --no-open ``` `--no-open` 表示不自动打开浏览器。不加会默认用系统浏览器打开。启动成功会打印： ```cpp dsh web: http://127.0.0.1:3080 ``` 浏览器访问 `http://127.0.0.1:3080` 即可看到 Web UI。   进来之后需要填写配置 deepseek-platform 的 api-key，可以自行到官网（[https://platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys)）充值和创建配置。  三、测试 ==== 配置完成就可以使用了，和 codex 等产品用法差不多，都是选定一个工作目录，然后提出需求即可让其工作，如：  
🎙️面试官说的每一句话，我都想留下来：于是我用 Vibe Coding 做了一个免费的 macOS 面试录音工具
## 背景 找过工作的人应该都懂： > **面试复盘有多重要，复盘就有多难。** 一场技术面四五十分钟下来，面试官可能连续问你： - Java / JVM - MySQL / Redis - 项目设计 - Agent / RAG - 场景题 - 算法题 面试结束以后，你脑子里往往只剩下几个模糊片段： > “刚刚那个问题，我是不是答错了？” > “面试官追问了什么来着？” > “我项目那里是不是讲得特别乱？” 更尴尬的是： **你明明知道这场面试里暴露了很多问题，却已经记不清到底暴露了什么。** 于是我想做一件非常简单的事：把面试完整录下来。 然后： ```text 线上面试 ↓ 完整录音 ↓ Whisper / AI 转录 ↓ 生成面试逐字稿 ↓ ChatGPT ↓ 逐题复盘 ``` 让 AI 帮我重新整理： - 面试官到底问了什么？ - 我的原回答是什么？ - 哪些地方答错了？ - 哪些地方虽然没错，但表达很差？ - 一个更好的面试回答应该是什么？ - 这场面试暴露了哪些知识薄弱点？ - 下一场面试前应该重点补什么？ 想法非常简单。 结果真正到了 Mac 上，我发现： > **“把面试官声音 + 自己声音一起录下来”居然没想象中那么省事。** ## 我只是想录个面试，为什么突然开始学虚拟声卡了？ 我的需求真的非常朴素： ```text 面试官的声音 + 我自己的回答 ↓ 一个音频文件 ``` 甚至： > **我连屏幕都不需要录。** 结果调研了一圈以后，发现现有方案大概是这样。 ### 方案一：系统自带录音备忘录 简单是简单。 但很多情况下你最终得到的是： ```text ✅ 自己的麦克风 ❌ 系统内部声音 ``` 也就是说： **你说的话录下来了，面试官的问题没了。** 那还复盘什么…… --- ### 方案二：OBS OBS 当然非常强。 但第一次打开： ```text 场景 来源 音频混音器 音轨 编码器 输出 容器 ``` 我当时只有一个想法： > **我真的只是想录个音。** 😂 --- ### 方案三：BlackHole / 虚拟声卡 这条路线也完全能解决问题。 但很快就变成： ```text 安装 BlackHole ↓ Audio MIDI Setup ↓ Multi-Output Device ↓ Aggregate Device ↓ 检查 Clock Source ↓ 检查 Drift Correction ``` 我： > “等一下，我不是来准备面试的吗？” --- ### 后来我发现了 LoopRec 在调研过程中，我看到了一款让我非常喜欢的软件： **LoopRec。** 它真正让我喜欢的不是功能特别多，而是： > **功能特别少。** 打开以后基本就是： ```text 系统声音 ON 麦克风 ON 系统声音音量 90% 麦克风音量 100% 开始录音 ``` - 没有场景。 - 没有复杂混音台。 - 没有一堆专业录音参数。 这才是我理解中的：“面试录音工具”。 但它的免费版本存在**单次录制时长限制**。问题是技术面试这种东西，很难控制时长：  ```text 30 min 45 min 60 min 90 min 120 min ``` 都有可能。 总不能面试进行到一半说： > “面试官您好，我这个录音软件免费额度快到了，要不今天先到这里？” 😂 然后那个非常典型的程序员念头就出现了：要不我自己写一个？ 于是 InterviewRec 出现了。 ## InterviewRec 一句话介绍： > **一个免费、开源、原生、轻量的 macOS 面试 / 会议录音工具。** 它的工作流程只有： ```text Mac 系统声音 ─┐ ├──→ InterviewRec ──→ M4A 麦克风声音 ───┘ ``` 系统声音就是： > 面试官 / 会议对方的声音。 麦克风就是： > 你自己的回答。 录完以后得到： ```text InterviewRec-2026-08-28-xxxxxx.m4a ``` 然后你想： - 直接回放； - 拖进 Whisper； - 用本地模型转录； - 丢给 ChatGPT； 都可以。 --- ### 它目前能做什么？ V0.1 的功能我刻意控制得非常克制： ```text ✅ 录制 Mac 系统声音 ✅ 录制麦克风 ✅ 系统声音 + 麦克风同时录制 ✅ 输出单个 M4A ✅ 不需要 BlackHole ✅ 不需要配置虚拟声卡 ✅ 系统声音 / 麦克风独立开关 ✅ 两路独立录音音量 ✅ 双路实时音量电平 ✅ 选择麦克风设备 ✅ AirPods / USB 麦克风等输入设备 ✅ 自定义保存目录 ✅ 录完直接播放 ✅ Finder 中定位录音文件 ✅ 设置自动保存 ✅ 完全本地运行 ✅ 免费 ✅ MIT 开源 ``` 项目当前代码就是围绕“系统声音 + 麦克风 → 单个 M4A”这一目标设计的，没有加入 AI、云端或账号系统。 --- ### 不需要虚拟声卡 这是我自己最在意的一点。 InterviewRec 直接使用 macOS 的： **ScreenCaptureKit** 来获取系统声音和麦克风。 当前实现中： ```text ScreenCaptureKit │ ┌─────────────┴─────────────┐ ↓ ↓ System Audio Microphone │ │ └─────────────┬─────────────┘ ↓ PCM Normalize ↓ 48 kHz Float32 ↓ ┌───────────┴──────────┐ ↓ ↓ System Gain Mic Gain │ │ └───────────┬──────────┘ ↓ Mixer ↓ Limiter ↓ AAC ↓ M4A ``` 系统声音和麦克风通过同一个 ScreenCaptureKit Session 获取，最终进入统一的音频处理链路。 所以使用的时候不用： ```text BlackHole Soundflower Loopback VB-Cable ``` 也不会为了录音去修改你的系统默认输出设备。 代码中也使用了 `excludesCurrentProcessAudio`，避免把 InterviewRec 自己产生的声音再次抓进录音链路。 对普通用户来说，最终感知应该只有： ```text 安装 ↓ 授权 ↓ 选择麦克风 ↓ 开始录音 ``` --- ### 真正的原生 macOS App 我没有使用： ```text Electron WebView Tauri Flutter ``` 整个项目技术栈非常简单： ```text Swift 6 + SwiftUI + ScreenCaptureKit + AVFoundation ``` 目前平台范围也砍得很直接： ```text macOS 15 Sequoia+ Apple Silicon Only ``` 支持： ```text M1 M2 M3 M4 M5 ``` 不考虑 Intel。 不考虑 Rosetta。 因为这是一个我自己真正要用的小工具： > **与其为了兼容所有机器把第一版做复杂，不如先把自己的核心场景做好。** UI也十分简洁：  ## Vibe Coding 这个项目还有一个很有意思的地方：它基本是靠 Vibe Coding 做出来的 InterviewRec 本身其实也是我的一次实验： > **现在的大模型，到底能不能从 0 做出一个真正能使用的 macOS 原生工具？** 但我没有采用： ```text “帮我写一个录音软件” ``` 然后坐等 AI 吐完整项目的方式。而是真正按照软件开发流程来做的。 ### 第一步：先做需求，而不是先写代码 我先把 V0.1 需求收缩成一句话： > **系统声音 + 麦克风 → 单个 M4A。** 然后把边界冻结： ```text macOS 15+ Apple Silicon 只录音 不录屏 不联网 不做 AI 不做后端 ``` 这一步看起来没有写一行代码。 但后来回头看： > **它可能是整个项目最重要的一步。** 因为 Vibe Coding 特别容易出现： > “既然 AI 写代码不要钱，那不如全加上。” 结果 Scope 直接爆炸。 --- ### 第二步：先写 Design，再让 Agent 开始干活 项目现在不是只有源码。 还专门保留了： ```text docs/ ├── DESIGN.md ├── PLAN.md └── TESTING.md ``` `DESIGN.md` 回答： > **这个软件怎么实现？** `PLAN.md` 回答： > **Agent 应该按照什么顺序实现？** `TESTING.md` 回答： > **你怎么证明这个东西真的能用？** 这和： ```text Prompt ↓ 疯狂生成代码 ↓ 能编译 ↓ 宣布完成 ``` 完全是两回事。 --- ### 第三步：把系统拆成 Agent 能理解的小模块 现在项目里的音频核心大概是： ```text AudioFrame PCMBufferReader PCMConverter GainProcessor AudioMixer AudioLimiter AudioLevelMeter RecordingWriter ScreenCaptureAudioService RecordingEngine ``` 而不是： ```text RecordingManager.swift 3000 行 ``` 😂 例如： `GainProcessor` 就只负责： > 数字增益。 `AudioMixer` 就只负责： > 合并音频。 `AudioLevelMeter` 就只负责： > 音量计算。 `RecordingWriter` 就只负责： > PCM → AAC/M4A。 我现在越来越觉得： > **好的架构不仅方便人维护，也非常方便 Coding Agent 工作。** 你告诉 Codex： > “修 AudioMixer。” 它只需要理解一个明确的小模块。 而不是每次把整个项目重新读一遍。 --- ### 第四步：不要相信 AI 说“已经完成” 这可能是这次 Vibe Coding 给我最大的体会。 Coding Agent 特别喜欢说： > “Implementation complete.” 但软件工程真正重要的是：测试。 所以我给核心音频 Pipeline 做了自动化测试。 目前覆盖了： ```text GainProcessor AudioMixer AudioLimiter AudioLevelMeter PCMConverter RecordingWriter RecordingState Settings FileNaming ``` 比如 Mixer 测试会真正验证： ```text System Audio + Microphone ↓ 混音结果 ``` 还做了： ```text Synthetic System Tone + Synthetic Mic Tone ↓ Mixer ↓ AAC / M4A ↓ 重新读取生成文件 ↓ 检查两种声音是否都还存在 ``` 以及不同麦克风输入格式的转换测试。 --- ### MVP思维 这个项目目前仍然是： > **V0.1。** 我现在尤其关注： ```text 30～120 分钟真实长录 不同采样率设备的长期同步 Writer Backpressure 异常中断 麦克风热插拔 Crash Recovery 分段保存 ``` 这些属于下一阶段要继续重点验证和改进的内容。 当前仓库里也明确把： > 完整崩溃恢复 / segment recording 留到了 V0.2。 我觉得开源项目没必要一上来就吹： > “完美、稳定、工业级。” 反而应该告诉大家： > **哪里已经做了，哪里还在继续验证。** Issue 和 PR 本来就是开源的一部分。 --- ### 隐私方面 InterviewRec 当前： ```text 不联网 不上传 无账号 无服务器 无埋点 无广告 ``` 所有录音文件只保存在： > **你自己选择的本地目录。** 默认： ```text ~/Music/InterviewRec/ ``` 毕竟： > **技术面试录音本身就是非常敏感的数据。** 如果一个纯录音工具还要求我： ```text 登录 上传 同步 注册账号 ``` 那反而不是我想要的东西。 --- ### 对 Vibe Coding 的理解 以前大家讲 Vibe Coding： > “一句话生成一个网站。” 但真正把 InterviewRec 做下来以后，我越来越觉得，一个更靠谱的流程应该是： ```text Idea ↓ Requirements ↓ Design ↓ Implementation Plan ↓ Coding ↓ Tests ↓ Manual Verification ↓ 迭代 ``` AI 并不是： > **让软件工程消失。** 而是：让软件工程的每一步都变快。 需求可以和 AI 一起讨论。 架构可以让 AI Review。 实施计划可以让 Agent 拆。 代码可以交给 Codex。 测试可以交给 Agent 补。 Bug 可以让 Agent Debug。 文档可以自动维护。 但最终： > **方向、取舍和验收，还是得由人负责。** 至少这是我做 InterviewRec 最大的感受。 --- ## 我自己最终准备怎么使用它？ 其实 InterviewRec 只是整个工作流的第一步。 真正让我觉得它有价值的是： ```text 腾讯会议 / Zoom / 飞书 ↓ InterviewRec ↓ interview.m4a ↓ Whisper ↓ interview.md ↓ ChatGPT ``` 然后把逐字稿交给 AI： ```text 请根据这份技术面试逐字稿： 1. 按时间顺序整理面试官所有问题 2. 还原我的回答 3. 对每个回答进行评价 4. 找出错误、遗漏和表达问题 5. 给出更好的面试标准答案 6. 总结这场面试暴露出的知识薄弱点 7. 给出下一轮复习优先级 ``` ## 最后，代码开源 项目地址：⭐ InterviewRec **GitHub：**[https://github.com/sz-xiaohuolong/InterviewRec](https://github.com/sz-xiaohuolong/InterviewRec) 目前： ```text 📌 macOS 15 Sequoia+ 📌 Apple Silicon 📌 Swift 6 + SwiftUI 📌 ScreenCaptureKit 📌 AVFoundation 📌 MIT License 📌 免费 📌 完全开源 📌 完全本地 📌 无会员 📌 无服务器 📌 无广告 ``` 如果你也是： - 准备秋招 / 春招； - 找实习； - 准备跳槽； - 经常参加线上技术面； - 需要录线上会议； - 想用 AI 复盘自己的表达； 欢迎拿去用。 --- 如果这个小工具刚好解决了你的问题 欢迎： > **点一个 Star ⭐** 也欢迎： ```text Issue PR Bug Report Feature Suggestion ``` 尤其欢迎帮我测试： - AirPods - USB 麦克风 - 腾讯会议 - Zoom - 飞书 - Teams - 不同型号 Apple Silicon Mac - 长时间录音 一个开源小工具最有价值的地方，就是：**一个人的需求，最后可能刚好解决了一群人的问题。**
Linux 安装 Claude Code 实战：Node.js、npm、GLM 配置一次跑通
# Linux 安装 Claude Code 实战：Node.js、npm、GLM 配置一次跑通  有些工作放在Linux服务器上处理更顺手：看日志、改配置、排查线上问题，或者直接在项目目录里让AI帮忙读代码。 Claude Code和OpenCode都能完成这些事。我个人更习惯Claude Code的终端界面，所以把这次在Linux服务器上的安装过程整理下来。 先说明一下：Claude Code官方目前更推荐原生安装器；本文使用npm，是因为服务器已经有Node.js环境，而且部分网络环境访问官方安装脚本并不稳定。两种方式都能用，按自己的服务器情况选择即可。 ## 整体安装路线  ## 先选安装方式 ### 官方原生安装器 服务器能够正常访问Claude官方地址时，可以直接运行： ~~~bash curl -fsSL https://claude.ai/install.sh | bash ~~~ 原生安装不依赖Node.js，步骤也更短。首次安装Claude Code，优先考虑这种方式。 ### npm全局安装 如果服务器已经装好Node.js，或者官方安装脚本受网络环境影响，也可以使用npm： ~~~bash npm install -g @anthropic-ai/claude-code@latest ~~~ Claude Code官方文档在“高级安装选项 → 使用 npm 安装”中写明：从 `v2.1.198` 开始，npm包需要Node.js 22或更高版本。 不过官方紧接着补充：使用较旧的Node.js时，npm通常只会提示 `EBADENGINE`，安装仍可能完成，`claude` 也可能正常运行，因为npm包最终下载的是不依赖Node.js运行时的原生二进制文件。 所以更准确地说，Node.js 22+是当前npm包声明的安装要求，并不代表Node.js 18下一定无法启动。为了避免安装警告和后续兼容问题，本文仍建议直接使用Node.js 22或更高版本。 官方依据：https://code.claude.com/docs/zh-CN/setup#install-with-npm 本文后面的步骤使用npm方式。 ## 检查Node.js和npm 先执行： ~~~bash node -v npm -v npm config get prefix ~~~  我的环境是： ~~~text Node.js：v24.16.0 npm：11.17.0 ~~~ 这个版本可以直接安装。 如果Node.js低于22，安装时可能出现 `EBADENGINE` 警告。程序未必不能运行，但新装环境没有必要停留在旧版本，建议先通过服务器面板、nvm或系统包管理器切换到Node.js 22或更高版本。 `npm config get prefix` 会告诉你全局包安装到哪里。使用Node项目管理器时，路径可能类似： ~~~text /www/server/nodejs/v24.16.0 ~~~ 使用nvm、系统Node.js或其他面板时，路径会不一样，不需要照抄。 ## 安装Claude Code 执行： ~~~bash npm install -g @anthropic-ai/claude-code@latest ~~~  安装完成后，不要急着配置模型，先确认命令是否正常： ~~~bash claude --version command -v claude ~~~  截图中返回： ~~~text 2.1.218 (Claude Code) /www/server/nodejs/v24.16.0/bin/claude ~~~ 这说明Claude Code已经装好，并且当前Shell能够找到 `claude` 命令。 ## claude命令为什么是一个软链接 npm全局安装命令行工具时，通常会在Node.js的 `bin` 目录创建入口。你输入 `claude`，系统先找到这个入口，再执行真正的程序文件。 可以用下面的命令查看最终位置： ~~~bash readlink -f "$(command -v claude)" ~~~  真实路径会随着Node.js安装方式、版本和Claude Code版本变化。文章中的 `/www/server/nodejs/v24.16.0` 只是这台服务器的结果，不应该写死到脚本中。 想做更完整的安装检查，还可以运行： ~~~bash claude doctor ~~~ ## 官方账号和第三方API，配置方式不同 如果使用Anthropic官方账号，进入项目目录后直接执行 `claude`，按照终端提示登录即可，不需要下面这份GLM配置。 如果使用智谱Coding Plan或兼容Anthropic协议的GLM API，需要修改Claude Code的环境配置。  ## 配置Claude Code接入GLM 先创建配置目录： ~~~bash mkdir -p ~/.claude ~~~ 然后编辑： ~~~bash vim ~/.claude/settings.json ~~~ 写入下面的配置，把 `YOUR_API_KEY` 换成自己的Key： ~~~json { "env": { "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7", "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]", "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]", "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1, "API_TIMEOUT_MS": "3000000" } } ~~~ 配置完成后，限制文件权限： ~~~bash chmod 600 ~/.claude/settings.json ~~~ 这几个字段可以这样理解： | 配置项 | 作用 | | --- | --- | | `ANTHROPIC_AUTH_TOKEN` | 智谱API Key | | `ANTHROPIC_BASE_URL` | Anthropic兼容接口地址 | | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Claude Code请求Haiku角色时使用的模型 | | `ANTHROPIC_DEFAULT_SONNET_MODEL` | Claude Code请求Sonnet角色时使用的模型 | | `ANTHROPIC_DEFAULT_OPUS_MODEL` | Claude Code请求Opus角色时使用的模型 | | `API_TIMEOUT_MS` | API请求超时时间 | `glm-5.2[1m]` 中的 `[1m]` 表示该服务商提供的100万Token上下文版本。模型名属于服务商配置，不是Claude Code统一规定的格式。后续智谱调整模型名称时，要以它的官方文档为准。 API Key现在保存在当前Linux用户的配置目录中。不要把 `settings.json` 上传到Git仓库，也不要让其他用户拥有读取权限。 ## 跳过第三方API场景下的首次登录 使用第三方Anthropic兼容接口时，如果启动后仍停留在首次登录流程，可以编辑： ~~~bash vim ~/.claude.json ~~~ 加入： ~~~json { "hasCompletedOnboarding": true } ~~~ 如果 `~/.claude.json` 已经存在，不要整份覆盖，只需要合并 `hasCompletedOnboarding` 字段。 ## 启动Claude Code 先进入准备操作的项目目录： ~~~bash cd /path/to/your/project claude ~~~ 首次进入某个目录时，Claude Code会询问是否信任当前项目。  只有确认代码来源可信时，才选择： ~~~text Yes, I trust this folder ~~~ 因为Claude Code获得授权后，可以读取、修改并执行这个目录里的文件。 进入主界面后，会看到当前模型、项目路径和输入框：  截图中显示 `glm-5.2[1m]`，说明模型映射已经生效。 ## 验证安装是否成功 建议按下面的顺序检查： ~~~bash # 查看版本 claude --version # 检查安装和配置 claude doctor # 查看当前命令入口 command -v claude # 解析软链接 readlink -f "$(command -v claude)" # 发起一次非交互测试，会产生少量模型费用 claude -p "只回复 OK" ~~~ 前四条正常，只能说明程序安装和路径基本没有问题；最后一条能够正常返回，才说明API地址、Key和模型配置也已经打通。 ## 常见问题 ### npm提示EBADENGINE 先看Node.js版本： ~~~bash node -v ~~~ 当前npm安装方式应使用Node.js 22或更高版本。切换版本后重新安装Claude Code。 ### 安装成功，但提示claude命令不存在 检查npm全局目录和当前PATH： ~~~bash npm config get prefix echo "$PATH" ~~~ 临时加入PATH： ~~~bash export PATH="$(npm config get prefix)/bin:$PATH" ~~~ 确认有效后，再把这一行写入 `~/.bashrc` 或 `~/.zshrc`。 ### root用户能运行，普通用户不能运行 不同Linux用户有各自的 `HOME`、npm目录和Claude配置。使用root安装并配置后，普通用户不一定能直接使用。 安装、写入 `~/.claude/settings.json` 和运行 `claude`，最好保持为同一个用户。 ### 返回401或403 重点检查： - `ANTHROPIC_AUTH_TOKEN` 是否正确。 - Key是否拥有对应模型权限。 - `ANTHROPIC_BASE_URL` 是否写错。 - 模型名称是否仍然有效。 ### 请求超时 先确认服务器能否访问API地址： ~~~bash curl -I https://open.bigmodel.cn ~~~ 网络正常后，再检查 `API_TIMEOUT_MS` 和服务商状态。单纯反复重装Claude Code通常解决不了API超时。 ### 界面中的模型和配置不一致 退出当前Claude Code会话，确认 `settings.json` 保存成功后重新启动。仍不一致时，检查是否在另一个Linux用户下运行。 ## 更新和卸载 npm版本建议这样更新： ~~~bash npm install -g @anthropic-ai/claude-code@latest ~~~ 官方文档不建议使用 `npm update -g`，因为它可能受到原始版本范围影响，未必升级到最新版。 卸载命令： ~~~bash npm uninstall -g @anthropic-ai/claude-code ~~~ 如果不再使用原来的第三方API配置，再手动处理 `~/.claude/settings.json` 和 `~/.claude.json`。删除前先确认里面没有其他仍需保留的Claude Code设置。 ## 参考资料 - Claude Code快速开始：https://code.claude.com/docs/zh-CN/quickstart - Claude Code高级设置（npm安装）：https://code.claude.com/docs/zh-CN/setup#install-with-npm - 智谱Claude Code配置：https://docs.bigmodel.cn/cn/coding-plan/tool/claude - Windows下安装Claude Code，使用API Key方式调用GLM：https://xdr630.blog.csdn.net/article/details/158777684 - Claude Code接入国产大模型实战：GLM / Qwen配置全解析：https://xdr630.blog.csdn.net/article/details/160308331 安装本身并不难。真正容易出错的，是Node.js版本、命令路径和第三方API配置被混在一起。按步骤逐项验证，哪一步不通就查哪一步，比反复卸载重装省事得多。 欢迎关注我的公众号【兮动人】，每天分享一些技术文章和实战经验。 