refactor: arch and domain redesign

.agents/skills/ai-sdk/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: ai-sdk
+description: 'Answer questions about the AI SDK and help build AI-powered features. Use when developers: (1) Ask about AI SDK functions like generateText, streamText, ToolLoopAgent, embed, or tools, (2) Want to build AI agents, chatbots, RAG systems, or text generation features, (3) Have questions about AI providers (OpenAI, Anthropic, Google, etc.), streaming, tool calling, structured output, or embeddings, (4) Use React hooks like useChat or useCompletion. Triggers on: "AI SDK", "Vercel AI SDK", "generateText", "streamText", "add AI to my app", "build an agent", "tool calling", "structured output", "useChat".'
+---
+
+## What the AI SDK Is
+
+The AI SDK by Vercel (the `ai` package on npm) is a TypeScript toolkit for building AI applications. It provides a unified API across model providers for text generation, structured output, tool calling, agents, embeddings, and framework UI integrations.
+
+- Repository: https://github.com/vercel/ai
+- Documentation: https://ai-sdk.dev/docs
+
+## Critical: Do Not Trust Your Own Memory
+
+Whatever you remember about the AI SDK is likely outdated. The SDK changes frequently across versions - APIs are renamed, removed, and added. Your training data almost certainly contains obsolete APIs, deprecated patterns, and model IDs that no longer exist. UI hooks like `useChat` are among the most frequently changed APIs, so be especially careful with client code.
+
+**Never write AI SDK code from memory.** Always verify every API, option, and pattern against the documentation and source code for the version that is actually installed in the project.
+
+## Use the Bundled, Version-Matched Docs
+
+The `ai` package ships its full documentation and source code inside `node_modules`. These always match the installed version, so trust them over anything you remember.
+
+1. Ensure `ai` is installed. If `node_modules/ai/` does not exist, install **only** the `ai` package using the project's package manager (e.g. `pnpm add ai`). Install provider packages (e.g. `@ai-sdk/openai`) and framework packages (e.g. `@ai-sdk/react`) later, when the task requires them.
+2. Read and grep the bundled docs at `node_modules/ai/docs/` and the source at `node_modules/ai/src/`.
+3. Provider and framework packages bundle their own docs at `node_modules/@ai-sdk/<name>/docs/`.
+4. If something isn't in the bundled docs, search https://ai-sdk.dev/docs. You can append `.md` to any docs page URL to get its markdown, and search via `https://ai-sdk.dev/api/search-docs?q=your_query`.
+5. If you cannot find support for an answer in the docs or source, say so explicitly — do not guess.
+
+## AI Gateway: The Fastest Way to Start
+
+The Vercel AI Gateway is the fastest way to get started with the AI SDK. It provides access to models from OpenAI, Anthropic, Google, and other providers through a single API, without installing provider packages or managing multiple API keys.
+
+To set it up:
+
+1. Authenticate with OIDC (for Vercel deployments) or get an AI Gateway API key.
+2. Provide it to your app via the `AI_GATEWAY_API_KEY` environment variable.
+3. Reference models with `provider/model` strings.
+
+For exact setup, authentication, and usage, read the bundled guide and the AI Gateway docs.
+
+### Choosing a Model
+
+Never use model IDs from memory — models are released and retired frequently. Fetch the current list before writing code that references a model. Do not truncate the list (e.g. with `head`) so you can find the newest models:
+
+```bash
+# All available models
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '.data[].id'
+
+# Filter by provider (e.g. anthropic, openai, google)
+curl -s https://ai-gateway.vercel.sh/v1/models | jq -r '[.data[] | select(.id | startswith("anthropic/")) | .id] | reverse | .[]'
+```
+
+When multiple versions of a model exist, prefer the one with the highest version number.
+
+## Building and Consuming Agents
+
+Use the SDK's built-in agent abstraction (such as `ToolLoopAgent`) rather than hand-rolling tool-calling loops. For end-to-end type safety, infer the UI message type from your agent definition when consuming it on the client (e.g. with `useChat`). Consuming an agent is framework-specific: check `package.json` to detect the stack, then follow the matching quickstart.
+
+Look up the current agent, tool, and type-safety APIs in the bundled docs (`node_modules/ai/docs/`, especially the agents section) or at https://ai-sdk.dev/docs.
+
+## DevTools
+
+AI SDK DevTools captures your AI SDK calls - requests, responses, tool calls, token usage, and multi-step runs - so you can inspect exactly what your agents do. Use it while developing to debug generations. It is a separate package and is intended for local development only.
+
+For setup instructions, read the bundled DevTools documentation.
+
+## Keep the SDK Current
+
+Outdated installs are the most common source of errors. Compare the installed version against the latest:
+
+- **Installed:** the `version` field in `node_modules/ai/package.json`.
+- **Latest:** run `npm view ai version`.
+
+If the installed version is a major version (or more) behind the latest, tell the user they are on an old release, and recommend upgrading before continuing. Migration guides are at https://ai-sdk.dev/docs/migration-guides.
+
+## After Making Changes
+
+Run the project's type checker. Be minimal — only set options that differ from the defaults, checking docs or source for the defaults rather than over-specifying. Most type errors come from remembered, now-changed APIs; re-check the current docs and source when they occur.

.agents/skills/debug-root/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: debug-root
+description: Use for complex, high-risk, or ambiguous debugging and code-fix tasks, especially when the user requires diagnosis before changes, explicit solution confirmation, preservation of an existing design, or comparison with reference implementations. 适用于复杂、高风险或边界不清的调试与修复任务。
+---
+
+# 四阶段调试
+
+按顺序执行：确认问题 → 诊断问题 → 确认方案 → 具体实现。除非用户已明确提供某阶段所需决定，不得跳过该阶段。
+
+## 1. 确认问题
+
+用简短文字复述目标、范围和已有约束。
+
+- 若缺少的事实或选择会实质改变实现，先提出一个具体的澄清问题。
+- 若任务已足够明确，陈述工作理解后直接进入只读诊断。
+- 可开始诊断不代表可开始修改。
+
+## 2. 诊断问题
+
+只使用读取、搜索、复现和无写入验证。不编辑文件、不格式化、不安装依赖、不生成文件、不提交代码。
+
+### 2a. 定位直接原因
+
+在实际实现中寻找证据，定位触发当前现象的直接代码路径。将根因表达为通用不变量，而不是为某个样例、标签或组件打补丁。
+
+### 2b. 横向扩散评估
+
+以直接原因中涉及的 pattern / 抽象 / 接口为锚点：
+
+- 同一 pattern 在项目中还有哪些使用点？
+- 这些使用点是否共享同一缺陷条件？
+- 如果存在共性缺陷，记录受影响范围及具体位置。
+
+若无扩散证据，明确写"横向扫描未发现扩散"，不要强行填充。
+
+### 2c. 纵向归因
+
+追问：为什么这段代码会被写成这样？
+
+- 接口设计是否缺乏约束（类型、校验、契约）？
+- 是否缺少防御机制（lint 规则、运行时断言、测试覆盖）？
+- 是否属于已知的架构短板或历史 workaround？
+
+仅在证据充分时归因，不要强行填充。
+
+### 参考实现
+
+将参考实现视为诊断证据，不视为迁移或改造授权。
+
+## 3. 确认方案
+
+### 直接原因
+
+一句话：什么代码在什么条件下产生了当前现象。
+
+### 修复层级判断
+
+| 层级 | 描述 | 本次是否适用 | 依据 |
+|------|------|-------------|------|
+| 实例修复 | 只修当前触发点 | — | — |
+| 抽象修复 | 修底层 pattern / 共享模块 | — | — |
+| 防御机制 | 加类型约束 / lint / 测试防止复发 | — | — |
+
+### 修复决策
+
+基于诊断结果，从以下三条路径中选择并论证：
+
+**路径 A：不修复**
+
+- 适用条件：预期行为被误报 / 修复成本远超问题危害 / 根因不在本系统 / 模块即将下线。
+- 输出：说明为什么当前行为是合理的，或为什么修复的代价不成立。必须引用具体证据（代码注释、设计文档、产品 spec、历史 issue、数据频率），不允许仅凭推测得出"不需要修"的结论。
+- 如果根因在外部系统，说明应由谁处理。
+
+**路径 B：最小修复（治标）**
+
+- 适用条件：问题真实存在、无扩散、无架构短板、修复成本低。
+- 输出：具体改动 + 每项改动对应的不变量 + 要维持不变的现有机制和边界。
+- 如果治标意味着不根治，说明残留风险。
+
+**路径 C：系统性修复（根治）**
+
+- 适用条件：存在扩散、存在架构短板、问题会反复出现。
+- 输出：改动范围 + 受影响模块列表 + 每项改动对应的不变量。
+- 明确标注哪些超出当前任务边界，建议后续处理。
+
+**每条路径必须附带：**
+
+- **成本**：改动量、风险、引入的复杂度。
+- **收益**：解决的问题范围、防止的未来故障。
+- **残留风险**：选这条路之后还剩什么没解决。
+
+### 影响范围和验证方法
+
+说明改动波及的模块、路径，以及验证通过的标准（测试命令、手动复现步骤等）。
+
+### 决策原则
+
+选择路径时以代码证据和产品逻辑为准，不以用户的初始判断为准。若诊断结论与用户预期矛盾，直接陈述矛盾及证据，不要回避或迎合。
+
+---
+
+除非用户已经明确确认这一准确方案，否则以 **"等待确认方案。"** 结束。不要实现。
+
+## 4. 具体实现
+
+只实现已确认的范围并运行约定的验证。
+
+- 不得趁机换架构、扩大范围或重构无关代码。
+- 实现中若发现新的关键选择，停止修改并回到"确认方案"。
+- 仅在用户明确要求时提交、推送或部署。
+
+## 用户质疑
+
+将"为什么""不满意""重新考虑"等消息视为诊断阶段输入。
+
+- 只回答问题或补充诊断。
+- 不得修改代码、不得换方案、不得把质疑视为授权。
+
+## 快速模式
+
+若用户显式表达"快速修""直接改""不用分析"等意图，跳过 2b 和 2c，仅执行 2a → 输出最小修复方案 → 确认后实现。

.agents/skills/migrate-ai-sdk-v6-to-v7/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: migrate-ai-sdk-v6-to-v7
+description: Migrate applications from AI SDK 6.x to AI SDK 7.0. Use when upgrading Vercel AI SDK packages, fixing v7 migration errors, or when the user mentions AI SDK v6, v7, upgrade, migration, breaking changes, system to instructions, fullStream, telemetry, tool context, or finalStep.
+---
+
+## AI SDK 6 to 7 Migration
+
+Use `content/docs/08-migration-guides/23-migration-guide-7-0.mdx` from the AI SDK repo as the source of truth. This skill is the working checklist; read the guide for exact examples or when behavior is unclear.
+
+## Migration Workflow
+
+1. Ensure the user has a clean backup or committed baseline before editing.
+2. Inspect `package.json` and lockfiles to identify installed `ai`, `@ai-sdk/*`, provider, UI, MCP, and telemetry packages.
+3. Upgrade AI SDK packages to latest versions, and add `@ai-sdk/otel` only if the project uses OpenTelemetry spans.
+4. Update runtime and module assumptions: Node.js must be `>=22`, and AI SDK packages are ESM-only. Replace `require()` imports with ESM imports and add `"type": "module"` or use `.mjs` where needed.
+5. Search for the v6 patterns below, migrate only the code that exists, then run typecheck and targeted tests.
+
+Prefer behavior-preserving changes. When v7 changes semantics, decide whether the app wants the new all-steps behavior or the previous final-step-only behavior.
+
+## Core API Changes
+
+- `experimental_customProvider` -> `customProvider`.
+- `experimental_generateImage` -> `generateImage`; `Experimental_GenerateImageResult` -> `GenerateImageResult`.
+- `experimental_transcribe` -> `transcribe`; `Experimental_TranscriptionResult` -> `TranscriptionResult`.
+- `experimental_generateSpeech` -> `generateSpeech`; `Experimental_SpeechResult` -> `SpeechResult`.
+- `experimental_output` option/result -> `output` option/result.
+- `CallSettings` -> `LanguageModelCallOptions & Omit<RequestOptions, 'timeout'>`; `prepareCallSettings` -> `prepareLanguageModelCallOptions`.
+- `stepCountIs` -> `isStepCount`.
+
+## Prompts and Steps
+
+- Rename top-level `system` to `instructions` for `generateText`, `streamText`, `generateObject`, `streamObject`, and `streamUI`.
+- Move `{ role: 'system' }` messages from `prompt` or `messages` into top-level `instructions`. Only use `allowSystemInMessages: true` for trusted persisted messages.
+- Rename `experimental_prepareStep` to `prepareStep`.
+- In `prepareStep`, rename returned `system` to `instructions`.
+- In `experimental_repairToolCall`, use `{ instructions }` instead of `{ system }`.
+- Audit `prepareStep` behavior: returned `instructions` and `messages` now carry forward into later steps. If code depended on one-step-only overrides, rebuild from `initialInstructions`, `initialMessages`, and `responseMessages` explicitly.
+
+## Lifecycle Callbacks
+
+- `experimental_onStart` -> `onStart`.
+- `experimental_onStepStart` -> `onStepStart`.
+- `onFinish` -> `onEnd`.
+- `onStepFinish` -> `onStepEnd`.
+- For `embed`, `embedMany`, and `rerank`, `experimental_onFinish` -> `onEnd`.
+- Callback event fields use `instructions` instead of `system`.
+
+## Usage, Telemetry, and Include Options
+
+- `usage.cachedInputTokens` -> `usage.inputTokenDetails.cacheReadTokens`.
+- `usage.reasoningTokens` -> `usage.outputTokenDetails.reasoningTokens`.
+- OpenTelemetry moved out of `ai`; install `@ai-sdk/otel` and call `registerTelemetry(new OpenTelemetry(...))` at app startup.
+- Telemetry is enabled by default once an integration is registered. Remove redundant `isEnabled: true`; use `isEnabled: false` to opt out per call.
+- Move `experimental_telemetry.tracer` into the `OpenTelemetry` constructor.
+- `experimental_telemetry` -> `telemetry`.
+- Telemetry integration callbacks: `onRerankFinish` -> `onRerankEnd`, `onEmbedFinish` -> `onEmbedEnd`. Update tracing-channel subscribers for the same event type names.
+- `experimental_include` -> `include`.
+- `includeRawChunks` -> `include.rawChunks`.
+- Request and response bodies are excluded by default. If code reads `request.body` or `response.body`, opt in with `include.requestBody` and, for `generateText`, `include.responseBody`.
+
+## Streaming, Messages, and Tools
+
+- `StreamTextResult.fullStream` -> `stream`.
+- `streamText` `onChunk` now receives all stream parts, including lifecycle, boundary, finish, abort, and error parts. Guard by `chunk.type` before assuming text/tool/raw content.
+- `step.response.messages` is no longer accumulated across previous steps. Use `result.responseMessages` for the full response message history, or flatten `result.steps`.
+- Tool execution callbacks: `experimental_onToolCallStart` -> `onToolExecutionStart`, `experimental_onToolCallFinish` -> `onToolExecutionEnd`.
+- Tool callback `experimental_context` -> `context`.
+- Split shared runtime data from tool-specific data: use top-level `runtimeContext` for orchestration state, declare per-tool `contextSchema`, and pass per-tool values through `toolsContext`.
+- Move `needsApproval` from `tool()` / `dynamicTool()` into per-call or agent `toolApproval`.
+- `experimental_activeTools` -> `activeTools`.
+- `ToolCallOptions` -> `ToolExecutionOptions`.
+- `isToolOrDynamicToolUIPart` -> `isToolUIPart`.
+
+## Content Parts and Reasoning
+
+- Tool result `{ type: 'media' }` is removed; use `{ type: 'file-data' }`.
+- Migrate `toModelOutput` `image-*`, `file-*`, `file-id`, and `image-file-id` variants to canonical `{ type: 'file', mediaType, data: { type: 'data' | 'url' | 'reference', ... } }`.
+- User message `{ type: 'image', image, mediaType? }` is deprecated; use `{ type: 'file', mediaType: 'image' | 'image/*', data }`.
+- Add support for the new `reasoning-file` content type in exhaustive switches, renderers, serializers, and validators.
+- When adopting top-level `reasoning`, remove overlapping provider-specific reasoning settings from `providerOptions` unless provider-specific settings intentionally take precedence.
+
+## Multi-Step Result Shape
+
+- `result.usage` now includes all steps; `result.totalUsage` is deprecated. Use `result.finalStep.usage` for final-step-only usage.
+- Top-level `content`, `toolCalls`, `staticToolCalls`, `dynamicToolCalls`, `toolResults`, `staticToolResults`, `dynamicToolResults`, `files`, `sources`, and `warnings` now include all steps. Use `finalStep` for previous final-step-only behavior.
+- Top-level `reasoning`, `reasoningText`, `request`, `response`, and `providerMetadata` are deprecated for final-step data. Use `result.finalStep.*`; for `streamText`, await `result.finalStep`.
+- Apply the same result-shape rules to `onEnd` events.
+
+## Stream Response Helpers
+
+The `streamText` result helper methods are deprecated. Replace result methods with top-level stateless helpers:
+
+- `result.toUIMessageStream(...)` -> `toUIMessageStream({ stream: result.stream, ... })`.
+- `result.toUIMessageStreamResponse(...)` -> `toUIMessageStream(...)` plus `createUIMessageStreamResponse({ stream })`.
+- `result.pipeUIMessageStreamToResponse(response, ...)` -> `toUIMessageStream(...)` plus `pipeUIMessageStreamToResponse({ response, stream })`.
+- `result.toTextStreamResponse()` -> `toTextStream({ stream: result.stream })` plus `createTextStreamResponse({ stream })`.
+- `result.pipeTextStreamToResponse(response)` -> `toTextStream({ stream: result.stream })` plus `pipeTextStreamToResponse({ response, stream })`.
+
+## Package-Specific Checks
+
+- MCP: `MCPTransportConfig.redirect` now defaults to `'error'`. Only set `redirect: 'follow'` for trusted MCP servers that rely on redirects.
+- Vue: `@ai-sdk/vue` `Chat` class is deprecated. Prefer `useChat`, including getter/ref init for reactive chat inputs.
+- Anthropic and `@ai-sdk/google-vertex/anthropic`: `providerMetadata.anthropic.cacheCreationInputTokens` was removed. Use `usage.inputTokenDetails.cacheWriteTokens`; raw Anthropic usage remains at `finalStep.providerMetadata?.anthropic?.usage`.
+- Google: rename `GoogleGenerativeAI*` types, classes, and functions to `Google*`, e.g. `createGoogleGenerativeAI` -> `createGoogle`. The `google` entry point is unchanged.
+
+## Validation
+
+Run the project typecheck after edits, then the smallest relevant test suite. Also smoke-test streaming, chat UI, tool execution, telemetry, and multi-step flows if the migration touched them. If type errors remain, search the migration guide for the exact removed or renamed symbol before inventing a workaround.