贡献指南

感谢您有兴趣为 InnoClaw 做出贡献！本指南介绍如何参与。

快速入门

  1. 在 GitHub 上 Fork 仓库

  2. 在本地克隆您的 Fork：

    git clone https://github.com/your-username/InnoClaw.git
cd InnoClaw

  3. 安装依赖：

    npm install

  4. 阅读仓库级指南 仓库规范

  5. 按照安装指南搭建开发环境

推荐继续阅读：

该看哪份指南

  • 将 仓库规范 作为本仓库本地工作流、验证流程与文档联动更新的统一权威来源。

  • 当工作树已经是脏状态、需要与多位贡献者协作，或有自动化工具参与编辑时，请阅读 协作规范。

  • 在修改 prompts、tools、智能体流式输出、deep-research 角色，或其他面向智能体的契约之前，请阅读 智能体开发。

贡献流程

        flowchart LR
    Start["Start contribution"] --> Branch["Create a focused branch"]
    Branch --> Scope{"Touches shared contracts?"}
    Scope -- "Yes" --> ReadDocs["Read AGENTS.md and matching docs/development pages"]
    Scope -- "No" --> Implement["Implement the change"]
    ReadDocs --> Implement
    Implement --> Docs{"Contributor-facing behavior changed?"}
    Docs -- "Yes" --> UpdateDocs["Update docs and related examples"]
    Docs -- "No" --> Validate["Run lint, test, and build"]
    UpdateDocs --> Validate
    Validate --> Ready{"Checks passed?"}
    Ready -- "No" --> Fix["Fix code, tests, or docs"]
    Fix --> Validate
    Ready -- "Yes" --> PR["Open PR with summary, validation, and contract notes"]
    
        flowchart LR
    Start["开始贡献"] --> Branch["创建聚焦分支"]
    Branch --> Scope{"是否涉及共享契约?"}
    Scope -- "是" --> ReadDocs["阅读 AGENTS.md 与对应 docs/development 页面"]
    Scope -- "否" --> Implement["实现变更"]
    ReadDocs --> Implement
    Implement --> Docs{"面向贡献者的行为是否变更?"}
    Docs -- "是" --> UpdateDocs["更新文档与相关示例"]
    Docs -- "否" --> Validate["运行 lint、test 与 build"]
    UpdateDocs --> Validate
    Validate --> Ready{"检查是否通过?"}
    Ready -- "否" --> Fix["修复代码、测试或文档"]
    Fix --> Validate
    Ready -- "是" --> PR["提交 PR，并附摘要、验证与契约说明"]

大多数变更都可以按这个流程推进：

  1. 从一个聚焦的分支开始。

  2. 尽早识别这次变更是否触及 schema、环境变量、路由返回形状或智能体能力等共享契约。

  3. 当面向贡献者的行为发生变化时，在同一个变更中同步更新文档。

  4. 只有在本地验证通过之后再请求评审。

分支策略

  • main —— 稳定的生产分支

  • 功能分支 —— 从 main 创建，用于新功能或错误修复

分支命名规范

feature/short-description
fix/issue-number-description
docs/what-is-changing

提交规范

我们遵循 Conventional Commits 规范：

<type>(<scope>): <short description>

[optional body]

提交类型

类型

描述

feat

新功能

fix

错误修复

docs

文档变更

style

代码风格变更（格式化，无逻辑变更）

refactor

代码重构（无新功能或修复）

test

添加或更新测试

chore

构建流程或辅助工具变更

示例

feat(chat): add streaming response indicator
fix(files): handle special characters in filenames
docs(api): update endpoint documentation

Pull Request 流程

  1. 从 main 创建分支，使用描述性名称

  2. 进行更改并使用规范的提交消息进行提交

  3. 提交之前运行检查：

    npm run lint
npm test
NEXT_TELEMETRY_DISABLED=1 npm run build

  4. 推送您的分支并打开 Pull Request

  5. 在 PR 描述中清楚地描述您的更改

  6. 等待审核 —— 维护者将审查您的代码

如果您的变更更新了贡献者工作流、环境配置或面向开发者的行为，请在同一个 PR 中同步更新 docs/development/ 下对应的页面。

如果您的变更更新了智能体或 deep-research 行为，请确认工具名称、权限边界、会话持久化与贡献者文档保持一致。

PR 检查清单

  • 代码遵循项目的编码风格

  • 测试通过（npm test）

  • Lint 通过（npm run lint）

  • 构建成功（NEXT_TELEMETRY_DISABLED=1 npm run build）

  • 文档已更新（如适用）

行为准则

请在所有互动中保持尊重和建设性。我们致力于创建一个友好和包容的社区。

报告问题

  • 使用 GitHub Issues 报告错误或提出功能请求

  • 包含清晰的错误复现步骤

  • 提供环境详情（操作系统、Node.js 版本、浏览器）