jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-10-04 00:03:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: mascot before each section heading in tutorial docs

Browse Source
This commit is contained in:
jianf
2026-07-17 21:44:15 +08:00
parent 706700ba8e
commit 0164e1cc12
8 changed files with 108 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/en/ADAPTER.md
View File

@ -1,11 +1,11 @@
**中文** | [English](../zh/ADAPTER.md)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# Lua Adapter — LLM Source Adaptation Guide
Each LLM API source corresponds to a Lua script, responsible for request transformation (Go unified format → API format) and response transformation (API format → Go unified format).
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Adapter Contract
The Lua script must return a table containing the following fields and functions:
@ -45,6 +45,8 @@ end
return adapter
```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Unified CompletionRequest Format (Go → Adapter)
```json
@ -63,6 +65,8 @@ return adapter
}
```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Unified CompletionResponse Format (Adapter → Go)
```json
@ -76,6 +80,8 @@ return adapter
}
```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Lua VM Built-in Functions
`json.encode(table)` — Encode Lua table to JSON string
@ -88,6 +94,8 @@ return adapter
`http_post(url, body)` — Perform HTTP POST request, returns response body as string
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Adapting Typical APIs
| API | endpoint | auth method | Format differences |
@ -101,6 +109,8 @@ return adapter
| **GitHub Models** | `/chat/completions` | `Authorization: Bearer <pat>` | OpenAI compatible |
| **Ollama** | `/api/chat` | None | Different options format |
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Steps to Add a New Source
1. Create `<name>.lua` under `internal/lua/adapters/`

24
docs/en/ARCHITECTURE.md
View File

@ -1,11 +1,11 @@
**中文** | [English](../zh/ARCHITECTURE.md)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent Architecture
The kernel performs zero IO; all external interaction comes from plugins.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Message Processing Flow
### Full Pipeline
@ -66,6 +66,8 @@ Exit conditions: LLM has no tool calls / all rejected / exceeded limit.
Setting `ctx.Response` at any stage jumps to `after_output`.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Three-Layer Memory
### Memory Flow
@ -203,6 +205,8 @@ Heartbeat 30min:
Entity conflict detection heuristic (bigram Jaccard > 0.75), routed through `selfInputCh` internal channel, LLM makes the final merge decision.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Knowledge Base
`internal/knowledge/knowledge.go`
@ -210,6 +214,8 @@ Entity conflict detection heuristic (bigram Jaccard > 0.75), routed through `sel
- Independent TF-IDF index, separate from memory system
- `knowledge_search` / `knowledge_create` / `knowledge_list`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Provider & Lua Adapter Layer
```
@ -234,6 +240,8 @@ ProviderManager manages multiple sources, fallback in registration order. Lua ad
VM built-ins: `json.encode` / `json.decode` / `log` / `http_get` / `http_post`.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Plugin System
### Three Loading Methods
@ -284,6 +292,8 @@ type Plugin interface {
}
```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Output Channel System
Each output channel generates two tools:
@ -306,6 +316,8 @@ Capability flags:
System prompt injection: output gate rules, multi-call support, long message splitting.
Child agent permission: `output_send__` prefix tools are allowed.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## EventAgentLLMChain Event
- Event type `agent_llm_chain` emitted after each LLM turn
@ -313,6 +325,8 @@ Child agent permission: `output_send__` prefix tools are allowed.
- WebUI subscribes to this event via SSE for real-time display
- Plugins can subscribe via EventSubscriber (read-only for external plugins)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Restricted External Plugin API
Layered architecture: internal plugins get full PluginSDK, external plugins get restricted SDK.
@ -326,6 +340,8 @@ Extended fields:
- Triple extensions: Confidence, SubjectType, ObjectType
- Relation extension: Confidence
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Interrupt Mechanism
```
@ -346,6 +362,8 @@ Three delivery paths:
Code: `internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Configuration System
`internal/config/registry.go` — ConfigRegistry
@ -355,6 +373,8 @@ Code: `internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt`
- `RegisterDefault` inserts ~80 default keys (seeds for 8 LLM sources)
- WebUI settings page `/api/v1/settings` for read/write
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Code Structure
```

8
docs/en/OVERVIEW.md
View File

@ -1,9 +1,9 @@
**中文** | [English](../zh/OVERVIEW.md)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent — Project Overview
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## What Is This
HomeAgent is a continuously-running personal intelligent Agent framework.
@ -27,6 +27,8 @@ The significance: the kernel stays pure (zero IO, only orchestration and memory)
Three progressive layers: context → cold archive → long-term graph memory, ensuring the agent doesn't degrade over time.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## What It Actually Does
Code is in the project root, implemented in Go.
@ -67,6 +69,8 @@ Code is in the project root, implemented in Go.
- OpenAI API-compatible `/v1/chat/completions` endpoint
- SSE event stream `/api/v1/chat/events`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Project Status
Core functionality is operational. Plugin system and SDK are ready for independent external plugin development.

16
docs/en/PLUGIN_DEV.md
View File

@ -1,9 +1,9 @@
**中文** | [English](../zh/PLUGIN_DEV.md)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent Plugin Development Guide
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Overview
All external interaction capabilities of HomeAgent comes from plugins. Plugins interact with the kernel through `PluginSDK` (Go API).
@ -35,6 +35,8 @@ type Plugin interface {
---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 1. Quick Start: Using the plugindev Toolchain
`plugindev` is the unified plugin development toolchain provided in the SDK repository, supporting both Go and Lua plugin types.
@ -134,6 +136,8 @@ Or upload via WebUI plugin management page.
---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 2. Go Plugin Development in Detail
### Plugin Interface
@ -346,6 +350,8 @@ channels := s.ListChannels()
---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 3. Lua Plugin Development in Detail
Lua plugins are suitable for lightweight rapid prototyping, requiring no Go compilation environment. Changes take effect after kernel restart.
@ -416,6 +422,8 @@ When running inside the kernel, `sdk.*` global variables are injected by the Go
---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 4. Built-in Plugins
Built-in plugins use `init()` self-registration, compiled into the kernel, no separate deployment needed.
@ -479,6 +487,8 @@ import (
---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 5. Best Practices
1. `Start()` is non-blocking — start long tasks in goroutines, don't block Start
@ -491,6 +501,8 @@ import (
---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 6. Example Plugin Reference
### SDK Repository Examples (`homeagent-sdk/example/`)