diff --git a/README.md b/README.md index 7b99a30d..2682d1a5 100644 --- a/README.md +++ b/README.md @@ -355,6 +355,8 @@ internal/ - [插件开发指南](assets/docs/zh/PLUGIN_DEV.md) | [English](assets/docs/en/PLUGIN_DEV.md) - [Lua Adapter](assets/docs/zh/ADAPTER.md) | [English](assets/docs/en/ADAPTER.md) - [知识库演示](assets/knowledge/homeagent_architecture/content.md) +- [设计文档索引](docs/zh/README.md) — 32 篇设计/计划文档的**状态分类与可信度规则** +- [未来计划](docs/zh/future-plan.md) — 尚未实现 / 已知缺口的**唯一登记处** ## 下载 diff --git a/docs/zh/README.md b/docs/zh/README.md new file mode 100644 index 00000000..7e547cd7 --- /dev/null +++ b/docs/zh/README.md @@ -0,0 +1,140 @@ +# docs/zh 文档索引 + +> 建立于 2026-10-31。目的：**让读者知道该信哪一篇、哪些是历史记录**。 +> +> 此前本目录 32 篇文档混着三种时态 —— 当时实测、历史推演、设计规划 —— +> 外观完全相同，读者无从分辨。曾有文档写着「`main.go` 仍走串行代码」 +> 而实际早已接完（滞后一整轮发布）。 +> +> 所以先分类，再读内容。 + +--- + +## 一、怎么判断一篇文档的可信度 + +每篇文档首部应有**状态行**，取值只允许这四种： + +| 状态 | 含义 | 能不能当事实用 | +|---|---|---| +| **已实现并部署** | 文中描述与代码一致，关键处给了取数命令 | ✅ 可以直接信 | +| **部分实现** | 先说清哪部分生效、哪部分没有（附实测调用点） | ⚠️ 只信标了"生效"的部分 | +| **设计 / 未实现** | 是方案，不是现状。代码里可能没有 | ❌ 只能当设计意图 | +| **归档说明** | 历史记录，**故意保留当时的写法** | ❌ 不要改它，也不要信它 | + +### 判据名的可信度规则（重要） + +文档里出现的 `TestXxx` 名字，**不保证现在还存在**： + +- **已实现并部署**类文档里的判据名 → 应当存在。找不到就是缺陷（报告它） +- **设计 / 未实现**类文档里的判据名 → 是**规划的名字**，可能从未实现 +- **归档说明**类文档里的判据名 → 记录的是当时的事实，可能已改名或删除 + +历史上有过一次真实漂移：`BootCtx` 改名为 `KernelState` 后， +`TestBootCtxCloseAllIsReverseOrder` 随之变成 +`TestKernelStateCloseAllIsReverseOrder`，而文档没跟上。 + +**核对命令**（任何时候都可以自己跑）： + +```bash +# 列出本目录引用的全部判据名里，仓库中找不到的那些 +for n in $(grep -rhoE '`Test[A-Z][A-Za-z0-9_]+`' docs/zh/*.md | tr -d '`' | sort -u); do + grep -rq "func $n(" --include="*_test.go" internal cmd 2>/dev/null || echo "缺失: $n" +done +``` + +跑出来有缺失**不一定**是缺陷 —— 先看它出在哪类文档里。 + +**当前基线（2026-10-31）**：27 条缺失，分布如下，全部已知且已说明： + +| 篇数 | 文档 | 性质 | +|---|---|---| +| 18 | `commondev-design.md` / `commondev-agent-runtime-design.md` | 「设计 · 未实现」类，判据名是**规划名** | +| 7 | `kernel-modularization-design.md` | §2.7.3 的**对照表左栏**（有意的历史记录），其中 4 条已登记 future-plan §2.3 | +| 2 | `multimodal-space.md` | 视频能力未纳入契约，判据为规划名 | + +⇒ **在「已实现并部署」类文档的正文里（非历史对照表）找不到判据名，才是缺陷。** + +--- + +## 二、文档清单（按状态分类） + +### 2.1 已实现并部署 —— 可以直接当事实 + +| 文档 | 内容 | +|---|---| +| [`kernel-modularization-design.md`](./kernel-modularization-design.md) | **装配架构权威**：依赖声明、BFS 分层、Group 0、实例化粒度 | +| [`kernel-secret-firewall-design.md`](./kernel-secret-firewall-design.md) | 安全防火墙（**部分实现**，见文首接线状态表） | +| [`input-scheduler-design.md`](./input-scheduler-design.md) | 两类别输入 + L1–L4 中断 + 可抢占 | +| [`resident-subagent-design.md`](./resident-subagent-design.md) | 驻留子：轻量内核、两级记忆、父子 L3/L4 | +| [`toolcall-contract-and-sequence-design.md`](./toolcall-contract-and-sequence-design.md) | 工具调用契约与顺序 | +| [`ci-cd-runbook.md`](./ci-cd-runbook.md) | CI/CD 操作手册 | +| [`deploy-runbook.md`](./deploy-runbook.md) | 部署手册 | +| [`site-infra-runbook.md`](./site-infra-runbook.md) | 站点基础设施 | + +### 2.2 参考 / 实测报告 —— 数据可信，结论看日期 + +| 文档 | 内容 | +|---|---| +| [`kernel-performance.md`](./kernel-performance.md) | 性能实测数据 | +| [`production-recall-validation.md`](./production-recall-validation.md) | 生产召回验证（含未解决的 3 条遗留边） | +| [`recall-as-association.md`](./recall-as-association.md) | 召回作为关联的机制说明 | +| [`recall-capability-tiers.md`](./recall-capability-tiers.md) | 召回能力分层（含 2 个未补的缺口） | +| [`multimodal-space.md`](./multimodal-space.md) | 多模态向量空间 | +| [`vector-provider-decision.md`](./vector-provider-decision.md) | 向量 provider 选型决策 | +| [`abstention-criterion.md`](./abstention-criterion.md) | 弃答判据 | +| [`triple-extract-attention.md`](./triple-extract-attention.md) | 三元组抽取与注意力 | + +### 2.3 设计 / 未实现 —— 只能当设计意图 + +| 文档 | 状态 | +|---|---| +| [`commondev-design.md`](./commondev-design.md) | 标题即写明「**设计 · 未实现**」；架构已变更，见其 §12 | +| [`commondev-agent-runtime-design.md`](./commondev-agent-runtime-design.md) | 架构已按前篇 §12 调整，部分未落地 | +| [`interrupt-subsystem-split-plan.md`](./interrupt-subsystem-split-plan.md) | 探测结论 + 实施计划 | +| [`toolcall-parallel-execution-plan.md`](./toolcall-parallel-execution-plan.md) | 并行化执行计划（含遗留项） | +| [`memory-blockflow-repair-plan.md`](./memory-blockflow-repair-plan.md) | 记忆块流修复计划 | +| [`memory-restructure-plan.md`](./memory-restructure-plan.md) | 记忆重构计划 | +| [`memory-usability-plan.md`](./memory-usability-plan.md) | 记忆可用性计划 | +| [`scene-memory-fix-plan.md`](./scene-memory-fix-plan.md) | 场景记忆修复计划 | +| [`legacy-table-retirement.md`](./legacy-table-retirement.md) | 遗留表退役（收尾中） | +| [`entities-retirement-plan.md`](./entities-retirement-plan.md) | 实体表退役 | +| [`prod-migration-checklist.md`](./prod-migration-checklist.md) | 生产迁移清单 | +| [`triple-distill-llm-design.md`](./triple-distill-llm-design.md) | 已实现并**部分否决** | + +### 2.4 归档说明 —— 历史记录，不要改也不要信 + +| 文档 | 说明 | +|---|---| +| [`context-overflow-l4-design.md`](./context-overflow-l4-design.md) | 术语已过时（`memory_*` 等旧工具名保留原样） | +| [`live-run-evidence-2026-10-04.md`](./live-run-evidence-2026-10-04.md) | 某次实跑证据快照 | +| [`legacy-issues.md`](./legacy-issues.md) | 遗留问题清单 | + +> **为什么归档文档里有旧工具名却不改**：它们是**证据快照**。 +> 把 `memory_recall` 改成 `stablemem_recall` 等于篡改当时的记录， +> 让后来的人无法判断"这条结论是在哪个版本上得出的"。 + +### 2.5 唯一未做登记处 + +| 文档 | 内容 | +|---|---| +| [`future-plan.md`](./future-plan.md) | **全仓唯一的「尚未实现 / 已知缺口」登记处** | + +**规则**：任何设计文档都不再自己维护「未做」小节，一律登记到 future-plan。 +历史上各文档各自维护，结果滞后过 —— 已完成仍写未做，未做被当成已完成。 + +--- + +## 三、写文档的三条纪律 + +1. **数字类断言必须给取数命令**（如模块数用 + `go run ./cmd/homed-depgraph -print`），**不要凭记忆写数字**。 + 本文档集历史上写错过一次（17 模块 vs 实际 20）。 + +2. **区分「机制存在」与「接线生效」**。本项目的头号缺陷形态是 + 机制写对了、判据全绿、生产里零调用方。描述能力时写**实测的生产调用点**， + 不要只写"已实现"。 + +3. **判据要能红**。写判据时先问：把对应实现删掉，这条判据会红吗？ + 本仓踩过两次：`security_toolgate_test.go` 手动调 `SetSecurity` + 把缺失的接线补上了；`retention_test.go` 手写合规文件名， + 从没跑过真实产物。两者都永远绿。 diff --git a/docs/zh/abstention-criterion.md b/docs/zh/abstention-criterion.md index ea9c1a63..d1003578 100644 --- a/docs/zh/abstention-criterion.md +++ b/docs/zh/abstention-criterion.md @@ -1,5 +1,8 @@ # 拒答判据：符号存在性 +> **状态：参考 / 机制说明。** 描述拒答判据的设计口径与实现位置，非逐条审计记录。 +> 未实现项见 [`future-plan.md`](./future-plan.md)。 + ## 结论先行 **「查询符号在库中零出现」可以安全拒答。** 依据是确定性事实 diff --git a/docs/zh/ci-cd-runbook.md b/docs/zh/ci-cd-runbook.md index bbfb2757..21f400c8 100644 --- a/docs/zh/ci-cd-runbook.md +++ b/docs/zh/ci-cd-runbook.md @@ -1,5 +1,7 @@ # CI/CD 流水线手册（GitHub Actions） +> **状态：操作手册（现行）。** 照着做即可；命令与配置如有变更需同步更新本文。 + > 2026-09-29 随仓库迁移 gitcode → GitHub 而建。此前 AtomGit 停止对普通用户 > 提供流水线，本仓无任何自动化验证。本文记录两条流水线的用法、机制与边界。 > 分支模型见 `docs/git-branching.md`（本文与其 §七「发版产物清单」衔接）。 diff --git a/docs/zh/deploy-runbook.md b/docs/zh/deploy-runbook.md index b7e41030..a3305fc7 100644 --- a/docs/zh/deploy-runbook.md +++ b/docs/zh/deploy-runbook.md @@ -1,5 +1,7 @@ # HologramAgent 生产部署手册（homed / waiter） +> **状态：操作手册（现行）。** 照着做即可；命令与配置如有变更需同步更新本文。 + > 适用范围：本机（`.60`）的 `homeagent.service`，以及两台设备桥宿主上的 > `waiter-remote.service`。 > diff --git a/docs/zh/future-plan.md b/docs/zh/future-plan.md index 4649febc..4ae3d30d 100644 --- a/docs/zh/future-plan.md +++ b/docs/zh/future-plan.md @@ -38,7 +38,7 @@ |---|---|---|---|---| | 1 | 工具黑白名单 `Policy.CheckTool` | 完整 | `Agent.security` 恒 nil，闸门恒放行 | ✅ 2026-10-30 修复（依赖图补 `FacSecurity`） | | 2 | 主体策略 `CheckToolFor` | 完整 | 0 生产调用方 | ✅ 2026-10-30 修复（父为子声明） | -| 3 | 插件命名档位 `ActivateProfile` | 完整 | **0 生产调用方** | 🔴 **未修**，见 §1.1 | +| 3 | 插件命名档位 `ActivateProfile` | 完整 | 曾 0 生产调用方 | ✅ 2026-10-31 修（见 §1.1，两次修才修对） | | 4 | 敏感词 / 注入预警 `ScanContent` | 完整（254 行） | **0 生产调用方** | 🔴 **未修**，见 §1.2 | | 5 | 沙箱 `CheckPath` / `CheckNetwork` | 完整 | **0 生产调用方** | 🔴 **未修**，见 §1.3 | @@ -48,48 +48,64 @@ ## 一、安全（security） -### 1.1 🔴 插件命名档位没有生效点 +### 1.1 ✅ 插件命名档位已接通（2026-10-31，两次提交） -**现状**：插件侧链路是完整的—— +> **本节已结案，保留是因为它的两次修法本身是教训。** +> 最初的诊断是「`activateSecurityProfile` 零调用方，在 `prepareInputTask` +> 里加一次调用」—— **那个诊断方向是错的**。 + +**真正的缺陷分三层：** ``` -QQ 插件 Start: s.Security().DeclareProfiles([qq.owner, qq.guest]) ✅ 内核登记了 -QQ 插件注入: InjectOptions{SecurityProfile: "qq.guest"} ✅ payload 里写进去了 -内核 activateSecurityProfile(payload) ❌ 零调用方 -CheckTool 按档位判定 ❌ 从未激活 ⇒ 恒"无档位" +第 3 层（表面）：activateSecurityProfile 零调用方 + ↑ 补一次调用「看起来」就好了 + +第 2 层：agent/core 在替 security 做**策略决策** + · 自己从 payload 抠 security_profile（解析 security 的协议） + · 自己判断 parentID != "" → 走 CheckToolFor，否则 CheckTool + · 自己拼 PrincipalPolicy{...} 字面量 + · 自己写 Kind: "resident" —— **声明自己是哪类主体**（提权口子） + +第 1 层（根因）：security 缺少「输入接入点」 + 判定原语是细粒度的，要求调用方自己知道"我是谁、该走哪条链"。 + 于是每个消费方都得理解策略语义，三条输入路径各接一遍。 ``` -实测确认： - -- `codegraph_callers("activateSecurityProfile")` → 4 个调用方，**全部是测试** -- `prepareInputTask` 逐条消费 `evt.Payload` 的各键（`no_memory` / `interrupt` / - `priority` / `scene` / `scene_policy` / `content` …），**唯独没有 `security_profile`** -- 生产日志里 `security profiles declared: qq.owner, qq.guest` 是**真的**（声明成功了）， - 但没有一条拒绝记录 —— 因为档位永远没被激活 - -**影响**：QQ 的 owner / guest 差别对待**在生产中完全失效**。访客能用的工具与所有者相同。 - -**要做的**： - -1. 在 `prepareInputTask` 里读 `evt.Payload["security_profile"]`，调 `activateSecurityProfile` -2. **必须自带归位**：不带档位的输入要显式清空（`ActivateProfile("")`）， - 否则进程级 `active` 会泄漏到下一轮（guest 的收窄误伤后续输入；方向相反就是提权） -3. 判据必须走**真实输入路径**（`runInputTask`），不能直接调 `activateSecurityProfile` - -**已知的架构限制**（解决前必须知道）： - -`security.Runtime` 的 active profile 是**进程级单例**，不按任务隔离。 -主 agent / 驻留子 / rtchild 同进程并发时，两个不同档位的轮次**交错**就无法表达。 +**收敛后的形态**（`5194a96`）： ``` -A 轮: 注入 guest 档 ─┐ - ├─ 共享一个 active ⇒ 后写者覆盖先写者 -B 轮: 注入 owner 档 ─┘ +RoundInput{AgentID, IsChild, Payload, Source} ← 只有事实，无 Kind +rt.BeginRound(in) → security 自己解析档位 + 自己判定主体类别 +round.CheckTool(t) → 本轮判定 +round.End() → 归位 ``` -正确形态是把档位挂到 `TaskFrame` 上按任务隔离，但那要先改 -`security.Runtime.CheckTool` 的签名（它当前无任务上下文）。 -**在此之前只保证串行场景正确。** +**再进一层：每 agent 一个实例**（`8293282`，用户裁定「每个 agent 一个， +分为 sessionProfile 和 longtimeProfile」）： + +``` +共享（进程级 1 份） per-agent（N 份） +───────────────────── ───────────────────── +gate / policy / content sessionProfile ← 轮次级，End 即清 +profiles / principals longtimeProfile ← agent 生命期，跨轮保留 +scopes / eventPolicy +``` + +优先级 **session > longtime**，这个顺序本身是安全语义： +session 是"这一轮的事实"，必须能盖住 long-time 默认值（否则访客在长期 +为 owner 的 agent 上无法收窄）；反向就是提权。 + +**判据**：`TestAgentScopesDoNotShareSessionProfile` / +`TestLongtimeProfileSurvivesRounds` / `TestReleaseAgentDropsLongtimeProfile` / +`TestAgentCoreHoldsNoPolicySemantics`（源码扫描，禁 agent 再做策略决策）/ +`TestEveryInputPathDeclaresRound`（三条输入路径都要声明轮次边界）。 + +**顺带暴露的一个仍未解决的限制**：`Round` 是 per-round 句柄，但 +`Runtime.active`（旧路径）仍是进程级。per-agent 视图已经解决**并发 agent 串档**， +但**同一 agent 内**若将来出现并行子任务，仍需按 task 隔离。 +当前所有路径都是串行的，故不构成缺陷。 + +--- ### 1.2 🔴 敏感词 / 提示词注入预警从未运行 diff --git a/docs/zh/kernel-modularization-design.md b/docs/zh/kernel-modularization-design.md index 720c0137..25fa4c77 100644 --- a/docs/zh/kernel-modularization-design.md +++ b/docs/zh/kernel-modularization-design.md @@ -864,6 +864,34 @@ platform-check → heartbeat-early → logging → data-dirs - `internal/kernelmod/all/bootgraph_test.go` 的 5 条整机判据 —— 真实登记表装配、 层间有序、逆序关闭、无残留、模块不漏挂 +#### 2.7.5 模块产物的**实例化粒度**（2026-10-31 补充） + +依赖图保证的是"设施**已就绪**"，但没说设施该有几个实例。这在本模块化设计里 +是个独立决策，已有两个不同的答案： + +| 设施 | 粒度 | 理由 | +|---|---|---| +| `memory` / `knowledge` / `llm` | **进程级 1 个** | 共享同一份数据源，复制没有意义 | +| `security` | **1 个 Runtime + 每 agent 1 个执行视图** | 全局基线共享（否则插件声明对部分 agent 不生效），但**轮次状态**必须 per-agent | + +security 的切分值得记下来，因为**整份复制是错的**： + +``` +共享（进程级 1 份） per-agent（N 份） +───────────────────── ───────────────────── +gate / policy / content sessionProfile ← 轮次级，End 即清 +profiles / principals longtimeProfile ← agent 生命期，跨轮保留 +scopes / eventPolicy +``` + +若把整个 Runtime 复制给每个 agent：插件往 A `DeclareProfile("qq.guest")`， +B 就看不到这个档位 ⇒ B 上注入 `qq.guest` 报"未声明"。那是最难查的一类缺陷 +（表现为"时灵时不灵"）。所以切分原则是**共享注册表 + per-agent 执行视图**。 + +**给未来新模块的判据**：决定实例化粒度时先问两件事 —— + +1. 这份状态是**共享的事实**（配置/注册表）还是**某个执行体的私有状态**（轮次/会话）？ +2. 复制它会不会让"某个模块声明的东西"对另一个实例不可见？ ### 2.8 完整启动流程与真实依赖（逐行核对，2026-10-16） @@ -960,7 +988,9 @@ func (d *Distiller) distillLoop() { 原 main 用 `defer closeMem()` 等 5 处，释放顺序 = **注册顺序的逆序**（LIFO）。 模块化后改为 `Put(".close", fn)` + `CloseAll()` 按**发布顺序逆序**执行 -⇒ 语义**逐字等价**（判据 `TestBootCtxCloseAllIsReverseOrder` 守）。 +⇒ 语义**逐字等价**（判据 `TestKernelStateCloseAllIsReverseOrder` 守 —— +原名 `TestBootCtxCloseAllIsReverseOrder`，`BootCtx` 改名为 `KernelState` 时判据跟着改名， +本文此前未同步，2026-10-31 更正）。 **(D) 包级 `init()` 注册（BuiltinFactory）** @@ -1353,7 +1383,8 @@ var i SyncState = nb // ★ i != nil！经典的 typed-nil 陷阱 接口值**非 nil**（它带类型信息），于是 `bus.IsReady(...)` 解引用空指针 ⇒ **panic**。 -**实测复现**：`TestNilTypedBusSafety` 确认 panic 真实发生 +**实测复现**：`TestNilTypedBusSafety`（**规划中的判据名，仓库中不存在**； +该 panic 形态由 §2.6 的 `SyncBus` 现行为规避）确认 panic 真实发生 （`invalid memory address or nil pointer dereference`）。 而 panic 在**插件拉起路径**上 ⇒ 整个内核启动失败。 diff --git a/docs/zh/kernel-performance.md b/docs/zh/kernel-performance.md index 81d734a5..9a4d556d 100644 --- a/docs/zh/kernel-performance.md +++ b/docs/zh/kernel-performance.md @@ -1,5 +1,7 @@ # 内核性能指标（实测基线） +> **状态：实测基线。** 数据来自标注的日期/版本；引用前先确认它是否仍对应当前版本。 + 本文记录**实测**数据，不是估算。每条都标出测量方法与采集时间， 便于复现与追回归。 diff --git a/docs/zh/kernel-secret-firewall-design.md b/docs/zh/kernel-secret-firewall-design.md index f8ffb3bc..157fdf14 100644 --- a/docs/zh/kernel-secret-firewall-design.md +++ b/docs/zh/kernel-secret-firewall-design.md @@ -1,5 +1,14 @@ # 内核安全模块（Secret Firewall）设计 · 计划追加 +> **架构形态（2026-10-31 收敛后）**：security 是**外围内核到核心内核之间的防火墙** +> —— 它自己提供接口、判定全部内聚在自己内部。调用方只提供**事实** +> （谁在跑、有没有父、原始载荷），不提供**结论**（我是哪类主体、该走哪条判定链）。 +> +> 落地形态：**每 agent 一个策略执行视图**（`AgentScope`），共享一个注册表 +> （`profiles` / `principals` / `scopes`）。档位分两层： +> `sessionProfile`（轮次级，End 即清）/ `longtimeProfile`（agent 生命期）。 +> 详见 `internal/security/agentscope.go` 与 `round.go` 的包注释。 +> > **状态：部分实现。** 凭据防火墙、配置加密、变量库统一与 C1–C8 判据已落地并**在生产线生效**； > 但**三条能力机制完整却零生产调用方**（敏感词/注入预警、路径沙箱、网络闸）。 > 本文保留原始设计与逐条审计记录；未实现项统一登记在 @@ -15,10 +24,10 @@ > | 出向凭据拦截 `PrepareOutbound` | 完整 | `eventguard.go` / 各界代理 | ✅ 生效 | > | 入向凭据清洗 `ScrubInbound` | 完整 | `eventguard.go`、`events/bus.go`、`device/mod.go` | ✅ 生效 | > | 执行前回填 `FillForExecution` | 完整 | stage 管道 | ✅ 生效 | -> | 工具黑白名单 `CheckTool` | 完整 | `agent/core/security_profile.go`（主 agent） | ✅ **2026-10-30 接通** | -> | 按主体授权 `CheckToolFor` | 完整 | `agent/core/security_profile.go`（子 agent） | ✅ **2026-10-30 接通** | +> | 工具黑白名单 `CheckTool` / `checkToolWithProfile` | 完整 | `security/agentscope.go` → `AgentScope.CheckTool` | ✅ **2026-10-31 接通** | +> | 按主体授权 `CheckToolFor` | 完整 | 同上（`checkToolForWithProfile` 同时叠主体策略） | ✅ **2026-10-30 接通** | > | 插件命名档位 `DeclareProfile` | 完整 | `sdk/security_impl.go`、`proc/corehandler_security.go` | ✅ 声明侧通 | -> | 插件命名档位 `ActivateProfile` | 完整 | `agent/core/security_profile.go` 内的 `activateSecurityProfile` | 🔴 **该函数零调用方** ⇒ 档位永不激活，见 future-plan §1.1 | +> | 插件命名档位 `ActivateProfile` | 完整 | `security/agentscope.go` 的 `setSession` + `BeginRound` | ✅ **2026-10-31 接通**（每 agent 独立实例） | > | 敏感词/注入 `ScanContent` | 完整（254 行） | **无** | 🔴 配置里的敏感词一条不生效，见 future-plan §1.2 | > | 路径沙箱 `CheckPath` | 完整 | **无**（只被 Runtime 自己调 Policy） | 🔴 见 future-plan §1.3 | > | 网络闸 `CheckNetwork` | 完整 | **无**（同上） | 🔴 见 future-plan §1.3 | diff --git a/docs/zh/legacy-issues.md b/docs/zh/legacy-issues.md index 2d69d993..4acd9035 100644 --- a/docs/zh/legacy-issues.md +++ b/docs/zh/legacy-issues.md @@ -1,5 +1,10 @@ # HologramAgent 遗留问题清单 +> **状态：长期清单（部分条目已过时）。** 本文按「仍未完成且经核实」筛选， +> 但清单会随代码演进滞后 —— 引用某条前请先用源码复核。 +> 它**不是** future-plan 的替代：future-plan 收「能力缺失」与「机制在但零调用方」， +> 本文收「已知问题与收尾项」。两者有交叉时以 future-plan 为准。 + > **本文定位（2026-09-25 重写）**：只写**仍未完成、且经源码/实测核实确属本仓库**的问题。 > > **判定方法**：不继承任何旧档的复选框，回到源码与构建现场逐条重验 diff --git a/docs/zh/legacy-table-retirement.md b/docs/zh/legacy-table-retirement.md index 9ba921be..290fe378 100644 --- a/docs/zh/legacy-table-retirement.md +++ b/docs/zh/legacy-table-retirement.md @@ -1,5 +1,7 @@ # 旧表清理可行性评估（2026-10-04） +> **状态：计划（收尾中）。** 遗留表退役的执行记录；剩余读方见文内 §八 / §十二。 + > 结论：**现在不能清理**。55 处生产调用点仍在读写 `entities` / `relations` / `sentences`。 > 这份评估回答「能不能删」以及「删之前要先做什么」。 diff --git a/docs/zh/live-run-evidence-2026-10-04.md b/docs/zh/live-run-evidence-2026-10-04.md index 376285cc..09c1e688 100644 --- a/docs/zh/live-run-evidence-2026-10-04.md +++ b/docs/zh/live-run-evidence-2026-10-04.md @@ -1,5 +1,8 @@ # 实战证据：新内核在真实跑分中的行为（2026-10-04 07:13~07:29） +> **状态：归档说明（历史证据快照）。** 记录 2026-10-04 那次实跑的现场数据。 +> **不要用它的结论覆盖现在的实现判断** —— 代码已演进，快照只证明"当时是这样"。 + 内核 `657ccd7`（含今天全部 19 个 memory 层提交）跑 tasks.zerobasis + memory_recall 时的实例日志。 ## 一、召回来源标签（今天新增的功能） diff --git a/docs/zh/multimodal-space.md b/docs/zh/multimodal-space.md index 2d6bfe21..cb3e7006 100644 --- a/docs/zh/multimodal-space.md +++ b/docs/zh/multimodal-space.md @@ -1,5 +1,9 @@ # 统一多模态向量空间 +> **状态：参考 / 实测。** 多模态向量空间的设计与实测数据。 +> 注意：文中 `TestEmbedderVideoMatchesONNXReference` 是**规划中的判据名**， +> 仓库中不存在（视频尚未纳入契约，见文内说明）。 + 核心不绑定任何具体模型：它按 provider 名从公共注册表（`pkg/embedding`）打开一个 向量空间。仓库内自带两个： diff --git a/docs/zh/production-recall-validation.md b/docs/zh/production-recall-validation.md index 33d8938f..5141cd8d 100644 --- a/docs/zh/production-recall-validation.md +++ b/docs/zh/production-recall-validation.md @@ -1,3 +1,8 @@ +# 生产召回验证：探针 PASS 但结论是假的 + +> **状态：实测报告（结论有效，日期见文内）。** 记录了「探针通过≠能力成立」 +> 这一类失败的具体形态，是判据设计的反面教材。 +> 文末 3 条遗留 sentence→块 边仍开放，已索引到 [`future-plan.md`](./future-plan.md) §六。 ## 二十五、生产规模验证：**探针 PASS 了，但结论是假的** diff --git a/docs/zh/recall-as-association.md b/docs/zh/recall-as-association.md index dda301bd..39f29f8f 100644 --- a/docs/zh/recall-as-association.md +++ b/docs/zh/recall-as-association.md @@ -1,5 +1,8 @@ # 召回即联想 +> **状态：参考 / 机制说明。** 描述召回作为关联的模型，非待办清单。 +> 未实现项见 [`future-plan.md`](./future-plan.md)。 + > **「召回是针对节点的，然后召回的是节点与 n 层 bfs 结果」** > —— 这个机制就是在模仿人类的联想能力。 diff --git a/docs/zh/recall-capability-tiers.md b/docs/zh/recall-capability-tiers.md index 3ae62f25..896cca4e 100644 --- a/docs/zh/recall-capability-tiers.md +++ b/docs/zh/recall-capability-tiers.md @@ -1,5 +1,8 @@ # 生产召回能力分层 +> **状态：实测报告 + 待补清单。** 能力分层与缺口来自生产实测。 +> 文末「待补的能力」两个缺口仍开放，已索引到 [`future-plan.md`](./future-plan.md) §六。 + > 单一分数（如「4/9」）会掩盖真实情况。真正有用的问题是： > **什么形态的查询能用、什么不能用、为什么。** diff --git a/docs/zh/scene-memory-fix-plan.md b/docs/zh/scene-memory-fix-plan.md index 13b443c6..da632d33 100644 --- a/docs/zh/scene-memory-fix-plan.md +++ b/docs/zh/scene-memory-fix-plan.md @@ -1,5 +1,8 @@ # 场景式记忆修复 plan +> **状态：计划（部分落地）。** 是修复计划，不是现状描述。 +> 未完成项已索引到 [`future-plan.md`](./future-plan.md) §六。 + > 起点：2026-09-26 生产库实测（`${HA_DATA}/memory/graph.db`）。 > 现象：65 个场景中 6 组是同一场面的双胞胎键；主力场景 `auto:chan:qq+part:morning` > strength=270、6 个 features、**0 条记忆**，日志里被"命中"179 次。 diff --git a/docs/zh/site-infra-runbook.md b/docs/zh/site-infra-runbook.md index 210d7335..101cd21d 100644 --- a/docs/zh/site-infra-runbook.md +++ b/docs/zh/site-infra-runbook.md @@ -1,5 +1,7 @@ # 站点基础设施运维手册 +> **状态：操作手册（现行）。** 站点基础设施的操作说明。 + > 适用：本项目**文档站与产品站**的生产部署（多站点、统一入口、多层 TLS 终止）。 > 读者：后续维护者 / AI agent。 > **本文件不含任何密钥、token、真实域名与 IP** —— 全部用占位符，取值见本机 `deploy/` 外的私有笔记或基础设施面板。 diff --git a/docs/zh/triple-extract-attention.md b/docs/zh/triple-extract-attention.md index 6927de66..8a96ad9d 100644 --- a/docs/zh/triple-extract-attention.md +++ b/docs/zh/triple-extract-attention.md @@ -1,5 +1,7 @@ # 三元组抽取：注意力模型方案 +> **状态：参考 / 机制说明。** 三元组抽取与注意力机制说明。 + > 2026-10-03。目标是**推理时零 LLM**——一次 LLM 标注，训一个专用网络。 ## 一、为什么必须是「注意力学任务结构」而不是更好的向量 diff --git a/docs/zh/vector-provider-decision.md b/docs/zh/vector-provider-decision.md index cbb52a9e..41d4a624 100644 --- a/docs/zh/vector-provider-decision.md +++ b/docs/zh/vector-provider-decision.md @@ -1,5 +1,7 @@ # 向量 provider 决策：Qwen3-VL vs chineseclip +> **状态：决策记录（已定）。** 记录了 provider 选型过程与结论，属决策归档性质。 + > 结论先行（2026-10-03 实测，真库 260 个块，两套 ONNX 均已导出校验通过） > > **不切换 provider。** 各用其位：