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

package/scripts/sync-agent-preset.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * 把 `preset/tita-data-agent/` 编译成 `cordis.patch.yml` 里的一条
+ * `@deepseek-ai/dsh-agent-preset` 声明行。
+ *
+ * ## 为什么需要一步「编译」，而不是直接把组合写进 patch
+ *
+ * preset 的真源要满足两件事，而它们指向不同的文件形态：
+ *
+ * 1. **它要能被人读、被 review、被测试。** `preset/tita-data-agent/agent.cordis.yml`
+ *    是一份完整组合，改动是「改提示词」这种语义级的事；`agent-preset.ts` 的
+ *    `readPersonaPrompt` 也已经按这份文件的 `persona` 行来解析。
+ * 2. **DSH 只认 `cordis.patch.yml` 里的声明行。** 见下面「0.1.7 换了寻址」。
+ *
+ * 所以两者之间需要一次投影，而不是让同一份组合在仓库里存两份、各自漂移。这个
+ * 脚本就是那次投影：真源唯一，生成物有标记，`--check` 让 doctor 能在 CI 与
+ * 本地都问出「改了真源但忘了编译」。
+ *
+ * ## 0.1.7 换了寻址：目录没了
+ *
+ * 0.1.5 时用户 preset 是 `$DSH_HOME/.agent-presets/<id>/`，里面放 `preset.yml`
+ * （展示名）与 `agent.cordis.yml`（组合）。**0.1.7 不再读那个目录**：registry
+ * 只接受 `agentPresets.register(config)`，没有任何文件系统扫描。preset 现在的
+ * 唯一形态是 profile 组合里的一条 `@deepseek-ai/dsh-agent-preset` 声明行，而
+ * 随插件一起分发的唯一办法就是让插件自己的 bundle patch 去 `insert` 它。
+ *
+ * 好消息是**子行的解析基准是 profile 根**（所有 patch 层由 `composeEntries`
+ * 合并进同一个 root include，`mountRootInclude` 把 baseUrl 定在 profile 目录），
+ * 而运行时的解析表同时收 installation scope（`@deepseek-ai/dsh-persona` 等）
+ * 与 profile scope（`dsh-data-domain-knowledge/intent-tools`）。所以这份组合里两种包
+ * 都能解析 —— 不需要给插件补一堆 peer。
+ *
+ * 用法：
+ *   node scripts/sync-agent-preset.mjs           # 编译并写回 cordis.patch.yml
+ *   node scripts/sync-agent-preset.mjs --check    # 只校验是否同步（不同步则退出 1）
+ *   node scripts/sync-agent-preset.mjs --dry-run  # 打印会写入的内容，不动文件
+ */
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 与 `src/client/agent-preset.ts` 的 `TITA_PRESET_ID`、组合文件里的引用一致。 */
+const PRESET_ID = 'tita-data-agent'
+
+/** patch 行 id 的约定形态：`preset-<preset id>`。 */
+const ROW_ID = `preset-${PRESET_ID}`
+
+/** 标记区。生成物只活在两者之间，区外的一切由人维护。 */
+const BEGIN = '# >>> agent preset (generated) >>>'
+const END = '# <<< agent preset (generated) <<<'
+
+/** 声明行在 YAML 里的缩进：`plugins:` 落在 8，列表项落在 10。 */
+const PLUGINS_INDENT = 10
+
+const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const sourceDir = join(pluginRoot, 'preset', PRESET_ID)
+const patchPath = join(pluginRoot, 'cordis.patch.yml')
+
+const check = process.argv.includes('--check')
+const dryRun = process.argv.includes('--dry-run')
+
+/**
+ * 读 `preset.yml` 的三个标量。
+ *
+ * **这不是一个 YAML 解析器**，和 `readPersonaPrompt` 同一个理由：这里要读的只有
+ * `name` / `description` / `order` 三个顶层标量，为它们拉一个依赖不值得。代价是
+ * 它只认「一行一个 `key: value`」，多行标量会读成第一行 —— 对这三个字段来说那是
+ * 一个显式的坏输入，而不是一个静默的错误答案。
+ */
+function readPresetMeta(content) {
+  const meta = {}
+  for (const line of content.split('\n')) {
+    const match = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line)
+    if (!match) continue
+    const [, key, raw] = match
+    // 去掉一层成对的引号（单引号里 `''` 是转义的 `'`）。
+    let value = raw.trim()
+    if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+      value = value.slice(1, -1).replaceAll("''", "'")
+    } else if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+      value = value.slice(1, -1)
+    }
+    meta[key] = value
+  }
+  return meta
+}
+
+/** YAML 单引号标量：内部 `'` 写成 `''`。 */
+function quote(value) {
+  return `'${String(value).replaceAll("'", "''")}'`
+}
+
+/** 把组合正文整体缩进到 `plugins:` 之下；空行保持空，免得留下尾随空格。 */
+function indentPlugins(content) {
+  const pad = ' '.repeat(PLUGINS_INDENT)
+  return content
+    .replace(/\s+$/, '')
+    .split('\n')
+    .map(line => (line.trim() === '' ? '' : pad + line))
+    .join('\n')
+}
+
+/** 渲染标记区之间的完整内容。 */
+function renderBlock(meta, agentComposition) {
+  const header = [
+    '# Tita Data Agent 的 agent preset 声明。',
+    '#',
+    '# 这一段由 `scripts/sync-agent-preset.mjs` 从 `preset/tita-data-agent/` 生成 ——',
+    '# **不要手改**：改真源再跑 `pnpm sync:preset`。`pnpm doctor` 会校验它与真源一致。',
+    '#',
+    '# 为什么 preset 必须长在插件的 patch 里：0.1.7 起 DSH 不再扫描',
+    '# `$DSH_HOME/.agent-presets/`，preset 的唯一形态就是这条 insert。详见脚本头注释。',
+  ]
+  const lines = [
+    ...header,
+    '- insert:',
+    `    - id: ${ROW_ID}`,
+    "      name: '@deepseek-ai/dsh-agent-preset'",
+    '      config:',
+    `        id: ${PRESET_ID}`,
+  ]
+  if (meta.name !== undefined && meta.name !== '') lines.push(`        name: ${quote(meta.name)}`)
+  if (meta.description !== undefined && meta.description !== '') lines.push(`        description: ${quote(meta.description)}`)
+  if (meta.order !== undefined && meta.order !== '') lines.push(`        order: ${meta.order}`)
+  lines.push('        plugins:')
+  lines.push(indentPlugins(agentComposition))
+  return lines.join('\n')
+}
+
+/**
+ * 把 `block` 放进 `BEGIN`/`END` 之间。
+ *
+ * 标记不存在时**追加**到文件末尾：patch 层的顺序是「bundle 数组顺序」，这条声明
+ * 只要在 registry 那条 entry 之后即可，而 registry 属于 `dsh-web-app`，排在所有
+ * 本地插件之前 —— 所以追加是安全的，不需要插到文件中间。
+ */
+function spliceBlock(patchContent, block) {
+  const beginAt = patchContent.indexOf(BEGIN)
+  const endAt = patchContent.indexOf(END)
+  const wrapped = `${BEGIN}\n${block}\n${END}`
+  if (beginAt !== -1 && endAt !== -1 && endAt > beginAt) {
+    const before = patchContent.slice(0, beginAt)
+    const after = patchContent.slice(endAt + END.length)
+    return { content: `${before}${wrapped}${after}`, existed: true }
+  }
+  const base = patchContent.replace(/\s+$/, '')
+  return { content: `${base}\n\n${wrapped}\n`, existed: false }
+}
+
+async function main() {
+  const [metaSource, agentComposition, patchSource] = await Promise.all([
+    readFile(join(sourceDir, 'preset.yml'), 'utf8'),
+    readFile(join(sourceDir, 'agent.cordis.yml'), 'utf8'),
+    readFile(patchPath, 'utf8'),
+  ])
+
+  const block = renderBlock(readPresetMeta(metaSource), agentComposition)
+  const { content, existed } = spliceBlock(patchSource, block)
+
+  if (check) {
+    if (content === patchSource) {
+      console.log(`preset 已同步：${ROW_ID}（标记区${existed ? '' : '缺失'}）`)
+      return
+    }
+    console.error(`preset 与真源不同步：${patchPath}`)
+    console.error(`跑 \`pnpm sync:preset\` 重新生成（真源：preset/${PRESET_ID}/）。`)
+    process.exitCode = 1
+    return
+  }
+
+  if (dryRun) {
+    console.log(block)
+    return
+  }
+
+  if (content === patchSource) {
+    console.log(`无变化：${ROW_ID} 已是最新。`)
+    return
+  }
+  await writeFile(patchPath, content)
+  console.log(`已写入 ${ROW_ID} → ${patchPath}`)
+  console.log(`重启 DSH 后生效；preset 在**会话创建时**固定，正在跑的会话不受影响。`)
+}
+
+main().catch(error => {
+  console.error(`同步失败：${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+})

package/src/client/AgentPresetCard.tsx

@@ -0,0 +1,247 @@
+/**
+ * Agent 提示词（0029 / 0030 / 0036）—— 控制台里对 **agent preset** 的只读视图，
+ * 外加一个「去真源目录改它」的动作。
+ *
+ * ## 为什么这里没有「默认 Agent preset」这一项
+ *
+ * 它曾经有：一个下拉，写 `agent-preset-registry` 那条 profile entry 的 `default`。
+ * 那是个**重复**——DSH 设置里本来就有同一项，同一个字段、同一个真源。在控制台里再
+ * 摆一个，用户就要回答「这两处哪个算数」（答案是都算数，因为写的是同一个字段，但
+ * 光看界面看不出来）。所以它撤了：**默认 preset 归 DSH 设置**，这里只在它不是默认
+ * 时把这件事说出来，并指明去哪儿改。
+ *
+ * ## 保留的是「提示词正文」和「怎么改它」
+ *
+ * 正文只读，因为它的真源是一份**组合文件**（`agent.cordis.yml` 的 `persona` 行），
+ * 不是一段配置值：它决定这个 Agent 挂哪些工具、有哪些提示词段。从浏览器里改它，等于
+ * 让一个表单去写一份组合 —— 而 DSH 对 preset 的授权模型刻意是「声明式创建、之后一切
+ * 发生在声明它的那份文件里」。
+ *
+ * 所以这一块做三件事：把正文读出来给你看、把**真源目录**告诉你并给你一个按钮打开它、
+ * 在空态与错误态里说清问题与恢复动作。
+ *
+ * ## 打开目录走的是 `session` 命名空间，不是 `settings`
+ *
+ * 0.1.7 起 DSH 那边的 preset **不是一个目录**，是组合里的一条声明行（见 docs/0036），
+ * 所以 `settings.openAgentPresetDirectory` 那种能力不存在了。但「提示词写在哪」仍然
+ * 是一个目录 —— 本插件随包分发的 `preset/tita-data-agent/`。打开它用的是
+ * `session.openWorkspacePath`（文件预览的「在访达中显示」用的也是它），路径由宿主
+ * 算好随布局一起给出来。
+ *
+ * ## 为什么名单走 Remote 而不是自己读磁盘
+ *
+ * roster 的发现（有哪些 preset、哪个是默认、哪个组合不出来）是
+ * `dsh-agent-preset-registry` 的领域知识。控制台自己扫磁盘既得不到准确名单，也会在
+ * DSH 改发现规则时悄悄漂移。所以名单与组合正文都从宿主问：
+ * `agentPresets/list` + `agentPresets/read`。
+ *
+ * @module
+ */
+
+import { useCallback, useEffect, useState, type ReactNode } from 'react'
+import { Button } from '@tita-data-agent/ui/components'
+import { AlertCircle, FolderOpen, LoaderCircle } from '@tita-data-agent/ui/icons'
+import { INTENT_TOOL_NAMES, TITA_PRESET_ID, readPersonaPrompt, type AgentPresetRemote, type PresetRow } from './agent-preset.ts'
+
+// 这几个名字是对外契约（组合文件、安装脚本、测试都引用），从纯数据模块转发出去。
+export { INTENT_TOOL_NAMES, TITA_PRESET_ID, readPersonaPrompt }
+export type { AgentPresetRemote, PresetRow }
+
+type Load =
+  | { status: 'loading' }
+  | { status: 'unavailable'; message: string }
+  | { status: 'ready'; row: PresetRow | null; rows: PresetRow[]; prompt: string | null; defaultRow: PresetRow | null }
+
+/** 「打开真源目录」这个动作的三种结局。`failed` 带一句给用户看的话。 */
+type Open =
+  | { status: 'idle' }
+  | { status: 'opening' }
+  | { status: 'failed'; message: string }
+
+/**
+ * Agent 提示词卡片。挂在设置抽屉的最后一块。
+ *
+ * 它回答三个问题，顺序就是用户会问的顺序：我们那个 preset 在不在、它的提示词写了
+ * 什么、我要改去哪儿改。
+ */
+export function AgentPresetCard({ remote, presetDir, presetDirExists = false }: {
+  remote?: AgentPresetRemote
+  /** 提示词真源目录的绝对路径，由 `/knowledge/layout` 算好给出。 */
+  presetDir?: string
+  /** 那个目录在不在。不在时按钮禁用并如实说明。 */
+  presetDirExists?: boolean
+}): ReactNode {
+  const [load, setLoad] = useState<Load>({ status: 'loading' })
+  const [open, setOpen] = useState<Open>({ status: 'idle' })
+
+  const refresh = useCallback((): void => {
+    /**
+     * 取命名空间这一步本身要兜住。
+     *
+     * cordis 的 remote 代理对**未声明 inject** 的属性直接抛（实测：
+     * `cannot get property "remote.agentPresets" without inject`），而它一旦抛在
+     * `useEffect` 里，React 会把整个面板子树卸掉 —— 打开设置抽屉就会让面板变空白。
+     * `inject` 里已经声明了，这里再兜一层：将来命名空间被摘掉时，坏掉的是一张卡片
+     * 的一句提示，不是整块面板。
+     */
+    let api: AgentPresetRemote['agentPresets']
+    try {
+      api = remote?.agentPresets
+    } catch (cause) {
+      setLoad({ status: 'unavailable', message: cause instanceof Error ? cause.message : String(cause) })
+      return
+    }
+    if (!api) {
+      setLoad({ status: 'unavailable', message: '宿主没有提供 agent preset 名单（dsh-agent-preset-registry 未挂载）。' })
+      return
+    }
+    setLoad({ status: 'loading' })
+    void (async () => {
+      try {
+        const listed = await api.list()
+        if (!listed.ok) {
+          setLoad({ status: 'unavailable', message: listed.message ?? '读取 preset 名单失败' })
+          return
+        }
+        const rows = listed.value.presets ?? []
+        const row = rows.find(item => item.id === TITA_PRESET_ID) ?? null
+        const fallback = rows.find(item => item.isDefault) ?? null
+        let prompt: string | null = null
+        // 我们那个 preset 不在时，预览**默认 preset** 的提示词：至少让用户看见
+        // 「现在这个 Agent 被交代了什么」，而不是一片空白。
+        const target = row ?? fallback
+        if (target) {
+          const read = await api.read(target.id)
+          if (read.ok) prompt = readPersonaPrompt(read.value.content)
+        }
+        setLoad({ status: 'ready', row, rows, prompt, defaultRow: fallback })
+      } catch (cause) {
+        setLoad({ status: 'unavailable', message: cause instanceof Error ? cause.message : String(cause) })
+      }
+    })()
+  }, [remote])
+
+  useEffect(() => { refresh() }, [refresh])
+
+  /**
+   * 在系统文件管理器里打开 preset 的真源目录。
+   *
+   * 宿主会先验证这个路径确实映射到它自己的文件系统上（`verifyDesktopPath`），验证
+   * 不过就拒 —— 那种情况下这里不装作成功：按钮旁边那句话会给出路径，用户仍能自己
+   * 复制过去打开。所以「打开失败」不是一个死胡同。
+   */
+  const openPresetDir = async (): Promise<void> => {
+    if (!presetDir) return
+    let api: AgentPresetRemote['session']
+    try {
+      api = remote?.session
+    } catch (cause) {
+      setOpen({ status: 'failed', message: cause instanceof Error ? cause.message : String(cause) })
+      return
+    }
+    if (!api || typeof api.openWorkspacePath !== 'function') {
+      setOpen({ status: 'failed', message: '宿主没有提供在系统文件管理器里打开路径的能力（session 命名空间未挂载），请手动打开下面这个路径。' })
+      return
+    }
+    setOpen({ status: 'opening' })
+    try {
+      const result = await api.openWorkspacePath({ path: presetDir, action: 'reveal' })
+      setOpen(result.ok
+        ? { status: 'idle' }
+        : { status: 'failed', message: result.message ?? '宿主拒绝了这个路径，请手动打开下面这个路径。' })
+    } catch (cause) {
+      setOpen({ status: 'failed', message: `${cause instanceof Error ? cause.message : String(cause)}　请手动打开下面这个路径。` })
+    }
+  }
+
+  const meta = load.status === 'loading'
+    ? '正在读取…'
+    : load.status === 'unavailable'
+      ? '不可用'
+      : load.row ? '已生效' : '不在名单里'
+
+  return <section className="tita-settingsSection">
+    <div className="tita-settingsSectionHeader">
+      <div>
+        <h3>Agent 提示词</h3>
+        <p>这个 Agent 被交代了什么。真源是随插件分发的 preset 目录，改那里，不在这里。</p>
+      </div>
+      <div className="tita-settingMeta" role="status" aria-live="polite">
+        {load.status === 'loading' && <LoaderCircle size={11} className="tita-spin" />}
+        {meta}
+      </div>
+    </div>
+
+    {load.status === 'unavailable' && <div className="tita-settingsError" role="alert"><AlertCircle size={13} />{load.message}</div>}
+
+    {/* 主操作放在 roster 之外：名单读不到时提示词照样要能改 —— 那两件事互不依赖。 */}
+    <div className="tita-presetActions">
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => void openPresetDir()}
+        disabled={!presetDir || !presetDirExists || open.status === 'opening'}
+      >
+        {open.status === 'opening' ? <LoaderCircle size={12} className="tita-spin" /> : <FolderOpen size={12} />}
+        打开 preset 目录
+      </Button>
+      {presetDir && <code className="tita-presetPath" title={presetDir}>{presetDir}</code>}
+    </div>
+    <small className="tita-settingHint tita-presetHint">
+      改 <code>agent.cordis.yml</code> 的 <code>persona</code> 行 → 跑 <code>pnpm sync:preset</code> 编译进
+      <code>cordis.patch.yml</code> → 重启 DSH → <strong>新建一个会话</strong>（preset 在会话创建时固定）。
+    </small>
+
+    {open.status === 'failed' && <div className="tita-settingsError" role="alert"><AlertCircle size={13} />{open.message}</div>}
+
+    {presetDir && !presetDirExists && <p className="tita-presetNote tita-presetNoteBad">
+      这个安装里没有 <code>preset/</code> 真源目录。它随插件分发，所以只可能是插件装漏了这一段 ——
+      重装插件即可，这里没有可以打开的东西。
+    </p>}
+
+    {load.status === 'ready' && <>
+      <dl className="tita-presetFacts">
+        <div>
+          <dt>{TITA_PRESET_ID}</dt>
+          <dd>
+            {load.row
+              ? <>{load.row.name ?? load.row.id}<span className="tita-presetTrust">随包</span></>
+              : <span className="tita-presetMissing">不在名单里</span>}
+          </dd>
+        </div>
+      </dl>
+
+      {!load.row && <p className="tita-presetNote">
+        名单里没有 <code>{TITA_PRESET_ID}</code>。它随插件分发 —— <code>cordis.patch.yml</code> 里那条
+        <code>@deepseek-ai/dsh-agent-preset</code> 声明就是它，所以只有两种可能：声明与
+        <code>preset/{TITA_PRESET_ID}/</code> 真源不同步（跑 <code>pnpm sync:preset</code>），或者 DSH 还没重启。
+      </p>}
+
+      {load.row?.broken && <p className="tita-presetNote tita-presetNoteBad">
+        它现在组合不出会话，挂载停在 <code>{load.row.broken}</code>。
+        冒号前是没挂上的那一行（只说明组合走到哪里），冒号后才是它抛出的错误原文 —— 按那句话改对应的代码或配置。
+        改的是 <code>preset/{TITA_PRESET_ID}/agent.cordis.yml</code> 就先跑 <code>pnpm sync:preset</code>，然后重启 DSH。
+      </p>}
+
+      {/* 「哪个 preset 是新会话的默认」是 DSH 设置里的一项。这里不重复那个控件，只在
+          它不是默认时把事实说出来并指明去哪儿改 —— 否则用户会以为这个部署已经换成它了。 */}
+      {load.row && !load.row.isDefault && <p className="tita-presetNote">
+        它还不是默认 —— 新建的会话仍在跑「{load.defaultRow?.name ?? load.defaultRow?.id ?? '宿主组合'}」。
+        默认 preset 是 DSH 设置里的一项，在那儿改。
+      </p>}
+
+      {load.prompt
+        ? <div className="tita-promptPreview">
+          <div className="tita-promptPreviewHead">
+            <span>提示词正文</span>
+            <small>persona 行的 prefix · {load.prompt.length} 字符</small>
+          </div>
+          {/* 只读的等宽块，不是输入框：正文的真源是那份 YAML，这里给它一个可选中复制的视图。 */}
+          <pre className="tita-promptBody" tabIndex={0} aria-label="Agent 提示词正文">{load.prompt}</pre>
+        </div>
+        : <p className="tita-presetNote">
+          这个 preset 的组合里没有 <code>persona</code> 提示词行，所以它用的是部署级的默认人格。
+        </p>}
+    </>}
+  </section>
+}