feat:再优化时间戳

Author: NyxJae

.snow/notebook/snow-cli.json

@@ -0,0 +1,47 @@
+{
+  "source/api/anthropic.ts": [
+    {
+      "id": "notebook-1770694883398_3ow0urpes",
+      "filePath": "source/api/anthropic.ts",
+      "note": "**职责**: Anthropic API 适配器,负责将内部 ChatMessage 格式转换为 Anthropic 消息格式\n\n**接口摘要**:\n- 输入: ChatMessage[] 消息数组,系统提示词配置\n- 输出: Anthropic 格式的消息和系统提示词\n\n**关键设计决策**:\n- 支持多模态消息(文本+图片)\n- 支持工具调用和工具结果的消息转换\n- 为系统提示词和最后一条 user 消息添加 cache_control 以支持提示词缓存\n\n**依赖拓扑**:\n- 被上层 API 调用层使用\n- 依赖 MainAgentManager 获取系统提示词\n- 依赖 types.js 中的类型定义\n\n**避坑指南**:\n- 多模态消息中图片和文本的处理顺序很重要\n- 注意 cache_control 的放置位置影响缓存命中率",
+      "createdAt": "2026-02-10T11:41:23.398",
+      "updatedAt": "2026-02-10T11:41:23.398"
+    }
+  ],
+  "source/api/chat.ts": [
+    {
+      "id": "notebook-1770694883572_4ydxyl8k0",
+      "filePath": "source/api/chat.ts",
+      "note": "**职责**: OpenAI Chat API 适配器,负责将内部 ChatMessage 格式转换为 OpenAI 消息格式\n\n**接口摘要**:\n- 输入: ChatMessage[] 消息数组,系统提示词配置\n- 输出: OpenAI 格式的 ChatCompletionMessageParam 数组\n\n**关键设计决策**:\n- 支持多模态消息(文本+图片)使用 content 数组格式\n- 支持 tool_calls 和 tool 角色的消息转换\n- 支持 reasoning_content (DeepSeek R1 模型)\n\n**依赖拓扑**:\n- 被上层 API 调用层使用\n- 依赖 MainAgentManager 获取系统提示词\n- 依赖 types.js 中的类型定义\n\n**避坑指南**:\n- 带图片的 user 消息必须使用 content 数组格式\n- tool 角色的消息需要 tool_call_id 字段\n- assistant 带 tool_calls 时需要保留 tool_calls 字段",
+      "createdAt": "2026-02-10T11:41:23.572",
+      "updatedAt": "2026-02-10T11:41:23.572"
+    }
+  ],
+  "source/api/gemini.ts": [
+    {
+      "id": "notebook-1770694883908_ow13cu46t",
+      "filePath": "source/api/gemini.ts",
+      "note": "**职责**: Google Gemini API 适配器,负责将内部 ChatMessage 格式转换为 Gemini 消息格式\n\n**接口摘要**:\n- 输入: ChatMessage[] 消息数组,系统提示词配置\n- 输出: Gemini 格式的 contents 数组和 systemInstruction\n\n**关键设计决策**:\n- 使用 parts 数组结构支持多模态内容\n- 支持 functionCalling 工具调用模式\n- 工具结果以 functionResponse 形式返回\n- 支持 thinking 内容(Gemini thinking 模式)\n\n**依赖拓扑**:\n- 被上层 API 调用层使用\n- 依赖 MainAgentManager 获取系统提示词\n- 依赖 types.js 中的类型定义\n\n**避坑指南**:\n- Gemini 的 system 消息需要提取为 systemInstruction\n- thinking 内容必须放在 parts 数组的第一位\n- 工具结果需要构建 tool_call_id 到 function_name 的映射\n- 多模态工具结果中文本必须在图片之前",
+      "createdAt": "2026-02-10T11:41:23.908",
+      "updatedAt": "2026-02-10T11:41:23.908"
+    }
+  ],
+  "source/api/responses.ts": [
+    {
+      "id": "notebook-1770694883742_l9t553m1w",
+      "filePath": "source/api/responses.ts",
+      "note": "**职责**: OpenAI Responses API 适配器,负责将内部 ChatMessage 格式转换为 Responses API 格式\n\n**接口摘要**:\n- 输入: ChatMessage[] 消息数组,系统提示词配置\n- 输出: Responses API 格式的 input 数组\n\n**关键设计决策**:\n- 使用 type: 'message' 包裹用户消息\n- 文本内容使用 input_text 类型\n- 图片内容使用 input_image 类型\n- 工具调用使用 function.call 和 function.output 类型\n\n**依赖拓扑**:\n- 被上层 API 调用层使用\n- 依赖 MainAgentManager 获取系统提示词\n- 依赖 types.js 中的类型定义\n\n**避坑指南**:\n- Responses API 不支持 system 消息在 input 中,需要放在 instructions\n- user 消息的 content 必须是数组格式\n- 图片 URL 必须是 http(s) URL 或 data URL\n- 工具调用和输出需要配对出现",
+      "createdAt": "2026-02-10T11:41:23.741",
+      "updatedAt": "2026-02-10T11:41:23.741"
+    }
+  ],
+  "source/utils/agentsPromptUtils.ts": [
+    {
+      "id": "notebook-1770694245812_aux171dlv",
+      "filePath": "source/utils/agentsPromptUtils.ts",
+      "note": "**职责**: 生成主代理和子代理的系统环境上下文信息，包括平台、shell、工作目录和时间信息\n\n**接口摘要**: \n- 输入: 无参数\n- 输出: 包含系统环境信息的字符串\n\n**关键设计决策**:\n- 时间戳只放置于角色提示词的系统环境信息中(北京时间，精确到分钟)\n- 不在每条工具返回和user消息中添加时间戳，避免破坏KV缓存命中率\n- 角色提示词随对话进度动态更新插入位置，其内容变化不影响缓存\n\n**依赖拓扑**: \n- 被MainAgentManager.ts调用（主代理系统提示词生成）\n- 被subAgentExecutor.ts调用（子代理系统提示词生成）\n- 依赖getPlatformDisplayName(), getShellDisplayName(), getPlatformCommandsSection()\n\n**避坑指南**:\n- MUST使用北京时间(CST/UTC+8)，确保时间准确性\n- 时间戳只应存在于角色提示词的系统环境信息部分",
+      "createdAt": "2026-02-10T11:30:45.812",
+      "updatedAt": "2026-02-10T11:42:35.663"
+    }
+  ]
+}

requirements/会话中时间戳.md

@@ -15,4 +15,8 @@
 
 最后兜底方案改下,如果当时没记录，那就不加时间戳,而非加现在的时间戳 -->
 
+已完成
+
+<!-- 改下,不再在每条工具返回和user都加时间戳了,而是在 主代理和子代理的 角色提示词(里拼的系统环境信息里加上时间戳)里加,因为角色提示词现在会随对话进度更新其插入位置了,故他内容变化也不对破坏kv缓存等. -->
+
 已完成