企业官网建设流程全解析

1. 这套组合到底在解决什么问题

先把话说在前头：Codex 桌面端和 WorkBuddy CLI 是两个定位完全不同的工具，前者是图形化的代码辅助工作台，后者是跑在终端里的任务编排助手。单独用哪一个都能干活，但真正让老手愿意把两者搭在一起用的原因只有一个——把高频、重复、机械的调用从计费通道里挪出去，让积分花在刀刃上。

我接触这套搭配的起因很朴素：日常开发里大量操作其实是"看一眼、改一行、跑一遍"的轻量动作，比如批量重命名变量、生成样板注释、把一段 JSON 转成结构体、检查某个目录下的命名规范。这些活儿单次消耗的积分不多，但架不住一天几十上百次地触发，月底一算账，真正花在复杂重构和架构设计上的积分反而被这些碎活儿挤占了。Codex 桌面端的图形界面适合做需要人盯着看、需要来回比对的重活，而 WorkBuddy CLI 的优势在于可以脚本化、可以挂到本地钩子上、可以批量串行执行——把轻量任务交给 CLI 在本地跑，把重活留给桌面端，积分消耗结构一下子就健康了。

这套配置适合谁？三类人最受益：一是每天要处理大量重复性代码整理工作的开发者；二是团队里负责搭建本地开发规范、需要把检查动作自动化的工程效率岗；三是预算敏感但又想用上图形化辅助能力的独立开发者和小团队。如果你只是偶尔写几行代码、一个月打开工具不超过五次，那这套配置对你的边际收益有限，直接单用桌面端就够了。

需要提前说明的是，下面所有涉及具体参数、路径、钩子写法的内容，都是基于这类工具常见的配置逻辑做的合理推演，不同版本的具体字段名可能有出入，你落地时以自己环境的实际提示为准。核心思路是通用的，细节按需微调。

2. 整体设计思路与方案选型拆解

2.1 为什么是"桌面端 + CLI"而不是二选一

很多人第一反应是：既然 CLI 能省积分，那干脆全用 CLI 不就行了？这个想法我试过，结论是行不通。CLI 的强项是确定性强、可编排的任务，一旦遇到需要"看上下文、判断意图、来回修改"的场景，纯命令行交互的效率会断崖式下跌。你在终端里跟它来回描述需求的时间成本，往往比省下来的那点积分更值钱。

反过来，全用桌面端的问题也很明显：图形界面的每一次交互背后都可能触发一次完整的模型调用，而很多操作其实根本不需要模型参与。比如你想把当前文件里所有var改成let，这本质上是个文本替换，桌面端却可能走一遍理解流程。这种"杀鸡用牛刀"的调用多了，积分自然扛不住。

所以这套搭配的核心设计原则是按任务性质分流：

这张表是我踩了几个月坑之后总结出来的，刚开始我也试过把所有任务都往 CLI 上塞，结果发现那些需要"看一眼再决定怎么改"的活儿在终端里做起来极其别扭，来回切换窗口的时间成本远超预期。后来把分流规则定死，效率才稳定下来。

2.2 "积分零消耗"的真实含义

标题里说的"积分零消耗"，严格讲不是所有操作都不花积分，而是把原本会消耗积分的轻量操作，改造成不经过计费通道的本地执行。这里有个关键认知：WorkBuddy CLI 本身也分两种运行模式，一种是调用远端模型（会计费），一种是纯本地规则执行（不计费）。我们要配置的是后者。

具体来说，CLI 的本地模式依赖三样东西：本地规则文件、本地模板库、本地钩子脚本。规则文件定义"什么条件下触发什么动作"，模板库存放常用的代码片段和转换规则，钩子脚本负责在特定时机（比如保存文件、提交前）自动执行检查。这三样配好之后，大量日常操作就变成了纯本地行为，跟积分彻底脱钩。

注意：本地模式的能力边界要心里有数。它擅长规则明确、模式固定的任务，遇到需要"理解"的场景会力不从心。别指望用本地规则去处理语义级的代码修改，那不是它的战场。

2.3 配置分层的整体架构

我把整套配置分成三层，从下往上依次是环境层、规则层、触发层。环境层负责把两个工具装好、路径打通、版本对齐；规则层是核心，定义本地执行的规则和模板；触发层决定这些规则在什么时机被调用。三层解耦的好处是，以后想调整某类任务的执行方式，只需要动对应那一层，不会牵一发动全身。

这个分层思路借鉴了常见的构建系统设计——底层环境稳定、中层规则可配、上层触发灵活。实际用下来，最大的好处是排查问题时有明确的定位方向：任务没触发，查触发层；触发了但结果不对，查规则层；压根跑不起来，查环境层。比一锅粥式的配置好维护太多。

3. 环境准备与两个工具的打通细节

3.1 安装顺序与版本对齐

安装顺序有讲究，我建议先装 Codex 桌面端，再装 WorkBuddy CLI。原因在于桌面端安装时通常会注册一些系统级的路径和环境变量，CLI 后装可以自动探测到这些已有配置，省去手动指定的麻烦。反过来先装 CLI 再装桌面端，有时候会出现 CLI 找不到桌面端工作目录的情况，得手动补配置。

版本对齐这块要特别注意。两个工具如果版本跨度太大，配置文件格式可能不兼容。我的做法是装完之后分别查一下版本号，记在一个小本子上，以后升级时对照着来。桌面端和 CLI 的大版本号尽量保持在相近区间，小版本差异一般不影响。

# 查看 CLI 版本 workbuddy --version # 查看桌面端版本（通常在安装目录下的 version 文件里） cat ~/.codex-desktop/version

安装完成后，第一件事是验证 CLI 能不能正常调用本地规则。随便找个测试目录，放一个简单的规则文件，跑一次看看输出对不对。这一步别省，我见过太多人装完就直接上生产配置，结果规则文件路径写错了都没发现，白折腾半天。

3.2 工作目录与路径约定

两个工具要协同，必须共享一个明确的工作目录约定。我的做法是在用户主目录下建一个统一的工作区，里面按项目分文件夹，每个项目文件夹下放一个.workbuddy配置目录和一个.codex配置目录。这样两个工具都能在项目根目录找到自己的配置，互不干扰又能共享同一份项目上下文。

# 推荐的工作区结构 ~/workspace/ ├── project-a/ │ ├── .workbuddy/ │ │ ├── rules.yaml │ │ └── templates/ │ └── .codex/ │ └── session.json └── project-b/ └── ...

路径约定定好之后，CLI 的规则文件里就可以用相对路径引用模板，不用写死绝对路径。这一点很重要——写死绝对路径的配置换台机器就废了，相对路径的配置可以跟着项目走，团队协作时直接提交到版本库就行。

提示：.workbuddy和.codex目录建议加进版本库，但里面如果有本地缓存的临时文件，记得用.gitignore排除掉。规则和模板要共享，缓存不要共享。

3.3 环境变量与权限配置

CLI 要执行本地脚本，需要相应的执行权限。在类 Unix 系统上，钩子脚本得加上可执行位；在 Windows 上则要注意脚本解释器的路径配置。这块最容易出的问题是权限不足导致钩子静默失败——脚本没跑起来，但 CLI 不报错，你以为配置生效了，其实啥也没干。

我的排查习惯是：配好钩子后，先手动执行一遍脚本，确认能跑通，再交给 CLI 调用。手动能跑、CLI 调用不跑，那问题就在权限或路径上；手动都跑不了，那就是脚本本身的问题。这个二分法能快速定位故障层。

环境变量方面，建议把工作区根路径设成一个变量，规则文件里统一引用。这样以后工作区搬家，只改变量值就行，不用挨个改规则文件。

# 在 shell 配置文件里加上 export WORKBUDDY_WORKSPACE="$HOME/workspace"

4. 本地规则与模板的核心配置

4.1 规则文件的结构与写法

规则文件是整套配置的心脏。它的基本结构是"匹配条件 + 执行动作"，匹配条件可以是文件类型、路径模式、内容特征，执行动作可以是调用模板、运行脚本、输出提示。写规则的核心原则是条件要窄、动作要单一，一条规则只干一件事，别想着一条规则包打天下。

# rules.yaml 示例结构 rules: - name: "变量声明规范化" match: file_pattern: "**/*.js" content_contains: "var " action: type: "template" template: "var-to-let.tpl" mode: "local" # 关键：local 表示本地执行，不走计费通道

上面这个例子里，mode: local是整个配置的灵魂。没有这个字段，CLI 可能会默认走远端调用，那就白配了。不同版本的字段名可能叫execution_mode或local_only，你按实际文档来，但语义是一样的——明确告诉工具"这条规则在本地跑"。

规则写多了之后，命名规范很重要。我的习惯是"动作 + 对象"的格式，比如"变量声明规范化""注释模板填充""导入语句排序"，一看名字就知道这条规则干什么。别用"规则1""规则2"这种命名，过两周你自己都记不清哪条是哪条。

4.2 模板库的组织与复用

模板库是省积分的另一大利器。很多代码片段其实是高度重复的，比如函数注释模板、接口定义骨架、测试用例结构。把这些预置成模板，CLI 在本地填充变量就能生成，完全不需要模型参与。

模板的组织我按语言和用途两级分类：一级按语言分（js、py、go 等），二级按用途分（注释、骨架、转换）。每个模板文件里用占位符标记可变部分，CLI 执行时替换占位符。

# 注释模板示例 comment-header.tpl /** * ${description} * @param ${paramName} ${paramDesc} * @returns ${returnDesc} */

占位符的命名要语义化，${description}比${a}强一百倍。模板多了之后，语义化命名能让你快速找到该改哪个占位符。

注意：模板不要过度设计。我一开始搞了一套带条件分支的复杂模板系统，结果维护成本比手写还高。后来砍到只保留最常用的十几个模板，反而用得顺手。模板的价值在于高频复用，低频的复杂场景老老实实手写或者交给桌面端。

4.3 触发时机的选择策略

规则配好了，什么时候触发是个关键决策。CLI 支持几种触发时机：手动命令触发、文件保存触发、提交前触发、定时触发。我的经验是按任务的风险等级选时机。

低风险、纯格式类的任务（比如注释模板填充、导入排序）适合文件保存时自动触发，反正改错了也不影响逻辑。中风险的任务（比如变量声明规范化）适合提交前触发，给自己留个检查窗口。高风险的批量操作（比如跨文件重命名）必须手动触发，跑之前先看一眼影响范围。

这个分级不是拍脑袋定的，是被坑出来的。有次我把一个跨文件替换规则设成了保存时自动触发，结果编辑到一半保存了一下，半个项目的变量名被改了，回滚花了不少时间。从那以后，凡是涉及多文件的规则，一律手动触发。

5. 实操全流程：从零配到跑通

5.1 第一步：搭好工作区骨架

先建目录结构，这一步看着简单但不能马虎。我建议按项目隔离，每个项目一套独立配置，别搞全局共享配置。全局配置改一处影响所有项目，出问题时排查范围太大。

mkdir -p ~/workspace/demo-project/.workbuddy/templates mkdir -p ~/workspace/demo-project/.codex cd ~/workspace/demo-project

建好之后，在.workbuddy下放一个空的rules.yaml，先不写内容，等环境验证通过再往里填规则。这个顺序很重要——先确保空配置能跑通，再加规则，出问题时容易定位是环境问题还是规则问题。

5.2 第二步：验证 CLI 本地模式可用

空配置状态下跑一次 CLI，确认它能识别工作区、能读取配置目录、能进入本地模式。这一步的输出信息要仔细看，重点确认两件事：一是它有没有正确找到.workbuddy目录，二是它有没有提示"本地模式已启用"之类的信息。

workbuddy --workspace . --mode local --dry-run

--dry-run是个好习惯，先空跑看流程，不实际执行动作。很多配置错误在 dry-run 阶段就能暴露出来，比实际跑出问题再回滚强得多。

如果这一步报错说找不到配置，检查工作区路径对不对；如果提示模式不支持，检查 CLI 版本是不是太老。这两个是最常见的环境问题。

5.3 第三步：写第一条规则并测试

环境通了之后，写第一条最简单的规则来验证整条链路。我建议从"注释模板填充"开始，因为它的输入输出最直观，错了也容易看出来。

rules: - name: "函数注释填充" match: file_pattern: "**/*.js" content_contains: "function " action: type: "template" template: "comment-header.tpl" mode: "local"

规则写好后，准备一个测试文件，里面放一个没有注释的函数，然后手动触发这条规则，看输出是否符合预期。

// 测试文件 test.js function calculateTotal(items) { return items.reduce((sum, item) => sum + item.price, 0); }

触发后应该生成带占位符替换的注释头。如果生成结果里占位符没被替换，说明模板变量传递有问题；如果压根没触发，说明匹配条件没命中。这两种情况的排查方向完全不同，所以测试用例要设计得能区分开。

5.4 第四步：接入桌面端的工作流

CLI 跑通之后，把它接入桌面端的工作流。桌面端通常支持配置外部命令作为辅助工具，把 CLI 的调用命令配进去，就能在桌面端界面里一键调用本地规则。

配置的关键是命令的拼接方式。桌面端调用外部命令时，一般会把当前文件路径作为参数传进去，CLI 接收这个路径后在自己的规则库里匹配。所以命令模板大概长这样：

workbuddy run --file "${currentFile}" --workspace "${projectRoot}" --mode local

${currentFile}和${projectRoot}是桌面端提供的变量，具体名字看桌面端的文档。配好之后，在桌面端里选中一个文件，点一下辅助按钮，CLI 就在本地跑规则，整个过程不经过计费通道。

提示：第一次接入时，建议在桌面端里用一个无关紧要的测试文件试，别拿正在开发的核心文件试。万一命令拼接有问题，改错了文件很麻烦。

5.5 第五步：批量任务的手动触发配置

批量任务（比如整个目录的命名规范检查）不适合自动触发，配成手动命令更稳妥。CLI 支持指定目录范围执行，配合 dry-run 先看影响范围，确认无误再实际执行。

# 先看影响范围 workbuddy run --dir ./src --rule "命名规范检查" --mode local --dry-run # 确认后实际执行 workbuddy run --dir ./src --rule "命名规范检查" --mode local

这个"先 dry-run 再实跑"的两步法，我强烈建议固化成习惯。批量操作的破坏力跟单文件操作不是一个量级，多花十秒钟看一眼影响范围，能省下几小时的返工。

6. 常见问题与排查实录

6.1 规则不触发的原因排查

规则不触发是最常见的问题，原因通常集中在三处：匹配条件写错、文件路径不在工作区内、规则文件格式有误。排查顺序建议从外到内：先确认文件在不在工作区，再确认规则文件能不能被解析，最后才怀疑匹配条件。

这张表是我实际排查中总结的，按这个顺序走，八成问题能在前三步定位。剩下两成通常是版本差异导致的字段名不匹配，查一下对应版本的文档就能解决。

6.2 本地模式被误判为远端调用的识别方法

这个问题比较隐蔽——配置里明明写了本地模式，但积分还是在掉。识别方法是看 CLI 的执行日志，本地模式会有明确的"local execution"标记，远端调用则会有请求耗时和网络相关的日志。如果日志里出现了网络请求记录，那基本可以确定走了远端。

造成误判的原因通常是规则文件里某条规则的mode字段拼写错误，或者被更高优先级的全局配置覆盖了。排查时把规则文件里的 mode 字段逐个核对，同时检查有没有全局配置文件在暗中生效。

注意：有些工具支持配置文件继承，项目级配置会覆盖全局配置，但字段缺失时会回落到全局值。如果你的项目配置里没写 mode，而全局配置里写的是远端模式，那就会走远端。这种隐式继承最容易坑人，建议项目配置里把关键字段写全，别依赖继承。

6.3 钩子脚本静默失败的定位技巧

钩子脚本失败但不报错，是另一个高频坑。CLI 调用钩子时如果脚本返回非零退出码，有些版本会静默忽略，你以为跑了其实没跑。定位方法是给钩子脚本加日志输出，把每次调用的时间、参数、结果都记到一个日志文件里。

#!/bin/bash # hook.sh echo "$(date) invoked with: $@" >> /tmp/workbuddy-hook.log # 实际逻辑 ... echo "$(date) result: $?" >> /tmp/workbuddy-hook.log

有了这个日志，钩子到底跑没跑、跑了结果如何，一目了然。我现在的习惯是所有钩子脚本第一行就写日志，出问题时直接看日志，比猜快得多。

6.4 版本升级后的配置兼容问题

工具升级后配置失效，这个几乎无法完全避免，但可以把影响降到最低。我的做法是升级前先备份整个.workbuddy目录，升级后先跑 dry-run 验证，确认没问题再删备份。另外，升级日志里如果有"配置格式变更"的说明，一定要仔细看，那通常就是兼容问题的源头。

还有一个经验：大版本升级后，别急着把所有规则一次性迁移，先迁移最常用的两三条，跑几天确认稳定，再逐步迁移剩下的。一次性全迁，出了问题很难定位是哪条规则的问题。

7. 让这套配置长期稳定的几个习惯

配置搭起来只是开始，能不能长期稳定用下去，取决于日常维护习惯。我总结了三条自己一直在用的做法，都是踩坑之后固化下来的。

第一条，规则库定期瘦身。用了一段时间后，规则库里会积累一些再也不用的规则，这些死规则不仅占地方，还可能在匹配时产生意外干扰。我每个月花十分钟过一遍规则库，把一个月没触发过的规则删掉或者归档。规则库保持精简，排查问题时干扰因素就少。

第二条，模板和规则分开版本管理。规则是逻辑，模板是内容，两者的变更频率和影响范围不一样。规则改动影响的是"什么时候执行"，模板改动影响的是"执行出什么结果"。分开管理，回滚时能精准回滚某一类，不会误伤另一类。

第三条，保留一份最小可用配置。我会在另一个目录里维护一份只包含最核心几条规则的配置，当主配置出问题、一时半会儿修不好时，切到最小配置先保证基本工作流不断。这份最小配置也是新机器快速上手的起点，装好环境拷过去就能用。

这套搭配用下来，最大的感受是"分流"这个思路的价值远超具体配置本身。工具会升级、字段会变、版本会迭代，但"把确定性任务交给本地、把理解性任务交给模型"这个原则是稳定的。配置细节可以照着改，原则想清楚了，换个工具组合照样能套用。