wuyang6
244 lines
4.8 KiB
Markdown
244 lines
4.8 KiB
Markdown
# 05. 会话工作区、运行态和记忆
|
||
|
||
|
||
|
||
## 1. 会话工作区
|
||
|
||
每个用户、每个会话都有独立目录：
|
||
|
||
```text
|
||
.port_sessions/accounts/<account_id>/sessions/<session_id>/
|
||
input/
|
||
scratchpad/
|
||
output/
|
||
session.json
|
||
```
|
||
|
||
目录职责：
|
||
|
||
```text
|
||
input/
|
||
用户上传或明确提供的输入资料。
|
||
|
||
scratchpad/
|
||
临时脚本、中间文件、抽样缓存、断点记录。
|
||
|
||
output/
|
||
最终交付产物。
|
||
|
||
session.json
|
||
会话消息、工具调用、usage、events、file_history、runtime metadata。
|
||
```
|
||
|
||
## 2. 工作区路径路由
|
||
|
||
路径解析实现：
|
||
|
||
```text
|
||
src/agent_tools.py:1658 _session_logical_path
|
||
```
|
||
|
||
逻辑路径：
|
||
|
||
```text
|
||
output/... -> session/output/...
|
||
outputs/... -> session/output/...
|
||
scratchpad/... -> session/scratchpad/...
|
||
scratch/... -> session/scratchpad/...
|
||
input/... -> session/input/...
|
||
inputs/... -> session/input/...
|
||
```
|
||
|
||
Python 执行 cwd：
|
||
|
||
```text
|
||
src/agent_tools.py:1685 _execution_cwd
|
||
```
|
||
|
||
优先使用当前 session scratchpad。这是为了避免临时脚本和缓存污染项目根目录。
|
||
|
||
## 3. 平台代码写保护
|
||
|
||
相关实现：
|
||
|
||
```text
|
||
src/agent_tools.py:1118 _PLATFORM_READONLY_DIRS
|
||
src/agent_tools.py:1698 _is_platform_code_path
|
||
src/agent_tools.py:1708 _ensure_not_platform_code_write
|
||
```
|
||
|
||
当前平台目录：
|
||
|
||
```text
|
||
src
|
||
backend
|
||
frontend
|
||
scripts
|
||
```
|
||
|
||
在数据 Agent 会话中默认视为只读。除非用户明确进入平台开发任务，否则业务任务不应修改平台代码。
|
||
|
||
## 4. Run 状态和活动区
|
||
|
||
后端在 `/api/chat` 运行时创建 run record：
|
||
|
||
```text
|
||
backend/api/server.py:1720 run_record = state.run_manager.start(...)
|
||
backend/api/server.py:1722 state.run_state_store.start(...)
|
||
```
|
||
|
||
运行事件通过 `emit_agent_event` 记录：
|
||
|
||
```text
|
||
backend/api/server.py:1751 emit_agent_event
|
||
backend/api/server.py:1756 run_manager.record_event
|
||
backend/api/server.py:1758 run_state_store.record_event
|
||
```
|
||
|
||
返回前端：
|
||
|
||
```text
|
||
backend/api/server.py:2034 StreamingResponse
|
||
```
|
||
|
||
前端活动区看到的内容主要来自：
|
||
|
||
- `run_started`
|
||
- `tool_start`
|
||
- `tool_result`
|
||
- 模型阶段说明
|
||
- final text stream events
|
||
- run finish/error/cancel 状态
|
||
|
||
## 5. 会话持久化
|
||
|
||
运行结束后，后端序列化结果：
|
||
|
||
```text
|
||
backend/api/server.py:2056 _serialize_run_result
|
||
backend/api/server.py:2069 _normalize_transcript_entry
|
||
```
|
||
|
||
会话读取：
|
||
|
||
```text
|
||
backend/api/server.py:2094 _serialize_stored_session
|
||
```
|
||
|
||
`agent_runtime` 在多个结束路径都会调用：
|
||
|
||
```text
|
||
_persist_session(session, result)
|
||
```
|
||
|
||
这让刷新后可以恢复：
|
||
|
||
- 用户消息。
|
||
- assistant 文本。
|
||
- tool_calls。
|
||
- tool result。
|
||
- elapsed。
|
||
- file_history。
|
||
|
||
## 6. 记忆体系
|
||
|
||
实现位置：
|
||
|
||
```text
|
||
src/personal_memory.py
|
||
```
|
||
|
||
### 6.1 文件和数据库
|
||
|
||
```text
|
||
memory.db
|
||
user.md
|
||
skills/<skill-name>.md
|
||
```
|
||
|
||
常量：
|
||
|
||
```text
|
||
src/personal_memory.py:26 MEMORY_DB_FILENAME
|
||
src/personal_memory.py:27 USER_MEMORY_FILENAME
|
||
src/personal_memory.py:28 SKILL_MEMORY_DIRNAME
|
||
```
|
||
|
||
### 6.2 注入逻辑
|
||
|
||
```text
|
||
src/personal_memory.py:102 render_injection
|
||
```
|
||
|
||
注入规则：
|
||
|
||
```text
|
||
1. 读取 user.md。
|
||
2. 根据 enabled_skill_names 读取对应 skills/<skill>.md。
|
||
3. 拼成 # 个性化记忆。
|
||
4. 如果用户本轮要求冲突，以本轮要求为准。
|
||
```
|
||
|
||
后端调用：
|
||
|
||
```text
|
||
backend/api/server.py:1739 memory_manager.render_injection(...)
|
||
```
|
||
|
||
### 6.3 入队逻辑
|
||
|
||
运行结束后：
|
||
|
||
```text
|
||
backend/api/server.py:1920 memory_manager.enqueue_interaction(...)
|
||
```
|
||
|
||
记忆模块内：
|
||
|
||
```text
|
||
src/personal_memory.py:138 enqueue_interaction
|
||
src/personal_memory.py:635 detect_memory_signals
|
||
```
|
||
|
||
会检测：
|
||
|
||
- 显式记忆词：记住、以后、下次、默认、总是、不要、应该、固定。
|
||
- 纠错词：不对、不是这样、格式错、之前说过、还是不行。
|
||
- Skill/工具/流程/格式相关表述。
|
||
- 工具参数非法 JSON 等工具经验。
|
||
|
||
### 6.4 后台整理
|
||
|
||
核心逻辑：
|
||
|
||
```text
|
||
src/personal_memory.py:378 _consolidate_events
|
||
src/personal_memory.py:419 _generate_memory_updates
|
||
src/personal_memory.py:471 _fallback_memory_updates
|
||
```
|
||
|
||
设计取舍：
|
||
|
||
- 主链路不直接生成记忆。
|
||
- 事件先进入 SQLite 队列。
|
||
- 后台 worker 批量整理。
|
||
- LLM 失败时有 fallback 规则。
|
||
- Markdown 是最终可编辑记忆正文。
|
||
|
||
## 7. 可观测性设计
|
||
|
||
当前可观测性来自三个层次：
|
||
|
||
```text
|
||
运行态
|
||
run_manager + run_state_store，支持运行中刷新、停止、恢复活动区。
|
||
|
||
会话态
|
||
session.json，保存完整消息和工具调用。
|
||
|
||
产物态
|
||
session/input、scratchpad、output，文件面板可查看和下载。
|
||
```
|
||
|
||
这个设计让用户不仅看到最终回复，也能看到 Agent 做了什么、文件在哪里、失败在哪个工具或阶段。
|