@xiongtao.xt/tau-plugins 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 更新记录
 
+## 0.16.0
+
+- 新增独立 `usePluginServices()`，由插件渲染运行时提供已有编译与转换服务；博客及无服务的宿主返回 undefined。
+- 服务按当前窗口和工作区绑定取消与失效保护，静态编辑器组件无需调用 activate；原有 context.services 保持不变。
+- 不修改 useSourceBlock、EditorKit、文档节点协议或编译接口；保留 TTS、上传、聊天工具展示及 TikZ 服务删除边界。
+
+## 0.15.0
+
+- 新增 `context.chat.registerToolRenderer`，按本插件 MCP ID 与原始工具名异步登记 React 工具渲染器，激活成功后发布，停用、重载或切库时回收。
+- 本地工具支持 `{ content, render: { version, data } }`，展示数据沿 pi 会话保存并支持历史回放；保留默认展示、宿主审批及失败/取消语义。
+- 渲染器仅匹配绑定工具，组件接收独立执行快照；修复异常订阅中断回收及审批/重试恢复状态的终态收敛。
+- 保留 0.13.0 的 TTS、资源上传接口及 0.14.0 移除 TikZ 服务的边界；UI 包无需升级。
+
 ## 0.14.0
 
 - 移除 `PluginServices.tikz` 和 `context.services.tikz.compile`。TikZ 编译、字体与文档块由独立插件 tau.tikz 提供，宿主不再保留编译实现或转发入口。

package/MCP.md

@@ -84,6 +84,31 @@ context.mcp.register({
 - 旧实例、旧数据库和重连前的调用不能转交给新实例。不要缓存上下文到下一次启用。
 - Skill 可描述这些工具的用途；ctx.ai.chat/stream 仍是文本生成接口，不会因为注册 MCP 而自动获得工具调用能力。
 
+## 聊天工具自定义渲染
+
+`context.chat.registerToolRenderer` 的类型契约自 SDK 0.15.0 提供，须搭配包含实现的客户端构建。旧客户端即使同为 0.59.0 也可能没有此能力，必须检查方法是否存在；只提高 SDK 类型版本不能替代客户端检查。
+
+在 `async activate(context)` 中，先通过 `context.mcp.register()` 声明工具，再注册组件并 await：
+
+```tsx
+await context.chat.registerToolRenderer({
+  mcpId: "notes",
+  toolName: "read_note",
+  component: ({ execution, renderDefault }) =>
+    execution.status === "success" ? <div>{execution.output}</div> : renderDefault(),
+});
+```
+
+这段代码放在异步激活函数内；`mcpId` 是本插件注册 MCP 时的 id，`toolName` 是其中的原始工具名，不拼接全局名称。可以绑定本地工具或本插件 transport 中的远端工具，不能绑定内置工具、其他插件或用户手动添加的服务器。返回 `Promise<Disposable>`，失败随 await 抛出；激活成功后才发布组件，停用或切库自动回收，无需再次 context.register。
+
+本地工具可返回 `{ content: string, render: { version: 1, data: JsonValue } }`；content 提供模型文本及默认展示，render.data 是独立的可持久化展示数据。组件参数为 `PluginToolRendererProps`（从 `@tau/plugins` 导入），包括 execution、isDark、parsedInput、inputParseError、data、dataVersion 和 renderDefault。展示版本为正整数，数据只接受有限 JSON；不支持的版本应调用 renderDefault。
+
+transport 工具当前读取 execution.output，不提供标准 structuredContent 或 MCP Apps HTML 界面能力。宿主决定渲染路由，远端返回不能选择其他渲染器。等待审批继续使用宿主审批 UI，失败和取消显示通用工具行。
+
+关闭 MCP 或工具执行开关不会隐藏历史结果；停用插件时回到通用输入输出，再启用后恢复。组件不应在渲染或挂载时自动执行工具。使用现有 React 和 `@tau/ui`/主题样式，不导入内部聊天包。
+
+完整示例见仓库 `scripts/plugins/fixtures/chat-tool-renderer.tsx`。在宿主仓库执行 `node scripts/plugins/verify-chat-author.mjs`，会生成 SDK 包、在独立目录安装、类型检查并构建该示例 ZIP；不安装到用户目录，也不发布。产物和验收记录保存在 `output/plugin-chat-sdk/`。
+
 ## 验证
 
 检查类型并打包后，在包含此实现的客户端启用插件：确认两项 MCP 出现在现有页面和快捷面板；测试整项开关、逐工具开关、外部连接配置和重连，再测试停用、重新启用及重启后偏好保留。真实服务器连接与模型调用需使用自己的服务和已配置的模型。

package/SERVICES.md

@@ -16,6 +16,12 @@
 | `ffmpeg.probe(file, options?)`           | `{ name, data: Blob }`                            | `{ format, streams }`               |
 | `ffmpeg.run(input, options?)`            | `{ files, args, outputs }`                        | `{ files, log }`                    |
 
+## 在静态组件中获取服务
+
+SDK 0.16.0 的 `usePluginServices()` 返回当前插件可用的同一组服务，类型为 `PluginServices | undefined`。服务由插件运行时提供，独立编辑窗口无需 activate；博客和未包裹的普通组件返回 undefined，组件应显示已保存结果或源码。它不属于源码块或 EditorKit，不要将服务存入模块全局变量。
+
+组件需用自己的 AbortSignal 取消过期或卸载的调用，宿主同时处理窗口与工作区失效。内容插件的启停按现有重启生效规则处理；写入启停意图不会提前拆掉当前窗口已生效的贡献。
+
 ## 取消与错误
 
 第二个参数均支持 `{ signal: AbortSignal }`。插件停用会自动取消本实例的任务，不必重复传入 `context.signal`。用户主动取消可使用单次任务的 `AbortController`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiongtao.xt/tau-plugins",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/types/packages/plugins/src/chat.d.ts

@@ -0,0 +1,24 @@
+import type { ComponentType, ReactNode } from "react";
+import type { ToolCallExecutionState } from "../../shared/src/chat-core/index";
+import type { Disposable } from "./contract";
+import type { JsonValue } from "./json";
+export type { ToolCallExecutionState } from "../../shared/src/chat-core/index";
+export interface PluginToolRendererProps {
+    execution: Readonly<ToolCallExecutionState>;
+    isDark: boolean;
+    parsedInput: unknown | null;
+    inputParseError?: string;
+    data: JsonValue | null;
+    dataVersion: number | null;
+    renderDefault(): ReactNode;
+}
+export interface PluginToolRendererDefinition {
+    mcpId: string;
+    toolName: string;
+    component: ComponentType<PluginToolRendererProps>;
+}
+export interface PluginChat {
+    /** 激活成功后发布，停用时自动回收；展示不受 MCP 执行开关影响。 */
+    registerToolRenderer(definition: PluginToolRendererDefinition): Promise<Disposable>;
+}
+export declare function snapshotToolRendererDefinition(definition: PluginToolRendererDefinition): PluginToolRendererDefinition;

package/types/packages/plugins/src/contract.d.ts

@@ -13,6 +13,7 @@ import type { PluginTTS } from "./tts";
 import type { PluginSidebar } from "./sidebar";
 import type { PluginExcerpts, PluginMaterials } from "./excerpts";
 import type { PluginMCP } from "./mcp";
+import type { PluginChat } from "./chat";
 import type { JsonValue } from "./json";
 export type { JsonValue } from "./json";
 export interface Disposable {
@@ -50,6 +51,7 @@ export interface PluginContext {
     readonly services: PluginServices;
     readonly ai: PluginAI;
     readonly mcp: PluginMCP;
+    readonly chat: PluginChat;
     /** 将订阅等资源交给宿主，在停用或激活失败时逆序回收。 */
     register(resource: Disposable): Disposable;
 }

package/types/packages/plugins/src/index.d.ts

@@ -9,8 +9,11 @@ export type { SourceBlockEditorProps, PluginRuntimeStyleCompiler } from "./sourc
 export * from "./sidebar";
 export type * from "./excerpts";
 export type * from "./services";
+export { usePluginServices } from "./service-access";
 export type { PluginSkill } from "./skills";
 export type { PluginMCP, PluginMCPDefinition, PluginMCPTool, PluginMCPTransport } from "./mcp";
+export type { PluginMCPToolResult } from "./mcp";
+export type { PluginChat, PluginToolRendererDefinition, PluginToolRendererProps, ToolCallExecutionState, } from "./chat";
 export type { PluginPageDefinition, PluginPageHandle, PluginPageParams, PluginPageProps, PluginPages, } from "./pages";
 export declare function definePlugin(definition: Omit<PluginDefinition, "apiVersion" | "create"> & Partial<Pick<PluginDefinition, "create">>): PluginDefinition;
 export type { PluginAI, PluginAIFeature, PluginAIRequest, PluginAIResult, PluginAIEvent, } from "./ai";

package/types/packages/plugins/src/mcp.d.ts

@@ -11,6 +11,13 @@ export type PluginMCPTransport = {
     url: string;
     headers?: Record<string, string>;
 };
+export interface PluginMCPToolResult {
+    content: string;
+    render?: {
+        version: number;
+        data: JsonValue;
+    };
+}
 export interface PluginMCPTool {
     name: string;
     description: string;
@@ -21,11 +28,7 @@ export interface PluginMCPTool {
     };
     execute(args: Record<string, JsonValue>, context: {
         signal: AbortSignal;
-    }): Promise<{
-        content: string;
-    }> | {
-        content: string;
-    };
+    }): Promise<PluginMCPToolResult> | PluginMCPToolResult;
 }
 export type PluginMCPDefinition = {
     id: string;
@@ -42,4 +45,5 @@ export interface PluginMCP {
     /** 同一插件可注册多个 MCP；停用时由宿主自动回收。 */
     register(definition: PluginMCPDefinition): Disposable;
 }
+export declare function snapshotMCPToolResult(result: PluginMCPToolResult): PluginMCPToolResult;
 export declare function snapshotMCPDefinition(definition: PluginMCPDefinition): PluginMCPDefinition;

package/types/packages/plugins/src/service-access.d.ts

@@ -0,0 +1,7 @@
+import type { PluginServices } from "./services";
+declare let useServices: () => PluginServices | undefined;
+/** 宿主绑定 React 上下文，作者只消费 usePluginServices。 */
+export declare function configurePluginServiceAccess(read: typeof useServices): void;
+/** 当前插件渲染作用域的服务；博客和无界面宿主不提供服务。 */
+export declare function usePluginServices(): PluginServices | undefined;
+export {};

package/types/packages/shared/src/chat-core/aiRunProtocol.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 浏览器扩展 ↔ 桌面的 AI 运行协议 v2（M5）。取代 v1 的 `ai.chat` 请求 + `ai.stream.*` 快照通知。
+ *
+ * 一次运行 = 一个 runId：
+ * - `ai.run.start`（请求）立即返回 `{ runId }`，不等回答结束；
+ * - 过程经 `ai.run.event` 通知推送（按 runId 路由，`seq` 单调递增，接收端据此丢弃乱序/重复）；
+ * - 最后一条一定是 `settled`（成功、失败、被停止都会有），接收端据此收尾；
+ * - `ai.run.abort` 停止；`ai.run.state` 查某个扩展对话此刻是否在跑（侧栏重开后接上）。
+ *
+ * 事件是快照语义，与 v1 相同的块组装（applyChatStreamEvent）可以直接消费 text/reasoning/tool-calls；
+ * v1 丢掉的 usage、重试、错误、交互（审批/提问）在 v2 里都有。
+ */
+import type { ChatSessionMessage, ModelUsage, ResponseMessage, ToolCallExecutionState, ToolCallPayload } from "./messages";
+/** 审批：模型要执行需要确认的工具 */
+export interface AiRunApprovalRequest {
+    requestId: string;
+    toolCallId: string;
+    toolName: string;
+    risk: string;
+    input: string;
+    requestedAt: number;
+}
+/** 提问：宿主原生 ask-question，payload 为已归一化的问题结构 */
+export interface AiRunQuestionRequest {
+    requestId: string;
+    toolCallId: string;
+    payload: unknown;
+    askedAt: number;
+}
+export type AiRunEvent = {
+    type: "text";
+    turnId: string;
+    fullText: string;
+} | {
+    type: "reasoning";
+    turnId: string;
+    fullText: string;
+} | {
+    type: "tool-calls";
+    turnId: string;
+    executions: ToolCallExecutionState[];
+    toolCalls?: ToolCallPayload[];
+} | {
+    type: "turn-finish";
+    turnId: string;
+} | {
+    type: "usage";
+    turnId: string;
+    usage: ModelUsage;
+}
+/** 自动重试中（null = 重试等待结束） */
+ | {
+    type: "retry";
+    status: {
+        attempt: number;
+        maxAttempts: number;
+        delayMs: number;
+    } | null;
+}
+/** 模型或运行报错（不一定终止：重试可能接着成功；终止与否看 settled） */
+ | {
+    type: "error";
+    message: string;
+}
+/** 待用户处理的交互快照（审批 + 提问），为空表示没有在等 */
+ | {
+    type: "interactions";
+    approvals: AiRunApprovalRequest[];
+    questions: AiRunQuestionRequest[];
+}
+/** 运行结束（唯一终态）：ok=false 时带 error；aborted 表示用户停止 */
+ | {
+    type: "settled";
+    ok: boolean;
+    aborted: boolean;
+    error?: string;
+    lastText: string;
+};
+export interface AiRunEventNotification {
+    runId: string;
+    seq: number;
+    event: AiRunEvent;
+}
+export interface AiRunStartParams {
+    /** 客户端生成（接收端先订阅再发起，避免漏掉最早的事件） */
+    runId: string;
+    /**
+     * 持久对话（侧栏）：只带本轮的用户消息，历史由桌面从页面会话文件恢复。
+     * 一次性调用（概览页、行内问答）：带全量历史，最后一条为 user。
+     */
+    messages: Array<{
+        role: string;
+        content: unknown;
+        [key: string]: unknown;
+    }>;
+    session?: {
+        id: string;
+        pageUrl: string;
+    };
+    systemPrompt?: string;
+    pageContext?: {
+        url: string;
+        title: string;
+        content?: string;
+    };
+    /** false = 纯文本单发（行内问答） */
+    enableTools?: boolean;
+    /** 扩展本地执行的页面工具（OpenAI function 形状） */
+    browserTools?: Array<{
+        type: "function";
+        function: {
+            name: string;
+            description: string;
+            parameters: Record<string, unknown>;
+        };
+    }>;
+    thinkingLevel?: string;
+    feature?: string;
+}
+/** 一轮运行到此刻的快照（侧栏重开后接回）：之后的事件按 `lastSeq` 续接 */
+export interface AiRunSnapshot {
+    runId: string;
+    lastSeq: number;
+    /**
+     * 这一轮开始前的对话投影。接回时界面 = baseMessages + request + response；不用会话文件的当前投影，
+     * 因为本轮已完成的回答片段可能已落盘（与 response 重复），也可能还没落盘（新对话首轮 pi 不写文件）。
+     */
+    baseMessages: ChatSessionMessage[];
+    /** 这一轮的用户消息（与 start 时的 messages 末条同一形状） */
+    request: {
+        role: string;
+        content: unknown;
+        [key: string]: unknown;
+    };
+    /** 本轮回答到此刻的归约结果（与接收端同一套 applyChatStreamEvent 组装） */
+    response: ResponseMessage;
+    interactions: {
+        approvals: AiRunApprovalRequest[];
+        questions: AiRunQuestionRequest[];
+    };
+    retry: {
+        attempt: number;
+        maxAttempts: number;
+        delayMs: number;
+    } | null;
+}
+export interface AiRunStateResult {
+    running: boolean;
+    runId?: string;
+    snapshot?: AiRunSnapshot;
+}
+export declare const AI_RUN_METHODS: {
+    readonly start: "ai.run.start";
+    readonly abort: "ai.run.abort";
+    readonly state: "ai.run.state";
+    readonly approve: "ai.run.approve";
+    readonly answer: "ai.run.answer";
+    readonly event: "ai.run.event";
+};
+/** 按 runId 收事件：丢弃乱序与重复（seq 不大于已收到的）；接回在跑的运行时从快照的 lastSeq 续接 */
+export declare const createRunEventFilter: (runId: string, afterSeq?: number) => (notification: AiRunEventNotification) => AiRunEvent | null;

package/types/packages/shared/src/chat-core/assistantBlocks.d.ts

@@ -0,0 +1,12 @@
+import type { RequestMessage, ProviderMetadata, ResponseContentBlock, ResponseMessage, ToolCallExecutionState, ToolCallPayload } from "./messages";
+export declare const syncAssistantDerivedFields: (message: ResponseMessage) => ResponseMessage;
+export declare const ensureAssistantMessage: (message: ResponseMessage) => ResponseMessage;
+export declare const getAssistantToolExecutions: (message: ResponseMessage) => ToolCallExecutionState[];
+export declare const getAssistantContentBlocks: (message: ResponseMessage) => ResponseContentBlock[];
+export declare const createAssistantMessage: (initial?: Partial<ResponseMessage>) => ResponseMessage;
+export declare const applyAssistantTextSnapshot: (message: ResponseMessage, turnId: string, fullText: string) => void;
+export declare const applyAssistantReasoningSnapshot: (message: ResponseMessage, turnId: string, fullReasoning: string, now?: number) => void;
+export declare const applyAssistantToolCallsSnapshot: (message: ResponseMessage, turnId: string, executions: ToolCallExecutionState[], toolCalls?: ToolCallPayload[]) => void;
+export declare const finalizeAssistantTurn: (message: ResponseMessage, turnId: string) => void;
+export declare const applyAssistantProviderMetadataSnapshot: (message: ResponseMessage, turnId: string, providerMetadata?: ProviderMetadata) => void;
+export declare const buildAssistantHistoryMessages: (message: ResponseMessage) => RequestMessage[];

package/types/packages/shared/src/chat-core/index.d.ts

@@ -0,0 +1,6 @@
+/** 不依赖 React 或 DOM 的公共聊天入口，可供主进程和浏览器共同使用。 */
+export * from "./messages";
+export * from "./messageSchema";
+export * from "./assistantBlocks";
+export * from "./streamEvents";
+export * from "./aiRunProtocol";

package/types/packages/shared/src/chat-core/messageSchema.d.ts

@@ -0,0 +1 @@
+export declare const createChatMessageClientId: () => string;

package/types/packages/shared/src/chat-core/messages.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 统一消息模型：桌面端与浏览器插件共用的会话记录、请求/响应消息与流式块类型。
+ * 桌面 src/types/llm.ts、src/types/chat-message.ts、src/types/tool.ts 对本文件为 re-export 关系，
+ * 两端禁止再各自定义同名类型。
+ */
+import type { MentionRef } from "../components/ChatInputArea/types";
+export declare enum Role {
+    User = "user",
+    Assistant = "assistant",
+    System = "system",
+    Tool = "tool"
+}
+export interface TextContent {
+    type: "text";
+    text: string;
+    mentions?: MentionRef[];
+    /** 本条消息用 `$` 点名的 Skill（folderName），发送时注入全文（D-060） */
+    skills?: string[];
+}
+export interface ImageContent {
+    type: "image";
+    image: string;
+    path?: string;
+    resourceId?: number;
+}
+export interface FileContent {
+    type: "file";
+    file: string;
+    resourceId?: number;
+    fileName?: string;
+}
+export type MessageContent = TextContent | ImageContent | FileContent;
+export type ProviderMetadata = Record<string, unknown>;
+export interface ToolCallPayload {
+    id: string;
+    type?: string;
+    function: {
+        name: string;
+        arguments?: string;
+    };
+}
+export type ToolCallStatus = "pending" | "executing" | "success" | "failed" | "retrying" | "cancelled" | "awaiting-approval";
+/** 工具调用执行状态详情 */
+export interface ToolCallExecutionState {
+    toolCallId: string;
+    toolName: string;
+    status: ToolCallStatus;
+    input: string;
+    output?: string;
+    error?: string;
+    metadata?: Record<string, unknown>;
+    /** 错误类型：parameter 为参数错误（已反馈模型纠正），execution 为执行失败（已自动重试） */
+    errorType?: "parameter" | "execution";
+    /** 首次进入 pending 的时间戳 */
+    timestamp: number;
+    duration?: number;
+    /** 自动重试次数（仅用于执行失败的自动重试场景） */
+    retryCount?: number;
+}
+export type AssistantBlockState = "streaming" | "final";
+export interface AssistantTextBlock {
+    id: string;
+    turnId: string;
+    type: "text";
+    state: AssistantBlockState;
+    content: string;
+}
+export interface AssistantReasoningBlock {
+    id: string;
+    turnId: string;
+    type: "reasoning";
+    state: AssistantBlockState;
+    content: string;
+    startTime?: number;
+    endTime?: number;
+    duration?: number;
+}
+export interface AssistantToolCallBlock {
+    id: string;
+    turnId: string;
+    type: "tool_call";
+    state: AssistantBlockState;
+    toolCall: ToolCallPayload;
+    execution?: ToolCallExecutionState;
+}
+/** 流式助手块：文本/思考/工具调用按 turn 顺序交替出现 */
+export type AssistantBlock = AssistantTextBlock | AssistantReasoningBlock | AssistantToolCallBlock;
+/** 内容块：ChatMessageType.contentBlocks 的展示层结构 */
+export type ResponseContentBlock = {
+    type: "text";
+    content: string;
+} | {
+    type: "reasoning";
+    content: string;
+    startTime?: number;
+    endTime?: number;
+    duration?: number;
+} | {
+    type: "tool_calls";
+    executions: ToolCallExecutionState[];
+};
+/** ContentBlock 为 ResponseContentBlock 的兼容别名（历史导出名） */
+export type ContentBlock = ResponseContentBlock;
+export interface ModelUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    providerId?: string;
+    modelId?: string;
+    modelName?: string;
+}
+export interface MessageVersions {
+    ids: string[];
+    index: number;
+}
+export interface RequestMessage {
+    clientId?: string;
+    /**
+     * 对应的 pi 会话 entry id（M4：从 JSONL 投影出来的消息才有）。改历史操作（删除/编辑重发/
+     * 重新生成）按它定位，不能靠 clientId——迁移数据的 clientId 是旧值。
+     */
+    piEntryIds?: string[];
+    /**
+     * 会话树上同一位置的全部版本（M4-d：编辑重发/重新生成/从这里建分支产生的兄弟）。
+     * ids 为各版本用户消息的 entry id（写入顺序），index 是本条是第几个；只有一个版本时不带。
+     */
+    piVersions?: MessageVersions;
+    role: Role;
+    content: MessageContent[] | string;
+    reasoning_content?: string;
+    provider_metadata?: ProviderMetadata;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCallPayload[];
+}
+export interface ResponseMessage {
+    clientId?: string;
+    /** 一条回答的全部 pi entry id（assistant + toolResult）：删除回答要全部省略，否则只删一半 */
+    piEntryIds?: string[];
+    role: Role;
+    content: string;
+    reasoning_content?: string;
+    provider_metadata_by_turn?: Record<string, ProviderMetadata>;
+    tool_calls?: ToolCallPayload[];
+    assistant_blocks?: AssistantBlock[];
+    usage?: ModelUsage;
+}
+export type ChatSessionMessage = RequestMessage | ResponseMessage;
+/**
+ * 一个已打开的对话（M4：会话目录行 + pi JSONL 投影出的消息）。注意与 ChatComponents 的
+ * ChatMessage（单条消息）区分，桌面历史代码以 `ChatMessage` 名字消费本类型。
+ *
+ * id 即 pi 会话 id（字符串）：新对话在渲染端生成 id，目录表里查不到就是草稿，
+ * 首轮发送后才登记目录行，id 从头到尾不变。
+ */
+export interface ChatSessionRecord {
+    /** 桌面投影所属库，不属于消息内容。 */
+    databaseName?: string;
+    id: string;
+    createTime: number;
+    updateTime: number;
+    messages: ChatSessionMessage[];
+    title: string;
+    titleDirty?: boolean;
+    groupId?: number | null;
+    archived?: boolean;
+    orderNum?: number | null;
+    /** 会话来源：desktop 为桌面端创建，browser 为浏览器插件创建 */
+    source?: "desktop" | "browser";
+    /** 相对会话目录的 JSONL 文件名；草稿（尚未登记）为空 */
+    sessionFile?: string;
+    /** 聊天场景（main-chat / pdf-chat / …）与所属对象 */
+    scope?: string;
+    domainRef?: string | null;
+}
+export interface ChatGroup {
+    id: number;
+    name: string;
+    parentId: number | null;
+    orderIndex: number;
+    createTime: number;
+    updateTime: number;
+}
+export interface CreateChatGroup {
+    name: string;
+    parentId?: number | null;
+    orderIndex?: number;
+}
+export interface UpdateChatGroup {
+    id: number;
+    name?: string;
+    parentId?: number | null;
+    orderIndex?: number;
+}

package/types/packages/shared/src/chat-core/streamEvents.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 统一流事件与归约器：把「快照语义」的流事件应用到 ResponseMessage，
+ * 内部复用 assistantBlocks 的块组装逻辑。
+ * 浏览器扩展消费 AI 运行协议 v2 的 `ai.run.event`（aiRunProtocol.ts），桌面主进程的扩展桥用它维护
+ * 接回快照；两端禁止再各自手写流式拼块。
+ */
+import type { ModelUsage, ProviderMetadata, ResponseMessage, ToolCallExecutionState, ToolCallPayload } from "./messages";
+/** turn 内快照事件：fullText / executions 为当前全量，幂等可重放 */
+export type ChatStreamTurnEvent = {
+    type: "text";
+    turnId: string;
+    fullText: string;
+} | {
+    type: "reasoning";
+    turnId: string;
+    fullText: string;
+} | {
+    type: "tool-calls";
+    turnId: string;
+    /** 执行状态快照；流式计划阶段可只带 toolCalls */
+    executions?: ToolCallExecutionState[];
+    toolCalls?: ToolCallPayload[];
+} | {
+    type: "turn-finish";
+    turnId: string;
+} | {
+    type: "provider-metadata";
+    turnId: string;
+    metadata: ProviderMetadata;
+};
+/** run 级事件 */
+export type ChatStreamRunEvent = {
+    type: "usage";
+    turnId?: string;
+    usage: ModelUsage;
+} | {
+    type: "run-finish";
+    content?: string;
+    reasoning?: string;
+    error?: string;
+};
+export type ChatStreamEvent = ChatStreamTurnEvent | ChatStreamRunEvent;
+/**
+ * 把流事件应用到助手消息（原地更新并返回同一引用；调用方负责渲染投影时复制）。
+ * run-finish / usage 不改变块结构，仅原样返回。
+ */
+export declare const applyChatStreamEvent: (message: ResponseMessage, event: ChatStreamEvent) => ResponseMessage;

package/types/packages/shared/src/components/ChatInputArea/types.d.ts

@@ -0,0 +1,126 @@
+import type { ReactNode } from "react";
+/**
+ * 模型下拉菜单项（antd Dropdown 时代的结构子集；ChatInputArea 换 @tau/ui Menu 后收敛为原语协议）。
+ * ext / desktop 侧构造的字段不超出此面，antd message 等 UI 库类型不得回流 shared 类型层。
+ */
+export interface ChatDropdownItem {
+    key: string;
+    label: ReactNode;
+    /** 分组小标题（非交互项，如模型菜单的 provider 名） */
+    group?: boolean;
+    danger?: boolean;
+    disabled?: boolean;
+    icon?: ReactNode;
+}
+/**
+ * 思考档位——全仓唯一定义，取值与运行时（pi ThinkingLevel）逐项对齐。
+ * 桌面端 `PiThinkingLevel` 即本类型；此前两侧各有一套（旧枚举用 "none" 且没有 "minimal"），
+ * 导致 minimal 在界面上不可达、每处转换都要记得 none→off。
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type MentionEntityType = "card" | "article" | "project-item";
+/** 聊天 mention 引用 */
+export interface MentionRef {
+    entityType: MentionEntityType;
+    entityId: number;
+    contentId: number;
+    title: string;
+    previewText: string;
+}
+/** 消息内容类型；resourceId 仅兼容历史数据，新附件只写入路径。 */
+export type MessageContentItem = {
+    type: "text";
+    text: string;
+    mentions?: MentionRef[];
+    skills?: string[];
+} | {
+    type: "image";
+    image: string;
+    path?: string;
+    resourceId?: number;
+} | {
+    type: "file";
+    file: string;
+    resourceId?: number;
+    fileName?: string;
+};
+/** ChatInputArea 需要的服务函数 */
+export interface ChatInputAreaServices {
+    /** 上传文件，返回文件路径 */
+    uploadFile: (file: File) => Promise<string | null>;
+    /** 将本地文件路径转换为可访问的 URL */
+    convertFileSrc: (path: string) => Promise<string>;
+    /** 获取用户主目录 */
+    getHomeDir: () => Promise<string>;
+    /** 搜索可提及的内部内容 */
+    searchMentionRefs?: (query: string) => Promise<MentionRef[]>;
+}
+/** ChatInputArea 的 ref handle */
+export interface ChatInputAreaHandle {
+    getValue: () => MessageContentItem[];
+    clear: () => void;
+    setValue: (content: string) => void;
+    appendMention?: (mention: MentionRef) => void;
+    focusEnd: () => void;
+}
+export interface ChatContextUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/** ChatInputArea 的 props */
+export interface ChatInputAreaProps {
+    /** 服务函数 */
+    services: ChatInputAreaServices;
+    /** 自定义类名 */
+    className?: string;
+    /** 是否可编辑 */
+    contentEditable?: boolean;
+    /** 按下回车时的回调 */
+    onPressEnter?: () => void;
+    /** 停止生成时的回调 */
+    onStop?: () => void;
+    /** 占位符 */
+    placeholder?: string;
+    /** 是否正在发送 */
+    sendLoading?: boolean;
+    /** 生成期间是否仍允许编辑并将消息加入发送队列 */
+    allowSendWhileLoading?: boolean;
+    /** 当前等待发送的消息数量 */
+    queuedMessageCount?: number;
+    /** 是否正在创建新消息 */
+    createMessageLoading?: boolean;
+    /** 创建新消息的回调 */
+    onCreateNewMessage?: () => void;
+    /** 模型选择菜单项 */
+    modelSelectItems?: ChatDropdownItem[];
+    /** 当前选中模型的菜单项 key，用于菜单勾选 */
+    currentModelKey?: string;
+    /** 模型选择回调 */
+    onModelSelect?: ({ key }: {
+        key: string;
+    }) => void;
+    /** 当前模型名称 */
+    currentModelName?: string;
+    /** 当前模型上下文窗口，单位为 k tokens */
+    contextWindowK?: number;
+    /** 当前聊天最近一次模型请求的 token 用量 */
+    contextUsage?: ChatContextUsage | null;
+    /** 是否支持图片上传 */
+    isSupportImage?: boolean;
+    /** 是否支持文件上传 */
+    isSupportFile?: boolean;
+    /** 思考档位 */
+    thinkingLevel?: ThinkingLevel;
+    /** 当前模型真实支持的档位（由模型能力决定，不是固定几档） */
+    thinkingLevelOptions?: readonly ThinkingLevel[];
+    /** 档位变化回调 */
+    onThinkingLevelChange?: (level: ThinkingLevel) => void;
+    /** 档位选择是否禁用 */
+    thinkingLevelDisabled?: boolean;
+    /** MCP 管理按钮点击回调（可选，不提供则不显示按钮） */
+    onMcpManagerClick?: () => void;
+    /** 额外的工具栏按钮（渲染在 ＋ 右侧） */
+    extraToolbarButtons?: ReactNode;
+}