# capp-sdk

**Repository Path**: fa0/capp-sdk

## Basic Information

- **Project Name**: capp-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# capp

基于 [`@anthropic-ai/claude-agent-sdk`](https://code.claude.com/docs/en/agent-sdk) 的应用创建工具。既可以作为 CLI 交互使用，也可以安装为 Node.js SDK，嵌入其他项目。

## 安装

```bash
npm install capp
```

认证复用 Claude Code 的登录凭证，也可以设置 `ANTHROPIC_API_KEY`。

## CLI 使用

```bash
# 安装后运行
npx capp

# 直接创建应用
npx capp "帮我在 ./todo-app 创建一个 React todo 应用"

# 指定模型
npx capp --model claude-sonnet-4-6 "创建一个博客应用"

# 指定输出根目录
CAPP_OUTPUT_DIR=./apps/blog npx capp "创建一个博客应用"
```

CLI 默认会把生成文件统一写入当前目录下的 `capp-output/<sessionId>`，每次会话使用独立的 SDK session id 作为子目录名，避免不同会话互相覆盖；可通过 `CAPP_OUTPUT_DIR` 修改输出根目录。交互模式支持 `/rewind`、`/model`、`/session`、`/help` 和 `/exit`。`Ctrl+C` 会中断当前轮，再次使用则退出。

本仓库开发：

```bash
npm install
npm run dev
npm run build
npm start
```

> **Linux 下以 root 运行**：capp 会以 `--dangerously-skip-permissions` 启动底层 Claude Code 进程。在 Linux 上以 root（或 `sudo`）身份运行时，Claude Code 出于安全考虑会拒绝该模式并以退出码 1 退出，表现为 `会话异常: Claude Code process exited with code 1`。请确认运行在容器 / 沙箱等隔离环境中，并设置环境变量 `IS_SANDBOX=1` 放行：
>
> ```bash
> IS_SANDBOX=1 npm run dev
> # CLI 同理：
> IS_SANDBOX=1 npx capp "创建一个博客应用"
> # Web 示例同理：
> IS_SANDBOX=1 npm run example:web
> ```

## 运行示例

仓库内提供了一个完整的多轮 SDK 示例：[examples/create-app.mjs](./examples/create-app.mjs)。它会在 `examples/output/todo-app` 中创建应用：

```bash
npm run example
```

另有一个 Claude Desktop 风格的本地 Web 客户端，包含流式回复、工具调用展示、中断、模型切换和 rewind：

```bash
npm run example:web
# 浏览器打开 http://127.0.0.1:4173
```

生成的应用默认写入 `examples/output/web-app/<sessionId>`，每个 Web 会话使用独立子目录。可通过 `CAPP_OUTPUT_DIR`、`CAPP_MODEL` 和 `PORT` 环境变量修改输出根目录、模型和端口；未设置 `CAPP_MODEL` 时也会读取 `ANTHROPIC_MODEL`。Web 客户端会根据 `ANTHROPIC_BASE_URL` 请求上游模型列表；自定义网关也可通过 `CAPP_MODELS_URL` 显式指定模型列表接口。

运行前请确保已登录 Claude Code，或已设置 `ANTHROPIC_API_KEY`。

## SDK：单次创建

`createApp()` 会在指定工作目录内执行创建任务，并在完成后自动关闭会话：

```ts
import { createApp } from "capp";

const result = await createApp("创建一个 Express REST API，包含测试", {
  cwd: "/absolute/path/to/workspace",
  model: "claude-sonnet-4-6",
  onEvent(event) {
    if (event.type === "text_delta") process.stdout.write(event.text);
    if (event.type === "tool_use") {
      console.log(event.name, JSON.stringify(event.input, null, 2));
    }
    if (event.type === "tool_result") {
      console.log(event.toolUseId, event.isError, event.content);
    }
  },
});

console.log(result.sessionId);
console.log(result.response);
```

## SDK：多轮会话

需要继续修改应用或使用 rewind 时，创建一个 `AppCreator`：

```ts
import { AppCreator } from "capp";

const creator = new AppCreator({
  cwd: "/absolute/path/to/workspace",
  onEvent: (event) => {
    if (event.type === "text_delta") process.stdout.write(event.text);
  },
});

try {
  await creator.create("创建一个 TypeScript todo 应用");
  await creator.send("增加用户登录，并补充测试");

  // 回退到第一个提示词执行前的文件与对话状态
  if (creator.checkpoints.length > 0) {
    await creator.rewind(0);
  }
} finally {
  creator.close();
}
```

## 自定义底层 Agent

通过 `agentOptions` 传递 Claude Agent SDK 的原生选项。它们会覆盖 capp 默认值：

```ts
import { createApp } from "capp";

await createApp("创建应用", {
  cwd: process.cwd(),
  agentOptions: {
    maxTurns: 20,
    maxBudgetUsd: 5,
    permissionMode: "acceptEdits",
    allowDangerouslySkipPermissions: false,
  },
});
```

## SDK：获取模型列表

`getModels()` 默认读取 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`：

```ts
import { getModels } from "capp";

const models = await getModels();
```

自定义网关也可传入 `modelsURL`、`baseURL`、`apiKey` 或自定义 `fetch`。

默认配置允许 Agent 自动执行工具并修改 `cwd` 下的文件。对不可信输入或共享环境，建议通过 `agentOptions` 使用更严格的权限策略。

## API

- `createApp(prompt, options)`：单次创建，返回 `CreateAppResult`
- `new AppCreator(options)`：多轮创建客户端
- `getModels(options)`：获取 Anthropic 兼容服务提供的模型列表
- `creator.create(prompt)` / `creator.send(prompt)`：发送需求并等待本轮结束
- `creator.interrupt()`：中断当前轮
- `creator.setModel(model)`：切换模型
- `creator.rewind(index)`：回退文件和对话
- `creator.close()`：释放底层进程和输入流
- `createAppOptions(options)`：获取并扩展默认 Claude Agent SDK 配置

## Rewind 限制

文件检查点只追踪 Write、Edit、NotebookEdit 的改动。Bash 命令产生的文件变化，以及目录的创建、移动、删除，不会被回退；检查点也只能用于创建它的 session。