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