mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 09:17:31 +00:00
docs: 全量校订文档到当前代码状态 + 建立 future-plan 作为唯一未做登记处
## 为什么
文档里混着三种时态:当时实测、历史推演、描述现状但已失真。三者外观相同,
读者无从分辨。本次逐条用实测核对,把失真的改成事实,把「已做」从「未做」
里摘出来,把「真没做」集中登记到一处。
## 新文件:docs/zh/future-plan.md
此前「未做」散落在各设计文档的「待办/剩余/遗留」小节,时间一长就与代码
脱节(已完成却仍写未做,未做却被当成已完成)。新建本文作为**唯一登记处**,
收录规则明确:只收「代码里确实没有」与「有机制但零生产调用方」两类。
它同时把本仓一个反复出现的缺陷形态显式化 —— **机制 ≠ 接线**。已攒够 5 例:
| 能力 | 曾经/现在的状态 |
|---|---|
| `Policy.CheckTool` | 曾 `Agent.security` 恒 nil → 2026-10-30 修 |
| `CheckToolFor` | 曾 0 生产调用方 → 2026-10-30 修 |
| `ActivateProfile` | **现在仍 0 调用方** |
| `ScanContent` | **现在仍 0 调用方** |
| `CheckPath` / `CheckNetwork` | **现在仍 0 调用方** |
## 已失真的表述(逐条实测后更正)
**kernel-modularization-design.md**
- §2.7.4 原标题是「未做(Step 4b 的剩余)」,写着「main.go 仍走原来的串行代码,
下一步是把 Run(plan) 真接进 main」。**实际 `main.go:229` 早已调用
`RunKernelModules` → `kernelboot.Run`**,插件调度也已归位 plugin-host。
改为「已完成」并给出两处代码位置 + 生产日志证据。
- §2.7 分层数字「6 层 / 17 模块,最宽层 9」→ 实测 **20 模块 / 6 层 / 最宽 10**。
同时给出取数命令,并要求「数字一律现场取,不凭文档记忆」。
- §2.3.5 那段标着「当前已产出的分层结果(实测)」的 4 层 14 模块表,是
2026-10-16 的推演。改为明确标注「已过时,仅作设计推演保留」。
- §2.7.3 判据表 7 条**全部不存在**(随 3864f36 删死包迁包时丢失)。改为
左右栏对照:左边当时名字、右边现仓库真实判据,找不到对应物的 4 条明确标 ❌。
- 文件头补状态声明、与 future-plan 的分工、数字取数方式。
**kernel-secret-firewall-design.md**
- 状态从「已实现」改为「部分实现」。原来那句会让读者以为整套安全能力都在跑。
- 新增接线状态表:逐个写**实测的生产调用点**(不写 ✅/❌ 定性)。
事实是:凭据三件套与工具闸生效;**敏感词/注入、路径沙箱、网络闸三条
机制完整但零生产调用方**;档位声明侧通、激活侧零调用方。
- §5 T1–T10:T2/T3/T4 早已落地却仍挂在「待办」表里。改为现状列,
并把真未做的 T5–T10 迁入 future-plan §1.5。
**对外文档的工具名**(外部读者正在看错的名字)
- `ARCHITECTURE.md` 6 处、`OVERVIEW.md` 1 处、`README.md` / `README_EN.md` 各 3 处、
`resident-subagent-design.md` 2 处:`memory_*` / `doc_query` → `stablemem_*` / `coldcontext_*`
- README 的 v1.1.1 发布说明保留原名(那是历史事实),加一句现名注记
**input-scheduler-design.md / resident-subagent-design.md**
- 补状态头。input-scheduler 记入 rtchild 不走四级阶梯(单槽覆盖)这一下游差异;
resident-subagent 记入「继承安全运行时实例但**不继承权限**」这一下沉事实。
## 未动的(有意为之)
历史归档文档(`legacy-*`、`*-plan.md`、`live-run-evidence-*`、
`production-recall-validation.md`、`context-overflow-l4-design.md`、
`entities-retirement-plan.md`、`memory-*-plan.md`)**一律不改** ——
它们是历史记录,改了就篡改证据。其中的待办以索引形式登记在
future-plan §六,原文档保留。
## 核对结论
- 文档现在只描述两种内容:**已落地的实现**(附实测证据/取数命令)与
**尚未实现的事项**(统一在 future-plan)
- 数字类断言全部给出取数命令
- 跨文档的「未做」引用统一指向 future-plan,避免再次分叉
This commit is contained in:
@ -228,12 +228,13 @@ L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样
|
||||
③ Graph (图数据库 — 顶层仍是三元组,节点即记忆块)
|
||||
SQLite — memory_blocks(节点) + memory_block_edges(边)
|
||||
三元组 = 【节点】【关系边】【节点】;putTripleBlocksTx 落为 src --edge_type--> dst
|
||||
写入: memory_commit / 冷文档蒸馏 / Pipeline 规则蒸馏 / memory_merge
|
||||
写入: stablemem_commit / 冷文档蒸馏 / Pipeline 规则蒸馏 / stablemem_merge
|
||||
读取:
|
||||
├── 自动召回: Indexer.BuildContext(input)
|
||||
│ → CleanText → 向量实体搜索 + jieba关键词 → SQLite LIKE + BFS depth=2
|
||||
│ → 【记忆索引】→ system prompt
|
||||
└── LLM主动: memory_recall / memory_merge / memory_purge / memory_edit / memory_delete_entity
|
||||
└── LLM主动: stablemem_recall / stablemem_merge / stablemem_purge /
|
||||
stablemem_edit / stablemem_delete_entity
|
||||
Social: person_query / set_trait / relate (包装 GraphDB)
|
||||
|
||||
④ 四个独立心跳循环(各自独立的 ticker 和配置间隔)
|
||||
@ -356,20 +357,26 @@ Core ◀─入向审查── 外部
|
||||
|
||||
| 工具 | 作用 |
|
||||
| ------ | ------ |
|
||||
| `memory_recall` | 从 Graph 召回 |
|
||||
| `memory_commit` | 写入 Graph 三元组 |
|
||||
| `memory_merge` | 合并两个实体节点 |
|
||||
| `memory_purge` | 删除指定实体 |
|
||||
| `memory_edit` | 编辑已有实体/关系 |
|
||||
| `memory_delete_entity` | 删除实体及其所有关系 |
|
||||
| `memory_introspect` | 查看记忆统计 |
|
||||
| `stablemem_recall` | 从 Graph 召回 |
|
||||
| `stablemem_commit` | 写入 Graph 三元组 |
|
||||
| `stablemem_merge` | 合并两个实体节点 |
|
||||
| `stablemem_block_merge` | 合并两个记忆块 |
|
||||
| `stablemem_purge` | 删除指定实体 |
|
||||
| `stablemem_edit` | 编辑已有实体/关系 |
|
||||
| `stablemem_delete_entity` | 删除实体及其所有关系 |
|
||||
| `stablemem_introspect` | 查看记忆统计 |
|
||||
| `coldcontext_query` | 从冷上下文(cold context)召回 |
|
||||
| `coldcontext_commit` | 写入冷上下文 |
|
||||
|
||||
`memory_commit` 与 `coldcontext_commit` 自 v1.1.1 起接受 `media_digests`,并由内核把
|
||||
> ★ 工具名以 `stablemem_` / `coldcontext_` 为前缀(v1.2 起,旧的
|
||||
> `memory_*` / `doc_*` 已废弃)。权威定义在
|
||||
> `internal/agent/core/tooldefs.go`;核对命令:
|
||||
> `grep -rhoE '"(stablemem|coldcontext)_[a-z_]+"' --include=*.go internal | sort -u`
|
||||
|
||||
`stablemem_commit` 与 `coldcontext_commit` 自 v1.1.1 起接受 `media_digests`,并由内核把
|
||||
`[<mime> <短digest>] <描述>` 标记补进句子/正文——**标记由内核拼,模型只给 digest**。
|
||||
要求调用方知道格式,等于让一个拼写错误静默切断引用绑定而全链路无人报错。
|
||||
`memory_commit` 同时新增 `sentence_text`:媒体引用挂在句子上,没有句子就无处可挂。
|
||||
`stablemem_commit` 同时新增 `sentence_text`:媒体引用挂在句子上,没有句子就无处可挂。
|
||||
|
||||
### 媒体记忆(块 union:媒体即块)
|
||||
|
||||
|
||||
@ -46,7 +46,7 @@ CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `Ev
|
||||
- **无独立 GC、无引用计数、无 keep-set**:记忆块遵循单层不变量——Context → Document → Graph
|
||||
是块的**迁移**,不是复制、也不靠引用保活;**删除块即删内容**
|
||||
- **v1.1.1 起贯通插件边界**:插件可通过 `InsertWithMedia` / `InjectInputMedia` 读写媒体,
|
||||
模型可用 `memory_commit` / `coldcontext_commit` 的 `media_digests` 参数关联媒体
|
||||
模型可用 `stablemem_commit` / `coldcontext_commit` 的 `media_digests` 参数关联媒体
|
||||
- **旧机制已整体拆除**:此前把视觉模型生成的描述写进正文、以 `[<mime> <短digest>] <描述>` 标记
|
||||
参与检索的**描述式索引**,以及 `media_refs` 引用计数,均已在 v1.2.0 删除——描述是模型生成的
|
||||
二手信息,检索「别人转述的图片」不如检索图片自己的向量
|
||||
|
||||
Reference in New Issue
Block a user