Shipwright：AI编程插件市场，打造专业级AI开发工作流

1. 项目概述：一个为AI编程工具而生的“插件市场”

如果你和我一样，日常开发重度依赖 Cursor、Claude Code 这类 AI 驱动的 IDE，那你肯定遇到过这样的场景：想让 AI 帮你写个单元测试，结果它生成了一堆不痛不痒的断言；想让 AI 审查代码安全，它却只停留在“注意 SQL 注入”这种泛泛之谈。我们缺的不是一个能写代码的 AI，而是一个能像资深工程师一样，带着“领域知识”和“最佳实践”来工作的 AI 伙伴。

这就是 Shipwright 要解决的问题。它不是一个单一的工具，而是一个专为 AI 编程环境设计的、开源的插件市场与框架。你可以把它理解成一个“AI 技能包”的集合分发中心。这些“技能包”分为三类：Agents（智能体）、Skills（技能）和MCPs（模型上下文协议服务器）。它们共同的目标，是将零散的 AI 指令，升级为一套覆盖软件开发生命周期（SDLC）的、可复用的自动化工作流。

简单来说，Shipwright 让 AI 从“一个什么都能聊但可能都不精通的实习生”，变成了一个“拥有明确岗位职责和深厚专业经验的团队”。这个团队里有专门做架构设计的“架构师”，有专注代码安全的“安全专家”，有负责生成变更日志的“文档工程师”。你不再需要每次都对 AI 进行冗长的“岗前培训”，只需安装对应的 Agent，它就已经内置了完成特定任务所需的全部知识和判断逻辑。

2. Shipwright 的核心组件与设计哲学

要理解 Shipwright 的价值，得先拆解它的三个核心组件，以及它们背后“深度专业化”的设计理念。

2.1 Agents：深度专业化的“AI 角色”

Agent 是 Shipwright 中最上层的概念，代表一个能独立完成特定开发任务的 AI 角色。每个 Agent 都不仅仅是一个简单的提示词（Prompt），而是一个深度定制化、高度专业化的“AI 员工”。

以security-reviewer（安全审查员）这个 Agent 为例。一个普通的 AI 指令可能是：“请检查这段代码的安全问题。” 而 Shipwright 的security-reviewerAgent 内部，则封装了以下逻辑：

1. 知识框架：它内置了 OWASP Top 10 等安全知识库，知道当前最需要关注哪些漏洞类型。
2. 审查流程：它会按照威胁建模的思路，先识别数据流、信任边界，再逐项检查输入验证、身份认证、敏感数据处理等环节。
3. 输出标准：它的反馈不是模糊的建议，而是会明确指出漏洞类型（如 CWE-ID）、风险等级（高/中/低）、受影响代码位置以及具体的修复代码示例。

这种“深度专业化”意味着，当你使用architect-agent时，你得到的不只是一个能画 UML 图的 AI，而是一个会进行多方案权衡分析（比如在微服务 vs 单体、不同数据库选型间的取舍）、考虑非功能性需求（如可扩展性、可维护性），并能输出包含 Mermaid 架构图和分阶段实施计划的“架构师”。

注意：Agent 的“深度”来源于其“技能”的捆绑。一个 Agent 可以依赖多个 Skills，这确保了它的专业性不是空谈，而是建立在可复用的最佳实践模块之上。

2.2 Skills：可复用的“最佳实践”模块

如果说 Agent 是“岗位”，那么 Skill 就是“职业技能”。Skills 是独立的、可复用的知识模块，它们定义了在某个特定领域应该如何思考和工作。

例如，code-quality-fundamentals这个 Skill，可能包含了：

• 命名规范：变量、函数、类的命名原则（如使用camelCase还是snake_case，避免使用data,info等模糊词）。
• SOLID 原则：如何识别违反单一职责原则的类，如何重构以遵循依赖倒置原则。
• 错误处理模式：何时使用返回错误码，何时使用异常，如何设计可读的错误信息。

Skills 的妙处在于其可组合性。implementer-agent（实现者）可能同时依赖code-quality-fundamentals和security-awareness两个 Skills。这意味着它写出的每一行代码，都会同时兼顾代码整洁度和安全性。而test-engineer（测试工程师）则可能依赖test-patterns和code-quality-fundamentals，确保生成的测试不仅覆盖全面，而且代码本身也易于维护。

更重要的是，Skills 遵循 Agent Skills 开放规范 ，这意味着它们理论上可以被任何兼容此规范的 AI 工具或平台使用，提高了知识的可移植性。

2.3 MCPs：连接外部世界的“桥梁”

MCP（Model Context Protocol）是 Anthropic 提出的一种协议，旨在让 AI 模型能够安全、结构化地访问外部工具、数据和系统。在 Shipwright 中，MCP 服务器扮演了“信息提供者”的角色。

例如，context7这个 MCP 可以为 AI 提供最新版本的库和框架文档。当implementer-agent在使用一个不熟悉的库时，它可以通过context7实时查询 API 用法，而不是依赖于可能过时的训练数据。mcp-atlassian则直接连接你的 Jira 和 Confluence，让 AI 在分析 issue 或编写设计文档时，能直接获取项目管理系统中的上下文信息。

MCP 极大地扩展了 AI Agent 的能力边界，使其不再是一个封闭的、仅依赖内部知识的系统，而是一个能够实时与开发生态交互的智能体。

2.4 设计哲学：从“通用聊天”到“专项自动化”

Shipwright 的整个设计，体现了一种清晰的范式转变：从依赖每次对话的、即兴的 AI 指令，转向基于预定义角色和技能的、可重复的自动化流程。

这种转变带来了几个关键优势：

1. 一致性：无论哪个团队成员触发pr-reviewer，其审查的标准和严格程度都是一致的。
2. 可预测性：你知道changelog-generator一定会按照语义化版本（SemVer）的规则来生成版本号和发布说明。
3. 效率：无需为每个重复性任务（如 Issue 分类、基础安全扫描）重新描述需求，一键调用即可。
4. 知识沉淀：团队的最佳实践（如安全规范、代码审查清单）可以固化到 Skills 和 Agents 中，新人也能立即产出符合标准的工作成果。

3. 三种使用路径详解与实操指南

Shipwright 提供了三种接入方式，覆盖了从本地开发到 CI/CD 自动化的全场景。选择哪条路径，取决于你的主要使用场景。

3.1 路径一：Ship CLI（通用命令行工具）—— 本地开发的瑞士军刀

这是最灵活、最推荐给个人开发者或小团队的方式。Ship CLI 是一个用 Go 编写的命令行工具，它像一个智能的“插件管理器”，能识别你的开发环境（Cursor、Claude Code、Codex），并将插件安装到对应工具的原生目录中。

安装与基础使用

# 1. 安装 Ship CLI (需要 Go 环境) go install github.com/CaptShanks/shipwright/cli/cmd/ship@latest # 2. 验证安装 ship --version # 3. 浏览插件市场 ship search # 这会列出所有可用的 Agents, Skills 和 MCPs，并附带简短描述。 # 4. 查看某个插件的详细信息 ship info pr-reviewer # 输出会包括该 Agent 的描述、捆绑的 Skills、使用示例等，帮助你决定是否安装。 # 5. 安装插件（以 pr-reviewer 为例） # 默认安装到当前项目的所有检测到的工具中 ship install pr-reviewer # 6. 查看已安装的插件 ship list

高级配置与管理

# 1. 针对特定工具安装 # 如果你只在 Cursor 中工作，可以指定目标，避免污染其他工具的配置 ship install architect-agent --target cursor # 2. 全局安装 # 将插件安装到用户主目录下的工具配置中，对所有项目生效 ship install shipwright-full --global # 注意：`shipwright-full` 是包含所有插件的捆绑包，体积较大，首次安装可能需要一些时间。 # 3. 安装 MCP 服务器 # MCP 服务器通常需要全局安装，以便所有项目都能访问 ship mcp install context7 --global # 4. 卸载插件 ship uninstall triage-agent # 同样可以结合 --target 和 --global 参数 # 5. 更新所有已安装插件 ship update

实操心得：我通常会在新项目初始化时，运行ship install implementer-agent test-engineer --target cursor，为项目快速配备“实现”和“测试”两个核心角色。对于security-reviewer和pr-reviewer，我更倾向于全局安装，因为它们属于跨项目的通用质量门禁。

3.2 路径二：Claude Code 插件市场（原生集成）—— 最无缝的体验

如果你主要使用 Claude Code，那么通过其内置的插件系统安装 Shipwright 是最直接的方式。这种方式完全在 Claude Code 的生态内完成，管理起来非常直观。

安装步骤

1. 在 Claude Code 的聊天窗口中，输入以下命令来添加 Shipwright 的插件市场源（只需一次）：

   /plugin marketplace add CaptShanks/shipwright

2. 添加成功后，你就可以像安装其他插件一样安装 Shipwright 的组件了：

   /plugin install security-reviewer@shipwright /plugin install implementer-agent@shipwright

3. 如果你想一次性获得全部能力，可以安装完整包：

   /plugin install shipwright-full@shipwright

安装后，这些 Agents 会出现在 Claude Code 的插件列表中。当你需要执行特定任务时，只需在聊天中@对应的 Agent（例如@security-reviewer），然后附上你的代码或问题即可。

注意事项：通过此方式安装的插件，其更新依赖于 Claude Code 的插件管理机制和 Shipwright 作者在市场上的发布。如果你需要更频繁的更新或测试自定义插件，使用 Ship CLI 是更灵活的选择。

3.3 路径三：GitHub Actions（CI/CD 自动化）—— 团队协作与流程固化

这是 Shipwright 最具威力的使用方式。它将 AI Agents 集成到你的 GitHub 工作流中，实现从 Issue 创建到代码合并的自动化流水线。

核心概念：可重用工作流Shipwright 提供了几个开箱即用的 GitHub Actions 可重用工作流（Reusable Workflows），你只需要在你的仓库中创建一个“薄薄的”调用文件即可。

实战：自动化 Issue 分类与响应

假设我们想实现：每当有新的 Issue 被创建时，自动由 AI 进行分析，判断其是否清晰、可执行，并自动回复请求更多信息或分类标签。

1. 准备项目上下文：首先，在你的仓库根目录创建.github/shipwright/project-context.md文件。这个文件是 AI 理解你项目的基础，至关重要。

   # 项目：我的微服务应用 ## 技术栈 - 后端：Go 1.21+, Gin 框架，GORM - 数据库：PostgreSQL，Redis - 部署：Kubernetes，Docker ## 代码规范 - 遵循 Go 官方代码规范。 - 错误处理：使用 `errors.Wrap` 包装错误，并记录日志。 - API 响应：统一使用 `{“code”: 200, “data”: {}, “msg”: ““}` 格式。 ## Issue 模板要求 - **Bug 报告**：必须包含复现步骤、预期行为、实际行为、相关日志。 - **功能请求**：必须描述业务场景、价值、以及初步的 API 设计思路。 ## 分支策略 - `main`: 生产分支。 - `develop`: 开发分支。 - 功能分支：`feat/xxx`。 - 修复分支：`fix/xxx`。

   这个文件越详细，AI 做出的判断就越准确。

2. 创建调用工作流：在.github/workflows/目录下创建ai-triage.yml。

   name: AI Triage on: issues: types: [opened, edited] # 在 Issue 被创建或编辑时触发 jobs: triage: # 关键：使用 Shipwright 提供的可重用工作流 uses: CaptShanks/shipwright/.github/workflows/ai-triage.yml@main with: # 指定使用的 AI 提供商，支持 claude (Claude Code) 或 codex ai-provider: claude # 指向你的项目上下文文件 project-context-path: .github/shipwright/project-context.md # (可选) 注入额外的技能，例如针对 Go 项目的技能 additional-skills: go-skills secrets: # 必须提供 AI 服务的认证令牌 CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

3. 配置 GitHub Secrets：在仓库的 Settings -> Secrets and variables -> Actions 中，添加CLAUDE_CODE_OAUTH_TOKEN，其值需要从你的 Claude Code 设置中获取（通常涉及 OAuth 授权流程）。

完成以上步骤后，当有新 Issue 提交，GitHub Actions 会自动触发triage-agent。该 Agent 会读取 Issue 内容和你的project-context.md，然后执行以下操作：

• 判断 Issue 描述是否清晰、完整。
• 如果信息不足，它会自动在 Issue 下发表评论，以你的项目规范为基准，请求用户提供缺失的信息（例如：“请提供相关的错误日志”或“请描述一下这个功能的预期用户流程”）。
• 根据内容，自动打上bug、enhancement、needs-info等标签。
• 甚至可以将复杂的 Issue 分配给architect-agent进行下一步处理。

其他自动化工作流

• ai-implement.yml：可用于在特定分支（如triage/approved）创建后，自动分析 Issue 并尝试生成实现代码的 Pull Request。
• ai-pr-review.yml：在 PR 创建或更新时，自动进行代码审查，从代码质量、安全、规范符合度等方面给出评审意见。

核心优势：这种方式将 AI 能力“服务化”和“流程化”了。它不再依赖于某个开发者手动去触发 AI，而是成为了团队开发流程中一个自动化的、可靠的环节，极大地提升了问题响应和代码审查的效率和一致性。

4. 核心插件深度解析与选型建议

Shipwright 的插件生态是其核心价值。了解每个插件的特性和适用场景，能帮助你组建高效的“AI 团队”。

4.1 Agents 插件选型指南

4.2 Skills 技能库：构建自定义 Agent 的基石

Skills 是混合搭配的乐高积木。除了 Agent 自带的，你还可以在 CI/CD 工作流或 Agent 的 Frontmatter 中注入额外的 Skills。

如何为 Agent 附加额外 Skill？对于本地使用，你需要编辑 Agent 的配置文件（通常是一个.md文件）。例如，在 Cursor 中，.cursor/agents/implementer-agent.md文件顶部可能有如下 Frontmatter：

--- skills: - security-awareness - scalability-resilience - code-quality-fundamentals # 你可以在这里添加 - go-skills # 为 Go 项目添加 Go 专属技能 - terraform-development # 如果项目涉及 IaC ---

在 GitHub Actions 中，则通过additional-skills输入参数传递：

with: ai-provider: claude project-context-path: .github/shipwright/project-context.md additional-skills: go-skills, terraform-development

核心技能解析：

• go-skills/terraform-development：这类语言/框架特定技能是提升 AI 输出质量的关键。它们包含了该领域特有的惯用法、设计模式和最佳实践。
• security-awareness与security-owasp：前者更偏向于安全编码意识（如输入验证、密钥管理），后者则提供了具体的漏洞检查清单和模式。两者结合，能实现从意识到具体检查的全覆盖。
• scalability-resilience：对于开发云原生或分布式系统尤为重要，它指导 AI 思考幂等性、重试、熔断、优雅降级等模式。

4.3 MCP 服务器：扩展 AI 的“视野”

MCP 服务器为 AI Agent 提供了动态的、结构化的外部知识。

• context7：必装的基础设施。它能极大减少 AI 因依赖过时知识而产生的“幻觉”，尤其是在使用快速迭代的框架或库时。
• serena：提供语义级别的代码导航。对于大型重构或理解复杂代码库非常有帮助，能让 AI 更准确地定位符号和依赖关系。
• mcp-atlassian/bitbucket-cloud：团队协作集成。如果你的项目管理、文档和代码仓库分散在不同平台，这些 MCP 能打通信息孤岛，让 AI 在分析任务时拥有全局视角。例如，architect-agent在设计时可以直接引用 Jira 上的原始需求描述。

选型建议：对于个人开发者，context7是首选。对于使用 Atlassian 全家桶的团队，mcp-atlassian能带来显著的上下文提升。建议通过ship mcp install <name> --global全局安装 MCP，以便所有项目共享。

5. 项目集成实战与自定义开发

5.1 深度集成：打造属于你团队的 AI 工作流

仅仅安装插件是不够的，真正的威力在于将其深度集成到你的团队规范和流程中。

第一步：精心编写project-context.md这是 AI 理解你项目的“宪法”。一份好的上下文文件应包含：

• 技术栈与版本：精确到主要库的版本号。
• 架构概述：简单的架构图描述或核心服务列表。
• 开发规范：
  • 代码风格指南（链接或简要说明）。
  • 提交信息格式（如 Conventional Commits）。
  • API 设计规范（RESTful 风格、错误响应格式）。
  • 测试规范（覆盖率要求、测试文件命名）。
• 业务领域术语：解释项目特有的业务概念和缩写。
• 常用命令：项目启动、测试、构建、部署的命令。

第二步：设计自动化工作流链一个进阶的用法是将多个 Agents 串联起来，形成一个自动化流水线。这可以通过 GitHub Actions 的workflow_call或条件触发来实现。

示例：从 Issue 到 PR 的自动化流水线

1. ai-triage.yml处理新 Issue，打上approved标签。
2. 另一个工作流监听带有approved标签的 Issue，自动创建功能分支，并触发ai-implement.yml。
3. ai-implement.yml调用implementer-agent和test-engineer，在该分支上提交实现代码和测试。
4. 创建 PR 后，ai-pr-review.yml自动被触发进行审查。
5. 审查通过后，changelog-generator可以准备发布说明。

第三步：创建团队共享的 Custom Skills如果团队有非常特定的实践（例如，使用一套内部的状态管理库，或有独特的日志规范），可以将其封装成自定义的 Skill。这确保了所有 AI Agent 在相关任务上都遵循同一套内部标准。 创建 Skill 需要遵循 Agent Skills 规范 ，本质上是一个结构化的 Markdown 文件，定义了技能的名称、描述、上下文、示例和约束条件。

5.2 创建自定义 Agent

当现有的 Agent 无法满足你的特定需求时，你可以创建自定义 Agent。例如，你可能需要一个专门为你的“数据报表微服务”生成特定类型 API 文档的 Agent。

创建步骤：

1. 定义角色与目标：明确你的 Agent 要解决什么问题？它的专业领域是什么？（例如：“GraphQL API 文档专家”）。
2. 编写 Frontmatter：在 Agent 文件的头部，用 YAML 定义其元数据。

   --- name: graphql-doc-agent description: 专门为我们的 GraphQL 服务生成符合团队标准的 API 文档。 skills: - code-quality-fundamentals - go-skills # 假设后端是 Go # 可以引用一个自定义的 graphql-doc-skill instructions: | 你是一个经验丰富的 GraphQL API 文档工程师。你的任务是根据提供的 GraphQL Schema 和解析器代码，生成清晰、完整的 API 文档。 文档必须包含： 1. 每个 Query 和 Mutation 的详细描述、参数说明、返回类型。 2. 复杂类型的定义和关系。 3. 使用示例（包括请求和响应）。 4. 错误码列表及其含义。 请使用我们团队标准的 Markdown 模板。 ---

3. 编写详细指令：在 Frontmatter 下的instructions部分，用自然语言详细描述 Agent 应该如何工作，包括步骤、格式要求、注意事项等。这部分越详细，Agent 的行为就越可控。
4. 放置到正确目录：根据目标工具，将写好的.md或.toml文件放到对应的目录（如.cursor/agents/或.claude/agents/）。
5. 测试与迭代：在真实场景中测试你的 Agent，根据输出结果不断优化instructions和引用的skills。

5.3 性能调优与成本考量

使用 AI Agents 会消耗 AI 提供商的 API 额度（如 Claude 的 Token）。在团队中大规模使用时，需要关注成本。

优化策略：

1. 精准触发：在 CI/CD 中，不要为每一次提交都触发全量审查。可以设置为仅当 PR 达到一定规模（如超过 200 行代码）或修改了特定路径（如src/auth/）时才触发security-reviewer。
2. 优化上下文：确保project-context.md简洁相关，避免放入无关信息。在调用 Agent 时，只提供完成任务所必需的文件和上下文。
3. 分层使用：对于简单的代码风格检查，可以使用更轻量、更便宜的模型或规则工具（如 linter）。将 AI Agent 聚焦在需要深度理解和推理的任务上，如架构设计、复杂逻辑审查。
4. 缓存结果：对于一些分析类任务（如codebase-analyzer的结果），如果代码库没有重大变化，可以考虑缓存分析结果，避免重复计算。

6. 常见问题、排查技巧与未来展望

6.1 安装与配置问题

问题1：ship命令找不到或安装失败。

• 排查：确保 Go 环境已正确安装且GOPATH/bin已加入系统的 PATH 环境变量。可以尝试go version和echo $PATH来检查。
• 解决：如果网络问题导致安装失败，可以尝试从 Shipwright 的 GitHub Releases 页面直接下载对应平台的可执行文件。

问题2：在 Cursor/Claude Code 中安装了 Agent，但无法调用或没有反应。

• 排查：
  1. 确认插件安装到了正确的目录。使用ship list --target cursor查看。
  2. 检查 Agent 文件格式是否正确（特别是 Frontmatter 的 YAML 部分）。
  3. 重启你的 IDE。有时 IDE 需要重启才能加载新的插件。
• 解决：查看 IDE 的控制台或日志文件，通常会有加载插件失败的详细错误信息。

问题3：GitHub Actions 工作流运行失败，提示认证错误。

• 排查：检查CLAUDE_CODE_OAUTH_TOKEN或CODEX_API_KEY这个 Secret 是否已在仓库中正确设置，且没有过期。
• 解决：重新生成 Token/Key，并更新 GitHub Secrets。确保工作流 YAML 中secrets部分的变量名拼写正确。

6.2 Agent 输出质量问题

问题4：Agent 生成的代码不符合项目规范。

• 原因：project-context.md描述不够具体，或者 Agent 没有加载到正确的、强相关的 Skills。
• 解决：
  1. 细化你的上下文文件。不要只说“遵循 Go 规范”，而要给出具体例子，如“错误变量命名以Err开头”、“使用ctx作为上下文参数名”。
  2. 为 Agent 附加更具体的技能，如go-skills。
  3. 在给 Agent 的指令中，明确引用你项目中的一个规范文件或示例文件作为参考。

问题5：Agent 在处理复杂任务时“跑偏”或输出无关内容。

• 原因：指令（Instructions）不够清晰，或者提供的上下文窗口过大，导致 AI 注意力分散。
• 解决：
  1. 将大任务拆解。不要一次性让implementer-agent实现整个模块。先让architect-agent输出设计，再分多个步骤让implementer-agent实现各个部分。
  2. 在指令中使用明确的约束和步骤。例如：“第一步，只修改UserService类中的createUser方法。第二步，确保新代码通过所有现有测试。”
  3. 使用@引用其他文件来提供精确的上下文，而不是粘贴大段代码到聊天框。

6.3 高级技巧与最佳实践

1. 组合使用 Agents：不要只用一个 Agent。典型的流程是：triage-agent->architect-agent->implementer-agent->test-engineer->pr-reviewer。每个 Agent 各司其职，形成流水线。
2. 善用 MCP 提供动态上下文：在启动一个涉及第三方库的任务前，先通过@context7让 AI 查询最新文档。这能有效避免基于过时知识的错误。
3. 将 Agents 的输出作为迭代的起点：AI 生成的代码、设计或文档很少是完美的。它们应该被视为一个高质量的“初稿”，需要开发者进行审查、调整和优化。将其纳入你的工作流，而不是完全替代你的工作。
4. 建立反馈循环：如果某个 Agent 的输出持续不符合预期，不要只是抱怨。去检查并优化它的instructions、引用的skills或你提供的project-context。这是一个持续调优的过程。

从我近几个月的实践来看，Shipwright 代表了一种更成熟的 AI 辅助开发范式。它不再是玩具式的聊天交互，而是开始触及软件开发流程的核心——将知识、规范和最佳实践工具化、自动化。虽然目前它更偏向于与 Claude 系工具深度集成，但其基于开放规范（如 Agent Skills）的设计理念，让我们有理由期待一个更互通、更强大的 AI 开发工具生态的到来。对于积极拥抱 AI 的团队和个人来说，现在投入时间学习和集成这样的工具，正是在为未来更高阶的“人机协同”开发模式打下基础。