HomeAgent/审查.md

# HomeAgent 代码审查报告（第三轮逐行全面复审）

审查日期: 2026-07-18

## 审查范围

- `cmd/homed/main.go` (453 行)
- `internal/agent/core/agent.go` (3156 行), `stages.go` (155 行), `context.go` (252 行), `plugin_health.go` (128 行)
- `internal/agent/core/stages_test.go` (199 行)
- `internal/agent/api/provider.go` (783 行)
- `internal/agent/io/channel.go` (636 行)
- `internal/sdk/` 全部 9 个文件 (510 行)
- `internal/plugin/` registry.go (426 行), plugin.go (295 行), dynamic.go (142 行)
- `internal/plugin/cabi/loader.go` (651 行)
- `internal/lua/vm.go` (403 行)
- `internal/events/bus.go` (83 行)
- `internal/config/registry.go` (700 行)
- `internal/memory/graph.go` (766 行), indexer.go (312 行), static_embedder.go (369 行), clean_text.go (57 行)
- `internal/memory/document/document.go` (471 行)
- SDK 仓库 `sdk/` 全部 6 个 API 文件 + `plugin_test.go` (~700 行)
- SDK 仓库 `tools/plugindev/templates.go`
- 架构文档 4 份 (`docs/zh/`)

---

## Bug 级别

### A-1 `processTextInput` 缺失 `runStage(StageOnInput)` 调用

- **位置**: `internal/agent/core/agent.go:494-562`
- **严重程度**: 高
- **描述**: `processTextInput` 创建了 `stageCtx` (行515) 但从未调用 `a.runStage(sdk.StageOnInput, stageCtx)`。注册了 `on_input` 阶段的插件对文本输入完全不可见。
- **对照**: `processMediaInput` (行410) 正确调用了 `runStage(StageOnInput)`。
- **影响**: 所有文本输入的 `on_input` 阶段钩子静默失效。黑名单、限流、短路回复等功能对文本输入无效。
- **文档对照**: ARCHITECTURE.md 完整链路图中 `processTextInput()` 下方第一支路即为 `on_input stage`。

### A-2 `processTextInput` 缺失 `publishEvent(EventRawInput)`

- **位置**: `internal/agent/core/agent.go:494-562`
- **严重程度**: 中
- **描述**: `processTextInput` 没有发布 `EventRawInput` 事件。
- **对照**: `processMediaInput` (行405) 正确调用了 `a.publishEvent(events.EventRawInput, ...)`。
- **影响**: 订阅 `raw_input` 事件的插件/WebUI 收不到文本输入的原始事件。

### A-4 `processMediaInput` 缺失 `emitMemoryCandidate` 调用

- **位置**: `internal/agent/core/agent.go:371-436`
- **严重程度**: 中
- **描述**: 媒体输入处理完成后，没有调用 `emitMemoryCandidate`（文本处理在行560对应调用）。图片/音频对话不会被捕获到文本记忆层。
- **影响**: `text memory` 中缺失多模态交互记录。

### A-5 `StageOnInput` 在 `context.Append` 之后执行

- **位置**: `internal/agent/core/agent.go:389-410`
- **严重程度**: 低
- **描述**: `processMediaInput` 中行389 `a.context.Append()` 先执行，行410 `runStage(StageOnInput)` 后执行。插件在 `on_input` 阶段无法阻止上下文被追加。
- **文档对照**: ARCHITECTURE.md 描述 `on_input` 为"消息到 Agent，零处理"，应在任何处理之前执行。

### A-6 `lua/vm.go` 中 `http_get`/`http_post` 返回 mock 数据

- **位置**: `internal/lua/vm.go:69-80`
- **严重程度**: 高
- **描述**: `http_get` 返回 `{"url":...,"body":"mock","status":200}`，`http_post` 返回 `{"url":...,"body":...,"status":200}`。没有实际 HTTP 网络调用。
- **文档对照**: ADAPTER.md 第93-95行明确说明 `http_get(url)` 和 `http_post(url, body)` 应发起真实 HTTP 请求。
- **影响**: Lua 适配器脚本中尝试使用 `http_get`/`http_post` 获取外部数据的功能均静默失败。

---

## 功能限制

### A-7 C ABI 注册阶段时未传递 `StageScope`

- **位置**: `internal/plugin/cabi/loader.go:285-304`
- **描述**: C ABI 的 `CORE_REGISTER_STAGE` (methodID=2) 调用 `s.RegisterStage(sdk.Stage(st), handler)`，没有 scope 参数，总是使用 `StageScopeGlobal`。外部 `.so` 插件无法使用 `StageScopeOwnTools`。
- **对照**: 公共 SDK `sdk/plugin.go:237` 的 `RegisterStage` 支持 `...scope` 变参。

---

## 顺序/次要问题

### A-8 `processConsolidation` 未注入 source context

- **位置**: `internal/agent/core/agent.go:2567`
- **描述**: `processConsolidation` 直接传 `&sdk.StageContext{RawMessage: input}`，没有调用 `injectSourceContext`。整理任务在 `process()` 内部的阶段钩子中无法获取来源/通道信息。

---

## 已确认无问题的功能

1. **SDK 接口映射**: `internal/sdk/` 的 5 组 type alias (`MemoryAPI`, `KnowledgeAPI`, `SettingsAPI`, `LLMAPI`, `DocMemoryAPI`) 全部正确对齐 `pubsdk`，impl 包装器逐一桥接。

2. **C ABI 45 个 dispatch 方法**: 全部覆盖 SDK API，JSON 序列化/反序列化正确，无遗漏。方法列表:
   - 1: CORE_REGISTER_TOOL
   - 2: CORE_REGISTER_STAGE
   - 3: CORE_REGISTER_OUTPUT_CH
   - 4: CORE_REGISTER_PLUGIN_API
   - 5-7: CORE_INJECT_TEXT / INJECT_INTERRUPT_TEXT / INJECT_TEXT_NO_MEMORY
   - 8: CORE_SET_AUTO_RESTART
   - 9-13: CORE_MEMORY_RECALL / COMMIT / INTROSPECT / MERGE / PURGE
   - 14: CORE_DOC_QUERY
   - 15: CORE_KNOWLEDGE_SEARCH
   - 16-18: CORE_SETTINGS_GET / SET / REGISTER_DEF
   - 19-20: CORE_LLM_LIST_SOURCES / SET_SOURCE
   - 21-22: CORE_SOCIAL_GET_PERSON / GET_NETWORK
   - 23-24: CORE_SUBSCRIBE / UNSUBSCRIBE
   - 25: CORE_FREE_STRING
   - 26-31: CORE_SETTINGS_GET_CORE / SET_CORE / LIST_CORE / GET_PLUGIN / SET_PLUGIN / LIST_PLUGIN
   - 32-34: CORE_DOC_INSERT / REMOVE / STATS
   - 35-36: CORE_KNOWLEDGE_ADD / LIST
   - 37: CORE_LLM_CURRENT_SOURCE
   - 38-40: CORE_SOCIAL_GET_TRAIT / GET_RELATIONS / LIST_PERSONS
   - 41: CORE_TEXT_MEMORY_APPEND
   - 42-45: CORE_SETTINGS_LIST / DEFS / DUMP / PLUGINS

3. **`pipeline.go` 非死代码**: `internal/memory/pipeline/pipeline.go` 在 `cmd/homed/main.go:122-130` 中被引用和启动。

4. **`emitMemoryCandidate` 被消费**: `cmd/homed/main.go:213-247` 的 goroutine 消费 `iom.OutputChan()` 中的 `memory_candidate` 事件，写入 `textMem` 和 `distiller`。

5. **向量表示跨会话兼容**: `StaticEmbedder` / `TFIDFVectorizer` 的 `Vectorize()` 是纯函数（基于词袋权重），不依赖会话状态。

6. **`processConsolidation` 不发射记忆候选**: 行2579注释说明这是有意为之，防止任务文本被蒸馏进图库造成污染。

---

## 汇总

| 编号 | 级别 | 文件 | 行 | 描述 |
|------|------|------|----|------|
| A-1 | **Bug** | `agent.go` | 494-562 | `processTextInput` 未调用 `StageOnInput` |
| A-2 | **Bug** | `agent.go` | 494-562 | `processTextInput` 未发布 `EventRawInput` |
| A-4 | **Bug** | `agent.go` | 371-436 | `processMediaInput` 未调用 `emitMemoryCandidate` |
| A-5 | **Bug** | `agent.go` | 389-410 | `StageOnInput` 在 `context.Append` 之后执行 |
| A-6 | **Bug** | `lua/vm.go` | 69-80 | `http_get`/`http_post` 返回 mock |
| A-7 | 限制 | `cabi/loader.go` | 285-304 | C ABI 缺 `StageScopeOwnTools` 支持 |
| A-8 | 顺序 | `agent.go` | 2567 | `processConsolidation` 未注入 source context |