企业官网建设流程全解析

1. 项目缘起与核心定位

1.1 从一个真实痛点说起

我在日常工作中大量使用 Claude Code 处理代码审查、文档生成和自动化脚本编写。用得越深，越发现一个问题：每次开启新会话，都要重新交代一遍项目背景、代码规范、常用命令和输出格式。比如我负责的一个后端服务项目，每次都要告诉它“用 FastAPI 风格写接口”“日志用 structlog”“测试用 pytest + factory_boy”，重复到让人抓狂。

knowledge-work-plugins这个项目，本质上就是为解决这类重复劳动而生的。它是一套面向 Claude Code 和 Claude Cowork 的插件集合，把知识工作者日常高频使用的技能、命令和工作流封装成可复用、可分发、可组合的模块。你可以把它理解成给 Claude Code 装上一套“职业技能包”——装上之后，它就知道在特定场景下该用什么工具、按什么流程、输出什么格式。

这个项目适合三类人：一是每天用 Claude Code 写代码、写文档、做分析的深度用户；二是想把团队内部最佳实践固化下来、让 AI 助手“入职即上手”的技术负责人；三是对 Claude Code 插件机制好奇、想自己写插件但不知道从哪下手的开发者。不管你是哪一类，理解这个项目的设计思路和实操方法，都能让你的 AI 协作效率上一个台阶。

1.2 为什么是“插件”而不是“提示词”

很多人第一反应是：我写个 system prompt 不就行了？为什么要搞插件这么重？

我一开始也这么想，直到我维护了十几个项目的提示词模板之后才发现问题。提示词是“散装”的，每个项目一份，改了一处忘了另一处；提示词是“静态”的，没法根据当前打开的文件类型动态切换行为；提示词是“不可组合”的，想把“代码审查”和“安全扫描”两个能力合在一起用，只能复制粘贴拼起来。

插件的核心价值在于三点。第一是封装性：一个插件把相关的 slash commands、技能定义、配置文件和辅助脚本打包在一起，安装即用，卸载即走，不会污染全局环境。第二是可组合性：你可以同时装“代码审查插件”和“文档生成插件”，在同一个会话里按需调用，互不干扰。第三是可分发性：团队里一个人写好插件，其他人通过一个命令就能装上，保证所有人用的都是同一套规范。

提示：如果你目前只是偶尔用 Claude Code 问几个问题，确实没必要上插件。但当你发现自己反复输入类似的指令超过三次，就该考虑把它封装成插件了。

1.3 项目整体架构一览

knowledge-work-plugins的目录结构遵循 Claude Code 插件规范，核心由以下几部分组成：

• .claude-plugin/目录：存放插件元信息，其中plugin.json是入口文件，声明插件名称、版本、作者和包含的组件。
• commands/目录：存放 slash command 定义文件，每个.md文件对应一个可通过/调用的命令。
• skills/目录：存放技能定义，描述 Claude 在特定场景下应具备的能力和知识。
• agents/目录：存放子代理配置，用于把复杂任务拆解给专门的代理处理。
• hooks/目录：存放钩子脚本，在特定事件（如文件保存、会话开始）触发时执行。
• README.md和文档：说明安装方法、使用示例和贡献指南。

这种结构的好处是职责清晰。你想加一个新命令，就在commands/下新建一个文件；想调整某个技能的行为，就改skills/下对应的定义。不需要动核心逻辑，降低了维护成本。

2. 核心机制深度拆解

2.1 Slash Commands 的工作原理

Slash commands 是用户与插件交互最直接的入口。当你在 Claude Code 会话中输入/时，它会扫描已安装插件中commands/目录下的所有.md文件，把文件名作为命令名，把文件内容作为命令的提示词模板。

一个典型的命令文件长这样：

--- description: 对当前选中的代码进行安全审查 allowed-tools: Read, Grep, Bash --- 请对以下代码进行安全审查，重点关注： 1. 输入验证是否充分 2. 是否存在注入风险 3. 敏感信息是否硬编码 4. 错误处理是否泄露内部信息 审查完成后，按严重程度分级列出问题，并给出修复建议。

这里有几个关键点值得展开。description字段决定了这个命令在命令列表里显示什么说明，写得好不好直接影响你记不记得住这个命令是干嘛的。allowed-tools字段限制了执行该命令时 Claude 可以调用的工具范围，这是安全边界——比如一个只读审查命令就不应该允许Write工具。正文部分就是提示词模板，Claude 会把当前上下文（选中的代码、打开的文件等）和这段模板一起送给模型。

我实测下来，命令文件里的提示词要写得“具体到可执行”。像“请审查代码”这种就太泛，模型会给你一堆泛泛而谈；而“检查所有用户输入是否经过 sanitize、检查 SQL 拼接是否使用参数化查询”这种，模型就能给出真正有用的结果。

2.2 Skills 与 Commands 的分工

很多人分不清 skills 和 commands 的区别。我用一个类比来解释：command 像是你按下的一个按钮，按下去就执行一个动作；skill 像是你给 Claude 的一本参考手册，它会在需要的时候自己翻阅。

具体来说，commands 是用户主动触发的，有明确的输入输出预期；skills 是模型在推理过程中根据任务需要自动加载的知识模块。比如你装了一个“Python 测试规范”的 skill，当 Claude 在帮你写测试代码时，它会自动参考这个 skill 里的规范，而不需要你手动调用。

在knowledge-work-plugins里，skills 通常包含：

• 领域知识：比如某个框架的最佳实践、某个 API 的使用约定。
• 决策规则：在什么情况下该用什么方案，什么情况下该拒绝。
• 输出模板：特定类型任务的输出格式要求。

这种分工让插件既能响应用户的显式指令，又能在后台默默提升输出质量。我个人的经验是，把“每次都要交代的背景知识”放进 skills，把“需要主动触发的操作”做成 commands，这样用起来最顺手。

2.3 插件加载与优先级机制

Claude Code 启动时会按以下顺序加载插件：

1. 内置插件（随 Claude Code 一起发布）
2. 用户级插件（安装在用户主目录下）
3. 项目级插件（安装在项目.claude/目录下）

后加载的插件会覆盖先加载的同名命令。这个机制很有用：你可以在用户级装一个通用插件，然后在特定项目里装一个项目级插件来覆盖某些命令的行为。比如通用插件里的/review命令做基础审查，项目级插件里的/review命令加上该项目特有的检查项。

注意：覆盖是整体覆盖，不是合并。如果你只想在原有命令基础上加一条检查项，需要把原命令内容复制过来再修改，而不是只写新增部分。

2.4 权限模型与安全边界

插件系统有一套权限模型，决定了插件能做什么、不能做什么。核心概念是allowed-tools和denied-tools：

这套机制的意义在于，当你从社区安装一个第三方插件时，你可以通过审查它的allowed-tools配置来判断它是否安全。一个文档生成插件如果声明了Bash权限，你就该多留个心眼。

我自己的做法是：所有涉及文件写入的命令，都显式声明allowed-tools: Read, Write，不写Bash；所有涉及网络请求的命令，单独审查其必要性。这样即使插件本身有 bug，也不会造成意外破坏。

3. 从零搭建一个知识工作插件

3.1 环境准备与项目初始化

在开始写插件之前，你需要确保本地已经装好 Claude Code。安装方式根据操作系统不同略有差异，但核心步骤一致：下载对应平台的安装包，运行安装程序，然后在终端里执行claude --version验证安装成功。

安装完成后，创建一个插件开发目录。我习惯在~/dev/claude-plugins/下放所有自研插件，每个插件一个子目录。以创建一个“API 文档生成”插件为例：

mkdir -p ~/dev/claude-plugins/api-doc-gen/.claude-plugin mkdir -p ~/dev/claude-plugins/api-doc-gen/commands mkdir -p ~/dev/claude-plugins/api-doc-gen/skills cd ~/dev/claude-plugins/api-doc-gen

然后创建.claude-plugin/plugin.json：

{ "name": "api-doc-gen", "version": "1.0.0", "description": "根据代码自动生成 API 文档", "author": "your-name", "commands": ["commands/"], "skills": ["skills/"] }

这个文件是插件的“身份证”，Claude Code 靠它识别插件并加载对应目录。name字段要唯一，建议用 kebab-case；version遵循语义化版本规范，方便后续更新管理。

3.2 编写第一个 Slash Command

在commands/目录下新建gen-api-doc.md：

--- description: 扫描当前项目的路由定义，生成 Markdown 格式的 API 文档 allowed-tools: Read, Grep, Write --- 请执行以下步骤生成 API 文档： 1. 使用 Grep 搜索项目中所有路由定义文件，识别框架类型（FastAPI、Express、Spring 等） 2. 逐个读取路由文件，提取每个接口的路径、方法、请求参数、响应结构 3. 按以下模板生成 Markdown 文档： ## 接口名称 - **路径**: /api/xxx - **方法**: GET/POST/... - **请求参数**: 参数名、类型、是否必填、说明 - **响应示例**: JSON 代码块 - **错误码**: 常见错误及含义 4. 将结果写入 `docs/API.md` 注意：如果发现接口缺少参数说明或响应定义，在文档中用 `[待补充]` 标记，不要编造。

这个命令的设计有几个考量。第一，它明确要求先识别框架类型，因为不同框架的路由定义方式差异很大，不先判断就容易提取错误。第二，它给出了固定的输出模板，保证每次生成的文档格式一致。第三，它明确禁止编造信息，这是 AI 生成文档最容易出问题的地方——模型会“脑补”不存在的参数。

写完之后，在项目里安装这个插件进行测试：

claude plugin install ~/dev/claude-plugins/api-doc-gen

然后在 Claude Code 会话里输入/gen-api-doc，看它是否能正确执行。

3.3 设计一个实用的 Skill

Skill 文件放在skills/目录下，每个 skill 一个子目录，里面放SKILL.md。以“代码审查规范”为例：

--- name: code-review-standards description: 团队代码审查的检查清单和输出规范 --- ## 审查维度 ### 正确性 - 边界条件是否处理（空值、越界、并发） - 错误处理是否完整，异常是否被吞掉 - 资源是否正确释放（文件句柄、数据库连接） ### 可维护性 - 函数是否过长（超过 50 行需拆分） - 命名是否表意清晰，避免缩写歧义 - 是否有重复代码可以抽取 ### 安全性 - 用户输入是否验证和转义 - 敏感数据是否加密存储 - 权限检查是否在每个入口都有 ## 输出格式 按严重程度分三级： - **阻断**: 必须修复才能合并 - **建议**: 应该修复，但不阻塞合并 - **提示**: 可选优化，记录备查 每条问题需包含：文件路径、行号、问题描述、修复建议。

这个 skill 的价值在于，它把团队内部的审查标准固化下来。新成员用 Claude Code 做审查时，输出质量直接对齐团队要求，不需要额外培训。我实测下来，有了这个 skill 之后，代码审查意见的“可操作性”提升非常明显，以前模型爱说“建议优化错误处理”，现在会说“第 42 行的except Exception会吞掉 KeyboardInterrupt，建议改为except (ValueError, IOError)”。

3.4 用 Hooks 实现自动化触发

Hooks 是插件里最容易被忽视但威力最大的部分。它允许你在特定事件发生时自动执行脚本。比如你想在每次保存文件时自动运行格式化：

{ "hooks": { "PostToolUse": [ { "matcher": "Write", "command": "bash hooks/format-on-save.sh" } ] } }

hooks/format-on-save.sh可以调用项目的格式化工具：

#!/bin/bash FILE=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.file_path') if [[ "$FILE" == *.py ]]; then black "$FILE" 2>/dev/null elif [[ "$FILE" == *.js || "$FILE" == *.ts ]]; then prettier --write "$FILE" 2>/dev/null fi

注意：Hook 脚本要尽量轻量、快速返回。如果脚本执行超过几秒，会明显拖慢 Claude Code 的响应速度。我踩过的坑是在 hook 里跑了全量测试，结果每次保存文件都要等半分钟，后来改成只跑受影响文件的 lint 才恢复正常。

3.5 本地调试与迭代方法

插件开发最烦的是“改了要重装才能测”。我的做法是直接用--plugin-dir参数指定插件目录启动 Claude Code：

claude --plugin-dir ~/dev/claude-plugins/api-doc-gen

这样修改命令文件后，重启会话就能生效，不需要反复安装卸载。调试 slash command 时，我习惯在命令文件里临时加一行echo输出中间状态，确认模型是否正确理解了指令。调试 skill 时，则通过观察模型输出是否引用了 skill 里的规范来判断加载是否成功。

另一个实用技巧是建一个“测试项目”，里面放各种典型场景的代码文件，每次改完插件就在这个项目里跑一遍，看输出是否符合预期。这比在真实项目里试错安全得多。

4. 实战场景与组合玩法

4.1 场景一：多插件协同的代码审查流水线

单独一个审查插件能力有限，但把几个插件组合起来，就能形成一条完整的流水线。我的配置是这样的：

• security-scan插件：负责安全维度的检查，输出漏洞列表。
• style-check插件：负责代码风格和规范检查。
• review-summary插件：把前两者的输出汇总成一份审查报告。

在 Claude Code 里依次执行：

/security-scan /style-check /review-summary

review-summary的命令定义里会读取前两个命令的输出文件，按统一格式合并。这种“分而治之”的思路比写一个巨型审查命令要好维护得多——安全规则变了只改 security-scan，风格规范变了只改 style-check。

我实测下来，这条流水线在中等规模的项目（约 5 万行代码）上跑一次完整审查大约需要 3-5 分钟，能发现 80% 以上的常见问题。剩下的 20% 需要人工判断的，模型会明确标注“需要人工确认”，不会强行给结论。

4.2 场景二：文档生成与同步

知识工作者另一大痛点是文档和代码不同步。代码改了，文档没改，过两个月谁也不知道哪个是对的。用插件可以缓解这个问题：

• doc-sync插件：对比代码变更和文档变更，找出可能过时的文档段落。
• changelog-gen插件：根据 git 提交记录生成 changelog。
• readme-update插件：检查 README 里的示例代码是否还能运行。

doc-sync的实现思路是：先用git diff找出本次变更涉及的文件和函数，然后在文档里搜索这些函数名，如果文档里提到了但内容没更新，就标记为“可能过时”。这个逻辑不复杂，但非常实用。我把它设成 pre-commit hook，每次提交前自动跑一遍，提醒我更新文档。

4.3 场景三：团队知识库的插件化封装

团队里总有一些“只有老员工知道”的知识：某个服务的部署流程、某个接口的调用注意事项、某个工具的配置方法。这些知识散落在 wiki、聊天记录和某人的脑子里，新人上手成本很高。

我的做法是建一个team-knowledge插件，把这些知识做成 skills：

• deploy-checklistskill：部署前的检查清单。
• api-gotchasskill：各接口的坑和注意事项。
• troubleshootingskill：常见故障的排查步骤。

新人装好这个插件后，遇到问题时 Claude 会自动参考这些知识给出建议。比如新人问“订单服务部署后报 503 怎么办”，Claude 会加载troubleshootingskill，按里面记录的步骤引导排查。

这个做法的好处是知识“活”了。以前写在 wiki 里的文档没人看，现在集成到日常工具里，用的时候自然就看到了。而且更新方便，改一个 skill 文件，所有人下次会话就生效。

4.4 插件组合的配置管理

插件装多了之后，管理是个问题。我的经验是分三层管理：

用户级放那些跟具体项目无关的，比如“Markdown 格式化”“JSON 校验”。团队级放代码规范、审查标准这类全团队统一的。项目级放这个项目特有的，比如“这个项目的数据库 schema 说明”。

更新时按层级来：项目级改动最频繁，直接改直接生效；团队级走 PR 流程，保证质量；用户级基本不动，装好就不管了。

5. 常见问题与排查实录

5.1 插件装了但不生效

这是最常见的问题，排查顺序如下：

1. 检查 plugin.json 格式：用jq . plugin.json验证 JSON 是否合法。我遇到过因为多了一个逗号导致整个插件加载失败的情况。
2. 检查目录结构：commands/和skills/必须在 plugin.json 里正确声明，且路径相对于插件根目录。
3. 检查命令文件名：文件名就是命令名，不能有空格或特殊字符。gen-api-doc.md对应/gen-api-doc。
4. 检查加载顺序：用claude plugin list查看已加载插件，确认你的插件在列表里。如果被同名插件覆盖了，需要调整加载顺序或改命令名。

提示：Claude Code 启动时加--debug参数可以看到插件加载的详细日志，排查加载问题非常有用。

5.2 Slash Command 执行结果不符合预期

模型没有按命令文件里的指令执行，通常有三个原因。一是指令太模糊，模型自由发挥。解决办法是把指令拆成明确的步骤，每步都有可验证的输出。二是上下文太长，指令被“淹没”了。这时候要把关键指令放在命令文件的开头，并用加粗或列表突出。三是allowed-tools配置不对，模型想调用某个工具但被拒绝了，只能绕路走。

我踩过的一个坑是：命令里要求“读取所有相关文件”，但allowed-tools只写了Read没写Grep，模型没法搜索文件，只能凭猜测回答。加上Grep之后就正常了。

5.3 Skill 没有被自动加载

Skill 的加载是模型根据任务判断的，不是每次都会触发。如果发现 skill 没生效，可以：

• 在命令里显式引用 skill 名称，比如“请参考 code-review-standards skill 进行审查”。
• 检查 skill 的description是否准确描述了适用场景，描述太泛会导致模型判断不准。
• 确认 skill 文件路径在 plugin.json 里正确声明。

5.4 插件冲突与覆盖问题

两个插件定义了同名命令时，后加载的会覆盖先加载的。如果你发现某个命令的行为跟预期不符，先用claude plugin list确认是否有同名命令被覆盖。解决办法要么改命令名，要么调整插件加载顺序。

我自己的命名习惯是给命令加前缀，比如api-gen-doc、api-scan-security，这样即使装了多个插件也不容易冲突。

5.5 性能问题与优化建议

插件装多了之后，Claude Code 启动会变慢。主要原因是启动时要扫描所有插件的命令和 skill 文件。优化方法：

• 把不常用的插件禁用而不是卸载，需要时再启用。
• 命令文件尽量精简，不要把大段参考文档塞进命令文件，那部分应该放 skill。
• Hook 脚本要快，超过 1 秒的脚本考虑改成异步或手动触发。

我实测下来，装 10 个左右的插件对启动速度影响在可接受范围内（增加 1-2 秒），超过 20 个就明显变慢了。所以插件要精选，不要什么都装。

5.6 常见问题速查表

6. 插件开发的经验与边界

6.1 什么该封装成插件

不是所有东西都值得做成插件。我的判断标准是：如果一个操作你每周至少做三次，且每次的流程基本固定，那就值得封装。反之，一次性的、高度依赖具体上下文的操作，写个临时提示词就够了。

另外要考虑维护成本。插件是要长期维护的，代码规范变了、工具升级了，插件都得跟着改。如果某个流程本身还在快速迭代中，过早封装反而会增加负担。我的做法是先用提示词跑一段时间，等流程稳定了再封装成插件。

6.2 插件粒度的把握

一个插件应该只做一件事，但要把这件事做完整。比如“API 文档生成”是一个合理的插件粒度，它包含扫描路由、提取信息、生成文档、写入文件这一整套流程。而“读取文件”就不该单独做成插件，它太底层了。

我见过有人把一个插件的功能拆得太细，结果用的时候要依次调用五六个命令，体验很差。也见过有人把所有功能塞进一个插件，结果命令列表长得找不到想要的。我的经验是：一个插件对应一个完整的工作流，命令数量控制在 3-7 个之间比较合适。

6.3 版本管理与分发

插件是要分发的，所以版本管理很重要。我遵循的规则是：

• 主版本号：命令名变更、输出格式不兼容变更时递增。
• 次版本号：新增命令或 skill 时递增。
• 修订号：修复 bug、调整提示词时递增。

分发方式看场景。团队内部用 git 仓库，成员通过claude plugin install <git-url>安装。公开分享可以发布到插件市场，或者直接给一个压缩包。不管哪种方式，README 里都要写清楚安装方法、依赖项和使用示例。

6.4 安全审查不可跳过

从外部安装插件前，一定要审查它的内容。重点看三处：allowed-tools是否声明了不必要的权限、hook 脚本是否执行了可疑操作、命令文件里是否有诱导模型泄露敏感信息的指令。

我自己的审查清单是：

• [ ] plugin.json 里的 author 和来源是否可信
• [ ] 所有命令的 allowed-tools 是否最小化
• [ ] hook 脚本是否只做声明的事情
• [ ] 是否有命令会读取或写入敏感路径
• [ ] 是否有命令会发起网络请求

这套审查流程花不了几分钟，但能避免很多风险。毕竟插件是运行在你本地环境里的，权限给大了等于把家门钥匙交出去。

6.5 持续迭代的思路

插件不是写完就完了。我的做法是每次用完插件后花一分钟想想：这次输出哪里不满意？是提示词不够具体，还是缺少某个检查项？把这些记下来，攒够几条就更新一版。

另外要关注 Claude Code 本身的更新。新版本可能会引入新的插件能力，比如新的 hook 事件类型、新的工具类型。及时跟进这些变化，能让插件保持好用。我订阅了 Claude Code 的更新日志，每次有新版本就看看有没有跟插件相关的改动。

最后分享一个我个人的小习惯：给每个插件写一个CHANGELOG.md，记录每次改了什么、为什么改。过几个月回头看，能快速回忆起当时的决策背景，避免重复踩坑。这个习惯看起来麻烦，但长期来看省的时间远超投入。