HomeAgent

jianf/HomeAgent

Fork 0

mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-21 17:38:10 +00:00

Commit Graph

Author	SHA1	Message	Date
JianFeeeee	02cc74ce11	fix(proc): 子进程崩溃自愈 + 集中台账 + 注册面摘除根因：子进程插件被 kill 后，内核只发了一个无人订阅的事件，工具/stage handler/IO 通道全留在注册表里指向死进程，模型继续调用只吃 ErrProcessExited，没有任何路径把插件拉回来。 ## 四层修复 ### 1. 专职 waitLoop（进程收割） - 每个子进程配一根 waitLoop goroutine，是 cmd.Wait() 的唯一调用点 - 不再依赖 stdout EOF 判定死亡（孙子进程继承 stdout 时 EOF 永不到来） - 手工 os.Pipe 替代 cmd.StdinPipe/StdoutPipe，避免 waitLoop 与 os/exec 的内部关闭竞争 - host.go: Host.Supervisor()，Host.Close() 先 StopAll 再拆段 ### 2. 集中台账 Supervisor - proc/supervisor.go: 插件 Spawn 握手成功即 track，进程退出即 untrack - StopAll: 并发发 plugin.stop 走优雅路径，到期仍在的一律 Kill - 关停后才完成握手的进程被立即结束，不会活过内核 - 消除「孤儿进程持共享段映射 → SIGBUS」的隐患 ### 3. 注册面摘除（detachPlugin） - 新增 StageHost.UnregisterPluginStages：摘除指定插件的全部 stage handler - 新增 Registry.pluginChannels 台账：记录每个插件注册的 IO 通道 - 三条路径统一走 detachPlugin：Disable / ReloadOne / RemovePlugin - StopAndUnload 漏了 IO 通道也一并补上 ### 4. 自动重启 - onProcCrash 从「只发事件」改为「摘注册面 → 从注册表移除 → 异步排重启」 - scheduleProcRestart: 窗口 5 分钟内最多 3 次，线性退避 1s/2s/3s - 超限停手留日志；重启前复核是否已被 Disable 或被其他路径加载 - 崩溃计数窗口过期自动归零 ### 5. 主动停止 vs 崩溃的区分 - proc.Plugin 新增 stopping 标志：Stop()/Close() 里 Set(true) - handleExit 读 stopping 标志，主动停止不上报 onCrash - 防止重载/禁用/卸载被误判为崩溃触发多余重启 ### 6. Linux Pdeathsig 兜底 - procattr_linux.go: SysProcAttr.Pdeathsig = SIGKILL - 兜 homed 自身被 SIGKILL/OOM 时子进程变孤儿的场景 - macOS/Windows 无等价物，空实现 ### 7. pluginmgr 升级 - PluginManager 接口新增 PluginRuntime / ListPluginRuntimes - plugin_list 输出运行态：loaded / alive / pid / crash_count / channel - 新增 plugin_status: 全量运行期快照 + dead/unhealthy 汇总 - 新增 plugin_restart: 无条件重启单个插件（plgreload 不动未改二进制的插件） ### 测试 - process_test.go: 3 例（grandchild stdout 感知 / Supervisor track-untrack / StopAll 无孤儿） - crash_recovery_test.go: 8 例（detach 三项齐全 / 通道重注册 / 崩溃不阻塞 / 退避阈值 / 窗口过期 / 关停中跳过 / PluginRuntime 通道识别） - stages_plugin_test.go: 4 例（stage 按插件摘除 / 空 stage 清理 / 空名 no-op / 工具+stage 双摘后可重新注册同名）	2026-09-03 12:37:58 +08:00
JianFeeeee	d027c964e2	proc: Windows 共享内存 + 事件通知适配（Part 6.2 内核侧）补齐内核侧的 Windows 创建端，与 6.1 的插件侧打开端配对。三平台（linux/darwin/windows）现在都能构建 internal/plugin/proc。 ## Windows 走命名内核对象（无 fd 继承语义） os/exec 的 ExtraFiles 在 Windows 实现里不被支持，故： - shmalloc_windows.go：CreateFileMappingW（INVALID_HANDLE_VALUE + 命名 → 系统页文件支撑的匿名段，不落盘）+ MapViewOfFile - evtfd_windows.go：CreateEventW 命名 Event 对象 + SetEvent 通知 - shmpass_windows.go：把段名/对象名经环境变量注入子进程（HOMEAGENT_SHM_STAGE / HOMEAGENT_SHM_EVTRING / HOMEAGENT_EVT_EVENT）名字带 PID + 递增序号：多个 homed 实例并存时不能撞名。 Event 与 eventfd 的语义差异：Event 是二元信号，多次 SetEvent 只对应一次唤醒，不累积。不影响正确性——消费者被唤醒后按 readSeq 追 writeSeq 批量 drain，丢的是"唤醒次数"不是"事件"；事件环本身就允许溢出丢弃并让消费者知道丢了（dropped 计数），通知面从来不是可靠投递语义。 ## 传递机制抽象为 shmpass_.go Plugin.Start 不再直接构造 ExtraFiles 列表，改为问 Host 要： Env: p.host.procEnvForShm() // Windows 返回段名，Unix 返回 nil ExtraFiles: p.host.procExtraFilesForShm() // Unix 返回 fd 列表，Windows 返回 nil 平台差异被收敛到这一对函数，Plugin/coreHandler/stage 全部平台无关。 ## macOS pipe 生命周期修正原实现只返回读端 fd，写端 os.File 无人持有 → 可能被 GC 回收 → 读端收到 EOF 而非阻塞 → 消费循环变忙转。改为 pipePair 表同时持有两端， evtfdClose 一并关闭。 ## E2E 测试跟进模板拆分模板从单文件拆成三个（主体 + unix/windows 挂载），测试需要一并落盘，否则编译报 attachStageShm undefined。procRuntimeTemplates 表必须与 SDK 仓 proc_runtime.go 的 procRuntimeFiles 一致。验证：三平台 go build ./internal/plugin/... 通过（gojieba 的 cgo 依赖导致 internal/memory 在非 linux 失败，与本次无关）； go test -race ./internal/plugin/... 全绿，含 2 项真实模板 E2E。 Ref: docs/zh/架构迁移评估.md §9.2、docs/zh/plugin-migration-plan.md Part 6	2026-09-02 19:07:14 +08:00
dev	d62430a71b	feat(proc): 子进程通道 —— RPC 协议 + 进程管理（Part 2 核心）协议面（protocol.go，§3.2 method id 平移为 method 名）: - NDJSON 帧，双向复用同一对 stdio；ID>0 需应答，ID==0 为通知(post-and-forget) - 51 个 C ABI method id 全部平移为可读 method 名并标注原编号对照编号本身扔掉——加能力不用改两边常量表，不再有 47 夹在 7 和 8 之间的痕迹 - case 25(CORE_FREE_STRING) 无对应 method：进程模型下各自 GC，概念消失 - case 23/24(事件订阅) 与 io.setToolBlocks 今日均为空实现「给不了」，子进程下首次真正可给（§3.8 能力对齐） - 新增 stage.lock/stage.unlock（C ABI 下不存在跨进程锁概念） - StageInvokeParams 不含 StageContext 数据本身——数据在共享段，只带 stage 名 + seq 进程面（process.go，§2.3 保留现有生命周期机制）: - Spawn: 启动 + 握手（协议版本不匹配显式拒绝，不半兼容运行） - readLoop: NDJSON 分派应答/插件反向请求，1MB 单帧上限（大 payload 走 arena） - CallContext: ctx 取消时立即返回且清理 pending 条目对比 cgo：超时只让调用方返回，goroutine 永久卡在 C 调用里（现网泄漏 26 次） - Notify: ID=0 不占 pending 表，满足约束 B（流式逐 token 发布不得等待消费者） - markExited: EOF/退出 → 唤醒全部在途调用 → onExit 回调这是「把 panic 捕获换成进程退出检测」的落点，plugin_health 逻辑完全复用 - Stop: plugin.stop → 宽限期 → 超时 Kill；Kill 后 OS 回收全部资源，零泄漏 - serveRequest 带 panic 隔离：内核 handler panic 不带崩 readLoop 验证（10 项，真实子进程而非 mock，含 -race）: - 握手/工具调用/错误上报（插件失败调用方收到 error，非假成功） - 插件反向调用内核（tool.register + settings.get 双向往返） - 崩溃隔离：插件 panic → 子进程 exit 2，内核存活、收到 onExit、在途调用不挂死 - 优雅停止 / Kill 卡死插件（ctx 超时返回 + pending 清零 + 资源回收） - 通知不等应答（100 条 < 1s）/ 50 并发调用应答不串 / 协议版本不匹配拒绝接口冻结: git diff third_party/homeagent-sdk/sdk/ 为空	2026-09-02 10:59:59 +08:00

Author

SHA1

Message

Date

JianFeeeee

02cc74ce11

fix(proc): 子进程崩溃自愈 + 集中台账 + 注册面摘除

根因：子进程插件被 kill 后，内核只发了一个无人订阅的事件，
工具/stage handler/IO 通道全留在注册表里指向死进程，
模型继续调用只吃 ErrProcessExited，没有任何路径把插件拉回来。

## 四层修复

### 1. 专职 waitLoop（进程收割）
- 每个子进程配一根 waitLoop goroutine，是 cmd.Wait() 的唯一调用点
- 不再依赖 stdout EOF 判定死亡（孙子进程继承 stdout 时 EOF 永不到来）
- 手工 os.Pipe 替代 cmd.StdinPipe/StdoutPipe，避免 waitLoop 与
  os/exec 的内部关闭竞争
- host.go: Host.Supervisor()，Host.Close() 先 StopAll 再拆段

### 2. 集中台账 Supervisor
- proc/supervisor.go: 插件 Spawn 握手成功即 track，进程退出即 untrack
- StopAll: 并发发 plugin.stop 走优雅路径，到期仍在的一律 Kill
- 关停后才完成握手的进程被立即结束，不会活过内核
- 消除「孤儿进程持共享段映射 → SIGBUS」的隐患

### 3. 注册面摘除（detachPlugin）
- 新增 StageHost.UnregisterPluginStages：摘除指定插件的全部 stage handler
- 新增 Registry.pluginChannels 台账：记录每个插件注册的 IO 通道
- 三条路径统一走 detachPlugin：Disable / ReloadOne / RemovePlugin
- StopAndUnload 漏了 IO 通道也一并补上

### 4. 自动重启
- onProcCrash 从「只发事件」改为「摘注册面 → 从注册表移除 → 异步排重启」
- scheduleProcRestart: 窗口 5 分钟内最多 3 次，线性退避 1s/2s/3s
- 超限停手留日志；重启前复核是否已被 Disable 或被其他路径加载
- 崩溃计数窗口过期自动归零

### 5. 主动停止 vs 崩溃的区分
- proc.Plugin 新增 stopping 标志：Stop()/Close() 里 Set(true)
- handleExit 读 stopping 标志，主动停止不上报 onCrash
- 防止重载/禁用/卸载被误判为崩溃触发多余重启

### 6. Linux Pdeathsig 兜底
- procattr_linux.go: SysProcAttr.Pdeathsig = SIGKILL
- 兜 homed 自身被 SIGKILL/OOM 时子进程变孤儿的场景
- macOS/Windows 无等价物，空实现

### 7. pluginmgr 升级
- PluginManager 接口新增 PluginRuntime / ListPluginRuntimes
- plugin_list 输出运行态：loaded / alive / pid / crash_count / channel
- 新增 plugin_status: 全量运行期快照 + dead/unhealthy 汇总
- 新增 plugin_restart: 无条件重启单个插件（plgreload 不动未改二进制的插件）

### 测试
- process_test.go: 3 例（grandchild stdout 感知 / Supervisor track-untrack /
  StopAll 无孤儿）
- crash_recovery_test.go: 8 例（detach 三项齐全 / 通道重注册 / 崩溃不阻塞 /
  退避阈值 / 窗口过期 / 关停中跳过 / PluginRuntime 通道识别）
- stages_plugin_test.go: 4 例（stage 按插件摘除 / 空 stage 清理 / 空名 no-op /
  工具+stage 双摘后可重新注册同名）

2026-09-03 12:37:58 +08:00

JianFeeeee

d027c964e2

proc: Windows 共享内存 + 事件通知适配（Part 6.2 内核侧）

补齐内核侧的 Windows 创建端，与 6.1 的插件侧打开端配对。三平台
（linux/darwin/windows）现在都能构建 internal/plugin/proc。

## Windows 走命名内核对象（无 fd 继承语义）

os/exec 的 ExtraFiles 在 Windows 实现里不被支持，故：
- shmalloc_windows.go：CreateFileMappingW（INVALID_HANDLE_VALUE + 命名 →
  系统页文件支撑的匿名段，不落盘）+ MapViewOfFile
- evtfd_windows.go：CreateEventW 命名 Event 对象 + SetEvent 通知
- shmpass_windows.go：把段名/对象名经环境变量注入子进程
  （HOMEAGENT_SHM_STAGE / HOMEAGENT_SHM_EVTRING / HOMEAGENT_EVT_EVENT）

名字带 PID + 递增序号：多个 homed 实例并存时不能撞名。

Event 与 eventfd 的语义差异：Event 是二元信号，多次 SetEvent 只对应一次
唤醒，不累积。不影响正确性——消费者被唤醒后按 readSeq 追 writeSeq 批量
drain，丢的是"唤醒次数"不是"事件"；事件环本身就允许溢出丢弃并让消费者
知道丢了（dropped 计数），通知面从来不是可靠投递语义。

## 传递机制抽象为 shmpass_*.go

Plugin.Start 不再直接构造 ExtraFiles 列表，改为问 Host 要：
  Env:        p.host.procEnvForShm()        // Windows 返回段名，Unix 返回 nil
  ExtraFiles: p.host.procExtraFilesForShm() // Unix 返回 fd 列表，Windows 返回 nil

平台差异被收敛到这一对函数，Plugin/coreHandler/stage 全部平台无关。

## macOS pipe 生命周期修正

原实现只返回读端 fd，写端 *os.File 无人持有 → 可能被 GC 回收 →
读端收到 EOF 而非阻塞 → 消费循环变忙转。改为 pipePair 表同时持有两端，
evtfdClose 一并关闭。

## E2E 测试跟进模板拆分

模板从单文件拆成三个（主体 + unix/windows 挂载），测试需要一并落盘，
否则编译报 attachStageShm undefined。procRuntimeTemplates 表必须与
SDK 仓 proc_runtime.go 的 procRuntimeFiles 一致。

验证：三平台 go build ./internal/plugin/... 通过（gojieba 的 cgo 依赖
导致 internal/memory 在非 linux 失败，与本次无关）；
go test -race ./internal/plugin/... 全绿，含 2 项真实模板 E2E。

Ref: docs/zh/架构迁移评估.md §9.2、docs/zh/plugin-migration-plan.md Part 6

2026-09-02 19:07:14 +08:00

dev

d62430a71b

feat(proc): 子进程通道 —— RPC 协议 + 进程管理（Part 2 核心）

协议面（protocol.go，§3.2 method id 平移为 method 名）:
- NDJSON 帧，双向复用同一对 stdio；ID>0 需应答，ID==0 为通知(post-and-forget)
- 51 个 C ABI method id 全部平移为可读 method 名并标注原编号对照
  编号本身扔掉——加能力不用改两边常量表，不再有 47 夹在 7 和 8 之间的痕迹
- case 25(CORE_FREE_STRING) 无对应 method：进程模型下各自 GC，概念消失
- case 23/24(事件订阅) 与 io.setToolBlocks 今日均为空实现「给不了」，
  子进程下首次真正可给（§3.8 能力对齐）
- 新增 stage.lock/stage.unlock（C ABI 下不存在跨进程锁概念）
- StageInvokeParams 不含 StageContext 数据本身——数据在共享段，只带 stage 名 + seq

进程面（process.go，§2.3 保留现有生命周期机制）:
- Spawn: 启动 + 握手（协议版本不匹配显式拒绝，不半兼容运行）
- readLoop: NDJSON 分派应答/插件反向请求，1MB 单帧上限（大 payload 走 arena）
- CallContext: ctx 取消时立即返回**且清理 pending 条目**
  对比 cgo：超时只让调用方返回，goroutine 永久卡在 C 调用里（现网泄漏 26 次）
- Notify: ID=0 不占 pending 表，满足约束 B（流式逐 token 发布不得等待消费者）
- markExited: EOF/退出 → 唤醒全部在途调用 → onExit 回调
  这是「把 panic 捕获换成进程退出检测」的落点，plugin_health 逻辑完全复用
- Stop: plugin.stop → 宽限期 → 超时 Kill；Kill 后 OS 回收全部资源，零泄漏
- serveRequest 带 panic 隔离：内核 handler panic 不带崩 readLoop

验证（10 项，真实子进程而非 mock，含 -race）:
- 握手/工具调用/错误上报（插件失败调用方收到 error，非假成功）
- 插件反向调用内核（tool.register + settings.get 双向往返）
- **崩溃隔离**：插件 panic → 子进程 exit 2，内核存活、收到 onExit、在途调用不挂死
- 优雅停止 / **Kill 卡死插件**（ctx 超时返回 + pending 清零 + 资源回收）
- 通知不等应答（100 条 < 1s）/ 50 并发调用应答不串 / 协议版本不匹配拒绝

接口冻结: git diff third_party/homeagent-sdk/sdk/ 为空

2026-09-02 10:59:59 +08:00

3 Commits