claw-code 个人 AI 助手路线图：从终端 Agent 到 Life OS 的五层演进

claw-code 正在从一个面向开发者的 CLI 编码 Agent，演化为一个可全天候使用的"个人 AI 助手（Life OS）"。本文基于仓库中的路线图文档 docs/personal-assistant-roadmap.md 展开，逐层解析其五大方向——多通道接口、个人记忆（RAG）、工具执行（MCP + 插件）、主动性（定时循环）与长生命周期身份（会话 + 画像）——并结合仓库中已落地的 Rust 源码（RAG 服务、会话恢复、MCP 运行时、cron 注册表）说明每一层的现状基础与演进路径。读完本文，你既能理解 claw-code 的助手化蓝图，也能掌握当前仓库中已实现的 RAG 检索、会话续接与定时任务等能力的实际用法。

---

路线图定位：务实的分层演进

原路线图开篇即声明了其意图：把当前"开发者 CLI Agent"的方向，转化为一条通向个人 AI 助手的可行路径，涵盖五个维度：

• 多通道接口：聊天 / 语音，让助手脱离终端；
• 个人记忆：面向"生活"的 RAG，而不只是面向代码仓库的 RAG；
• 工具与动作：通过 MCP + 插件接入外部系统；
• 主动性：OmX 风格的循环（检查 → 提炼 → 起草 → 推送）；
• 长生命周期身份：会话 + 用户画像，让助手跨天、跨周保持连续性。

文档刻意采用"务实"的组织方式：每一节都给出 MVP 范围、Next step（下一步）与 Evolution（远期演进）。后文严格按这五节展开，并在每节末尾补充仓库中对应模块的源码级现状。

---

第一层：接口——走出终端

目标与 MVP

路线图的第一个目标是让 claw 不依赖 IDE 或终端即可使用：从手机、从聊天软件，最终通过语音。其 MVP 定义为：

• 聊天桥（Chat bridge）：一个小型服务，把 Discord（首选）或 Telegram 的消息中继到 claw / claw-analog 执行运行时。聊天线程被当作"前端"，claw 是执行运行时；
• 通道/线程 → 会话 id 的映射：每个聊天线程映射到一个 session id，支持 resume/append（续接/追加）；
• 基础 UX：在聊天中支持类斜杠命令：
  • /prompt …、/resume latest、/status、/cost、/help
  • 默认"安全模式"（只读），除非显式提升权限。

下一步与演进

• 语音：Whisper 级别的 STT 接入同一聊天桥作为输入；TTS 输出用于免提反馈；
• 多模态：附件（图片/PDF）路由进摄入/个人记忆管线；
• 在线感知与通知：把摘要主动推回聊天。

仓库现状佐证

当前仓库中尚无独立的 Discord/Telegram 桥接服务（搜索仓库源码未发现相关客户端实现），这一层属于规划中的分发生成层。但它的两个关键依赖在仓库里已有基础：

• 会话映射的落点：claw-analog 已支持会话持久化与续接。从 claw-analog 配置结构 可以看到 session 路径相关配置——"When set, load/save turn history (resume with the same path)"，即同一 session 路径可加载/保存多轮历史，这正是聊天线程 → session id 映射所需的底层能力；
• 只读安全模式：claw-analog 的权限体系（PermissionMode）已区分只读与可写工具，工具定义按模式装配，retrieve_context 等工具被标注为只读要求，与路线图中"默认只读、显式提升"的安全模式设计一致。

换言之，聊天桥"本身"只需实现消息中继与会话路由，执行侧的会话续接与权限边界能力已经就位。

---

第二层：记忆——从"代码的 RAG"到"生活的 RAG"

目标与 MVP

路线图认为，助手要能基于你的长期上下文（而非只有当前仓库）来回答个人问题并做决策。MVP 包含两部分：

• 扩展摄入输入源，超出 git 工作区：
  • Markdown 笔记、导出的聊天记录、简单文本日志；
  • PDF（初期允许在 Rust 之外做文本抽取，后期再内置管线）；
• 保持清晰的分离：
  • Work RAG（代码/工作区）
  • Personal RAG（笔记、计划、历史）

下一步与演进

• 把 retrieve_context 工具演进为多源检索工具：
  • "在哪搜"选择器（work / personal / both）；
  • 元数据过滤（来源、日期区间、标签）；
• 演进：增量摄入 + 事件驱动更新（watch 文件夹、聊天事件）；当规模要求时换用更好的向量库（ANN/Qdrant 等）。

仓库现状：claw-rag-service 已是可运行的 Work RAG

这一层是五大方向中仓库落地程度最高的部分，核心 crate 位于 rust/crates/claw-rag-service。

摄入管线（ingest）

摄入入口 run_ingest 接受多个工作区根目录，逐个 WalkDir 遍历并写入 SQLite + 向量。关键参数在 ingest.rs 中硬编码为常量：

常量	值	含义
DEFAULT_MAX_FILE_BYTES	2 MiB	单文件最大摄入字节数
CHUNK_CHARS	900	分块字符长度
CHUNK_OVERLAP	120	相邻块重叠字符数
EMBED_BATCH	16	每次 embedding API 批大小

同时定义了跳过目录（.git、target、node_modules、__pycache__、.claw-rag）与 25 种文本扩展名白名单（rs、md、toml、json、yaml、py、ts 等）。注意两点与路线图的对应关系：

• 白名单已包含 md 与 txt——Markdown 笔记与纯文本日志按现有代码可直接摄入，"Personal RAG 输入源 #1（笔记文件夹）"无需改动摄入器，只需指向一个笔记目录；
• PDF 不在白名单内，印证了路线图"初期在 Rust 之外做文本抽取"的说法：需先把 PDF 转为文本再摄入。

CLI 用法（见 main.rs 的 clap 定义，docs/rag-web-ui.md 有完整示例）：

cargo run -p claw-rag-service -- ingest -w <workspace1> -w <workspace2> --db <index.sqlite>

--workspace 可重复传入以实现跨仓库 RAG；--db 缺省为 .claw-rag/index.sqlite，也可用环境变量 CLAW_RAG_DB 覆盖。

检索服务（search / query）

检索核心 query_index 目前采用线性扫描 MVP：加载 SQLite 中全部已索引向量，对查询 embedding 计算余弦相似度排序后取 top-k（上限 64）。响应通过 phase 字段自描述状态：1-sqlite、1-sqlite-empty、1-sqlite-no-db（见 lib.rs）。

当规模增长时，仓库已预留了 Qdrant 后端：编译开启 qdrant-index feature 后，qdrant_index.rs 从环境变量读取配置——CLAW_RAG_QDRANT_URL、CLAW_RAG_QDRANT_COLLECTION（默认 claw_rag_chunks）、CLAW_RAG_QDRANT_API_KEY；查询时若 Qdrant collection 已存在则优先走 Qdrant，否则回退 SQLite 线性扫描。这正是路线图"Evolution：Better stores (ANN/Qdrant) when scale demands it"的在库实现。

关键环境变量（实操速查）

整理自 docs/rag-web-ui.md 与 main.rs：

变量	默认值	作用
OPENAI_API_KEY / CLAW_RAG_OPENAI_API_KEY	—	调用 embedding API 的密钥
CLAW_RAG_EMBEDDING_BASE_URL	https://api.openai.com/v1	embedding 端点（OpenAI 兼容）
CLAW_RAG_EMBEDDING_MODEL	text-embedding-3-small	embedding 模型
CLAW_RAG_DB	.claw-rag/index.sqlite	SQLite 索引路径
CLAW_RAG_PORT / CLAW_RAG_HOST	8787 / 127.0.0.1	HTTP 服务监听
CLAW_RAG_MOCK_PROVIDERS	—	置 1 时生成确定性假向量，免网络（CI 测试用）

HTTP 面包括 GET /（单页 UI）、GET /health、GET /v1/stats、POST /v1/query（请求体 {"query":"...", "top_k":8}，top_k 默认 8，见 QueryRequest）。lib.rs 中的集成测试 ingest_and_query_roundtrip_mock 演示了完整闭环：两个目录写入笔记 → run_ingest → query_index 返回带 path/snippet/score 的命中。

检索如何进入 Agent：retrieve_context 工具

路线图"Next step：evolve retrieve_context into a multi-source retrieval tool"所指的正是 claw-analog 中的同名工具。从 lib.rs 的配置字段看：

• rag_base_url（TOML rag_base_url 或环境变量 RAG_BASE_URL）非空时才暴露 retrieve_context 工具；
• rag_top_k_max 限制单次检索条数上限，rag_timeout_secs 限制 HTTP 超时。

工具实现 会先经权限执行器校验（enforce_tool），再调用 POST {base}/v1/query。当前实现只有单一 base_url——"work/personal/both 选择器"尚未实现，这正是路线图规划的演进点；从现有单库设计推断，最自然的做法是为 Personal RAG 另起一个索引库与 base URL，在工具层增加来源选择参数。

---

第三层：双手——工具、MCP 与插件

目标与 MVP

"助手之所以有价值，是因为它能做事，而不仅仅是会说。" MVP 要求：

• 通过 MCP 服务器接入外部系统：日历、笔记（Notion）、邮件、任务管理、智能家居（视可用性）；
• 建立"个人技能"约定：
  • 专用目录（如 .claw/skills/）存放用户自有的自动化；
  • 小而可组合的工具（日报摘要、预算、提醒），而非单体。

下一步与演进

• 工具发现 UX：直接在聊天里列出可用的 MCP/工具/技能；
• 按工具类别划权限边界：读 vs 写，破坏性操作需显式确认；
• 演进：技能市场（plugin marketplace）流程复用技能；动作的审计日志与回放。

仓库现状佐证

这一层的运行时基础已经比较完整，MCP 与插件子系统分布在 rust/crates/runtime/src 与 rust/crates/plugins：

• mcp.rs / mcp_client.rs / mcp_stdio.rs 覆盖 MCP 生命周期与 stdio 传输；mcp_lifecycle_hardened.rs 针对生命周期做了加固（配套验证文档 docs/g007-mcp-lifecycle-mapping.md 与 docs/g007-plugin-mcp-verification-map.md 描述了对应契约）；
• mcp_tool_bridge.rs 负责把外部 MCP 工具桥接进内部工具面，这与"工具发现 UX"是同一问题域；
• rust/crates/plugins 提供捆绑插件与 hooks（如 bundled/sample-hooks/hooks/pre.sh、post.sh），配套说明见 rust/crates/plugins/AGENTS.md；
• 权限边界方面，permission_enforcer.rs 与 permissions.rs 实现按工具的工具级强制校验——retrieve_context 的只读标注即走这条路径，路线图中"破坏性操作需显式确认"可构建在此之上。

因此，MVP 中"接一个日历/笔记类 MCP 服务器"在运行时侧已无障碍；缺的是个人技能目录约定与聊天侧的"列出工具"入口。

---

第四层：主动性——OmX 风格的循环

目标与 MVP

从被动的"回答我"转向主动的"注意到 → 准备 → 提议 → 执行"。MVP 是一个定时 runner，周期性执行：

1. 检查收件箱/通知；
2. 提炼可执行任务；
3. 起草回复；
4. 向聊天推送一条简短摘要。

下一步与演进

• 多 Agent 模式（Architect/Executor/Reviewer）提升可靠性：executor 提议动作，reviewer 校验安全性与正确性，之后才由桥接层执行写/动作类工具；
• 演进：以事件驱动（webhooks）替代纯 cron 触发；带边界（时间、工具、花费限额）的"Autopilot"模式。

仓库现状佐证

定时任务的基础设施已存在于 runtime crate：team_cron_registry.rs 实现了 cron 注册表——CronEntry 携带 cron_id（形如 cron_{:08x}_{ts}）与 schedule 字段，create(schedule, prompt, description) 可登记"定时 + 提示词"的条目，并支持 get/delete。这与 MVP 中"周期性检查、提炼、起草、推送"的调度骨架吻合：把"digest 提示词"作为 prompt 入册即可。需要指出的是，仓库中尚未看到 webhooks/事件触发实现，"事件驱动触发"仍停留在 Evolution 阶段；同样，Executor/Reviewer 多 Agent 校验在仓库中暂无对应独立模块，属于待建能力。

---

第五层：长生命周期身份——会话 + 画像

目标与 MVP

让助手跨天、跨周显得连续且个性化。MVP 两点：

• 默认续接最近会话（--resume latest 风格的行为）；
• 使用一段简短的、用户自有的 profile/系统提示词来固定语气与偏好。

下一步与演进

• 三者分离：
  • personality（风格、偏好）
  • memory（事实、历史）
  • policies（权限、安全规则）
• 演进：多人格（工作/个人）显式切换；透明的记忆控制（"忘掉这个"、"记住这个"）。

仓库现状佐证

会话持久化已在 claw-analog 落地：lib.rs 的 session 路径配置说明"设置后按同一路径 load/save 多轮历史"，并配有会话保存与续接的测试（如 session_save_and_resume_appends_prompt、mock_session_save_export_without_resume_path）。CLI 侧的会话/斜杠命令行为另有测试文件 resume_slash_commands.rs 覆盖。"personality / memory / policies 三分"与"多人格切换"目前在仓库中没有对应数据结构，属于规划项；但从现有配置体系（TOML 文件配置 + 系统提示词）推断，画像文件最可能以独立 profile 文件 + 按人格选择的形式实现。

---

建议的里程碑顺序

路线图最后给出了五步落地顺序，这也是判断各层优先级的官方依据：

1. Discord 桥 + 会话映射——不引入新 AI 能力，纯分发层；
2. 个人摄入源 #1（笔记文件夹）+ 检索选择器（personal/work）；
3. 一个 MCP 集成（日历或笔记）+ 一个"每日摘要"技能；
4. 定时 digest 循环（cron），权限受边界约束；
5. 在同一桥之上加语音输入/输出。

值得注意的是，顺序设计刻意把"分发"放在"新能力"之前：先让现有能力触手可及，再逐层叠加记忆、动作与主动性——这与仓库现状完全一致（RAG、MCP、cron 等"被调用方"能力已就绪，缺的主要是"调用入口"）。

读者动手的最小验证路径

如果你想在当前仓库上亲手走通路线图的第 2 步（笔记摄入 + 检索），最短路径是：

# 1. 摄入一个"个人笔记"目录（md/txt 已支持）
$env:OPENAI_API_KEY = "sk-..."
cargo run -p claw-rag-service -- ingest -w <path/to/notes> --db .claw-rag/personal.sqlite

# 2. 起检索服务（默认 127.0.0.1:8787）
cargo run -p claw-rag-service -- serve --db .claw-rag/personal.sqlite

# 3. 在 claw-analog 配置中指向该服务，启用 retrieve_context
#    .claw-analog.toml: rag_base_url = "http://127.0.0.1:8787"

Work RAG 与 Personal RAG 各持一个 SQLite 索引（不同 --db），即可先用"两个独立端点"近似路线图中"work/personal 选择器"的效果——这是从源码现状看最贴合 MVP 的过渡方案。

---

小结

docs/personal-assistant-roadmap.md 给出的不是一份空想清单，而是一张与仓库代码高度咬合的路线图：RAG 记忆层已有可运行的服务与 retrieve_context 工具（rust/crates/claw-rag-service）、MCP 与插件运行时已具备（rust/crates/runtime、rust/crates/plugins）、cron 注册表与会话续接也已就位（rust/crates/runtime/src/team_cron_registry.rs、rust/crates/claw-analog）。路线图真正的增量工作集中在"入口"：聊天/语音桥、多源检索选择器、个人技能目录与主动摘要循环。理解了这五层的 MVP/下一步/演进划分及其在仓库中的落点，你就能准确判断 claw-code 距离"个人 AI 助手"还差哪些具体模块，以及每个模块应当从哪里动工。