mirror of
https://github.com/agentscope-ai/ReMe.git
synced 2026-10-08 03:10:24 +00:00
83831ec90c
### 1. Agent Wrapper（统一 Agent 后端抽象） - **`base_agent_wrapper.py`**：`reply()` 返回值从 `tuple[str, Any]` 改为 `dict`（含 `session_id` / `last_message` / `result` / 可选 `structured_output`）；`reply_stream()` 改为产出统一的 `StreamChunk`。废弃 `add_tools()`，改为 `add_job_tools(names: list[str])`（按名解析 BaseJob）与 `add_skills()`；新增 `_resolve_job_tools()`、`_merged_kwargs()`、`_chunk()` 辅助方法及 `project_path` / `project_skills_root` 属性。 - **`as_agent_wrapper.py`（AgentScope 后端）**： - 会话持久化重写：`session_path` 落地到 `<vault>/<session_dir>/agentscope/`，`_load_state` 支持 `resume` / `session_id` / `fork_session`，并做 UUID 校验（`_validate_session_id`）；`_cleanup_expired_sessions` 按天数清理过期会话。 - 新增内置工具集（`BypassAnalysisBash` + Edit/Glob/Grep/Read/Write），`BypassAnalysisBash` 绕过 AgentScope 自带 Bash 静态分析以让 permission_mode 生效；`_resolve_skills()` 把配置的 skill 暴露给后端，`_load_tool_env()` 注入项目 `.env`。 - `_event_to_chunk()` 把 20+ 种 AgentScope 事件（Reply/Text/Thinking/Data/ToolCall/ToolResult/ModelCall/ExceedMaxIters）归一化为 `StreamChunk`。 - **`cc_agent_wrapper.py`（Claude Code SDK 后端，+551 行）**： - 新增 `_CcFileSessionStore`：基于 vault 的文件型会话存储，实现 append（按 uuid 去重）/ load / list / delete / list_subkeys，并对路径做 `_safe_parts` + `resolve()` 防越界校验。 - `_build_options()`：统一构建 `ClaudeAgentOptions`，处理 skills、disallowed_tools（默认禁 `WebSearch`）、`.env` 注入、Claude Code 的 API 凭据解析（`_claude_code_api_env`，多级 base_url/api_key 回退）、`CLAUDE_CONFIG_DIR` 设置、skill 目录软链接（`_ensure_claude_skill_dir`）。 - `_raw_event_to_chunk()` / `_message_content_to_chunks()`：把 Anthropic 流式事件（message_start/delta/stop、content_block_*）与 SDK 消息块（AssistantMessage/UserMessage/ResultMessage/RateLimitEvent）转换为统一 `StreamChunk`；跟踪 block_id/block_type/tool_call_name 做关联；处理尾部 `"success"` 误报异常的吞掉逻辑。 ### 2. 统一流式协议（StreamChunk / ChunkEnum） - **`stream_chunk.py`**：`StreamChunk` 扩展为承载 AS + CC 双后端完整信息的统一结构，新增 `session_id` / `block_id` / `tool_call_id` / `tool_call_name` / `media_type` / `input_tokens` / `output_tokens` 等字段，纯文本流仍保持轻量。 - **`chunk_enum.py`**：补全生命周期标记 `REPLY_START` / `REPLY_END`，并文档化两套后端事件 → ChunkEnum 的映射。 ### 3. Index 模块重构（变化批次化 + dispatch） - 新增 `_change_batch.py`：`coalesce_changes()` 把同路径多次事件折叠为最终状态（结合 path 存在性判定），`bucket_changes()` 按 watchfiles.Change 分桶。 - 新增 `init_changes.py`（`InitChangesStep`）：一次性扫描，对比 file_store / file_catalog 已索引节点计算 added/modified/deleted，写入 `context["changes"]` 后 dispatch。 - 新增 `update_changes.py`：抽象基类 `ChangeApplyStep` 统一 added/modified/deleted 处理与错误收集；`UpdateCatalogStep`（写 file_catalog）、`UpdateIndexStep`（写 file_store，含按后缀解析 chunker）。 - **`watch_changes.py`**：改用 `dispatch_step_specs`（基类提供的 `dispatch_steps()`），每批先 `coalesce_changes` 再 dispatch；默认参数调整（debounce 5000ms / step 1000ms / poll 5000ms）并暴露常量。 - 删除旧步骤：`clear_and_scan` / `foreach_dispatch` / `scan_changes` / `update_catalog`(旧) / `update_index`(旧)；`clear_store.py` 取代 clear_and_scan。 ### 4. Evolve / Dream 模块（拆分为多步 pipeline） - 删除旧的单体 `auto_dream.py` / `dream.py` / `dream.yaml`，新增 `dream/` 子包，按 5 个步骤组织： - **`extract.py`**：扫描当日 day-index + daily 笔记，对比 file_catalog 找出 changed/deleted，调用 LLM 全局抽取 `units`（procedure/personal/wiki 三桶）与 `topics`，路径与桶做清洗/路由。 - **`integrate.py`**：逐个 unit 调用 LLM 写入 digest，结构化输出 `IntegrateOutcome`（CREATE/CORROBORATE/REFINE/CORRECT），失败 unit/路径收集回写。 - **`topics.py`**：写 `daily/<date>/interests.yaml`，结合当天已有 + 近 N 天做去重（`normalize_topic`），可走 LLM 或纯规则去重两条路径。 - **`proactive.py`**：读取当日 `interests.yaml`，作为主动推荐话题的入口。 - **`finish.py`**：把变更路径落盘到 dream file_catalog（checkpoint），渲染最终汇总摘要。 - 新增 `schema.py`（`DreamState` 等跨步骤共享状态与结构化输出模型）与 `utils.py`（状态存取、扫描打包、YAML 读写、结构化回复解析等公共函数）。 - `evolve/__init__.py` 导出全部新 step。 ### 5. auto_memory / auto_resource（适配新 Agent API） - **`auto_memory.py`**：会话路径迁移到 `<session_dir>/dialog/<session_id>.jsonl`；改用 `job_tools`；新增 `source_conversation` frontmatter 反向链接（`_session_link`）；执行后刷新 day 索引（`refresh_day_index`），并对 session_id 做合法性校验。 - **`auto_resource.py`**：资源改用「同名 daily note」方案（`_compute_note_stem` 取文件 stem）；批量处理 `changes: list[dict]`（`_handle_change` 逐项处理，返回逐项结果摘要）；agent 会话 id 用稳定的 `uuid5`；同样刷新 day 索引。 ### 6. BaseStep 基类增强 - 新增 `dispatch_steps` / `dispatch_step_specs` 机制：`_resolve_dispatch_step()` 支持字符串或 dict 形式的 step spec，`dispatch_steps()` 复用当前 context 调用下游 step。 - 新增 `config_value()`：按 key 取 app config，缺失时回退 `ApplicationConfig` 默认值。 - 小幅清理：`language` 初始化、`copy()`、`Ref.__init__` 签名精简。 ### 7. Components 改动 - **`file_store/local_file_store.py`**：持久化改用 zstd 压缩（`.jsonl.zst`，通过新 `utils/jsonl_zst.py`）；upsert 时先删除旧 chunk 的 keyword 文档；embedding 复用改为 `(text, embedding)` 键控，要求文本一致才复用；新增 `_matches_search_filter()` 对 vector/keyword 搜索做 path/path_prefix/metadata 的统一后过滤。 - **`keyword_index/bm25_index.py`**：索引文件名加入组件名 + tokenizer 指纹（sha256 前 12 位），快照/恢复时校验指纹防配置漂移；空索引 dump 时删除文件，加载失败抛错而非静默。 - **`file_chunker/markdown_file_chunker.py`**：弃用 `python-frontmatter`，改用内置 YAML 解析（非法 YAML 不阻断正文索引），并修正因 frontmatter 占用行号导致的 AST 行号偏移（`line_offset`）。 - **`cron_job.py`**：大幅简化（-187 行），由原来「dispatch 外部 job/step + 多种调度模式」改为「在自身 steps 上跑 cron 表达式」；`Application` 启动顺序随之调整为 base > stream > background > cron。 - 其余小调整：service（base/http/mcp）、file_graph、file_catalog、as_llm、as_embedding、tokenizer、prompt_handler、base_component 的签名/接口微调。 ### 8. Application 生命周期 - `_start()` 启动顺序明确为 components → base → stream → background → cron，启动失败会触发 `_close()` 回滚并 re-raise（不再吞异常）。 - 启动时创建 `session_dir` 目录；新增 `update_component()`（按类型/名就地更新已存在组件，不存在则报错）。 ### 9. File IO / 路径安全 - **`_path.py`**：`resolve_path` 增加 vault 越界防护（`is_relative_to` 校验），禁止 `.` / `..` 路径分量，支持 `allow_empty`。 - **`read.py`**：大文件（超过 `MAX_FILE_READ_BYTES`）走按行读取 `read_file_lines_safe`，避免一次性载入内存。 - **`_file_io.py` / `_daily_index.py` / `_path.py`** 等支持函数补齐（如 `refresh_day_index`、`read_file_lines_safe`）。 - **`env_utils.py`**：新增 `parse_env_file()`，`load_env()` 返回加载到的键值、支持 `override`、对无路径调用做幂等缓存。 ### 10. Config - `ApplicationConfig` 新增 `session_dir`（默认 `reme_session`）。 - `config_parser.py`：环境变量展开后做类型转换（`_convert_value`）、dot-notation 与 key=value 参数校验更严格、配置文件路径支持相对 `_CONFIG_DIR` 查找、根非 dict 报错。 - `default.yaml`：作业编排改用 `init_changes_step` + `dispatch_steps`（index/resource/digest 三个 watch loop 与 reindex）；新增 `auto_dream`（4 步）、`proactive` 作业，移除旧 `dream`；file_catalog 增配 `resource` / `digest` / `dream` 实例；LLM 默认值与 Claude Code 凭据配置调整（tool_result_limit 50000、thinking_enable=false 等）。 ### 11. 其它 - 新增 `steps/common/add.py`（`AddStep` 算术 demo）、`channel/__init__.py` 与 common `__init__` 导出整理。 - 新增 4 篇文档：`docs4/auto_dream_logic_and_step_refactor.md`、`docs4/watch_loop_step_refactor_plan.md`、`docs4/todo.md`，以及 `reme_design.md` 更新。 **
389 lines
24 KiB
Markdown
389 lines
24 KiB
Markdown
# ReMe 设计文档
|
||
|
||
## 整体定位
|
||
|
||
> 一句话总结：**自进化的个人知识库**——你只管往里扔东西和对话，它自己长成一张知识图谱。
|
||
|
||
## 特性1：记忆分层
|
||
|
||
记忆按"原始 → 浅加工 → 深加工"三层组织：
|
||
|
||
### 1.1 目录结构
|
||
|
||
```
|
||
- reme_session/
|
||
- agentscope|claude_code / # 使用内置的agent wrapper，session会保存在这里
|
||
{session_id}.jsonl UUID格式要求 # /Users/yuli/workspace/ReMe/reme4/components/agent_wrapper
|
||
- dialog/
|
||
{session_id}.jsonl # auto memory保存 可以监控可以被检索【可选】
|
||
- resource/
|
||
- YYYY-MM-DD/
|
||
- {channel}_{xxxx}.html
|
||
- {channel}_{xxxx}.md
|
||
- daily/【日记，浅加工】
|
||
- YYYY-MM-DD.md
|
||
- YYYY-MM-DD/
|
||
- session_{session_id}.md
|
||
- {resource_stem}.md
|
||
- digest/
|
||
- personal/
|
||
- procedure/
|
||
- wiki/
|
||
```
|
||
|
||
### 1.2 分层详解
|
||
|
||
| 目录 | 存什么 | 谁写入 | 举例 |
|
||
|---------------------|----------------|-------------|-----------------------------------|
|
||
| `resource/` | 原始文件（研报、网页、邮件） | upload / 手动 | PDF 研报、对话 JSONL |
|
||
| `daily/` | 每天的事件记录 | auto-memory | "调试登录 CSS"、"与 Alice 聚餐" |
|
||
| `digest/procedure/` | 方法论、步骤 | auto-dream | "webpack 编译卡死排查路径" |
|
||
| `digest/personal/` | 用户画像、偏好 | auto-dream | "用户不爱写注释"、"用户喜欢 pnpm" |
|
||
| `digest/wiki/` | 通用知识、决策先例 | auto-dream | "光伏产业链"、"React Server Components" |
|
||
|
||
`resource/` 和 `daily/` 是只增不删的流水账；`digest/` 下三个桶是反复消费的精华层，各桶有独立的整合 prompt。
|
||
|
||
## 特性2：Obsidian 兼容的 Markdown 格式
|
||
|
||
所有笔记都是标准 Markdown + Obsidian 语法，可以直接用 Obsidian 打开浏览：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 一个 .md 文件的完整结构 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ --- │
|
||
│ name: 宁德时代 ← YAML front matter │
|
||
│ description: 全球动力电池龙头 │
|
||
│ tags: [新能源, 电池] │
|
||
│ --- │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 所属行业:: [[新能源]] ← 语义化链接（Dataview） │
|
||
│ 竞争对手:: [[比亚迪]] │
|
||
│ │
|
||
│ # 基本面 ← Markdown 正文 │
|
||
│ 全球动力电池出货量第一，核心技术为 │
|
||
│ [[CTP]] 和 [[钠离子电池]]…… ← 标准 wikilink │
|
||
│ │
|
||
│ 参考 ![[2026Q1调研纪要]] ← 嵌入引用 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ↓ AST 语义分块 ↓ │
|
||
│ chunk 1: [标题骨架] + 正文片段 │
|
||
│ chunk 2: [标题骨架] + 正文片段 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.1 YAML front matter
|
||
|
||
每个笔记头部的元数据：
|
||
|
||
```markdown
|
||
---
|
||
name: 光伏产业链研究
|
||
description: 从硅料到组件的全链条梳理
|
||
tags: [新能源, 光伏, 产业链]
|
||
---
|
||
```
|
||
|
||
`name` / `description` 是约定字段，其余键值对全部保留，不会丢弃任何自定义字段。
|
||
|
||
### 2.2 四种 wikilink 写法
|
||
|
||
| 写法 | 示例 | 语义 |
|
||
|------|----------------|----------|
|
||
| 标准链接 | `[[光伏产业链]]` | 指向目标文件 |
|
||
| 锚点链接 | `[[钴#应用]]` | 指向特定章节 |
|
||
| 别名链接 | `[[宁德时代\|宁德]]` | 自定义显示文本 |
|
||
| 嵌入引用 | `![[钴]]` | 内联嵌入目标内容 |
|
||
|
||
### 2.3 语义化链接（Dataview 风格）
|
||
|
||
普通 wikilink 只说"A 提到了 B"，语义化链接还能表达"A 和 B 是什么关系"：
|
||
|
||
```markdown
|
||
所属行业:: [[新能源]] ← 行级属性（独占一行）
|
||
总部:: [[宁德]]
|
||
[竞争对手:: [[比亚迪]]] ← 内联属性（嵌入正文中）
|
||
```
|
||
|
||
`WikilinkHandler` 是全系统唯一的 wikilink 解析入口，确保 parser、graph、search 各层规则一致。
|
||
|
||
### 2.4 AST 感知的语义分块
|
||
|
||
传统 RAG 按固定 token 长度切片，经常切坏文档结构。ReMe 基于 Markdown AST 做语义分块：
|
||
|
||
- 按 H1/H2/H3 章节嵌套建树，递归分块
|
||
- **每个 chunk 保留完整标题骨架**——检索到片段后一眼看出它在哪个章节下
|
||
- 表格自动重复表头、代码块保留 fence、列表按项打包
|
||
|
||
```
|
||
示例 chunk：
|
||
─────────────────────
|
||
# 光伏产业链
|
||
## 上游：硅料
|
||
### 多晶硅工艺
|
||
[chunk 正文] ← 实际内容
|
||
## 中游：硅片 ← 骨架（只有标题）
|
||
## 下游：组件
|
||
─────────────────────
|
||
```
|
||
|
||
## 特性3：自进化
|
||
|
||
> **ReMe 的记忆不是被动存的，是主动长成知识图谱的。**
|
||
|
||
```
|
||
用户对话 / 外部素材
|
||
│
|
||
├───────────────────────────────────┐
|
||
▼ ▼
|
||
┌────────────┐ ┌────────────┐
|
||
│ auto-memory│ │auto-resource│
|
||
│ 对话→日记 │ │ 素材→解析 │
|
||
└─────┬──────┘ └──────┬─────┘
|
||
│ │
|
||
▼ ▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ daily/ │
|
||
│ (事件日记 + resource 加工笔记) │
|
||
└─────────────────────┬───────────────────────────┘
|
||
│
|
||
▼ 定时触发
|
||
┌─────────────┐
|
||
│ auto-dream │
|
||
│ 提炼 + 建图谱 │
|
||
└──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ digest/ │
|
||
│ (知识卡片 + wikilink 互联 = 知识图谱) │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
用户什么都不用做，Agent 在后台让笔记自己长出结构。
|
||
|
||
### 3.1 auto-resource
|
||
|
||
监控 `resource/` 目录，新文件进来后自动解析内容、整理为结构化笔记写入 `daily/` 下。
|
||
|
||
### 3.2 auto-memory
|
||
|
||
对话进行时，ReMe 在后台把上下文自动写入当天日记。不是简单的对话摘要——而是一个拥有完整读写能力的 LLM
|
||
Agent，自己决定记什么、怎么组织、合并还是新增。
|
||
|
||
### 3.3 auto-dream + auto-link：睡眠式记忆整理
|
||
|
||
借鉴人在睡眠中巩固记忆的机制——把日记和素材提炼成知识卡片，并自动织出图谱关系：
|
||
|
||
```
|
||
┌───────────────────────────┐
|
||
│ daily/2026-05-28/xxx.md │ ← 一篇日记或素材
|
||
└─────────────┬─────────────┘
|
||
│
|
||
╔═════════════════════════════════════╗
|
||
║ Phase 1 — Extract（一个 Agent） ║
|
||
║ "这份材料教了什么道理？" ║
|
||
║ ║
|
||
║ 输出 N 个抽象单元，各带 bucket 标签 ║
|
||
║ (空 → 结束，没东西值得记) ║
|
||
╚══════════╤══════════╤═══════════════╝
|
||
│ │
|
||
┌─────────────┘ └──────────────┐
|
||
▼ ▼
|
||
╔══════════════════════════════╗ ╔══════════════════════════════╗
|
||
║ Phase 2 — Integrate ║ ║ Phase 2 — Integrate ║
|
||
║ (每个 unit 独立一个 Agent) ║ ║ (每个 unit 独立一个 Agent) ║
|
||
║ ║ ║ ║
|
||
║ 1. search + traverse 召回 ║ ║ 1. search + traverse 召回 ║
|
||
║ 2. 决策: CREATE / UPDATE ║ ║ 2. 决策: CREATE / UPDATE ║
|
||
║ 3. 写入 + 自动织链接 ║ ║ 3. 写入 + 自动织链接 ║
|
||
╚══════════════╤═══════════════╝ ╚══════════════╤═══════════════╝
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ digest/ │
|
||
│ procedure/key-rotation.md ←─ derived_from:: [[daily/..]] │
|
||
│ wiki/credential-compliance.md ─ relates_to:: [[...]] │
|
||
│ personal/user-pr-pref.md │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
知识图谱自动生长
|
||
```
|
||
|
||
**Phase 1 筛选**——多个事实说明同一个道理就合并为一个 unit，分到三个桶：`procedure`（怎么做）/ `personal`（用户偏好）/ `wiki`
|
||
（通用知识）。没东西值得记则流程结束。
|
||
|
||
**Phase 2 先搜后写**——先搜已有 digest，再决策：新建（CREATE）、追加佐证（CORROBORATE）、补充精度（REFINE）、修正矛盾（CORRECT）。
|
||
|
||
**auto-link 是写入的副产品**——写 digest 时自动加 `derived_from:: [[素材]]` 溯源 + `relates_to::` 概念互联，图谱随每次
|
||
dream 自动变密。
|
||
|
||
**CronDreamer 定时批跑**——每天扫描当天所有 daily + resource 文件，逐个执行上述管线。
|
||
|
||
## 特性4：混合索引 + 渐进式展开
|
||
|
||
```
|
||
用户提问: "宁德时代的电池技术？"
|
||
│
|
||
├──────────────────────┬──────────────────────────┐
|
||
▼ ▼ │
|
||
┌─────────────────┐ ┌──────────────────┐ │
|
||
│ 全文倒排索引 │ │ 向量索引 │ │
|
||
│ (numpy + jieba) │ │ (faiss) │ │
|
||
│ │ │ │ │
|
||
│ "宁德时代" 精确 │ │ "动力电池龙头" │ │
|
||
│ 命中 │ │ 语义近似命中 │ │
|
||
└────────┬────────┘ └────────┬─────────┘ │
|
||
│ text_weight=0.3 │ vector_weight=0.7 │
|
||
└──────────┬──────────┘ │
|
||
▼ │
|
||
┌───────────────┐ │
|
||
│ RRF 融合排序 │ │
|
||
│ score = Σ(w/(k+rank)) │
|
||
└───────┬───────┘ │
|
||
▼ │
|
||
┌──────────────────────────────────────┐ │
|
||
│ 第一跳：Top-K chunk 全文 + 评分 │ │
|
||
└───────────────────┬──────────────────┘ │
|
||
▼ │
|
||
┌──────────────────────────────────────┐ │
|
||
│ 第二跳：邻居目录（只有标题，不展开正文）│ ← wikilink 图谱 │
|
||
└───────────────────┬──────────────────┘ │
|
||
▼ │
|
||
┌──────────────────────────────────────┐ │
|
||
│ 第 N 跳：Agent 按需追问，展开正文 │ │
|
||
└──────────────────────────────────────┘ │
|
||
```
|
||
|
||
### 4.1 混合索引构建
|
||
|
||
两套索引并行维护，各擅其长：
|
||
|
||
- **全文倒排索引**（基于numpy）——精确匹配专有名词，搜"宁德时代"必须命中。支持增量更新索引，无原生扩展依赖。
|
||
- **向量索引**（基于faiss）——语义相似度，搜"锂电正极原料"能命中"钴"。
|
||
|
||
### 4.2 基于 RRF 的混合检索
|
||
|
||
两条通路并行跑（`asyncio.gather`），用 RRF（Reciprocal Rank Fusion）融合排序：
|
||
|
||
```
|
||
融合分 = Σ( weight_i / (k + rank_i) ) k=60, vector_weight=0.7, text_weight=0.3
|
||
```
|
||
|
||
为什么要两路？纯向量容易错配名词（"苹果公司"≈"水果"），纯关键词抓不到同义改写——融合互补盲区。
|
||
|
||
### 4.3 渐进式链接展开
|
||
|
||
传统 RAG 一次性把 Top-K 全塞进上下文，token 浪费且噪音多。ReMe 分跳展开，按需深入：
|
||
|
||
**第一跳** — 返回命中 chunk 全文 + 分数明细
|
||
|
||
**第二跳** — 展开 wikilink 邻居的"目录"（只有标题，不展开正文）：
|
||
|
||
```
|
||
========== digest/wiki/宁德时代.md:5-22 [score=0.0247 vector=0.0156 keyword=0.0091] ==========
|
||
# 宁德时代
|
||
全球动力电池出货量第一，核心技术为 CTP（Cell to Pack）和钠离子电池……
|
||
|
||
outlinks (2):
|
||
→ digest/wiki/磷酸铁锂.md name="磷酸铁锂正极路线" description="磷酸铁锂与三元路线对比" via predicate=相关技术
|
||
→ digest/wiki/固态电池.md name="固态电池技术路线" description="全固态与半固态进展" via predicate=技术演进
|
||
inlinks (2):
|
||
← daily/2026-03-18/宁德调研.md name="宁德时代调研纪要" description="2026Q1产能与订单跟踪" via plain
|
||
← digest/wiki/新能源产业链.md name="新能源产业链全景" description="从锂矿到整车的全链条" via predicate=下游应用
|
||
```
|
||
|
||
**第 N 跳** — Agent 看过"目录"后，自己决定哪些邻居值得深入，再发起 read 拿正文。
|
||
|
||
二跳目录每条只占一行（最多 10 outlink + 10 inlink），Agent 拥有全局视野却不撑爆上下文。
|
||
|
||
## 特性5：多 Agent 框架集成
|
||
|
||
ReMe 不做独立 Agent 产品，而是作为**能力层**被任意框架调用：
|
||
|
||
| 集成路径 | 适用对象 | 方式 |
|
||
|---------------------|----------------------|---------------------------------------------|
|
||
| SDK 深度集成 | AgentScope / Qwenpaw | middleware 注册 tools + prompt，hook 注册 auto-* |
|
||
| MCP Tool + skill.md | Claude Code | MCP 注册 Tool，配 skill.md 开箱即用，hook 注册 auto-* |
|
||
| HTTP API + CLI | 通用方案 | skill.md + CLI 调用 |
|
||
|
||
---
|
||
|
||
# 二、工程架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Service 层（HTTP / MCP 双协议） │
|
||
│ FastAPI + FastMCP，同一套 Job 同时暴露为 REST 和 MCP Tool │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ Application 层 │
|
||
│ 配置加载 → 组件初始化 → Job 注册 → start() / close() 生命周期 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ Job 层（编排） │
|
||
│ 每个 Job = 一组 Step 的有序管线，YAML 声明式配置 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ Step 层（业务逻辑） │
|
||
│ 原子操作单元，按功能域分组：file_io / index / evolve / common │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ Component 层（可插拔基础设施） │
|
||
│ 统一注册表 R，一行配置切换实现 │
|
||
│ file_store / embedding / keyword_index / llm / file_graph │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 2.1 服务层
|
||
|
||
每个 Job 同时暴露为两种协议，写一次逻辑、两种方式调用：
|
||
|
||
| 协议 | 传输方式 | 适用场景 |
|
||
|---------------|-------------------------------|------------------------------|
|
||
| HTTP（FastAPI） | JSON POST / SSE | REST 调用、Web 前端 |
|
||
| MCP（FastMCP） | stdio / SSE / streamable-http | Claude Code、Cursor 等 MCP 客户端 |
|
||
|
||
- **按需拉起**：Agent 检测到服务未运行时自动后台启动，用户无感知
|
||
- **服务发现**：通过 `REME_SERVICE_INFO` 环境变量广播地址，`find_reme` 一键探活
|
||
|
||
## 2.2 组件系统（Component）
|
||
|
||
统一注册表 `R`，所有基础设施都是可插拔的——改一行配置就能切换后端：
|
||
|
||
| 组件 | 干什么 | 可选后端 |
|
||
|-----------------|---------------|-----------------------|
|
||
| file_store | 文件存储 + 索引协调 | local |
|
||
| file_graph | wikilink 双向图谱 | local / nx / neo4j |
|
||
| keyword_index | 全文倒排索引 | bm25（numpy + jieba） |
|
||
| embedding_store | 向量存储与检索 | local（faiss） |
|
||
| embedding | 文本转向量 | openai 兼容接口 |
|
||
| llm | 大模型调用 | anthropic / openai 兼容 |
|
||
| tokenizer | 分词 | regex / jieba |
|
||
|
||
## 2.3 Job 列表
|
||
|
||
**Job** 是 ReMe 暴露给外部的操作单元——同一个 Job 可以作为 Python 函数直接调用、作为 MCP Tool 被 Agent 使用、也可以作为 CLI
|
||
命令执行。
|
||
|
||
| 类别 | Job | 功能 |
|
||
|------|---------------------------|----------------------------------|
|
||
| 检索 | `search` | 混合检索（向量 + BM25 + RRF）+ 渐进式图展开 |
|
||
| 检索 | `traverse` | 从指定路径遍历 wikilink 图谱 |
|
||
| 文件读写 | `read` | 读取 markdown 文件内容 |
|
||
| 文件读写 | `read_image` | 读取图片文件（base64） |
|
||
| 文件读写 | `write` | 新建或覆写 markdown 文件（含 frontmatter） |
|
||
| 文件读写 | `edit` | 文件内查找替换 |
|
||
| 文件读写 | `delete` | 删除文件，返回残留入边 |
|
||
| 文件读写 | `move` | 移动 / 重命名，自动重写 wikilink |
|
||
| 文件读写 | `list` | 列出目录下文件 |
|
||
| 文件读写 | `stat` | 文件元信息（大小、修改时间） |
|
||
| 文件读写 | `frontmatter_read` | 读取 frontmatter |
|
||
| 文件读写 | `frontmatter_update` | 合并更新 frontmatter |
|
||
| 文件读写 | `frontmatter_delete` | 删除 frontmatter 字段 |
|
||
| 日记管理 | `daily_create` | 幂等创建当天日记文件 |
|
||
| 日记管理 | `daily_list` | 列出某天的所有日记 |
|
||
| 日记管理 | `daily_reindex` | 重建当天索引页 |
|
||
| 索引维护 | `reindex` | 清空并全量重建索引 |
|
||
| 索引维护 | `update_store_index_loop` | 后台监听文件变更，增量更新 |
|
||
| 自进化 | `auto_memory` | 对话记录写入日记（LLM Agent） |
|
||
| 自进化 | `dream` | 单文件记忆提炼到 digest（LLM Agent） |
|
||
| 自进化 | `auto-dream` | 批量扫描当天文件，逐个 dream |
|
||
| 系统 | `health_check` | 组件健康检查 |
|
||
| 系统 | `version` | 返回版本号 |
|
||
| 系统 | `help` | 列出所有已注册 Job |
|