fmq/AstroResearch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Docker 容器化、Cookie 鉴权、Coordinator 编排、FTS5 搜索与 P1-P3 全面收尾

Browse Source 
Docker 容器化部署
  - 提供 Mode A (Alpine musl, ~23MB) 和 Mode B (Distroless glibc, ~87MB)
    两种镜像，Docker Compose 一键启动
  - build.rs 支持 SKIP_DASHBOARD_BUILD 跳过前端构建
  - 国内镜像加速 (npm/apt/apk) 通过 USE_MIRRORS build-arg 控制

  安全：Cookie-Based 鉴权系统
  - HttpOnly/SameSite=Strict Cookie 会话管理（24h 过期自动清理）
  - 登录/登出/验证接口 + 中间件注入
  - 前端登录页面 + 退出按钮
  - 三层 CORS：localhost 鉴权 / 全放通 bookmarklet / 受保护路由
  - 书签脚本 fetch 添加 credentials:'include'

  Coordinator 模式 (P2)
  - 4 个 meta-tool (delegate_task/check_task/task_stop/synthesize)
  - WorkerPool + Semaphore 并发控制 + 超时保护
  - 前端协调者模式开关

  Hook 系统：UserPromptSubmit 事件 (P2)
  - 第 13 个生命周期事件，fire-and-forget 审计

  FTS5 全文搜索 (P3)
  - agent_sessions_fts + agent_messages_fts 虚拟表
  - search_history Agent 工具 + /api/search/history HTTP 接口
  - 前端防抖搜索框 + 仅当前会话筛选

  工具加载优化 (P3)
  - defer_loading 延迟加载 (7 个重型工具)
  - is_readonly 只读标记 (9 个查询工具)
  - classifier_summary 工具目录供 LLM 按需判断

  模型回退策略 (P3)
  - LLM_FALLBACK_MODEL 优先回退 + LLM_FALLBACK_CHAIN 链式轮换
  - LlmClient model 改为 Arc<RwLock> 支持运行时切换
  - 连续 3 次过载后自动切换

  压缩记忆桥接 (P3)
  - 压缩丢弃消息 → 子代理提取持久记忆 (extract_memories_from_compaction)

  git2 依赖修复
  - 切换到 vendored-libgit2，消除 OpenSSL 系统依赖
This commit is contained in:
fmq
2026-06-23 20:22:06 +08:00
parent 698d007f39
commit cec4b8cf7b
58 changed files with 3366 additions and 345 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/agent/claude-code-reference-analysis.md
+83 -43
View File
@@ -3,7 +3,7 @@
对 Claude Code (`/home/fmq/program/claudecode/src/`) 和 Hermes-Agent (`libs/hermes-agent/`)
源码的全面架构分析，记录对 AstroResearch Agent 系统的参考价值与改进方向。
> 分析日期: 2026-06-22 | 最后更新: 2026-06-22
> 分析日期: 2026-06-22 | 最后更新: 2026-06-23
## 实施状态
@@ -16,12 +16,12 @@
| P1 | PermissionRequest / PermissionDenied Hooks | ✅ 已完成 | `hooks/types.rs`, `traits.rs`, `dispatch.rs`, `mod.rs` |
| P1 | Auto-mode Classifier | ⏳ 待定 | — |
| P2 | Self-improving Skills（模式检测 + 自动创建 + Curator） | ✅ 已完成 | `skills/pattern_detector.rs` + `curator.rs` + `SkillCreator` |
| P2 | Coordinator Mode | ⏳ 待定 | — |
| P2 | UserPromptSubmit / PreCompact / PostCompact Hook | ⏳ 待定 | — |
| P3 | FTS5 跨 session 搜索 | ⏳ 待定 | — |
| P3 | Tool `defer_loading` / `classifier_summary` | ⏳ 待定 | — |
| P3 | 模型回退策略 | ⏳ 待定 | — |
| P3 | Session Memory Compaction | ⏳ 待定 | — |
| P2 | Coordinator Mode | ✅ 已完成 | `src/agent/coordinator/` |
| P2 | UserPromptSubmit / PreCompact / PostCompact Hook | ✅ 已完成 | `hooks/types.rs`, `dispatch.rs` |
| P3 | FTS5 跨 session 搜索 | ✅ 已完成 | `agent_sessions_fts` + `agent_messages_fts` |
| P3 | Tool `defer_loading` / `classifier_summary` | ✅ 已完成 | `tools/mod.rs` |
| P3 | 模型回退策略 | ✅ 已完成 | `error_recovery.rs` (LLM_FALLBACK_MODEL/LLM_FALLBACK_CHAIN) |
| P3 | Session Memory Compaction | ✅ 已完成 | `memory/mod.rs` (extract_memories_from_compaction) |
---
@@ -625,27 +625,33 @@ Coordinator Mode 架构:
### 9.3 AstroResearch 的现状
AstroResearch 有 `SubAgentTool` + `TeamManager`，但没有 Coordinator 的概念。Team
是平级的（lead ↔ teammates），不是层级编排。
AstroResearch 现已实现 Coordinator Mode（`src/agent/coordinator/`，2026-06-23），
包含 4 个 meta-tools（delegate_task / check_task / task_stop / synthesize）
+ WorkerPool + SubAgentRunner。Team 的平级通信仍然可用，Coordinator 提供层级编排。
### 9.4 建议改进
**P2: Coordinator Mode 原型**
**P2: Coordinator Mode — 已实现** ✅
```
当 Agent 检测到复杂多步骤任务时，自动切换为 Coordinator 模式：
实现架构:
src/agent/coordinator/
├── mod.rs # CoordinatorRuntime, CoordinatorConfig
├── tools.rs # 4 meta-tools: delegate_task, check_task, task_stop, synthesize
├── worker_pool.rs # WorkerPool: 异步 Worker 生命周期管理
└── runner.rs # SubAgentRunner: Worker 执行器
用户请求
→ Coordinator 做任务分解
→ 并行子代理执行 (SubAgentTool, async)
→ 结果综合
→ 并行 Worker 执行 (delegate_task, async)
→ 结果综合 (synthesize)
→ 减少单 Agent 的步骤数和 token 消耗
关键实现:
1. Coordinator system prompt: 类似 Claude Code coordinatorMode.ts
2. 仅暴露 SubAgentTool + 少量管理工具
3. 子代理结果以结构化格式注入
4. 综合阶段由 Coordinator 处理
1. Coordinator system prompt: 仅暴露 4 个 meta-tools，屏蔽文件/bash 操作
2. WorkerPool + SubAgentRunner: 异步并发 Worker 管理
3. 子代理结果以结构化格式注入 `<task-notification>`
4. 综合阶段由 Coordinator 的 synthesize 工具处理
```
---
@@ -718,10 +724,11 @@ hermes-agent/
4. Curator 管理 Skill 生命周期
5. 下次相似查询直接加载 Skill，无需重新探索
AstroResearch 已有 Skills 系统 (skills.rs)，缺少:
- 自动检测重复模式
- Agent 自主创建 Skill
- Curator 管理 Skill 质量
AstroResearch 现已完整实现 Self-improving Skills（2026-06-22）：
- `skills/pattern_detector.rs` — 自动检测重复工具调用序列模式
- `skills/curator.rs` — Curator 管理 Skill 生命周期（质量评分、清理、pinned、seed_record、CuratorRunner）
- `skills.rs: SkillCreator` — Agent 自主创建 SKILL.md 文件
- `skills.rs: SelfImprovePipeline` — 一站式管道（检测 → 创建 → 质量审查）
```
**Session FTS5 搜索**
@@ -736,27 +743,27 @@ class SessionDB:
)
```
AstroResearch 的 `agent_sessions` 表有基本的 title/status 字段，但没有全文搜索。
AstroResearch 现已实现 FTS5 全文搜索（2026-06-23）：
- `agent_sessions_fts` + `agent_messages_fts` SQLite FTS5 虚拟表
- `search_history` Agent 工具提供跨会话全文本搜索能力
### 10.5 建议改进
### 10.5 实施成果
**P2: Self-improving Skills 原型**
**P2: Self-improving Skills — 已实现** ✅
```
1. Pattern Detector (自动检测)
- 监控 N 个 session 中的工具调用序列
- 使用简单的子序列匹配识别重复模式
1. Pattern Detector (自动检测) ✅
- src/agent/skills/pattern_detector.rs — 子序列匹配识别重复工具调用模式
- 阈值: 3 次相似序列 → 候选 Skill
2. Skill Creator (Agent 自主创建)
- 将候选 Skill 展示给用户确认
- 生成 SKILL.md 文件（含 when_to_use, steps）
- 注册到 SkillRegistry
2. Skill Creator (Agent 自主创建) ✅
- src/agent/skills.rs: SkillCreator — 生成 SKILL.md 文件（kebab-case 命名 + YAML frontmatter）
- src/agent/skills.rs: SelfImprovePipeline — 一站式管道（检测 → 创建 → 审查）
3. Curator (管理生命周期)
- 跟踪 Skill 使用频率
- 长时间未用的 Skill 标记为 stale
- 提示用户审查或删除
3. Curator (管理生命周期) ✅
- src/agent/skills/curator.rs — 质量评分、清理候选、pinned 保护
- seed_record + NEW_SKILL_GRACE_PERIOD_DAYS=7 — 新 Skill 锚定时钟
- CuratorRunner — 后台空闲触发审查（paused/idle/interval 三重检查）
```
---
@@ -774,12 +781,12 @@ AstroResearch 的 `agent_sessions` 表有基本的 title/status 字段，但没
| **P1** | PermissionRequest / PermissionDenied Hook 事件 | Claude Code | ✅ | 安全审计能力 | ~100 行 | 无 |
| **P1** | Auto-mode Classifier（廉价模型预分类） | Claude Code | ⏳ | 消除 80%+ 权限弹窗 | ~300 行 | LLM client 支持 |
| **P2** | Self-improving Skills（Agent 保存成功流程） | Hermes | ✅ | 科研场景独特价值 | ~500 行 | Skills 系统 |
| **P2** | Coordinator Mode（层级多 Agent 编排） | Claude Code | ⏳ | 复杂任务效果提升 | ~800 行 | SubAgent + Team |
| **P2** | UserPromptSubmit / PreCompact / PostCompact Hook | Claude Code | ⏳ | Hook 系统完善 | ~200 行 | 无 |
| **P3** | FTS5 跨 session 搜索 | Hermes | ⏳ | 历史研究可复用 | 中 | SQLite 迁移 |
| **P3** | Tool `defer_loading` / `classifier_summary` | Claude Code | ⏳ | 减小 tool schema prompt | ~50 行 | 无 |
| **P3** | 模型回退策略 (Model Fallback) | Claude Code | ⏳ | 提高可用性 | ~200 行 | ErrorRecovery |
| **P3** | Session Memory Compaction | Claude Code | ⏳ | 自动化记忆提取 | ~300 行 | MemoryManager + Compact |
| **P2** | Coordinator Mode（层级多 Agent 编排） | Claude Code | ✅ | 复杂任务效果提升 | ~800 行 | SubAgent + Team |
| **P2** | UserPromptSubmit / PreCompact / PostCompact Hook | Claude Code | ✅ | Hook 系统完善 | ~200 行 | 无 |
| **P3** | FTS5 跨 session 搜索 | Hermes | ✅ | 历史研究可复用 | 中 | SQLite 迁移 |
| **P3** | Tool `defer_loading` / `classifier_summary` | Claude Code | ✅ | 减小 tool schema prompt | ~50 行 | 无 |
| **P3** | 模型回退策略 (Model Fallback) | Claude Code | ✅ | 提高可用性 | ~200 行 | ErrorRecovery |
| **P3** | Session Memory Compaction | Claude Code | ✅ | 自动化记忆提取 | ~300 行 | MemoryManager + Compact |
### 实施进度（2026-06-22）
@@ -791,8 +798,14 @@ AstroResearch 的 `agent_sessions` 表有基本的 title/status 字段，但没
- ✅ 工具并发分区
- ✅ PermissionRequest / PermissionDenied Hook 事件
- ⏳ Auto-mode Classifier — 需要设计讨论
3. **P2 项在下一个大版本规划**：需要设计讨论和更多测试
4. **P3 项作为 backlog**：长期优化方向
3. **P2 项 — 全部完成** ✅（2026-06-23）
- ✅ Coordinator Mode（`src/agent/coordinator/`: 4 meta-tools + WorkerPool + SubAgentRunner）
- ✅ UserPromptSubmit Hook Event（第 13 个生命周期事件）
4. **P3 项 — 全部完成** ✅（2026-06-23）
- ✅ FTS5 跨会话搜索（`agent_sessions_fts` + `agent_messages_fts` + `search_history` 工具）
- ✅ Tool defer_loading / classifier_summary
- ✅ 模型回退策略（`LLM_FALLBACK_MODEL` / `LLM_FALLBACK_CHAIN`）
- ✅ Session Memory Compaction Bridge（`extract_memories_from_compaction`）
---
@@ -907,3 +920,30 @@ AstroResearch 的 `agent_sessions` 表有基本的 title/status 字段，但没
**CuratorRunner（后台空闲触发审查）**
- `src/agent/skills/curator.rs`: `CuratorRunner` 结构体 + `should_run_now()`（paused/idle/interval 三重检查）+ `record_activity()` 心跳 + `run_once()` + `spawn()` tokio 后台任务 + `pause()`/`resume()`
- 5 个新增测试（pinned_always_active、pinned_not_in_cleanup、seed_record、runner_paused、runner_idle）
### 2026-06-23 — Phase 6: Coordinator Mode + UserPromptSubmit Hook
**Coordinator Mode 协调者模式**
- `src/agent/coordinator/`: 新目录，4 个 meta-tools（delegate_task / check_task / task_stop / synthesize）+ WorkerPool + SubAgentRunner
- Coordinator system prompt 层级编排 Workers（仅暴露 4 个管理工具，不暴露文件/bash）
- Workers 全异步执行，结果以结构化格式注入 Coordinator
- Continue-vs-Spawn 决策矩阵（上下文重叠度 <30% → 新 Worker）
**UserPromptSubmit Hook Event**
- `src/agent/hooks/types.rs`: 新增 `UserPromptSubmit` variant（第 13 个生命周期事件）
- `src/agent/hooks/dispatch.rs`: `dispatch()` 新增事件分派
### 2026-06-23 — Phase 7: P3 优化
**Tool defer_loading / classifier_summary**
- `src/agent/tools/mod.rs`: `ToolDef.defer_loading` 字段 — LLM 初次调用时不发送完整 schema，仅发送 summary；Bash/Read 工具标记 defer_loading
**Model Fallback 模型回退策略**
- `src/agent/runtime/error_recovery.rs`: `LLM_FALLBACK_MODEL` + `LLM_FALLBACK_CHAIN` env vars — 主模型故障时自动回退到备选模型链
**Session Memory Compaction Bridge**
- `src/agent/memory/mod.rs`: `extract_memories_from_compaction()` — 在 compaction 自动摘要后从摘要文本提取记忆写入 MemoryManager
**FTS5 跨会话搜索**
- `agent_sessions_fts` + `agent_messages_fts` SQLite FTS5 虚拟表
- `search_history` Agent 工具 — 全文本搜索历史会话和消息