docs(agents): 上游 PR 引入流程与台账

.agents/notes/upstream-pr-intake.md

@@ -0,0 +1,87 @@
+# 上游 PR 引入台账
+
+记录上游 `omdsh-dev/dsh-browser`（本文称「上游」）待导入本 fork `graydovee/dsh-browser`（「fork」）的 PR：判定、来源 SHA、落地 fork PR 与 merge SHA。流程见 `AGENTS.md`《上游 PR 引入流程》。
+
+判定取值：`adopt` / `adopt-partial` / `duplicate` / `reject` / `defer`。状态取值：`pending` / `open` / `merged` / `reverted` / `skipped`。
+
+## 台账
+
+| PR | 作者 | 判定 | 分支 | 源 SHA | fork PR | merge SHA | changelog | 状态 |
+|---|---|---|---|---|---|---|---|---|
+| [#92](https://github.com/omdsh-dev/dsh-browser/pull/92) 滚动内层容器 | @happinessisreal | adopt | `upstream/92-scroll-nested` | `a99933c` | - | - | `## latest` | pending |
+| [#125](https://github.com/omdsh-dev/dsh-browser/pull/125) 新窗口工具 | @zzalancelot | adopt | `upstream/125-open-window` | `2c12f81` | - | - | `## latest` | pending |
+| [#99](https://github.com/omdsh-dev/dsh-browser/pull/99) 发现路由 CORS | @PerryLink | adopt-partial（另需适配 fork 的发现信标） | `upstream/99-discovery-cors` | `fa39152` | - | - | `## latest` | pending |
+| [#110](https://github.com/omdsh-dev/dsh-browser/pull/110) 扩展 origin 白名单 | Toto Leung (@chintoleung) | adopt | `upstream/110-extension-origin-pin` | `a118d3a` | - | - | `## latest` | pending |
+
+已导入（历史）：[#111](https://github.com/omdsh-dev/dsh-browser/pull/111) 支付/密码字段多段自动填充掩码，merge `06f8179`（2026-10-19）。
+
+## 分诊判据
+
+- 价值：安全/正确性 > dsh 运行时兼容 > 新工具/能力 > 重构 > 纯文档；低价值 defer。
+- 重复度检测（每个候选都跑）：
+
+  ```sh
+  git log --oneline main -- <PR 触及的路径>
+  git cherry -v main origin/pr/<n>
+  git diff main...origin/pr/<n> -- <关键文件>
+  grep -n "<功能关键词>" CHANGELOG*.md
+  ```
+
+- 风险面：改 wire 协议 / manifest 权限 / 依赖 / 高权限工具 → 强制安全评审 + `node scripts/smoke-runtime.mjs`。
+- 无测试的 PR 不合入；由 fork 补 vitest，放在 `adapt(upstream)` 提交里并注明 based on #<n>。
+- 上游的 `0.2.0-rc.x` 写法统一改为本 fork 的 `0.2.1-rc.2`。
+- 与 fork 自研功能重叠的部分以上游最终版为准，删除 fork 等价实现，单独成一个收敛提交。
+
+## 命令清单
+
+先让上游 PR ref 可 fetch（一次性配置）：
+
+```sh
+git config --add remote.origin.fetch '+refs/pull/*/head:refs/remotes/origin/pr/*'
+git fetch origin
+```
+
+单个 PR 的导入流程：
+
+```sh
+n=92; slug=scroll-nested
+git checkout main && git fetch fork && git merge --ff-only fork/main
+git checkout -b upstream/$n-$slug main
+
+git log --oneline main..origin/pr/$n
+git cherry -v main origin/pr/$n
+
+git merge --no-ff origin/pr/$n -m "merge(upstream): #$n <title>" \
+  -m "Upstream-PR: https://github.com/omdsh-dev/dsh-browser/pull/$n
+Source: origin/pr/$n @ <sha>
+Author: <name> <email>"
+
+# 冲突/对齐 fork 契约：单独提交
+# git commit -m "adapt(upstream): #$n <适配说明>"
+
+pnpm run typecheck && pnpm run check:runtime && pnpm run test && pnpm run build
+# 触碰 wire/Host/工具契约或认证面时再加：
+# node scripts/smoke-runtime.mjs
+
+# changelog（中英各一条，含致谢）随本分支提交后再推
+
+git push -u git@github.com:graydovee/dsh-browser.git upstream/$n-$slug
+gh pr create -R graydovee/dsh-browser --base main --head upstream/$n-$slug \
+  --title "feat(upstream #$n): <摘要>" --body-file /tmp/pr-$n.md
+gh pr checks -R graydovee/dsh-browser --watch
+
+gh pr merge -R graydovee/dsh-browser <num> --merge --delete-branch \
+  --subject "merge(upstream): #$n <title>" \
+  --body "Upstream-PR: https://github.com/omdsh-dev/dsh-browser/pull/$n
+Source: origin/pr/$n @ <sha>
+Author: <name> <email>"
+
+git log -1 --format=%B $(gh pr view <num> -R graydovee/dsh-browser --json mergeCommit --jq .mergeCommit.oid)
+```
+
+## 边界与失败模式
+
+- 导入物不进 `omdsh-dev/dsh-browser`（PR #121）：那条分支继续只装 fork 自研功能。
+- 不回滚已合并的导入时用 `git revert -m 1 <merge sha>`，台账改 `reverted` 并写原因。
+- 上游日后合入同一 PR：因保留原 SHA 与作者，`git merge origin/main` 通常是干净的三方合并；异常时用 `git cherry -v origin/main main` 复核并记台账。
+- 上游若 rebase/squash 成新 SHA：内容通常仍自动合并，台账记复核结果。

AGENTS.md

@@ -96,6 +96,20 @@ powershell scripts/install.ps1          # 安装/升级（Windows）：同上，
 - `omdsh-dev/dsh-browser` 不要删除、改名或强推：它是 PR 的 head 分支；需要重整提交时改为在上面追加提交。
 - PR 的标题不列举具体功能（功能会持续增加，列不完），只说明性质与维护方式；具体功能由描述里的 changelog 摘要与逐条评论承载。
 - 上游恢复维护、PR 合入后，把上游 `main` 合回本仓库 `main`（同样走下面的 PR 流程），`omdsh-dev/dsh-browser` 分支再按下一轮功能重新积攒。
+- **例外**：导入上游 `omdsh-dev/dsh-browser` 的第三方 PR 不走这条通路，见下《上游 PR 引入流程》。
+
+### 上游 PR 引入流程
+
+上游停更期间，把上游待合入 PR 搬进本 fork 时，只落 fork `main`，**不进 `omdsh-dev/dsh-browser` 承载分支**——那条分支继续只装 fork 自研功能，避免把别人的工作打包回上游。入口是 fork 内 PR：CI 门禁、公开可审计记录、原作者可见的反向链接、按 PR 回滚，四件事一次拿到。
+
+- **一上游 PR 一 fork PR**：分支 `upstream/<n>-<slug>` 从当前 `main` 切出，base 为 `graydovee/dsh-browser:main`；标题写成 `feat|fix(upstream #<n>): <摘要>`。
+- **只允许 merge commit**：用 `git merge --no-ff` 保留原作者与原始 SHA；禁止 squash 与 rebase（rebase 会让上游日后合入同一 PR 时产生重复提交）。
+- **冲突单独成适配提交**：`adapt(upstream): #<n> <说明>`，不重写上游提交。`scripts/install.*`、`extensions/dsh-browser/src/panel/updates.ts`、版本号、`AGENTS.md`、CI 工作流、`CHANGELOG*` 一律保留 fork 版本；桥/扩展产品代码以上游为准，语义冲突手工合并；`pnpm-lock.yaml` 重新 `pnpm install` 生成，不手工合并。
+- **验证门禁**：`pnpm run typecheck && pnpm run check:runtime && pnpm run test && pnpm run build`；改动 wire/Host/工具契约或认证面的再跑 `node scripts/smoke-runtime.mjs`。上游 CI 红的不直接导入，先修好或 defer。
+- **changelog 随该 PR 提交**：中英各一条（见《CHANGELOG 规则》），条目末尾回填致谢。
+- **PR 正文首段固定**：原始 PR 链接、作者、`Source: origin/pr/<n> @ <sha>`、合并方式、适配说明；其余按 `.github/PULL_REQUEST_TEMPLATE.md` 填（概述/动机/改动内容/测试/影响范围）。
+- **合并后核对与登记**：`git log -1 --format=%B <merge sha>` 确认 `Upstream-PR:` / `Source:` / `Author:` trailer 保留，并在 `.agents/notes/upstream-pr-intake.md` 台账登记（判定、源 SHA、fork PR、merge SHA、changelog、状态）。
+- **不要做的事**：不替上游维护者关闭/合并 PR，不在上游仓库提交任何东西（可选的致谢评论除外），不改远端命名。
 
 ### `main` 分支保护
 
@@ -135,6 +149,7 @@ gh api -X DELETE repos/graydovee/dsh-browser/branches/main/protection
 - 按已发布版本分组（`## v0.x.y`，与 git tag 一致）；已打 tag 的段落冻结，永不新增条目。
 - 新条目只加在最上面的段落。下一个 tag 未定期间用 `## latest`（不存在就新建），发版后再把它改成 tag 名——不要提前猜版本号。
 - 打 tag / 重命名 `## latest` 时只做明确要求的机械步骤，不得自行增加、删除或改写条目内容；条目内容的修改需要显式请求。
+- **致谢尾注**：导入上游贡献者的改动时（见《上游 PR 引入流程》），条目在同一行末尾补尾注——中文 `（感谢 @handle）`，英文 `(thanks @handle)`；不另起条目，也不改写他人已发布的条目。
 - **语言归属与链接**：changelog 的语言版本跟随 README 约定，每个语言的 README 必须链接同语言的 changelog——英文 README 链 `CHANGELOG.md`，中文 README 链 `CHANGELOG.zh-CN.md`；子目录 README 用相对路径（`../../CHANGELOG.zh-CN.md`）。某个组件还没有 README 时，先补出中英两份 README，再在各自 README 中链接对应语言的 changelog。
 
 ## Deployment & Release Safety