先交代一下背景。我过去大半年几乎天天泡在 WorkBuddy 这类 AI 智能体工作台里写自定义指令、调 skill、把一堆重复性任务丢给它处理。工具本身很顺手但用得越深心里那个疙瘩越大——很多内部机制是闭源的数据流经别人的服务想改个行为逻辑还要看厂商排期。于是就有了 WorkDSH一个开源版 WorkBuddy 替代方案主打本地优先、可扩展、完全可控。这篇文章我想把整个项目的由来、设计思路、核心功能、安装过程和我踩过的坑一次性讲清楚给正在选型或也想自建 AI 工作台的人一个真实参考。1. 为什么要做 WorkDSH开源版 WorkBuddy 的由来与设计思路1.1 WorkBuddy 好用但为什么我还是决定自建WorkBuddy 本质上是一个带 skill 机制的 AI Agent 工作台你给它配好模型、写好规则它就能帮你处理代码审查、文档生成、数据整理这类偏重流程化的任务。同类产品里还有 CodeBuddy两者定位接近但侧重点略有不同CodeBuddy 更聚焦编码场景WorkBuddy 则把范围放宽到日常工作流。对我这种既写代码又要管项目文档的人来说WorkBuddy 的工作台模式确实比单纯在终端里敲对话要高效。但重度用了一段时间后痛点也变得很实际。第一是定制受限我想在会话里加一个内部项目的专用命令闭源工具做不到第二是数据归属感所有会话记录都放在厂商的服务体系里本地只留缓存哪天想导出做分析很麻烦第三是生态绑定skill 的加载方式、规则解析的优先级、上下文处理的细节全部由上游决定我看不到也无法修改。作为一个长期使用者这种黑盒感会一点点积累成不安全感。所以 WorkDSH 不是头脑一热的重写而是被这几个现实问题推着走的结果。我想要的工具很简单数据留在本地、规则我能改、skill 我来定、模型想换就换。开源是这一切的前提。1.2 WorkDSH 的定位本地优先、可插拔、不绑架用户WorkDSH 这个名字里的 DSH我取的是 Deep Self-Hosting 的含义也是 Do Something Here 的意思一个强调自主、一个强调动手。它不是一个 WorkBuddy 的像素级模仿而是把 WorkBuddy 里那些让我觉得好用的交互模式提炼出来用一套更透明的机制重新实现。定位上有几条硬性原则。第一本地优先。所有会话、配置、skill 数据默认存在用户自己的目录里不上传任何东西到云端。第二可插拔。模型层、技能层、规则层都是独立模块用户随时可以替换。第三轻量。整个项目不引入重型中间件跑起来只需要一个 Python 环境和可选的本地模型服务普通笔记本就能带得动。这套设计解决的核心问题是“工具属于谁”。商用 AI 工作台本质上属于厂商用户只是租客WorkDSH 则反过来代码属于社区数据属于用户能力边界由使用者自己划定。对于那些想深入研究 Agent 工作台实现原理的开发者、需要把 AI 工作流嵌入公司内部 SOP 的团队、或者单纯不想被闭源生态绑定的个人用户这个项目提供了一个可以随时拆开看、改、扩展的底子。1.3 技术栈选择我为什么用 Python 而不是 Rust 重写技术选型是整个项目里第一个需要认真决策的点。一开始我确实考虑过用 Rust 重写核心性能更好、分发也方便但评估下来还是选了 Python 3.10 作为主语言。最直接的原因是 AI 生态无论是连接 Ollama 本地推理、对接 OpenAI 兼容接口还是后续接各种 Agent 框架Python 的库和社区支持都是最成熟的用 Rust 重写意味着所有协议层、模型传输层都要自己造轮子开发周期会拉长数倍。具体到组件CLI 层用 Typer它基于类型注解自动生成命令行参数比 Click 写起来更简洁API 层用 FastAPI 加 Uvicorn方便后面做 Web 控制面板数据层直接用 SQLite零配置、单文件、足够支撑本地单人使用场景配合 WAL 模式还能解决并发读写的问题。模型接入方面我实现了 OpenAI 兼容接口客户端这样既能连远程服务也能直接指向 Ollama 的本地端点切换模型时只需要改配置不用重启服务。这个组合的核心逻辑是“够用就好”。单机场景下SQLite 的并发能力远大于实际需要Typed 的 CLI 对维护者友好FastAPI 的 OpenAPI 文档让我调试 API 时省了很多力气。性能上 Python 确实不如编译型语言但工作台类工具的瓶颈从来不在解析速度而在模型推理的耗时。所以这个取舍我认为是合理的。2. 核心功能拆解WorkDSH 最值得看的四个模块2.1 会话管理多任务并行与上下文隔离会话是 WorkDSH 里最基础的单位。每个会话有独立 ID、独立的历史记录和独立的上下文窗口互不干扰。这个看起来简单的设计实际做起来容易出错的地方在数据写入。我一开始用简单的 JSON 文件存储会话记录多个会话并行写入时偶尔会出现文件覆盖后来统一迁到 SQLite 才彻底解决。数据模型上我建了三张核心表会话表存会话元数据、消息表存每轮问答内容、技能表存已加载的 skill 信息。会话和消息是一对多关系查询时按会话 ID 过滤再按时间戳排序。这样即使开几十个会话并行跑每条消息的归属都不会乱。上下文管理则用了滑动窗口加摘要策略。长对话时窗口只保留最近的 N 轮完整消息更早的内容在超过阈值后自动交给模型做一次摘要再把摘要塞回系统提示里。这个策略的好处是防止上下文无限膨胀导致 token 超限坏处是摘要过程会多一次模型调用。我在配置里开放了max_context_rounds参数用户可以根据自己模型的上下文长度调整默认值是 20 轮。并行能力走的是 asyncio 协程。每个会话的请求被拆成独立任务丢进事件循环里跑再通过信号量控制最大并发数默认 4 个。这样既不会把本地资源打满也不会因为某个会话阻塞拖累其他任务。2.2 Skill 机制像装插件一样扩展能力Skill 是 WorkDSH 最核心的扩展机制设计目标和 WorkBuddy 的 skill 类似但加载方式完全透明。每个 skill 是一个目录里面必须包含一个manifest.yaml描述文件和若干实现文件描述文件声明了技能的名称、版本、入口函数和依赖说明。name: code-review description: 对指定目录或文件做一轮代码走查 version: 0.1.0 entry: main.py dependencies: - requests加载流程是启动时扫描技能目录校验 manifest 的字段完整性再动态导入入口模块。入口模块需要暴露一个统一签名的run函数参数是上下文对象和任务参数返回值会作为结果回填到对话里。# main.py def run(context, params): target params.get(path) if not target: return 缺少 path 参数 report review_code(target, context.model) return report新增 skill 不需要改核心代码把目录放进skills/路径执行workdsh skill add注册即可。这个设计让 WorkDSH 可以变成一个社区共享技能的载体别人写好的 review 工具、文档生成器、数据分析脚本克隆下来就能用不需要理解项目内部实现。2.3 规则系统自定义指令的优先级设计用过 WorkBuddy 的人都会对自定义指令有印象你可以在配置里写“所有回复用中文”“代码示例必须可运行”之类的全局规则。WorkDSH 把规则系统做了三层拆分全局规则、目录规则和会话规则。全局规则放在rules/global.yaml作用于所有会话目录规则放在项目目录下命名.workdsh/rules.yaml作用于该目录下的任务会话规则则通过对话内指令动态添加。优先级是会话规则最高目录规则次之全局规则兜底。这样设计的场景是公司级规范写在全局项目级约定写进目录临时调整只在会话里生效。规则的书写格式我选了 YAML 加自由文本的组合。每个规则项有pattern和instruction两个字段pattern 描述适用场景instruction 是具体指示。系统在每次请求前会把当前作用域内的规则按优先级拼接进系统提示。这块有一个容易忽略的点规则文本不能太长否则会挤占上下文空间。我在文档里建议全局规则不超过 10 条单条不超过 50 字。2.4 任务编排从单轮到流水线单次对话解决一个问题这是第一层能力把多个问题串成自动化流程这是 WorkDSH 想提供的第二层能力。任务编排模块引入了队列和依赖图的概念用户可以定义多个 task每个 task 指定模型、技能和参数task 之间通过depends_on声明依赖关系系统按照拓扑顺序执行。执行引擎就是消费队列的一组 worker。每条任务跑完后输出会写入自己的会话上下文后续任务可以直接引用前序任务的输出作为输入。这解决了实际工作里最常见的场景比如“先拉取代码变更 → 再生成变更说明 → 最后按模板输出周报”三步可以一键串联。Web 控制面板里实时展示每个任务的状态还在排队、正在执行、已完成、失败失败的任务会给出对应的错误信息。最初做这版编排时我在异常处理上吃过亏单个任务失败时整个流水线会卡住。后来加了两条规则失败任务默认跳过后续依赖它的任务但允许通过continue_on_error: true强制继续。现在跑批处理任务时稳当多了。3. 安装部署与实操指南从零跑起 WorkDSH3.1 环境准备Python 版本与虚拟环境WorkDSH 要求的运行环境非常简单Python 3.10 以上版本即可。我建议用虚拟环境安装避免污染系统级的 Python。在 Linux 或 macOS 上命令是三板斧python3 -m venv .venv source .venv/bin/activate pip install workdshWindows 上有两种方式原生命令行和 WSL。如果你主要想连本地模型做日常使用原生 PowerShell 环境没问题Python 安装时记得勾选 Add to PATH如果你后面要跑一些依赖 Linux 工具的脚本建议直接上 WSL2省掉很多路径和权限的麻烦。依赖安装完成后执行workdsh --version能看到版本号就说明环境没问题。如果是在公司内网环境pip install可能走不了默认源可以用国内镜像源加速命令里加一个-i参数指向镜像地址就好。3.2 配置文件逐项解读WorkDSH 初始化后会在~/.workdsh/下生成config.yaml这是整个工具的配置中枢。我第一次打开这个文件时也被字段数量吓了一跳但实际需要改的就那么几个。model: provider: ollama base_url: http://127.0.0.1:11434/v1 name: qwen2.5-coder:14b api_key: empty cache_dir: ~/.workdsh/cache session_dir: ~/.workdsh/sessions log_level: info max_context_rounds: 20 max_concurrent: 4 rules: - pattern: default instruction: 所有回复使用中文model段配模型接入信息provider支持ollama、openai或任意兼容 OpenAI 协议的服务base_url指向端点name是模型名。api_key本地模型填empty就行远程服务填对应密钥。值得注意的是环境变量优先级高于配置文件跑定时任务时可以通过WORKDSH_MODEL_NAME这类变量临时更换模型。cache_dir和session_dir控制数据和缓存的存放位置默认都在用户目录下。Windows 用户如果想把缓存挪到 D 盘直接改这两个路径再重启服务即可不需要担心权限问题。max_concurrent是并发上限如果你的模型 API 有限流可以把它调低到 2 甚至 1。3.3 五分钟跑通初始化、配模型、开启第一个会话快速跑通整个流程其实只需要四步。第一步执行workdsh init生成默认配置和目录结构。第二步如果使用本地模型预先用 Ollama 把模型拉下来我用的是qwen2.5-coder:14b这个尺寸代码理解能力足够笔记本内存 16GB 能跑。ollama pull qwen2.5-coder:14b workdsh init workdsh config --set model.providerollama workdsh config --set model.base_urlhttp://127.0.0.1:11434/v1 workdsh run --session demo第三步用workdsh config --set命令把模型配置项改好这样避免手动编辑 YAML 时出错。第四步执行workdsh run --session demo进入交互式会话直接在终端里输入问题看到模型返回内容就算跑通了。第一次使用时建议开一个简单任务试试水比如让它写一个 Python 脚本读取 CSV 文件并输出统计信息。跑通后可以慢慢尝试加载 skill、配置规则、接入 Web 面板整个学习曲线不算陡峭。3.4 常用命令速查表这里整理一份高频命令速查表方便日常使用。命令设计上保持了workdsh 子命令 动作的格式记忆成本不高。命令作用示例workdsh init初始化配置目录workdsh initworkdsh run进入交互式会话workdsh run --session demoworkdsh skill list查看已安装技能workdsh skill listworkdsh skill add安装技能workdsh skill add ./skills/code-reviewworkdsh task add添加后台任务workdsh task add 总结今天的变更workdsh task status查看任务状态workdsh task statusworkdsh config --get读取配置项workdsh config --get model.nameworkdsh config --set修改配置项workdsh config --set max_concurrent2workdsh web启动 Web 控制面板workdsh web --port 8080有两点使用心得想分享一是task add支持直接传原始任务描述系统会自动解析生成结构化任务比手动填参数快很多二是config --set支持点号访问嵌套字段改配置省心了不少不用打开文件找层级。3.5 给想二次开发的人如何新增一个 Skill如果你用过 WorkBuddy 的 skill会发现它的生态虽好但自己写一个可发布的 skill 需要过一遍对方平台的审核流程。WorkDSH 把这个门槛降到了本地过程只有三步。第一步创建技能目录。目录名建议用中划线连接的小写字母例如my-skill。第二步编写manifest.yaml和入口文件。manifest 里最关键的是entry字段它指向实现文件入口函数固定为run。# my_skill/main.py def run(context, params): keyword params.get(keyword, ) if not keyword: return keyword 参数必填 return f已收到搜索关键词{keyword}第三步注册技能。执行workdsh skill add ./my-skill看到Skill my-skill registered就表示安装成功接着就可以在会话里通过my-skill keyword测试的语法调用它。开发技能时有个坑需要提醒入口函数的params只能接收字符串类型的键值对如果要在技能内部传递复杂结构建议用 JSON 字符串传入再解析。这个设计一开始是为了简化参数解析但用久了发现产品化需求反而更常出现下一版会考虑加上类型声明支持。4. 常见问题与避坑实录排查思路和我的踩坑总结4.1 高频问题排查表把社区反馈里出现频率最高的问题整理成了一张表。这些问题不只在 WorkDSH 里有用同类 AI 工作台时大概率也会遇到。问题典型现象排查方向模型连接超时对话迟迟无响应确认 Ollama 是否启动检查 base_url 是否可达查看日志上下文被截断长对话丢失早期内容调大max_context_rounds检查是否触发了摘要逻辑中文路径报错Windows 下加载配置失败确认路径用 UTF-8 编码改用Path对象处理路径并发写入冲突多会话同时保存时崩溃开启 SQLite WAL 模式调低max_concurrent技能未生效调用时不返回结果检查 manifest 字段是否完整确认依赖已安装任务卡在排队流水线一直不执行检查是否有失败任务阻塞确认依赖关系无环排查这些问题的第一原则是看日志。WorkDSH 默认把日志写到~/.workdsh/logs/用workdsh config --set log_leveldebug切换到调试模式后能看到详细的请求链路。多数问题在 debug 日志里都能直接定位到原因不用瞎猜。4.2 性能优化上下文裁剪与并发控制本地跑 AI 工作台资源瓶颈一般有三个上下文长度、并发请求数、模型推理速度。上下文长度可以通过控制滑动窗口参数来优化max_context_rounds设置得越小单次请求消耗的 token 越少响应越快但可参考的历史信息也会变少。建议代码相关任务设 15 轮左右文档类任务设 25 轮左右。并发控制上max_concurrent不是越高越好。我曾为了跑批量任务把它调到 8结果 Ollama 在 CPU 推理模式下直接把内存吃满系统开始卡顿。后来改成 4并把批量任务错峰提交每个任务间隔几秒整体效率反而更高。如果你的模型跑在 GPU 上可以尝试调到 6 试试。模型推理速度方面本地模型优先用量化版本比如qwen2.5-coder:14b-q4_K_M比原版少占近一半内存效果差距可接受。如果你同时开了 Web 面板建议把面板日志轮转周期缩短避免日志文件无限膨胀把磁盘占满。4.3 我踩过的几个坑从路径编码到并发写入这里分享几个我在开发过程中真实踩过的坑每一个都花了不少时间才定位到根因。第一个坑是 Windows 下中文路径的编码问题。最初配置文件里的缓存路径写的是字符串在 Windows 上如果用户名是中文路径拼接会出现乱码。后来把所有路径都改成pathlib.Path对象并显式声明 UTF-8 编码读取配置文件问题才彻底解决。如果你在 Windows 上遇到“找不到配置”这类诡异问题十有八九是编码引发的。第二个坑是 SQLite 并发写入时的锁冲突。多会话并行时消息写入频繁偶尔会遇到database is locked的报错。解决办法是打开 WAL 模式并设置合理的 busy timeout。这个改动只有三行代码但效果立竿见影之后再没出现过锁冲突。第三个坑是 Python 版本兼容性。Typer 的某些新语法需要 Python 3.10 以上版本早期 README 里只写了 3.8导致好几个用户装了跑不起来。后来我在项目里加了一个启动时的版本检查版本不足直接给出明确提示。开源项目面向的用户环境千差万别这种防御性检查不能省。最后一个坑是关于任务依赖的死环检测。任务编排里的依赖关系如果配置不当会形成环最开始没有任何保护程序直接卡死。加一个基于 DFS 的环检测后初始化阶段就能报错拦截。如果你也做类似的编排系统这个检测一定要放在最早执行的位置。做完 WorkDSH 这几个月我最大的体会是工具的价值不在于功能堆得多全而在于它允许你在不合意的地方亲手修改。WorkBuddy 帮我验证了这个方向的确有需求WorkDSH 则让需求变成了一份可以自由编辑的代码。如果你也在用类似的工作台并且偶尔觉得哪里不对劲不妨试试自己动手改一版。最后再分享一个小技巧开发技能时先在本地用一个最简单的模型跑通逻辑再换到更大的模型调效果能省下不少排队等待的时间。