# 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)