@lark-apaas/coding-steering 0.1.32-dev.1b5c337 → 0.1.32-dev.1e6418b

package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/debugging.md

@@ -1,76 +0,0 @@
-# 调试：mcp_call、错误定位、本地模式
-
-## mcp_call
-
-云端沙箱里的开发态 MCP 调试工具。它经 MCP 网关连当前应用的开发态 MCP Server，以当前用户身份发起，与预览页里操作应用的身份一致。
-
-| action | 参数 | 返回 |
-|---|---|---|
-| `list_tools` | 无 | server 名、每个工具的 name / title / description / annotations / `_meta.ui` / inputSchema（长 schema 截断）、资源清单 |
-| `call` | `tool_name`（带 prefix 的完整名）、`arguments`（JSON 对象**字符串**，缺省 `{}`）、`safe` | 文本内容、`structuredContent`（截断）、`isError`、耗时 |
-| `read_resource` | `resource_uri`（如 `ui://order/list`、`skill://app/SKILL.md`） | uri、mimeType、`_meta.ui`、正文前若干字符 |
-
-- `safe`：工具未声明 `annotations.readOnlyHint: true` 时，`call` 在发起前被拒为 `requires_safe`。确认这次调用只影响你自建的测试数据后再传 `safe: true`；用户已有的真实数据未经明确要求不动。只读工具反复撞这条，是源码漏了 `readOnlyHint: true`，补注解而不是加 `safe`。
-- 单个子请求 60s 无动静即超时，整次动作 600s 硬上限。server 是无状态 JSON 模式（不开 SSE），`ctx.extra.sendNotification` 发的 `notifications/progress` 到不了客户端、不会重置计时；超时只能靠缩小单次处理范围。
-- 同一工具连续失败 4 次熔断 60s：先改代码或入参，不是等。`requires_safe`、`tool_not_found`、`aborted` 不计入熔断。
-- 失败或 `isError: true` 时结果尾部附 Trace-ID 对应的 `server.log` / `trace.log` 片段。
-
-## 回路
-
-1. 改工具 / 资源 / 界面。
-2. `npx miaoda-mcp validate`。失败即改，不进下一步。
-3. 等 dev server 重启（`nest --watch` 会自动重启；界面改动由 `[mcp-ui]` 插件自动重建）。
-4. `list_tools` 核对清单与源码一致（`visibility: ['app']` 的工具也在清单里，属正常）。
-5. `call` 逐个工具跑一次真实入参：先只读，再写（`safe: true`）。写工具跑两次验证幂等语义。
-6. 带界面的工具 `read_resource`。
-7. 每个 `McpToolError` 分支构造一次触发（不存在的 ID、非法状态），确认 `isError: true` 且 `code` 与 `description` 预告一致。
-8. 更新 `server/mcp/SKILL.md`，`read_resource` `skill://app/SKILL.md` 确认最新正文已生效。
-
-## 错误分流
-
-| 现象 | 原因 | 动作 |
-|---|---|---|
-| 端点 404「当前工程可能尚未接入 MCP 层，或 dev server 尚未就绪」 | `server/mcp` 不存在；dev server 没起来；零工具零资源无应用 Skill（SDK 此时返回 404） | 确认三者；有工具但 404 看启动日志是否被校验阻断 |
-| `list_tools` 少了某个工具 | 类没进任何模块 `providers`，无任何日志提示 | 对照启动日志「已注册 N 个 MCP 工具：…」，缺的加进所属业务模块的 `providers` |
-| dev server 起不来，报「MCP 工具必须使用单例及单例依赖」 | 工具类或其依赖是 request / transient 作用域 | 改回单例，身份从 `ctx.user` 取 |
-| 启动日志「MCP 定义校验失败」 | 工具名不合法 / 重名、资源 URI 不以 `ui://` 开头 / 重名、`ui.resourceUri` 找不到 `@McpUiResource()`、同一方法同时标两个装饰器 | 按日志逐条修，`validate` 能提前查出 |
-| `tool_not_found` | 名字没带 prefix，或用了 `title` | 用 `list_tools` 里的 name |
-| `requires_safe` | 见上文 `safe` | 只读工具补注解；写工具确认测试数据后 `safe: true` |
-| `isError` + `code: MCP_USER_REQUIRED` | 请求未携带用户身份 | 请求没经过网关 / 开发服务入口。`mcp_call` 自带身份，正常不会撞到；撞到说明链路有问题，不改 `requireUser` |
-| `isError` + 业务 `code` | 工具按设计抛了 `McpToolError` | 对照 `description` 检查是否预告了该 code；入参是否真的该触发 |
-| `isError` + 通用失败提示 | 方法抛了非 `McpToolError` 的异常 | 读结果尾部 Trace-ID 日志定位；该异常若是可预期的业务失败，改抛 `McpToolError` |
-| zod 校验错误 | 入参不符 inputSchema | 对照 `list_tools` 里的 schema 改 `arguments`；schema 本身不合理就改源码 |
-| 「工具已执行，但输出与其声明的 outputSchema 不符」 | `structuredContent` 与 `outputSchema` 对不上 | 工具已跑通：改返回值或改 schema，不重试同一调用 |
-| `timeout` | 单个子请求 60s 无动静，或整次超 600s | 收窄入参 / 分页 / 拆成「发起 + 查状态」两个工具；加进度通知无效（JSON 模式发不出去） |
-| `connect_failed` / `http_error` / `unauthorized` | 网关或预览环境问题 | 看 statusCode；不是应用代码问题时告知用户，不改代码绕 |
-| 「已连续 4 次调用失败，已暂停对它的重复调用」 | 同一工具连续失败 4 次熔断 | 先修实现或入参，60s 后再验 |
-| 「当前运行环境不支持开发态 MCP 调试」 | 本地 CLI 宿主没有 `mcp_call` 后端 | 走下节本地模式 |
-| `read_resource` 报「读取 MCP Apps 界面产物失败」 | `dist/mcp-ui/<entry>.html` 不存在 | 入口名对齐 `readMcpUiTemplate('<entry>')`；确认 `client/mcp-ui/<entry>/index.html` 存在；看 `[mcp-ui]` 日志是否构建失败 |
-
-同一失败不原样重试。改完代码再验，每轮只改一个变量。
-
-## 本地模式（IDE Agent / 本地 CLI）
-
-本地开发（`MIAODA_LOCAL_DEV=1`，`npm run dev` 走 `dev-local.js`）没有 `mcp_call`，MCP 客户端是你自己或 IDE 里的 Agent。
-
-- 带身份的入口只有 dev server：`http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/__innerapi__/mcp`（本地 `CLIENT_BASE_PATH` 通常为空）。dev server 代理把 `+env-pull` 拉到的 `SUDA_WEBUSER` 注入为身份头，工具里的 `ctx.user` 就是开发者本人。直连 NestJS 端口没有身份，会撞 `MCP_USER_REQUIRED`。
-- 标准 MCP 客户端配置 Streamable HTTP、URL 填上面地址即可连接。
-- 看原始请求响应：`npx @modelcontextprotocol/inspector`，指向同一地址。
-- 快速验证：
-
-```bash
-curl -s -X POST 'http://localhost:<port><base>/__innerapi__/mcp' \
-  -H 'content-type: application/json' \
-  -H 'accept: application/json, text/event-stream' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
-```
-
-`accept` 必须同时含两种类型，否则 406。`GET` / `DELETE` 返回 405，端点只接受 `POST`。
-
-- 平台目录接口 `GET <入口>/__innerapi__/mcp/manifest` 返回工具、资源、应用 Skill 正文与源码定位，是面板用的聚合接口，不是工具调用接口。
-
-## 汇报
-
-- 用业务表述：「`order_search` 返回 3 条待支付订单」「取消不存在的订单返回 ORDER_NOT_FOUND，符合预期」；不贴整段 JSON。
-- 写操作说明动了哪些测试数据。
-- 未验证的分支明说未验证，不写「已全部通过」。

package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/mcp-apps.md

@@ -1,182 +0,0 @@
-# MCP Apps：给工具结果加界面
-
-一个 MCP App = 一个 `ui://` 资源（单文件 HTML）+ 至少一个用 `ui.resourceUri` 指向它的工具。宿主调用工具后把 HTML 放进沙箱 iframe 渲染，再把工具入参与结果通过通知推给界面；界面里的操作经宿主回调 server 的工具。
-
-## 先决定要不要界面
-
-| 信号 | 做法 |
-|---|---|
-| 结果是列表 / 详情 / 状态，文本 + `structuredContent` 已够 Agent 继续推理 | 不加界面 |
-| 用户要从多条候选里挑一个（航班、订单、文件） | 选择型界面，选中后 `updateModelContext` 同步给模型 |
-| 结果是图表、地图、对比等空间信息 | 展示型界面 |
-| 写操作前要让用户在界面里核对、确认 | 确认型界面，确认动作经 `callServerTool` 调一个 `visibility: ['app']` 的工具 |
-
-不需要的地方不加：文本更快，也没有构建与 CSP 负担。
-
-## 目录与构建
-
-```text
-client/mcp-ui/<entry>/
-├── index.html      # 入口骨架，见下
-└── main.tsx        # 或 main.ts；React 或原生 JS 都行
-dist/mcp-ui/<entry>.html   # 预设产物，@McpUiResource 经 readMcpUiTemplate 读取
-```
-
-```html
-<!-- client/mcp-ui/<entry>/index.html -->
-<!doctype html>
-<html><head><meta charset="utf-8" /></head>
-<body><div id="root"></div><script type="module" src="./main.tsx"></script></body></html>
-```
-
-`<div id="root">` 不能少：缺了 `createRoot(document.getElementById('root')!)` 拿到 null，iframe 全白，而 `validate` 与 `read_resource` 都不会报错。
-
-- `<entry>` 只允许 `A-Z a-z 0-9 _ -`。
-- Vite 预设的 `mcp-ui` 插件：检测到 `client/mcp-ui/` 就为每个入口跑一次独立子构建，JS / CSS / 资源全部内联成一个 HTML。开发态监听 `client/`、`shared/` 与入口目录，改完自动重建；生产在主构建之后构建，并同步到发布目录 `dist/server/dist/mcp-ui`。
-- 子构建只带 React 插件与 `@shared` 别名：`@/`、`@client/*`、`@server/*` 解析不到，不支持 styled-jsx。样式写在入口自己的 CSS 里，不依赖主应用的全局样式与 Tailwind；颜色字体优先读宿主下发的 CSS 变量（`useHostStyles`）。
-- 界面代码归 `tsconfig.app.json` 管（浏览器代码）。放到 `server/` 下会被服务端 tsconfig 编译报 JSX 错误。
-- `@modelcontextprotocol/ext-apps` 随 SDK 安装，直接 import。解析失败时把它加进 `package.json` `dependencies`，版本与 `node_modules/@lark-apaas/nestjs-mcp/package.json` 里声明的一致（1.x），不装 2.x。
-
-## server 侧：声明资源并关联工具
-
-```typescript
-import { McpTools, McpTool, McpUiResource, readMcpUiTemplate } from '@lark-apaas/fullstack-nestjs-core';
-
-@McpTools({ prefix: 'order_' })
-export class OrderMcpTools {
-  @McpTool({
-    title: '查询订单',
-    description: '…',
-    inputSchema: SearchOrdersInput,
-    outputSchema: SearchOrdersOutput,
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    ui: { resourceUri: 'ui://order/list' },            // 结果由该界面渲染；模型与界面都可调
-  })
-  async search(/* … */) { /* … */ }
-
-  @McpTool({
-    description: '按 ID 取一条订单明细，供订单列表界面展开详情时调用。',
-    inputSchema: GetOrderInput,
-    outputSchema: GetOrderOutput,
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    ui: { resourceUri: 'ui://order/list', visibility: ['app'] },   // 只供界面回调，模型工具清单里隐藏
-  })
-  async detail(/* … */) { /* … */ }
-
-  @McpUiResource({
-    uri: 'ui://order/list',
-    title: '订单列表',
-    description: '分页订单列表，可展开详情、勾选后取消。',
-    csp: { connectDomains: [], resourceDomains: [] },   // 界面要访问的外部域名写这里，默认全禁
-  })
-  listView() {
-    return readMcpUiTemplate('order-list');            // 读 dist/mcp-ui/order-list.html
-  }
-}
-```
-
-- `uri` 必须以 `ui://` 开头，全应用唯一；`ui.resourceUri` 找不到对应 `@McpUiResource()` 时 `validate` 与启动都会报错。
-- `visibility` 默认 `['model', 'app']`。只给界面用的取数 / 刷新工具写 `['app']`，避免污染模型的工具清单。隐藏由宿主做，server 不过滤：`mcp_call` 的 `list_tools` 仍会列出它，`_meta.ui.visibility` 为 `['app']` 即正确，不要因为「还在清单里」去改代码。
-- 一个工具既返回 `structuredContent` 又绑界面是常态；模型还需要纯数据继续推理时，拆成「取数工具（无 ui）」+「展示工具（绑 ui）」。
-- 资源读取沿用 `requireUser`：无身份的 `resources/read` 会被拒。
-
-## 界面侧：接结果、回调工具
-
-React 写法（`@modelcontextprotocol/ext-apps/react`）：
-
-```tsx
-// client/mcp-ui/order-list/main.tsx
-import { useState } from 'react';
-import { createRoot } from 'react-dom/client';
-import { useApp, useHostStyles } from '@modelcontextprotocol/ext-apps/react';
-// 与 outputSchema 对齐的 TS 类型放 shared/（如 shared/mcp-types.ts），server 与界面共用；@shared 是子构建唯一可用别名
-import type { OrderPage as Page } from '@shared/mcp-types';
-
-function OrderList() {
-  const [page, setPage] = useState<Page | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  const { app, isConnected } = useApp({
-    appInfo: { name: 'order-list', version: '1.0.0' },
-    capabilities: {},
-    onAppCreated: (app) => {
-      // 宿主推送：工具入参（可先渲染骨架）、工具结果、取消
-      app.ontoolinput = ({ arguments: args }) => console.debug('input', args);
-      app.ontoolresult = (result) => {
-        if (result.isError) setError(textOf(result));
-        else setPage(result.structuredContent as Page);
-      };
-      app.ontoolcancelled = () => setError('调用已取消');
-    },
-  });
-  useHostStyles(app, app?.getHostContext()); // 应用宿主主题、CSS 变量与字体；第二参数让首帧就生效
-
-  async function cancel(orderId: string) {
-    if (!app) return;
-    const res = await app.callServerTool({ name: 'order_cancel', arguments: { orderId } });
-    if (res.isError) return setError(textOf(res));
-    // 把用户在界面里做的选择同步给模型，模型下一轮据此继续
-    await app.updateModelContext({
-      content: [{ type: 'text', text: `用户已在界面中取消订单 ${orderId}` }],
-      structuredContent: { cancelledOrderId: orderId },
-    });
-    setPage((p) => p && { ...p, items: p.items.filter((i) => i.id !== orderId) });
-  }
-
-  if (!isConnected) return <p>连接宿主中…</p>;
-  if (error) return <p role="alert">{error}</p>;
-  if (!page) return <p>等待查询结果…</p>;
-  return (
-    <ul>
-      {page.items.map((o) => (
-        <li key={o.id}>
-          {o.customer} · {o.amount} 元 · {o.status}
-          {o.status === 'pending' && <button onClick={() => cancel(o.id)}>取消</button>}
-        </li>
-      ))}
-    </ul>
-  );
-}
-
-function textOf(result: { content?: Array<{ type: string; text?: string }> }) {
-  return result.content?.find((c) => c.type === 'text')?.text ?? '调用失败';
-}
-
-createRoot(document.getElementById('root')!).render(<OrderList />);
-```
-
-原生 JS 写法（`@modelcontextprotocol/ext-apps`）：
-
-```typescript
-import { App } from '@modelcontextprotocol/ext-apps';
-const app = new App({ name: 'order-list', version: '1.0.0' }, {});
-app.ontoolresult = (result) => render(result.structuredContent);
-await app.connect();
-```
-
-宿主能力速查（`App` 实例方法）：
-
-| 方法 | 用途 |
-|---|---|
-| `ontoolinput` / `ontoolinputpartial` / `ontoolresult` / `ontoolcancelled` | 宿主推送的入参（完整 / 流式）、结果、取消 |
-| `callServerTool({ name, arguments })` | 经宿主调本 server 的工具；工具名带 prefix；返回标准 `CallToolResult` |
-| `updateModelContext({ content?, structuredContent? })` | 把界面状态同步给模型，不触发模型立刻回复 |
-| `sendMessage({ role: 'user', content })` | 以用户身份发一条消息，触发模型回复 |
-| `getHostContext()` / `onhostcontextchanged` | 主题、`displayMode`、`containerDimensions`、`locale`、`timeZone`、发起本次渲染的 `toolInfo` |
-| `requestDisplayMode({ mode })` | 请求 inline / fullscreen 等展示模式，以 `availableDisplayModes` 为限 |
-
-`useApp` 默认开自动调高（`autoResize`），内容变化不用手动发尺寸。
-
-## 界面约束
-
-- 不存凭证、不读 cookie / localStorage 里的登录态：iframe 是独立 origin，用户在业务系统的登录态带不进来。所有数据走 `callServerTool`，身份由宿主转发。
-- 外部域名写进 `@McpUiResource` 的 `csp`：`connectDomains`（fetch / WebSocket）、`resourceDomains`（图片、脚本、样式）、`frameDomains`（内嵌 iframe）、`baseUriDomains`；默认全禁，漏写表现为资源静默加载失败。
-- 业务返回值用 `textContent` 或 JSX 文本渲染，不拼 `innerHTML`。
-- 每次调用重新注入数据；界面不假设自己能跨调用保留状态。
-- 宿主不支持 MCP Apps 时只显示 `content` 文本，所以带界面的工具也要返回可读的文本摘要。
-
-## 调试
-
-- `mcp_call` `read_resource` 读 `ui://…`：成功返回 `text/html;profile=mcp-app` 与正文开头；报「读取 MCP Apps 界面产物失败」→ `dist/mcp-ui/<entry>.html` 不存在：入口名与 `readMcpUiTemplate('<entry>')` 不一致、`client/mcp-ui/<entry>/index.html` 缺失、或 dev server 还没重建，看 dev server 日志里 `[mcp-ui]` 前缀的行。
-- 界面逻辑用 `mcp_call` 看不到；先用 `call` 确认 `structuredContent` 形状正确，再在预览里看渲染。宿主渲染失败时保留工具结果，只重试界面。
-- 界面里调 `callServerTool` 失败，错误也走 server 日志：按 Trace-ID 查。

package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/tool-authoring.md

@@ -1,197 +0,0 @@
-# 工具类写法
-
-API 形状以 `node_modules/@lark-apaas/nestjs-mcp/dist/index.d.ts` 为准。下面是当前版本的写法与约束；字段名对不上时以 d.ts 为准。
-
-## 骨架
-
-```typescript
-// server/mcp/tools/order.tools.ts
-import { z } from 'zod';
-import {
-  McpTools,
-  McpTool,
-  McpToolError,
-  type Infer,
-  type McpContext,
-  type McpToolResult,
-} from '@lark-apaas/fullstack-nestjs-core';
-import { OrderService } from '@server/modules/order/order.service';
-
-// schema 提成常量：方法签名用 Infer<typeof …> 引用，清单导出也从这里取
-export const SearchOrdersInput = {
-  keyword: z.string().optional().describe('客户名关键字，模糊匹配'),
-  limit: z.number().int().min(1).max(50).default(20).describe('单页条数'),
-  cursor: z.string().optional().describe('上一页返回的 nextCursor；首页不传'),
-};
-export const SearchOrdersOutput = {
-  items: z.array(
-    z.object({
-      id: z.string(),
-      customer: z.string(),
-      amount: z.number().describe('金额，单位元'),
-      status: z.enum(['pending', 'paid', 'cancelled']),
-    }),
-  ),
-  nextCursor: z.string().nullable().describe('还有下一页时非空，原样传回 cursor'),
-};
-
-export const CancelOrderInput = { orderId: z.string().describe('订单 ID，来自 order_search 的 items[].id') };
-export const CancelOrderOutput = { orderId: z.string(), status: z.literal('cancelled') };
-
-@McpTools({ prefix: 'order_' })
-export class OrderMcpTools {
-  constructor(private readonly orders: OrderService) {}
-
-  @McpTool({
-    title: '查询订单',
-    description:
-      '按客户名关键字分页查询当前用户可见的订单。用户想找订单、看订单列表时调用；一页最多 50 条，超出用 cursor 翻页。',
-    inputSchema: SearchOrdersInput,
-    outputSchema: SearchOrdersOutput,
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  })
-  async search(
-    input: Infer<typeof SearchOrdersInput>,
-    ctx: McpContext,
-  ): Promise<McpToolResult<typeof SearchOrdersOutput>> {
-    const userId = ctx.user.userId!; // requireUser 默认开启，执行到这里必有值；取一次往下传
-    const page = await this.orders.search({ ...input, userId });
-    return {
-      structuredContent: page,
-      content: [{ type: 'text', text: `找到 ${page.items.length} 条订单` }],
-    };
-  }
-
-  @McpTool({
-    title: '取消订单',
-    description:
-      '取消一个待支付订单。仅在用户明确要求取消、且订单状态为 pending 时调用；订单不存在返回 ORDER_NOT_FOUND，状态不允许返回 ORDER_NOT_CANCELLABLE。重复取消同一订单返回同一结果。',
-    inputSchema: CancelOrderInput,
-    outputSchema: CancelOrderOutput,
-    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-  })
-  async cancel(
-    input: Infer<typeof CancelOrderInput>,
-    ctx: McpContext,
-  ): Promise<McpToolResult<typeof CancelOrderOutput>> {
-    const userId = ctx.user.userId!;
-    const order = await this.orders.findVisibleTo(input.orderId, userId);
-    if (!order) throw new McpToolError('订单不存在', { code: 'ORDER_NOT_FOUND' });
-    if (order.status === 'cancelled') return { structuredContent: { orderId: order.id, status: 'cancelled' } };
-    if (order.status !== 'pending') {
-      throw new McpToolError(`订单状态为 ${order.status}，不能取消`, { code: 'ORDER_NOT_CANCELLABLE' });
-    }
-    await this.orders.cancel(order.id, userId);
-    return { structuredContent: { orderId: order.id, status: 'cancelled' } };
-  }
-}
-```
-
-```typescript
-// server/modules/order/order.module.ts —— 工具类和它依赖的 Service 注册在同一个模块
-import { Module } from '@nestjs/common';
-// OrderController / OrderService / OrderMcpTools 的 import 略
-
-@Module({
-  controllers: [OrderController],
-  providers: [OrderService, OrderMcpTools],
-})
-export class OrderModule {}
-```
-
-`@McpTools()` 自带 `@Injectable()`。SDK 启动时用 DiscoveryService 扫所有 provider；类没进任何模块的 `providers` 就扫不到它，启动日志不会有任何提示，工具静默缺席——启动日志「已注册 N 个 MCP 工具：…」列出的名字才是真相，对不上就是没注册。工具类及其依赖必须是单例：request / transient 作用域会在启动时抛「MCP 工具必须使用单例及单例依赖」，整个应用起不来。
-
-## 装饰器选项
-
-`@McpTool(options)`：
-
-| 字段 | 说明 |
-|---|---|
-| `name?` | 默认取方法名；最终工具名 = `prefix + name`，需匹配 `^[A-Za-z0-9_.-]{1,128}$`，全应用唯一 |
-| `title?` | 面向人的展示名，面板里显示 |
-| `description` | 必填，面向模型 |
-| `inputSchema?` / `outputSchema?` | zod：原始形状 `{ a: z.string() }` 或 `z.object({...})` 都行；顶层必须是对象 |
-| `annotations?` | `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`，四项都写 |
-| `ui?` | `{ resourceUri: 'ui://…', visibility?: ['model' \| 'app'] }`，见 `mcp-apps.md` |
-| `meta?` | 额外 `_meta`，与 `ui` 生成的字段合并 |
-
-`@McpTools({ prefix? })`：给类下所有工具名加前缀，如 `order_`。
-
-## 方法签名与返回值
-
-- 固定 `(input, ctx)`。无入参的工具 `input` 为 `Record<string, never>`，仍要写第二个参数 `ctx`。
-- 声明了 `outputSchema`：返回 `{ structuredContent }`，类型由 schema 推导；`content` 可选，SDK 会自动补一份 JSON 文本给不支持结构化输出的客户端。加一句业务摘要的 `content` 让文本客户端也能读。
-- 未声明 `outputSchema`：返回 `{ content: [{ type: 'text', text }] }`；`content` 还支持 `image` / `audio` / `resource_link` 块。
-- `isError: true` 由 SDK 在捕获 `McpToolError` 时设置，不需要手动返回。
-
-## McpContext
-
-| 字段 | 用途 |
-|---|---|
-| `user` | 与 REST 里的 `req.userContext` 同源：`userId` / `tenantId` / `roles` / `env`（`preview` \| `runtime`）等，字段全部可选（`userId?: string`）。默认 `requireUser: true`，缺 `userId` 时 SDK 直接返回 `MCP_USER_REQUIRED`、方法不执行，所以方法体开头 `const userId = ctx.user.userId!;` 取一次往下传；不要为迁就类型去改 Service 签名 |
-| `request` | 原始 HTTP 请求，读 header、logid |
-| `signal` | 客户端取消时触发，长任务把它传给下游 |
-| `requestId` | MCP 请求 id |
-| `extra` | SDK 的 `RequestHandlerExtra`（`sessionId` / `requestId` / `authInfo` 等）。它有 `sendNotification`，但端点是无状态 JSON 模式，`notifications/progress` 发不到客户端——长任务别靠进度通知续命，拆成「发起 + 查状态」两个工具 |
-
-## 错误处理
-
-- 可预期的业务失败抛 `new McpToolError(message, { code?, data? })`：SDK 转成 `isError: true`，`message` / `code` / `data` 原样进 Agent 上下文。`code` 用 `SCREAMING_SNAKE`，并在 `description` 里预告，Agent 才知道怎么应对。
-- 其他异常：SDK 记日志、返回通用失败提示，Agent 看不到原因。调试时看到「通用失败提示」就去读 Trace-ID 日志。
-- 入参校验交给 zod，方法体不重复判空；zod 失败由 SDK 返回，方法不执行。
-
-## description 怎么写
-
-消费方 Agent 只靠 `description` 与字段 `.describe()` 决定调不调、怎么填。写全五件事：用途、何时调用（含前置条件）、参数从哪来（「来自 order_search 的 items[].id」）、返回什么、失败会返回哪些 code。写操作再加一句幂等语义（「重复取消返回同一结果」）。
-
-字段描述写单位、格式、取值来源；枚举用 `z.enum`；入参不用 `z.any()` / `z.unknown()`。
-
-## 开通（首次）
-
-1. 前置检查通过（见 SKILL.md）。
-2. 建 `server/mcp/tools/<域>.tools.ts`，至少一个只读工具复用现有 Service。
-3. 把工具类加进所属业务模块的 `providers`。
-4. 写 `server/mcp/SKILL.md`（下节）。
-5. `npx miaoda-mcp validate` 通过，`.spark/mcp/manifest.json` 一起提交。
-6. 进 `debugging.md` 的调试回路。
-
-## 应用 Skill：`server/mcp/SKILL.md`
-
-给消费方 Agent 的使用说明，SDK 自动注册为资源 `skill://app/SKILL.md`（`text/markdown`），每次请求重新读文件，改完不用重启；上限 1 MiB，必须是工程内的普通文件。
-
-必含：`name` / `description` frontmatter、适用场景、实际工具名与关键参数、调用顺序、需要用户确认的边界、身份与权限要求、每个错误 code 的处理、界面 URI（如有）。只写已实现的能力；不写凭证、用户数据、内部实现。
-
-```markdown
----
-name: orders
-description: 查询当前用户可见的订单，并在用户明确要求后取消待支付订单。
----
-# 订单能力
-- 需要已登录用户身份；只返回当前用户可见的订单。
-- 找订单：order_search，keyword 模糊匹配客户名；nextCursor 非空时用 cursor 翻页。
-- 取消订单：只有用户明确要求取消、且 status 为 pending 时调用 order_cancel；orderId 取自 order_search 的 items[].id。
-- ORDER_NOT_FOUND：请用户核对订单 ID。ORDER_NOT_CANCELLABLE：告知当前状态，不重试。
-- 支持界面的宿主会用 ui://order/list 展示查询结果。
-```
-
-## 校验与清单
-
-- `npx miaoda-mcp validate`：用工程自身 TypeScript 加载 `server/mcp` 源码（不启动应用），检查工具名格式、重名、`ui://` 前缀、`ui.resourceUri` 引用，写入 `.spark/mcp/manifest.json`。
-- `npx miaoda-mcp validate --check`：只比对不写入，CI 用。
-- 开发态启动应用也会写清单；生产不写。删光工具、资源与应用 Skill 后再跑一次 `validate` 清理旧清单。
-- 启动期同样的校验失败会阻断启动（「MCP 定义校验失败」），一个方法不能同时标 `@McpTool()` 与 `@McpUiResource()`。
-
-## 模块配置（一般不动）
-
-```typescript
-PlatformModule.forRoot({
-  mcp: {
-    serverName: 'my-app',   // 默认 SUDA_APP_ID，再缺省为 miaoda-app
-    serverVersion: '1.0.0',
-    instructions: '…',      // initialize 响应里的说明
-  },
-});
-// 关闭端点：PlatformModule.forRoot({ mcp: false })
-```
-
-`requireUser` 保持默认 `true`。零工具、零资源、无应用 Skill 时端点返回 404，这是正常状态不是故障。