从答疑机器人到有办公桌的助理:一次 RAG Agent 的「加法」改造

0 阅读9分钟

起点

我的个人秘书系统原本是个标准 RAG Agent:Supervisor 路由给学业/生活两个专家,Worker 检索本地 ChromaDB,MemoryCurator 每轮写长期记忆。本质是一个更聪明的搜索引擎——问,答,结束。

我要的是主动和持久:记住要做的事、盯着时间、到点提醒、每天早上主动汇报。从"答疑机器人"变成"有办公桌的助理"。

一、架构决策:先定死,再动手

1. 存储:SQLite,理由是并发正确性 这个系统至少三个进程并发读写同一份数据——CLI、Streamlit、提醒 daemon。JSON 是"全量读→改→全量写",两进程并发改就互相覆盖;要救就得自己加文件锁,等于造一个没有事务的数据库。

sqlite3 是标准库,WAL 下"一写多读"并发良好。

2. 幂等:条件更新,不是先查后写 提醒"只弹一次"的保证,不靠"先 SELECT 再 UPDATE"(有竞态),而是让数据库自己判定:

def mark_reminded(self, task_id: str, ts: int) -> bool:
    with self._write() as conn:
        cursor = conn.execute(
            "UPDATE tasks SET reminded_ts = ? "
            "WHERE id = ? AND reminded_ts IS NULL",
            (ts, task_id),
        )
        return cursor.rowcount == 1   # 只有真正抢到的人才写通知

rowcount == 1 才继续写通知/推送。多进程或多轮并发扫到同一任务时,只有一个返回 True,其余全部跳过。幂等性交给 SQL 条件,不交给应用层的时序假设。

3. daemon 的推送契约:先标记,后发送

for task in store.list_due(now_ts):
    # catch_up 只在启动第一轮为 True:截止已过的合并成 missed
    if catch_up and task.due_ts is not None and task.due_ts <= now_ts:
        missed.append(task)
        continue

    if not store.mark_reminded(task.id, now_ts):
        continue                      # 没抢到,说明别的轮次已处理

    store.add_notification(kind="remind", ...)
    _print_reminder(task)
    _push(notifier, task.title, f"截止:{to_local_iso(task.due_ts)}")

牺牲是"极端崩溃漏一条",换来"永不重复弹"。主动选择漏而不是重——重复提醒比漏提醒更伤信任。

4. 去重:返回值必须携带"是否新建" 早期 add_task 只返回 Task,命中去重时和新建返回值完全一样,CLI 对重复添加谎报"已添加"。评审抓到的真 bug。改成:

with self._write() as conn:
    existing = self._find_duplicate(conn, title=cleaned_title, due_ts=due_ts, dedupe_key=key)
    if existing is not None:
        return existing, False        # 复用
    ...
    return task, True                 # 新建

原则:凡是"命中已有"的分支,返回值必须携带该事实,否则上层必然说谎。

5. Schema 演进:SQLite 不能改 CHECK kind 从 (remind, missed) 扩到 +briefing,而 CHECK 写死在表定义里。SQLite 不能 ALTER CHECK,只能重建表,用"建表 SQL 是否已含新值"做幂等判断:

row = conn.execute(
    "SELECT sql FROM sqlite_master WHERE type='table' AND name='notifications'"
).fetchone()
if row is None or "briefing" in (row["sql"] or ""):
    return                                    # 新库或已迁移

conn.execute("ALTER TABLE notifications RENAME TO notifications_v2")
conn.execute("CREATE TABLE notifications (... CHECK (kind IN ('remind','missed','briefing')) ...)")
conn.execute("INSERT INTO notifications (...) SELECT ... FROM notifications_v2")
conn.execute("DROP TABLE notifications_v2")

教训:任何写死取值的 CHECK 约束,都要预留升级路径。

6. 时间:epoch 秒单值存储 库里只存 due_ts(int epoch),展示层转本地时间。比较/排序/区间查询全在 SQL 层用整数完成,零时区歧义。只写日期时默认本地 18:00,用显式常量 DATE_ONLY_HOUR。

二、六个 Slice,每个可独立 bisect

Slice 1 数据底座。Slice 2 时间解析 + 提醒 daemon。Slice 3 desk_expert 接入。Slice 4 被动简报。Slice 5 主动简报 + 三面面板。Slice 6 企业微信推送 + 接收 + 双向对话。

时间解析的分层:先绝对,后相对 parse_natural 的设计是"格式明确的先交给既有解析器,失败再按中文习惯理解相对时间":

# 1) 绝对时间优先,保证与 store/CLI 行为一致
try:
    abs_ts = parse_timestamp(raw, field="时间")
except ValueError:
    pass
else:
    return datetime.fromtimestamp(abs_ts)

# 2) 相对时间:去掉空白后按文法解析
normalized = "".join(raw.translate(_TRANSLATION).split())
result = _parse_relative(normalized, base)
if result is None:
    raise ValueError(f"无法解析时间:{text!r}")   # 不猜,不兜底

关键:认不出就抛异常,不返回近似值。"明天下午"猜成 18:00 比报错更危险。

Slice 4 的坑:18:00 默认值 vs 全天区间 parse_natural("今天") 按约定返回 18:00,但简报需要"今天全天从 00:00 起"。解法是检测"纯日期写法"并对齐零点:

def _schedule_bound(text: str) -> int:
    moment = parse_natural(text)
    # 纯日期写法(今天/下周一/2026-11-20)才对齐到 00:00
    if _DATE_ONLY_EXPR_RE.fullmatch(text.strip()):
        moment = datetime.combine(moment.date(), datetime.min.time())
    return int(moment.timestamp())

"今天下午3点" 这种带时刻的,fullmatch 不命中,保留解析出的准确时间。于是 list_schedule("今天","明天") = [今天00:00, 明天00:00),正好覆盖一整天。

三、部署环境反向决定了需求

原计划做 Windows toast。系统最终跑在云服务器(Linux 无桌面)——toast 毫无意义。

候选:Server 酱(5 次/天)→ 飞书/钉钉(单向)→ 企业微信(官方 API、双向、免费)。三道关:

60020:IP 不在企业可信 IP 白名单; 配可信 IP 前必须先配接收消息服务器:Slice 顺序被强行倒过来; **8080 公网不通 **:本地 curl 400(服务正常),公网超时——服务器内部 ufw 没放行,只开了云控制台安全组。

四、企业微信的工程细节

加解密:最易踩的是 32 字节填充 企业微信要求 PKCS#7 填充到 32 字节倍数,不是 AES 常规的 16:

_PKCS7_BLOCK_SIZE = 32   # 企业微信特例

def _decode_aes_key(encoding_aes_key: str) -> bytes:
    # 43 位、去掉 '=' 的 Base64;补足到 4 的倍数再解码成 32 字节
    padded = encoding_aes_key.strip() + "=" * (-len(encoding_aes_key.strip()) % 4)
    key = base64.b64decode(padded, validate=True)
    if len(key) != 32:
        raise ValueError(...)
    return key

明文结构 random(16B) + msg_len(4B 大端) + msg + receiveid,解密时按长度字段切。用企业微信官方的测试向量做断言,确保自研实现和官方一致。

5 秒超时:ACK + 异步主动回复 企业微信被动回复有 5 秒限制,而 DeepSeek 生成回答要几秒到几十秒。所以 POST 立即返回空包(ACK),后台线程处理完再主动 message/send:

thread = threading.Thread(
    target=reply_to_message,
    args=(message, assistant, notifier),
    daemon=True,
)
thread.start()
return 200, ""     # 立即 ACK,不等生成

reply_to_message 里 assistant.ask 异常兜底成固定文案,notifier.send 异常也吞掉——后台线程不能把 HTTP 服务拖垮。

token 缓存:提前 5 分钟刷新

def _get_access_token(self) -> str | None:
    now = self._clock()
    if self._access_token and now < self._token_expires_at:
        return self._access_token
    ...
    ttl = max(0, expires_in - TOKEN_REFRESH_MARGIN_SECONDS)  # 7200 - 300
    self._access_token = token
    self._token_expires_at = now + ttl

clock 可注入,测试用假时钟验证"跨刷新点重取",不 sleep。

五、一个"假成功"的坑

上线后:企业微信能对话、补发提醒能收到,但到点提醒收不到。

日志显示 daemon 打印了 [提醒] 出门,没有任何报错。_push 的逻辑是"send 返回 True 就不打印",所以日志干净 = 它认为推送成功了。

真相:daemon 进程在 .env 配好企业微信之前启动。get_settings() 有 @lru_cache,第一次调用就缓存了配置,那时 notify_channel 还是 none,make_notifier 返回 NoopNotifier——send 直接返回 True,不打印、也不真发。

class NoopNotifier(Notifier): def send(self, title: str, body: str, user_id: str | None = None) -> bool: return True # 未配置不是错误,但和"推送成功"无法区分 解法:重启 daemon + systemd 加 EnvironmentFile=-/root/rag-agent-secretary/.env。

教训:任何"成功"都要区分"真发出去了"和"静默返回 True"。Noop 返回 True 合理,但排查时它会骗人。

六、差在哪里

拿"真人秘书"当标尺,差的不是功能数量,是范式。

1. 单轮 vs 连续:现在每句话独立单轮(assistant.ask(question) 不带 history)。"提醒我交房租"→"改成后天",第二句不知道改哪条。真人秘书记忆连续,系统是断的。

2. 规则触发 vs 意图推理:现在"主动"只有两条硬规则——due_ts 到点→推、08:00→简报。真人秘书的主动是推理:"你明天出差,今天该交报告"。系统只会按 list_due 的 SQL 条件触发。

3. 文法解析 vs 语义理解:parse_natural 是确定性文法。"3点"凌晨还是下午是显式约定(24 小时制),不是真理解。语义消歧交给了 LLM 提示词——明确分工,不是能力。

4. 存储 vs 关联:MemoryCurator 存"事实条目",检索靠向量相似度。真人秘书的记忆是关联图("健身""腰疼""减脂目标"是一件事)。

5. 提醒 vs 代办:系统能提醒"11:47 交房租",但不会排优先级。只有 low/medium/high 三个标签,没有真正的调度取舍。

6. 任务分解:让真人秘书"准备下周旅行",她拆成订票、订酒店、查天气。系统只能一条条建待办。

7. 通知 vs 对话:提醒推过去就结束。真人秘书会等你回"知道了"或"帮我改到明天"。

一句话:当前系统是规则驱动的状态机,真人秘书是意图驱动的推理体。

七、我是怎样利用 AI Agent 的

三个 AI agent 分工协作:

规划 agent(Deepseek V4 pro):架构决策、slice 划分、写任务书; 执行 agent(Deepseek v4.1 flash):写代码、跑测试、自测; 评审 agent:读 diff、抓 bug、给修复任务书。

成本控制 routine 输出不读:只看 pytest 数字 + git status; 每 slice 评审一次:只读 diff,不读自测报告; 关键 slice 才升级模型:改核心路由/并发/提示词的,切 Pro 或换 GLM 交叉审。 回报压成 6 行模板,评审输入从 4k token 降到 300。

最有效的一条:评审读 diff,不读自测报告 这轮抓到的真 bug——去重谎报、clear_remind 缺失、状态标签两套叫法、Noop 假成功——全部来自读代码。测试只会说"绿了",不会说"这里语义不对"。

局限 AI agent 擅长"给定约束下的实现",不擅长"定义约束"。为什么用 SQLite、为什么先标记后推送、为什么去重要返回 created——这些取舍必须人来定。agent 能写对代码,但做不对决策。

八、方法论

评审读 diff,不读自测报告:报告只会说绿了,代码才会说对不对。 返回值要诚实:区分"新建/复用""成功/已存在",别让上层猜。 主动任务,状态必须落库:进程会死会重启,内存标记靠不住。 可测性来自注入点:时间逻辑接受 now_ts,I/O 接受 notifier/clock;daemon 的"单步函数"和"循环"分离。 部署环境提前想清楚:在错误的环境假设上做设计,是最大的浪费。

结语

最终形态:

用户 ⇄ 企业微信 / Web / CLI
        ↓
   Supervisor 路由
        ↓
study_expert · life_expert · desk_expert
        ↓
  Chroma 知识库 · SQLite 工作台
        ↓
  remind_daemon(systemd 常驻)
        ↓
  提醒 + 每日简报 → 企业微信推送

没有 Redis、Celery、Docker,唯一新依赖是 pycryptodome。一个能跑在单台小服务器上的个人助理。

真正的难点不是写代码,是每一步想清楚"为什么这样选"。决策做对了,代码只是自然生长的结果。从答疑机器人到有办公桌的助理:一次 RAG Agent 的改造实录