@oyasmi/pipiclaw 0.3.5 → 0.5.0

package/docs/proj-review.md

@@ -0,0 +1,188 @@
+Pipiclaw 项目全面审查报告
+
+  项目概述
+
+  Pipiclaw 是一个基于 @mariozechner/pi-coding-agent SDK 的 DingTalk AI 编码助手运行时，提供持久化记忆、子 Agent 委派、定时事件等企业级功能。当前 v0.4.0，约 6,844 行
+  TypeScript，22 个测试文件。
+
+  ---
+  一、当前设计/实现问题
+
+  1. 代码重复严重
+
+  extractJsonObject() 在 3 处重复实现：
+  - memory-consolidation.ts
+  - memory-recall.ts
+  - session-memory.ts
+
+  clipText() 在 3 处重复：
+  - session-memory.ts
+  - tools/subagent.ts
+  - memory-recall.ts
+
+  Markdown section 解析存在 3 个变体：
+  - splitMarkdownSections() (## 级别) — memory-files.ts
+  - splitLevelOneSections() — tools/subagent.ts
+  - splitLevelOneSections() — memory-candidates.ts
+
+  建议： 提取到 src/utils/ 共享模块，统一实现。
+
+  ---
+  2. 核心模块职责过重
+
+  ┌───────────────────┬──────┬────────────────────────────────────────────────────────────────────────────┐
+  │       文件        │ 行数 │                                    问题                                    │
+  ├───────────────────┼──────┼────────────────────────────────────────────────────────────────────────────┤
+  │ agent.ts          │ 907  │ Session 管理 + 事件订阅 + 消息格式化 + 记忆生命周期 + 工具配置全部混在一起 │
+  ├───────────────────┼──────┼────────────────────────────────────────────────────────────────────────────┤
+  │ dingtalk.ts       │ 881  │ 协议处理 + 消息队列 + AI Card 状态 + Token 缓存耦合                        │
+  ├───────────────────┼──────┼────────────────────────────────────────────────────────────────────────────┤
+  │ sub-agents.ts     │ 511  │ 发现 + 配置解析 + 验证 + 合并逻辑混杂                                      │
+  ├───────────────────┼──────┼────────────────────────────────────────────────────────────────────────────┤
+  │ tools/subagent.ts │ ~600 │ 配置解析 + 上下文构建 + 工具过滤 + Worker 创建 + 事件处理 + 预算跟踪       │
+  └───────────────────┴──────┴────────────────────────────────────────────────────────────────────────────┘
+
+  agent.ts 中的 ChannelRunner 承担了太多职责，既是会话编排器，又是事件分发器和记忆协调器。
+
+  ---
+  3. 类型安全缺陷
+
+  - 大量 as any 类型断言：agent.ts 的事件处理中频繁使用 event as any，缺少正确的联合类型定义
+  - noExplicitAny: Off：biome 配置关闭了 any 检查，降低了类型安全性
+  - JSON 提取使用正则：extractJsonObject() 基于正则匹配 {...} 非常脆弱，嵌套 JSON、字符串中的花括号等边界情况容易出错
+  - Partial 配置合并：使用展开运算符合并配置，缺少运行时校验
+
+  ---
+  4. 记忆系统设计问题
+
+  4.1 召回算法过于简单
+
+  当前的 token overlap 打分方式本质上是关键词匹配：
+  - 按空格分词，匹配命中数累加
+  - 不理解语义相似性（如 "登录" 和 "认证" 无法关联）
+  - 中文分词完全缺失（中文 token 化基于 \W+ 分割，对中文几乎无效）
+
+  4.2 合并管道缺少超时保护
+
+  runInlineConsolidation() 和 runBackgroundMaintenance() 依赖 LLM sidecar worker，但没有超时机制。如果 LLM 响应缓慢或挂起，整个管道会无限等待。
+
+  4.3 记忆候选者无缓存
+
+  buildMemoryCandidates() 每次调用都读取 4 个文件并解析。在一个 run 内可能被多次调用（recall + consolidation），但每次都从磁盘重新读取。
+
+  4.4 SESSION.md 的 LLM 更新缺乏一致性保证
+
+  session memory 更新依赖 LLM 生成结构化 JSON，但 LLM 输出格式不稳定，可能导致 SESSION.md 内容退化或丢失关键信息。
+
+  ---
+  5. 测试覆盖缺口
+
+  未测试的关键路径：
+
+  ┌───────────────────────────────────┬──────────────────────────────┐
+  │               模块                │             影响             │
+  ├───────────────────────────────────┼──────────────────────────────┤
+  │ agent.ts (ChannelRunner 核心编排) │ 最核心的业务逻辑完全没有单测 │
+  ├───────────────────────────────────┼──────────────────────────────┤
+  │ dingtalk.ts (连接/重连/消息路由)  │ 生产环境最易出问题的部分     │
+  ├───────────────────────────────────┼──────────────────────────────┤
+  │ main.ts (启动流程/配置校验)       │ 首次启动失败无法快速定位     │
+  ├───────────────────────────────────┼──────────────────────────────┤
+  │ delivery.ts (响应投递)            │ 消息丢失/重复风险            │
+  ├───────────────────────────────────┼──────────────────────────────┤
+  │ 完整消息流的集成测试              │ 无法验证端到端行为           │
+  └───────────────────────────────────┴──────────────────────────────┘
+
+  现有测试质量良好（工厂模式、临时目录清理、边界情况），但覆盖面集中在工具层和记忆文件 I/O，编排层几乎空白。
+
+  ---
+  6. 错误处理与韧性
+
+  - 用户消息大小无限制：恶意或意外的超大消息可以直接注入 prompt
+  - 并发控制不够健壮：每个 channel 的 channelStates 依赖简单的状态标记，竞态条件下可能出现重复 run
+  - 磁盘写入没有容量检查：log.jsonl 无上限增长，memory 文件合并失败时没有回退机制
+  - 子 Agent 异常传播不清晰：子 Agent 超时/失败的错误信息格式化后丢失了原始堆栈
+
+  ---
+  7. 架构耦合
+
+  - DingTalk 耦合深入核心：DingTalkContext 类型贯穿 agent.ts、delivery.ts、commands.ts，使得支持其他 IM 平台（飞书、企业微信）成本很高
+  - 记忆系统与文件系统强绑定：所有记忆操作直接读写 Markdown 文件，无抽象层，难以切换到数据库或向量存储
+  - 配置路径硬编码：paths.ts 中的 ~/.pi/pipiclaw/ 路径硬编码，不利于多实例部署
+
+  ---
+  8. 其他问题
+
+  - release.yml 使用 Node 20，但项目要求 >=22，CI 测试也只跑 22/24
+  - attach.ts 是空壳：抛出 not implemented 错误，但已导出为公开 API
+  - shell-escape.ts 仅 7 行：功能过于简单，不处理特殊字符（如 \0、unicode）
+  - 无日志轮转：log.jsonl 和 context.jsonl 会无限增长
+
+  ---
+  二、进一步迭代方向
+
+  高优先级
+
+  1. 拆分 ChannelRunner
+    - 将 agent.ts 拆为：session-orchestrator.ts（会话生命周期）、event-dispatcher.ts（事件流处理）、tool-configurator.ts（工具组装）
+    - 使核心编排可测试
+  2. 引入传输层抽象
+    - 定义 Transport 接口（send/receive/stream），DingTalk 作为一个实现
+    - 为未来支持飞书、Slack、CLI 等铺路
+  3. 修复中文记忆召回
+    - 当前分词对中文无效，需引入分词库（如 jieba-wasm）或转向 embedding 向量召回
+    - 至少作为 rerank 阶段的补充
+  4. 补全编排层测试
+    - 为 ChannelRunner 的 run() 流程编写集成测试
+    - Mock AgentSession，验证记忆召回 → prompt 构建 → 事件处理的完整链路
+  5. 提取共享工具函数
+    - extractJsonObject()、clipText()、splitMarkdownSections() 统一到 src/utils/
+
+  中优先级
+
+  6. 记忆系统改进
+    - 为 sidecar worker 添加超时（30s-60s）
+    - 记忆候选者添加 run 级别缓存
+    - SESSION.md 更新增加 schema 校验和回退机制
+    - 考虑引入 embedding 存储做语义检索
+  7. 添加防护措施
+    - 用户消息长度限制
+    - log.jsonl 轮转（按大小或时间）
+    - 磁盘写入前检查可用空间
+    - 并发 run 的互斥锁（替代状态标记）
+  8. 类型安全加固
+    - 定义 AgentEvent 联合类型，消除 as any
+    - 启用 noExplicitAny，逐步修复
+    - JSON 提取改用 proper parser（如先找到平衡的 {} 再 JSON.parse）
+  9. 可观测性增强
+    - 结构化日志（JSON 格式）替代当前的 chalk 彩色输出
+    - 关键操作添加 metrics（记忆召回耗时、合并频率、子 Agent 使用率）
+    - 健康检查端点
+
+  低优先级
+
+  10. 记忆存储抽象
+    - 定义 MemoryStore 接口（read/write/query），当前文件系统作为默认实现
+    - 为未来 SQLite / 向量数据库做准备
+  11. 子 Agent 改进
+    - 支持子 Agent 间通信
+    - 子 Agent 结果的结构化输出（而非纯文本）
+    - 子 Agent 池化（避免每次创建新实例）
+  12. release.yml 修复
+    - Node 版本改为 22，与 engines 字段一致
+  13. 文档补充
+    - 架构决策记录（ADR）
+    - 记忆系统的运维指南（如何手动清理/重建）
+    - 子 Agent 开发指南
+
+  ---
+  三、总结
+
+  Pipiclaw 在 v0.4.0 阶段已具备清晰的分层架构、完善的记忆管道、灵活的子 Agent 系统。主要短板集中在：
+
+  1. 核心编排层 (agent.ts) 过于臃肿且缺少测试 — 这是最大风险
+  2. 记忆召回对中文场景基本失效 — 作为面向钉钉的中文产品这是关键缺陷
+  3. DingTalk 耦合过深 — 限制了平台扩展能力
+  4. 代码重复和类型安全 — 影响长期维护效率
+
+  建议下一阶段优先处理 ChannelRunner 拆分 + 中文召回修复 + 编排层测试补全，这三项能同时降低风险和提升产品质量。

package/docs/subagent/pi-subagent-analyse.txt

@@ -0,0 +1,190 @@
+多 Agent / Sub-Agent 模式分析
+
+  一、pi-coding-agent 当前支持到什么程度？
+
+  当前已有完整但处于 example 状态的 sub-agent 实现：
+
+  1. 进程级隔离的 SubAgent 扩展 (packages/coding-agent/examples/extensions/subagent/)
+
+  这是一个完整的 Extension，支持三种执行模式：
+
+  ┌──────────┬────────────────────────────────────────────────┬────────────────────────────────┐
+  │   模式   │                      语法                      │              描述              │
+  ├──────────┼────────────────────────────────────────────────┼────────────────────────────────┤
+  │ Single   │ { agent: "name", task: "..." }                 │ 单个子代理执行单个任务         │
+  ├──────────┼────────────────────────────────────────────────┼────────────────────────────────┤
+  │ Parallel │ { tasks: [{agent, task}, ...] }                │ 最多 8 个任务，并发度 4        │
+  ├──────────┼────────────────────────────────────────────────┼────────────────────────────────┤
+  │ Chain    │ { chain: [{agent, task: "...{previous}..."}] } │ 链式执行，前一个输出注入后一个 │
+  └──────────┴────────────────────────────────────────────────┴────────────────────────────────┘
+
+  实现方式是 spawn 独立 pi 子进程（--mode json --no-session），通过 NDJSON
+  事件流收集结果。每个子代理有完全独立的 context window。
+
+  2. Agent 发现系统 (agents.ts)
+
+  - 从 ~/.pi/agents/*.md（用户级）和 .pi/agents/*.md（项目级）加载 Agent 定义
+  - 每个 Agent 是一个带 YAML frontmatter 的 Markdown 文件，定义
+  name、description、tools、model、systemPrompt
+  - 项目级 Agent 覆盖同名的用户级 Agent
+
+  3. 轻量 Worker Agent 模式 (pipiclaw/src/memory-consolidation.ts:208-243)
+
+  pipiclaw 已经在用一种极简 sub-agent 模式：直接在进程内 new Agent() 创建一个无工具、纯文本生成的
+  worker，用于内存整理。这是最低开销的 sub-agent 形态。
+
+  4. 底层基础设施
+
+  - Agent 类完全支持独立实例化，构造参数灵活（tools、model、systemPrompt、thinkingLevel 等均可定制）
+  - AgentSession 的 Extension 系统提供 60+ 事件钩子，可以拦截/增强工具调用
+  - registerTool() API 可以在运行时注入新工具（包括"调用子代理"这个工具）
+
+  总结：核心能力已就绪，但 subagent 扩展还在 examples/ 目录，不是标准内置功能。
+
+  ---
+  二、Multi-Agent vs Sub-Agent 的区别
+
+  这是两种根本不同的协作范式：
+
+  Sub-Agent（主从模式）               Multi-Agent（对等协作模式）
+  ┌───────────┐                     ┌──────────┐    ┌──────────┐
+  │  主 Agent  │                     │ Agent A  │◄──►│ Agent B  │
+  │           │                     │  (编码)   │    │  (测试)   │
+  │  ┌──────┐ │                     └──────────┘    └──────────┘
+  │  │子Agent│ │                          ▲               ▲
+  │  │(工具) │ │                          │               │
+  │  └──────┘ │                     ┌──────────┐         │
+  └───────────┘                     │ 协调层    │◄────────┘
+                                    └──────────┘
+
+  ┌──────────┬──────────────────────────────────────────┬────────────────────────────────────────┐
+  │   维度   │                Sub-Agent                 │              Multi-Agent               │
+  ├──────────┼──────────────────────────────────────────┼────────────────────────────────────────┤
+  │ 关系     │ 主从/调用方-被调用方                     │ 对等/协作                              │
+  ├──────────┼──────────────────────────────────────────┼────────────────────────────────────────┤
+  │ 发起方   │ 主 Agent 通过 tool call 发起             │ 协调层编排，或 Agent 互相触发          │
+  ├──────────┼──────────────────────────────────────────┼────────────────────────────────────────┤
+  │ 上下文   │ 子 Agent 只看到主 Agent 传入的 task 描述 │ 每个 Agent 有自己的完整上下文          │
+  ├──────────┼──────────────────────────────────────────┼────────────────────────────────────────┤
+  │ 生命周期 │ 短暂——完成任务即销毁                     │ 长期运行，可持续对话                   │
+  ├──────────┼──────────────────────────────────────────┼────────────────────────────────────────┤
+  │ 结果流向 │ 子 → 主（返回文本结果）                  │ 双向或多向（共享状态/消息传递）        │
+  ├──────────┼──────────────────────────────────────────┼────────────────────────────────────────┤
+  │ 决策权   │ 主 Agent 决定何时调用、给什么任务        │ 各 Agent 可自主决策                    │
+  ├──────────┼──────────────────────────────────────────┼────────────────────────────────────────┤
+  │ 复杂度   │ 低（现有 tool 框架直接支持）             │ 高（需要消息总线、共享状态、冲突解决） │
+  ├──────────┼──────────────────────────────────────────┼────────────────────────────────────────┤
+  │ 典型场景 │ "帮我搜索这个"、"审查这段代码"           │ "一个写代码、一个写测试、一个做Review" │
+  └──────────┴──────────────────────────────────────────┴────────────────────────────────────────┘
+
+  对 pipiclaw 的实际建议：先做 Sub-Agent，这是投入产出比最高的路径。 Multi-Agent
+  的协调成本和调试复杂度目前不适合 DingTalk bot 场景。
+
+  ---
+  三、在 pipiclaw 中如何设计和规划
+
+  Phase 1：内置 Sub-Agent 工具（短期，投入小）
+
+  将 examples/extensions/subagent/ 的核心能力集成到 pipiclaw 中，但做适配：
+
+  pipiclaw 适配要点：
+  1. 不能 spawn `pi` CLI 子进程（pipiclaw 无 CLI）
+     → 改为进程内 new Agent() + 注入精简 tool 集
+  2. Agent 发现：复用 .pi/agents/*.md 机制
+     → 或从 AGENTS.md 中解析 agent 定义
+   3. 输出回传：子 Agent 结果直接返回给主 Agent 的 tool result
+  4. 资源限制：子 Agent 的 token 消耗需要计入总量
+
+  核心实现路径：
+
+  // pipiclaw 的 sub-agent tool 骨架
+  function createSubAgentTool(parentConfig: ChannelConfig): AgentTool {
+    return {
+      name: "subagent",
+      execute: async (toolCallId, { agent, task }, signal) => {
+        const agentConfig = discoverAgents(workDir, "both")
+          .agents.find(a => a.name === agent);
+
+        // 进程内创建，比 spawn 更轻量
+        const worker = new Agent({
+          initialState: {
+            systemPrompt: agentConfig.systemPrompt,
+            model: agentConfig.model ?? parentModel,
+            tools: resolveTools(agentConfig.tools), // bash, read, write 等
+          },
+          getApiKey,
+          beforeToolCall, // 可复用主 Agent 的安全拦截
+        });
+
+        await worker.prompt(task);
+        await worker.waitForIdle();
+        return extractResult(worker);
+      }
+    };
+  }
+
+  Phase 2：Parallel Sub-Agent 支持（中期）
+
+  当 LLM 判断任务可分解时，允许并行派发多个 sub-agent：
+
+  - 实现 parallel 模式（复用 examples 中的 mapWithConcurrencyLimit）
+  - 添加 chain 模式用于流水线式任务
+
+  Phase 3：Agent 自主决策触发（长期，实验性）
+
+  让主 Agent 学会在适当场景自动使用 sub-agent，而不是用户手动指定：
+
+  - 在 SOUL.md 中定义策略（如"代码修改量超过 3 个文件时，自动启用 sub-agent 做代码审查"）
+  - 或者通过 Extension 监听 tool call 事件，在特定条件下自动触发
+
+  ---
+  四、目标效果
+
+  ┌──────────────┬─────────────────────────────────────────┬────────────────────────────────────┐
+  │     场景     │              无 Sub-Agent               │            有 Sub-Agent            │
+  ├──────────────┼─────────────────────────────────────────┼────────────────────────────────────┤
+  │ 复杂代码任务 │ 主 Agent 在单一 context                 │ 拆分子任务，每个子 Agent           │
+  │              │ 中处理所有文件，容易超长截断            │ 聚焦具体文件/模块                  │
+  ├──────────────┼─────────────────────────────────────────┼────────────────────────────────────┤
+  │ 代码审查     │ 改完即结束                              │ 主 Agent 改代码 → sub-agent 自动   │
+  │              │                                         │ review → 反馈改进                  │
+  ├──────────────┼─────────────────────────────────────────┼────────────────────────────────────┤
+  │ 信息搜集     │ 串行搜索，效率低                        │ 并行派 3 个 sub-agent              │
+  │              │                                         │ 同时搜不同方向                     │
+  ├──────────────┼─────────────────────────────────────────┼────────────────────────────────────┤
+  │ 测试         │ 手动让 Agent 跑测试                     │ 代码写完后 sub-agent               │
+  │              │                                         │ 自动运行测试并汇总                 │
+  ├──────────────┼─────────────────────────────────────────┼────────────────────────────────────┤
+  │ 长对话场景   │ context window 膨胀，质量下降           │ 重计算子任务卸载到独立 context 的  │
+  │              │                                         │ sub-agent                          │
+  └──────────────┴─────────────────────────────────────────┴────────────────────────────────────┘
+
+  核心价值：context window 分治。 DingTalk bot
+  场景中，用户可能在一个频道里提出复杂的多步骤需求，sub-agent 让主 Agent
+  可以将重计算子任务卸载，保持主 context 的精简和高质量。
+
+  ---
+  五、怎样决定是否启用 Sub-Agent
+
+  不应该让用户手动决定——由 Agent 自主判断，但需要给出决策框架：
+
+  适合启用 sub-agent 的条件（可写入 SOUL.md 作为 Agent 指令）：
+
+  1. 任务可分解性：当前任务可以拆分成独立子问题（如"搜索 A 并搜索 B"→ parallel）
+  2. context 压力：主 context 已接近上限，或需要处理大量代码文件
+  3. 专业化需求：任务需要不同"人格"（如编码 Agent vs 审查 Agent）
+  4. 耗时操作：长时间运行的 bash 命令或大范围文件搜索
+  5. 质量保证：写代码后希望有独立视角的审查
+
+  不适合使用的场景：
+
+  1. 简单问答：用户问一个简单问题，没有调用开销的必要
+  2. 上下文密集：子任务严重依赖当前对话上下文，传递成本高
+  3. 交互式任务：需要频繁和用户确认的任务（sub-agent 是批处理模式）
+  4. 成本敏感：每个 sub-agent 都有额外的 token 开销
+
+  实现建议：在 pipiclaw 中，初期可以不做自动决策，而是：
+  - 在 AGENTS.md 中定义可用的 Agent 列表和各自能力
+  - 在 SOUL.md 中告诉主 Agent "当遇到 X 场景时，可以使用 subagent 工具"
+  - 让 LLM 基于指令自主判断——这本身就是 LLM 擅长的决策
+

package/docs/subagent/pi-subagent-design.txt

@@ -0,0 +1,266 @@
+Sub-Agent 集成方案
+
+  整体思路
+
+  现有 examples/extensions/subagent/ 是通过 spawn pi CLI 子进程 实现隔离的，但 pipiclaw 是长驻
+  DingTalk bot 进程，没有 CLI 入口。所以核心改造是：用进程内 new Agent() 替代 subprocess
+  spawn，复用同一个 Executor（sandbox）实例。
+
+  现有 subagent (pi-coding-agent CLI):
+    主 Agent → spawn("pi", ["--mode json"]) → 子进程 Agent → stdout NDJSON → 解析
+
+  pipiclaw 方案:
+    主 Agent → tool call "subagent" → new Agent({tools, systemPrompt}) → 事件订阅 → 结果收集
+
+  需要做的事情（共 5 件）
+
+  ---
+  一、新建 src/tools/subagent.ts — Sub-Agent 工具实现
+
+  这是核心，作为一个 AgentTool 注册给主 Agent，LLM 通过 tool call 触发。
+
+  关键设计：
+
+  // src/tools/subagent.ts 骨架
+
+  interface SubAgentToolOptions {
+    executor: Executor;              // 复用父 Agent 的 sandbox
+    getModel: () => Model<Api>;      // 当前活跃模型
+    resolveApiKey: (model: Model<Api>) => Promise<string>;
+    workspaceDir: string;            // Agent 定义文件搜索根
+    channelDir: string;              // 当前频道目录
+  }
+
+  // 工具 schema — 简化版，只支持 single 模式（Phase 1）
+  const subagentSchema = Type.Object({
+    label: Type.String({ description: "Brief description of what this subagent task does" }),
+    agent: Type.String({ description: "Name of the agent to invoke (from .pi/agents/)" }),
+    task: Type.String({ description: "Task description for the subagent" }),
+  });
+
+  执行流程：
+
+  1. 发现 Agent — 从 {workspaceDir}/.pi/agents/ 和 {channelDir}/agents/ 加载 .md 文件，解析
+  frontmatter 得到 AgentConfig
+  2. 构造工具集 — 根据 AgentConfig.tools 字段（如 "bash,read"），从已有的
+  createReadTool/createBashTool/... 中按名过滤
+  3. 创建 Agent 实例 — new Agent({initialState: {systemPrompt, model, tools}, ...})
+  4. 订阅事件收集结果 — 通过 agent.subscribe() 监听 message_end 事件，累积输出
+  5. 等待完成 — await agent.waitForIdle()，提取最终文本输出返回给主 Agent
+  6. 传递 abort 信号 — 父 Agent 被取消时，子 Agent 也跟着取消
+
+    与现有 memory-consolidation 中 runWorkerPrompt 的区别：
+
+  ┌──────────┬────────────────────────────┬─────────────────────────────────┐
+  │   维度   │      runWorkerPrompt       │          subagent tool          │
+  ├──────────┼────────────────────────────┼─────────────────────────────────┤
+  │ tools    │ []（纯文本生成）           │ 按配置注入 bash/read/edit/write │
+  ├──────────┼────────────────────────────┼─────────────────────────────────┤
+  │ 触发方   │ 系统自动（compaction 时）  │ LLM 自主决策（tool call）       │
+  ├──────────┼────────────────────────────┼─────────────────────────────────┤
+  │ 输出     │ 内部消费（更新 MEMORY.md） │ 返回给主 Agent 作为 tool result │
+  ├──────────┼────────────────────────────┼─────────────────────────────────┤
+  │ 生命周期 │ fire-and-forget            │ 可被 abort                      │
+  └──────────┴────────────────────────────┴─────────────────────────────────┘
+
+  ---
+  二、新建 src/agents.ts — Agent 发现与加载
+
+  从 examples/extensions/subagent/agents.ts 提取核心逻辑，适配 pipiclaw 的目录结构：
+
+  搜索路径（优先级从低到高）：
+    ~/.pi/agents/*.md          → 用户全局 Agent 定义
+    {workspaceDir}/.pi/agents/*.md → 项目级 Agent 定义（覆盖同名）
+
+  这个文件基本可以直接复用 examples/extensions/subagent/agents.ts 的 discoverAgents() +
+  loadAgentsFromDir() + frontmatter 解析逻辑，只需要：
+  - 去掉对 getAgentDir() 的依赖（pipiclaw 有自己的目录约定）
+  - 把 findNearestProjectAgentsDir 简化为直接用已知的 workspaceDir
+
+  Agent 定义文件格式（与现有一致）：
+
+  ---
+  name: reviewer
+  description: Reviews code changes for quality and correctness
+  model: claude-sonnet-4-20250514
+  tools: bash,read
+  ---
+
+  You are a code reviewer. Given a task, review the relevant code...
+
+  ---
+  三、修改 src/tools/index.ts — 工具注册集成
+
+  当前 createPipiclawTools() 返回固定的 4 个工具。需要改为：
+
+  // 改造前
+  export function createPipiclawTools(executor: Executor): AgentTool<any>[] {
+    return [createReadTool(executor), createBashTool(executor), createEditTool(executor),
+  createWriteTool(executor)];
+  }
+
+    // 改造后
+  export function createPipiclawTools(executor: Executor): AgentTool<any>[] {
+    return [createReadTool(executor), createBashTool(executor), createEditTool(executor),
+  createWriteTool(executor)];
+  }
+
+  // 新增：按名称过滤工具子集（供 sub-agent 使用）
+  export function filterToolsByName(allTools: AgentTool<any>[], names: string[]): AgentTool<any>[] {
+    const nameSet = new Set(names);
+    return allTools.filter(t => nameSet.has(t.name));
+  }
+
+  // 新增：创建包含 subagent 的完整工具集（供主 Agent 使用）
+  export function createPipiclawToolsWithSubAgent(
+    executor: Executor,
+    subagentOptions: SubAgentToolOptions,
+  ): AgentTool<any>[] {
+    const baseTools = createPipiclawTools(executor);
+    const subagentTool = createSubAgentTool(subagentOptions, baseTools);
+    return [...baseTools, subagentTool];
+  }
+
+  关键设计决策：sub-agent 不能递归调用 subagent 工具。 createSubAgentTool 内部只传入 baseTools（4
+  个基础工具），不包含 subagent 自身，天然防止递归。
+
+  ---
+  四、修改 src/agent.ts (ChannelRunner) — 接入主流程
+
+  在 ChannelRunner 构造器中，将 subagent 工具加入主 Agent 的工具集：
+
+  // agent.ts 中现有的工具创建：
+  // const tools = createPipiclawTools(executor);
+
+  // 改为：
+  const baseTools = createPipiclawTools(executor);
+  const subagentTool = createSubAgentTool({
+    executor,
+    getModel: () => this.activeModel,
+    resolveApiKey: (model) => getApiKeyForModel(this.modelRegistry, model),
+    workspaceDir: this.workspaceDir,
+    channelDir,
+  }, baseTools);
+  const tools = [...baseTools, subagentTool];
+
+  变更范围极小 — 只改工具数组的组装方式，Agent 构造、AgentSession 构造、Extension 注册等全部不变。
+
+    ---
+  五、修改 src/prompt-builder.ts — 告诉 LLM 如何使用 sub-agent
+
+  在 buildAppendSystemPrompt() 中新增一个 section，告知主 Agent sub-agent 的存在和使用策略：
+
+  ## Sub-Agents
+
+  You have a `subagent` tool that delegates tasks to specialized agents.
+  Available agents are discovered from `.pi/agents/*.md` files.
+
+  Use sub-agents when:
+  - The task can be decomposed into independent sub-problems
+  - You need a fresh context window for a heavy computation
+  - A specialized agent (reviewer, researcher) would produce better results
+  - The current context is getting long and you want to offload work
+
+  Do NOT use sub-agents for:
+  - Simple questions or short tasks
+  - Tasks that heavily depend on current conversation context
+  - Interactive tasks requiring user confirmation
+
+  Each sub-agent runs with an isolated context — it cannot see your conversation history.
+  You must provide sufficient context in the `task` parameter.
+
+  同时，如果 workspace 下存在 .pi/agents/ 目录，可以在 prompt 中列出可用 Agent 名称和描述，帮助 LLM
+  决策。
+
+  ---
+  数据流总览
+
+  用户 (DingTalk)
+    │
+    ▼
+  主 Agent (ChannelRunner)
+    │ tools: [read, bash, edit, write, subagent]
+    │
+    │  LLM 决定调用 subagent({agent: "reviewer", task: "Review PR #42"})
+    │
+    ▼
+  subagent tool execute()
+    │
+    ├─ discoverAgents(workspaceDir) → 找到 "reviewer" 配置
+    │
+    ├─ filterToolsByName(baseTools, ["bash", "read"]) → 子工具集
+    │
+    ├─ new Agent({
+    │    systemPrompt: reviewer.systemPrompt,
+    │    model: reviewer.model ?? parentModel,
+    │    tools: filteredTools,
+    │    thinkingLevel: "off",
+    │  })
+    │
+    ├─ agent.subscribe(event => { 收集 message_end 事件 })
+    │
+    ├─ await agent.prompt(task)
+    ├─ await agent.waitForIdle()
+    │
+    ├─ 提取最终文本输出
+    │
+    └─ return { content: [{type: "text", text: output}] }
+        │
+        ▼
+  主 Agent 收到 tool result，继续推理
+
+  ---
+  需要注意的设计要点
+
+  1. 工具实例共享安全性
+
+  sub-agent 和主 Agent 共享同一个 Executor 实例。这是安全的，因为：
+  - Executor.exec() 是无状态的（每次 spawn 新进程）
+  - Docker sandbox 本身提供了文件系统隔离
+  - Host 模式下两者操作相同的工作目录，这是预期行为
+
+  2. API Key 与 Model 解析
+
+  sub-agent 可以指定不同的 model（如主 Agent 用 opus，子 Agent 用 sonnet 降低成本）。API key
+  通过同一个 ModelRegistry 解析，不需要额外配置。
+
+  3. Token 消耗可见性
+
+  sub-agent 的 token 消耗不会自动体现在主 Agent 的 usage 统计中。可以在 tool result 的 details
+  中附带 usage 信息，并在 /session 命令中展示。这个是增强项，不阻塞 Phase 1。
+
+  4. 超时与取消
+
+  - 主 Agent 的 AbortSignal 通过 tool execute 的 signal 参数传入
+  - sub-agent 创建时用同一个 signal，或创建子 AbortController 链接到父 signal
+  - DingTalk 用户发新消息中断时，整条链路都能正确取消
+
+  5. Phase 2 扩展路径
+
+  Phase 1 只做 single 模式。后续扩展：
+  - Parallel 模式：schema 加 tasks 数组，复用 mapWithConcurrencyLimit 模式，并发创建多个 Agent
+  - Chain 模式：schema 加 chain 数组，顺序执行，{previous} 占位符替换
+  - Streaming 更新：通过 onUpdate 回调实时推送子 Agent 进度到 DingTalk 卡片
+
+  ---
+  文件变更清单
+
+
+  ┌───────────────────────┬──────┬────────────────────────────────────────────────┐
+  │         文件          │ 操作 │                      说明                      │
+  ├───────────────────────┼──────┼────────────────────────────────────────────────┤
+  │ src/tools/subagent.ts │ 新建 │ Sub-agent 工具核心实现                         │
+  ├───────────────────────┼──────┼────────────────────────────────────────────────┤
+  │ src/agents.ts         │ 新建 │ Agent 发现与加载（从 examples 提取）           │
+  ├───────────────────────┼──────┼────────────────────────────────────────────────┤
+  │ src/tools/index.ts    │ 修改 │ 新增 filterToolsByName，导出 subagent 相关函数 │
+  ├───────────────────────┼──────┼────────────────────────────────────────────────┤
+  │ src/agent.ts          │ 修改 │ ChannelRunner 中组装工具时加入 subagent        │
+  ├───────────────────────┼──────┼────────────────────────────────────────────────┤
+  │ src/prompt-builder.ts │ 修改 │ 新增 sub-agent 使用指南 section                │
+  └───────────────────────┴──────┴────────────────────────────────────────────────┘
+
+  不需要改动的部分： AgentSession 构造、Extension
+  系统、MemoryLifecycle、DingTalkBot、DeliveryController、Store、Sandbox — 全部保持不变。
+
+  这个方案的核心优势是侵入性极低：本质上就是多注册了一个 tool，其余架构完全不动。