Skip to main content

WeaveAgentImplementationPlan

WeaveAgent 实现计划

从骨架 Agent/WeaveAgent.py 到"能跑起来"的工程落地规划，与 Agent/WeaveAgentDesign.md 配套。

一、当前状态

  • 设计已闭合：Agent/一种理想的智能体编排架构.md（理念）+ Agent/WeaveAgentDesign.md（工程设计）+ 两轮共 25 项决策。
  • 骨架已落地：Agent/WeaveAgent.py 包含所有类定义、字段、方法签名，方法体均为 ...。
  • 底层库尚未实现：Agent/基于关键词的知识树系统设计方案.md 仅有设计，无代码。

二、缺失清单（按层组织）

A. 核心运行时

# 项 说明
A1 LLM 客户端层 async HTTP 客户端（DeepSeek / Kimi / OpenAI 任选），封装 chat、重试、超时、限流
A2 结构化输出解析 JSON schema 校验 {reasoning, actions[], next_status}，失败时错误回写 logic_trace 并发下轮 Next() 让 LLM 自纠
A3 Scheduler 主循环 asyncio event loop，Tick() 取 ready → 并发信号量获取 → 调 Next()
A4 事件分发链路 EventLog.Log → Scheduler.OnEvent → ready 标脏入队 → worker 取走 → Next() 的实际连接
A5 async 上下文变量 current_frame contextvars.ContextVar 声明；Tick 前 set、Tool Call 内 get

B. 状态与动作

# 项 说明
B1 合法状态转移白名单 _VALID_TRANSITIONS: dict[FrameStatus, set[FrameStatus]]，_handle_declare_status 据此校验（含"DONE/FAILED 必经 REFLECTING"、"REFLECTING 严格单向"）
B2 _select_actions 策略 每个 FrameStatus 允许哪些动作的表 + 条件逻辑
B3 动作分发器 按 action.type 路由到 _handle_* 或 ToolRegistry.Find(path).Call()；Frame 自处理动作和 Tool 动作共用一个统一入口
B4 Guide 模板库 next / summary / reflect 三套文本模板；REFLECTING 按最终 status=DONE|FAILED 切换成败两套 guide；按动作类型定制的自洽片段

C. Prompt 工程

# 项 说明
C1 _build_prompt 实际渲染 四段分层文本拼接、token 预算分配、各子段的降级策略（超长时压什么）
C2 Session 压缩策略 Session.Compress() 的实际算法（滑窗 / 摘要 / 分层）
C3 ToolRegistry.DescribePrompt 每个 Tool 在 prompt 里的呈现格式（name + description + input/output schema 摘要）
C4 Persona 渲染模板 Persona.RenderSystemPrompt() 的实际模板

D. 工具实现（填充 ToolRegistry.Register）

# 工具组 说明
D1 memory/short/* create / find / modify / delete / snapshot，经 current_frame 定位
D2 memory/long/* 包装 LongTermMemory 的所有方法（search / create_keyword / create_info / link_info / merge / delete …）
D3 public/* public/get、public/set、public/snapshot
D4 frame/* stimulate / poll_children / get_child_memory_snapshot（注意这些不是 Frame 自处理动作——spawn_subframe 是自处理；查询类是 Tool）
D5 file/* 文件读写（按需，最小可 skip）
D6 skill/* find_skills / save_skill 包装 LongTermMemory.FindSkills / SaveSkill

E. 数据层

# 项 说明
E1 LongTermMemory 底层库 按 基于关键词的知识树系统设计方案.md 实现关键词树 + Info + 多对多关联 + change_log + undo；独立 package，LongTermMemory 类是薄封装
E2 ShortTermMemory 实现 内存存储、按 capacity 做简单管理（LRU 或"不满不淘汰"）
E3 持久化后端 Session / Frame / EventLog / LTM / PublicStore 的存储方案（起步阶段可用 SQLite + JSON 快照，生产可换 Postgres + Qdrant）
E4 恢复逻辑 Agent 启动时从持久化重建 _frames、root_frame、ready 队列

F. 接入与运维

# 项 说明
F1 外部入口 CLI（stdin 交互）→ HTTP server → WebSocket 渐进式
F2 异常处理 LLM 调用失败、JSON 解析失败、Tool 执行失败的统一 handler；写 logic_trace + 下轮 Next() 自纠
F3 per-Frame 锁 asyncio.Lock per frame，避免同一 Frame 并发 Next()
F4 Token / 成本预算 统计每轮 Next() 的输入输出 token，设单 Frame / 单会话上限
F5 可观测性 结构化日志（每个 Next() 一条：输入 prompt 摘要 + 输出 JSON + 动作结果）、事件时间线、关键指标

G. 小补丁

# 项 说明
G1 Message.timestamp / id 自增 构造时自动填充
G2 Agent._next_frame_id 并发安全 用 itertools.count() 或加锁
G3 Scheduler.ScheduleTimer loop.call_later(delay, lambda: self.OnEvent(TIMER_event))
G4 Frame.id 分配的线程安全 见 G2

三、里程碑

M1：hello-world 最短链路

目标：外部输入 → 根 Frame Next() → LLM 调用 → 派发 add_task → 再 Next() → reasoning 写 trace → 经 REFLECTING → declare DONE。

必做：A1 / A2 / A3 / A4 / A5 + B1 / B2 / B3 + 最简版 B4（guide 就一行） + C1（朴素拼接） + D1 / D3（short + public 各一个 Tool） + E2（内存 ShortTerm） + F1（CLI） + G1-4

可跳过：E1（LTM 用桩实现）、E3 / E4（不持久化）、F2（异常直接抛）、F4 / F5（裸跑）、D2 / D4 / D5 / D6

预期工作量：1-2 周。

M2：接长时记忆 + 多 Frame 协作

目标：跑通完整思维树——父 spawn 子、子 REFLECTING 后 SUBFRAME_DONE 唤醒父、父读子 result 决策；命中长时记忆能进 prompt。

必做（在 M1 基础上）：E1（LTM 底层库真实实现）+ D2（长时记忆 Tool）+ D4（frame Tool）+ B4 的完整 guide 模板 + C2 / C3 + D6（skill）

预期工作量：2-3 周（其中 E1 占大头）。

M3：生产化

目标：可长时运行、可重启恢复、有观测、有预算。

必做：E3 / E4（持久化 + 恢复）+ F2（异常处理）+ F3（并发锁）+ F4（预算）+ F5（观测）+ D5（file Tool）

预期工作量：2-3 周。

四、依赖关系

A1 LLM客户端 ──┐
               ├─→ A2 解析 ─→ A3 主循环 ─→ A4 事件分发 ─→ M1 可跑
A5 ctx变量 ────┘                │
                                ├─→ B1 B2 B3（必须同步）
B4 Guide 模板 ──→ C1 C4          │
                                ├─→ D1 D3 ─→ E2 ─→ M1
E1 LTM 底层 ───→ D2 ─→ D6 ─→ M2
                                 │
E3 持久化 ──→ E4 恢复 ──────────→ M3
F3/F4/F5 ────────────────────→ M3

关键瓶颈：E1（LTM 底层库）是 M2 的必经之路，其工作量单独接近 M1 总量，建议并行于 A/B/C/D 的开发。

五、验收标准

M1 验收

  1. 用户 SubmitExternalInput("帮我整理桌面 todo")；
  2. 根 Frame 进入 Next() 循环；
  3. LLM 连续输出合法 JSON；
  4. logic_trace 至少 3 条记录；
  5. 最终 root_frame 进入 REFLECTING → DONE；
  6. result 和 summary 非空。

M2 验收

  1. 根 Frame 在处理中 spawn 至少一个 SubFrame；
  2. SubFrame 独立 Next()，完成后触发 SUBFRAME_DONE；
  3. 父 Frame 被唤醒后读到子的 result 并续作；
  4. 过程中调用 memory/long/search 命中至少一条 Info；
  5. 至少产生一条新的 memory/long/create_info（学到新东西）。

M3 验收

  1. Agent 进程 kill -9 后再启动，_frames 与 root_frame 状态恢复；
  2. 连续运行 24 小时无崩溃；
  3. 每次 Next() 都有结构化日志；
  4. 单 Frame 超过 token 预算时优雅降级（压缩 Session 或提前 REFLECT）。

六、未纳入本计划的议题

  • 多 Agent（多实例）协作与隔离
  • 人格 / 情绪的动态演化机制（决策 #13 明确 Persona 静态；动态状态存 PublicStore，演化规则留待探索）
  • Skill 的自动演化与版本管理（UpdateInfo 已有，但自动触发时机未定）
  • 前端 / 交互 UI
  • 多模态输入（图像 / 音频）

这些需要后续再起一份扩展计划。

No comments to display

Back to top