@xixka/dsh-hub 0.4.11 → 0.4.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/lib/atomcode-auth.js +3 -3
  2. package/lib/atomcode-auth.js.map +1 -1
  3. package/lib/atomcode-credits.js +3 -3
  4. package/lib/atomcode-credits.js.map +1 -1
  5. package/lib/atomcode-product.d.ts +8 -0
  6. package/lib/atomcode-product.d.ts.map +1 -1
  7. package/lib/atomcode-product.js +10 -0
  8. package/lib/atomcode-product.js.map +1 -1
  9. package/lib/chromium-session.d.ts +102 -51
  10. package/lib/chromium-session.d.ts.map +1 -1
  11. package/lib/chromium-session.js +361 -147
  12. package/lib/chromium-session.js.map +1 -1
  13. package/lib/doubao-login.d.ts +0 -20
  14. package/lib/doubao-login.d.ts.map +1 -1
  15. package/lib/doubao-login.js +53 -17
  16. package/lib/doubao-login.js.map +1 -1
  17. package/lib/doubao-signin.d.ts +0 -32
  18. package/lib/doubao-signin.d.ts.map +1 -1
  19. package/lib/doubao-signin.js +21 -35
  20. package/lib/doubao-signin.js.map +1 -1
  21. package/lib/login.d.ts +7 -20
  22. package/lib/login.d.ts.map +1 -1
  23. package/lib/login.js +7 -21
  24. package/lib/login.js.map +1 -1
  25. package/lib/loomy-adapter.d.ts.map +1 -1
  26. package/lib/loomy-adapter.js +23 -7
  27. package/lib/loomy-adapter.js.map +1 -1
  28. package/lib/openai-compat.d.ts.map +1 -1
  29. package/lib/openai-compat.js +6 -0
  30. package/lib/openai-compat.js.map +1 -1
  31. package/lib/raccoon-account-queue.d.ts +15 -0
  32. package/lib/raccoon-account-queue.d.ts.map +1 -0
  33. package/lib/raccoon-account-queue.js +59 -0
  34. package/lib/raccoon-account-queue.js.map +1 -0
  35. package/lib/raccoon-adapter.d.ts +3 -0
  36. package/lib/raccoon-adapter.d.ts.map +1 -1
  37. package/lib/raccoon-adapter.js +226 -190
  38. package/lib/raccoon-adapter.js.map +1 -1
  39. package/package.json +1 -1
@@ -554,8 +554,23 @@ function windowsBrowserCandidates(env, home,
554
554
  */
555
555
  exists = existsSync) {
556
556
  const localAppData = env.LOCALAPPDATA ?? '';
557
- const programFiles = env.PROGRAMFILES ?? '';
558
- const programFilesX86 = env['PROGRAMFILES(X86)'] ?? '';
557
+ /**
558
+ * ⚠️ PROGRAMFILES / PROGRAMFILES(X86) 缺失时给**标准默认值**(PR-A 随豆包收编补):
559
+ *
560
+ * 旧实现 `env.PROGRAMFILES ?? ''` 会在变量被清掉(沙箱 / 被改写的异常环境)时
561
+ * 拼出 `Google\Chrome\Application\chrome.exe` 这种**相对路径** —— isAbsolute
562
+ * 过滤后这条腿**恒不可能命中**。豆包收编前它的私有链一直是
563
+ * `env['ProgramFiles'] ?? 'C:\\Program Files'`(带默认值),收编后这份语义
564
+ * 必须进共享链,否则「env 缺失 + Chrome 装在标准位置」的机器上豆包的
565
+ * 解析结果会从 legacy 漂成 undefined(存量契约,见
566
+ * `tests/unit/doubao-browser-discovery.spec.ts`「存量候选链逐字节不变」)。
567
+ *
568
+ * ⚠️ `localAppData` **刻意不给默认值**:`browserCandidates` 头部「坑 1」的
569
+ * 回归判据(`zcode-browser-detection.spec.ts`「相对路径候选确实存在」)
570
+ * 靠它锁住「空环境 ⇒ 相对路径 ⇒ 被 isAbsolute 挡掉」这条防线。
571
+ */
572
+ const programFiles = env.PROGRAMFILES ?? 'C:\\Program Files';
573
+ const programFilesX86 = env['PROGRAMFILES(X86)'] ?? 'C:\\Program Files (x86)';
559
574
  const scoopRoot = scoopRootFromPath(env, exists);
560
575
  const defaultScoopRoot = join(home, 'scoop');
561
576
  /**
@@ -700,6 +715,119 @@ function linuxBrowserCandidates(home) {
700
715
  posix.join(home, '.local', 'share', 'flatpak', 'exports', 'bin', 'org.chromium.Chromium'),
701
716
  ];
702
717
  }
718
+ /**
719
+ * 从 Windows 注册表取**系统默认浏览器**的可执行文件路径(一处定义,多方复用)。
720
+ *
721
+ * ## 为什么搬到共享层(PR-A,2026-11-18)
722
+ *
723
+ * 原实现长在 `src/login.ts`(无痕开窗用);后来「浏览器登录候选链」这条线
724
+ *(`browserCandidates`,六个登录模块共用)发现一个缺口:**用户默认浏览器
725
+ * 不在候选链里**(360 / QQ / 便携 Chrome 等),最后落到的反而是 Edge 兜底。
726
+ * 注册表是默认浏览器的唯一真相源 ⇒ 这份读取必须在共享层**只定义一次**
727
+ *(`login.ts` 的无痕开窗与本候选链共用同一份,不再抄第二份 ——
728
+ * 「一文件两套同义判据」的反模式见 `docs/agent-notes/misc.md`)。
729
+ *
730
+ * 读法:`UrlAssociations\https\UserChoice` 拿 ProgId,再读该 ProgId 的
731
+ * `shell\open\command`(ProgId 可能注册在 HKCR / HKCU / HKLM 三处,逐个试)。
732
+ *
733
+ * @returns 可执行文件路径;非 Windows / 读不到 / 文件不存在时 `undefined`
734
+ *(调用方静默落回后续候选,**不报错**)。
735
+ */
736
+ let defaultBrowserExecutableCache = null;
737
+ export function defaultBrowserExecutable() {
738
+ if (process.platform !== 'win32')
739
+ return undefined;
740
+ // ⚠️ 进程内 memo:注册表在进程生命周期内不会漂;`browserCandidates()`
741
+ // 每次解析都会走到这里,不能让每次都付两次 `reg query` 的子进程成本。
742
+ if (defaultBrowserExecutableCache !== null)
743
+ return defaultBrowserExecutableCache;
744
+ const resolved = queryDefaultBrowserExecutable();
745
+ defaultBrowserExecutableCache = resolved ?? null;
746
+ return resolved;
747
+ }
748
+ function queryDefaultBrowserExecutable() {
749
+ // ⚠️ 只用 `reg.exe` 而不引第三方依赖:注册表读取是本功能唯一的平台相关调用,
750
+ // 为它加一个 native 依赖不划算(且本插件的 peer 约束不允许)。
751
+ const query = (key, value) => {
752
+ try {
753
+ const out = execFileSync('reg', ['query', key, '/v', value], {
754
+ encoding: 'utf8', timeout: 5000, windowsHide: true,
755
+ });
756
+ // 形如:` ProgId REG_SZ 360ChromeXURL`
757
+ const m = /REG_SZ\s+(.+?)\s*$/m.exec(out);
758
+ return m?.[1]?.trim();
759
+ }
760
+ catch {
761
+ return undefined;
762
+ }
763
+ };
764
+ const progId = query('HKCU\\SOFTWARE\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\https\\UserChoice', 'ProgId');
765
+ if (progId === undefined || progId.length === 0)
766
+ return undefined;
767
+ // ⚠️ 三个位置都要试:`UserChoice` 的 ProgId 可能只注册在 HKCR(合并视图)
768
+ // 或 HKCU\Software\Classes(用户级安装,本机 360 就是这种)。
769
+ for (const root of [
770
+ `HKCR\\${progId}\\shell\\open\\command`,
771
+ `HKCU\\SOFTWARE\\Classes\\${progId}\\shell\\open\\command`,
772
+ `HKLM\\SOFTWARE\\Classes\\${progId}\\shell\\open\\command`,
773
+ ]) {
774
+ try {
775
+ const out = execFileSync('reg', ['query', root, '/ve'], {
776
+ encoding: 'utf8', timeout: 5000, windowsHide: true,
777
+ });
778
+ // 形如:` (Default) REG_SZ "C:\...\360ChromeX.exe" -- "%1"`
779
+ const m = /REG_SZ\s+(.+?)\s*$/m.exec(out);
780
+ const raw = m?.[1];
781
+ if (raw === undefined)
782
+ continue;
783
+ // 取命令行里的**第一个**被引号包裹的路径;没有引号则取到第一个空格前。
784
+ const quoted = /^"([^"]+)"/.exec(raw);
785
+ const exe = quoted?.[1] ?? raw.split(' ')[0];
786
+ if (exe !== undefined && exe.length > 0 && existsSync(exe))
787
+ return exe;
788
+ }
789
+ catch { /* 试下一个位置 */ }
790
+ }
791
+ return undefined;
792
+ }
793
+ /**
794
+ * 「系统默认浏览器」档的 **chromium 内核判据**(静态,零成本)。
795
+ *
796
+ * ⚠️⚠️ 为什么是**allowlist(白名单)而不是 denylist**:
797
+ *
798
+ * - 默认浏览器可能是 Firefox(Gecko)/ Waterfox 乃至任何壳。把未知名字当
799
+ * chromium 收进候选 ⇒ spawn 一个不吃 chromium 参数的进程,失败形态更迷惑。
800
+ * - 反方向(把 360Chrome 误判成非 chromium ⇒ 跳过该档)只是**落回现状**
801
+ * (Edge 兜底),零回归。
802
+ * - 任务约束「优先静态判据」:spawn `--version` 探测有启动成本(且对
803
+ * Chrome++ 这类中继 launcher 还会得到**误导性**应答),只在名字确实认不出
804
+ * 时才值得 —— 而本判据的语义正是「认不出就跳过」。
805
+ *
806
+ * 判据用 `basename`(大小写不敏感):对 `Microsoft\Edge\…`、scoop 布局、
807
+ * 便携版目录都成立;macOS 的无扩展名二进制(`Google Chrome` / `Microsoft Edge`)
808
+ * 也一并覆盖(与 {@link isEdgeExecutable} 的命名口径一致)。
809
+ */
810
+ const CHROMIUM_FAMILY_EXECUTABLE_BASENAMES = new Set([
811
+ 'chrome.exe',
812
+ 'new_chrome.exe',
813
+ 'chromium.exe',
814
+ 'msedge.exe',
815
+ 'brave.exe',
816
+ 'vivaldi.exe',
817
+ 'opera.exe',
818
+ 'google chrome',
819
+ 'chromium',
820
+ 'microsoft edge',
821
+ 'brave browser',
822
+ // 国内第三方 chromium 内核(Chrome++ 生态的常见宿主)。
823
+ '360chrome.exe',
824
+ '360chromex.exe',
825
+ '360chromeenterprise.exe',
826
+ 'qqbrowser.exe',
827
+ ]);
828
+ export function isChromiumFamilyExecutable(executable) {
829
+ return CHROMIUM_FAMILY_EXECUTABLE_BASENAMES.has(basename(executable).toLowerCase());
830
+ }
703
831
  /**
704
832
  * 浏览器可执行文件的**候选链**(按优先级,`ZCODE_CHROME_PATH` 恒排第一)。
705
833
  *
@@ -740,6 +868,22 @@ export function browserCandidates(input = {}) {
740
868
  const platform = input.platform ?? process.platform;
741
869
  const env = input.env ?? process.env;
742
870
  const home = input.home ?? homedir();
871
+ /**
872
+ * ★ 「系统默认浏览器」档(PR-A):只参与 **win32** 分支。
873
+ *
874
+ * - 默认浏览器是 Windows 注册表概念;macOS / Linux 各自的「默认浏览器」
875
+ * 机制(LaunchServices / xdg-settings)不共享这份读取,也不在本档范围。
876
+ * - 注册表读不到 / 非 chromium 内核(Firefox 等)⇒ 静默落回后续候选,
877
+ * 零行为变化。
878
+ * - ⚠️ 内核判据在 {@link isChromiumFamilyExecutable}(静态白名单,一处定义)。
879
+ */
880
+ const defaultBrowserTier = [];
881
+ if (platform === 'win32') {
882
+ const resolved = (input.defaultBrowser ?? defaultBrowserExecutable)();
883
+ if (resolved !== undefined && resolved.length > 0 && isChromiumFamilyExecutable(resolved)) {
884
+ defaultBrowserTier.push(resolved);
885
+ }
886
+ }
743
887
  let candidates;
744
888
  if (platform === 'darwin') {
745
889
  candidates = macBrowserCandidates(home);
@@ -749,41 +893,36 @@ export function browserCandidates(input = {}) {
749
893
  }
750
894
  else {
751
895
  candidates = windowsBrowserCandidates(env, home, input.exists ?? existsSync);
896
+ /**
897
+ * 插入位置:**Brave 之后、Edge 兜底之前**(定位用 `isEdgeExecutable`,
898
+ * Edge 三条是链尾 ⑦ 档)。位置语义:Edge 是最后一道兜底,而「默认浏览器」
899
+ * 是用户亲口指定的意愿,理应压过 Edge;但任何**已知的通用 chromium 安装
900
+ * 位置**(scoop / Chrome / Chromium / Brave 的标准位置)都比「用户碰巧把
901
+ * 默认设成了什么」更可预期,不该被它压过 —— 这正是本缺陷(默认浏览器
902
+ * 不被认、落到 Edge)要修的那一格。
903
+ *
904
+ * ⚠️ 去重:默认浏览器可能就是链里已有的那条(最常见:默认 = Edge)。
905
+ * 重复入链不会改变解析结果(先到先得),只会让「已尝试」清单把同一条
906
+ * 路径**列两遍** —— 用户以为扫了两个地方(IKQ4JN 文案审计的同型问题)。
907
+ */
908
+ const tier = defaultBrowserTier[0];
909
+ if (tier !== undefined && !candidates.some((c) => winPathEquals(c, tier))) {
910
+ const firstEdge = candidates.findIndex((c) => isEdgeExecutable(c));
911
+ candidates.splice(firstEdge === -1 ? candidates.length : firstEdge, 0, tier);
912
+ }
752
913
  }
753
914
  /**
754
- * ★ 「头部队列」按最终优先级从高到低组装后整体前插:
755
- *
756
- * ① 渠道专属候选(`extraCandidates`,如豆包的专用覆盖档);
757
- * ② `ZCODE_CHROME_PATH`(原恒排第一,对不传 `extraCandidates` 的调用方
758
- * 语义**逐字不变**);
759
- * ③ 系统默认浏览器档(2026-11-18 新增:用户在系统里选定的浏览器理应
760
- * 优先于我们瞎猜的安装位置 —— 候选链原先完全不认它,前面档位全未命中
761
- * 时只能落到 Edge,用户报障「明明默认浏览器是 X 却给我开 Edge」)。
915
+ * ⚠️ 渠道专属候选排在环境变量覆盖**之后**、通用链之前(顺序契约见
916
+ * `channelCandidates` 入口注释);多条时保持调用方给定的相对顺序。
762
917
  */
763
- const head = [];
764
- for (const extra of input.extraCandidates ?? []) {
765
- if (extra.length > 0)
766
- head.push(extra);
767
- }
768
- const override = env.ZCODE_CHROME_PATH;
918
+ const channelCandidates = (input.channelCandidates ?? []).filter((channel) => channel.length > 0);
919
+ if (channelCandidates.length > 0)
920
+ candidates.unshift(...channelCandidates);
921
+ const override = env[input.overrideEnvName ?? 'ZCODE_CHROME_PATH'];
769
922
  if (typeof override === 'string' && override.trim().length > 0) {
770
- head.push(override.trim());
771
- }
772
- if (platform === 'win32'
773
- /**
774
- * ⚠️ **只在「真环境」或「显式注入了解析器」时探测注册表**:
775
- * 注入 `env` 的既有用例不触发真实 `reg.exe` 查询(保持跨平台确定性,
776
- * 否则 Windows 开发机上跑单测会读本机真实注册表 ⇒ 不可复现的红);
777
- * 生产入口(`findBrowserExecutable()` 无参调用)不注入 `env` ⇒ 正常探测。
778
- */
779
- && (input.defaultBrowser !== undefined || input.env === undefined)) {
780
- const resolveDefault = input.defaultBrowser ?? defaultBrowserExecutable;
781
- const exe = resolveDefault();
782
- // Firefox 等非 chromium 默认浏览器:跳过该档、落回后续(不报错)。
783
- if (exe !== undefined && !isNonChromiumExecutable(exe))
784
- head.push(exe);
923
+ candidates.unshift(override.trim());
785
924
  }
786
- return [...head, ...candidates];
925
+ return candidates;
787
926
  }
788
927
  /**
789
928
  * 在候选链里挑第一个**存在**的绝对路径。
@@ -919,102 +1058,6 @@ export function isEdgeExecutable(executable) {
919
1058
  const name = basename(executable).toLowerCase();
920
1059
  return name === 'msedge.exe' || name === 'microsoft edge';
921
1060
  }
922
- /**
923
- * 从 Windows 注册表取**系统默认浏览器**的可执行文件路径。
924
- *
925
- * ## 为什么搬到这里(2026-11-18,原在 `src/login.ts`)
926
- *
927
- * 它原本只服务「无痕开窗」(`openIncognitoWindow` 要绕过 `cmd /c start`
928
- * 以附加 `--incognito`)。本次修「候选链不认系统默认浏览器」时,候选链
929
- * {@link browserCandidates} 也需要它 —— 同一份注册表读取**不允许出现第二份**
930
- * (`AGENTS.md`:「一文件两套同义判据」反模式),故整段搬到浏览器设施模块,
931
- * `login.ts` 转为 import + re-export(既有 import `src/login.js` 的用例不动)。
932
- *
933
- * 读法:`UrlAssociations\https\UserChoice` 拿 ProgId,再读该 ProgId 的
934
- * `shell\open\command`(用户装的可能是 Chrome / Edge / 360 / Firefox,
935
- * 路径各不相同,不能硬编码)。
936
- *
937
- * ⚠️ 只用 `reg.exe` 而不引第三方依赖:注册表读取是本功能唯一的平台相关调用,
938
- * 为它加一个 native 依赖不划算(且本插件的 peer 约束不允许)。
939
- *
940
- * ⚠️ 非零 / 良性 stderr 输出一律按「读不到」处理(返回 `undefined`),
941
- * 不得据此断言「用户没有默认浏览器」或污染日志 —— 最多四轮、每轮 5 秒超时,
942
- * 代价有界。
943
- *
944
- * @returns 可执行文件路径;读不到时 `undefined`(调用方静默落回既有候选链)。
945
- */
946
- export function defaultBrowserExecutable() {
947
- if (process.platform !== 'win32')
948
- return undefined;
949
- const query = (key, value) => {
950
- try {
951
- const out = execFileSync('reg', ['query', key, '/v', value], {
952
- encoding: 'utf8', timeout: 5000, windowsHide: true,
953
- });
954
- // 形如:` ProgId REG_SZ 360ChromeXURL`
955
- const m = /REG_SZ\s+(.+?)\s*$/m.exec(out);
956
- return m?.[1]?.trim();
957
- }
958
- catch {
959
- return undefined;
960
- }
961
- };
962
- const progId = query('HKCU\\SOFTWARE\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\https\\UserChoice', 'ProgId');
963
- if (progId === undefined || progId.length === 0)
964
- return undefined;
965
- // ⚠️ 三个位置都要试:`UserChoice` 的 ProgId 可能只注册在 HKCR(合并视图)
966
- // 或 HKCU\Software\Classes(用户级安装,本机 360 就是这种)。
967
- for (const root of [
968
- `HKCR\\${progId}\\shell\\open\\command`,
969
- `HKCU\\SOFTWARE\\Classes\\${progId}\\shell\\open\\command`,
970
- `HKLM\\SOFTWARE\\Classes\\${progId}\\shell\\open\\command`,
971
- ]) {
972
- try {
973
- const out = execFileSync('reg', ['query', root, '/ve'], {
974
- encoding: 'utf8', timeout: 5000, windowsHide: true,
975
- });
976
- // 形如:` (Default) REG_SZ "C:\...\360ChromeX.exe" -- "%1"`
977
- const m = /REG_SZ\s+(.+?)\s*$/m.exec(out);
978
- const raw = m?.[1];
979
- if (raw === undefined)
980
- continue;
981
- // 取命令行里的**第一个**被引号包裹的路径;没有引号则取到第一个空格前。
982
- const quoted = /^"([^"]+)"/.exec(raw);
983
- const exe = quoted?.[1] ?? raw.split(' ')[0];
984
- if (exe !== undefined && exe.length > 0 && existsSync(exe))
985
- return exe;
986
- }
987
- catch { /* 试下一个位置 */ }
988
- }
989
- return undefined;
990
- }
991
- /**
992
- * 已知的**非 chromium 内核**浏览器文件名(Gecko / Goanna / Trident 家族)。
993
- *
994
- * ⚠️ 刻意用**黑名单**而不是白名单:chromium 生态的包装名数不过来(360、
995
- * QQ、搜狗、Brave、Opera、Vivaldi、豆包客户端……逐个枚举必漏),而 Windows
996
- * 上「默认浏览器非 chromium」的现实中只有这几个家族。判据打在**文件名**
997
- * (不区分大小写)上 —— 与 {@link isEdgeExecutable} 同一纪律:路径里搜
998
- * 子串会把 `…\Mozilla Firefox\…` 之外的巧合路径误伤。
999
- */
1000
- const NON_CHROMIUM_BASENAMES = new Set([
1001
- 'firefox', 'firefox.exe', 'waterfox', 'waterfox.exe',
1002
- 'librewolf', 'librewolf.exe', 'pale moon', 'pale moon.exe',
1003
- 'seamonkey', 'seamonkey.exe', 'iexplore.exe',
1004
- ]);
1005
- /**
1006
- * 该可执行文件是否**确定不是** chromium 内核(静态判据,零探测成本)。
1007
- *
1008
- * 用途:{@link browserCandidates} 的「系统默认浏览器」档只在**确属 chromium**
1009
- * 时入链 —— Firefox 等非 chromium 默认浏览器会被**跳过该档、落回后续候选**
1010
- * (不报错;那是用户的桌面选择,不是部署错误)。
1011
- *
1012
- * ⚠️ 返回 `false` 只代表「没认出是已知的非 chromium」,不代表「确属 chromium」:
1013
- * 未知包装名一律放行(本仓库候选链本来也只敢保「chromium 系可用」这一层)。
1014
- */
1015
- export function isNonChromiumExecutable(executable) {
1016
- return NON_CHROMIUM_BASENAMES.has(basename(executable).toLowerCase());
1017
- }
1018
1061
  /** 尽力删除临时目录(失败无妨,系统会回收临时目录)。 */
1019
1062
  function safeRemoveDir(dir) {
1020
1063
  try {
@@ -1637,6 +1680,29 @@ export class ChromiumSession {
1637
1680
  * 否则「浏览器秒退」要白等满 `readyTimeoutMs`(默认 30 秒)才报错。
1638
1681
  */
1639
1682
  spawnFailure;
1683
+ /**
1684
+ * ★ 中继形态(Chrome++ 等,PR-B / 旧仓 P25):spawn 的外层 exe 已以
1685
+ * `code=0` 自行退出,但它拉起的真实 chromium 可能仍在 `--remote-debugging-port`
1686
+ * 上就绪(见 `'exit'` 监听处的时序说明)。
1687
+ *
1688
+ * `true` = 已观察到外层 exe 的 code=0 退出 ⇒ 会话的生死**不再**以外层 exe
1689
+ * 为准,改为以「接续的真实例」为准(`relayGone` / `relayPid`)。
1690
+ */
1691
+ relayExit = false;
1692
+ /**
1693
+ * 接续的真实例也没了(CDP ws 关闭/出错,或主动 `kill()`)。
1694
+ *
1695
+ * ⚠️ 只在 `relayExit` 时参与 {@link exited} 判据 —— 正常形态下 `child` 的
1696
+ * `'exit'` 事件就是唯一判据,再挂 ws 监听就成了「一套性质两处判据」。
1697
+ */
1698
+ relayGone = false;
1699
+ /**
1700
+ * 接续的真实例主进程 pid(尽力而为捕获:`System.getProcessInfo`)。
1701
+ *
1702
+ * 外层 exe 已死 ⇒ `killProcessTree()` 对 `this.child` 打空;清理真实例
1703
+ * 要靠这个 pid(`taskkill /T /F` / 进程组),拿不到时退回 `Browser.close`。
1704
+ */
1705
+ relayPid;
1640
1706
  log;
1641
1707
  constructor(options = {}) {
1642
1708
  this.options = options;
@@ -1650,9 +1716,14 @@ export class ChromiumSession {
1650
1716
  get debugPort() {
1651
1717
  return this.port;
1652
1718
  }
1653
- /** 浏览器主进程 pid(清理与诊断用)。 */
1719
+ /**
1720
+ * 浏览器主进程 pid(清理与诊断用)。
1721
+ *
1722
+ * ⚠️ 中继形态下 `child` 已死:回落到捕获到的 `relayPid`(可能仍是
1723
+ * `undefined` —— `System.getProcessInfo` 是异步尽力而为)。
1724
+ */
1654
1725
  get pid() {
1655
- return this.child?.pid;
1726
+ return this.child?.pid ?? this.relayPid;
1656
1727
  }
1657
1728
  /**
1658
1729
  * 本次会话的临时 profile 目录(即传给 chromium 的 `--user-data-dir`)。
@@ -1676,10 +1747,17 @@ export class ChromiumSession {
1676
1747
  * 监听只在**它自己**退出时同时满足这两条(主动 `kill()` 会先把 `child` 置空,
1677
1748
  * 那一刻 `spawnFailure` 仍是 `undefined`;启动前两者也都为空)。
1678
1749
  *
1750
+ * ⚠️ **中继形态(PR-B / P25)**:外层 exe 本来就会 code=0 秒退,它的生死
1751
+ * 不再是会话的生死 ⇒ 改判「接续的真实例也没了」(`relayGone`:CDP ws
1752
+ * 关闭/出错,含用户自己关掉真实浏览器窗口)。用户关窗时真实例进程树
1753
+ * 退出,CDP ws 随之断开 —— 两个事件近同时发生,判据等价。
1754
+ *
1679
1755
  * 用途:登录类流程(`magicrew-browser-login.ts`)据它**提前**结束等待 ——
1680
1756
  * 用户关窗后若还耗满 4 分钟预算,用户看到的是「明明关掉了却还在转圈」。
1681
1757
  */
1682
1758
  get exited() {
1759
+ if (this.relayExit)
1760
+ return this.relayGone;
1683
1761
  return this.child === undefined && this.spawnFailure !== undefined;
1684
1762
  }
1685
1763
  /**
@@ -1769,8 +1847,14 @@ export class ChromiumSession {
1769
1847
  /**
1770
1848
  * 每次启动都是一次全新的尝试:上一次的失败原因必须清掉,
1771
1849
  * 否则上一轮「浏览器起不来」会让后续**所有**轮次秒失败。
1850
+ *
1851
+ * ⚠️ 中继形态的三个标记同样要清(PR-B):上一轮的 code=0 退出
1852
+ * 不许影响这一轮的判死路径。
1772
1853
  */
1773
1854
  this.spawnFailure = undefined;
1855
+ this.relayExit = false;
1856
+ this.relayGone = false;
1857
+ this.relayPid = undefined;
1774
1858
  this.profileDir = mkdtempSync(join(tmpdir(), this.options.profilePrefix ?? 'chromium-session-'));
1775
1859
  /**
1776
1860
  * ★ **必须挑一个确实空闲的端口**(真实缺陷)。
@@ -1791,7 +1875,13 @@ export class ChromiumSession {
1791
1875
  */
1792
1876
  this.port = this.options.debugPort ?? await pickFreePort();
1793
1877
  const hide = this.options.hideWindow !== false;
1794
- this.child = spawn(executable, [
1878
+ /**
1879
+ * ⚠️ 经 `spawnImpl` 注入口起进程(PR-B):缺省就是 `spawn`,行为逐字不变;
1880
+ * spec 用它注入假 `ChildProcess` 驱动真实 `launch()` 流程(见
1881
+ * `ChromiumSessionOptions.spawnImpl` 的注释)。
1882
+ */
1883
+ const spawnBrowser = this.options.spawnImpl ?? spawn;
1884
+ this.child = spawnBrowser(executable, [
1795
1885
  `--remote-debugging-port=${this.port}`,
1796
1886
  `--user-data-dir=${this.profileDir}`,
1797
1887
  '--no-first-run',
@@ -1883,25 +1973,53 @@ export class ChromiumSession {
1883
1973
  ? `signal=${signal}`
1884
1974
  : `code=${String(code)}`;
1885
1975
  /**
1886
- * ## ⚠️⚠️ `code=0` 也算「起不来」(Gitee issue IKQ4JN 的实测坑)
1976
+ * ## ⚠️⚠️ `code=0` 的双面性(Gitee issue IKQ4JN 实测 → PR-B / 旧仓 P25 修)
1887
1977
  *
1888
1978
  * 有人用 **Chrome++ 之类的封装 exe**(如 `D:\…\Chrome\App\Chrome.exe`):
1889
- * 外层 exe 会**在 9ms 内以 exit code 0 正常退出**,然后拉起一个独立进程。
1979
+ * 外层 exe 会**在 9ms 内以 exit code 0 正常退出**,然后拉起一个独立进程
1980
+ *(真实 chromium,带着我们传的 `--remote-debugging-port` 与
1981
+ * `--user-data-dir`)。实测表象极具误导性:CDP `/json/version`
1982
+ * **517ms 就绪、端口完全正常**,而这里判 `code=0`。
1983
+ *
1984
+ * 原实现「判失败」的理由(保留在此,作为权衡记录):继续用一个
1985
+ * **已经死了的** `this.child` 会让 `killProcessTree` 打空、真实例泄漏。
1986
+ * 但代价是**浏览器明明跑着却被判死** —— 用户看到
1987
+ * 「浏览器进程异常退出(code=0)」(超级麦吉扫码登录的真实报障形态),
1988
+ * 而 CDP 马上就会就绪。
1890
1989
  *
1891
- * 实测表象极具误导性:CDP `/json/version` **517ms 就绪、端口完全正常**,
1892
- * 而这里判 `code=0`。若按「退出码 0 = 正常」放行,就会继续用一个
1893
- * **已经死了的** `this.child`(`killProcessTree` 打空、真实例泄漏);
1894
- * 若按「异常退出」处理,则**浏览器明明跑着却被判死**。
1990
+ * ⇒ PR-B 的修法:**code=0 不再立刻判死**,改为「在 `readyTimeoutMs` 内
1991
+ * 等真实例」:
1992
+ * - 端口出现真实例(且端口校验通过)→ **接续**:会话改以 CDP 通道为准
1993
+ * (`captureRelayPid` 捕获真实主进程 pid,`kill()` 用它 + `Browser.close`
1994
+ * 清理 —— 打空/泄漏的原顾虑由这两处专门兜住);
1995
+ * - 超时仍无真实例 → 失败,文案沿用 `spawnFailure`(就是用户看到的那句,
1996
+ * 含「如 Chrome++」的括注);
1997
+ * - **非 0 退出**(含 signal)→ 仍然立刻失败(下面的轮询循环每轮先查
1998
+ * `spawnFailure`,`relayExit` 不拦它)。
1895
1999
  *
1896
- * ⇒ 当前选择后者(判失败)并**明确告知**用户换一个真浏览器:
1897
- * 泄漏整棵进程树比「误判一个非标准封装」严重得多。这条也解释了
1898
- * 为什么它属于**部署错误**(换浏览器就能好,重试没用)。
2000
+ * ⚠️ 这是把「立刻失败」**放宽**为「等真实例、超时才失败」,不是删保护:
2001
+ * 三条路径由 `tests/unit/chromium-relay-continuation.spec.ts` 锁死。
1899
2002
  */
1900
2003
  this.spawnFailure ??= new BrowserDeploymentError(`${label}: 浏览器进程异常退出(${executable},${how})` +
1901
2004
  `。请重试,或用 ${envName} 指定其它 chromium 内核浏览器。` +
1902
2005
  (code === 0
1903
2006
  ? '(退出码 0 = 该 exe 启动了别的进程后自行退出,属不支持的封装形态,如 Chrome++)'
1904
2007
  : ''), 'browser-spawn-failed');
2008
+ if (code === 0 && signal === null) {
2009
+ /**
2010
+ * ★ 中继形态:先记 `spawnFailure`(它同时是**超时路径**的文案),
2011
+ * 再翻 `relayExit` —— 轮询循环看到 `relayExit` 会**跳过**「每轮先查
2012
+ * spawnFailure」的立刻失败,继续等 CDP;`exited` 也改为以真实例为准。
2013
+ */
2014
+ this.relayExit = true;
2015
+ /**
2016
+ * 真实例可能**已经**在了(轮询循环早于 exit 事件连上的情形)——
2017
+ * 若是,立刻挂上「真实例没了」的监听(`exited` 判据)。
2018
+ */
2019
+ this.watchRelayDeath();
2020
+ return;
2021
+ }
2022
+ // 非 0 退出:spawnFailure 已就位,轮询循环下一轮立刻失败。
1905
2023
  });
1906
2024
  const timeoutMs = this.options.readyTimeoutMs ?? 30_000;
1907
2025
  const deadline = Date.now() + timeoutMs;
@@ -1911,8 +2029,12 @@ export class ChromiumSession {
1911
2029
  * ⚠️ **每轮先看 `spawnFailure`**:浏览器起不来 / 秒退时立刻失败,
1912
2030
  * 而不是白等满 `readyTimeoutMs`(默认 30 秒)才报一个含糊的「超时」。
1913
2031
  * 旧实现的用户体感就是「签到卡住半分钟然后失败」—— 根因就在这里。
2032
+ *
2033
+ * ⚠️ **中继形态(PR-B)例外**:`code=0` 退出时 `spawnFailure` 已就位
2034
+ *(那是超时路径的文案),但真实例可能还在路上 —— 跳过立刻失败,
2035
+ * 继续轮询;超时后由循环外的 `throw this.spawnFailure` 兜底。
1914
2036
  */
1915
- if (this.spawnFailure !== undefined) {
2037
+ if (this.spawnFailure !== undefined && !this.relayExit) {
1916
2038
  const failure = this.spawnFailure;
1917
2039
  this.kill();
1918
2040
  throw failure;
@@ -1967,6 +2089,22 @@ export class ChromiumSession {
1967
2089
  });
1968
2090
  this.ws = ws;
1969
2091
  this.cdp = new CdpConnection(ws);
2092
+ /**
2093
+ * ★ 中继形态的「接续」收尾(PR-B / P25):走到这里 = 真实例已在我们的
2094
+ * 端口上应答且端口校验通过 ⇒ **接续成功**。还差两件事:
2095
+ *
2096
+ * 1. `watchRelayDeath()`:真实例没了(ws close/error)要把 `exited` 翻真
2097
+ * —— magicrew 靠它「用户自己关了窗就别再等 4 分钟」。
2098
+ * (`exit` 监听里也调过它 —— 两种时序都覆盖:exit 先于 ws 建立 /
2099
+ * ws 先于 exit 建立。)
2100
+ * 2. `captureRelayPid()`:尽力捕获真实例主进程 pid(`System.getProcessInfo`),
2101
+ * `kill()` 才能杀到它(外层 exe 已死,`this.child` 打空)。不 await:
2102
+ * 失败不阻断接续(拿不到 pid 就靠 `Browser.close` + 目录重试兜底)。
2103
+ */
2104
+ if (this.relayExit) {
2105
+ this.watchRelayDeath();
2106
+ void this.captureRelayPid();
2107
+ }
1970
2108
  /**
1971
2109
  * ★ **把窗口从任务栏移除**(Windows / Linux / macOS 各一条路)。
1972
2110
  *
@@ -1977,10 +2115,47 @@ export class ChromiumSession {
1977
2115
  * (库库AI 的登录要让用户看见并自己操作)。
1978
2116
  *
1979
2117
  * ⚠ 不 await:这是装饰性优化,失败要静默,不能拖慢启动。
2118
+ *
2119
+ * ⚠ **中继形态下会跳过**(PR-B):`this.child` 是已死的外层 exe,
2120
+ * 它的 pid 藏不了真实例的窗口;`relayPid` 是异步尽力捕获的,此刻
2121
+ * 多半还没就位。代价只是任务栏图标可能闪一下(窗口本身仍被
2122
+ * `--window-position` 移到屏幕外 —— 参数传给了真实例)。
1980
2123
  */
1981
2124
  if (hide && this.child?.pid !== undefined)
1982
2125
  hideWindowFromTaskbar(this.child.pid, this.log);
1983
2126
  }
2127
+ /**
2128
+ * 中继形态:把「接续的真实例也没了」接到 {@link exited}。
2129
+ *
2130
+ * ⚠️ 只在 `relayExit` 时挂监听:正常形态下 `child` 的 `'exit'` 事件就是
2131
+ * `exited` 的唯一判据,再挂 ws 监听就成了「一套性质两处判据」。
2132
+ * 两个调用时机(都调,时序谁先都覆盖):`'exit'` 监听内(真实例可能
2133
+ * 已先就绪)、ws 建立后(exit 可能先发生)。
2134
+ */
2135
+ watchRelayDeath() {
2136
+ if (!this.relayExit || this.relayGone || this.ws === undefined)
2137
+ return;
2138
+ const onGone = () => { this.relayGone = true; };
2139
+ this.ws.addEventListener('close', onGone, { once: true });
2140
+ this.ws.addEventListener('error', onGone, { once: true });
2141
+ }
2142
+ /**
2143
+ * 中继形态:尽力捕获真实例主进程 pid(CDP `System.getProcessInfo`)。
2144
+ *
2145
+ * 拿到 pid ⇒ `kill()` 的 `killProcessTree()` 能对真实例整棵树
2146
+ * `taskkill /T /F` / `kill(-pid)`;拿不到 ⇒ 退回 `Browser.close`(kill 里
2147
+ * 已先行发出)+ `dispose()` 的目录删除重试。失败一律吞掉 ——
2148
+ * 接续会话不能因诊断性探测失败而中断。
2149
+ */
2150
+ async captureRelayPid() {
2151
+ try {
2152
+ const info = await this.cdp?.send('System.getProcessInfo');
2153
+ const browser = info?.processInfo?.find((process) => process.type === 'browser');
2154
+ if (typeof browser?.pid === 'number')
2155
+ this.relayPid = browser.pid;
2156
+ }
2157
+ catch { /* 尽力而为:真实例不答 System 域就靠 Browser.close 兜底 */ }
2158
+ }
1984
2159
  /**
1985
2160
  * 终止浏览器进程**树**并清理所有 CDP 连接(**保留**临时 profile)。
1986
2161
  *
@@ -2005,6 +2180,24 @@ export class ChromiumSession {
2005
2180
  * Windows 用 `taskkill /T /F`(`/T` = 含子进程树)。
2006
2181
  */
2007
2182
  kill() {
2183
+ /**
2184
+ * ★ 中继形态的清理(PR-B / P25):外层 exe 已死,`killProcessTree()`
2185
+ * 对 `this.child` 打空 —— 真实例按优先级两路收:
2186
+ *
2187
+ * 1. **`relayPid`(权威路径)**:`captureRelayPid()` 捕获的真实主进程
2188
+ * pid,下面的 `killProcessTree()` 会对它整棵树 `taskkill /T /F` /
2189
+ * `kill(-pid)`(确定性:返回即已终止)。
2190
+ * 2. **CDP `Browser.close`(优雅路径,fire-and-forget)**:请真实例自己
2191
+ * 退出。随后的 `ws.close()` 可能让它发不出去 —— 所以 1 才是权威路径,
2192
+ * 这条只是 pid 捕获失败时的兜底(外加 `dispose()` 的目录删除重试)。
2193
+ */
2194
+ if (this.relayExit) {
2195
+ this.relayGone = true;
2196
+ try {
2197
+ void this.cdp?.send('Browser.close').catch(() => { });
2198
+ }
2199
+ catch { /* cdp 已关 */ }
2200
+ }
2008
2201
  try {
2009
2202
  this.cdp?.close();
2010
2203
  }
@@ -2037,9 +2230,29 @@ export class ChromiumSession {
2037
2230
  killProcessTree() {
2038
2231
  const child = this.child;
2039
2232
  this.child = undefined;
2040
- if (child === undefined || child.pid === undefined)
2233
+ if (child === undefined || child.pid === undefined) {
2234
+ /**
2235
+ * ★ 中继形态(PR-B / P25):外层 exe 已死,但接续的真实例还活着 ——
2236
+ * 用 `captureRelayPid()` 捕获的 `relayPid` 杀它的**整棵树**。
2237
+ * 拿不到 pid(真实例不答 System 域)⇒ 这里静默跳过,由 kill() 里已
2238
+ * 发出的 `Browser.close` + `dispose()` 的目录删除重试兜底。
2239
+ */
2240
+ const relayPid = this.relayPid;
2241
+ if (relayPid !== undefined)
2242
+ this.killPidTree(relayPid);
2041
2243
  return;
2042
- const pid = child.pid;
2244
+ }
2245
+ this.killPidTree(child.pid, child);
2246
+ }
2247
+ /**
2248
+ * 按 pid 终止浏览器及其**全部子进程**(树)。
2249
+ *
2250
+ * ⚠ 从 {@link killProcessTree} 抽出(PR-B):中继形态的 `relayPid` 与正常
2251
+ * 形态的 `child.pid` 需要**同一份**杀树判据 —— 抄两份必然分叉(方向恒定
2252
+ * 是「漏修的那份」,见本文件头部的缺陷表)。行为逐字沿用原实现:
2253
+ * `spawnSync`(同步)、`/T /F`、超时 10 秒、POSIX 进程组。
2254
+ */
2255
+ killPidTree(pid, child) {
2043
2256
  if (process.platform === 'win32') {
2044
2257
  /**
2045
2258
  * ⚠ Windows 没有进程组信号,用 `taskkill /T`(树)+ `/F`(强制)。
@@ -2055,23 +2268,24 @@ export class ChromiumSession {
2055
2268
  });
2056
2269
  }
2057
2270
  catch { /* 尽力而为 */ }
2058
- // 兜底:万一 taskkill 不可用,至少杀掉主进程。
2271
+ // 兜底:万一 taskkill 不可用,至少杀掉主进程(中继形态无 child,跳过)。
2059
2272
  try {
2060
- child.kill();
2273
+ child?.kill();
2061
2274
  }
2062
2275
  catch { /* 已退出 */ }
2063
2276
  return;
2064
2277
  }
2065
2278
  /**
2066
2279
  * POSIX:`detached: true` 时子进程自成进程组,负 pid 即整组。
2067
- * ⚠ 失败(ESRCH 等)就退回单进程 kill。
2280
+ * ⚠ 失败(ESRCH 等)就退回单进程 kill(中继形态无 child,跳过 ——
2281
+ * 真实例不是我们拉起的进程组成员,-pid 不成即视为已退出)。
2068
2282
  */
2069
2283
  try {
2070
2284
  process.kill(-pid, 'SIGKILL');
2071
2285
  }
2072
2286
  catch {
2073
2287
  try {
2074
- child.kill('SIGKILL');
2288
+ child?.kill('SIGKILL');
2075
2289
  }
2076
2290
  catch { /* 已退出 */ }
2077
2291
  }