【Agent进阶专题】Workspace 与对话持久化

本篇实现第一版 Workspace:绑定当前项目,并将 Conversation 消息保存到本地数据目录。

能力介绍

Workspace 负责所有需要落地数据的管理,包括绑定关系/对话记录/产物记录等。代码留在原项目,Agent 产生的数据统一写入落地数据存储节点 LLM_TO_AGENT_HOME,两者物理隔离,互不干扰。

实现思路

第一版只实现一个 linked Workspace 和一个当前 Conversation,不处理列表、切换、归档和删除。

创建 Workspace 时可以指定数据根目录、项目路径和 Conversation ID。未指定时,数据根目录依次取显式配置、LLM_TO_AGENT_HOME 和 ~/.llm-to-agent;项目路径默认是当前工作目录,Conversation 默认是 default。

项目绝对路径经过 SHA-256 计算并截取前 16 位,得到稳定的 Workspace ID。确保同一个项目再次启动时仍会落到原目录。

LLM_TO_AGENT_HOME下的目录结构可以参考:【Agent进阶专题】数据目录介绍

setup 行为

Workspace 的初始化全部在 setup 中完成:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
async setup(context) {
await mkdir(conversationDirectory, { recursive: true });
await writeFile(
join(workspaceDirectory, "workspace.json"),
`${JSON.stringify(
{
id: workspaceId,
kind: "linked",
projectPath,
activeConversationId: conversationId,
},
null,
2,
)}\n`,
"utf8",
);

context.add(Hook.Workspace, workspace);
}

setup 依次完成三件事:

  1. 创建 Workspace 和 Conversation 目录。
  2. 写入当前项目的绑定信息。
  3. 将 WorkspaceService 注册到 Kernel。

每次启动都会重写 workspace.json,使项目路径和当前 Conversation 与本次参数一致。

Workspace 没有 start 和 stop,也没有需要在停止时释放的长期资源。

抓手

Workspace 对外暴露一个名为 workspace 的能力,它的契约是 WorkspaceService:

1
2
3
4
5
6
7
8
export interface WorkspaceService {
home: string;
projectPath: string;
workspaceId: string;
conversationId: string;
messages(): Promise<ChatMessage[]>;
append(role: MessageRole, content: string): Promise<ChatMessage>;
}
  • home:Agent 数据的存储根目录。
  • projectPath:当前 Workspace 绑定的项目绝对路径。
  • workspaceId:根据项目路径生成的稳定标识,用于定位当前 Workspace 的数据目录。
  • conversationId:当前 Conversation 的标识。
  • messages():读取当前 Conversation 的全部消息。首次使用、消息文件尚未创建时返回空数组。
  • append():向当前 Conversation 追加一条消息,并返回带有创建时间的完整消息对象。

这些字段提供当前工作空间的基本上下文,两个方法负责对话记录的读写。具体数据落在哪个文件、以什么格式保存,都留在 Workspace 内部。

Workspace 已经可以恢复对话历史。下一篇接入模型提供者,让 Agent 将这些消息真正发送给大模型。