@oyasmi/pipiclaw 0.4.0 → 0.5.0

package/docs/test-supplementation-plan.md

@@ -0,0 +1,553 @@
+# Pipiclaw 测试补充方案
+
+## Context
+
+Pipiclaw 当前有 22 个测试文件，工具层和记忆文件 I/O 覆盖良好，但**核心编排层（agent.ts）、消息投递层（delivery.ts）、命令扩展（command-extension.ts）、DingTalk 协议层（dingtalk.ts）完全没有测试**。记忆生命周期（memory-lifecycle.ts）和合并逻辑（memory-consolidation.ts）仅通过 mock 做了基础验证。**没有任何集成测试或端到端冒烟测试**。本方案旨在补全这些关键缺口。
+
+### 当前测试覆盖现状
+
+**已覆盖（22 个文件，单元测试）：**
+- 工具层：read, bash, edit, write, truncate, attach, shell-escape
+- 记忆文件 I/O：memory-files, memory-recall, memory-candidates, session-memory
+- 记忆生命周期：memory-lifecycle（仅 2 个基础 hook 测试）
+- 子 Agent：sub-agents（发现/解析）、subagent tool（执行/上下文注入）
+- 配置/运行时：config-loader, context, model-utils, prompt-builder, sandbox
+- 基础设施：commands, events, store, log, sidecar-worker, llm-json, tools-index
+
+**未覆盖：**
+
+| 模块 | 行数 | 风险等级 | 说明 |
+|------|------|----------|------|
+| `agent.ts` | 907 | **高** | ChannelRunner: run(), 事件订阅, 命令分发, steer/followup |
+| `delivery.ts` | 247 | **高** | 节流投递状态机, progress/finalize/silent 模式 |
+| `command-extension.ts` | 169 | **中** | /session, /model, /new, /compact 命令 |
+| `dingtalk.ts` | 881 | **高** | 连接生命周期, 消息去重, 授权, Card API, 消息路由 |
+
+**欠覆盖：**
+
+| 模块 | 现有测试 | 缺失 |
+|------|----------|------|
+| `memory-lifecycle.ts` | 2 个 hook 测试 | 阈值触发、后台队列、错误恢复 |
+| `memory-consolidation.ts` | 仅通过 mock 验证 | 真实文件 I/O 的合并/清理/折叠逻辑 |
+
+---
+
+## 前置工作：共享测试基础设施
+
+### `test/helpers/fake-bot.ts` — DingTalkBot 测试替身
+
+提供一个可配置的 DingTalkBot 替身，记录所有方法调用及其参数，支持通过 `configure()` 控制返回值。
+
+```typescript
+export class FakeDingTalkBot {
+   calls: { method: string; args: unknown[] }[] = [];
+   private returnValues: Map<string, unknown> = new Map();
+
+   configure(method: string, returnValue: unknown): void;
+
+   async streamToCard(channelId: string, content: string): Promise<boolean>;
+   async finalizeCard(channelId: string, content: string): Promise<boolean>;
+   async finalizeExistingCard(channelId: string, content: string): Promise<boolean>;
+   discardCard(channelId: string): void;
+   async sendPlain(channelId: string, text: string): Promise<boolean>;
+   enqueueEvent(event: DingTalkEvent): boolean;
+}
+```
+
+### `test/helpers/fake-store.ts` — ChannelStore 测试替身
+
+```typescript
+export class FakeChannelStore {
+   logged: { method: string; args: unknown[] }[] = [];
+   async logMessage(channelId: string, message: unknown): Promise<void>;
+   async logBotResponse(channelId: string, text: string, ts: string): Promise<void>;
+   async logSubAgentRun(channelId: string, run: unknown): Promise<void>;
+   getChannelDir(channelId: string): string;
+}
+```
+
+### `test/helpers/fake-extension-api.ts` — ExtensionAPI 测试替身
+
+```typescript
+export class FakeExtensionAPI {
+   registeredCommands = new Map<string, { description: string; handler: Function }>();
+   sentMessages: unknown[] = [];
+   handlers = new Map<string, Function>();
+
+   registerCommand(name: string, config: { description: string; handler: Function }): void;
+   sendMessage(msg: unknown): void;
+   on(event: string, handler: Function): void;
+}
+```
+
+### `test/helpers/fixtures.ts` — 通用 Fixture 工厂
+
+```typescript
+export function createFakeEvent(overrides?: Partial<DingTalkEvent>): DingTalkEvent;
+export function createTempWorkspace(prefix?: string): string;
+export function setupChannelFiles(dir: string, content?: {
+   memory?: string; session?: string; history?: string;
+}): void;
+```
+
+**设计原则：**
+- 复用项目中已有的 `FakeWorker`、`createAssistantMessage` 模式（源自 `subagent-phase1.test.ts`）
+- 复用已有的 `createFakePi` 模式（源自 `memory-lifecycle.test.ts`）
+- 复用已有的临时目录 `mkdtempSync` + `afterEach` cleanup 模式
+
+---
+
+## Phase 1：未覆盖模块的单元测试
+
+Phase 1 的三个测试文件之间无依赖关系，可以并行实现。
+
+### 1.1 `test/delivery.test.ts` — 消息投递状态机
+
+**测试对象：** `src/delivery.ts` — `ChannelDeliveryController`（通过 `createDingTalkContext` 导出）
+
+**Mock 策略：**
+- `FakeDingTalkBot` 记录所有 card/sendPlain 调用
+- `FakeChannelStore` 记录 logBotResponse 调用
+- `vi.useFakeTimers()` 控制 800ms 节流窗口（`MIN_UPDATE_INTERVAL_MS`）
+
+**测试用例：**
+
+#### describe("buildContext")
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 1 | 返回完整 DingTalkContext 接口 | 验证返回对象包含所有 10 个方法 | 每个方法存在且为 function 类型 |
+
+#### describe("respond / progress streaming")
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 2 | 累积 progress 文本 | 连续 respond("A"), respond("B"), flush | `streamToCard` 收到 `"A\n\nB"` |
+| 3 | 忽略空白文本 | respond("  ") | `streamToCard` 未调用 |
+| 4 | 节流 800ms | 两次 respond 间隔 <800ms | 窗口内只触发一次 streamToCard |
+| 5 | 节流窗口过后立即投递 | 推进 800ms+ 后第二次 respond | 第二次立即投递 |
+| 6 | shouldLog=true 时写入 store | respond("text", true) | `store.logBotResponse` 被调用 |
+| 7 | shouldLog=false 时不写 store | respond("text", false) | `store.logBotResponse` 未调用 |
+
+#### describe("respondPlain")
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 8 | 发送最终消息 | respondPlain("final") | `bot.sendPlain` 被调用，返回 true |
+| 9 | 失败返回 false | sendPlain 配置返回 false | respondPlain 返回 false |
+| 10 | 阻止进一步 progress | respondPlain 后再 respond | `streamToCard` 不再调用 |
+
+#### describe("replaceMessage / deleteMessage")
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 11 | replaceMessage 设置 finalize-with-fallback | replaceMessage("text"), flush | `finalizeCard` 被调用 |
+| 12 | deleteMessage 设置 silent 模式 | deleteMessage(), flush | `discardCard` 被调用 |
+
+#### describe("flush / close")
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 13 | flush 无待处理操作时立即返回 | 直接 flush | 同步完成 |
+| 14 | flush 等待进行中的投递 | respond 后立即 flush | flush 在投递完成后 resolve |
+| 15 | close 阻止后续操作 | close 后 respond/respondPlain | 均为 no-op |
+| 16 | close 幂等 | 两次 close | 不报错 |
+
+#### describe("error recovery")
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 17 | streamToCard 失败时 discard card | streamToCard 返回 false | `discardCard` 被调用 |
+
+---
+
+### 1.2 `test/command-extension.test.ts` — 命令扩展
+
+**测试对象：** `src/command-extension.ts` — `createCommandExtension`
+
+**Mock 策略：**
+- `FakeExtensionAPI` 捕获 registerCommand / sendMessage 调用
+- `vi.fn()` 模拟 options 中的回调（getCurrentModel, switchModel 等）
+- 构造 `FakeExtensionCommandContext`（包含 newSession, compact, sessionManager.getSessionId）
+
+**测试用例：**
+
+#### describe("registration")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 1 | 注册 session/model/new/compact 四个命令 | registerCommand 调用 4 次，每次名称正确 |
+
+#### describe("/session")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 2 | 渲染会话统计 | sendMessage 内容含 Session ID、model ref、token 数、cost |
+
+#### describe("/model")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 3 | 无参数显示当前模型和可用列表 | 输出含 "Current model" 和模型列表 |
+| 4 | 精确匹配切换模型 | `switchModel` 被调用，消息含 "已切换模型" |
+| 5 | 歧义引用报错 | 输出含 "匹配到多个模型" |
+| 6 | 未知引用报错 | 输出含 "未找到模型" |
+
+#### describe("/new")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 7 | 成功创建新会话 | `refreshSessionResources` 被调用，输出含新会话 ID |
+| 8 | 取消创建 | `refreshSessionResources` 未调用，输出含 "已取消" |
+
+#### describe("/compact")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 9 | 执行压缩 | 输出含 tokensBefore 和 summary |
+| 10 | 传递自定义指令 | compact 收到 customInstructions |
+
+#### describe("message format")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 11 | 使用正确 customType | sendMessage 参数含 `customType: "pipiclaw.command_result"` |
+
+---
+
+### 1.3 `test/dingtalk.test.ts` — DingTalk 协议层
+
+**测试对象：** `src/dingtalk.ts` — `DingTalkBot`
+
+**Mock 策略：**
+- `vi.mock("dingtalk-stream")` 替换 DWClient（FakeDWClient 记录 connect/disconnect/registerCallbackListener）
+- `vi.mock("axios")` 拦截所有 HTTP 请求（token、card、消息发送）
+- `FakeDingTalkHandler` 以 `vi.fn()` 实现 handleEvent / handleStop / handleBusyMessage
+- `vi.useFakeTimers()` 控制重连退避和 keep-alive
+- 真实临时目录用于 conversation metadata 持久化测试
+
+**测试用例（按功能分组）：**
+
+#### describe("message deduplication")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 1 | 新 messageId 正常处理 | markProcessed 返回 true |
+| 2 | 重复 messageId 跳过处理 | markProcessed 返回 false |
+| 3 | FIFO 超过 200 条后驱逐最早 ID | 被驱逐 ID 可再次通过 |
+| 4 | 相同 msgId 不同 messageId 去重 | 第二次跳过处理 |
+
+#### describe("message extraction and routing")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 5 | 提取 text.content 字段 | 文本内容正确 |
+| 6 | 提取 richText 内容 | 拼接后内容正确 |
+| 7 | 空消息返回空字符串 | 不抛错 |
+| 8 | DM 路由到 `dm_{senderId}` | channelId 格式正确 |
+| 9 | Group 路由到 `group_{conversationId}` | channelId 格式正确 |
+
+#### describe("authorization")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 10 | allowFrom 为空允许所有人 | handleEvent 被调用 |
+| 11 | allowFrom 不含发送者时忽略 | handleEvent 未调用 |
+| 12 | allowFrom 包含发送者时处理 | handleEvent 被调用 |
+
+#### describe("busy command routing")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 13 | /help → sendPlain 帮助文本 | 不经过 handler |
+| 14 | /stop → handler.handleStop | 调用 handleStop 并 sendPlain "Stopping" |
+| 15 | /steer msg → handleBusyMessage("steer") | mode 正确，文本正确 |
+| 16 | /followup msg → handleBusyMessage("followUp") | mode 正确 |
+| 17 | 纯文本 → 默认 steer | handleBusyMessage mode="steer" |
+
+#### describe("access token management")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 18 | 首次调用刷新 token | axios POST 到 oauth2/accessToken |
+| 19 | 过期前使用缓存 | 第二次不发 HTTP |
+| 20 | 并发刷新合并 | 两个并发调用只发一次 HTTP |
+
+#### describe("conversation metadata persistence")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 21 | 写入文件系统 | .channel-meta.json 内容正确 |
+| 22 | 从文件系统回退读取 | 内存清空后仍可读 |
+
+#### describe("channel queue")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 23 | 顺序处理工作项 | 3 个 enqueue 按序完成 |
+| 24 | stop 阻止后续处理 | 后续 enqueue 返回 false |
+| 25 | 超过队列上限时拒绝 | 返回 false |
+
+#### describe("lifecycle")
+
+| # | 用例 | 关键断言 |
+|---|------|----------|
+| 26 | stop 清理队列和 disconnect | disconnect 被调用 |
+
+---
+
+## Phase 2：集成测试
+
+集成测试放在 `test/integration/` 子目录下，验证模块间协作的正确性。三个文件之间无依赖，可并行实现。
+
+### 2.1 `test/integration/memory-lifecycle.test.ts` — 记忆生命周期完整链路
+
+**测试边界：** `MemoryLifecycle` → `session-memory` → `memory-consolidation` → `memory-files`
+
+**Mock 策略：**
+- **仅 mock `sidecar-worker.js`**（`runSidecarTask` 返回可控的 JSON 输出）
+- 真实文件系统 + 真实 memory-files I/O
+- 真实 MemoryLifecycle 实例（非 mock）
+
+**与现有 `memory-lifecycle.test.ts` 的区别：**
+现有测试 mock 了 `session-memory.js` 和 `memory-consolidation.js`，只验证调用是否发生。此集成测试让这些模块真实执行，仅 mock 最底层的 LLM 调用（sidecar-worker），验证文件最终状态。
+
+**测试用例：**
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 1 | turn 阈值触发 session memory 更新 | `noteCompletedAssistantTurn` N 次 | SESSION.md 被重写，包含 sidecar 返回的结构化内容 |
+| 2 | tool call 阈值触发 | `noteToolCall` M 次 + 1 次 turn | SESSION.md 被重写 |
+| 3 | 计数器更新后重置 | 触发后再计数 | 需要完整 N 次才再触发 |
+| 4 | session_before_compact 链式执行 | 触发事件 | 顺序：1) SESSION.md 更新 → 2) MEMORY.md 追加 → 3) HISTORY.md 追加 |
+| 5 | session_compact 触发后台维护 | 触发事件 | `runBackgroundMaintenance` 完成执行 |
+| 6 | 后台队列串行执行 | 快速触发两次 | 两个任务按序完成，文件状态一致 |
+| 7 | 合并失败不阻塞后续操作 | 第一次 sidecar 抛错 | 后续操作正常执行，不影响主流程 |
+| 8 | enabled=false 全部跳过 | 设置 disabled | 无文件读写发生 |
+
+---
+
+### 2.2 `test/integration/memory-consolidation.test.ts` — 合并管道完整链路
+
+**测试边界：** `runInlineConsolidation` / `runBackgroundMaintenance` → `sidecar-worker`（mock）→ `memory-files`（真实 I/O）
+
+**Mock 策略：**
+- 仅 mock `sidecar-worker.js`（返回可控的 JSON/Markdown 输出）
+- 真实文件系统（临时目录 + afterEach 清理）
+
+**测试用例：**
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 1 | 无实质消息时跳过 | 传入单条短消息 | 返回 `{ skipped: true }`，文件未修改 |
+| 2 | inline 合并追加 memory 条目 | LLM 返回 `{memoryEntries: ["fact1", "fact2"]}` | MEMORY.md 含时间戳标记的 fact1, fact2 |
+| 3 | inline 合并追加 history 块 | LLM 返回 `{historyBlock: "summary"}` | HISTORY.md 含新的时间戳区块 |
+| 4 | 使用 compaction boundary 切割消息 | sessionEntries 含 compaction marker | 只处理 boundary 之后的消息内容 |
+| 5 | 后台清理 MEMORY.md | 预填充 >8000 字符 | MEMORY.md 被 LLM 输出完整重写 |
+| 6 | 后台折叠 HISTORY.md | 预填充 >8 个 ## 区块 | 旧区块折叠，保留最近 4 个 |
+| 7 | 低于阈值时跳过 | 小文件 | 返回 `{cleaned: false, folded: false}` |
+| 8 | LLM 返回格式错误优雅降级 | sidecar 抛 SidecarParseError | 不崩溃，返回含错误信息的结果 |
+
+---
+
+### 2.3 `test/integration/recall-scoring.test.ts` — 记忆召回评分完整链路
+
+**测试边界：** `recallRelevantMemory` → `buildMemoryCandidates` → scoring → rendering
+
+**Mock 策略：**
+- 基本召回无需 mock（纯关键词评分）
+- rerank 测试 mock `sidecar-worker.js`
+- 真实文件系统
+
+**与现有 `memory-recall.test.ts` 的区别：**
+现有测试验证了候选构建和基础召回。此测试专注于评分精确性、优先级排序、渲染限制和 rerank 集成。
+
+**测试用例：**
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 1 | 候选按关键词相关性排序 | 多文件含不同关键词密度 | 高密度候选排在前面 |
+| 2 | session 候选优先级高于 channel memory | 相同关键词在两处出现 | session 候选分数更高 |
+| 3 | maxInjected 限制生效 | maxInjected=1 | 结果只含 1 个候选 |
+| 4 | maxChars 限制生效 | maxChars=100 | renderedText 长度 ≤100 |
+| 5 | 无记忆文件时返回空 | 空目录 | 空结果，无错误 |
+| 6 | 候选缓存避免重复读取 | 连续两次调用传同一 cache 对象 | 文件只读一次 |
+| 7 | rerank 模式调用 sidecar | rerankWithModel=true | sidecar 被调用，结果按 LLM 选择过滤 |
+
+---
+
+## Phase 3：端到端冒烟测试
+
+### `test/e2e/smoke.test.ts` — 完整消息处理管道
+
+**目标：** 验证从 DingTalk 事件接收到最终响应投递的完整链路，以最小化 mock 覆盖最大真实代码路径。
+
+#### 架构
+
+```
+DingTalkEvent (构造)
+    ↓
+createDingTalkContext() [真实 delivery.ts]
+    ↓
+ChannelRunner.run() [真实 agent.ts, mock 外部依赖]
+    ├─ recallRelevantMemory() [真实召回, 真实文件系统]
+    ├─ session.prompt() [mock AgentSession → 脚本化事件序列]
+    ├─ event subscription [真实事件处理逻辑]
+    └─ delivery [真实投递状态机 → FakeDingTalkBot]
+```
+
+#### Mock 层级
+
+**原则：** 只 mock 外部边界（LLM API、DingTalk API、pi-agent SDK），最大化内部模块的真实执行。
+
+| 组件 | 策略 | 说明 |
+|------|------|------|
+| `@mariozechner/pi-agent-core` Agent | mock `prompt()` 发射脚本化事件序列 | 模拟 Agent 的思考-工具-回复流程 |
+| `@mariozechner/pi-coding-agent` AgentSession | mock 构造器，delegate 到 mock Agent | 保留 session 管理逻辑 |
+| `@mariozechner/pi-coding-agent` SessionManager | 内存实现 | 无需真实文件 session 持久化 |
+| `@mariozechner/pi-coding-agent` ModelRegistry | 返回固定模型列表 | 避免 auth.json 依赖 |
+| `sidecar-worker.js` | 返回可控 LLM 输出 | 记忆合并/更新使用 mock |
+| DingTalkBot | **FakeDingTalkBot** | 记录所有调用，验证投递行为 |
+| 文件系统 | **真实临时目录** | 验证记忆文件最终状态 |
+| 计时器 | `vi.useFakeTimers()` | 控制投递节流 |
+
+#### 脚本化 Agent 行为
+
+Mock Agent 在 `prompt()` 被调用时按顺序发射以下事件：
+
+```typescript
+// 场景 1: 简单回复
+[
+  { type: "message_start", message: { role: "assistant" } },
+  { type: "message_end", message: assistantMsg("Here is the analysis...") },
+  { type: "turn_end", message: assistantMsg, toolResults: [] },
+]
+
+// 场景 2: 工具调用 + 回复
+[
+  { type: "message_start", message: { role: "assistant" } },
+  { type: "tool_execution_start", toolName: "read", toolCallId: "tc-1" },
+  { type: "tool_execution_end", toolCallId: "tc-1", result: "file content" },
+  { type: "message_end", message: assistantMsg("Analysis complete.") },
+  { type: "turn_end", message: assistantMsg, toolResults: [...] },
+]
+
+// 场景 3: 静默
+[
+  { type: "message_end", message: assistantMsg("[SILENT]") },
+  { type: "turn_end", message: assistantMsg("[SILENT]") },
+]
+
+// 场景 4: 错误
+prompt() → reject(new Error("Model overloaded"))
+```
+
+#### 测试用例
+
+| # | 用例 | 描述 | 关键断言 |
+|---|------|------|----------|
+| 1 | 简单消息处理并投递最终响应 | 构造 event → createDingTalkContext → run() | `bot.sendPlain` 或 `finalizeCard` 收到 assistant 文本 |
+| 2 | 记忆召回注入 prompt | 预填充 MEMORY.md 和 SESSION.md | Agent.prompt 的输入包含 `<runtime_context>` 包裹的召回内容 |
+| 3 | 工具执行事件链 | Agent 发射 tool_start → tool_end → message_end → turn_end | progress 投递包含工具名；最终 usage 正确累积 |
+| 4 | [SILENT] 响应走 deleteMessage | Agent 返回 "[SILENT]" | `bot.discardCard` 被调用，`sendPlain` 未调用 |
+| 5 | Agent 抛错走错误投递 | Agent prompt() reject | bot 收到包含错误提示的消息 |
+| 6 | /help 命令不触发 Agent run | 构造 /help 事件 | `bot.sendPlain` 收到帮助文本，Agent.prompt 未被调用 |
+| 7 | /session 命令返回会话信息 | 通过 command extension 处理 | 输出含 Session ID 和 token 统计 |
+| 8 | 忙碌时 steer 消息正确排队 | run 执行中调用 queueSteer | steer 文本被注入到 session.prompt 调用 |
+
+#### 冒烟测试的验证维度
+
+每个测试用例验证以下维度：
+
+1. **投递正确性**：bot 方法调用的参数和顺序
+2. **文件状态**：记忆文件（SESSION.md, MEMORY.md）的最终内容
+3. **Store 日志**：ChannelStore 记录的消息和响应
+4. **Usage 累积**：token 统计和 cost 计算
+5. **错误隔离**：错误不泄漏到不相关的 channel
+
+---
+
+## 实施顺序
+
+```
+Phase 0: test/helpers/ (4 个文件，前置依赖)
+   │
+   ▼
+Phase 1 (可并行):
+   ├─ test/delivery.test.ts          (~17 用例)
+   ├─ test/command-extension.test.ts  (~11 用例)
+   └─ test/dingtalk.test.ts           (~26 用例)
+   │
+   ▼
+Phase 2 (可并行):
+   ├─ test/integration/memory-lifecycle.test.ts      (~8 用例)
+   ├─ test/integration/memory-consolidation.test.ts  (~8 用例)
+   └─ test/integration/recall-scoring.test.ts        (~7 用例)
+   │
+   ▼
+Phase 3:
+   └─ test/e2e/smoke.test.ts (~8 用例)
+```
+
+## 新增文件清单
+
+| 文件路径 | 类型 | 预估用例数 |
+|----------|------|-----------|
+| `test/helpers/fake-bot.ts` | Helper | - |
+| `test/helpers/fake-store.ts` | Helper | - |
+| `test/helpers/fake-extension-api.ts` | Helper | - |
+| `test/helpers/fixtures.ts` | Helper | - |
+| `test/delivery.test.ts` | 单元测试 | 17 |
+| `test/command-extension.test.ts` | 单元测试 | 11 |
+| `test/dingtalk.test.ts` | 单元测试 | 26 |
+| `test/integration/memory-lifecycle.test.ts` | 集成测试 | 8 |
+| `test/integration/memory-consolidation.test.ts` | 集成测试 | 8 |
+| `test/integration/recall-scoring.test.ts` | 集成测试 | 7 |
+| `test/e2e/smoke.test.ts` | 冒烟测试 | 8 |
+| **合计** | **4 helpers + 7 tests** | **~85** |
+
+---
+
+## vitest.config.ts 调整
+
+```typescript
+export default defineConfig({
+   test: {
+      environment: "node",
+      include: ["test/**/*.test.ts"],  // 已支持子目录，无需修改
+      coverage: {
+         provider: "v8",
+         reporter: ["text", "json-summary", "html"],
+         reportsDirectory: "./coverage",
+         include: ["src/**/*.ts"],
+         // 排除难以测试的入口/常量文件
+         exclude: ["src/main.ts", "src/index.ts", "src/paths.ts"],
+         // Phase 3 完成后启用阈值
+         thresholds: {
+            statements: 70,
+            branches: 60,
+            functions: 70,
+            lines: 70,
+         },
+      },
+   },
+});
+```
+
+## 覆盖率目标
+
+| 阶段 | Statements | Branches | Functions | Lines |
+|------|-----------|----------|-----------|-------|
+| 当前（估算） | ~50% | ~40% | ~50% | ~50% |
+| Phase 1 完成后 | 65% | 55% | 65% | 65% |
+| Phase 2 完成后 | 70% | 60% | 70% | 70% |
+| Phase 3 完成后 | **75%+** | **65%+** | **75%+** | **75%+** |
+
+## 验证方式
+
+每个 Phase 完成后：
+
+1. `npm run test` — 全部测试通过（含新增）
+2. `npm run test:coverage` — 覆盖率达到阶段目标
+3. `npm run check` — lint + typecheck + test 全绿
+

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oyasmi/pipiclaw",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "An AI assistant runtime for coding and team workflows, with DingTalk AI Cards, sub-agents, memory, and scheduled events.",
 	"type": "module",
 	"bin": {
@@ -29,6 +29,7 @@
 		"lint": "biome check .",
 		"typecheck": "tsc --noEmit -p tsconfig.json",
 		"test": "vitest --run",
+		"test:coverage": "vitest --run --coverage",
 		"check": "npm run lint && npm run typecheck && npm run test",
 		"prepublishOnly": "npm run clean && npm run build && npm run check"
 	},
@@ -47,6 +48,7 @@
 		"@biomejs/biome": "2.3.5",
 		"@types/diff": "^7.0.2",
 		"@types/node": "^24.3.0",
+		"@vitest/coverage-v8": "^3.2.4",
 		"shx": "^0.4.0",
 		"typescript": "^5.7.3",
 		"vitest": "^3.2.4"