PenEcho 开源贡献指南：如何快速跑通完整检查体系并提交你的第一个 PR

PenEcho 开源贡献指南如何快速跑通完整检查体系并提交你的第一个 PR【免费下载链接】penechoThink with AI beyond the chat box. A shared canvas for handwriting, equations, diagrams, and spatial reasoning.项目地址: https://gitcode.com/gh_mirrors/pe/penechoPenEcho 是一个开源 AI 画布应用支持手写、公式、专业图表与空间推理本指南将带你从零跑通它的完整检查体系顺利提交第一个开源贡献 PR。你只需 Node.js 和约 10 分钟就能在本地启动 PenEcho 开发环境、执行官方推荐的npm run check全量检查并写出一份维护者愿意合入的 Pull Request。为什么选择 PenEcho 作为你的第一个开源项目 PenEcho 用一句话概括在画布上手写或草图AI 会把它变成可编辑的图表、文档和可运行的组件。整个项目是标准的 Node.js 架构——浏览器端静态客户端 服务端验证与模型调度没有复杂构建链非常适合作为新手的第一次开源贡献。PenEcho 的整体架构浏览器访问本地 CLI 或 AppAI Agent 可通过 Local MCP / Cloud MCP 接入架构图源文件项目文档维护得相当完善贡献前建议浏览 docs/architecture.md 了解渲染与 AI 请求流程规则速查见 CONTRIBUTING.md。一键搭建 PenEcho 开发环境最快配置方法贡献前先确保本地能正常跑起来。完整步骤来自官方 CONTRIBUTING.md安装 Node.js 22.19 或更高版本package.json 中engines声明为22.19.0npm install时会自动校验版本。克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/pe/penecho cd penecho npm install npm link运行配置向导penecho configure选择 API、Codex CLI 或 Claude CLI 作为 AI 后端Codex / Claude 模式需要先完成各自 CLI 的登录。启动并验证运行penecho打开http://localhost:3888看到画布即表示环境就绪。小技巧开发默认使用全局~/.penecho/config.env配置。如果你想与已安装的正式版本完全隔离可以用独立配置penecho configure --config ./local.env penecho --config ./local.env认识代码结构你的第一处修改改在哪里PenEcho 的目录分工很清晰贡献前花两分钟认路能少走很多弯路目录职责常见贡献点src/client/app/浏览器端交互运行时画布、导航、AI 运行时、MCPUI 逻辑、交互修复src/server/服务端验证、模型调度、Canvas Agent请求校验、协议src/providers/API / Codex CLI / Claude CLI 等模型提供方适配新增 AI 后端public/静态资源与入口注意public/app.js是生成产物样式、多语言test/2000 个测试用例文件名与模块一一对应回归测试docs/架构、MCP、测试报告等文档文档完善⚠️ 一个关键细节public/app.js不是手写文件它由src/client/app/下的有序源码通过npm run build:client打包生成test/project-structure.test.js 会校验生成结果与源码严格一致。所以修改客户端逻辑后务必重新构建而不是直接编辑生成文件。提交 PR 前需要像发布流程一样并行完成回归测试、安全检查与文档更新图表源文件跑通完整检查体系核心命令 npm run check这是 PenEcho 贡献流程的心脏。官方要求每个 PR 提交前都必须通过npm run check这一条命令背后是三层防线定义见 package.json构建一致性检查check:client、check:architecture、check:sequence、check:workflow等确保public/app.js等生成文件与src/源码完全同步语法检查对 CLI、服务端、桌面端等几十个关键入口逐个执行node --check全量测试套件node --test运行 test/ 下 2000 个用例——官方 1.3.5 版本发布验证时全量结果为2,188 通过、0 失败见 docs/verification/release-1.3.5-2026-09-26.md。提交前建议再补一条空白检查git diff --checkPenEcho 的测试大量覆盖 MCP 请求、画布操作等真实链路时序图源文件修复类贡献的黄金实践先写一个能在修改前失败、修改后通过的回归测试。官方 docs/verification/p1-pr-2026-09-26/README.md 记录了一次真实整合基线上 36 个测试 19 个失败五个修复合入后38 通过、0 失败每个 PR 都保留了修改前失败 / 修改后通过的完整证据链。这正是新手可以模仿的高分作业方式。面向浏览器的改动手工回归清单 ✅如果你的修改涉及界面或交互官方要求手工验证以下场景摘自 CONTRIBUTING.md桌面端与移动端两种布局触控笔 / 鼠标书写与触摸导航Manual / Auto AI 延迟控制AI 草稿确认Draft Confirmation新建画布的各选项分支本地快照的保存与恢复发布验证中的画布截图AI 生成结果需要人工确认渲染与交互正常截图源文件编写 Pull Request描述模板与授权说明 官方对 PR 的描述要求四要素见 CONTRIBUTING.md 的 Pull Requests 一节用户可见行为改动对用户意味着什么实现思路方案与关键取舍验证情况跑了哪些命令、结果如何已知局限诚实地列出。同时请注意两条红线不要提交含凭据的配置文件、日志、浏览器测试输出或本地 Agent 状态遵循 工程准则保留稀疏瓦片架构不要为 20,000×20,000 画布分配完整位图、英文为默认界面语言、用户可见中文文案统一走多语言表 public/locales/zh.js。最后PenEcho 采用AGPL-3.0-only许可并可能按商业条款分发因此每个可版权贡献都受 CONTRIBUTOR-LICENSE-AGREEMENT.md 约束你保留所有权授予项目方非独占许可。勾选贡献者协议复选框即表示接受若代码属于雇主或第三方请先取得授权。常见问题快速排查 npm install报版本错误Node 低于 22.19preinstall钩子会拦截安装升级 Node 即可。改了src/client/app/但check:client失败忘记执行npm run build:client重新生成public/app.js。只跑部分测试更快node --test test/文件名.test.js例如node --test test/widget-patch.test.js。本地跑不起来 AI先单独验证penecho configure选择的后端是否已登录/配好 Key再排查代码改动。按照跑起来 → 小步改 →npm run check全绿 → 写清四要素的节奏你的第一个 PR 就能以维护者最期待的样子出现。祝贡献顺利 【免费下载链接】penechoThink with AI beyond the chat box. A shared canvas for handwriting, equations, diagrams, and spatial reasoning.项目地址: https://gitcode.com/gh_mirrors/pe/penecho创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考