jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 06:47:29 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
7f43a6bfc78b2f0c2b6104c10584e41d8dc4801c
HomeAgent/assets/docs/zh/OVERVIEW.md
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

8.3 KiB
Raw Blame History

English | 中文

HologramAgent — 项目概览

这是什么

HologramAgent 是一个持续运行的个人智能 Agent 框架。

核心架构：一个长时间运行的内核进程（homed），通过插件系统接入各种 IO 通道（QQ、Web、命令行等）。内核负责 LLM 调用编排、记忆管理、知识检索；插件负责所有外部 IO——收发消息、执行文件操作、搜索网络等。

设计要点

核心域与应用域分离 — 内核（核心域）不执行任何 IO 操作，所有 IO 能力归属插件（应用域）。边界通过 PluginSDK 明确定义：

  • 插件向内核注册工具（Tool），供 LLM 调用
  • 插件挂入处理管道（Stage），在各阶段拦截/改写消息流
  • 插件订阅/发布事件（Event），松耦合通信
  • 插件通过 IO API 排队或打断投递输入

这一划分的意义在于职责边界清晰：内核专注于编排与记忆管理，插件负责具体 IO 实现，二者互不耦合。

业务语义留在插件层 — 内核不定义业务对象：终端、命令历史、设备状态、媒体库 都属于插件域。以终端为例，PTY、会话生命周期与输出缓冲全归 agentcli；WebUI 与 CLI 需要终端面板时，订阅事件总线（EventTerminalOutput + EventToolCall） 自己攒视图，而不是去读内核里的某个状态组件。内核只提供事件总线与插件注册面—— 新增一类能力不需要改内核，也不会在核心里堆出第二套业务真相。

三层记忆架构 — 三层不是三种数据结构，而是同一批记忆块的三层持有关系：

  • Context 层（L1，直接投喂）：内存中预训练词嵌入评分的事件窗口（StaticEmbedder 词向量 → CosineSimilarity，TF-IDF 回退），实时维护最近上下文，低相关性事件自动下沉到下一层
  • Document 层（L2，不直接投喂）：与 L1 结构同构——同样的事件 + 同样的块，只是不直接进模型视野；支持显式提交和隐式归档，冷数据蒸馏到稳定记忆（stablemem）
  • Stablemem 层（L3，持久）：SQLite 图数据库，顶层仍是三元组（节点 + 关系边），但节点从 entities 表升级为 memory_blocks；BFS 遍历召回，蒸馏管道从对话中提取三元组

★ L1 与 L2 唯一区别是「是否被直接投喂给模型」：L2 不是 L1 的摘要层，也不是 另一种数据形态。召回 = 把事件（连同它持有的块）从“不投喂”的持有层迁回“投喂”的持有层。

★ 正文（含多媒体正文）内联在块里：文本块的 Text 是正文，媒体块的 Data 是字节。 不存在「块 + 外部正文」的分离形态。任何一层都不压缩 —— 视图（检索摘要、渲染结果） 可以是压缩的，但视图不是记忆。

三层流动：上下文 → 冷归档 → 长期稳定记忆，构成从短期到持久的信息衰减与整合管道； 每一次都是迁移（块 ID 与向量不变，只换持有层），不是复制。

媒体记忆（v1.2.0 起：一等记忆块） — 图片/音频不是附属物，而是记忆的一等节点：

  • 内容寻址存储（CAS）：digest 寻址，元数据在 SQLite、blob 在磁盘（两级分桶），相同字节只存一份， 每次 Get 重校 digest（磁盘损坏静默返回脏数据比报错更危险）
  • 媒体块直接参与向量检索：块携带自己的多模态向量与指纹，正文里不再有任何媒体标记
  • 无独立 GC、无引用计数、无 keep-set：记忆块遵循单层不变量——Context → Document → Graph 是块的迁移，不是复制、也不靠引用保活；删除块即删内容
  • v1.1.1 起贯通插件边界：插件可通过 InsertWithMedia / InjectInputMedia 读写媒体， 模型可用 stablemem_commit / coldcontext_commit 的 media_digests 参数关联媒体
  • 旧机制已整体拆除：此前把视觉模型生成的描述写进正文、以 [<mime> <短digest>] <描述> 标记 参与检索的描述式索引，以及 media_refs 引用计数，均已在 v1.2.0 删除——描述是模型生成的 二手信息，检索「别人转述的图片」不如检索图片自己的向量

它实际做了什么

代码位于项目仓库根目录，Go 语言实现。

内核 (internal/agent/core/)：

  • eventloop.go — 消息循环（eventLoop），从 IO 层排队接收输入
  • process.go / stages.go — 处理管道：记忆召回 → 人格注入 → LLM 调用 → 工具执行 → 输出发送，7 阶段钩子
  • toolcall.go — 工具调度与执行
  • context.go — 上下文管理（预训练词嵌入评分 StaticEmbedder → CosineSimilarity，TF-IDF 回退），自动剪枝低相关性事件
  • LLM 调用通过 Provider 接口抽象，多源自动降级

记忆系统 (internal/memory/)：

  • GraphDB (graph.go) — SQLite，entities + relations 表，BFS 遍历
  • Document Store (document/document.go) — 临时记忆，JSON 文件 + TF-IDF 向量索引，消费即删
  • Text Memory (text/text.go) — 原始对话日志，JSONL 文件轮转
  • Social Store (social/social.go) — 人格特质 + 关系网，包装 GraphDB
  • Memory Indexer (indexer.go) — 自动将 GraphDB 实体向量化，用户输入时召回注入 system prompt

知识库 (internal/knowledge/knowledge.go)：

  • 文件系统目录 knowledge/<name>/content.md
  • TF-IDF 向量搜索，独立于记忆系统的索引实例
  • LLM 通过 knowledge_search / knowledge_create / knowledge_list 三个工具操作

插件系统 (internal/plugin/)：

  • 内置插件：Go init() 自注册，编译进内核
  • 外部插件（v1.0.0 起）：编译为普通 Go 二进制 plugin.bin，内核 spawn 为独立子进程， 经 stdio JSON-RPC（控制面）+ 共享内存段（数据面）+ 事件环（通知面）通信；也支持 Lua 脚本插件 （C ABI 动态库通道 -buildmode=c-shared 已在 v1.0.0 整体删除）
  • PluginSDK (internal/sdk/) 定义四通道：RegisterTool / RegisterStage / Subscribe / RegisterOutputChannel
  • 阶段钩子 7 个：on_input → pre_action → post_action → before_toolcall → after_toolcall → before_output → after_output

LLM Provider (internal/agent/api/provider.go)：

  • Provider 接口：Name / Chat / ChatStream / MaxContextTokens
  • 唯一实现 LuaAdaptedProvider：所有源都经 Lua 适配脚本做请求/响应变换； 适配器脚本位于 internal/lua/adapters/，每类协议一个 .lua 脚本
  • 内置 10 个适配器：deepseek / openai / anthropic / gemini / mistral / groq / github / kimicode / ollama / server
  • 源（core.llm.sources.<name>.*）由部署时配置，数量不固定，不随内置适配器数绑定

WebUI (internal/plugins/webui/)：

  • 嵌入式 SPA 仪表盘（dashboard.html 通过 //go:embed 打包）
  • REST API：状态查询、配置管理、记忆操作、知识库管理、插件管理
  • 兼容 OpenAI API 格式的 /v1/chat/completions 端点
  • SSE 事件流 /api/v1/chat/events

ClawHub 适配器 (internal/plugins/clawhubadapter/)：

  • 统一加载 OC 插件（Node.js）、Python sidecar、JS sidecar、SKILL 四种插件类型
  • RegistryDispatcher 模式：Tool/Provider/Channel/Stage 注册通知分发
  • ClawHub 市场搜索与安装：clawhubadapter_search / clawhubadapter_npm_install
  • 9 种 Provider 类型映射为 LLM 可用工具（图片生成、搜索、语音等）
  • OC 通道自动注册为 IO 设备，支持文本/文件/图片/音频能力标志

项目状态

核心功能已可运行。插件系统和 SDK 已就绪，可独立开发外部插件。

  • 内置插件（13 个）：webui / cli / agentcli / cfgmgr / healthcheck / kbtree / multimodal / pluginmgr / clawhubadapter / remotedevice / skillmgr / seemedia / seq
  • 判定标准：只有必须使用内部 SDK 能力（公开 SDK 没有的接口面）的插件才内置，其余一律外置为 .hmap 插件（详见 ARCHITECTURE「内置插件的判定标准」）
  • 外部插件示例（hologramagentsdk 仓库 example/，含 Go 和 Lua 两种类型）：qq / files / a2a / ai_image / bili / browser / calendar / editdoc / memo / music / ocr / rss / sanitizer / weather / luademo
  • 打包分发：.hmap 插件包格式，通过 WebUI 安装