merge: integrate main and reconcile export dependencies

docs/contracts/第二阶段接口契约-开发版.md

@@ -1592,3 +1592,27 @@ CUDA 组件：`GET /api/local-models/runtime-components/cuda` 返回 status、st
 | `POST /api/providers/request-probe` | 输入 `{provider:ProviderCreateRequest, stream:boolean}`；固定短消息真实聊天推理，45 秒超时。成功返回 success/stream/model/message；空响应 422、供应商错误 502、超时 504。只使用 credential_id，不接收明文密钥。 |
 
 请求预览新增 capability 选择（chat/embedding/transcription/speaker_matching），仍只返回隐藏正文的请求体。实际扩展字段是否被供应商接受，以推理响应为准。
+# 聊天检索与 Markdown 工具补充（2026-09-06）
+
+`/api/chat` 在 `use_rag=true` 且 Provider 声明 `tool_calling` 时允许最多 3 轮只读补检索。SSE 事件类型不变，只有最终轮发送 `Done`；`Usage` 为模型轮次累计值。`Citation.number` 在同一回复内稳定，新增来源追加编号；候选来源不等于已引用来源，前端按正文 `[n]` 展示。`ToolCallEnd.data.status` 可为 `completed` 或 `failed`，表示执行结果而非参数接收完成。
+
+工具目录新增 `markdown.catalog`、`markdown.compose`、`notes.patch_markdown`。`notes.read` 输出新增 `content_hash`；局部修改须携带 SHA-256 `expected_content_hash`、唯一匹配的 `old_text` 和替换值 `new_text`，沿用 `notes.write` 权限。详细边界及验证方法见 [聊天按需检索与 Markdown 工具](../development/聊天按需检索与Markdown工具.md)。
+
+
+## 工作区聊天与智能体委托补充（2026-09-06）
+
+- `ChatRequest.workspace_context`：可选 `{ file_path, content }`，传递当前编辑器快照，含未保存编辑。内容上限 200 万字符。
+- `ChatRequest.allow_agent`：默认 `false`；开启且 Provider 支持工具调用时提供 `agent.create` 与 `agent.status`。每个回答最多创建一次，执行仍受原有工具白名单、预算和权限机制约束。
+- `ChatMessage.workspace_context`：保存发送时的文件快照，列表和版本恢复接口返回同一数据；现有聊天记录接口供工作区浮窗与完整聊天页共享。
+- `ToolCallEnd.data.result`：智能体工具返回 `{ run_id, status, output?, error? }`，消息工具记录以 JSON 字符串持久化此结果，客户端展示运行入口。
+
+
+## 聊天附件补充（2026-09-06）
+
+`/api/media/attachments` 新增允许 DOCX、PPTX、PPT、PNG、JPG/JPEG、WebP 后缀。聊天通过 `ChatRequest.attachments` 提交最多 8 个持久化附件 ID，并通过 `ChatMessage.attachments` 恢复记录。`image_fallback_tools` 最多两个注册工具名，服务端固定 MCP 优先、Plugin 次之，不接受任意命令或远程下载 URL。
+
+内部模型 `Message.images` 使用有大小限制的 PNG/JPEG/WebP base64 data URI，Provider 适配器转换为各自原生协议。文档和音频提取为参考文本后才交给普通聊天，清除已解析的二进制附件标记，使文本上下文检测仍可工作。附件失败返回 `CHAT_ATTACHMENT_FAILED`，进度与截断提示使用 `ContextStatus`，不将失败附件当作已读取内容。
+
+#### 回答版本的上下文快照（2026-09-07）
+
+`ChatMessage.context_captured` 为布尔值，旧记录默认 false。新 assistant 消息保存本次请求的 `workspace_context` 和 `attachments`，并设置 context_captured 为 true；此时 null 文件上下文和空附件列表都是明确快照。重新生成不覆盖原 user 消息的快照。客户端恢复旧记录时仅在 context_captured 为 false 时回退到对应父用户消息。