mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-24 10:58:13 +00:00
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
This commit is contained in:
root
@ -82,6 +82,10 @@ return adapter
|
||||
|
||||
`log(level, message)` — Output log (level: info/warn/error)
|
||||
|
||||
`http_get(url)` — Perform HTTP GET request, returns response body as string
|
||||
|
||||
`http_post(url, body)` — Perform HTTP POST request, returns response body as string
|
||||
|
||||
## Adapting Typical APIs
|
||||
|
||||
| API | endpoint | auth method | Format differences |
|
||||
|
||||
@ -123,8 +123,8 @@ TF-IDF is the core algorithm running through all three memory layers, used in 4
|
||||
|
||||
| Location | File | Purpose | Algorithm |
|
||||
|----------|------|---------|-----------|
|
||||
| Context Prune | `context.go:162` | Trim low-relevance context events | CosineSimilarity(queryVec, evt.Vector) |
|
||||
| DocStore Query | `document.go:205` | Recall related content from document memory | InvertedIndex + CosineSimilarity |
|
||||
| Context Prune | `context.go:161` | Trim low-relevance context events | CosineSimilarity(queryVec, evt.Vector) |
|
||||
| DocStore Query | `document.go:198` | Recall related content from document memory | InvertedIndex + CosineSimilarity |
|
||||
| Indexer Entity Search | `indexer.go:149` | Recall related entities from Graph | InvertedIndex + CosineSimilarity |
|
||||
| Entity Similarity Detection | `agent.go:2297` | Detect similar entities in Graph | Bigram Jaccard (>0.75 → consolidation) |
|
||||
|
||||
@ -136,7 +136,7 @@ TF-IDF is the core algorithm running through all three memory layers, used in 4
|
||||
|
||||
### Document Layer
|
||||
|
||||
`internal/memory/document/doc.go` — `Store`
|
||||
`internal/memory/document/document.go` — `Store`
|
||||
- Consume-on-read mode: deleted after `doc_query` retrieval
|
||||
- TF-IDF index with character bigram + inverted index
|
||||
|
||||
@ -185,7 +185,7 @@ Heartbeat 30min:
|
||||
selfInputCh → LLM decides merge/skip
|
||||
```
|
||||
|
||||
Entity conflict detection heuristic (bigram Jaccard > 0.5), routed through `selfInputCh` internal channel, LLM makes the final merge decision.
|
||||
Entity conflict detection heuristic (bigram Jaccard > 0.75), routed through `selfInputCh` internal channel, LLM makes the final merge decision.
|
||||
|
||||
## Knowledge Base
|
||||
|
||||
@ -366,7 +366,7 @@ internal/
|
||||
│ ├── agentcli/ — PTY terminal
|
||||
│ ├── healthcheck/ — Health check
|
||||
│ └── pluginmgr/ — Plugin manager
|
||||
├── internal/sdk/ — PluginSDK definitions
|
||||
├── sdk/ — PluginSDK definitions
|
||||
│ ├── plugin.go — Plugin interface + PluginSDK
|
||||
│ ├── memory.go — MemoryAPI
|
||||
│ ├── knowledge.go — KnowledgeAPI
|
||||
@ -376,7 +376,7 @@ internal/
|
||||
│ ├── graph.go — SQLite graph database
|
||||
│ ├── indexer.go — Graph → vector index
|
||||
│ ├── vector/store.go — TF-IDF vector engine
|
||||
│ ├── document/doc.go — Document memory
|
||||
│ ├── document/document.go — Document memory
|
||||
│ ├── text/text.go — Text logs
|
||||
│ └── pipeline/ — Distiller
|
||||
├── knowledge/knowledge.go — Knowledge base
|
||||
@ -387,6 +387,8 @@ internal/
|
||||
├── events/bus.go — Event bus
|
||||
├── tracker/ — OverlayFS change tracking
|
||||
├── supervisor/ — Daemon management
|
||||
├── snapshot/ — Snapshots
|
||||
└── tokenizer/ — Chinese tokenization (jieba wrapper)
|
||||
├── skill/ — Skill plugin management
|
||||
│ └── manager.go — Skill loading/matching
|
||||
└── meta/ — Meta information
|
||||
└── meta.go — Agent metadata
|
||||
```
|
||||
|
||||
@ -37,7 +37,7 @@ Code is in the project root, implemented in Go.
|
||||
|
||||
**Memory System** (`internal/memory/`):
|
||||
- **GraphDB** (`graph.go`) — SQLite, entities + relations tables, BFS traversal
|
||||
- **Document Store** (`document/doc.go`) — Temporary memory, JSON files + TF-IDF vector index, consume-on-read
|
||||
- **Document Store** (`document/document.go`) — Temporary memory, JSON files + TF-IDF vector index, consume-on-read
|
||||
- **Text Memory** (`text/text.go`) — Raw conversation logs, JSONL file rotation
|
||||
- **Social Store** (`social/social.go`) — Persona traits + relationship network, wraps GraphDB
|
||||
- **Memory Indexer** (`indexer.go`) — Auto-vectorizes GraphDB entities, recalls and injects into system prompt on user input
|
||||
@ -50,7 +50,7 @@ Code is in the project root, implemented in Go.
|
||||
**Plugin System** (`internal/plugin/`):
|
||||
- Built-in plugins: Go `init()` self-registration, compiled into kernel
|
||||
- External plugins: Go `-buildmode=plugin` compiled to `.so`/`.dll`, dynamically loaded via `plugin.Open`; also supports Lua script plugins
|
||||
- PluginSDK (`internal/sdk/`) defines three channels: RegisterTool / RegisterStage / Subscribe
|
||||
- PluginSDK (`internal/sdk/`) defines four channels: RegisterTool / RegisterStage / Subscribe / RegisterOutputChannel
|
||||
- 7 stage hooks: on_input → pre_action → post_action → before_toolcall → after_toolcall → before_output → after_output
|
||||
|
||||
**LLM Provider** (`internal/agent/api/provider.go`):
|
||||
|
||||
@ -265,10 +265,10 @@ s.Settings().GetPlugin("other_plugin", "some_key")
|
||||
|
||||
```go
|
||||
// Queued delivery (processed in order)
|
||||
s.InjectInput(source, channel string, payload map[string]interface{})
|
||||
s.InjectInput(source, channel, eventType string, payload map[string]interface{})
|
||||
|
||||
// Interrupt delivery (can interrupt current LLM processing)
|
||||
s.InjectInterrupt(source, channel string, payload map[string]interface{})
|
||||
s.InjectInterrupt(source, channel, eventType string, payload map[string]interface{})
|
||||
|
||||
// Shortcuts
|
||||
s.InjectText(source, channel, text string)
|
||||
@ -318,7 +318,15 @@ s.Publish(&events.Event{
|
||||
#### IO Channel Management (built-in plugins)
|
||||
|
||||
```go
|
||||
// Register a channel (bind device driver)
|
||||
// Register a channel (bind device driver), dev must implement the agentIO.Device interface:
|
||||
// Name() string
|
||||
// Type() DeviceType
|
||||
// Description() string
|
||||
// Tools() []ToolDef
|
||||
// Execute(tool string, args map[string]interface{}) (interface{}, error)
|
||||
// Start() error
|
||||
// Stop() error
|
||||
// OutputCapabilities() OutputCapability
|
||||
s.RegisterChannel("mydevice", deviceImpl)
|
||||
|
||||
// Unregister a channel
|
||||
|
||||
@ -82,6 +82,10 @@ return adapter
|
||||
|
||||
`log(level, message)` — 输出日志（level: info/warn/error）
|
||||
|
||||
`http_get(url)` — 发起 HTTP GET 请求，返回响应体字符串
|
||||
|
||||
`http_post(url, body)` — 发起 HTTP POST 请求，返回响应体字符串
|
||||
|
||||
## 适配典型 API
|
||||
|
||||
| API | endpoint | auth 方式 | 格式差异 |
|
||||
|
||||
@ -123,8 +123,8 @@ TF-IDF 是贯穿三层记忆的核心算法，在 4 个独立位置以不同方
|
||||
|
||||
| 位置 | 文件 | 用途 | 算法 |
|
||||
|------|------|------|------|
|
||||
| Context Prune | `context.go:162` | 裁剪低相关性上下文事件 | CosineSimilarity(queryVec, evt.Vector) |
|
||||
| DocStore Query | `document.go:205` | 从文档记忆召回相关内容 | InvertedIndex + CosineSimilarity |
|
||||
| Context Prune | `context.go:161` | 裁剪低相关性上下文事件 | CosineSimilarity(queryVec, evt.Vector) |
|
||||
| DocStore Query | `document.go:198` | 从文档记忆召回相关内容 | InvertedIndex + CosineSimilarity |
|
||||
| Indexer 实体搜索 | `indexer.go:149` | 从Graph召回相关实体 | InvertedIndex + CosineSimilarity |
|
||||
| 实体相似度检测 | `agent.go:2297` | 检测Graph中相似实体 | Bigram Jaccard (>0.75 → consolidation) |
|
||||
|
||||
@ -136,7 +136,7 @@ TF-IDF 是贯穿三层记忆的核心算法，在 4 个独立位置以不同方
|
||||
|
||||
### Document 层
|
||||
|
||||
`internal/memory/document/doc.go` — `Store`
|
||||
`internal/memory/document/document.go` — `Store`
|
||||
- 消费即删模式：`doc_query` 检索到后删除
|
||||
- TF-IDF 索引 character bigram + 倒排
|
||||
|
||||
@ -185,7 +185,7 @@ TF-IDF 是贯穿三层记忆的核心算法，在 4 个独立位置以不同方
|
||||
selfInputCh → LLM 判断合并/跳过
|
||||
```
|
||||
|
||||
实体冲突检测启发式（bigram Jaccard > 0.5），走 `selfInputCh` 内部通道，LLM 最终判断是否合并。
|
||||
实体冲突检测启发式（bigram Jaccard > 0.75），走 `selfInputCh` 内部通道，LLM 最终判断是否合并。
|
||||
|
||||
## 知识库
|
||||
|
||||
@ -366,7 +366,7 @@ internal/
|
||||
│ ├── agentcli/ — PTY 终端
|
||||
│ ├── healthcheck/ — 健康检查
|
||||
│ └── pluginmgr/ — 插件管理器
|
||||
├── internal/sdk/ — PluginSDK 定义
|
||||
├── sdk/ — PluginSDK 定义
|
||||
│ ├── plugin.go — Plugin 接口 + PluginSDK
|
||||
│ ├── memory.go — MemoryAPI
|
||||
│ ├── knowledge.go — KnowledgeAPI
|
||||
@ -376,7 +376,7 @@ internal/
|
||||
│ ├── graph.go — SQLite 图数据库
|
||||
│ ├── indexer.go — 图→向量索引
|
||||
│ ├── vector/store.go — TF-IDF 向量引擎
|
||||
│ ├── document/doc.go — 文档记忆
|
||||
│ ├── document/document.go — 文档记忆
|
||||
│ ├── text/text.go — 文本日志
|
||||
│ └── pipeline/ — 蒸馏器
|
||||
├── knowledge/knowledge.go — 知识库
|
||||
@ -387,6 +387,8 @@ internal/
|
||||
├── events/bus.go — 事件总线
|
||||
├── tracker/ — OverlayFS 变更追踪
|
||||
├── supervisor/ — 守护进程管理
|
||||
├── snapshot/ — 快照
|
||||
└── tokenizer/ — 中文分词 (jieba 包装)
|
||||
├── skill/ — Skill 插件管理
|
||||
│ └── manager.go — Skill 加载/匹配
|
||||
└── meta/ — 元信息
|
||||
└── meta.go — Agent 元数据
|
||||
```
|
||||
|
||||
@ -37,7 +37,7 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
|
||||
|
||||
**记忆系统** (`internal/memory/`)：
|
||||
- **GraphDB** (`graph.go`) — SQLite，entities + relations 表，BFS 遍历
|
||||
- **Document Store** (`document/doc.go`) — 临时记忆，JSON 文件 + TF-IDF 向量索引，消费即删
|
||||
- **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
|
||||
@ -50,7 +50,7 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
|
||||
**插件系统** (`internal/plugin/`)：
|
||||
- 内置插件：Go `init()` 自注册，编译进内核
|
||||
- 外部插件：Go `-buildmode=plugin` 编译为 `.so`/`.dll`，通过 `plugin.Open` 动态加载；也支持 Lua 脚本插件
|
||||
- PluginSDK (`internal/sdk/`) 定义三通道：RegisterTool / RegisterStage / Subscribe
|
||||
- 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`)：
|
||||
|
||||
@ -266,10 +266,10 @@ s.Settings().GetPlugin("other_plugin", "some_key")
|
||||
|
||||
```go
|
||||
// 排队投递（按序处理）
|
||||
s.InjectInput(source, channel string, payload map[string]interface{})
|
||||
s.InjectInput(source, channel, eventType string, payload map[string]interface{})
|
||||
|
||||
// 中断投递（可打断当前 LLM 处理）
|
||||
s.InjectInterrupt(source, channel string, payload map[string]interface{})
|
||||
s.InjectInterrupt(source, channel, eventType string, payload map[string]interface{})
|
||||
|
||||
// 快捷方式
|
||||
s.InjectText(source, channel, text string)
|
||||
@ -319,7 +319,15 @@ s.Publish(&events.Event{
|
||||
#### IO 通道管理（内置插件）
|
||||
|
||||
```go
|
||||
// 注册通道（绑定设备驱动）
|
||||
// 注册通道（绑定设备驱动），dev 必须实现 agentIO.Device 接口：
|
||||
// Name() string
|
||||
// Type() DeviceType
|
||||
// Description() string
|
||||
// Tools() []ToolDef
|
||||
// Execute(tool string, args map[string]interface{}) (interface{}, error)
|
||||
// Start() error
|
||||
// Stop() error
|
||||
// OutputCapabilities() OutputCapability
|
||||
s.RegisterChannel("mydevice", deviceImpl)
|
||||
|
||||
// 注销通道
|
||||
|
||||
Reference in New Issue
Block a user