Asfmq f6df9d8136 feat: Agent 思考模式前端可控、子代理全链路持久化、权限系统、工具 ID 追踪体系、前端面板与文档架构重构

- 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 等变量说明

2026-06-18 01:21:02 +08:00

8.1 KiB

Raw Blame History

AstroResearch Deployment Guide / 部署指南

AstroResearch 的后端服务是由 Rust 编译出的单执行文件，它内置托管了前端 React 的静态构建资源，因此生产部署十分简单。

1. 系统要求与环境依赖 (Requirements)

操作系统：Linux / macOS / Windows
运行环境：
- Node.js (v18+) 用以构建前端 React 资源
- Rust (1.75+) 用以编译后端 Axum 进程
- SQLite (自动内置，无需单独部署)

2. 生产构建步骤 (Production Build Steps)

步骤 1：构建 React 前端静态资源

进入 dashboard 文件夹，安装依赖并执行编译命令。编译产物会自动输出在 dashboard/dist 目录下：

cd dashboard
npm install
npm run build

步骤 2：编译 Rust 后端二进制文件

返回项目根目录，通过 Cargo 构建 Release 版本的执行文件。编译后的程序会内置链接 dashboard/dist 下的全部静态资源：

cd ..
cargo build --release

编译产物位于 target/release/astroresearch。

步骤 3（可选）：编译健康检查工具

如需在目标服务器上运行馆藏健康度诊断与修复：

cargo build --release --bin health_check

编译产物位于 target/release/health_check。

3. 服务部署与启动 (Running in Production)

将编译出来的 target/release/astroresearch 二进制文件部署到目标服务器。
在二进制文件同一目录下，创建并填写 .env 环境变量配置文件（可从根目录的 .env.example 复制模板）。
确保本地相对路径下拥有天文对照词典文件 dictionary.txt。
运行后端服务：
```
./astroresearch
```
进程将默认在后台启动并监听 http://localhost:8000 端口。你可以通过 Nginx 将此端口反向代理到公网 80/443 端口。

4. Obscura 两种抓取后备部署模式选择 (Obscura Deployment Modes)

系统集成了 Obscura 无头浏览器框架来作为遭遇 WAF/Cloudflare 反爬时的自动后备抓取通道。系统支持以下两种编译与部署模式：

模式 A：外部命令行模式 (默认，推荐)

该模式将主 Web 服务与 V8 浏览器运行引擎相隔离，最适合常规生产环境。它拥有最快的编译时间，且进程隔离确保无头浏览器内核异常（如 OOM 或 Panic）不会拖垮主服务器。

编译主服务：
```
cargo build --release
```
下载/配置外部二进制：从 GitHub Releases 下载编译好的 obscura-x86_64-linux.tar.gz 压缩包，解压后将 obscura 和 obscura-worker 两个二进制文件放到项目根目录的 bin/ 目录下：
```
mkdir -p bin/
# 放入 bin/obscura 和 bin/obscura-worker，并赋予执行权限
chmod +x bin/obscura bin/obscura-worker
```
运行：
```
./target/release/astroresearch
```
当遭遇 WAF 拦截时，主进程将自动通过异步子进程调用 ./bin/obscura 进行抓取。

模式 B：进程内集成模式 (In-Process Feature)

该模式将整个无头浏览器及 V8 运行引擎直接静态链接编译进单个二进制文件中。这免去了在服务器分发和配置外部可执行程序的步骤，提供了”零配置”的部署体验。

Warning

由于需要静态链接 C++ 编写的 V8 引擎，首次编译会额外多耗时 1 到 3 分钟，且最终编译生成的单体可执行文件体积会膨胀约 80MB。

获取 Obscura 依赖源码（仅首次）： libs/ 目录未被 Git 跟踪（已列入 .gitignore），git clone 后需要单独拉取 Obscura 浏览器内核源码：
```
mkdir -p libs
git clone https://github.com/h4ckf0r0day/obscura libs/obscura
```
启用 Feature 编译：在构建时指定 --features obscura-inprocess 特性标记：
```
cargo build --release --features obscura-inprocess
```
运行：
```
./target/release/astroresearch
```
主服务运行期间，无需在磁盘中放置任何 bin/obscura 二进制。当触发反爬时，系统会在后台的专有阻塞线程池上通过独立包装的单线程 runtime 驱动进程内 V8 浏览器内核直接抓取。

5. 极致内存与体积优化部署 (Ultra-Low Memory & Size Optimization)

对于运行在低配/低内存服务器（如 1核512M 或 1核1G 实例）的环境，系统内置了可选的编译与运行时优化策略。

Note

极致内存与体积优化编译配置（release-min）和“进程内集成模式 (In-Process Feature)”在技术上可以完全兼容并共同启用，但它们在优化目标（指标）上是相互抵消（矛盾）的。如果启用了进程内 V8 特性，C++ 静态链接库本身占用的 80MB+ 空间将无法被剔除，导致无法达成极致轻量化（~8.3MB）的体积指标；且 V8 运行时堆内存也会带来额外的物理内存开销。因此，为追求极致低资源消耗，建议在低配服务器上采用**“模式 A：外部命令行模式”**。

如果你执意要在进程内浏览器集成下尽可能对其体积和依赖进行优化，可以组合使用 --profile 与 --features 参数进行编译和运行：
# 编译并打包优化后的进程内单二进制文件：
cargo build --profile release-min --features obscura-inprocess

# 编译并直接运行：
cargo run --profile release-min --features obscura-inprocess

优化指标对比：

二进制执行文件大小：由 17.0 MB 压缩至 8.3 MB（缩减约 51%）。
启动物理常驻内存 (RSS)：由 34.8 MB 降至 32.9 MB（得益于词典加载后的容量自动收缩）。
虚拟内存 (VSZ)：由 1.27 GB 降至 302 MB（缩减约 76%）。
数据段内存 (VmData)：由 60.1 MB 降至 26.5 MB（缩减约 55%）。

部署优化步骤：

使用优化 Profile 进行编译：在项目根目录下，使用内置的 release-min 编译配置：
```
cargo build --profile release-min
```
编译完成后的执行文件位于 target/release-min/astroresearch。该配置开启了 LTO（链接时优化）、剥离了调试符号，并在生成时进行了大小优化。
限制运行时异步线程数：默认情况下，异步运行时 Tokio 会根据系统的 CPU 核心数（例如 16 核）创建对应数量的 Worker 线程，这会带来很多虚拟/物理内存浪费。启动服务时，可通过注入 TOKIO_WORKER_THREADS=1 环境变量限制线程池大小：
```
PORT=8000 TOKIO_WORKER_THREADS=1 ./astroresearch
```

6. 环境变量配置 (Environment Variables)

变量名	必需	默认值	说明
`DATABASE_URL`	否	`sqlite://library/astro_research.db`	SQLite 数据库连接 URL
`ADS_API_KEY`	是	-	NASA ADS API 访问 Token
`LLM_API_KEY`	是	-	大语言模型 API Key
`LLM_API_BASE`	否	`https://api.openai.com/v1`	大语言模型 API 基础地址
`LLM_MODEL`	否	`gpt-4o-mini`	翻译大模型名称
`EMBEDDING_API_KEY`	否	默认与 `LLM_API_KEY` 一致	向量模型 API Key
`EMBEDDING_API_BASE`	否	默认与 `LLM_API_BASE` 一致	向量模型 API 基础地址
`EMBEDDING_MODEL`	否	`text-embedding-3-small`	向量模型名称
`QINIU_AK`	否	-	七牛云 Access Key
`QINIU_SK`	否	-	七牛云 Secret Key
`QINIU_BUCKET`	否	-	七牛云存储空间名
`QINIU_DOMAIN`	否	-	七牛云外链 CDN 域名
`MINERU_API_URL`	否	-	MinerU PDF 解析远程 API 地址
`MINERU_API_KEY`	否	-	MinerU API Token
`LIBRARY_DIR`	否	`./library`	本地文献馆藏根目录
`PORT`	否	`8000`	后端服务监听端口

7. 健康检查与维护 (Health Check)

部署后可定期运行健康检查工具排查馆藏一致性问题：

# 只读扫描（不修改任何数据）
./health_check

# 自动修复（清理损坏文件、重置无效路径）
./health_check -- --fix

详见排障指南 §4.2。

8.1 KiB Raw Blame History Unescape Escape