说明书 · DPS AI

一、记忆系统全景：你的日记是怎么被记住的

你每天写的日记，就是全部记忆的原始文件——相当于人的"亲身经历"本身，一切都从这里来。

日记不是直接拿来用的。就像人不会把一辈子的经历一股脑装进脑子里想事情，系统会把日记里的内容拆分放到三个不同的"记忆仓库"里，各自负责不同的用法：
1. 知识库——像"我知道的事实"。比如"程校长约62岁、耳根软"。你问到一个话题，系统就去翻相关的几条出来用，用完就放回去，不占地方。
2. 全局记忆·人格层——像"我是谁、我最近在忙什么"。这部分不用你去问，它一直在场，AI 每次开口前都已经知道你是谁、你在干什么、你跟谁是什么关系。
3. 永久记忆 + 会话历史——像"具体某件事的记忆"和"我们刚聊过什么"。按需回忆，聊完的旧对话可以压缩成摘要省地方。

一句话：日记是源头，知识库/人格层/永久记忆都只是"调取方式"。同一个事实可以同时存在于好几层，各层各干各的活，互不冲突。

存储与调用链路（实测代码）：日记 → diary_sync 管道（版本快照 data/diary/versions/ → 段落级 diff → AI 只看变化 → 产出结构化操作）→ 写入两个目标：
① knowledge_base（/opt/dps-ai/knowledge_base_data/store.json + chroma_db 向量库，bge-small-zh 384维向量 + TF-IDF + BM25 + bge-reranker 精排）
② global_memory 人格/近期记忆分组（data/global_memories.json）
运行时注入（steward/routes.py ~L252）：每条用户消息 → search_knowledge(top_k=2) + memory.recall(top_k=2) 拼进 system_prompt 的「知识库匹配」「永久记忆匹配」区块；AI 需要时再主动调 search_knowledge(top_k=3) / recall(top_k=10) / retrieval_engine.hybrid_search(初检30+20 → 精排5)。

三层调取一览表（每次取几条）

通道	什么时候触发	条数	为什么是这个数
知识库·自动匹配	你每发一条消息	top-2	主流是 3~5 条，原因：①注意力稀释——模型对长上下文中间部分注意力弱（lost in the middle），10 条平庸的不如 2~3 条扎实的；②token 成本——每条 300~500 token，多轮对话成本翻倍；③噪声误导——低相关条目会给模型"看似有依据"的错误线索。你的条目是整段式（比业内常见切片长），top-2~3 配合精排器是成比例的。
永久记忆·自动匹配	你每发一条消息	top-2（相似度≥0.4 才入选）
知识库·AI 主动搜索	AI 判断需要深查	top-3	工具调用，按需触发
永久记忆·AI 主动回忆	AI 判断需要	top-10	工具调用，按需触发
混合检索引擎	AI 调用 search_kb	向量30+关键词20 初检 → 精排 5	多路召回扩大覆盖，精排控制噪声，5 条是精度/覆盖的平衡点（主流做法）
人格 + 近期记忆	所有对话（第二步上线后）	全部（≤8+10条）	人格是"背景常识"，不检索、始终在场——这就是它和知识库的本质区别

二、日记同步（diary_sync）——怎么用

频率：一天或两天一次，随你。
用法：打开「日记同步」页面 → 把最新版日记全文整个粘进去（改没改、改了哪都不用管，系统自己比对）→ 选 AI → 点一键同步 → 看一眼它识别出的变更清单 → 点应用。
它自动做了什么：存档这次日记的快照（以后每次都能跟上一次比）→ 找出改了哪些段落 → 让 AI 只看变化的部分，判断哪些知识要新增、哪些旧条目要补充、哪些作废 → 写入知识库，同时更新人格层和近期记忆。
出问题怎么办：每次应用前都自动备份，历史记录里点"回滚"就回到那之前的状态，什么都不丢。

面板：/dashboard/diary-sync.html；插件：plugins/diary_sync/；API：/api/diary-sync/{state,upload,analyze,apply,rollback,diary-current}。
安全设计：append 带 expect 锚点校验（目标条目必须含该原文）+ marker 防重复追加；delete 需 expect 校验；单次操作上限 80 条；AI 走 model_router 正规链路（resolve_with_router / _resolve_model_credentials），不手写 payload 直连；同步 httpx 放 run_in_executor（Py3.8 无 to_thread）；备份含 store+index+chroma tgz+global_memories 四件套。

Token 档位（截断了怎么办）

AI 每次回答有一个"最长能说多少字"的上限。就像一个人写字，纸就那么长——思考型模型更费纸：它"打草稿"和"写正文"共用同一张纸，草稿写太长，正文还没写完纸就用完了，这叫截断。
现在的机制：默认 16K 档。一旦发生截断，页面立刻弹出提示，告诉你当前档位，给你三个选择：升一档重试（16K→32K）、直接 64K 临时全开、或关闭不管。都是一键点按钮，不用改任何配置。
档位参考（业内主流标准）：普通模型默认输出上限 4K~8K；思考型模型因为草稿占额度，业内普遍直接给到 16K+；32K/64K 是给超长内容（比如全量重建知识库）准备的。

档位表：8K=8192 / 16K=16384 / 32K=32768 / 64K=65536。检测逻辑：finish_reason=="length" 或输出中无可解析 JSON（_looks_like_json）即判定截断，返回 {truncated:true, tier, next_tier}；前端弹层提供 retryWithTier(next.id) / retryWithTier('64k')。截断原始输出留痕 data/diary/debug_ai_*.txt（含 content tail，供排查）。说明：JSON 截断自动修复逻辑仍保留作为兜底，但首选路径是升档重试，保证内容完整不硬凑。

三、全局记忆（人格层）——AI 是怎么"记住你是谁"的

全局记忆现在分两类用法：
① 人格 + 近期记忆（系统自动维护，第二步上线自动注入后所有对话始终在场）——人格像一个人的性格和自我认知："我是谁、当前处境、核心目标、原则红线、关键人物都是什么人、当前战略"。近期记忆像"最近两周发生了什么"，新事进来、旧事滚出，永远只有最近 14 天。
② 其他分组（如"默认"、"8.21 快照"）——还是老用法：聊天页面板里勾选哪些，就往当前对话注入哪些。你勾了才算数，不勾不影响。
和知识库的区别一句话：知识库是"查资料"——问到才翻；人格是"自我认知"——不用问也带着。

数据：data/global_memories.json（{items, groups}）。人格 ≤8条×200字（按 name 匹配更新，超限淘汰最旧）；近期记忆 ≤10条滚动窗口（每次同步整组重写，条目名带【月-日】前缀）。注入现状（第一步）：前端 memory-panels.js 勾选 → index.html 把 getSelectedGlobalMemContent() 拼进 _sysParts（"=== 全局记忆（背景板，始终生效） ==="）。第二步改造点：steward/routes.py 上下文装配函数里自动追加"人格""近期记忆"两分组（服务端注入，全设备生效，不依赖 localStorage/勾选）。

四、知识库——"我知道的事实"仓库

现在有 181 条（2026-10-03 刚做过一次大更新），分 11 类：人物档案、事件时间线、商业策略、渠道运营、团队管理、销售业绩、项目概况、关系演变、冲突应对、未来规划、通用。
每条是一个独立知识点（"成海军，46岁，PLC老师……"），AI 聊天时自动按话题匹配 2 条最相关的塞给模型；AI 觉得不够还能自己再搜。
维护方式：以后主要靠日记同步自动维护；也可以在聊天里让 AI 记（它有 add_knowledge 工具）。想手动管理，用模型管理那套面板（dashboard 的知识库页面）。

插件 plugins/knowledge_base/（engine.py：store.json + chroma kb_entries collection，cosine 空间）。写入统一走 add_knowledge(auto_extract=False)（HTTP 接口默认 auto_extract=True 会触发 LLM 二次提取——仅适合文档上传场景，批量维护禁用）。检索：向量(30) + BM25(20) 初检 → RRF 合并 → bge-reranker 精排 top-k。坑：HTTP add 接口对 ≥50 字内容必调 AI 提取，结果不可控（手册坑位已记录）。

五、四层记忆全景图

层	像人的什么	存哪	怎么进对话	怎么更新
全局记忆·人格	性格、自我认知（我是谁）	global_memories.json「人格」组	始终在场（自动注入，第二步）	日记同步时 AI 判断变化才更新
全局记忆·近期	最近经历（前几天的事）	global_memories.json「近期记忆」组	始终在场（同上）	14天滚动窗口，每次同步重写
知识库	语义记忆（我知道关于X的事）	knowledge_base_data/（store+向量库）	按话题检索 top-2 自动 + 按需深查	日记同步 / AI 工具 / 手动
永久记忆	情景记忆（具体某事）	memory 插件向量库	相似度≥0.4 召回 top-2 / recall 工具	对话中 AI 用 remember 工具记
会话历史	短期记忆（刚聊过什么）	chat_history/<会话>.json	全文进上下文	20轮阈值自动压缩成摘要

六、其他功能速查

日常聊天（PWA）

手机加到主屏当 App 用。锁屏/息屏不会断流（服务端任务化，断线续接）。设置里有：模型选择、多轮/单轮、知识库分组、全局记忆勾选、自动压缩开关、20轮阈值。改完设置记得 Cmd+Shift+R 强刷（PWA 有缓存）。

模型管理

13 个模型可切换。加新模型时 base_url 只填到版本号（如 https://api.deepseek.com/v1），系统自己拼 /chat/completions——填多了必 404。

会话管理

聊天记录存在服务器 chat_history/。长对话到 20 轮自动压缩（可关）。想保留细节的重要对话，可以提前让 AI "记住"关键内容进永久记忆。

排查问题

报错看服务器 /opt/dps-ai/data/app.log（不是 journalctl）。429 带页面提示=触发限流(600/分钟)；401 弹窗=token 问题（不会删你的钥匙，重新输一次即可）。日记同步失败看 data/diary/debug_ai_*.txt 留痕。

七、安全机制总览（防呆设计）

机制	保护什么	白话解释
expect 锚点校验	改错条目	改一条知识前，先核对这条里确实有某句原文——对不上就拒绝改，防止 AI 张冠李戴
marker 防重复	重复追加	每段更新带独特短语，已存在就跳过——同一件事不会被写两遍
操作上限 80 条	AI 失控	单次同步最多动 80 条，再多直接不要
自动备份+回滚	一切误操作	每次应用前备份知识库+向量库+全局记忆，一键回到任意一次之前
版本快照	日记本身	每次上传的日记都存不可变快照，随时可查任何版本
调试留痕	排查难	AI 每次原始输出都存档（含截断现场），出问题不用猜

📖 说明书