From 2e0f7b47d106598bddb4c1350d6d17ddf2d379a2 Mon Sep 17 00:00:00 2001 From: JianFeeeee <2198972886@qq.com> Date: Sat, 25 Jul 2026 12:17:53 +0800 Subject: [PATCH] =?UTF-8?q?delete:=20=E5=88=A0=E9=99=A4=E6=96=87=E4=BB=B6?= =?UTF-8?q?=20plan.md=20=E7=A7=BB=E9=99=A4=E4=B8=8D=E5=BF=85=E8=A6=81?= =?UTF-8?q?=E7=9A=84=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: JianFeeeee <2198972886@qq.com> --- plan.md | 274 -------------------------------------------------------- 1 file changed, 274 deletions(-) delete mode 100644 plan.md diff --git a/plan.md b/plan.md deleted file mode 100644 index ca650ab..0000000 --- a/plan.md +++ /dev/null @@ -1,274 +0,0 @@ -# 记忆系统重构计划 — 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 -``` - -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 (文档) ── 全部完成 ✅ -```