dsh-card-dispatch 0.0.0-stage → 0.1.0

package/src/client/index.js

@@ -0,0 +1,155 @@
+/**
+ * card-dispatch · 浏览器半（client）
+ *
+ * 只做一件事：在左侧边栏加一行「派卡台」，点开后在主区域用 **iframe** 嵌入控制台
+ * （`/api/card-dispatch/`，由宿主半的 human-channel 提供）。
+ *
+ * 为什么用 iframe 而不是把整页重写成 React 组件：
+ *   1. 控制台是一份完全自包含的 HTML（`src/console.html`），浏览器里直接打开也能用，
+ *      桌面端只是把它塞进侧边栏——同一份实现，不会出现「面板和网页行为不一致」；
+ *   2. 页面里的 `fetch` 与 GUI 同源，宿主签发的连接 cookie 自动带上，不需要再搭 RPC 通道；
+ *   3. 客户端模块加载失败也不会连累台账：这个文件只负责注册座位，所有异常都吞掉并打日志。
+ *
+ * 与 dsh-go-workbench 相同的注册方式（本机已验证可用的写法）：
+ *   `slots.inject('sidebar.panellist', …)` 加一行；`slots.inject('main', …)` 用我们的 key
+ *   挂整页面板。座位由 shell 声明，回调缺席时面板只是不出现，不会让 GUI 启动失败。
+ *
+ * @module dsh-card-dispatch/client
+ */
+
+'use strict'
+
+;(function () {
+  /** 控制台路径（与宿主半 HUMAN_ROUTE_PREFIX 一致）。 */
+  var CONSOLE_PATH = '/api/card-dispatch/'
+  var PANEL_ID = 'card-dispatch'
+  var PANEL_ORDER = 42
+
+  /** 是否运行在 DSH 客户端模块加载器里（false = Node 单测环境）。 */
+  var IS_BROWSER =
+    typeof window !== 'undefined' &&
+    window.__ModuleLoader__ !== undefined &&
+    typeof window.__ModuleLoader__.load === 'function'
+
+  /**
+   * 构建客户端模块（`require` 由加载器注入，React 从浏览器模块表取）。
+   * @param {(id: string) => any} require 模块加载器提供的 require。
+   * @returns {object} 客户端插件模块。
+   */
+  function createCardDispatchModule(require) {
+    var React = require('react')
+    var h = React.createElement
+
+    /** 侧边栏图标：一个「流水线 + 勾」的简化线稿，跟着主题文字色走。 */
+    function PanelIcon() {
+      return h(
+        'svg',
+        { width: 18, height: 18, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor',
+          strokeWidth: 1.8, strokeLinecap: 'round', strokeLinejoin: 'round' },
+        h('rect', { x: 3, y: 4, width: 7, height: 5, rx: 1.5 }),
+        h('rect', { x: 14, y: 4, width: 7, height: 5, rx: 1.5 }),
+        h('path', { d: 'M6.5 9v4.5h11V9' }),
+        h('rect', { x: 8.5, y: 13.5, width: 7, height: 5, rx: 1.5 }),
+        h('path', { d: 'M10.2 16l1.3 1.3 2.3-2.4' }),
+      )
+    }
+
+    /**
+     * 整页面板：占满主区域，里面是控制台 iframe。
+     * @returns {object} React 元素。
+     */
+    function Panel() {
+      return h(
+        'div',
+        { style: { display: 'flex', flexDirection: 'column', height: '100%', minHeight: 0 } },
+        h('iframe', {
+          src: CONSOLE_PATH,
+          title: '派卡台控制台',
+          style: { flex: '1 1 auto', width: '100%', border: 'none', background: 'transparent' },
+        }),
+      )
+    }
+
+    /**
+     * 注册座位。任何一步失败都只打日志：界面缺一行，绝不是台账故障。
+     * @param {object} ctx 客户端插件上下文。
+     */
+    function apply(ctx) {
+      try {
+        var slots = ctx.slots
+        if (!slots || typeof slots.register !== 'function' || typeof slots.inject !== 'function') {
+          console.error('[card-dispatch] 客户端缺少 slots 服务，侧边栏入口未注册')
+          return
+        }
+        var disposers = []
+        var add = function (dispose) {
+          if (typeof dispose === 'function') disposers.push(dispose)
+        }
+        ctx.effect(function () {
+          return function () {
+            for (var index = 0; index < disposers.length; index += 1) {
+              try {
+                disposers[index]()
+              } catch (error) {
+                // 卸载期的失败没有意义，忽略
+              }
+            }
+          }
+        }, 'card-dispatch: client panel')
+
+        add(
+          slots.inject('sidebar.panellist', function () {
+            return slots.register(
+              {
+                name: 'sidebar.panellist',
+                id: PANEL_ID,
+                order: PANEL_ORDER,
+                label: function () {
+                  return '派卡台'
+                },
+              },
+              PanelIcon,
+            )
+          }),
+        )
+        add(
+          slots.inject('main', function () {
+            return slots.register({ name: 'main', key: PANEL_ID }, Panel)
+          }),
+        )
+      } catch (error) {
+        console.error('[card-dispatch] 客户端面板注册失败：', error)
+      }
+    }
+
+    return {
+      name: PANEL_ID,
+      inject: ['slots'],
+      apply: apply,
+      Panel: Panel,
+      PanelIcon: PanelIcon,
+      CONSOLE_PATH: CONSOLE_PATH,
+    }
+  }
+
+  // 浏览器侧：注册进 DSH 的客户端模块加载器（id 必须等于包名）
+  if (IS_BROWSER) {
+    window.__ModuleLoader__.load({
+      id: 'dsh-card-dispatch',
+      factory: function (require) {
+        return createCardDispatchModule(require)
+      },
+    })
+  }
+
+  // Node 侧（单测）：把工厂挂到 globalThis——本包是 type:module，CJS 的 module.exports
+  // 分支在 ESM 里取不到，所以两种加载方式都给一条路。
+  if (!IS_BROWSER) {
+    if (typeof globalThis !== 'undefined') {
+      globalThis.__CARD_DISPATCH_CLIENT_FACTORY__ = createCardDispatchModule
+    }
+    if (typeof module !== 'undefined' && module.exports !== undefined) {
+      module.exports = { createCardDispatchModule: createCardDispatchModule }
+    }
+  }
+})()

package/src/config-store.js

@@ -0,0 +1,49 @@
+/**
+ * config-store.js：面板改的开关落到 `dataDir/config.json`。
+ *
+ * 三个刻意选择：
+ *
+ * 1. **落盘的是「归一化后的完整配置」**，不是人提交的那个补丁。这样下次启动时哪怕
+ *    缺省值变了，也不会出现「文件里只有半份配置」的中间态（偏差 D-10 的同一个教训）。
+ * 2. **读失败一律当空配置**。文件被手改成半截 JSON 时，插件要能起来并让人在面板里
+ *    看见「配置读取失败」，而不是整个宿主装不上。
+ * 3. **写入不是原子的**，但损坏时可恢复（下次读失败 = 缺省值）。这里没有并发写者：
+ *    只有本机人在面板上点，够用；换成原子写在当前沙箱里反而更容易踩到 rename 的坑。
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+export function createConfigStore({ dir }) {
+  const root = resolve(dir)
+  const file = join(root, 'config.json')
+
+  /** @returns {{config: object, error: string|null}} */
+  function load() {
+    try {
+      const text = readFileSync(file, 'utf8')
+      const parsed = JSON.parse(text)
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { config: {}, error: `配置文件的顶层必须是对象，实际是 ${Array.isArray(parsed) ? 'array' : typeof parsed}` }
+      }
+      return { config: parsed, error: null }
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { config: {}, error: null }
+      return { config: {}, error: `配置文件读取失败：${error?.message ?? String(error)}` }
+    }
+  }
+
+  /** @param {object} config 归一化后的完整配置 */
+  function save(config) {
+    mkdirSync(root, { recursive: true })
+    writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+    return config
+  }
+
+  return { file, load, save }
+}
+
+/** 配置的存放位置（面板/日志里展示用）。 */
+export function configFilePath(dir) {
+  return join(resolve(dir), 'config.json')
+}

package/src/config.js

@@ -0,0 +1,229 @@
+/**
+ * config.js：插件的**唯一配置真源**。
+ *
+ * 设计约束（都是踩过的坑）：
+ *
+ * 1. **任何键都可选、任何值都不许让插件装不上**。宿主 profile 的 `cordis.patch.yml`
+ *    里可能还留着上一版插件的键（`acknowledgedFindings` / `defaultRole` / `budgetPerDay`…），
+ *    按 id 打补丁是**整体替换 config**，少写一个键就会冲掉别的值——所以缺省值必须由
+ *    代码兜住，而不是靠 YAML 写全（偏差 D-10）。
+ * 2. **只做数值/枚举/布尔的收敛，不做语义校验**。类型不对就退回缺省并记一条 note，
+ *    由 `/status` 告诉人哪一项没生效，而不是启动时抛错。
+ * 3. 配置分两类，面板和文档都按这个分类展示：
+ *    - `enforce`：插件能真拦的（开关、预算、并发、证据门槛）；
+ *    - `observe`：平台行为，插件只能体检和提示（委派深度、拓扑审计）。
+ */
+
+/** 配置项声明表：归一化、面板、文档共用这一份，避免三处写法漂移。 */
+export const CONFIG_SPEC = Object.freeze([
+  { path: 'enabled', type: 'boolean', default: false, kind: 'enforce', label: '总开关', help: '关掉后不注册执行能力，只留控制台' },
+  { path: 'permission', type: 'enum', values: ['read-only', 'workspace-write', 'danger-full-access', null], default: 'workspace-write', kind: 'enforce', label: '卡片权限预设' },
+  { path: 'dataDir', type: 'string', default: '.card-dispatch', kind: 'enforce', label: '数据目录' },
+  { path: 'gates.requirePlanApproval', type: 'boolean', default: true, kind: 'enforce', label: '计划闸', help: 'DAG 未经人确认不开会话' },
+  { path: 'gates.budgetPerDay', type: 'int', min: 0, max: 100000, default: 200, kind: 'enforce', label: '每日运行预算' },
+  { path: 'gates.maxParallelRuns', type: 'int', min: 1, max: 32, default: 3, kind: 'enforce', label: '并发上限' },
+  { path: 'gates.maxReworkRounds', type: 'int', min: 0, max: 10, default: 2, kind: 'enforce', label: '打回上限' },
+  { path: 'gates.requireEvidence', type: 'boolean', default: true, kind: 'enforce', label: '交付门槛', help: '没有 commit / 报告不允许提交' },
+  { path: 'models.useModel', type: 'boolean', default: true, kind: 'enforce', label: '用模型写判据草稿', help: '关掉就只用规则提炼（点一次生成也会花钱）' },
+  { path: 'models.draftRoute', type: 'string', default: '', kind: 'enforce', label: '判据草稿用哪个模型', help: 'provider/model；留空=宿主默认' },
+  { path: 'org.departments', type: 'stringList', default: ['dev', 'verify', 'integrate'], kind: 'enforce', label: '部门' },
+  { path: 'org.depthRequired', type: 'int', min: 0, max: 3, default: 2, kind: 'observe', label: '所需委派深度', help: '主管要带人就得 2；插件改不了，只能体检' },
+  { path: 'execution.driver', type: 'enum', values: ['task-board', 'none'], default: 'task-board', kind: 'enforce', label: '执行层驱动' },
+  { path: 'execution.teamRun', type: 'boolean', default: true, kind: 'enforce', label: '用 teamRun 卡片', help: '父卡起 Lead，子卡起 teammate' },
+  { path: 'audit.orgChart', type: 'boolean', default: true, kind: 'observe', label: '拓扑审计', help: '人员越权在平台上已不可能，这里只做事后稽查' },
+])
+
+/** 旧版顶层键 → 新路径。只在新闻路径都没写时生效。 */
+const LEGACY_ALIASES = Object.freeze({
+  budgetPerDay: 'gates.budgetPerDay',
+  maxParallelRuns: 'gates.maxParallelRuns',
+})
+
+/** 反查表：新路径 → 旧顶层键，供 coerce 用。 */
+const LEGACY_LOOKUP = Object.freeze(
+  Object.fromEntries(Object.entries(LEGACY_ALIASES).map(([legacy, path]) => [path, legacy])),
+)
+
+/** 同一项配置的降级来源：新路径没写时按顺序回退（旧版嵌套结构）。 */
+const FALLBACK_PATHS = Object.freeze({
+  permission: ['autoProvision.permission'],
+})
+
+/** 认得但并不等于「没用过」的旧顶层键：它们不该出现在「不认识」清单里。 */
+const LEGACY_TOP = new Set(['budgetPerDay', 'maxParallelRuns', 'autoProvision'])
+
+function getPath(source, path) {
+  return path.split('.').reduce((node, key) => (node == null ? undefined : node[key]), source)
+}
+
+function hasPath(source, path) {
+  const keys = path.split('.')
+  let node = source
+  for (const key of keys) {
+    if (node == null || typeof node !== 'object' || !Object.prototype.hasOwnProperty.call(node, key)) return false
+    node = node[key]
+  }
+  return true
+}
+
+function toBoolean(value) {
+  if (typeof value === 'boolean') return value
+  if (value === 'true') return true
+  if (value === 'false') return false
+  return undefined
+}
+
+function toInt(value, min, max) {
+  const number = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10)
+  if (!Number.isFinite(number)) return undefined
+  const rounded = Math.trunc(number)
+  if (rounded < min || rounded > max) return undefined
+  return rounded
+}
+
+function toStringList(value) {
+  if (!Array.isArray(value)) return undefined
+  const out = value
+    .map((item) => String(item ?? '').trim())
+    .filter((item) => item !== '')
+  return out.length > 0 ? out : undefined
+}
+
+/**
+ * 按声明表收敛一项配置。
+ * @returns {{value:any, note:string|null}}
+ */
+function coerce(spec, raw, source) {
+  const candidates = [spec.path]
+  if (LEGACY_LOOKUP[spec.path]) candidates.push(LEGACY_LOOKUP[spec.path])
+  for (const fallback of FALLBACK_PATHS[spec.path] ?? []) candidates.push(fallback)
+  const found = candidates.find((path) => hasPath(source, path))
+  const rawValue = found === undefined ? undefined : getPath(source, found)
+
+  if (rawValue === undefined) return { value: spec.default, note: null }
+
+  let value
+  switch (spec.type) {
+    case 'boolean':
+      value = toBoolean(rawValue)
+      break
+    case 'int':
+      value = toInt(rawValue, spec.min, spec.max)
+      break
+    case 'string':
+      value = typeof rawValue === 'string' && rawValue.trim() !== '' ? rawValue.trim() : undefined
+      break
+    case 'stringList':
+      value = toStringList(rawValue)
+      break
+    case 'enum':
+      value = spec.values.includes(rawValue) ? rawValue : undefined
+      break
+    default:
+      value = undefined
+  }
+
+  if (value === undefined) {
+    return { value: spec.default, note: `配置项 ${spec.path} 的值不合法（收到 ${JSON.stringify(rawValue)}），已退回缺省值` }
+  }
+  return { value, note: null }
+}
+
+function setPath(target, path, value) {
+  const keys = path.split('.')
+  let node = target
+  for (const key of keys.slice(0, -1)) {
+    if (node[key] == null || typeof node[key] !== 'object') node[key] = {}
+    node = node[key]
+  }
+  node[keys[keys.length - 1]] = value
+}
+
+/**
+ * 归一化：永远返回完整配置，永远不抛错。
+ *
+ * @param {object} [raw] 宿主传进来的原始 config（可能是 null、字符串、旧版结构）
+ * @returns {{config: object, notes: string[], unknownKeys: string[]}}
+ */
+export function normalizeConfigDetailed(raw) {
+  const source = raw !== null && typeof raw === 'object' ? raw : {}
+  const config = {}
+  const notes = []
+
+  for (const spec of CONFIG_SPEC) {
+    const { value, note } = coerce(spec, raw, source)
+    setPath(config, spec.path, value)
+    if (note !== null) notes.push(note)
+  }
+
+  // 未知顶层键：不报错，但要能被人看见（旧版键还在 profile 里时，这条 note 就是线索）
+  const knownTop = new Set(CONFIG_SPEC.map((spec) => spec.path.split('.')[0]))
+  const unknownKeys = Object.keys(source).filter((key) => !knownTop.has(key) && !LEGACY_TOP.has(key))
+  if (unknownKeys.length > 0) {
+    notes.push(`配置里有本版不认识的键：${unknownKeys.join('、')}（已忽略；若是旧版遗留，可以删掉）`)
+  }
+
+  return { config, notes, unknownKeys }
+}
+
+/**
+ * 兼容旧调用点：只要配置对象。
+ * @param {object} [raw]
+ * @returns {object}
+ */
+export function normalizeConfig(raw) {
+  return normalizeConfigDetailed(raw).config
+}
+
+/**
+ * 面板/文档用的声明表快照（去掉内部字段，加上当前值）。
+ * @param {object} config
+ * @returns {Array<object>}
+ */
+export function describeConfig(config) {
+  return CONFIG_SPEC.map((spec) => ({
+    path: spec.path,
+    label: spec.label,
+    kind: spec.kind,
+    type: spec.type,
+    help: spec.help ?? '',
+    values: spec.values ?? null,
+    value: getPath(config, spec.path),
+  }))
+}
+
+/**
+ * 把「面板提交的部分配置」合并进当前配置。
+ *
+ * 只接受声明表里出现过的路径；未知路径直接报出来，不静默丢弃——
+ * 人以为改了其实没改，比报错更糟。
+ *
+ * @param {object} current 已归一化的配置
+ * @param {object} patch 面板提交的**扁平**补丁（键是 `gates.budgetPerDay` 这种路径）
+ * @returns {{config: object, rejected: string[]}}
+ */
+export function mergeConfig(current, patch) {
+  const known = new Set(CONFIG_SPEC.map((spec) => spec.path))
+  const accepted = {}
+  const rejected = []
+  for (const [path, value] of Object.entries(patch ?? {})) {
+    if (!known.has(path)) {
+      rejected.push(path)
+      continue
+    }
+    setPath(accepted, path, value)
+  }
+  const merged = normalizeConfig(deepMerge(current, accepted))
+  return { config: merged, rejected }
+}
+
+/** 递归合并：patch 覆盖 base 的同名键，其余保持 base 的值。 */
+function deepMerge(base, patch) {
+  const out = { ...(base ?? {}) }
+  for (const [key, value] of Object.entries(patch ?? {})) {
+    const nested = value !== null && typeof value === 'object' && !Array.isArray(value)
+    const baseNested = out[key] !== null && typeof out[key] === 'object' && !Array.isArray(out[key])
+    out[key] = nested && baseNested ? deepMerge(out[key], value) : value
+  }
+  return out
+}