jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-05 16:57:32 +00:00
Code Issues Packages Projects Releases Wiki Activity
1,092 Commits 5 Branches 29 Tags
bb29096f605afe7b7889ea97aa2b91f2f474c9ec
Commit Graph

23 Commits

Author SHA1 Message Date
JianFeeeee
06f3161e1d docs(en): 建立英文文档目录 —— 索引 + 教训全文 + 设计摘要 
## 问题

仓库是公开的，README / README_EN 已经双语，但 `docs/` 只有 `docs/zh/`：
英文读者读完首页就撞墙。

## 做法：摘要而非全译，并写明为什么

`docs/zh/` 有 27 份文档、约 7000 行设计。**全译会烂得比审得还快**，
而一份陈旧的译文比没有更糟 —— 读者不知道它落后于原文多少。

所以按"内容变化速度"分级：

| 类型 | 译法 | 理由 |
| --- | --- | --- |
| 教训 | ✅ 全文 | 复用价值最高，失败形态会反复出现 |
| 索引 | ✅ 全文 | 没有它其余都不可发现 |
| 设计文档 | ⚠️ 一页摘要 + 状态行 | 7000 行全译跟不上演进 |
| 历史快照/证据 | ❌ 不译 | 时点产物，翻译无增益 |
| 未实施计划 | ❌ 不译 | 会变；且按 §4.3 本就不该进仓 |

判据写在 `docs/en/README.md` 里：

> 如果一份文档的内容变化速度快过译文能被审阅的速度，就译它的**摘要**而不是正文。

## 三份文件

**docs/en/README.md** —— 索引。含分类表（哪些已译、哪些只有中文摘要、
哪些不译）、状态行约定、以及"本索引必须在同一提交里更新"这条硬规则
（滞后的索引比没有索引更糟：它教读者信任错的地图）。

**docs/en/engineering-lessons.md** —— §1（判据会骗人）+ §5（判据形态）
全文翻译，§2–§4 摘要。§5 是本轮新增的核心内容：

    5.1    判据必须把被测模块当黑箱（含三个正当例外）
    5.2    禁止读源码做断言（附"想保证什么 → 错误做法 → 正确做法"表）
    5.2.1  判据不得以文档为依据
    5.3    测试与业务代码分离
    5.3.1  三种测试位置的实测边界
    5.3.2  覆盖率必须用 -coverpkg=./...
    5.4    CI 必须覆盖每个独立 module
    5.5    CI 与本地必须跑同一套门

每个小节都带实测数据与变异验证结果，不是原则罗列。

**docs/en/design-summaries.md** —— 6 份核心设计的一页摘要：

    kernel-modularization   6 层 20 模块；依赖图在构建期算好并嵌进二进制；
                            depgraph.bin 必须与二进制同目录，放数据目录会崩溃循环
    secret-firewall         security 是外围到核心之间的防火墙，自持数据结构、
                            只接受事实不接受策略；出入向都要洗
    input-scheduler         L1–L4 + 现场保存；工具执行是临界区不可抢占
    resident-subagent       与 rtchild 语义相反；单数/复数共用 Cleanup
    toolcall-contract       assistant(tool_calls) 后必须紧跟每个 id 的 tool
                            消息；批内不得插入任何东西
    context-overflow-l4     下沉到冷上下文而非截断；InactivePages 是本次渲染
                            的临时标记（json:"-"）

另有 13 份（插件相关 / 数据报告型）列为 "Chinese only" 并说明理由。

## 中文索引加了英文入口

`docs/zh/README.md` 顶部增加指向 `../en/README.md` 的一行，并明确：

> 本目录是**中文原文，也是唯一权威**；英文侧只做摘要，与本文冲突时以本文为准。

这一条很重要 —— 否则两份文档会逐渐分叉，而读者不知道该信哪个。

## 验证

    go build ./...        PASS
    go vet ./...          PASS
    gofmt -l              干净
    go test ./...         65 包全过，0 FAIL
 2026-11-04 20:05:10 +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
JianFeeeee
7df8be0128 feat: NoMemory/Cleaner memory system + doc update 
- _sdk_local/ removed (moved to standalone sdk repo)
- internal/agent/core: NoMemory/Cleaner data-flow breakpoints
- internal/memory: clean_text, document store refactor
- internal/plugin/registry.go: plugin API alignment
- docs: PLUGIN_DEV.md, ARCHITECTURE.md NoMemory/Cleaner docs
- plan.md, review.md: status update
 2026-07-25 11:17:31 +08:00
JianFeeeee
42570ebbf5 docs: revise architecture docs for academic rigor and source-code accuracy 
- Rewrite 体系结构原则/Architectural Principles section with precise
  implementation details from source code (3-way eventLoop select,
  StageHost parallelism, provider ordered fallback, recency bias)
- Document shared StaticEmbedder vector space between Context and Document
- Remove marketing tone, OS analogy table, and mascot emoji separators
- Remove contrastive sentence patterns (而非/not...but/rather than)
- Align terminology with actual implementation across all 6 doc files
 2026-07-24 12:12:37 +08:00
JianFeeeee
dc360405f8 docs: update file references after agent.go split (process.go, eventloop.go, distill.go) 2026-07-22 17:34:35 +08:00
JianFeeeee
613d4a62a3 refactor: split agent.go into 12 files + add mcp_restart_server tool 2026-07-22 15:40:27 +08:00
JianFeeeee
770c2c9edb docs: sync PLUGIN_DEV.md with SDK toolchain updates 
- Fix project structure: remove main.go, add auto-generated bridge files note
- Clarify plg.json (targets) vs plugin.json (entry/platforms) distinction
- Add --bundle multi-platform build section
- Add plugindev sdk version management subcommands
- Update entry point section: NewPlugin is in plugin.go, no separate main.go
- Sync zh and en versions
 2026-07-19 12:32:56 +08:00
JianFeeeee
ab465f64c6 feat: multi-platform .hmap bundle + platform auto-selection 
- PluginManifest: add platforms field declaring supported OS
- validatePackage: accept bundle .hmap with platform-aware binary check
- extractPackage: extract only current OS binary, skip others (macOS renames .dylib → .so)
- installFromPath/installFromURL: path install keeps source, URL install auto-cleanup
- cabi/loader.go + dynamic.go: add linux/darwin build constraints for Windows cross-compile
- dynamic_loader_unix/windows: split SO loading with proper build tags
- package/build.sh: enable windows/amd64 for homed, add CXX export for arm64
- tryLoadSO: fallback to plugin.dylib on macOS
- docs: update PLUGIN_DEV.md for bundle format and install methods
 2026-07-19 12:01:35 +08:00
JianFeeeee
54e0ab7045 docs: update output channel interface (payload/meta/type) in architecture docs 2026-07-19 10:35:25 +08:00
JianFeeeee
aeff84a266 docs: restore bili entry, update browser to web+webfetch merge only 2026-07-18 21:11:18 +08:00
JianFeeeee
23c9d6fe6e docs: replace web/webfetch/bili with merged browser plugin in example tables 2026-07-18 21:06:56 +08:00
JianFeeeee
bcea1f5822 docs: 恢复内置插件中断投递 API 文档 
PLUGIN_DEV.md 第二节保留公开 API (InjectText/InjectInterruptText/InjectTextNoMemory)，
第四节新增"输入投递（内置插件）"小节展示 InjectInput/InjectInterrupt/InjectInputSync 等
内置插件专属方法，附注说明区分外部与内置插件 API 边界。
 2026-07-18 20:48:54 +08:00
JianFeeeee
710039554b docs: 修正全部文档使其与源码实现一致 
主仓库：
- 修复 4 份英文文档语言切换链接指向错误 (../zh/ → ../en/)
- ARCHITECTURE.md 标题 "三种加载方式" → "四种加载方式" (实际表格4行)
- PLUGIN_DEV.md 示例表: 添加 webfetch, 移除不存在的 luaplugintest/testlua
- PLUGIN_DEV.md 代码示例: InjectInput/InjectInterrupt → InjectText/InjectInterruptText
- PLUGIN_DEV.md 代码示例: Memory/Knowledge/LLM/Events 接口签名修正
- PLUGIN_DEV.md .hmap 内容统一, plugindev 编译去除 .exe 后缀

SDK 仓库:
- Plugin.Start(sdk *PluginSDK) 接口签名改为指针
- 方法表重写: 移除 CallLLM/QueryKnowledge/SetMemory 等不存在方法
- IOInjector 参数顺序修正为 (source, channel, text)
- 删除虚构 SDKConfig, 替换为实际 New() 构造函数签名
- .hmap 内容描述一致化

修正前一次会话中的 QQ/Bili 插件问题:
- qq napcat() 超时, fetchBotInfo 竞态, handleWebhook 同步阻塞
- bili CDN 直连失败, 添加 HTTP_PROXY 代理
 2026-07-18 20:46:58 +08:00
JianFeeeee
161f40d1e8 docs: update sequence diagram, memory flow, vectorization strategy for StaticEmbedder + CleanTemplateText + three-branch vector 2026-07-17 21:51:03 +08:00
JianFeeeee
67353ec7f7 docs: mascot before each section heading in tutorial docs 2026-07-17 21:44:15 +08:00
JianFeeeee
66b86f6369 feat: mascot integration - WebUI/GUI icons, chat avatar, system prompt, docs 2026-07-17 21:41:03 +08:00
JianFeeeee
0505d41897 RegisterStage: add scope parameter, remove RegisterStageOwnTools 
- SDK: RegisterStage(stage, handler, scope...) with StageScopeGlobal/StageScopeOwnTools
- Delete RegisterStageOwnTools, migrate cmd and qq plugins
- Internal SDK: add StageScope alias
- Docs: update all zh/en docs for C ABI buildmode and stage scope
- C ABI: fix nil errorOut in Handle.Start/Handle.Stop (SIGSEGV fix)
- C ABI header: add dispatch IDs 26-45 for Settings/Doc/Knowledge/LLM/Social/TextMemory
 2026-07-17 11:25:54 +08:00
JianFeeeee
8a6e283db7 docs: graph memory uses jieba keyword extraction via ExtractKeywords 
- Indexer uses dual recall: char-bigram TF-IDF vector search + jieba keywords
- Document layer: char-bigram TF-IDF + jieba keyword extraction
- Memory Indexer description: add jieba keyword extraction
 2026-07-17 07:04:05 +08:00
JianFeeeee
980ded9e48 docs: update vectorization algorithm - LocalWordEmbedder (jieba + TF-IDF + PMI co-occurrence) 
Context layer uses LocalWordEmbedder not plain TF-IDF:
- jieba segmentation, TF-IDF weights, sliding window PMI co-occurrence
- Document/Indexer layers still use char-bigram TF-IDF (TFIDFVectorizer)
- Add 'protect last 10 events' detail to Context pruning description
 2026-07-17 07:02:53 +08:00
JianFeeeee
75f9c60aaa docs: fix documentation-source mismatches across all doc files 
- Go version: 1.19+/1.21+ → 1.25+ (matches go.mod)
- document/doc.go → document/document.go (actual filename)
- PluginSDK: 3 channels → 4 channels (add RegisterOutputChannel)
- InjectInput/InjectInterrupt: 3 params → 4 params (add eventType)
- RegisterChannel: document agentIO.Device interface requirement
- Architecture: remove non-existent snapshot/tokenizer dirs, add skill/meta
- Architecture: fix double internal/internal/sdk, fix Jaccard threshold
- Adapter: add http_get/http_post Lua VM built-ins
- Knowledge: 4-layer → 3-layer memory, CGO for go-sqlite3 not overlayfs
- Code structure tree: fix sdk/ and lua/adapters/ path consistency
 2026-07-16 23:17:55 +08:00
JianFeeeee
75499b1562 docs: update for v0.7.1 - output channels, restricted API, LLM chain event 2026-07-16 18:54:20 +08:00
JianFeeeee
88d837e722 refactor: move webui.listen_addr from core.daemon to webui category 2026-07-14 11:22:46 +08:00
JianFeeeee
73486de5e3 feat: 实现多语言文档架构 
- 创建 docs/zh/ 和 docs/en/ 目录结构
- 迁移文档至多语言目录，添加中英文切换链接
- 创建 README_EN.md 英文版本
- 更新 README.md 添加语言切换链接
- 删除旧文档和临时文件
 2026-07-13 23:29:35 +08:00