@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/bin/gotry-bootstrap.js

@@ -75,16 +75,98 @@ const HBCLI_NPM_INSTALL_CMD = 'npm install -g staicli --registry=https://registr
 const HBCLI_INSTALL_CMD = HBCLI_NPM_INSTALL_CMD
 const REACH_INSTALL_URL = 'git+https://github.com/Panniantong/Agent-Reach.git'
 
-/** 带超时的子进程(inherit stdio 让用户看见上游安装进度) */
+let activeInstallerChild = null
+let activeInstallerGroupPid = null
+let installerSignalHandling = false
+const installerSignalListeners = new Map()
+const INSTALLER_TERM_GRACE_MS = 2_000
+const INSTALLER_KILL_WAIT_MS = 1_000
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const waitChildClose = (child, ms) => new Promise((resolve) => {
+  if (!child) { resolve(false); return }
+  let done = false
+  const finish = (value) => {
+    if (done) return
+    done = true
+    clearTimeout(timer)
+    child.off('close', onClose)
+    child.off('error', onError)
+    resolve(value)
+  }
+  const onClose = () => finish(true)
+  const onError = () => finish(true)
+  const timer = setTimeout(() => finish(false), ms)
+  child.once('close', onClose)
+  child.once('error', onError)
+})
+const signalInstallerChild = (child, signal, groupPid = null) => {
+  if (!child) return
+  if (process.platform !== 'win32' && groupPid) {
+    try { process.kill(-groupPid, signal); return } catch { /* fallback */ }
+  }
+  try { child.kill(signal) } catch { /* ignore */ }
+}
+const terminateInstallerChild = async (child, signal, groupPid = null, graceMs = INSTALLER_TERM_GRACE_MS, killMs = INSTALLER_KILL_WAIT_MS) => {
+  if (!child) return
+  signalInstallerChild(child, signal, groupPid)
+  const closed = await waitChildClose(child, graceMs)
+  if (closed) return
+  signalInstallerChild(child, 'SIGKILL', groupPid)
+  await waitChildClose(child, killMs)
+}
+const registerInstallerSignalForwarding = () => {
+  if (installerSignalListeners.size) return
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    const listener = () => {
+      if (installerSignalHandling) return
+      installerSignalHandling = true
+      void (async () => {
+        await terminateInstallerChild(activeInstallerChild, sig, activeInstallerGroupPid)
+        for (const [s, l] of installerSignalListeners) process.off(s, l)
+        installerSignalListeners.clear()
+        process.kill(process.pid, sig)
+        await wait(2_000)
+        process.exit(128 + (sig === 'SIGINT' ? 2 : 15))
+      })()
+    }
+    process.on(sig, listener)
+    installerSignalListeners.set(sig, listener)
+  }
+}
+const unregisterInstallerSignalForwarding = () => {
+  for (const [s, l] of installerSignalListeners) process.off(s, l)
+  installerSignalListeners.clear()
+  installerSignalHandling = false
+}
+
+/** 带超时的子进程(inherit stdio 让用户看见上游安装进度);POSIX 下用进程组约束 installer 子树 */
 function run(cmd, args, { timeoutMs, cwd, env } = {}) {
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, { stdio: 'inherit', cwd, env: env ?? process.env })
+    const detachedInstaller = process.platform !== 'win32'
+    const child = spawn(cmd, args, { stdio: 'inherit', cwd, env: env ?? process.env, detached: detachedInstaller })
+    activeInstallerChild = child
+    activeInstallerGroupPid = detachedInstaller ? child.pid : null
+    registerInstallerSignalForwarding()
     let done = false
-    const timer = setTimeout(() => {
-      if (!done) { done = true; try { child.kill('SIGKILL') } catch { /* ignore */ } }
+    let timer = null
+    const finish = (result) => {
+      if (done) return
+      done = true
+      if (timer) clearTimeout(timer)
+      activeInstallerChild = null
+      activeInstallerGroupPid = null
+      unregisterInstallerSignalForwarding()
+      resolve(result)
+    }
+    timer = setTimeout(() => {
+      void (async () => {
+        if (done) return
+        await terminateInstallerChild(child, 'SIGTERM', activeInstallerGroupPid)
+        finish({ ok: false, error: 'timeout' })
+      })()
     }, timeoutMs)
-    child.on('error', (e) => { if (!done) { done = true; clearTimeout(timer); resolve({ ok: false, error: e.message }) } })
-    child.on('exit', (code) => { if (!done) { done = true; clearTimeout(timer); resolve({ ok: code === 0, error: code === 0 ? undefined : `exit ${code}` }) } })
+    child.on('error', (e) => finish({ ok: false, error: e.message }))
+    child.on('close', (code, signal) => finish({ ok: code === 0, error: code === 0 ? undefined : signal ? `signal ${signal}` : `exit ${code}` }))
   })
 }
 
@@ -93,7 +175,9 @@ function probe(cmd, args, timeoutMs = 10_000) {
   return new Promise((resolve) => {
     const child = spawn(cmd, args, { stdio: 'ignore' })
     let done = false
-    const timer = setTimeout(() => { if (!done) { done = true; try { child.kill('SIGKILL') } catch { /* ignore */ } resolve(false) } }, timeoutMs)
+    const timer = setTimeout(() => {
+      if (!done) { done = true; try { child.kill('SIGKILL') } catch { /* ignore */ } resolve(false) }
+    }, timeoutMs)
     child.on('error', () => { if (!done) { done = true; clearTimeout(timer); resolve(false) } })
     child.on('exit', (code) => { if (!done) { done = true; clearTimeout(timer); resolve(code === 0) } })
   })
@@ -113,7 +197,8 @@ function parseVersion(v) {
 }
 
 function versionAtLeast(v, min) {
-  const a = parseVersion(v); const b = parseVersion(min)
+  // v 可能是 hbcliVersion 已解析的数组,也可能是原始字符串——两者都接受
+  const a = Array.isArray(v) ? v : parseVersion(v); const b = parseVersion(min)
   if (!a || !b) return false
   for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] > b[i] }
   return true
@@ -154,7 +239,7 @@ async function setupHbcli() {
   if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
   say(`  安装中(npm,staicli@npmjs): ${HBCLI_INSTALL_CMD}`)
   const r = await run('bash', ['-c', HBCLI_INSTALL_CMD], { timeoutMs: 120_000 })
-  if (!r.ok) { say(`  ✗ 安装失败(${r.error})——不影响 gotry,酒店检索将用内置静态包;可稍后重试: npx gotry setup`); return { ok: false } }
+  if (!r.ok) { say(`  ✗ 安装失败(${r.error})——不影响 gotry,酒店检索将用内置静态包;可稍后重试: npx @danceiny/gotry setup`); return { ok: false } }
   const binDir = join(homedir(), '.local/bin')
   if (!process.env.PATH.split(':').includes(binDir)) {
     say(`  ⚠ ${binDir} 不在当前 PATH —— gotry 工具已内建候选路径回退,无需手动处理;其他程序可用: export PATH="${binDir}:$PATH"`)
@@ -173,13 +258,13 @@ async function setupReach() {
   if (existsSync(venvBin)) { say('  ✓ 已安装(.venv)'); return { ok: true } }
   if (CHECK_ONLY) { say('  ✗ 未安装(--check-only 只报告)'); return { ok: true } }
   const hasPy = await probe('python3', ['--version'], 10_000)
-  if (!hasPy) { say('  ✗ 跳过:未找到 python3(agent-reach 需 Python 3;装好后重跑 npx gotry setup)'); return { ok: false } }
+  if (!hasPy) { say('  ✗ 跳过:未找到 python3(agent-reach 需 Python 3;装好后重跑 npx @danceiny/gotry setup)'); return { ok: false } }
   say(`  创建 .venv 并安装上游(${REACH_INSTALL_URL})`)
   const venv = await run('python3', ['-m', 'venv', join(repoRoot, '.venv')], { timeoutMs: 120_000 })
   if (!venv.ok) { say(`  ✗ venv 创建失败(${venv.error})——不影响 gotry,gotry_agent_reach 将返回 not-installed 指引`); return { ok: false } }
   const pip = join(repoRoot, '.venv/bin/pip')
   const inst = await run(pip, ['install', '-q', REACH_INSTALL_URL], { timeoutMs: 300_000 })
-  if (!inst.ok) { say(`  ✗ pip 安装失败(${inst.error})——可稍后重试: npx gotry setup`); return { ok: false } }
+  if (!inst.ok) { say(`  ✗ pip 安装失败(${inst.error})——可稍后重试: npx @danceiny/gotry setup`); return { ok: false } }
   say('  ✓ 安装完成(渠道凭证选配见 docs/tokens.md: .venv/bin/agent-reach configure --from-browser chrome --platform <渠道>)')
   return { ok: true }
 }
@@ -232,7 +317,7 @@ async function setupSidebar(attemptInstall) {  say('[gotry-setup] dsh-better-sid
     say('  ✓ 安装完成(npx 途径 exit 非 0,但按落盘状态复核已就位)')
     return { ok: true }
   }
-  say('  ✗ 安装失败——不影响 gotry:产物仍可在对话里说「看看我生成的行程」经 gotry_artifacts_list/read 查看;可稍后重试: npx gotry doctor --fix')
+  say('  ✗ 安装失败——不影响 gotry:产物仍可在对话里说「看看我生成的行程」经 gotry_artifacts_list/read 查看;可稍后重试: npx @danceiny/gotry doctor --fix')
   return { ok: false }
 }
 
@@ -243,6 +328,10 @@ async function setupSidebar(attemptInstall) {  say('[gotry-setup] dsh-better-sid
 
 const DOCTOR = process.argv.includes('doctor')
 const DOCTOR_FIX = process.argv.includes('--fix')
+// onboarding 子命令(issue #258):`gotry web` 启动前的显式可选能力配置 prompt——每次符合条件的
+// 启动评估一次、至多问一次,无跨启动持久确认。inner 以 `onboarding --result-file=…` 同步 inherit
+// 调用;`--scan` 只读查看计划(测试/调试)。
+const ONBOARDING = process.argv.includes('onboarding')
 // calendar 子命令(issue #106/D-9):可选日历挂载的 setup 状态管理面。
 // `gotry setup calendar`=开启;`--off`=关闭(删状态文件恢复默认);`--status`=只读查看。
 const CALENDAR_CMD = process.argv.includes('calendar')
@@ -276,12 +365,12 @@ async function runCalendar() {
     const state = readCalendarState()
     say(`  状态: ${calendarDetail(state)}`)
     say(`  状态文件: ${calendarStatePath()}`)
-    say('  说明: 挂载=`npx gotry setup calendar`;关闭=`npx gotry setup calendar --off`;配置在 dsh profile 的 cordis.patch.yml 覆盖 calendar 行 config 填 username')
+    say('  说明: 挂载=`npx @danceiny/gotry setup calendar`;关闭=`npx @danceiny/gotry setup calendar --off`;配置在 dsh profile 的 cordis.patch.yml 覆盖 calendar 行 config 填 username')
     return 0
   }
   if (CALENDAR_OFF) {
     try { rmSync(calendarStatePath()) } catch { /* 本就未开启 */ }
-    say('  ✓ 已关闭——恢复默认不挂载(状态文件已删除;如需再开: npx gotry setup calendar)')
+    say('  ✓ 已关闭——恢复默认不挂载(状态文件已删除;如需再开: npx @danceiny/gotry setup calendar)')
     return 0
   }
   mkdirSync(dirname(calendarStatePath()), { recursive: true })
@@ -317,7 +406,7 @@ async function doctorChecks() {
   const reachBin = join(repoRoot, '.venv/bin/agent-reach')
   const reachOk = existsSync(reachBin)
   const reachLevel = reachOk ? 'ok' : existsSync(venvPython) ? 'degraded' : 'missing'
-  items.push({ label: 'Agent Reach(网页/社媒读取)', ok: reachOk, level: reachLevel, detail: reachOk ? `已安装(${reachBin})` : reachLevel === 'degraded' ? '.venv 在但缺 agent-reach 包——gotry_agent_reach / gotry_web_search 读页会失败' : '未装配——gotry_agent_reach / gotry_web_search(读网页)/ gotry_video_subtitle / gotry_github_search 全部不可用', fix: reachOk ? undefined : 'npx gotry doctor --fix' })
+  items.push({ label: 'Agent Reach(网页/社媒读取)', ok: reachOk, level: reachLevel, detail: reachOk ? `已安装(${reachBin})` : reachLevel === 'degraded' ? '.venv 在但缺 agent-reach 包——gotry_agent_reach / gotry_web_search 读页会失败' : '未装配——gotry_agent_reach / gotry_web_search(读网页)/ gotry_video_subtitle / gotry_github_search 全部不可用', fix: reachOk ? undefined : 'npx @danceiny/gotry doctor --fix' })
   // hbcli(裸名靠 PATH 探测;绝对路径 existsSync;版本 < MIN_HBCLI_VERSION 视为 missing,见 issue #142)
   let hbBin = ''
   for (const p of ['hbcli', join(homedir(), '.local/bin/hbcli'), join(homedir(), '.staicli/current/hbcli')]) {
@@ -332,24 +421,25 @@ async function doctorChecks() {
       items.push({ label: 'hbcli(酒店实时源)', ok: whoami, level: whoami ? 'ok' : 'degraded', detail: whoami ? `已安装且凭证有效(${hbBin}, v${v ? v.join('.') : '?'})` : '二进制在,但凭证未配置/失效——酒店检索将降级静态包(非实时)', fix: whoami ? undefined : 'hbcli auth set-credentials --app-key hotelbyte_api_demo --app-secret hotelbyte_api_demo(快速试用沙箱;正式 key 向 HotelByte 申请)' })
     }
   } else {
-    items.push({ label: 'hbcli(酒店实时源)', ok: false, level: 'missing', detail: '未安装——酒店检索降级静态包(公开渠道估算,非实时,仅覆盖内置场景)', fix: 'npx gotry doctor --fix' })
+    items.push({ label: 'hbcli(酒店实时源)', ok: false, level: 'missing', detail: '未安装——酒店检索降级静态包(公开渠道估算,非实时,仅覆盖内置场景)', fix: 'npx @danceiny/gotry doctor --fix' })
   }
   // flyai key(匿名试用额度共享易达限;正式 key 即免)
   const flyaiKey = (process.env.FLYAI_API_KEY ?? '').trim()
   items.push({ label: 'FlyAI(飞猪官方检索)', ok: Boolean(flyaiKey), level: flyaiKey ? 'ok' : 'degraded', detail: flyaiKey ? 'FLYAI_API_KEY 已配(正式 key,无试用额度限制)' : '未配 FLYAI_API_KEY——走匿名试用额度(共享,易达限;达限报 "Trial limit reached")', fix: flyaiKey ? undefined : '到 flyai.open.fliggy.com 控制台申请正式 key,配进环境变量 FLYAI_API_KEY' })
   // sidebar(状态面与 setupSidebar 的落盘复核同一口径)
   const sbOk = sidebarInstalled()
-  items.push({ label: 'dsh-better-sidebar(侧栏工作台)', ok: sbOk, level: sbOk ? 'ok' : 'missing', detail: sbOk ? '已安装——web UI 右侧工作台可预览产物与 doctor 报告(gotry-state/doctor-report.md)' : '未安装——dsh web 无右侧工作台,产物与 doctor 报告只能在对话里看(gotry_artifacts_list)', fix: sbOk ? undefined : 'npx gotry doctor --fix' })
+  items.push({ label: 'dsh-better-sidebar(侧栏工作台)', ok: sbOk, level: sbOk ? 'ok' : 'missing', detail: sbOk ? '已安装——web UI 右侧工作台可预览产物与 doctor 报告(gotry-state/doctor-report.md)' : '未安装——dsh web 无右侧工作台,产物与 doctor 报告只能在对话里看(gotry_artifacts_list)', fix: sbOk ? undefined : 'npx @danceiny/gotry doctor --fix' })
   // dsh-calendar(setup 状态面;默认不挂载=ok 是合法态,opt-in 未配置才 degraded)
   const calState = readCalendarState()
   const calOn = calState?.enabled === true
   const calConfigured = calOn && calendarProfileConfigured()
-  items.push({ label: 'dsh-calendar(日历工作窗口)', ok: !calOn || calConfigured, level: !calOn ? 'ok' : calConfigured ? 'ok' : 'degraded', detail: calendarDetail(calState), fix: !calOn ? undefined : calConfigured ? undefined : '在 ~/.dsh/profiles/web/cordis.patch.yml 覆盖 calendar 行 config 填 username(或 npx gotry setup calendar --off 恢复默认不挂载)' })
+  items.push({ label: 'dsh-calendar(日历工作窗口)', ok: !calOn || calConfigured, level: !calOn ? 'ok' : calConfigured ? 'ok' : 'degraded', detail: calendarDetail(calState), fix: !calOn ? undefined : calConfigured ? undefined : '在 ~/.dsh/profiles/web/cordis.patch.yml 覆盖 calendar 行 config 填 username(或 npx @danceiny/gotry setup calendar --off 恢复默认不挂载)' })
   // dsh-map-tools(patch 分发面宿主插件,issue #139):解析失败启动时整块静默剔除,
   // doctor 把两态照亮。候选清单与 bin/gotry-inner.js 解析链、ts/capabilities/doctor.ts 同口径:
-  // tarball vendor 副本优先(随 files[] 分发,不进 npm 依赖——其 peerDependencies 要求
-  // dsh-settings/dsh-tools >=0.1.2-rc.1,与锁定的 0.1.2-alpha.3 家族在 npm 严格 peer
-  // 解析下 ERESOLVE,依赖形态会弄坏 npx 安装),其余覆盖 source/提升/profile 布局。
+  // tarball vendor 副本优先(随 files[] 分发,不进 npm 依赖——历史上游 peerDependencies
+  // 要求 dsh-settings/dsh-tools >=0.1.2-rc.1,与锁定的 0.1.2-alpha.3 家族在 npm 严格 peer
+  // 解析下 ERESOLVE;当前锁定 0.1.5-rc.1 家族,vendored 副本已对齐 0.1.5-rc.1,
+  // 保持 vendored 形态复用适配补丁),其余覆盖 source/提升/profile 布局。
   const rootRequire = createRequire(join(repoRoot, 'package.json'))
   const mapCandidates = [
     join(repoRoot, 'ts/dsh-runtime/vendor/dsh-map-tools/lib/index.js'),
@@ -396,13 +486,13 @@ const doctorIcon = { ok: '✅', missing: '❌', degraded: '⚠️' }
 const fixCell = (fix) => (!fix ? '—' : /^(npx|hbcli|curl|pip|python|\$)/.test(fix) ? `\`${fix}\`` : fix)
 
 /** 启动一次性摘要行(issue #114,design §3.1③):全 ok 返回 null(静默零输出);
- *  有待处理项给一行人话 + 指路(对话里 gotry_doctor 看详情 / 终端 npx gotry doctor)。
+ *  有待处理项给一行人话 + 指路(对话里 gotry_doctor 看详情 / 终端 npx @danceiny/gotry doctor)。
  *  纯函数,bootstrap-tests 直接断言。 */
 function startupDoctorLine(items) {
   const broken = (items ?? []).filter((i) => i.level && i.level !== 'ok')
   if (broken.length === 0) return null
   const human = (lv) => (lv === 'missing' ? '缺' : '半可用')
-  return `[gotry] doctor: ${broken.length} 项待处理(${broken.map((i) => `${i.label}=${human(i.level)}`).join('、')})——对话里让助手调 gotry_doctor 看详情与指引,或终端跑 npx gotry doctor`
+  return `[gotry] doctor: ${broken.length} 项待处理(${broken.map((i) => `${i.label}=${human(i.level)}`).join('、')})——对话里让助手调 gotry_doctor 看详情与指引,或终端跑 npx @danceiny/gotry doctor`
 }
 
 /** 体检报告 markdown(与 ts/capabilities/doctor.ts renderDoctorReportMd 同形) */
@@ -411,18 +501,18 @@ function renderDoctorReportMd(items) {
   const lines = [
     '# GoTry 依赖体检报告(doctor)',
     '',
-    `> 生成于 ${new Date().toISOString()};重新生成:终端 \`npx gotry doctor\`,或在对话里让助手调 gotry_doctor。`,
+    `> 生成于 ${new Date().toISOString()};重新生成:终端 \`npx @danceiny/gotry doctor\`,或在对话里让助手调 gotry_doctor。`,
     '',
     '| 状态 | 依赖 | 现状 | 修复指引 |',
     '|---|---|---|---|',
     ...items.map((i) => `| ${doctorIcon[i.level]} | ${i.label} | ${i.detail} | ${fixCell(i.fix)} |`),
     '',
-    `**结论**:${broken.length === 0 ? '全部就绪(可选依赖齐,LLM key 归 dsh 宿主管)。' : `${broken.length} 项待处理:${broken.map((i) => i.label).join('、')}。补装: npx gotry doctor --fix`}`,
+    `**结论**:${broken.length === 0 ? '全部就绪(可选依赖齐,LLM key 归 dsh 宿主管)。' : `${broken.length} 项待处理:${broken.map((i) => i.label).join('、')}。补装: npx @danceiny/gotry doctor --fix`}`,
     '',
     '---',
     '',
-    '- `npx gotry doctor` 随时可重跑(只读,不改任何东西);',
-    '- `npx gotry doctor --fix` 按上表补装(hbcli 官方脚本 / agent-reach pip / dsh-better-sidebar 插件);',
+    '- `npx @danceiny/gotry doctor` 随时可重跑(只读,不改任何东西);',
+    '- `npx @danceiny/gotry doctor --fix` 按上表补装(hbcli 官方脚本 / agent-reach pip / dsh-better-sidebar 插件);',
     '- LLM key 由 dsh 宿主 UI 管理,gotry 永不体检、不回显。',
     '',
   ]
@@ -446,8 +536,8 @@ async function runDoctor() {
     if (i.level !== 'ok' && i.fix) say(`      ↳ 修复: ${i.fix}`)
   }
   if (DOCTOR_FIX) {
-    if (process.platform === 'win32') {
-      say('[gotry-doctor] --fix 在 Windows 暂不支持自动安装(hbcli/agent-reach 上游无 win 安装面);请按各项修复指引手动处理')
+    if (!doctorFixAutoSupported()) {
+      say('[gotry-doctor] --fix 在 Windows 暂不支持自动安装(hbcli/agent-reach/sidebar 上游无 win 安装面);请按各项修复指引手动处理')
     } else {
       say('[gotry-doctor] 开始补装缺失项(--fix)…')
       const results = []
@@ -455,7 +545,7 @@ async function runDoctor() {
       if (process.env.GOTRY_SETUP_REACH !== '0') results.push(await setupReach())
       if (process.env.GOTRY_SETUP_SIDEBAR !== '0') results.push(await setupSidebar())
       const failedFix = results.filter((r) => !r.ok).length
-      say(failedFix === 0 ? '[gotry-doctor] 补装完成;下面是补装后复检。' : `[gotry-doctor] ${failedFix} 项补装失败——见上方安装器输出;可重跑 npx gotry doctor --fix`)
+      say(failedFix === 0 ? '[gotry-doctor] 补装完成;下面是补装后复检。' : `[gotry-doctor] ${failedFix} 项补装失败——见上方安装器输出;可重跑 npx @danceiny/gotry doctor --fix`)
       items = await doctorChecks()
       for (const i of items) {
         say(`  ${doctorIcon[i.level]} ${i.label}:${i.detail}`)
@@ -476,6 +566,339 @@ async function runDoctor() {
   return stillMissing === 0 ? 0 : 1
 }
 
+// ---------------------------------------------------------------------------
+// onboarding(issue #258):`npx @danceiny/gotry web` 启动前的显式可选能力配置 prompt——每次符合条件的启动
+//  评估一次、至多问一次,无跨启动持久确认(不写「已问过」标记,每次 web 启动独立判定)。
+//  契约:仅交互式 TTY + 有「可自动安装」缺项时问一次;y → 复用 doctor --fix 的幂等
+//  安装器(setupHbcli/setupReach/setupSidebar,不建第二套);n → 立即继续 web。
+//  CI/benchmark/非 TTY/全健康/GOTRY_SETUP_SKIP=1/GOTRY_ONBOARDING_SKIP=1/--no-onboarding
+//  均零 prompt 零安装,仍启 web;永不 postinstall 或后台任务里安装。结果三态:
+//  installed / needs-user-action / unavailable,各带具体原因;浏览器商店/凭证/账号/
+//  key/上游授权永不冒充自动完成。部分失败不挡 web 且给重试命令;再跑不重装已健康项
+//  (安装器自带存在性短路 + doctor 复检)。纯函数(classify/plan/skipReason)与
+//  runOnboardingFix(注入安装器)均导出供 bootstrap-tests 隔离单测,不跑真安装器。
+// ---------------------------------------------------------------------------
+
+/** 安装器 id 映射:doctor item label → 安装器 id(与 GOTRY_SETUP_* env 同名)。纯函数。 */
+function installerIdFor(label) {
+  if (typeof label !== 'string') return null
+  if (label.startsWith('Agent Reach')) return 'reach'
+  if (label.startsWith('hbcli')) return 'hbcli'
+  if (label.startsWith('dsh-better-sidebar')) return 'sidebar'
+  return null
+}
+
+/** 该安装器是否被 GOTRY_SETUP_*=0 显式 opt-out(与 runDoctor 同口径)。纯函数。
+ *  env 可注入:测试与可复用逻辑不依赖 ambient GOTRY_SETUP_*,生产 CLI 路径仍取 process.env。 */
+function installerEnabled(id, env = process.env) {
+  if (id === 'hbcli') return env.GOTRY_SETUP_HBCLI !== '0'
+  if (id === 'reach') return env.GOTRY_SETUP_REACH !== '0'
+  if (id === 'sidebar') return env.GOTRY_SETUP_SIDEBAR !== '0'
+  return true
+}
+
+/** doctor --fix 自动安装的平台支持面(共享契约):win32 上 hbcli(staicli)/agent-reach(pip venv)
+ *  上游无 win 安装面,dsh-better-sidebar(dsh plugin → pnpm)在 win32 同样不自动跑——runDoctor
+ *  的 --fix 守卫与 onboarding 的 auto 分桶复用同一条边界,不在 win32 把这些缺项分到 auto
+ *  (否则 prompt 了却装不上,不诚实)。纯函数,可注入 platform 供确定性单测。 */
+function doctorFixAutoSupported(platform = process.platform) {
+  return platform !== 'win32'
+}
+
+/** win32 上本可 auto 的缺项降为 unavailable 时的具体原因(诚实,不冒充 auto / 不给无效的
+ *  `npx @danceiny/gotry doctor --fix` 指引)。纯函数。 */
+function platformAutoUnavailableReason(id) {
+  if (id === 'hbcli') return 'Windows 暂不支持 hbcli 自动安装(staicli 上游无 win 安装面);请按 doctor 指引手动配置或切到 macOS/Linux'
+  if (id === 'reach') return 'Windows 暂不支持 agent-reach 自动安装(pip venv 上游无 win 安装面);请按 doctor 指引手动配置或切到 macOS/Linux'
+  if (id === 'sidebar') return 'Windows 暂不支持 dsh-better-sidebar 自动安装(dsh plugin → pnpm 在 win32 不自动跑);请按 doctor 指引手动配置或切到 macOS/Linux'
+  return 'Windows 暂不支持自动安装;请按 doctor 指引手动配置'
+}
+
+/**
+ * 把单个 doctor item 分到 onboarding 桶(纯函数,与 ts/capabilities/doctor.ts 同口径)。
+ *  auto = 本机可自动安装(setupHbcli/setupReach/setupSidebar 且未被 env opt-out);
+ *  user-action = 浏览器商店/凭证/账号/key/上游授权/手动配置——必须用户本人操作;
+ *  unavailable = 本仓无自动安装面(重装 gotry / Node 升级 / env opt-out / 安装器不自动升级项)。
+ *  LLM key 永远 ok,不进任何桶。
+ */
+function classifyDoctorGap(item, opts = {}) {
+  const platform = opts.platform ?? process.platform
+  const env = opts.env ?? process.env
+  if (!item || !item.level || item.level === 'ok') return 'ok'
+  const label = item.label ?? ''
+  if (label === 'LLM key') return 'ok'
+  const autoSupported = doctorFixAutoSupported(platform)
+  if (label.startsWith('Agent Reach')) return installerEnabled('reach', env) && autoSupported ? 'auto' : 'unavailable'
+  // hbcli:二进制缺失(missing)= auto(setupHbcli 装;win32 → unavailable,上游无 win 安装面);
+  // 凭证未配(degraded)= user-action(平台无关);旧版本(missing,安装器不自动升级)= auto 分桶
+  // 但安装会失败 → 结果兜底 unavailable,诚实不冒充。
+  if (label.startsWith('hbcli')) {
+    if (item.level === 'degraded') return 'user-action'
+    return installerEnabled('hbcli', env) && autoSupported ? 'auto' : 'unavailable'
+  }
+  if (label.startsWith('dsh-better-sidebar')) return installerEnabled('sidebar', env) && autoSupported ? 'auto' : 'unavailable'
+  if (label.startsWith('GoTry Session Bridge')) return 'user-action' // 浏览器商店一键装
+  if (label.startsWith('FlyAI')) return 'user-action' // 上游控制台申请 key
+  if (label.startsWith('dsh-calendar')) return 'user-action' // profile cordis.patch.yml 配置
+  if (label.startsWith('dsh-map-tools')) return 'unavailable' // 随包 vendor,缺失即重装 gotry
+  if (label.startsWith('dsh-tool-ask-user')) return 'unavailable' // 随 dsh 闭包,缺失即重装 gotry
+  if (label.startsWith('Node')) return 'unavailable' // 手动升级运行时
+  return 'unavailable'
+}
+
+/**
+ * 由 doctor items 构建 onboarding 计划(纯函数)。
+ *  promptable = 存在可自动安装缺项(决定是否问那一次)。
+ */
+function buildOnboardingPlan(items, opts = {}) {
+  const platform = opts.platform ?? process.platform
+  const env = opts.env ?? process.env
+  const auto = []
+  const userAction = []
+  const unavailable = []
+  for (const item of items ?? []) {
+    const bucket = classifyDoctorGap(item, { platform, env })
+    if (bucket === 'ok') continue
+    const entry = { label: item.label, level: item.level, detail: item.detail, fix: item.fix }
+    if (bucket === 'auto') auto.push(entry)
+    else if (bucket === 'user-action') userAction.push(entry)
+    else {
+      // win32 平台把本可 auto 的缺项降为 unavailable 时,给具体平台原因(诚实,不冒充 auto,
+      // 也不给 win32 上无效的 `npx @danceiny/gotry doctor --fix` 指引);env opt-out / 随包缺失等保持原 detail。
+      const id = installerIdFor(item.label)
+      if (id && !doctorFixAutoSupported(platform) && installerEnabled(id, env)) {
+        entry.detail = platformAutoUnavailableReason(id)
+      }
+      unavailable.push(entry)
+    }
+  }
+  return { promptable: auto.length > 0, auto, userAction, unavailable }
+}
+
+/**
+ * onboarding 跳过原因(纯函数;inner 与 bootstrap 共用,确保两边判定一致且可单测)。
+ *  返回原因字符串则跳过(零 prompt 零安装),null 则可继续。mode/benchmark 仅 inner
+ *  提供;bootstrap 直接调用时 mode 缺省(不检 non-web),只检 env/argv/isTTY。
+ */
+function onboardingSkipReason({ mode, benchmark, env = process.env, argv = process.argv, isTTY = process.stdin?.isTTY } = {}) {
+  if (mode !== undefined && mode !== 'web') return 'non-web-mode'
+  if (benchmark) return 'benchmark'
+  if (env.GOTRY_SETUP_SKIP === '1') return 'GOTRY_SETUP_SKIP=1'
+  if (env.GOTRY_ONBOARDING_SKIP === '1') return 'GOTRY_ONBOARDING_SKIP=1'
+  if (env.CI) return 'CI'
+  if (Array.isArray(argv) && argv.includes('--no-onboarding')) return '--no-onboarding'
+  if (!isTTY) return 'non-tty'
+  return null
+}
+
+/** 读取 stdin 一行(对 TTY 与注入流均工作;finish 后 pause,不干扰后续 dsh web 的 stdin)。 */
+function readOneLine(input) {
+  return new Promise((resolve) => {
+    let buf = ''
+    let done = false
+    const finish = (line) => {
+      if (done) return
+      done = true
+      input.removeListener('data', onData)
+      input.removeListener('end', onEnd)
+      try { input.pause?.() } catch { /* ignore */ }
+      resolve(line ?? '')
+    }
+    const onData = (chunk) => {
+      buf += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk)
+      const nl = buf.indexOf('\n')
+      if (nl >= 0) finish(buf.slice(0, nl).replace(/\r$/, ''))
+    }
+    const onEnd = () => finish(buf)
+    input.on('data', onData)
+    input.on('end', onEnd)
+    try { input.resume?.() } catch { /* ignore */ }
+  })
+}
+
+/**
+ * 交互 prompt:打印缺项概览 + 一次询问,读一行返回 'yes' | 'no'。
+ *  input/output 可注入(测试);默认 process.stdin/process.stdout。
+ */
+async function promptOnboarding(plan, opts = {}) {
+  const input = opts.input ?? process.stdin
+  const output = opts.output ?? process.stdout
+  output.write('\n[gotry] 启动前检测到可选能力缺项,其中可自动配置:\n')
+  for (const g of plan.auto) output.write(`  • ${g.label} —— ${g.detail}\n`)
+  if (plan.userAction.length || plan.unavailable.length) {
+    output.write('需你本人操作(浏览器商店 / 凭证 / key / 重装),gotry 不自动处理:\n')
+    for (const g of plan.userAction) output.write(`  • ${g.label} —— ${g.detail}\n`)
+    for (const g of plan.unavailable) output.write(`  • ${g.label} —— ${g.detail}\n`)
+  }
+  output.write('\n现在自动配置可安装项吗?(y/N,随后继续启动 web) ')
+  const answer = await readOneLine(input)
+  return /^\s*y(es)?\s*$/i.test(answer) ? 'yes' : 'no'
+}
+
+/**
+ * 渲染分类计划(无可自动安装项时):把 needs-user-action / unavailable 逐项带具体原因打印,
+ * 不 prompt 不安装。用于 win32 等无 auto 安装面、或仅凭证/key/重装缺口的交互式启动——
+ * 让用户看见分类与原因,而非只剩后台一行摘要。output 可注入(测试)。
+ */
+function renderClassifiedPlan(plan, output) {
+  output.write('\n[gotry] 启动前检测到可选能力缺项(无可自动安装项,以下需你本人操作或本机暂不支持):\n')
+  if (plan.userAction.length) {
+    output.write('需你本人操作(浏览器商店 / 凭证 / key / 配置),gotry 不自动处理:\n')
+    for (const g of plan.userAction) output.write(`  • ${g.label} —— ${g.detail}\n`)
+  }
+  if (plan.unavailable.length) {
+    output.write('本机暂不支持自动安装(平台限制 / 重装 gotry / Node 升级):\n')
+    for (const g of plan.unavailable) output.write(`  • ${g.label} —— ${g.detail}\n`)
+  }
+  output.write('详情与指引:对话里让助手调 gotry_doctor,或终端跑 npx @danceiny/gotry doctor\n')
+}
+
+/**
+ * 执行安装(复用 setupHbcli/setupReach/setupSidebar,不建第二套)。
+ *  installers/recheck 可注入(测试用 fakes,永不跑真安装器)。返回逐项结果:
+ *  installed / needs-user-action / unavailable(失败带重试命令)。部分失败不抛、不挡 web。
+ */
+const ONBOARDING_DEFAULT_INSTALLERS = { hbcli: setupHbcli, reach: setupReach, sidebar: setupSidebar }
+
+async function runOnboardingFix(plan, opts = {}) {
+  const installers = { ...ONBOARDING_DEFAULT_INSTALLERS, ...(opts.installers ?? {}) }
+  const recheck = opts.recheck ?? doctorChecks
+  const attempts = {}
+  for (const gap of plan.auto) {
+    const id = installerIdFor(gap.label)
+    const installer = id ? installers[id] : null
+    if (!installer) { attempts[gap.label] = { ok: false, error: 'no installer mapped for this gap' }; continue }
+    try {
+      const r = await installer()
+      attempts[gap.label] = { ok: r?.ok === true, error: r?.error }
+    } catch (e) {
+      attempts[gap.label] = { ok: false, error: e?.message ?? String(e) }
+    }
+  }
+  // 复检决定 auto 项最终状态(安装器自带存在性短路 → 已健康项不重装;幂等)
+  const rechecked = await recheck()
+  const byLabel = new Map(rechecked.map((i) => [i.label, i]))
+  const results = []
+  for (const gap of plan.auto) {
+    const item = byLabel.get(gap.label)
+    if (item && item.level === 'ok') {
+      results.push({ label: gap.label, status: 'installed', reason: item.detail ?? '已就位' })
+    } else {
+      const a = attempts[gap.label]
+      results.push({ label: gap.label, status: 'unavailable', reason: a?.error ?? item?.detail ?? 'install failed', retry: 'npx @danceiny/gotry doctor --fix' })
+    }
+  }
+  for (const gap of plan.userAction) {
+    results.push({ label: gap.label, status: 'needs-user-action', reason: gap.fix ?? gap.detail ?? '需用户本人操作' })
+  }
+  for (const gap of plan.unavailable) {
+    results.push({ label: gap.label, status: 'unavailable', reason: gap.detail ?? '本仓无自动安装面' })
+  }
+  return results
+}
+
+/**
+ * `onboarding` 子命令(inner 以 `onboarding --result-file=…` 同步 inherit 调用;
+ *  亦可直接 `node gotry-bootstrap.js onboarding --scan` 只读查看计划)。
+ *  恒 exit 0(永不挡 web);result JSON 写到 --result-file 告知 inner 是否 prompt 过。
+ *
+ *  opts(注入位,供 bootstrap-tests 在进程内跨 inner→onboarding→web 边界跑真实 onboarding 逻辑,
+ *  永不跑真安装器/开浏览器):input/output(注入流替 stdin/stdout)、isTTY/env/argv(覆盖跳过判定)、
+ *  scan(注入 doctor items 替真机探测)、installers/recheck(注入假安装器/复检)、platform(注入平台)。
+ *  返回 result 对象({ prompted, answered?, results?, skipped?, plan? });CLI 仍恒 exit 0。
+ */
+async function runOnboarding(args, opts = {}) {
+  const resultFile = (args.find((a) => a.startsWith('--result-file=')) ?? '').slice('--result-file='.length) || null
+  const scanOnly = args.includes('--scan')
+  const input = opts.input ?? process.stdin
+  const output = opts.output ?? process.stdout
+  const isTTY = opts.isTTY ?? process.stdin?.isTTY
+  const env = opts.env ?? process.env
+  const argv = opts.argv ?? process.argv
+  const scan = opts.scan ?? doctorChecks
+  const platform = opts.platform ?? process.platform
+  // result 通道硬化:mode 0600 + flag wx——存在路径/符号链接永不覆盖(inner 在 0700
+  // mkdtemp 私有目录下传 result.json,这里 wx 防该确切路径被预置/符号链接互换攻击)。
+  const writeResult = (r) => { if (resultFile) { try { writeFileSync(resultFile, JSON.stringify(r), { mode: 0o600, flag: 'wx' }) } catch { /* 坏 result 不挡 web */ } } }
+
+  if (scanOnly) {
+    const plan = buildOnboardingPlan(await scan(), { platform, env })
+    say(JSON.stringify(plan))
+    return { prompted: false, scan: true, plan }
+  }
+
+  const skipReason = onboardingSkipReason({ env, argv, isTTY })
+  if (skipReason) {
+    const result = { prompted: false, skipped: skipReason }
+    writeResult(result)
+    return result
+  }
+
+  const plan = buildOnboardingPlan(await scan(), { platform, env })
+  if (!plan.promptable) {
+    // 无可自动安装缺项。两类:
+    //  (1) 有需用户操作/不可用项(如 win32 平台不支持自动安装,或仅凭证/key/重装缺口):
+    //      渲染分类计划与具体原因,不 prompt 不安装;标记 reported 让 inner 抑制重复的
+    //      detached doctor 摘要(design §3.1③,#114)——用户已看见分类,不再叠一行摘要。
+    //  (2) 全健康:静默(后台摘要亦静默),不渲染。
+    const reportable = plan.userAction.length + plan.unavailable.length
+    if (reportable > 0) {
+      renderClassifiedPlan(plan, output)
+      const result = { prompted: false, reported: true, plan }
+      writeResult(result)
+      return result
+    }
+    const result = { prompted: false, plan }
+    writeResult(result)
+    return result
+  }
+
+  const answer = await promptOnboarding(plan, { input, output })
+  if (answer === 'yes') {
+    say('[gotry] 开始自动配置可安装项(复用 doctor --fix 幂等安装器)…')
+    const results = await runOnboardingFix(plan, { installers: opts.installers, recheck: opts.recheck })
+    say('')
+    say('[gotry] 配置结果:')
+    for (const r of results) {
+      const tag = r.status === 'installed' ? '✅ installed' : r.status === 'needs-user-action' ? '↪ needs-user-action' : '✗ unavailable'
+      say(`  ${tag}  ${r.label} —— ${r.reason}${r.retry ? `(重试: ${r.retry})` : ''}`)
+    }
+    const result = { prompted: true, answered: 'yes', results }
+    writeResult(result)
+    return result
+  }
+  say('  跳过——随时可跑: npx @danceiny/gotry doctor --fix(随后继续启动 web)')
+  const result = { prompted: true, answered: 'no' }
+  writeResult(result)
+  return result
+}
+
+/**
+ * web 模式的 onboarding + 启动编排(issue #258 E2E 边界缝):
+ *  跳过判定 →(可选)onboarding →(可选)后台 doctor 摘要 → dsh web 启动。抽成显式注入依赖的
+ *  函数,使 bootstrap-tests 能在不 spawn 真 dsh / 不跑真安装器的前提下,断言 inner 的真实编排跨过
+ *  inner→onboarding→web 启动边界(yes/no/非 TTY/部分失败/summary 抑制均到达 web 启动标记)。
+ *  生产侧 inner 传入真实依赖(spawnSync 跑 bootstrap onboarding 子进程、spawn detached 跑 doctor
+ *  --summary、spawn 跑 dsh web);launchWeb 即 web 启动边界标记。
+ *  摘要抑制契约:onboarding 已 prompt(用户交互过)或已 reported(渲染过分类计划,如 win32 无 auto
+ *  安装面)时,抑制重复的 detached doctor 摘要;跳过态(非 TTY/CI/opt-out)与全健康态仍走摘要
+ *  (全健康时摘要本身静默)。返回 onboardingPrompted 供 inner 复用(本函数内已处理摘要抑制,返回值仅信息性)。
+ */
+async function orchestrateWebLaunch({ onboardingSkip, runOnboarding, runSummary, launchWeb }) {
+  let onboardingPrompted = false
+  let onboardingResult = null
+  if (!onboardingSkip) {
+    try { onboardingResult = await runOnboarding() } catch { /* onboarding 不可用不挡 web */ }
+    onboardingPrompted = onboardingResult?.prompted === true
+  }
+  // onboarding 已 prompt 或已 reported(渲染过分类计划)时抑制重复后台摘要(design §3.1③,#114)
+  if (!onboardingPrompted && !onboardingResult?.reported) {
+    try { runSummary() } catch { /* 体检不可用不挡启动 */ }
+  }
+  await launchWeb()
+  return { launched: true, onboardingPrompted, onboardingResult }
+}
+
 const EXTENSION_FILES = ['manifest.json', 'background.js', 'content-main.js', 'content-bridge.js', 'README.md']
 
 function readManifestVersion(manifestPath) {
@@ -497,7 +920,7 @@ async function setupExtension() {
   const srcDir = join(repoRoot, 'extension')
   const srcManifest = join(srcDir, 'manifest.json')
   if (!existsSync(srcManifest)) {
-    say(`  ✗ 包内未找到扩展文件(${srcDir})——不影响 gotry:会话检索降级,重装 npx gotry 可恢复`)
+    say(`  ✗ 包内未找到扩展文件(${srcDir})——不影响 gotry:会话检索降级,重装 npx @danceiny/gotry 可恢复`)
     return { ok: false }
   }
   const srcVersion = readManifestVersion(srcManifest)
@@ -517,7 +940,7 @@ async function setupExtension() {
   say(`  ✓ 已落位 ${dstDir}(v${srcVersion};manifest 带固定 key,unpacked 扩展 ID 恒为 olpgkofjhhiiiahdkkbcninhjmegghfe)`)
   say('  推荐(免下面三步):Chrome 应用商店一键安装 GoTry Session Bridge(自动更新): https://chromewebstore.google.com/detail/gotry-session-bridge/oeajpiccmonococjcegddlooeeohlbgd')
   say('  本地加载(每台浏览器一次,约 30 秒):Chrome 打开 chrome://extensions → 右上角开启「开发者模式」→「加载已解压的扩展程序」→ 选择 ~/.gotry/extension')
-  say('  获取/更新本地通道扩展可走 GitHub Releases:npx gotry setup --extension-from=github(自动下载校验落位;手动下载: github.com/Danceiny/gotry/releases 标签 ext-*)')
+  say('  获取/更新本地通道扩展可走 GitHub Releases:npx @danceiny/gotry setup --extension-from=github(自动下载校验落位;手动下载: github.com/Danceiny/gotry/releases 标签 ext-*)')
   say('  装好即生效,零系统弹窗;扩展卡片开关=总闸(与 gotry 授权闸 sessionAccess 双重控制)')
   return { ok: true }
 }
@@ -758,6 +1181,9 @@ async function main() {
   // 只读体检零副作用(--fix 才装),win32 也可跑体检(fix 面另有提示)。
   if (DOCTOR) process.exit(await runDoctor())
 
+  // onboarding 子命令(issue #258):web 启动前的交互式可选能力配置(恒 exit 0,不挡 web)。
+  if (ONBOARDING) { await runOnboarding(process.argv.slice(2)); process.exit(0) }
+
 // wizard 子命令(2026-09-02 商店上架后退化):**只走 stdout 提示 + 健康探活等待**;
 // 不 spawn 任何 GUI 工具(不动 pbcopy / osascript / open / xdg-open / zenity),
 // 不打开 chrome://extensions,不动扩展路径——浏览器自己当安装器,gotry 不越界。
@@ -806,7 +1232,7 @@ if (WIZARD) {
   else say('[gotry-setup] GoTry Session Bridge 扩展:GOTRY_SETUP_EXTENSION=0 跳过')
   const failed = results.filter((r) => !r.ok).length
   if (failed > 0) {
-    say(`[gotry-setup] ${failed} 项未就绪——gotry 本体不受影响;可稍后重跑: npx gotry setup`)
+    say(`[gotry-setup] ${failed} 项未就绪——gotry 本体不受影响;可稍后重跑: npx @danceiny/gotry setup`)
     process.exit(AUTO ? 0 : 1)
   }
   say('[gotry-setup] 扩展就绪检查完成。')
@@ -817,9 +1243,14 @@ if (WIZARD) {
 // bin/gotry-inner.js 始终以 `node …/gotry-bootstrap.js` 直接 spawn,不受影响)
 if (process.argv[1] && process.argv[1].endsWith('gotry-bootstrap.js')) {
   main().catch((e) => {
-    say(`[gotry-setup] 异常:${e.message}(不影响 gotry 本体;可重试 npx gotry setup)`)
+    say(`[gotry-setup] 异常:${e.message}(不影响 gotry 本体;可重试 npx @danceiny/gotry setup)`)
     process.exit(AUTO ? 0 : 1)
   })
 }
 
-export { setupSidebar, sidebarInstalled }
+export {
+  setupSidebar, sidebarInstalled,
+  classifyDoctorGap, buildOnboardingPlan, onboardingSkipReason,
+  runOnboardingFix, promptOnboarding, renderClassifiedPlan, runOnboarding, orchestrateWebLaunch,
+  doctorFixAutoSupported, platformAutoUnavailableReason, installerEnabled,
+}