@kernel4632/agent-core 0.35.1 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1255,8 +1255,13 @@ History.user({ content: [{ type: 'text', text: '这是什么' }, { type: 'image'
1255
1255
  History.assistant({ content: '你好', toolCalls: [{ id: 'call-1', name: 'add', arguments: { a: 1, b: 2 } }] })
1256
1256
  History.tool({ toolCallId: 'call-1', toolName: 'add', content: '3' })
1257
1257
  History.compact({ content: '之前的对话总结...' })
1258
+
1259
+ // 只给宿主看的失败记录:存进 history、刷新后还能渲染,但模型永远收不到,也不占上下文预算。
1260
+ History.error({ content: '请求失败:500', request: { model: 'claude', ms: 1234, error: 'boom' } })
1258
1261
  ```
1259
1262
 
1263
+ **失败记录(`role:'error'`)**:它不参与回合、不参与工具配对、不参与压缩,`Context.build()` 会整条丢掉;`render()` 仍然把正文渲染出来,`request` 原样保存在这条消息上,宿主可以放自己的审计信息(模型、耗时、错误原因)。只有 `user` / `assistant` / `tool` 会发给模型——history 里出现别的 role,会跳过并 `console.warn` 一次(`error` 除外,那是预期用法)。
1264
+
1260
1265
  **读历史**——渲染给用户看、数聊了几轮,这两件事的知识本来就在核心里,不用你照着内部结构重写:
1261
1266
 
1262
1267
  ```js
@@ -1392,7 +1397,7 @@ const agent = Agent.create({ config: { /* ... */ }, tools })
1392
1397
  | `Agent.version` | 包版本,排查问题时报得出来 |
1393
1398
  | `Agent.create(...)` | 创建 Agent 实例 |
1394
1399
  | `Agent.tool` | `.from()` / `.scan()` / `.adopt()` / `.execute()` / `.merge()` / `.pick()` / `.omit()` |
1395
- | `Agent.history` | `.user()` / `.assistant()` / `.tool()` / `.compact()` 造消息块;`.turns()` / `.render()` 读历史 |
1400
+ | `Agent.history` | `.user()` / `.assistant()` / `.tool()` / `.compact()` / `.error()` 造消息块;`.turns()` / `.render()` 读历史 |
1396
1401
  | `Agent.context` | `.build()` |
1397
1402
  | `Agent.compact` | `.run()` |
1398
1403
  | `Agent.llm` | `.chat()` |
@@ -176,12 +176,14 @@ export interface ToolModule {
176
176
  }
177
177
 
178
178
  // --- 历史块 ---
179
- export type Role = 'user' | 'assistant' | 'tool'
179
+ // 前三种是模型能读的对话;'error' 是宿主自己的失败记录(History.error),模型永远看不到。
180
+ export type Role = 'user' | 'assistant' | 'tool' | 'error'
180
181
  export interface Message {
181
182
  id: string
182
183
  role: Role
183
184
  content: string | any[] | null
184
185
  compact?: boolean
186
+ request?: any // 只有 role:'error' 会带:宿主自己的审计信息(model / 耗时 / 错误原因等),原样保存。
185
187
  }
186
188
 
187
189
  export interface HistoryModule {
@@ -189,6 +191,8 @@ export interface HistoryModule {
189
191
  assistant: (options: { id?: string; content?: string | any[] | null; toolCalls?: Array<{ id: string; name: string; arguments?: any; input?: any }> }) => Message
190
192
  tool: (options: { id?: string; toolCallId: string; toolName: string; content: any }) => Message
191
193
  compact: (options: { id?: string; content: string }) => Message
194
+ // 只给宿主看的失败记录:存进 history、能渲染、刷新后还在,但不发给模型、不占上下文预算。
195
+ error: (options: { id?: string; content: string; request?: any }) => Message
192
196
  stored: (message: any) => Message
193
197
  turns: (history: Message[]) => Message[][]
194
198
  render: (history: Message[]) => string