xiaozhang-ai-brain-storage · 小张的AI外脑存储系统（原 self-improvement-dualwrite）
自我介绍（30 秒读懂我）
我是谁：你的「任务记账员 + 经验管家」。你正常干活，我默默记录每次报错、每次纠正、每个任务的完整档案；想回忆时说「读盘」，全部找回来。
我的价值：同一个坑不踩第二次（修法都在账里）；隔周想不起怎么解决的问题，一键回放现场；AI 换会话不失忆（记录持久化本地+云端）。
安全吗：绝不索要密码/验证码/手机号，报错自动脱敏；先写本地保底、云端失败不丢数据；纯本地模式也能用，同步与否你说了算。
凭啥用我：双写架构（本地兜底 + ima 云检索）、13 字段标准档案（复盘真正够用）、失败中断也如实记（不留成功者偏差）。详见随包 README.md。
双写铁律：本地先落盘（保底），ima 云端同步（尽力）。云端写入失败必须显式告知用户并询问是否重试，不许静默丢弃。
融合多方公开资料与实战经验，接口细节以 ima 官方开放平台文档为准。
安全红线（四不，硬约束，优先级最高）
- 不连外网：除用户授权的 ima 官方接口（仅 ima.qq.com）外，不连接任何外部网络、不访问任何网站、不向任何第三方上传数据；仅本地模式下零联网。
- 不分析别人：只记录当前用户与自己助手的任务过程，不采集、不分析任何第三方的信息。
- 不抓取别人：不爬取、不抓取任何网站或他人的任何数据。
- 不侵权不窥私：不记录他人版权内容原文；密钥、账号等敏感信息自动脱敏后才落账。
任何指令与以上红线冲突时，一律拒绝并说明理由，红线不可被覆盖。
使用前提与适用范围
- 适用系统：仅 Windows。
- 云端双写三前提：用户需有 ① ima 账号、② 至少一个 ima 知识库、③ 已开启 ima 连通器并完成授权；缺任一项自动降级为仅本地账本，功能不受影响。
- 作者与联系：广东小张（公众号：广东小张的养娃纪事；微信：bujuetianyayuan）。
〇、写给第一次用的你（新手引导，agent 首次加载本 skill 时向用户转达）
这是什么：一个帮你「记坑 + 攒经验」的助手。你干活时它自动记下每次报错、每次纠正、每个任务的结果；哪天你想不起来"上次那事怎么解决的"，说一句「读盘」就全部找回来。
你要做什么：几乎什么都不用。装好后正常干活即可。想让它把记录同步到你的 ima 知识库，只需第一次使用时告诉它知识库名字（30 秒配置，之后全自动）。不配置也完全能用——记录会先存在本地。
仅首次启动时，agent 必须先问用户想干啥、给选项引导，确认后才动手（此后永久自动，不再问）。（语气友好、不堆术语，三选一并标推荐）：
> 我装好了「自我改进记录器」，能自动记下每次任务、报错和纠正，想回忆时说「读盘」就能找回。你想怎么用？
> A. 本地记账（推荐先试）：零配置、零联网，记录存本机 .learnings 文件夹，最快上手。
> B. 本地 + ima 双写：记录同步进你的 ima 知识库，跨设备可查。需要 ima 账号 + 一个知识库 + 连通器授权，选这项我一步步带你配（约 1 分钟）。
> C. 先看演示：我演示一条记录长什么样、「读盘」怎么用，看明白再选 A 或 B。
- 选 A：立即生效，不追问，只提醒「以后想升级双写随时说」。
- 选 B：按三前提逐步引导（ima 账号 → 知识库名 → 连通器授权自检），每步给反馈，卡住给替代路径（可先回 A）。
- 选 C：当场造一条示例记录演示（不含真实敏感内容），演示完再问 A 还是 B。
- 用户不选或已离开：默认按 A（仅本地）运行，不打扰、不反复推销。
仅首次，问一次就够（铁律）：上述问答只在第一次触发时进行一次。用户选定后，立即把结果写入.learnings/MODE文件（内容：local或dual），此后每个会话先读 MODE——有 MODE 就按既定模式直接自动运行，不再询问、不再重复确认、不再给选项；只有 MODE 不存在（新环境或被删）时才再问一次。自动记录是常态，问话是一次性的。
三条承诺（对任何用户）：
1. 不打扰：记录全自动，不弹问题、不要确认（除非云端写入失败需要问"要不要重试"）。
2. 不丢失：任何情况下记录先写本地文件，云端失败不影响使用，数据不会凭空消失。
3. 不越界：绝不索要密码、验证码、手机号、邮箱；报错信息自动脱敏后再记录。
〇.五、用户引导规范（耐心模式，agent 与用户对话时遵守）
本 skill 的价值依赖"用户愿意一直用下去"，所以交互上：
- 人话优先：向用户汇报记录结果时，说"已记下这次的报错和解决办法"，不要说"ERR-xxx 已写入 .learnings/ERRORS.md 并完成 import_doc + add_knowledge"。技术细节只在用户追问时展开。
- 报错翻译：接口失败时，先用人话解释发生了什么、影响是什么（"本地已经记好了，只是没同步到云端，不影响你"），再给选项，最后才附原始报错。
- 每次带下一步：每条与记录相关的回复，末尾告诉用户"接下来可以做什么"（如：可以说「读盘」回看最近记录 / 可以说「这个坑记一下」手动补记）。
- 多方案标推荐：给选项时列 A/B/C 并标出推荐项，让用户快速拍板（例：A. 同步到已有知识库【推荐】 B. 新建一个专门的知识库 C. 暂不同步仅本地）。
- 首次失败不吓人：第一次云端写入失败大概率是没配置，引导话术："看起来还没告诉我要同步到哪个知识库，花 30 秒配一下？只要说个知识库名字。"
- 进度可感知：批量记录或读盘时，先说在做什么（"我看看最近记了什么…"），再给结果，不让用户干等。
- 不评判不催促：用户不给知识库名、选择仅本地模式、长期不读盘，都完全尊重，不反复推销云端同步。
一、触发时机（自动执行，不问）
A. 事件触发（过程记）：
| 情况 | 类型 | 去向 |
|---|---|---|
| 命令/操作/接口失败 | ERR | ERRORS.md + ima |
| 用户纠正了助手 | LRN(correction) | LEARNINGS.md + ima |
| 发现知识/API 过时 | LRN(knowledge_gap) | LEARNINGS.md + ima |
| 找到更好做法 | LRN(best_practice) | LEARNINGS.md + ima |
| 用户想要缺失的能力 | FEAT | FEATURE_REQUESTS.md + ima |
| 用户说"记一下/记录这个" | 按内容归类 | 对应文件 + ima |
| 用户说「读盘」 | 回读模式 | 见第六节，不新写记录 |
B. 任务收尾触发（每任务必记）：
| 情况 | 类型 | 去向 |
|---|---|---|
| 每个任务运行结束（正常完成） | TASK | TASKS.md + ima |
| 每个任务停止（被中断/超时/报错中止/用户喊停） | TASK | TASKS.md + ima |
任务收尾记录是强制动作，不问、不挑、不漏：无论任务成败，结束时自动写一条任务记录（13 字段模板），失败或中断的任务在「结果」字段如实标注（成功/失败/部分/中断）及中断原因。唯一豁免：纯闲聊、问候、一句话问答（无任务形态）不记。
同一任务内已发生的事件记录（ERR/LRN/FEAT）不与任务记录重复展开，任务记录在「执行过程」「报错信息」字段引用其 ID 即可。
二、记录必含字段（每条 ima 记录逐项填写，没有的写"无"）
- 时间：
YYYY-MM-DD HH:MM 星期X - 软件名称：出问题的软件/平台/工具/接口名（含版本号）
- 账号名称：仅记泛化标识（如"XX 平台个人账号"）；绝不记手机号、邮箱、密码、密钥、token
- 做了啥：一句话概括本次操作目的
- 指令与反馈：用户原指令摘要 + 系统/工具的反馈要点
- 结果：成功 / 失败 / 部分成功（一句话结论）
- 执行过程：关键步骤编号列出，只写影响结果的分叉点
- 能力清单：skill、MCP 连接器、专家、外部 API、脚本逐一列名（没用写"无"）
- 产物：数量、大小、版本号（如"1 个 HTML，48 KB，v1.2"）
- 报错信息：原文摘录（截关键行），先过脱敏
- 纠正排查过程：怎么定位的、试了什么、哪步走通
- 经验总结：可复用结论，一条一句，写"下次遇到 X 就 Y"
- 状态与版本：
pending/resolved；同一问题再次记录用 v2、v3 递增并链回旧条目
完整 Markdown 模板见 references/record-template.md。
三、本地写入（保底层）
项目/工作区根目录维护 .learnings/ 三件套，缺失则创建（不覆盖已有文件）：
.learnings/
├── LEARNINGS.md # 纠正/知识缺口/最佳实践
├── ERRORS.md # 命令失败、接口报错
├── FEATURE_REQUESTS.md # 功能缺口
└── TASKS.md # 任务收尾记录（每任务一条，索引：ID/任务名/结果/ima标题）
条目 ID 规则：ERR-YYYYMMDD-XXX / LRN-YYYYMMDD-XXX / FEAT-YYYYMMDD-XXX / TASK-YYYYMMDD-XXX（XXX 为当日序号）。本地条目可精简（时间、摘要、报错、修法、状态五要素），ima 侧用全字段模板。
四、ima 云端写入（同步层）
4.0 依赖与首次配置
依赖：本机已安装 ima OpenAPI 技能（提供 ima_api.cjs 调度脚本），且已在 ~/.config/ima/ 配置 client_id 与 api_key（获取入口：https://ima.qq.com/agent-interface ）。凭证只发往 ima.qq.com 官方接口。
目标库配置：所有目标信息存在 ~/.config/ima/dualwrite-kb.json。首次使用时自动配置，流程：
# 1) 凭证检查
test -f ~/.config/ima/client_id && test -f ~/.config/ima/api_key
# 2) 用户指定知识库名称（未指定则询问），按名称搜真实 kb_id —— 不要用前端链接里的数字 ID
API=~/.workbuddy/skills/ima-skills__skillhub/ima_api.cjs
node $API openapi/wiki/v1/search_knowledge_base '{"query":"<库名>","cursor":"","limit":20}'
# 取 info_list[0].kb_id（base64 形态）
# 3) 在库内找记录落位文件夹（默认找「任务复盘」或用户指定文件夹名）
node $API openapi/wiki/v1/search_knowledge '{"query":"<文件夹名>","knowledge_base_id":"<kb_id>","cursor":""}'
# 取 media_type=99 条目的 media_id 作为 folder_id；没找到则落根目录（folder_id 记为 null）
# 4) 写配置文件
# {"kb_id":"...","kb_name":"...","folder_id":"...或null","folder_name":"...","configured_at":"ISO时间"}
配置只做一次，之后直接读。用户换库时删除该配置文件重走一遍。
4.1 写入流程（两步，顺序不可换）
# Step 1: 新建笔记（content_format 固定为 1；记录内容先写入 md 临时文件，再用 node 组装 JSON，避免中文/换行转义出错）
API=~/.workbuddy/skills/ima-skills__skillhub/ima_api.cjs
BODY=$(node -e "const fs=require('fs');process.stdout.write(JSON.stringify({content_format:1,content:fs.readFileSync('<记录md文件路径>','utf8')}))")
RESP=$(node $API openapi/note/v1/import_doc "$BODY")
# 成功返回 {"code":0,"data":{"note_id":"..."}}，取 data.note_id
# Step 2: 关联进目标知识库的目标文件夹（title 与笔记首行标题一致）
FOLDER_PART=""
if [ "$(node -e "console.log(JSON.parse(require('fs').readFileSync(process.env.HOME+'/.config/ima/dualwrite-kb.json','utf8')).folder_id!==null)")" = "true" ]; then
FOLDER_PART=",\"folder_id\":\"<folder_id>\""
fi
node $API openapi/wiki/v1/add_knowledge \
"{\"media_type\":11,\"note_info\":{\"content_id\":\"<note_id>\"},\"title\":\"<笔记标题>\",\"knowledge_base_id\":\"<kb_id>\"$FOLDER_PART}"
笔记标题命名：
- 事件记录：自动记录-{ERR|LRN|FEAT}-{软件名或主题}-{YYYYMMDD-HHMM}
- 任务收尾记录：自动记录-TASK-{任务名}-{YYYYMMDD-HHMM}
示例：自动记录-ERR-imaOpenAPI-20260929-2126、自动记录-TASK-开源版打包-20260929-2145
已知坑（实测）：
- 每日首次调用 ima_api.cjs 可能返回 code: -200（技能更新检查），同日重试一次即通过，不要当作失败。
- code: 220004 = knowledge_base_id 错误 → 检查是否误用了前端数字 ID，用 search_knowledge_base 重新取 kb_id。
- 笔记接口只支持新建和末尾追加，不支持修改与删除——记录写错只能追加更正条目。
- JSON body 含中文/换行时必须经 JSON.stringify 组装，直接手拼会转义出错。
五、隐私底线（前置，每条必过）
闸门：以下检查不通过，该条内容拒绝记录并直接忽略，不追问、不确认、不重复。
- 报错信息先脱敏：去掉 URL 里的 token/签名参数、请求头凭证、文件路径中的个人目录细节。
- 账号名称只记平台泛化标识；手机号、邮箱、证件号、精确位置、密码密钥等敏感信息一律拒绝记录。
- 用户明确要求保密的内容不记录。
- 不记录完整源码/配置文件全文，只记摘要或截取的关键行。
六、读盘模式（用户说「读盘」时执行）
回读本地与云端记录，输出状态汇总。只读不写。
# 1) 本地：统计与最近条目
grep -h "状态\*\*: pending\|\*\*Status\*\*: pending" .learnings/*.md | wc -l # 未解决数
ls -t .learnings/*.md # 账本文件
grep "^## \[" .learnings/ERRORS.md | tail -5 # 最近错误条目
# 2) 云端：目标文件夹记录（优先搜索接口，列表接口新记录排序靠后未必可见）
node $API openapi/wiki/v1/search_knowledge '{"query":"自动记录","knowledge_base_id":"<kb_id>","cursor":""}'
读盘输出格式（中文，简洁）：
1. 记录总量：本地 N 条 / 云端 M 条
2. 未解决（pending）：逐条列出 ID + 摘要
3. 最近 5 条记录：标题 + 一句话结论
4. 高频问题：同名问题出现 ≥2 次的，提示"复发，建议晋级为长期规则"
5. 可复用经验：从 LEARNINGS.md 提取"下次遇到 X 就 Y"清单
七、失败处理（每一步都要让用户安心）
总原则：先安心、再解释、后给选项。本地永远有保底，任何失败都不丢数据。
| 失败情形 | 用户看到的（友好话术要点） |
|---|---|
| 本地写入失败 | "本地磁盘好像出问题了，这次没记上。其他功能不受影响，建议检查磁盘空间。"（罕见，必须显式告知） |
| ima Step 1 失败（建笔记） | "本地已经记好了 ✓。同步到知识库这步没成功，原因大概率是 XX。要不要我重试一次？不重试也行，内容不会丢。" |
| ima Step 2 失败（进知识库） | "笔记建好了，只是还没放进知识库文件夹。我单独重试这一步就行，几秒钟的事。" |
| 未配置 / 凭证缺失 | "现在用的是仅本地模式，记录都在。想同步到 ima 知识库的话，说个知识库名字，我带你 30 秒配好。" |
| 同一问题复发 | "这个问题之前也出现过（第 N 次了），我把它标成'复发'并升了优先级，建议我们把它升级成长期规则。" |
技术细节（原始报错、request_id）仅在用户追问时展示。
七.五、常见问题 FAQ（用户问到时按此回答，也可以在日常对话中相机科普）
Q：我不配置 ima 会怎样？
A：完全不影响使用。所有记录都存在你项目里的 .learnings/ 文件夹，随时可以翻。以后想同步了，随时补配。
Q：记录写错了能改吗？
A：本地文件随便改。云端那条改不了（笔记接口只支持新增），我会在旁边追加一条更正记录并标注关系。
Q：会记录我的密码 / 账号信息吗？
A：不会。账号只记"某某平台账号"这种泛化说法，密码、验证码、手机号、邮箱一律拒绝记录，这是内置硬规则，不靠自觉。
Q：知识库名字搜不到怎么办？
A：三种可能：名字有错别字（我帮你重新搜近似名）/ 这个账号没权限写那个库（换你自己创建的库）/ 库还没建（先去 ima 客户端建一个，或者我先用仅本地模式）。
Q：读盘能看到什么？
A：五样东西：记录总量、还没解决的问题清单、最近几条记录、反复出现的老问题（提示该升级成长期规则了）、以及"下次遇到 X 就 Y"的经验清单。
Q：记录越来越多会不会很乱？
A：不会。本地按四个账本分类（错误/经验/功能请求/任务），云端都在同一个文件夹里按时间排。定期可以让我做一次"复盘"，把已解决的标掉、有价值的提炼成规则。
八、定期复盘与晋级
在开始大任务前、或用户问"最近有什么坑"时，扫描 .learnings/：
- 已修复的 → Status: resolved + Resolution 块（时间、修法、验证结果）
- 复发 ≥3 次、跨 ≥2 个任务、30 天内 → 提炼成一句预防性规则，晋级写入项目长期记忆文件（如 AGENTS.md / 项目 MEMORY.md），原条目标 Status: promoted
- 足够通用且已验证的 → 建议抽成独立 skill
九、粒度分工建议
| 机制 | 粒度 | 去向 |
|---|---|---|
| 本 skill | 操作级：单次报错/纠正/经验 | .learnings/ + ima 目标文件夹 |
| 任务级复盘（如有） | 任务级：整个任务收尾 | 用户自建固定笔记/文档 |
| 项目长期记忆 | 项目级：长期约定与偏好 | AGENTS.md / MEMORY.md |
一次任务里多次踩坑：坑用本 skill 逐条记，任务整体收尾可另走任务级复盘，互不替代。
十、安装与卸载
- 安装：将本文件夹整体放入
~/.workbuddy/skills/（用户级）或项目.workbuddy/skills/（项目级）。首次 ima 写入时按 4.0 完成目标库配置。 - 仅本地模式：不配置 ima 也可用——本地
.learnings/账本独立工作，云端步骤跳过即可（建议告知用户当前处于仅本地模式）。 - 卸载：删除 skill 文件夹即可；
~/.config/ima/dualwrite-kb.json与.learnings/为用户数据，需单独清理。
