Skip to content

PLAN.md

Latest commit

 

History

History
189 lines (140 loc) · 6.78 KB

PLAN.md

File metadata and controls

189 lines (140 loc) · 6.78 KB
Raw

PLAN.md — 开发计划

最后更新：2026-07-03 当前阶段：规划中

开发阶段总览

阶段 名称 预计时间 状态 开始日期 完成日期
1 项目骨架 1-2h ✅ 2026-07-03 2026-07-03
2 Executa Tool 核心 3-4h ✅ 2026-07-03 2026-07-03
3 前端核心 3-4h ✅ 2026-07-03 2026-07-03
4 Mock Fixture 0.5h ✅ 2026-07-03 2026-07-03
5 集成测试 1-2h ✅ 2026-07-03 2026-07-03
6 打包与发布 2-3h ✅ 2026-07-03 2026-07-03
7 文档 1-2h ✅ 2026-07-03 2026-07-03

阶段 1：项目骨架

目标：建立完整的 monorepo 项目结构，确保 anna-app validate --strict 通过，anna-app dev --no-llm 能加载。

任务

  • 1.1 初始化 pnpm workspace（根 package.json, pnpm-workspace.yaml）
  • 1.2 创建 manifest.json（声明 schema, required_executas, permissions, ui, dev）
  • 1.3 初始化前端项目 ui/（Vite + React + TypeScript）
  • 1.4 写最小前端（"Hello Anna" + AnnaAppRuntime 连接）
  • 1.5 初始化 Executa Tool 项目 executa/（package.json, tsconfig.json）
  • 1.6 写最小 Executa Tool（initialize + describe 响应）
  • 1.7 创建 executa/executa.json manifest
  • 1.8 配置 ui.host_api.storage 和 ui.host_api.tools 权限
  • 1.9 运行 anna-app validate --strict 确认通过
  • 1.10 运行 anna-app dev --no-llm 确认前端可加载

产出

  • 根 package.json, pnpm-workspace.yaml
  • manifest.json（完整声明）
  • ui/ 项目骨架（可构建）
  • executa/ 项目骨架（最小 RPC）

阶段 2：Executa Tool 核心

目标：完整实现 JSON-RPC 2.0 over stdio 的 Executa Tool，包括 sampling 支持。

任务

  • 2.1 实现 stdio 通信框架（stdin readline → JSON parse → route → JSON stringify → stdout flush）
  • 2.2 实现 initialize handler（v2 capability negotiation，声明 sampling capability）
  • 2.3 实现 describe handler（返回完整 tool manifest）
  • 2.4 实现 health handler
  • 2.5 实现 shutdown handler
  • 2.6 实现 invoke handler（解析 summarize 请求，构建 notes 列表）
  • 2.7 实现 sampling/createMessage 反向请求（构建 prompt，发送 JSON-RPC 请求到 stdout）
  • 2.8 实现 sampling 响应处理（同一 stdin reader 接收 host 响应）
  • 2.9 错误处理（无效 JSON-RPC、未知 method、invoke 参数错误）
  • 2.10 日志全部输出到 stderr

产出

  • executa/src/index.ts（入口 + stdio 循环）
  • executa/src/rpc.ts（JSON-RPC 2.0 框架）
  • executa/src/handlers/*.ts（各方法处理器）
  • executa/executa.json（完整 manifest）

阶段 3：前端核心

目标：完整实现笔记 CRUD 和 LLM 总结 UI。

任务

  • 3.1 实现 ui/src/anna/runtime.ts（AnnaAppRuntime.connect 封装）
  • 3.2 实现 ui/src/anna/storage.ts（get/set 封装 + 错误处理）
  • 3.3 实现 ui/src/anna/tools.ts（invoke 封装 + 错误处理）
  • 3.4 实现 ui/src/hooks/useNotes.ts（笔记 CRUD 状态管理）
  • 3.5 实现 NoteInput 组件（输入框 + 空内容禁用 + Enter 提交 + 保存后清空）
  • 3.6 实现 NoteList 组件（列表展示 + 序号）
  • 3.7 实现 NoteItem 组件（内容 + 删除按钮）
  • 3.8 实现 EmptyState 组件（无笔记时显示）
  • 3.9 实现 ErrorBanner 组件（错误信息展示）
  • 3.10 实现 Summarize 组件（按钮 + loading + 结果 + 错误）
  • 3.11 实现 App.tsx 根组件（组合所有组件 + 连接状态）
  • 3.12 配置 Vite 构建（输出静态文件到 dist/）
  • 3.13 确认 manifest.json 的 ui.bundle.entry 指向正确

产出

  • ui/src/ 完整源码
  • 可 pnpm build 生成 bundle
  • 所有组件覆盖正常/空/错误状态

阶段 4：Mock Sampling Fixture

目标：创建用于 anna-app executa dev --mock-sampling 的 fixture 文件。

任务

  • 4.1 创建 fixtures/sampling-mock.jsonl
  • 4.2 fixture 包含对 sampling/createMessage 请求的模拟响应
  • 4.3 fixture 中的 summary 内容合理（看起来像 LLM 生成的）

产出

  • fixtures/sampling-mock.jsonl

阶段 5：集成测试

目标：按验收标准逐项验证。

任务

  • 5.1 anna-app validate --strict 通过
  • 5.2 anna-app dev --no-llm → 创建笔记 → 确认 storage.set 被调用
  • 5.3 刷新/重新加载 → 确认 storage.get 被调用
  • 5.4 删除笔记 → 确认 storage.set 被调用（数量减少）
  • 5.5 点击 Summarize → 确认 tools.invoke 被调用 → 显示 [-32603] 错误
  • 5.6 anna-app executa dev --mock-sampling fixtures/sampling-mock.jsonl 通过
  • 5.7 确认 fixture/log 中有 sampling/createMessage 请求记录
  • 5.8 手动测试 initialize/describe/invoke JSON-RPC

产出

  • 测试通过记录（截图或 log）

阶段 6：打包与发布

目标：编写打包脚本和 GitHub Actions workflow。

任务

  • 6.1 确定 binary 打包方案（esbuild + SEA）
  • 6.2 编写 scripts/build-executa.sh（macOS/Linux）
  • 6.3 编写 scripts/build-executa.ps1（Windows）
  • 6.4 验证产物 archive 结构（根目录 manifest.json, bin/ 目录）
  • 6.5 编写 .github/workflows/release.yml
  • 6.6 workflow 包含：三平台构建 + smoke test + 上传 Release assets
  • 6.7 测试 workflow 触发和产物

产出

  • scripts/build-executa.sh
  • scripts/build-executa.ps1
  • .github/workflows/release.yml
  • 三平台 release assets（验证用）

阶段 7：文档

目标：编写完整 README，覆盖所有验收标准。

任务

  • 7.1 项目结构说明
  • 7.2 安装依赖说明
  • 7.3 构建前端 bundle 说明
  • 7.4 anna-app validate --strict 说明
  • 7.5 anna-app dev --no-llm 说明 + [-32603] 解释
  • 7.6 anna-app executa dev --mock-sampling 说明
  • 7.7 手动测试 Executa JSON-RPC 说明
  • 7.8 确认 storage 走 anna.storage.* 的方法
  • 7.9 确认 summary 走完整链路的方法
  • 7.10 本机二进制打包说明
  • 7.11 GitHub Actions release 说明
  • 7.12 Anna App 平台概念解释（manifest/bundle/executas/storage/sampling/binary）

产出

  • README.md（完整）

里程碑

里程碑 完成标准
🏗️ 骨架可用 ✅ anna-app validate --strict 通过 + dev 可加载
🔧 后端可用 ✅ Executa Tool 全部 RPC 方法可测试
🎨 前端可用 ✅ 笔记 CRUD + Summarize 在 --no-llm 下可操作
✅ 测试通过 ✅ 所有验收标准满足（自动化 + 代码审查）
📦 可发布 ✅ 三平台 binary + GitHub Actions 可用
📖 文档完成 ✅ README 覆盖所有要求