diff --git a/docs/en/ADAPTER.md b/docs/en/ADAPTER.md index e34fbdb..7b172ce 100644 --- a/docs/en/ADAPTER.md +++ b/docs/en/ADAPTER.md @@ -1,11 +1,11 @@ **中文** | [English](../zh/ADAPTER.md) - : - # 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). + : + ## Adapter Contract The Lua script must return a table containing the following fields and functions: @@ -45,6 +45,8 @@ end return adapter ``` + : + ## Unified CompletionRequest Format (Go → Adapter) ```json @@ -63,6 +65,8 @@ return adapter } ``` + : + ## Unified CompletionResponse Format (Adapter → Go) ```json @@ -76,6 +80,8 @@ return adapter } ``` + : + ## 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 + : + ## Adapting Typical APIs | API | endpoint | auth method | Format differences | @@ -101,6 +109,8 @@ return adapter | **GitHub Models** | `/chat/completions` | `Authorization: Bearer ` | OpenAI compatible | | **Ollama** | `/api/chat` | None | Different options format | + : + ## Steps to Add a New Source 1. Create `.lua` under `internal/lua/adapters/` diff --git a/docs/en/ARCHITECTURE.md b/docs/en/ARCHITECTURE.md index e9562fb..1fd13b4 100644 --- a/docs/en/ARCHITECTURE.md +++ b/docs/en/ARCHITECTURE.md @@ -1,11 +1,11 @@ **中文** | [English](../zh/ARCHITECTURE.md) - : - # HomeAgent Architecture The kernel performs zero IO; all external interaction comes from plugins. + : + ## 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`. + : + ## 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. + : + ## 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` + : + ## 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`. + : + ## Plugin System ### Three Loading Methods @@ -284,6 +292,8 @@ type Plugin interface { } ``` + : + ## 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. + : + ## 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) + : + ## 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 + : + ## Interrupt Mechanism ``` @@ -346,6 +362,8 @@ Three delivery paths: Code: `internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt` + : + ## 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 + : + ## Code Structure ``` diff --git a/docs/en/OVERVIEW.md b/docs/en/OVERVIEW.md index 1cb4c9c..650b4d9 100644 --- a/docs/en/OVERVIEW.md +++ b/docs/en/OVERVIEW.md @@ -1,9 +1,9 @@ **中文** | [English](../zh/OVERVIEW.md) - : - # HomeAgent — Project Overview + : + ## 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. + : + ## 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` + : + ## Project Status Core functionality is operational. Plugin system and SDK are ready for independent external plugin development. diff --git a/docs/en/PLUGIN_DEV.md b/docs/en/PLUGIN_DEV.md index cf1cc80..4db25d1 100644 --- a/docs/en/PLUGIN_DEV.md +++ b/docs/en/PLUGIN_DEV.md @@ -1,9 +1,9 @@ **中文** | [English](../zh/PLUGIN_DEV.md) - : - # HomeAgent Plugin Development Guide + : + ## 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 { --- + : + ## 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. --- + : + ## 2. Go Plugin Development in Detail ### Plugin Interface @@ -346,6 +350,8 @@ channels := s.ListChannels() --- + : + ## 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 --- + : + ## 4. Built-in Plugins Built-in plugins use `init()` self-registration, compiled into the kernel, no separate deployment needed. @@ -479,6 +487,8 @@ import ( --- + : + ## 5. Best Practices 1. `Start()` is non-blocking — start long tasks in goroutines, don't block Start @@ -491,6 +501,8 @@ import ( --- + : + ## 6. Example Plugin Reference ### SDK Repository Examples (`homeagent-sdk/example/`) diff --git a/docs/zh/ADAPTER.md b/docs/zh/ADAPTER.md index cc563ca..c81368f 100644 --- a/docs/zh/ADAPTER.md +++ b/docs/zh/ADAPTER.md @@ -1,11 +1,11 @@ [English](../en/ADAPTER.md) | **中文** - : - # Lua Adapter — LLM 源适配指南 每个 LLM API 源对应一个 Lua 脚本，负责请求转换（Go 统一格式 → API 格式）和响应转换（API 格式 → Go 统一格式）。 + : + ## 适配器契约 Lua 脚本必须返回一个包含以下字段和函数的 table： @@ -45,6 +45,8 @@ end return adapter ``` + : + ## 统一 CompletionRequest 格式（Go → Adapter） ```json @@ -63,6 +65,8 @@ return adapter } ``` + : + ## 统一 CompletionResponse 格式（Adapter → Go） ```json @@ -76,6 +80,8 @@ return adapter } ``` + : + ## Lua VM 内置函数 `json.encode(table)` — 将 Lua table 编码为 JSON 字符串 @@ -88,6 +94,8 @@ return adapter `http_post(url, body)` — 发起 HTTP POST 请求，返回响应体字符串 + : + ## 适配典型 API | API | endpoint | auth 方式 | 格式差异 | @@ -101,6 +109,8 @@ return adapter | **GitHub Models** | `/chat/completions` | `Authorization: Bearer ` | OpenAI 兼容 | | **Ollama** | `/api/chat` | 无 | 不同的 options 格式 | + : + ## 添加新源步骤 1. 在 `internal/lua/adapters/` 下创建 `.lua` diff --git a/docs/zh/ARCHITECTURE.md b/docs/zh/ARCHITECTURE.md index 604c017..6df707b 100644 --- a/docs/zh/ARCHITECTURE.md +++ b/docs/zh/ARCHITECTURE.md @@ -1,11 +1,11 @@ [English](../en/ARCHITECTURE.md) | **中文** - : - # HomeAgent 架构 内核零 IO，一切外界交互来自插件。 + : + ## 消息处理流程 ### 完整链路 @@ -66,6 +66,8 @@ eventLoop() → processTextInput() 任意阶段设 `ctx.Response` 即跳到 `after_output`。 + : + ## 三层记忆 ### 记忆流转 @@ -203,6 +205,8 @@ eventLoop() → processTextInput() 实体冲突检测启发式（bigram Jaccard > 0.75），走 `selfInputCh` 内部通道，LLM 最终判断是否合并。 + : + ## 知识库 `internal/knowledge/knowledge.go` @@ -210,6 +214,8 @@ eventLoop() → processTextInput() - 独立 TF-IDF 索引，与记忆系统不冲突 - `knowledge_search` / `knowledge_create` / `knowledge_list` + : + ## Provider 与 Lua 适配层 ``` @@ -234,6 +240,8 @@ ProviderManager 管理多个源，按注册顺序 fallback。Lua 适配器位于 VM 内置 `json.encode` / `json.decode` / `log` / `http_get` / `http_post`。 + : + ## 插件系统 ### 三种加载方式 @@ -284,6 +292,8 @@ type Plugin interface { } ``` + : + ## 输出通道系统 每个输出通道生成两个工具： @@ -306,6 +316,8 @@ type Plugin interface { 系统提示注入：输出门控规则、多调用支持、长消息拆分。 子代理权限：`output_send__` 前缀工具允许使用。 + : + ## LLM 链事件 - 事件类型 `agent_llm_chain`，每次 LLM 轮次后发射 @@ -313,6 +325,8 @@ type Plugin interface { - WebUI 通过 SSE 订阅此事件实现实时显示 - 插件可通过 EventSubscriber 订阅（外部插件只读） + : + ## 受限外部插件 API 分层架构：内部插件获得完整 PluginSDK，外部插件获得受限 SDK。 @@ -326,6 +340,8 @@ type Plugin interface { - Triple 扩展：Confidence、SubjectType、ObjectType - Relation 扩展：Confidence + : + ## 中断机制 ``` @@ -346,6 +362,8 @@ interceptLoop (goroutine) 代码：`internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt` + : + ## 配置系统 `internal/config/registry.go` — ConfigRegistry @@ -355,6 +373,8 @@ interceptLoop (goroutine) - `RegisterDefault` 插入 ~80 个默认键（8 个 LLM 源的 seeds） - WebUI 设置页 `/api/v1/settings` 读写 + : + ## 代码结构 ``` diff --git a/docs/zh/OVERVIEW.md b/docs/zh/OVERVIEW.md index 16774ee..70900b4 100644 --- a/docs/zh/OVERVIEW.md +++ b/docs/zh/OVERVIEW.md @@ -1,9 +1,9 @@ [English](../en/OVERVIEW.md) | **中文** - : - # HomeAgent — 项目概览 + : + ## 这是什么 HomeAgent 是一个持续运行的个人智能 Agent 框架。 @@ -27,6 +27,8 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。 三层递进：上下文 → 冷归档 → 长期图记忆，确保 Agent 长时间运行不退化。 + : + ## 它实际做了什么 代码位于项目仓库根目录，Go 语言实现。 @@ -67,6 +69,8 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。 - 兼容 OpenAI API 格式的 `/v1/chat/completions` 端点 - SSE 事件流 `/api/v1/chat/events` + : + ## 项目状态 核心功能已可运行。插件系统和 SDK 已就绪，可独立开发外部插件。 diff --git a/docs/zh/PLUGIN_DEV.md b/docs/zh/PLUGIN_DEV.md index 81f4ba4..c94c746 100644 --- a/docs/zh/PLUGIN_DEV.md +++ b/docs/zh/PLUGIN_DEV.md @@ -1,9 +1,9 @@ [English](../en/PLUGIN_DEV.md) | **中文** - : - # HomeAgent 插件开发指南 + : + ## 概述 HomeAgent 的所有外部交互能力都来自插件。插件通过 `PluginSDK`（Go API）与内核交互。 @@ -36,6 +36,8 @@ type Plugin interface { --- + : + ## 一、快速开始：使用 plugindev 工具链 `plugindev` 是 SDK 仓库提供的统一插件开发工具链，支持 Go 和 Lua 两种插件类型。 @@ -135,6 +137,8 @@ curl -X POST http://127.0.0.1:9876/plugins \ --- + : + ## 二、Go 插件开发详解 ### 插件接口 @@ -347,6 +351,8 @@ channels := s.ListChannels() --- + : + ## 三、Lua 插件开发详解 Lua 插件适合轻量级快速原型，无需 Go 编译环境，修改后直接重启内核即可生效。 @@ -417,6 +423,8 @@ lua main.lua --- + : + ## 四、内置插件 内置插件使用 `init()` 自注册方式，编译进内核，无需单独部署。 @@ -480,6 +488,8 @@ import ( --- + : + ## 五、最佳实践 1. `Start()` 非阻塞 — goroutine 启动长任务，不要阻塞 Start @@ -492,6 +502,8 @@ import ( --- + : + ## 六、示例插件参考 ### SDK 仓库示例（`homeagent-sdk/example/`）