@njuptlzf/agent-chat-protocol 0.4.1 → 0.5.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 +29 -9
- package/dist/index.js +1 -7
- package/dist/memory-provider.d.ts +104 -0
- package/dist/memory-provider.js +17 -0
- package/package.json +1 -1
- package/src/index.ts +31 -8
- package/src/memory-provider.ts +108 -0
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { MemorySettings } from "./memory-provider.ts";
|
|
1
2
|
/**
|
|
2
3
|
* Wire protocol between the agent server and any chat UI.
|
|
3
4
|
*
|
|
@@ -31,7 +32,13 @@ export interface TokenUsage {
|
|
|
31
32
|
cacheRead: number;
|
|
32
33
|
cacheWrite: number;
|
|
33
34
|
total: number;
|
|
34
|
-
/**
|
|
35
|
+
/**
|
|
36
|
+
* Unified cost in CU (Cost Unit, integer) from the platform cost model.
|
|
37
|
+
* Historical field name: despite `Usd`, this is NOT a dollar amount — the
|
|
38
|
+
* numeric value is the platform cost-model CU. No CU-to-currency conversion
|
|
39
|
+
* happens here; display units/rates are a caller concern. Falls back to the
|
|
40
|
+
* legacy provider-reported cost when no cost model is configured.
|
|
41
|
+
*/
|
|
35
42
|
costUsd: number;
|
|
36
43
|
}
|
|
37
44
|
export type ErrorCode = "bad_request" | "unauthorized" | "quota_exceeded" | "payment_required" | "input_too_long" | "model_error" | "limit_exceeded"
|
|
@@ -941,14 +948,25 @@ export interface ProductManifest {
|
|
|
941
948
|
*/
|
|
942
949
|
extensions?: string[];
|
|
943
950
|
/**
|
|
944
|
-
* Per-user/per-scope long-term memory
|
|
945
|
-
*
|
|
946
|
-
*
|
|
947
|
-
*
|
|
948
|
-
*
|
|
949
|
-
*
|
|
951
|
+
* Per-user/per-scope long-term memory. Default true.
|
|
952
|
+
*
|
|
953
|
+
* `true` mounts the platform default provider; `false` disables memory;
|
|
954
|
+
* `{ provider }` picks a named implementation from the registry (see
|
|
955
|
+
* `memory-provider.ts`) — that is the whole point of the port: swapping the
|
|
956
|
+
* memory engine is a manifest edit, not a server change.
|
|
957
|
+
*
|
|
958
|
+
* Storage stays host-owned either way: `<dataDir>/memory/<userId>/<scope>/`,
|
|
959
|
+
* never exposed to the browser and never rendered into the prompt as a path.
|
|
960
|
+
*/
|
|
961
|
+
memory?: boolean | MemorySettings;
|
|
962
|
+
/**
|
|
963
|
+
* 外部记忆提供方模块:产品目录内的相对路径,或包说明符(如
|
|
964
|
+
* `@njuptlzf/pi-hermes-memory/scoped-provider`)。加载时过准入扫描——它们与
|
|
965
|
+
* `agent.extensions` 同权,在服务进程内运行。
|
|
966
|
+
*
|
|
967
|
+
* 只声明"有哪些实现可用",不决定用哪个;用哪个由 `agent.memory.provider` 决定。
|
|
950
968
|
*/
|
|
951
|
-
|
|
969
|
+
memoryProviders?: string[];
|
|
952
970
|
model: {
|
|
953
971
|
provider: string;
|
|
954
972
|
id: string;
|
|
@@ -990,6 +1008,8 @@ export interface ProductManifest {
|
|
|
990
1008
|
memberDailyTokenQuota?: number;
|
|
991
1009
|
/** 会员每月发放 token 池(池内免余额,池尽才扣余额)。 */
|
|
992
1010
|
memberMonthlyTokenPool?: number;
|
|
1011
|
+
/** 全局成本倍率(CU / 千 token),用于无逐模型 costModel 声明时的兜底折算;默认 1。运维成本尺子,与收费单价无关。 */
|
|
1012
|
+
costRatePerThousandTokens?: number;
|
|
993
1013
|
/**
|
|
994
1014
|
* 按人格(= 账本产品)覆盖上面的额度。缺省继承产品级。
|
|
995
1015
|
* 例:声明人格 `freeDailyRuns: 0`(不限轮)但池只有 100 万。
|
|
@@ -1096,4 +1116,4 @@ export interface ProductManifest {
|
|
|
1096
1116
|
}>;
|
|
1097
1117
|
};
|
|
1098
1118
|
}
|
|
1099
|
-
export
|
|
1119
|
+
export * from "./memory-provider.ts";
|
package/dist/index.js
CHANGED
|
@@ -1,10 +1,3 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Wire protocol between the agent server and any chat UI.
|
|
3
|
-
*
|
|
4
|
-
* This file is the only contract the UI depends on. pi's own event shapes stay
|
|
5
|
-
* behind the server-side adapter, so upgrading pi never breaks a client.
|
|
6
|
-
* Bump PROTOCOL_VERSION on any breaking change.
|
|
7
|
-
*/
|
|
8
1
|
export const PROTOCOL_VERSION = 7;
|
|
9
2
|
/**
|
|
10
3
|
* 产品**没有**声明 `agent.defaultPersona` 时用的兜底 id。
|
|
@@ -19,3 +12,4 @@ export const DEFAULT_PERSONA_ID = "default";
|
|
|
19
12
|
* 的专用分支与其泛型 cast,见人格配置面设计稿 §17。
|
|
20
13
|
*/
|
|
21
14
|
export const PERSONA_UI_FIELDS = ["label", "icon", "tag", "hint", "welcome", "policyNote", "suggestions", "followUpMode"];
|
|
15
|
+
export * from "./memory-provider.js";
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 记忆提供方接口(memory provider port)。
|
|
3
|
+
*
|
|
4
|
+
* 平台**不认识任何具体实现**:它只知道"一次 open 拿到一个可挂载的扩展工厂 + 提示段落 +
|
|
5
|
+
* 擦除能力"。换记忆实现 = 换一个 `providerId`,服务器代码不动。
|
|
6
|
+
*
|
|
7
|
+
* 三条约束,都是踩过坑才写下来的:
|
|
8
|
+
*
|
|
9
|
+
* 1. **本包不依赖 pi**。`P` 由宿主实例化成 `ExtensionAPI`,协议包只表达"有个工厂接收它"。
|
|
10
|
+
* 理由与 `events.ts` 一致:pi 的类型留在服务器适配层,升级 pi 不波及客户端契约。
|
|
11
|
+
* 2. **open 与挂载分离**。宿主要在自己组装 system prompt 时就要到提示段落,那时 pi 会话
|
|
12
|
+
* 还不存在;把两者捆在一起,宿主只能先去挂一个它只要字符串的扩展。
|
|
13
|
+
* 3. **`selfInjects` 必须显式**。有的实现靠 `before_agent_start` 自己追加段落(pi 系插件),
|
|
14
|
+
* 有的只把文本交给宿主(服务端自组装)。不写清楚,宿主要么重复注入、要么完全不注入,
|
|
15
|
+
* 而两种症状都不会报错——只会表现成"记忆好像没用"。
|
|
16
|
+
*/
|
|
17
|
+
/** 一个租户的完整身份。平台只传不改,提供方不得据此推导别的东西。 */ export interface MemoryScope {
|
|
18
|
+
readonly userId: string;
|
|
19
|
+
readonly productId: string;
|
|
20
|
+
/** 资格/子作用域;无资格的产物传 `""`,不要传 undefined 让下游自己猜。 */
|
|
21
|
+
readonly qual: string;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* open 的输入。
|
|
25
|
+
*
|
|
26
|
+
* `storageRoot` 是宿主算好的绝对路径,**一个租户一个根**:提供方不得读
|
|
27
|
+
* `process.env`、`os.homedir()` 或任何机器级默认来补路径——那正是多租户串数据的入口。
|
|
28
|
+
*/
|
|
29
|
+
export interface MemoryProviderContext {
|
|
30
|
+
readonly storageRoot: string;
|
|
31
|
+
/**
|
|
32
|
+
* 该用户跨 scope 共享的根(一个 userId 一个),宿主算好传入。
|
|
33
|
+
*
|
|
34
|
+
* 省略 = 只要 scope 隔离,不做跨会话画像。**两处删除语义不同**:scope 根随
|
|
35
|
+
* 资格/会话消亡,共享根只在注销用户时消亡;provider 不得把 profile 放进 scope 根,
|
|
36
|
+
* 否则"删掉这门课"会顺手删掉用户身份。
|
|
37
|
+
*/
|
|
38
|
+
readonly sharedRoot?: string | null;
|
|
39
|
+
/** 本会话的 pi agent 目录(宿主按产品/用户分的 dataDir),提供方只读不写。 */
|
|
40
|
+
readonly agentDir: string;
|
|
41
|
+
readonly scope: MemoryScope;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* 一次 open 的产物。
|
|
45
|
+
*
|
|
46
|
+
* 生命周期:`open()` → 宿主决定 `promptSection` 怎么用 → 把 `factory` 放进 pi 的
|
|
47
|
+
* extension 列表 → 会话结束 `dispose()`;用户注销 `erase()`。
|
|
48
|
+
*/
|
|
49
|
+
export interface MemoryProviderSession<P = unknown> {
|
|
50
|
+
readonly providerId: string;
|
|
51
|
+
/**
|
|
52
|
+
* 挂进 pi 的扩展工厂。必须只注册工具/事件,不得自己 spawn 子进程、不得读 env
|
|
53
|
+
* (see `extension-admission.ts`)。
|
|
54
|
+
*/
|
|
55
|
+
readonly factory: (pi: P) => void;
|
|
56
|
+
/**
|
|
57
|
+
* 是否由扩展自己往系统提示里追加记忆段落。
|
|
58
|
+
* `true` → 宿主不要再用 `promptSection()`,否则会重复注入;
|
|
59
|
+
* `false` → 宿主负责把 `promptSection()` 拼进提示。
|
|
60
|
+
*/
|
|
61
|
+
readonly selfInjects: boolean;
|
|
62
|
+
/** 记忆策略段落;`selfInjects` 为 true 时返回空串。 */
|
|
63
|
+
promptSection(): Promise<string>;
|
|
64
|
+
/**
|
|
65
|
+
* 抹掉该租户的记忆。幂等;不得触碰本次调用声明范围之外的路径。
|
|
66
|
+
*
|
|
67
|
+
* `includeShared` 默认 false:删一个 scope 不该删掉用户画像,注销用户是宿主的
|
|
68
|
+
* 第二次显式调用。
|
|
69
|
+
*/
|
|
70
|
+
erase(options?: {
|
|
71
|
+
readonly includeShared?: boolean;
|
|
72
|
+
}): Promise<void>;
|
|
73
|
+
/** 释放句柄(数据库连接、锁)。幂等。 */
|
|
74
|
+
dispose(): Promise<void>;
|
|
75
|
+
}
|
|
76
|
+
export interface MemoryProvider<P = unknown> {
|
|
77
|
+
/** 稳定标识,写进 manifest 的 `agent.memory.provider`。 */
|
|
78
|
+
readonly id: string;
|
|
79
|
+
readonly version: string;
|
|
80
|
+
open(ctx: MemoryProviderContext): Promise<MemoryProviderSession<P>>;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* manifest 里的记忆开关。
|
|
84
|
+
*
|
|
85
|
+
* `true` = 用平台默认实现,`false` = 关掉,对象形式 = 指定某个注册表条目。
|
|
86
|
+
* 刻意只留 `provider` 一个字段:给实现传参数会让 manifest 变成实现的配置文件,
|
|
87
|
+
* 换实现就得改产品仓——那正是这个端口要消除的成本。实现专属参数走宿主配置。
|
|
88
|
+
*/
|
|
89
|
+
export interface MemorySettings {
|
|
90
|
+
/** 注册表里的 provider id;省略 = 平台默认。 */
|
|
91
|
+
provider?: string;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* 外部提供方模块的形状。
|
|
95
|
+
*
|
|
96
|
+
* 平台从 manifest 声明的路径/包名动态加载它,所以**默认导出就是 provider 本身**
|
|
97
|
+
* (不是工厂):模块自己决定怎么读配置,平台只校验 id/open 两个字段。
|
|
98
|
+
*
|
|
99
|
+
* 一个产品侧的适配文件长这样,三行:
|
|
100
|
+
* export { default } from "@njuptlzf/pi-hermes-memory/scoped-provider";
|
|
101
|
+
*/
|
|
102
|
+
export interface MemoryProviderModule<P = unknown> {
|
|
103
|
+
readonly default: MemoryProvider<P>;
|
|
104
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 记忆提供方接口(memory provider port)。
|
|
3
|
+
*
|
|
4
|
+
* 平台**不认识任何具体实现**:它只知道"一次 open 拿到一个可挂载的扩展工厂 + 提示段落 +
|
|
5
|
+
* 擦除能力"。换记忆实现 = 换一个 `providerId`,服务器代码不动。
|
|
6
|
+
*
|
|
7
|
+
* 三条约束,都是踩过坑才写下来的:
|
|
8
|
+
*
|
|
9
|
+
* 1. **本包不依赖 pi**。`P` 由宿主实例化成 `ExtensionAPI`,协议包只表达"有个工厂接收它"。
|
|
10
|
+
* 理由与 `events.ts` 一致:pi 的类型留在服务器适配层,升级 pi 不波及客户端契约。
|
|
11
|
+
* 2. **open 与挂载分离**。宿主要在自己组装 system prompt 时就要到提示段落,那时 pi 会话
|
|
12
|
+
* 还不存在;把两者捆在一起,宿主只能先去挂一个它只要字符串的扩展。
|
|
13
|
+
* 3. **`selfInjects` 必须显式**。有的实现靠 `before_agent_start` 自己追加段落(pi 系插件),
|
|
14
|
+
* 有的只把文本交给宿主(服务端自组装)。不写清楚,宿主要么重复注入、要么完全不注入,
|
|
15
|
+
* 而两种症状都不会报错——只会表现成"记忆好像没用"。
|
|
16
|
+
*/
|
|
17
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@njuptlzf/agent-chat-protocol",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Wire protocol between the agentChat server and any chat UI: event, request/response and config types. Shapes only — no business semantics.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
package/src/index.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
|
|
2
2
|
|
|
3
|
+
import type { MemorySettings } from "./memory-provider.ts";
|
|
4
|
+
|
|
3
5
|
/**
|
|
4
6
|
* Wire protocol between the agent server and any chat UI.
|
|
5
7
|
*
|
|
@@ -31,7 +33,13 @@ export interface TokenUsage {
|
|
|
31
33
|
cacheRead: number;
|
|
32
34
|
cacheWrite: number;
|
|
33
35
|
total: number;
|
|
34
|
-
/**
|
|
36
|
+
/**
|
|
37
|
+
* Unified cost in CU (Cost Unit, integer) from the platform cost model.
|
|
38
|
+
* Historical field name: despite `Usd`, this is NOT a dollar amount — the
|
|
39
|
+
* numeric value is the platform cost-model CU. No CU-to-currency conversion
|
|
40
|
+
* happens here; display units/rates are a caller concern. Falls back to the
|
|
41
|
+
* legacy provider-reported cost when no cost model is configured.
|
|
42
|
+
*/
|
|
35
43
|
costUsd: number;
|
|
36
44
|
}
|
|
37
45
|
export type ErrorCode =
|
|
@@ -888,14 +896,25 @@ export interface ProductManifest {
|
|
|
888
896
|
*/
|
|
889
897
|
extensions?: string[];
|
|
890
898
|
/**
|
|
891
|
-
* Per-user/per-scope long-term memory
|
|
892
|
-
*
|
|
893
|
-
*
|
|
894
|
-
*
|
|
895
|
-
*
|
|
896
|
-
*
|
|
899
|
+
* Per-user/per-scope long-term memory. Default true.
|
|
900
|
+
*
|
|
901
|
+
* `true` mounts the platform default provider; `false` disables memory;
|
|
902
|
+
* `{ provider }` picks a named implementation from the registry (see
|
|
903
|
+
* `memory-provider.ts`) — that is the whole point of the port: swapping the
|
|
904
|
+
* memory engine is a manifest edit, not a server change.
|
|
905
|
+
*
|
|
906
|
+
* Storage stays host-owned either way: `<dataDir>/memory/<userId>/<scope>/`,
|
|
907
|
+
* never exposed to the browser and never rendered into the prompt as a path.
|
|
897
908
|
*/
|
|
898
|
-
memory?: boolean;
|
|
909
|
+
memory?: boolean | MemorySettings;
|
|
910
|
+
/**
|
|
911
|
+
* 外部记忆提供方模块:产品目录内的相对路径,或包说明符(如
|
|
912
|
+
* `@njuptlzf/pi-hermes-memory/scoped-provider`)。加载时过准入扫描——它们与
|
|
913
|
+
* `agent.extensions` 同权,在服务进程内运行。
|
|
914
|
+
*
|
|
915
|
+
* 只声明"有哪些实现可用",不决定用哪个;用哪个由 `agent.memory.provider` 决定。
|
|
916
|
+
*/
|
|
917
|
+
memoryProviders?: string[];
|
|
899
918
|
model: { provider: string; id: string; thinking?: ThinkingLevel };
|
|
900
919
|
/**
|
|
901
920
|
* Selectable quality tiers (batch 3-1). The UI sees only `id`/`label`/the
|
|
@@ -933,6 +952,8 @@ export interface ProductManifest {
|
|
|
933
952
|
memberDailyTokenQuota?: number;
|
|
934
953
|
/** 会员每月发放 token 池(池内免余额,池尽才扣余额)。 */
|
|
935
954
|
memberMonthlyTokenPool?: number;
|
|
955
|
+
/** 全局成本倍率(CU / 千 token),用于无逐模型 costModel 声明时的兜底折算;默认 1。运维成本尺子,与收费单价无关。 */
|
|
956
|
+
costRatePerThousandTokens?: number;
|
|
936
957
|
/**
|
|
937
958
|
* 按人格(= 账本产品)覆盖上面的额度。缺省继承产品级。
|
|
938
959
|
* 例:声明人格 `freeDailyRuns: 0`(不限轮)但池只有 100 万。
|
|
@@ -1030,3 +1051,5 @@ export interface ProductManifest {
|
|
|
1030
1051
|
}>;
|
|
1031
1052
|
};
|
|
1032
1053
|
}
|
|
1054
|
+
|
|
1055
|
+
export * from "./memory-provider.ts";
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 记忆提供方接口(memory provider port)。
|
|
3
|
+
*
|
|
4
|
+
* 平台**不认识任何具体实现**:它只知道"一次 open 拿到一个可挂载的扩展工厂 + 提示段落 +
|
|
5
|
+
* 擦除能力"。换记忆实现 = 换一个 `providerId`,服务器代码不动。
|
|
6
|
+
*
|
|
7
|
+
* 三条约束,都是踩过坑才写下来的:
|
|
8
|
+
*
|
|
9
|
+
* 1. **本包不依赖 pi**。`P` 由宿主实例化成 `ExtensionAPI`,协议包只表达"有个工厂接收它"。
|
|
10
|
+
* 理由与 `events.ts` 一致:pi 的类型留在服务器适配层,升级 pi 不波及客户端契约。
|
|
11
|
+
* 2. **open 与挂载分离**。宿主要在自己组装 system prompt 时就要到提示段落,那时 pi 会话
|
|
12
|
+
* 还不存在;把两者捆在一起,宿主只能先去挂一个它只要字符串的扩展。
|
|
13
|
+
* 3. **`selfInjects` 必须显式**。有的实现靠 `before_agent_start` 自己追加段落(pi 系插件),
|
|
14
|
+
* 有的只把文本交给宿主(服务端自组装)。不写清楚,宿主要么重复注入、要么完全不注入,
|
|
15
|
+
* 而两种症状都不会报错——只会表现成"记忆好像没用"。
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** 一个租户的完整身份。平台只传不改,提供方不得据此推导别的东西。 */export interface MemoryScope {
|
|
19
|
+
readonly userId: string;
|
|
20
|
+
readonly productId: string;
|
|
21
|
+
/** 资格/子作用域;无资格的产物传 `""`,不要传 undefined 让下游自己猜。 */
|
|
22
|
+
readonly qual: string;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* open 的输入。
|
|
27
|
+
*
|
|
28
|
+
* `storageRoot` 是宿主算好的绝对路径,**一个租户一个根**:提供方不得读
|
|
29
|
+
* `process.env`、`os.homedir()` 或任何机器级默认来补路径——那正是多租户串数据的入口。
|
|
30
|
+
*/
|
|
31
|
+
export interface MemoryProviderContext {
|
|
32
|
+
readonly storageRoot: string;
|
|
33
|
+
/**
|
|
34
|
+
* 该用户跨 scope 共享的根(一个 userId 一个),宿主算好传入。
|
|
35
|
+
*
|
|
36
|
+
* 省略 = 只要 scope 隔离,不做跨会话画像。**两处删除语义不同**:scope 根随
|
|
37
|
+
* 资格/会话消亡,共享根只在注销用户时消亡;provider 不得把 profile 放进 scope 根,
|
|
38
|
+
* 否则"删掉这门课"会顺手删掉用户身份。
|
|
39
|
+
*/
|
|
40
|
+
readonly sharedRoot?: string | null;
|
|
41
|
+
/** 本会话的 pi agent 目录(宿主按产品/用户分的 dataDir),提供方只读不写。 */
|
|
42
|
+
readonly agentDir: string;
|
|
43
|
+
readonly scope: MemoryScope;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* 一次 open 的产物。
|
|
48
|
+
*
|
|
49
|
+
* 生命周期:`open()` → 宿主决定 `promptSection` 怎么用 → 把 `factory` 放进 pi 的
|
|
50
|
+
* extension 列表 → 会话结束 `dispose()`;用户注销 `erase()`。
|
|
51
|
+
*/
|
|
52
|
+
export interface MemoryProviderSession<P = unknown> {
|
|
53
|
+
readonly providerId: string;
|
|
54
|
+
/**
|
|
55
|
+
* 挂进 pi 的扩展工厂。必须只注册工具/事件,不得自己 spawn 子进程、不得读 env
|
|
56
|
+
* (see `extension-admission.ts`)。
|
|
57
|
+
*/
|
|
58
|
+
readonly factory: (pi: P) => void;
|
|
59
|
+
/**
|
|
60
|
+
* 是否由扩展自己往系统提示里追加记忆段落。
|
|
61
|
+
* `true` → 宿主不要再用 `promptSection()`,否则会重复注入;
|
|
62
|
+
* `false` → 宿主负责把 `promptSection()` 拼进提示。
|
|
63
|
+
*/
|
|
64
|
+
readonly selfInjects: boolean;
|
|
65
|
+
/** 记忆策略段落;`selfInjects` 为 true 时返回空串。 */
|
|
66
|
+
promptSection(): Promise<string>;
|
|
67
|
+
/**
|
|
68
|
+
* 抹掉该租户的记忆。幂等;不得触碰本次调用声明范围之外的路径。
|
|
69
|
+
*
|
|
70
|
+
* `includeShared` 默认 false:删一个 scope 不该删掉用户画像,注销用户是宿主的
|
|
71
|
+
* 第二次显式调用。
|
|
72
|
+
*/
|
|
73
|
+
erase(options?: { readonly includeShared?: boolean }): Promise<void>;
|
|
74
|
+
/** 释放句柄(数据库连接、锁)。幂等。 */
|
|
75
|
+
dispose(): Promise<void>;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export interface MemoryProvider<P = unknown> {
|
|
79
|
+
/** 稳定标识,写进 manifest 的 `agent.memory.provider`。 */
|
|
80
|
+
readonly id: string;
|
|
81
|
+
readonly version: string;
|
|
82
|
+
open(ctx: MemoryProviderContext): Promise<MemoryProviderSession<P>>;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* manifest 里的记忆开关。
|
|
87
|
+
*
|
|
88
|
+
* `true` = 用平台默认实现,`false` = 关掉,对象形式 = 指定某个注册表条目。
|
|
89
|
+
* 刻意只留 `provider` 一个字段:给实现传参数会让 manifest 变成实现的配置文件,
|
|
90
|
+
* 换实现就得改产品仓——那正是这个端口要消除的成本。实现专属参数走宿主配置。
|
|
91
|
+
*/
|
|
92
|
+
export interface MemorySettings {
|
|
93
|
+
/** 注册表里的 provider id;省略 = 平台默认。 */
|
|
94
|
+
provider?: string;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* 外部提供方模块的形状。
|
|
99
|
+
*
|
|
100
|
+
* 平台从 manifest 声明的路径/包名动态加载它,所以**默认导出就是 provider 本身**
|
|
101
|
+
* (不是工厂):模块自己决定怎么读配置,平台只校验 id/open 两个字段。
|
|
102
|
+
*
|
|
103
|
+
* 一个产品侧的适配文件长这样,三行:
|
|
104
|
+
* export { default } from "@njuptlzf/pi-hermes-memory/scoped-provider";
|
|
105
|
+
*/
|
|
106
|
+
export interface MemoryProviderModule<P = unknown> {
|
|
107
|
+
readonly default: MemoryProvider<P>;
|
|
108
|
+
}
|