HomeAgent/plan.md

# 记忆系统重构计划 — NoMemory 与 TextCleaner 设计修正

> **更新日期：** 2026-07-25
> **实施状态：** 全部完成 ✅

基于 `review.md` 审查结论，核心层两个设计偏差已全部修复：
- `RegisterTextCleaner` → 拆为 `ToolDef.Cleaner`（工具级，仅计算层生效）✅
- `hasNoMemoryTool` → 工具输出不参与向量/jieba/蒸馏，原文保留 ✅

---

## 第九阶段：SDK 示例插件更新（全部完成 ✅）

> **当前状态：** 所有示例插件已按以下分类添加 `NoMemory`/`Cleaner` 字段。其中多数插件由前期迭代完成，`editdoc`/`rss`/`qq` 三个插件在本次审查后补全。

### 9.1 背景

SDK 公有仓 `homeagentsdk/example/` 中的示例插件全部使用基础 `ToolDef`（仅 `Name`/`Description`/`Parameters`），未展示 `NoMemory`/`Cleaner` 用法，新插件开发者无从知晓这些字段。

### 9.2 QQ 插件分析

**文件：** `homeagentsdk/example/qq/plugin.go`

QQ 插件通过 `regTool` 包装方法注册（line 437），已扩展为直接透传 `sdk.ToolDef`：

```go
func (p *Plugin) regTool(s *sdk.PluginSDK, def sdk.ToolDef, handler sdk.ToolHandler) {
    s.RegisterTool(def.Name, def, handler)
}
```

备选方案（保持便捷性但增加可选参数）：
```go
func (p *Plugin) regTool(s *sdk.PluginSDK, name, desc string, params map[string]interface{}, handler sdk.ToolHandler, opts ...ToolOpt) {
    def := sdk.ToolDef{Name: name, Description: desc, Parameters: params}
    for _, o := range opts { o(&def) }
    s.RegisterTool(name, def, handler)
}
type ToolOpt func(*sdk.ToolDef)
func WithNoMemory() ToolOpt { return func(d *sdk.ToolDef) { d.NoMemory = true } }
func WithCleaner(fn func(string) string) ToolOpt { return func(d *sdk.ToolDef) { d.Cleaner = fn } }
```

### 9.3 示例插件完整清单

| 示例插件 | 工具数 | 实际状态 |
|---------|--------|---------|
| `files/plugin.go` | 4 (read/write/edit/ls) | `files_read` `NoMemory=false` + `Cleaner` ✅ |
| `memo/plugin.go` | 3 | 无需改动 ✅ |
| `weather/plugin.go` | 3 | 无需改动 ✅ |
| `browser/plugin.go` | 11 | `search/fetch/render` `Cleaner` ✅ |
| `qq/plugin.go` | 18 | `regTool` 已扩展 `def sdk.ToolDef`；12 查询类 `NoMemory=false`（6 个加 `Cleaner`），6 操作类 `NoMemory=true` ✅（本次补全） |
| `a2a/plugin.go` | 4 | `a2a_query` `Cleaner` ✅ |
| `ai_image/plugin.go` | 1 | 无需 Cleaner ✅ |
| `bili/plugin.go` | 1 | `bili_video` `Cleaner` ✅ |
| `calendar/plugin.go` | 6 | 无需改动 ✅ |
| `editdoc/plugin.go` | 1 | `edit_document` `NoMemory=true` ✅（本次补全） |
| `music/plugin.go` | 2 | `music_search` `Cleaner` ✅ |
| `ocr/plugin.go` | 1 | `ocr_image` `Cleaner` ✅ |
| `rss/plugin.go` | 4 | `subscribe/unsubscribe/check_now` `NoMemory=true` ✅（本次补全） |
| `sanitizer/plugin.go` | 0 (stage only) | 无需改动 ✅ |

### 9.4 各示例插件具体改动（均已实施 ✅）

**`files/plugin.go`** — `files_read` `NoMemory=false` + Cleaner（提取 JSON `.content` 字段），与核心仓内置插件对齐。✅

**`browser/plugin.go`** — `search/fetch/render` 注册 Cleaner 提取正文。✅

**`qq/plugin.go`** — 各工具分类（全部已实施）：
- 查询类（NoMemory=false，6 个加 Cleaner 提取 `.content`）: `get_message`, `get_history`, `read_document`, `video_download`, `get_group_files`, `get_download_tasks`, `get_groups`, `get_friends`, `get_recent_contacts`, `resolve_name`, `resolve_nickname`, `get_group_member_info`
- 操作类（NoMemory=true）: `send_file`, `download_file`, `upload_group_file`, `group_manage`, `friend_action`, `send_like`

**`a2a/plugin.go`** — `a2a_query` Cleaner 提取 response 文本。✅

**`bili/plugin.go`** — `bili_video` Cleaner 提取视频信息文本。✅

**`editdoc/plugin.go`** — `edit_document` NoMemory=true。✅（本次补全）

**`music/plugin.go`** — `music_search` Cleaner 提取纯文本。✅

**`ocr/plugin.go`** — `ocr_image` Cleaner 确保纯文本进入计算层。✅

**`rss/plugin.go`** — `subscribe/unsubscribe/check_now` NoMemory=true。✅（本次补全）

**无需改动：** `memo`, `weather`, `calendar`, `sanitizer`, `ai_image`（输出简短或结构化，无噪音）。

---

## 第十阶段：plugindev 工具链更新

> **当前状态：** 生成模板已更新 ✅，mock 调试框架尚未实施。

### 10.1 生成模板更新 ✅

**文件：** `homeagentsdk/tools/plugindev/templates.go`

`tmplPluginGo` 模板（line 48-57）生成的注册代码已展示 `NoMemory`/`Cleaner` 用法：

```go
// 修改前：
s.RegisterTool(tp+"hello", sdk.ToolDef{
    Name: tp + "hello", Description: "A hello world tool",
    Parameters: map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
}, p.handleHello)

// 修改后：
s.RegisterTool(tp+"hello", sdk.ToolDef{
    Name:        tp + "hello",
    Description: "A hello world tool",
    Parameters:  map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
    NoMemory:    false,  // 工具输出对 LLM 注意力有信号价值时为 false，纯操作工具为 true
    // Cleaner:  func(output string) string {
    //     // 工具输出参与向量化/jieba/蒸馏前，在此过滤噪音
    //     return output
    // },
}, p.handleHello)
```

`tmplMainLua` Lua 模板同理，在注册工具时添加 `no_memory` 注释示范。

### 10.2 C ABI 桥接无需改动

- `Cleaner` 是 `func` 类型 + `json:"-"`，天然无法序列化过 C 边界（正确行为）
- `NoMemory` 是 `bool` + `json:"no_memory,omitempty"`，JSON 序列化后自动包含

### 10.3 新增 mock 调试框架

**背景：** 当前 `plugindev debug` 对 Go 插件仅打印 "use standard Go tooling"（`cmd_debug.go:123-132`），无任何 mock 能力。Lua 插件虽有 REPL，但无法模拟完整的 agent 消息管道。

**需求：** 在 `plugindev` 中新增一个 mock 调试框架，让插件开发者可以在本地模拟消息处理流程，无需连接真实 agent 内核。

**设计要点：**

```
plugindev debug --mock <dir>
```

Mock 框架应提供：

1. **Mock StageContext 构建器** — 通过 CLI 或 YAML/JSON 配置文件构建模拟的 `StageContext`，包含：
   - `RawMessage` / `UserID` / `GroupID`
   - `ToolCalls` / `ToolResults`
   - `LLMText` / `FinalText`
   - `NoMemory` / `Memory` / `Extra`

2. **Mock API 实现** — 为 `MemoryAPI`、`TextMemoryAPI`、`DocMemoryAPI`、`KnowledgeAPI`、`LLMAPI`、`SettingsAPI`、`SocialAPI` 提供内存 mock 实现：
   ```go
   // 内置 mock 实现，开发者可直接使用
   mockSDK := sdk.New("test-plugin", mockSettings, mockRegTool, mockRegStage, mockRegAPI, mockRegOutput)
   mockSDK.SetMemoryAPI(NewMockMemory())
   mockSDK.SetLLMAPI(NewMockLLM())
   ```

3. **Stage 触发模拟** — 支持手动触发各个 Stage：
   ```go
   // 模拟 before_toolcall 阶段
   ctx := sdk.StageContext{
       ToolCalls: []sdk.ToolCall{{Name: "files_read", Arguments: {"path": "/test.txt"}}},
   }
   host.RunStage(sdk.StageBeforeToolcall, &ctx)
   ```

4. **工具直接调用** — 按名称调用已注册的工具并验证返回值：
   ```go
   result, err := host.ExecuteTool("files_read", map[string]interface{}{"path": "/test.txt"})
   ```

5. **配置文件驱动** — 支持 YAML/JSON 测试场景文件：
   ```yaml
   # test_scenario.yaml
   stages:
     - stage: before_toolcall
       context:
         tool_calls:
           - name: files_read
             arguments:
               path: "/test.txt"
       expectations:
         - check: context.modified
           path: "tool_calls[0].arguments.path"
           equals: "/test.txt"
   ```

6. **集成 `go test`** — 提供 `mocktest` 包，插件开发者可在 `_test.go` 中直接使用：

   ```go
   // homeagentsdk/example/files/plugin_test.go
   func TestFilesReadTool(t *testing.T) {
       m := mocktest.New(t)
       p := &Plugin{name: "files", filesDir: t.TempDir()}
       os.WriteFile(filepath.Join(p.filesDir, "test.txt"), []byte("hello"), 0644)
       
       m.RegisterPlugin(p)
       m.ToolShouldReturn(t, "files_read", map[string]interface{}{"path": "test.txt"},
           map[string]interface{}{"content": "hello"})
   }
   ```

---

## 第十一阶段：文档更新（全部完成 ✅）

### 11.1 核心仓文档

**文件：**
- `docs/zh/PLUGIN_DEV.md:248` — 中文插件开发指南
- `docs/en/PLUGIN_DEV.md:250` — 英文插件开发指南
- `docs/zh/ARCHITECTURE.md:11` — 中文架构文档
- `docs/en/ARCHITECTURE.md:11` — 英文架构文档

**PLUGIN_DEV.md 改动：** 在注册工具示例中展示 `NoMemory`/`Cleaner` 用法：

```go
// 修改前：
s.RegisterTool("weather_query", sdk.ToolDef{
    Name:        "weather_query",
    Description: "Get current weather...",
    Parameters:  map[string]interface{}{...},
}, handler)

// 修改后：
s.RegisterTool("weather_query", sdk.ToolDef{
    Name:        "weather_query",
    Description: "Get current weather...",
    Parameters:  map[string]interface{}{...},
    NoMemory:    false,                           // ← 文档新增
    // Cleaner:  func(output string) string {     // ← 文档新增（注释示范）
    //     return extractJSON(output, "content")
    // },
}, handler)
```

并在文档中新增独立章节说明 NoMemory 和 Cleaner 的设计意图与使用场景。

**ARCHITECTURE.md 改动：** 在阶段管道说明中补充 ToolDef 的 NoMemory/Cleaner 字段描述。

### 11.2 SDK 仓文档

**文件：** `homeagentsdk/README.md` / `README_EN.md`

在 SDK README 的 ToolDef 说明中列出新增字段。

---

## SDK 公有仓实施状态清单

| 文件 | 操作 | 阶段 | 优先级 | 状态 |
|---|---|---|---|---|
| `homeagentsdk/sdk/plugin_test.go` | `TestToolDefCleaner`/`TestToolDefNoMemory`/`TestToolDefRegisterPreservesNoMemory` | 一 | P0 | ✅ |
| `homeagentsdk/example/qq/plugin.go` | `regTool` 签名扩展 `def sdk.ToolDef` + 各工具 NoMemory/Cleaner | 九 | P1 | ✅（本次补全） |
| `homeagentsdk/example/files/plugin.go` | `files_read` `NoMemory=false` + `Cleaner` | 九 | P1 | ✅ |
| `homeagentsdk/example/browser/plugin.go` | `search/fetch/render` `Cleaner` | 九 | P1 | ✅ |
| `homeagentsdk/example/a2a/plugin.go` | `a2a_query` `Cleaner` | 九 | P1 | ✅ |
| `homeagentsdk/example/bili/plugin.go` | `bili_video` `Cleaner` | 九 | P1 | ✅ |
| `homeagentsdk/example/editdoc/plugin.go` | `edit_document` `NoMemory=true` | 九 | P1 | ✅（本次补全） |
| `homeagentsdk/example/music/plugin.go` | `music_search` `Cleaner` | 九 | P1 | ✅ |
| `homeagentsdk/example/ocr/plugin.go` | `ocr_image` `Cleaner` | 九 | P1 | ✅ |
| `homeagentsdk/example/rss/plugin.go` | `subscribe/unsubscribe/check_now` `NoMemory=true` | 九 | P1 | ✅（本次补全） |
| `homeagentsdk/tools/plugindev/templates.go` | `tmplPluginGo` 展示 `NoMemory` + `Cleaner` | 十 | P2 | ✅（本次补全） |
| `homeagentsdk/tools/plugindev/...` | mock 调试框架 | 十 | P2 | ❌ |
| `docs/zh/PLUGIN_DEV.md` | 注册工具示例展示 NoMemory/Cleaner + 独立说明章节 | 十一 | P3 | ✅（本次补全） |
| `docs/en/PLUGIN_DEV.md` | 同上（英文版） | 十一 | P3 | ✅（本次补全） |
| `docs/zh/ARCHITECTURE.md` | 补充 ToolDef 新字段描述 | 十一 | P3 | ✅（本次补全） |
| `docs/en/ARCHITECTURE.md` | 同上（英文版） | 十一 | P3 | ✅（本次补全） |
| `homeagentsdk/README.md` / `README_EN.md` | 在 ToolDef 说明中列出新增字段 | 十一 | P3 | ✅（本次补全） |

### 实施顺序

```
P0 (单元测试) ── 已完成 ✅
P1 (示例插件) ── 全部完成 ✅
P2 (生成模板) ── tmplPluginGo 已完成 ✅，mock 框架待实施 ❌
P3 (文档)     ── 全部完成 ✅
```