tantingwu/GPU_GUARD_MONOREPO
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
GPU_GUARD_MONOREPO/docs/superpowers/plans/2026-04-19-neta-pi-first-platform-plan-suite.md
陈二狗 cc660d19d1 初始化提交
2026-05-20 21:39:12 +08:00

16 KiB
Raw Blame History

Neta Pi-First Agent 平台实施计划套件

给自动化实施代理： 必须使用子技能：superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans，按任务逐项实施本计划。步骤使用复选框（- [ ]）语法跟踪进度。

目标： 将 Neta Pi-First Agent Platform 重构设计 拆成可独立规划、独立验证、按依赖顺序推进的实施计划套件。

架构： 总体重构拆成 6 个计划：运行时内核、会话通信与对话页、subagent 进程隔离、skill/tool/model 资源层、管理后台 UI、平台 UI 设计系统。所有计划共享同一事实源：树状 session entry graph、双 provider、完整流式事件、统一资源模型。

技术栈： NestJS/Midway 后端、TypeORM/MySQL、文件化 JSONL session provider、Vue 3 + Vite + Pinia 前端、WebSocket/Socket.IO、pnpm monorepo、Jest。

范围拆分

总设计文档：

  • docs/superpowers/specs/2026-04-19-neta-pi-first-agent-runtime-design.md

该设计已经覆盖以下独立子系统：

  • Agent 运行时内核
  • 对话工作区
  • Subagent 进程编排器
  • Skill / Tool / Model 资源层
  • 管理后台适配
  • 平台 UI 设计系统

这些子系统不应塞进同一个实施计划。每个子系统都需要单独计划、单独测试、单独提交。

计划 1：Agent 运行时内核

计划文件： docs/superpowers/plans/2026-04-19-neta-agent-runtime-kernel.md

目标： 建立树状 session entry graph、SessionTreeProvider 抽象、默认 file provider、MySQL provider 契约，以及 leaf 驱动上下文重建。

负责范围：

  • 后端 session tree 类型
  • file/mysql 双 provider
  • provider 契约测试
  • 上下文构建器
  • entry graph 快照
  • agent 配置中的 session provider 选择

主要后端文件：

  • packages/backend/src/modules/netaclaw/session-tree/types.ts
  • packages/backend/src/modules/netaclaw/session-tree/provider.ts
  • packages/backend/src/modules/netaclaw/session-tree/file_provider.ts
  • packages/backend/src/modules/netaclaw/session-tree/mysql_provider.ts
  • packages/backend/src/modules/netaclaw/session-tree/context_builder.ts
  • packages/backend/src/modules/netaclaw/session-tree/snapshot.ts
  • packages/backend/src/modules/netaclaw/entity/agent_session.ts
  • packages/backend/src/modules/netaclaw/entity/agent_session_entry.ts
  • packages/backend/src/modules/netaclaw/entity/agent.ts

主要测试：

  • packages/backend/src/modules/netaclaw/session-tree/session_tree_provider.contract.spec.ts
  • packages/backend/src/modules/netaclaw/session-tree/context_builder.spec.ts

Pi 参考源码：

  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/coding-agent/src/core/session-manager.ts
  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/coding-agent/src/core/compaction/

可直接复用或高强度移植：

  • SessionHeader / SessionEntry union 的结构设计。
  • 单文件 JSONL session 协议。
  • buildSessionContext() 的 leaf-to-root 路径构建、compaction、branch_summary、custom_message、thinking/model setting 处理。
  • branch()、resetLeaf()、branchWithSummary()、createBranchedSession() 的纯逻辑。
  • compaction 的 firstKeptEntryId、split turn、previous summary 合并策略。

不能简化掉的 Pi 语义：

  • 不得把 file provider 改成 session.json + entries.jsonl 双文件。
  • 不得把 tool_call/tool_result 强行拆成独立 entry 而丢掉 Pi AgentMessage 结构。
  • 不得只用 content/summary 字段表示 message，必须保留完整 message payload。
  • 不得把 completed entry 当普通数据库记录随意 update。

依赖： 无。

阻塞：

  • 计划 2 的对话协议
  • 计划 3 的 subagent 树节点
  • 计划 4 中与运行时绑定的资源策略
  • 计划 5 的 Agent 会话管理页面

完成定义：

  • file provider 可以创建会话、追加 entry、创建分支、切换 leaf 并构建上下文。
  • mysql provider 暴露完全相同的契约。
  • 契约测试同时覆盖两个 provider。
  • 契约测试覆盖 Pi 核心语义：单文件 JSONL、branch/resetLeaf、branch summary、compaction firstKeptEntryId、label、session_info、thinking/model change。
  • 不实现旧历史数据兼容。

计划 2：对话协议与 UI

计划文件： docs/superpowers/plans/2026-04-19-neta-conversation-workspace.md

目标： 将 Agent 对话页改为聊天为主、树为辅的 Conversation Workspace，并实现 snapshot + realtime patch + 完整流式通信。

负责范围：

  • session snapshot API
  • realtime patch 协议
  • assistant/tool/subagent 完整流式事件
  • Pinia SessionTreeStore
  • active path 投影
  • 树侧栏
  • 对话子组件重构
  • task planning / Todo / thinking / clarify 运行时组件

主要后端文件：

  • packages/backend/src/modules/netaclaw/gateway/protocol.ts
  • packages/backend/src/modules/netaclaw/gateway/server.ts
  • packages/backend/src/modules/netaclaw/controller/session.ts
  • packages/backend/src/modules/netaclaw/service/chat_orchestrator.ts

主要前端文件：

  • packages/frontend/src/modules/agent/store/session-tree.ts
  • packages/frontend/src/modules/agent/types/session-tree.ts
  • packages/frontend/src/modules/agent/hooks/session-tree-socket.ts
  • packages/frontend/src/modules/agent/views/chat.vue
  • packages/frontend/src/modules/agent/components/conversation/ConversationWorkspace.vue
  • packages/frontend/src/modules/agent/components/conversation/ConversationEntryList.vue
  • packages/frontend/src/modules/agent/components/conversation/StreamingAssistantPanel.vue
  • packages/frontend/src/modules/agent/components/conversation/StreamingToolPanel.vue
  • packages/frontend/src/modules/agent/components/conversation/StreamingSubagentPanel.vue
  • packages/frontend/src/modules/agent/components/conversation/PlanningPanel.vue
  • packages/frontend/src/modules/agent/components/conversation/ThinkingPanel.vue
  • packages/frontend/src/modules/agent/components/conversation/ClarifyPanel.vue
  • packages/frontend/src/modules/agent/components/conversation/ConversationComposer.vue
  • packages/frontend/src/modules/agent/components/session-tree/SessionTreeSidebar.vue
  • packages/frontend/src/modules/agent/components/session-tree/SessionTreeNode.vue

Pi 参考源码：

  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/web-ui/src/components/AgentInterface.ts
  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/web-ui/src/components/StreamingMessageContainer.ts
  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/web-ui/src/ChatPanel.ts
  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/coding-agent/src/modes/interactive/components/tree-selector.ts

依赖： 计划 1。

阻塞：

  • 计划 3 的 subagent 流式 UI
  • 计划 5 的会话诊断能力
  • 计划 6 的最终视觉统一

完成定义：

  • 对话页不再把线性消息列表作为前端事实源。
  • 首次加载使用 snapshot。
  • 运行时更新使用 patch 事件。
  • Assistant 文本、tool 状态、tool 结果和 subagent 事件可以独立流式更新。
  • 树侧栏可以切换 leaf，并从历史 user 节点继续对话。

计划 3：子 Agent 进程编排器

计划文件： docs/superpowers/plans/2026-04-19-neta-subagent-process-orchestrator.md

目标： 将 session subagent 从同进程软隔离改为 Pi 风格进程级隔离，并把 subagent run/event/result 映射为正式 session tree 节点。

负责范围：

  • subagent worker 入口
  • 子进程启动与生命周期
  • task envelope schema
  • JSONL 事件解析器
  • run/event 持久化
  • 取消与并发限制
  • subagent batch/result 树节点

主要后端文件：

  • packages/backend/src/modules/netaclaw/subprocess/types.ts
  • packages/backend/src/modules/netaclaw/subprocess/orchestrator.ts
  • packages/backend/src/modules/netaclaw/subprocess/jsonl.ts
  • packages/backend/src/modules/netaclaw/subprocess/worker.ts
  • packages/backend/src/modules/netaclaw/entity/subprocess_run.ts
  • packages/backend/src/modules/netaclaw/entity/subprocess_event.ts
  • packages/backend/src/modules/netaclaw/service/subagent.ts
  • packages/backend/src/modules/netaclaw/tools/builtin/delegate_task.ts
  • packages/backend/src/modules/netaclaw/tools/builtin/delegate_parallel.ts

Pi 参考源码：

  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/coding-agent/examples/extensions/subagent/index.ts
  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/coding-agent/examples/extensions/subagent/agents.ts

依赖： 计划 1 与计划 2 的事件协议。

阻塞：

  • 计划 4 的 subagent skill/tool policy 集成
  • 计划 5 的管理后台 subagent 诊断能力

完成定义：

  • 委派任务运行在独立子进程中。
  • 父进程接收 JSONL 事件。
  • 子进程不能直接修改父进程的 session provider。
  • Subagent 事件可以流式推送到前端，并持久化用于回放。

计划 4：Skill / Tool / Model 资源层

计划文件： docs/superpowers/plans/2026-04-19-neta-resource-layer.md

目标： 将 skill、tool、model 能力统一为 platform resource，并适配主 agent 与 subagent runtime policy。

负责范围：

  • skill resource registry
  • Pi 风格 skill discovery
  • sourceInfo/fingerprint/scope
  • tool catalog 与 runtime policy 分离
  • model capability 元数据
  • runtime policy resolver

主要后端文件：

  • packages/backend/src/modules/netaclaw/resource/types.ts
  • packages/backend/src/modules/netaclaw/resource/skill_discovery.ts
  • packages/backend/src/modules/netaclaw/resource/skill_registry.ts
  • packages/backend/src/modules/netaclaw/resource/tool_policy.ts
  • packages/backend/src/modules/netaclaw/resource/model_capability.ts
  • packages/backend/src/modules/netaclaw/entity/skill_resource.ts
  • packages/backend/src/modules/netaclaw/service/tool_resolver.ts
  • packages/backend/src/modules/netaclaw/service/model_channel.ts
  • packages/backend/src/modules/netaclaw/service/skill_loader.ts

Pi 参考源码：

  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/coding-agent/src/core/skills.ts
  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/coding-agent/src/core/source-info.ts
  • C:/Users/lixin/Desktop/RZYX_ZT/pi-mono-main/packages/web-ui/src/tools/renderer-registry.ts

依赖： 计划 1；subagent policy 集成依赖计划 3。

阻塞：

  • 计划 5 的 skill/tool/model 管理页面

完成定义：

  • Skill discovery 在命中 SKILL.md 根目录后停止继续递归。
  • 资源记录暴露 source、scope、sourceInfo、fingerprint。
  • Tool 可用性可以分别为主 agent 和 subagent 解析。
  • Model capability 可供运行时和管理后台页面使用。

计划 5：管理后台适配

计划文件： docs/superpowers/plans/2026-04-19-neta-admin-console-adaptation.md

目标： 将 skill 管理、tool 管理、agent 管理、agent 会话、模型管理页面适配新平台资源模型，并统一为 Resource Workbench / Agent Structure Canvas 交互。

负责范围：

  • Skill 管理页面
  • Tool 管理页面
  • Agent 管理页面
  • Agent 会话管理页面
  • 模型管理页面
  • Agent Structure Canvas
  • Resource Workbench 交互模式

主要前端文件：

  • packages/frontend/src/modules/agent/views/skills.vue
  • packages/frontend/src/modules/agent/views/tools.vue
  • packages/frontend/src/modules/agent/views/agent-list.vue
  • packages/frontend/src/modules/agent/views/agent-edit.vue
  • packages/frontend/src/modules/agent/views/model-channel.vue
  • packages/frontend/src/modules/agent/components/admin/ResourceWorkbench.vue
  • packages/frontend/src/modules/agent/components/admin/ResourceDetailPanel.vue
  • packages/frontend/src/modules/agent/components/admin/AgentStructureCanvas.vue
  • packages/frontend/src/modules/agent/components/admin/AgentCanvasNode.vue
  • packages/frontend/src/modules/agent/components/admin/AgentCanvasInspector.vue

主要后端文件：

  • packages/backend/src/modules/netaclaw/controller/admin/skill.ts
  • packages/backend/src/modules/netaclaw/controller/admin/tool.ts
  • packages/backend/src/modules/netaclaw/controller/admin/model_channel.ts
  • packages/backend/src/modules/netaclaw/controller/agent.ts
  • packages/backend/src/modules/netaclaw/controller/session.ts

依赖： 计划 1 与计划 4。Agent 会话页面还依赖计划 2。

阻塞： 不直接阻塞其他计划，但平台发布前必须完成。

完成定义：

  • Agent 编辑不再依赖旧的抽屉式复杂配置流程。
  • Agent 管理使用 Agent Structure Canvas 编排 system prompt、model、session provider、memory、tools、skills、subagents。
  • Skill/tool/model/session 页面共享 Resource Workbench 布局和状态语言。
  • 管理后台页面暴露 provider、sourceInfo、runtime status、model capability 和 policy diagnostics。

计划 6：平台 UI 设计系统

计划文件： docs/superpowers/plans/2026-04-19-neta-platform-ui-design-system.md

目标： 统一 Agent 平台 UI 视觉语言，形成专业后台型 + 轻科技感的设计系统，并系统治理显示 bug。

负责范围：

  • Conversation Workspace 视觉语言
  • Resource Workbench 视觉语言
  • Agent Structure Canvas 视觉语言
  • 运行时状态 token
  • 流式状态 token
  • 空状态、加载态、错误态、重试态、取消态
  • 显示问题审计与清理

主要前端文件：

  • packages/frontend/src/modules/agent/styles/platform-ui.scss
  • packages/frontend/src/modules/agent/components/ui/RuntimeBadge.vue
  • packages/frontend/src/modules/agent/components/ui/StatusPill.vue
  • packages/frontend/src/modules/agent/components/ui/MetricStrip.vue
  • packages/frontend/src/modules/agent/components/ui/EmptyState.vue
  • packages/frontend/src/modules/agent/components/ui/ErrorState.vue
  • packages/frontend/src/modules/agent/components/ui/SectionSurface.vue
  • packages/frontend/src/modules/agent/components/ui/NodeSurface.vue

依赖： 计划 2 与计划 5。

阻塞： 最终发布前的视觉打磨。

完成定义：

  • Agent 相关页面不再像不同产品拼接在一起。
  • 复杂 Agent 编辑移除传统后台抽屉式交互。
  • 运行时子组件共享同一套间距、状态和容器语言。
  • 对话页和管理页的已知显示问题要么修复，要么记录为明确的后续任务。

执行顺序

  • 步骤 1：创建第 1 份详细计划

写入 docs/superpowers/plans/2026-04-19-neta-agent-runtime-kernel.md。

预期内容：

  • session tree 类型

  • provider 接口

  • file provider 实现任务

  • MySQL provider 实现任务

  • provider 契约测试

  • context builder 测试

  • agent 配置集成

  • 步骤 2：创建第 2 份详细计划

写入 docs/superpowers/plans/2026-04-19-neta-conversation-workspace.md。

预期内容：

  • snapshot API 任务

  • websocket patch 协议任务

  • streaming event 任务

  • 前端 session tree store 任务

  • conversation workspace 组件任务

  • tree sidebar 任务

  • runtime child component 任务

  • 步骤 3：创建第 3 份详细计划

写入 docs/superpowers/plans/2026-04-19-neta-subagent-process-orchestrator.md。

预期内容：

  • worker 入口

  • spawn 生命周期

  • envelope schema

  • JSONL parser

  • run/event 持久化

  • delegate tool 集成

  • 取消与并发测试

  • 步骤 4：创建第 4 份详细计划

写入 docs/superpowers/plans/2026-04-19-neta-resource-layer.md。

预期内容：

  • skill discovery 与 registry

  • tool policy resolver

  • model capability 元数据

  • runtime resource 绑定

  • subagent policy 集成

  • 步骤 5：创建第 5 份详细计划

写入 docs/superpowers/plans/2026-04-19-neta-admin-console-adaptation.md。

预期内容：

  • Resource Workbench 外壳

  • Skill 页面适配

  • Tool 页面适配

  • Agent Structure Canvas

  • Agent 会话页面适配

  • 模型页面适配

  • 步骤 6：创建第 6 份详细计划

写入 docs/superpowers/plans/2026-04-19-neta-platform-ui-design-system.md。

预期内容：

  • 视觉 token
  • 共享 UI 容器
  • runtime status 组件
  • canvas 视觉语言
  • 显示问题审计与修复任务

自检

  • 设计覆盖：平台设计中的每个主要章节都映射到六份详细计划之一。
  • 占位内容检查：本套件文档只定义计划边界和预期内容；详细任务代码放入六份子实施计划。
  • 类型一致性：所有计划统一使用核心术语：SessionTreeProvider、entry、leaf、snapshot、provider、Resource Workbench、Agent Structure Canvas、Conversation Workspace。