dsh-data-domain-knowledge 0.1.1-alpha.2 → 0.1.1-alpha.3

package/src/intent/tools.ts

@@ -1,154 +0,0 @@
-/**
- * 两个 `intent_*` 工具的**注册器**：与「引擎住在哪个平面」解耦。
- *
- * ## 为什么要单独一个文件
- *
- * 工具由 Host 层注册，因此可以被标准模式调用。由于 Host 工具也可能出现在其他 preset
- * 中，执行端会检查会话，只接受 `standard`。
- *
- * @module
- */
-
-import { defineTool, type ToolRunContext } from '@deepseek-ai/dsh-tools'
-import { envelopeFailure } from '#contracts'
-import type { LineageContext } from '#contracts'
-import { isIntentAgentSession } from './scope.js'
-
-/**
- * 注册这两个工具需要引擎提供的能力。
- *
- * 刻意是**结构化的最小面**而不是 `IntentEngine` 本身：宿主平面通过
- * `INTENT_SERVICE` 提供它，注册器只按这个形状使用引擎，不依赖其具体实现位置。
- */
-export interface IntentToolHost {
-  /** `intent_record` 的**工具描述就是路由提示词**（0023）。 */
-  routingPrompt(): string
-  record(args: Record<string, unknown>, exec?: ToolRunContext): unknown
-  view(sessionKey: string, includePrompt?: boolean): unknown
-}
-
-/** `intent_record` 的参数表。描述是路由提示词（工具级），所以这里只声明字段。 */
-const INTENT_RECORD_PARAMS: Record<string, unknown> = {
-  user_input: { type: 'string', required: true, description: '本轮用户原文' },
-  act: { type: 'string', description: '本轮动作 id，取自工具描述里的 act 词表' },
-  category: { type: 'string', description: '意图分类 id：先按预置分类匹配，命中就直接用它的 id；全不命中才自行新起一个 id 或落 unknown' },
-  predicate: { type: 'string', description: '要执行的动作，例如 query_babel_data' },
-  slots: { type: 'json', description: '从用户输入抽取的关键参数' },
-  confidence: { type: 'number', description: '0-1，用于标注 lowConfidence' },
-  refs: { type: 'array', description: '引用对象，例如 { id, kind, label }' },
-  relation: { type: 'string', enum: ['new_task', 'subtask_of'], description: '本轮是新任务还是已有任务的子任务' },
-  turn_id: { type: 'string', description: '当前对话轮次 id；不传则由 Host 生成' },
-  task_id: { type: 'string', description: 'relation=subtask_of 时指向的已有业务任务 id；新任务不传' },
-  subtask_id: { type: 'string', description: '已有子任务 id；新子任务不传，由 Host 生成' },
-  parent_subtask_id: { type: 'string', description: '父任务节点 id；通常由 Host 生成' },
-  run_id: { type: 'string', description: '已有执行尝试 id；重试时传新值' },
-  trace_id: { type: 'string' },
-  domain: { type: 'string' },
-}
-
-/** 工具的最小注册面。测试替身与真实 `ctx` 都满足它。 */
-export interface ToolRegistryLike {
-  register(definition: unknown): unknown
-}
-
-export function jsonTool(name: string, description: string, parameters: Record<string, unknown>, execute: (args: any, exec?: ToolRunContext) => unknown) {
-  return defineTool({
-    name, description, parameters: parameters as any,
-    output: { schema: { type: 'json' }, render: (_args: unknown, value: unknown) => [{ type: 'text' as const, text: JSON.stringify(value) }] },
-    execute: async (args: any, exec: ToolRunContext) => execute(args, exec),
-  } as any)
-}
-
-export function lineageOf(args: Record<string, unknown>, exec?: ToolRunContext): Partial<LineageContext> | undefined {
-  const lineage: Partial<LineageContext> = {}
-  // Session identity is execution context, never model-controlled input.
-  const sessionId = exec?.agent?.session?.header?.id
-  if (sessionId) lineage.sessionId = sessionId
-  const fields: Array<[keyof LineageContext, string]> = [
-    ['turnId', 'turn_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()
-  return Object.keys(lineage).length > 0 ? lineage : undefined
-}
-
-export function sessionKeyOf(exec?: ToolRunContext): string | undefined {
-  const sessionId = exec?.agent?.session?.header?.id
-  return typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : undefined
-}
-
-/**
- * 这个会话是不是**子代理**。
- *
- * 子代理会加入父会话的组合，所以它会继承到 `intent_*` 两个工具。而意图记录描述的是
- * 「用户在跟 Agent 要什么」：子代理做的是被拆出来的一个片段，它记一条只会污染任务树。
- *
- * 这条规矩原来写在 preset 的 delegation 行上（`toolFilter: { deny: [...] }`）。DSH 0.1.8
- * 起 `toolFilter`（与 `persona`）**不再被 `dsh-tool-subagent` 接受** —— 带上它的 preset
- * 直接挂载失败，整个组合都不会生效。平台给的替代是「在 Agent Preset 里配好工具，再用
- * `agentPreset` 选中它」，而那**只对 spawn provider 有效**：fork / codex / claude-code
- * 的子会话按定义继承父会话的组合，没有选择余地（`inheritsParentContext` 直接拒绝）。
- *
- * 所以判据搬进工具本身：看会话头，与「谁把子会话拉起来的」无关。四个 provider 一视同仁，
- * 也不会再出现「新增一个 delegation 行忘了 deny」这种漏法。
- *
- * 判据取两个字段：`origin === 'subagent'` 是产品分类，`delegationDepth > 0` 是递归深度
- * （持久化过，重启后仍然成立）。任一条成立就算子会话。
- */
-export function isSubagentSession(exec?: ToolRunContext): boolean {
-  const header = exec?.agent?.session?.header
-  if (!header) return false
-  if (header.origin === 'subagent') return true
-  return typeof header.delegationDepth === 'number' && header.delegationDepth > 0
-}
-
-/** 子代理调这两个工具时统一回这一条：说清为什么，并给出该走的路。 */
-function subagentRefusal(): unknown {
-  return envelopeFailure({ sessionKey: null }, {
-    code: 'SUBAGENT_NOT_RECORDED',
-    message: '子代理不记录意图：意图描述的是用户与主 Agent 的交互。把要记的内容写进返回结果，由主 Agent 记录。',
-    retryable: false,
-  })
-}
-
-/**
- * 注册两个 `intent_*` 工具，返回一个把两者一起撤掉的 disposer。
- *
- * `intent_record` 的描述来自固定的会话审计契约，不依赖设置或注册表。
- *
- * 类型守卫（`typeof disposer === 'function'`）是因为测试替身的 `register` 不一定
- * 返回 disposer。
- */
-export function registerIntentTools(ctx: { tools: ToolRegistryLike }, host: IntentToolHost): () => void {
-  const disposeRecord: unknown = ctx.tools.register(jsonTool('intent_record', host.routingPrompt(), INTENT_RECORD_PARAMS, (args, exec) => (
-    isSubagentSession(exec) ? subagentRefusal() : host.record(args, exec)
-  )))
-  const disposeView: unknown = ctx.tools.register(jsonTool(
-    'intent_store_view', 'View recent intent records and active task ids for the current session. Only standard sessions can use this tool.',
-    { include_prompt: { type: 'boolean' } },
-    (args: { include_prompt?: boolean }, exec) => {
-      if (isSubagentSession(exec)) return subagentRefusal()
-      const session = exec?.agent?.session
-      if (session && !isIntentAgentSession(session)) {
-        return envelopeFailure({ sessionKey: null }, {
-          code: 'INTENT_PRESET_UNSUPPORTED',
-          message: '意图记录只支持标准模式。',
-          retryable: false,
-        })
-      }
-      const sessionKey = sessionKeyOf(exec)
-      if (!sessionKey) {
-        return envelopeFailure({ sessionKey: null }, {
-          code: 'SESSION_CONTEXT_REQUIRED',
-          message: '意图记录只能在有活动 DSH 会话的上下文中读取。',
-          retryable: false,
-        })
-      }
-      return host.view(sessionKey, args.include_prompt)
-    },
-  ))
-  return () => {
-    if (typeof disposeRecord === 'function') (disposeRecord as () => void)()
-    if (typeof disposeView === 'function') (disposeView as () => void)()
-  }
-}

package/src/intent/types.ts

@@ -1,229 +0,0 @@
-import type { ToolStatus } from '#contracts'
-import type { LineageContext } from '#contracts'
-
-export type { ToolStatus }
-
-/**
- * 一个动作类型（act）。
- *
- * act 回答"这一轮用户在**做什么**"，与 category（做什么**业务**）正交：同一句
- * "帮我看下上个月的 GMV" 是 `query` × `data_analysis`。光有 id 时模型只能猜
- * `query` 和 `request` 的区别，所以每一类都带 label 与 description。
- */
-export interface IntentActDef {
-  id: string
-  label: string
-  description: string
-  enabled: boolean
-}
-
-/**
- * 内置 act 词表。它是会话审计的固定提示，不是知识召回配置，也不提供编辑入口。
- */
-export const DEFAULT_ACTS: IntentActDef[] = [
-  { id: 'query', label: '查询', description: '向数据或知识提问，要一个答案或一批结果。', enabled: true },
-  { id: 'request', label: '执行请求', description: '让 Agent 做一件事并产生副作用：写入、发送、导出、修改。', enabled: true },
-  { id: 'inform', label: '补充信息', description: '用户提供事实、参数或上下文，本身不要求动作。', enabled: true },
-  { id: 'confirm', label: '确认', description: '用户认可某个提议或方案，允许继续。', enabled: true },
-  { id: 'select', label: '选择', description: '在多个候选中指定一个。', enabled: true },
-  { id: 'correct', label: '纠正', description: '指出前面的理解或结果不对，要求改。', enabled: true },
-  { id: 'cancel', label: '取消', description: '终止或撤回正在进行的任务。', enabled: true },
-  { id: 'review', label: '审阅', description: '对已产出的内容做检查、评估与把关。', enabled: true },
-  { id: 'explain', label: '解释', description: '要求讲清原理、口径或原因，而不是要新数据。', enabled: true },
-  { id: 'compare', label: '对比', description: '把两个及以上对象放在一起比较差异。', enabled: true },
-  { id: 'recommend', label: '推荐', description: '要建议与取舍意见。', enabled: true },
-  { id: 'resume', label: '继续', description: '回到之前中断的任务继续做。', enabled: true },
-  { id: 'reject', label: '拒绝', description: '不接受某个提议或结果。', enabled: true },
-  { id: 'greet', label: '问候', description: '打招呼、开场。', enabled: true },
-  { id: 'chat', label: '闲聊', description: '非任务性的对话。', enabled: true },
-  { id: 'unknown', label: '未判定', description: '无法归入以上任何一类，或本轮信息不足以判断。', enabled: true },
-]
-
-/** Free-form act id; validated against the fixed audit vocabulary when possible. */
-export type IntentAct = string
-
-/** How one turn relates to the session's existing tasks. */
-export type IntentRelation = 'new_task' | 'subtask_of' | 'unknown'
-
-/** `model` is a model-authored record; `fallback` is the Host's data-turn backfill. */
-export type IntentSource = 'model' | 'fallback'
-
-export interface IntentSlotMap {
-  [name: string]: unknown
-}
-
-export interface IntentRef {
-  id: string
-  kind?: string
-  label?: string
-}
-
-/**
- * One built-in intent category; `route` names the act it usually maps to.
- *
- * 固定分类的作用是**把模型的自由判断收窄成一次匹配**：
- * {@link description} 说明这一类"是什么"，{@link examples} 给出用户可能怎么说。
- * 两者都会被拼进固定的 routing prompt，模型先按它们匹配，命中就直接用该 id。
- */
-export interface IntentCategory {
-  id: string
-  label: string
-  route: string
-  description: string
-  /**
-   * 预置说法（few-shot）：用户可能怎么表达这一类意图，每行一条。
-   *
-   * 固定词表中的 few-shot 说法。
-   */
-  examples?: string[]
-  enabled: boolean
-}
-
-/**
- * Recorder settings. 只有审计运行参数保留为内部默认值；分类词表属于固定契约，
- * 不再作为用户配置暴露。
- */
-export interface IntentSettings {
-  /** Below this confidence a record is annotated lowConfidence; the model decides whether to clarify. */
-  clarifyThreshold: number
-  ttlSeconds: number
-  /**
-   * 0023：路由提示词**没有开关**。它随 `intent_record` 的工具描述一起下发，
-   * 分类规则必须始终在场——否则模型退化成每轮从零判断。
-   */
-  /** Backfill one `unknown` record when an eligible data turn ends without a model record. */
-  fallbackEnabled: boolean
-}
-
-function category(id: string, label: string, route: string, description: string, examples: string[]): IntentCategory & { examples: string[] } {
-  return { id, label, route, description, examples, enabled: true }
-}
-
-/**
- * 出厂预置的意图分类。
- *
- * 每一项都**必须**带 `description` 与 `examples`：只给标签（"数据分析"）时模型
- * 只能靠猜，同一句话在不同轮次会被分到不同类。这些文案是模型的匹配依据，全部
- * 词表随代码发布，不通过知识库配置或 UI 修改。
- */
-export const DEFAULT_CATEGORIES: Array<IntentCategory & { examples: string[] }> = [
-  category('data_analysis', '数据分析', 'query', '取数、算指标、拆口径的请求：给一个数或一段分析结论。', ['帮我算一下上个月的 GMV', '这个指标怎么拆', '跑个数看看环比']),
-  category('metadata_exploration', '元数据探索', 'query', '问"有哪些表/字段/口径"本身，要的是结构而不是数字。', ['这张表有哪些字段', '库里有几张订单表', '这些指标的口径是怎么定义的']),
-  category('data_validation', '数据校验', 'query', '核对数据是否可信：对不上、空值、重复、异常波动。', ['这两个数对不上，查一下', '帮我看下这列有没有重复', '空值率是不是偏高了']),
-  category('knowledge_consultation', '知识咨询', 'query', '问组织既有的结论、规则、流程或负责人，答案在知识库里。', ['我们去年是怎么定这个口径的', '知识库里有没有相关文档', '这个流程找谁确认']),
-  category('knowledge_building', '知识构建', 'request', '把材料沉淀进知识库：录入来源、写卡片、重建索引。', ['把这份文档存进知识库', '记一条：这个口径改成…', '帮我整理成一张知识卡片']),
-  category('document_research', '文档研究', 'query', '对一份或多份长文档做通读、归纳、对比、找证据。', ['把这份 PRD 读一遍，总结需求点', '这几篇文档有没有冲突', '从报告里找出支持这个结论的证据']),
-  category('message_collaboration', '消息协作', 'request', '替用户发消息、同步进度、在群里通知或拉人。', ['发条消息给张三', '在群里同步一下进度', '@一下负责人催确认']),
-  category('artifact_delivery', '产物交付', 'request', '要一个可交付的文件：表格、报告、周报、导出件。', ['导出一份 Excel', '生成这周的周报', '把结果做成表格发我']),
-  category('agent_engineering', 'Agent 工程', 'request', '改 Agent 自身：加工具、调提示词、改 skill、查它为什么这么答。', ['加一个工具', '这个 skill 怎么改', '它刚才为什么没调那个工具']),
-  category('tooling_operations', '工具运维', 'request', '运维动作：重启、看队列、清缓存、处理环境报错。', ['重启一下服务', '看看任务队列', '这个报错怎么修']),
-  category('personal_assistant', '个人助理', 'request', '个人日程与提醒类事务。', ['明天提醒我开会', '帮我约个会', '看下我今天的日程']),
-  category('conversation', '普通对话', 'chat', '寒暄、闲聊、对 Agent 本身的提问，没有数据或交付目标。', ['你好', '你是谁', '谢谢，先这样']),
-]
-
-export const DEFAULT_PREDICATES: string[] = [
-  'query_babel_data', 'query_knowledge', 'query_source_truth', 'query_metadata',
-  'query_graph', 'add_source', 'propose_wiki_cards', 'rebuild_knowledge',
-  'send_message', 'export_artifact', 'unknown',
-]
-
-export const DEFAULT_INTENT_SETTINGS: IntentSettings = {
-  clarifyThreshold: 0.65,
-  ttlSeconds: 600,
-  fallbackEnabled: true,
-}
-
-/** One recorded intent. The record is an audit fact; it never drives control flow. */
-export interface IntentRecord {
-  id: string
-  sessionKey: string
-  /** `sessionKey#turn` — the upsert key that keeps one record per turn. */
-  turnKey: string
-  turnId: string
-  userInput: string
-  act: IntentAct
-  category?: string
-  predicate?: string
-  slots: IntentSlotMap
-  confidence?: number
-  lowConfidence?: boolean
-  refs: IntentRef[]
-  relation: IntentRelation
-  source: IntentSource
-  createdAt: string
-  updatedAt: string
-  lineage: LineageContext
-  meta: Record<string, unknown>
-}
-
-export interface IntentRecordInput {
-  userInput: string
-  act?: string
-  category?: string
-  predicate?: string
-  slots?: IntentSlotMap
-  confidence?: number
-  refs?: IntentRef[]
-  relation?: IntentRelation
-  sessionKey: string
-  turnId?: string
-  lineage?: Partial<LineageContext>
-  now?: number
-}
-
-/** Compact task context returned to the model so it can pick the next relation. */
-export interface IntentTaskSummary {
-  taskId: string
-  lastSubtaskId?: string
-  category?: string
-  ageSeconds: number
-}
-
-export interface IntentStoreView {
-  sessionKey: string
-  activeTaskId?: string
-  activeIntentId?: string
-  tasks: IntentTaskSummary[]
-  recent: IntentRecord[]
-  expiresAt?: string
-}
-
-export interface IntentResultData {
-  intentId?: string
-  taskId?: string
-  subtaskId?: string
-  parentSubtaskId?: string
-  runId?: string
-  turnId?: string
-  act?: string
-  category?: string
-  relation?: IntentRelation
-  source?: IntentSource
-  lowConfidence?: boolean
-  activeTasks?: IntentTaskSummary[]
-  store?: IntentStoreView
-  prompt?: string
-  /** True when the scoped tool call was intentionally ignored as a non-data turn. */
-  skipped?: boolean
-  skipReason?: 'non_data_agent' | 'unsupported_preset' | 'non_data_turn'
-}
-
-export interface IntentResult {
-  ok: boolean
-  status: ToolStatus
-  data: IntentResultData
-  warnings: string[]
-}
-
-/** Live turn state: the provisional ids allocated before the model records. */
-export interface IntentTurnState {
-  turn: number
-  userInput: string
-  subtaskId: string
-  taskId?: string
-  /** The turn entered the data intent scope through text, payload or a data tool. */
-  eligible: boolean
-  /** A data tool ran during this turn; a later chat classification cannot revoke it. */
-  dataToolUsed: boolean
-  committed: boolean
-}