AMClaw

AMClaw 是一个用 Rust 编写的实验性项目，当前主要包含两部分能力：

1. 微信 iLink Bot Demo
2. 一个最小可运行的文件型 Agent 原型

这个项目主要基于我自己的使用习惯来设计，同时也把它当作一个学习 Rust 开发 Agent 的持续实验场。

这个项目是我很多 Agent 设计思路的试验场，所以很多代码设计可能会经常发生破坏性变化。

当前仓库代码版本是 0.3.2，请优先以本文档描述的“当前实现”为准。

仓库里已经有更完整的架构设计和实施计划，但当前代码实现仍处于 Demo / 验证阶段。DESIGN-0.1.0.md 和 PLAN.md 代表后续目标，而不是现状。

当前实现

微信 Bot

• 扫码登录微信 iLink
• 长轮询 getupdates 接收消息
• 缓存每个用户的 context_token
• 文本消息进入会话层，支持 .. / !! / 超时合并
• 待提交聊天会话会持久化，进程重启后可恢复最小会话状态
• 支持显式记录用户记忆：记住 <content>，并可用 我的记忆 查询；支持 忘记 <id> 屏蔽记忆，支持 有用 <id> 标记某条记忆对当前使用确实有帮助
• 支持 /context [text] / 上下文 [text] 预览当前会话会如何装配到 Agent 上下文中；支持 /context verbose [text] 查看更详细的 section 与 memory dropped 细节
• 长会话的 Session Text 会采用 boundary compaction（summary_compact + recent_tail），减少上下文膨胀并保留最近轨迹
• 支持从部分聊天表达中自动提炼最小“主题 / 偏好”记忆
• 入站消息去重，避免重复回复
• 入站原文持久化到 SQLite
• 对链接消息自动入库 articles / tasks
• 自动消费 pending 任务并生成本地归档产物
• 普通 HTTP 网页会尝试最小正文抽取，并记录 source=http 与 page_kind
• 对公众号链接支持浏览器抓取链路
• 抓取受限时进入 awaiting_manual_input，支持人工补正文
• 支持任务状态查询、最近任务查询与任务重试
• retry 会进入异步队列，不再同步返回最终状态
• 支持周报查询（周报 / 周报 YYYY-WW）
• 内置简单回复规则：hello / 你好 / 时间 / 帮助
• 非命令消息默认 Echo 回复
• 长回复（超过 1200 字符）自动拆分为多条带 （i/n） 前缀的分段消息发送
• 长输入（超过 180 字符）在 Agent 生成前会先收到"收到，处理中，稍后给你完整回复。"回执
• 真实聊天触发的 Agent run 会写入 data/agent_traces/<date>/，并附带 source_type、user_id、message_ids 等上下文
• Agent Trace 现会记录结构化 context_sections、Session State、section budget，以及 section 的 trimmed / dropped reason
• C3/C4：上下文组装升级为结构化 ContextPack 单入口渲染（src/context_pack.rs），所有 prompt 通过 build_context_pack -> render_prompt_from_context_pack 组装，trace 新增 context_pack_present / context_pack_section_count / context_pack_total_chars / context_pack_drop_reasons 字段，并输出 context_pack_built / context_pack_trimmed 日志事件
• 支持生成本地日报 Markdown，并可按配置时间自动触发

Agent Demo

• 支持一个正在演进中的 Agent runtime：
  • 最小多步 ReAct
  • 显式 plan
  • progress_note
  • step_status
  • current_step_index
  • expected_observation（含 expected_fields / minimum_novelty）
  • 最小 watchdog（含 stalled_trajectory）
  • 最小 retry_step / replan / ask_user / abort
  • 最小 planner / executor / watchdog helper 分层
  • 最小 state/controller budget（max_steps / replan_budget）
• 内置文件工具：
  • read
  • write
  • create
• 内置只读业务工具：
  • get_task_status
  • list_recent_tasks
  • list_manual_tasks
  • read_article_archive
• 对工具访问路径做工作区边界限制
• 支持多 Provider 规划调用：
  • DEEPSEEK
  • MOONSHOT
  • OPENAI
• 当 LLM 不可用时，可回退到规则解析命令

Agent Trace

• 每次 Agent run 默认会落盘：
  • JSON trace
  • Markdown trace
  • 每日 index.jsonl
  • 每日可读总览 index.md
• Demo 入口触发的 trace 会标记 source_type=agent_demo
• 真实微信聊天触发的 trace 会标记 source_type=wechat_chat，并补充 trigger_type、user_id、message_ids

日报 / 调度

• 支持按 config.toml 中的 [scheduler] 配置每天生成一份本地日报
• 日报会写入 data/reports/daily-YYYY-MM-DD.md
• 周报会写入 data/reports/weekly-YYYY-WW.md
• 当前日报聚合的是当天 archived 任务
• 当前周报聚合的是当周（ISO 周）archived 任务
• 若配置 [scheduler].report_to_user_id，并且该用户已有可用 context_token，程序会尝试按计划自动把日报内容回传到微信；每周一同一时间也会尝试自动回传周报；超长会截断，且不会暴露服务器路径字段
• 如需手动一次性生成某天日报，可运行：

cd ~/Desktop/AMClaw
AMCLAW_GENERATE_DAILY_REPORT_FOR=2026-04-10 cargo run

当前未实现

以下内容在设计文档中有规划，但当前仓库里还没有完整落地：

• 通用网页的高质量正文抽取、分类与摘要
• 更成熟的 Plan & Execute executor
• 更强的长期主题记忆与语义检索
• Web 控制台
• 完整的 restricted / unrestricted 模式治理

项目结构

当前真正承载运行逻辑的模块主要是：

• src/main.rs：启动入口、加载环境变量与 config.toml
• src/chat_adapter：微信 iLink 登录、轮询、会话接线、收发消息
• src/command_router：聊天流 / 链接流 / 查询命令分流
• src/task_store：SQLite 初始化、入站消息持久化、任务读写
• src/pipeline：任务消费、HTTP / 浏览器抓取、归档生成、人工补录归档
• src/config.rs：配置加载与路径解析
• src/session_router.rs：会话缓冲、超时 flush、最小会话恢复
• src/agent_core：Plan-aware ReAct runtime、执行状态、失败分类与最小 watchdog
• src/context_pack：结构化上下文包（ContextPack）组装、渲染与预算裁剪
• src/tool_registry：文件工具执行与路径校验
• src/scheduler：本地日报的定时触发
• src/reporter：本地日报 Markdown 生成

其余模块目录目前主要用于占位和约束未来职责。

环境要求

• Rust 2021
• 可用的网络环境，用于访问微信 iLink 接口
• 如需启用 LLM 规划，需要配置至少一个 Provider 的环境变量

已自动加载的本地配置文件

启动时会按顺序尝试加载以下文件：

• .env.deepseek.local
• .env.deepseek
• .env.moonshot.local
• .env.moonshot

建议先从示例模板复制，再填入真实值：

cp .env.deepseek.example .env.deepseek
cp .env.moonshot.example .env.moonshot

如果你使用 OpenAI，可直接在 shell 环境中设置：

• OPENAI_API_KEY
• OPENAI_BASE_URL
• OPENAI_MODEL

也可设置其他 Provider：

• DEEPSEEK_API_KEY
• DEEPSEEK_BASE_URL
• DEEPSEEK_MODEL
• MOONSHOT_API_KEY
• MOONSHOT_BASE_URL
• MOONSHOT_MODEL

本地配置文件

首次启动会自动生成 config.toml。默认情况下：

• SQLite 数据库写到 ./data/amclaw.db
• 会话合并窗口为 5 秒
• agent.session_summary_strategy 默认 semantic（可选 truncate）
• agent.retriever_mode 默认 rule（可选 semantic / hybrid / shadow）
• agent.embedding_provider 默认 noop（可选 moonshot / deepseek / openai）
• agent.retriever_rollout_enabled 默认 false（关闭时语义链路短路回退 rule，不初始化 embedding provider）
• agent.retriever_rollout_allow_users 默认空数组（为空表示全量放行；非空时仅名单内 user_id 放行）
• 微信 channel version 为 1.0.0
• 浏览器抓取默认关闭，需要显式在 [browser] 下启用
• .env*.example 是可提交模板；真实 .env 文件仅用于本地开发，不应提交

最小 rollout 示例（逐步放量）：

[agent]
retriever_mode = "hybrid"
embedding_provider = "moonshot"
retriever_rollout_enabled = true
retriever_rollout_allow_users = ["user-a", "user-b"]

运行

运行微信 Bot

cd ~/Desktop/AMClaw
cargo run

启动后会打印二维码 URL，扫码完成登录，然后进入长轮询收消息。

当前支持的微信命令

• 发送普通文本：进入聊天流
• 发送带 http:// / https:// 的消息：直接作为链接任务入库
• 发送裸域名链接，例如 mp.weixin.qq.com 或 mp.weixin.qq.com/s/...：会自动补成 https:// 后入库
• 收藏 <url>：显式提交链接任务
• 状态 <task_id> / status <task_id>：查询任务状态
• 最近任务：查询最近任务列表
• 日报 / 日报 <YYYY-MM-DD> / 今日整理：生成并返回当天日报内容；超长会截断，且不会暴露服务器路径字段
• 周报 / 周报 <YYYY-WW>：生成并返回当周周报内容；超长会截断，且不会暴露服务器路径字段
• 记住 <content>：写入一条用户记忆
• 我的记忆：查看当前已保存的用户记忆（含 id，可用于 忘记 命令）
• 有用 <id> / 标记有用 <id> / useful <id>：显式确认某条记忆确实有用，增加 use_count
• 忘记 <id> / 屏蔽记忆 <id> / forget <id>：屏蔽指定记忆，不再出现在查询结果中
• /context [text] / 上下文 [text] / context [text]：预览当前上下文装配结果；若当前已有 pending 会话，会与附加文本一起参与预览
• /context verbose [text] / 上下文 详细 [text]：输出更详细的 section 内容预览与 memory dropped 明细
• 重试 <task_id> / retry <task_id>：重新处理任务，进入异步队列执行
• 补正文 <task_id> :: <content>：对待人工补录任务手动写入正文
• 待补录任务：查看当前等待人工补正文的任务
• 帮助 / help

公众号抓取策略

• mp.weixin.qq.com 链接优先走浏览器抓取链路
• 浏览器抓取成功时，会保留：
  • 原始 HTML
  • 全页截图
  • 提取后的标题与正文归档
• 截图前会主动触发公众号长文懒加载图片，并等待图片渲染后再截
• 如果页面被验证码、权限或错误页拦截：
  • 原始链接仍然保留
  • 任务进入 awaiting_manual_input
  • 可用 补正文 <task_id> :: <content> 继续归档
• 真实 Bot 中已经完成过一次公众号链接端到端抓取验证

普通网页抓取策略

• 非公众号链接默认走 HTTP 抓取链路
• HTTP 抓取成功时，会保留原始 HTML，并生成本地 Markdown 归档
• 归档时会优先尝试从 <article> / <main> / <body> 提取正文；提取不到时退回短预览
• 归档产物会记录 source=http 与最小 page_kind 判断，目前仅区分 article / webpage

运行 Agent Demo

cd ~/Desktop/AMClaw
AMCLAW_AGENT_DEMO_COMMAND='读文件 README.md' cargo run

支持的规则命令格式：

• 读文件 <path>
• 创建文件 <path> :: <content>
• 写文件 <path> :: <content>
• read <path>
• create <path> :: <content>
• write <path> :: <content>

也支持带前缀的自然语言包装：

• 帮我运行：读文件 README.md
• 请帮我运行: 创建文件 demo/a.txt :: hello

测试

cd ~/Desktop/AMClaw
cargo test

当前测试主要覆盖：

• Agent 命令解析
• 聊天流 .. / !! / 超时合并
• 最小会话恢复
• 用户记忆写入、查询与屏蔽
• 链接流路由与 URL 提取
• SQLite 表结构、消息去重、入站消息持久化
• articles / tasks 入库、状态查询、最近任务、任务重试
• 人工补正文闭环
• 公众号错误页 / 验证页识别
• 浏览器抓取归档的正文提取
• 待人工补录任务的查询与恢复
• 日报查询命令
• 工具路径边界限制
• 最小 Agent loop 行为
• 日报生成与调度时间解析
• 仓库内 scope 标记文件存在性检查

运行离线评测

context_eval（Session Summary 策略评测）

cd ~/Desktop/AMClaw
cargo run --bin context_eval

• 默认读取 notes/context-memory/eval_samples.jsonl，对比 semantic 与 truncate 的 session summary 质量与压缩率。
• 默认输出报告到 notes/context-memory/SESSION-SUMMARY-EVAL-2026-04-17.md。
• 可用 --input、--output、--max-chars 覆盖默认路径与预算。

trace_eval（Agent Trace 评测）

cd ~/Desktop/AMClaw
cargo run --bin trace_eval

• 扫描 data/agent_traces/ 目录下的所有 trace JSON，生成统计报告。
• 默认输出报告到 notes/agent-eval/reports/TRACE-EVAL-REPORT.md。
• 默认关联 notes/agent-eval/baselines/EVAL-BASELINE-SAMPLES-2026-04-18.md 做 baseline 命中统计。
• 支持 --date、--dir、--output、--baseline、--no-baseline、--only-interesting 参数。
• 支持 --compare-before <path>、--compare-after <path>、--compare-output <path> 对比两份已有报告，输出 PASS/WARN/FAIL 结论。缺少 --compare-before 或 --compare-after 时报错退出。
• Gate 模式：--gate 输出精简结果并返回退出码（PASS=0, FAIL=1, N/A=2；WARN 默认=0，--gate-strict 下 WARN=2）。可用作 CI / 收尾阶段的自动化门禁。指标规范见 notes/agent-eval/specs/EVAL-GATE-SPEC-2026-04-20.md；策略规范（soft/hard 模式、升级/回退条件）见 notes/agent-eval/specs/GATE-POLICY-SPEC-2026-05-08.md。
  • 文本输出协议（按顺序，--gate，默认）：
    • OVERALL=PASS|WARN|FAIL|N/A
    • STATE_UPDATED=before_count=... after_count=... before_rate=... after_rate=... delta=...（人类可读，rate/delta 可能为 N/A）
    • STATE_UPDATED_RAW=bc=...|ac=...|br=...|ar=...|d=...（机器可解析，缺失值为 NA，无单位）
    • REASONS=...（仅当有理由时输出）
  • JSON 输出协议（--gate --gate-json）：输出单条 JSON，包含结构化字段，适合程序直接解析。rate/delta 单位为百分点（0–100），缺失时值为 null。CI workflow 已改用 JSON 做软门禁判断，避免文案变更导致误判。
• 推荐收尾命令：
  • make trace-compare：生成最新报告并输出对比报告
  • make eval-gate：执行宽松门禁（FAIL/N/A 阻断，WARN 不阻断）
  • make eval-gate-strict：执行严格门禁（WARN/FAIL 都阻断）
  • make eval-gate-json：输出 JSON 格式门禁结果（适合 CI 或脚本消费）
  • make lint-scripts：对 scripts/*.sh 和 scripts/tests/*.sh 运行 shellcheck
  • make test-scripts：运行脚本回归测试（trace soft gate 等）
  • make test-gate-mode：运行 gate 模式行为矩阵测试（soft/hard × PASS/WARN/FAIL/N/A）
  • 本地复现 CI soft gate（与 workflow 逻辑一致，含 GATE_EXIT 传递）：

    set +e
    GATE_JSON=1 ./scripts/eval_gate.sh > trace-gate.json
    GATE_EXIT=$?
    set -e
    ./scripts/trace_soft_gate.sh trace-gate.json "$GATE_EXIT"

embedding_test（Embedding Provider 端到端验证）

cd ~/Desktop/AMClaw
cargo run --bin embedding_test

• 验证 OpenAI 兼容 embedding provider 的连接与向量返回。
• 默认读取 .env 中的 OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_EMBEDDING_MODEL。
• 支持 DeepSeek / Moonshot / OpenAI / ollama / MLX server 后端。
• 执行前请确保对应服务可达且环境变量已配置。

hybrid_test（Hybrid Retriever 端到端验证）

cd ~/Desktop/AMClaw
cargo run --bin hybrid_test

• 验证 HybridRetriever 的完整链路：规则召回 → embedding 编码 → 语义重排序。
• 需配置 embedding provider（同上），否则 hybrid 会 fallback 到纯 rule，并在候选 metadata 记录 retrieval_mode=hybrid_fallback 与 fallback_reason。
• 执行前请确保 embedding 服务可达。

协作与文档约定

• README.md：面向人类读者，描述“当前能跑什么、怎么跑、怎么验证”。
• AGENTS.md：仓库或模块级开发约束；修改模块职责或边界时，要同步更新对应目录的 AGENTS.md。
• CLAUDE.md：给只识别该文件名的助手使用；内容应与同目录 AGENTS.md 保持一致，避免指令漂移。
• 影响用户可见行为、命令、任务状态或运行方式的改动，必须同步更新 README.md。
• 日常改动后至少执行 cargo check；提交前建议再跑 cargo fmt --check、cargo clippy --all-targets --all-features 和 make lint-scripts。
• 本地环境文件、运行配置和数据库默认不提交：如 .env、.env.*、config.toml、data/；示例模板 *.example 除外。

文档说明

• DESIGN-0.1.0.md：目标架构与版本设计
• PLAN.md：当前实施路线
• NEXT-STEPS.md：当前阶段执行备忘
• CORE-SKILL-ROADMAP.md：core/runtime、service/tool 与 skill 的分层路线
• AGENT-RUNTIME-IMPLEMENTATION-PLAN.md：agent_core、上下文与 Tool Use 的分阶段实施计划
• notes/README.md：记录类文档总索引（runtime 演进、retro、约束记录）
• notes/runtime-evolution/README.md：runtime 演进记录索引（含 AGENT-RUNTIME-01~04）
• sessions/README.md：按日期归档的开发 session 索引与命名约定
• AMCLAW-FEATURE-ROADMAP.md：未来功能路线与优先级、分层归属建议
• DEVELOPMENT.md：后续开发、维护与提交流程说明
• LOGGING.md：当前结构化日志字段、事件名与扩展约定

如果你准备继续开发这个项目，建议先读这三个文件，再看 src/chat_adapter、src/command_router、src/task_store 和 src/agent_core 的当前实现。