Asfmq
f6df9d8136
- 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 等变量说明
108 lines
3.3 KiB
Markdown
108 lines
3.3 KiB
Markdown
# 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)
|