PicoClaw 贡献指南：从开发环境搭建到 AI 辅助代码合入的完整工作流

PicoClaw 贡献指南：从开发环境搭建到 AI 辅助代码合入的完整工作流

【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw

PicoClaw 是一款追求"小巧、快速、随处可部署"的轻量级个人 AI 助手，其架构与代码大量借助 AI 辅助完成，也因此形成了一套独特的、围绕 AI 协作设计的开源贡献流程。本文以仓库根目录的 CONTRIBUTING.md 为骨架，结合 Makefile、go.mod、.github/workflows/pr.yml 等仓库实况，完整还原贡献者从搭建开发环境、编写代码、提交 PR 到通过代码审查的每一步：你将掌握make check等核心命令的用法、AI 辅助贡献的披露分级与安全审查要点、main与release/x.y的分支管理规则，以及一套可直接照做的 PR 提交清单。

为什么需要一份"AI 原生"的贡献指南

PicoClaw 是一个社区驱动的项目，欢迎 bug 修复、新功能、文档、翻译与测试等各类贡献。它与多数开源项目的不同之处在于：项目本身主要由 AI 辅助开发而成，因此贡献流程也围绕 AI 协作设计。这不是"禁止使用 AI"，而是要求贡献者在使用 AI 工具时承担明确责任——每份 PR 都必须披露 AI 参与程度，且 AI 生成的代码要经过与人类代码同等甚至更严格的审查。

从仓库结构可以看到，这是一个由 Go 编写的单体应用，go.mod 声明模块为github.com/sipeed/picoclaw，Go 版本要求 1.25.12；代码分布覆盖pkg/agent（Agent 核心）、pkg/channels（20+ 聊天渠道接入）、pkg/providers（多家 LLM 供应商）与pkg/tools（工具调用）等模块。理解了这一点，再进入贡献流程会更容易把握"哪类改动应该落在哪个包"。

参与方式：不止写代码

贡献不必始于代码。按 CONTRIBUTING.md 的划分，有以下五类参与途径：

• Bug 报告：使用 bug 模板（见 .github/ISSUE_TEMPLATE/bug_report.md）提交 issue，模板要求填写 PicoClaw 版本、Go 版本、AI 模型与 Provider、操作系统、渠道，以及复现步骤；
• 功能请求：使用 feature 模板（见 .github/ISSUE_TEMPLATE/feature_request.md），且强调"先讨论再实现"；
• 代码：修复 bug 或实现功能，遵循下文的工作流；
• 文档：改进 README、指南、内联注释或翻译；
• 测试：在新硬件、新渠道或新 LLM Provider 上实际运行 PicoClaw 并回报结果。

对于较大的新功能，请先开 issue 讨论设计再写代码，避免返工。文档类贡献则要求遵循 docs/README.md 约定的目录布局与命名规范，并在新增或移动 Markdown 文件后运行make lint-docs。

开发环境搭建与构建

前置条件

• Go 1.25 或更高版本：与 go.mod 中go 1.25.12的声明一致；
• make：项目所有构建、测试、质量检查都通过 Makefile 目标编排。

构建与检查命令

Makefile 中的核心目标是：

make build # 构建二进制（会先执行 go generate） make generate # 仅运行 go generate make check # 提交前完整检查：deps + fmt + vet + test + 文档一致性检查

make check在 Makefile 中定义为check: deps fmt vet test lint-docs，即一次覆盖依赖下载、代码格式化、静态分析、全部单测和文档规范检查。CI 中对应的则是 .github/workflows/pr.yml 里的四个 job：Linter（golangci-lint，build tags 为goolm,stdjson）、Security Check（govulncheck漏洞扫描）、Tests（go test -tags goolm,stdjson ./...）与 Integration Tests（Docker 集成套件）。

make build会调用go generate ./...，这一步会重建cmd/picoclaw/workspace下的内嵌工作区内容；构建产物输出到build/目录，命名形如picoclaw-linux-amd64。项目还针对树莓派（build-pi-zero）、Android（build-android-bundle）、龙芯（loong64）、RISC-V、MIPS 等平台提供了专门的构建目标，其中 MIPS 目标还会对 ELF 头做 e_flags 修补（PATCH_MIPS_FLAGS），以兼容仅支持 NaN2008 编码的旧内核。

运行测试

make test # 运行全部测试 make integration-test # 运行 Docker 支撑的集成测试套件 go test -run TestName -v ./pkg/session/ # 运行单个测试 go test -bench=. -benchmem -run='^$' ./... # 运行基准测试

Docker 支撑的集成测试套件从integration/suites/自动发现，布局与约定详见 integration/README.md。make integration-test实际执行 scripts/run-integration-tests.sh：该脚本自动枚举integration/suites/<name>/下每个套件，要求每个套件目录必须包含suite.env（至少定义TEST_COMMAND）和至少一个docker-compose*.yml；脚本会合并共享的 integration/docker-compose.runner.yml、启动依赖服务、以GOFLAGS=-tags=goolm,stdjson,integration的运行容器执行测试命令，最后自动清理。参考实现是integration/suites/mcp-streamable/，它启动一个真实的 MCP fixture 服务器（见 integration/fixtures/mcp-streamable-server）并验证 PicoClaw 的 MCP 客户端能完成建连、工具发现与调用。

代码风格

make fmt # 格式化代码 make vet # 静态分析（go vet，排除 web/ 子模块） make lint # 完整 linter 运行（golangci-lint + lint-docs） make lint-docs # 检查常见文档布局与命名约定

所有 CI 检查必须通过后 PR 才能合并。提交前先在本机运行make check是发现早期问题最直接的方式。

文档贡献与 docs 布局规范

文档类贡献不是"随便放个 Markdown 就行"。项目在 docs/README.md 中定义了严格的文档组织规则：

• 按文档类型目录组织，再按语言区分，例如docs/guides/（使用指南）、docs/reference/（参考）、docs/operations/（调试排障）、docs/security/（安全）、docs/architecture/（架构设计）、docs/channels/（渠道接入）、docs/migration/（迁移）；
• 英文文档使用基础文件名（如configuration.md），翻译使用小写 locale 后缀放在英文原文旁边（如configuration.zh.md、README.pt-br.md）；
• 仓库根级不允许出现翻译版入口文档（如README.zh.md），应放入docs/project/；
• 模块专属文档应紧邻代码存放（如pkg/**/README.md、cmd/**/README.md、web/README.md）。

这些规则由 scripts/lint-docs.sh 落地为可执行的检查：它通过git ls-files枚举所有 Markdown，逐一校验是否存在根级翻译入口、docs/<locale>/语言桶、嵌套 locale 目录、README_zh.md这类遗留命名、非规范的.ZH.md后缀，以及"翻译文件缺少英文源文档"等问题，失败时打印路径、原因与修复建议。所以文档贡献者的最低门槛就是：新增或移动文档后运行一次make lint-docs。

提交变更的工作流

分支与提交

所有变更都必须从main拉分支，PR 也以main为目标，绝不直接向main或任何release/*分支推送：

git checkout main git pull upstream main git checkout -b your-feature-branch

分支名要能自解释，例如fix/telegram-timeout、feat/ollama-provider、docs/contributing-guide。提交规范包括：

• 使用清晰、简洁的英文提交信息，采用祈使语气："Add retry logic" 而不是 "Added retry logic"；
• 关联相关 issue，如Fix session leak (#123)；
• 保持提交聚焦，一个逻辑变更一个提交；小修补或拼写错误在开 PR 前 squash 成一个提交；
• 遵循 Conventional Commits 约定（如feat:、fix:、docs:前缀）。

保持与上游同步

开 PR 前先将分支 rebase 到上游main：

git fetch upstream git rebase upstream/main

AI 辅助贡献规范：本项目的特色制度

PicoClaw 是少见的把"AI 参与开发"明文写进贡献制度的项目。核心原则是：欢迎 AI，但人类必须对提交的内容负责。

披露是强制的

每个 PR 都必须通过 .github/pull_request_template.md 中的🤖 AI Code Generation部分披露 AI 参与程度，共三个等级：

诚实披露是预期行为，任何等级都不会被贴上标签——最终评判标准是贡献质量本身。

你对提交的内容负责

用 AI 生成代码并不会降低贡献者的责任。提交含 AI 代码的 PR 前，必须：

• 逐行阅读并理解生成的代码；
• 在真实环境中测试（对应 PR 模板的 Test Environment 部分）；
• 检查安全问题——AI 模型可能生成隐蔽的不安全代码（路径遍历、注入、凭据泄露等），需仔细审查；
• 验证正确性——AI 生成的逻辑可能"听起来合理但实际错误"，要验证行为而非仅看语法。

CONTRIBUTING.md 明确：凡明显能看出贡献者没有阅读或测试 AI 生成代码的 PR，将不经审查直接关闭。

AI 生成代码的质量标准

AI 贡献与人类代码适用同一质量门槛：

• 必须通过全部 CI 检查（make check）；
• 必须是惯用的 Go 写法，与现有代码风格一致；
• 不得引入不必要的抽象、死代码或过度工程；
• 必须包含或更新相应测试。

安全审查重点

AI 生成代码需要额外的安全审查，CONTRIBUTING.md 特别点名了四类高风险点（并以 commit244eb0b的沙箱逃逸修复为真实案例）：

• 文件路径处理与沙箱逃逸：pkg/tools/fs、pkg/isolation等模块涉及路径与进程隔离；
• 渠道处理器与工具实现的外部输入校验：pkg/channels/下 20+ 渠道会接收不可信的外部消息；
• 凭据与密钥处理：pkg/credential、pkg/auth涉及令牌存储与加密；
• 命令执行：exec.Command、shell 调用（如pkg/tools/shell.go、pkg/tools/spawn.go）。

拿不准某段 AI 代码是否安全时，直接在 PR 里说明，审查者会协助判断。

Pull Request 流程

提交前清单

• 本机运行make check并通过；
• 完整填写 PR 模板，包括 AI 披露部分；
• 在 PR 描述中关联相关 issue；
• 保持 PR 聚焦，不要把无关改动捆绑在一起。

PR 模板的组成部分

.github/pull_request_template.md 要求填写以下内容：

• Description：这个变更做了什么、为什么；
• Type of Change：Bug fix / New feature / Documentation update / Code refactoring；
• AI Code Generation：AI 参与披露（必填）；
• Related Issue：关联 issue；
• Technical Context：参考资料 URL 与设计理由（纯文档 PR 可跳过）；
• Test Environment：测试所用硬件、OS、模型/Provider 与渠道；
• Evidence（可选）：证明变更生效的日志或截图；
• Checklist：自审确认。

PR 规模

偏好小且易于审查的 PR：改动 200 行、涉及 5 个文件的 PR，远胜改动 2000 行、涉及 30 个文件的 PR。大功能应拆分成一系列逻辑完整的小 PR 依次提交。

分支策略与合并规则

长期分支

• main：活跃开发分支，所有功能 PR 都以它为目标。分支受保护：不允许直接推送，合并前至少需要一位维护者批准；
• release/x.y：从main切出的稳定发布分支，保护比main更严格。

合并到main的必要条件

1. CI 通过：全部 GitHub Actions 工作流（lint、test、build）保持绿色；
2. 审查者批准：至少一位维护者批准；
3. 无未解决的审查意见：所有 review 线程均已解决；
4. PR 模板填写完整：包括 AI 披露与测试环境。

谁能合并

只有维护者可以合并 PR。贡献者即使有写权限也不能合并自己的 PR。

合并策略

大多数 PR 使用squash merge，保证main历史干净可读——每个合并的 PR 变成引用 PR 编号的单个提交，例如：

feat: Add Ollama provider support (#491)

如果某个 PR 由多个相互独立、故事清晰的提交组成，维护者也可酌情使用普通合并。

发布分支的维护

版本就绪时，维护者从main切出release/x.y分支。之后：

• 新功能不回移植：发布分支不再接收新功能；
• 安全修复与关键 bug 修复会 cherry-pick：如果main中的修复属于安全漏洞、数据丢失或崩溃级别，维护者会把相关提交 cherry-pick 到受影响的release/x.y分支并发布补丁版本。

如果你认为main中的某个修复应该回移植到发布分支，请在 PR 描述中注明或另开 issue，由维护者决定。发布分支在任何情况下都禁止直接推送。

代码审查：贡献者与审查者的双向约定

给贡献者

• 在合理时间内回应审查意见；需要更多时间就明说；
• 更新 PR 回应反馈时，简要说明改了什么（例如"按建议改为使用sync.RWMutex"）；
• 不认同反馈时要有礼有节地说明理由——审查者也可能出错；
• 审查开始后不要 force-push，这会让审查者难以追踪变更；改为追加提交，合并时维护者会 squash。

给审查者

审查时关注五个维度：

1. 正确性：代码是否达成声称的行为？边界情况是否覆盖？
2. 安全性：尤其针对 AI 生成代码、工具实现与渠道处理器；
3. 架构：实现方式是否与现有设计一致；
4. 简洁性：是否存在更简单的方案？是否引入了不必要的复杂度？
5. 测试：变更是否被测试覆盖？既有测试是否仍然有意义？

反馈要具体可操作："如果两个 goroutine 并发调用这里可能产生竞态——建议使用互斥锁"，而不是笼统的"这看起来不对"。

模块审查人列表

PR 提交后可按模块联系对应审查人（来自 CONTRIBUTING.md 的 Reviewer 表）：

Skill、MCP、Security、UX、Document 等模块的审查人待定，提交相关 PR 时可主动在评论中说明。

社区沟通渠道

• GitHub Issues：bug 报告、功能请求、设计讨论；
• GitHub Discussions：通用问题、想法与社区交流；
• Pull Request 评论：针对具体代码的反馈；
• 微信与 Discord：至少合并一个 PR 后会邀请加入。

拿不准时就先开 issue 再写代码——成本极低，却能避免大量返工。

结语：对项目 AI 起源的一则说明

CONTRIBUTING.md 的最后特别提醒：PicoClaw 的架构在很大程度上是由 AI 辅助设计并实现、人类监督把关的。因此，如果你发现某些代码看起来奇怪或过度工程，那可能是这一过程的产物——欢迎开 issue 讨论。项目相信负责任的 AI 辅助开发能产出优秀结果，也坚持"人类必须对自己发布的内容负责"，这两者并不冲突。

这正是 PicoClaw 贡献文化的内核：AI 提速，人来把关。无论你提交的是第一行 Go 代码、一篇翻译，还是一次在新硬件上的真机测试报告，只要遵循本文的流程——本地make check通过、如实填写 PR 模板、诚实披露 AI 参与、认真回应审查——你的贡献都会被认真对待。

【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw