ACP组件库

Prerequisites

• Node.js >= 18
• pnpm
• An ACP-compatible agent (e.g., opencode with acp subcommand)

Install dependencies

pnpm install

Installation

pnpm add @acp-components/core @acp-components/react

Peer dependencies: react (^18 || ^19), react-dom (^18 || ^19)

Setup

```bash

Build all packages

pnpm build

Build individual packages

pnpm build:core pnpm build:react

Quick Start

import ReactDOM from 'react-dom/client';
import {
  I18nProvider,
  AcpProvider,
  Workbench,
  ProjectOpener,
  SessionList,
  ChatView,
  PermissionDialog,
  LoginDialog,
} from '@acp-components/react';
import { useAcpStore } from '@acp-components/react';

function App() {
  const activeSessionId = useAcpStore((s) => {
    if (!s.activeWorkspaceCwd) return null;
    return s.workspaces.get(s.activeWorkspaceCwd)?.activeSessionId ?? null;
  });

  return (
    <I18nProvider>
      <AcpProvider
        agents={[
          {
            id: 'main',
            name: 'Main Agent',
            transport: { type: 'websocket', url: 'ws://127.0.0.1:3100' },
          },
        ]}
        theme="dark"
        defaultCwd="/path/to/project"
      >
        <Workbench
          sidebar={
            <>
              <ProjectOpener />
              <SessionList />
            </>
          }
          main={<ChatView sessionId={activeSessionId} />}
        />
        <PermissionDialog sessionId={activeSessionId} />
        <LoginDialog />
      </AcpProvider>
    </I18nProvider>
  );
}

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);

Multi-Agent Example

Connect to multiple agents in different modes simultaneously:

<AcpProvider
  agents={[
    {
      id: 'craft',
      name: 'Craft Agent',
      transport: { type: 'websocket', url: 'ws://127.0.0.1:3100' },
      clientCapabilities: { fs: { readTextFile: true, writeTextFile: true } },
    },
    {
      id: 'ask',
      name: 'Ask Agent',
      transport: { type: 'stdio', command: 'opencode', args: ['acp', '--mode', 'ask'] },
    },
  ]}
  theme="dark"
>
  <App />
</AcpProvider>

Framework-Agnostic Usage

The @acp-components/core package has zero React dependency. You can use it with any framework:

import { acpStore, sessionStore, createAcpProvider, sendPrompt } from '@acp-components/core';

// 1. Create multi-agent provider
const provider = createAcpProvider({
  agents: [
    { id: 'main', name: 'Main', transport: { type: 'stdio', command: 'opencode', args: ['acp'] } },
  ],
});

// 2. Wait for ready
provider.subscribe(() => {
  if (provider.ready) {
    console.log('All agents connected!');
  }
});

// 3. Read from vanilla stores
acpStore.getState().workspaces;       // workspace state tree
acpStore.getState().agents;           // agent connection statuses
acpStore.subscribe((state) => { });   // watch for changes

// 4. Use actions (need to provide client and agentId)
const client = provider.getClient('main');
await sendPrompt(client!, sessionId, blocks);

// 5. Add/remove agents dynamically
await provider.addAgent({ id: 'analyze', name: 'Analyze', transport: { type: 'websocket', url: 'ws://...' } });
await provider.removeAgent('analyze');

Screenshots

Web Demo

Web Demo

```bash

Transport Options

Each agent in the agents array gets its own transport configuration:

// Stdio — spawn an agent process directly (Electron / Tauri / Node.js desktop)
{
  id: 'desktop-agent',
  name: 'Desktop',
  transport: { type: 'stdio', command: 'opencode', args: ['acp'] },
}

// HTTP — connect via HTTP POST
{
  id: 'http-agent',
  name: 'HTTP',
  transport: { type: 'http', url: 'http://localhost:8080/acp', headers: { 'Authorization': 'Bearer token' } },
}

// WebSocket — connect to a bridge server (browser environments)
{
  id: 'ws-agent',
  name: 'WebSocket',
  transport: { type: 'websocket', url: 'ws://127.0.0.1:3100' },
}

// Custom — provide your own AcpTransport implementation
{
  id: 'custom-agent',
  name: 'Custom',
  transport: { type: 'custom', transport: myCustomTransport },
}

Bridge Server Configuration

acp-components

A universal frontend component library for building AI Agent interfaces based on the Agent Client Protocol (ACP). Designed with a data-layer / UI-layer separation architecture:

• @acp-components/core — Framework-agnostic TypeScript module: transport communication, state management, business logic
• @acp-components/react — React component library: UI rendering and user interaction

You can use the data layer alone to build UI component libraries with Vue, Svelte, or any other frontend framework.

Packages

Components

Terminal Integration

Control how agents create and manage terminals:

<AcpProvider
  agents={[...]}
  onTerminal={{
    create: async (params) => {
      // params: { sessionId, command, args?, cwd? }
      const proc = spawn(params.command, params.args ?? [], { cwd: params.cwd ?? undefined });
      return {
        terminalId: generateId(),
        getOutput: async () => ({ output: allOutput }),
        waitForExit: async () => new Promise((resolve) => proc.on('exit', resolve)),
        kill: async () => proc.kill(),
        release: async () => {},
        onOutputChange: (fn) => proc.stdout.on('data', fn),
        onExit: (fn) => proc.on('exit', fn),
      };
    },
  }}
>

Terminal states are accessible via the useTerminals(sessionId) hook and rendered with the TerminalView component.

File System Integration

Control how agents read and write files:

<AcpProvider
  agents={[...]}
  onFileRead={async (req) => {
    const content = await nativeFs.readTextFile(req.path);
    return { content };
  }}
  onFileWrite={async (req) => {
    await nativeFs.writeTextFile(req.path, req.content);
    return {};
  }}
>