ReMe/docs4/reme4_index.md

# reme4 代码模块索引

> 本文档梳理 `reme4/` 下各能力模块、核心类和代码路径，便于快速定位与扩展。
> 所有路径相对仓库根目录 `/Users/yuli/workspace/ReMe/`。

## 1. 顶层入口与运行流程

| 文件 | 作用 |
| --- | --- |
| `reme4/reme.py` | CLI 入口（`main()`）：`start` 启动应用；`find_reme` 探活；其他动作转发到 client。 |
| `reme4/application.py` | `Application` 基类：解析 config → 注册 service / components / jobs → 拓扑排序启动 → `run_job` / `run_stream_job` / `run_app`。 |
| `reme4/constants.py` | 服务发现常量：`REME_SERVICE_INFO`、默认 host/port (`127.0.0.1:2333`)。 |
| `reme4/__init__.py` | 包入口。 |

启动流程：`reme.main()` → `parse_args` → `resolve_app_config` → `precheck_start` → `ReMe(...).run_app()` → `service.run_app(app)` → `app.start()`（按拓扑序启动 components 与 jobs）。

## 2. 配置与枚举

| 文件 | 作用 |
| --- | --- |
| `reme4/config/default.yaml` | 默认配置：service / jobs / components 全套样例。 |
| `reme4/config/config_parser.py` | `parse_args`、`resolve_app_config`、env 变量展开、点号配置覆盖、YAML/JSON 加载。 |
| `reme4/enumeration/component_enum.py` | `ComponentEnum`：所有组件类型枚举（service/client/job/step/file_*/embedding/keyword_index/tokenizer/as_*）。 |
| `reme4/enumeration/chunk_enum.py` | `ChunkEnum`：流式分块类型 (THINK/CONTENT/TOOL_*/USAGE/ERROR/DONE)。 |

## 3. Schema（Pydantic 数据模型）

代码：`reme4/schema/`

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `ApplicationConfig` / `ComponentConfig` / `JobConfig` | `application_config.py` | 顶层配置模型；包含 service/jobs/components/vault_dir 等字段。 |
| `EmbNode` | `emb_node.py` | 文本+embedding 节点基类，`np.ndarray` 序列化为列表存储。 |
| `FileChunk` | `file_chunk.py` | 文件切片（继承 `EmbNode`）：`path/start_line/end_line/scores`，含 `set_hash_id()`。 |
| `FileNode` | `file_node.py` | 文件级图节点：`path/st_mtime/links/chunk_ids/front_matter`。 |
| `FileLink` | `file_link.py` | 文件间 wikilink 边：`source_path → target_path`，可选 `target_anchor` / `predicate`。 |
| `FileFrontMatter` | `file_front_matter.py` | YAML 头：`name/description`，`extra="allow"` 保留未知键。 |
| `Request` / `Response` | `request.py` / `response.py` | 服务端请求/响应封装。 |
| `StreamChunk` | `stream_chunk.py` | 流式分块：`chunk_type/chunk/done/metadata`。 |

## 4. Components（核心能力组件）

> 所有组件继承 `BaseComponent`（`reme4/components/base_component.py`），提供：
> - `start/close/restart` 生命周期；
> - `bind(name, base_cls, default_factory, optional)` 声明依赖（启动时通过拓扑排序解析）；
> - `vault_path` / `working_metadata_path` 工作目录；
> - `dump/load` 持久化钩子。
>
> 组件通过 `ComponentRegistry`（`R`，`reme4/components/component_registry.py`）按 `(ComponentEnum, name)` 注册和查找；上下文容器为 `ApplicationContext`（`application_context.py`），运行期上下文为 `RuntimeContext`（`runtime_context.py`）。

### 4.1 Tokenizer — `reme4/components/tokenizer/`

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseTokenizer` | `base_tokenizer.py` | 抽象基类，启动时加载 `stopwords` 文件。 |
| `RegexTokenizer` (`@R "regex"`) | `regex_tokenizer.py` | 正则切词；中文按字符切分，非中文按词切分。 |
| `JiebaTokenizer` (`@R "jieba"`) | `jieba_tokenizer.py` | 基于 jieba 的中文分词。 |

### 4.2 Keyword Index — `reme4/components/keyword_index/`

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseKeywordIndex` | `base_keyword_index.py` | 抽象基类：`add_docs/delete_docs/retrieve/clear/optimize_index`，依赖 tokenizer。 |
| `BM25Index` (`@R "bm25"`) | `bm25_index.py` | 自实现 Okapi BM25 倒排索引：`vocab` / `inverted_index` / `doc_meta`，pickle 持久化，支持增量更新与 `optimize_index` 紧凑化。 |

### 4.3 Embedding — `reme4/components/embedding/`

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseEmbeddingModel` | `base_embedding_model.py` | LRU 缓存 + npz 磁盘持久化、批量、重试、健康检查（`is_healthy`）；提供 `get_embedding/get_embeddings/get_node_embeddings`。 |
| `OpenAIEmbeddingModel` (`@R "openai"`) | `openai_embedding_model.py` | OpenAI 兼容协议（dashscope/qwen 等），`AsyncOpenAI` 客户端。 |

### 4.4 File Graph — `reme4/components/file_graph/`

存储 `FileNode` 节点与 `FileLink` 边，支持「虚节点」(被指但尚未导入的目标占位)。

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseFileGraph` | `base_file_graph.py` | 抽象接口：`upsert_nodes/delete_nodes/get_nodes/rebuild_links/clear/get_outlinks/get_inlinks`。 |
| `LocalFileGraph` (`@R "local"`) | `local_file_graph.py` | 纯 dict 实现 + JSONL 持久化；维护 `_nodes`/`_inverse`/`_pending`。 |
| `NxFileGraph` (`@R "nx"`) | `nx_file_graph.py` | networkx `MultiDiGraph` + pickle 持久化，虚节点用「无 node 属性」标识。 |
| `Neo4jFileGraph` (`@R "neo4j"`) | `neo4j_file_graph.py` | Neo4j 后端（bolt 驱动），`(:File)-[:LINKS]->(:File)`，支持升降级虚节点、`rebuild_links` 修复重建。 |

### 4.5 File Parser — `reme4/components/file_parser/`

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseFileParser` | `base_file_parser.py` | 抽象接口：`parse(path) -> (FileNode, list[FileChunk])`，提供 `_get_relative_path`。 |
| `DefaultFileParser` (`@R "default"`) | `default_file_parser.py` | 仅 stat：附件/二进制不读内容、不切块、不抽链接；作为无 `supported_extensions` 命中时的兜底 parser。 |
| `ChunkedFileParser` (`@R "chunked"`) | `chunked_file_parser.py` | 字节级带 overlap 切片 + YAML front matter + wikilink 抽取（含 Dataview `predicate::`）。 |
| `LinkedFileParser` (`@R "linked"`) | `linked_file_parser.py` | Markdown 专用：mistletoe AST → MdNode 树 → 章节递归分块；每个 chunk 携带完整 heading skeleton（TOC）；wikilink 解析支持隐式 `.md`、folder-note、短路径歧义扇出，需注入 `file_graph` 解析目标。 |

### 4.6 File Store — `reme4/components/file_store/`

聚合 `embedding_model` + `keyword_index` + `file_graph`，统一 chunk 写入与混合检索。

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseFileStore` | `base_file_store.py` | 抽象基类：`upsert_file/delete_by_path/clear/vector_search/keyword_search/rebuild_links/get_nodes/get_outlinks/get_inlinks`；启动时探活 embedding，失败则降级为纯关键字检索。 |
| `LocalFileStore` (`@R "local"`) | `local_file_store.py` | 内存 chunk 字典 + JSONL 持久化；upsert 时复用旧 chunk 的 embedding（按 chunk.id 命中）；`vector_search` 用 `batch_cosine_similarity`，`keyword_search` 委托给 keyword_index。 |

### 4.7 File Watcher — `reme4/components/file_watcher/`

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseFileWatcher` | `base_file_watcher.py` | 抽象接口：`watch_loop/update_store/on_added/on_modified/on_deleted`；启动后台任务先做一次全量同步再进入监听循环。 |
| `LiteFileWatcher` (`@R "lite"`) | `lite_file_watcher.py` | 基于 `watchfiles.awatch` 的轮询监听；变更分类后调用 file_parser 解析、写 file_store；`update_store` 通过 mtime 对比做增量。 |

### 4.8 Job — `reme4/components/job/`

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseJob` (`@R "base"`) | `base_job.py` | 顺序执行 `steps`：每个 step 共享 `RuntimeContext`，最终返回 `Response`；启动时把 step config 实例化为 `BaseStep`。 |
| `StreamJob` (`@R "stream"`) | `stream_job.py` | 流式执行：异常包装为 ERROR chunk，结束时 emit DONE 终止流。 |

### 4.9 Service — `reme4/components/service/`

把 jobs 暴露给外部协议。

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseService` | `base_service.py` | 抽象接口：`build_service/add_job/start_service`，`run_app` 串起来。 |
| `HttpService` (`@R "http"`) | `http_service.py` | FastAPI + uvicorn；普通 job → POST JSON 端点，stream job → SSE 流；CORS 全开。 |
| `MCPService` (`@R "mcp"`) | `mcp_service.py` | FastMCP；把 job 注册为 MCP `FunctionTool`（StreamJob 跳过）；transport 支持 sse/stdio/streamable-http。 |

### 4.10 Client — `reme4/components/client/`

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseClient` | `base_client.py` | 抽象接口：`__call__` 分发 `list`/`_execute`，`list_actions` 列出 server 能力。 |
| `HttpClient` (`@R "http"`) | `http_client.py` | httpx 异步流式：根据 `Content-Type` 自适应 JSON/SSE；`/openapi.json` 列出 actions；CLI 友好格式化。 |
| `MCPClient` (`@R "mcp"`) | `mcp_client.py` | fastmcp Client 包装；transport=`sse/stdio/streamable-http`；`list_tools` 列出工具。 |

### 4.11 AgentScope 适配（as_*） — `reme4/components/as_*/`

把 AgentScope 的 LLM / Formatter / TokenCounter 包成 ReMe 组件，供 step 通过 `step.as_llm` / `step.as_llm_formatter` / `step.as_token_counter` 访问。

| 类 | 文件 | 说明 |
| --- | --- | --- |
| `BaseAsLLM` / `OpenAIAsLLM` (`openai`) / `AnthropicAsLLM` (`anthropic`) | `as_llm/__init__.py` | 包装 `agentscope.model.OpenAIChatModel / AnthropicChatModel`，启动时实例化 `self.model`。 |
| `BaseAsLLMFormatter` / `AsOpenAIChatFormatter` (`openai`) / `AsAnthropicChatFormatter` (`anthropic`) | `as_llm_formatter/__init__.py` | 包装 AgentScope formatter；OpenAI 版用 `ReMeOpenAIChatFormatter` 扩展 |
| `ReMeOpenAIChatFormatter` | `as_llm_formatter/reme_openai_chat_formatter.py` | OpenAI formatter 扩展：tool_result 中的 image 提升为 user 消息；thinking 块合并为 `reasoning_content`；新增 video block 支持。 |
| `BaseAsTokenCounter` / `EstimatedAsTokenCounter` (`estimated`) | `as_token_counter/__init__.py` | 字符级估算 token 计数器（`encoded_byte_len / divisor`）。 |
| `EstimatedTokenCounter` | `as_token_counter/estimate_token_counter.py` | 实现类。 |

### 4.12 Prompt Handler — `reme4/components/prompt_handler.py`

`PromptHandler`：YAML/JSON 加载或类同名文件加载；多语言后缀（`key_zh/key_en`）；`prompt_format` 支持 `[flag]` 行级条件、`{var}` 参数校验。

## 5. Steps（最小执行单元）

代码：`reme4/steps/`

| 类 | 注册名 | 文件 | 作用 |
| --- | --- | --- | --- |
| `BaseStep` | — | `base_step.py` | 抽象基类：`execute()` + `RuntimeContext` 注入 + `input/output_mapping` + 通过 `_resolve` 自动取组件（`as_llm/as_llm_formatter/as_token_counter/file_parser/file_store/embedding/file_watcher`）；`add_as_tool(toolkit, job_name)` 把 job 包成 AgentScope tool。 |
| `DemoEchoStep1/2` | `demo_echo_step1` / `demo_echo_step2` | `common/demo.py` | 烟雾测试：query 处理 + 应答。 |
| `HealthCheckStep` | `health_check_step` | `common/health_check.py` | 各组件健康/规模快照（embedding/file_graph/file_store/file_watcher/keyword_index）+ 内存深度估算。 |
| `HelpStep` | `help_step` | `common/help.py` | 一行式列出全部 job 元信息（含参数 schema）。 |
| `ReindexStep` | `reindex_step` | `common/reindex.py` | 全量重建：停 watcher → clear store → `update_store` → 重启 watcher。 |
| `SearchStep` | `search_step` | `common/search.py` | 混合检索：vector_search + keyword_search 并发 → RRF 融合 → 阈值过滤 → 截断 → 可选 outlinks/inlinks 邻居展开（含元数据）。 |
| `StreamDemoStep1/2` | `stream_demo_step1` / `stream_demo_step2` | `common/stream_demo.py` | 流式烟雾测试：逐字符 emit CONTENT。 |
| `VersionStep` | `version_step` | `common/version.py` | 输出 `reme4.__version__`。 |

## 6. Utils — `reme4/utils/`

| 文件 | 主要导出 |
| --- | --- |
| `common_utils.py` | `hash_text`(SHA-256)、`execute_stream_task`(SSE 流转发)、`mock_reme_server`(子进程启动测试服务器)、`call_action` / `call_and_check`(HTTP 调用与断言)。 |
| `service_utils.py` | `find_reme` / `locate_reme` / `precheck_start` / `cli_find_reme`：服务发现，`lsof` + `pgrep` 扫描运行实例，端口冲突预检。 |
| `env_utils.py` | `load_env`：加载 `.env`。 |
| `logger_utils.py` | `get_logger`：loguru 日志（控制台 + 文件）。 |
| `logo_utils.py` | `print_logo`：启动 ASCII logo。 |
| `similarity_utils.py` | `cosine_similarity` / `batch_cosine_similarity`：numpy 向量相似度。 |

## 7. 内置 Jobs（`reme4/config/default.yaml`）

| Job | Backend | 步骤 | 说明 |
| --- | --- | --- | --- |
| `demo` | `base` | `demo_echo_step1` → `demo_echo_step2` | 端到端 demo。 |
| `version` | `base` | `version_step` | 返回包版本。 |
| `health_check` | `base` | `health_check_step` | 组件健康快照。 |
| `help` | `base` | `help_step` | 列出全部 job。 |
| `reindex` | `base` | `reindex_step` | 全量重建索引。 |
| `search` | `base` | `search_step` | 混合检索（vector+keyword RRF，可展开邻居）。 |
| `stream_demo` | `stream` | `stream_demo_step1` → `stream_demo_step2` | 流式 demo。 |

## 8. 默认依赖关系（来自 `default.yaml`）

```
tokenizer (regex)        ──┐
embedding_model (openai) ──┤── file_store (local) ── file_watcher (lite)
file_graph (local)       ──┤            (持有 embedding/keyword_index/file_graph)
file_parser (default)    ──┘                                    │
keyword_index (bm25)  ── tokenizer ──────────────┘              │
                                                  file_parser ──┘
```

启动时由 `Application._topological_order()`（Kahn 算法）按依赖拓扑序启动；关闭时反向。

## 9. 扩展点速查

| 需求 | 入口 |
| --- | --- |
| 新增检索后端 | 实现 `BaseFileStore` 子类，`@R.register("xxx")` |
| 新增图后端 | 实现 `BaseFileGraph` 子类（参考 `Neo4jFileGraph` 处理虚节点） |
| 新增分词器 | 实现 `BaseTokenizer.tokenize` |
| 新增解析器 | 实现 `BaseFileParser.parse`（返回 `(FileNode, list[FileChunk])`） |
| 新增 Job | 在 `default.yaml`（或自定义 yaml）`jobs:` 段声明 + 写步骤实现 |
| 新增 Step | 继承 `BaseStep`，实现 `execute()` 并 `@R.register("xxx_step")` |
| 暴露新协议 | 实现 `BaseService`（参考 `HttpService` / `MCPService`） |
| 接入新 LLM | 实现 `BaseAsLLM` 子类（`agentscope.model` 适配） |