Asfmq
b11b8ad015
- AgentConfig: 移除 10+ 个环境变量读取，仅保留 TOKEN_SOFT/HARD_LIMIT 两个
可调参数，context_char_limit 替换为统一的 token_soft_limit 阈值
- compact: find_safe_cut_point 重写为 HashSet O(n) 算法，
micro_compact 改为不可变风格，compress_context 签名升级为
token_soft_limit + max_messages 双参数，新增 COMPACTION_OUTPUT_RESERVE
- modes: ModeConfig.max_steps/tool_timeout_secs 去 Optional 化，
Deep Research 步数 16→100，Literature Reader 步数 6→25
- dashboard: 提取 AgentMarkdown/ThoughtCard/ToolCallCard/AnswerCard/
SubAgentContainer 等共享组件，ResearchAgentPanel 大幅瘦身，
交互卡片重构为 console-panel 紧凑风格
- security: 移除 HERMES_YOLO_MODE、AGENT_BLOCK_NETWORK 开关、
AGENT_CHECKPOINT_ENABLED 开关，关键安全机制强制启用
108 lines
3.4 KiB
Markdown
108 lines
3.4 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_TOKEN_SOFT_LIMIT` (32000)、`AGENT_TOKEN_HARD_LIMIT` (40000)。
|
||
|
||
## 代码规范
|
||
|
||
- 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)
|