# claude-web

**Repository Path**: HSKS/claude-web

## Basic Information

- **Project Name**: claude-web
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# claude-agent-web

**Web 版 Claude Code**：多人共用的 AI 编码智能体平台。基于 `@anthropic-ai/claude-agent-sdk`
驱动 CLI 子进程，Bun + Hono 后端（无 DB，运行时状态落 sidecar 文件），React 聊天前端，
可编译为单文件可执行部署（含 deep-link 拉起与自更新）。

> 开发前必读 [开发规范.md](./开发规范.md)：强约定 + 固定范式，`packages/backend/src/modules/auth/` 是业务模块标准范式（活教材），
> `packages/backend/src/modules/agent/` 是复杂模块（SSE/注册表/子进程）进阶参考。

## 功能特性

- **AI 编码会话**：SSE 流式输出、工具调用特化渲染（Bash/文件树/搜索结果…）、工具审批
  （可修改参数/总是放行）、中断、执行模式四档（auto/standard/safe/plan 热切换）、
  子代理上下文面板、图片输入、斜杠命令与 @ 提及、文件树在线编辑与上传
- **多用户隔离**：CIM 薄代理认证（EdDSA JWT 验签 + cookie）；每用户独立 `CLAUDE_CONFIG_DIR`，
  会话注册表按目录做属主校验与配额（每用户/全局上限、空闲回收、绝对寿命、evict 接管）
- **无 DB 存储**：项目元数据（`.project.json`）与会话 runMode 快照（`.meta.json`）落
  `AGENT_CONFIG_ROOT/<user>/` sidecar，会话历史即 SDK JSONL——一人一套，零跨用户并发
- **工作空间**：路径后端推导（用户只输项目名），落 `AGENT_CONFIG_ROOT/<user>/workspaces/<uuid>/`
- **deep-link**：`csmcode://download?url=<zip>&name=<workspace>&user=<name>` 拉起 +
  解压落 uuid 工作空间 + launch token 免登；单实例锁 + 热转发
- **工程化**：结构化日志 traceId 全链路、单文件编译产物（内嵌前端）、自更新（OBS 清单）、
  BASE_URL 子路径部署

## 技术栈

| 关注点 | 选型 |
|---|---|
| 运行时 / 包管理 / 测试 | bun（`bun test`） |
| 后端框架 | hono + zod v4（`vh` 校验中间件，无 OpenAPI 文档层） |
| AI 能力 | @anthropic-ai/claude-agent-sdk（spawn CLI 子进程，streaming-input 常驻） |
| 持久化 | 无 DB：`AGENT_CONFIG_ROOT` sidecar 文件（原子写 tmp+rename） |
| 前端 | Vite + React 19 + Tailwind v4 + zustand + shadcn 范式组件 + sonner |
| 契约 | `@csm/shared`：请求 zod schema（运行时校验 + 类型双导出）+ 响应纯 TS 接口 |
| 日志 | pino（结构化 JSON，dev 彩色 pretty） |
| Lint / Format | biome（backend/shared）/ prettier（webui/） |

## 快速开始

```bash
# 0) 前置：Node/Bun 已装；.env 至少需要 Anthropic 网关三件套
#    （ANTHROPIC_BASE_URL/AUTH_TOKEN/MODEL，见 .env.example）

bun install                     # 全 workspace 依赖

bun run dev:backend             # 后端（热重载）-> http://localhost:30000
bun run dev:webui               # 前端（另开终端）-> http://localhost:3001（proxy 转 30000）
```

- 健康检查：`/healthz`（存活）、`/readyz`（就绪）
- 全部环境变量说明见 `.env.example`

## 常用命令

| 命令 | 说明 |
|---|---|
| `bun run dev:backend` / `dev:webui` | 后端 / 前端开发模式 |
| `bun run build` | 打包单文件可执行到 bin/（见「打包部署」） |
| `bun test` / `bun run test:watch` | 运行测试 |
| `bun run typecheck` | TS 类型检查（backend+shared；webui 另跑 `cd packages/webui && bunx tsc --noEmit -p tsconfig.app.json`） |
| `bun run lint` / `lint:fix` | biome 检查 / 自动修复（backend/shared；webui 用 prettier） |

## 目录结构

```
├── packages/
│   ├── backend/
│   │   └── src/
│   │       ├── index.ts       # 进程入口：单实例锁 + deep-link 分流 + Bun.serve + 优雅停机
│   │       ├── app.ts         # 应用组装：中间件 -> 路由 -> onError/notFound（不监听端口，可测）
│   │       ├── env.ts         # 环境变量 zod 校验，导出类型安全的 env（配置唯一来源）
│   │       ├── core/          # 框架地基（默认禁止修改）：错误码/AppError/响应工厂/日志/中间件
│   │       ├── modules/       # 业务模块区（开发主战场）
│   │       │   ├── auth/      # CIM 薄代理 + EdDSA 验签（标准范式）
│   │       │   ├── agent/     # AI 会话核心：project-store/会话/审批/SSE + SDK 集成层
│   │       │   └── system/    # deep-link 拉起/自更新/安装引导
│   │       ├── routes/        # 路由总表：healthz/readyz + 模块挂载
│   │       └── utils/         # 跨模块纯函数工具（分页等）
│   ├── webui/                 # React 前端（pages/components/hooks/stores/lib，详见开发规范第 13 节）
│   └── shared/                # @csm/shared：FE↔BE 契约（dto/sdk-protocol/messages/sse-events）
└── packages/backend/scripts/  # build 编译编排 / install 安装器 / publish-obs 发布
```

## 存储布局（无 DB）

```
AGENT_CONFIG_ROOT/
└── <account>/                          # 每用户根 = userConfigDir(<account>)
    ├── projects/<encoded-cwd>/<sid>.jsonl     # SDK 会话转录
    ├── projects/<encoded-cwd>/<sid>.meta.json # 会话 runMode/personaId 快照
    ├── sessions/<pid>.json                     # CLI 槽位（SDK 写）
    └── workspaces/<uuid>/                      # 项目工作空间（CLI cwd）
        └── .project.json                       # { name, createdAt }
```

## 全局配置分发（GLOBAL_CONFIG_ROOT）

admin 维护一份共享内容，所有用户会话自动获得（`.env` 的 `GLOBAL_CONFIG_ROOT`，缺省 `./data/global-configs`；目录不存在 = 功能自动关闭，零影响）。三个通道：

| 通道 | 目录 | 机制 |
|---|---|---|
| skills / agents / commands / hooks | `<GLOBAL>/skills/<name>/SKILL.md`、`<GLOBAL>/agents/*.md`、`<GLOBAL>/commands/`、`<GLOBAL>/hooks/` | 整个 `<GLOBAL>` 作为一个本地插件包经 SDK `Options.plugins` 注入；每次开会话重读盘上内容，**admin 改动对新会话即时生效**（无需重启服务）。skill 调用带命名空间：`/global:skill-name` |
| marketplace 插件 | `<GLOBAL>/plugins/` | 用户目录 `plugins/` 整目录 junction 到全局（Windows junction 免特权）；admin 预装一次全员共享。**已知取舍**：CLI 运行时会回写该共享目录，多用户并发存在竞争损坏风险（已知情接受），admin 变更请在低峰 |
| 人设库（系统提示词） | `<GLOBAL>/system-prompt/<id>.md` | 前端输入框下方人设选择器；正文以 systemPrompt append 注入（`snapshot:false` 支持热切换）。frontmatter `name/description` 可省（兜底文件名/首行）；resume 会话按 sidecar 快照回填人设 |

### admin 操作

```powershell
# 1) 插件包内容：直接放文件即可（推荐补一个 manifest 获得干净的 global: 命名空间前缀）
#    <GLOBAL>/.claude-plugin/plugin.json → { "name": "global", "description": "全局共享能力包", "version": "1.0.0" }
#    注意：agents 需平铺在 <GLOBAL>/agents/*.md（不支持 built-in/ 等子目录嵌套）

# 2) marketplace 插件 bootstrap（在全局目录装好，用户 junction 共享）
$env:CLAUDE_CONFIG_DIR = "<repo 绝对路径>\data\global-configs"
& node_modules\.bun\@anthropic-ai+claude-agent-sdk-win32-x64@0.3.278\node_modules\@anthropic-ai\claude-agent-sdk-win32-x64\claude.exe
#   交互会话内：/plugin marketplace add <repo> → /plugin install <plugin>@<marketplace>
#   装完确认 <GLOBAL>/settings.json 的 enabledPlugins 与 <GLOBAL>/plugins/ 就位；
#   用户侧下次 openSession/probe 自动 junction + merge enabledPlugins。
#   编译部署：设置 AGENT_CLI_PATH 指向自备 claude 二进制，或在部署机直装 Claude Code 后同法操作。

# 3) 人设：放 <GLOBAL>/system-prompt/xxx.md 即出现在前端选择器（放文件即生效，新会话起）
```

用户侧冲突保护：用户目录已有真实非空 `plugins/` 目录时不强制接管（warn 跳过，README 手工迁移）；settings.json 的 `enabledPlugins` merge 只增不删。

## 请求处理链路

```
Bun.serve
  └─ requestContext   traceId 生成/透传 + child logger（AsyncLocalStorage）
  └─ accessLog        每请求一条汇总日志（method/path/status/durationMs/ip/ua）
  └─ [cors]           CORS_ORIGIN 配置时启用
  └─ routes           route handler：c.req.valid() -> service -> ok()
       └─ service     业务逻辑；错误只 throw AppError；不依赖 hono
            └─ project-store / agent-session-history   sidecar 文件读写（原子写）
  └─ onError          AppError -> 注册表查 status；未知 -> 500（日志留全量）
  └─ notFound         未匹配路由统一 404
```

统一响应：成功 `{ "data": ... }`；失败 `{ "error": { "code", "message", "traceId" } }`。

会话操作特殊协议：POST/DELETE 类携带 header `x-session-id` + `x-workspace-dir`(base64url)；
SSE 端点走 query 参数（EventSource 不支持自定义 header）。

## 日志与问题排查

**traceId 三处一致**：每条日志字段、响应头 `x-request-id`、错误响应体 `error.traceId`。
拿到一个 traceId 即可在 `logs/`（按日滚动，保留期 LOG_RETENTION_DAYS）还原该请求完整链路。

| 手段 | 开启方式 |
|---|---|
| 请求体日志（截断 2KB，敏感字段脱敏） | `LOG_BODY=true` |
| dev 彩色单行日志 | `NODE_ENV=development`（默认） |
| 生产 JSON 日志 | `NODE_ENV=production` |

## 打包部署

```bash
bun run build
# 产物：bin/csmcode-{platform}-{arch}-{version}[.exe] —— 唯一产物，单文件（约 300MB）
# 内嵌 bun 运行时 + 前端页面
# 交叉编译：bun run build -- --target=win（短名）或 bun-{windows|linux|darwin}-{x64|arm64}
#   注意：bun install 按本机 OS 只装本机平台的 CLI 包，交叉编译前需手工补装目标平台包：
#   bun add @anthropic-ai/claude-agent-sdk-linux-x64@0.3.278   # 版本对齐 dependencies 中的 SDK
#   （仅构建期解析需要，构建完可还原 package.json / bun.lock）
#   musl / darwin-x64 / arm64 变体不内嵌 CLI：产物需目标机设置 AGENT_CLI_PATH 指向自备 claude 二进制
```

部署用安装器一键装（下载 + 协议注册 + PATH shim + 开始菜单）：

```powershell
# Windows
irm https://<obs>/install-win.ps1 | iex
# Linux / macOS 对应 install-linux.sh / install-mac.sh
```

- 安装后命令：`csmcode`（启动 + 开浏览器）/ `csmcode update`（自更新）/ `csmcode uninstall`
- 也会自动读取 exe 同目录下的 `.env`
- 可执行文件同时服务前端页面与 API：`/` 为前端入口，`/api/*` 为后端接口
- **子路径部署**（nginx 反代场景）：`.env` 设 `BASE_URL=/claude`（一处配置全链生效）；
  构建 exe 时须设相同值（驱动前端产物路径），启动时同理

## 常见问题

- **Windows 终端 curl 中文乱码**：Git Bash 的 curl 以本地编码发送 body，属客户端问题；
  用 `--data-binary @file.json`（UTF-8 文件）或代码内 fetch 验证。
- **bun --hot 后行为异常**：热重载旧实例状态可能残留，重启 dev 即可。
- **改后端代码后 AI 会话报「会话不存在」**：dev 热重载会中断活跃 CLI 子进程（属预期），
  刷新页面即走恢复链路；生产编译版无此现象。
- **创建会话后列表空**：看后端日志是否 `executable_launch_failed`（ENOENT）——
  项目工作空间目录被删/移动会导致 CLI spawn 静默失败，现已有前置校验显式报错，
  按提示移除项目重建即可。
- **agent 调用 LLM 报错**：检查 `.env` 的 Anthropic 网关三件套是否填写正确。