ai-mcp-web-ui/planning-artifacts/tech-spec-json-render-official-hook-refactor.md

title, slug, created, status, stepsCompleted, spec_file, tech_stack, files_to_modify, code_patterns, test_patterns

title	slug	created	status	stepsCompleted	spec_file	tech_stack	files_to_modify	code_patterns	test_patterns
Quick Spec: json-render 官方 Hook 重构	json-render-official-hook-refactor	2026-03-20	ready-for-dev	1 2 3 4 5	quick-spec-json-render-official-hook.md	@json-render/react@0.14.1 @json-render/core@0.14.1 ai@^4.0.0 @ai-sdk/anthropic@^1.0.0 @ai-sdk/mcp@^1.0.0 Next.js 14.2	frontend-v2/app/api/chat/route.ts frontend-v2/app/page.tsx frontend-v2/lib/hooks.ts frontend-v2/components/ChatMessage.tsx frontend-v2/.env.local	官方 useChatUI hook 管理消息和 spec 状态 Vercel AI SDK streamText + toTextStreamResponse 混合流解析: createMixedStreamParser	API Route 返回正确格式 前端正确渲染 spec $state 引用正确解析

Quick Spec: json-render 官方 Hook 重构

Overview

Problem Statement

当前前端使用自定义 useChat hook 手动处理 SSE 事件，通过 specFromToolCall 手动转换 tool result。$state 引用无法正常解析，NovelList 组件只显示标题不渲染小说卡片。

Solution

迁移到官方 @json-render/react 的 useChatUI hook + Next.js API Route (Vercel AI SDK)，让 AI 直接生成 JSONL patches，无需手动转换。

Scope

In Scope:

• 新建 Next.js API Route (app/api/chat/route.ts)
• 前端使用官方 useChatUI hook
• 使用 catalog.prompt() 生成系统提示
• 保留 Python 后端用于 MCP 服务

Out of Scope:

• 删除 Python 后端（保留用于 MCP）
• 新增 json-render 组件类型
• 修改 catalog 或 registry 定义

Context for Development

Codebase Patterns

官方 useChatUI 工作方式:

1. 发送 POST 请求: { messages: [{ role: "user", content: "..." }] }
2. 接收混合流: 文本行 + JSON Patch 行
3. 自动解析并更新 messages[id].text 和 messages[id].spec

当前代码状态:

• 自定义 useChat hook 在 lib/hooks.ts（需废弃）
• Python FastAPI 后端在 backend/ 目录（保留用于 MCP）
• 通过 SSE 发送自定义事件 (tool_call, tool_done 等)

Files to Reference

File	Purpose
/tmp/json-render/packages/react/src/hooks.ts	官方 useChatUI 实现参考
frontend-v2/lib/catalog/catalog.ts	组件 catalog 定义
frontend-v2/lib/registry.tsx	组件 registry 实现
backend/app_fastapi.py	当前 Python 后端（保留）

Technical Decisions

1. 使用 Vercel AI SDK - 简化流式响应处理，与 Anthropic 原生集成
2. 保留 Python 后端 - 用于 MCP 工具调用（可选，未来可迁移）
3. 废弃 specFromToolCall - 让 AI 直接生成 JSONL patches，无需手动转换
4. 环境变量管理 - 使用 Next.js 标准的 .env.local 存储 Anthropic API Key

Implementation Plan

Tasks

Task 1: 安装 Vercel AI SDK 依赖

• File: frontend-v2/package.json
• Action: 添加依赖
• Command:

  cd frontend-v2 && npm install ai @ai-sdk/anthropic @ai-sdk/mcp
  

• Notes:
  • ai 是 Vercel AI SDK 核心
  • @ai-sdk/anthropic 是 Anthropic 集成
  • @ai-sdk/mcp 是 MCP 客户端（独立包，v1.0.25+）

Task 2: 创建 Next.js API Route（集成 MCP）

• File: frontend-v2/app/api/chat/route.ts (新建)
• Action: 创建流式聊天 API，集成 MCP 工具
• Code:

  import { streamText } from 'ai';
  import { anthropic } from '@ai-sdk/anthropic';
  import { createMCPClient } from '@ai-sdk/mcp';
  import catalog from '@/lib/catalog/catalog';
  
  export const runtime = 'edge'; // 可选：边缘运行时
  
  export async function POST(req: Request) {
    const { messages } = await req.json();
  
    // 创建 MCP 客户端
    const mcpClient = await createMCPClient({
      name: 'novel-translator',
      version: '1.0.0',
      transport: {
        type: 'http',
        url: process.env.MCP_URL || 'https://d8d-ai-vscode-8080-223-236-template-6-group.dev.d8d.fun/mcp',
      },
    });
  
    // 获取 MCP 工具
    const tools = await mcpClient.tools();
  
    const result = streamText({
      model: anthropic('claude-sonnet-4-6'),
      system: catalog.prompt({ mode: 'inline' }),
      messages,
      tools, // 传入 MCP 工具
      maxSteps: 5, // 允许多步工具调用
    });
  
    return result.toDataStreamResponse();
  }
  

• Notes:
  • catalog.prompt() 生成系统提示，AI 会输出正确格式的 JSONL
  • 使用官方 @ai-sdk/mcp 的 HTTP Transport 连接 MCP 服务器
  • maxSteps: 5 允许 AI 进行多轮工具调用

Task 3: 更新前端使用官方 useChatUI hook

• File: frontend-v2/app/page.tsx (修改)
• Action: 替换自定义 useChat 为官方 useChatUI
• Key Changes:
  1. 导入 useChatUI from '@json-render/react'
  2. 调用 useChatUI({ api: '/api/chat' })
  3. 渲染 messages[].text (Markdown) 和 messages[].spec (Renderer)
• Notes: 移除对 specFromToolCall 的依赖

Task 4: 配置 Anthropic API Key 环境变量

• File: frontend-v2/.env.local (新建或修改)
• Action: 添加 Anthropic API Key
• Content:

  ANTHROPIC_API_KEY=sk-ant-...
  

• Notes: 可从容器环境变量读取或用户自行配置

Task 5: 清理废弃代码

• File: frontend-v2/lib/hooks.ts
• Action: 删除或注释掉自定义 useChat hook
• Notes: 保留其他可能有用的 hooks（如 useTheme）

Task 6: 更新组件引用

• File: frontend-v2/components/ChatMessage.tsx (简化)
• Action: 移除 specFromToolCall 相关逻辑
• Notes: 使用官方 spec 解析机制

Acceptance Criteria

• AC 1: Given API Route 已创建，当发送 POST 请求到 /api/chat，则返回混合流响应（文本+JSONL）
• AC 2: Given 前端使用 useChatUI，当用户发送消息，则消息正确显示并流式更新
• AC 3: Given AI 返回 JSONL patches，当前端接收，则 messages[].spec 正确构建
• AC 4: Given NovelList spec 包含 $state 引用，当渲染时，则正确解析并显示小说卡片
• AC 5: Given 流式响应进行中，当 token 逐步到达，则 UI 实时更新
• AC 6: Given 用户请求小说列表，当 AI 调用 MCP 工具，则 NovelList 正确渲染（核心验证点）
• AC 7: Given 所有任务完成，当运行 npm run build，则无编译错误

Error Handling

• AC 8: Given API Key 未配置，当调用 /api/chat，则返回 500 错误并提示配置
• AC 9: Given 网络请求失败，当超时或断开，则显示错误提示并允许重试
• AC 10: Given AI 返回无效 JSON Patch，当解析失败，则跳过该行继续处理

Dependencies

External Dependencies

• ai (Vercel AI SDK) - 流式响应处理
• @ai-sdk/anthropic - Anthropic Claude 集成
• @ai-sdk/mcp - MCP 客户端（独立包，需安装）
• @json-render/react - 已安装 (0.14.1)
• @json-render/core - 已安装 (0.14.1)

Configuration Dependencies

• Anthropic API Key（从环境变量或容器获取）
• Next.js 14 App Router（已配置）

MCP 连接方案

• 使用官方 @ai-sdk/mcp 包的 HTTP Transport
• 无需自定义 Transport 类
• 测试验证通过（/tmp/ai-sdk-mcp-test/test-official-mcp.ts）

测试结果：

• HTTP Transport: ✅ 成功
• SSE Transport: ❌ 失败（服务器不支持）

用法：

import { createMCPClient } from '@ai-sdk/mcp';

const mcpClient = await createMCPClient({
  name: 'novel-translator',
  version: '1.0.0',
  transport: {
    type: 'http',
    url: process.env.MCP_URL,
  },
});

const tools = await mcpClient.tools();

Testing Strategy

Unit Tests

• API Route 响应格式测试
• useChatUI hook 状态管理测试
• JSON Patch 解析测试

Integration Tests

• 前端到后端完整流程测试
• MCP 工具调用 + NovelList 渲染测试

Manual Testing Steps

1. 启动 Next.js 开发服务器
2. 打开浏览器访问聊天页面
3. 发送消息请求小说列表
4. 验证 NovelList 正确渲染小说卡片
5. 验证 $state 引用正确解析

Notes

High-Risk Items

1. $state 引用解析 - 核心问题所在，需重点验证
2. 混合流解析 - 确保文本和 JSONL 正确分离处理
3. 环境变量 - 确保 API Key 正确传递

Known Limitations

• Python 后端仍保留用于 MCP 服务（未来可迁移到 Node.js）
• 不支持多轮对话上下文持久化（可后续添加）

Future Considerations

• 考虑将 MCP 服务迁移到 Node.js（统一技术栈）
• 添加对话历史持久化（localStorage 或后端存储）
• 支持多模型选择（Claude / GPT / 本地模型）

Status

• Step 1: 理解需求 - 完成
• Step 2: 深度调查 - 完成
• Step 3: 生成规格 - 完成
• Step 4: 审核定稿 - 完成
• Step 5: MCP 验证 - 完成

验证结果 (2026-03-20)

@ai-sdk/mcp 官方包测试 ✅

测试环境: /tmp/ai-sdk-mcp-test/test-official-mcp.ts

测试结果:

• HTTP Transport: ✅ 成功连接
• 获取工具: ✅ 11 个工具
• 工具列表: translate_text, translate_batch, translate_file, clean_file, split_chapters, glossary_add, glossary_list, glossary_import, glossary_clear, check_duplicate, get_fingerprint

关键发现:

1. 官方 @ai-sdk/mcp v1.0.25 的 HTTP Transport 可直接使用
2. 无需自定义 Transport 类
3. MCP 功能已从 ai 包迁移到独立的 @ai-sdk/mcp 包

安装命令:

cd frontend-v2 && npm install @ai-sdk/mcp