mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-10-03 15:53:56 +00:00
docs(readme): 按源码修正 README 的过时事实(中英同步)
上一轮只补了 v1.3.x 变更日志,没系统核对全文。本次逐条对照源码,修掉 5 处硬错误: 1. **消息时序图漏掉输入调度器**(最严重):还画着 `IO->>EV: inputCh` 直连 eventLoop,而当前输入必须先进调度器。补 participant 与调度阶段 (两类别+四级中断、同级不排队/更高级抢占、转投分诊助手)。 2. **图里的 `drainInterrupts` 已不存在**:实测该函数在源码中查无此项, 改为「安全点:中断求值/让位」(真实机制见 scheduler.go)。 3. **内置插件数 11 → 18**:漏列 ai_image / data / localuse / multimodal / remotedevice / skillmgr(实测 `ls internal/plugins/` = 18)。 4. **Lua 适配器 8 → 10**:漏列 ollama / server(实测 = 10)。 5. **`agent/api/` 描述错误**:它只有 provider.go,不含 Lua 适配器 (适配器在 internal/lua/adapters/);改为如实的「provider.go 调 vm」。 另修一处**自相矛盾**:构建章节写「依赖 Linux/Windows」,而下载章节说 homed 已放弃 Windows 原生(`package-windows.sh` 明确「不往 Windows 装 homed」, 只建 waiter.exe + 引导 WSL2)。改为「依赖 Linux」并说明 Windows/macOS 的真实边界。 并给「设计要点」补上两个当前核心机制(此前只有域分离与三层记忆): 输入调度(两类别+四级中断)与驻留子/分诊助手。 验证:全仓文档断链 0;6 个 mermaid 图块配对全 OK;上述数字逐条实测复核。
This commit is contained in:
40
README_EN.md
40
README_EN.md
@ -32,6 +32,19 @@ plane). A plugin crash cannot take down the kernel and it restarts automatically
|
||||
- **Document Layer**: Temporary memory with automatic cold data sinking, also supports user-initiated submissions
|
||||
- **Graph Layer**: SQLite graph database, persists entity relationships and semantic memory, supports distillation pipelines to extract triples from conversations
|
||||
|
||||
**Input Scheduling: 2 classes + 4 interrupt levels** — Input does not go straight to the LLM;
|
||||
it first enters the scheduler. Two classes (queued = pending work, interrupt = ranked L1–L4 by
|
||||
"how urgent") with preemption and frame saving (interrupt stack); same level never preempts
|
||||
same level. L4 belongs only to the kernel and kernel-level plugins (e.g. the WebUI stop button).
|
||||
See "Input Scheduler & Interrupt Mechanism" in [`assets/docs/en/ARCHITECTURE.md`](assets/docs/en/ARCHITECTURE.md).
|
||||
|
||||
**Resident sub-agents** — The kernel can station lightweight-kernel child agents (their own
|
||||
scheduler and temp graph memory, sharing the channel registry) to run long or backlogged work
|
||||
in parallel. When the main agent stays busy, the kernel hands queued input to a temporary
|
||||
**triage assistant**: simple items are handled directly, items needing the main agent get an
|
||||
immediate "busy, please wait" — users no longer wait in silence.
|
||||
See [`docs/zh/resident-subagent-design.md`](docs/zh/resident-subagent-design.md).
|
||||
|
||||
## Architecture Diagrams
|
||||
|
||||
### 1. Message Processing Sequence
|
||||
@ -40,6 +53,7 @@ plane). A plugin crash cannot take down the kernel and it restarts automatically
|
||||
sequenceDiagram
|
||||
participant U as User/Plugin
|
||||
participant IO as IOManager
|
||||
participant SCH as Input Scheduler
|
||||
participant EV as eventLoop
|
||||
participant CTX as RelevanceContext
|
||||
participant LLM as LLM+Tool Loop
|
||||
@ -47,7 +61,14 @@ sequenceDiagram
|
||||
participant MEM as Three-Layer Memory
|
||||
|
||||
U->>IO: InjectInput(type, payload)
|
||||
IO->>EV: inputCh
|
||||
IO->>SCH: inputCh
|
||||
rect lavender
|
||||
Note over SCH: 2 task classes + 4 interrupt levels (L1-L4)
|
||||
SCH->>SCH: same level never preempts -> ready/interrupt queue
|
||||
SCH->>SCH: higher level -> preempt (frame pushed to interrupt stack)
|
||||
SCH->>SCH: offload (main agent busy too long -> temporary triage assistant)
|
||||
end
|
||||
SCH->>EV: pick one task and run it
|
||||
rect lavender
|
||||
Note over EV: processTextInput
|
||||
EV->>ST: StageOnInput Plugin can rewrite/short-circuit
|
||||
@ -61,7 +82,7 @@ sequenceDiagram
|
||||
EV->>MEM: buildSystemPrompt DocQuery summary+Graph memory index+Persona+Skills
|
||||
EV->>ST: StagePreAction Plugin can pre-intercept
|
||||
loop Tool loop
|
||||
LLM->>LLM: drainInterrupts
|
||||
LLM->>LLM: safe point: interrupt eval / yield
|
||||
LLM->>LLM: LLM Chat
|
||||
LLM->>ST: StagePostAction Plugin can modify/short-circuit
|
||||
alt No tool call
|
||||
@ -169,16 +190,16 @@ API keys are configured via WebUI `http://localhost:8080` settings page, persist
|
||||
cmd/homed/ Daemon entry, assembles all subsystems
|
||||
cmd/waiter/ CLI client (Unix socket)
|
||||
internal/
|
||||
├── agent/core/ Agent core: event loop, LLM tool loop, 7-stage pipeline
|
||||
├── agent/api/ LLM Provider + 8 Lua adapters
|
||||
├── agent/core/ Agent core: input scheduler (2 classes + 4 levels), event loop, LLM tool loop, 7-stage pipeline, residents
|
||||
├── agent/api/ LLM Provider (Lua adapter layer: provider.go drives the vm)
|
||||
├── memory/ Three-layer memory: Graph(SQLite) / Document(JSON+TF-IDF) / Text(JSONL) + StaticEmbedder(pretrained word embedding/TF-IDF fallback) + CleanTemplateText(de-template)
|
||||
├── knowledge/ Knowledge base (filesystem + TF-IDF)
|
||||
├── plugin/ Plugin registry + subprocess loader (stdio RPC + shared memory segment + event ring)
|
||||
├── plugins/ 11 built-in plugins (webui/cli/timer/cmd/mcp/clawhubadapter/agentcli/healthcheck/pluginmgr/files/cfgmgr)
|
||||
├── plugins/ 18 built-in plugins (webui/cli/timer/cmd/mcp/files/cfgmgr/agentcli/healthcheck/pluginmgr/clawhubadapter/multimodal/remotedevice/ai_image/localuse/skillmgr/data, ...)
|
||||
├── sdk/ PluginSDK (Tool/Stage/Event three channels)
|
||||
├── config/ SQLite config center
|
||||
├── events/ Event bus
|
||||
└── internal/lua/adapters/ 8 LLM protocol adapter scripts
|
||||
└── internal/lua/adapters/ 10 LLM protocol adapter scripts
|
||||
External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) repo, use `hmapdev` toolchain, refer to Go and Lua examples in `example/`
|
||||
```
|
||||
|
||||
@ -304,7 +325,12 @@ make test # go test ./...
|
||||
make install # Install to system
|
||||
```
|
||||
|
||||
Dependencies: Go 1.25+, CGo (go-sqlite3), Linux/Windows.
|
||||
Dependencies: Go 1.25+, CGo (go-sqlite3), Linux.
|
||||
|
||||
> `homed` requires Linux (it relies on fd inheritance and intra-segment offset
|
||||
dereferencing of the shared memory region; see `cmd/homed/platform_windows.go`).
|
||||
On Windows only `waiter.exe` is built and `homed` runs under WSL2 (see Downloads).
|
||||
macOS can build `waiter`/`initconfig`; `homed` must be built on native macOS.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user