工具
快来分享你的内容吧～
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-05 10:48·云兮导航: https://www.xd
- 07-17 16:18·后端开发
06-10 11:59·全干的耄耋之神，老登的年纪且登味为0，只
06-08 12:03·Java后端llm-wiki 不是另一个笔记软件，而是一个面向 AI Agent 时代的本地长期记忆层。查看全文加油鸭：这个开源项目太棒了！把AI会话沉淀为可检索、可维护的本地知识库，思路清晰又实用，为开发者提供了真正可持续的长期记忆方案。837分享
告别 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 不是最好用的视频转文字产品，但它是很值得拥有的本地转写底座**  --- 最后： 后面肯定还会继续遇到： 让我真正想装下来试试的项目。 这个系列也会继续更新下去。
Codex Plus会员现阶段靠谱的氪金教程
### 写在前面：为什么要氪金 Codex Plus？ 这篇教程适合想和我一样，准备用 Codex 做一些练习项目来强化 **vibe coding** 技能的同学。在 vibe coding 练手的时候，最怕的就是对 token 消耗有焦虑，打断学习的道心。用上官方纯净、无套路的 Codex，才是我认为比较高效的解法。 **核心建议：** 不要总想着蹭免费额度，打个比方氪金648和买一个正版3A游戏的钱花在Codex上,足够你用一段时间搞好几个Vibe Coding项目了，甚至有机会助你找到工作拿到心仪的Offer，这样看这笔自我提升的投资绝对划算。实测也是Codex的额度足够学习Vibe Coding和做一些赋能中小项目用了。  --- ### 注册与验证避坑指南 OpenAI 体系（包含 ChatGPT 和 Codex）对注册的地区有严格限制，这里提供一个目前最稳的接码方案： * **接码建议：** 注册时推荐使用 **Vietnam的 xuni号码**。这是目前实测下来过 ChatGPT 手机验证最方便、成功率最高的途径。 * **虚拟号码网站：** 首选5sim，Vietnam号码一个0.1刀左右，网站上充个10RMB 备用最佳。 ### 费用预算与充值渠道 * **官方费用：** 20 刀 / 月（一般代充高于这个价，低于20刀懂得都懂） * **氪金方式（懒人版）：** 推荐直接在**某宝找靠谱的店铺**协助解决支付问题（如代充或购买正规的虚拟信用卡）。挑选时注意多看评价和店铺信誉，切忌贪小便宜购买低价黑卡，以免导致账号被封禁。店铺一定要承诺保30天使用，对话留据。对方一般会加wx帮你做单子，那头有额外费用的话你就说是以某宝订单为准防一手套路。 * **最佳氪金方案：** 有能力正规银行注册一张可以国际支付的VISA那更稳了，付款认准OpenAI官方。我后续会开一张国际支付能力副卡，专门充AI相关的工具，省得和某宝商家斗智斗勇了。 * **验收方式：** 侧边栏左下角出现剩余用量说明会员成功激活，当然你还需要亲自对话试一轮才能真正完成验收（最好是你vibe coding项目测试各模型真实能力，和免费额度部分作对比，防止一开始拿到降智模型）。  ### 日常使用必备环境 * **网络要求：** **使用时科学上网必备**。 * **注意事项：** 建议使用固定且纯净的节点，不要频繁切换国家和地区，以防触发系统的安全风控。保持网络环境的稳定，才能让你的 vibe coding 体验丝滑无卡顿。最好注册好ChatGPT账号，再去搞氪金plus会员的事。我个人已经成功用了半个月，才来分享这套使用方案的，早知道注册个VISA再搞了。
llm-wiki：把 AI 会话沉淀成可长期复用的本地知识库
> 开源地址：[https://github.com/fengguanghuai/llm-wiki](https://github.com/fengguanghuai/llm-wiki) > 关键词：AI Agent、长期记忆、知识库、Claude Code、Codex CLI、Gemini CLI、Markdown、Python CLI ## 一、为什么需要 llm-wiki 过去一段时间，越来越多开发者开始把 Claude Code、Codex CLI、Gemini CLI 等 AI Agent 融入日常研发流程。它们能帮我们读代码、改代码、排查问题、整理文档，甚至在多仓库、多工具链之间协作。 但实际用久了之后，会遇到一个很明显的问题： > AI 会话很多，真正可复用的经验却很容易散落在历史记录里。 比如： - 某个 adapter 当时为什么这样解析会话文件？ - 某次 sync 输出文件为什么发生覆盖，后来是怎么修复的？ - 某个 CLI 命令的参数和目录约定在哪里说明过？ - 某个项目设计决策能不能被不同 AI Agent 共享？ 如果每次都让 AI 从零开始问、从零开始读、从零开始猜，长期来看会浪费大量上下文成本。 `llm-wiki` 的目标就是解决这个问题：**把多个 AI Agent 的会话记录和人工精选笔记，沉淀成一份本地 Markdown 知识库，让它成为可检索、可维护、可迁移、可长期复用的项目记忆。** ## 二、项目简介 `llm-wiki` 是一个本地 Python CLI 工具，命令名是 `pel`。 它可以把 Claude Code、Codex CLI、Gemini CLI 等工具产生的本地会话记录转换为 Markdown，并按照 `raw/`、`wiki/`、`inbox/`、`concepts/`、`entities/` 等目录约定组织起来。 项目特点很克制： - **本地优先**：知识库就是一堆 Markdown 文件，没有数据库绑定。 - **零第三方运行依赖**：Python 3.11+ 标准库实现，不依赖 Node.js、不强制虚拟环境、不需要额外服务。 - **显式沉淀**：不是黑盒自动总结，而是 `capture → inbox → promote` 的可控流程。 - **多 Agent 共享**：Codex、Claude Code 等可以通过同一个 `SKILL.md` 指向同一个 wiki 根目录。 - **可追溯**：原始会话放在 `raw/`，长期结论放在 `wiki/`，修订写入 `log.md`。 一句话概括： > llm-wiki 不是另一个笔记软件，而是一个面向 AI Agent 时代的本地长期记忆层。  ## 三、它解决的核心问题 ### 1. AI 会话历史难复用 AI Agent 的会话记录往往保存在各自工具目录里，比如： - Claude Code：`~/.claude/projects/*/*.jsonl` - Codex CLI：`~/.codex/sessions/`、`~/.codex/archived_sessions/` - Gemini CLI：`~/.gemini/tmp/` 这些文件对工具自己有用，但对人来说并不适合直接阅读，也不方便跨工具检索。 `llm-wiki sync` 会把它们转换成统一的 Markdown： ```bash pel sync ``` 转换后，会话会进入： ```text raw/sessions/<adapter>/ ``` 比如： ```text raw/sessions/claude_code/ raw/sessions/codex_cli/ raw/sessions/gemini_cli/ ``` 这样原始证据就被保留下来了。 ### 2. 原始记录和长期知识混在一起 会话记录很长，里面有命令输出、工具调用、尝试过程、上下文噪音。它们适合作为证据，但不适合作为最终知识。 所以 `llm-wiki` 把知识库分成两层： ```text raw/ # 原始素材，只读证据层 wiki/ # 长期沉淀，可维护知识层 ``` 你可以先把一条结论捕获到 inbox： ```bash pel capture "Claude Code 子会话输出文件名应优先使用源文件 stem，避免多个 agent-*.jsonl 因父 sessionId 相同而互相覆盖。" ``` 再把它提升到长期页面： ```bash pel inbox pel promote <inbox-note> --to memory ``` 也可以提升到不同类型的知识页： ```bash pel promote <inbox-note> --to concept pel promote <inbox-note> --to entity pel promote <inbox-note> --to project pel promote <inbox-note> --to synthesis ``` 这套流程的好处是：**原始材料保留，长期结论可控。** ### 3. 多个 AI Agent 无法共享记忆 很多人会同时使用多个 AI 工具，比如： - Codex 负责代码修改 - Claude Code 负责复杂阅读和重构 - Gemini CLI 用来辅助分析 如果每个工具都有一套自己的历史和记忆，最终会变成“多个孤岛”。 `llm-wiki` 的设计是：所有 Agent 共享一个中心 wiki。 初始化时可以加上： ```bash python -m pelib.cli init --wiki-root "../LLM-WIKI Vault" --title "My LLM Wiki" --link-agents ``` 它会生成共享 skill，并链接到： ```text ~/.codex/skills/llm-wiki ~/.claude/skills/llm-wiki ``` 这样 Codex 和 Claude Code 看到的是同一份知识库，而不是各自复制一份。 ## 四、目录结构设计 初始化后，wiki 根目录大致如下： ```text <wiki_root>/ ├── CLAUDE.md ├── AGENTS.md ├── raw/ │ └── sessions/ ├── wiki/ │ ├── index.md │ ├── MEMORY.md │ ├── log.md │ ├── inbox/ │ ├── concepts/ │ ├── entities/ │ ├── projects/ │ ├── syntheses/ │ └── playbooks/ ├── site/ └── outputs/queries/ ``` 几个核心目录的定位： | 目录 | 作用 | |---|---| | `raw/` | 原始素材和会话转换结果，尽量只读 | | `wiki/MEMORY.md` | 长期记忆的简短结论 | | `wiki/inbox/` | 临时捕获，等待整理 | | `wiki/concepts/` | 可复用概念，例如“Session Adapter 输出命名策略” | | `wiki/entities/` | 实体页，例如某个系统、工具、模型、项目 | | `wiki/projects/` | 项目专题 | | `wiki/syntheses/` | 综合分析和阶段性总结 | | `wiki/log.md` | 操作与修订日志 | 这个结构有一个很重要的原则： > raw 保留证据，wiki 沉淀判断，log 记录变化。 ## 五、快速开始 ### 1. 克隆项目 ```bash git clone https://github.com/fengguanghuai/llm-wiki.git cd llm-wiki ``` ### 2. 初始化知识库 ```bash python -m pelib.cli init --wiki-root "../LLM-WIKI Vault" --title "My LLM Wiki" ``` 如果希望自动为 Codex / Claude Code 创建共享 skill 链接： ```bash python -m pelib.cli init --wiki-root "../LLM-WIKI Vault" --title "My LLM Wiki" --link-agents ``` 在 Windows 上，如果创建符号链接遇到权限限制，可以先不加 `--link-agents`，后续手动配置或以管理员权限处理链接。 ### 3. 查看状态 ```bash python -m pelib.cli status python -m pelib.cli doctor ``` `status` 用来看当前项目指向哪个 wiki 根目录，`doctor` 用来检查必要文件是否存在。 ### 4. 同步历史会话 先 dry-run： ```bash python -m pelib.cli sync --dry-run ``` 确认没有问题后正式同步： ```bash python -m pelib.cli sync ``` 也可以只同步某个 adapter： ```bash python -m pelib.cli sync --adapter claude_code python -m pelib.cli sync --adapter codex_cli python -m pelib.cli sync --adapter gemini_cli ``` ### 5. 捕获和沉淀结论 ```bash python -m pelib.cli capture "这是一条值得长期复用的工程经验" python -m pelib.cli inbox python -m pelib.cli promote <inbox-note> --to memory ``` ### 6. 检索知识库 ```bash python -m pelib.cli query "adapter 输出冲突" python -m pelib.cli query "capture promote" python -m pelib.cli query "旧知识库迁移" ``` ### 7. 修正知识并留痕 如果你手动修改了某个页面，可以追加一条修订记录： ```bash python -m pelib.cli correct "wiki/MEMORY.md" "修正了某条结论的适用范围" ``` ## 六、命令速查 | 命令 | 说明 | |---|---| | `init` | 初始化配置、wiki 骨架和共享 skill | | `status` | 查看项目配置和 Agent 链接状态 | | `doctor` | 检查 wiki 根目录、AGENTS.md、CLAUDE.md、shared skill | | `write-skill` | 重新渲染共享 SKILL.md | | `link-agents` | 将 shared skill 链接到 Codex / Claude Code | | `sync` | 同步本机 AI 会话到 raw/sessions | | `capture` | 捕获一条待整理结论 | | `inbox` | 查看待整理结论 | | `promote` | 将 inbox 内容提升到长期页面 | | `promote-batch` | 批量提升 inbox 内容 | | `query` | 检索长期知识页 | | `correct` | 记录人工修订日志 | | `adapters` | 查看已注册 adapter | ## 七、适合哪些场景 ### 1. 开源项目的设计决策沉淀 比如一个工具项目会持续出现这类问题： - CLI 命令为什么这样设计 - adapter 如何兼容不同工具的会话格式 - raw 和 wiki 两层目录为什么要分开 - Windows 下符号链接失败时如何处理 - 同步时如何避免重复转换和输出覆盖 - 旧知识库迁移时哪些内容应保留 这些内容很多不会自然出现在 README 里，但它们会影响后续维护和贡献者理解。 `llm-wiki` 适合把这些设计背景沉淀下来，后续让 AI 先查项目记忆，再参与代码修改或文档补充。 ### 2. 多 AI 工具协作 如果你同时用 Codex、Claude Code、Gemini CLI，`llm-wiki` 可以作为它们共享的本地记忆层。 一个 Agent 今天沉淀的知识，另一个 Agent 明天可以读取。 ### 3. 需要本地化和可控性的知识库 相比云端知识库，`llm-wiki` 更适合对本地可控性有要求的场景： - Markdown 文件可直接查看 - Git 可版本管理 - Obsidian 等工具可直接打开 - 不绑定某个 SaaS 平台 - 不依赖数据库迁移 ## 八、设计取舍 `llm-wiki` 没有把目标做成“大而全”的知识管理平台，而是选择了几个很明确的取舍。 ### 1. 不做黑盒记忆 它不会偷偷把所有会话总结成某种不可见的向量库，而是把过程暴露出来： ```text capture → inbox → promote ``` 你知道哪些内容被沉淀了，也可以随时修改。 ### 2. 不绑定数据库 知识库就是 Markdown 文件。 这意味着： - 可以直接 grep - 可以用 Git 做版本管理 - 可以用 Obsidian 打开 - 可以被任意 AI Agent 读取 ### 3. 不追求复杂依赖 项目使用 Python 3.11+ 标准库实现，运行依赖尽量保持为零。 这对本地工具很重要：越少依赖，越容易长期维护。 ## 九、一个项目相关案例 下面用 `llm-wiki` 项目本身举一个例子：在重新同步历史会话时，发现 Claude Code 和 Gemini CLI 的部分会话会输出到同一个 Markdown 文件，导致后写入的内容覆盖先写入的内容。 第一步，同步会话： ```bash pel sync ``` 第二步，把问题和修复结论捕获下来： ```bash pel capture "Session adapter 生成输出路径时，不能只依赖事件里的 sessionId；遇到子会话或同 sessionId 多文件时，应优先使用源文件 stem 保证输出唯一。" ``` 第三步，提升为概念页： ```bash pel inbox pel promote <note> --to concept --title "Session Adapter 输出命名策略" ``` 以后再维护同步逻辑时，就可以： ```bash pel query "输出命名策略" ``` 或者让 AI Agent 先读取 `llm-wiki`，再结合当前 adapter 代码和测试做判断。 这样，一次修复就不只是一次提交，而会变成可复用的项目维护知识。 ## 十、当前版本定位 当前项目更像是一个面向开发者和小团队的本地知识库基础设施，重点解决： - 会话历史归档 - 多 Agent 共享记忆 - 显式知识沉淀 - Markdown 化长期维护 - 本地优先和可迁移 它不是为了替代 Obsidian、语雀、Notion 这类笔记工具，而是更偏向于成为 AI Agent 的“工作记忆底座”。 如果你已经在日常研发里大量使用 AI Agent，那么 `llm-wiki` 可以帮你把这些碎片化会话变成长期资产。 ## 十一、总结 AI Agent 能提升单次任务效率，但真正的长期收益来自知识复用。 `llm-wiki` 做的事情很朴素： - 把会话留下来 - 把结论挑出来 - 把知识组织好 - 让不同 Agent 都能读 - 让历史经验能被下一次任务复用 对于经常使用 AI 辅助研发的人来说，这类本地长期记忆工具会越来越重要。 项目地址： [https://github.com/fengguanghuai/llm-wiki](https://github.com/fengguanghuai/llm-wiki) 欢迎试用、提 issue，也欢迎根据自己的工作流改造。