开源
快来分享你的内容吧～
2 天前·Golang后端- 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分享
- 09-20 10:42·后端最近把自己开源的 重构了一遍。 做这个 Skill 的原因一直没变。 现在用 Codex、Claude Code 做项目，写代码已经越来越省事。问题慢慢跑到了另外一边：项目做久以后，Agent 开始忘，文档开始乱，方案改过几轮没人记得，代码写完了也不知查看全文加油鸭：太棒了！把项目状态管理得这么清晰又实用，这份重构思路既有深度又超接地气，为 Vibe Coding 项目提供了真正可持续的协作骨架！91015分享
09-03 12:48·全栈开发
08-07 12:00·Java后端
新版 Cursor 用不了 cursor-byok？修好啦！
分享一个最近修复并开源的项目：**cursor-byok 社区维护版**。 GitHub：https://github.com/leehainuo/cursor-byok 原项目：https://github.com/leookun/cursor-byok cursor-byok 是一个本地 Cursor 模型网关，允许开发者配置自己的 OpenAI / Anthropic 兼容模型 API，并通过本地协议适配继续使用 Cursor 的 Agent 工作流。 由于原项目目前已归档，随着 Cursor 客户端更新，旧版出现了 Agent 通信协议不兼容的问题。 最近我基于原项目进行了修复，并创建了一个独立维护的开源版本。 **本次主要修复：** 新版 Cursor 的 Agent 通信路径出现变化，可能使用与原网关预期不同的请求消息。维护版本调整了相关功能开关及协议兼容处理，使请求继续使用现有网关能够处理的 AgentRunRequest 流程。 项目仍然保留原有的模型接入和 Agent 工具协调架构，后续会持续关注 Cursor 版本变化及兼容性问题。 需要说明的是，这不是 Cursor 官方项目，也不能保证所有客户端版本、模型和功能均已验证。 欢迎遇到类似问题的开发者查看源码、测试、反馈 Issue 或提交 PR。 感谢原作者 leookun 及所有原项目贡献者。 如果对大家有帮助，欢迎 Star 支持！
做了三年 ProseMirror 后，我用四个月自研排版引擎实现 WPS / Google Docs 替代品，整套框架 MIT 开源
先别急着划走，这不是概念图，也不是拼出来的截图。 打开 [https://quirekit.com/demo/classic-editor](https://quirekit.com/demo/classic-editor/)，首屏就是一个真实的编辑器：一页一页的纸，打字、换行、表格跨页、切换 Canvas / SVG 渲染，全都是实时的。  *演示里的 DOCX 导出、页眉页脚等是商业 Word 组件，编辑器框架、排版引擎和编辑器本身是开源的。* 这是我过去四个月在做的 **QuireKit**。它不是某一个编辑器，而是**一整套编辑器生态**： - **最底层**是两套编辑器框架，写法都是 Tiptap 风格：一套基于 ProseMirror，API 兼容 Tiptap；一套基于 CodeMirror，专门做 Markdown； - **中间**是自研的排版引擎、Canvas / SVG / HTML 等多种视图，以及一套统一的 UI 组件库； - **最上层**是能直接用的编辑器：分页文档、块编辑器、Markdown 编辑器，还有公式、思维导图、白板、流程图这些周边编辑器。 每一层都可以单独拿去用，也可以整套组合起来。一句话说它能干嘛：**用它，你可以在自己的产品里搭一个“自己的 WPS 在线版 / Google Docs”。** ## 先说做出了什么 ### 1. 浏览器里真正分页的文档编辑器 做过在线文档的都知道，浏览器只会排一条无限长的页面。想要“一页一页的纸”，常见做法是排完再量高度、手动切页，内容一改就全乱。 QuireKit 的分页编辑器不靠 DOM 排版：**断行、分页、光标、选区全部自己算，再画到 Canvas 或 SVG 上**。屏幕上看到的分页，就是打印出来的分页。 - 表格可以跨页，表头自动重复 - 公式、流程图、思维导图、白板直接放进页面里一起排版 - 暗黑模式、中英文界面切换 - 长文档只绘制看得见的页，滚动不卡 操作面板也不是摆设。我按 Word 的功能区逐项对过一遍：开始、插入、页面、引用、审阅、视图，加上右键菜单、格式设置面板、表格和图片的上下文工具，**已经有 350+ 功能能直接在界面上点出来用**，还在继续补。 **DOCX 往返也打通了**：Word、WPS 写的文档导进来，可以接着改，再导出成 DOCX，拿回 Word 里继续用。 **PDF 和 OFD 导出也是自研的**：不走浏览器打印，直接复用分页排版画出来的那一份绘制指令，屏幕上一页什么样，导出的 PDF / OFD 就是什么样。OFD 是国产版式文件格式，政务、公文场景用得多。 DOCX 往返和 PDF / OFD 导出属于商业的 Word 组件，开发和评估免费。 ### 2. 块编辑器 不需要分页的场景，比如笔记、知识库，用块编辑器：拖拽、斜杠菜单、表格、目录都有。  它解决了一个用过 contenteditable 的人都踩过的坑：**你选中一段字，去工具栏输个链接，选区就没了。** 在 QuireKit 里，光标和选区是自己画的，焦点跑到输入框，选区照样在。  ### 3. Markdown 编辑器：原文一个字不丢 MD Editor 有四种视图：文档、实时预览、源码、阅读。前三种都能直接编辑，**改的都是同一份 Markdown 原文**，中间没有转成 JSON 再转回来，所以保存时你没碰过的行，一个字符都不会变。  大文档也不怕。我给 Markdown 解析器加了一个“复用证明”，编辑时直接跳过没变的部分。1 MiB 的文档连续输入 20 次，实测： | 工作量 | 优化前 | 优化后 | | --- | --- | --- | | 语法树访问 | 107,760 | 1,380（**少了 98.7%**） | | 语法树比较 | 153,940 | 660（**少了 99.6%**） | ### 4. 一整套周边编辑器，单独也能用 公式、思维导图、白板、文本绘图（Mermaid / PlantUML / Graphviz）、流程图、图表、多维表格，每一个都是独立的包，不用整个编辑器也能单独装。  ### 5. 自己设计的 UI 组件库 编辑器的操作界面比一般后台复杂得多：字体菜单、颜色选择、表格右键菜单、格式设置对话框、缩放、快捷键提示……为了让分页文档、块编辑器、Markdown 编辑器和这些周边编辑器用起来是同一种手感，我单独设计了一套 UI 组件库（Vue + UnoCSS），颜色、间距、字号都由同一套设计令牌管理，亮色和暗黑两套主题一键切换。 上面截图里所有的按钮、菜单和面板，都来自这套组件库，它同样是 MIT 开源的，可以单独用在你自己的项目里：https://design.quirekit.com ## 再说说最难的一块：中文输入法 Canvas 上没有输入框，**中文输入法是最难啃的骨头**。拼音还没确认的时候，字要先显示出来、把后面的内容往后推，但又不能进撤销历史、不能同步给协作者。 我的做法是：输入法组合期间，用一份“临时文档状态”去排版和绘制，等你按下确认才真正写进文档。  浏览器在输入法上的坑非常多，事件数据为空、组合结束事件不来、确认后重复插入……这套处理我单独做成了 `@quirekit/ime` 包，其他 Canvas 编辑器也能直接拿去用。 ## 底层：两套 Tiptap 风格的编辑器框架  - **ProseMirror 线：`@quirekit/core`**。保留 ProseMirror 的文档模型、命令、插件、协同，API 兼容 Tiptap，目标是迁移一个 Tiptap 扩展时，主要只需把 `@tiptap/core` 的导入换成 `@quirekit/core`。不同的是视图层：除了原生的 DOM 视图，还能挂自己排版的 Canvas / SVG 视图（分页文档用的就是它），以及自己管光标和选区的 HTML 视图（块编辑器用的就是它）。 - **CodeMirror 线：MSFE**。基于 CodeMirror 和 Lezer，Markdown 原文就是文档，扩展和命令的写法也是 Tiptap 风格。MD Editor 构建在它上面。 两套框架的成品共用一套 UI 组件库，所以分页文档、块编辑器、Markdown 编辑器看起来是一家人。熟悉 Tiptap 的话，两条线都能很快上手。 ## 能用吗？怎么用？ 几行代码就能把 Markdown 编辑器放进 Vue 项目： ```bash npm install @quirekit/md-editor@alpha ``` ```vue <script setup lang="ts"> import { MdEditor } from '@quirekit/md-editor/vue' import '@quirekit/md-editor/styles.css' </script> <template> <MdEditor markdown="# Hello" label="Document" /> </template> ``` 块编辑器和分页编辑器分别是 `@quirekit/block-editor`、`@quirekit/classic-editor`。 **整套生态里开源的部分**，MIT 许可，闭源商用也可以：两套编辑器框架、Canvas / SVG 排版引擎和各种视图、UI 组件库、分页 / 块 / Markdown 三个编辑器，以及公式、导图、白板这些周边编辑器。Word 兼容能力（DOCX 往返、PDF/OFD 导出、审阅等）是单独的商业组件，开发和评估免费，不用它们也能完整使用编辑器。 目前是 alpha，API 还会变，欢迎来试、来挑刺： - 在线体验：https://quirekit.com - 文档：https://docs.quirekit.com - GitHub：https://github.com/quirekit/quirekit 觉得有意思的话，点个 Star 就是对我最大的支持。
DiskScope：找出是谁在悄悄吃掉你的硬盘
> 一个 Windows 磁盘分析 + 清理工具。扫 16 万个文件只要 1.7 秒, 并且会告诉你**谁在长**, 而不只是**谁大**。 --- ## 起因 C 盘又满了。 每次都得开个现成的工具, 然后等它慢慢扫, 看进度条慢慢转, 扫完再自己对着几百兆的 `node_modules` 猜哪些能删。 这些工具做的是**快照**: 告诉你此刻谁占地方。但我真正想知道的是另一件事 —— > **这个目录是什么时候开始变大的? 是不是某个东西在偷偷长?** Steam 的 workshop 素材会自动重新下载并换目录 ID, 某些项目隔三差五 `npm install` 一次, 缓存目录悄悄膨胀到几十 GB —— 这些在静态快照里完全看不出来。 所以我写了 **DiskScope**，全程vibecoding将想法变成现实。     --- ## 四个页面 ### 1. 体积分布 Squarified treemap, 点任意方块下钻, 配可展开的层级明细。目标是**一眼看出空间去哪了**。 ### 2. 时间轴（核心） 最近 30 天**每天**写入了多少数据, 堆叠柱状图, 外加一张「谁在悄悄变大」排行榜。 这是这个工具和别的磁盘分析器最不一样的地方: ``` 今天写入 578 MB │ 最近 7 天 1.8 GB │ 最近 30 天 5.4 GB │ 30 天以上没动过 142 GB ``` 一眼就能分清: **上面那 5.4 GB 是活的东西, 下面那 142 GB 是死的**。后者才是清理的目标。 ### 3. 清理 53 条规则, 分三级: | 级别 | 数量 | 含义 | 例子 | |-----|---|---|---| | 🟢 可重建 | 39 | 删了会自动重新生成, 默认勾选 | `node_modules` `target` `dist` `__pycache__` | | 🟡 需确认 | 12 | 要重新下载, 或会丢历史记录, 默认不勾 | `.venv` `Pods` `*.log` `.idea` | | 🔴 勿删 | 2 | 勾选框**直接禁用** | `.git` `*.tfstate` | 配套 **dry-run 预演**: 先看清要动什么, 再决定删不删。 ### 4. 大文件 面向**普通文件夹**（照片 / 视频 / 安装包 / 归档）。构建垃圾规则匹配不到这些, 所以单独追踪: Top 200 大文件 + 按扩展名汇总。 --- ## 技术上花了力气的地方 ### 16 个 worker 线程, 单线程的 5.5 倍 第一版用 `fs.promises.stat` + 异步池, 16 万文件要 8.4 秒。瓶颈不是 Promise 开销, 是 **stat 系统调用本身**。 改成 worker 线程池后, 主进程只管派活, worker 各扫各的: | worker 数 | 文件/秒 | 相对单线程 | |---|---|---| | 1 | 20,844 | 1.0x | | 4 | 63,343 | 3.0x | | 8 | 90,923 | 4.4x | | 16 | **114,088** | **5.5x** | 实际效果: 扫完 161,207 个文件 / 70 GB, **1.7 秒**。 ### 31 格直方图, 任意层级 O(1) 回答「最近长了多少」 每个目录存一个 31 格的直方图（第 0 格 = 今天, 最后一格 = 30 天前的冷数据）, 自底向上**滚动相加**: ```js // 父目录的直方图 = 自己的 + 所有子目录的 for (let i = 0; i < NDAYS; i++) daily[i] += child.daily[i]; ``` 于是任意层级都能 O(1) 回答"这里最近 7 天长了多少", 不需要重新遍历子树。 ### 有界小顶堆, 内存恒定 要记住最大的 200 个文件, 但不能随扫描量涨内存。堆顶始终是 Top-N 里最小的那个, 新文件比它还小就直接丢弃: ```js push(v) { if (a.length < cap) { a.push(v); this._up(a.length - 1); } else if (v[0] > a[0][0]) { a[0] = v; this._down(0); } // 堆顶换掉 } ``` 扫 5 万个文件和扫 500 万个文件, 内存都是 200 条。 --- ## 踩过的坑（这部分可能比功能更有用） ### 1. Electron 的 asar 补丁会悄悄改掉你的统计结果 Electron 会把「路径最后一个扩展名是 asar 的文件」当成 asar 包来解析: - 合法的 asar → `statSync` 返回 **0 字节**（把包根当虚拟目录） - 损坏的 asar → 直接抛 `Invalid package` 结果就是**所有 .asar 文件的大小都没被统计, 磁盘总量一直偏小**, 而且 stderr 刷一片错误。 绕法是加 NTFS 备用数据流后缀 `::$DATA`（指向文件本体）, 路径最后一个扩展名变成 `DATA`, Electron 就不会去解析 asar 了: ```js function statFile(p) { if (/\.asar$/i.test(p)) { try { return fs.statSync(p + "::$DATA"); } catch { /* 退回普通方式 */ } } return fs.statSync(p); } ``` ### 2. `D:\` 自带尾随分隔符, 拼路径会多一个反斜杠 ```js path.resolve("D:\\") // "D:\\" ← 带尾随分隔符 dirPath + "\\" + fn // "D:\\software" ← 双反斜杠 path.join(dirPath, fn) // "D:\software" ✓ ``` Windows 内部会容忍双斜杠, 但**路径字符串比较会失效** —— 我那个「文件被挪走了, 帮你找回来」的功能就是这么失灵的。改用 `path.join` 一劳永逸。 ### 3. 悬停提示会残留在页面上 提示框原本是每次 hover 新建一个 div 挂在 `document.body` 上, 引用存在**柱子元素**里。点击柱子下钻 → 图表整个重建 → 旧元素被丢弃 → `mouseleave` 永远不触发 → 提示框永久留在屏幕上。 修法是改成**全局单个复用的节点**, 从根上消除这类孤儿节点。 ### 4. 文件会「被挪到隔壁去」 Steam 重新下载 workshop 素材时会换一个新的目录 ID, 文件名却不变: ``` 扫描时: ...\431960\344551134\CSCT-013.mp4 现在: ...\431960\3445511134\CSCT-013.mp4 ← 多了一个 1 ``` 于是点路径时文件「不存在了」。现在的处理是分三档: 1. 目标在 → 正常定位 2. **被挪到隔壁去了** → 按文件名在上一级的其他子目录里找一遍, 找到就直接定位到新位置 3. 真没了 → 打开最近还存在的上级目录, 并明确告诉你 三种情况都会给提示, 不会静默无反应。 --- ## 安全设计 清理工具删的是用户的数据, 所以默认必须是保守的: - **默认进回收站**（可还原）, 而不是直接 `rm` - **dry-run 预演**先过一遍 - **三级分类**, `.git` 永远不可勾选 - **服务端硬性闸门**: 磁盘根目录、工具自身所在目录和程序文件, 一律拒绝 - **嵌套路径自动去重**（选了 `node_modules` 就不会再单独处理它内部的 `.vite`） - Electron 版把 Python 版那套「本地 HTTP + 随机 token」整个去掉了 —— 改成 IPC, **连端口都不占** ### 测试 118 项检查, 打包版也跑: ``` 规则校验 27 项 │ 后端 40 项 │ 界面 51 项 ``` 界面自检是**真的去点按钮**的 —— 包括点「停止」并验证扫描真的停下来了, 点路径并验证资源管理器真的打开了。 --- ## 获取 **绿色版**（免安装, 单文件）: ``` dist\DiskScope-1.0.0-绿色版.exe ``` **从源码构建**: ```bash npm install npm run build # electron-builder + 写入图标与版本信息 npm run uitest # 界面自检, 会自动截图 ``` **Python 版**（只用标准库, 双击 `run.bat` 就能跑）也保留着, 两版共用同一套前端和同一份规则表。 源码: <https://github.com/star-sda/diskscope> --- ## 最后 工具的开发全程vibecoding，作为一名javaer真切感受到了AI的强大。
总在找刚才复制的东西，我给 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**。告诉我系统版本、在哪个应用里、做了什么操作，比一句“不能用”更方便定位问题。截图或举例时，记得避开自己的隐私内容。 希望下次再问“刚才复制的那个呢”，我们都不用回去翻聊天记录了。
手把手教你设计一个成熟的 Agent Harness
# 手把手设计一个成熟的 Agent Harness > 讲思路和选型，不绑定具体框架。目标是推演一个问题：一个能长期跑、断线能恢复、上下文不被撑爆、出错时不撒谎的 Agent 系统该怎么搭。 写给刚上手做 Agent 的人，术语第一次出现时用一句人话解释。 ## 前言 大家好，我是汉堡🍔。 写这篇只有一个原因：做 Notus（https://notus.hejiajun.com/ ） 的 Harness 时踩了一堆坑，想汇总下来分享。任务跑到一半断线、模型说完成了其实什么都没做、上下文越滚越贵最后撑爆、一个危险操作崩溃后被重放了两次——这些坑在讲 Agent 的文章里基本看不到，它们大多停在「怎么调 API、怎么接工具」。 所以本篇文章将这些坑进行汇总，帮助大家少踩一些 Agent Harness 上的坑。 ## 术语说明 - **Agent**：能自己决定下一步、调用工具、把任务做完的程序。 - **Harness**：包在模型外面的那层调度代码，管状态、管预算、管工具、管失败。 - **上下文（context）**：每轮发给模型的全部内容，包括系统提示、历史消息、工具定义、工具返回结果。 - **token**：模型计费和限量的单位，一个汉字大致 1 个 token。 - **工具调用（tool call）**：模型不直接干活，它输出"我要调用某个工具，参数是这些"，由你的代码执行完把结果回灌给它。 - **检查点（checkpoint）**：某一刻的完整可恢复快照，崩溃后从这里接着跑。 - **幂等（idempotent）**：同一个操作重复执行，结果和执行一次一样。 - **SSE**：服务端往浏览器单向推流，聊天界面那种边生成边显示的能力。 ## 目录 1. Agent 里哪部分是 Harness 2. 成熟度阶梯 3. 上下文的成本与上限 4. 架构上的两条界线 5. 核心部件 6. 状态与恢复 7. 失败路径的处理 8. 行为验收 9. 技术栈选型 10. 高频坑清单 11. 落地路线 --- ## 1. Agent 里哪部分是 Harness 把 Agent 理解成"接了大模型的对话框"，后面会一直走错路。能干活的 Agent 由四部分组成： ```text Agent = LLM（决策） + Harness（调度与约束） + Tools（手脚） + Memory（记忆） ``` LLM 决定下一步做什么，它是概率性的，会犯错、会跑偏；Tools 是它接触外部世界的通道；Memory 是能带到下一轮的记录；Harness 是剩下的全部——谁发请求、谁管状态、谁卡预算、谁兜住失败。 Harness 的职责压成一句：**把模型的不确定输出，变成外部世界能核对、能恢复、能追查的动作。** 类比操作系统：模型是 CPU，Harness 是内核。CPU 再快，没有内存管理、没有中断处理、没有权限控制，也跑不出能用的系统。模型决定能力上限，Harness 决定这些能力能不能稳定发挥。 有一条认知要提前建立：模型聪明，不等于系统可以偷懒。恰恰因为它会自己挑工具、看错误重试、为达目标做出你没预料到的动作，Harness 才必须更严谨。它的作用是在模型越界、卡死、断线、说错话的时候，把世界拉回一致状态。 --- ## 2. 成熟度阶梯 Harness 没法一步到位。成熟系统基本都沿同一条台阶爬上来，你可以用它对一下自己的位置。 | 台阶 | 你能做到什么 | 还没解决 | | --- | --- | --- | | S0 无脑拼接 | 把历史消息和检索结果全塞进 prompt，能对话 | 上下文爆炸、答非所问、幻觉 | | S1 单轮工具调用 | 模型选工具、工具返回、直接回复 | 复杂任务断在半路 | | S2 多轮循环 | 工具结果回灌，循环到出结果 | 工具结果越滚越大，可能死循环 | | S3 有状态、能恢复 | 会话状态 + 检查点 + 任务队列 + 断线重连 | 上下文治理、重复执行、恢复语义 | | S4 上下文治理 | 结果外置、按需读取、每轮重新拼视图、预算控制 | 结果对不对没法验收，拦不住模型自称完成 | | S5 契约与护栏 | 任务意图、工具裁剪、交付前核对、权限控制 | 要持续打磨，要用真实模型回归 | 大部分教程停在 S2。S3 到 S5 才是难点，后面每一节都对应这条阶梯。 --- ## 3. 上下文的成本与上限 这篇只留一句结论的话：**上下文有硬上限，越长越贵，而且每一轮都要重新付一次钱。** 四个具体后果： 1. **体积随轮数增长。** 每轮都要追加一条模型输出和一条工具结果，量随"轮数 × 每轮工具数 × 单项结果大小"滚动。读一篇长文或抓一整页网页，几万 token 就没了。 2. **注意力会衰减。** 技术上塞得下，模型对超长上下文中间部分的关注也会下降，关键信息容易被淹掉。 3. **越长越贵。** 每轮都要重发整个历史，长任务是成本的放大器。 4. **一次外置省的不是一轮。** 省下的是后面所有轮的重发量。 ### 大对象的处理顺序 面对文件、检索结果、网页正文、图片这类体积大的材料，成熟系统的处理顺序是固定的： ```text 外置 → 引用 → 按需读取 → 投影 ``` - **外置**：正文不进对话，脱敏压缩后写进独立存储。 - **引用**：上下文里只留一个可寻址的引用，带上状态、大小、摘要、哈希。 - **按需读取**：给模型一个受控的读取工具，让它自己决定读不读、读哪段、读多少。 - **投影**：每次发请求前，按这一轮预算临时拼一个视图，而不是去改原始消息。 ### 截断与投影的区别 新手的常见做法是"太长了就砍掉前面几条"。这会同时踩三个坑：砍掉的可能是模型正在依赖的事实；原始数据被破坏，出问题没法回溯；每轮砍法不同，行为没法回归测试。 正确做法是原始消息永远不动，只在发请求前拼一个临时视图。视图用完就丢，检查点才是恢复的唯一依据。可恢复和可复现，是 Harness 的两条底线。 --- ## 4. 架构上的两条界线 **第一条：把"决定能不能做"和"实际执行"分开。** 前者管状态、权限、调度、预算；后者负责调模型、跑工具、写文件、发事件。混在一起写，后面加权限和并发时会大面积返工。 **第二条：执行不要挂在 HTTP 请求上。** 新手做法是用户发一个请求，服务端在请求里跑完整个循环，用 SSE 推流。后果是用户关掉页面任务就丢了，网络抖一下任务半死，没法排队也没法并发。 成熟做法是请求只负责建任务，执行交给独立的后台进程和任务队列，SSE 降级成一个随时可以断开的观察通道： ```text 请求 → 落库(session + task) → 立即返回/建立订阅 Worker → 领任务 → 跑循环 → 写事件 → 广播 订阅 → 按事件游标补齐 + 接收增量 ``` 这两条界线划清之后，断线和取消就分开了。断线只是没人在看，任务还在跑。 ### 数据表的职责拆分 不要全堆进一张会话表： - `sessions`：会话状态、当前任务、租约、预算、版本号 - `messages`：用户/助手/工具消息，原始权威数据 - `checkpoints`：可恢复快照，版本化 - `tool_results`：外置结果的元数据，只存路径、哈希、大小、状态，不存正文 - `runtime_facts`：工具调用的执行事实，用于判重和判断"结果未知" - `run_events`：进度、产物、最终结果这类语义事件，用于重建时间线 - `usage`：逐次用量，主模型、检索、重排分开记 迁移方式用加法：新表加、旧字段留着兼容，不要为了"干净"破坏性删列。 --- ## 5. 核心部件 ### 5.1 上下文装配器 它决定每次发给模型的消息数组长什么样，是最难写对的地方。 先划预算。不要用"最多 N 条消息"这种拍脑袋规则，按模型真实上下文窗口算，下面的比例是经验起始值： ```text 安全余量 = window × 10% // 固定，任何情况不借用 可用区 = window × 90% system + 工具定义 ≈ 20% 当前任务 ≈ 20% 活动工具链 ≈ 25% 动态材料 ≈ 25% ``` 触发规则： ```text 估算输入 ≥ 硬预算 × 85% → 压缩到约 75% Provider 报 overflow → 压到约 60%，只重试一次 仍超限 → 存检查点，明确报"预算超限"，不硬撑 ``` 会话累计用量再设三档：到窗口 70% 主动压缩；到 85% 停止加载非必要材料和可选工具；到 100% 暂停，等用户确认扩容。 刹车用预算，不要用"最大轮次"。轮次上限看着安全，实际会把长任务硬生生切断，逼用户点继续。预算和循环守卫这两道刹车互相独立，互不干扰。 ### 5.2 历史怎么进上下文 历史是上下文的第一大来源，分三级： - **近期原文**：按预算选，不按条数。"最近 10 条 + 每条截 1400 字"这种写法就是长对话丢事实的根源。 - **滚动摘要**：预算外的内容分批摘要，必须带来源指纹（对覆盖范围内的消息算哈希），消息被改写或删除就失效重建。摘要会丢信息，所以摘要不是权威，原文才是。摘要服务失败要明确降级，告诉模型"我记忆不完整"，不要假装记得。 - **历史检索入口**：给模型一个回查历史的工具，支持关键词和分页，只能读当前会话、且早于本轮用户消息的部分。 摘要本身也要限资源，防止它变成无底洞：单次摘要最多 3 次模型调用、最长 60 秒窗口、最多花掉剩余任务预算的 25%，失败就降级为可查询原文，不阻断主任务。 ### 5.3 工具结果外置 这一步是从 S3 迈向 S4 的主要动作。常规工具的完整结果在进入上下文之前，先做三件事再落盘： ```text 脱敏 → 压缩 → 原子写 路径： <dataRoot>/tool-results/<会话>/<任务>/<uuid>.json.gz ``` 给模型的不是正文，而是一份回执： ```json { "tool": "search_notes", "status": "ok", "summary": "返回 3 篇候选，最高相关度 0.83", "result_ref": "tool-result://8f3c...", "sha256": "sha256:...", "original_bytes": 184320, "stored_bytes": 41250, "fields": ["title", "path", "score"], "read_hint": "可用 json_pointer / query / offset 读取" } ``` 配额给死：单项未压缩结果不超过 32 MiB，单会话压缩后占用不超过 512 MiB，超了就明确报错，不要静默截断。 外置失败时记住一条：执行状态和存储状态是两回事。工具真的执行成功了、只是归档失败，就如实标记"载荷不可用"，并停掉依赖正文的后续步骤，但不要把这个已经成功的外部调用改写成失败。 图片和附件同理：进上下文的只有一个引用，发送前由投影器加载成多模态输入，base64 不进正文、事件流和检查点。 ### 5.4 读取工具的接口设计 外置之后，模型怎么把内容读回来，这里很容易踩坑：不要直接把服务器文件路径交给模型。路径会泄漏内部结构，模型可能读到它无权访问的内容，而且很多宿主根本没有 shell 让它去 cat。 正确做法是自己实现一个受控读取工具，只接受会话内有权限的不透明引用： ```text read_result(ref, mode) ├─ json_pointer: "/items/0/content" ├─ query: 关键词窗口，命中段落返回 └─ offset+size: 第 8KB 起读 4KB 默认返回 8 KiB，硬上限 16 KiB ``` 再配一个索引工具，让模型能分页列出本会话有哪些结果可读。 这一步是自研 Harness 和套壳 Harness 的分界线。套壳方案给模型一个 shell；自研方案给它一条带权限、带分页、带配额的读取通道。前者在沙箱里成立，后者在不允许执行任意代码的宿主（笔记应用、办公套件、SaaS 后台）里是唯一选择。 ### 5.5 压缩的顺序与约束 压缩不是砍前面的，分两级、有顺序： ```text 1) 先回收大读取窗口 优先回收"较早 且 估算超过阈值(如 2048 token)"的读取片段，预算满足就停 最近 4 条消息、错误结果、小型目录暂不回收 2) 还超预算，再按完整的"调用 + 结果"分组压缩 一条 tool_call 和它的结果必须成对处理，压缩时保留读取参数（offset/limit） ``` 三条硬约束缺一不可：保持调用和结果配对（拆散了下一轮请求会被直接拒绝）；不改原始消息；不自动重放工具，压缩只是让模型看不见，不是让它重新执行。 有个典型坑：把"只保留最近 4 条"写成无条件逻辑，模型刚读过的内容被过早收走，只好反复重读同一个大文件，token 反而更费。 ### 5.6 工具运行时 工具不只是函数，它是一份契约： ```text Tool = { name, description, input_schema, // JSON Schema，执行前必须校验 handler, permission, // 是否需要用户确认 idempotency: read_only | idempotent | unknown_side_effect, result_policy: { maxBytes, redact, archive } } ``` 参数要在执行前校验（JS 用 Ajv 或 zod，Python 用 pydantic）。要区分"工具不存在"和"参数非法"：前者是授权或投影问题，后者是模型问题，混在一起模型会误以为这个能力不可用。校验失败要把错误回灌给模型让它改，不要直接终止。 按副作用把工具分三类： | 类别 | 例子 | 崩溃重启后 | | --- | --- | --- | | read_only | 读文件、检索 | 可以安全重放 | | idempotent | 按 ID 覆盖写 | 可以恢复 | | unknown_side_effect | 发邮件、下单、装软件、调外部 MCP | 绝不自动重放 | 第三类在调用前先写一条 prepared 事实。崩溃重启后发现"有 prepared、没有终态"，就标记成 `outcome_unknown`（结果未知），把错误和已有引用交回模型，让它自己判断，而不是替它决定重来一次。在"可能重复执行一次危险操作"和"如实告诉用户结果未知"之间，选后者。 工具来自多个来源（内置 + 扩展 + 外部 MCP）时，不要一次把 schema 全塞进上下文：启动只给一份摘要目录，模型需要时用 list_tools 分页发现，下一轮再给完整 schema。 结果治理跟装配器配合：执行期先做一次大小裁剪（读文件 256KB、网页 64KB 就截断并附摘要）；脱敏只在归档前做一次，按需读取时不要再脱敏，否则会把路径、哈希这类合法内容也破坏掉；失败结果也要落盘，错误正文同样值得被按需读取。 ### 5.7 循环终止条件 循环骨架很简单，难的是终止条件： ```text while (true) { resp = callLLM(messages, tools) if (!resp.tool_calls && stopReason in [end_turn, stop]) break // 正常收尾 if (invalidToolInput(resp)) { pushError(resp); continue } // 让模型改 results = dispatchTools(resp) messages.push(assistant(resp), toolResults(results)) } ``` 四类终止条件互相独立： - **正常完成**：没有工具调用，加上明确的结束原因。 - **交付前核对**：结束后按任务要求对一遍，需要联网的有没有证据，需要写文件的有没有产物。最多给一次修正机会，仍不足就如实报告未完成。 - **循环守卫**：相邻、同工具、同参数、同结果连续 N 次，把已有结果交回模型并提示；同错误码连续 M 次，交回模型判断；连续空响应判为无进展。 - **预算耗尽**：走 5.1 的闸门。 守卫负责拦住明显的原地打转，不要把它写成"重复调用直接判失败"，那会误伤正常的"不同 URL、不同分页"读取。 --- ## 6. 状态与恢复 能不能把 S2 抬到 S3，基本决定了 Agent 产品能不能用。工具谁都会接，状态很少有人做对。 **会话状态显式建模**，不要用一堆布尔标志位： ```text created → running → waiting_interaction → queued_resume → running → waiting_limit // 等用户确认扩容 → waiting_retry // 临时错误重试耗尽 → waiting_recovery // 需要用户处理：额度、密钥、权限 → completed | failed | cancelled ``` 每个状态变化都要幂等：同一份用户回答重复提交，只返回同一个恢复任务。每个状态都要能回答"现在能不能继续、能不能取消、能不能输入"。 **检查点两阶段提交**，不要"先删旧再写新"： ```text 1) 读当前 active 检查点（不动） 2) 写入新的检查点内容 3) 事务内把新记录置为 active，更新会话指针 4) 成功之后，才把旧的置为 superseded ``` 在步骤 3 之前崩溃，旧检查点照样能救回来。 **租约（lease）**：执行前拿一个带时限的租约，比如 90 秒，执行中定期续租，比如每 20 秒，状态更新时同时匹配当前执行者 ID 和版本号。进程崩溃后租约过期，允许新执行者接管。没有租约，会出现两个 Worker 同时跑同一个会话，把文件写两遍。 **交互票据**：需要用户回答、确认或恢复任务时，用短期、一次性、带签名的票据。票据只走请求体或请求头，不进 URL、日志和消息正文，校验时匹配 owner，用完即废，防止重放。 **事件推送**：事件先写数据库再广播，这样断线重连才能按游标补齐。事件分语义通道，不要只发原始 token：`progress` 是短进展，`artifact` 是交互、预览、文件状态和待确认项，`final` 只出现一次，落成最终消息并带累计用量。订阅用游标，重连时从"我收到哪了"继续，避免重放旧的 final 导致消息重复。加心跳，比如每 15 秒一行注释，防止空闲连接被代理掐断。进程内的事件总线要挂在全局单例上，否则多个模块会各发各的。 **断线不等于取消**：用户显式点取消才算 cancelled；浏览器断线就存检查点，任务保留为 queued_resume，回来接着跑。恢复的规则是复用检查点和已有的工具结果，不重放已完成的工具，按"下一个待分发的工具索引"继续，配合执行事实表去重。 --- ## 7. 失败路径的处理 成熟与否，在失败路径上最明显。 错误先分类，不要都当失败： ```text retryable 网络抖动、429、部分 5xx → 等待 + 有界重试（如 30s × 最多 5 次） action_required 额度、密钥、权限、模型不可用 → 等用户处理后可继续 fatal 请求结构非法、安全或上下文无法恢复 → 终止 ``` 重试要绑定取消信号：用户停止任务时，正在等待的重试定时器立刻取消，不要"再发一次试试"。 失败结果同样落盘，回执带原因摘要和错误字段位置。让模型读错误、改参数、换个方式继续，不要替它判断"这工具坏了"。多数"工具不可用"的假象是参数写错了。 给用户看的错误要克制：一张错误卡片加一个继续入口，不透传 Provider 的 HTML 错误页或原始响应正文。内部诊断要尽量全，包括 HTTP 状态、错误码、请求窗口、预算数字、消息角色统计、工具调用与结果配对统计、耗时，这些用来排障，不能省。一份好的错误信息能把排障时间从半天压到几分钟。 --- ## 8. 行为验收 到 S5，问题不再是能不能做，而是行为能不能被验收。 **提示词要模块化、带版本。** 几千行的巨型 system prompt 没法维护，改成注册表驱动：政策、工作区规则、写作规则、检索规则、资源规则、交互规则、输出规则分模块，每个模块带模块 ID、规则 ID、优先级、适用条件、token 上限和对应的测试用例。渲染阶段做三件事：拒绝重复的规则 ID、拒绝显式冲突的规则、校验材料配额，并记录提示词版本，让每次请求可追溯。 **不可信材料要降权。** 检索结果、网页、外部 API 返回、用户上传的文档都是数据，不是指令。用统一信封包起来，带上来源类型、来源 ID、信任等级、摘要哈希。信封内容永远不能覆盖系统策略，也不能扩大工具权限。用户自己维护的长期记忆可以是高信任等级，但依然低于策略和权限。 **把判断从模型手里收回。** 早期做法是让一次模型调用同时判意图、选材料、选工具、判完成，结果是行为没法验收，你想测的每条路径都挤在同一次概率输出里。成熟做法是拆成可持久化的契约：这一轮的任务意图由 Harness 采集并记下来（意图、目标对象、用户更正、待核实问题、证据要求）；每轮重新挑材料，不沿用任务开头那个大上下文；按意图编译这轮该给的工具；交付前按契约核对结果。 **提示词写法上的六条经验**：顺序判断（第一步→第二步）比"综合考虑 ABC"对弱模型友好；是非题比开放题准；给映射表比描述规则省事；几个具体例子胜过一段长规则；显式写兜底（不确定时提问）比让模型自己想兜底安全；划边界（永远不要声称做了没做的事）比列路径有效。 **外部副作用靠声明，不靠推导。** 不要根据工具名字猜它有没有副作用，让工具自己声明。未知副作用的工具默认串行、默认不可自动重放。 --- ## 9. 技术栈选型 Harness 对技术栈要求不高，对可靠性原语要求高。 **语言**：Node.js / TypeScript 生态最全，前端同语言，流式成熟；Python 的 AI 生态最好，数据处理强；纯 JavaScript 也能做，但要靠 Schema 补上类型约束。 **存储与检索**： | 需求 | 单机 / 本地优先 | 服务端 / 多租户 | | --- | --- | --- | | 关系 + 状态 | SQLite（WAL 模式） | PostgreSQL | | 全文检索 | SQLite FTS5 | Postgres tsvector / Elastic | | 向量检索 | sqlite-vec | pgvector / Qdrant | | 结果文件 | 本地文件系统（原子写） | S3 兼容对象存储 | | 缓存 / 队列 | DB-backed queue | Redis（BullMQ 等） | 会话、检查点、事件这些最关键的数据优先放关系库，并保证写事件和写状态能在同一个事务里完成。 **传输**：SSE 优先，单向、浏览器原生、经得起代理；需要双向再上 WebSocket。无论哪种，事件先落库再广播，重连靠游标。 **队列与并发**：起步用数据库任务表加轮询 Worker，简单、可恢复、够用；复杂编排再上 Temporal 这类状态机引擎。并发模型用同会话 FIFO、跨会话并行，既保序又不互相堵。 **可观测性**：结构化日志，加上每次请求的诊断字段；密钥、凭据、带登录信息的 URL 一律脱敏后再进日志、事件和消息；提供一个只读的"任务活动"查询，让模型和用户都能回看真实执行记录。 **沙箱**：宿主允许执行代码时，轻量用 Docker + gVisor，强隔离用 Firecracker microVM。给了 shell 反而要更严，因为模型能自己 cat 的时候，权限和配额更容易被绕过。 --- ## 10. 高频坑清单 | 现象 | 原因 | 对策 | | --- | --- | --- | | 长对话丢早期事实 | 用"最近 N 条"裁剪 | 预算化历史 + 摘要 + 历史检索 | | 压缩后仍然溢出 | 只压缩成功的工具结果，没救到长正文 | 先算预算，再回收大读取窗口 | | 模型反复重读同一文件 | 读取窗口被无条件驱逐 | 预算够就保留，按大小阈值回收 | | 工具结果撑爆上下文 | 正文直接进上下文 | 外置 + 引用 + 按需读取 | | 请求报 prefill 或 reasoning_content 错误 | 模型协议差异没归一化 | 统一适配层，修消息形状 | | 断线后任务丢失 | 执行挂在 HTTP 请求上 | 队列 + Worker，SSE 只观察 | | 消息重复出现 | 恢复时从 0 重放旧 final | 事件游标去重，final 只写一次 | | 同一会话被跑两遍 | 没有租约或版本号 | lease + 版本号条件更新 | | 危险操作重复执行 | 崩溃后盲目重放 | 幂等分类，结果未知不重放 | | 模型谎报完成 | 没有交付前核对 | 按契约核对 + 一次纠正 | | 脱敏把合法内容破坏 | 归档和读取反复脱敏 | 只在归档前脱敏一次 | --- ## 11. 落地路线 按台阶来，每一级都要求可恢复、可回归： ```text 里程碑 1（S1→S2）跑通多轮循环 验收：能完成一个需要 3 次以上工具调用的任务 里程碑 2（S3-a）执行与请求解耦 验收：断线、刷新、重启进程后任务都能继续，SSE 断线不取消任务 里程碑 3（S3-b）状态与恢复 验收：检查点两阶段提交；并发被租约挡住；重复回答只产生一个恢复任务 里程碑 4（S4-a）上下文预算 验收：构造超长输入，能在触发线压缩，overflow 只重试一次，不越界 里程碑 5（S4-b）结果外置与按需读取 验收：大结果只给引用；模型能用读取工具取回指定片段；配额生效 里程碑 6（S4-c）投影与压缩 验收：压缩保持调用与结果配对；原始检查点不被改写；已读材料不无故丢失 里程碑 7（S5）契约与护栏 验收：任务意图可持久化；工具按意图裁剪；交付前核对能拦下只说不动； 未知副作用不重放；提示词有版本和冲突检测 里程碑 8 可观测与真实模型回归 验收：错误可诊断、密钥不泄漏；真实模型 + 真实工具 + 多端跑通 ``` 验收上有一条底线：不要拿"接口存在"当"功能可用"，也不要拿"静态测试通过"当"用户路径通过"。测试要覆盖故障注入，而不只是正常路径： - 检查点在模型失败、数据库失败、进程被杀这三种时刻崩溃，能否恢复； - 取消、超时、心跳、租约冲突； - 超长消息、超大工具结果、overflow 单次重试； - 非幂等调用发出后中断，是否被正确标为结果未知且没有被重放； - 密钥和凭据是否出现在日志、事件、消息元数据里（应为 0）。 --- ## 结语 把这些取舍连起来，方向是一致的：能外置的就外置，能引用的就引用，能恢复的不重放，能算预算的别数轮数，能核对的别信模型的自我汇报。 模型会越来越强，但 Harness 里关于状态、权限、恢复的这些工作不会因为模型变强而消失。模型给的是概率性的输出，外部世界需要的是确定、可恢复、可追查的结果。 ## 我的项目 [Notus](https://github.com/dnwwdwd/Notus)：本地优先的 AI Agent 笔记软件 [喵喵搜索](https://github.com/dnwwdwd/miaomiao-search)：自托管多引擎网络搜索和远程MCP服务，覆盖必应、百度、微信公众号、DuckDuckGo、CSDN、GitHub 等多个搜索源，支持微信公众号、CSDN、掘金、GitHub README、Linux Do、小红书等文章内容抓取。 [Project Vibe Spec](https://github.com/dnwwdwd/project-vibe-spec)：用于 Vibe Coding 项目的协作与交付治理：把用户确认、项目事实、设计决策、实现、验证和进度维持在同一条可追溯链路上，同时避免把所有上下文塞进一个巨大的 AGENTS.md。
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)
码途：一个学习交流平台 - 开源
# 个人介绍 我是一名专升本目前在读的学生，我来编程导航已经快两年了，学习了很多技术，感谢鱼皮哥的平台，我参考鱼皮哥的项目 oj 刷题、面试刷题平台、智能协同云图库等视频教程，vibe coding了这样的一个微服务项目，整个项目编写周期有3个多月，花费了几百块的token，现在我把他开源出来，大家如果有需要的可以去GitHub上自取，记得点点 Star 感谢 ！ 地址：[github.com/peakui/matucode ](url) 介绍地址：https://www.rockui.cn/matucode/ # 项目介绍 码途（matu）是一个面向计算机专业学生与开发者的学习社区平台。它把「学、练、问、评」串成一条完整的链路：用教程与课程讲知识，用在线判题即时反馈，用面试题库备岗，用班级作业与排名支撑教学，用问答社区沉淀经验，再用 AI 助手降低学习与创作的启动成本。 项目采用四端协同 + 微服务后端的结构：Web 用户端供学习者使用，管理后台供运营维护内容，微信小程序与移动 App 覆盖移动场景；后端按业务域拆分为 14 个微服务，统一经网关鉴权，配套消息队列、缓存、搜索引擎与容器化判题沙箱。 # 技术栈 - 用户端 Web（matu-user）：React 19 · TypeScript · Ant Design 6 · Redux Toolkit · React Router 7 · Vite · Monaco Editor - 管理后台（matu_admin）：Vue 3 · Element Plus · Pinia · Vue Router · Vite · Sass - 微信小程序（matu-liteapp）：uni-app - 移动 App（matu-appp）：Flutter · GetX - 后端（matu-backend）：Java 17 · Spring Boot 3 · Spring Cloud（Nacos / Gateway / OpenFeign）· MyBatis-Plus · Flyway - 数据与中间件：MySQL 8（12 个业务库）· Redis · RabbitMQ · Elasticsearch 8 · PostgreSQL + pgvector（AI 向量检索） - 判题沙箱（matu-code-sandbox）：Docker · openjdk / python / gcc 镜像，容器级资源隔离 # 主页页面 ## 用户端      ## 管理端   ## 小程序端   ## APP端   感谢观看
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) ⭐
MOSAEL，一个开源的AI原生视频工作站。智能体、工作流、无限画布，你想要的TA都有！
 项目网站：https://mosael.com 开源地址：https://github.com/Alndaly/Mosael  其实本来很早之前就应该做一期来讲讲这个东西了，因为大概两周左右时间这个产品就已经有了第一个版本，但是由于还没有做任何测试，就一直拖着了。 而现在我感觉起码对于个人使用而言，基本没有太大的问题了（狗头🐶）。 > 今天就来简单聊聊这个产品。 ## 为什么做这个东西 开始的时候只是有一次尝试着用seedance2.5的模型api生成了一段视频，感觉相当🐮。 然后就开始沉迷于AI视频生成，但生成过程中意识到了一些实际的问题。 比如：下载一些网站上的素材可能需要找一些工具站点或者打开终端用脚本；写文案可能在 ChatGPT；生成图片如果用的GPT的话还好，用ComfyUI就需要换个阵营；生成视频又是一个平台（L站或者别的什么）；下载完以后再丢进剪辑软件（剪映或者达芬奇）。 **如此这一套不断循环往复。** 而且剪完还不算结束。 如果要做自媒体，还得再去小红书、抖音、B站、视频号、tk、油管一个个上传。 最终的素材管理又得自己使用百度网盘/本地文件夹分类。 再联想到之前的时候做的一些视频，我录制用的是macos自带/obs，剪辑用的是达芬奇，实际剪辑的时候还得一点点过视频找到没声音/说错话的地方，极其的麻烦，干脆将所有的问题集中到一个项目中解决。 所以这个产品并非是为了AI视频而生，更准确的来说是**为了解决视频制作过程中的麻烦的地方而生**。 于是有了 Mosael。 > 出发点其实是我自己感觉到了繁琐。 ## Mosael的核心其实分为五块 - 其一是**素材管理** - 其二是**剪辑页面** - 其三是**智能体** - 其四是**工作流** - 其五是**无限画布** ### 素材管理具有非常多的能力，我把大部分我常使用到的方面都加入了进去。 首先关于素材增加方面，除了常见且必备的从系统导入以外，比如屏幕录制、音频录制、摄像头录制、从链接导入（就是从各大媒体网站下载资源）。  其中不同素材之间支持细节对比。  ### 剪辑页面中包含一些常见的剪辑能力，以及我基于自媒体的一些特殊需求也做了一些扩充，比如逐字稿一键转写、逐字稿剪切、字幕自动生成、一键翻译字幕、AI配音、声音克隆等等，你可以自行探索。  ### 其中智能体贯穿着所有的模块，大部分的操作都可以通过这个智能体内完成，整个项目内，所有的能力我都将其完整接入到了其中。  - 有时间线、轨道、字幕、调色、变速等这些常见的剪辑能力 - 有工作流编辑、管理、执行等能力 - 有无限画布的编辑、管理能力 - 有素材的管理能力 比如可以直接和 Agent 说： > 帮我把XX视频里的废话删掉。 Agent 可以读取该视频，通过asr转为实时字幕，分析字幕，然后调用剪辑工具实际修改时间线。 如有必要，会先弹出确认，不会直接动你的项目。 ### 工作流也是一个比较重要的模块，可以把 AI 生成、素材处理、转写、配音、导出甚至发布串起来。  一些重复的事情，搭一次之后就可以直接跑，甚至你可以将其导出为工作流文件分享给他人，他人可以一键使用。 ### **至于无限画布，核心是便于创意发散**，在无限画布内，你可以自由引用、生成新的素材，并且进行拖动对比。  ## QA ### 1. 能直接发布到平台吗？ 对于真正做内容的人来说，导出之后还有一堆事情。 上传、填标题、选账号、定时发布…… 所以我干脆继续往后做了。 Mosael 现在可以管理不同平台的账号和浏览器环境，让视频从时间线一直走到最终发布。 我希望以后整个过程可以在一个地方完成： **素材 → AI → 剪辑 → 导出 → 发布** 不用中间来回倒腾文件。 ### 2. 数据在云端还是本地？ 关于这一点，有一些因素 - 个别视频素材很大 - 我希望能够使用到本地的算力 - 我希望可以接入本地框架（比如ComfyUI、Ollama等） 所以 Mosael 从一开始就是桌面应用。 工程、素材和很多数据都留在自己的电脑上，渲染也在本地完成。 AI 则自己选。 想用 OpenAI、Gemini 或其他 API 都可以，也可以接本地模型。 同时我也希望软件提供能力，但数据最终放在哪里，由用户决定。 ### 3. Mosael 接下来有哪些计划？ 现在里面已经有： 剪辑合成、智能体、工作流、无限画布、账号池...... > 其实原先这个项目的名称我起的是MibuCut，正是因为功能面开始扩充了导致cut显得过于细分，我改为了Mosael。 后续我会思考一些面向小型团队的交互和实际功能，毕竟现实中并非所有都是一人成军，确实也有着不少视频制作团队有着相似的困境。 ### 4. 有浏览器插件吗？ 有的有的。 配套的下载链接中已一起打包了chrome插件，你可以直接下载并开启chrome系列浏览器的开发者模式然后加载这个插件包即可。 插件提供的能力有如下： - 一键导入当前链接内的媒体视频到Mesael素材库 - 一键获取当前视频帧并导入Mesael素材库 - 一键生成当前视频字幕、逐字稿（还支持一键翻译），逐字稿支持点击跳转到指定的视频进度
【原创项目】Flow Forge - AI接口测试框架，支持Codex等智能体以及本地部署的弱模型
  为AI接口测试提供两条路径：可以把skill接入Codex等智能体，实现一键从生成到执行和报告；可以使用llama.cpp / Ollama 等本地弱模型结合AI工作流，实现用例生成。支持编写和执行一个完整的业务链路。提供GUI工作台。 ## 开源地址   需要把代码完整下载到本地，因为skill需要配套的代码才可以使用。GUI工作台在[GitHub release](https://github.com/Remon-16/flow-forge/releases)提供了Windows的安装包。仓库中也提供了一些做好的测试用例和报告供参考：[简单电商项目示例](https://github.com/Remon-16/flow-forge/tree/main/examples/foli-mall)。如果感觉这个项目有帮助的话，麻烦帮我点个star，感谢。如果项目有bug、任何不足之处或者需要新功能的话，也欢迎在评论区或者issues中提交，我会及时更新的。 [Flow Forge — 接口自动化测试框架](https://github.com/Remon-16/flow-forge) ## 功能特性 - **测试用例的特性**：测试用例就是yaml或者excel文件，把用例扔给执行器就可以直接运行。不过像是数据库、MQ和Redis这种插件可能还是需要一些代码（可以用智能体生成）。用例不光是单接口的用例，还支持整个业务链路的顺序执行。如果业务用例有问题，也会在报告中指出是哪一步出了问题：   - **Codex等智能体的SKILL**：这是我最推荐的一个用法。在 [flowforge-testing/](https://github.com/Remon-16/flow-forge/tree/main/flowforge-testing) 中，我本地测试这个SKILL用的是Codex + deepseek-v4-flash，可以从需求和接口文档直接完成用例生成、校验、执行插件的补充、执行以及分诊。**分诊就是它能够判断失败的用例是因为用例写错了，还是业务有bug。用例写错了还会自己改用例，直到通过或者确定是业务bug。** 有plan模式，可以先审核计划再执行后续任务。上面说的插件也可以让它来编写和测试。 - **llama.cpp / Ollama 本地模型的工作流**：我测试功能用的是Qwen3-8B-Q4_K_M，-c 64000。这种就是适合公司不让用API的内网用户尝试。弱模型幻觉还是比较明显的，所以[agent/](https://github.com/Remon-16/flow-forge/tree/main/agent)中提供了一个AI工作流，也是能够从需求和接口文档生成测试用例。有plan模式。有resume模式，可以从断点恢复执行。不过生成的用例基本上就是给搭个架子，需要修改的东西可能比较多。然后生成速度会慢一些（速度取决于LLM执行的速度以及设置合适的batchsize）。仓库里也有弱模型配置参考文件：[配置文件](https://github.com/Remon-16/flow-forge/blob/main/examples/foli-mall/raw/weak-model-config.example.yaml)。后面我会说一些我试过的模型以及踩过的坑。 - **Studio 桌面工作台（Windows）**：在[GitHub release](https://github.com/Remon-16/flow-forge/releases)里有Windows的安装包，可以直接运行。这个就是给智能体工作流、用例编辑器、用例执行器和用例转换器提供了UI界面。**首次使用需要在右上角设置`⚙`中配置python环境以及agent/和python/目录地址。**     - **用例执行器**：[执行器](https://github.com/Remon-16/flow-forge/tree/main/python)，内部有登录态管理器，通过`#{}`触发，能自动管理登录态（不过目前只验证过JWT这类的登录态），业务链路用例的每个步骤之间传数据也支持，有两级断言引擎（支持equals、数值比较、类型检查、包含、正则以及一些函数，详见[断言引擎](https://github.com/Remon-16/flow-forge/blob/main/python/docs/processors-and-report.md)），能并发执行用例（非压力测试，并且需要用例之间互斥），有插件系统（目前已经做了一些插件，这些插件也可以直接让智能体做）。因为执行器是CLI的，所以可以集成到Jenkins，每天定时执行这种功能也支持。 - **用例转换器**：[转换器](https://github.com/Remon-16/flow-forge/blob/main/python/docs/converters.md)，目前支持四种：excel2yaml、yaml2excel、yaml2pytest、excel2pytest。pytest是尽可能原生的（.py里有命令，可以直接执行），也会把所有的插件都打包，单独放一个包里。 ## 整体架构 ```mermaid graph TD REQ[需求文档] --> PA[路径 A：强智能体 + flowforge-testing skill] API[接口文档] --> PA REQ --> PB[路径 B：agent/ LangGraph 弱模型流水线] API --> PB PA --> |测试计划 + 人工审核| CASES[YAML / Excel 用例] PB --> |测试计划 + 人工审核| CASES CASES --> STUDIO[Studio 可视化编辑 / 批注] STUDIO --> EXEC[执行器] CASES --> EXEC EXEC --> REPORT[HTML 报告] EXEC --> |退出码 0/1/2| CI[Jenkins CI/CD] ``` ## 适合人群 1. 开发，但需要兼顾测试，需要工作留痕，可以试一试我的工具。建议用法是接入Codex + deepseek-v4-flash（不是不建议其他智能体或模型，因为其他的我暂时没试过。ds4f个人感觉够用）。AI生成用例并执行之后，会生成yaml文件和测试报告。这些用例文件可以直接用执行器来执行。项目内也提供了一个桌面应用，不需要每次都敲命令。后续万一有bug可以翻一翻用例文件，然后甩锅/doge。 2. 测试，但平时工作量比较饱和，可以从边缘业务开始尝试一下。建议用法也是接入Codex + deepseek-v4-flash。因为这个项目算是刚刚可用，可能很多特性或者功能还不算太完善，太复杂的用例可能不一定支持。如果公司对于测试质量的要求很高的话，可以先观望一下或者在issue中提一提需要的功能或特性。目前这个项目应付一下冒烟测试，或者用生成好的用例结合Jenkins做定期测试这种，大概是可以的。 3. 内网用户，仍然在手写用例，可以尝试一下。如果公司的模型相对强一些，可以试一试用智能体接入本地模型。但如果是Qwen3-8B-Q4_K_M这种级别的模型，也可以试试（我目前还没试过）。实在不行的话，用AI工作流也可以，至少搭个架子没问题。AI工作流也支持plan模式，也有UI界面。 > 在使用GUI运行AI工作流，测试计划审核环节，如果用的模型比较弱，对于一些简单的计划错误（比如多了某个用例，描述轻微不对），可以双击文本块后，在批注器右侧手动修改。测试计划修改是代码级别分块，然后对批注选中的块进行修改。但如果模型很弱的话，可能它会把批注的整个块都修改了，比较难做到“仅删除某个不需要测试的用例，仅把接口响应码改成404”这种指令。  ## 弱模型 + AI工作流使用经验   这个项目大概做了两个多月，期间试过deepseek4flash预览版、GLM-4.7-flash的免费API、Qwen2.5coder:14B(ollama，量化版本忘了)、Qwen3-8B-Q4_K_M(llama.cpp)和Qwen3.5-4B-Q4_K_M(llama.cpp)。   因为这个AI工作流主要是针对弱模型设计的，所以强模型千万不要尝试接入，有很多工程优化可能会浪费token。强模型直接往Codex接。比如deepseek-v4-flash正式版。   用AI工作流生成用例的话建议用Excel格式的用例做首轮编辑，因为对批量编辑更友好。如果需要做diff，再转化成yaml用例。 - GLM-4.7-flash的免费API，没有执行到最终结果，因为它会疯狂报500，然后每次请求需要间隔3秒左右，如果调用失败了需要等90秒，不然会报429 too many request（好像是）。agent/中有很多参数都是为了这种免费API搞的。中间产物的话，效果看起来还行，印象里体感上可能接近deepseek4flash预览版，但是生成个用例比本地部署模型还慢。大概是6月初测试的，记忆不一定完全准确。模型可能不错，但是API确实有些一言难尽，不推荐尝试API。 - Qwen2.5coder:14B和Qwen3-8B-Q4_K_M的思考模式，体感上差不多。Qwen3-8B-Q4_K_M生成测试计划的能力还是明显比2.5好的。虽然后面的业务链路用例生成的步骤有挺多时候直接都是不对，缺个步骤啥的，用例名称用例描述给生成个英文（有兜底翻译智能体）的等等，不过至少搭个架子还行。条件实在有限的话，应该也能凑合用。 >Qwen3-8B-Q4_K_M 偶尔会输出空的json数据`{}`，一般是执行到case生成环节出现，有时稳定复现，比如用例的描述“生成超长用户名1024”。像这种稳定复现的情况，修改一下描述，比如“生成较长用户名”，resume恢复执行，可能就过去了，后续再手动修改一下即可。 - Qwen3.5-4B-Q4_K_M，印象最深刻的就是它经常会输出空的json数据`{}`，运气成分比较大，也是没完整执行过。不过像是Qwen3-8B-Q4_K_M生成的用例，如果用例名称和用例描述生成的是非中文，agent/里提供了一个兜底智能体，能翻译用例。CLI命令也很简约，能自动识别用例类型并翻译。一行命令就可以。 ## 技术栈 | 组件 | 技术 | |------|------| | Studio 桌面应用 | Vue 3, Ant Design Vue, Vite, Tauri 2, TypeScript | | agent 弱模型流水线 | Python 3.12, LangGraph, OpenAI 兼容 API, prance (OpenAPI), pymupdf (PDF) | | skill 工具脚本 | Python 3.12（ff_tool / resolve_python，复用 python/ 执行器与转换器） | | 执行器与转换器 | Python 3.12, requests, openpyxl, pyyaml | | CI/CD | Jenkins Pipeline, 命令行退出码 | ## 结语   像是功能原理之类的，因为代码仓库里都有，所以我也就不赘述了。我做这个项目很大一部分原因是很多年以来就一直想自己做个什么项目，然后最好有人能觉得好用。现在AI编程发达了之后，正好我在自动化测试这块算是有点经验，所以就做了这个项目。如果对你有帮助的话，麻烦帮我点个star。如果项目有bug、任何不足之处或者需要新功能的话，也欢迎在评论区或者issues中提交，我会及时更新的。