From 71faf8d9adbd0700213aa0e5b7df0cd9cacd93a1 Mon Sep 17 00:00:00 2001
From: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
Date: Sat, 19 Sep 2026 20:59:42 +0800
Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E6=8C=89=E6=BA=90=E7=A0=81?=
 =?UTF-8?q?=E4=BF=AE=E6=AD=A3=20README=20=E7=9A=84=E8=BF=87=E6=97=B6?=
 =?UTF-8?q?=E4=BA=8B=E5=AE=9E=EF=BC=88=E4=B8=AD=E8=8B=B1=E5=90=8C=E6=AD=A5?=
 =?UTF-8?q?=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

上一轮只补了 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；上述数字逐条实测复核。
---
 README.md    | 37 ++++++++++++++++++++++++++++++-------
 README_EN.md | 40 +++++++++++++++++++++++++++++++++-------
 2 files changed, 63 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 6f36635..b9f35ac 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,16 @@ homed（内核零 IO） ← PluginSDK → 插件（所有 IO 能力）
 - **Document 层**：临时记忆，冷数据自动下沉，也支持用户主动提交
 - **Graph 层**：SQLite 图数据库，持久化实体关系和语义记忆，支持蒸馏管道从原始对话中提取三元组
 
+**输入调度：两类别 + 四级中断** — 输入不直接进 LLM，先进调度器。
+排队（待办工作）与中断（按"有多不能等"分 L1~L4）两类；高级可抢占低级并保存现场
+（中断栈），同级不抢占。L4 只归内核与内核级插件（如 WebUI 终止按钮）。
+见 [`assets/docs/zh/ARCHITECTURE.md`](assets/docs/zh/ARCHITECTURE.md) 的「输入调度器与中断机制」。
+
+**驻留式子 agent** — 内核可派驻轻量内核的子 agent（自己的调度器与 temp 图记忆，
+共享通道登记表），把长任务/积压交出去并行做。主 agent 忙久了，内核还会把排队输入
+交给临时**分诊助手**：简单的直接处理，需要主 agent 的立刻回「忙碌中，请稍候」，
+用户不再干等。见 [`docs/zh/resident-subagent-design.md`](docs/zh/resident-subagent-design.md)。
+
 ## 架构图
 
 ### 一、消息处理时序
@@ -34,6 +44,7 @@ homed（内核零 IO） ← PluginSDK → 插件（所有 IO 能力）
 sequenceDiagram
     participant U as 用户/插件
     participant IO as IOManager
+    participant SCH as 输入调度器
     participant EV as eventLoop
     participant CTX as RelevanceContext
     participant LLM as LLM+工具循环
@@ -41,7 +52,14 @@ sequenceDiagram
     participant MEM as 三层记忆
 
     U->>IO: InjectInput(type, payload)
-    IO->>EV: inputCh
+    IO->>SCH: inputCh
+    rect lavender
+        Note over SCH: 两类别 + 四级中断（L1~L4）
+        SCH->>SCH: 同级不抢占 → 入就绪队列/中断队列
+        SCH->>SCH: 更高级 → 抢占（现场压中断栈，稍后可恢复）
+        SCH->>SCH: 转投（主 agent 忙久了 → 交给临时分诊助手）
+    end
+    SCH->>EV: 选中一个任务开始跑
     rect lavender
         Note over EV: processTextInput
         EV->>ST: StageOnInput  插件可改写/短路
@@ -55,7 +73,7 @@ sequenceDiagram
         EV->>MEM: buildSystemPrompt  DocQuery摘要+Graph记忆索引+人格+技能
         EV->>ST: StagePreAction  插件可预拦截
         loop 工具循环
-            LLM->>LLM: drainInterrupts
+            LLM->>LLM: 安全点：中断求值/让位
             LLM->>LLM: LLM Chat
             LLM->>ST: StagePostAction  插件可修改/短路
             alt 无tool call
@@ -180,16 +198,16 @@ API 密钥通过 WebUI `http://localhost:8080` 设置页配置，持久化在 SQ
 cmd/homed/          守护进程入口，组装所有子系统
 cmd/waiter/         CLI 客户端（Unix socket）
 internal/
-├── agent/core/     Agent 核心：事件循环、LLM 工具循环、7 阶段管道
-├── agent/api/      LLM Provider + 8 个 Lua 适配器
+├── agent/core/     Agent 核心：输入调度器（两类别+四级中断）、事件循环、LLM 工具循环、7 阶段管道、驻留子
+├── agent/api/      LLM Provider（Lua 适配层：provider.go 调 vm）
 ├── memory/         三层记忆：Graph(SQLite) / Document(JSON+TF-IDF) / Text(JSONL) + StaticEmbedder(预训练词嵌入/TF-IDF回退) + CleanTemplateText(去模版)
 ├── knowledge/      知识库（文件系统 + TF-IDF）
 ├── plugin/         插件注册表 + 子进程加载器（stdio RPC + 共享内存段 + 事件环）
-├── plugins/        内置 11 个插件（webui/cli/timer/cmd/mcp/clawhubadapter/agentcli/healthcheck/pluginmgr/files/cfgmgr）
+├── plugins/        内置 18 个插件（webui/cli/timer/cmd/mcp/files/cfgmgr/agentcli/healthcheck/pluginmgr/clawhubadapter/multimodal/remotedevice/ai_image/localuse/skillmgr/data 等）
 ├── sdk/            PluginSDK（Tool/Stage/Event 三通道）
 ├── config/         SQLite 配置中心
 ├── events/         事件总线
-└── internal/lua/adapters/   8 个 LLM 协议适配器脚本
+└── internal/lua/adapters/   10 个 LLM 协议适配器脚本
 外部插件开发见 [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) 仓库，使用 `hmapdev` 工具链开发，参考 `example/` 目录下的 Go 和 Lua 示例
 ```
 
@@ -282,7 +300,12 @@ make test               # go test ./...
 make install            # 安装到系统
 ```
 
-依赖：Go 1.25+, CGo (go-sqlite3), Linux/Windows。
+依赖：Go 1.25+, CGo (go-sqlite3), Linux。
+
+> `homed` 需 Linux（依赖 fd 继承与共享内存段的段内偏移解引用，见
+> `cmd/homed/platform_windows.go`）；Windows 上只构建 `waiter.exe`，
+> `homed` 跑在 WSL2 里（见「下载」）。macOS 可构建 `waiter`/`initconfig`，
+> `homed` 需在原生 macOS 构建。
 
 ## 许可
 
diff --git a/README_EN.md b/README_EN.md
index c9541d7..3ca84fe 100644
--- a/README_EN.md
+++ b/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