jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-10-15 12:15:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
785 Commits 6 Branches 29 Tags
6089b86935bae0ee488f11955366e129253958f9
Commit Graph

10 Commits

Author SHA1 Message Date
JianFeeeee
a9e0489e57 docs: 修正「项目概览/架构」把已删除机制写成现行机制（中英四份） 
## 问题

assets/docs/{zh,en}/OVERVIEW.md 的媒体记忆段仍在描述 v1.2.0 **已整体拆除**的机制，
且两份文档的第一读者入口（README「文档」区、site/index.html 的「项目概览」链接）
都指向它。docs/git-branching.md §七.7 的反例表里恰好列着这一条，说明这是
「文档当事实后反向误导」的复发项。

同时修掉同一批里其余过期的结构性断言（均为逐条回源码核实后改）。

## 改动（四份文件，7 处）

OVERVIEW.md（zh/en 对称）：
- 媒体记忆段：「引用计数 GC + 描述文本才是持久语义记忆 + [<mime> <digest>] 标记」
  → 「一等记忆块：块自带向量与指纹直接检索；无独立 GC / 无引用计数 / 无 keep-set；
    删除块即删内容」，并显式注明旧机制已在 v1.2.0 拆除
  - 依据：internal/memory/block.go（"不携带 Layer、Owner 或 RefCount"）、
    ARCHITECTURE.md 自身的「不再有描述式索引」段、
    graphmedia_test.go:24「描述文本、marker 反解…全部已废弃」、
    inputunify_test.go:226「不往文本里贴 marker」
- LLM Provider 段：「三种实现 OpenAIProvider/OllamaProvider/LuaAdaptedProvider」
  → 「唯一实现 LuaAdaptedProvider」
  - 依据：internal/agent/api/provider.go 只有 LuaAdaptedProvider 一个实现类型
- 适配器：「内置 8 个」→「内置 10 个」并补全名单（+kimicode/server）
  - 依据：ls internal/lua/adapters/*.lua = 10；README.md 同一处早已写「10 个」，
    两份文档此前自相矛盾
- 「支持 8 个 LLM 源自动降级」→「多源自动降级」
  - 依据：源数量由部署配置，默认 seed 仅 deepseek 一个
    （registry.go defaultSources 唯一条目）

ARCHITECTURE.md（zh/en 对称）：
- 代码结构树 internal/skill/（**该目录不存在**）→ 移入 plugins/skillmgr/
  - 依据：internal/plugins/skillmgr/ 存在，internal/skill/ 不存在（README 亦写 plugins/skillmgr）
- dynamic.go 描述「.so 动态加载器」→「加载通道分派（proc/lua/skill）；.so 仅剩给明确报错」
  - 依据：dynamic.go 的 tryDynamic 实际只分派 proc 与 lua，.so 命中只为给出「请用新版
    hmapdev 重编」的明确错误（legacyCABIEntries 注释）
- 配置系统「8 个 LLM 源的 seeds」→「含 1 个 LLM 源 seed，其余源由部署时添加」
- 适配器数 8 → 10
- Provider 分层图（仅 en 侧滞后）：删掉不存在的 OpenAIProvider/OllamaProvider
  - 依据：zh 侧同一图早已写作「LuaAdaptedProvider (唯一实现)」，en 侧未跟上

## 验证

- 全量残留扫描：OpenAIProvider / OllamaProvider / 引用计数 GC /
  Reference-counted GC / 8 个 LLM / 8 LLM / internal/skill / .so 动态加载
  → 在 assets/docs/ 与两份 README 中均为 **0 命中**（改前分别为 3/2/2/1/2/1/2/2）
- 每条新断言逐条回源码核实（adapters=10、provider struct=1、skillmgr 存在、
  internal/skill 不存在、defaultSources=1、无 marker 写入代码）
- 纯文档改动：不涉及 .go，不改变构建产物（assets/docs 未被 //go:embed 打包，
  仅被 site/index.html 以 GitHub 链接形式引用）
- 未新增版本号字面量，符合 §七.7 的「模型或用户会当作事实的文本不得写死版本号」

## 分支归属

按 docs/git-branching.md §七.7：面向使用者的开发者文档先落 release 线、
再 cherry-pick 合入 main（不 merge）。本次提交在 release/v1.3.x。
 2026-10-08 07:55:28 +08:00
JianFeeeee
6f5059c214 docs: 全面按当前源码更新文档 + 删除已过时文档 
## 删除（内容已落地/已被替换，保留只会误导）
- demo.md ................... failback 与 recoverydiag 均已实现，0 引用
- docs/defect-qq-output-send-loop.md .. 已修复（本身也标了「已修复」），0 引用
- docs/embedding-comparison.md ....... 一次性选型报告，仅被 agent 产物引用
- docs/zh/plan.md ............ 描述的旧 nav 布局已重写、死配置已清，全部完成
- docs/zh/plugin-migration-plan.md ... 迁移已上生产，纯过程稿（Part 0~6 全完成）

## 更新（按当前源码核对）
- assets/docs/{zh,en}/ARCHITECTURE.md（README 指向的用户文档，最重要）：
  把只讲 cancel/intercept 的旧「中断机制」章节重写为「输入调度器与中断机制」——
  补上两类别 + 四级中断（L1~L4，默认 L1、外部插件 L4 夹到 L3）+ 抢占/挂起/中断栈
  + 饥饿防护（PreemptCount 提升，封顶 L4）+ 抢占冷却（2s）+ 停止语义（cancelBudget）
  + 驻留子/分诊助手/残余任务；新增「上下文预算」章节（窗口 ≠ 工作面，600K 封顶，
  预算是上限非填充目标）。中英章节数现已对齐（各 13 节）。
- assets/docs/{zh,en}/PLUGIN_DEV.md：插件示例表补 6 个缺失项
  （acp/deepsearch/plugindev/recoverydiag/vanblog/vikunja）；qq 工具数 17 → 20（实测）。
- README.md / README_EN.md：补 v1.3.x 线（此前只到 v1.2.0，而 1.3.x 已发布 12 个 patch）——
  驻留式子 agent、输出通道寻址、输入调度器、轻量内核 profile、积压及时反馈。
- plan.md：开头两个「⚠️ 紧急/正在持续污染」是过期告警（实测  残留 = 0），
  改为「已解决」并加文档定位说明；§13 仍是活跃路线图故保留。
- docs/zh/plugin-interface-matrix.md + 两处源码注释：清理指向已删文档的断链。

全仓 md 断链检查：仅剩 1 处，位于 third_party 的 oh_modules（第三方依赖，非本项目）。
 2026-09-19 19:14:55 +08:00
JianFeeeee
387bc67af5 docs(architecture): 记忆流转图对齐统一多模态空间 
流程图里 Context/Prune/DocStore 三行仍只写 StaticEmbedder 与 TF-IDF，
读起来像"向量化只有词嵌入一条路"，与 1.2.0 实际（多模态统一空间为主，
带 fingerprint；词嵌入/TF-IDF 是降级层）不符。

- Context Append：补三层向量层级说明
- Context Prune：改为 DenseCosine（仅同指纹比较）→ StaticEmbedder 回退
- DocStore：改为稠密向量 + dense_fp 同指纹要求（不符即重算）
- 中英双版同步
 2026-09-12 12:46:21 +08:00
JianFeeeee
4c1fe03d98 refactor(plugin)!: 重编提示与模板路径改用 hmapdev；文档全面对齐 1.2.0 
工具链在 SDK 1.2.0 更名为 hmapdev（原 plugindev）。核心侧三处功能耦合同步：

1. 用户可见报错：旧 C ABI 产物 / 协议版本不匹配 / 共享段版本不匹配
   三处「请用配套 plugindev 重编」→ hmapdev（对应两条测试断言同步）
2. e2e_template_test 的模板路径改为 tools/hmapdev/templates，
   并保留旧路径回退（旧 SDK 检出仍能跑测试）
3. 注释与文档同步

文档更新（用户可见面）：
- assets/docs/{zh,en}/PLUGIN_DEV.md：工具链章节整体改为 hmapdev，
  补改名说明与 SDK 存储目录迁移；命令示例全部更新
- assets/docs/{zh,en}/ARCHITECTURE.md：**流程图与章节对齐 v1.2.0** ——
  · 向量化章节改为三层降级：统一多模态空间（主）→ 词嵌入 → TF-IDF（回退），
    写明「同指纹且同维度才参与融合」
  · 媒体记忆章节重写：媒体是一等记忆块（无独立 GC / 无引用计数 / 无描述式索引 /
    正文不再写 media marker），并写明 reembedStaleMedia 的跨空间迁移与写回
- README{,_EN}.md、docs/zh/plugin-interface-matrix.md：工具名与模板路径同步
  （历史条目标注「当时名为 plugindev」）

验证：go test ./internal/plugin/ ./internal/plugin/proc/ ok，
含 4 条真实模板 E2E（模板路径切换后仍通过）。
 2026-09-12 12:42:43 +08:00
JianFeeeee
3cb4686727 docs: 同步仓库文档到 v1.1.1，补媒体记忆与接口扩展规则 
五处文档此前停在 v1.0.0，而 v1.1.0/v1.1.1 都已发布并在现网运行。
本轮补齐三层记忆的媒体架构、模型工具的媒体参数、通信面 method 数，
以及冻结解除后的替代约束。

## 中英双语 OVERVIEW.md

三层记忆段只写了 Context/Document/Graph 三层，而 v1.1.0 起图片/音频是
三层里的一类节点。补上媒体记忆的架构概要：CAS + 引用计数 GC + 标记格式
（描述文本才是持久语义记忆，blob 是可淘汰的缓存）+ 插件边界贯通。

## 中英双语 ARCHITECTURE.md

- 「记忆工具」表补 `memory_commit`/`doc_commit` 的 `media_digests` 与
  `sentence_text`（后者从未暴露给模型，而它是媒体绑定链的必经环节）
- 「三层记忆」段新增媒体记忆子节：CAS 设计表（寻址/完整性/写入原子性/引用/GC）、
  标记格式、可选性（`enabled=false` 时整条链路静默退化）
- 「三个通信面」从 51 改为 55 个 method，新增四个 media method 的说明
- 「SDK 四通道」代码示例补媒体注入三方法 + 与 SetToolBlocks 的区别

## plugin-interface-matrix.md

- 状态从「完成 v2」改「完成 v3」，v3 记录 v1.1.1 的接口扩展
- §二 A3 DocMemoryAPI 补 InsertWithMedia
- §二 A4 补三个媒体注入方法 + 为何不能搭 SetToolBlocks 的车
- §二 A5 补 MediaAttachment 类型 + Triple/Doc/TextEvent 的扩展字段
- §六「新获得的能力」补 SetToolBlocks 已落地、媒体入记忆、插件主动发起
  带媒体的对话
- §七 冻结检查点补第 5 条（冻结已解除，取代它的是 §九）
- 新增 §九「v1.1.x 的接口扩展规则」：冻结解除后的三条硬约束
  （只增不减签名不改 / 新增方法方向 / 模板接线六处失败链）+ 验证方式
  （存量插件 17/17、旧产物 4/4 建链、模板断言、压测 -race）

## 为何分立两笔 commit

前一笔（SDK 仓 README + 内核 README）改的是给**插件开发者**看的文本，
本笔改的是给**架构师与维护者**看的技术文档。受众与改动层次不同，
放在同一个 commit 会让追溯时看不出"文档在哪一层跟上了代码"。
 2026-09-06 15:07:14 +08:00
JianFeeeee
d043fed5ce docs: 文档与发布脚本同步到 v1.0.0 子进程架构 
README/架构文档仍在描述 C ABI 动态库加载，与 v1.0.0 实际实现不符。
新用户按文档走会去做 -buildmode=c-shared，产物新内核根本不加载。

README.md / README_EN.md：
- 设计要点补子进程架构段（三面通信、崩溃自愈、真热重载）
- 代码结构 plugin/ 描述：.so 动态加载器 → 子进程加载器
- 项目状态补 v1.0.0 条目（6 类缺陷 + 实测数字），v0.9.0 标注 ABI 已退场
- 新增「下载」章节：三变体对照 + 各平台包格式 + macOS 限制

assets/docs/{zh,en}/ARCHITECTURE.md：
- 四种加载方式表：外部 .so/C ABI → 外部子进程/握手+stdio JSON-RPC
- 加载流程改写为 exec.Command → 继承 fd → 握手 → init → start
- 内置 vs 外部对照表 7 行更新
- 新增「子进程插件的三个通信面」小节，含每个面的选择理由

assets/docs/{zh,en}/OVERVIEW.md：插件系统段落改写

deploy/ 发布脚本三处回归（v0.7.2 的 7f08f3c 把 package/ 移到
deploy/packaging/ 使目录深度 1→2，但没改相对路径，此后两个版本
的发布都没有二进制资产）：
- build.sh：.syso 按目标平台 hide/restore（trap 兜底），恢复
  windows 目标的 CXX，arm64 刻意不带 CXX
- installer.nsi：5 处 ..\build → ..\..\build，PRODUCT_VERSION 可注入
  （原先硬编码 0.8.0）
- homeagent.spec：server 变体补装 waiter（control-server 声明了 CLI 却没装）

deploy/scripts/upload_assets.py：release 资产上传（两步签名 URL → OBS
PUT）。放 deploy/scripts/ 而非 scripts/，因为后者在 .gitignore 里。
支持 GITCODE_REPO/ASSET_DIR 环境变量以复用于 SDK 仓。
 2026-09-03 19:26:17 +08:00
JianFeeeee
74d30915ea docs: correct plugindev toolchain usage, Lua execution model, and stale plugin examples 
- 工具链：修正 bundle 默认开启（plugindev build 默认多平台合集）、补充 --no-bundle/debug/--target/--outdir/--sdk-path/--replace 用法、Lua 打包内容、安装端点语义
- 新增「执行模型」节：Lua 插件为被动回调模型，无常驻服务能力
- OVERVIEW/ARCHITECTURE：示例列表与 Lua 加载描述修正（internal/plugin gopher-lua，非 internal/lua VM；无热加载）
 2026-07-31 12:59:06 +08:00
JianFeeeee
53a00793d3 docs: 修复记忆分层引用错误 + 补充内置/外部插件说明 + 同步中英文文档 2026-07-28 21:56:53 +08:00
JianFeeeee
cb0f11c33d v0.7.3: 重构 Provider 层 + 计算层隔离 + Cleaner/NoMemory 架构 
- 删除 OpenAIProvider/OllamaProvider 死代码，LuaAdaptedProvider 独存
- DisableThinking 从 ExtraBody 移到 CompletionRequest 顶层字段
- ContextWindow 从 Provider 签名移到 BaseConfig/ModelContextWindow() 统管
- 确认 CleanText 仅做基本空白 trim，QQ 模板剥离归插件 Cleaner
- Cleaner/NoMemory 仅作用于向量计算和 jieba 分词层，原文不变
- context.ContextEvent/Doc.Content 始终保存原文
- 删除 nlp/download.go 死代码
- media.go: context.Background() -> a.ctx 级联
- clawhubadapter: HTTP 超时
- cut.go: 跨平台 mod cache 路径 (GOMODCACHE->GOPATH->HomeDir)
- bridge_e2e_test: 移除未用 runtime import
- lua 适配器: disable_thinking 传参
 2026-07-28 11:42:29 +08:00
JianFeeeee
7f08f3ca09 v0.7.2: 根目录清理 + Agent 心跳重构 + 内嵌 ONNX 模型 
- 根目录清理: branding/docs/knowledge -> assets/, package/tools/deploy -> deploy/
- meta.go: Version 0.7.2, SDKCompatibleVersion 语义改为最高兼容
- Makefile: 版本回退 0.7.2
- registry.go: 系统提示词改用 meta.Version 格式化
- Agent 心跳: reorgGraph 拆分为三个独立循环(archive/merge/review)，各自可配间隔
- GraphDB: 新增 sentences 表 + 关系句子溯源 + ClearSentenceID + CleanupOrphanedSentences
- Knowledge: 支持词嵌入向量化器
- NLP 四阶段流水线: Parse -> Extract -> Verify -> Fuse + SentenceRef
- 移除远程 HTTP 解析器(remote_parser.go)
- 新增内嵌 ONNX 模型(vocab + dep_parser.onnx):
  +build onnxruntime: 全量 ONNX Runtime 推理
  !build onnxruntime: 内嵌词表规则式降级解析器
- config: core.agent.onnx_model_path 替代 dep_parser_url
 2026-07-28 09:56:26 +08:00