429 lines
16 KiB
Markdown
429 lines
16 KiB
Markdown
# 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`。
|