Mini Agent Runtime

提交材料位置

• 代码链接：https://github.com/sodie2323/mini-agent-runtime
• 补充材料位置：https://github.com/sodie2323/mini-agent-runtime/releases/tag/submission-v1
  • 终端操作录屏：demo-recording.mp4
  • AI Prompt 与问题解决记录：ai-prompt-and-notes.md
  • 架构设计题回答：architecture-answers.md
• README：当前文件

从零实现的最小工具型 Agent Runtime。主流程自行实现，没有依赖现成 Agent 框架。

1. 运行方式

cd mini-agent
cp .env.example .env

编辑 .env，填入真实 DeepSeek Key：

LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-xxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-pro

运行测试：

npm test

启动终端版：

npm run cli -- --user A --session window1

另开独立 session：

npm run cli -- --user A --session window2

重新打开同一个 userId + sessionId 会加载历史消息。

2. 系统设计

核心文件：

src/agent/runtime.js      Agent 主循环
src/agent/llm.js          DeepSeek / OpenAI-compatible LLM 调用
src/agent/parser.js       解析 thought / tool_calls / final answer
src/agent/context.js      Context 构建与压缩
src/tools/registry.js     工具注册与参数校验
src/storage/jsonStore.js  Session 持久化

Agent Loop：

1. 接收用户输入。
2. 读取当前 userId + sessionId 的 session。
3. 构建 context：summary、todos、memory、最近消息、tool schemas。
4. 调用真实 LLM API。
5. 解析 LLM 输出：短 thought、tool calls 或 final answer。
6. 有工具调用则执行工具，把结果写回 role=tool message。
7. 继续 loop，直到最终答案或达到最大轮次。

已实现工具：

calculator  四则运算
search      mock 搜索
weather     mock 天气
todo        session 级待办
memory      长期记忆

Session 隔离：

sessionKey = userId + sessionId

例如 A:window1 和 A:window2 的 messages / todos / traces / queue 相互独立。

Context 管理：

• 最近消息进入 context，支持追问。
• 工具调用和工具结果进入 messages，支持带工具的追问。
• context 过长时压缩旧消息到 session.summary。
• 压缩时避免拆开 assistant tool call 和 tool result。

CLI 会按执行顺序同步显示工具开始和工具结果。

3. Memory 的召回时机与放置方式

Memory 分三层：

1. Core Memory：常驻上下文，保存用户稳定偏好和当前目标。
2. Recall Memory：历史对话/事件，最终回答后自动写入。
3. Archival Memory：长期事实/偏好/目标，通过关键词检索召回。

召回策略：

• Core Memory：每轮固定注入，因为它是稳定用户状态。
• Recall / Archival Memory：不在每轮自动召回；模型需要历史信息时，通过 memory 工具发起 function call：recall_search 或 archival_search。

执行位置：

src/agent/runtime.js        每轮只读取 Core Memory 并放入 system context
src/tools/memory.js         提供 recall_search / archival_search 工具动作
src/storage/userMemoryStore.js  执行关键词 Top-K 检索

放置方式：

System Prompt
Session Summary
Open Todos
Core Memory
Recent Messages
Tool Schemas

当模型调用 memory.recall_search 或 memory.archival_search 后，检索结果会作为 role=tool message 写回当前 session，再进入下一轮 LLM context。

长期 memory metadata 包含：

id / layer / userId / kind / tags / sourceSessionId / sourceToolCallId /
confidence / importance / accessCount / lastAccessedAt / createdAt / updatedAt