dsh-data-domain-knowledge 0.1.0-alpha.13 → 0.1.0-alpha.15

package/src/diagnosis/store.ts

@@ -7,7 +7,7 @@ import {
   cardFromRecord, cardsToGraph, CARD_EDGE_KINDS, graphToCards, parseCard, serializeCard,
   RUN_EDGE_KINDS, type DiagnosisCard,
 } from './cards.js'
-import { caseCardOf, parseRunSource, renderRunSource, runReferenceProblems, runToGraph } from './run.js'
+import { caseViewOfRun, parseRunSource, renderRunSource, runReferenceProblems, runToGraph } from './run.js'
 import type {
   AttributionCase, AttributionEdge, AttributionEvent, AttributionGraphData, AttributionNode, AttributionNodeKind, DiagnosisRunRecord,
 } from './types.js'
@@ -22,7 +22,7 @@ import type { SchemaType } from '../types.js'
  * | 目录 | 内容 | 谁是真相 |
  * | --- | --- | --- |
  * | `01_source_raw/` | 手册、复盘与排查原文 | SourceRaw 的唯一真相 |
- * | `02_wiki/diagnosis/` | 五类卡片（三段式） | **知识侧的唯一真相**，由一次排查 / 载入示例 / 迁移直接写入（0044 起不经人确认） |
+ * | `02_wiki/diagnosis/` | 历史诊断卡片 | 仅为旧数据兼容读取；新排查不再写 diagnosis/case 卡片 |
  *
  * `05_diagnosis/` 在 v1.1 撤销了（0021 §0.3）。它同时装着两类东西 —— 「一次排查的产物」
  * （源头）与「五类模板卡」（配置）—— 一个编号段混装两种性质，`rebuild --only` 的语义
@@ -58,8 +58,8 @@ const LEGACY_RUN_SHARDS: Record<string, AttributionNodeKind> = {
   'causes.jsonl': 'cause',
 }
 
-/** 读取顺序的显式来源，界面据此说明「现在看到的是哪一份」。 */
-export type DiagnosisSource = 'cards' | 'jsonl' | 'empty'
+/** 读取来源，界面据此说明当前展示的是卡片、记录、旧快照还是空库。 */
+export type DiagnosisSource = 'cards' | 'records' | 'jsonl' | 'empty'
 
 export interface DiagnosisSnapshot {
   graph: AttributionGraphData
@@ -87,7 +87,7 @@ export interface DiagnosisSnapshot {
  * `loadSources` 是 v1.1 新增的：一次排查的产物现在是一条 `agent_diagnosis_case`
  * 的 SourceRaw，归因图读的是它，而不是自造的 jsonl。
  */
-type DiagnosisHost = Pick<KnowledgeRuntime, 'rootDir' | 'addSource' | 'writeCard' | 'loadSources' | 'loadCards' | 'loadEvents' | 'readCard'>
+type DiagnosisHost = Pick<KnowledgeRuntime, 'rootDir' | 'addSource' | 'writeCard' | 'loadSources' | 'loadCards' | 'loadEvents' | 'readCard' | 'knowledgeStoreAvailable'>
 
 export class DiagnosisStore {
   constructor(private readonly host: DiagnosisHost) {}
@@ -113,26 +113,53 @@ export class DiagnosisStore {
    * 造出「设置里改了、磁盘上那份没改」的第二真源。
    */
   async ensure(): Promise<{ seeded: boolean; migrated: boolean; problems: string[] }> {
+    /**
+     * **「读不到」不等于「空」**（0070）。
+     *
+     * `readCards()` 在存储不可用时返回空数组，于是「node:sqlite 连不上 / 属主标记不符 /
+     * 权限不对」会被读成「这个库什么都还没有」，接着走下面的旧格式迁移 —— 那是一次
+     * **写**（会写入内置种子来源与几十张卡）。一次可恢复的读故障就这样变成不可逆的污染。
+     * 所以先问一句存储到底在不在，不在就什么都不做，并如实报出来。
+     */
+    if (!await this.host.knowledgeStoreAvailable()) {
+      return { seeded: false, migrated: false, problems: ['知识存储当前不可用，已跳过内置示例与旧格式迁移；请先解决存储问题再打开本页。'] }
+    }
     if ((await this.readCards()).length > 0) return { seeded: false, migrated: false, problems: [] }
     if ((await this.legacyShardFiles()).length > 0) return await this.migrate()
     return { seeded: false, migrated: false, problems: [] }
   }
 
   /**
-   * 载入**内置示例**：一份排查手册 + 三篇复盘 + 三次排查日志 → SourceRaw → 卡片 → 图。
+   * 载入**内置示例**：一份排查手册 + 三篇复盘 + 三次排查日志 → SourceRaw、可复用诊断卡与只读排查视图。
    *
    * 只有用户明确点了「载入内置示例」才走这里（`ensure()` 不再自动调用）。幂等：
    * `addSource` 按 `externalId`、`writeCard` 按 entityId，点两次不会写出第二份。
    *
-   * **它走的是「提议 → 确认」那条门，不是绕过它**（0021 §6.1）。区别只在确认者是谁：
-   * 用户点「载入内置示例」这个动作本身就是**对整批示例的确认**，所以这里给每条提议记下
-   * `confirmedBy = user:load-sample`，然后照常走 `writeCard`。这样做的两个好处：
-   * 待办区里能看到这批卡片是怎么来的；而「未确认不落 `02_wiki/`」这条规则没有被开一个
-   * 后门 —— 例外是**确认者的身份**，不是门的缺失。
+   * 示例里的可复用诊断 Knowledge 是预先整理好的演示数据，直接写入当前知识库。
+   * 三条排查记录作为 SourceRaw 写入，并由读取层派生只读 Case 视图；不创建 `diagnosis/case` WikiCard。
    */
   async loadSample(): Promise<{ seeded: boolean; migrated: boolean; problems: string[] }> {
+    /**
+     * 载入示例是一次**写**，所以门要在服务端，不能只在界面上。
+     *
+     * `canLoadSample` 原来只出现在 `snapshot()` 的返回值里，用来决定那枚按钮显不显示 ——
+     * 而 `POST /diagnosis/sample` 直接调这里。任何非界面的调用方（脚本、旧标签页、
+     * 以后的 runbook）打一次，就能在一个已经有真实知识的库上注入一整套演示数据，
+     * 库里于是有两份互相矛盾的知识，而这正是本文件开头要防的事。
+     *
+     * **不给覆盖开关**：曾经加过一个 `force`，但它没有任何调用方（路由按无参调用），
+     * 而且「往有真实知识的库里再塞一套演示」本来就不该是一个可选项 —— 那正是这条门要防的。
+     */
+    const allowed = await this.sampleAllowed()
+    if (!allowed.ok) {
+      return { seeded: false, migrated: false, problems: [`这个知识库里已经有内容（${allowed.reason}），不再载入内置示例。`] }
+    }
     const { problems: sourceProblems, refs } = await this.writeSources(seedSources())
-    const cards = withSourceRefs(graphToCards(SEED_GRAPH, SEED_CASES), refs, SEED_CASES)
+    const cards = withSourceRefs(
+      graphToCards(SEED_GRAPH),
+      refs,
+      SEED_CASES,
+    )
     const problems = [...sourceProblems, ...await this.writeCards(cards, 'user:load-sample')]
     return { seeded: true, migrated: false, problems }
   }
@@ -142,44 +169,55 @@ export class DiagnosisStore {
     return this.readEvents()
   }
 
+  /**
+   * 「能不能载入内置示例」的**唯一**判据 —— 只看四个计数。
+   *
+   * 抽出来是因为它有两个消费者（`snapshot()` 的 `canLoadSample` 与 `loadSample()` 的门），
+   * 各写一份的话，界面说「可以」而服务端说「不行」只是时间问题。判据与**读取**分开：
+   * 两边各自的读取是必要的（一个已经拿到了卡片/Event，一个还没读），规则不必要各写一遍。
+   */
+  private static sampleGate(state: { cards: number; events: number; runs: number; shards: number }): { ok: boolean; reason?: string } {
+    if (state.cards > 0) return { ok: false, reason: '已经有卡片' }
+    if (state.events > 0) return { ok: false, reason: '已经有 Event' }
+    if (state.runs > 0) return { ok: false, reason: '已经有排查记录' }
+    if (state.shards > 0) return { ok: false, reason: '还有旧格式的 05_diagnosis 分片等待迁移' }
+    return { ok: true }
+  }
+
+  private async sampleAllowed(): Promise<{ ok: boolean; reason?: string }> {
+    return DiagnosisStore.sampleGate({
+      cards: (await this.readCards()).length,
+      events: (await this.readEvents()).length,
+      runs: (await this.readRuns()).records.length,
+      shards: (await this.legacyShardFiles()).length,
+    })
+  }
+
   async snapshot(): Promise<DiagnosisSnapshot> {
     const { seeded, migrated, problems } = await this.ensure()
     const cards = await this.readCards()
     const events = await this.readEvents()
+    const baseGraph = cards.length > 0 ? { nodes: [], edges: [] } : await this.readLegacyGraph()
+    const baseCases = cards.length > 0 ? [] : await this.readLegacyCases()
+    const built = await this.buildGraph(cards, baseGraph, baseCases)
+    const runRecords = (await this.readRuns()).records
     /**
-     * 「什么都没有」= 没有卡片、也没有旧 jsonl。它是**可以载入内置示例**的唯一条件：
+     * 「什么都没有」= 没有卡片、Event、排查日志和旧 jsonl。它是**可以载入内置示例**的唯一条件：
      * 已经有知识（不管哪一代形态）时不该再往里塞示例 —— 那会变成第二份互相矛盾的知识。
      */
-    const canLoadSample = cards.length === 0 && events.length === 0 && (await this.legacyShardFiles()).length === 0
-
-    if (cards.length > 0) {
-      const built = await this.buildGraph(cards)
-      return {
-        graph: built.graph,
-        cases: built.cases,
-        events,
-        issues: validateDiagnosis(built.graph),
-        seeded,
-        migrated,
-        source: 'cards',
-        canLoadSample: false,
-        problems: [...problems, ...built.problems],
-      }
-    }
-
-    // 还没有卡片：旧 jsonl 就是当前可读的来源；两份都没有就是一个空库。
-    const graph = await this.readLegacyGraph()
-    const cases = await this.readLegacyCases()
+    const canLoadSample = DiagnosisStore.sampleGate({
+      cards: cards.length, events: events.length, runs: runRecords.length, shards: (await this.legacyShardFiles()).length,
+    }).ok
     return {
-      graph,
-      cases,
+      graph: built.graph,
+      cases: built.cases,
       events,
-      issues: validateDiagnosis(graph),
+      issues: validateDiagnosis(built.graph),
       seeded,
       migrated,
-      source: canLoadSample ? 'empty' : events.length > 0 ? 'cards' : 'jsonl',
+      source: canLoadSample ? 'empty' : cards.length > 0 ? 'cards' : events.length > 0 || runRecords.length > 0 ? 'records' : 'jsonl',
       canLoadSample,
-      problems,
+      problems: [...problems, ...built.problems],
     }
   }
 
@@ -190,21 +228,27 @@ export class DiagnosisStore {
    * 与四条执行边全部来自 `agent_diagnosis_case` 的 SourceRaw。合成一张图是**读**的时候
    * 做的，不是写的时候 —— 写的时候合成，等于让一次执行的结果变成可复用的知识。
    */
-  private async buildGraph(cards: DiagnosisCard[]): Promise<{ graph: AttributionGraphData; cases: AttributionCase[]; problems: string[] }> {
+  private async buildGraph(cards: DiagnosisCard[], baseGraph: AttributionGraphData = { nodes: [], edges: [] }, baseCases: AttributionCase[] = []): Promise<{ graph: AttributionGraphData; cases: AttributionCase[]; problems: string[] }> {
     const compiled = cardsToGraph(cards)
     const problems = [...compiled.problems]
-    const nodes: AttributionNode[] = [...compiled.graph.nodes]
-    const edges: AttributionEdge[] = [...compiled.graph.edges]
+    const nodes: AttributionNode[] = [...baseGraph.nodes, ...compiled.graph.nodes]
+    const edges: AttributionEdge[] = [...baseGraph.edges, ...compiled.graph.edges]
+    const knownCardNodes = [...baseGraph.nodes, ...compiled.graph.nodes]
+    const cases = new Map<string, AttributionCase>()
+    for (const item of [...baseCases, ...compiled.cases]) cases.set(item.id, item)
 
     const runs = await this.readRuns()
     problems.push(...runs.problems)
     for (const record of runs.records) {
       const run = runToGraph(record)
       // 引用完整性要**连这次排查自己产出的 id 一起算**：路径里的 `E1` / `C1` 正是它写下的。
-      const known = new Set([...compiled.graph.nodes.map(node => node.id), ...run.nodes.map(node => node.id)])
+      const known = new Set([...knownCardNodes.map(node => node.id), ...run.nodes.map(node => node.id)])
       problems.push(...run.problems, ...runReferenceProblems(record, known))
       nodes.push(...run.nodes)
       edges.push(...run.edges)
+      const symptomTitle = knownCardNodes.find(node => node.id === record.symptomId)?.title ?? record.symptomId
+      const view = caseViewOfRun(record, symptomTitle)
+      cases.set(view.id, view)
     }
 
     /**
@@ -219,7 +263,7 @@ export class DiagnosisStore {
     nodes.push(...legacyRun.nodes)
     edges.push(...legacyRun.edges)
 
-    return { graph: dedupe({ nodes, edges }, problems), cases: compiled.cases, problems }
+    return { graph: dedupe({ nodes, edges }, problems), cases: [...cases.values()], problems }
   }
 
   /**
@@ -247,14 +291,15 @@ export class DiagnosisStore {
 
   async readGraph(): Promise<AttributionGraphData> {
     const cards = await this.readCards()
-    if (cards.length > 0) return (await this.buildGraph(cards)).graph
-    return await this.readLegacyGraph()
+    const baseGraph = cards.length > 0 ? { nodes: [], edges: [] } : await this.readLegacyGraph()
+    return (await this.buildGraph(cards, baseGraph)).graph
   }
 
   async readCases(): Promise<AttributionCase[]> {
     const cards = await this.readCards()
-    if (cards.length > 0) return cardsToGraph(cards).cases
-    return await this.readLegacyCases()
+    const baseGraph = cards.length > 0 ? { nodes: [], edges: [] } : await this.readLegacyGraph()
+    const baseCases = cards.length > 0 ? [] : await this.readLegacyCases()
+    return (await this.buildGraph(cards, baseGraph, baseCases)).cases
   }
 
   /* ────────────────────────────────────────────── 卡片：读写 ── */
@@ -326,15 +371,11 @@ export class DiagnosisStore {
   }
 
   /**
-   * 一次排查结束：写一条 SourceRaw，并**直接写入**一张案例卡片。
-   *
-   * 0044：案例卡片原来只提议、等人确认。与编译那条链路一样改成直接入库 ——
-   * 一次排查的价值就在于「当时是怎么走的」，让它停在待办队列里等于把经验丢掉。
-   * 卡片会被标成 `unreviewed`，人在「知识库 → Wiki」里 review 它。
-   *
-   * 幂等：`externalId` = runId，同一次排查重跑不会写出第二条来源；卡片按 entityId 写入。
+   * 一次排查结束只写一条 SourceRaw。案例视图从这条记录派生；Knowledge / Event 的抽取与归一
+   * 仍由知识处理阶段执行，避免把同一份排查过程再写成另一张 WikiCard。
+   * 幂等：`externalId` = runId，同一次排查重跑不会写出第二条来源。
    */
-  async recordRun(record: DiagnosisRunRecord): Promise<{ sourceId?: string; entityId?: string; problems: string[] }> {
+  async recordRun(record: DiagnosisRunRecord): Promise<{ sourceId?: string; problems: string[] }> {
     const problems: string[] = []
     const added = await this.host.addSource({
       title: `AI 诊断日志 · ${record.symptomId} · ${record.runId}`,
@@ -345,18 +386,7 @@ export class DiagnosisStore {
     if (added.ok === false) return { problems: [`诊断日志 ${record.runId} 写入失败：${added.error.code} ${added.error.message}`] }
     const sourceId = added.data.sourceId
 
-    const symptomTitle = (await this.readCards()).find(card => card.entityId === record.symptomId)?.title ?? record.symptomId
-    const draft = caseCardOf(record, symptomTitle)
-    const written = await this.host.writeCard({
-      entityType: draft.entityType as SchemaType,
-      entityId: draft.entityId,
-      title: draft.title,
-      content: renderCardBody(draft),
-      sourceRefs: [sourceId],
-      status: 'unreviewed',
-    })
-    if (written.ok === false) problems.push(`案例卡片 ${draft.entityId} 写入失败：${written.error.code} ${written.error.message}`)
-    return { sourceId, ...(written.ok === false ? {} : { entityId: draft.entityId }), problems }
+    return { sourceId, problems }
   }
 
   /* ────────────────────────────────────────────── 旧知识根迁移 ── */
@@ -499,8 +529,8 @@ export function renderCardBody(card: DiagnosisCard): string {
 /**
  * 给卡片挂出处。
  *
- * 规则是**数据驱动的**，不是凭印象分的：案例卡片与它自己的复盘原文一一对应；
- * 其它卡片取「第一篇走过它的复盘」，没有走过它的就挂那本手册。
+ * 规则是**数据驱动的**，不是凭印象分的：可复用诊断卡优先引用第一篇走过该节点的复盘；
+ * 没有经过复盘的节点引用手册。历史 Case 卡仍由旧数据读取，不在新示例里生成。
  */
 function withSourceRefs(
   cards: DiagnosisCard[],

package/src/diagnosis/types.ts

@@ -15,7 +15,8 @@ import type { ProblemClassId } from './problem-classes.js'
 export type NodeLayer = 'type' | 'reference' | 'instance'
 
 /**
- * 九类归因节点。与 wiki 卡片的 `entity_type` 一一对应（`asset` 与三类执行产物除外）。
+ * 九类归因图节点。当前 Knowledge 节点可对应 WikiCard；`case` 是排查记录视图，
+ * `asset` 与执行产物也不对应 WikiCard。历史 Case WikiCard 仅为兼容数据。
  *
  * **两个名字用的是下划线**（`check_point` / `failure_reason`），卡片类型用连字符
  * （`diagnosis/check-point` / `diagnosis/failure-reason`）：kind 是代码里的标识符，
@@ -187,18 +188,9 @@ export interface AttributionGraphData {
 }
 
 /**
- * 案例 = **一篇 wiki 定义 + 一条有序排查路径**。
- *
- * 它住在领域层而不是示例里（原来是 `seed.ts`）：案例是编译产物的一种
- * （`cardsToGraph()` 从卡片把它算出来，`/diagnosis/graph` 把它发给界面），
- * 而示例只是**一份**案例的取值来源。视图要渲染「服务端给的案例」，
- * 那它 import 的形状就不该从示例模块里拿。
- *
- * 两段各有明确消费者，不能合并：
- * - `sections` 是给人读、给向量召回的散文（可 diff、可评审、可追溯）；
- * - `path` 是给图和剪枝用的结构（有序、可判真假、带被否定的分支）。
- *
- * 序和枚举一旦写进散文，归并算法就再也读不到它们了 —— 所以路径单独成段。
+ * Case 是一次排查记录的只读展示投影，不是持久化实体。
+ * `sections` 供人阅读，`path` 保留检查顺序与被否定的分支；来源是 SourceRaw 运行记录。
+ * 历史 `diagnosis/case` WikiCard 仍可读取，但新的运行与示例载入不再生成它。
  */
 export interface CaseSection {
   heading: string
@@ -223,9 +215,11 @@ export interface AttributionCase {
   /** 误导段：最贵的那条知识。没有它，下次还会有人在同一个假设上烧掉四十分钟。 */
   misleading?: { nodeId: string; label: string; wastedMinutes: number; why: string }
   rootCause: string
+  /** 排查记录里的根因确认状态；旧案例卡片缺省时按已有内容展示。 */
+  rootCauseStatus?: 'confirmed' | 'unconfirmed'
 }
 
-/** 从通用 `event` Wiki 卡读取的一次具体发生，供智能归因的事件视图展示。 */
+/** 从独立 Event 实体读取的一次具体发生，供智能归因的事件视图展示。 */
 export interface AttributionEvent {
   id: string
   title: string
@@ -323,8 +317,8 @@ export interface DiagnosisRunCause {
 /**
  * 一次排查的完整记录。落到 SourceRaw 正文里的 ```json diagnosis-run 块。
  *
- * 它与案例卡片的区别是**谁写的、有没有被归纳过**：这里是 Agent 跑完一圈留下的
- * 原始记录，案例卡片是**之后**归纳出来的知识（而且必须经人确认才生效）。
+ * 它是 Agent 跑完一圈留下的原始记录。Case 视图从这条记录派生；可复用 Knowledge 与 Event
+ * 由独立抽取和归一阶段生成，不在这条记录写成第二张卡片。
  */
 export interface DiagnosisRunRecord {
   /** 本次排查的 runId。同时用作 SourceRaw 的 `externalId`，重跑不产生第二条记录。 */

package/src/environment/dsh-python.ts

@@ -0,0 +1,156 @@
+/**
+ * DSH 自带 Python 的落点（2026-10-18）。
+ *
+ * 桌面端把 Python 3.12 **打在自己的运行时里**：
+ * `<App>/Contents/Resources/runtime/primary-runtime/dependencies/python`（清单见同目录
+ * `runtime.json` 的 `python` 字段）。但这一层没把位置告诉插件 —— 宿主不导出 `DSH_PYTHON`，
+ * 于是「一键准备」的默认值 `python3` 落到了系统那个 3.9（macOS 命令行工具自带的正是 3.9），
+ * 第一步就报「Python 版本不受支持」，而机器上明明有 3.12。
+ *
+ * 所以这里自己找，顺序是：
+ *
+ * 1. **`DSH_PYTHON`** —— 显式覆盖永远是第一位的（文档里承诺的自定义入口）。
+ * 2. **DSH 自带的那一个** —— 从宿主告诉我们的两个锚点推：Electron 的 `resourcesPath`，
+ *    以及 `process.execPath`（桌面端是 `Contents/MacOS/<App>`，`ELECTRON_RUN_AS_NODE` 下
+ *    它就是运行时用的那个可执行文件）。两者都会向上找几级，因为包装脚本与真实二进制的
+ *    层级不一定一样。
+ * 3. **PATH 上的 `python3`** —— 都没有才退回。
+ *
+ * ## 这里只回答「哪个路径最可能是它」，不回答「它是哪个版本」
+ *
+ * 版本判断必须由准备阶段做（它要跑一次 `sys.version_info`，并把结论写进安装日志）。
+ * 在这里再探测一遍等于把同步可判的事情做成两次异步调用，而且拿到版本也不知道该报给谁。
+ */
+
+import { existsSync } from 'node:fs'
+import { posix, win32 } from 'node:path'
+import { runProcess } from './process.js'
+
+/**
+ * 按**目标平台**拼路径，不按跑这段代码的机器。
+ *
+ * 生产里两者永远一致（Windows 上 `process.platform` 就是 `win32`），但这里允许注入平台 ——
+ * 而 POSIX 上的 `dirname('C:\\x\\node.exe')` 会给出 `'.'`，于是那条 Windows 断言在 mac 上
+ * 跑不通。用平台自己的路径工具，注入才是真的能测。
+ */
+const pathsFor = (platform: NodeJS.Platform): typeof posix => platform === 'win32' ? win32 : posix
+
+/** 相对 App 资源根的落点。`runtime.json` 就在它的上一级。 */
+const BUNDLE_RELATIVE = ['runtime/primary-runtime/dependencies/python']
+
+/** 一个解释器可能叫的几个名字。Windows 的独立发行版把 `python.exe` 放在根上。 */
+function interpreterNames(root: string, platform: NodeJS.Platform): string[] {
+  const { join } = pathsFor(platform)
+  return platform === 'win32'
+    ? [join(root, 'python.exe'), join(root, 'python3.exe')]
+    : [join(root, 'bin', 'python3'), join(root, 'bin', 'python')]
+}
+
+/** 从锚点向上走几级，每一级都试「本体」和「本体/Resources」两种排法。 */
+function bundleCandidates(anchor: string, platform: NodeJS.Platform): string[] {
+  const { dirname, join } = pathsFor(platform)
+  const found: string[] = []
+  let dir = anchor
+  for (let depth = 0; depth < 6; depth += 1) {
+    for (const relative of BUNDLE_RELATIVE) {
+      for (const name of interpreterNames(join(dir, relative), platform)) found.push(name)
+      // macOS / Windows 的 `.app`：真实资源在 `Contents/Resources`，而锚点是 `Contents/MacOS`。
+      for (const name of interpreterNames(join(dir, 'Resources', relative), platform)) found.push(name)
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return found
+}
+
+export interface PythonPick {
+  /** 要拿去建虚拟环境的解释器。 */
+  path: string
+  /** 它从哪来 —— 报错时要能说清「我没找到自带的那个」。 */
+  source: 'override' | 'bundled' | 'path'
+}
+
+export interface PythonProbe {
+  env?: Record<string, string | undefined>
+  /** Electron 的 `process.resourcesPath`；不在 Electron 里时省略。 */
+  resourcesPath?: string
+  /** 宿主的可执行文件路径；默认取 `process.execPath`。 */
+  execPath?: string
+  platform?: NodeJS.Platform
+  /** 存在性判断，测试里换成假的。 */
+  exists?: (path: string) => boolean
+}
+
+/**
+ * 挑一个基础解释器。**纯函数**（存在性判断可注入），所以「自带优先于 PATH」这条能被单独断言。
+ */
+export function pickBasePython(probe: PythonProbe = {}): PythonPick {
+  const env = probe.env ?? process.env
+  const override = env.DSH_PYTHON?.trim()
+  if (override) return { path: override, source: 'override' }
+  const platform = probe.platform ?? process.platform
+  const exists = probe.exists ?? existsSync
+  const anchors: string[] = []
+  if (probe.resourcesPath) anchors.push(probe.resourcesPath)
+  const { dirname } = pathsFor(platform)
+  const executables = [env.DSH_DESKTOP_NODE_EXECUTABLE, probe.execPath ?? process.execPath]
+  for (const executable of executables) {
+    const value = executable?.trim()
+    if (value) anchors.push(dirname(value))
+  }
+  for (const anchor of anchors) {
+    for (const candidate of bundleCandidates(anchor, platform)) {
+      if (exists(candidate)) return { path: candidate, source: 'bundled' }
+    }
+  }
+  return { path: 'python3', source: 'path' }
+}
+
+/** 报错里那句「没找到自带的那一个」用得上。 */
+export function pythonSourceLabel(source: PythonPick['source']): string {
+  return source === 'override' ? 'DSH_PYTHON' : source === 'bundled' ? 'DSH 自带运行时' : 'PATH 上的 python3'
+}
+
+/**
+ * 这个解释器能不能加载**第三方原生扩展**（torch 这类 pip 装的 dylib）。
+ *
+ * macOS 上不行的一种情况是真实存在过的（2026-10-18 实测）：DSH 桌面端把 Python 3.12
+ * 打在自己的运行时里，并给它签了 Developer ID + **hardened runtime**
+ * （`flags=0x10000(runtime)`），又没有 `com.apple.security.cs.disable-library-validation`。
+ * 库校验因此生效 —— 它只肯加载**同一 Team ID** 签的 dylib。pip 上的 torch 是 ad-hoc 签名
+ * （Team ID 为空），于是：
+ *
+ * ```
+ * OSError: dlopen(.../libtorch_global_deps.dylib, 0x000A):
+ *   code signature ... not valid for use in process:
+ *   mapping process and mapped file (non-platform) have different Team IDs
+ * ```
+ *
+ * 同一个 dylib 换成 uv 管的独立 CPython（`adhoc, linker-signed`，没有 runtime 标记）
+ * 就能加载 —— 这一条在同一台机器上验过。
+ *
+ * 判据读的是 `codesign` 的 flags，不看路径：运行时目录在某些安装形态下不在 `.app` 里，
+ * 而「带不带 hardened runtime」才是真正决定库校验的那件事。没有 `codesign`（Linux/Windows）
+ * 或读不到（没签名）时一律当「能加载」—— 不因为探测失败就改道去下载解释器。
+ */
+export async function hasHardenedRuntime(path: string, run: typeof runProcess = runProcess): Promise<boolean> {
+  if (process.platform !== 'darwin') return false
+  try {
+    const output = await run('/usr/bin/codesign', ['-dv', '--verbose=2', path], { timeoutMs: 10_000 })
+    const flags = /flags=0x[0-9a-f]+\(([^)]*)\)/i.exec(output)?.[1] ?? ''
+    return flags.split(',').some(flag => flag.trim() === 'runtime')
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 这个解释器要不要换成 uv 管的那一个。
+ *
+ * 判据只有一条：**带 hardened runtime 就用不了第三方原生扩展**（见 `hasHardenedRuntime`）。
+ * `DSH_PYTHON` 显式给的不改道 —— 那是用户的选择；插件只把风险写进日志。
+ */
+export function needsManagedInterpreter(pick: PythonPick, hardened: boolean): boolean {
+  return hardened && pick.source !== 'override'
+}