feat: Agent 思考模式前端可控、子代理全链路持久化、权限系统、工具 ID 追踪体系、前端面板与文档架构重构

- AgentConfig/LlmClient 新增 enable_thinking 参数，前端 SSE 请求传递 thinking
  开关，仅千问/DashScope 时启用
  - 完善权限系统，支持细粒度的权限控制和用户权限申请
  - delegate_research 工具重命名为 subagent，SubAgentTool/SubAgentRunner 重构
  - 子代理消息（system/user/assistant/tool）持久化到 agent_messages 表，带 agent_name 标识
  - 子代理活动日志（工具调用列表+思考摘要）注入返回结果，Hooks 获得正确 session_id 和 subagent_name
  - LLM 工具调用 ID 回退生成 UUID（llm.rs），ToolCall/ToolResult SSE 事件增加 id/tool_call_id 双字段
  - ToolContext 扩展 session_id/sse_tx/enable_thinking 字段，executor 统一注入而非构造函数传参
  - agent_messages 新增 metadata+raw_json 列，agent_sessions 暴露 summary 字段
  - 删除文件级 transcript 快照（compact.rs），改为依赖 DB 持久化
  - ResearchAgentPanel 重写：TimelineItem 类型替代 StreamStep，支持会话历史回放
  - 新增 AgentMetricsPanel/AskUserQuestionCard/AuditLogViewer 三个前端组件，types.ts 完整类型定义
  - docs/architecture/ 分层重组：概览/核心模块/核心工作流 + agent/ 子目录 11 篇专题文档
  - docs/api.md 补充 RAG/Target/Agent 接口，docs/development.md 新建开发指南
  - .env.example 完全重写，补充 FALLBACK_MODEL 等变量说明

docs/api.md

@@ -517,6 +517,93 @@ export interface SavedSyncQuery {
 
 ---
 
+### 2.8 RAG 问答与天体目标识别 (RAG & Target)
+
+#### 2.8.1 RAG 文献问答
+- **Endpoint**: `POST /api/chat/rag`
+- **Description**: 基于本地向量库进行 RAG 检索增强生成，回答天文学相关问题。
+- **Request Body**:
+  ```json
+  {
+    "question": "什么是赫罗图？",
+    "limit": 5
+  }
+  ```
+- **Response Schema**:
+  ```json
+  {
+    "answer": "...",
+    "sources": [{"bibcode": "...", "title": "...", "relevance": 0.95}]
+  }
+  ```
+
+#### 2.8.2 图表问答
+- **Endpoint**: `POST /api/chat/figure`
+- **Description**: 对文献中的图表进行问答分析。
+
+#### 2.8.3 天体目标查询
+- **Endpoint**: `GET /api/target/query`
+- **Query Parameters**: `name` (string, required) — 天体名称。
+- **Description**: 通过 CDS Sesame 服务查询天体坐标和基本信息。
+
+#### 2.8.4 天体目标关联
+- **Endpoint**: `POST /api/target/associate`
+- **Description**: 将识别出的天体目标与文献 Bibcode 关联。
+
+#### 2.8.5 天体目标提取
+- **Endpoint**: `POST /api/target/extract`
+- **Description**: 从文本中自动提取 IAU 标准天体名称。
+
+#### 2.8.6 天体目标列表
+- **Endpoint**: `GET /api/target/list`
+- **Description**: 获取所有已提取的天体目标列表。
+
+---
+
+### 2.9 智能体模块 (Agent)
+
+#### 2.9.1 SSE 流式对话
+- **Endpoint**: `POST /api/chat/agent`
+- **Description**: 创建或恢复智能体会话，通过 SSE (Server-Sent Events) 流式返回 ReAct 循环的思考/工具调用/结果。
+- **Request Body**:
+  ```json
+  {
+    "question": "搜索并下载最近关于暗物质晕的论文",
+    "session_id": null
+  }
+  ```
+- **SSE Event Types**: `thought`, `tool_call`, `tool_result`, `text_delta`, `usage`, `error`, `done`。
+
+#### 2.9.2 会话管理
+- `GET /api/chat/sessions` — 列出所有会话（支持 `?limit=&offset=` 分页）。
+- `GET /api/chat/sessions/:id` — 获取会话详情（含消息历史）。
+- `DELETE /api/chat/sessions/:id` — 软删除一个会话。
+- `POST /api/chat/sessions/:id/stop` — 终止正在运行的会话。
+
+#### 2.9.3 Agent 运行指标
+- **Endpoint**: `GET /api/chat/metrics`
+- **Description**: 返回聚合的智能体运行指标。
+- **Response Schema**:
+  ```json
+  {
+    "total_sessions": 42,
+    "total_tool_calls": 318,
+    "tool_call_breakdown": {"read_file": 120, "search_papers": 85, "run_bash": 43},
+    "avg_steps_per_session": 7.6,
+    "error_rate": 0.03
+  }
+  ```
+
+#### 2.9.4 会话审计日志
+- **Endpoint**: `GET /api/chat/sessions/:id/audit`
+- **Description**: 返回指定会话的工具调用审计日志（工具名、状态、耗时、输出预览）。
+
+#### 2.9.5 人机交互问答
+- `GET /api/chat/questions` — Agent 发出的待处理问题列表。
+- `POST /api/chat/answer` — 用户回答 Agent 提出的问题，推进任务执行。
+
+---
+
 ## 3. 完整路由表 (Route Summary)
 
 | 方法 | 路径 | 说明 |
@@ -542,6 +629,21 @@ export interface SavedSyncQuery {
 | `GET` | `/api/sync/asset/status` | 查询资源处理状态 |
 | `GET` | `/api/sync/queries` | 获取已保存检索条件 |
 | `DELETE` | `/api/sync/queries/:id` | 删除已保存检索条件 |
+| `GET` | `/api/chat/sessions` | 列出所有智能体会话 |
+| `GET` | `/api/chat/sessions/:id` | 获取会话详情与消息历史 |
+| `DELETE` | `/api/chat/sessions/:id` | 软删除指定会话 |
+| `POST` | `/api/chat/sessions/:id/stop` | 终止正在运行的会话 |
+| `GET` | `/api/chat/metrics` | 聚合智能体运行指标 |
+| `GET` | `/api/chat/sessions/:id/audit` | 获取会话工具调用审计日志 |
+| `GET` | `/api/chat/questions` | Agent 发出的待处理问题列表 |
+| `POST` | `/api/chat/answer` | 用户回答 Agent 提出的问题 |
+| `POST` | `/api/chat/agent` | SSE 流式智能体对话 |
+| `POST` | `/api/chat/rag` | RAG 文献问答 |
+| `POST` | `/api/chat/figure` | 图表问答分析 |
+| `GET` | `/api/target/query` | 天体目标查询 |
+| `POST` | `/api/target/associate` | 天体目标关联文献 |
+| `POST` | `/api/target/extract` | 提取文本中的天体目标 |
+| `GET` | `/api/target/list` | 天体目标列表 |
 | `GET` | `/api/active_bibcode` | 获取当前活跃文献 |
 | `POST` | `/api/active_bibcode` | 设置当前活跃文献 |