tianshu-harness 3.23.0

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "tianshu-harness",
+  "version": "3.23.0",
+  "description": "Cognitive runtime (CVM) for coding agents — stable, evidence-gated delivery; prefix cache works with all models (98–99% hit rate)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "keywords": [
+    "coding-agent",
+    "terminal",
+    "tui",
+    "deepseek",
+    "ai",
+    "cli"
+  ],
+  "homepage": "https://github.com/huiliyi37/Tianshu-Tui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huiliyi37/Tianshu-Tui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/huiliyi37/Tianshu-Tui/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist/",
+    "!dist/native",
+    "!dist/pro",
+    "!dist/node_modules/**",
+    "dist/node_modules/better-sqlite3/",
+    "scripts/check-mobile-env.mjs",
+    "scripts/fetch-native-sqlite.js",
+    "scripts/prune-installed-wasms.js",
+    "scripts/tree-sitter-wasm-keep.js",
+    "README.md",
+    "LICENSE",
+    "completions/"
+  ],
+  "bin": {
+    "rivet": "dist/cli/entry.js",
+    "tianshu": "dist/cli/entry.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/check-mobile-env.mjs && (node scripts/install-git-hooks.mjs || node -e 1) && (node scripts/fetch-native-sqlite.js || node -e 1) && (node scripts/prune-installed-wasms.js || node -e 1)",
+    "prepack": "npm run build && node scripts/stage-cli-sqlite-wrapper.js",
+    "dev": "tsup --watch",
+    "build": "tsup && node scripts/pack-native.js && node scripts/stage-runtime-deps.js",
+    "build:bundle": "tsup",
+    "start": "node --expose-gc --max-old-space-size=4096 dist/cli/entry.js",
+    "typecheck": "tsx scripts/typecheck-guard.ts",
+    "lint": "oxlint src scripts",
+    "budgets:check": "tsx scripts/verify-source-budgets.ts",
+    "lint:fix": "oxlint src scripts --fix",
+    "typecheck:direct": "tsc --noEmit",
+    "typecheck:baseline": "tsx scripts/typecheck-baseline.ts",
+    "test": "tsx scripts/run-node-tests.ts",
+    "test:unit": "tsx scripts/run-node-tests.ts --unit",
+    "test:integration": "tsx scripts/run-node-tests.ts --integration",
+    "test:fast": "tsx scripts/run-node-tests.ts --exclude-tui",
+    "test:desktop": "node --import tsx desktop/scripts/run-tests.ts 'src/**/__tests__/*.test.ts' 'scripts/__tests__/*.test.ts'",
+    "test:incremental": "tsx scripts/test-incremental.ts",
+    "structure:check": "tsx --test src/__tests__/architecture-guards.test.ts",
+    "contributors:check": "tsx scripts/contributors.ts --check",
+    "cache:audit": "tsx src/cache/cache-audit-cli.ts",
+    "prefix:budget": "tsx scripts/prefix-budget.ts",
+    "tokens:audit": "tsx scripts/analyze-output-tokens.ts",
+    "diagnose:orphans": "tsx scripts/diagnose-tool-orphans.ts",
+    "benchmark": "tsx scripts/run-benchmark.ts",
+    "smoke:mcp": "tsx scripts/smoke-mcp-presets.ts",
+    "docs:index": "tsx scripts/docs-index.ts",
+    "docs:check": "tsx scripts/docs-index.ts --check",
+    "probe:thresholds": "tsx scripts/telemetry-probes/threshold-coverage.ts",
+    "probe:control-health": "tsx scripts/telemetry-probes/control-health.ts",
+    "probe:test": "tsx scripts/run-node-tests.ts scripts/telemetry-probes",
+    "probe:typecheck": "tsc --noEmit -p scripts/telemetry-probes/tsconfig.json"
+  },
+  "dependencies": {
+    "@ast-grep/lang-json": "^0.0.7",
+    "@ast-grep/lang-python": "^0.0.6",
+    "@ast-grep/napi": "^0.44.0",
+    "esbuild": "^0.28.1",
+    "pdfjs-dist": "^6.3.289",
+    "playwright-core": "1.62.0",
+    "tree-sitter-wasms": "^0.1.13",
+    "typescript": "^5.7.0",
+    "web-tree-sitter": "^0.24.7",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "optionalDependencies": {
+    "@huiliyi37/node-addon-landlock-run": "^0.4.0",
+    "better-sqlite3": "^12.10.0"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@tauri-apps/cli": "^2.11.2",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/diff": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@types/pngjs": "^6.0.5",
+    "@types/turndown": "^5.0.6",
+    "chalk": "^5.6.2",
+    "diff": "^9.0.0",
+    "exceljs": "^4.4.0",
+    "get-east-asian-width": "^1.6.0",
+    "oxlint": "^1.80.0",
+    "parquet-wasm": "^0.7.2",
+    "patch-package": "^8.0.0",
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0",
+    "string-width": "^8.2.1",
+    "ts-morph": "^28.0.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.22.0",
+    "turndown": "^7.2.4",
+    "undici": "^8.3.0",
+    "zod": "^3.24.0"
+  }
+}

package/scripts/check-mobile-env.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * 移动端安装环境守卫（postinstall 第一步，2026-09-05）。
+ *
+ * 背景（issue #55 同期的移动端调研）：手机端两类环境——
+ *   1. 裸 Termux（bionic，process.platform === 'android'）：必需原生依赖
+ *      `@ast-grep/napi` 与 `esbuild` 没有 android 平台二进制，npm 会静默跳过，
+ *      安装「成功」但运行必坏。此类环境必须 fail-loud 并指引 proot-distro。
+ *   2. proot-distro（glibc arm64，platform === 'linux'）：官方支持路径，依赖
+ *      按 linux-arm64 正常解析；ripgrep 缺失时 grep 工具族如实降级，此处仅提醒。
+ *
+ * 逃生口：RIVET_ALLOW_MOBILE_INSTALL=1 时裸 Termux 也放行（降级为醒目警告），
+ * 供实验环境自担风险继续安装。
+ */
+import { execFileSync } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
+
+function detectRipgrep() {
+  try {
+    execFileSync('rg', ['--version'], { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {object} [input] 测试注入点
+ * @param {string} [input.platform] process.platform
+ * @param {string} [input.arch] process.arch
+ * @param {Record<string, string|undefined>} [input.env] process.env
+ * @param {boolean} [input.hasRg] ripgrep 是否在 PATH
+ * @returns {{ level: 'ok'|'warn'|'fatal', messages: string[] }}
+ */
+export function evaluateMobileInstallEnv(input = {}) {
+  const platform = input.platform ?? process.platform
+  const arch = input.arch ?? process.arch
+  const env = input.env ?? process.env
+  const hasRg = input.hasRg ?? detectRipgrep()
+
+  if (platform === 'android') {
+    const guidance = [
+      '检测到裸 Termux 环境（Android bionic）。',
+      'tianshu-harness 的必需原生依赖（@ast-grep/napi / esbuild）没有 Android 平台二进制，npm 会静默跳过它们——装完运行必坏。',
+      '官方支持路径是 proot-distro（glibc 发行版）：',
+      '  pkg install proot-distro && proot-distro install ubuntu && proot-distro login ubuntu',
+      '  （容器内）apt install -y curl ripgrep，安装 Node >= 24，然后 npm i -g tianshu-harness',
+      '沙箱/LSP/语音等能力在容器内会自动降级，不影响核心功能。',
+    ]
+    if (env.RIVET_ALLOW_MOBILE_INSTALL === '1') {
+      return {
+        level: 'warn',
+        messages: ['RIVET_ALLOW_MOBILE_INSTALL=1：跳过裸 Termux 拦截，继续安装（运行时大概率损坏，自担风险）。', ...guidance],
+      }
+    }
+    return { level: 'fatal', messages: guidance }
+  }
+
+  const warnings = []
+  if (platform === 'linux' && arch === 'arm64' && !hasRg) {
+    warnings.push('未检测到 ripgrep——grep/glob 工具族将不可用。安装：Debian/Ubuntu（proot 容器内）apt install -y ripgrep；Arch pacman -S ripgrep。')
+  }
+  return { level: warnings.length > 0 ? 'warn' : 'ok', messages: warnings }
+}
+
+function main() {
+  const result = evaluateMobileInstallEnv()
+  if (result.level === 'ok') return
+  const log = result.level === 'fatal' ? console.error : console.warn
+  for (const line of result.messages) log(line)
+  if (result.level === 'fatal') process.exit(1)
+}
+
+const invokedDirectly = process.argv[1]
+  && import.meta.url === pathToFileURL(process.argv[1]).href
+if (invokedDirectly || process.env.RIVET_MOBILE_GUARD_FORCE_RUN === '1') main()

package/scripts/fetch-native-sqlite.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+/**
+ * 从国内镜像下载 better-sqlite3 预编译原生二进制（postinstall 调用）。
+ *
+ * 背景：better-sqlite3 是 optionalDependency，其 prebuild-install 从 GitHub
+ * Releases 拉取预编译 .node 文件。中国大陆用户常因 GitHub 不可达导致下载失败，
+ * 又缺少编译工具链做 fallback 源码编译 → 静默跳过 → 运行时退化为纯内存模式。
+ *
+ * 本脚本在 postinstall 时运行，穷尽安装链后才降级（不能随便降级到内存模式）：
+ *   1. better-sqlite3 已通过 npm 正常编译安装 → 拷贝到 dist/native/（零开销）
+ *   2. 四路预编译镜像（npmmirror registry / npmmirror CDN 直连 / kkgithub /
+ *      GitHub 直连）逐个尝试拉取预编译 .tar.gz
+ *   3. 镜像全败 → npm install better-sqlite3 --no-save 源码编译兜底（走用户
+ *      自己的 registry 配置；有编译工具链的机器此时仍能装上；启动自愈以
+ *      RIVET_FETCH_SKIP_COMPILE=1 调用时跳过本段——编译数分钟，留给
+ *      postinstall/手动重跑，启动路径只做分钟内下载自愈）
+ *   4. 全部失败 → 落 .fetch-failed 标记 + 可操作提示，不阻断安装（optional 语义保留）
+ *
+ * 与 pack-native.js 的分工：
+ *   pack-native.js — 桌面 sidecar 打包期，走 prebuild-install 确保 ABI 匹配
+ *   fetch-native-sqlite.js — CLI 用户 postinstall，从镜像快速拉取
+ */
+
+import { createWriteStream, existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, rmSync } from 'node:fs'
+import { mkdir, unlink } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { pipeline } from 'node:stream/promises'
+import { get } from 'node:https'
+import { createGunzip } from 'node:zlib'
+import { execSync } from 'node:child_process'
+import { Readable } from 'node:stream'
+import { tmpdir } from 'node:os'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const repoRoot = join(__dirname, '..')
+
+// ── 平台/架构/ABI ──────────────────────────────────────────────────
+const PLATFORM = process.platform
+const ARCH = process.arch
+const ABI = process.versions.modules
+
+const PLATFORM_TOKEN = { win32: 'win32', darwin: 'darwin', linux: 'linux' }[PLATFORM]
+const ARCH_TOKEN = { x64: 'x64', arm64: 'arm64', ia32: 'ia32' }[ARCH] ?? ARCH
+
+if (!PLATFORM_TOKEN) {
+  console.warn(`[fetch-native-sqlite] unsupported platform: ${PLATFORM}, skipping`)
+  process.exit(0)
+}
+
+// ── better-sqlite3 版本 ────────────────────────────────────────────
+// 兼容 optionalDependencies 与 dependencies 两种声明位置——避免将来挪动
+// 依赖段时兜底链静默失效（原本只读 optionalDependencies）。
+const req = createRequire(import.meta.url)
+let version
+try {
+  const pkg = req('../package.json')
+  const raw = pkg.optionalDependencies?.['better-sqlite3'] ?? pkg.dependencies?.['better-sqlite3']
+  if (!raw) {
+    console.log('[fetch-native-sqlite] better-sqlite3 not found in dependencies/optionalDependencies, skipping')
+    process.exit(0)
+  }
+  version = raw.replace(/^[\^~]/, '')
+} catch {
+  console.log('[fetch-native-sqlite] cannot read package.json, skipping')
+  process.exit(0)
+}
+
+// ── 目标路径 ────────────────────────────────────────────────────────
+const TARGET_DIR = join(repoRoot, 'dist', 'native')
+const TARGET = join(TARGET_DIR, 'better_sqlite3.node')
+const FAILED_MARKER = join(TARGET_DIR, '.fetch-failed')
+const NODE_MODULES_NATIVE = join(
+  repoRoot, 'node_modules', 'better-sqlite3', 'build', 'Release', 'better_sqlite3.node',
+)
+
+/**
+ * 失败标记（native-resolver 启动自愈消费）：
+ *   写入——下载链全部失败时落 dist/native/.fetch-failed（{ ts, error }），
+ *         启动自愈见 5 分钟内的新鲜标记即跳过重试，不再每次启动白等下载超时；
+ *   清除——所有成功路径（已有产物/复用 node_modules/下载成功）都清掉陈旧标记。
+ * 静默失败从此有痕迹：用户与自愈逻辑都能看到「上次什么时候、败在哪一步」。
+ */
+function clearFailedMarker() {
+  try {
+    if (existsSync(FAILED_MARKER)) rmSync(FAILED_MARKER, { force: true })
+  } catch { /* 标记清理失败不影响主流程 */ }
+}
+
+function writeFailedMarker(lastError) {
+  try {
+    mkdirSync(TARGET_DIR, { recursive: true })
+    writeFileSync(FAILED_MARKER, JSON.stringify({ ts: Date.now(), error: String(lastError).slice(0, 500) }, null, 2) + '\n')
+  } catch { /* 写不了标记也不阻断——提示文案已在 stdout/stderr */ }
+}
+
+const TARBALL = `better-sqlite3-v${version}-node-v${ABI}-${PLATFORM_TOKEN}-${ARCH_TOKEN}.tar.gz`
+
+// ── 完整性钉扎（供应链防线）────────────────────────────────────────────
+// 官方 release tarball 的 SHA-256（v12.10.0；ABI 127=node22、137=node24）。
+// 来源：github.com 直连下载计算，npmmirror 双源交叉验证一致。
+// 升级 better-sqlite3 版本时须重新生成本表（sha256sum 各平台 tarball），
+// 否则新版本走「无钉扎」策略（见 verifyTarball）——kkgithub 镜像将拒绝服务。
+const SHA256_PINNED = {
+  'better-sqlite3-v12.10.0-node-v127-darwin-arm64.tar.gz': '35533f9ada82cb3f33760c1dc2f128f77c2b34ec2b2ede722824cb64cd50a46a',
+  'better-sqlite3-v12.10.0-node-v127-darwin-x64.tar.gz': '8d2ef0eb7f880f88882f0a7a7362a15e2d210a077681f0672d0dfc8b919bd91b',
+  'better-sqlite3-v12.10.0-node-v127-linux-arm64.tar.gz': 'efb625877ea517be6003c14dbabdb748d0ac172ab50bc4e5af08c2cb272b70c6',
+  'better-sqlite3-v12.10.0-node-v127-linux-x64.tar.gz': '899dcec7d0e4e2ec35db783a9155b878ae15754512585de7352bbd33cb1d6c48',
+  'better-sqlite3-v12.10.0-node-v127-win32-arm64.tar.gz': '81ab2327e76e8cc6290a08528d41f19b913d4c5146bfd12c159970fa59559d48',
+  'better-sqlite3-v12.10.0-node-v127-win32-x64.tar.gz': '86a12ba6f19ecf1e4db4effaf5918e716d4d4fb60b0316e18d95d569ba62d6bc',
+  'better-sqlite3-v12.10.0-node-v137-darwin-arm64.tar.gz': 'b140983c8befcef30532ea615aa106c770f2f95cd20994d31ca593c0b4e85423',
+  'better-sqlite3-v12.10.0-node-v137-darwin-x64.tar.gz': 'a02f8e9c2024f2bd4386e58671524fcf722c5187b549f46a955d8e9c3b22f733',
+  'better-sqlite3-v12.10.0-node-v137-linux-arm64.tar.gz': '7648f3a8295cf03a036eb392b66fbef75347662d654f6ab558f5f33c9e47d69a',
+  'better-sqlite3-v12.10.0-node-v137-linux-x64.tar.gz': 'c2f7503e6cc3a2b1dc9fd03e7194934438f42e0724ecac6696da0582585362f2',
+  'better-sqlite3-v12.10.0-node-v137-win32-arm64.tar.gz': '406e45058184a8f2d2f541fa8deb06933e29bf4dc384fa069c0930dde6e75681',
+  'better-sqlite3-v12.10.0-node-v137-win32-x64.tar.gz': '0f6d948e6438f64c983d08a2048ef10d6f467f36a8c08f20d31f585c019eb83c',
+}
+
+/**
+ * 校验策略：
+ *   有钉扎    → 所有镜像一律校验，不匹配即硬失败换下一路（被替换的镜像无法
+ *               投毒——产物是加载进 agent 进程的原生代码）；
+ *   无钉扎    → 仅允许既有基础设施源（npmmirror registry/CDN、github 官方），
+ *               第三方代理 kkgithub 拒绝——版本升级漏更新哈希表时收窄暴露面，
+ *               而不是放行全部镜像。
+ */
+async function verifyTarball(tmpTar, mirrorName) {
+  const expected = SHA256_PINNED[TARBALL]
+  if (!expected) {
+    if (mirrorName === 'kkgithub') {
+      throw new Error(`no SHA-256 pin for ${TARBALL} — third-party proxy rejected without pin (regenerate SHA256_PINNED on version bump)`)
+    }
+    console.warn(`[fetch-native-sqlite] ⚠ no SHA-256 pin for ${TARBALL} — allowing infra mirror (${mirrorName}) unverified`)
+    return
+  }
+  const hash = createHash('sha256').update(readFileSync(tmpTar)).digest('hex')
+  if (hash !== expected) {
+    throw new Error(`SHA-256 mismatch for ${TARBALL} from ${mirrorName}: got ${hash}`)
+  }
+  console.log(`[fetch-native-sqlite] SHA-256 verified (${hash.slice(0, 12)}…)`)
+}
+
+// ── 镜像源（按优先级）────────────────────────────────────────────────
+// 四路预编译 + 一路源码编译（stage 4），穷尽后才降级——不能随便降级到内存模式。
+const MIRRORS = [
+  {
+    name: 'npmmirror',
+    url: `https://registry.npmmirror.com/-/binary/better-sqlite3/v${version}/${TARBALL}`,
+  },
+  {
+    // registry 域名故障/被墙但 CDN 可达时的直连兜底（registry 302 的最终目标）
+    name: 'npmmirror-cdn',
+    url: `https://cdn.npmmirror.com/binaries/better-sqlite3/v${version}/${TARBALL}`,
+  },
+  {
+    name: 'kkgithub',
+    url: `https://kkgithub.com/WiseLibs/better-sqlite3/releases/download/v${version}/${TARBALL}`,
+  },
+  {
+    name: 'github (direct)',
+    url: `https://github.com/WiseLibs/better-sqlite3/releases/download/v${version}/${TARBALL}`,
+  },
+]
+
+// ── main ────────────────────────────────────────────────────────────
+
+async function main() {
+  // 1. 已有 dist/native 产物 → 跳过（顺带清陈旧失败标记——产物在，标记必过期）
+  if (existsSync(TARGET)) {
+    clearFailedMarker()
+    console.log('[fetch-native-sqlite] native binary already present, skipping')
+    process.exit(0)
+  }
+
+  // 2. node_modules 中已有编译产物 → 直接复用（npm 正常安装了）
+  if (existsSync(NODE_MODULES_NATIVE)) {
+    mkdirSync(TARGET_DIR, { recursive: true })
+    copyFileSync(NODE_MODULES_NATIVE, TARGET)
+    clearFailedMarker()
+    console.log('[fetch-native-sqlite] ✓ native binary found in node_modules, copied to dist/native/')
+    process.exit(0)
+  }
+
+  // 3. 从镜像下载
+  mkdirSync(TARGET_DIR, { recursive: true })
+
+  let lastError = 'unknown'
+  for (const mirror of MIRRORS) {
+    try {
+      console.log(`[fetch-native-sqlite] trying ${mirror.name}: ${mirror.url}`)
+      await downloadAndExtract(mirror.url, TARGET_DIR, mirror.name)
+      clearFailedMarker()
+      console.log(`[fetch-native-sqlite] ✓ downloaded from ${mirror.name}`)
+      process.exit(0)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      lastError = `${mirror.name}: ${msg}`
+      console.warn(`[fetch-native-sqlite] ${mirror.name} failed: ${msg}`)
+    }
+  }
+
+  // 4. 预编译全败 → 源码编译兜底（本地 npm install：走用户自己的 registry 配置，
+  //    prebuild-install 再试一轮 GitHub，失败则 node-gyp 编译——有编译工具链的
+  //    机器此时能装上；npm 整体不可达则快速失败）。启动自愈（native-resolver）
+  //    以 RIVET_FETCH_SKIP_COMPILE=1 调本脚本时跳过——编译动辄数分钟，启动路径
+  //    只做分钟内的下载自愈，编译兜底留给 postinstall/手动重跑。
+  if (!process.env.RIVET_FETCH_SKIP_COMPILE) {
+    try {
+      console.log('[fetch-native-sqlite] mirrors exhausted, trying source build via npm install …')
+      execSync(`npm install better-sqlite3@${version} --no-save --no-audit --no-fund`, {
+        cwd: repoRoot,
+        stdio: 'pipe',
+        timeout: 10 * 60_000, // 源码编译 2-5 分钟常见，给足
+      })
+      if (existsSync(NODE_MODULES_NATIVE)) {
+        mkdirSync(TARGET_DIR, { recursive: true })
+        copyFileSync(NODE_MODULES_NATIVE, TARGET)
+        clearFailedMarker()
+        console.log('[fetch-native-sqlite] ✓ source build succeeded, copied to dist/native/')
+        process.exit(0)
+      }
+      lastError = 'npm install: no binary produced'
+    } catch (err) {
+      lastError = `npm install: ${err instanceof Error ? err.message : String(err)}`.slice(0, 400)
+      console.warn(`[fetch-native-sqlite] source build failed: ${lastError}`)
+    }
+  }
+
+  // 5. 全部失败 → 落失败标记（启动自愈 5 分钟内不再重试）+ 可操作提示
+  writeFailedMarker(lastError)
+  console.warn('')
+  console.warn('⚠ [fetch-native-sqlite] All mirrors failed. better-sqlite3 not available.')
+  console.warn('  Session history & cross-session memory will run in memory-only mode.')
+  console.warn('')
+  // Fix 指引修正（2026-08-17）：旧的 windows-build-tools（npm 包已废弃多年）+
+  // `npm rebuild better-sqlite3 -g tianshu-harness`（rebuild 不到全局安装包里的
+  // optional dep，语法本身也不通）全部换成本仓库自带的预编译拉取脚本——
+  // 无需任何编译工具链，网络恢复后在安装目录重跑一次即可。
+  console.warn('  Fix: 网络恢复后在安装目录重跑本脚本（含预编译四镜像 + 源码编译兜底）:')
+  console.warn('    npm root -g                 # 找到全局 node_modules 路径')
+  if (PLATFORM === 'win32') {
+    console.warn('    cd <该路径>\\tianshu-harness && node scripts\\fetch-native-sqlite.js')
+  } else {
+    console.warn('    cd <该路径>/tianshu-harness && node scripts/fetch-native-sqlite.js')
+  }
+  process.exit(0)
+}
+
+// ── downloadAndExtract ──────────────────────────────────────────────
+
+/**
+ * 下载 better-sqlite3 .tar.gz 预编译包，解压出 .node 文件到 destDir。
+ * 实测镜像 tarball 内部结构（npm 镜像源的 prebuild）：
+ *   build/
+ *     Release/
+ *       better_sqlite3.node   ← 我们需要的（仅 2 层目录，strip-components=2）
+ * 注意：原代码假设是 package/build/Release/...（3 层）用了 strip=3，实际镜像
+ * tarball 是 2 层，strip 3 会剥光路径报 "Not found in archive"。
+ */
+async function downloadAndExtract(url, destDir, mirrorName) {
+  const tmpTar = join(tmpdir(), `better-sqlite3-${mirrorName}-${Date.now()}.tar.gz`)
+
+  try {
+    await downloadFile(url, tmpTar)
+    await verifyTarball(tmpTar, mirrorName)
+    await extractNodeBinary(tmpTar, destDir)
+  } finally {
+    try { await unlink(tmpTar) } catch { /* ignore */ }
+  }
+}
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const timeout = 30_000
+    // 延迟创建文件流：只在确认是最终 200 响应时才 open 目标文件。
+    // 否则重定向链（npmmirror registry → cdn.npmmirror.com 实测 302）会反复
+    // close()/createWriteStream() 同一路径，Windows 文件锁语义下偶发 EBUSY。
+    let file = null
+
+    const req = get(url, { timeout }, (res) => {
+      // 处理重定向：未写任何字节，直接递归跟新 URL
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        // 释放本次响应体，避免 socket 泄漏
+        res.resume()
+        downloadFile(res.headers.location, dest).then(resolve, reject)
+        return
+      }
+      if (res.statusCode !== 200) {
+        res.resume()
+        reject(new Error(`HTTP ${res.statusCode}`))
+        return
+      }
+      // 最终响应——此时才创建目标文件流
+      file = createWriteStream(dest)
+      pipeline(res, file).then(resolve, reject)
+    })
+
+    req.on('error', (err) => {
+      if (file) file.close()
+      reject(err)
+    })
+    req.on('timeout', () => {
+      req.destroy()
+      if (file) file.close()
+      reject(new Error('download timeout'))
+    })
+  })
+}
+
+async function extractNodeBinary(tarPath, destDir) {
+  // 用系统 tar 命令解压。镜像 tarball 结构为 build/Release/better_sqlite3.node
+  // （2 层目录），strip-components=2 剥到文件名本身。Windows 上 bsdtar（Win10+ 自带）
+  // 同样支持该标志；旧版不支持时进 catch 走纯 Node 解压 fallback。
+  const cmd = process.platform === 'win32'
+    ? `tar -xzf "${tarPath}" -C "${destDir}" --strip-components=2 --wildcards "*/better_sqlite3.node"`
+    : `tar -xzf "${tarPath}" -C "${destDir}" --strip-components=2 "*/better_sqlite3.node"`
+
+  try {
+    execSync(cmd, { stdio: 'pipe', timeout: 30_000 })
+  } catch {
+    // tar 可能不支持 --strip-components（Windows 旧版），用 Node 手动解压
+    await extractWithNode(tarPath, destDir)
+  }
+
+  if (!existsSync(join(destDir, 'better_sqlite3.node'))) {
+    throw new Error('better_sqlite3.node not found in tarball after extraction')
+  }
+}
+
+async function extractWithNode(tarPath, destDir) {
+  // 纯 Node 解压：读取 .tar.gz，在 tar 流中找 better_sqlite3.node
+  const zlib = await import('node:zlib')
+  const { createReadStream } = await import('node:fs')
+  const { Transform } = await import('node:stream')
+
+  return new Promise((resolve, reject) => {
+    const gunzip = zlib.createGunzip()
+    let buffer = Buffer.alloc(0)
+    let found = false
+
+    const parser = new Transform({
+      transform(chunk, _encoding, callback) {
+        buffer = Buffer.concat([buffer, chunk])
+        // Tar 格式：512 字节 header + 数据块
+        while (buffer.length >= 512 && !found) {
+          const name = buffer.toString('utf8', 0, 100).replace(/\0/g, '')
+          const sizeStr = buffer.toString('utf8', 124, 136).replace(/\0/g, '').trim()
+          const size = parseInt(sizeStr, 8) || 0
+
+          if (name.endsWith('better_sqlite3.node')) {
+            const dataStart = Math.ceil(512 / 512) * 512 // next 512-aligned
+            const dataEnd = dataStart + size
+            if (buffer.length >= dataEnd) {
+              const fileData = buffer.subarray(dataStart, dataEnd)
+              const dest = join(destDir, 'better_sqlite3.node')
+              // 原 require('node:fs') 在 ESM 模块下会抛 "require is not defined"
+              // ——Windows 上 tar 不支持 --strip-components 进此分支必崩。改用顶部 import。
+              writeFileSync(dest, fileData)
+              found = true
+              resolve()
+              return
+            }
+            // Need more data
+            break
+          }
+
+          // Skip this entry
+          const totalLen = 512 + Math.ceil(size / 512) * 512
+          if (buffer.length >= totalLen) {
+            buffer = buffer.subarray(totalLen)
+          } else {
+            break // need more data
+          }
+        }
+        callback()
+      },
+      flush(callback) {
+        if (!found) reject(new Error('better_sqlite3.node not found in tar stream'))
+        callback()
+      },
+    })
+
+    createReadStream(tarPath)
+      .pipe(gunzip)
+      .pipe(parser)
+      .on('error', reject)
+  })
+}
+
+main()

package/scripts/prune-installed-wasms.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * prune-installed-wasms.js — npm 安装后裁剪 tree-sitter-wasms 的多余语法 wasm。
+ *
+ * 背景：tree-sitter-wasms 整包约 50MB（40+ 语言 grammar），但运行时只有
+ * src/repo/meridian-parser.ts 加载 TS/Python/Go 三个（见 LANG_WASM）。
+ * 桌面 sidecar 打包期已由 stage-runtime-deps.js 裁剪；npm 用户走 postinstall，
+ * 在这里对已安装到 node_modules 的副本做同样裁剪，把安装体积砍掉 ~47MB。
+ *
+ * 安全语义：
+ *   - pnpm 内容寻址 store（路径含 .pnpm）会污染共享缓存 → 跳过
+ *   - 任何异常只告警不阻断安装（裁剪失败只是体积大，功能不受影响）
+ */
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { createRequire } from 'node:module'
+import { pruneTreeSitterWasms } from './tree-sitter-wasm-keep.js'
+
+try {
+  const req = createRequire(import.meta.url)
+  const wasmsPkgJson = req.resolve('tree-sitter-wasms/package.json')
+  const pkgRoot = dirname(wasmsPkgJson)
+
+  if (pkgRoot.includes('.pnpm')) {
+    console.log('[prune-installed-wasms] pnpm 共享 store，跳过裁剪')
+    process.exit(0)
+  }
+
+  const outDir = join(pkgRoot, 'out')
+  if (!existsSync(outDir)) {
+    console.log('[prune-installed-wasms] tree-sitter-wasms/out 不存在，跳过')
+    process.exit(0)
+  }
+
+  const { kept, removed } = pruneTreeSitterWasms(outDir)
+  if (removed.length > 0) {
+    console.log(
+      `[prune-installed-wasms] 保留 ${kept.length} 个 grammar（${kept.join(', ')}），裁剪 ${removed.length} 个`,
+    )
+  } else {
+    console.log('[prune-installed-wasms] 已是最小集，无需裁剪')
+  }
+} catch (err) {
+  console.warn('[prune-installed-wasms] 裁剪失败（不影响功能）:', err && err.message ? err.message : err)
+}

package/scripts/tree-sitter-wasm-keep.js

@@ -0,0 +1,40 @@
+/**
+ * Allowlist of tree-sitter grammar wasm files shipped in the packaged sidecar.
+ *
+ * Only languages loaded by `src/repo/meridian-parser.ts` (LANG_WASM) are kept.
+ * Unsupported languages fall back to heuristic chunking; missing wasm would
+ * only surface if meridian tried to parse them (it doesn't).
+ */
+import { existsSync, readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Filenames under tree-sitter-wasms/out/ that must remain after staging. */
+export const TS_WASM_KEEP = new Set([
+  'tree-sitter-typescript.wasm',
+  'tree-sitter-python.wasm',
+  'tree-sitter-go.wasm',
+])
+
+/**
+ * Delete non-allowlisted .wasm files under `outDir`.
+ * @param {string} outDir absolute path to tree-sitter-wasms/out
+ * @returns {{ kept: string[], removed: string[] }}
+ */
+export function pruneTreeSitterWasms(outDir) {
+  /** @type {string[]} */
+  const kept = []
+  /** @type {string[]} */
+  const removed = []
+  if (!existsSync(outDir)) return { kept, removed }
+  for (const f of readdirSync(outDir)) {
+    if (!f.endsWith('.wasm')) continue
+    const p = join(outDir, f)
+    if (TS_WASM_KEEP.has(f)) {
+      kept.push(f)
+    } else {
+      rmSync(p, { force: true })
+      removed.push(f)
+    }
+  }
+  return { kept, removed }
+}