fmq
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 等变量说明
60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# AstroResearch Contributing Guide / 参与贡献
|
|
|
|
我们欢迎社区共同参与 AstroResearch 的开发与优化。
|
|
|
|
环境搭建和项目结构详见 **[开发指南](development.md)**。
|
|
|
|
---
|
|
|
|
## 1. 项目结构约定 (Project Structure Conventions)
|
|
|
|
---
|
|
|
|
## 2. 编码规范 (Coding Style Guidelines)
|
|
|
|
### Rust 规范 (Backend)
|
|
- 遵循 Rust 官方标准样式，提交前必须执行 `cargo fmt` 与 `cargo clippy`。
|
|
- 注释和系统日志建议统一使用中文，便于开发者追踪和阅读。
|
|
- API handlers 中的异常信息请使用 `anyhow` 或 `thiserror` 进行结构化抛出。
|
|
- **模块化原则**：API 层按职责拆分文件（papers / notes / sync / helpers），避免单文件过大（目标 <800 行）。
|
|
- **错误诊断约定**：下载失败时使用 `error:` 前缀存入 `pdf_path` / `html_path`，便于前端和 `health_check` 工具解析。
|
|
|
|
### React & TypeScript 规范 (Frontend)
|
|
- 严格遵循 `React 18/19` 函数式组件写法，使用 React Hooks 维护状态。
|
|
- 为保证生产编译成功，务必开启类型安全限制（如在导入纯类型时显式使用 `import type { ... }`）。
|
|
- CSS 层面使用 Tailwind CSS 统一的高对比度浅色纯中文控制台风格，所有布局、间距、颜色需遵循实边框、高对比度黑白字及高雅按钮样式（`.btn-console` 等），以保障学术沉浸与阅读的高保真性。
|
|
- **下拉选择器统一使用 `CustomSelect` 组件**，不要使用原生 `<select>`。
|
|
- **新增 API 字段**：后端 `StandardPaper` 新增字段时，必须同步更新 `dashboard/src/types.ts` 中的 `StandardPaper` 接口。
|
|
|
|
---
|
|
|
|
## 3. 测试与验证 (Testing)
|
|
|
|
### 运行后端单元测试
|
|
系统为各个下载、解析、词典分词、接口提取等模块设计了健全的测试。运行测试命令：
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
### 运行前端校验
|
|
```bash
|
|
cd dashboard
|
|
npm run build # 运行 TypeScript 类型检查及 Vite 打包编译
|
|
```
|
|
确保无编译 Error 或 Warn 警告后方可提交 PR。
|
|
|
|
### 运行健康检查工具
|
|
提交前建议对本地馆藏运行健康检查，确保功能正常：
|
|
```bash
|
|
cargo run --bin health_check
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 数据库迁移 (Database Migrations)
|
|
|
|
添加新的数据库字段或表时，需在 `migrations/` 目录下创建新的迁移脚本：
|
|
1. 文件命名格式：`YYYYMMDDHHMMSS_description.sql`
|
|
2. 迁移脚本会在 `cargo run` 启动时自动执行
|
|
3. 新增字段需同时在后端 `StandardPaper` 结构体和前端 `types.ts` 中同步更新
|