@prisflow/proactiveai-plugin-types 0.1.0 → 0.2.0

package/index.d.ts

@@ -1,8 +1,12 @@
 /**
  * @prisflow/proactiveai-plugin-types
  *
- * ProactiveAI 宿主插件 API 的类型契约（自包含，可独立发布 npm）。
- * 插件开发者安装本包后获得 setup(api) 的全部类型提示与编译检查。
+ * ProactiveAI 宿主插件 API 的类型契约。
+ * 本文件为自包含声明（不 import 宿主相对路径），可独立发布 npm。
+ *
+ * 发布：push 到 main 且 plugin-types/ 有变更时，
+ * 由 .github/workflows/publish-plugin-types.yml 触发；
+ * 仓库已在 npmjs 侧配置 trusted publishing（OIDC 自动认证，无需 NPM_TOKEN）。
  *
  * 使用：
  *   npm i -D @prisflow/proactiveai-plugin-types
@@ -67,7 +71,7 @@ export interface ContextCompactionConfig {
   summarySlot?: string
   /** 摘要头部标签文本（如 【剧情史】）。 */
   summaryLabel?: string
-  /** 触发压缩的 token 预算（缺省 60000）。 */
+  /** 触发压缩的 token 预算。已弃用——触发改为 provider 真实 usage > 窗口-输出上限，不再读取该字段。 */
   tokenBudget?: number
   /** 压缩后保留的最近消息估算 token 数（缺省 8000）。 */
   keepTokens?: number
@@ -93,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
 }
@@ -136,11 +140,11 @@ export interface NonSilentToolDef {
 /** 工具定义 —— 注册时需满足对应的 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 单条）。 */
@@ -194,6 +198,7 @@ export interface LlmNode {
   system: string
   input: (ctx: FlowCtx) => string
   schema?: Record<string, unknown>
+  /** 结果存入 ctx.data 的键（缺省为 system 前 16 字符，无稳定语义，建议显式指定）。 */
   assign?: string
   maxTries?: number
   maxTokens?: number
@@ -251,12 +256,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: {
@@ -271,22 +281,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,6 +1,6 @@
-{
+{
   "name": "@prisflow/proactiveai-plugin-types",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "ProactiveAI 宿主插件 API 的类型契约（纯类型，无运行时代码）。插件开发者通过该包获得类型提示与编译检查。",
   "license": "MIT",
   "private": false,