{
  "contractVersion": 1,
  "skillId": "tavern-project-contributing",
  "title": "参与开发与协作",
  "summary": "指导贡献者按当前仓库的分层边界、验证要求和 PR 规范参与 TavernHeadless 开发。",
  "status": "active",
  "audience": [
    "contributors",
    "api-developers",
    "web-developers",
    "sdk-maintainers",
    "docs-contributors"
  ],
  "recommendedWhen": [
    "准备第一次参与 TavernHeadless 开发时。",
    "需要判断改动应该落在哪一层时。",
    "需要同步处理官方包、文档和验证要求时。"
  ],
  "avoidWhen": [
    "只想接入 TavernHeadless，而不是参与仓库开发时。",
    "只需要查看具体协议字段和错误码时。",
    "只处理局部页面视觉和单页交互细节时。"
  ],
  "decisionRules": [
    {
      "title": "先判断改动属于哪一层",
      "rule": "开始实现前，先确认改动属于 core、api、web、shared，还是官方集成层，避免边界混乱。"
    },
    {
      "title": "公开接入面只通过两个官方包暴露",
      "rule": "新增公开接入能力时，不应落到 @tavern/shared，而应评估是否进入 @tavern/sdk 或 @tavern/client-helpers。"
    },
    {
      "title": "外部可见语义变化要联动官方包和文档",
      "rule": "只要后端语义、OpenAPI、SSE 或公开行为变化，就应在同一个 PR 中检查官方包和文档同步。"
    },
    {
      "title": "按改动范围选择最小但完整的验证",
      "rule": "代码 PR 至少执行 lint、typecheck 和相应测试；涉及 OpenAPI 或官方包生成面时，要补充 sdk:generate 和 sdk:check。"
    }
  ],
  "workflow": [
    {
      "step": 1,
      "title": "阅读当前协作规则",
      "action": "先阅读 README、协作指南、测试与 CI，以及必要时的文档规范，确认当前仓库规则。"
    },
    {
      "step": 2,
      "title": "判断改动边界",
      "action": "开始写代码前，先确认改动属于哪一层，并判断是否会影响 @tavern/sdk、@tavern/client-helpers 或公开文档。"
    },
    {
      "step": 3,
      "title": "必要时读取 Agent 更新面",
      "action": "如果是在跟进最近一次主干外部变更，先读取 /agent/latest.json 和 manifest，确认当前公开变化已经覆盖到哪些表面。",
      "relatedAgentFields": [
        "summary.domains",
        "summary.breaking",
        "changes",
        "surfaceSummaries.openapi",
        "surfaceSummaries.sdk",
        "surfaceSummaries.clientHelpers"
      ]
    },
    {
      "step": 4,
      "title": "同步更新文档和接入层",
      "action": "如果改动已经影响公开行为，应在同一个 PR 中同步更新官方包、文档和必要的示例。"
    },
    {
      "step": 5,
      "title": "完成本地验证和 PR 说明",
      "action": "按范围执行最小但完整的验证，并在 PR 中说明影响范围、验证方式，以及是否影响官方包和 OpenAPI。"
    }
  ],
  "checks": [
    {
      "command": "pnpm lint",
      "purpose": "通用代码 PR 的基础检查。"
    },
    {
      "command": "pnpm typecheck",
      "purpose": "验证整个仓库的类型一致性。"
    },
    {
      "command": "pnpm test:ci",
      "purpose": "在合并前复现 CI 常规测试路径。"
    },
    {
      "command": "pnpm sdk:generate && pnpm sdk:check",
      "purpose": "当改动影响 OpenAPI 或官方包生成面时，检查生成物是否仍然一致。"
    },
    {
      "command": "pnpm docs:build",
      "purpose": "当只改文档或公开入口说明时，确认文档站仍可构建。"
    }
  ],
  "relatedAgentFields": [
    "summary.domains",
    "summary.breaking",
    "changes",
    "surfaceSummaries.openapi",
    "surfaceSummaries.sdk",
    "surfaceSummaries.clientHelpers"
  ],
  "relatedDocs": [
    {
      "title": "Agent 与 Skill 总入口",
      "path": "/TavernHeadless/agent/"
    },
    {
      "title": "Skill 索引",
      "path": "/TavernHeadless/agent/skills/"
    },
    {
      "title": "协作指南",
      "path": "/TavernHeadless/development/contributing"
    },
    {
      "title": "测试与 CI",
      "path": "/TavernHeadless/development/testing"
    },
    {
      "title": "文档规范",
      "path": "/TavernHeadless/development/doc-standards"
    },
    {
      "title": "官方集成层",
      "path": "/TavernHeadless/guide/integration-kit"
    }
  ],
  "humanPage": "/TavernHeadless/agent/skills/tavern-project-contributing/",
  "json": "/TavernHeadless/agent/skills/tavern-project-contributing.json",
  "lastReviewedAt": "2026-05-13T16:24:09.115Z"
}