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 等变量说明
2026-06-18 01:21:02 +08:00
parent 49784739fa
commit f6df9d8136
60 changed files with 9913 additions and 1844 deletions
@@ -0,0 +1,107 @@
+# AstroResearch Development Guide / 开发指南
+
+## 快速开始
+
+### 后端 (Rust)
+
+```bash
+# 前置：Rust 1.75+，可选 sqlx-cli
+cargo install sqlx-cli --no-default-features --features sqlite
+
+# 启动开发模式
+cargo run                              # 默认模式
+cargo run --features obscura-inprocess # 进程内浏览器
+
+# 运行 CLI / 工具
+cargo run --bin astroresearch_cli
+cargo run --bin health_check           # 只读诊断
+cargo run --bin health_check -- --fix  # 自动修复
+```
+
+### 前端 (React + Vite)
+
+```bash
+cd dashboard
+npm install
+npm run dev      # HMR 开发服务器 :5173，/api → :8000
+```
+
+### 构建命令
+
+```bash
+# Rust
+cargo build                          # Debug
+cargo build --release                # Release (速度优化)
+cargo build --profile release-min    # Release (体积优化, LTO)
+
+# 前端
+cd dashboard && npm run build        # → dashboard/dist/
+
+# Lint & Format
+cargo clippy
+cargo fmt
+
+# 测试
+cargo test                           # 全部测试
+cargo test --lib                     # 单元测试
+cargo test test_name                 # 指定测试
+```
+
+## 项目结构
+
+```
+src/
+├── main.rs              # Axum 服务入口、路由注册
+├── lib.rs               # Config 配置加载
+├── api/                 # HTTP handlers + AppState
+├── agent/               # ReAct 智能体引擎
+│   ├── runtime/         #   ReAct 循环 + 流式执行 + Token 管理
+│   ├── tools/           #   工具定义 (filesystem/ astro/ memory/ team/)
+│   ├── compact/         #   上下文压缩
+│   ├── memory/          #   项目记忆管理
+│   ├── team/            #   多 Agent 团队
+│   ├── hooks.rs         #   生命周期事件
+│   ├── skills.rs        #   技能注册表
+│   └── subagent.rs      #   隔离子代理
+├── clients/             # 外部 API 客户端 (ADS, arXiv, LLM, Qiniu)
+├── services/            # 业务逻辑 (search, download, parser/, translation, rag, batch/)
+└── bin/                 # 独立二进制 (cli, health_check, reparse)
+```
+
+## 环境变量
+
+参见 `.env.example`，关键变量：
+
+| 变量 | 默认 | 说明 |
+|:---|:---|:---|
+| `DATABASE_URL` | `sqlite://library/astro_research.db` | SQLite 路径 |
+| `ADS_API_KEY` | — | NASA ADS API Token |
+| `LLM_API_KEY` / `LLM_API_BASE` / `LLM_MODEL` | OpenAI 默认值 | LLM 配置 |
+| `LLM_MODEL` | `gpt-4o-mini` | Agent/Skills 继承模型 |
+| `SKILLS_DIR` | `./skills` | Agent Skills 目录 |
+| `PORT` | `8000` | 服务端口 |
+
+Agent 调优参数：`AGENT_MAX_STEPS` (8)、`AGENT_TOOL_TIMEOUT_SECS` (120)、`AGENT_CONTEXT_CHAR_LIMIT` (16000)。
+
+## 代码规范
+
+- Rust: `cargo fmt` + `cargo clippy`，提交前必须通过
+- 不可变性优先：使用 `let` 默认，必要时才 `let mut`
+- 错误处理：应用层用 `anyhow`，库层用 `thiserror`
+- 参数化 SQL：`sqlx::query("...").bind(...)`，禁止字符串拼接
+- 文件组织：按功能域拆分，单文件 200-400 行，上限 800 行
+- Hook 检查：`PreToolUse` / `PostToolUse` / `Stop` 生命周期
+
+## 测试
+
+- 单元测试：`#[cfg(test)]` 模块内联在源文件中
+- 集成测试：`tests/` 目录
+- 目标覆盖率：80%+
+
+## 相关文档
+
+- [架构设计](architecture.md)
+- [API 接口](api.md)
+- [数据库设计](database.md)
+- [部署指南](deployment.md)
+- [参与贡献](contributing.md)