jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-02 23:37:24 +00:00
Code Issues Packages Projects Releases Wiki Activity
1,023 Commits 5 Branches 29 Tags
7c0eec1b2f4ccfeb26a4380c0d5b18d5d9bdfd03
Commit Graph

4 Commits

Author SHA1 Message Date
JianFeeeee
a402bfd777 docs: 删除 7 份已完结的执行计划，把教训与数据提出来 
## 为什么删

执行计划在实施完结后**会变成误导性读物**：它记录的是"当时打算做什么"，
而读者会读成"现在是什么"。

这在本仓已经造成真实误读 —— `prod-migration-checklist.md` 写着
「状态：HologramAgent 已停机」，那是一次性迁移（2026-10-04）当场的状态，
但照着读会以为服务现在还停着。

## 删了 7 份，删前提取三类内容

| 删掉的文档 | 行数 |
|---|---|
| `memory-restructure-plan.md` | 168 |
| `memory-blockflow-repair-plan.md` | 450 |
| `memory-usability-plan.md` | 309 |
| `scene-memory-fix-plan.md` | 271 |
| `toolcall-parallel-execution-plan.md` | 578 |
| `prod-migration-checklist.md` | 157 |
| `entities-retirement-plan.md` | 118 |

**提取去向**：

1. **教训 → 新建 `engineering-lessons.md`**

   这些是它们唯一还有长期价值的部分。汇总成一篇，并按形态归类：

   - 判据类（5 条）：结构判据不能替代质量判据 / 测「接线之后」≠测「有没有接线」/
     验证通过≠架构正确 / fixture 照臆测字段编 / 先改代码再写测试
   - 接线类（3 条）：机制≠接线 / 依赖图是唯一保证顺序的地方 / 单数改了复数漏了
   - 权限与生命周期（3 条）：「接上了」有三层 / 以调用方名字为键的表要清理 /
     提权口子：让调用方声明自己是谁
   - 流程类（3 条）：长任务纪律 / 数字要现场取 / 计划不进仓库

   文末点出它们共同的形态：**某种"看起来对了"的信号与"真的对了"之间存在缺口。**

2. **实测数据 → 并入 `toolcall-contract-and-sequence-design.md` 附录 A**

   那是新旧内核的对比压测（288 条输入 × 两版），核心结论值得留：

   ```
   场景        旧版中位/工具数    新版中位/工具数
   slowbatch8  0.220s / 0 个     0.409s / 8 个
   ```

   ★ **旧版"更快"是假的** —— 它的 `openai.lua` 缺 `stream_index` 透传，
   多个分片并到槽 0 ⇒ 每个工具报参数错误而一个都没真跑。
   这是「只看耗时会被骗」的典型。

   另附 stage 锁告警的完整归因（不是内核缺陷，成因在插件进程侧运行时）。

3. **未完成的项 → `future-plan.md` §六**

   尤其 `entities-retirement-plan` 那条：方案是"三表全退"，但 2026-10-31
   实测生产库 `entities 1292 / relations 978 / sentences 66` 行**仍在用**。
   这个事实不能随文档一起消失。

## 保留两份（它们不是计划，是依据）

- `legacy-table-retirement.md` —— 被 **4 处生产代码注释**引用（`graph.go` ×2、
  `commit_blocks_test.go`、`probe_prod_test.go`），是退役判断的依据
- `interrupt-subsystem-split-plan.md` —— 探测事实被 `interrupt_invariant_test.go`
  引用；拆分本身确实未实施

## 索引重写

`docs/zh/README.md` 现在是「四类文档」的规则说明：

| 类型 | 回答什么 | 命名 |
|---|---|---|
| 设计文档 | 为什么这样设计 | `*-design.md` |
| 操作手册 | 怎么做 | `*-runbook.md` |
| 教训 | 踩过什么坑 | `engineering-lessons.md` |
| 未做登记 | 还剩什么没做 | `future-plan.md` |

并明确写「**不放执行计划**」及例外条件。

## 顺带修掉的引用

删除后 4 处引用指向不存在的文件：

- `deploy-runbook.md` → 改指 `toolcall-contract-and-sequence-design.md`
- SDK 仓 `guide/stream-tool-call-index.md` / `guide/parallel-tool-declaration.md`
  → 同样改指（这两个在 SDK 仓，随后单独提交）

## 验证

- docs/zh 27 篇，索引里列的全部存在、无遗漏
- 全仓无指向已删文档的引用（代码 + 文档）
- 代码块全部配平
- go build 通过
 2026-10-31 08:50:39 +08:00
JianFeeeee
4963d70215 docs: 逐篇核实全部文档的完成状态 —— 修正 6 处与代码不符的自述 
## 上一轮的遗漏

上次只补了"缺状态行"，但**32 篇正文里的状态声明基本没动**。而那些声明
大多是 1~2 周前写的，代码早已推进。本轮逐篇对代码核实。

## 逐篇核实结果（方法：读当前代码，不看文档的历史描述）

### 1. memory-usability-plan：待执行 → 已实施

文档写「状态：**待执行**（2026-10-22）」。三条根因实测**全部已修**：

| 根因 | 实测 |
|---|---|
| R1 向量化输入是 jieba 词袋 | ✅ `coldcontext.go` 的 `denseFor` 明写「用事件正文（原文），不用 Summary（jieba 词袋）」 |
| R2 媒体块无语义 | ✅ 块 union 化，媒体即块自带描述 |
| R3 提示词无引导 | ✅ `tooldefs.go` 明写 `coldcontext_query` 把历史**插回时序**，并下沉到 kernel-memory skill |

### 2. entities-retirement-plan：执行中 → 方案已定、执行未完成

写「三表全退，执行中」，容易被读成"快完成了"。实测生产库：
`entities 1292 / relations 978 / sentences 66` 行**仍在用**。
迁移工具就绪，但生产未切换 —— 这个区别对判断风险很关键。

### 3. scene-memory-fix-plan：部分落地 → 7 步里 5 步完成

逐条核实：步骤 1/2/3/5/6 已完成（含 SDK 的 `ScenePolicy`、
`scene_emerge.go` 已区分 `peer:group_*` 与 `peer:user_*`）；
步骤 4（清现网垃圾场景）与 7（收口验证）属现场操作，未复核。

### 4. prod-migration-checklist：⚠️ 最危险的一处

写「**状态**：HologramAgent 已停机（inactive + disabled）」——
那是一次性迁移（2026-10-04）当场的真实状态，**不是现在的**。
照着它读会以为服务停着。改为明确归档说明 + 指向现行 runbook。

### 5. abstention-criterion：「拒答尚未接入生产路径」已不成立

实测拒答已下沉到图库层（`RecallBlocksGuarded`），生产路径
`toolcall.go:1312` 与端到端探针**走同一条路**。保留了下沉的理由
（第一版放上层，探针绕过它 ⇒ 判据测不到被测路径）。
剩余两项（泛指词检测、n=10 样本偏小）仍开放。

### 6. toolcall-parallel-execution-plan：阶段 0.5 起为待办 → 全部已完成

实测阶段 0/0.2/0.5/1/2/2.5 与 3/4 全部完成，遗留项也已解决。

## 顺带修正两处写法

- `memory-restructure-plan.md`：顶部有「执行结果摘要」但正文各步骤仍写
  `✗ 未开始`（原始计划快照，有意保留）。加一句读法说明，
  避免读者拿正文的快照当现状。
- `future-plan.md` §六：新增 5 条实测确认的待办并去掉 2 条重复项
  （遗留表退役、中断子系统原先各出现两次）。

## 核对

- docs/zh 32 篇全部有状态行，且与代码实测一致
- 代码块全部配平；文档间相对链接全部有效
- go build 通过（纯文档改动）
 2026-10-31 08:20:47 +08:00
JianFeeeee
cf14b840ef docs: 补齐文档状态分类 + 校正两轮代码改动后的失真 
## 背景

上一次文档校订（b9b5ac0）之后又有两次代码提交（5194a96 / 8293282），
把 future-plan §1.1 整节变成了错的 —— 它还写着「档位没有生效点」
和「在 prepareInputTask 里加一次 activateSecurityProfile 调用」，
而后者正是被后来的收敛**否定掉的方案**。

## 新增 docs/zh/README.md（文档索引）

32 篇文档此前混着三种时态（当时实测 / 历史推演 / 设计规划），外观相同。
索引给出**状态分类与可信度规则**：

| 状态 | 能不能当事实用 |
|---|---|
| 已实现并部署 | ✅ 直接信 |
| 部分实现 | ⚠️ 只信标了"生效"的部分 |
| 设计 / 未实现 | ❌ 只能当设计意图 |
| 归档说明 | ❌ 不要改、也不要信 |

并写死**判据名可信度规则**：文档里的 `TestXxx` 不保证还存在。
给了核对命令，以及当前基线（27 条缺失的分布 —— 18 条属"设计未实现"类
文档的规划名、7 条是 §2.7.3 有意保留的历史对照表左栏、2 条属视频能力
未纳入契约）。判定标准：**在"已实现"类文档正文里找不到才是缺陷**。

## 重写 future-plan §1.1（已结案）

原节写的是错的方案。改成记录**真正的缺陷分三层**：

```
第 3 层（表面）：activateSecurityProfile 零调用方
第 2 层：agent/core 在替 security 做策略决策
         （自己抠 security_profile / 自己选判定链 /
           自己写 Kind:"resident" 声明主体类别 —— 提权口子）
第 1 层（根因）：security 缺少「输入接入点」
```

并补上「每 agent 一个实例」的最终形态（共享注册表 + per-agent 执行视图，
sessionProfile / longtimeProfile 两层，优先级 session > longtime 本身是安全语义）。

§〇「机制 ≠ 接线」表格里档位那一条从 🔴 改为 ✅。

## 各文档状态行

此前 14 篇缺状态行（runbook / 实测报告 / 计划类）。逐篇补上**符合实际内容**
的声明，而不是统一套一句。特别地：

- `commondev-design.md` 标题本就写「设计 · 未实现」→ 归到"设计"类
- `live-run-evidence-2026-10-04.md` → 明确标注"历史证据快照，不要用它的
  结论覆盖现在的实现判断"
- `legacy-issues.md` → 写明它与 future-plan 的分工（前者收已知问题，
  后者收能力缺失与零调用方）

## 正文里两处判据名漂移

- `TestBootCtxCloseAllIsReverseOrder` → 实际是
  `TestKernelStateCloseAllIsReverseOrder`（`BootCtx` 改名时判据跟着改的）
- `TestNilTypedBusSafety` → 标注为"规划名，仓库中不存在"

## 新增 §2.7.5 模块产物的实例化粒度

依赖图保证"设施已就绪"，但没说该有几个实例 —— 这是独立决策。
记下 security 的两个答案：全局基线共享（否则插件声明对部分 agent 不生效）、
轮次状态 per-agent。并给出给未来新模块的两条判断标准。

## 安全文档

状态头补「架构形态」段（防火墙定位、per-agent 视图、两层档位）；
接线状态表里 `ActivateProfile` 从 🔴 改为 ✅（2026-10-31 接通）。

## README

文档列表加索引与 future-plan 入口 —— 此前从 README 找不到 docs/zh 的任何指引。

## 核对

- docs/zh 32 篇全部有状态行
- 索引里列的文档全部存在，无遗漏
- 分类与各文档自述一致（逐篇抽查）
- go build 仍通过（纯文档改动）
 2026-10-31 07:50:58 +08:00
JianFeeeee
b9b5ac0282 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，避免再次分叉
 2026-10-31 06:58:17 +08:00