# 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`。