@leeoohoo/ui-apps-devkit 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeoohoo/ui-apps-devkit",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "ChatOS UI Apps DevKit (CLI + templates + sandbox) for building installable ChatOS UI Apps plugins.",
   "license": "MIT",
   "type": "module",

package/src/sandbox/server.js

@@ -65,11 +65,58 @@ function resolveSandboxConfigPath({ primaryRoot, legacyRoot }) {
 }
 
 const DEFAULT_LLM_BASE_URL = 'https://api.openai.com/v1';
+const UI_PROMPTS_FILENAME = 'ui-prompts.jsonl';
 
 function normalizeText(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
 
+function ensureUiPromptsFile(filePath) {
+  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
+  if (!normalized) return '';
+  try {
+    ensureDir(path.dirname(normalized));
+    if (!fs.existsSync(normalized)) {
+      fs.writeFileSync(normalized, '', 'utf8');
+    }
+  } catch {
+    // ignore
+  }
+  return normalized;
+}
+
+function appendUiPromptsEntry(filePath, entry) {
+  const target = ensureUiPromptsFile(filePath);
+  if (!target) return;
+  try {
+    const payload = entry && typeof entry === 'object' ? entry : { value: entry };
+    fs.appendFileSync(target, `${JSON.stringify(payload)}\n`, 'utf8');
+  } catch {
+    // ignore
+  }
+}
+
+function readUiPromptsEntries(filePath) {
+  const target = ensureUiPromptsFile(filePath);
+  if (!target) return [];
+  try {
+    const raw = fs.readFileSync(target, 'utf8');
+    if (!raw) return [];
+    const lines = raw.split(/\r?\n/).filter((line) => line.trim());
+    const entries = [];
+    for (const line of lines) {
+      try {
+        entries.push(JSON.parse(line));
+      } catch {
+        // ignore parse errors
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -925,7 +972,10 @@ function htmlPage() {
               <input id="mcpDisableTools" type="checkbox" style="width:auto;" />
               Disable tools
             </label>
-            <button id="btnMcpSend" class="btn" type="button">Send</button>
+            <div class="row">
+              <button id="btnMcpAsync" class="btn" type="button">AsyncTask Test</button>
+              <button id="btnMcpSend" class="btn" type="button">Send</button>
+            </div>
           </div>
           <div id="mcpStatus" class="muted"></div>
         </div>
@@ -1003,6 +1053,7 @@ const mcpPanel = $('#mcpPanel');
 const btnMcpClose = $('#btnMcpClose');
 const btnMcpClear = $('#btnMcpClear');
 const btnMcpSend = $('#btnMcpSend');
+const btnMcpAsync = $('#btnMcpAsync');
 const mcpPaths = $('#mcpPaths');
 const mcpWorkdir = $('#mcpWorkdir');
 const mcpModelId = $('#mcpModelId');
@@ -1013,7 +1064,46 @@ const mcpStatus = $('#mcpStatus');
 const mcpOutput = $('#mcpOutput');
 const mcpConfigHint = $('#mcpConfigHint');
 
-const setPanelOpen = (open) => { panel.style.display = open ? 'flex' : 'none'; };
+const mcpStreamState = {
+  active: false,
+  seen: false,
+  runId: '',
+};
+
+const resetMcpStreamState = () => {
+  mcpStreamState.active = false;
+  mcpStreamState.seen = false;
+  mcpStreamState.runId = '';
+};
+
+const markMcpStreamStatus = (payload) => {
+  const method = payload && typeof payload.method === 'string' ? payload.method : '';
+  if (!method.startsWith('codex_app.window_run.')) return;
+  const params = payload && typeof payload.params === 'object' ? payload.params : null;
+  const runId = params && typeof params.runId === 'string' ? params.runId : '';
+  if (runId && (!mcpStreamState.runId || mcpStreamState.runId === runId)) {
+    mcpStreamState.runId = runId;
+  }
+  mcpStreamState.seen = true;
+  const status = params && typeof params.status === 'string' ? params.status.toLowerCase() : '';
+  const done =
+    method === 'codex_app.window_run.done' ||
+    method === 'codex_app.window_run.completed' ||
+    params?.done === true ||
+    ['completed', 'failed', 'aborted', 'cancelled'].includes(status);
+  if (done) {
+    mcpStreamState.active = false;
+    setMcpStatus('Done');
+  } else {
+    mcpStreamState.active = true;
+    setMcpStatus('Streaming...');
+  }
+};
+
+const setPanelOpen = (open) => {
+  panel.style.display = open ? 'flex' : 'none';
+  if (open) refreshUiPromptsFromFile();
+};
 fab.addEventListener('click', () => setPanelOpen(panel.style.display !== 'flex'));
 panelClose.addEventListener('click', () => setPanelOpen(false));
 window.addEventListener('chatos:uiPrompts:open', () => setPanelOpen(true));
@@ -1221,6 +1311,108 @@ const setMcpPanelOpen = (open) => {
   }
 };
 
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const normalizeRequestId = (value) => (typeof value === 'string' ? value.trim() : '');
+
+const buildAsyncRequestIds = (taskId) => {
+  const id = normalizeRequestId(taskId);
+  if (!id) return [];
+  return [id, `mcp-task:${id}`];
+};
+
+const extractAsyncResult = (list, requestIds) => {
+  const ids = new Set((Array.isArray(requestIds) ? requestIds : []).filter(Boolean));
+  if (ids.size === 0) return null;
+  const entriesList = Array.isArray(list) ? list : [];
+  for (let i = entriesList.length - 1; i >= 0; i -= 1) {
+    const entry = entriesList[i];
+    if (!entry || typeof entry !== 'object') continue;
+    if (entry.type !== 'ui_prompt') continue;
+    if (entry.action !== 'request') continue;
+    const requestId = normalizeRequestId(entry.requestId);
+    if (!requestId || !ids.has(requestId)) continue;
+    const prompt = entry.prompt && typeof entry.prompt === 'object' ? entry.prompt : null;
+    if (!prompt || typeof prompt.kind !== 'string' || prompt.kind.trim() !== 'result') continue;
+    if (typeof prompt.markdown === 'string') return prompt.markdown;
+    if (typeof prompt.result === 'string') return prompt.result;
+    if (typeof prompt.content === 'string') return prompt.content;
+    return '';
+  }
+  return null;
+};
+
+const pollAsyncResult = async ({ taskId, timeoutMs = 6000, intervalMs = 500 } = {}) => {
+  const requestIds = buildAsyncRequestIds(taskId);
+  const deadline = Date.now() + Math.max(500, timeoutMs);
+  while (Date.now() < deadline) {
+    const fileEntries = await readUiPromptsFromFile();
+    const text = extractAsyncResult(fileEntries, requestIds);
+    if (text !== null) return { found: true, text };
+    await sleep(Math.max(200, intervalMs));
+  }
+  return { found: false, text: '' };
+};
+
+const buildAsyncTaskCallMeta = (taskId) => ({
+  asyncTask: {
+    tools: ['codex_app_window_run'],
+    taskIdKey: 'taskId',
+    resultSource: 'ui_prompts',
+    uiPromptFile: 'ui-prompts.jsonl',
+  },
+  taskId,
+});
+
+const runMcpAsyncTest = async () => {
+  const sendBtn = btnMcpAsync;
+  try {
+    const message = mcpMessage ? String(mcpMessage.value || '').trim() : '';
+    if (!message) {
+      setMcpStatus('Message is required.', true);
+      return;
+    }
+    resetMcpStreamState();
+    if (sendBtn) sendBtn.disabled = true;
+
+    const taskId = 'task_' + uuid();
+    const callMeta = buildAsyncTaskCallMeta(taskId);
+    const ack = { status: 'accepted', taskId };
+    const resultText = `AsyncTask result for ${taskId}`;
+
+    appendMcpOutput('asyncTask.request', { message, callMeta });
+    appendMcpOutput('asyncTask.ack', ack);
+    setMcpStatus(`ACK: ${taskId} (waiting for uiPrompts result)...`);
+
+    const pollPromise = pollAsyncResult({ taskId, timeoutMs: 8000, intervalMs: 400 });
+
+    setTimeout(async () => {
+      const prompt = { kind: 'result', markdown: resultText, source: 'sandbox-async-test' };
+      try {
+        await host.uiPrompts.request({ requestId: taskId, prompt });
+        appendMcpOutput('asyncTask.result', { requestId: taskId, prompt });
+        setMcpStatus(`Result stored in uiPrompts (taskId=${taskId})`);
+      } catch (err) {
+        appendMcpOutput('asyncTask.error', err?.message || String(err));
+        setMcpStatus(err?.message || String(err), true);
+      }
+    }, 800);
+
+    const pollResult = await pollPromise;
+    if (pollResult.found) {
+      appendMcpOutput('asyncTask.polled', pollResult.text);
+      setMcpStatus(`Polled result (taskId=${taskId})`);
+    } else {
+      appendMcpOutput('asyncTask.timeout', { taskId });
+      setMcpStatus(`Polling timeout (taskId=${taskId})`, true);
+    }
+  } catch (err) {
+    setMcpStatus(err?.message || String(err), true);
+  } finally {
+    if (sendBtn) sendBtn.disabled = false;
+  }
+};
+
 const runMcpTest = async () => {
   const sendBtn = btnMcpSend;
   try {
@@ -1229,6 +1421,7 @@ const runMcpTest = async () => {
       setMcpStatus('Message is required.', true);
       return;
     }
+    resetMcpStreamState();
     if (sendBtn) sendBtn.disabled = true;
     const payload = {
       messages: [{ role: 'user', text: message }],
@@ -1255,7 +1448,11 @@ const runMcpTest = async () => {
     if (Array.isArray(j?.toolTrace) && j.toolTrace.length > 0) {
       appendMcpOutput('toolTrace', j.toolTrace);
     }
-    setMcpStatus('Done');
+    if (mcpStreamState.seen || mcpStreamState.active) {
+      setMcpStatus('Waiting for MCP stream...');
+    } else {
+      setMcpStatus('Done');
+    }
   } catch (err) {
     setMcpStatus(err?.message || String(err), true);
   } finally {
@@ -1378,6 +1575,10 @@ if (btnMcpClear)
     if (mcpOutput) mcpOutput.textContent = '';
     setMcpStatus('');
   });
+if (btnMcpAsync)
+  btnMcpAsync.addEventListener('click', () => {
+    runMcpAsyncTest();
+  });
 if (btnMcpSend)
   btnMcpSend.addEventListener('click', () => {
     runMcpTest();
@@ -1391,18 +1592,31 @@ updateContextStatus();
 
 const entries = [];
 const listeners = new Set();
-const emitUpdate = () => {
-  const payload = { path: '(sandbox)', entries: [...entries] };
-  for (const fn of listeners) { try { fn(payload); } catch {} }
-  renderPrompts();
+const notifyUiPrompts = (list) => {
+  const payload = {
+    path: sandboxPaths.uiPromptsFile || '(sandbox)',
+    entries: Array.isArray(list) ? [...list] : [],
+  };
+  for (const fn of listeners) {
+    try {
+      fn(payload);
+    } catch {
+      // ignore
+    }
+  }
+};
+
+const emitUpdate = async () => {
+  await refreshUiPromptsFromFile();
 };
 
 const uuid = () => (globalThis.crypto?.randomUUID ? crypto.randomUUID() : String(Date.now()) + '-' + Math.random().toString(16).slice(2));
 
-function renderPrompts() {
+function renderPrompts(sourceEntries = entries) {
   panelBody.textContent = '';
   const pending = new Map();
-  for (const e of entries) {
+  const list = Array.isArray(sourceEntries) ? sourceEntries : [];
+  for (const e of list) {
     if (e?.type !== 'ui_prompt') continue;
     const id = String(e?.requestId || '');
     if (!id) continue;
@@ -1453,8 +1667,15 @@ function renderPrompts() {
     };
 
     const submit = async (response) => {
-      entries.push({ ts: new Date().toISOString(), type: 'ui_prompt', action: 'response', requestId, response });
-      emitUpdate();
+      const entry = {
+        ts: new Date().toISOString(),
+        type: 'ui_prompt',
+        action: 'response',
+        requestId,
+        response,
+      };
+      await appendUiPromptsToFile(entry);
+      await emitUpdate();
     };
 
     if (kind === 'result') {
@@ -1591,6 +1812,46 @@ const callSandboxChat = async (payload, signal) => {
   return j;
 };
 
+const appendUiPromptsToFile = async (entry) => {
+  try {
+    const r = await fetch('/api/ui-prompts/append', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ entry }),
+    });
+    const j = await r.json();
+    return Boolean(j?.ok);
+  } catch {
+    return false;
+  }
+};
+
+const readUiPromptsFromFile = async () => {
+  try {
+    const r = await fetch('/api/ui-prompts/read');
+    const j = await r.json();
+    if (j?.ok && Array.isArray(j.entries)) return j.entries;
+  } catch {
+    // ignore
+  }
+  return [];
+};
+
+const replaceEntries = (list) => {
+  entries.length = 0;
+  if (Array.isArray(list) && list.length > 0) {
+    entries.push(...list);
+  }
+};
+
+const refreshUiPromptsFromFile = async () => {
+  const fileEntries = await readUiPromptsFromFile();
+  replaceEntries(fileEntries);
+  notifyUiPrompts(entries);
+  renderPrompts(entries);
+  return entries;
+};
+
 const getTheme = () => currentTheme || resolveTheme();
 
 const host = {
@@ -1634,22 +1895,41 @@ const host = {
     },
   },
   uiPrompts: {
-    read: async () => ({ path: '(sandbox)', entries: [...entries] }),
+    read: async () => {
+      const fileEntries = await readUiPromptsFromFile();
+      return { path: sandboxPaths.uiPromptsFile || '(sandbox)', entries: fileEntries };
+    },
     onUpdate: (listener) => { listeners.add(listener); return () => listeners.delete(listener); },
     request: async (payload) => {
       const requestId = payload?.requestId ? String(payload.requestId) : uuid();
       const prompt = payload?.prompt && typeof payload.prompt === 'object' ? { ...payload.prompt } : null;
       if (prompt && !prompt.source) prompt.source = __SANDBOX__.pluginId + ':' + __SANDBOX__.appId;
-      entries.push({ ts: new Date().toISOString(), type: 'ui_prompt', action: 'request', requestId, runId: payload?.runId, prompt });
-      emitUpdate();
+      const entry = {
+        ts: new Date().toISOString(),
+        type: 'ui_prompt',
+        action: 'request',
+        requestId,
+        runId: payload?.runId,
+        prompt,
+      };
+      await appendUiPromptsToFile(entry);
+      await emitUpdate();
       return { ok: true, requestId };
     },
     respond: async (payload) => {
       const requestId = String(payload?.requestId || '');
       if (!requestId) throw new Error('requestId is required');
       const response = payload?.response && typeof payload.response === 'object' ? payload.response : null;
-      entries.push({ ts: new Date().toISOString(), type: 'ui_prompt', action: 'response', requestId, runId: payload?.runId, response });
-      emitUpdate();
+      const entry = {
+        ts: new Date().toISOString(),
+        type: 'ui_prompt',
+        action: 'response',
+        requestId,
+        runId: payload?.runId,
+        response,
+      };
+      await appendUiPromptsToFile(entry);
+      await emitUpdate();
       return { ok: true };
     },
     open: () => (setPanelOpen(true), { ok: true }),
@@ -1964,6 +2244,7 @@ try {
     if (!payload) return;
     const server = payload?.serverName ? String(payload.serverName) : 'mcp';
     const method = payload?.method ? String(payload.method) : 'notification';
+    markMcpStreamStatus(payload);
     appendMcpOutput(server + ' ' + method, payload?.params?.text || payload);
   });
 } catch {
@@ -2227,6 +2508,8 @@ export async function startSandboxServer({ pluginDir, port = 4399, appId = '' })
   ctxBase.dataDir = path.join(sandboxRoot, 'data', ctxBase.pluginId);
   ensureDir(ctxBase.stateDir);
   ensureDir(ctxBase.dataDir);
+  const uiPromptsPath = path.join(ctxBase.stateDir, UI_PROMPTS_FILENAME);
+  ensureUiPromptsFile(uiPromptsPath);
   sandboxCallMeta = buildSandboxCallMeta({
     rawCallMeta: app?.ai?.mcp?.callMeta,
     context: {
@@ -2321,6 +2604,7 @@ export async function startSandboxServer({ pluginDir, port = 4399, appId = '' })
           dataDir: ctxBase.dataDir || '',
           pluginDir: ctxBase.pluginDir || '',
           stateDir: ctxBase.stateDir || '',
+          uiPromptsFile: uiPromptsPath || '',
           sessionRoot: ctxBase.sessionRoot || '',
           projectRoot: ctxBase.projectRoot || '',
         };
@@ -2346,6 +2630,24 @@ export async function startSandboxServer({ pluginDir, port = 4399, appId = '' })
         return sendJson(res, 200, { ok: true, manifest });
       }
 
+      if (pathname === '/api/ui-prompts/read') {
+        if (req.method !== 'GET') return sendJson(res, 405, { ok: false, message: 'Method not allowed' });
+        const entries = readUiPromptsEntries(uiPromptsPath);
+        return sendJson(res, 200, { ok: true, path: uiPromptsPath || '', entries });
+      }
+
+      if (pathname === '/api/ui-prompts/append') {
+        if (req.method !== 'POST') return sendJson(res, 405, { ok: false, message: 'Method not allowed' });
+        try {
+          const payload = await readJsonBody(req);
+          const entry = payload?.entry && typeof payload.entry === 'object' ? payload.entry : payload;
+          appendUiPromptsEntry(uiPromptsPath, entry);
+          return sendJson(res, 200, { ok: true });
+        } catch (err) {
+          return sendJson(res, 200, { ok: false, message: err?.message || String(err) });
+        }
+      }
+
       if (pathname === '/api/sandbox/llm-config') {
         if (req.method === 'GET') {
           const cfg = getSandboxLlmConfig();

package/templates/basic/docs/CHATOS_UI_APPS_ASYNC_TASK_PROTOCOL.md

@@ -0,0 +1,100 @@
+# ChatOS UI Apps：AsyncTask 轮询协议（MCP 调用）
+
+本协议用于描述 **ACK + 交互待办轮询** 的异步 MCP 调用模式。当 `callMeta.asyncTask` 配置命中某个工具时，ChatOS 不走流式通知，而是：
+
+1. 立即接收 MCP ACK（包含 taskId）
+2. 后台执行任务
+3. 结果写入「交互待办」（`ui-prompts.jsonl`）
+4. ChatOS 轮询匹配结果并返回给工具调用
+
+> 关键点：**没有流式通知**，只能通过轮询 `ui-prompts.jsonl` 获取结果。
+
+## 1) 触发条件（callMeta.asyncTask）
+
+当 MCP server 的 `callMeta` 包含 `asyncTask`，且 `tools` 覆盖当前工具名时，ChatOS 会启用轮询模式。
+
+示例：
+```json
+{
+  "asyncTask": {
+    "tools": ["codex_app_window_run"],
+    "taskIdKey": "taskId",
+    "resultSource": "ui_prompts",
+    "uiPromptFile": "ui-prompts.jsonl",
+    "pollIntervalMs": 1000
+  }
+}
+```
+
+约定字段：
+- `tools`: 触发异步模式的 tool 名列表（小写匹配）
+- `taskIdKey`: taskId 字段名（默认 `taskId`）
+- `resultSource`: 固定 `ui_prompts`
+- `uiPromptFile`: 固定 `ui-prompts.jsonl`
+- `pollIntervalMs`: 轮询间隔（200-5000ms）
+
+## 2) ACK 规范（MCP 返回）
+
+工具调用应立即返回 ACK，并带上 `taskId`：
+
+```json
+{
+  "status": "accepted",
+  "taskId": "task_123"
+}
+```
+
+> ChatOS 不会依赖 ACK 的结构完成轮询，但该 ACK 对其它客户端/调试很重要。
+
+## 3) 结果写入（交互待办）
+
+异步结果必须写入 `ui-prompts.jsonl`，格式必须满足以下条件：
+
+- `type = "ui_prompt"`
+- `action = "request"`
+- `requestId = taskId` 或 `mcp-task:<taskId>`
+- `prompt.kind = "result"`
+
+示例：
+```json
+{
+  "ts": "2025-01-01T00:00:00.000Z",
+  "type": "ui_prompt",
+  "action": "request",
+  "requestId": "task_123",
+  "prompt": {
+    "kind": "result",
+    "markdown": "final output"
+  }
+}
+```
+
+`prompt` 文本字段优先级（ChatOS 解析顺序）：
+1. `prompt.markdown`
+2. `prompt.result`
+3. `prompt.content`
+
+## 4) 轮询规则（ChatOS）
+
+ChatOS 会在 `ui-prompts.jsonl` 中按以下规则匹配结果：
+
+- `type === "ui_prompt"`
+- `action === "request"`
+- `prompt.kind === "result"`
+- `requestId in [taskId, "mcp-task:" + taskId]`
+
+匹配成功即返回结果文本给工具调用。
+
+## 5) 沙箱调试（Devkit）
+
+Devkit 沙箱已提供 `uiPrompts` 内存存储与 UI 面板，可用于调试本协议：
+
+- 通过 **MCP Test 面板的 AsyncTask Test** 按钮生成 taskId + 写入结果，并执行轮询匹配
+- 在 MCP Output 中可看到轮询命中结果，UI Prompts 面板可看到 result 类型条目
+- 沙箱会同时写入 `stateDir/ui-prompts.jsonl`（可在 MCP Test 的 Paths 中查看路径）
+
+## 6) 常见问题
+
+- **轮询超时**：确认 `ui-prompts.jsonl` 中是否有正确格式的 `prompt.kind=result`。
+- **找不到结果**：确认 `requestId` 为 `taskId` 或 `mcp-task:<taskId>`。
+- **结果为空**：确认 `prompt.markdown/result/content` 至少存在一个文本字段。

package/templates/basic/docs/CHATOS_UI_APPS_OVERVIEW.md

@@ -9,6 +9,7 @@
 - [`CHATOS_UI_APPS_STYLE_GUIDE.md`](./CHATOS_UI_APPS_STYLE_GUIDE.md)：主题与样式约定（CSS Tokens / 主题切换）。
 - [`CHATOS_UI_APPS_TROUBLESHOOTING.md`](./CHATOS_UI_APPS_TROUBLESHOOTING.md)：常见问题与排查清单。
 - [`CHATOS_UI_PROMPTS_PROTOCOL.md`](./CHATOS_UI_PROMPTS_PROTOCOL.md)：右下角笑脸「交互待办（UI Prompts）」协议（表单/单选/多选/复杂确认）。
+- [`CHATOS_UI_APPS_ASYNC_TASK_PROTOCOL.md`](./CHATOS_UI_APPS_ASYNC_TASK_PROTOCOL.md)：AsyncTask 轮询协议（ACK + 交互待办）。
 - [`CHATOS_UI_APPS_BACKEND_PROTOCOL.md`](./CHATOS_UI_APPS_BACKEND_PROTOCOL.md)：插件后端（Electron main 进程）协议与 `ctx` 运行时上下文。
 - [`CHATOS_UI_APPS_AI_CONTRIBUTIONS.md`](./CHATOS_UI_APPS_AI_CONTRIBUTIONS.md)：应用如何对 Chat Agent 暴露 MCP/Prompt（含命名规则、合并规则、内置清单机制）。
 

package/templates/notepad/docs/CHATOS_UI_APPS_ASYNC_TASK_PROTOCOL.md

@@ -0,0 +1,100 @@
+# ChatOS UI Apps：AsyncTask 轮询协议（MCP 调用）
+
+本协议用于描述 **ACK + 交互待办轮询** 的异步 MCP 调用模式。当 `callMeta.asyncTask` 配置命中某个工具时，ChatOS 不走流式通知，而是：
+
+1. 立即接收 MCP ACK（包含 taskId）
+2. 后台执行任务
+3. 结果写入「交互待办」（`ui-prompts.jsonl`）
+4. ChatOS 轮询匹配结果并返回给工具调用
+
+> 关键点：**没有流式通知**，只能通过轮询 `ui-prompts.jsonl` 获取结果。
+
+## 1) 触发条件（callMeta.asyncTask）
+
+当 MCP server 的 `callMeta` 包含 `asyncTask`，且 `tools` 覆盖当前工具名时，ChatOS 会启用轮询模式。
+
+示例：
+```json
+{
+  "asyncTask": {
+    "tools": ["codex_app_window_run"],
+    "taskIdKey": "taskId",
+    "resultSource": "ui_prompts",
+    "uiPromptFile": "ui-prompts.jsonl",
+    "pollIntervalMs": 1000
+  }
+}
+```
+
+约定字段：
+- `tools`: 触发异步模式的 tool 名列表（小写匹配）
+- `taskIdKey`: taskId 字段名（默认 `taskId`）
+- `resultSource`: 固定 `ui_prompts`
+- `uiPromptFile`: 固定 `ui-prompts.jsonl`
+- `pollIntervalMs`: 轮询间隔（200-5000ms）
+
+## 2) ACK 规范（MCP 返回）
+
+工具调用应立即返回 ACK，并带上 `taskId`：
+
+```json
+{
+  "status": "accepted",
+  "taskId": "task_123"
+}
+```
+
+> ChatOS 不会依赖 ACK 的结构完成轮询，但该 ACK 对其它客户端/调试很重要。
+
+## 3) 结果写入（交互待办）
+
+异步结果必须写入 `ui-prompts.jsonl`，格式必须满足以下条件：
+
+- `type = "ui_prompt"`
+- `action = "request"`
+- `requestId = taskId` 或 `mcp-task:<taskId>`
+- `prompt.kind = "result"`
+
+示例：
+```json
+{
+  "ts": "2025-01-01T00:00:00.000Z",
+  "type": "ui_prompt",
+  "action": "request",
+  "requestId": "task_123",
+  "prompt": {
+    "kind": "result",
+    "markdown": "final output"
+  }
+}
+```
+
+`prompt` 文本字段优先级（ChatOS 解析顺序）：
+1. `prompt.markdown`
+2. `prompt.result`
+3. `prompt.content`
+
+## 4) 轮询规则（ChatOS）
+
+ChatOS 会在 `ui-prompts.jsonl` 中按以下规则匹配结果：
+
+- `type === "ui_prompt"`
+- `action === "request"`
+- `prompt.kind === "result"`
+- `requestId in [taskId, "mcp-task:" + taskId]`
+
+匹配成功即返回结果文本给工具调用。
+
+## 5) 沙箱调试（Devkit）
+
+Devkit 沙箱已提供 `uiPrompts` 内存存储与 UI 面板，可用于调试本协议：
+
+- 通过 **MCP Test 面板的 AsyncTask Test** 按钮生成 taskId + 写入结果，并执行轮询匹配
+- 在 MCP Output 中可看到轮询命中结果，UI Prompts 面板可看到 result 类型条目
+- 沙箱会同时写入 `stateDir/ui-prompts.jsonl`（可在 MCP Test 的 Paths 中查看路径）
+
+## 6) 常见问题
+
+- **轮询超时**：确认 `ui-prompts.jsonl` 中是否有正确格式的 `prompt.kind=result`。
+- **找不到结果**：确认 `requestId` 为 `taskId` 或 `mcp-task:<taskId>`。
+- **结果为空**：确认 `prompt.markdown/result/content` 至少存在一个文本字段。

package/templates/notepad/docs/CHATOS_UI_APPS_OVERVIEW.md

@@ -9,6 +9,7 @@
 - [`CHATOS_UI_APPS_STYLE_GUIDE.md`](./CHATOS_UI_APPS_STYLE_GUIDE.md)：主题与样式约定（CSS Tokens / 主题切换）。
 - [`CHATOS_UI_APPS_TROUBLESHOOTING.md`](./CHATOS_UI_APPS_TROUBLESHOOTING.md)：常见问题与排查清单。
 - [`CHATOS_UI_PROMPTS_PROTOCOL.md`](./CHATOS_UI_PROMPTS_PROTOCOL.md)：右下角笑脸「交互待办（UI Prompts）」协议（表单/单选/多选/复杂确认）。
+- [`CHATOS_UI_APPS_ASYNC_TASK_PROTOCOL.md`](./CHATOS_UI_APPS_ASYNC_TASK_PROTOCOL.md)：AsyncTask 轮询协议（ACK + 交互待办）。
 - [`CHATOS_UI_APPS_BACKEND_PROTOCOL.md`](./CHATOS_UI_APPS_BACKEND_PROTOCOL.md)：插件后端（Electron main 进程）协议与 `ctx` 运行时上下文。
 - [`CHATOS_UI_APPS_AI_CONTRIBUTIONS.md`](./CHATOS_UI_APPS_AI_CONTRIBUTIONS.md)：应用如何对 Chat Agent 暴露 MCP/Prompt（含命名规则、合并规则、内置清单机制）。