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

7.7 KiB

Raw Blame History

Agent 环境变量参考

Agent 系统的所有可配置参数，按子系统分类。

1. AgentConfig — ReAct 循环核心参数

AgentConfig::from_env_optional() 加载，所有变量可选，缺失时使用默认值。

变量	默认值	类型	说明
`AGENT_MAX_STEPS`	8	usize	单轮对话中最大 ReAct 迭代步数。到达后强制终止，注入"请根据已有信息直接给出最终答案"消息，调用 `final_answer_without_tools()` 不带工具生成最终回答。
`AGENT_TOOL_TIMEOUT_SECS`	120	u64	单个工具调用的超时时间（秒）。`read_file` / `grep_files` 等快速工具通常 <1s；`download_paper` 可能需要 30-60s。超时后返回 `ToolOutput::error`，不终止整个 turn。
`AGENT_MAX_TOOL_OUTPUT_CHARS`	4000	usize	工具输出截断字符数。超过此值的输出被截断并在尾部附加 `[已截断，原始 N 字符]`。大文件的完整内容可通过 `maybe_persist_tool_result()` 写入磁盘，返回文件路径指针。
`AGENT_CONTEXT_CHAR_LIMIT`	16000	usize	上下文字符估算上限。用于 `rough_estimate_tokens` 与 micro_compact 层的触发判断。仅在 LLM 不返回精确 token 计数时作为后备。
`AGENT_TOKEN_SOFT_LIMIT`	32000	usize	Token 预算软限制。达到 80% 时注入 💡 "Token 预算提示"；达到 100% 时注入 🟡 "Token 预算警告"；同时作为自动压缩的触发阈值（`estimated_tokens > soft_limit`）。
`AGENT_TOKEN_HARD_LIMIT`	40000	usize	Token 预算硬限制。达到时注入 🔴 "已耗尽" 消息，强制要求模型立即给出最终答案。error recovery escalate 步骤可临时提升此值到 64,000。
`AGENT_MAX_MESSAGES`	50	usize	snip_compact (Layer 0) 的触发阈值。消息数超过此值时截断中间段：保留前 3 条 + 后 47 条，中间替换为含工具名称列表的占位消息。

硬编码参数（非环境变量，修改需改代码）：

参数	值	位置	说明
`duplicate_call_threshold`	3	`AgentConfig`	工具连续以相同参数调用 3 次判定为死循环
`HEAD_KEEP`	3	`compact.rs`	snip_compact 保留的头部消息数
`MAX_CONSECUTIVE_FAILURES`	3	`circuit_breaker.rs`	压缩熔断器触发阈值
`AUTO_RECOVERY_TIMEOUT_SECS`	300	`circuit_breaker.rs`	熔断器自动恢复等待时间
`MAX_ENTRIES`	100	`file_cache.rs`	文件状态缓存条目上限
`MAX_CACHE_SIZE_BYTES`	25 MB	`file_cache.rs`	文件状态缓存内容总大小上限
`POST_COMPACT_MAX_FILES_TO_RESTORE`	5	`file_cache.rs`	压缩后恢复的文件数
`POST_COMPACT_MAX_CHARS_PER_FILE`	4,000	`file_cache.rs`	每文件恢复内容的字符上限
`nag_after_steps`	3	`runtime/mod.rs`	TodoWrite 提醒间隔（步数）
`MAX_BACKOFF_RETRIES`	10	`runtime/mod.rs`	429/529 退避重试最大次数

2. 错误恢复

变量	默认值	说明
`FALLBACK_MODEL`	—	529 连续过载 3 次时尝试切换的备用模型名称。当前仅记录日志，因 `LlmClient` 的 model 不可变。需配合支持 model override 的客户端使用。

3. 自动记忆提取 (`memory/extraction.rs`)

ExtractionConfig::from_env() 加载。在每次会话结束时，可选地使用受限子代理分析对话内容并自动提取值得保留的记忆。

变量	默认值	说明
`EXTRACT_MEMORY_ENABLED`	false	是否启用自动记忆提取。默认关闭以避免意外的 LLM 费用。提取在 turn 结束时 fire-and-forget 执行，不阻塞会话关闭。如果主代理已通过 `save_memory` 工具写入过记忆，则跳过提取。
`EXTRACT_MEMORY_THROTTLE_TURNS`	3	最小提取间隔（轮次）。避免每轮都消耗 LLM 调用进行提取。
`EXTRACT_MEMORY_MAX_STEPS`	3	提取子代理的最大 ReAct 步数。提取使用受限工具集（read_file, grep_files, glob_files, save_memory），步数较少以控制成本。

4. Agent 关联的系统级环境变量

以下变量在 Config::from_env() 中加载，直接影响 Agent 运行时。

4.1 核心 API

变量	默认值	说明
`LLM_API_KEY`	—	LLM API 密钥（OpenAI 兼容协议）
`LLM_API_BASE`	`https://api.openai.com/v1`	LLM API 基础地址
`LLM_MODEL`	`gpt-4o-mini`	Agent 使用的对话模型
`EMBEDDING_API_KEY`	同 `LLM_API_KEY`	Embedding API 密钥
`EMBEDDING_API_BASE`	同 `LLM_API_BASE`	Embedding API 基础地址
`EMBEDDING_MODEL`	`text-embedding-3-small`	RAG 使用的向量模型
`EMBEDDING_DIM`	1536	向量维度。与 `vec_paper_chunks` 表的维度校验相关，不匹配时自动重建。
`ADS_API_KEY`	—	NASA ADS API Token（`search_papers` 工具使用）

4.2 本地路径与端口

变量	默认值	说明
`DATABASE_URL`	`sqlite://library/astro_research.db`	SQLite 数据库路径
`LIBRARY_DIR`	`./library`	文献下载/解析/缓存的根目录
`SKILLS_DIR`	`./skills`	Agent Skills 目录，SkillRegistry 从此加载 `{name}/SKILL.md`
`PORT`	8000	Axum 服务监听端口

4.3 云存储与解析

变量	默认值	说明
`QINIU_AK`	—	七牛云 Access Key（PDF 配图托管）
`QINIU_SK`	—	七牛云 Secret Key
`QINIU_BUCKET`	—	七牛云存储空间名
`QINIU_DOMAIN`	—	七牛云 CDN 域名
`MINERU_API_URL`	—	MinerU PDF 解析远程 API 地址
`MINERU_API_KEY`	—	MinerU API Token

4.4 日志

变量	默认值	说明
`LOG_LEVEL`	`info,astroresearch=debug`	日志级别：trace / debug / info / warn / error，可指定模块级别
`LOG_FORMAT`	`pretty`	日志格式：`pretty`（彩色控制台）或 `json`（结构化）
`LOG_OUTPUTS`	`stdout,file`	日志输出目标，逗号分隔：`stdout`（控制台）、`file`（滚动文件）
`LOG_DIR`	`./logs`	日志文件目录（仅 `LOG_OUTPUTS` 含 `file` 时生效），按天滚动

4.5 其他

变量	默认值	说明
`OBSCURA_ROTATE_PROFILE`	`true`	Obscura 浏览器 Profile 轮换，用于绕过 Cloudflare/WAF
`OBSCURA_ALLOW_PRIVATE_NETWORK`	—	Obscura 内网访问许可（程序自动设置，无需手动配置）

5. 与模型 Context Window 的配置建议

推荐的配置比例（为多轮对话预留空间）：

模型 Context	建议 soft_limit	建议 hard_limit	说明
128K (GPT-4o)	32,000 (25%)	40,000 (31%)	默认值适用
128K (Claude)	32,000 (25%)	64,000 (50%)	Claude 200K 则向上调整
200K (Claude)	64,000 (32%)	100,000 (50%)	大 context 可更宽松
32K (旧模型)	8,000 (25%)	16,000 (50%)	小 context 需更激进压缩

6. 关键源文件索引

文件	加载的变量
`src/lib.rs` (Config)	`LLM_API_KEY`, `LLM_API_BASE`, `LLM_MODEL`, `EMBEDDING_`, `ADS_API_KEY`, `DATABASE_URL`, `LIBRARY_DIR`, `SKILLS_DIR`, `PORT`, `QINIU_`, `MINERU_*`
`src/main.rs`	`EMBEDDING_DIM`
`src/services/logging.rs`	`LOG_LEVEL`, `LOG_FORMAT`, `LOG_OUTPUTS`, `LOG_DIR`
`src/agent/runtime/mod.rs` (AgentConfig)	`AGENT_MAX_STEPS`, `AGENT_TOOL_TIMEOUT_SECS`, `AGENT_MAX_TOOL_OUTPUT_CHARS`, `AGENT_CONTEXT_CHAR_LIMIT`, `AGENT_TOKEN_SOFT_LIMIT`, `AGENT_TOKEN_HARD_LIMIT`, `AGENT_MAX_MESSAGES`
`src/agent/runtime/mod.rs` (call_llm_with_recovery)	`FALLBACK_MODEL`
`src/agent/memory/extraction.rs` (ExtractionConfig)	`EXTRACT_MEMORY_ENABLED`, `EXTRACT_MEMORY_THROTTLE_TURNS`, `EXTRACT_MEMORY_MAX_STEPS`
`src/services/download.rs`	`OBSCURA_ALLOW_PRIVATE_NETWORK`（程序自动设置）

7.7 KiB Raw Blame History Unescape Escape