tldraw 仓库 Pull Request 创建与更新完整工作流从分支准备到评审提交pr / write-pr 技能指南【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw导读本文基于 tldraw 开源仓库skills/目录下维护的pr与write-pr两套 Agent 技能系统讲解在该仓库中创建、更新 Pull Request 的标准工作流以及 PR 标题、描述、录制素材、变更统计等内容规范。读完本文你将掌握一套从收集上下文、规避重叠工作、分支准备、自审提交到创建 PR、按规范撰写描述、录制 Before/After 视频、保留人工笔记的端到端实操流程并理解每一条规范背后的仓库源码级依据提交钩子、脚本工具、评审约定。该工作流面向的是 tldraw 的 monorepo 结构Yarn workspacespackages/为 SDK 源码、apps/为应用与示例任何向该仓库提交代码的开发者或 Agent 都可以直接套用。两套技能的分工pr与write-prskills/pr/SKILL.md 是用户面向的工作流入口当用户发起pr、要求创建/更新 PR、推送当前分支供评审或准备 PR 时触发。它定义了做什么的步骤顺序。skills/write-pr/SKILL.md 是内容标准参考定义 PR 标题、描述、release notes、API 变更、代码变更表、人工笔记保留等写成什么样的规范并附带前置的注释清扫comment sweep。它不作为用户直接调用的工作流而是被pr等技能引用的支持性标准。pr技能在第一步即声明以write-pr为标准来源涉及标题、描述、release notes、API 变更、代码变更表与人工笔记保留时一律以其为准。一、PR 工作流的九个步骤pr技能将整个流程收敛为九个步骤每一步都对应具体的 git/gh 命令下面逐一展开。1. 收集上下文进入任何操作之前先通过四条命令摸清当前状态git branch --show-current # 当前分支 git status --short # 工作树状态 gh pr view --json number,title,url 2/dev/null # 是否已有对应 PR git log main..HEAD --oneline 2/dev/null || git log -3 --oneline # 本分支相对 main 的提交git log main..HEAD用区间语法列出当前分支领先于main的提交若main分支不存在或比较失败2/dev/null吞掉报错则回退到最近 3 条提交作为风格参考。这四条命令同时服务于后续的是否存在 PR分支基于什么提交风格如何三个判断。2. 检查重叠工作避免踩到队友的脚仓库鼓励先看有没有人正在做同一块区域的工作再决定是否动手# 列出所有开放 PR含作者、分支名与更新时间 gh pr list --state open --json number,title,url,author,headRefName,updatedAt # 按关键词搜索相关开放 PR gh pr list --search keywords --state open # 对比对方 PR 改动的文件判断是否真的重叠而非只是文件名相同 gh pr diff number --stat技能给出了明确的协作优先级如果已经有人为此开了 PR优先在对方的工作上构建——可以是把自己的分支基于对方分支、贡献一条评审意见或后续提交或者把改动交接过去。只有当实现路径真正分叉时才允许开一个竞争性 PR且必须在描述里链接对方的 PR 并说明差异让评审者容易做出选择。一个值得注意的细节技能要求用gh pr diff number --stat对比实际改动的文件来判断重叠而不是只看是否共享文件名——因为共享文件名可能只是碰巧真实重叠应以改动集为准。若发现有意义的重叠需要在继续之前把发现呈现给用户。3. 准备分支若当前在main上先创建一个描述性名称的新分支提交相关改动排除密钥和明确属于私有的内容推送分支到远程。任何情况下不得 force push详见处理问题一节的钩子约束。4. 在请人工评审之前先做一轮初始评审这是本工作流最有特色的环节在 diffgit diff main...HEAD上并行派出若干子代理subagents每个聚焦一个视角然后把发现收敛为具体修复。技能列出的四个评审视角端到端解决问题改动是否真正解决了所述问题而不是掩盖症状让代码库变得更好命名是否清晰、有无死代码或重复代码、有无顺带引入的回归drive-by regressions抽象是否得当有无评审者会标记的怪异抽象、过早泛化或不必要的代码优先选择更小、更直接的版本。注释清扫扫描 diff 新增的注释执行write-pr中的 The comment sweep 一节详见后文。在更新已有 PR 时这一步能捕获分支自 PR 打开以来新增的注释——在长寿分支上这往往占了新增注释的大头。修复明显值得修的问题让人工评审从一个强健的 diff 开始若某个发现需要产品或设计决策去问用户而不是猜。本轮修复要提交并推送确保远程分支在 PR 创建/更新/分享之前与本地一致。同样绝不 force push。5~7. 创建、读取与更新 PR# 不存在 PR创建 gh pr create # 存在 PR读取标题、正文、标签、编号并查看改动文件摘要 gh pr view --json title,body,labels,number gh pr diff --stat # 若现有 PR 与当前 diff 或 write-pr 标准不符更新标题/正文 gh pr edit更新 PR 时技能要求先完整读取现有 PR 的title、body、labels、number并检查改动文件摘要再决定是否需要用gh pr edit修正标题或正文——不能盲目覆盖。特别地若正文顶部存在人工笔记human note必须按write-pr的规则逐字节保留详见下文。8. 关联相关 issue搜索相关 issue并在 PR 描述中用Closes #123或Relates to #123链接。关联的关键词决定了 issue 是否会被自动关闭Closes会在 PR 合并时关闭 issueRelates to只建立关联不关闭。9. 分享 PR 链接将 PR URL 交给用户流程结束。二、提交钩子与问题处理pr技能明确指出提交会自动运行钩子hooks。tldraw 仓库根目录的 AGENTS.md 也印证了这一点——它要求使用 Yarn 4 workspaces、yarn lint、yarn typecheck、yarn api-check等命令作为质量闸门而提交钩子正是这些检查的自动化载体。处理原则分两种情况机械性修复格式化、lint、类型或导入问题直接修复即可需要决策的失败如果钩子失败暴露出有意义的产品或实现决策问题停下并询问用户如何处理硬性红线绝不 force commit、绝不 force push。这条机械问题自己修、决策问题问用户的边界与第四步初始评审中产品/设计决策找用户的原则一脉相承。三、PR 内容标准为评审者写作skills/write-pr/SKILL.md 的全部内容围绕一条最高法则展开其余所有规则都服务于它面向一个了解代码库架构、但没读过你的代码和 diff的评审者写作。评审者的时间是最稀缺的资源描述的工作是给他们代码里读不到的框架信息然后让开。默认要短倒金字塔结构默认从短开始几句话的框架是常态而非例外。描述长度匹配改动规模——一行修复配一句话新系统才配完整论述。一份看起来又长又结构化的描述并不更有价值往往是反的它把框架埋在脚手架下面。如果评审者还需要自己的 AI 来解读你的描述它就失败了。由粗到细排列描述按倒金字塔组织最重要的在最前面。读者可以在任何一点停下来都能带着正确、自洽的理解离开扫读者从开头几句得到目标与动机评估方案的人往下读到设计与决策严格评审者继续看到具体细节。绝不能让读者读到最后才知道这个 PR 是干什么的。覆盖层次大致按此顺序每层比前一层更细改动不再需要时每层都可省略目标、动机与用例——为什么改、为什么现在改、为谁服务之前缺什么或错什么。永远放在最前。更上层的变更——解决方案的形态行为与结构而不是对 diff 的逐行复述。API 设计与决策——新增或变更的公开面、你选定的方案、排除的方案及原因、你不确定的地方。你不提出的决策评审者就无法捕捉到。示例片段与细节——凡是涉及 API、数据形态或用法模式的改动几行 before/after 胜过一段文字保持最小化。禁止事项不要复述 diff不做逐文件走查、不叙述某个函数做什么、不逐步描述代码如何工作——评审者自己能读代码。不要生成镜像代码的表格或列表比如Method | Description表只是重述签名、列出每个改动文件的清单、为不言自明的名字做术语表。不要用仪式感填充为了显得全面而存在的结构就是噪音。永不虚构为什么动机与取舍必须来自真实意图——提交记录、关联的 issue、或作者本人。如果不知道某个改动为什么发生或考虑了哪些方案问用户不要猜。一个自信但虚构的理由比没有更糟它具有误导性而它恰恰是评审者最需要信任的东西。四、PR 标题语义化提交格式PR 标题使用 Conventional Commits 语义化格式type(scope): description类型type类型含义feat新功能fix缺陷修复docs仅文档refactor既不修 bug 也不加功能的代码变更perf性能改进test新增或修复测试chore维护性任务作用域scope可选用名词描述受影响区域fix(editor):、feat(sync):、docs(examples):。从仓库结构看这些作用域名称与 monorepo 内的包/应用名对应如packages/editor、packages/sync、apps/examples。示例feat(editor): add snap threshold configuration optionfix(arrows): correct binding behavior with rotated shapesdocs: update sync documentationrefactor(store): simplify migration system仓库根目录 AGENTS.md 同样要求对 Markdown 标题、UI 标签、文档标题、PR 标题、issue 标题使用 sentence case句首大写写 PR 标题时保持一致。五、PR 正文两套模板write-pr按变更类型区分两套正文模板bugfix / improvement使用固定的 before/after 结构其余一切使用通用模板。通用模板description paragraph ### Change type - [x] bugfix | improvement | feature | api | other ### Test plan 1. Step to test... 2. Another step... - [ ] Unit tests - [ ] End to end tests ### Release notes - Brief description of changes for users描述段落的写作要领以In order to X, this PR does Y.开头并遵循前文的评审者优先规则X 是使这项工作成为必要的具体情境——某个人真正想做的事——而不是对 Y 做了什么的重述。技能给出了一个反例为了让应用能在编辑器重建时保留撤销历史本 PR 增加了跨编辑器重建保留撤销历史的 API就是循环论证X 只是重命名了 Y。应把 X 向上推一层到真实目标例如为了让桌面端能重新加载编辑器而不丢失用户位置就像 HMR 在代码编辑时保留组件状态那样。点名真实驱动场景而非假设场景。如果为了说明 why 而在编造示例场景比如有人切换了插件……那是在从成品代码反向工程理由——你还没写下真正触发它的案例。要从那个案例正向工作。警惕用抽象机制代替动机。关于 SDK 的真实技术事实editor 配置在构造时固定解释的是约束而不是为什么有人在乎。继续追问直到读者能想象出那个具体停止工作或变得可能的事情。保持具体避免improve user experience这类含糊说法在首段链接相关 issue不要假设读者会去读链接的 issue。Bug fix / improvement 专用模板This PR fixes a bug where symptom a user or developer would hit. ### Before what the code did and why that produced the symptom ### After what the code does now ### Implementation notes optional: what exactly changed and how — decisions, trade-offs, anything non-obvious ### Change type - [x] bugfix | improvement ### Test plan - [x] Unit tests — the new test fails on main and passes with this change ### Release notes - Fix symptom | Improve behavior ### Code changes | Section | LOC change | | --------- | ---------- | | Core code | 10 / -2 | | Tests | 5 / -0 |各部分的写作要点Intro一句话对 bug——This PR fixes a bug where XX 是可观察的症状不是原因或修复本身对 improvement——This PR improves X so that YY 是用户或开发者现在能做的事。有 issue 就在这里链接。若 PR 不止一件事用第二句话It also ...而不是列表。Before之前的行文及产生症状的机制。对 bug点名出错的函数或路径——这是唯一允许简短描述旧代码怎么错了的地方因为它是评审者对照修复去核查的原因。对 improvement描述用户或开发者之前不得不做什么或做不到什么以及代码中什么造成了这种状况。After之后的行文详细程度与 Before 持平。注明是否同步更新了相关 spec 或文档。Implementation notes可选。仅当 Before/After 无法承载的信息才写——你选择的一种方案而非另一种、改动中的微妙之处、你有意留作后续的工作。多数小修复无话可说时整个省略该标题。通用块的标准要求Change type用[x]精确勾选一个类型删除未勾选项。Test plan适用时列出人工测试步骤无法人工测试的改动删除编号列表勾选包含的测试类型复选框。Release notes用祈使语气写面向用户的简短说明Add...、Fix...、Remove...纯内部工作CI、工具、测试等若无用户可见影响整个省略此节。六、画布交互改动的 Before/After 录制当 bug 修复或改进改变了画布交互方式——拖动、缩放、旋转、裁剪、句柄或工具手势——而这些行为评审者不本地运行就看不到时在 Before 和 After 小节各放一段短视频。散文描述机制录制展示症状及其消失评审者更信任视频而不是对一次跳动或抖动的文字描述。数据、API、文档、工具类等不在画布上可见的改动跳过此节。录制工具与脚本录制由 skills/write-pr/scripts/record-interaction.mjs 完成配套的 skills/write-pr/scripts/example-scenario.mjs 是场景起点。从源码看record-interaction.mjs的工作机制包括用 Playwright 驱动运行中的 examples 应用默认 URLhttp://localhost:5420/develop可用--url覆盖以 1280×720 视口录制 16:9 MP4通过注入 CSS 隐藏 tldraw 界面外壳.tlui-layout, .tlui-debug-panel让画布铺满画面--keep-ui可保留 UI注入一个可见的 SVG 光标并跟随pointermove事件——因为无头录制没有光标运行场景模块后用 ffmpeg 剪掉启动阶段的帧-ss定位到场景开始时间戳并以libx264 / yuv420p / crf 22转码输出。场景模块的形态是export default async (page, helpers) {}helpers提供三个能力见 example-scenario.mjseditor(fn, arg)在页面内对window.editor执行函数examples 应用暴露了window.editor可用来创建形状、设置用户偏好等drag(from, to, {steps, dwellMs})分小步移动鼠标让录制中能看到运动轨迹pause(ms)等待。环境准备# 本仓库禁用了安装脚本yarn install 不会下载浏览器需手动安装一次 Chromium yarn playwright install chromium # ffmpeg 需在 PATH 中macOS: brew install ffmpeg然后从仓库根目录启动yarn devexamples 应用运行于 localhost:5420再按顺序录制# After当前分支 node skills/write-pr/scripts/record-interaction.mjs scenario.mjs scratch/after.mp4 # Before本分支修改的文件的 main 版本由 vite 热更新生效 git diff --name-only --diff-filterM origin/main...HEAD | xargs git checkout origin/main -- sleep 10 node skills/write-pr/scripts/record-interaction.mjs scenario.mjs scratch/before.mp4 git diff --name-only --diff-filterM origin/main...HEAD | xargs git checkout HEAD -- git status --porcelain # 继续前必须为空这段命令链有几个刻意设计只检出被修改的文件--diff-filterM从main检出一整个目录会把只在main存在的文件也 staging 进来而本分支新增的文件在main没有对应版本可恢复仅在工作树干净时使用此法sleep 10留给 vite 完成热更新git status --porcelain验证恢复干净后才继续。录制规范同一场景两段视频只能在被测代码上有差异评审者才能同比比较。先录 After确认场景确实展示了行为再录 Before。让症状不可忽视选择放大 bug 的输入——大角度旋转、长距离拖动、非正方形形状。15 度旋转让形状移动几个像素在视频尺度上等于没有。挂载前检查帧用接触印表contact sheet检查 Before 是否真的生效——看起来和 After 一模一样的 Before 通常意味着 checkout 没生效而不是 bug 不明显ffmpeg -i before.mp4 -vf selectnot(mod(n\,15)),scale320:-1,tile6x3 -frames:v 1 sheet.png不烧录标签### Before与### After标题已说明哪个是哪个。保持短小几秒 setup 交互 结尾一个停顿每段控制在 10 秒以内。挂载视频需要 gh 2.99 或更新版本在仓库内执行使用绝对路径gh pr edit number --body-file body.md --attach /abs/path/before.mp4 --attach /abs/path/after.mp4正文中在每个小节标题下以该文件引用作为该段落的唯一内容gh 会把引用重写为上传的资源### Before mechanism Before ### After behavior now After七、概念、示例与 FAQ只在评审者真正需要时提供这些节以评审者需求为门槛而不是 PR 体量——大 PR 不是加表的理由评审者需要共享词汇或用法示例来跟上改动才是。大多数大 PR 都够不上这个门槛。确需时把相关小节放在标准的### Change type/### Test plan/### Release notes块之上。护栏一行只有当它说出了代码没说的事才配存在。重述签名的Method | Description表、为不言自明的名字加 Concepts 行就是 diff 的重复——删掉。拿不准就不放。按此顺序从菜单中选取只用适合的ConceptsPR 引入的新术语/类型表列为Term | Type | Meaning。读者需要共享词汇才能跟上其余描述时使用。Module augmentation展示消费者如何扩展新类型的短代码块——当 PR 暴露了可增强augmentable接口时。Editor API / Component props新公开面的Method | Description与Prop | Type | Description表。Per-shape / per-feature breakdown展示各受影响的形状/模块在新系统下返回或接受什么的表。Example一段真实、可复制的代码片段展示默认实现如何使用新系统再加一段消费者如何覆盖的片段。FAQ预判下游用户第一个会伸手去够的自定义路径配短代码答案。New examples新增在apps/examples/src/examples/下的条目列表每条一行描述让评审者知道去哪里找可运行演示。八、API 变更小节当改动影响api-report.md时必须包含此节。仓库中每个包都维护api-report.api.md如 packages/editor/api-report.api.md根目录 AGENTS.md 也要求公开 API 改动后运行yarn api-check并纳入有意的 API report 更新。### API changes - Added Editor.newMethod() for X - Breaking! Removed Editor.oldMethod() - Changed Editor.method() to accept optional options parameter九、代码变更表唯一允许复述 diff的例外该表是不复述 diff规则的刻意例外它是高层索引而不是伪装成洞见的散文。它让评审者一眼看出改动规模——核心代码、测试、生成文件、工具各占多少——并决定往哪里看。总是包含它。表的每一行给出净 LOC 变更所有行的总和必须等于整个 PR 的 diff 总量没有改动的行省略区块内容Core codeSDK 包packages/源码排除测试与 API reportTests单元测试、e2e 测试*.test.*、e2e/Automated files生成文件如api-report.api.md、快照Documentation文档站与示例apps/docs/、apps/examples/Apps应用代码apps/dotcom/、apps/mcp-app/、apps/vscode/等排除 e2e 测试Templates启动模板templates/Config/tooling配置文件、锁文件、lint 配置、CI、构建脚本.oxlintrc.json、yarn.lock等### Code changes | Section | LOC change | | --------------- | ---------- | | Core code | 10 / -2 | | Tests | 5 / -0 | | Automated files | 0 / -1 | | Documentation | 2 / -0 | | Apps | 3 / -1 | | Templates | 0 / -0 | | Config/tooling | 1 / -0 |十、相关 issue搜索并链接本 PR 解决的 issue见第一步工作流中的Closes #123/Relates to #123用法。十一、注释清扫The comment sweep这是对diff的预检而不是对描述的检查像读新增代码一样仔细读 diff 中新增的注释在打开 PR 之前删掉冗余。git diff origin/main...URL -U0 | grep -nE ^\\s*(//|/\*|\*)把输出对照仓库根目录 AGENTS.md 的 Comments 一节来评判——那里是规则本体本节不复述它。随身携带一条判据一条好注释命名的是失败模式而不是机制。机制已经在屏幕上代码本身了注释的作用是说没有它会出什么错。只描述代码做什么的注释块可以整块删掉说否则就会 X的块留下那句话删掉把它解释两遍的段落。技能特别提醒预期的缺陷是长度而不是类别。多数需要编辑的大注释块已经命名了真正的力——它们是对的那类注释只是长度是必要的两三倍。所以通常的编辑是修剪到承重的那几行而不是删除。以下内容保留原样或最多轻微修剪图表、枚举型用例列表列表本身就是规格说明、出处issue 编号、我们试过 X 它产生了 Y、以及任何承载不变式的东西。在packages/*中public面上的文档注释就是 API 参考——用同样的说出代码没说的事标准要求它们但它们是交付物不是开销。为什么是预检而不是评审后补救现在做便宜以后做贵。一条复述自身代码的注释读起来像填充物浪费一次评审往返来移除合并之后没人会回来处理它。解释改动是 PR 正文的工作——diff 不是放解释的地方。十二、人工笔记Human notes逐字节保留PR 作者常常在描述最顶端写一段个人笔记以人物emoji如 或 开头。这段是人工写的读者信任它。更新已有 PR 时如果正文以人物 emoji 引导的段落/小节开头必须在顶部逐字节byte-for-byte原样保留——不重写、不重排、不重新措辞、不改标题、不改进哪怕一点点。若人工笔记超过一段它会在结尾用---水平线定界。从人物 emoji 开始一直到含---的所有内容都要精确保留。若没有---人工笔记就是那个 emoji 引导的首段。所有编辑都发生在人工笔记之下若有---则在其下。创建新 PR 时不要发明人工笔记——留给作者去加。十三、不可违反的规则清单write-pr在结尾汇总了硬性规则绝不包含 AI 署名除非 PR 直接与 AI 工具相关描述永不用标题式大写title case一律用 sentence case绝不把自己设为任何提交的合著者co-author只要 PR 改动了任何api-report.md就必须包含 API changes 小节。pr技能补充了对应的工作流红线提交消息、PR 标题、PR 描述中都不包含 AI 署名不把 AI 工具加为合著者。这些与根目录 AGENTS.md 的仓库写作风格约定不在提交、PR 描述、issue、文档、release notes 或生成内容中包含 AI 署名完全一致。附与仓库其他协作技能的衔接pr技能不是孤立存在的它处于 tldraw 仓库一套完整的 Agent 协作工作流之中。根目录 AGENTS.md 列出了面向用户的工作流技能skills/pr/、skills/issue/、skills/take/、skills/commit-changes/、skills/clean-copy/。其中 skills/commit-changes/SKILL.md 定义了提交阶段同样的 Conventional Commits 格式、git commit -m、不 push、不 amend、不使用--no-verify、不包含 AI 署名是pr技能准备分支步骤的前置环节。而pr技能自身通过../write-pr/SKILL.md引用内容标准、通过 skills/write-pr/scripts/record-interaction.mjs 引用录制工具——从仓库结构看skills/目录是这些技能的单一事实来源.claude/skills、.cursor/skills等目录均为指向它的符号链接。这套流程的完整链路是take认领任务→commit-changes提交→pr建/改 PR→write-pr内容标准→ 评审。掌握了本文的prwrite-pr部分你就掌握了其中最关键、也最考验为评审者着想的一环。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 12:14:58 · 阅读 1.2k tldraw 仓库 Pull Request 创建与更新完整工作流：从分支准备到评审提交（pr / write-pr 技能指南）
tldraw 仓库 Pull Request 创建与更新完整工作流从分支准备到评审提交pr / write-pr 技能指南【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw导读本文基于 tldraw 开源仓库skills/目录下维护的pr与write-pr两套 Agent 技能系统讲解在该仓库中创建、更新 Pull Request 的标准工作流以及 PR 标题、描述、录制素材、变更统计等内容规范。读完本文你将掌握一套从收集上下文、规避重叠工作、分支准备、自审提交到创建 PR、按规范撰写描述、录制 Before/After 视频、保留人工笔记的端到端实操流程并理解每一条规范背后的仓库源码级依据提交钩子、脚本工具、评审约定。该工作流面向的是 tldraw 的 monorepo 结构Yarn workspacespackages/为 SDK 源码、apps/为应用与示例任何向该仓库提交代码的开发者或 Agent 都可以直接套用。两套技能的分工pr与write-prskills/pr/SKILL.md 是用户面向的工作流入口当用户发起pr、要求创建/更新 PR、推送当前分支供评审或准备 PR 时触发。它定义了做什么的步骤顺序。skills/write-pr/SKILL.md 是内容标准参考定义 PR 标题、描述、release notes、API 变更、代码变更表、人工笔记保留等写成什么样的规范并附带前置的注释清扫comment sweep。它不作为用户直接调用的工作流而是被pr等技能引用的支持性标准。pr技能在第一步即声明以write-pr为标准来源涉及标题、描述、release notes、API 变更、代码变更表与人工笔记保留时一律以其为准。一、PR 工作流的九个步骤pr技能将整个流程收敛为九个步骤每一步都对应具体的 git/gh 命令下面逐一展开。1. 收集上下文进入任何操作之前先通过四条命令摸清当前状态git branch --show-current # 当前分支 git status --short # 工作树状态 gh pr view --json number,title,url 2/dev/null # 是否已有对应 PR git log main..HEAD --oneline 2/dev/null || git log -3 --oneline # 本分支相对 main 的提交git log main..HEAD用区间语法列出当前分支领先于main的提交若main分支不存在或比较失败2/dev/null吞掉报错则回退到最近 3 条提交作为风格参考。这四条命令同时服务于后续的是否存在 PR分支基于什么提交风格如何三个判断。2. 检查重叠工作避免踩到队友的脚仓库鼓励先看有没有人正在做同一块区域的工作再决定是否动手# 列出所有开放 PR含作者、分支名与更新时间 gh pr list --state open --json number,title,url,author,headRefName,updatedAt # 按关键词搜索相关开放 PR gh pr list --search keywords --state open # 对比对方 PR 改动的文件判断是否真的重叠而非只是文件名相同 gh pr diff number --stat技能给出了明确的协作优先级如果已经有人为此开了 PR优先在对方的工作上构建——可以是把自己的分支基于对方分支、贡献一条评审意见或后续提交或者把改动交接过去。只有当实现路径真正分叉时才允许开一个竞争性 PR且必须在描述里链接对方的 PR 并说明差异让评审者容易做出选择。一个值得注意的细节技能要求用gh pr diff number --stat对比实际改动的文件来判断重叠而不是只看是否共享文件名——因为共享文件名可能只是碰巧真实重叠应以改动集为准。若发现有意义的重叠需要在继续之前把发现呈现给用户。3. 准备分支若当前在main上先创建一个描述性名称的新分支提交相关改动排除密钥和明确属于私有的内容推送分支到远程。任何情况下不得 force push详见处理问题一节的钩子约束。4. 在请人工评审之前先做一轮初始评审这是本工作流最有特色的环节在 diffgit diff main...HEAD上并行派出若干子代理subagents每个聚焦一个视角然后把发现收敛为具体修复。技能列出的四个评审视角端到端解决问题改动是否真正解决了所述问题而不是掩盖症状让代码库变得更好命名是否清晰、有无死代码或重复代码、有无顺带引入的回归drive-by regressions抽象是否得当有无评审者会标记的怪异抽象、过早泛化或不必要的代码优先选择更小、更直接的版本。注释清扫扫描 diff 新增的注释执行write-pr中的 The comment sweep 一节详见后文。在更新已有 PR 时这一步能捕获分支自 PR 打开以来新增的注释——在长寿分支上这往往占了新增注释的大头。修复明显值得修的问题让人工评审从一个强健的 diff 开始若某个发现需要产品或设计决策去问用户而不是猜。本轮修复要提交并推送确保远程分支在 PR 创建/更新/分享之前与本地一致。同样绝不 force push。5~7. 创建、读取与更新 PR# 不存在 PR创建 gh pr create # 存在 PR读取标题、正文、标签、编号并查看改动文件摘要 gh pr view --json title,body,labels,number gh pr diff --stat # 若现有 PR 与当前 diff 或 write-pr 标准不符更新标题/正文 gh pr edit更新 PR 时技能要求先完整读取现有 PR 的title、body、labels、number并检查改动文件摘要再决定是否需要用gh pr edit修正标题或正文——不能盲目覆盖。特别地若正文顶部存在人工笔记human note必须按write-pr的规则逐字节保留详见下文。8. 关联相关 issue搜索相关 issue并在 PR 描述中用Closes #123或Relates to #123链接。关联的关键词决定了 issue 是否会被自动关闭Closes会在 PR 合并时关闭 issueRelates to只建立关联不关闭。9. 分享 PR 链接将 PR URL 交给用户流程结束。二、提交钩子与问题处理pr技能明确指出提交会自动运行钩子hooks。tldraw 仓库根目录的 AGENTS.md 也印证了这一点——它要求使用 Yarn 4 workspaces、yarn lint、yarn typecheck、yarn api-check等命令作为质量闸门而提交钩子正是这些检查的自动化载体。处理原则分两种情况机械性修复格式化、lint、类型或导入问题直接修复即可需要决策的失败如果钩子失败暴露出有意义的产品或实现决策问题停下并询问用户如何处理硬性红线绝不 force commit、绝不 force push。这条机械问题自己修、决策问题问用户的边界与第四步初始评审中产品/设计决策找用户的原则一脉相承。三、PR 内容标准为评审者写作skills/write-pr/SKILL.md 的全部内容围绕一条最高法则展开其余所有规则都服务于它面向一个了解代码库架构、但没读过你的代码和 diff的评审者写作。评审者的时间是最稀缺的资源描述的工作是给他们代码里读不到的框架信息然后让开。默认要短倒金字塔结构默认从短开始几句话的框架是常态而非例外。描述长度匹配改动规模——一行修复配一句话新系统才配完整论述。一份看起来又长又结构化的描述并不更有价值往往是反的它把框架埋在脚手架下面。如果评审者还需要自己的 AI 来解读你的描述它就失败了。由粗到细排列描述按倒金字塔组织最重要的在最前面。读者可以在任何一点停下来都能带着正确、自洽的理解离开扫读者从开头几句得到目标与动机评估方案的人往下读到设计与决策严格评审者继续看到具体细节。绝不能让读者读到最后才知道这个 PR 是干什么的。覆盖层次大致按此顺序每层比前一层更细改动不再需要时每层都可省略目标、动机与用例——为什么改、为什么现在改、为谁服务之前缺什么或错什么。永远放在最前。更上层的变更——解决方案的形态行为与结构而不是对 diff 的逐行复述。API 设计与决策——新增或变更的公开面、你选定的方案、排除的方案及原因、你不确定的地方。你不提出的决策评审者就无法捕捉到。示例片段与细节——凡是涉及 API、数据形态或用法模式的改动几行 before/after 胜过一段文字保持最小化。禁止事项不要复述 diff不做逐文件走查、不叙述某个函数做什么、不逐步描述代码如何工作——评审者自己能读代码。不要生成镜像代码的表格或列表比如Method | Description表只是重述签名、列出每个改动文件的清单、为不言自明的名字做术语表。不要用仪式感填充为了显得全面而存在的结构就是噪音。永不虚构为什么动机与取舍必须来自真实意图——提交记录、关联的 issue、或作者本人。如果不知道某个改动为什么发生或考虑了哪些方案问用户不要猜。一个自信但虚构的理由比没有更糟它具有误导性而它恰恰是评审者最需要信任的东西。四、PR 标题语义化提交格式PR 标题使用 Conventional Commits 语义化格式type(scope): description类型type类型含义feat新功能fix缺陷修复docs仅文档refactor既不修 bug 也不加功能的代码变更perf性能改进test新增或修复测试chore维护性任务作用域scope可选用名词描述受影响区域fix(editor):、feat(sync):、docs(examples):。从仓库结构看这些作用域名称与 monorepo 内的包/应用名对应如packages/editor、packages/sync、apps/examples。示例feat(editor): add snap threshold configuration optionfix(arrows): correct binding behavior with rotated shapesdocs: update sync documentationrefactor(store): simplify migration system仓库根目录 AGENTS.md 同样要求对 Markdown 标题、UI 标签、文档标题、PR 标题、issue 标题使用 sentence case句首大写写 PR 标题时保持一致。五、PR 正文两套模板write-pr按变更类型区分两套正文模板bugfix / improvement使用固定的 before/after 结构其余一切使用通用模板。通用模板description paragraph ### Change type - [x] bugfix | improvement | feature | api | other ### Test plan 1. Step to test... 2. Another step... - [ ] Unit tests - [ ] End to end tests ### Release notes - Brief description of changes for users描述段落的写作要领以In order to X, this PR does Y.开头并遵循前文的评审者优先规则X 是使这项工作成为必要的具体情境——某个人真正想做的事——而不是对 Y 做了什么的重述。技能给出了一个反例为了让应用能在编辑器重建时保留撤销历史本 PR 增加了跨编辑器重建保留撤销历史的 API就是循环论证X 只是重命名了 Y。应把 X 向上推一层到真实目标例如为了让桌面端能重新加载编辑器而不丢失用户位置就像 HMR 在代码编辑时保留组件状态那样。点名真实驱动场景而非假设场景。如果为了说明 why 而在编造示例场景比如有人切换了插件……那是在从成品代码反向工程理由——你还没写下真正触发它的案例。要从那个案例正向工作。警惕用抽象机制代替动机。关于 SDK 的真实技术事实editor 配置在构造时固定解释的是约束而不是为什么有人在乎。继续追问直到读者能想象出那个具体停止工作或变得可能的事情。保持具体避免improve user experience这类含糊说法在首段链接相关 issue不要假设读者会去读链接的 issue。Bug fix / improvement 专用模板This PR fixes a bug where symptom a user or developer would hit. ### Before what the code did and why that produced the symptom ### After what the code does now ### Implementation notes optional: what exactly changed and how — decisions, trade-offs, anything non-obvious ### Change type - [x] bugfix | improvement ### Test plan - [x] Unit tests — the new test fails on main and passes with this change ### Release notes - Fix symptom | Improve behavior ### Code changes | Section | LOC change | | --------- | ---------- | | Core code | 10 / -2 | | Tests | 5 / -0 |各部分的写作要点Intro一句话对 bug——This PR fixes a bug where XX 是可观察的症状不是原因或修复本身对 improvement——This PR improves X so that YY 是用户或开发者现在能做的事。有 issue 就在这里链接。若 PR 不止一件事用第二句话It also ...而不是列表。Before之前的行文及产生症状的机制。对 bug点名出错的函数或路径——这是唯一允许简短描述旧代码怎么错了的地方因为它是评审者对照修复去核查的原因。对 improvement描述用户或开发者之前不得不做什么或做不到什么以及代码中什么造成了这种状况。After之后的行文详细程度与 Before 持平。注明是否同步更新了相关 spec 或文档。Implementation notes可选。仅当 Before/After 无法承载的信息才写——你选择的一种方案而非另一种、改动中的微妙之处、你有意留作后续的工作。多数小修复无话可说时整个省略该标题。通用块的标准要求Change type用[x]精确勾选一个类型删除未勾选项。Test plan适用时列出人工测试步骤无法人工测试的改动删除编号列表勾选包含的测试类型复选框。Release notes用祈使语气写面向用户的简短说明Add...、Fix...、Remove...纯内部工作CI、工具、测试等若无用户可见影响整个省略此节。六、画布交互改动的 Before/After 录制当 bug 修复或改进改变了画布交互方式——拖动、缩放、旋转、裁剪、句柄或工具手势——而这些行为评审者不本地运行就看不到时在 Before 和 After 小节各放一段短视频。散文描述机制录制展示症状及其消失评审者更信任视频而不是对一次跳动或抖动的文字描述。数据、API、文档、工具类等不在画布上可见的改动跳过此节。录制工具与脚本录制由 skills/write-pr/scripts/record-interaction.mjs 完成配套的 skills/write-pr/scripts/example-scenario.mjs 是场景起点。从源码看record-interaction.mjs的工作机制包括用 Playwright 驱动运行中的 examples 应用默认 URLhttp://localhost:5420/develop可用--url覆盖以 1280×720 视口录制 16:9 MP4通过注入 CSS 隐藏 tldraw 界面外壳.tlui-layout, .tlui-debug-panel让画布铺满画面--keep-ui可保留 UI注入一个可见的 SVG 光标并跟随pointermove事件——因为无头录制没有光标运行场景模块后用 ffmpeg 剪掉启动阶段的帧-ss定位到场景开始时间戳并以libx264 / yuv420p / crf 22转码输出。场景模块的形态是export default async (page, helpers) {}helpers提供三个能力见 example-scenario.mjseditor(fn, arg)在页面内对window.editor执行函数examples 应用暴露了window.editor可用来创建形状、设置用户偏好等drag(from, to, {steps, dwellMs})分小步移动鼠标让录制中能看到运动轨迹pause(ms)等待。环境准备# 本仓库禁用了安装脚本yarn install 不会下载浏览器需手动安装一次 Chromium yarn playwright install chromium # ffmpeg 需在 PATH 中macOS: brew install ffmpeg然后从仓库根目录启动yarn devexamples 应用运行于 localhost:5420再按顺序录制# After当前分支 node skills/write-pr/scripts/record-interaction.mjs scenario.mjs scratch/after.mp4 # Before本分支修改的文件的 main 版本由 vite 热更新生效 git diff --name-only --diff-filterM origin/main...HEAD | xargs git checkout origin/main -- sleep 10 node skills/write-pr/scripts/record-interaction.mjs scenario.mjs scratch/before.mp4 git diff --name-only --diff-filterM origin/main...HEAD | xargs git checkout HEAD -- git status --porcelain # 继续前必须为空这段命令链有几个刻意设计只检出被修改的文件--diff-filterM从main检出一整个目录会把只在main存在的文件也 staging 进来而本分支新增的文件在main没有对应版本可恢复仅在工作树干净时使用此法sleep 10留给 vite 完成热更新git status --porcelain验证恢复干净后才继续。录制规范同一场景两段视频只能在被测代码上有差异评审者才能同比比较。先录 After确认场景确实展示了行为再录 Before。让症状不可忽视选择放大 bug 的输入——大角度旋转、长距离拖动、非正方形形状。15 度旋转让形状移动几个像素在视频尺度上等于没有。挂载前检查帧用接触印表contact sheet检查 Before 是否真的生效——看起来和 After 一模一样的 Before 通常意味着 checkout 没生效而不是 bug 不明显ffmpeg -i before.mp4 -vf selectnot(mod(n\,15)),scale320:-1,tile6x3 -frames:v 1 sheet.png不烧录标签### Before与### After标题已说明哪个是哪个。保持短小几秒 setup 交互 结尾一个停顿每段控制在 10 秒以内。挂载视频需要 gh 2.99 或更新版本在仓库内执行使用绝对路径gh pr edit number --body-file body.md --attach /abs/path/before.mp4 --attach /abs/path/after.mp4正文中在每个小节标题下以该文件引用作为该段落的唯一内容gh 会把引用重写为上传的资源### Before mechanism Before ### After behavior now After七、概念、示例与 FAQ只在评审者真正需要时提供这些节以评审者需求为门槛而不是 PR 体量——大 PR 不是加表的理由评审者需要共享词汇或用法示例来跟上改动才是。大多数大 PR 都够不上这个门槛。确需时把相关小节放在标准的### Change type/### Test plan/### Release notes块之上。护栏一行只有当它说出了代码没说的事才配存在。重述签名的Method | Description表、为不言自明的名字加 Concepts 行就是 diff 的重复——删掉。拿不准就不放。按此顺序从菜单中选取只用适合的ConceptsPR 引入的新术语/类型表列为Term | Type | Meaning。读者需要共享词汇才能跟上其余描述时使用。Module augmentation展示消费者如何扩展新类型的短代码块——当 PR 暴露了可增强augmentable接口时。Editor API / Component props新公开面的Method | Description与Prop | Type | Description表。Per-shape / per-feature breakdown展示各受影响的形状/模块在新系统下返回或接受什么的表。Example一段真实、可复制的代码片段展示默认实现如何使用新系统再加一段消费者如何覆盖的片段。FAQ预判下游用户第一个会伸手去够的自定义路径配短代码答案。New examples新增在apps/examples/src/examples/下的条目列表每条一行描述让评审者知道去哪里找可运行演示。八、API 变更小节当改动影响api-report.md时必须包含此节。仓库中每个包都维护api-report.api.md如 packages/editor/api-report.api.md根目录 AGENTS.md 也要求公开 API 改动后运行yarn api-check并纳入有意的 API report 更新。### API changes - Added Editor.newMethod() for X - Breaking! Removed Editor.oldMethod() - Changed Editor.method() to accept optional options parameter九、代码变更表唯一允许复述 diff的例外该表是不复述 diff规则的刻意例外它是高层索引而不是伪装成洞见的散文。它让评审者一眼看出改动规模——核心代码、测试、生成文件、工具各占多少——并决定往哪里看。总是包含它。表的每一行给出净 LOC 变更所有行的总和必须等于整个 PR 的 diff 总量没有改动的行省略区块内容Core codeSDK 包packages/源码排除测试与 API reportTests单元测试、e2e 测试*.test.*、e2e/Automated files生成文件如api-report.api.md、快照Documentation文档站与示例apps/docs/、apps/examples/Apps应用代码apps/dotcom/、apps/mcp-app/、apps/vscode/等排除 e2e 测试Templates启动模板templates/Config/tooling配置文件、锁文件、lint 配置、CI、构建脚本.oxlintrc.json、yarn.lock等### Code changes | Section | LOC change | | --------------- | ---------- | | Core code | 10 / -2 | | Tests | 5 / -0 | | Automated files | 0 / -1 | | Documentation | 2 / -0 | | Apps | 3 / -1 | | Templates | 0 / -0 | | Config/tooling | 1 / -0 |十、相关 issue搜索并链接本 PR 解决的 issue见第一步工作流中的Closes #123/Relates to #123用法。十一、注释清扫The comment sweep这是对diff的预检而不是对描述的检查像读新增代码一样仔细读 diff 中新增的注释在打开 PR 之前删掉冗余。git diff origin/main...URL -U0 | grep -nE ^\\s*(//|/\*|\*)把输出对照仓库根目录 AGENTS.md 的 Comments 一节来评判——那里是规则本体本节不复述它。随身携带一条判据一条好注释命名的是失败模式而不是机制。机制已经在屏幕上代码本身了注释的作用是说没有它会出什么错。只描述代码做什么的注释块可以整块删掉说否则就会 X的块留下那句话删掉把它解释两遍的段落。技能特别提醒预期的缺陷是长度而不是类别。多数需要编辑的大注释块已经命名了真正的力——它们是对的那类注释只是长度是必要的两三倍。所以通常的编辑是修剪到承重的那几行而不是删除。以下内容保留原样或最多轻微修剪图表、枚举型用例列表列表本身就是规格说明、出处issue 编号、我们试过 X 它产生了 Y、以及任何承载不变式的东西。在packages/*中public面上的文档注释就是 API 参考——用同样的说出代码没说的事标准要求它们但它们是交付物不是开销。为什么是预检而不是评审后补救现在做便宜以后做贵。一条复述自身代码的注释读起来像填充物浪费一次评审往返来移除合并之后没人会回来处理它。解释改动是 PR 正文的工作——diff 不是放解释的地方。十二、人工笔记Human notes逐字节保留PR 作者常常在描述最顶端写一段个人笔记以人物emoji如 或 开头。这段是人工写的读者信任它。更新已有 PR 时如果正文以人物 emoji 引导的段落/小节开头必须在顶部逐字节byte-for-byte原样保留——不重写、不重排、不重新措辞、不改标题、不改进哪怕一点点。若人工笔记超过一段它会在结尾用---水平线定界。从人物 emoji 开始一直到含---的所有内容都要精确保留。若没有---人工笔记就是那个 emoji 引导的首段。所有编辑都发生在人工笔记之下若有---则在其下。创建新 PR 时不要发明人工笔记——留给作者去加。十三、不可违反的规则清单write-pr在结尾汇总了硬性规则绝不包含 AI 署名除非 PR 直接与 AI 工具相关描述永不用标题式大写title case一律用 sentence case绝不把自己设为任何提交的合著者co-author只要 PR 改动了任何api-report.md就必须包含 API changes 小节。pr技能补充了对应的工作流红线提交消息、PR 标题、PR 描述中都不包含 AI 署名不把 AI 工具加为合著者。这些与根目录 AGENTS.md 的仓库写作风格约定不在提交、PR 描述、issue、文档、release notes 或生成内容中包含 AI 署名完全一致。附与仓库其他协作技能的衔接pr技能不是孤立存在的它处于 tldraw 仓库一套完整的 Agent 协作工作流之中。根目录 AGENTS.md 列出了面向用户的工作流技能skills/pr/、skills/issue/、skills/take/、skills/commit-changes/、skills/clean-copy/。其中 skills/commit-changes/SKILL.md 定义了提交阶段同样的 Conventional Commits 格式、git commit -m、不 push、不 amend、不使用--no-verify、不包含 AI 署名是pr技能准备分支步骤的前置环节。而pr技能自身通过../write-pr/SKILL.md引用内容标准、通过 skills/write-pr/scripts/record-interaction.mjs 引用录制工具——从仓库结构看skills/目录是这些技能的单一事实来源.claude/skills、.cursor/skills等目录均为指向它的符号链接。这套流程的完整链路是take认领任务→commit-changes提交→pr建/改 PR→write-pr内容标准→ 评审。掌握了本文的prwrite-pr部分你就掌握了其中最关键、也最考验为评审者着想的一环。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考