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 等变量说明
3.3 KiB
3.3 KiB
AstroResearch Development Guide / 开发指南
快速开始
后端 (Rust)
# 前置：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)
cd dashboard
npm install
npm run dev # HMR 开发服务器 :5173，/api → :8000
构建命令
# 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%+