工具
快来分享你的内容吧～
- 09-20 10:42·后端最近把自己开源的 重构了一遍。 做这个 Skill 的原因一直没变。 现在用 Codex、Claude Code 做项目，写代码已经越来越省事。问题慢慢跑到了另外一边：项目做久以后，Agent 开始忘，文档开始乱，方案改过几轮没人记得，代码写完了也不知查看全文加油鸭：太棒了！把项目状态管理得这么清晰又实用，这份重构思路既有深度又超接地气，为 Vibe Coding 项目提供了真正可持续的协作骨架！91013分享
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十几分钟就搞定了，初步测试😂453分享- 08-28 13:51·后端开发
- 08-05 10:48·云兮导航: https://www.xd
- 07-17 16:18·后端开发
学习开源项目时我们应该画哪些图？
大家好，我是不会喷火的小火龙。 刚开始深入看开源项目的时候，我经历过两个极端。 一个是纯靠肉眼硬看。连着翻了三天，几万行代码从头看到尾，自以为搞懂了，合上电脑脑子里依然是一团浆糊。 另一个是把精力全花在画图的排版上。打开 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配置被混在一起。按步骤逐项验证，哪一步不通就查哪一步，比反复卸载重装省事得多。 欢迎关注我的公众号【兮动人】，每天分享一些技术文章和实战经验。 
RKit：我常用的 uTools 工具的“轻量替代”
我以前一直用 `uTools`。 说实话，它在我这儿属于那种“装机必备”级别的工具：搜东西、翻译、截图、OCR、剪贴板……一堆日常零碎事，按个热键就能搞定。 但后来 uTools 越来越臃肿，也开始限制插件数量，这我还能忍，毕竟我平时用的插件也不多，最让我绷不住的是：**开始强制登录**了。 我不是说登录就一定不好，我只是很不喜欢“一个本来用来提升效率的小工具”，慢慢变成“需要账号体系才能用”的东西 于是我就去找“uTools 平替”。 我试了 `zTools`，确实和utools差不多，但用了一段时间总觉得有些地方不太对：要么是某个流程不顺手，要么是细节不符合我的习惯。也不是不能用，就是用的时候会忍不住嘀咕一句：“要是这里能这样就好了……” 结果我一想：我每天高频用的功能就那几个，**干脆我自己做一个算了**。 于是就有了 `RKit`。 --- ## RKit 是个啥？一句话 `RKit` 就是一个 **macOS 上的命令面板**(后面也会做 windows)，有点像 Spotlight： 按热键 → 弹出一个小面板 → 执行动作。 我不想做插件市场，也不想做一堆花里胡哨的功能。 我就想把我每天用的那几个能力做得**顺手、够快、够稳定**。 --- ## 它能干啥？就我常用的这几个 我现在最常用的是这些： - `截图`：区域截图 → 自动复制到剪贴板 → 顺手还能进内置编辑器改两笔 - `OCR`：对最近一次截图做文字识别（macOS 自带 `Vision`） - `翻译`：默认 Google GTX（不用 key），也可以配 Deeplx（自己搭个接口那种） - `剪贴板历史`：文本 + 图片，支持置顶/搜索，还能一键暂停采集 10 分钟 - `设置`：语言、热键录制、开机自启动、清理历史这些 你会发现，它就是“uTools 里我真正每天在用的那几个东西”。  --- ## 我做它最在意的点 ### 1）快：要像 Spotlight 那样“按下就出来” 默认热键是： - `Option + Space`：呼出/关闭 - `Esc`：关闭 我希望它是那种你不需要思考的动作： 手指一按，它就出现；你输入，回车，事情结束。 ### 2）别打扰：别把我从当前桌面/当前软件拽走 有些工具的面板会乱跳桌面，或者截图完又把焦点抢回去，这种我很难忍。 RKit 的目标是：**你在哪儿用，它就在哪儿出现**，尽量别干扰你的主工作流。 ### 3）本地优先：默认不联网 我个人比较敏感的一点是： 这种工具一旦开始“强制登录”，我就会下意识担心：我输入的东西、剪贴板、截图，会不会被上传、被统计、被分析？ RKit 的原则很简单： - 默认本地优先 - 只有“翻译”可能要联网（你选的翻译服务决定） --- ## 怎么装？（现在是未签名 ZIP） RKit 目前走的是 **未签名 ZIP** 发布（主打一个快，先让大家用起来）。 ### 安装步骤 1. 从 GitHub Releases 下载 `RKit.app.zip` 2. 解压得到 `RKit.app` 3. 把 `RKit.app` 拖到 `/Applications` 4. 打开运行 ### 如果被 Gatekeeper 拦了（无法打开 / 提示“已损坏”） 先确认你已经把 `RKit.app` 拖到了 `/Applications`，再执行： ```bash xattr -dr com.apple.quarantine /Applications/RKit.app ``` 然后 Finder 里右键 `RKit.app` → `打开`。 --- ## 权限这块：截图一定会要“屏幕录制” 截图功能需要 macOS 的“屏幕录制”权限： `系统设置 → 隐私与安全性 → 屏幕录制 → 勾选 RKit` 这块没啥好绕的，系统规则就是这样。 我能做的就是把引导写清楚、交互做顺，不搞那些“偷偷申请一堆你用不到的权限”。 --- ## 后续计划 我不会把 RKit 做成“全能工具”，我更想把它做成一种**很顺手的日常习惯**： 有什么我高频使用的功能，我会添加进去 也会尽快开发 windows 版本 --- ## 致谢 - Deeplx（DeepLX）：<https://github.com/OwO-Network/DLX> 感谢 DeepLX 开源项目：它使得在自建环境中通过本地 API 方式使用 DeepL 的免费网页翻译成为可能。 我就是使用本地部署的地址：  --- ## 最后 做 RKit 的起点其实很简单： 我只是想要一个“不臃肿、不强制登录、只做我常用功能”的工具。 如果你也跟我一样日常使用这几个工具，欢迎来试试看。 如果遇到什么问题，欢迎随时指出。 如果你觉得项目对你有帮助，欢迎点个Star，感谢！！ 项目地址：[https://github.com/Han-GR/rkit](https://github.com/Han-GR/rkit) 下载地址：[https://github.com/Han-GR/rkit/releases/download/v1.0.1/RKit.zip](https://github.com/Han-GR/rkit/releases/download/v1.0.1/RKit.zip)
codex同时使用官方账号与第三方 API
# Codex 双环境隔离：在同一台 Windows 上同时使用官方账号与第三方 API > 通过 `CODEX_HOME` 隔离 VS Code Stable、VS Code Insiders、ChatGPT Desktop 与 Codex CLI 的账号和 API 环境。 ## 1. 背景 大家好，这是一个简单的用户隔离操作，我在 Windows 上使用 Codex / ChatGPT / VS Code 插件时，遇到了一个需求： 由于plus账号的codex额度太少，5X的pro对于开发时间分布并不均匀的我来说会造成浪费 而且codex的风控让我不敢贸然使用ccswitch来切换账户 所以我希望在同一台电脑上同时保留两套 Codex 环境： - **官方账号环境** - VS Code Stable - ChatGPT Desktop / Codex Desktop - 普通 Codex CLI - 使用 ChatGPT 官方账号 - 走官方订阅额度 - **第三方 API 环境** - VS Code Insiders - 使用第三方 API 中转站 - 使用独立 API Key - 和官方账号完全隔离 - 不影响 Stable、普通 CLI 和 ChatGPT Desktop 一开始我以为只要安装两个 VS Code，或者使用 VS Code Profile，就可以实现账号隔离。实际测试后发现并不是这样。 最终可维护的方案是： > 不依赖 VS Code Profile，也不依赖 Stable / Insiders 天然隔离，而是通过 `CODEX_HOME` 为 Codex 创建独立的本地身份空间。 --- ## 2. 问题现象 ### 2.1 VS Code Profile 不能可靠隔离 Codex 账号 我创建了两个 VS Code Profile： ```text Codex-Official Codex-API ``` 但两个 Profile 中仍然显示同一个 Codex 账号。 这说明： ```text VS Code Profile 只能隔离编辑器设置、扩展列表、UI 状态； 不能可靠隔离 Codex 的认证状态。 ``` ### 2.2 Stable + Insiders 也不是天然隔离 后来我安装了： ```text VS Code Stable VS Code Insiders ``` 但如果不做额外配置，二者仍可能读取同一个默认 Codex 认证目录： ```text C:\Users\<用户名>\.codex ``` 结果就是： ```text Stable 和 Insiders 仍然可能显示同一个 Codex 账号。 ``` ### 2.3 启动脚本中注入代理会引入新的不稳定因素 我为了修复 reconnecting 问题，把代理变量注入 VS Code Insiders 启动脚本： ```powershell HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 ALL_PROXY=http://127.0.0.1:7897 ``` 后来出现了大量网络错误： ```text SSL handshake failed ERR_CONNECTION_CLOSED stream disconnected before completion error decoding response body ``` 排查后发现，第三方 API 可以国内直连，因此不应该把代理强行注入到 Insiders 进程中。启动脚本越复杂，后期越难定位问题。 --- ## 3. 最终架构 最终采用的结构是： ```text VS Code Stable / ChatGPT Desktop / 普通 Codex CLI ↓ C:\Users\...\.codex ↓ 官方 ChatGPT 账号 ↓ 官方订阅额度 VS Code Insiders 专用启动器 ↓ CODEX_HOME=C:\Users\...\.codex-insiders-api ↓ 第三方 API Key ↓ 第三方中转站，例如 https://lingsuan.top ``` 核心原则： ```text 官方账号环境和第三方 API 环境必须使用不同的 CODEX_HOME。 ``` --- ## 4. 目录规划 ### 4.1 官方账号目录 ```text C:\Users\...\.codex ``` 用途： ```text 官方 ChatGPT 账号 VS Code Stable ChatGPT Desktop 普通 Codex CLI ``` 这个目录不要动。 ### 4.2 第三方 API 隔离目录 ```text C:\Users\...\.codex-insiders-api ``` 用途： ```text VS Code Insiders 第三方 API 环境 保存 config.toml 和 auth.json ``` ### 4.3 Insiders 独立用户数据目录 ```text C:\Users\...\AppData\Local\VSCode-Insiders-API ``` 用途： ```text 隔离版 VS Code Insiders 的 user-data-dir 隔离 UI 状态、缓存、扩展 globalState ``` ### 4.4 Insiders 独立扩展目录 ```text C:\Users\...\.vscode-insiders-api\extensions ``` 用途： ```text 隔离版 VS Code Insiders 的扩展目录 ``` --- ## 5. Codex 配置文件 ### 5.1 config.toml 文件位置： ```text C:\Users\...\.codex-insiders-api\config.toml ``` 示例配置： ```toml cli_auth_credentials_store = "file" forced_login_method = "api" model_provider = "OpenAI" model = "gpt-5.6-sol" review_model = "gpt-5.6-sol" model_reasoning_effort = "xhigh" disable_response_storage = true network_access = "enabled" windows_wsl_setup_acknowledged = true [model_providers.OpenAI] name = "OpenAI" base_url = "中转站提供网址" wire_api = "responses" requires_openai_auth = true [features] goals = true ``` ### 5.2 关键字段解释 ```toml cli_auth_credentials_store = "file" ``` 表示认证信息保存在当前 `CODEX_HOME` 下的文件中，而不是系统凭据库。 ```toml forced_login_method = "api" ``` 表示这个环境只允许 API Key 登录，避免误用 ChatGPT OAuth 登录。 ```toml model_provider = "OpenAI" ``` 这里的 `OpenAI` 是本地 Provider 名称，不一定代表请求一定发往官方 OpenAI。 ```toml base_url = "中转站提供网址" ``` 表示请求发往第三方中转站。 ```toml wire_api = "responses" ``` 表示使用 Responses API 协议。 ```toml requires_openai_auth = true ``` 表示使用 OpenAI 风格的 Bearer Token，即从 `auth.json` 中读取： ```json { "OPENAI_API_KEY": "..." } ``` --- ## 6. API Key 放在哪里 API Key 不要写进： ```text config.toml 启动脚本 项目代码 README 环境变量 setx ``` 只写在： ```text C:\Users\...\.codex-insiders-api\auth.json ``` 格式： ```json { "OPENAI_API_KEY": "你的第三方 API Key" } ``` --- ## 7. VS Code Insiders 专用启动脚本 文件位置： ```text C:\Users\...\Tools\codex-insiders-api\Start-Codex-Insiders-API.ps1 ``` 脚本内容： ```powershell param( [string]$ProjectPath ) $ErrorActionPreference = "Stop" # 只设置 Codex 隔离目录，不注入代理 $env:CODEX_HOME = "$env:USERPROFILE\.codex-insiders-api" $UserDataDir = "$env:LOCALAPPDATA\VSCode-Insiders-API" $ExtensionsDir = "$env:USERPROFILE\.vscode-insiders-api\extensions" $CandidatePaths = @() $Cmd = Get-Command code-insiders -ErrorAction SilentlyContinue if ($Cmd) { $CandidatePaths += $Cmd.Source } $CandidatePaths += @( "D:\Microsoft VS Code Insiders\Code - Insiders.exe", "$env:LOCALAPPDATA\Programs\Microsoft VS Code Insiders\Code - Insiders.exe", "$env:ProgramFiles\Microsoft VS Code Insiders\Code - Insiders.exe", "${env:ProgramFiles(x86)}\Microsoft VS Code Insiders\Code - Insiders.exe" ) $InsidersExe = $CandidatePaths | Where-Object { $_ -and (Test-Path $_) } | Select-Object -First 1 if (-not $InsidersExe) { throw "未找到 VS Code Insiders 可执行文件。" } $Arguments = @( "--user-data-dir", $UserDataDir, "--extensions-dir", $ExtensionsDir, "--new-window" ) if ($ProjectPath) { if (-not (Test-Path $ProjectPath)) { throw "项目路径不存在：$ProjectPath" } $Arguments += $ProjectPath } Write-Host "Insiders executable: $InsidersExe" Write-Host "" Write-Host "=== Isolated Environment ===" Write-Host "CODEX_HOME = $env:CODEX_HOME" Write-Host "User Data Dir = $UserDataDir" Write-Host "Extensions Dir = $ExtensionsDir" Write-Host "Proxy = disabled" Write-Host "" Start-Process -FilePath $InsidersExe -ArgumentList $Arguments ``` 这个脚本只做三件事： ```text 1. 设置 CODEX_HOME 2. 指定 VS Code user-data-dir 3. 指定 VS Code extensions-dir ``` 不做： ```text HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY setx 注册表修改 ``` --- ## 8. 桌面启动器 文件位置： ```text C:\Users\...\Desktop\Codex Insiders API.cmd ``` 内容： ```bat @echo off powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\Tools\codex-insiders-api\Start-Codex-Insiders-API.ps1" pause ``` 如果想指定项目路径，可以写成： ```bat @echo off powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\Tools\codex-insiders-api\Start-Codex-Insiders-API.ps1" -ProjectPath "C:\Users\...\Desktop\question glm5.2" pause ``` 以后打开第三方 API 版 Insiders，只用这个入口。 不要使用普通的： ```text Visual Studio Code - Insiders.lnk ``` 否则可能不会加载专用 `CODEX_HOME`。 --- ## 9. 验证隔离是否成功 打开隔离版 VS Code Insiders 后，在集成终端执行： ```powershell $env:CODEX_HOME ``` 期望输出： ```text C:\Users\...\.codex-insiders-api ``` 检查代理是否为空： ```powershell $env:HTTP_PROXY $env:HTTPS_PROXY $env:ALL_PROXY ``` 期望为空。 检查配置： ```powershell Get-Content "$env:CODEX_HOME\config.toml" ``` 应看到： ```toml model_provider = "OpenAI" model = "gpt-5.6-sol" review_model = "gpt-5.6-sol" [model_providers.OpenAI] base_url = "https://lingsuan.top" wire_api = "responses" requires_openai_auth = true ``` 不要执行： ```powershell Get-Content "$env:CODEX_HOME\auth.json" ``` 因为里面是 API Key。 只检查是否存在： ```powershell Test-Path "$env:CODEX_HOME\auth.json" ``` --- ## 10. 验证官方环境是否未被影响 打开普通 PowerShell，不要从 Insiders 中打开。 执行： ```powershell $env:CODEX_HOME ``` 期望为空。 这说明普通 Codex CLI 仍然使用默认目录： ```text C:\Users\...\.codex ``` 不要在普通 PowerShell 中执行： ```powershell codex logout ``` 否则可能退出官方账号环境。 --- ## 11. 常见问题排查 ### 11.1 Insiders 仍显示官方账号 原因通常是： ```text 没有通过专用启动器启动 CODEX_HOME 没有生效 ``` 检查： ```powershell $env:CODEX_HOME ``` 必须是： ```text C:\Users\...\.codex-insiders-api ``` ### 11.2 出现 SSL handshake failed 如果看到： ```text SSL handshake failed ERR_CONNECTION_CLOSED ``` 优先检查： ```powershell $env:HTTP_PROXY $env:HTTPS_PROXY $env:ALL_PROXY ``` 如果不为空，说明仍然有代理注入。 最终方案不建议给 Insiders 注入代理，因为第三方 API 可以国内直连。 ### 11.3 出现 stream disconnected / error decoding response body 典型错误： ```text Error running remote compact task: stream disconnected before completion: Transport error: network error error decoding response body ``` 如果启动脚本无代理、`CODEX_HOME` 正确、`config.toml` 正确，那么这通常不是本地配置问题，而是第三方中转站对 Responses API streaming、长上下文、remote compact 场景兼容不稳定。 规避方式： ```text 1. 新建任务窗口，减少上下文长度 2. 不要在一个 Codex 会话里连续塞太多任务 3. 长任务拆成多个小任务 4. 换更稳定的中转站或模型 ``` --- ## 12. 维护原则 ### 12.1 只换 API Key 只改： ```text C:\Users\...\.codex-insiders-api\auth.json ``` 不要动： ```text config.toml 启动脚本 C:\Users\...\.codex ``` ### 12.2 只换模型 只改： ```toml model = "新模型ID" review_model = "新模型ID" ``` ### 12.3 换中转站 才改： ```toml [model_providers.OpenAI] base_url = "新中转站地址" ``` 必要时同步改： ```toml model = "新模型ID" review_model = "新模型ID" ``` --- ## 13. 最终经验总结 ### 13.1 VS Code Profile 不是 Codex 身份隔离边界 Profile 能隔离 UI 和扩展配置，但不能保证隔离 Codex 登录态。 真正可靠的隔离方式是： ```text CODEX_HOME ``` ### 13.2 Stable + Insiders 也不是天然隔离 两个 VS Code 版本可以帮助分离 UI，但如果它们读同一个： ```text C:\Users\...\.codex ``` 那么 Codex 账号仍然可能是同一个。 ### 13.3 启动脚本不要承担过多职责 启动脚本应该只负责： ```text CODEX_HOME user-data-dir extensions-dir ``` 不应该混入： ```text 代理 模型 API Key 业务项目配置 ``` 否则后期非常难排查。 ### 13.4 第三方中转的最大风险是 Streaming 兼容性 短请求能成功，不代表长任务、remote compact、上下文压缩也一定稳定。 如果总是在： ```text remote compact task stream disconnected error decoding response body ``` 阶段失败，优先怀疑中转站对 Responses API streaming 的兼容性。 --- ## 14. 最终推荐结构 ```text 官方环境： C:\Users\...\.codex → ChatGPT 官方账号 → Stable / Desktop / 普通 CLI 第三方 API 环境： C:\Users\...\.codex-insiders-api → 第三方 API Key → VS Code Insiders 专用启动器 启动脚本： 只设置 CODEX_HOME / user-data-dir / extensions-dir config.toml： 管理供应商、模型、base_url、wire_api auth.json： 只保存 API Key ``` 一句话总结： > 在同一台 Windows 电脑上同时使用 Codex 官方账号和第三方 API，真正可维护的方案不是切账号，而是用 `CODEX_HOME` 创建两个互不共享的 Codex 本地身份空间。 希望对大家有所帮助
GitHub 每周精选｜2026 W25
GitHub 上每天都会冒出很多新项目。 大多数我都会看过就忘。 有些看起来很酷，但装完就吃灰。 还有一些，会让我真的想留下来继续折腾。 我想把这些项目记录下来。 不追求“最火”。 只记录那些： 让我真正想装下来试试的东西。 --- ### 1. 人味 skill 项目名：renwei-writing GitHub 仓库地址： https://github.com/orange2ai/renwei-writing **这是继 web-access 之后，我基本上天天会使用的 skill，目前还不到 1k 的 star，暂时算是不温不火的状态** 从这个仓库名称也基本可以猜到这个仓库的作用到底是什么了，没错就是输出的时候更有人味 这里我没有单独去做一个用和不用这个 skill 输出的文本的实验了，因为自从用了这个 skill 之后，就基本没有在创作的时候不用这个 skill 了 如果你是一名创作者的话，这个 skill 大抵会让你爱不释手的 **虽然这个 skill 的效果确实很不错，但对于输出的内容并不能做到真正的全部使用，还是需要人的创作指导的，要不人味依然不会很高** ### 2. andrej-karpathy-skills 项目名：andrej-karpathy-skills GitHub 仓库地址： https://github.com/multica-ai/andrej-karpathy-skills Andrej Karpathy 在 26 年的 1 月发了一条推特，来聊了聊过去几周大量使用Claude编程的一些零散想法，**有 770 万次浏览量**，推特链接如下： https://x.com/karpathy/status/2015883857489522876 这里也简单介绍一下 Andrej Karpathy 的背景 Andrej Karpathy 是 AI 研究者与工程实践者，**OpenAI 创始团队成员之一**，后担任 Tesla Autopilot 视觉方向负责人 --- 在这条推特当中，Andrej Karpathy 聊到了现在 AI 智能体在编码时的一些问题，这里我还是觉得直接放原文会好一些，相信这也是大家在用 AI 智能体编码时多多少少会遇到的一个问题  为了解决上面的问题，就有这个仓库，ndrej-karpathy-skills 做的事情，就是把以上问题压缩成 4 条规则（**以下不是完整的 skill 内容**）： 1. 编码前先思考：不要默默假设，有歧义就说出来 2. 简洁优先：能 50 行解决，就不要写成 200 行 3. 精准修改：只动和当前任务有关的地方，不顺手重构 4. 目标驱动执行：不要只说“修一下”，而是定义可验证的成功标准 优先是很轻，可以直接将这个 skill 安装到 AI Agent 当中，或者直接写进 CLAUDE.md 或者 AGENTS.md 都是可以的，可以一定程度上解决上面的问题 **缺点也是比较明显的，它不是强约束**，它不会像类型系统、测试、lint 那样硬性拦住错误，能减少犯错的概率，但并不能杜绝错误的发生 比如关于 "编码前先思考" 这点，用 superpower 的效果会更好 --- 至于使用人群的话，如果你打算用 AI 认真写代码，那么值得一试，它做了一件很朴素的事情：**AI coding 的下一步，不只是让模型更会写代码，也要让模型少乱写代码**  ### 3. guizang-social-card-skill 项目名：guizang-social-card-skill GitHub 仓库地址： https://github.com/op7418/guizang-social-card-skill 藏师傅的新作品，之前也有推荐过藏师傅的 PPT skill，感兴趣的话可以点击下面的链接去看一下 https://zhuanlan.zhihu.com/p/2040526006285509057 优点有如下几个： 第一：延续上次 guizang-ppt-skill 的两种风格，审美起点更高 不是让你从零调字体、颜色、间距，而是先给你一套有约束的视觉语言。这个约束反而是好事，因为大多数内容图做丑，不是因为自由不够，而是因为自由太多 第二：适合长文拆图 说成大白话就是为文章配图，将一片文章拆成 5 到 9 张小红书卡片，它能从结构、标题、重点句、截图排布这些地方一起处理，不只是做一张封面 第三：修改成本低 最初的产物是单文件 HTML，再用 Playwright 渲染成 PNG。HTML 和 CSS 都能继续改，出问题也能查，不像很多在线设计工具，最后只剩一个不可控的导出结果 当然我也需要说一说局限性，原配的 skill 主要是生成小红书和公众号内容的，这两个平台的图片比例为 3:4 和 21:9，**对于 4:3 和 16:9 比例的支持稍微差一些**，我第一次在生成 16:9 的配图时出现了配图模糊的情况，后续在原配的基础上进行一些改进，顺利的解决了这个问题，这一点有必要告诉大家  ### 4. agent-skills 项目名：agent-skills GitHub 仓库地址： https://github.com/addyosmani/agent-skills 区别于很多 "角色大全" 式的 skill 合集，产品、运营、设计、销售、法务、数据分析都来一点，看起来很全 agent-skills 的重心收得很窄，基本围绕软件开发这条线展开：**从需求澄清、写规格、拆任务，到编码、测试、调试、代码审查、安全、性能、CI/CD、发布、监控和迁移废弃** 所以它更像是把一个资深工程团队的日常习惯拆开，写成 AI coding agent 可以照着执行的工作流 里面不只是“你是一个前端工程师”这种角色设定，还会告诉agent：什么时候该写 spec，什么时候该停下来补测试，什么时候该做安全检查，什么时候该考虑回滚和可观测性等等  ### 5. whisper 项目名：whisper GitHub 仓库地址： https://github.com/openai/whisper 如果单说功能的话，这个仓库的功能是极其简单的： 将视频 / 音频转换成文字稿 而且这个文字稿也不是完美的。**它不会顺手帮你清理语气词，不会自动帮你删除重复表达，对一些专业名词、人名、品牌名的识别也不总是稳定。**你如果拿它的结果直接发出去，往往还是要自己再校对一遍 对于做字幕，没有剪映方便 对于视频会议的转写也没有腾讯会议、飞书会议方便 对于只是偶尔转一段采访或者播客，现在市面上也有很多现成工具能做，比如 TurboScribe、Riverside、VEED、Otter、Notta，中文场景里还有飞书妙记、通义听悟这类产品，很多都比它更省事 --- 那我为什么还想要来推荐这个仓库呢？ 第一点是，**它足够便宜**，准确点说，是几乎没有使用门槛上的持续成本 很多在线转写产品表面上能免费试，但真正想长期用，要么限制分钟数，要么限制文件大小，要么导出字幕和全文稿时开始收费 Whisper 不一样。环境装好、模型下载好之后，它就是一个可以一直放在你电脑上的本地工具。你不用反复算时长，也不用担心哪天平台把免费额度收紧 第二点是，**它是本地可控的** 你的视频、录音、采访、会议材料，不需要上传到第三方网站。这个差别平时不明显，但一旦素材涉及客户、内部沟通、未发布内容、个人隐私，你就会知道“本地处理”这四个字有多值钱。很多产品更方便，但方便的代价就是文件先出去；Whisper 不是。 第三点是，它虽然简单，但它简单得很像一个基座 很多成品工具解决的是“给你一个结果”，Whisper 解决的是“把音频转文字这一步，变成你自己手里的一项能力” 你可以拿它输出 .txt、.srt、.vtt、.json，然后继续接自己的工作流：字幕、归档、摘要、检索、内容拆条、AI 总结，后面怎么接都行 这也是它和剪映、飞书会议、腾讯会议这类工具最大的差异点。那些工具是成品，目标是让普通用户少折腾；Whisper 是底层能力，目标是让你自己决定后面怎么用 它的优点说白了就三个：免费、本地、通用 它的缺点也很明确：不够傻瓜、不够省心、结果不够干净、后处理要靠自己 --- 所以它并不是一个适合所有人的仓库 如果你只是想偶尔给视频加字幕，剪映更合适 如果你主要是开会并且想自动生成纪要，腾讯会议、飞书会议更合适。 如果你不想碰命令行，也不想自己管模型和环境，那各种在线转写网站也更合适 --- 但如果你属于下面这几类人，Whisper 就很值得看一眼： 你经常要处理录音、播客、口播、采访、课程、会议素材； 你在意隐私，不想把文件上传到第三方平台； 你想把“音频转文字”这一步沉淀成一个长期可用的本地能力； 或者你是开发者，后面还想接字幕、摘要、检索、自动化流程 对这些人来说，Whisper 的价值不在于它做得比所有产品都更好，而在于它把最基础、也最关键的一步，稳定地交回到了你自己手里。 如果要给它一句比较准确的定位，我会更愿意这么说： **Whisper 不是最好用的视频转文字产品，但它是很值得拥有的本地转写底座**  --- 最后： 后面肯定还会继续遇到： 让我真正想装下来试试的项目。 这个系列也会继续更新下去。