@prisflow/proactiveai-plugin-types 0.1.1 → 0.3.0

package/index.d.ts

@@ -71,7 +71,7 @@ export interface ContextCompactionConfig {
   summarySlot?: string
   /** 摘要头部标签文本（如 【剧情史】）。 */
   summaryLabel?: string
-  /** 触发压缩的 token 预算（缺省 60000）。 */
+  /** 触发压缩的 token 预算。已弃用——触发改为 provider 真实 usage > 窗口-输出上限，不再读取该字段。 */
   tokenBudget?: number
   /** 压缩后保留的最近消息估算 token 数（缺省 8000）。 */
   keepTokens?: number
@@ -97,10 +97,10 @@ export interface ContextDefinition {
   compaction?: ContextCompactionConfig
 }
 
-/** 工具调用上下文（调用方传入）。 */
+/** 工具调用上下文（调用方传入）。conversationId/contextId 恒有值（工具都在会话+上下文内执行）。 */
 export interface ToolCallMeta {
-  conversationId?: string
-  contextId?: string
+  conversationId: string
+  contextId: string
   /** 触发本次工具调用的 LLM 轮次 runId（日志链路树）。 */
   parentRunId?: string
 }
@@ -125,6 +125,10 @@ export interface SilentToolDef {
   run: (input: Record<string, unknown>, meta: ToolCallMeta) => ToolResult | Promise<ToolResult>
   silent: true
   transformPrompt?: undefined
+  /** 收轮引擎化：执行 + transformPrompt 完成后，引擎直接收轮（等同 host_yield），
+   * 不再以 instruction 回喂 LLM。剧情类工具专用——收轮由引擎保证，不依赖模型自觉。
+   * 需宿主 ≥ 0.6.3。 */
+  autoYield?: boolean
 }
 
 /** 非静默工具：执行后产生事件入总线，必须提供 transformPrompt。 */
@@ -135,16 +139,20 @@ export interface NonSilentToolDef {
   run: (input: Record<string, unknown>, meta: ToolCallMeta) => ToolResult | Promise<ToolResult>
   silent?: false
   transformPrompt: (result: ToolResult) => ToolPromptResult
+  /** 收轮引擎化：执行 + transformPrompt 完成后，引擎直接收轮（等同 host_yield），
+   * 不再以 instruction 回喂 LLM。剧情类工具专用——收轮由引擎保证，不依赖模型自觉。
+   * 需宿主 ≥ 0.6.3。 */
+  autoYield?: boolean
 }
 
 /** 工具定义 —— 注册时需满足对应的 silent/transformPrompt 约束。 */
 export type ToolDefinition = SilentToolDef | NonSilentToolDef
 
-/** LLM API 连接配置。 */
+/** LLM API 连接配置（与宿主对齐：baseURL 未配置为 null）。 */
 export interface LlmConfig {
   apiKey: string
   model: string
-  baseURL?: string
+  baseURL: string | null
 }
 
 /** LLM 消息（OpenAI Chat Completion 单条）。 */
@@ -198,6 +206,7 @@ export interface LlmNode {
   system: string
   input: (ctx: FlowCtx) => string
   schema?: Record<string, unknown>
+  /** 结果存入 ctx.data 的键（缺省为 system 前 16 字符，无稳定语义，建议显式指定）。 */
   assign?: string
   maxTries?: number
   maxTokens?: number
@@ -255,12 +264,17 @@ export interface PluginSetupAPI {
     /** 整体覆盖写入插件持久化数据。 */
     set(data: unknown): void
   }
-  /** 宿主通用记忆层（host_memory 表，按会话+上下文隔离）。 */
-  memory: {
-    set(slot: string, data: string, opts?: { conversationId?: string; contextId?: string }): void
-    get(slot: string, opts?: { conversationId?: string; contextId?: string }): string | null
-    search(query: string, opts?: { conversationId?: string; contextId?: string }): Array<{ slot: string; data: string }>
-    remove(slot: string, opts?: { conversationId?: string; contextId?: string }): boolean
+  /**
+   * 头部稳定层注入（三段式 system 稳定前缀）。
+   * 向当前会话+上下文的头部注入固定/慢变文本（如世界状态卡），
+   * 宿主组装 LLM 请求时自动读入稳定前缀（慢变 → 缓存恒命中）。
+   * 归属自动取自宿主执行上下文，插件无需传会话 ID。
+   */
+  prompts: {
+    /** 注入/更新头部稳定层文本（覆盖该会话+上下文的注入位）。 */
+    set(text: string): void
+    /** 移除已注入的文本。 */
+    remove(text: string): void
   }
   /** 宿主 LLM 能力：结构化生成（schema 校验失败自动重试）。 */
   llm: {
@@ -275,22 +289,10 @@ export interface PluginSetupAPI {
   flow: {
     /** 注册一张图（节点链）。 */
     register(def: FlowDefinition): boolean
-    /** 执行一张图，渲染经 push 通道推送并落库。 */
+    /** 执行一张图，渲染经 push 通道推送并落库。会话归属自动取自执行上下文。 */
     run(
       name: string,
-      input: unknown,
-      opts?: { conversationId?: string; contextId?: string }
+      input: unknown
     ): Promise<FlowResult>
   }
-  /** 三段式骨架提示词注入（优化缓存命中）。 */
-  prompts: {
-    /** inject(where, text)：'prefix' 稳定前缀（system 内）｜'suffix' 尾部指令前。 */
-    inject(where: 'prefix' | 'suffix', text: string, opts?: { contextId?: string }): void
-    /** 移除注入。 */
-    remove(where: 'prefix' | 'suffix', text: string, opts?: { contextId?: string }): void
-  }
-  /** 压缩层配置（覆盖 ContextDefinition.compaction 或全局默认）。 */
-  compaction: {
-    configure(cfg: Partial<ContextCompactionConfig>, opts?: { contextId?: string }): void
-  }
 }

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@prisflow/proactiveai-plugin-types",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "ProactiveAI 宿主插件 API 的类型契约（纯类型，无运行时代码）。插件开发者通过该包获得类型提示与编译检查。",
   "license": "MIT",
   "private": false,
   "types": "index.d.ts",
-  "files": ["index.d.ts"],
+  "files": [
+    "index.d.ts"
+  ],
   "scripts": {
     "check": "tsc --noEmit"
   },