AgentScope第15式·论剑PR

AgentScope第15式·贡献闭环

提 PR 之前，先证明问题不是你的

[读者] Java 后端 / Agent 应用工程师，已经能读 AgentScope Java 源码
[痛点] 遇到疑似框架问题，只会绕开、发帖、等官方修
[现在读] 要把“会读源码”升级成“能参与上游”
[读完] 能独立判断问题归属，并产出一个可提交的 PR

[旧方案] 跑 Demo 报错 → 贴日志到群里问 → 自己绕开
    |
    v
[新需求] 想给 agentscope-java 提一次真实贡献
    |
    v
[冲突] 分不清是业务代码、版本已修、文档缺口，还是框架真缺陷
    |
    v
[后果] 重复 Issue 被打回、chapter 分支污染上游、PR 被要求重开

我是老李，带一个三人小组做企业数字人。教程仓库 agentscopepractice 已经从第 3 式的 LiveKit + AgentScope Java 最小 Demo 一路长到现在的形态，基线一直钉在 AgentScope Java v2.0.3。前十几式里我们补上了 Tool/MCP、结构化输出、权限、中间件、状态这些能力，团队对这套框架的脾气已经摸得差不多了。

这一次的问题不一样。它不是“怎么用框架”，而是“框架本身是不是有问题”。同事在数字人会话里观察到一段不符合预期的行为，第一反应是在群里 @ 我：这是不是 AgentScope 的 Bug？要不要提个 Issue 让官方修？

而团队里同时有另一种声音：先别打扰官方，自己改成能跑就行。

那么，是业务代码写错了，还是框架真的有问题？

是先发 Issue 沟通，还是先 Fork 改完再提 PR？

如果判断错了，代价是一次被关闭的 Issue，还是一整个被拒的 PR？

01、故事

那天下午的现场很典型：数字人项目的一个会话流程跑到最后一步，返回的内容和预期对不上。日志不长，但足够让人起疑。群里先热闹了两分钟，然后所有人看向我。

任务是：判断这个问题到底归谁。

放在半年前，我的做法会很直接——打开编辑器，在业务代码里绕过去，加个补丁，能跑就行。或者更省事，把日志贴到社区群里等一个答案。前一种做法让团队的技术债越积越多，后一种做法通常等不到回复，因为没有人能只凭一段日志判断框架的行为。

真正确立流程，是因为一次很尴尬的经历。我们当时认定某处行为“不合理”，花了两天整理材料提了 Issue，结果维护者的第一条回复就是：请提供最小复现，并说明在 main 上是否仍然存在。那一刻我们才意识到，我们提供的不是证据，是情绪。

后来我把这件事反过来做了一次：先在教程分支里写一个最小复现，再把 v2.0.3 和官方 main 拉出来对比，然后去 Issues、PR、Discussions 里搜一遍。三步走完，结论往往在第 5 分钟就出现了——大部分时候问题在我们自己身上，剩下的那一小部分，才是真正值得提上游的东西。

而真正值得提的那一小部分，需要的不是热情，是纪律：独立的 Fork、独立主题分支、单一目的的 diff、能跑通的单测、符合规范的提交信息。这套纪律，就是这一式要补上的能力。

先复现再问
先搜索再提
分支要隔离
改动要最小

02、问题

旧方案是这样的：遇到疑似框架问题，凭直觉判断归属，然后二选一——要么自己绕开，要么直接把日志丢进官方 Issue。

这条路走不通的地方很具体。第一，直觉判断的准确率很低。框架行为和业务代码之间隔着一层，你以为是框架在“犯错”，实际上往往是参数传法、状态生命周期、并发时序出了问题。第二，绕过问题的成本会累积。每一次绕开，都是在数字人项目里埋一颗定时炸弹，等后续章节加 Memory、加 Subagent 的时候一起爆。第三，直接丢日志提 Issue，维护者拿不到有效信息，只会要求你补充，来回两三周，热情耗尽。

技术表现上，一个不合格的上游反馈通常缺三样东西：没有最小复现（别人无法在你之外复现）、没有版本坐标（不知道是 v2.0.3 还是 main）、没有对比结论（不知道是不是已经被修复）。除了 Issue 质量，PR 侧也常见两类问题：把 chapter 分支直接当 PR 分支推上去，把复现代码和框架修改混在一个 PR 里，以及把多个目的压进一次提交。

业务影响是双重的。短期看，数字人项目在原地打转；长期看，团队永远停在“框架使用者”的位置，遇到真问题只能等。

本篇的完成标准是四条：完成一次完整的“最小复现 → 查 Issue/PR → 判断上游归属 → Fork → 修改 → 测试 → 形成可提交 PR”演练；教程仓库只保留复现代码、问题分析和 Issue/PR 链接；官方 PR 分支与教程 chapter 分支严格分离；提交信息符合 Conventional Commits。本文不预设任何具体上游缺陷——没有真实问题就换文档改进或官方 good first issue 演练，绝不硬造 Bug。

旧法凭直觉
新法凭证据
判归属在前
写代码在后

03、原理

这一式只讲一个原理，但它是反直觉的。

反直觉判断：开源贡献的主要成本不在写代码，而在归属判断。绝大多数失败的 PR，代码本身并不差，只是解决了一个不该在框架侧解决的问题，或者解决了一个早已在 main 上修好的问题，又或者把三件事混进了一个 PR。

所以第一步不是打开 IDE，而是把问题放进四个象限里。

象限一，业务代码问题。你在数字人项目里调用方式不对、状态没清理、并发没控制。特征是：最小复现离不开你的业务上下文，剥离之后就消失了。结论：改自己的代码，不上游。

象限二，版本已修复问题。你在 v2.0.3 上看到的行为，在官方 main 上已经有变化。特征是：v2.0.3 可复现，main 不可复现。结论：升级版本，或记录差异，不上游重复提 PR。这一点尤其重要——教程基线是 v2.0.3，而官方 Releases 上的正式版可能已经更新，把旧版限制写成当前版本的永久缺陷是常见错误。

象限三，文档缺口。代码行为正确，但文档没写清楚，导致使用者反复踩坑。特征：源码/测试里能找到明确设计意图，官方文档却没说。结论：这是低风险、高价值的贡献路径，改 docs 就能走完整个 PR 闭环。

象限四，真实上游缺陷。v2.0.3 可复现，main 仍存在，官方 Issues、PR、Discussions 里没有相同记录或记录未被解决。特征是：最小复现与业务无关、有明确的期望行为、有可执行的测试。结论：这才是值得进入 Issue → PR 流程的问题。

这里两个 AgentScope 名词先定边界，不做百科展开：AgentScope Java 是 AgentScope 的 Java 实现，负责 Agent 推理、Tool、状态、Harness、Memory、Skill 等能力；最小复现是一份能独立跑起来、脱离你业务上下文、能稳定触发目标行为的最小工程。

判断顺序必须是：先复现，再对比版本，再搜历史记录，最后才讨论改哪里。倒过来做，就是本式反复强调的那些翻车姿势。

会读是入门
能改是进阶
能证是资格
能提是闭环

04、架构

[输入] 数字人项目中一次不符合预期的行为
    |
    v
[复现层] repro/ 最小复现工程（脱离业务上下文）
    |
    v
[证据层] v2.0.3 结果 + main 结果 + 官方 Issues/PR/Discussions 检索
    |
    v
[判断层] 业务问题 / 版本已修 / 文档缺口 / 真实缺陷
    |
    v
[动作层] 改自己 / 升级 / 提 Issue / 提 PR（Fork + 主题分支 + 单测）
    |
    v
[输出] 已关闭的问题记录，或一个单一目的的 PR 链接

这条链路一共 5 段，每一段都能独立验证。复现层输出一个可运行的工程；证据层输出三份可查的记录；判断层输出一个四选一的结论；动作层输出一次上游交互；输出物则是一个可以贴回教程仓库的链接。

边界：教程仓库负责复现、分析和链接，不负责承载官方代码修改。官方修改只存在于你个人 Fork 的主题分支上，chapter/* 分支永远不直接充当 PR 分支。

收益：把“怀疑”变成“结论”，把“抱怨”变成“证据”，把一次性的个人经验变成团队可复用的流程。更实际的一点是，上游维护者的时间被尊重了，你的 Issue 和 PR 通过率会明显不同。

代价：前期投入明显增加。写一个最小复现可能要半天，对比 main 又要半天，最后发现是自己的问题。这是常态，不是失败。

适用条件：你已经能读框架源码和测试，能在本地跑通教程 Demo，能稳定复现一个具体行为。

不适用条件：问题无法脱离业务上下文复现；问题已经在官方 main 上修复；你只是想给框架加一个“更适合自己项目”的特性。这三种情况都不该进入上游。

涉及 AgentScope 内部机制时，判断依据必须落到官方仓库的具体位置。本次演练会用到的入口包括根目录的 CONTRIBUTING.md（贡献规范与检查命令）、官方 Issues / Pull requests / Discussions 三个列表页，以及以 v2.0.3 为 tag 的固定版本源码。当代码行为与文档描述不一致时，以固定版本源码和测试为准，并在 Issue 中写清核验依据。

一端是复现
一端是 PR
中间是判断
两侧是纪律

05、实战一次

本章分支为 chapter/15-open-source-pr，从第 14 式分支继续创建，建议提交：docs(ch15): add upstream issue and pull request workflow。下面这套动作未在当前环境实测运行，命令与模板以官方 CONTRIBUTING.md 当前内容为准，读者执行后以实际输出为准。

第一步，固定你的环境坐标。教程基线是 AgentScope Java v2.0.3，写本文时官方最新正式版可能已经更新，两者必须分开记录。

# 1. 记录你的版本坐标
git -C agentscopepractice log -1 --oneline
git -C agentscope-java describe --tags 2>/dev/null || echo "v2.0.3"
java -version
mvn -v

第二步，在教程仓库里建复现目录。复现目录只放复现、证据和链接，不放框架源码修改。

cd agentscopepractice
git checkout -b chapter/15-open-source-pr
mkdir -p repro/issue-template

第三步，拉取官方仓库并做版本对比。这是判断“版本已修”还是“仍然存在”的关键动作。

cd /tmp
git clone https://github.com/agentscope-ai/agentscope-java.git
cd agentscope-java
git fetch --tags --all
git tag -l "v2.0.3"
git diff v2.0.3 main --stat | tail -40

如果 diff 的输出里出现了与你复现行为相关的模块路径，就要进一步看这个模块在 v2.0.3 与 main 之间的差异，判断你的现象是否已经在 main 上被修复。这属于“版本已修”象限，正确动作是升级或记录，不是提 PR。

第四步，写复现记录。这份记录同时是 Issue 正文的素材，也是教程仓库的问题分析文件。

# repro/issue-template/README.md

## 环境
- OS: <你的系统>
- JDK: <java -version 输出>
- AgentScope Java: v2.0.3
- 复现工程: repro/<问题短名>

## 最小复现步骤
1. 执行 <具体命令或测试类>
2. 观察 <具体输出位置>

## 期望行为
<一句话>

## 实际行为
<贴最小输出，不要贴全量日志>

## 版本对比
- v2.0.3: <可复现 / 不可复现>
- main: <可复现 / 不可复现 / 未验证>

## 检索结论
- Issues: <关键词 + 结论>
- Pull requests: <关键词 + 结论>
- Discussions: <关键词 + 结论>

## 归属判断
<业务问题 / 版本已修 / 文档缺口 / 真实缺陷>

第五步，按 CONTRIBUTING.md 的要求准备上游修改。先读规范，再动手。

curl -sL https://raw.githubusercontent.com/agentscope-ai/agentscope-java/main/CONTRIBUTING.md | head -120

如果该 raw 链接不可用，就打开 https://github.com/agentscope-ai/agentscope-java/blob/main/CONTRIBUTING.md 阅读。规范里通常包含代码风格、分支与提交约定、测试要求。写作时约定的提交前检查命令为：

mvn spotless:check
mvn test
mvn verify

第六步，Fork 并建立主题分支。分支名选择 fix/、docs/ 或 feat/*，一个分支只干一件事。注意：这是你个人 Fork 上的分支，不是教程仓库的 chapter 分支。

# 在你自己 Fork 出来的仓库里操作
git remote add fork https://github.com/<你的账号>/agentscope-java.git
git fetch fork
git checkout -b docs/xxx-clarify-yyy fork/main

第七步，最小修改。改一处，写一处测试，改一处文档。改完自查每一行 diff 是否都在回答同一个问题。

第八步，提交。Conventional Commits 格式如下，type 之后用括号标出范围：

# 示例格式，实际 message 按你的改动填写
git commit -F - <<'MSG'
docs(core): clarify xxx behavior in yyy

Explain why the behavior happens and add a test that pins it.
MSG

如果最终判断本次属于“无真实上游问题”，就切换到演练路径：在官方 Issues 中筛选 good first issue 标签的条目，或选择一处确实缺失的文档说明，走完上面同一套流程。这不是走形式——Fork、分支、修改、测试、PR 描述这五步，缺任何一步都不算闭环。

先克隆仓库
再建主题支
后跑检查命
末写提交信

06、排查

本章不预设任何具体上游缺陷，以下两条证据链是本次演练使用的判断流程，具体现象以读者自己的最小复现为准。

证据链一，现象是数字人会话在某种输入下返回不符合预期。第一反应是“框架有问题”。检查方式是三件事：把现象从业务里剥出来写最小复现；在 v2.0.3 上确认可复现；在官方 main 上再跑一次。结论是：如果最小复现脱离业务上下文就消失，那它属于业务代码问题；如果 v2.0.3 可复现但 main 不可复现，属于版本已修；只有当两者都可复现、且官方 Issues/PR/Discussions 里没有相同记录时，才进入“真实缺陷”候选。根因不是框架，而是我们在业务侧对状态生命周期的使用方式超出了它承诺的范围。修复动作是改业务代码，同时把这条经验写进教程仓库的问题分析文件。

错误尝试： 一开始我们打算直接照日志里的异常关键词去官方 Issues 搜索，搜到若干条“看起来相似”的条目后，就认为问题已被记录，放弃了继续排查。这个做法错在两点：一是关键词匹配不等于行为匹配，相似异常可能是完全不同的触发路径；二是把“有人提过”当成“问题已解决”，实际上未关闭的 Issue 只说明问题存在，不说明可以跳过最小复现。正确做法是：先有最小复现，再用最小复现的特征去检索——包括复现所需的 API 组合、版本号和期望行为，而不是只搜异常字符串。

证据链二，现象是第一次提 Issue 后维护者要求补充信息。当时的判断是“官方不给力”。检查方式是回头看自己提交的内容：没有最小复现，没有 v2.0.3 与 main 的对比结论，没有说明业务上下文与框架的边界。官方证据是根目录的 CONTRIBUTING.md 与仓库的 Issue 模板，它们通常在提交前就要求你勾选这些项。正确结论是：这不是维护者态度问题，是反馈质量不达标。修正做法是把复现记录模板前置到提交之前，先填满，再决定提不提。

上游贡献判断，按下面五问逐条确认：

• 是否可在最小 Demo 复现：能脱离业务复现才继续，否则停在这里。
• v2.0.3 是否存在：以固定 tag 的源码和你的复现工程为准。
• main 是否仍存在：拉取官方 main 重跑，不要凭 Release Notes 猜。
• 是否已有 Issue/PR：在 Issues、Pull requests、Discussions 三处分别检索，记录检索词与结论。
• 当前只能记录候选，还是已经有真实 Issue/PR：没有真实链接时，只写“可作为上游 Issue/PR 候选”，不得写成“已提交”或“已合并”。

错在抢结论
对在补证据
一链到源码
一链到 Issue

07、优化

根因是流程缺环：我们的排查只产出“怀疑”，不产出“证据”，而上游只接受证据。所以 V2 不在于写更多代码，而在于把三个缺环补上。

修改一，把复现前置。任何疑似上游问题，先在教程仓库的 repro/ 下建目录，写一份能独立跑起来的最小复现。原因很简单：复现是唯一能让别人和你站在同一现场的东西。新行为是：未完成最小复现，不允许进入 Issue 讨论。验证方法是让另一位同事在不问你的前提下跑通复现目录，能稳定看到同一现象即为通过。

修改二，把版本对比做成固定动作。每次判断都要明确写出 v2.0.3 与 main 的各自结果，并注明写本文时教程基线为 v2.0.3、官方最新正式版以 Releases 页面为准。原因是要从源头杜绝“把旧版限制写成当前版本缺陷”这类错误。验证方法是在复现记录的“版本对比”小节里，两行都必须有非空结论，允许写“未验证”，但必须显式写出。

修改三，把仓库职责分开。教程仓库只存复现代码、问题分析和 Issue/PR 链接；Fork 上的 fix/、docs/、feat/* 分支只存框架修改；chapter/* 分支永不直接充当官方 PR 分支。原因是混用会让两边都变得不可维护。验证方法是任意打开一个 PR，diff 里只应出现框架仓库相关文件。

在提交前，执行官方项目要求的格式与测试检查，并按 Conventional Commits 书写提交信息。PR 描述里要能解释每一处 diff 的存在理由，不能有“顺手改的”。

模板少扯皮
复现省来回
自检挡返工
一 PR 一事

08、演进

[同一输入] 一次疑似框架问题
    |
    +--[V1] 凭直觉判断 → 绕开或直接提日志
    |       代价：技术债累积、Issue 被要求补充、热情耗尽
    |
    +--[V2] 复现 → 对比版本 → 检索历史 → 判断归属 → 单一目的 PR
    |       代价：前期投入半天到一天，多数结论是“自己的问题”
    |
[Trade-off]
得到：可复用的判断流程与可提交的 PR
失去：遇到问题立刻有人替你解决的心理预期
适用边界：问题可脱离业务复现，且你已能读固定版本源码

正确性上，V1 的结论来自直觉，误差率高；V2 的结论来自最小复现与版本对比，可被第三方复核。稳定性上，V1 每次遇到问题都要重新摸索；V2 把判断固化成模板，新人也能跑。复杂度上，V2 明显更高——多了复现工程、版本对比和检索记录三份产物。成本上，V2 前期贵，但省下了与被维护者来回拉扯的时间，也省下了重复提 Issue 的风险。

适用范围上，V1 在“问题明显在业务侧”时反而更快，比如拼错配置、忘关连接这类无需证据的场景。V2 适合边界模糊、需要跨版本核验、可能需要上游处理的问题。

遗留问题有三个：一是官方 main 与 v2.0.3 差异较大时，定位相关模块需要额外时间；二是 Issue/PR/Discussions 的检索结果依赖关键词质量，容易漏；三是如果本次确实没有真实上游问题，演练的说服力会低于真实贡献，这只能靠后续章节里持续保持这套流程来弥补。

V1 靠人问
V2 靠流程
得到的是确定
失去的是随意

09、洞见

9.1 判断归属比写代码难，也比值钱

反直觉判断：一个 PR 被打回，最常见的原因不是代码质量，而是它解决了一个不该在框架侧解决的问题。从本次流程看，四象限判断把原本模糊的“是不是 Bug”压缩成四个可验证的出口，代价只是半天复现时间，收益是把返工概率大幅压低。判断归属的能力，本质上是把用户视角切换成维护者视角。

9.2 版本对比是贡献者的基本礼貌

反直觉判断：你以为在报 Bug，维护者看到的是“又一个没看 Release 的人”。教程基线钉在 v2.0.3 是为了教学稳定，但贡献时必须先确认官方 main 的现状，也必须确认写作当天 Releases 上的最新正式版是什么。把“v2.0.3 存在”直接写成“框架缺陷”，是本系列最容易犯、也最容易被打回的错。版本对比不是额外步骤，是入场券。

9.3 什么时候不应该用本章能力

本章能力并不适用于所有场景。第一，问题无法脱离业务上下文复现时，不该走上游，该回去重构自己的调用方式。第二，问题在官方 main 上已修复时，不该提 PR，该升级版本或记录差异。第三，你只是想让框架更贴合自己项目时，不该提 feat PR，该在自己的 Fork 上维护补丁或改用扩展点。第四，团队还没跑通教程 Demo、还不会读固定版本源码时，先补前几式，不要直接进入贡献流程——因为你连“期望行为”都定义不了。贡献的门槛不在编码能力，而在你能不能给出一个别人无法反驳的证据链。

9.4 教程分支与官方分支必须物理隔离

这条不是洁癖，是纪律。chapter/15-open-source-pr 是教学分支，它的使命是保存复现代码、问题分析和 Issue/PR 链接；官方 PR 必须来自你个人 Fork 上的独立主题分支。混用的直接后果是：教程历史里出现无关的框架文件，官方 PR 里出现教程文件，两边都难以审阅。单一目的的 PR 之所以重要，是因为它让 review 的每一分钟都花在同一件事上。

先判归属
再定分支
后补证据
末求合并

10、系统落地

原来有什么：我们有一个能跑通 LiveKit + AgentScope Java 的数字人 Demo，有一套基于 v2.0.3 的教程分支演进历史，也有能力读懂框架源码和测试。但遇到疑似框架问题时，团队的动作仍然是即兴的。

本篇新增什么：一条可复用的上游贡献闭环——复现目录规范、复现记录模板、四象限归属判断、v2.0.3 与 main 对比动作、Fork 与主题分支纪律、提交前检查命令、Conventional Commits 提交格式、以及教程仓库与官方分支的职责边界。这些产物都落在 chapter/15-open-source-pr 分支上。

现在能做什么：拿到一个疑似问题，你能独立完成“最小复现 → 查 Issue/PR → 判断上游归属 → Fork → 修改 → 测试 → 形成可提交 PR”的全流程；如果最终判定不是上游问题，你也能给出有据可依的结论，而不是一句“框架有问题”。

还缺什么：一是对 AgentScope Java 内部模块的深入程度，判断“该改哪里”仍需要更细的源码地图；二是与维护者的沟通经验，Issue 措辞、复现精简度、PR 描述的取舍都需要实战积累；三是当问题涉及并发、状态生命周期或多 Agent 协作时，最小复现的构造难度会显著上升。

下一步如何演进：把这套闭环作为横向检查点保留在后续每一式里——只有当复现确认真实、且 main 仍未修复、且官方没有记录时，才进入 Issue/PR，不硬造 Bug。真实贡献使用个人 Fork 的主题分支，不使用教程 chapter 分支直接充当官方 PR 分支。

开源参与点：本章未发现明确上游问题。本次演练采用官方 Issues 中现有的 good first issue 标签条目或文档改进路径完成流程闭环，具体条目需按官方 GitHub 当前状态现场核验，本文不声称已提交或已合并任何 Issue/PR。

仓库只存复现
PR 只放修改
链接串起两者
闭环才算完成

11、小结

Q1 → 归属判断靠证据：最小复现 + v2.0.3/main 对比 + 官方历史检索
Q2 → 先沟通再动手：非平凡改动先按 CONTRIBUTING 走 Issue，再 Fork 提 PR
Q3 → 判断错的代价可控：Issue 可关闭重来，PR 必须保证单一目的与可解释 diff
状态 → 完成一次“复现→检索→判断→Fork→修改→测试→可提交 PR”的完整演练

一问定归属
二问定版本
三问定分支
状态是闭环

12、作业

12.1 理解题：为什么“最小复现”是判断上游归属的第一步，而不是最后一步？

参考答案：因为归属判断的四个象限都依赖同一份东西——一个脱离业务上下文、能稳定触发的现象。没有最小复现，你无法区分“业务代码问题”和“框架问题”；也无法在 v2.0.3 与 main 上做同一件事的对比；更无法把问题写进 Issue 让别人复现。复现不是提交材料，它是判断工具。

12.2 实战题：在 chapter/15-open-source-pr 分支上建一个 repro/ 目录，按本文模板写一份复现记录，并说明你会用哪些检索词去官方 Issues、Pull requests、Discussions 三处搜索。

参考答案：目录结构建议为 repro/<问题短名>/README.md，内容至少包含环境、最小复现步骤、期望行为、实际行为、版本对比、检索结论、归属判断七个部分。检索词应由三个维度交叉组成：现象特征（报错类型或错误行为）、触发所需的 API 组合、版本号（v2.0.3）。不要只用异常字符串检索，因为相似异常可能来自完全不同的触发路径。

12.3 排障题：你复现了一个现象，v2.0.3 可复现，main 不可复现，但官方 Issues 里没有任何相关记录。此时应该怎么做？

参考答案：这属于“版本已修”象限，正确动作是升级到已修复的版本，或者如果暂时无法升级，在教程仓库里记录这条差异与影响面。不要针对已修复的旧版本行为提交新 Issue 或 PR，那会给维护者制造重复工作量。

12.4 架构判断题：请打开 https://github.com/agentscope-ai/agentscope-java/blob/main/CONTRIBUTING.md 与官方 Issues 列表，说明为什么教程仓库的 chapter/* 分支不能直接作为官方 PR 分支，并结合官方当前的 good first issue 条目判断本文演练路径是否成立。

参考答案：chapter/* 分支承载的是教程演进历史，包含 Demo 业务代码、复现工程、教学文档等多类文件；官方 PR 需要的是单一目的、最小 diff、包含单测与文档的修改。两者职责不同，混用会导致教程历史与上游仓库互相污染。是否采用 good first issue 演练路径，必须以官方 Issues 当前状态为准，逐条查看标签、描述和已有讨论，不能凭文章预设；本文写作时不预设任何具体条目，读者需现场核验。

理解考边界
实战考流程
排障考证据
架构考取舍

13、思考

回到本篇的核心冲突：遇到疑似框架问题，团队到底该不该上游。这一式的答案不是“该”，也不是“不该”，而是一套能自己给出答案的判断流程。

复现把怀疑变成现象，版本对比把现象变成坐标，历史检索把坐标变成归属，而 Fork、主题分支、单测和提交规范，把归属变成一次可以被别人审阅的修改。这四步里，只有最后一步是写代码。

所以本式的工程判断很朴素：在你还没有证据之前，不要动框架；在你有了证据之后，也不要顺便改别的。单一目的、可解释 diff、可运行测试，这三件事做到位，你的 PR 才有可能被合入。

“会用框架”和“能参与框架演进”的差别，就在于后者能把自己的问题，翻译成别人可以复现和审阅的证据。

一念辨边界
一证定归属
一改知取舍
一役见真章