@njuptlzf/agent-chat-protocol 0.2.0 → 0.4.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/dist/index.d.ts +210 -1
- package/dist/index.js +3 -1
- package/package.json +42 -42
- package/src/index.ts +1032 -834
package/dist/index.d.ts
CHANGED
|
@@ -170,6 +170,56 @@ export type ChatEvent = {
|
|
|
170
170
|
message: string;
|
|
171
171
|
level: "info" | "warning" | "error";
|
|
172
172
|
}
|
|
173
|
+
/**
|
|
174
|
+
* 编排层成员维度的事件(W4 / R-010)。**只在多 phase 的 Run 下发**;
|
|
175
|
+
* 单 phase(档 1)一个都不发,字节流与接入编排层之前完全一致(I8)。
|
|
176
|
+
*
|
|
177
|
+
* 为什么不给既有事件加 `memberId` 可选字段:那会让**每一次**单 phase 下发都
|
|
178
|
+
* 多一个 `memberId: undefined` 被 `JSON.stringify` 丢掉、语义上却存在,
|
|
179
|
+
* 前端还得判「有 memberId 才是成员流」。独立事件类型把两档彻底分开,
|
|
180
|
+
* 旧前端不认识就跳过(降级契约),新前端按需接管。
|
|
181
|
+
*
|
|
182
|
+
* `state` 用内联字面量而不是导出新类型:公开导出符号清单(54 项)不动(I8)。
|
|
183
|
+
*/
|
|
184
|
+
| {
|
|
185
|
+
type: "member_started";
|
|
186
|
+
runId: string;
|
|
187
|
+
phaseId: string;
|
|
188
|
+
/** 成员 id:产品 manifest 里声明的人格 id,与 `JobSpec.persona` 同源。 */
|
|
189
|
+
memberId: string;
|
|
190
|
+
/** 交给这个成员的任务文本(前端可据此显示「在干什么」)。 */
|
|
191
|
+
task: string;
|
|
192
|
+
}
|
|
193
|
+
/** 成员的流式输出增量。前端按 `memberId` 归到各自的卡片。 */
|
|
194
|
+
| {
|
|
195
|
+
type: "member_delta";
|
|
196
|
+
runId: string;
|
|
197
|
+
phaseId: string;
|
|
198
|
+
memberId: string;
|
|
199
|
+
delta: string;
|
|
200
|
+
}
|
|
201
|
+
/** 成员收口:状态 + 它自己消耗的 usage(Run 级总量由 `run_done` 给)。 */
|
|
202
|
+
| {
|
|
203
|
+
type: "member_done";
|
|
204
|
+
runId: string;
|
|
205
|
+
phaseId: string;
|
|
206
|
+
memberId: string;
|
|
207
|
+
state: "completed" | "failed" | "stopped" | "blocked";
|
|
208
|
+
usage: TokenUsage;
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* 整个 Run 的汇总(多 phase 才有):全部成员加总后的 usage、最终输出、耗时。
|
|
212
|
+
* 与 `done` 的分工——`done` 是**流结束**的传输语义(恒发,单 phase 的字节流靠它),
|
|
213
|
+
* `run_done` 是**编排结果**的业务语义(多 phase 才有)。两者不互替。
|
|
214
|
+
*/
|
|
215
|
+
| {
|
|
216
|
+
type: "run_done";
|
|
217
|
+
runId: string;
|
|
218
|
+
state: "completed" | "failed" | "stopped" | "blocked";
|
|
219
|
+
usage: TokenUsage;
|
|
220
|
+
output: string;
|
|
221
|
+
durationMs: number;
|
|
222
|
+
}
|
|
173
223
|
/** The run is fully finished (agent will not continue on its own). Always the last event on success. */
|
|
174
224
|
| {
|
|
175
225
|
type: "done";
|
|
@@ -212,6 +262,74 @@ export interface ChatAttachment {
|
|
|
212
262
|
* core 只回答「这个 id 产品声明了没有」——加人格、换产品都是改 manifest。
|
|
213
263
|
*/
|
|
214
264
|
export type Persona = string;
|
|
265
|
+
/**
|
|
266
|
+
* 产品声明的一个**多 agent 流程**(M-14 / R-010 W4)。
|
|
267
|
+
*
|
|
268
|
+
* 这是「一次请求要跑哪几段」的声明:平台把它翻成 `RunSpec`,交给编排层执行。
|
|
269
|
+
* **产品不会看到 `RunSpec`**——那是平台内部类型;产品只填这份声明。
|
|
270
|
+
*
|
|
271
|
+
* ```
|
|
272
|
+
* flows:
|
|
273
|
+
* review:
|
|
274
|
+
* label: 双人评审
|
|
275
|
+
* phases:
|
|
276
|
+
* - { id: draft, member: writer, task: "写一段" }
|
|
277
|
+
* - { id: reviewA, member: reviewer-a, task: "审 {steps.draft.output}", dependsOn: [draft] }
|
|
278
|
+
* - { id: reviewB, member: reviewer-b, task: "审 {steps.draft.output}", dependsOn: [draft] }
|
|
279
|
+
* - { id: merge, kind: reduce, member: writer, from: [reviewA, reviewB],
|
|
280
|
+
* task: "汇总:{previous.output}", final: true }
|
|
281
|
+
* concurrency: 2
|
|
282
|
+
* ```
|
|
283
|
+
*
|
|
284
|
+
* `task` 里可用两种占位符(由编排引擎替换):
|
|
285
|
+
* - `{steps.<phaseId>.output}` —— 引用某个已完成 phase 的产物;
|
|
286
|
+
* - `{previous.output}` —— 仅 `kind: reduce` 用,指 `from` 聚合后的输入。
|
|
287
|
+
*/
|
|
288
|
+
export interface ProductFlow {
|
|
289
|
+
/** 面向用户的名称(前端选流程时显示)。 */
|
|
290
|
+
label?: string;
|
|
291
|
+
/** 说明文案。 */
|
|
292
|
+
description?: string;
|
|
293
|
+
/** 这些节点连成 DAG。顺序不重要,`dependsOn` 才是关系。 */
|
|
294
|
+
phases: ProductFlowPhase[];
|
|
295
|
+
/**
|
|
296
|
+
* 同时在跑的成员上限。**缺省 = 引擎默认**(不在这里写死数字)。
|
|
297
|
+
* 见 `RunSpec.concurrency`:它与 pi 自己的 worker 队列必须同口径(待办 T1)。
|
|
298
|
+
*/
|
|
299
|
+
concurrency?: number;
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* 流程里的一个节点。
|
|
303
|
+
*
|
|
304
|
+
* `kind` 三选一(缺省 `agent`):
|
|
305
|
+
* - `agent`:一个成员跑一件事(最常见);
|
|
306
|
+
* - `parallel`:`members` 各跑一件事,全部完成后节点收口;
|
|
307
|
+
* - `reduce`:把 `from` 的产物聚合后交给 `member` 汇总。
|
|
308
|
+
*
|
|
309
|
+
* **没有 `gate`**:gate 要的是「这个节点算通过吗」的判定规则,那是产品业务语义
|
|
310
|
+
* (及格线、必含项),平台不猜。真需要时再加,现在加就是编一个没人验证的规则形状。
|
|
311
|
+
*/
|
|
312
|
+
export interface ProductFlowPhase {
|
|
313
|
+
/** 节点 id,flow 内唯一。 */
|
|
314
|
+
id: string;
|
|
315
|
+
/** 缺省 `agent`。 */
|
|
316
|
+
kind?: "agent" | "parallel" | "reduce";
|
|
317
|
+
/**
|
|
318
|
+
* 执行这个节点的**成员 id**:必须是产品已声明的人格
|
|
319
|
+
* (`agent.defaultPersona` ∪ `agent.personas.*`)。`kind: parallel` 时用 `members`。
|
|
320
|
+
*/
|
|
321
|
+
member?: Persona;
|
|
322
|
+
/** `kind: parallel` 的分支成员列表(各自的 persona)。 */
|
|
323
|
+
members?: Persona[];
|
|
324
|
+
/** 交给成员的指令。支持 `{steps.<id>.output}` / `{previous.output}` 占位符。 */
|
|
325
|
+
task?: string;
|
|
326
|
+
/** 依赖的节点 id。空/缺省 = 入口。 */
|
|
327
|
+
dependsOn?: string[];
|
|
328
|
+
/** `kind: reduce` 的输入来源(节点 id 列表)。 */
|
|
329
|
+
from?: string[];
|
|
330
|
+
/** 是否作为整个 Run 的最终输出来源。 */
|
|
331
|
+
final?: boolean;
|
|
332
|
+
}
|
|
215
333
|
/**
|
|
216
334
|
* 产品**没有**声明 `agent.defaultPersona` 时用的兜底 id。
|
|
217
335
|
* core 只发明这一个 id(其余全部来自产品 manifest);它同时是配额/流水里
|
|
@@ -239,6 +357,31 @@ export interface ChatRequest {
|
|
|
239
357
|
* `agent.personas.*`); core knows none of them by name.
|
|
240
358
|
*/
|
|
241
359
|
persona?: Persona;
|
|
360
|
+
/**
|
|
361
|
+
* Which multi-agent flow (`agent.flows.<id>`) this request runs.
|
|
362
|
+
*
|
|
363
|
+
* **Omit for a normal single-agent turn** — that path is byte-for-byte what it
|
|
364
|
+
* was before flows existed (`wire-baseline.test.ts` pins it). With `flow` set,
|
|
365
|
+
* the request becomes a multi-phase Run: the declared DAG runs member by member
|
|
366
|
+
* and the client receives `member_*` / `run_done` events on top of the usual
|
|
367
|
+
* stream, so one UI can render "who is working on what".
|
|
368
|
+
*
|
|
369
|
+
* Legal ids come from the product manifest; an unknown id is a 400. The flow is
|
|
370
|
+
* **not** bound to the session (unlike `persona`): running a different flow in
|
|
371
|
+
* the same conversation is a legitimate action (e.g. "re-review this with the
|
|
372
|
+
* other team"), and each request carries its own DAG.
|
|
373
|
+
*/
|
|
374
|
+
flow?: string;
|
|
375
|
+
/**
|
|
376
|
+
* Resume a previously interrupted multi-phase flow run by its run id.
|
|
377
|
+
*
|
|
378
|
+
* The server only accepts a run id belonging to the authenticated user's
|
|
379
|
+
* current session (`<sessionId>:<timestamp>`); a foreign id is a 400. Only
|
|
380
|
+
* meaningful together with `flow` — a plain single-agent turn has no
|
|
381
|
+
* phase checkpoints to resume. Completed phases are replayed from the stored
|
|
382
|
+
* checkpoint without re-spending tokens (I7).
|
|
383
|
+
*/
|
|
384
|
+
resumeRunId?: string;
|
|
242
385
|
/**
|
|
243
386
|
* Which scope (qualification) this conversation belongs to. The scope is bound
|
|
244
387
|
* to the session when it is created and is immutable afterwards: resuming an
|
|
@@ -513,17 +656,42 @@ export interface PersonaUi {
|
|
|
513
656
|
policyNote?: string;
|
|
514
657
|
/** 空态快捷问法。 */
|
|
515
658
|
suggestions?: string[];
|
|
659
|
+
/**
|
|
660
|
+
* 轮次结束后「下一步建议」的生效模式,覆盖全局 `branding.ui.followUp.mode`。
|
|
661
|
+
* 注意:全局 `off` 是硬地板,人格不能把全局关闭重新打开。
|
|
662
|
+
*/
|
|
663
|
+
followUpMode?: "off" | "static" | "llm";
|
|
516
664
|
}
|
|
517
665
|
/**
|
|
518
666
|
* `PersonaUi` 的展示字段(顺序即页面顺序)。manifest 加载与运行时配置校验共用这一份,
|
|
519
667
|
* 避免两处各写一份清单后漂移——漂移的表现是「页面能存、manifest 读不懂」。
|
|
668
|
+
* 注意:加字段要同步 3 处——本清单 + `loadPersonaUi` 的循环外专用块 + `parseUi`
|
|
669
|
+
* 的专用分支与其泛型 cast,见人格配置面设计稿 §17。
|
|
520
670
|
*/
|
|
521
|
-
export declare const PERSONA_UI_FIELDS: readonly ["label", "icon", "tag", "hint", "welcome", "policyNote", "suggestions"];
|
|
671
|
+
export declare const PERSONA_UI_FIELDS: readonly ["label", "icon", "tag", "hint", "welcome", "policyNote", "suggestions", "followUpMode"];
|
|
672
|
+
/** 一轮对话结束后展示的「下一步建议」配置。 */
|
|
673
|
+
interface BrandingFollowUp {
|
|
674
|
+
mode?: "off" | "static" | "llm";
|
|
675
|
+
/** 建议条数,默认 3。 */
|
|
676
|
+
count?: number;
|
|
677
|
+
/** static 模式的内容,也是生成失败时的回落。 */
|
|
678
|
+
static?: string[];
|
|
679
|
+
/** 覆盖内置的生成指令。 */
|
|
680
|
+
systemPrompt?: string;
|
|
681
|
+
maxMessages?: number;
|
|
682
|
+
timeoutMs?: number;
|
|
683
|
+
}
|
|
684
|
+
/** 视觉件与交互件的配置值。键是平台定义的语义槽名,不是组件名。 */
|
|
685
|
+
interface BrandingUi {
|
|
686
|
+
icons?: Record<string, string>;
|
|
687
|
+
followUp?: BrandingFollowUp;
|
|
688
|
+
}
|
|
522
689
|
/** What the UI needs to re-skin itself for a product. Served by GET /api/branding. */
|
|
523
690
|
export interface Branding {
|
|
524
691
|
title: string;
|
|
525
692
|
logo?: string;
|
|
526
693
|
welcome?: string;
|
|
694
|
+
/** 空态快捷问法;与 `ui.followUp`(轮次结束后的下一步)语义不同。 */
|
|
527
695
|
suggestions?: string[];
|
|
528
696
|
/**
|
|
529
697
|
* CSS custom properties injected on the app root, overriding the design
|
|
@@ -532,6 +700,8 @@ export interface Branding {
|
|
|
532
700
|
* from pre-token bundles is still honoured as a legacy alias.
|
|
533
701
|
*/
|
|
534
702
|
theme?: Record<string, string>;
|
|
703
|
+
/** 图标值 + 下一步建议配置;改这里不用改代码、不用重建前端。 */
|
|
704
|
+
ui?: BrandingUi;
|
|
535
705
|
}
|
|
536
706
|
/**
|
|
537
707
|
* A selectable quality tier as shown to the user. Deliberately carries no model
|
|
@@ -573,6 +743,17 @@ export interface BrandingResponse extends Branding {
|
|
|
573
743
|
* 只是一个 id,不带任何能力信息,所以可以公开。
|
|
574
744
|
*/
|
|
575
745
|
defaultPersona?: string;
|
|
746
|
+
/**
|
|
747
|
+
* Multi-agent flows this product declares (`agent.flows.<id>`), display
|
|
748
|
+
* fields only. A client can render a flow picker from this list; it never
|
|
749
|
+
* sees phase internals (member tasks / DAG) — those stay server-side. Absent
|
|
750
|
+
* when the product declares no flows, so existing clients are unaffected.
|
|
751
|
+
*/
|
|
752
|
+
flows?: Array<{
|
|
753
|
+
id: string;
|
|
754
|
+
label?: string;
|
|
755
|
+
description?: string;
|
|
756
|
+
}>;
|
|
576
757
|
}
|
|
577
758
|
/**
|
|
578
759
|
* 管理端模型配置。物理模型名只到这一层:
|
|
@@ -835,6 +1016,24 @@ export interface ProductManifest {
|
|
|
835
1016
|
act: string;
|
|
836
1017
|
}>;
|
|
837
1018
|
};
|
|
1019
|
+
/**
|
|
1020
|
+
* **多 agent 流程**(M-14 / R-010 W4):产品声明「有哪些流程、谁是成员、
|
|
1021
|
+
* 谁依赖谁、汇总成什么」;平台给的是机制(DAG 调度、并发闸门、账本归集、
|
|
1022
|
+
* 事件协议)。
|
|
1023
|
+
*
|
|
1024
|
+
* 与 `personas` 完全同构的分层:
|
|
1025
|
+
* - 平台不认识任何具体流程,只认 id 与结构;
|
|
1026
|
+
* - **成员必须是已声明的人格**(`defaultPersona` ∪ `personas.*`)——
|
|
1027
|
+
* 流程不能凭空造出一个没有 prompt / 没有工具白名单的 agent;
|
|
1028
|
+
* - 请求侧只传 `flow: "<id>"`,不带就还是今天那个单 agent 对话。
|
|
1029
|
+
*
|
|
1030
|
+
* 声明即启动期校验(fail-closed):phase id 重复、`dependsOn` 悬空、环、
|
|
1031
|
+
* 成员未声明、`from` 指向不存在的 phase——全部启动失败,不进运行期。
|
|
1032
|
+
* 这与 `personas` 里写坏 prompt 路径就起不来的口径一致。
|
|
1033
|
+
*
|
|
1034
|
+
* **不声明 = 没有多 agent 能力**,产品完全不受影响。
|
|
1035
|
+
*/
|
|
1036
|
+
flows?: Record<string, ProductFlow>;
|
|
838
1037
|
};
|
|
839
1038
|
tools?: {
|
|
840
1039
|
/** Module whose default export is `(ctx) => ToolDefinition[]`. */
|
|
@@ -858,6 +1057,15 @@ export interface ProductManifest {
|
|
|
858
1057
|
routes?: string;
|
|
859
1058
|
assembly?: string;
|
|
860
1059
|
};
|
|
1060
|
+
/**
|
|
1061
|
+
* 准出声明:本产品实际使用的平台能力 ID 列表(机器可读声明面,唯一权威)。
|
|
1062
|
+
* **运行时 no-op**——loadProduct 不校验、内核行为完全不受影响;合法性、
|
|
1063
|
+
* 与 manifest/代码痕迹的双向对账、按声明跑测试门禁,全部由
|
|
1064
|
+
* `agentchat-integrate check` 执行(注册表见平台仓 docs/specs/能力注册表.md)。
|
|
1065
|
+
* 恒开能力(chat / auth-quota / branding / audit / admin-plane)不写在这里——
|
|
1066
|
+
* 写了反而会被 check 判 FAIL。空列表合法:表示除恒开面外什么增量能力都没用。
|
|
1067
|
+
*/
|
|
1068
|
+
capabilities?: string[];
|
|
861
1069
|
/**
|
|
862
1070
|
* Usage-based billing in integer cents (-8). When present (and the server
|
|
863
1071
|
* wires a BillingStore), a chat run needs a positive balance up front and
|
|
@@ -888,3 +1096,4 @@ export interface ProductManifest {
|
|
|
888
1096
|
}>;
|
|
889
1097
|
};
|
|
890
1098
|
}
|
|
1099
|
+
export {};
|
package/dist/index.js
CHANGED
|
@@ -15,5 +15,7 @@ export const DEFAULT_PERSONA_ID = "default";
|
|
|
15
15
|
/**
|
|
16
16
|
* `PersonaUi` 的展示字段(顺序即页面顺序)。manifest 加载与运行时配置校验共用这一份,
|
|
17
17
|
* 避免两处各写一份清单后漂移——漂移的表现是「页面能存、manifest 读不懂」。
|
|
18
|
+
* 注意:加字段要同步 3 处——本清单 + `loadPersonaUi` 的循环外专用块 + `parseUi`
|
|
19
|
+
* 的专用分支与其泛型 cast,见人格配置面设计稿 §17。
|
|
18
20
|
*/
|
|
19
|
-
export const PERSONA_UI_FIELDS = ["label", "icon", "tag", "hint", "welcome", "policyNote", "suggestions"];
|
|
21
|
+
export const PERSONA_UI_FIELDS = ["label", "icon", "tag", "hint", "welcome", "policyNote", "suggestions", "followUpMode"];
|
package/package.json
CHANGED
|
@@ -1,42 +1,42 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@njuptlzf/agent-chat-protocol",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Wire protocol between the agentChat server and any chat UI: event, request/response and config types. Shapes only — no business semantics.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"license": "Apache-2.0",
|
|
7
|
-
"main": "./dist/index.js",
|
|
8
|
-
"types": "./dist/index.d.ts",
|
|
9
|
-
"exports": {
|
|
10
|
-
".": {
|
|
11
|
-
"agent-chat-source": "./src/index.ts",
|
|
12
|
-
"types": "./dist/index.d.ts",
|
|
13
|
-
"default": "./dist/index.js"
|
|
14
|
-
},
|
|
15
|
-
"./package.json": "./package.json"
|
|
16
|
-
},
|
|
17
|
-
"files": [
|
|
18
|
-
"dist",
|
|
19
|
-
"src"
|
|
20
|
-
],
|
|
21
|
-
"repository": {
|
|
22
|
-
"type": "git",
|
|
23
|
-
"url": "git+https://github.com/njuptlzf/agent-chat.git",
|
|
24
|
-
"directory": "packages/protocol"
|
|
25
|
-
},
|
|
26
|
-
"bugs": {
|
|
27
|
-
"url": "https://github.com/njuptlzf/agent-chat/issues"
|
|
28
|
-
},
|
|
29
|
-
"homepage": "https://github.com/njuptlzf/agent-chat#readme",
|
|
30
|
-
"keywords": [
|
|
31
|
-
"agent-chat",
|
|
32
|
-
"protocol",
|
|
33
|
-
"chat",
|
|
34
|
-
"sse"
|
|
35
|
-
],
|
|
36
|
-
"engines": {
|
|
37
|
-
"node": ">=22.
|
|
38
|
-
},
|
|
39
|
-
"publishConfig": {
|
|
40
|
-
"access": "public"
|
|
41
|
-
}
|
|
42
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@njuptlzf/agent-chat-protocol",
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "Wire protocol between the agentChat server and any chat UI: event, request/response and config types. Shapes only — no business semantics.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "Apache-2.0",
|
|
7
|
+
"main": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"agent-chat-source": "./src/index.ts",
|
|
12
|
+
"types": "./dist/index.d.ts",
|
|
13
|
+
"default": "./dist/index.js"
|
|
14
|
+
},
|
|
15
|
+
"./package.json": "./package.json"
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"dist",
|
|
19
|
+
"src"
|
|
20
|
+
],
|
|
21
|
+
"repository": {
|
|
22
|
+
"type": "git",
|
|
23
|
+
"url": "git+https://github.com/njuptlzf/agent-chat.git",
|
|
24
|
+
"directory": "packages/protocol"
|
|
25
|
+
},
|
|
26
|
+
"bugs": {
|
|
27
|
+
"url": "https://github.com/njuptlzf/agent-chat/issues"
|
|
28
|
+
},
|
|
29
|
+
"homepage": "https://github.com/njuptlzf/agent-chat#readme",
|
|
30
|
+
"keywords": [
|
|
31
|
+
"agent-chat",
|
|
32
|
+
"protocol",
|
|
33
|
+
"chat",
|
|
34
|
+
"sse"
|
|
35
|
+
],
|
|
36
|
+
"engines": {
|
|
37
|
+
"node": ">=22.15"
|
|
38
|
+
},
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"access": "public"
|
|
41
|
+
}
|
|
42
|
+
}
|