我做的第一个真正耐用的个人自动化项目，名字就叫 cua。目录名是 cua，启动命令是 cua，配置文件也是 cua.json。全称是我自己起的，Cognitive Unified Assistant，认知统一助手。说白了，就是把我的日程、提醒、笔记、快捷指令、常用 API 调用，全部收拢到一个命令行工具里，用自然语言去操作，相当于给自己养了一个听话的执行管家。
这个项目的起因很现实。我日常要打交道的工具太多了：系统日历、备忘录、待办清单、闹钟、timeline 上的各种差旅信息，还有一堆不想背参数的命令行脚本。每个工具都在做自己的事，但它们之间没有联系。我明明在日历里建了一个会议，却还要手动去备忘录里写一份准备要点；明明写了一段定时抓数据的脚本，却总忘记在特定时间跑一下。碎片化工具带来的结果，不是效率，而是更多的切换成本。cua 要解决的，就是把我所有的“轻量操作”统一到一个入口下，让我能用说人话的方式去调度它们。
如果你也想给自己搭一个类似的个人助手系统，或者你手里也攒了一堆小脚本但不知道如何组织，这篇东西可以给你一套完整可复现的路径。我不会写那种“三天打造智能管家”的神话，全部都是实际动手过程中的设计取舍、代码片段和踩坑记录。我会解释每个关键选择背后的原因，也会把真正卡住我很久的细节问题原样拆给你看。
1. 项目概述与设计思路
1.1 为什么叫 cua
先说名字。项目标题就是 cua，我给自己定了一个规矩：所有项目先有名字，后有功能。名字很重要，它是你日常输入频率最高的一个词。cua 是我刻意挑的三个字母，简短、无歧义、在终端里不会跟常见命令冲突。全称 Cognitive Unified Assistant 是我后补的解释，为了让它在文档里看起来正式一点。实际使用中，我只需要敲三个字母加一条指令。
cua 要解决的核心痛点，我总结成三个词：碎片化、割裂感、记不住。碎片化指的是功能分散在不同应用里；割裂感是指这些应用之间没有数据流通；记不住则是我自己的问题——脚本参数、API 地址、正则表达式，写过就忘。cua 的定位不是一个超级 AI，而是一个轻量的调度中枢。它负责接收我的请求，把请求解析成可执行的指令，再去调用背后那些真正干活的工具。
这种定位决定了选型方向。我不需要做一个重型的框架，也不需要接一个多聪明的大模型。我需要的是一个稳定、快速、容易被我自己扩展的命令行小系统。Python 的 argparse 或者 click 都能做参数解析，但它们面向的是结构化参数。我想要的是自然语言输入，比如“明天下午三点提醒我给老周回电话”，这种句子如果用 argparse 去解析，等于给自己找麻烦。所以我在第一轮调研时就把方向定成了：自然语言解析 + 规则模板 + 外部工具调用。
1.2 初始版本的范围控制
做个人项目最大的坑，就是范围失控。我第一版的目标清单控制得很窄，只有三类功能：
- 快速记录和查询笔记
- 创建定时提醒和日程事件
- 唤起系统里的常用脚本
这个范围是刻意缩小的。笔记解决了“写了找不到”的问题，提醒解决了“说过会忘”的问题，脚本唤起解决了“不想记命令”的问题。这三个功能已经覆盖了我 80% 的日常需求，而且每一类单独拆出来，技术上都够得着，不会让我陷入三个月写不完的窘境。
我不建议一上来就做语音交互、多端同步、自然语言大模型接入这些花活。个人工具的甜蜜点，是让自己用起来顺手。范围越小，完成度越高，完成度越高，你才会坚持用，坚持用了才有后续迭代的动力。cua 的第一版，说白了就是几个 JSON 文件加一百多行核心逻辑，但正因为简单，它从立项到可用只花了一个周末。
1.3 方案选型：统一入口 vs 碎片化工具
做技术选型时，我的核心考量是入口唯一。市面上有很多工具，比如各种笔记软件、日历应用、剪贴板工具，每一个都做得挺精致，但它们各自为政。cua 的切入点不是替代它们，而是做一个位于它们之上的入口层，术语叫 front-end。我的所有操作都先经过 cua，再由 cua 去决定是记到本地 markdown 文件里，还是生成一个系统通知，或者直接调用某段 Python 脚本。
这个设计带来一个明显的好处：我只需要记忆一种交互方式。以前我可能要记“日历里怎么快速开会”“备忘录怎么打标签”“脚本传什么参数”，现在统统简化为一句中文自然语言。坏处也明显：多了一层解析，就多了一层出错的可能。比如我说“明天下午三点提醒我”，cua 得能准确理解“明天下午三点”是哪一天哪个时刻。这种时间解析的坑，我在后面专门讲。
从工程架构来说，cua 分成四层：
- 输入层：命令行接收自然语言
- 解析层：识别意图、抽取出关键实体
- 执行层：根据解析结果调用对应的处理器
- 存储层：笔记、日程配置统一落在本地 JSON 或 Markdown
这四个层级我分别放在四个目录下，parser、handler、storage、utils。这么做不是摆架子，而是为了让我在加新功能时，不用翻遍所有代码。想加一个新命令，只需要在 handler 目录下新建一个文件，然后在映射表里登记一下，cua 就能认得新指令。
2. 核心功能拆解与关键参数
2.1 意图识别与命令路由
意图识别是整个 cua 的大脑。我没有用训练模型那套高大上的方法，而是采用关键词模板 + 规则优先级。原因很简单：我的个人指令集大概不到五十种，规则完全覆盖得住，而且规则引擎的响应是毫秒级的，大模型接口反而要等一两秒。对于“提醒我”这种固定句式，规则匹配的准确率接近百分之百。
我的实现思路是这样的：每一条指令都对应一个正则模板。比如：
提醒我 (.*)对应 reminder 处理器记一下 (.*)对应 memo 处理器(.*) 脚本对应 script 处理器
这看起来很简单，但实际落地时，我加入了两个关键的辅助机制。第一个是意图优先级排序。有些指令同时满足多个模板，比如“记一下明天开会脚本要改”，既像是笔记命令，又像是脚本命令。我的策略是给更具体、更长的模板分配更高的优先级。对于包含“提醒”的句子，优先走提醒；包含“记一下”的句子，优先走笔记。第二个机制是关键词白名单字典。我在解析前先对句子做一次轻量词法扫描，把“提醒”“笔记”“脚本”“日程”这些触发词抓出来，再决定走哪个路由。
核心路由代码和映射表长这样：
# router.py # 每条指令对应一个 pattern，命中的 handler 会在执行器中调用 ROUTES = [ { "name": "reminder", "pattern": r"提醒我?", "priority": 10, "handler": "handle_reminder" }, { "name": "memo", "pattern": r"记(一下|一笔|个)?", "priority": 8, "handler": "handle_memo" }, { "name": "script", "pattern": r"脚本|运行|执行", "priority": 9, "handler": "handle_script" }, ]优先级数字越大的先匹配。这个表我用一个普通 JSON 文件维护，已经运行了几个月，没有出现过一次路由错乱的情况。如果你要复刻这个方案，我的建议是：先把你自己的指令需求列成表，再为每个指令设计模板。自己做规则引擎，最忌讳为了通用性把模板写得太抽象，那样反而把简单问题搞复杂。
2.2 时间解析的逻辑与参数计算
时间解析是 cua 里技术含量最高的一部分，也是我踩坑最多的部分。中文自然语言里的时间表达非常灵活，光是“明天下午三点”就有好几种等同说法：明天下班时、明天三点、明天15:00。我的解决思路是分步回归：先把能格式化的时间表达用正则捕获，再对剩余模糊表达做规则替换，最后统一转换为时间戳。
这里我给出一个实际演示。假设用户输入：
明天下班后提醒我提交周报
解析步骤是这样的：
- 先识别日期词：“明天”，当天日期加上一天得到目标日期。
- 再识别时间词：“下班后”。我维护了一个时间段映射表，把“下班后”“晚上”“午休”“早晨”这类词映射到具体时间点。比如“下班后”默认是 18:00，“晚上”默认是 20:00。
# time_parser.py # 基础日期偏移和时段映射 import datetime import re DAY_OFFSET = { "今天": 0, "明天": 1, "后天": 2, "大后天": 3, } PERIOD_MAP = { "早上": (7, 0), "上午": (9, 0), "中午": (12, 0), "下午": (14, 0), "下班后": (18, 0), "晚上": (20, 0), } def parse_datetime(text, now=None): now = now or datetime.datetime.now() day_offset = 0 for word, offset in DAY_OFFSET.items(): if word in text: day_offset = offset break target_date = now.date() + datetime.timedelta(days=day_offset) hour, minute = None, 0 for period, (ph, pm) in PERIOD_MAP.items(): if period in text: hour, minute = ph, pm break # 如果同时匹配到 "3点"、"15:30" 这类显式时间，优先使用显式时间 m = re.search(r"(\d{1,2})[:：点](\d{1,2})?", text) if m: hour = int(m.group(1)) minute = int(m.group(2)) if m.group(2) else 0 if hour is None: # 未识别到任何时间，默认取当前时间后一小时 delta = datetime.timedelta(hours=1) target_dt = now + delta else: target_dt = datetime.datetime.combine(target_date, datetime.time(hour, minute)) return target_dt这段代码有一个很典型的取舍：显式时间优先于时段映射。因为用户明确说出“三点”的时候，他显然期望是 3 点，而不是我在“下午”映射里预设的 14 点。真实开发中，参数计算的本质是排列优先级，不是把所有情况写成并列关系。
2.3 笔记存储的结构设计
笔记系统我一开始想了很久，最后决定用最笨也最稳的方案：本地 Markdown 文件 + 索引 JSON。每个笔记存成一个带时间戳的 md 文件，文件名格式是note_YYYYMMDD_HHMMSS.md，文件头部自动写入 metadata，包含标题、创建时间、标签。索引 JSON 只维护摘要和文件路径，方便快速搜索，不至于每次都要扫描磁盘上的所有 md 文件。
这个设计的核心考量是可迁移性。Markdown 是纯文本，任何时候我都能用其他工具打开、查看、编辑，不会被 cua 绑架。索引丢失了也没关系，重新扫描一遍就能恢复，数据永远在本地。相比用 SQLite 或者某个云端服务，这种方案地成本几乎为零，但我换来的却是完全的控制权。
下面是写笔记时的核心函数：
# storage.py import json, os, datetime NOTES_DIR = os.path.expanduser("~/.cua/notes") INDEX_FILE = os.path.expanduser("~/.cua/notes_index.json") def save_note(title, content, tags): os.makedirs(NOTES_DIR, exist_ok=True) timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S") filename = f"note_{timestamp}.md" filepath = os.path.join(NOTES_DIR, filename) tag_text = ", ".join(tags) if tags else "默认" with open(filepath, "w", encoding="utf-8") as f: f.write(f"# {title}\n\n") f.write(f"- 创建时间: {datetime.datetime.now().isoformat()}\n") f.write(f"- 标签: {tag_text}\n\n") f.write(content) # 更新索引 index = [] if os.path.exists(INDEX_FILE): with open(INDEX_FILE, "r", encoding="utf-8") as f: index = json.load(f) index.append({ "title": title, "file": filename, "tags": tags, "created": datetime.datetime.now().isoformat() }) with open(INDEX_FILE, "w", encoding="utf-8") as f: json.dump(index, f, ensure_ascii=False, indent=2) return filepath这里有一个细节：更新索引时，我没有做全文索引，只存了标题和标签。原因是全文搜索可以用 grep 或者 rg 命令实现，没必要自己维护倒排索引。把时间花在真正会出问题的地方，比如时间解析和命令路由，比什么都重要。
2.4 提醒机制的执行细节
提醒功能是 cua 里给我带来实际价值最大的功能。它的执行机制是这样的：解析完用户的提醒请求之后，计算目标时间和当前时间的差值，生成一个带sleep的线程任务，同时把任务持久化到reminders.json。这样即使程序重启，也能通过扫描 JSON 文件恢复未触发的提醒。
这种方案有几个关键参数。一个是提前量。比如“明天下午三点提醒我开会”，我的系统默认会提前 10 分钟触发一次预备提醒，然后到点再触发一次正式提醒。这个“提前 10 分钟”不是拍脑袋定的，是我观察自己使用习惯得到的经验值——提前 10 分钟看到提醒，我有足够时间收拾手头的事情，又不至于忘记。你也可以根据自己的习惯，把这个参数调成 15 分钟或 5 分钟。
另外一个参数是重复规则。“每天早上提醒我吃药”这种周期性提醒，就需要用到 cron 表达式。我在 cua 里内置了一个简单的 cron 解析器，支持分、时、日、月、周五个字段。实现不复杂，但周期任务的判断逻辑里有一个高频陷阱：跨天判断。比如设置每天早上 8 点的提醒，当任务线程 sleep 一整天后，到了一个奇怪的时刻，需要提前算好下一个触发点，而不能简单用“当前时间加上 24 小时”处理，因为夏令时和跨时区会导致偏差。
# schedule.py def next_trigger(cron_expr, now): minute, hour, day, month, week = cron_expr.split() # 简化判断：每分钟检查一次当前字段是否匹配 candidates = [] # 生成未来24小时内的候选时间点 for offset in range(1, 24 * 60 + 1): candidate = now + datetime.timedelta(minutes=offset) if match_cron(cron_expr, candidate): candidates.append(candidate) if len(candidates) >= 5: break return candidates3. 实操过程与核心环节实现
3.1 基础框架搭建
前面讲了设计和原理，现在我完整走一遍实操。cua 的最小骨架，我推荐用 Python 的argparse做命令行入口，配合subcommand机制。为什么不用click？因为我不想为了一个个人工具引入额外依赖，argparse 是标准库，随处可用。核心 CLI 入口长这样：
cua 记一下 晚上八点和老张吃饭 cua 提醒我 明天上午十点交方案 cua 查询 所有笔记 cua 运行 日报脚本入口解析脚本如下：
# cli.py import sys from parser.intent import parse_intent from handlers.dispatcher import dispatch def main(): args = sys.argv[1:] if not args: print("用法: cua [自然语言指令]") return text = " ".join(args) intent, entities = parse_intent(text) if not intent: print("抱歉，我没有听懂。试试包含'提醒''记一下''运行'这些词") return result = dispatch(intent, entities) print(result) if __name__ == "__main__": main()在 Linux 或 macOS 上，我把这个脚本软链到/usr/local/bin/cua，就能在任意目录直接调用。整个搭建过程不超过十分钟。我特意不在这个项目里引入复杂的依赖和初始化流程，个人工具的启动速度比别人少一个量级，用起来才爽。初期调试时，我会开一个 debug 开关，把解析结果打印出来，用来验证每一条规则是否按预期工作。
3.2 意图识别模块实战
意图识别模块的完整实现，我拆成三层：预处理、模式匹配、实体抽取。预处理阶段做三件事：去除多余空格、统一中英文标点、转小写。这里有一个容易被忽略的坑：用户可能在“提醒我”和指令内容之间输入了全角冒号，比如“提醒我：明天交周报”，如果不把全角冒号处理成空格，正则匹配就会失败。
模式匹配阶段，我维护一个intents.json文件，格式如下：
[ { "name": "reminder", "patterns": ["提醒我", "记得提醒", "到点提醒"], "entities": ["time", "task"], "priority": 10 }, { "name": "memo", "patterns": ["记一下", "记个", "备忘录", "快速记录"], "entities": ["content", "tags"], "priority": 8 } ]实体抽取阶段，我会根据意图类型调用不同的抽取器。提醒的抽取器会调用时间解析函数；笔记的抽取器则负责提取标题、标签。每次匹配时，我用total_match_count作为排序键，匹配数越多越优先。比如“提醒我明天给客户回电话”和“给客户回电话”都命中提醒，但前者多了“明天”这个时间词，会提取出更完整的时间实体。
3.3 时间解析模块的坑与解法
时间解析是这个项目里我修复次数最多的模块。我先列一个容易踩的坑单，这些都是我真实遇到并解决过的。
第一个坑是时间词重叠。“明天下午三点”同时包含“明天”“下午”“三点”，我的第一阶段正则会把“三点”提取出来，第二阶段又检测到“下午”，于是生成了 3:00 而不是 15:00。解决办法是引入优先级约束：检测到显式的小时数时，如果小时数小于等于 12，且前面同时存在“下午”“晚上”“中午”这些时段词，就把小时数自动加上 12。这个规则在绝大多数场景下是合理的。
第二个坑是跨午夜提醒。“凌晨零点半提醒我”这句，解析出来的时间大概率是 00:30，但当前时间如果是 23:50，说明用户想要的很可能是下一个凌晨 00:30，而不是已经过去的今天 00:30。我的处理办法很直接：当计算出的目标时间已经早于当前时间，自动加上一天。这在语义上符合大部分人的生活经验。
第三个坑是模糊时间与具体时间的冲突。比如“下午3点之前提醒我开会”，这里“之前”是一个截止边界，不是触发时间。我的系统会解析出两个实体：一个时间点（15:00），一个约束（deadline）。在生成提醒任务时，如果存在截止时间，触发时间要取 15:00 减去一个预设的提前量。这种实体关系建模，光靠正则是不够的，我加了一层简单的规则树，专门处理“之前”“之前半小时”“内”这类相对时间词。
3.4 外部 API 与工具链接入
cua 的定位是一个调度中枢，必然要接外部工具。我第一个接入的是系统的notify-send（Linux 桌面通知），这样提醒触发时，系统右上角会弹出通知。第二个接入的是at命令，用于后台定时任务。第三个接入的是一个内部数据抓取脚本，每天定时抓取几个网站的数据，生成汇总报告。
接入方式统一做成 handler 模式。每个 handler 是一个独立的 Python 文件，暴露一个handle(entities)接口。录入新工具时，我只需要在handlers目录新建文件，在路由表添加一条，重新加载配置即可。比如新增一个天气查询工具：
# handlers/weather.py def handle(entities): city = entities.get("city", "北京") days = entities.get("days", 1) # 调用一个天气 API result = call_weather_api(city, days) return f"{city}未来{days}天天气：{result}"在路由注册表里添加：
{ "name": "weather", "patterns": ["天气", "气温", "下雨"], "entities": ["city", "days"], "handler": "weather", "priority": 7 }接入 API 最重要的一个经验是超时控制。外部 API 有时候会卡住，导致 cua 的响应变得很慢。我统一在 API 调用层加了 timeout 参数，默认 5 秒超时。一旦超时，直接返回“服务暂时不可用”的提示，而不是让用户傻等。这个设置让 cua 的整体稳定性提升了一个量级，再也没有因为某个第三方接口抽风而卡死整个命令入口。
4. 常见问题与排查技巧实录
4.1 识别不准确：规则过宽或过窄
规则引擎最大的风险是模板写得不好。我的经验是：每个模板至少满足三条真实输入，再进主库。如果只拿一条样例写模板，很容易过拟合。比如“运行日报脚本”，和“运行周报脚本”可能只差一个字，如果在模板里写死了“日报”，那第二句就会跑到无关 handler 里去。
解决识别不准确的问题，我主要靠两个手段。一是日志回放。我在 debug 模式下会把所有输入的解析结果写入~/.cua/logs/parse.log。每周翻一次日志，发现哪条输入解析错了，就针对性地调整模板。二是同义词表。我把不同用户习惯下的同义表达集中放在一个字典里，比如“提醒”“别忘了”“记得”“提醒一下”都会映射到同一个触发器。这个字典是我自己长期维护的，迭代成本低，却非常实用。
4.2 时间解析的边界场景
我把时间解析遇到的问题整理成一张速查表，方便你直接对照排查：
| 输入情况 | 问题表现 | 解决方案 |
|---|---|---|
| 明天下午三点 | 生成 3:00 而非 15:00 | 显式小时 ≤12 且有时段词时加 12 |
| 凌晨零点半 | 目标时间已过去 | 目标时间早于当前时间时自动加一天 |
| 周五之前提醒 | 不知道“之前”扩展到哪天 | 默认取本周五，超过当前周取下一周 |
| 默认时间缺失 | “提醒我喝水”没有时间词 | 统一取当前时间后的一小时 |
| 跨周重复提醒 | 每周一早上点容易忘记计算 | cron 匹配用“最近未来时间”算法 |
这张表里的第五个问题，是周期提醒最容易出事的。比如“每周一下午两点开会”，在非周一设置时，如果往未来 24 小时找，永远找不到下周一，因为下周一可能在 6 天后。我最终实现的算法是：至少向后搜索 14 天。这个经验数值足够覆盖所有周级任务，又不会因为搜索空间太大影响性能。
4.3 命令冲突与优先级设计
命令冲突是一个隐蔽但高频的问题。我的最初版路由逻辑，是完全按照优先级顺序，一旦命中就立即返回。后来发现一个问题：比如输入“提醒我明天记一下季度末的账”，这句话同时含有“提醒”和“记一下”两个触发词。用户真实意图可能是“提醒我”一个动作，这个动作的内容是“明天记一下账”。但我的旧逻辑会匹配到“记一下”，直接当作备忘录存储，错过了设置提醒的机会。
解决思路是我自己发明的意图粘合机制。当一句子里出现多个触发词时，先判断它们的位置关系。如果“提醒我”出现在句首，而“记一下”出现在中后部，那么“记一下”更像是提醒的具体内容，而不是独立指令。因此，整句应该路由到 reminder，并且把“明天记一下季度末的账”作为提醒的任务内容。这个规则虽然粗糙，但覆盖了我能想到的大多数情况，几个月下来没有误报过。
4.4 性能与资源占用优化
cua 的核心逻辑简单，资源占用本来就不大，但我在实际使用中还是遇到了两个性能问题。第一个是笔记索引无限增长。用了两个月后，索引 JSON 文件变大，每次读写都要全量 serialize，有一点卡顿。解决办法很简单：索引只保留最近 500 条，更早的记录不进入索引，而是直接通过 ripgrep 搜索原文。这样索引清理任务每隔一周自动跑一次，性能恢复正常。
第二个问题是提醒扫描线程空转。我初始版本是每秒钟扫描一次所有未触发的提醒，即便没有任务也会空转。优化后改为所有提醒根据最早触发时间动态调整睡眠时间：把当前时间和最近一条提醒的时间差值算出来，先 sleep 这段时间，等到快触发时再恢复秒级扫描。这个改动让 cua 的常驻内存占用从 40MB 降到了 8MB 左右，对于命令行工具来说，已经非常轻了。
5. 后续扩展与个人使用体会
5.1 可以自然生长的功能模块
cua 这套架构最大的好处是扩展成本低。我后续一直在往里加模块，每加一个 handler，平均只需要十几分钟。目前已经接入的功能包括：查询天气、生成周报、快速记账、倒计时、定时抓取网页摘要。每一个模块都是独立文件，互不干扰。
如果你想复刻这个项目，我的建议是从一个小范围开始，先跑通“笔记 + 提醒 + 脚本”这三个核心功能，用上两周再说。个人工具的粘性，不是看功能列表有多华丽，而是看你在日常生活里有多愿意用它。功能太多，反而增加记忆负担。cua 虽然能支持几十条指令，但我平时高频使用的也就那么七八条。真正好用的个人助手，应该能让人把常用操作变成肌肉记忆。
5.2 我在维护中积累的三个习惯
第一，保持端到端可测试。我给 cua 写了几条固定的冒烟测试，比如输入“记一下测试笔记”“提醒我明天早上开会”，每次改完代码都会跑一遍，确保核心链路不坏。这不是为了多么严谨的工程质量，而是个人项目必须保证改动不破坏自己每天都在用的路径。
第二，日志是最好的老师。我在日志里记录了每一条原始输入和解析结果。每次感觉 cua 变笨了，我就翻日志，看哪条指令没有被正确解析。这种数据驱动的改进方式，比凭空猜测用户意图高效得多。
第三，允许自己偷懒。不是所有指令都必须用自然语言，cua 同时也支持几个快捷键命令，比如cua t直接打开今日待办列表。个人工具不需要为了统一的优雅而牺牲便捷，什么时候偷懒都行。
5.3 一点提醒：个人工具的边界
最后分享一点个人体会。cua 再聪明，它也只是个工具。我不主张把重要决策、复杂项目管理全部交给它。个人助手最适合承接的，是那些低频但不能再丢的琐事，以及高频但足够机械的操作。真正的思考、判断和规划，永远应该留在自己脑子里。
对我而言，cua 最大的贡献，不是省了多少时间，而是让我建立了一套统一处理杂事的心智模型。每次输入一句指令，我都会下意识地思考：这件事的核心实体是什么，最迟什么时候要完成，应该用什么方式去追踪。有了这套模型，哪怕脱离 cua 这个工具，我的工作效率也提高了不少。如果你打算搭建自己的工具，希望这篇记录能帮你把第一个版本快速落地，并且少踩几个我踩过的坑。
