dsh-data-domain-knowledge 0.1.0-alpha.9 → 0.1.1-alpha.2

package/src/intent/README.md

@@ -11,24 +11,26 @@ Host 提供两个工具：
 - `intent_record`：把模型对当前轮次的判断写成一条审计记录。
 - `intent_store_view`：查看当前会话的最近记录与任务链路。
 
-工具只在 Tita preset 的 agent 平面注册。HTTP 只读接口是 `/intent/overview` 与
+工具在 Host 层注册，供标准模式使用。意图写入与读取只接受 `standard` 会话。
+HTTP 只读接口是 `/intent/overview` 与
 `/intent/store`，服务名仍为 `titaDataAgentIntent`。
 
 ## 固定审计契约
 
 分类、act 与 predicate 的内置词表由代码固定提供，不属于知识库配置，也没有编辑入口。
-`intent_record` 的工具描述携带这份固定规则；记录器只校验并保留模型结论，不做关键词
-匹配、不反问、不阻断请求。模型漏调时，Host 在 `turn/end` 补一条
-`source: 'fallback'` 的 `unknown` 记录。
+`intent_record` 的工具描述携带这份固定规则；记录器只校验并保留模型结论，不做完整的
+意图分类、不反问、不阻断请求。门控只负责判断是否进入数据域：其他 preset 和普通聊天
+不创建意图记录；标准模式在数据工具、数据域请求或数据分类被激活后，模型漏调时，
+Host 才在 `turn/end` 补一条 `source: 'fallback'` 的 `unknown` 记录。
 
 ## 记录与 ID
 
-- 按 `session + turn` upsert：同一轮重复调用只保留一条记录。
+- 按 `session + data turn` upsert：同一数据轮次重复调用只保留一条记录，普通轮次不落记录。
 - Host 在 `turn/start` 为当前轮次预分配 `subtaskId`；模型用 `relation` 表示新任务
   （`new_task`）或已有任务的子任务（`subtask_of`）。
 - 记录写入 `<agentRoot>/intent/intent.db`。`intent_records` 保存每轮当前版本，
   `intent_record_history` 追加保存每次变更。内存工作集仍按 TTL（默认 600 秒）管理，
-  SQLite 用于重启后的审计留痕与面板读取。旧的 `records.ndjson` 只做一次性迁移。
+  SQLite 用于重启后的审计留痕与面板读取。
 
 ## 与知识库召回的边界
 

package/src/intent/engine.ts

@@ -15,8 +15,8 @@ import {
   type IntentTaskSummary,
   type IntentTurnState,
 } from './types.js'
-import { envelopeSuccess } from 'dsh-data-contracts/envelope'
-import type { LineageContext } from 'dsh-data-contracts/refs'
+import { envelopeSuccess } from '#contracts'
+import type { LineageContext } from '#contracts'
 
 function id(prefix = 'intent'): string {
   return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
@@ -226,12 +226,14 @@ export class IntentEngine {
    * Downstream calls dispatched in parallel with the record can already carry
    * an id; the record later commits the authoritative task binding.
    */
-  beginTurn(sessionKey: string, turn: number, userInput: string): IntentTurnState {
+  beginTurn(sessionKey: string, turn: number, userInput: string, eligible = true): IntentTurnState {
     const state: IntentTurnState = {
       turn,
       userInput: userInput.slice(0, 2000),
       subtaskId: id('subtask'),
       taskId: this.store.last(sessionKey)?.lineage.taskId,
+      eligible,
+      dataToolUsed: false,
       committed: false,
     }
     this.turns.set(sessionKey, state)
@@ -252,11 +254,46 @@ export class IntentEngine {
     return true
   }
 
-  /** Backfill one `unknown` record when a turn ends without a model record. */
+  /** Mark the current turn as a data turn without classifying it. */
+  markDataIntent(sessionKey: string, turn?: number): boolean {
+    const state = this.turns.get(sessionKey)
+    if (!state || state.committed || (turn !== undefined && state.turn !== turn)) return false
+    state.eligible = true
+    return true
+  }
+
+  /** Mark the current turn as a data turn based on actual data-tool use. */
+  markDataToolUse(sessionKey: string, turn?: number): boolean {
+    const state = this.turns.get(sessionKey)
+    if (!state || state.committed || (turn !== undefined && state.turn !== turn)) return false
+    state.eligible = true
+    state.dataToolUsed = true
+    return true
+  }
+
+  /** Clear a text-only gate when the model explicitly identifies a non-data turn. */
+  clearDataIntent(sessionKey: string, turn?: number): boolean {
+    const state = this.turns.get(sessionKey)
+    if (!state || state.committed || (turn !== undefined && state.turn !== turn)) return false
+    if (!state.dataToolUsed) state.eligible = false
+    return true
+  }
+
+  /** Whether the current turn is eligible for data intent recording. */
+  isDataIntentTurn(sessionKey: string, turn?: number): boolean {
+    const state = this.turns.get(sessionKey)
+    return Boolean(state && !state.committed && state.eligible && (turn === undefined || state.turn === turn))
+  }
+
+  /** Backfill one `unknown` record only when an eligible data turn has no model record. */
   fallbackWhenMissing(sessionKey: string, turn: number): IntentResult | undefined {
     if (!this.settings.fallbackEnabled) return undefined
     const state = this.turns.get(sessionKey)
     if (!state || state.turn !== turn || state.committed) return undefined
+    if (!state.eligible) {
+      this.turns.delete(sessionKey)
+      return undefined
+    }
     const result = this.record({
       userInput: state.userInput,
       act: 'unknown',
@@ -271,7 +308,7 @@ export class IntentEngine {
     return result
   }
 
-  /** Record the model's intent judgement. Always stores a record. */
+  /** Record the model's intent judgement. The host applies scope before calling this method. */
   record(input: IntentRecordInput, source: IntentSource = 'model'): IntentResult {
     const sessionKey = input.sessionKey?.trim() || 'default'
     const timestamp = new Date(input.now ?? Date.now()).toISOString()
@@ -453,7 +490,8 @@ export class IntentEngine {
       })
       .join('\n')
     return [
-      '记录本轮用户意图：先判断，再调用 intent_record 落一条审计记录，然后继续完成请求——记录不改变、不阻塞、也不需要用户确认。',
+      '本工具支持 standard preset 的顶层会话。先判断本轮是否属于数据 / 知识域；只有属于数据域时，才调用 intent_record 落一条数据意图审计；寒暄、闲聊、Agent 自身说明、纯写作、代码和一般运维请求不要调用，也不要补 unknown。记录不改变、不阻塞、也不需要用户确认。',
+      '如果当前请求会使用数据、知识库、表格、报告、SourceRaw、WikiCard、查询、分析、导入、编译或召回工具，它属于数据域；否则按普通对话处理。',
       '当前轮是新的任务用 relation=new_task；如果是在延续某个已有任务（追问、补充、纠正），用 relation=subtask_of 并带上该任务的 task_id；无法判断时省略 relation。',
       '',
       '分类判定分两步，必须先匹配预置、再自行判断：',

package/src/intent/host.ts

@@ -2,19 +2,20 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-settings'
 import type {} from '@deepseek-ai/dsh-system-prompt'
-import { envelopeSuccess } from 'dsh-data-contracts/envelope'
-import type { LineageContext } from 'dsh-data-contracts/refs'
+import { envelopeFailure, envelopeSuccess } from '#contracts'
+import type { LineageContext } from '#contracts'
 import { DEFAULT_INTENT_SETTINGS } from './types.js'
 import { IntentEngine } from './engine.js'
 import { appendIntentRecord, readIntentRecords } from './store.js'
 import type { IntentToolHost } from './tools.js'
 import { lineageOf, sessionKeyOf } from './tools.js'
+import { isIntentAgentSession, isDataIntentCandidate, isDataIntentPayload, isDataToolName, isExplicitNonDataIntentPayload } from './scope.js'
 
 export * from './types.js'
 export * from './engine.js'
 export * from './tools.js'
 
-/** Read-only HTTP surface the 意图 panel reads: `/intent/overview` and `/intent/store`. */
+/** Session intent audit endpoints. */
 export const INTENT_MOUNT_PATH = '/intent'
 /** Cordis service name consumers read to inherit the session's active task ids. */
 export const INTENT_SERVICE = 'titaDataAgentIntent'
@@ -24,10 +25,9 @@ export const INTENT_SERVICE = 'titaDataAgentIntent'
  *
  * 两类消费者，一个服务：
  * - `activeLineage` —— 其它插件（`data-table`）读本轮活动血缘。
- * - 其余成员 —— agent 平面的挂载行（`./preset-tools.ts`）按它注册 `intent_*` 工具。
+ * - 其余成员 —— Host 组合根按它注册 `intent_*` 工具。
  *
- * 0029 之前这两个工具由本模块直接全局注册；现在注册搬到了 agent 平面，这里只留
- * 「引擎能做什么」。引擎只有一份，工具定义也只有一份（`./tools.ts`）。
+ * 本模块只提供意图引擎。组合根在 Host 层注册工具；执行端只接受标准模式的会话。
  */
 export interface IntentService extends IntentToolHost {
   /**
@@ -68,9 +68,7 @@ function userText(message: unknown): string {
  * 它是 `KnowledgePanel` 五个视图之一「意图」的宿主实现。0029 起它**只负责引擎**：
  * 轮次记账、`/intent/**` 只读面，以及通过 `INTENT_SERVICE` 暴露操作面。
  *
- * 两个 `intent_*` 工具**不再在这里注册** —— 它们搬到了 agent 平面的
- * `./preset-tools.ts`，只被自定义 preset 的 `agent.cordis.yml` 挂载，于是只有跑
- * TitaAgent 那套组合的会话才看得到它们。理由见那个文件的模块注释。
+ * `intent_*` 工具由组合根在 Host 层注册；本模块只提供引擎和会话审计能力。
  *
  * 本模块由 `src/index.ts` 组合根调用，不自己导出 `name` / `inject`。
  * @module dsh-data-domain-knowledge/intent
@@ -134,6 +132,26 @@ export function applyIntent(ctx: Context, deps: IntentHostDeps = {}): IntentHost
      */
     record: (args, exec) => {
       const lineage = lineageOf(args, exec)
+      const session = exec?.agent?.session
+      if (session && !isIntentAgentSession(session)) {
+        return envelopeSuccess({ skipped: true, skipReason: 'unsupported_preset' as const })
+      }
+      const sessionKey = sessionKeyOf(exec)
+      if (!sessionKey) {
+        return envelopeFailure({ skipped: false }, {
+          code: 'SESSION_CONTEXT_REQUIRED',
+          message: '意图记录只能在有活动 DSH 会话的上下文中写入。',
+          retryable: false,
+        })
+      }
+      if (isExplicitNonDataIntentPayload(args)) {
+        engine.clearDataIntent(sessionKey)
+        return envelopeSuccess({ skipped: true, skipReason: 'non_data_turn' as const })
+      }
+      if (!engine.isDataIntentTurn(sessionKey) && !isDataIntentPayload(args)) {
+        return envelopeSuccess({ skipped: true, skipReason: 'non_data_turn' as const })
+      }
+      engine.markDataIntent(sessionKey)
       return engine.record({
         userInput: typeof args.user_input === 'string' ? args.user_input : '',
         ...(typeof args.act === 'string' ? { act: args.act } : {}),
@@ -143,7 +161,7 @@ export function applyIntent(ctx: Context, deps: IntentHostDeps = {}): IntentHost
         ...(typeof args.confidence === 'number' ? { confidence: args.confidence } : {}),
         ...(Array.isArray(args.refs) ? { refs: args.refs as Array<{ id: string }> } : {}),
         ...(args.relation === 'new_task' || args.relation === 'subtask_of' ? { relation: args.relation } : {}),
-        sessionKey: sessionKeyOf(args, exec),
+        sessionKey,
         ...(lineage ? { lineage } : {}),
       })
     },
@@ -154,11 +172,15 @@ export function applyIntent(ctx: Context, deps: IntentHostDeps = {}): IntentHost
   // 描述（见 `./tools.ts` 的 `registerIntentTools`）。两处都放会重复占用上下文，
   // 而且会漂移。
 
-  // Turn bookkeeping: allocate provisional ids per turn and backfill one record
-  // if the turn ends without one (issue 0012 decision B).
+  // Turn bookkeeping: allocate provisional ids for standard data turns and backfill
+  // one record only when a data turn ends without one (issue 0012 decision B).
   const pendingInput = new Map<string, string>()
   ctx.on('session/event', (session, event) => {
     const sessionKey = session.header.id as unknown as string
+    if (!isIntentAgentSession(session)) {
+      pendingInput.delete(sessionKey)
+      return
+    }
     if (event.type === 'user/message') {
       const text = userText(event.data)
       if (!text) return
@@ -166,10 +188,12 @@ export function applyIntent(ctx: Context, deps: IntentHostDeps = {}): IntentHost
       // `turn/start` may have arrived before the user message. In that case update the
       // provisional state instead of leaving the record with an empty userInput.
       engine.updateTurnInput(sessionKey, text)
+      if (isDataIntentCandidate(text)) engine.markDataIntent(sessionKey)
       return
     }
     if (event.type === 'turn/start') {
-      engine.beginTurn(sessionKey, event.data.turn, pendingInput.get(sessionKey) ?? '')
+      const input = pendingInput.get(sessionKey) ?? ''
+      engine.beginTurn(sessionKey, event.data.turn, input, isDataIntentCandidate(input))
       return
     }
     if (event.type === 'turn/end') {
@@ -178,9 +202,22 @@ export function applyIntent(ctx: Context, deps: IntentHostDeps = {}): IntentHost
     }
   })
 
-  // Read-only HTTP surface for the 意图 panel. The intent store is in-memory and
-  // session-scoped, so the panel reads it over HTTP instead of duplicating the
-  // engine in the browser.
+  /**
+   * 实际数据工具是比关键词更可靠的后置证据。
+   *
+   * 例如「帮我看看这个」本身没有明显关键词，但模型随后调用了
+   * `recall_knowledge`；这种轮次仍应在结束时补齐一条数据意图审计。
+   */
+  ctx.on('tools/pre-execute', (exec, next) => {
+    const session = exec?.agent?.session
+    if (isIntentAgentSession(session) && isDataToolName(exec?.name)) {
+      const sessionKey = session?.header?.id
+      if (typeof sessionKey === 'string') engine.markDataToolUse(sessionKey)
+    }
+    return next()
+  })
+
+  // Intent audit HTTP surface. It exposes stored intent data only.
   ctx.inject(['webServer'], webCtx => {
     const web = webCtx as unknown as {
       webServer: {
@@ -246,6 +283,10 @@ export function applyIntent(ctx: Context, deps: IntentHostDeps = {}): IntentHost
           const url = new URL(req.url ?? '/', 'http://127.0.0.1')
           const sessionKey = url.searchParams.get('session_key')?.trim() || 'default'
           const includePrompt = url.searchParams.get('include_prompt') === 'true'
+          const requestedLimit = Number(url.searchParams.get('limit'))
+          const recentLimit = Number.isFinite(requestedLimit) && requestedLimit > 0
+            ? Math.min(500, Math.max(1, Math.round(requestedLimit)))
+            : 10
           const view = engine.view(sessionKey, includePrompt)
           const base = root()
           if (base) {
@@ -256,9 +297,9 @@ export function applyIntent(ctx: Context, deps: IntentHostDeps = {}): IntentHost
              * 「意图记录」会莫名其妙变空，而文件里明明一条不少。`tasks` /
              * `activeTaskId` 仍来自工作集 —— 那是**活的血缘**，不是历史。
              */
-            const durable = await readIntentRecords(base, sessionKey, 50)
+            const durable = await readIntentRecords(base, sessionKey, recentLimit)
             const store = (view.data as { store?: { recent?: unknown[] } }).store
-            if (store) store.recent = durable.slice(-10).reverse()
+            if (store) store.recent = durable.slice(-recentLimit).reverse()
           }
           send(res, 200, view)
         },

package/src/intent/scope.ts

@@ -0,0 +1,125 @@
+/**
+ * 会话意图的作用域门控。
+ *
+ * 意图记录只服务于 DSH 标准模式，不是宿主里每个 Agent 都要承担的全局开销。
+ * 这里的判断只回答「这一轮是否值得进入数据意图链路」，不负责替模型判断具体的
+ * act / category。具体分类仍由 `intent_record` 的固定提示词完成。
+ */
+
+import { isIntentEnabledPreset } from '../preset-ids.js'
+
+/** 数据域分类。其它分类（闲聊、运维、Agent 工程等）不应写入数据意图审计。 */
+const DATA_CATEGORY_IDS = new Set([
+  'data_analysis',
+  'metadata_exploration',
+  'data_validation',
+  'knowledge_consultation',
+  'knowledge_building',
+  'document_research',
+  'artifact_delivery',
+])
+
+/** 模型明确标成普通对话 / Agent 运维时，不因原文碰到一个数据词就强行落记录。 */
+const NON_DATA_CATEGORY_IDS = new Set([
+  'conversation',
+  'agent_engineering',
+  'tooling_operations',
+  'personal_assistant',
+  'message_collaboration',
+])
+
+const NON_DATA_ACT_IDS = new Set(['greet', 'chat'])
+
+/** 直接表示数据 / 知识链路的 predicate。 */
+const DATA_PREDICATE_IDS = new Set([
+  'query_babel_data',
+  'query_knowledge',
+  'query_source_truth',
+  'query_metadata',
+  'query_graph',
+  'add_source',
+  'propose_wiki_cards',
+  'rebuild_knowledge',
+])
+
+/** 发生实际数据工作的工具。意图工具本身不在这里，避免自调用激活门控。 */
+const DATA_TOOL_NAMES = new Set([
+  'recall_knowledge',
+  'get_knowledge_events',
+  'get_knowledge_cases',
+  'run_knowledge_pipeline',
+  'get_knowledge_pipeline',
+  'query_knowledge_graph',
+  'query_source_truth',
+  'list_knowledge_bases',
+  'check_knowledge_embeddings',
+  'add_source',
+  'import_sources',
+  'propose_wiki_cards',
+  'annotate_wiki_card',
+  'review_wiki_card',
+  'set_knowledge_status',
+  'record_feedback',
+  'rebuild_knowledge',
+  'convert_source',
+  'convert_ingest',
+  'convert_task',
+])
+
+/**
+ * 这些词只做「是否进入数据域」的廉价门控，不做分类，也不替代模型判断。
+ * 列表刻意覆盖知识库、表格、查询、编译与召回；普通聊天不会因为一个泛化动词
+ * （例如「帮我写」）被误判成数据请求。
+ */
+const DATA_DOMAIN_RE = /数据|指标|字段|数据库|知识库|知识卡|知识矩阵|召回|检索|向量|坐标|实体|source.?raw|wiki.?card|文档|资料|表格?|SQL|Excel|GMV|销售额|订单|报表|口径|编译|重建|导入|抽取|卡片/i
+const DATA_ACTION_RE = /查|查询|统计|分析|计算|核对|校验|对比|召回|检索|读取|查看|导入|编译|重建|抽取|整理|生成|导出|写入|构建|解释|定义|口径/i
+const DATA_QUESTION_RE = /(?:数据|指标|字段|数据库|知识库|文档|表格?|报表|口径)(?:里|中|有|是|怎么|如何|哪个|哪些|什么|相关)/i
+
+/** 读取 DSH Session 的 preset 标识；结构读取以兼容测试替身和旧宿主。 */
+export function sessionPresetOf(session: unknown): string | undefined {
+  const value = session as { header?: { agentPreset?: unknown } } | undefined
+  return typeof value?.header?.agentPreset === 'string' ? value.header.agentPreset : undefined
+}
+
+/** 标准模式参与数据 / 知识意图留痕。 */
+export function isIntentAgentSession(session: unknown): boolean {
+  return isIntentEnabledPreset(sessionPresetOf(session))
+}
+
+/** 判断一个工具是否代表真实的数据 / 知识工作。 */
+export function isDataToolName(name: unknown): boolean {
+  if (typeof name !== 'string') return false
+  return DATA_TOOL_NAMES.has(name) || /^workbook_/.test(name)
+}
+
+/**
+ * 判断用户原文是否明显进入数据域。
+ *
+ * 这是 gate，不是 NLU：宁可让模型通过 `category` 或实际数据工具调用补充一次，
+ * 也不在这里生成意图分类，避免第二套分类逻辑与 `intent_record` 漂移。
+ */
+export function isDataIntentCandidate(value: unknown): boolean {
+  if (typeof value !== 'string') return false
+  const text = value.trim()
+  if (!text) return false
+  return (DATA_DOMAIN_RE.test(text) && DATA_ACTION_RE.test(text)) || DATA_QUESTION_RE.test(text)
+}
+
+/** 模型已经给出数据分类 / predicate 时，允许这一轮进入审计。 */
+export function isDataIntentPayload(args: Record<string, unknown>): boolean {
+  const category = typeof args.category === 'string' ? args.category.trim() : ''
+  const predicate = typeof args.predicate === 'string' ? args.predicate.trim() : ''
+  const domain = typeof args.domain === 'string' ? args.domain.trim().toLowerCase() : ''
+  return DATA_CATEGORY_IDS.has(category)
+    || DATA_PREDICATE_IDS.has(predicate)
+    || domain === 'data'
+    || domain === 'knowledge'
+    || isDataIntentCandidate(args.user_input)
+}
+
+/** 模型已经明确表示这是普通对话时，覆盖廉价的文本 gate。 */
+export function isExplicitNonDataIntentPayload(args: Record<string, unknown>): boolean {
+  const category = typeof args.category === 'string' ? args.category.trim() : ''
+  const act = typeof args.act === 'string' ? args.act.trim() : ''
+  return NON_DATA_CATEGORY_IDS.has(category) || NON_DATA_ACT_IDS.has(act)
+}

package/src/intent/tools.ts

@@ -3,35 +3,22 @@
  *
  * ## 为什么要单独一个文件
  *
- * 0029 之前这两个工具由宿主平面的 `applyIntent` 直接 `ctx.tools.register(...)`，
- * 于是它们是**全局工具**：任何 agent、任何 preset 的会话都会在提示词里看到
- * `intent_record`，也都能调它。而意图记录是这个方案自己的东西 —— 只有跑
- * TitaAgent 那套组合的会话才该有它，别的 agent 场景（别的 preset、临时会话）
- * 不该被塞一个用不上的工具。
- *
- * DSH 里「只有某个 preset 能用」的**唯一**支持形态是**注册作用域**：注册在哪个
- * 作用域，就只在哪个作用域可见（`dsh-tools` 的 `register` 是 scope-layered）。
- * `ctx.tools.restrict()` 只能做减法（从继承来的工具里减掉），宿主平面调它还会
- * 直接抛 —— 没有「只给某一个作用域」的正向开关。所以正确的做法是把注册搬到
- * **agent 平面**：一个只被自定义 preset 的 `agent.cordis.yml` 挂载的行
- * （`./preset-tools.ts`），它注册的工具只覆盖那个 preset 的会话。
- *
- * 注册逻辑本身与平面无关，所以它留在这里：宿主平面负责「引擎怎么跑」（轮次记账、
- * 轮次记账、HTTP 只读面），agent 平面负责「模型看到什么工具」。两边共用这一份，
- * 不各写一套工具定义。
+ * 工具由 Host 层注册，因此可以被标准模式调用。由于 Host 工具也可能出现在其他 preset
+ * 中，执行端会检查会话，只接受 `standard`。
  *
  * @module
  */
 
 import { defineTool, type ToolRunContext } from '@deepseek-ai/dsh-tools'
-import type { LineageContext } from 'dsh-data-contracts/refs'
+import { envelopeFailure } from '#contracts'
+import type { LineageContext } from '#contracts'
+import { isIntentAgentSession } from './scope.js'
 
 /**
  * 注册这两个工具需要引擎提供的能力。
  *
  * 刻意是**结构化的最小面**而不是 `IntentEngine` 本身：宿主平面通过
- * `INTENT_SERVICE` 提供它，agent 平面的行只按这个形状取用。这样 preset 行不必
- * import 引擎、也不必知道引擎住在哪个模块里。
+ * `INTENT_SERVICE` 提供它，注册器只按这个形状使用引擎，不依赖其具体实现位置。
  */
 export interface IntentToolHost {
   /** `intent_record` 的**工具描述就是路由提示词**（0023）。 */
@@ -50,7 +37,6 @@ const INTENT_RECORD_PARAMS: Record<string, unknown> = {
   confidence: { type: 'number', description: '0-1，用于标注 lowConfidence' },
   refs: { type: 'array', description: '引用对象，例如 { id, kind, label }' },
   relation: { type: 'string', enum: ['new_task', 'subtask_of'], description: '本轮是新任务还是已有任务的子任务' },
-  session_key: { type: 'string' },
   turn_id: { type: 'string', description: '当前对话轮次 id；不传则由 Host 生成' },
   task_id: { type: 'string', description: 'relation=subtask_of 时指向的已有业务任务 id；新任务不传' },
   subtask_id: { type: 'string', description: '已有子任务 id；新子任务不传，由 Host 生成' },
@@ -75,7 +61,8 @@ export function jsonTool(name: string, description: string, parameters: Record<s
 
 export function lineageOf(args: Record<string, unknown>, exec?: ToolRunContext): Partial<LineageContext> | undefined {
   const lineage: Partial<LineageContext> = {}
-  const sessionId = typeof args.session_key === 'string' && args.session_key.trim() ? args.session_key.trim() : exec?.agent?.session.header.id
+  // 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'],
@@ -85,9 +72,43 @@ export function lineageOf(args: Record<string, unknown>, exec?: ToolRunContext):
   return Object.keys(lineage).length > 0 ? lineage : undefined
 }
 
-export function sessionKeyOf(args: Record<string, unknown>, exec?: ToolRunContext): string {
-  const explicit = typeof args.session_key === 'string' ? args.session_key.trim() : ''
-  return explicit || exec?.agent?.session.header.id || 'default'
+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,
+  })
 }
 
 /**
@@ -99,11 +120,32 @@ export function sessionKeyOf(args: Record<string, unknown>, exec?: ToolRunContex
  * 返回 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) => host.record(args, exec)))
+  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 the active task ids for the current session.',
-    { session_key: { type: 'string' }, include_prompt: { type: 'boolean' } },
-    (args: { session_key?: string; include_prompt?: boolean }, exec) => host.view(sessionKeyOf(args, exec), args.include_prompt),
+    '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)()

package/src/intent/types.ts

@@ -1,5 +1,5 @@
-import type { ToolStatus } from 'dsh-data-contracts/envelope'
-import type { LineageContext } from 'dsh-data-contracts/refs'
+import type { ToolStatus } from '#contracts'
+import type { LineageContext } from '#contracts'
 
 export type { ToolStatus }
 
@@ -45,7 +45,7 @@ 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 turn-end backfill. */
+/** `model` is a model-authored record; `fallback` is the Host's data-turn backfill. */
 export type IntentSource = 'model' | 'fallback'
 
 export interface IntentSlotMap {
@@ -91,7 +91,7 @@ export interface IntentSettings {
    * 0023：路由提示词**没有开关**。它随 `intent_record` 的工具描述一起下发，
    * 分类规则必须始终在场——否则模型退化成每轮从零判断。
    */
-  /** Backfill one `unknown` record when a turn ends without a model record. */
+  /** Backfill one `unknown` record when an eligible data turn ends without a model record. */
   fallbackEnabled: boolean
 }
 
@@ -203,6 +203,9 @@ export interface IntentResultData {
   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 {
@@ -218,5 +221,9 @@ export interface IntentTurnState {
   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
 }