dsh-card-dispatch 0.0.0-stage → 0.1.0

package/src/human-channel.js

@@ -0,0 +1,794 @@
+/**
+ * human-channel：控制台页面 + 拆分接口（**只剩这些**）。
+ *
+ * 定位（偏差 D-15）：本插件不再开会话、不再派发、不再记台账——
+ * 执行全部交给 `@linxin666/dsh-client-ui-task-board`。这里只提供：
+ *
+ *   GET  /              控制台页面（每次请求从磁盘读，改页面不用重启）
+ *   GET  /view          页面要的快照：版本号 + 可用路由 + 看板基址
+ *   POST /split         需求 → 看板卡片 + action 信封（纯计算，不落盘）
+ *
+ * 两道门（沿用旧实现，仍然值得保留）：
+ *   1. **本地回环**：只看 `req.socket.remoteAddress`，非回环一律 403；
+ *      宿主若有 `connection` 服务，再叠一次它的 Host/Origin 栅栏。
+ *   2. **人操作标记**：POST 必须带 `x-card-dispatch-human: true` 或 body `human: true`。
+ *      这不是鉴权（本机人类就是权威），而是把「人手点的」和「脚本误发」分开。
+ */
+
+import { readFileSync } from 'node:fs'
+import { createHash, randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+
+import { splitRequirement } from './split.js'
+import { describeConfig, mergeConfig, normalizeConfig } from './config.js'
+import { evaluateStart } from './gates.js'
+import { runSelfCheck } from './selfcheck.js'
+import { decideNext, parseVerdict, verdictPath } from './verdict.js'
+import { parseRequirementDoc } from './import.js'
+import { suggestCriteria } from './criteria.js'
+import { draftWithModel } from './criteria-llm.js'
+import { PARSE_SYSTEM, parseRequirementWithModel } from './parse-llm.js'
+import { PROMPTS_SYSTEM, writeCardIntros } from './prompts-llm.js'
+import { outlineCards } from './split.js'
+import { listRoutes, pickRoute, splitRoute } from './models.js'
+
+export const HUMAN_ROUTE_PREFIX = '/api/card-dispatch'
+export const HUMAN_HEADER = 'x-card-dispatch-human'
+
+/** 请求体上限：需求文本再长也用不了这么多，超了直接 413。 */
+const BODY_LIMIT = 256 * 1024
+
+/** 页面占位符：服务端渲染时替换成真实哈希，页面拿它和自己比，不一致就整页 reload。 */
+const PAGE_VERSION_PLACEHOLDER = '__CARD_DISPATCH_PAGE_VERSION__'
+
+const CONSOLE_FILE = new URL('./console.html', import.meta.url)
+
+function isLoopbackAddress(address) {
+  const value = String(address ?? '')
+  return value === '::1' || value === '127.0.0.1' || value.startsWith('127.') || value === '::ffff:127.0.0.1'
+}
+
+/**
+ * 模型写的「提示词开头」，只认 root / part-N 两种 key。
+ *
+ * /split 是能直接 curl 的，所以这些从页面回传的文本要在这里再收一遍：
+ * 只收字符串、只收认得的键、限长。
+ */
+function sanitizeIntros(input) {
+  if (input === null || input === undefined || typeof input !== 'object') return {}
+  const out = {}
+  for (const [key, value] of Object.entries(input)) {
+    if (!/^(root|part-\d{1,2})$/.test(key)) continue
+    if (typeof value !== 'string') continue
+    const text = value.trim()
+    if (text === '') continue
+    out[key] = text.slice(0, 1200)
+  }
+  return out
+}
+
+/** 读页面 + 算版本号。每次请求都读：改 HTML 不该要求重启宿主。 */function readConsole() {
+  const html = readFileSync(CONSOLE_FILE, 'utf8')
+  const version = createHash('sha256').update(html).digest('hex').slice(0, 12)
+  return { html: html.replace(PAGE_VERSION_PLACEHOLDER, version), version }
+}
+
+async function readBoundedBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > BODY_LIMIT) {
+      const error = new Error('请求体过大')
+      error.code = 'E_BODY_TOO_LARGE'
+      throw error
+    }
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+/**
+ * 只读快照。字段刻意很少：页面需要知道「宿主是不是旧代码」和「看板挂在哪」。
+ *
+ * @param {object} options
+ * @param {string} options.version 当前页面哈希
+ * @returns {object}
+ */
+function snapshot({ version, workspaces }) {
+  return {
+    ok: true,
+    pageVersion: version,
+    // 工作区列表：卡片不指定 workspaceId 时，看板会回退到「最近改动过的那个工作区」，
+    // 对自动跑卡来说是隐患（会随人切会话而变）。所以把列表给页面，让人显式选。
+    workspaces,
+    // 页面据此判断自己是不是旧文档（旧文档会调不存在的路由，看着像功能没做）
+    capabilities: ['view', 'split', 'status', 'config', 'rework', 'import', 'criteria', 'models', 'parse', 'plan'],
+    // 看板路由挂在同一个宿主上，页面自己拼基址；这里给出来只是方便排障
+    board: { prefix: '/api/task-board' },
+  }
+}
+
+/**
+ * 路由表。刻意做成纯函数集合，测试可以直接喂 `{method, pathname, body, headers}`。
+ *
+ * @param {object} [deps]
+ * @returns {{handle: (request: object) => Promise<{status:number, body:any, content?:string}>}}
+ */
+export function createHumanChannel(deps = {}) {
+  const marked = (body, headers) => headers?.[HUMAN_HEADER] === 'true' || body?.human === true
+  // 惰性：workspaceRegistry 可能比本插件晚注册；拿不到就返回空列表，页面退化成「默认」
+  const listWorkspaces = typeof deps.workspaces === 'function' ? deps.workspaces : () => []
+  const safeWorkspaces = () => {
+    try {
+      const items = listWorkspaces()
+      return Array.isArray(items) ? items : []
+    } catch {
+      return []
+    }
+  }
+
+  /** 运行期配置：面板改完立刻生效，不需要重启宿主。 */
+  let current = deps.config ?? normalizeConfig({})
+  const store = deps.store ?? null
+  const facts = typeof deps.facts === 'function' ? deps.facts : () => ({})
+  /* 模型接口：llm 是宿主的官方服务，catalog 是「设置里已添加的模型」。
+     两者都可能拿不到（旧宿主、没有 provider），所以每次调用都重新取并容错。 */
+  const modelDeps = deps.models ?? {}
+  const getLlm = () => {
+    try {
+      return typeof modelDeps.llm === 'function' ? modelDeps.llm() : null
+    } catch {
+      return null
+    }
+  }
+  const loadCatalogSafe = async () => {
+    try {
+      const result = typeof modelDeps.catalog === 'function' ? await modelDeps.catalog() : null
+      return result !== null && typeof result === 'object'
+        ? result
+        : { file: null, catalog: { default: null, groups: [] }, error: '宿主没有提供模型清单' }
+    } catch (error) {
+      return { file: null, catalog: { default: null, groups: [] }, error: String(error?.message ?? error) }
+    }
+  }
+
+  /**
+   * 改配置。只接受声明表里出现过的路径（`gates.budgetPerDay` 这种扁平写法），
+   * 未知路径原样回给页面——人以为改了其实没改，比报错更糟。
+   */
+  const configRoute = async ({ body, headers }) => {
+    if (!marked(body, headers)) {
+      return {
+        status: 400,
+        body: {
+          ok: false,
+          error: { code: 'E_SCHEMA_INVALID', message: `改配置也要人标记：请求头 ${HUMAN_HEADER}: true 或 body 里 human: true` },
+        },
+      }
+    }
+    const patch = body?.patch
+    if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) {
+      return {
+        status: 400,
+        body: { ok: false, error: { code: 'E_SCHEMA_INVALID', message: 'patch 必须是「路径 → 值」的扁平对象' } },
+      }
+    }
+    const { config: merged, rejected } = mergeConfig(current, patch)
+    current = merged
+    try {
+      store?.save(merged)
+    } catch (error) {
+      return {
+        status: 500,
+        body: { ok: false, error: { code: 'E_STORE_WRITE', message: `配置写盘失败：${error?.message ?? String(error)}` } },
+      }
+    }
+    return { status: 200, body: { ok: true, rejected, config: describeConfig(merged) } }
+  }
+
+  const statusRoute = () => {
+    const workspaces = safeWorkspaces()
+    const check = runSelfCheck({ config: current, facts: { ...facts(), workspaceCount: workspaces.length } })
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        enabled: current.enabled === true,
+        permission: current.permission,
+        configFile: store?.file ?? null,
+        config: describeConfig(current),
+        selfCheck: check,
+      },
+    }
+  }
+
+  /**
+   * 「检查并返工」：人点一下（或命令行敲一下）才跑——不轮询、不起定时器。
+   *
+   * 判定材料是验收卡落盘的 `verdict.json`：插件读得到**文件**，读不到**看板状态**
+   * （`/api/task-board/state` 走看板自己的信任栅栏，实测 403）。这也是为什么结论
+   * 必须落盘：落盘的才存在（基线 P3），才轮得到第三方复核。
+   */
+  const reworkRoute = async ({ body, headers }) => {
+    if (!marked(body, headers)) {
+      return {
+        status: 400,
+        body: {
+          ok: false,
+          error: { code: 'E_SCHEMA_INVALID', message: `触发返工也要人标记：请求头 ${HUMAN_HEADER}: true 或 body 里 human: true` },
+        },
+      }
+    }
+    const rootId = String(body?.rootId ?? '').trim()
+    const workspaceRoot = String(body?.workspaceRoot ?? '').trim()
+    if (!/^[0-9a-fA-F-]{36}$/.test(rootId)) {
+      return { status: 400, body: { ok: false, error: { code: 'E_SCHEMA_INVALID', message: 'rootId 必须是拆分时返回的父卡 id' } } }
+    }
+    if (workspaceRoot === '') {
+      return {
+        status: 400,
+        body: { ok: false, error: { code: 'E_SCHEMA_INVALID', message: '需要 workspaceRoot（工作区根目录），否则不知道去哪读验收结论' } },
+      }
+    }
+
+    const path = join(workspaceRoot, verdictPath(rootId))
+    let text = null
+    let readError = null
+    try {
+      text = readFileSync(path, 'utf8')
+    } catch (error) {
+      readError =
+        error?.code === 'ENOENT'
+          ? `还没有验收结论：${path} 不存在（验收卡可能还没跑）`
+          : `读取验收结论失败：${error?.message ?? String(error)}`
+    }
+    const parsed =
+      text === null
+        ? { ok: false, verdict: null, items: [], problems: [], summary: '', error: readError }
+        : parseVerdict(text)
+
+    const decision = decideNext({ parsed, config: current, rejectedCount: body?.rejectedCount ?? 0 })
+    // 一次可以重跑多张卡：验收结论的 items 里可能有好几条判据，分属不同子卡。
+    // `taskId` 是单卡的老写法，保留；`taskIds` 是页面上用的写法。
+    const requested = Array.isArray(body?.taskIds)
+      ? body.taskIds
+      : (typeof body?.taskId === 'string' ? [body.taskId] : [])
+    const taskIds = requested.map((value) => String(value ?? '').trim()).filter((value) => value !== '')
+    const runs = decision.action === 'rework'
+      ? taskIds.map((id) => ({ requestId: `card-dispatch-${randomUUID()}`, action: { kind: 'run', taskId: id } }))
+      : []
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        path,
+        verdict: parsed,
+        decision,
+        runs,
+        run: runs.length > 0 ? runs[0] : null,
+        // 判定做完了但不知道重跑哪张卡时，明确说清楚
+        hint: decision.action === 'rework' && runs.length === 0 ? '要重跑就带上 taskIds（被拒的那几张开发卡）' : '',
+      },
+    }
+  }
+
+  /**
+   * 从文档导入需求。
+   *
+   * 文件由浏览器读成文本再发过来——插件不碰用户的磁盘路径，也就没有「读哪个目录」的权限问题。
+   * 解析永远返回 200：`ok:false` 表示「读到了但抽不出东西」，警告原文给页面显示，
+   * 比一个 400 更接近事实（文件没坏，只是格式不支持或没写判据）。
+   */
+  const importRoute = async ({ body, headers }) => {
+    if (!marked(body, headers)) {
+      return {
+        status: 400,
+        body: {
+          ok: false,
+          error: { code: 'E_SCHEMA_INVALID', message: `导入也要人标记：请求头 ${HUMAN_HEADER}: true 或 body 里 human: true` },
+        },
+      }
+    }
+    const text = typeof body?.text === 'string' ? body.text : ''
+    if (text.trim() === '') {
+      return {
+        status: 400,
+        body: { ok: false, error: { code: 'E_SCHEMA_INVALID', message: '没有收到文档正文（text 为空）' } },
+      }
+    }
+    const result = parseRequirementDoc({ filename: String(body?.filename ?? ''), text })
+    return { status: 200, body: { ok: result.ok, ...result } }
+  }
+
+  /** 模型清单：页面下拉用。读的是宿主设置里已添加的模型，这里只读不写。 */
+  const modelsRoute = async () => {
+    const loaded = await loadCatalogSafe()
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        file: loaded.file,
+        error: loaded.error,
+        default: loaded.catalog.default,
+        configured: current.models.draftRoute,
+        effective: pickRoute(current.models.draftRoute, loaded.catalog),
+        // 页面要知道这个"生效中的模型"是配置里存的、还是宿主的默认值（决定提示怎么写）。
+        source: current.models.draftRoute.trim() === '' ? 'host' : 'config',
+        options: listRoutes(loaded.catalog),
+        enabled: current.models.useModel,
+      },
+    }
+  }
+
+  /**
+   * 判据草稿：**先用模型**（宿主已添加的模型），失败或关掉时退回规则提炼。
+   *
+   * 一次点击 = 一次很小的模型调用，会计费，所以响应里把用的模型写清楚，
+   * 页面也会显示。模型与密钥都由宿主管，插件不碰。
+   */
+  const criteriaRoute = async ({ body, headers }) => {
+    if (!marked(body, headers)) {
+      return {
+        status: 400,
+        body: {
+          ok: false,
+          error: { code: 'E_SCHEMA_INVALID', message: `生成草稿也要人标记：请求头 ${HUMAN_HEADER}: true 或 body 里 human: true` },
+        },
+      }
+    }
+    const title = String(body?.title ?? '')
+    const description = String(body?.description ?? '')
+    const requested = String(body?.model ?? '').trim()
+    const notes = []
+
+    if (!current.models.useModel) notes.push('模型生成是关着的（开关里可开），下面是规则提炼的草稿。')
+
+    if (current.models.useModel) {
+      const loaded = await loadCatalogSafe()
+      const routeText = pickRoute(requested !== '' ? requested : current.models.draftRoute, loaded.catalog)
+      const route = routeText === null ? null : splitRoute(routeText)
+      const llm = getLlm()
+      if (route === null) {
+        notes.push('没有可用的模型（设置里还没添加？），下面是规则提炼的草稿。')
+      } else if (llm === null) {
+        notes.push('宿主没提供模型接口，下面是规则提炼的草稿。')
+      } else {
+        const drafted = await draftWithModel({ llm, route, title, description })
+        if (drafted.ok) {
+          return {
+            status: 200,
+            body: { ok: true, source: 'model', model: routeText, criteria: drafted.criteria, notes: [`由 ${routeText} 生成，改完再用。`] },
+          }
+        }
+        notes.push(`模型没用上（${drafted.error}），下面是规则提炼的草稿。`)
+      }
+    }
+
+    const fallback = suggestCriteria({ title, description })
+    return {
+      status: 200,
+      body: { ok: true, source: 'rules', model: null, criteria: fallback.criteria, notes: [...notes, ...fallback.notes] },
+    }
+  }
+
+  /**
+   * AI 解析需求：把粘贴的一段原文整理成「标题 + 描述 + 判据」。
+   *
+   * 模型可用就用模型；不可用就退回文档解析（同一套规则：认标题、认判据列表），
+   * 并在 notes 里说清是哪条路——绝不假装模型读过。
+   * `prompt` 一并回给页面，人可以点开看模型到底被告知了什么。
+   */
+  const parseRoute = async ({ body, headers }) => {
+    if (!marked(body, headers)) {
+      return {
+        status: 400,
+        body: {
+          ok: false,
+          error: { code: 'E_SCHEMA_INVALID', message: `解析也要人标记：请求头 ${HUMAN_HEADER}: true 或 body 里 human: true` },
+        },
+      }
+    }
+    const text = String(body?.text ?? '').trim()
+    if (text === '') {
+      return { status: 400, body: { ok: false, error: { code: 'E_EMPTY_TEXT', message: '没有可解析的原文' } } }
+    }
+    const notes = []
+    const requested = String(body?.model ?? '').trim()
+
+    if (current.models.useModel) {
+      const loaded = await loadCatalogSafe()
+      const routeText = pickRoute(requested !== '' ? requested : current.models.draftRoute, loaded.catalog)
+      const route = routeText === null ? null : splitRoute(routeText)
+      const llm = getLlm()
+      if (route === null) {
+        notes.push('没有可用的模型，下面是按格式规则解析的结果。')
+      } else if (llm === null) {
+        notes.push('宿主没提供模型接口，下面是按格式规则解析的结果。')
+      } else {
+        const parsed = await parseRequirementWithModel({ llm, route, text })
+        if (parsed.ok) {
+          return {
+            status: 200,
+            body: {
+              ok: true,
+              source: 'model',
+              model: routeText,
+              title: parsed.title,
+              description: parsed.description,
+              criteria: parsed.criteria,
+              notes: [`由 ${routeText} 解析，改完再用。`],
+              prompt: PARSE_SYSTEM,
+            },
+          }
+        }
+        notes.push(`模型没用上（${parsed.error}），下面是按格式规则解析的结果。`)
+      }
+    } else {
+      notes.push('模型解析是关着的（开关里可开），下面是按格式规则解析的结果。')
+    }
+
+    // 走文档解析时借一个 .md 文件名：解析器按扩展名判格式，粘贴的原文没有文件名。
+    const fallback = parseRequirementDoc({ filename: '粘贴的需求.md', text })
+    if (!fallback.ok) {
+      return {
+        status: 200,
+        body: {
+          ok: false,
+          source: 'rules',
+          model: null,
+          title: '',
+          description: '',
+          criteria: [],
+          notes: [...notes, ...fallback.warnings],
+          prompt: PARSE_SYSTEM,
+        },
+      }
+    }
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        source: 'rules',
+        model: null,
+        title: fallback.title,
+        description: fallback.description,
+        criteria: fallback.criteria,
+        notes: [...notes, ...fallback.warnings],
+        prompt: PARSE_SYSTEM,
+      },
+    }
+  }
+
+  /**
+   * AI 解析并拆分：一次点击走完
+   *   原文 →（模型）标题 / 描述 / 判据 →（规则）拆成哪几张卡 →（模型）每张卡的提示词开头。
+   *
+   * 结构仍由规则决定（拆几张、哪几条判据一组），模型只负责措辞——这样账单可预期，
+   * 「完成要交证据」那些硬要求也仍然由 split.js 确定性拼上。
+   * 返回的 intros 由页面回传给 /split，写卡时与预览用的是同一份。
+   */
+  const planRoute = async ({ body, headers }) => {
+    if (!marked(body, headers)) {
+      return {
+        status: 400,
+        body: {
+          ok: false,
+          error: { code: 'E_SCHEMA_INVALID', message: `解析也要人标记：请求头 ${HUMAN_HEADER}: true 或 body 里 human: true` },
+        },
+      }
+    }
+    const text = String(body?.text ?? '').trim()
+    if (text === '') {
+      return { status: 400, body: { ok: false, error: { code: 'E_EMPTY_TEXT', message: '没有可解析的原文' } } }
+    }
+    const notes = []
+    const requested = String(body?.model ?? '').trim()
+    const parallel = body?.parallel !== false
+
+    let title = ''
+    let description = ''
+    let criteria = []
+    let source = 'rules'
+    let modelUsed = null
+    let llm = null
+    let route = null
+    let routeText = null
+
+    if (current.models.useModel) {
+      const loaded = await loadCatalogSafe()
+      routeText = pickRoute(requested !== '' ? requested : current.models.draftRoute, loaded.catalog)
+      route = routeText === null ? null : splitRoute(routeText)
+      llm = getLlm()
+      if (route === null) notes.push('没有可用的模型（设置里还没添加？），按格式规则解析。')
+      else if (llm === null) notes.push('宿主没提供模型接口，按格式规则解析。')
+      else {
+        const parsed = await parseRequirementWithModel({ llm, route, text })
+        if (parsed.ok) {
+          title = parsed.title
+          description = parsed.description
+          criteria = parsed.criteria
+          source = 'model'
+          modelUsed = routeText
+          notes.push(`标题 / 描述 / 判据由 ${routeText} 整理。`)
+        } else {
+          notes.push(`解析没用上模型（${parsed.error}），按格式规则解析。`)
+        }
+      }
+    } else {
+      notes.push('模型解析是关着的（开关里可开），按格式规则解析。')
+    }
+
+    if (source !== 'model') {
+      // 借一个 .md 文件名：解析器按扩展名判格式，粘贴的原文没有文件名。
+      const fallback = parseRequirementDoc({ filename: '粘贴的需求.md', text })
+      if (!fallback.ok) {
+        return {
+          status: 200,
+          body: { ok: false, source, model: modelUsed, title: '', description: '', criteria: [], intros: {}, notes: [...notes, ...fallback.warnings] },
+        }
+      }
+      title = fallback.title
+      description = fallback.description
+      criteria = fallback.criteria
+      notes.push(...fallback.warnings)
+    }
+
+    const outline = outlineCards({
+      title,
+      criteria,
+      parallel,
+      requireEvidence: current.gates.requireEvidence === true,
+    })
+
+    let intros = {}
+    if (llm !== null && route !== null) {
+      const written = await writeCardIntros({
+        llm,
+        route,
+        requirement: [title, description].filter((line) => line !== '').join('\n'),
+        cards: outline,
+      })
+      if (written.ok) {
+        intros = written.intros
+        notes.push(`每张卡的提示词由 ${routeText} 按需求写（结构仍按规则拆）。`)
+        if (written.error !== null) notes.push(written.error)
+      } else {
+        notes.push(`提示词没写成（${written.error}），用模板拼。`)
+      }
+    } else {
+      notes.push('没有可用模型，每张卡的提示词用模板拼。')
+    }
+
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        source,
+        model: modelUsed,
+        title,
+        description,
+        criteria,
+        outline,
+        intros,
+        notes,
+        // 让人能核对模型到底被告知了什么：两段提示词都回给页面。
+        prompts: { parse: PARSE_SYSTEM, cardIntros: PROMPTS_SYSTEM },
+      },
+    }
+  }
+
+  const splitRouteHandler = async ({ body, headers }) => {
+    if (!marked(body, headers)) {
+      return {
+        status: 400,
+        body: {
+          ok: false,
+          error: {
+            code: 'E_SCHEMA_INVALID',
+            message: `写看板的请求需要明确标记：请求头 ${HUMAN_HEADER}: true 或 body 里 human: true`,
+          },
+        },
+      }
+    }
+    try {
+      const plan = splitRequirement({
+        title: body?.title,
+        description: body?.description ?? '',
+        criteria: body?.criteria ?? [],
+        parallel: body?.parallel !== false,
+        workspaceId: body?.workspaceId ?? null,
+        agentPreset: body?.agentPreset ?? null,
+        permission: body?.permission ?? current.permission ?? 'workspace-write',
+        // 交付门槛开着才生成验收卡与证据要求；关掉就是省一张卡（它的会话费在团队模式下本来也不额外计）。
+        requireEvidence: current.gates.requireEvidence === true,
+        // 智能体团队由开关决定；父卡带 teamRun，子卡不带（子卡是 Lead 派出去的 teammate）。
+        teamRun: current.execution?.teamRun === true,
+        intros: sanitizeIntros(body?.intros),
+      })
+      // 拆分本身不花钱（只算文本），所以闸门卡的是**运行信封**：闸门不允许时
+      // `run` 直接为 null，页面拿不到可执行的指令，就不会误开一轮。
+      // 计划闸的「批准」在这一层只能来自人点「写入并运行」这一下——插件无法证明人
+      // 真的读过拆分，这点在文档里写明了，不假装能证明。
+      const gate = evaluateStart({
+        config: current,
+        state: {},
+        request: { planApproved: body?.planApproved === true },
+      })
+      return { status: 200, body: { ok: true, ...plan, run: gate.allow ? plan.run : null, gate } }
+    } catch (error) {
+      return {
+        status: 400,
+        body: { ok: false, error: { code: 'E_SCHEMA_INVALID', message: error?.message ?? String(error) } },
+      }
+    }
+  }
+
+  return {
+    /** 运行期配置的唯一读取口：后续闸门/派发都从这里拿，避免两处配置漂移。 */
+    getConfig: () => current,
+    async handle(request) {
+      const method = String(request.method ?? 'GET').toUpperCase()
+      const pathname = String(request.pathname ?? '/')
+
+      if (method === 'GET' && (pathname === '/' || pathname === '')) {
+        try {
+          const { html, version } = readConsole()
+          return { status: 200, body: html, content: 'text/html; charset=utf-8', version }
+        } catch (error) {
+          return {
+            status: 500,
+            body: { ok: false, error: { code: 'E_CONSOLE_MISSING', message: error?.message ?? '页面读取失败' } },
+          }
+        }
+      }
+
+      if (method === 'GET' && pathname === '/view') {
+        const { version } = readConsole()
+        return { status: 200, body: snapshot({ version, workspaces: safeWorkspaces() }) }
+      }
+
+      if (method === 'POST' && pathname === '/split') return splitRouteHandler(request)
+      if (method === 'POST' && pathname === '/rework') return reworkRoute(request)
+      if (method === 'POST' && pathname === '/import') return importRoute(request)
+      if (method === 'GET' && pathname === '/models') return modelsRoute(request)
+      if (method === 'POST' && pathname === '/criteria') return criteriaRoute(request)
+      if (method === 'POST' && pathname === '/parse') return parseRoute(request)
+      if (method === 'POST' && pathname === '/plan') return planRoute(request)
+      if (method === 'GET' && pathname === '/status') return statusRoute()
+      if (method === 'GET' && pathname === '/config') {
+        return { status: 200, body: { ok: true, configFile: store?.file ?? null, config: describeConfig(current) } }
+      }
+      if (method === 'POST' && pathname === '/config') return configRoute(request)
+
+      return {
+        status: 404,
+        body: {
+          ok: false,
+          error: {
+            code: 'E_NOT_FOUND',
+            message: `没有这个路由：${method} ${pathname}（本插件只有 / 、/view、/split、/status、/config、/rework、/import、/criteria、/models、/parse、/plan）`,
+          },
+        },
+      }
+    },
+  }
+}
+
+function createHttpHandler(channel, options = {}) {
+  const send = (res, status, body, contentType = 'application/json; charset=utf-8') => {
+    res.statusCode = status
+    res.setHeader('content-type', contentType)
+    res.setHeader('cache-control', 'no-store')
+    res.end(typeof body === 'string' ? body : JSON.stringify(body ?? null))
+  }
+
+  return async function handleHttp(req, res) {
+    const remote = req.socket?.remoteAddress ?? ''
+    if (!isLoopbackAddress(remote)) {
+      send(res, 403, { ok: false, error: { code: 'E_NOT_LOOPBACK', message: '控制台只接受本机回环请求' } })
+      return
+    }
+    const rejection = options.connection?.requestRejection?.(req)
+    if (rejection !== undefined) {
+      send(res, rejection, { ok: false, error: { code: 'E_UNTRUSTED_CONNECTION', message: `宿主连接栅栏拒绝：${rejection}` } })
+      return
+    }
+
+    const url = new URL(String(req.url ?? '/'), 'http://localhost')
+    const pathname = url.pathname.startsWith(HUMAN_ROUTE_PREFIX)
+      ? url.pathname.slice(HUMAN_ROUTE_PREFIX.length) || '/'
+      : url.pathname
+
+    let body
+    if (String(req.method).toUpperCase() === 'POST') {
+      try {
+        const text = await readBoundedBody(req)
+        body = text.trim() === '' ? {} : JSON.parse(text)
+      } catch (error) {
+        const status = error?.code === 'E_BODY_TOO_LARGE' ? 413 : 400
+        send(res, status, { ok: false, error: { code: error?.code ?? 'E_BAD_JSON', message: error?.message ?? '请求体不可解析' } })
+        return
+      }
+    }
+
+    try {
+      const result = await channel.handle({
+        method: req.method,
+        pathname,
+        searchParams: url.searchParams,
+        headers: req.headers ?? {},
+        body,
+        remoteAddress: remote,
+      })
+      send(res, result.status, result.body, result.content)
+    } catch (error) {
+      send(res, 500, { ok: false, error: { code: 'E_INTERNAL', message: error?.message ?? String(error) } })
+    }
+  }
+}
+
+/**
+ * 挂到宿主 webServer 上。服务可能晚于本插件出现，所以走 `ctx.inject(['webServer'])` 懒挂。
+ *
+ * @returns {() => void} 释放函数
+ */
+/**
+ * 组 channel 的依赖：除了 workspaces 要包一层惰性，其余原样透传。
+ *
+ * 单独抽出来是因为这里少写一个键**不会报错**——只会让某个功能悄悄失效
+ * （`models` 就被丢过一次：路由在，但永远回「宿主没有提供模型清单」）。
+ * 所以这条路径单独有单测盯着。
+ *
+ * @param {object} deps 宿主给的依赖（config / store / facts / models …）
+ * @param {() => Array} resolveWorkspaces 惰性的工作区读取
+ * @returns {object}
+ */
+export function channelDeps(deps = {}, resolveWorkspaces = () => []) {
+  return { ...deps, workspaces: resolveWorkspaces }
+}
+
+export function registerHumanChannel(ctx, deps = {}) {
+  /** 宿主的 workspaceRegistry 只在 mount 时拿得到，所以用一个可变引用喂给 channel。 */
+  let workspaces = () => []
+  const channel = createHumanChannel(channelDeps(deps, () => workspaces()))
+  const disposers = []
+
+  const mount = (hostCtx) => {
+    const webServer = hostCtx.webServer ?? hostCtx.get?.('webServer')
+    if (!webServer || typeof webServer.register !== 'function') return
+    workspaces = () => {
+      const registry = hostCtx.get?.('workspaceRegistry') ?? hostCtx.workspaceRegistry
+      const items = registry?.list?.() ?? []
+      return items.map((item) => ({
+        id: String(item?.id ?? ''),
+        title: String(item?.title ?? item?.name ?? ''),
+        path: String(item?.path ?? item?.rootPath ?? ''),
+      })).filter((item) => item.id !== '')
+    }
+    const connection = hostCtx.get?.('connection')
+    const handler = createHttpHandler(channel, { connection })
+    const effect = typeof hostCtx.effect === 'function' ? hostCtx.effect.bind(hostCtx) : (fn) => fn()
+    const dispose = effect(
+      () => webServer.register({ kind: 'prefix', path: HUMAN_ROUTE_PREFIX, handler }),
+      `card-dispatch: console ${HUMAN_ROUTE_PREFIX}`,
+    )
+    disposers.push(typeof dispose === 'function' ? dispose : () => {})
+  }
+
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['webServer'], (hostCtx) => mount(hostCtx))
+  } else {
+    mount(ctx)
+  }
+
+  return () => {
+    for (const dispose of disposers.splice(0)) {
+      try {
+        dispose()
+      } catch {
+        // 释放失败不影响卸载：宿主会随 fiber 一起回收
+      }
+    }
+  }
+}