Agent Protocol v1

    状态：已实现（应用内进程契约）
    版本：1.0.0
    源码：py_tauri_works/src/services/agent/protocol/agentProtocol.ts

    本协议描述 开发助手 AI 与应用能力之间的版本化对接面。当前为进程内 API；语义对齐 OpenAI tools / MCP tools，便于后续挂 SSE 或 WebSocket 而不改 Action 名称与结果形态。

    1. 能力总览

    能力说明
    actions/list发现全部已注册 Action（含参数 JSON Schema）
    actions/call执行单个 Action
    events/*进程内事件总线（见下文）
    MCP外部工具通过 MCP 连接 动态注册为 integration.{id}.{tool}
    软件连接外部桌面工具经 HTTP 调用本应用 AI 服务，见 软件连接
    import {
  AGENT_PROTOCOL_VERSION,
  getAgentProtocolManifest,
  listProtocolActions,
  callProtocolAction,
  exportActionsMarkdown,
} from '@/services/agent/protocol/agentProtocol';

getAgentProtocolManifest();
// → { protocolVersion: '1.0.0', capabilities: { actions, events, mcp, ... }, events: [...] }

listProtocolActions();
// → { protocolVersion, actions: [...], count }

await callProtocolAction({ name: 'memory.search', params: { query: '上次备份' } });

    2. Action 结果（AgentActionResult）

    字段类型说明
    successboolean是否成功
    messagestring人类可读摘要（亦作为 LLM tool observation）
    dataunknown结构化数据
    contentContentPart[]多段内容：text / image / video / file / json
    errorCodestring机器可读错误码
    progressnumber0–100，长任务可选
    needUser / userPrompt—需用户确认时暂停
    userChoices选项数组可选；界面渲染为可点选按钮（登录继续、编号选项等）
    sideEffectsstring[]副作用标记

    content 片段

    type AgentActionContentPart =
  | { type: 'text'; text: string }
  | { type: 'image'; path?: string; url?: string; mimeType?: string }
  | { type: 'video'; path?: string; url?: string; mimeType?: string }
  | { type: 'file'; path: string; mimeType?: string }
  | { type: 'json'; data: unknown };

    常见 errorCode

    码含义
    unknown_actionAction 未注册
    invalid_params参数缺失或非法
    permission_denied / need_user权限或待确认
    hook_denied / hook_errorHooks 阻断
    embedding_not_ready向量记忆组件未就绪
    mcp_not_connectedMCP 未连接
    execution_errorhandler 抛错

    3. 事件目录

    通过 onAgentEvent(type, handler) 订阅（agentEventBus.ts）。

    事件含义
    agent:runStartedRun 开始
    agent:runCompleted / agent:runFailedRun 结束
    agent:runStatus规范化状态：{ runId, status, goal?, summary?, loop? }
    agent:stepCompleted单步完成
    agent:progress / agent:actionProgress进度文案（及可选 progress%）
    agent:toolCallStart / agent:toolCallEnd工具调用生命周期
    agent:taskProgress任务脚本执行进度（Tauri 桥）
    media:saved媒体已落盘
    integration:mcpEvent / mcpReplan / terminalOutput集成相关
    task:* / workflow:*任务与工作流变更

    说明：当前为 进程内单向事件；尚未提供跨进程 SSE/WebSocket 订阅端点。本应用调外部工具请用 MCP 连接；外部工具调本应用 LLM 请用 软件连接。

    4. 编排策略

    路径条件说明
    Agent Loop（主路径）agentLoopEnabled !== false（默认）tool_calls 自主循环
    Legacy planner显式关闭 Loop兼容多步规划；日志标记弃用倾向

    取消：用户发送「取消/停止」，或 UI 停止按钮 → cancelActiveRun（同时中止进行中的浏览器工作）。

    预算：步数/轮次将尽时，若任务仍在推进可自动扩预算（有次数上限）；否则进入 paused，用户可继续。

    need_user：除文案提示外，可附带 userChoices，聊天区以按钮展示，点击即作为用户回复继续 Run。

    5. 与 MCP / 软件连接 / 历史 IBP

    协议方向状态
    MCP（stdio / HTTP Streamable）本应用 → 工具MCP 连接（动态 Action）
    软件连接 v2（HTTP :14220）工具 → 本应用 AI桌面工具复用已配置模型；非 Agent Action 协议
    IBP—已废弃，请迁移到 MCP / 软件连接

    6. 相关文档