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 内部则封装了以下逻辑知识框架它内置了 OWASP Top 10 等安全知识库知道当前最需要关注哪些漏洞类型。审查流程它会按照威胁建模的思路先识别数据流、信任边界再逐项检查输入验证、身份认证、敏感数据处理等环节。输出标准它的反馈不是模糊的建议而是会明确指出漏洞类型如 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连接外部世界的“桥梁”MCPModel 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 指令转向基于预定义角色和技能的、可重复的自动化流程。这种转变带来了几个关键优势一致性无论哪个团队成员触发pr-reviewer其审查的标准和严格程度都是一致的。可预测性你知道changelog-generator一定会按照语义化版本SemVer的规则来生成版本号和发布说明。效率无需为每个重复性任务如 Issue 分类、基础安全扫描重新描述需求一键调用即可。知识沉淀团队的最佳实践如安全规范、代码审查清单可以固化到 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/shiplatest # 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 的生态内完成管理起来非常直观。安装步骤在 Claude Code 的聊天窗口中输入以下命令来添加 Shipwright 的插件市场源只需一次/plugin marketplace add CaptShanks/shipwright添加成功后你就可以像安装其他插件一样安装 Shipwright 的组件了/plugin install security-reviewershipwright /plugin install implementer-agentshipwright如果你想一次性获得全部能力可以安装完整包/plugin install shipwright-fullshipwright安装后这些 Agents 会出现在 Claude Code 的插件列表中。当你需要执行特定任务时只需在聊天中对应的 Agent例如security-reviewer然后附上你的代码或问题即可。注意事项通过此方式安装的插件其更新依赖于 Claude Code 的插件管理机制和 Shipwright 作者在市场上的发布。如果你需要更频繁的更新或测试自定义插件使用 Ship CLI 是更灵活的选择。3.3 路径三GitHub ActionsCI/CD 自动化—— 团队协作与流程固化这是 Shipwright 最具威力的使用方式。它将 AI Agents 集成到你的 GitHub 工作流中实现从 Issue 创建到代码合并的自动化流水线。核心概念可重用工作流Shipwright 提供了几个开箱即用的 GitHub Actions 可重用工作流Reusable Workflows你只需要在你的仓库中创建一个“薄薄的”调用文件即可。实战自动化 Issue 分类与响应假设我们想实现每当有新的 Issue 被创建时自动由 AI 进行分析判断其是否清晰、可执行并自动回复请求更多信息或分类标签。准备项目上下文首先在你的仓库根目录创建.github/shipwright/project-context.md文件。这个文件是 AI 理解你项目的基础至关重要。# 项目我的微服务应用 ## 技术栈 - 后端Go 1.21, Gin 框架GORM - 数据库PostgreSQLRedis - 部署KubernetesDocker ## 代码规范 - 遵循 Go 官方代码规范。 - 错误处理使用 errors.Wrap 包装错误并记录日志。 - API 响应统一使用 {“code”: 200, “data”: {}, “msg”: ““} 格式。 ## Issue 模板要求 - **Bug 报告**必须包含复现步骤、预期行为、实际行为、相关日志。 - **功能请求**必须描述业务场景、价值、以及初步的 API 设计思路。 ## 分支策略 - main: 生产分支。 - develop: 开发分支。 - 功能分支feat/xxx。 - 修复分支fix/xxx。这个文件越详细AI 做出的判断就越准确。创建调用工作流在.github/workflows/目录下创建ai-triage.yml。name: AI Triage on: issues: types: [opened, edited] # 在 Issue 被创建或编辑时触发 jobs: triage: # 关键使用 Shipwright 提供的可重用工作流 uses: CaptShanks/shipwright/.github/workflows/ai-triage.ymlmain 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 }}配置 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 插件选型指南插件核心职责适用场景捆绑技能使用建议triage-agentIssue 分类与澄清。分析新 Issue 的完整性、可操作性自动请求更多信息并打标签。开源项目、团队项目用于过滤低质量 Issue减轻维护者负担。无强烈推荐全局启用。作为开发流程的第一道自动化关卡能节省大量沟通成本。architect-agent方案设计与架构。根据需求进行技术选型、绘制架构图、制定实施计划。面对复杂的新功能或重构需求时用于快速生成可供讨论的技术方案。security-awareness,scalability-resilience在启动中型以上开发任务前调用。将其输出尤其是 Mermaid 图作为技术方案文档的一部分。implementer-agent代码实现。根据架构方案或 Issue 描述编写符合项目规范的代码。实现已明确设计的功能或根据清晰的 Bug 描述进行修复。security-awareness,scalability-resilience,code-quality-fundamentals核心生产力工具。为其提供最清晰、最具体的需求描述和上下文效果最好。常与test-engineer搭配使用。test-engineer测试编写。为代码生成单元测试、集成测试追求高覆盖率和边缘案例覆盖。在实现功能后或对遗留代码补充测试时使用。code-quality-fundamentals,test-patterns指定测试框架如 Jest, pytest和项目已有的测试模式能生成更贴合项目的测试代码。security-reviewer安全审查。基于 OWASP 等标准静态分析代码中的安全漏洞。在提交 PR 前或对敏感模块如认证、支付进行专项审计时。security-awareness,security-owasp建议集成到 PR 流程中。将其审查意见作为合并前必须处理的安全清单。pr-reviewer代码审查。从代码风格、逻辑正确性、性能、安全等多角度审查 PR。替代或辅助人工进行初步的、规范性的代码审查。security-awareness,code-quality-fundamentals,code-review-standards配置严格的审查标准可以显著提升代码库的整体质量。对于格式化、命名等基础问题AI 审查非常高效。changelog-generator生成变更日志。分析 Git 历史根据约定式提交Conventional Commits自动生成语义化版本和发布说明。每次发布前自动化生成CHANGELOG.md。semantic-versioning与团队的 Git 提交规范强绑定。如果团队遵循 Angular 等规范此工具能极大简化发布工作。codebase-analyzer代码库分析。生成依赖图、运行时路径分析、架构边界图帮助理解复杂项目。接手新项目、进行大型重构前用于快速理解代码结构和模块关系。无探索性工具。在需要绘制项目架构图或梳理复杂调用链时非常有用。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 的自动化流水线ai-triage.yml处理新 Issue打上approved标签。另一个工作流监听带有approved标签的 Issue自动创建功能分支并触发ai-implement.yml。ai-implement.yml调用implementer-agent和test-engineer在该分支上提交实现代码和测试。创建 PR 后ai-pr-review.yml自动被触发进行审查。审查通过后changelog-generator可以准备发布说明。第三步创建团队共享的 Custom Skills如果团队有非常特定的实践例如使用一套内部的状态管理库或有独特的日志规范可以将其封装成自定义的 Skill。这确保了所有 AI Agent 在相关任务上都遵循同一套内部标准。 创建 Skill 需要遵循 Agent Skills 规范 本质上是一个结构化的 Markdown 文件定义了技能的名称、描述、上下文、示例和约束条件。5.2 创建自定义 Agent当现有的 Agent 无法满足你的特定需求时你可以创建自定义 Agent。例如你可能需要一个专门为你的“数据报表微服务”生成特定类型 API 文档的 Agent。创建步骤定义角色与目标明确你的 Agent 要解决什么问题它的专业领域是什么例如“GraphQL API 文档专家”。编写 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 模板。 ---编写详细指令在 Frontmatter 下的instructions部分用自然语言详细描述 Agent 应该如何工作包括步骤、格式要求、注意事项等。这部分越详细Agent 的行为就越可控。放置到正确目录根据目标工具将写好的.md或.toml文件放到对应的目录如.cursor/agents/或.claude/agents/。测试与迭代在真实场景中测试你的 Agent根据输出结果不断优化instructions和引用的skills。5.3 性能调优与成本考量使用 AI Agents 会消耗 AI 提供商的 API 额度如 Claude 的 Token。在团队中大规模使用时需要关注成本。优化策略精准触发在 CI/CD 中不要为每一次提交都触发全量审查。可以设置为仅当 PR 达到一定规模如超过 200 行代码或修改了特定路径如src/auth/时才触发security-reviewer。优化上下文确保project-context.md简洁相关避免放入无关信息。在调用 Agent 时只提供完成任务所必需的文件和上下文。分层使用对于简单的代码风格检查可以使用更轻量、更便宜的模型或规则工具如 linter。将 AI Agent 聚焦在需要深度理解和推理的任务上如架构设计、复杂逻辑审查。缓存结果对于一些分析类任务如codebase-analyzer的结果如果代码库没有重大变化可以考虑缓存分析结果避免重复计算。6. 常见问题、排查技巧与未来展望6.1 安装与配置问题问题1ship命令找不到或安装失败。排查确保 Go 环境已正确安装且GOPATH/bin已加入系统的 PATH 环境变量。可以尝试go version和echo $PATH来检查。解决如果网络问题导致安装失败可以尝试从 Shipwright 的 GitHub Releases 页面直接下载对应平台的可执行文件。问题2在 Cursor/Claude Code 中安装了 Agent但无法调用或没有反应。排查确认插件安装到了正确的目录。使用ship list --target cursor查看。检查 Agent 文件格式是否正确特别是 Frontmatter 的 YAML 部分。重启你的 IDE。有时 IDE 需要重启才能加载新的插件。解决查看 IDE 的控制台或日志文件通常会有加载插件失败的详细错误信息。问题3GitHub Actions 工作流运行失败提示认证错误。排查检查CLAUDE_CODE_OAUTH_TOKEN或CODEX_API_KEY这个 Secret 是否已在仓库中正确设置且没有过期。解决重新生成 Token/Key并更新 GitHub Secrets。确保工作流 YAML 中secrets部分的变量名拼写正确。6.2 Agent 输出质量问题问题4Agent 生成的代码不符合项目规范。原因project-context.md描述不够具体或者 Agent 没有加载到正确的、强相关的 Skills。解决细化你的上下文文件。不要只说“遵循 Go 规范”而要给出具体例子如“错误变量命名以Err开头”、“使用ctx作为上下文参数名”。为 Agent 附加更具体的技能如go-skills。在给 Agent 的指令中明确引用你项目中的一个规范文件或示例文件作为参考。问题5Agent 在处理复杂任务时“跑偏”或输出无关内容。原因指令Instructions不够清晰或者提供的上下文窗口过大导致 AI 注意力分散。解决将大任务拆解。不要一次性让implementer-agent实现整个模块。先让architect-agent输出设计再分多个步骤让implementer-agent实现各个部分。在指令中使用明确的约束和步骤。例如“第一步只修改UserService类中的createUser方法。第二步确保新代码通过所有现有测试。”使用引用其他文件来提供精确的上下文而不是粘贴大段代码到聊天框。6.3 高级技巧与最佳实践组合使用 Agents不要只用一个 Agent。典型的流程是triage-agent-architect-agent-implementer-agent-test-engineer-pr-reviewer。每个 Agent 各司其职形成流水线。善用 MCP 提供动态上下文在启动一个涉及第三方库的任务前先通过context7让 AI 查询最新文档。这能有效避免基于过时知识的错误。将 Agents 的输出作为迭代的起点AI 生成的代码、设计或文档很少是完美的。它们应该被视为一个高质量的“初稿”需要开发者进行审查、调整和优化。将其纳入你的工作流而不是完全替代你的工作。建立反馈循环如果某个 Agent 的输出持续不符合预期不要只是抱怨。去检查并优化它的instructions、引用的skills或你提供的project-context。这是一个持续调优的过程。从我近几个月的实践来看Shipwright 代表了一种更成熟的 AI 辅助开发范式。它不再是玩具式的聊天交互而是开始触及软件开发流程的核心——将知识、规范和最佳实践工具化、自动化。虽然目前它更偏向于与 Claude 系工具深度集成但其基于开放规范如 Agent Skills的设计理念让我们有理由期待一个更互通、更强大的 AI 开发工具生态的到来。对于积极拥抱 AI 的团队和个人来说现在投入时间学习和集成这样的工具正是在为未来更高阶的“人机协同”开发模式打下基础。