dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/convert/host.ts

@@ -0,0 +1,579 @@
+/**
+ * The convert host — the DSH-facing half of multi-format conversion.
+ *
+ * Since 0018 this lives inside `plugins/dsh-data-domain-knowledge` (issue 0018):
+ * conversion is a sub-capability of knowledge, mounted as one plugin, with one
+ * sidebar entry and one settings surface for the user. The kernel
+ * (`dsh-convert-core`) stays an independent, optional package that
+ * `core-loader.ts` imports lazily.
+ *
+ * Layering this file must keep:
+ *
+ *   kernel (convert-core)   input → knowledge-ready Markdown + assets + console
+ *   this host               settings, agent tools, /convert route, ingestion
+ *
+ * Nothing about parsing lives here; nothing about DSH lives in the kernel. That
+ * is why the same console still works standalone at `tita-convert`.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { stat } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool, type PreToolDecision, type ToolRunContext } from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-settings'
+import type { ConvertRequest, ConvertService, ConvertTask } from 'dsh-convert-core'
+import { ConvertCoreMissingError, loadConvertCore } from './core-loader.js'
+import { tmpRoot, workspaceOutputRoot } from '../layout.js'
+import { ingestDelivery, type IngestOutcome, type IngestTarget } from './ingest.js'
+import {
+  CONVERT_SETTINGS_NAMESPACE,
+  DEFAULT_CONVERT_CONFIG,
+  failure,
+  success,
+  WRITE_TOOLS,
+  type ConvertPluginConfig,
+  type Envelope,
+} from './types.js'
+
+export { CONVERT_SETTINGS_NAMESPACE, DEFAULT_CONVERT_CONFIG, defaultConvertRoot } from './types.js'
+
+/** Route prefix the console and API are mounted on. Frozen contract. */
+export const MOUNT_PATH = '/convert'
+
+const PREVIEW_CHARS = 1200
+
+/**
+ * 转换的设置 schema。
+ *
+ * 0029 起它**没有路径字段**：交付物与工作区都从知识插件的 `agentRoot` 推出来
+ * （`<agentRoot>/output/<日期>/`、`<agentRoot>/tmp/`）。一个 Agent 只有一个根路径，
+ * 所以这里再放一个 `rootDir` 就等于把「东西存在哪」这个答案劈成两半。
+ *
+ * 定义本身搬到了 `./settings-schema.js`（纯数据、可被 `Config` 组合并在
+ * `node --test` 里独立解析）；这里 re-export，保持既有出口不变。
+ */
+export { CONVERT_SETTINGS_SCHEMA } from './settings-schema.js'
+
+/** What the convert host needs from the knowledge plugin it now lives in. */
+export interface ConvertHostDeps {
+  /** The live knowledge runtime; the seam may only call `addSource` on it. */
+  runtime(): IngestTarget
+  /** Absolute knowledge root the runtime currently writes to. */
+  knowledgeRoot(): string
+  /**
+   * 当前工作项目（交付物的落点）。省略时退回进程的工作目录。
+   *
+   * 转换内核是**宿主级单例**，而「工作项目」是**每个会话各自**的 —— 内核这一层拿不到
+   * 会话，所以这里只能给一个宿主级的答案。单项目部署（一个 DSH 进程服务同一个项目）下
+   * 两者一致；多项目共用同一个宿主时，交付物会集中落到宿主启动目录下，而不是各自项目里。
+   * 要做到完全按会话分，需要内核支持**按请求**解析输出目录，那是内核侧的一处改造。
+   */
+  workspace?(): string
+  /**
+   * Resolve an ingest target for one knowledge base (issue 0019). Optional so the
+   * host still works when the registry is unavailable; when it is absent every
+   * conversion lands in the default knowledge base.
+   */
+  resolveTarget?(kbId?: string): { runtime: IngestTarget; knowledgeRoot: string }
+  /**
+   * Tita Agent 根路径（0029）。转换的交付物与工作区都从它推出来，所以转换
+   * **没有自己的路径设置** —— 一个 Agent 只有一个根路径。
+   */
+  agentRoot(): string
+  /**
+   * 已解析的 `convert` 设置组（来自插件 entry 的 config）。
+   *
+   * 0.1.7 起设置不再是命名空间，而是随 `apply(ctx, config)` 进来的 entry config，
+   * 所以这里由调用方把那一组传下来。省略时用 `DEFAULT_CONVERT_CONFIG`。
+   *
+   * 允许给**函数**的理由与意图那组相同（见 `intent/host.ts` 的 `IntentHostDeps.config`）：
+   * 字段是 volatile，解包是一次快照，而 volatile 改动不会重载插件。
+   */
+  config?: Partial<ConvertPluginConfig> | (() => Partial<ConvertPluginConfig>)
+}
+
+/**
+ * `applyConvert` 交给组合根的那一个把手，与 `intent/host.ts` 的 `IntentHost` 同形。
+ *
+ * 转换这一组也有 volatile 字段（`maxConcurrent` / `maxInputBytes` / `retentionDays` /
+ * `toolWaitMs` / `ingestEnabled`），其中一个解包漏了就是沉默的错误：`maxInputBytes`
+ * 是引用时 `info.size > config.maxInputBytes` 恒为 false，体积上限静默消失；
+ * `ingestEnabled` 是引用时它恒为真，开关关不掉。所以这一组也要能就地重灌。
+ */
+export interface ConvertHost {
+  /** 按**当前**的 entry config 重灌一次设置，并按新值重置转换内核。 */
+  reprocess(): void
+}
+
+type Args = Record<string, any>
+
+interface WebServerLike {
+  port?: number
+  host?: string
+  register(route: { kind: 'exact' | 'prefix'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> | void }): () => unknown
+}
+
+function output() {
+  return { schema: { type: 'json' } as const, render: (_args: unknown, value: unknown) => [{ type: 'text' as const, text: JSON.stringify(value) }] }
+}
+
+function tool(toolName: string, description: string, parameters: Record<string, unknown>, execute: (args: Args, exec: ToolRunContext) => Promise<unknown>) {
+  return defineTool({ name: toolName, description, parameters: parameters as any, output: output(), execute: execute as any } as any)
+}
+
+function lineageOf(args: Args, exec?: ToolRunContext): Record<string, string> | undefined {
+  const lineage: Record<string, string> = {}
+  const sessionId = typeof args.session_key === 'string' && args.session_key.trim() ? args.session_key.trim() : exec?.agent?.session.header.id
+  if (sessionId) lineage.sessionId = sessionId
+  const fields: Array<[string, string]> = [
+    ['turnId', 'turn_id'], ['intentId', 'intent_id'], ['taskId', 'task_id'],
+    ['subtaskId', 'subtask_id'], ['parentSubtaskId', 'parent_subtask_id'], ['runId', 'run_id'], ['traceId', 'trace_id'], ['domain', 'domain'],
+  ]
+  for (const [target, source] of fields) if (typeof args[source] === 'string' && args[source].trim()) lineage[target] = args[source].trim().slice(0, 160)
+  return Object.keys(lineage).length > 0 ? lineage : undefined
+}
+
+async function readJsonBody(req: IncomingMessage, maxBytes = 2 * 1024 * 1024): Promise<any> {
+  const chunks: Buffer[] = []
+  let bytes = 0
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))
+    bytes += buffer.length
+    if (bytes > maxBytes) throw new Error('REQUEST_TOO_LARGE')
+    chunks.push(buffer)
+  }
+  if (!chunks.length) return {}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+function send(res: ServerResponse, status: number, body: unknown): void {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(body))
+}
+
+/** Compact task view for tools — the full ingest payload never enters context. */
+function taskView(task: ConvertTask): Record<string, unknown> {
+  const manifest = task.manifest
+  return {
+    taskId: task.id,
+    state: task.state,
+    inputKind: task.inputKind,
+    title: manifest?.title ?? task.label,
+    sourceFormat: manifest?.sourceFormat ?? task.sourceFormat,
+    parser: manifest?.parser,
+    progress: task.progress,
+    stage: task.stage,
+    message: task.message,
+    error: task.error ?? null,
+    warnings: task.warnings.map(warning => warning.code),
+    attempts: task.attempts,
+    deliveryDir: task.deliveryDir,
+    assetCount: manifest?.assets.length ?? 0,
+    wordCount: manifest?.wordCount ?? 0,
+    contentHash: manifest?.contentHash,
+    externalId: manifest?.externalId,
+    sourceTypeCandidates: manifest?.ingest.sourceTypeCandidates ?? [],
+    sourceTypeRequired: manifest?.ingest.sourceTypeRequired ?? true,
+    preview: manifest?.ingest.content.slice(0, PREVIEW_CHARS) ?? null,
+  }
+}
+
+async function waitForTask(service: ConvertService, taskId: string, timeoutMs: number): Promise<ConvertTask | undefined> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const task = service.get(taskId)
+    if (!task) return undefined
+    if (task.state === 'succeeded' || task.state === 'failed' || task.state === 'cancelled') return task
+    await new Promise(resolve => setTimeout(resolve, 250))
+  }
+  return service.get(taskId)
+}
+
+export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
+  let config: ConvertPluginConfig = { ...DEFAULT_CONVERT_CONFIG }
+  let service: ConvertService | undefined
+  let starting: Promise<ConvertService | undefined> | undefined
+  let kernelHandler: ((req: IncomingMessage, res: ServerResponse) => Promise<void>) | undefined
+  /**
+   * Set when the optional kernel could not be loaded. Kept as the original error
+   * so the tool/route layer can surface its code and install suggestion verbatim.
+   */
+  let dependencyError: unknown
+
+  async function ensureService(): Promise<ConvertService | undefined> {
+    if (service) return service
+    if (!starting) {
+      starting = loadConvertCore()
+        .then(async core => {
+          // 目录都从知识插件的根路径推出来：状态文件落在 `tmp/` 根（它是运行期
+          // 事实，不是交付物，所以不占日期桶），交付与工作区各自按日期分桶。
+          const root = deps.agentRoot()
+          const created = await core.createConvertService({
+            rootDir: tmpRoot(root),
+            outRoot: workspaceOutputRoot(deps.workspace?.() ?? process.cwd()),
+            workRoot: tmpRoot(root),
+            // 根路径契约里 output/ 与 tmp/ 的二级就是日期（`layout.ts`），所以插件
+            // 显式打开分桶；独立内核保持扁平布局不受影响。
+            bucketByDay: true,
+            maxConcurrent: config.maxConcurrent,
+            maxInputBytes: config.maxInputBytes,
+            retentionDays: config.retentionDays,
+          })
+          service = created
+          kernelHandler = core.createRequestHandler({ service: created, basePath: MOUNT_PATH })
+          dependencyError = undefined
+          return created
+        })
+        .catch(error => {
+          starting = undefined
+          dependencyError = error
+          return undefined
+        })
+    }
+    return await starting
+  }
+
+  async function resetService(): Promise<void> {
+    const current = service
+    service = undefined
+    starting = undefined
+    kernelHandler = undefined
+    if (current) await current.close().catch(() => undefined)
+  }
+
+  /** The kernel is optional; this is the single place its absence becomes an answer. */
+  function missingDependency<T>(data: T): Envelope<T> {
+    const error = dependencyError
+    const message = error instanceof Error ? error.message : '转换内核 dsh-convert-core 不可用。'
+    const suggestion = error instanceof ConvertCoreMissingError
+      ? error.suggestion
+      : '安装可选依赖 dsh-convert-core 后重试。'
+    return failure(data, 'DEPENDENCY_MISSING', message, true, suggestion)
+  }
+
+  function knowledgeBaseUrl(): string {
+    const web = ctx.get('webServer') as WebServerLike | undefined
+    const host = web?.host === '0.0.0.0' ? '127.0.0.1' : web?.host ?? '127.0.0.1'
+    return `http://${host}:${web?.port ?? 0}`
+  }
+
+  /**
+   * Since 0018 the knowledge root is not resolved from another plugin's settings
+   * or an environment variable: the convert host runs inside the knowledge
+   * plugin and writes exactly where the live runtime reads.
+   *
+   * Since 0019 a delivery can also target a **specific** knowledge base: the
+   * panel imports a file into whichever base the user selected.
+   */
+  function resolveKnowledgeRoot(): { root: string; source: string } {
+    return { root: deps.knowledgeRoot(), source: 'knowledge-runtime' }
+  }
+
+  /** Ingest target for one knowledge base, falling back to the default base. */
+  function targetFor(kbId?: unknown): { runtime: IngestTarget; knowledgeRoot: string; baseId?: string } {
+    const id = typeof kbId === 'string' && kbId.trim() ? kbId.trim() : undefined
+    const resolved = id ? deps.resolveTarget?.(id) : undefined
+    if (resolved) return { ...resolved, baseId: id }
+    return { runtime: deps.runtime(), knowledgeRoot: deps.knowledgeRoot(), ...(id ? { baseId: id } : {}) }
+  }
+
+  /**
+   * 目标知识库中「存在且启用」的来源分类 id（0013）。
+   *
+   * 用作转换内核的候选提示，**取代内核按载体格式猜出来的那张表**——那张表会给出
+   * video / image 这类载体名，和「source_type 描述业务场景」直接冲突。分类判定
+   * 仍然由 knowledge 侧负责，这里只是把真实候选告诉调用方。
+   */
+  function sourceTypeCandidateIds(runtime: IngestTarget): string[] {
+    return (runtime.sourceTypes?.() ?? []).filter(def => def.enabled).map(def => def.id)
+  }
+
+  /**
+   * 设置来源。0.1.7 起设置随 `applyConvert(ctx, deps)` 的 `deps.config` 进来
+   * （插件 entry 的 `convert` 组），`settings.installSection` 那套命名空间注册
+   * 已经整个删除。组合层会合上 schema 默认值，这里再铺一层
+   * `DEFAULT_CONVERT_CONFIG` 兜底，好让直接调用 `applyConvert` 的装配方式也成立。
+   *
+   * 「改设置会让插件整个重载」这句话对 volatile 字段**不成立** —— loader 只就地改
+   * 引用再发一个事件（见 `settings-volatile.ts`）。所以重灌这件事由组合根在
+   * `loader/volatile-update` 时调 `reprocess()` 补上，这里只负责读值。
+   */
+  const readConfig = (): Partial<ConvertPluginConfig> =>
+    (typeof deps.config === 'function' ? deps.config() : deps.config) ?? {}
+  config = { ...DEFAULT_CONVERT_CONFIG, ...readConfig() }
+  void resetService()
+
+  ctx.on('tools/pre-execute', (exec, next): Promise<PreToolDecision> => {
+    if ((WRITE_TOOLS as readonly string[]).includes(exec.name)) {
+      return Promise.resolve({ kind: 'ask', reason: '该操作会转换本地内容，并写入 Tita Knowledge Store，需要本轮用户审批。' })
+    }
+    return next()
+  })
+
+  // ---------------------------------------------------------------- tools
+
+  ctx.tools.register(tool(
+    'convert_capabilities',
+    'Inspect the conversion kernel: available adapters, engine version, supported formats and where deliveries are written. Read-only; call this before promising a format will work.',
+    { session_key: { type: 'string' } },
+    async () => {
+      const kernel = await ensureService()
+      if (!kernel) return missingDependency({ adapters: [], supportedExtensions: [] })
+      // Forced: this is an explicit question ("can you convert X?"), not the console's
+      // poll, and the service caches the report so that poll stays cheap. An agent that
+      // just installed a binary and then asked would otherwise get the stale answer.
+      const report = await kernel.capabilities({ force: true })
+      const knowledge = resolveKnowledgeRoot()
+      return success({
+        adapters: report.adapters,
+        runtime: report.runtime,
+        defaults: report.defaults,
+        supportedExtensions: report.extensions,
+        rootDir: kernel.rootDir,
+        outDir: kernel.outDir,
+        consolePath: `${MOUNT_PATH}/`,
+        knowledgeRoot: knowledge.root,
+        knowledgeRootSource: knowledge.source,
+        knowledgeBaseUrl: knowledgeBaseUrl(),
+        ingestEnabled: config.ingestEnabled,
+      })
+    },
+  ))
+
+  ctx.tools.register(tool(
+    'convert_source',
+    'Convert a document (Word / PowerPoint / Excel / OpenDocument / RTF / EPUB / CSV / text-layer PDF) or inline text into knowledge-ready Markdown + local images. Async kernel task; returns taskId, delivery dir and ingest hints (source_type candidates, external_id, content_hash). Write operation: DSH asks the user once before execution.',
+    {
+      kind: { type: 'string', enum: ['file', 'text'], required: true },
+      path: { type: 'string' },
+      text: { type: 'string' },
+      title: { type: 'string' },
+      source_type: { type: 'string' },
+      adapter: { type: 'string' },
+      wait: { type: 'boolean' },
+      session_key: { type: 'string' },
+      task_id: { type: 'string' },
+      subtask_id: { type: 'string' },
+      parent_subtask_id: { type: 'string' },
+      run_id: { type: 'string' },
+      turn_id: { type: 'string' },
+      trace_id: { type: 'string' },
+      domain: { type: 'string' },
+    },
+    async (args: Args, exec) => {
+      const kernel = await ensureService()
+      if (!kernel) return missingDependency({ taskId: null })
+      const kind = args.kind as ConvertRequest['kind']
+      const candidates = sourceTypeCandidateIds(targetFor(args.kb).runtime)
+      const request: ConvertRequest = {
+        kind,
+        ...(candidates.length > 0 ? { sourceTypeCandidates: candidates } : {}),
+        ...(typeof args.text === 'string' ? { text: args.text } : {}),
+        ...(typeof args.title === 'string' && args.title.trim() ? { title: args.title.trim() } : {}),
+        ...(typeof args.source_type === 'string' && args.source_type.trim() ? { sourceType: args.source_type.trim(), sourceTypeSource: 'agent' as const } : {}),
+        ...(typeof args.adapter === 'string' && args.adapter.trim() ? { adapter: args.adapter.trim() } : {}),
+        ...(lineageOf(args, exec) ? { lineage: lineageOf(args, exec)! } : {}),
+      }
+
+      // Local files are handed to the kernel as a path: it owns staging, size
+      // limits and cleanup, so the host never buffers a 256 MB file.
+      if (kind === 'file') {
+        if (typeof args.path !== 'string' || !args.path.trim()) {
+          return failure({ taskId: null }, 'PATH_REQUIRED', 'kind=file 必须提供本地绝对路径 path。', false, '用户上传的文件请走知识面板的「转换」页；Agent 侧只能读取本机已有路径。')
+        }
+        const absolute = resolve(args.path.trim())
+        try {
+          const info = await stat(absolute)
+          if (!info.isFile()) return failure({ taskId: null }, 'PATH_NOT_A_FILE', `路径不是文件：${absolute}`)
+          if (info.size > config.maxInputBytes) {
+            return failure({ taskId: null }, 'INPUT_TOO_LARGE', `文件 ${info.size} 字节超过上限 ${config.maxInputBytes}。`, false, '调大转换设置 maxInputBytes，或先压缩文件。')
+          }
+        } catch (cause) {
+          return failure({ taskId: null }, 'PATH_UNREADABLE', `无法读取 ${absolute}：${cause instanceof Error ? cause.message : String(cause)}`)
+        }
+        request.localPath = absolute
+        if (!request.title) request.title = basename(absolute)
+      }
+
+      const submitted = await kernel.submit(request)
+      const shouldWait = args.wait !== false
+      const finished = shouldWait ? await waitForTask(kernel, submitted.id, config.toolWaitMs) : submitted
+      const view = taskView(finished ?? submitted)
+      return success({
+        ...view,
+        waited: shouldWait,
+        ingestHint: '调用 convert_ingest 把该任务写入知识库；它会把 Markdown 与图片一起落地，并返回 cardHints。',
+      })
+    },
+  ))
+
+  ctx.tools.register(tool(
+    'convert_task',
+    'Inspect the conversion queue: list, get, cancel, retry, or read the delivered Markdown/manifest of a task. Read-only.',
+    {
+      action: { type: 'string', enum: ['list', 'get', 'cancel', 'retry', 'markdown', 'manifest'], required: true },
+      task_id: { type: 'string' },
+      limit: { type: 'integer' },
+    },
+    async (args: Args) => {
+      const kernel = await ensureService()
+      if (!kernel) return missingDependency({ tasks: [] })
+      const action = String(args.action)
+      if (action === 'list') {
+        const limit = Number.isFinite(args.limit) ? Math.max(1, Math.min(100, Number(args.limit))) : 20
+        return success({ tasks: kernel.list().slice(0, limit).map(taskView) })
+      }
+      const taskId = typeof args.task_id === 'string' ? args.task_id.trim() : ''
+      if (!taskId) return failure({ taskId: null }, 'TASK_ID_REQUIRED', `${action} 需要 task_id。`)
+      if (action === 'cancel') return success(taskView(kernel.cancel(taskId)))
+      if (action === 'retry') return success(taskView(await kernel.retry(taskId)))
+      if (action === 'markdown') {
+        const file = await kernel.readDeliveryFile(taskId, 'index.md')
+        if (!file) return failure({ taskId }, 'ARTIFACT_NOT_FOUND', '该任务没有 index.md（未成功或已被清理）。')
+        return success({ taskId, markdown: file.data.toString('utf8') })
+      }
+      if (action === 'manifest') {
+        const file = await kernel.readDeliveryFile(taskId, 'manifest.json')
+        if (!file) return failure({ taskId }, 'ARTIFACT_NOT_FOUND', '该任务没有 manifest.json。')
+        return success({ taskId, manifest: JSON.parse(file.data.toString('utf8')) })
+      }
+      const task = kernel.get(taskId)
+      if (!task) return failure({ taskId }, 'TASK_NOT_FOUND', `任务不存在：${taskId}`)
+      return success(taskView(task))
+    },
+  ))
+
+  ctx.tools.register(tool(
+    'convert_ingest',
+    'Ingest a delivered conversion into the knowledge store: copies images into the knowledge root, rewrites local image references, writes the SourceRaw document in-process, and returns cardHints so a wiki card can carry the images into multimodal recall. Write operation: DSH asks the user once before execution. Set plan_only=true for a dry run.',
+    {
+      convert_task_id: { type: 'string', required: true },
+      kb: { type: 'string', description: '目标知识库 id；省略则写入默认知识库' },
+      source_type: { type: 'string' },
+      title: { type: 'string' },
+      plan_only: { type: 'boolean' },
+      session_key: { type: 'string' },
+      task_id: { type: 'string' },
+      subtask_id: { type: 'string' },
+      parent_subtask_id: { type: 'string' },
+      run_id: { type: 'string' },
+      turn_id: { type: 'string' },
+      trace_id: { type: 'string' },
+      domain: { type: 'string' },
+    },
+    async (args: Args, exec) => {
+      if (!config.ingestEnabled) {
+        return failure({ taskId: String(args.convert_task_id) }, 'INGEST_DISABLED', '当前设置禁止转换写入知识库（ingestEnabled=false）。', false, '在 Tita Data Agent → 设置 → 转换 中开启「允许一键入库」，或手动调用 add_source。')
+      }
+      const kernel = await ensureService()
+      if (!kernel) return missingDependency({ taskId: String(args.convert_task_id) })
+      const target = targetFor(args.kb)
+      const result = await ingestDelivery({
+        service: kernel,
+        taskId: String(args.convert_task_id),
+        runtime: target.runtime,
+        knowledgeRoot: target.knowledgeRoot,
+        ...(typeof args.source_type === 'string' && args.source_type.trim() ? { sourceType: args.source_type.trim() } : {}),
+        ...(typeof args.title === 'string' && args.title.trim() ? { title: args.title.trim() } : {}),
+        planOnly: args.plan_only === true,
+        ...(lineageOf(args, exec) ? { lineage: lineageOf(args, exec)! } : {}),
+      })
+      return {
+        ...result,
+        data: {
+          ...(result.data as IngestOutcome),
+          knowledgeRootSource: 'knowledge-runtime',
+          ...(target.baseId ? { knowledgeBaseId: target.baseId } : {}),
+        },
+      }
+    },
+  ))
+
+  // ---------------------------------------------------------------- routes
+
+  ctx.inject(['webServer'], webCtx => {
+    const web = webCtx as unknown as Context & { webServer: WebServerLike }
+
+    // Plugin-level facts the kernel cannot know about itself.
+    const pluginFacts = (): Record<string, unknown> => {
+      const knowledge = resolveKnowledgeRoot()
+      const root = deps.agentRoot()
+      return {
+        rootDir: service?.rootDir ?? tmpRoot(root),
+        outDir: service?.outRoot ?? workspaceOutputRoot(deps.workspace?.() ?? process.cwd()),
+        workDir: service?.workRoot ?? tmpRoot(root),
+        mountPath: MOUNT_PATH,
+        knowledgeRoot: knowledge.root,
+        knowledgeRootSource: knowledge.source,
+        knowledgeBaseUrl: knowledgeBaseUrl(),
+        ingestEnabled: config.ingestEnabled,
+        kernelLoaded: service !== undefined,
+      }
+    }
+
+    const dispatch = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+      const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+
+      if (url.pathname === `${MOUNT_PATH}/api/ingest`) {
+        if (req.method !== 'POST') return send(res, 405, failure({}, 'METHOD_NOT_ALLOWED', '该 endpoint 只接受 POST'))
+        try {
+          const body = await readJsonBody(req)
+          const kernel = await ensureService()
+          if (!kernel) return send(res, 503, missingDependency({ taskId: String(body.task_id ?? '') }))
+          const target = targetFor(body.kb)
+          const result = await ingestDelivery({
+            service: kernel,
+            taskId: String(body.task_id ?? ''),
+            runtime: target.runtime,
+            knowledgeRoot: target.knowledgeRoot,
+            ...(typeof body.source_type === 'string' && body.source_type.trim() ? { sourceType: body.source_type.trim() } : {}),
+            ...(typeof body.title === 'string' && body.title.trim() ? { title: body.title.trim() } : {}),
+            planOnly: body.plan_only === true,
+            ...(body.lineage && typeof body.lineage === 'object' ? { lineage: body.lineage as Record<string, string> } : {}),
+          })
+          return send(res, 200, {
+            ...result,
+            data: {
+              ...(result.data as IngestOutcome),
+              knowledgeRootSource: 'knowledge-runtime',
+              ...(target.baseId ? { knowledgeBaseId: target.baseId } : {}),
+            },
+          })
+        } catch (cause) {
+          return send(res, 400, failure({}, 'REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause)))
+        }
+      }
+
+      if (url.pathname === `${MOUNT_PATH}/api/plugin`) {
+        if (req.method !== 'GET') return send(res, 405, failure({}, 'METHOD_NOT_ALLOWED', '该 endpoint 只接受 GET'))
+        return send(res, 200, success(pluginFacts()))
+      }
+
+      // Everything else belongs to the kernel console/API.
+      if (!kernelHandler) await ensureService()
+      if (!kernelHandler) return send(res, 503, missingDependency({ mountPath: MOUNT_PATH }))
+      return await kernelHandler(req, res)
+    }
+
+    const dispose = web.webServer.register({ kind: 'prefix', path: MOUNT_PATH, handler: dispatch })
+    return () => {
+      void dispose()
+      void resetService()
+    }
+  })
+
+  return {
+    reprocess: () => {
+      const next = { ...DEFAULT_CONVERT_CONFIG, ...readConfig() }
+      const changed = (Object.keys(next) as Array<keyof ConvertPluginConfig>).some(key => next[key] !== config[key])
+      config = next
+      // 只有真变了才重置内核：`loader/volatile-update` 是**这个 entry**的事件，但知识那组
+      // 的改动也会走到这里，无谓地关掉内核会让下一次转换重新起一遍内核。
+      if (changed) void resetService()
+    },
+  }
+}