{
  "title": "Agent Client Protocol (ACP) Tutorial Visual Pack",
  "theme": {
    "accent": "#1f4e79",
    "accent2": "#4e791f",
    "ink": "#111827",
    "muted": "#5f6673",
    "surface": "#f8f6f1",
    "border": "#d9d6cc",
    "paper": "#ffffff"
  },
  "board_style": {
    "layout": "sticky-rail-canvas",
    "aspect_ratio": "16:9",
    "visual_system": "frontend-slides-first canvas board"
  },
  "chapters": [
    {
      "id": "chapter-01",
      "title": "ACP vs. MCP 架构层级对比图",
      "diagram_type": "comparison",
      "layout_note": "A comparison/layer diagram is ideal to show how ACP and MCP work together but have different responsibilities.",
      "summary": "ACP standardizes Client-to-Agent communication (Control & Dialog), while MCP standardizes Agent-to-Tool communication (Data & Exec).",
      "columns": [
        {
          "title": "ACP (Agent Client Protocol)",
          "rows": [
            "边界: Code Editor <-> AI Agent",
            "核心协议: JSON-RPC 2.0 (Methods / Notifications)",
            "通信职责: 对话控制、生命周期、用户鉴权、终端/文件控制协商"
          ]
        },
        {
          "title": "MCP (Model Context Protocol)",
          "rows": [
            "边界: AI Agent <-> Tools / Services",
            "核心协议: JSON-RPC 2.0 (Tools / Prompts / Resources)",
            "通信职责: 提供外部工具、挂载本地资源、上下文供给"
          ]
        }
      ],
      "caption": "ACP 解决编辑器与 Agent 的决策对话问题；MCP 解决 Agent 与外部工具的数据流问题。两者层级分明，互为补充。"
    },
    {
      "id": "chapter-02",
      "title": "ACP 交互生命周期时序图",
      "diagram_type": "flow",
      "summary": "The four main stages of the ACP JSON-RPC message sequence.",
      "nodes": [
        {
          "label": "1. 初始化阶段 (Initialize)",
          "detail": "Client/Agent 握手并协商协议版本及 Capabilities (文件、终端能力)"
        },
        {
          "label": "2. 会话建立 (session/new)",
          "detail": "Client 发起新会话，指定工作目录 (cwd) 并可选注入 MCP 服务"
        },
        {
          "label": "3. 决策交互流 (session/prompt & session/update)",
          "detail": "Client 发送 Prompt，Agent 交互处理并流式回传 update 更新与权限校验"
        },
        {
          "label": "4. 会话结束 / 恢复 (load)",
          "detail": "通过 cancel 终止任务，或者支持 session/load 恢复持久化会话"
        }
      ],
      "caption": "ACP 连接生命周期有着严格的顺序要求。必须先经历 initialize 握手，才能调用 session/new 开启真正的会话决策流。"
    },
    {
      "id": "chapter-03",
      "title": "OpenCode ACP Stdio 管道拓扑图",
      "diagram_type": "layer",
      "summary": "How standard I/O (stdio) acts as the secure IPC mechanism for local ACP.",
      "nodes": [
        {
          "label": "IDE (Client)",
          "detail": "如 Zed / VS Code。作为父进程负责启动、监控和销毁 Agent。"
        },
        {
          "label": "stdin / stdout (Stdio 管道)",
          "detail": "操作系统级的双向标准管道，传输 JSON-RPC 的 NDJSON (按行切分的 JSON) 数据流。"
        },
        {
          "label": "OpenCode (Agent)",
          "detail": "运行 `opencode acp` 命令的主进程。拦截 stdin，解析 ACP 协议并直接控制底层的 LLM 执行任务。"
        }
      ],
      "caption": "在本地部署模式中，IDE 通过 Stdio 管道管理 OpenCode 子进程。每次通信都作为一个单行的 NDJSON，无状态、低开销且具有天然的操作系统沙箱隔离特性。"
    },
    {
      "id": "chapter-04",
      "title": "自定义 ACP Agent 服务双重启动模式",
      "diagram_type": "layer",
      "summary": "A single TypeScript Agent can be launched in two ways for local and remote deployment.",
      "nodes": [
        {
          "label": "模式 A: Stdio CLI (本地集成)",
          "detail": "使用 createStdioStream 绑定 process.stdin/stdout，由本地 IDE 直接进程拉起。"
        },
        {
          "label": "模式 B: Streamable HTTP/WS Server (远程自部署)",
          "detail": "利用 http 模块创建服务器并接收 WebSocket 升级，客户端可通过远程 IP:Port 访问 Agent。"
        }
      ],
      "caption": "通过 `@agentclientprotocol/sdk`，我们可以编写统一的 CoreAgent 业务逻辑，并只需更改入口封装，即可轻松在 Stdio 本地管道模式与 HTTP/WS 远程服务模式之间任意切换。"
    },
    {
      "id": "chapter-05",
      "title": "MCP-over-ACP 反向工具调用链",
      "diagram_type": "flow",
      "summary": "How Client provides local tools to Remote Agent via MCP-over-ACP reverse communication.",
      "nodes": [
        {
          "label": "1. 注册工具声明 (Client -> Agent)",
          "detail": "Client 在 session/new 时，随请求将 Client 侧支持的 MCP 服务器声明发送给 Agent。"
        },
        {
          "label": "2. 自主决策 (Agent)",
          "detail": "Agent 分析任务，发现需要客户端的文件写入或终端命令工具。"
        },
        {
          "label": "3. 反向调用 (Agent -> Client)",
          "detail": "Agent 通过 `mcp/message` 反向把 Tool Call 请求发送到 Client 侧。"
        },
        {
          "label": "4. 执行并返回 (Client -> Agent)",
          "detail": "Client 执行安全审计后运行本地工具，再通过 ACP 将结果原路返回给 Agent。"
        }
      ],
      "caption": "MCP-over-ACP 打通了双向互操作性。不仅 Client 可以调用 Agent 编排任务，Agent 也能反向利用 Client 侧自带的、受信任的本地工具链，解决了安全与本地执行的痛点。"
    }
  ]
}