Posts

从幻觉到问责：个人助理的可靠性边界

个人助理不可能永不出错。

真正需要的是可靠性边界：哪些结论必须有来源，哪些动作必须确认，哪些失败必须记录，哪些责任不能交给模型。

幻觉不是唯一问题

幻觉只是错误的一种。

个人助理还会遇到工具失败、权限错误、记忆污染、计划失效、环境变化和多步任务中断。如果只盯着“模型会不会编”，会漏掉很多工程问题。

可靠性的四个要求

我更关心四件事：

可见：错误不能被隐藏。
可追踪：知道错误来自哪里。
可恢复：失败后能继续或回滚。
可问责：知道哪些决定由人确认。

这比承诺“不会错”更现实。

事实类回答要有来源

查资料、查配置、查日志时，Agent 应该说明依据。

如果没有来源，就应该标注不确定，而不是编一个确定答案。事实类任务的底线是：不知道可以说不知道。

执行动作要有确认

会改变外部状态的动作都要更谨慎。

删除文件、修改配置、推送代码、重启服务、发送公开消息、财务操作，都应该在执行前说明影响，并等待确认。

错误要进入复盘

每次重要失败都应该能进入复盘：

错在哪里？
为什么没被提前拦住？
是否需要改 Skill？
是否需要改工具权限？
是否需要写入 QPC？

可靠性不是一次完成，而是持续收紧边界。

边界越清楚，助理越可信

个人助理的可信度，不来自它永远自信，而来自它知道什么时候停下来、什么时候引用来源、什么时候请求确认。

这就是从幻觉治理走向问责机制。

Posts

哪些能力应该内置，哪些应该交给工具

个人助理智能体的核心不应该越来越大。

很多能力看起来都值得内置：写文件、查网页、发消息、部署服务、整理知识、生成报告。但核心越大，越难测试、越难替换、越难限制权限。

更稳的原则是：判断和边界内置，具体动作交给工具。

应该内置的能力

内置能力应该少而稳定：

请求理解。
用户身份和上下文识别。
Skill 路由。
权限判断。
人工确认机制。
日志记录。
失败降级策略。

这些能力决定系统是否可控，适合放在核心链路里。

应该交给工具的能力

具体动作适合交给工具：

文件读写。
搜索网页。
查询数据库。
创建提醒。
部署服务。
生成图片。
读取知识库。

工具可以独立替换、禁用和限制权限，不应该让核心直接承担所有细节。

判断标准

可以用三个问题判断：

这个能力是否几乎每个任务都需要？
它是否决定权限和安全边界？
如果它坏了，是否会影响整个系统？

如果答案是是，考虑内置。否则优先做成工具或 Skill。

为什么不要把工具逻辑写进核心

工具逻辑变化很快。

今天用一个 API，明天换另一个 API；今天是本地文件，明天是远程存储。如果把这些细节塞进核心，系统会越来越难维护。

核心应该负责选择工具、检查权限、记录结果，而不是直接知道每个工具的全部实现。

最小核心更可靠

个人助理长期可用，靠的不是核心什么都会，而是边界稳定。

一个小核心加一组可替换工具，比一个巨大控制器更容易调试、审计和恢复。

Posts

工具调用失败时，Agent 应该怎样降级

Agent 的可靠性，往往不是看它成功时有多聪明，而是看它失败时怎么处理。

工具调用失败很常见：路径不存在、参数错了、网络超时、权限不足、接口返回格式变化。个人助理必须把失败当成正常路径，而不是异常意外。

不要假装成功

最坏的失败方式，是工具失败后继续输出成功结论。

例如构建命令失败，却说“已部署”；文件没写入，却说“已保存”；搜索不到资料，却编一个结果。这会直接破坏信任。

Agent 必须把工具返回结果当成事实来源，而不是只根据意图推断结果。

第一步：识别失败类型

失败先分类：

参数错误：输入格式、路径、字段不对。
权限错误：没有读写、执行或网络权限。
环境错误：命令不存在、依赖缺失、服务未启动。
网络错误：超时、DNS、API 不可达。
业务错误：接口返回成功但结果不符合预期。

分类之后，才知道能不能自动恢复。

第二步：有限重试

有些失败可以重试，例如网络超时或临时服务抖动。

但重试必须有限制。无限循环重试会浪费资源，还可能造成重复写入或重复请求。

一个简单规则是：

只对幂等或只读操作自动重试。
写入操作默认不自动重试，除非有明确幂等键。
重试次数固定，例如 1-2 次。
每次重试记录原因。

第三步：换工具或换路径

如果失败来自工具不可用，可以尝试替代路径。

例如 rg 不可用时用 PowerShell 搜索；Hugo 不在 PATH 时使用临时下载的二进制；网页无法访问时改用本地文件或缓存。

换工具前要保证语义一致。不能因为搜索失败，就把猜测当成搜索结果。

第四步：询问用户

当缺少关键信息，或者继续执行会改变外部状态时，应该停下来问用户。

适合询问的情况：

目标路径有多个候选。
需要凭据或人工登录。
操作可能覆盖现有数据。
高风险动作没有确认。
自动恢复会引入新假设。

询问不是失败，而是正确的降级。

第五步：记录失败

失败应该留下记录。

至少记录：

失败发生在哪个 Skill。
调用了哪个工具。
输入摘要是什么。
错误信息是什么。
是否重试。
最终是否需要人工处理。

这些记录以后可以变成 QPC 知识或维护手册。

降级决策表

失败类型	默认处理
参数错误	修正参数后最多重试一次
权限错误	停止并请求人工处理
环境缺失	查找替代工具或说明安装需求
网络超时	有限重试
写入不确定	停止，检查状态后再继续
高风险动作	请求人工确认

个人助理的底线是：失败要可见，恢复要可解释，不能为了完成任务牺牲可靠性。

Posts

打造精简个人助理智能体：系列总览

个人助理智能体最容易走偏的地方，是一开始就追求“大而全”。

真正长期可用的个人助理，应该先做到小、稳、可维护：能记住关键偏好，能调用少数可靠工具，能在失败时留下线索，能把高风险动作交还给人确认。

这组文章记录我围绕 Hermes-lite、QPC、Skill 路由和个人知识系统搭建精简助理智能体的过程。

系列目标

这个系列关注四个问题：

个人助理智能体的最小可用架构是什么。
怎么让记忆、知识库、工具调用和任务状态互相配合。
怎么在低资源 VPS 上稳定运行，而不是堆复杂组件。
怎么处理幻觉、工具失败、崩溃、多 Agent 协调和治理边界。

目标不是复刻一个复杂平台，而是形成一套个人可长期维护的系统。

当前已发布文章

架构与记忆

Hermes-lite 与部署

知识库与路由

可靠性专题

建议阅读框架

1. 最小架构

先回答个人助理需要哪些最小组件：入口、模型路由、技能路由、工具层、记忆层、日志和人工确认。

Posts

日志、备份和升级：长期运行的维护手册

个人助理智能体不是写完就结束。

只要它长期运行，就会遇到模型变更、API 失败、服务器重启、配置漂移、磁盘满、日志爆炸、密钥过期和工具失效。维护手册的价值，是让这些问题不靠临场发挥。

日志：先能看见问题

日志至少要回答：

用户发了什么请求。
命中了哪个 Skill。
调用了哪些工具。
工具是否成功。
失败原因是什么。
是否触发人工确认。

日志不需要记录完整隐私内容和密钥，但要足够支持排查。

日志检查频率

可以分三类：

日常：查看错误数量和最近失败。
每周：检查是否有重复失败模式。
每月：把高频失败整理成 QPC 或修复任务。

日志如果只写不看，就没有维护价值。

备份：先备配置和记忆

个人助理最重要的资产通常不是程序本身，而是配置、密钥引用、知识库和长期记忆。

备份优先级：

配置文件。
知识库或记忆数据库。
自定义 Skill。
部署脚本。
关键日志样本。

密钥本身要按安全方式保存，不应该明文塞进普通仓库。

恢复演练

没有恢复演练的备份，只是心理安慰。

至少要知道：

新机器上如何恢复配置。
如何恢复知识库。
如何重新启动服务。
如何验证入口和工具调用。
如何回滚到上一个可用版本。

恢复流程应该写成清单。

升级：小步走

升级模型、依赖或系统服务前，先看影响范围。

建议流程：

记录当前版本。
备份配置和记忆。
阅读变更说明。
小范围验证核心任务。
观察日志。
保留回滚路径。

不要在没有备份的情况下升级关键组件。

安全检查

每月做一次轻量安全检查：

是否有多余开放端口。
面板是否仍有认证保护。
密钥是否泄露到日志。
配置文件权限是否过宽。
高风险工具是否仍需人工确认。
依赖是否有明显安全更新。

个人助理越连接真实世界，越需要定期检查边界。

人工接管流程

当系统异常时，Agent 应该知道如何停下来。

人工接管流程包括：

停止自动执行高风险动作。
保留现场日志。
输出当前任务状态。
列出已完成和未完成动作。
等待人工决定是否继续。

这比“自动修复一切”更可靠。

维护手册的目标

维护手册不是为了把系统变复杂，而是为了让未来的你不用猜。

Posts

记忆系统的五层结构：从上下文到长期偏好

个人助理需要记忆，但不能什么都记。

更好的方式是分层：不同信息有不同生命周期、写入规则和检索方式。五层结构可以让记忆系统既有用，又不变成垃圾桶。

第一层：当前上下文

当前上下文只服务本轮任务。

它包括用户刚说的话、当前文件、最近命令输出和中间推理。任务结束后，大部分上下文应该丢弃。

第二层：任务状态

任务状态回答“做到哪里了”。

例如某篇博客已经写完但未构建，某个部署已经构建但未推送。任务状态应该在完成后归档，不应长期占用活跃记忆。

第三层：用户偏好

用户偏好影响输出方式。

例如喜欢中文回答、偏好短句、提交前必须构建、不要自动执行高风险操作。偏好必须来自稳定信号，不能把一次性表达写成长期规则。

第四层：稳定事实

稳定事实是关于项目和环境的信息。

例如仓库路径、部署方式、默认分支、常用配置。事实会过期，所以必须允许更新和校验。

第五层：长期知识

长期知识是以后会反复使用的信息。

例如踩坑、命令模板、文章素材、架构说明、QPC 条目。它不一定总在上下文里，但需要可检索。

写入规则

每次写入记忆前问：

它属于哪一层？
生命周期多长？
是否经过用户确认？
是否可能过期？
写错后影响多大？

分层的目的，是让个人助理记住真正有价值的东西，而不是把一切都存起来。

Posts

高风险工具的权限边界和确认机制

工具让 Agent 有行动能力，也让错误有了现实后果。

高风险工具不能只靠 prompt 约束。它们需要明确权限边界和确认机制，让 Agent 在执行前停下来，把影响说清楚。

什么是高风险工具

高风险工具包括：

删除或覆盖文件。
修改生产配置。
执行远程命令。
重启线上服务。
推送代码。
发送公开消息。
调用财务或账户相关 API。

共同点是：影响外部状态，且不一定容易撤销。

执行前必须说明

确认信息至少包括：

将执行什么动作：
影响哪些文件/服务/账户：
是否可回滚：
回滚方式：
不执行的后果：
需要用户确认的内容：

这让风险显式化。

默认只生成建议

高风险工具的默认模式应该是建议。

Agent 可以生成命令、说明步骤、列出风险，但不直接执行。只有用户明确确认后，才进入执行阶段。

执行后要记录

执行后记录：

时间。
工具。
输入摘要。
输出结果。
是否成功。
后续检查项。

如果失败，要进入失败分类表。

确认机制不是拖慢系统

确认机制的目的不是降低效率，而是保护不可逆边界。

个人助理最重要的能力之一，是知道什么时候不能替你做主。

Posts

Agent 的记忆：Hermes-Lite 如何用 5 层结构解决「鱼的难题」

人类 chatbot 最尴尬的瞬间：第二次见面完全不认识你。Agent 的记忆系统怎么同时做到持久化、低成本、不丢上下文？我深入 Hermes-Lite 源码写了一个月，拆解出 5 层架构。

从「鱼的难题」开始

用过 ChatGPT 的人都知道一个痛：下次打开，它完全不记得你了。

对一次性聊天这没问题。但对个人助理——帮你管理 200 条知识库、追踪几个项目的进度、记住你的偏好——这等于每次都要把整段友情重来。

我做 QPC（个人知识库）时就被这个问题卡过。后来折腾 Hermes-Lite、nanobot，逐步摸到一条可行的路。这篇文章从 Hermes-Lite 的实际源码出发，拆解它的 5 层记忆架构，看看一个 Agent 是怎么解决「鱼的难题」的。

总览：5 层架构

┌─────────────────────────────────────────────┐
│  Layer 1: 持久记忆 (MEMORY.md / USER.md)     │  ← 跨会话，纯文本
├─────────────────────────────────────────────�
│  Layer 2: 会话压缩 (ContextCompressor)       │  ← 长对话不爆
├─────────────────────────────────────────────┤
│  Layer 3: 会话检索 (session_search + FTS5)   │  ← 历史不丢
├─────────────────────────────────────────────�
│  Layer 4: 增量写入门控 (Nudge 机制)           │  ← 该记就记
├─────────────────────────────────────────────�
│  Layer 5: 原子性保障 (fcntl + 临时文件)       │  ← 不丢不坏
└─────────────────────────────────────────────┘

每一层解决一个独立问题，层与层之间不耦合。下面逐层拆解。