起点
我的个人秘书系统原本是个标准 RAG Agent:Supervisor 路由给学业/生活两个专家,Worker 检索本地 ChromaDB,MemoryCurator 每轮写长期记忆。本质是一个更聪明的搜索引擎------问,答,结束。
我要的是主动和持久:记住要做的事、盯着时间、到点提醒、每天早上主动汇报。从"答疑机器人"变成"有办公桌的助理"。
一、架构决策:先定死,再动手
1. 存储:SQLite,理由是并发正确性 这个系统至少三个进程并发读写同一份数据------CLI、Streamlit、提醒 daemon。JSON 是"全量读→改→全量写",两进程并发改就互相覆盖;要救就得自己加文件锁,等于造一个没有事务的数据库。
sqlite3 是标准库,WAL 下"一写多读"并发良好。
2. 幂等:条件更新,不是先查后写 提醒"只弹一次"的保证,不靠"先 SELECT 再 UPDATE"(有竞态),而是让数据库自己判定:
python
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 的推送契约:先标记,后发送
python
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。改成:
python
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 是否已含新值"做幂等判断:
python
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 的设计是"格式明确的先交给既有解析器,失败再按中文习惯理解相对时间":
python
# 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 起"。解法是检测"纯日期写法"并对齐零点:
python
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:
python
_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:
python
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 分钟刷新
python
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 的"单步函数"和"循环"分离。 部署环境提前想清楚:在错误的环境假设上做设计,是最大的浪费。
结语
最终形态:
bash
用户 ⇄ 企业微信 / Web / CLI
↓
Supervisor 路由
↓
study_expert · life_expert · desk_expert
↓
Chroma 知识库 · SQLite 工作台
↓
remind_daemon(systemd 常驻)
↓
提醒 + 每日简报 → 企业微信推送
没有 Redis、Celery、Docker,唯一新依赖是 pycryptodome。一个能跑在单台小服务器上的个人助理。
真正的难点不是写代码,是每一步想清楚"为什么这样选"。决策做对了,代码只是自然生长的结果。从答疑机器人到有办公桌的助理:一次 RAG Agent 的改造实录