@oyasmi/pipiclaw 0.5.1 → 0.5.2

package/docs/proj-review.md

@@ -1,188 +0,0 @@
-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 拆分 + 中文召回修复 + 编排层测试补全，这三项能同时降低风险和提升产品质量。