企业官网建设流程全解析

把 WorkBuddy 那套“用自然语言封装成可复用技能”的玩法，完整搬进开源世界，是我今年花时间最长的一件事。这个项目我起了个名字，叫 WorkDSH，核心思路就一句话：把 WorkBuddy 最打动人的技能编排、跨会话记忆和规则持续生效机制，用一种更透明、更可审计、更贴近开发者本地习惯的方式重新实现一遍。目前它已经具备日常可用状态，支持主流大模型 API 和本地模型，我也在持续打磨安装体验和安全边界。如果你正在用 Cursor、Cline 或者 Claude Code 这类工具，但对“技能包怎么管理”“指令怎么才能真正记住”“规则怎么跨对话生效”有同样的执念，那这篇东西很适合你——我尽量把设计和踩坑都摊开讲，能抄作业的直接抄。

1. 项目定位与整体思路

1.1 先想清楚：我们到底需要什么

WorkBuddy 这类 AI 编程助手，最接近“生产力”的部分不是基础对话，而是技能。技能本质上就是把一条复杂的、多步骤的指令固化成一份结构化的提示词包，比如“按团队规范写提交信息”“审查这段代码的边界条件”“用指定模板生成接口文档”。没有技能之前，每次都要重新描述一遍上下文；有了技能之后，一句话就能触发整套流程。

但真拿到实际场景里，我发现有几个痛点解决不掉：

• 技能和规则散落在各家产品里，换工具等于清零重来。
• 跨会话记忆通常被实现成“把历史记录一股脑塞进上下文”，浪费 token，还容易跑偏。
• 规则往往只能配置在全局，没有精细到项目级，更做不到“临时交代一件事，之后后续所有任务都生效”。
• 模型被封闭在厂商生态里，想用本地模型或者公司内部网关，要绕很多路。

所以 WorkDSH 的定位不是“再造一个 IDE”，而是一个开源的命令行 AI 工作台。它只做三件事：把技能做成文件体系，把记忆做成结构化存储，把规则做成可叠加的优先级链。模型、执行环境、工具权限都通过配置暴露出来，你完全清楚每一步发生了什么。

1.2 为什么要开源，而不是写个私有脚本

有人会问，这种工具自用就够了，开源图什么。我的理由很朴素：技能这东西，本质上是经验的结晶。一份写得很好的 SKILL.md，背后可能是几十次线上事故总结出来的避坑清单。如果技能不能共享，那每个人都在从头攒经验，太浪费了。

开源还能解决一个信任问题。AI 编程助手动辄要执行 shell 命令、读写文件、操作 git，这种工具如果不透明，你很难知道它到底在干什么。项目开源之后，执行逻辑、权限边界、日志审计全都是可审查的。社区可以帮忙提 issue 和补安全补丁，比自己闷头写稳得多。

开源许可证我也认真想过。WorkDSH 主体代码用 MIT，核心库和 CLI 都放开；技能包目录则采用更宽松的知识共享协议，方便大家自由引用和二次分发。这一块很多项目忽视，我建议所有做开源工具的同行，先想清楚“代码”和“生态内容”是不是应该用两套许可证，否则后期会非常被动。

2. 核心架构设计与技术选型

2.1 技术栈选择背后的权衡

WorkDSH 的主运行时我用的是 Python 3.10+。没有选 Node 或者 Go，主要出于三个考虑：

• 模型接入和 prompt 处理的生态在 Python 里最成熟，像 Pydantic、typing 这些库对结构化输出支持极好。
• 技能包的本质是 Markdown 加少量脚本，Python 做文本解析和规则匹配属于舒适区。
• AI 工具的贡献者很多来自数据科学背景，Python 能降低他们参与插件开发的门槛。

CLI 框架选了 Typer，交互终端用 Rich 渲染。REPL 模式下你会看到分栏输出：左边是工具调用记录，右边是模型思考摘要，底部是命令输入框。这个设计是为了可观测性，每一条指令触发过哪些技能、消耗了多少 token，都看得清清楚楚。

2.2 模型接入层：不做绑架，统一抽象

最关键的架构决策在 provider 层。WorkDSH 定义了一组统一的接口，叫 BaseProvider，不同厂商的模型只需要实现三个方法：complete(messages)、stream(messages)、count_tokens(text)。

class BaseProvider(ABC): @abstractmethod async def complete(self, messages: list[dict]) -> str: ... @abstractmethod async def stream(self, messages: list[dict]) -> AsyncIterator[str]: ... def count_tokens(self, text: str) -> int: return int(len(text) * 1.2)

OpenAI 兼容协议、Anthropic 消息格式、本地 Ollama，全部通过适配器接入。为什么这么设计？因为不同模型的 system prompt 注入方式不一样，工具调用格式也不一样。如果写死在单一 SDK 里，换模型就要改业务代码。统一 provider 的好处是，Skill 引擎和记忆模块完全不关心背后是哪个模型，只要接口不变，切换就是改一行配置文件的事。

2.3 状态与记忆层：让 AI 真正“记住”事情

跨对话记忆是 WorkDSH 和普通脚本最大的区别。我没有用“全文塞上下文”这种简单方案，而是建了三个存储结构：

• conversations/：每次会话的完整消息记录，按时间戳归档。
• memory.json：跨会话的长期 KV 存储，语义键值对。
• vector_store/：基于 embedding 的向量数据库，用来做相关片段检索。

当一个技能声明需要持久记忆时，它会往 memory.json 里写结构化键值，比如 issue_tracker_url、code_review_style。在后续对话开始前，WorkDSH 会先做一轮相关度检索，只把命中的记忆注入上下文，而不是把一整年历史全部塞进去。

向量检索用的是轻量级实现，不依赖重型数据库。文档小的话直接读内存，超过阈值才落盘。这套设计我实测下来，单会话 token 占用能压缩 60% 左右，而且长会话不容易跑题。

2.4 执行沙箱与权限机制

AI 要执行命令，安全就必须前置考虑。WorkDSH 默认的运行模式是受限沙箱：只能读写当前项目目录，只能执行白名单命令。白名单由 profiles/default.yaml 定义，包括 git、ls、cat、node、python 这些日常命令；要执行任意命令，必须显式开启 unsafe_mode。

文件写入也不是无脑放行。WorkDSH 对每个写操作生成 patch 预览，确认后才落盘。落盘前会自动创建备份副本，存放在 .workdsh/backups 目录。这个设计参考了 git 的思路：所有变更可回滚，所有操作可审计。

3. 技能系统与规则引擎的实现细节

3.1 技能包格式：一切皆文件

WorkDSH 的技能不是一个数据库条目，而是一个文件夹。目录结构长这样：

skills/ ├── commit-helper/ │ ├── SKILL.md │ ├── scripts/ │ │ └── fmt_msg.py │ └── assets/ │ └── template.txt

SKILL.md 是核心，采用带 Front-Matter 的 Markdown 格式：

--- name: commit-helper version: 1.2.0 description: 根据 git diff 生成符合团队规范的提交信息 author: wdsh-community license: CC-BY-4.0 memory: - commit_style --- 执行流程： 1. 运行 git diff --stat 获取改动概览 2. 运行 git diff 读取详细内容 3. 根据 memory 中的 commit_style 决定语言和风格 4. 输出三条候选提交信息

Front-Matter 里的 description 字段有个隐藏作用：它会作为工具选择器的一部分注入模型 system prompt。description 写得好不好，直接影响模型能不能在合适的时机调起这个技能。我一般在 description 里写“什么时候用、别什么时候用”，比如“当检测到 .git 目录且用户要求生成提交信息时触发，日常闲聊不触发”。

加载器启动时会扫描技能目录，解析 Front-Matter，生成技能清单。技能之间可以声明依赖关系，A 技能通过 requires 字段指定 B 技能的版本范围，冲突时加载器会拒绝启动并提示，防止两个技能对同一类问题给出互相矛盾的指令。

3.2 规则引擎与优先级链

规则是 WorkDSH 的灵魂。它解决的是“交代一次，之后全自动生效”的需求。规则的来源有四个层级，优先级从高到低：

1. 临时会话指令：在当前对话框里明确说的，比如“这次重构只改接口，不动实现”。
2. 项目级规则：存在项目根的 .workdsh/rules.md。
3. 全局规则：存在 ~/.workdsh/rules.md。
4. 内置安全底限：永远不可覆盖，比如“禁止执行删除根目录的 rm”。

当多个规则冲突时，按这个优先级合并。项目规则比全局规则更具体，所以它能覆盖全局的通用约定。合并之后，系统会生成一份编译后的操作清单，注入到每轮对话的上下文头部。

这就回答了“给 WorkBuddy 定几条规则，后续对所有任务都生效”这个诉求。在 WorkDSH 里，你只要在项目根目录写规则文件，或者直接在对话里说“记住：之后所有提交信息都用英文，动词开头”，它会被结构化存储并绑定到当前项目，之后每一轮自动生效，直到你显式删除。

3.3 技能加载与热更新

开发技能时最烦的就是改一行描述，要重启整个工具。WorkDSH 加了文件监听，技能目录里任何文件变化都会触发重新加载，延迟不超过 300ms。开发体验接近前端热更新。

热更新依赖缓存失效策略。每个技能的内存缓存以文件的 inode、mtime 和 size 三元组做指纹，指纹变了才重新解析。版本号不匹配的依赖也不硬失败，而是降级成警告，把冲突技能整体标记为“不参与本轮工具调用”，避免带病执行。

4. 实操：从零到一部署 WorkDSH

4.1 环境准备与安装

WorkDSH 支持 macOS、主流 Linux 发行版和 Windows 10/11。Windows 用户我建议优先走 Windows Terminal，兼容性最稳。Python 版本必须 3.10 及以上，Node 不是必须，但如果要用到前端脚本技能，建议也装上 18 以上的版本。

安装方式推荐 pipx，隔离依赖不会污染全局环境：

pipx install workdsh

装完后验证版本：

workdsh --version

如果显示 workdsh 0.x 就说明成功了。Linux 用户如果碰到缺少 ncurses 的报错，一般是编译环境不完整，装一下 build-essential 和 libncurses-dev 就能解决。

4.2 首次配置：接入模型

运行初始化命令：

workdsh init

向导会问三个问题：模型 provider、API 地址、模型名称。以 OpenAI 兼容协议为例，配置长这样：

# ~/.workdsh/config.yaml provider: openai_compatible base_url: https://api.example.com/v1 api_key_env: WORKDSH_API_KEY model: gpt-5-mini temperature: 0.2

api_key 不直接写在 yaml 里，而是读取环境变量 WORKDSH_API_KEY。这是安全设计的底线：配置文件可能被提交到 git，密钥绝对不能出现在里面。本地模型用户只需把 base_url 改成 http://127.0.0.1:11434/v1，model 改成本地模型名即可。

配置完跑一条测试命令，确认链路通了：

workdsh run "你好，回复OK即可"

如果回复正常，就可以进入正式操作。

4.3 配置缓存目录和跨平台路径

热搜里看到不少人想把缓存目录迁移走，比如从 C 盘挪到 D 盘。WorkDSH 默认把会话和缓存放在用户目录，但允许环境变量覆盖。Windows 上这么改：

setx WORKDSH_HOME "D:\workdsh_data" setx WORKDSH_CACHE "D:\workdsh_cache"

Unix 系统改 .bashrc 或 .zshrc，追加 export WORKDSH_HOME=/your/path。环境变量生效后再执行 workdsh run，日志里会显式打印当前的 HOME 和 CACHE 路径。这个特性不只是洁癖，有些企业环境用户目录是网络盘，读写性能差，挪到本地盘体感会快很多。

4.4 写一个属于自己的技能：实操全过程

以“自动生成周报”技能为例。先创建目录结构：

workdsh skill new weekly-report

命令会自动生成骨架，然后编辑 SKILL.md：

--- name: weekly-report version: 0.1.0 description: 读取当前 git 仓库近一周的提交记录，生成结构化周报。仅当用户明确要求周报时触发。 --- # 步骤 1. 执行 git log --since="7 days ago" --pretty=format:"%h %s" 2. 按 功能/修复/优化 分类 3. 调用 memory 中的 project_name 作为标题前缀 4. 输出 Markdown 周报

保存后，在 WorkDSH 对话里输入“生成上周的周报”，你就会看到技能被自动激活，工具调用区依次执行 git log 和格式化脚本。生成结果可以直接写入文件：

workdsh run "把周报写到 ./docs/weekly.md"

PowerShell 使用体验基本一致，唯一要注意的是多行字符串用这里文档时别夹带 CRLF，我在 Windows 上踩过坑，格式解析器会把 \r\n 当普通字符，导致 Front-Matter 报错。

5. 常见问题与排查技巧实录

5.1 高频错误速查表

我把这段时间别人踩的和自己踩的坑整理成一张表，按“现象 - 原因 - 解法”呈现。

5.2 跨会话记忆最容易踩的坑

跨会话记忆听起来高级，但踩坑也多。最常见的一个是“记忆污染”：上上个会话留下的临时 key 没清理，导致后续所有任务都被错误的记忆影响。我的建议是每个记忆键值都要附带生命周期字段：

{ "key": "commit_style", "value": "英文，动词开头", "scope": "project:web-app", "created_at": "2025-05-01T10:00:00Z", "expires_at": "2026-05-01T10:00:00Z" }

带 scope 的记忆只对指定项目生效，避免在项目 A 里设定的规则污染项目 B。过期时间防止永久残留。这套设计能解决 80% 的记忆混乱问题，剩下 20% 靠手动管理，WorkDSH 提供 memory list 和 memory delete 命令，随时可以检查已存储的记忆。

5.3 安全审核：开源 AI 工具必须过的一关

既然做开源 AI 工具，安全审核就是必修课。我整理了一个自查清单，每次发版前逐条过：

• 技能包是否包含任何形式的数据外传？检查 scripts 里的网络请求。
• shell 执行是否有超时？所有子进程默认 120 秒超时，防止模型死循环。
• 敏感文件是否可读？默认禁止读取 .env、id_rsa、.ssh 下的文件。
• 日志里是否可能残留密钥？truncate 掉 URL token 参数。
• 依赖版本是否锁定？requirements 用锁文件而非模糊版本。

技能共享还有一个被低估的风险，就是恶意技能包。仿冒知名项目的技能，通过依赖指定路径的脚本，在受害者本地执行任意代码。我的建议是：安装第三方技能前，先人工 review SKILL.md 和 scripts 目录里的所有文件，尤其注意有没有 base64、eval、curl 管道 shell 这类危险模式。WorkDSH 后续会加入技能签名机制，但人工审查在当前仍然是不可替代的环节。

5.4 模型本地化部署的兼容性问题

用本地模型（比如通过 Ollama）时，最容易出问题的不是对话，而是结构化输出和工具调用。本地小模型的 JSON 输出经常不稳定，要么多了一个逗号，要么把 JSON 包在 Markdown 代码块里。WorkDSH 对这类输出做了三层兜底：

• 先尝试标准解析。
• 失败后用正则提取代码块中的 JSON 部分。
• 还不行就把输出返回给模型，告诉它“解析失败，请只输出 JSON”。

实测下来，在 7B 和 13B 参数的模型上，工具调用成功率能从 40% 提升到 85%。本地模型如果还是频繁翻车，终极手段是把关键技能改成纯脚本执行，不让模型生成参数，而是用预设模板走确定性流程。AI 只负责判断该调哪个技能，参数由本地脚本自己拼，可靠度会高得多。

6. 开发心得与后续路线图

6.1 这个项目教会我的几件事

第一件事，提示词工程不等于写 prompt，而是设计上下文结构。WorkDSH 里真正稳定的是编译后的操作清单、技能元数据和记忆摘要，这三样东西在每一轮都会被重新注入，顺序固定。模型看到的不是一坨聊天记录，而是“结构化任务背景 + 当前输入”。这种设计的稳定性远好过自然语言洗脑式重复。

第二件事，技能描述写得再好，也不如“触发条件明确”重要。我给很多技能加了 do_not_trigger 字段，明确列出不该触发的场景。比如周报技能，明确说“日常对话不要触发”。效果立竿见影，误触发率下降非常明显。

第三件事，安全功能必须在第一天就做好，而不是事后补。我已经见过不少项目先把执行能力放出来，翻车之后再打补丁，社区的信任直接被透支。WorkDSH 从一开始就默认拒绝对项目目录外文件的访问，没有把安全做成可选项，而是内置在权限模型里。

6.2 路线图：接下来往哪走

短期计划是做 MCP（Model Context Protocol）接入。MCP 现在已经成为 AI 工具互联的事实标准，让 WorkDSH 的技能可以被其他 MCP 客户端读取，同时也能通过 MCP 调用外部工具服务。这样技能生态就不局限在单一 CLI 里。

中期会把 GUI 提上日程。CLI 适合重度用户，但技能编辑器、记忆管理器这种操作，有图形界面还是轻松很多。界面层会做成独立 Web 服务，通过 localhost 访问，保持核心引擎零前台的设计。

更远一点的规划是多智能体协作。把不同技能分配给多个“虚拟角色”并行处理，比如一个角色做代码审计，一个角色做测试生成，最后汇总结果。这个方向我还在实验阶段，单模型多轮调度的效率问题还没完全解决。

最后说个实际体会：做开源 AI 工具，最怕的不是代码能力不足，而是把“模型对话”当成产品全部。真正有价值的是围绕模型搭出来的那层脚手架——技能怎么组织、记忆怎么管理、权限怎么约束。WorkDSH 目前做到的是一个合格的脚手架，接下来社区愿意共建多少能力，决定它能长多高。如果你也对这个方向感兴趣，欢迎把第一个技能贡献出来，哪怕只是一个 SKILL.md，都是生态向前走的一步。