@aalis/api-session-manager 0.6.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ace Nyan <ace@acenyan.com>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,25 @@
1
+ # @aalis/api-session-manager
2
+
3
+ 类型/接口/能力声明包(只导出 `type` 与 `*Capabilities`,不含运行时逻辑)
4
+
5
+ ## 角色
6
+
7
+ 类型/接口/能力声明包(只导出 `type` 与 `*Capabilities`,不含运行时逻辑)
8
+
9
+ ## 安装
10
+
11
+ ```bash
12
+ pnpm add @aalis/api-session-manager
13
+ ```
14
+
15
+ ## 使用
16
+
17
+ ```ts
18
+ import type { /* ... */ } from '@aalis/api-session-manager';
19
+ ```
20
+
21
+ 本包为 *-api 类型包;实现见对应的运行时插件。
22
+
23
+ ## 许可
24
+
25
+ 见仓库根目录 LICENSE。
@@ -0,0 +1,180 @@
1
+ /**
2
+ * 会话级配置覆盖
3
+ *
4
+ * 每个会话可以独立配置 LLM 提供者、模型、工具集、人设等。
5
+ * Agent 处理消息时通过 session-manager 的 resolveConfig() 获取最终生效配置。
6
+ *
7
+ * 配置解析优先级(从高到低):
8
+ * 1. 会话自身 config(手工覆盖 / /model 指令设置)
9
+ * 2. 父会话默认配置(sessionDefaults,供子会话继承)
10
+ * 3. 平台默认配置(platformProfiles[platform])
11
+ * 4. 全局默认(各插件的 defaultConfig)
12
+ */
13
+ export interface SessionConfig {
14
+ /**
15
+ * 会话使用的 LLM 模型引用:`{ provider, model }` 二元组。
16
+ * provider 为 LLM 插件实例 contextId(如 `@aalis/plugin-llm-openai:main`),
17
+ * model 为该 provider 注册的 model id(如 `gpt-4o`)。
18
+ * 由 ConfigSchema type='llm-ref' 字段统一编辑。
19
+ */
20
+ llm?: {
21
+ provider: string;
22
+ model: string;
23
+ };
24
+ /** 启用的工具分组列表(为空时使用全局默认) */
25
+ enabledToolGroups?: string[];
26
+ /** 人格文件名(不含后缀,如 'aalis', 'aalis-webui', 'default') */
27
+ persona?: string;
28
+ /** 额外系统提示(追加到人格提示之后) */
29
+ systemPromptExtra?: string;
30
+ /** 最大工具迭代次数覆盖 */
31
+ maxToolIterations?: number;
32
+ /** 禁用结构化输出格式(该会话回复纯文本) */
33
+ disableOutputFormat?: boolean;
34
+ /** JSON 内容由客户端渲染,服务端不提取回复字段 */
35
+ clientSideJsonRendering?: boolean;
36
+ /** 子会话默认配置(创建子会话时自动继承,子会话可进一步覆盖) */
37
+ sessionDefaults?: Omit<SessionConfig, 'sessionDefaults'>;
38
+ }
39
+ /**
40
+ * 平台配置模板
41
+ *
42
+ * 为每个平台设定默认的 SessionConfig。
43
+ * 新建会话时,根据消息来源的平台自动应用对应模板。
44
+ * 在 session-manager 的 configSchema 中通过 WebUI 配置。
45
+ */
46
+ export type PlatformProfile = SessionConfig;
47
+ /**
48
+ * 会话信息
49
+ *
50
+ * 代表一个独立的对话会话,可拥有独立配置和树形层级关系。
51
+ * 树形结构为未来 agent 任务拆分和协作奠定基础。
52
+ */
53
+ export interface SessionInfo {
54
+ /** 会话唯一标识 */
55
+ id: string;
56
+ /** 会话显示名称 */
57
+ name: string;
58
+ /** 自动生成的会话标题(AI 总结,或父会话指定) */
59
+ title?: string;
60
+ /** 父会话 ID(根会话为 undefined) */
61
+ parentId?: string;
62
+ /** 子会话 ID 列表 */
63
+ children: string[];
64
+ /** 会话状态 */
65
+ status: 'active' | 'waiting' | 'completed' | 'error' | 'archived';
66
+ /** 会话级配置覆盖 */
67
+ config: SessionConfig;
68
+ /** 创建时间戳 */
69
+ createdAt: number;
70
+ /** 最后更新时间戳 */
71
+ updatedAt: number;
72
+ /** 创建者类型 */
73
+ createdBy?: 'user' | 'agent' | 'scheduler' | 'system';
74
+ /** 父会话传入的指令/上下文(创建子会话时由父会话填写) */
75
+ inputContext?: string;
76
+ /** 完成结果摘要(子会话完成后填充,用于向父会话汇报) */
77
+ result?: string;
78
+ /** 扩展元数据(供插件自由使用) */
79
+ metadata?: Record<string, unknown>;
80
+ }
81
+ /**
82
+ * 会话树节点(递归结构)
83
+ *
84
+ * 用于前端展示会话树和 agent 任务树状图。
85
+ */
86
+ export interface SessionTreeNode {
87
+ session: SessionInfo;
88
+ children: SessionTreeNode[];
89
+ }
90
+ /**
91
+ * 会话管理服务
92
+ *
93
+ * 负责会话的创建、查询、配置和树形管理。
94
+ * 由 plugin-session-manager 实现并注册为 'session-manager' 服务。
95
+ *
96
+ * 设计要点:
97
+ * - 每个会话拥有独立的 SessionConfig,Agent 处理消息时查询并应用
98
+ * - 树形结构通过 parentId/children 维护,支持未来的任务拆分场景
99
+ * - 会话生命周期事件通过 EventBus 广播
100
+ */
101
+ export interface SessionManagerService {
102
+ /** 创建新会话,返回完整的 SessionInfo */
103
+ createSession(opts?: Partial<Omit<SessionInfo, 'id' | 'children' | 'createdAt' | 'updatedAt'>>): Promise<SessionInfo>;
104
+ /** 获取指定会话(不存在返回 undefined) */
105
+ getSession(id: string): SessionInfo | undefined;
106
+ /** 列出会话(可按 parentId 和 status 过滤) */
107
+ listSessions(filter?: {
108
+ parentId?: string | null;
109
+ status?: SessionInfo['status'];
110
+ }): SessionInfo[];
111
+ /** 更新会话属性 */
112
+ updateSession(id: string, updates: Partial<Pick<SessionInfo, 'name' | 'config' | 'status' | 'metadata'>>): Promise<SessionInfo>;
113
+ /**
114
+ * 按精确 id 幂等 upsert 会话。
115
+ * - 已存在 → 合并式 update(emit `session:updated`)
116
+ * - 不存在 → 以传入 id(**不自生成**)建 active 记录(emit `session:created`)
117
+ *
118
+ * 用于平台派生 sessionId(如 `onebot:<self>:group:<gid>`):这些 id 不经
119
+ * createSession 预建,首次设置模型/人设覆盖时需按其原样 id 落档——而 createSession
120
+ * 会自生成 id、updateSession 缺记录会抛错,故需要本方法。
121
+ */
122
+ ensureSession(id: string, patch?: Partial<Pick<SessionInfo, 'name' | 'config' | 'status' | 'metadata' | 'createdBy'>>): Promise<SessionInfo>;
123
+ /** 删除会话(同时清理其消息历史) */
124
+ deleteSession(id: string): Promise<void>;
125
+ /** 创建子会话 */
126
+ createChildSession(parentId: string, opts?: Partial<Omit<SessionInfo, 'id' | 'parentId' | 'children' | 'createdAt' | 'updatedAt'>>): Promise<SessionInfo>;
127
+ /** 获取直接子会话列表 */
128
+ getChildren(parentId: string): SessionInfo[];
129
+ /** 获取会话树(传入 rootId 则只返回该子树,否则返回所有根会话的树) */
130
+ getTree(rootId?: string): SessionTreeNode[];
131
+ /** 标记会话完成(触发 session:completed 事件,通知父会话) */
132
+ completeSession(id: string, result?: string): Promise<void>;
133
+ /**
134
+ * 解析指定会话的最终生效配置
135
+ *
136
+ * 合并优先级:会话 config > 父会话 sessionDefaults > 平台 profile > 全局默认
137
+ * 返回合并后的完整 SessionConfig(不含 sessionDefaults 字段)
138
+ */
139
+ resolveConfig(sessionId: string, platform?: string): Omit<SessionConfig, 'sessionDefaults'>;
140
+ /**
141
+ * 解析「继承默认」——即如果当前会话不设置任何字段,会从父/平台 profile 拿到什么。
142
+ *
143
+ * 与 resolveConfig 的区别:**不包含** session 自身 config,只合并:
144
+ * 1. 平台 profile(最低)
145
+ * 2. 父会话 sessionDefaults(最高)
146
+ *
147
+ * 适用场景:WebUI 显示「继承 (xxx)」提示时,应该展示"未覆盖前的默认值"而非当前生效值,
148
+ * 否则用户一旦覆盖了某字段,"继承"提示就会变成他自己刚刚设置的值,产生迷惑。
149
+ */
150
+ resolveInheritedDefaults(sessionId: string, platform?: string): Omit<SessionConfig, 'sessionDefaults'>;
151
+ /** 获取已配置的平台 profile 列表 */
152
+ getPlatformProfiles(): Record<string, PlatformProfile>;
153
+ /** 设置指定平台的 profile */
154
+ setPlatformProfile(platform: string, profile: PlatformProfile): void;
155
+ /**
156
+ * 获取全局默认配置(platform profile 之下的最低层 fallback)。
157
+ * 当 session 自身、父会话 sessionDefaults、platform profile 都未指定某字段时,
158
+ * resolveConfig 会回落到这里。配置位置:`@aalis/plugin-session-manager.defaults`。
159
+ */
160
+ getDefaults(): Omit<SessionConfig, 'sessionDefaults'>;
161
+ /** 自动生成会话标题(调用 LLM 总结),返回生成的标题或 undefined。可传入 userMessage 避免依赖历史记录。 */
162
+ generateTitle(sessionId: string, userMessage?: string): Promise<string | undefined>;
163
+ /** 手动更新会话标题 */
164
+ updateSessionTitle(sessionId: string, title: string): Promise<void>;
165
+ }
166
+ declare module '@aalis/core' {
167
+ /** 会话生命周期事件(由 plugin-session-manager 增量声明) */
168
+ interface AalisEvents {
169
+ 'session:created': [session: SessionInfo];
170
+ 'session:updated': [session: SessionInfo];
171
+ 'session:completed': [session: SessionInfo];
172
+ 'session:deleted': [sessionId: string];
173
+ }
174
+ }
175
+ declare module '@aalis/core' {
176
+ interface ServiceTypeMap {
177
+ 'session-manager': SessionManagerService;
178
+ }
179
+ }
180
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/index.js ADDED
@@ -0,0 +1,8 @@
1
+ // ----- 会话管理服务接口(types + capability 声明 + 事件 augmentation)-----
2
+ //
3
+ // 该包是 plugin-session-manager 的"类型 + 能力声明"边界。
4
+ // 仅需要类型(如 ctx.getService<SessionManagerService>())或仅需要
5
+ // 触发 session:* 事件 augmentation 的下游插件应当依赖本包,而不是 impl 包,
6
+ // 以避免不必要的工作区依赖与编译循环风险。
7
+ export {};
8
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,EAAE;AACF,6CAA6C;AAC7C,uDAAuD;AACvD,uDAAuD;AACvD,uBAAuB"}
package/package.json ADDED
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "@aalis/api-session-manager",
3
+ "version": "0.6.0",
4
+ "license": "MIT",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/AalisLabs/Aalis.git",
8
+ "directory": "packages/api-session-manager"
9
+ },
10
+ "author": "Ace Nyan <ace@acenyan.com>",
11
+ "bugs": {
12
+ "url": "https://github.com/AalisLabs/Aalis/issues"
13
+ },
14
+ "homepage": "https://github.com/AalisLabs/Aalis#readme",
15
+ "type": "module",
16
+ "main": "dist/index.js",
17
+ "types": "dist/index.d.ts",
18
+ "files": [
19
+ "dist"
20
+ ],
21
+ "devDependencies": {
22
+ "@types/node": "^22.0.0",
23
+ "typescript": "^5.7.0",
24
+ "@aalis/core": "0.10.0"
25
+ },
26
+ "aalis": {
27
+ "types": true
28
+ },
29
+ "peerDependencies": {
30
+ "@aalis/core": ">=0.2.0 <1.0.0"
31
+ },
32
+ "keywords": [
33
+ "aalis",
34
+ "aalis-api"
35
+ ],
36
+ "scripts": {
37
+ "build": "tsc",
38
+ "dev": "tsc --watch"
39
+ }
40
+ }