我大概花了两周时间，做了一个叫“魔力工作台”的开源项目，本质上是想给 workbuddy 这类偏闭源、偏重量的 AI 工作台工具提供一个更轻、更可控、也更符合我自己使用习惯的替代方案。说实话，最初只是自己在用，后来发现身边不少同事也在折腾类似的东西，就顺手把代码整理了一下放了出来。没想到反响比我预期好不少，GitHub 上已经有不少人 star 和提 issue 了。
这个项目不是简单地“仿一个 workbuddy”，而是重新思考了“AI 编程工作台”到底应该长什么样。它不是一个 IDE 插件，也不是一个聊天机器人外壳，而是一个介于 AI Agent、任务编排、知识管理这三者之间的工作台框架。如果你平时用 Cursor、CodeBuddy、WorkBuddy 这类工具，但又觉得它们太重、太黑盒、或者功能绑得太死，那我这篇东西应该能给你一些完全不同的思路。
1. 为什么我不直接用 workbuddy，而要自己造一个轮子
先说说我的真实处境。我之前是 workbuddy 的重度用户，用它的 skill 机制做代码生成、做项目脚手架、甚至做文档管理，刚开始确实觉得挺惊艳，但用着用着就发现几个绕不开的问题。
第一个问题是定制成本太高。workbuddy 的核心逻辑是跑在它自己的运行时里，你想改一个底层行为，往往只能通过写 skill 去“绕”，一旦 skill 写得多了，整个系统就像在沙子上盖房子，牵一发而动全身。我有一段时间光维护自己的 skill 集合就花了很多精力，这完全偏离了“用工具省时间”的初衷。
第二个问题是数据不透明。我的对话历史、上下文、甚至代码片段都存储在它的私有格式里，想要导出到别的地方，或者自己做个数据分析，几乎不可能。作为一个习惯 everything as text 的人，这种封闭性是很难接受的。
第三个问题，也是最直接的导火索，是它越来越重。装一个工作台，动辄几百 MB，启动还慢，而且很多功能我根本用不到。我需要的其实是一个足够轻的骨架，然后我把自己的工具链、模型接口、知识库都挂进去，就像搭积木一样，而不是别人把积木拼好了再让我用锤子砸开重拼。
所以“魔力工作台”最初的定位就一句话：一个以本地优先、文本优先、可自由替换各组件、能跑通 AI 编程全流程的最小化工作台骨架。
这个定位决定了后续所有的技术选型和架构设计。后面我会逐个拆。
2. 整体架构和设计思路——它是怎么做到“轻”的
2.1 核心设计原则：一切皆文件
这是我整个项目最核心的一条原则。魔力工作台不搞私有格式，不搞数据库存储，所有的配置、上下文、技能、任务状态，全部是纯文本文件，用 Markdown、JSON、YAML 来承载。
这样做带来的直接好处是：你可以用 grep 搜配置，用 git 管历史，用任何编辑器改内容，甚至写一段 Python 脚本就能批量处理自己的任务记录。这套思路和 Emacs 的 org-mode 理念类似，但实现起来更轻。
举个例子，一个 skill（也就是工作台里的一个技能）在 workbuddy 里可能是一个需要安装的插件包，但在我这里就是一个目录：
skills/ ├── code-review/ │ ├── SKILL.md # 技能说明，包含触发条件和执行逻辑 │ ├── templates/ │ │ └── review.md # 输出模板 │ └── hooks/ │ └── post-run.sh # 执行完可以跑的辅助脚本这意味着什么？意味着你分享一个技能，只需要发一个目录；你备份整个工作台，只需要git push。对于一个开发者工具来说，这种透明感能带来极大的安全感和可控性。
2.2 插拔式运行时：模型和后端可以随便换
现在的 AI 工具基本都绑定了自己的模型通道，但我的想法是，模型本身不应该和工作台强耦合。魔力工作台的运行时层做了一个抽象，所有模型的调用都走同一个接口，不管你是用 OpenAI 兼容接口、本地跑 Ollama、还是接公司内部的模型网关，都只需要改一个配置文件。
# config/llm.yaml provider: openai_compatible base_url: http://localhost:11434/v1 model: qwen2.5-coder:14b temperature: 0.3 max_tokens: 8192这个配置的意义在于，你可以为不同任务配置不同的模型。写代码用代码模型，做总结用通用模型，做 OCR 用多模态模型，它们之间通过工作台的任务路由自动分发。这比在一个模型里反复切换要高效得多。
有人可能说，这不就是搞了个模型聚合网关吗？对，本质上就是这个思路，但区别在于我把它做成了工作台的内置能力，而不是一个独立服务，所以部署成本几乎为零。
2.3 Agent 编排：从“聊天”升级为“流水线”
用过 workbuddy 的应该知道，它的 agent 能力更像是一个“加强版聊天框”，你给它一个任务，它自己决定怎么拆解步骤并执行。但问题在于，它不擅长多任务并行和状态维护。
魔力工作台引入了一个“任务流水线”的概念。每个任务可以拆成多个步骤，步骤之间支持串行、并行、条件分支三种结构。步骤的输出会缓存成中间文件，后续步骤可以直接引用，而不需要整个任务重新跑。
下面这个例子是一条完整的“从需求到代码到测试”的流水线定义：
# workflows/feature.yml name: feature-dev steps: - id: parse-req type: llm prompt_file: prompts/parse-req.md output: output/req.md - id: gen-code type: llm prompt_file: prompts/gen-code.md input: output/req.md output: output/code.diff - id: run-tests type: shell command: pytest tests/ -q depends_on: gen-code这样做的好处是，每一步都可见、可重跑、可单独调试，而不是靠模型自己“随缘”执行。对于生产环境的使用，这种确定性非常重要。
3. 核心功能拆解——每个模块解决什么实际问题
3.1 Skill 系统：技能不是插件，是“方法论封装”
Skill 这个词被 workbuddy 带火了，但很多人的理解还停留在“一个 prompt 模板”。我觉得 skill 应该解决的是一个问题：如何把一个人的生产流程变成另一个人可以直接调用的工具。
在魔力工作台里，一个 skill 由三部分组成：
第一部分是说明文件 SKILL.md，描述这个技能解决什么问题、触发条件是什么、需要什么输入。这个说明文件同时也是模型理解技能的入口，相当于一个 function calling 的说明书。
第二部分是模板和对齐说明，决定了输出的格式。比如代码审查技能，我内置了“问题严重程度 → 对应行号 → 修改建议 → 代码示例”的输出模板，这样模型每次输出都是结构化的结果，直接可以接后续自动化流程。
第三部分是辅助脚本 hook。比如代码生成技能跑完之后，自动触发一个 git diff 统计脚本，告诉你这次生成改了多少行、新增了什么。这个脚本是用户自己写的，自由度极高。
我在项目里提供了几个开箱即用的 skill 作为示例，包括代码审查、技术方案生成、README 生成、SQL 优化建议、API 文档抽取。它们的设计目标都是“短小精悍”，让用户可以很快读懂然后改造成自己的东西。
3.2 上下文管理：让 AI 记住该记住的，忘掉该忘掉的
这是很多 AI 工具做得很烂的地方。上下文窗口越来越大没错，但不代表你应该什么都往里面塞。魔力工作台做了一个“上下文分层”的机制。
第一层是项目级上下文，存在项目根目录的.magic/context.yml里，包括项目结构说明、技术栈、编码规范等。这一层相对静态，每次会话加载一次。
第二层是会话级上下文，存在于当前对话的 session 文件中，记录的是本次任务中产生的关键决策和中间结果。会话结束时可以选择是否写回项目级上下文。
第三层是“临时记忆”，只存在于单个步骤中，步骤结束后就清空，避免无用的信息污染后续流程。
这样做的一个直接效果是，模型的 token 利用率大幅提升。我做过一个简单实验，同样一个代码生成任务，裸写 prompt 一次要消耗大约 12k token，用上下文分层之后只要 6k，而且输出准确率明显更高。
3.3 缓存与增量：省钱的核心武器
如果你是重度 API 用户，一定会懂 chat 类工具的 token 消耗有多快。魔力工作台做了两层缓存来缓解这个问题。
第一层是请求级缓存：相同的 prompt、相同的模型参数，在有效期内直接命中缓存，不再发起网络请求。这个对于“调整业务代码但 prompt 模板没变”的场景尤其管用。
第二层是步骤级缓存：流水线里某个步骤的输入没有变化时，直接复用上一次的输出，不重新执行模型调用。现在项目里跑一次完整的需求开发流水线，大约 40% 的 token 消耗能被缓存抵消。
我知道很多服务端框架都有这个机制，但在本地 AI 工作台里做这么细的缓存，目前确实还比较少见。
4. 从零开始搭建：20 分钟跑起来的完整流程
4.1 环境准备与安装
项目目前支持 macOS 和 Linux，Windows 可以通过 WSL 的方式跑。依赖也很简单，只需要 Python 3.10+ 和 Node.js 18+（后面有些工具链需要）。安装方式我做了尽量简化：
git clone https://github.com/yourname/magic-workbench.git cd magic-workbench pip install -r requirements.txt cp config/llm.yaml.example config/llm.yaml然后编辑config/llm.yaml，填上你的模型接口地址和密钥。如果你有本地跑 Ollama，直接填http://localhost:11434/v1就能通。
这是我认为这个项目体验比较好的地方：不需要安装庞大的桌面应用，不需要注册账号，不需要复杂的初始化引导，一个终端 + 一个编辑器就能干活。
4.2 初始化一个项目工作台
魔力工作台是面向“项目”维度的。进入任何一个项目目录后，执行：
magic init它会在当前目录生成.magic文件夹，里面包含默认的配置文件、技能目录、工作流目录。然后执行：
magic scan它会扫描你的代码仓库结构，自动生成一个project_context.md，这个文件就是前面提到的项目级上下文的底稿。你还可以手动补充编码规范、模块说明进去，这些信息会拼进每次 prompt 的 system message 开头。
实际用下来的感觉是，这个scan环节特别值得花点心思做完整。项目上下文写得越清晰，模型生成代码和回答问题的准确率提升得越明显。我甚至见过有人把整个架构文档都精简后塞进去，效果确实不一样。
4.3 跑通第一个任务
安装配置完成后，官方仓库里自带了一个示例技能叫doc-generator，作用是自动给代码文件生成文档。用法很简单：
magic run doc-generator --input src/main.py内部执行流程是这样的：读取文件内容 → 读取项目上下文 → 拼 prompt → 调用配置好的模型 → 按模板输出文档 → 自动写入同目录下的main.py.md。
这一步跑通了，说明整个链路没问题。从此你就有了一个完全属于自己掌控的 AI 工作台。
5. 实际使用场景和效果——它到底解决了什么具体问题
5.1 场景一：日常代码开发
我现在的主力开发模式已经完全切换到魔力工作台上了。比如接到一个需求“给订单模块增加导出 Excel 的功能”，我的做法是：
先在项目根目录写一个简单的需求描述文件req.md，然后用magic plan命令让它生成一份技术方案。方案生成后我会自己过一遍，把不合理的部分改掉，再让它根据方案生成代码 diff，最后手动 review 一遍合入。
这套流程下来，大概比之前直接打开 AI 聊天工具来回粘贴要高效 30% 以上。因为每一步的上下文都是自动从仓库里读的，不需要我手动把整个文件内容贴进去。
5.2 场景二：代码审查
团队里现在用我做的code-reviewskill 来做 MR 前的自检。它能识别出的问题包括但不限于：逻辑分支覆盖不全、异常处理缺失、SQL 注入风险、重复代码、资源未释放等。
我自己实测的准确率大约在八成左右，关键是它能保持稳定的输出格式，直接接到后续的标签系统里。这个技能也成了仓库里被 fork 最多的一份代码。
5.3 场景三：旧项目接手维护
接手一个没文档的老项目，是最痛苦的。魔力工作台在这里最大的价值是能自动生成“项目地图”。它会遍历代码目录，理解模块之间的依赖关系，生成一份结构化的说明文件。
以前要花两三天捋清的东西，现在大概一上午就能出个七八成。剩下的细节再靠 human in the loop 去验证和补充。这不是什么魔术，本质上就是把“读代码”这个体力活外包给了模型，但效果确实惊人地好。
6. 踩坑记录和避坑指南——希望你别重走我的弯路
6.1 不要把所有东西都交给模型决策
我早期版本的流水线是“全自动”的：模型自己决定要改哪些文件、怎么改、要不要跑测试。后来发现，这种模式在简单项目上表现得很好，但到了复杂项目上就开始失控，会出现“看起来很合理但实际上完全错误”的操作。
现在的设计改成了“半步自动”：模型生成建议，人工确认后执行。这可能不够“AI 原生”，但更可靠。真实工程不是 demo，稳定大于炫技。
6.2 技能数量不是越多越好
我一度在仓库里塞了几十个 skill，结果维护成本巨大，而且模型在面对一大堆技能时，选择困难症会被放大，经常选错技能。
现在的做法是，保持默认只有六七个核心技能，其余的都放到skills/contrib/目录，按需手动添加。这也是一个很实用的工程化思路：降低默认复杂度，保持扩展性。
6.3 缓存失效是一个容易忽略的坑
前面我说缓存能省钱，但缓存设计不好也会坑人。典型的问题是：代码文件变了，但 prompt 里没有体现这个变化，导致缓存命中后输出的内容是过时的。
解法是构建输入指纹。魔力工作台对每个步骤的所有输入文件做一个哈希，任何一个文件内容变了，缓存自动失效。这个机制已经内置，但如果你自己写扩展模块时偷懒没有接入指纹系统，就会踩坑。
6.4 模型选择的建议
如果你只是玩一玩，本地用 Ollama 跑一个 7B~14B 的代码模型就够了。但如果要正经做生产环境的代码生成，还是建议用商用 API 的大参数模型，尤其是在复杂逻辑和长上下文的场景，两者的差距非常明显。
我的个人配置是：代码生成主用更大的模型，文本总结和辅助分析走本地小模型，两者搭配覆盖率最合适。
7. 路线图和我接下来的计划
这个项目我打算长期维护下去。目前已经在做的方向有几个：一个是把前端交互做成 Web 界面，让不习惯命令行的人也能用；一个是更好的多项目支持，正在做项目之间技能和上下文的共享机制；还有一个是想接更多类型的执行后端，比如本地 Docker 沙箱，让模型生成的代码可以在隔离环境里自动跑测试。
说实话，这个项目能引来多少关注我没有特别在意，我更开心的是看到有一些人把它用在了自己的实际工作流里，还在 issue 区分享了他们写的技能。开源项目最有意思的地方就在这里，你搭一个脚手架，然后别人在上面盖出你完全没想到的房子。
如果你也想折腾一个自己的 AI 工作台，或者只是想找一份足够清爽的工作台骨架，不妨去仓库里瞄一眼，用不用再说，参考一下思路也是好的。
