convention.sh

什么是 convention.sh？

convention.sh 是一个托管工具包，用于指导编码代理生成更一致、可用于生产的 TypeScript。它提供了一个手工调优的 TypeScript 约定库，代理可按需获取，而非依赖静态的、受提示大小限制的规则集。

核心目的是通过提供具体约定（如更严格的类型模式和运行时验证方法）来减少粗糙的 TypeScript 输出，这些约定通过标准接口交付。

主要特性

• 托管 MCP 约定服务器：convention.sh 作为托管的模型上下文协议 (MCP) 服务器运行，代理可查询所需的约定片段。
• 按需片段检索（27 个约定）：代理无需在每个提示中嵌入规则墙，而是在需要时从 27 个约定的库中拉取相关片段。
• 针对 TypeScript 正确性的约定：列出的约定强调严格类型（避免 any）、使用 Zod 验证不受信任输入，并优先使用判别联合而非可选字段。
• 通过 MCP 集成模型上下文：通过将 MCP 端点添加到代理配置，即可与任何支持标准模型上下文协议的代理配合使用。
• 无需重新部署即可保持最新：约定从托管 MCP 端点提供，后续请求会自动获取变更，无需重写提示或重新部署应用。

如何使用 convention.sh

1. 在代理中添加 MCP 端点，使用提供的终端命令注册托管端点：claude mcp add conventiondotsh --transport http https://mcp.convention.sh。
2. 在编码代理中启动常规 TypeScript 任务。
3. 让代理按需请求约定：在任务期间，代理会向 convention.sh 服务器请求所需的特定约定片段。

如果使用示例中所示的不同 MCP 兼容代理，请配置其调用 convention.sh 描述的相同托管 MCP 端点。

使用场景

• 使用一致风格重构 TypeScript 模块：生成或更新 TypeScript 代码时，请求约定以应用相同的类型和输入验证模式。
• 在 API 处理程序中验证不受信任输入：使用推荐 Zod 验证的约定，保持输入检查明确且一致。
• 避免可选字段歧义：设计数据形状时，优先使用判别联合而非可选字段，使生成代码中的变体处理更清晰。
• 减少长时编码会话的提示冗余：通过代理仅在需要时拉取特定约定片段，保持代理提示专注。
• 团队标准化代理输出：从共享托管端点提供相同约定片段，确保应用 MCP 集成的代理跨机器保持一致（更新将在下次请求中获取）。

常见问题

• 这里的“按需”是什么意思？ 约定通过托管 MCP 服务器交付，代理在任务期间仅从 27 个约定的库中请求所需片段，而非每次接收完整规则集。

• 我需要自己构建或托管吗？ 网站将 convention.sh 描述为托管 MCP 服务器，因此您只需将端点添加到代理，而非自行托管约定库。

• 如何与我的编码代理集成？ 使用 MCP 集成流程：配置 MCP 兼容代理使用托管端点 https://mcp.convention.sh。页面包含添加 MCP 服务器的示例命令。

• 包含哪些 TypeScript 规则？ 页面列出示例约定，聚焦严格类型（无 any）、使用 Zod 验证不受信任输入，以及优先判别联合而非可选字段。

• 约定变更时需要更新提示吗？ 不需要——约定从托管 MCP 端点提供，代理将在下次请求中获取新规则，而非需要重新部署或跨机器使用过时副本。

替代方案

• 静态提示规则列表或维基：您可以将 TypeScript 指南直接包含在每个提示中，但这往往会增加提示体积，并且仍可能导致应用不一致。
• 本地 linting/格式化工具链（例如 TypeScript ESLint）：这些工具有助于强制执行风格并事后捕获问题，而 convention.sh 通过 MCP 在代码生成期间提供约定。
• 其他基于检索的代理上下文工具：如果您已经使用 RAG 或基于工具的上下文获取进行编码，您可以构建类似的“按需获取约定”工作流，不过这需要您自己维护约定库和检索逻辑。