内容
# ccWeb
基于 **Claude Agent SDK(Python) + Anthropic 兼容 API** 的多用户 Web 平台,提供 Claude Code 的原生能力:工具执行、`canUseTool` 权限门、hooks、MCP、subagents。底层模型走 Anthropic 兼容端点(默认示例为火山引擎),不消耗 Claude 订阅,共享池模式。
适合 **团队共享一台智能体工作站**、**在线智能编程/运维**、**多项目协作** 等场景。
## 项目愿景
1. **降低 AI 智能体使用门槛**：让更多的人能够享受到 AI 智能体的便利性,无需因为部署难、对接难而困扰。
2. **让智能体更懂需求**：充足的项目上下文有助于 AI 更准确地理解任务背景,从而完成更精准的开发与决策。
3. **让团队协作更流畅**：一键共享项目给团队其他人,并可配置读写管控权限,实现安全的协同作业。
4. **随时随地可用**：只要能登录 Web,就能在任何设备上使用自己的智能体工作站。
## 解决的痛点
1. ** vibe coding 背景信息不足导致开发偏差**：当前 vibe coding 正在承接大量日常技术迭代需求,但 coding agent 通常由技术驱动,需要把足够的背景描述给 agent。信息不足时 agent 对需求判断不明确,无法准确开发。ccWeb 通过团队共享项目、分岗位沉淀文档,让 agent 在实施时阅读到完整上下文,显著降低偏差。
2. **团队项目隔离与权限控制困难**：团队协作开发时,ccWeb 支持共享项目并控制成员读写权限,为项目隔离、人员隔离、共享项目上下文提供良好的作业环境。
3. **缺少可自定义的在线 Agent**：可以作为独立 Agent 使用,创建独立项目,支持自定义系统提示词,agent 可调用 Tools、Skills、MCP Servers 等能力。
4. **系统级安全可控**：可利用 Docker 部署,通过挂载目录读写权限从系统根源控制 agent 的文件访问范围,确保系统安全。
5. **外部系统对接复杂**：提供丰富的 API 接口,外部对接简单,可实现流式、非流式能力,无缝对接到业务系统。
6. **在线体验与本地 Claude Code 差距大**：ccWeb 尽量保持与本地使用 Claude Code 几乎无体感差异,支持 locale 设置、项目级 subagents、skills 等。
7. **缺乏团队级账号与用量管理**：提供团队账号管理、日/周/月额度管理、对话记录与 token 记录、丰富的用量看板等运营能力。
8. **上下文 token 消耗高**：针对每通对话可灵活设置工具调用权限、通行权限、skill 调用权限等,有效节省上下文 token 消耗,最大可节约 80% 以上。
## 核心特性
- **多用户 & 权限隔离**:管理员可创建/禁用用户、分配日/周/月 token 配额;普通用户只能访问自己的项目与会话。
- **项目级工作空间**:每个会话绑定项目,文件操作限制在项目目录内(软隔离),支持文件上传、目录树、在线预览、导出 zip。
- **原生 Claude Code 能力**:通过 `ClaudeSDKClient` 支持工具调用、权限确认、hooks、MCP Servers、subagents。
- **在线对话**:SSE 流式输出,支持工具授权回灌、会话上下文续聊、Token 用量实时统计。
- **用量看板**:按用户/项目/模型统计输入/输出/缓存/cost,支持日周月配额限制。
- **Agent 配置**:可预设系统提示词、权限模式、绑定工具/Skills、切换模型档位。
- **项目级 API Token**:给外部系统接入,不自动失效,可按项目细粒度控制。
- **一键 Docker 部署**:`docker-compose up -d --build` 即可启动 PostgreSQL + ccWeb。
## Skills 管理
ccWeb 支持**全局 skills 清单**与**项目级 skills 白名单**两套机制,兼顾“能力可见”与“按需加载”。
### 全局 skills 清单
- 服务启动时,后台探针通过 `ClaudeSDKClient` 跑一轮轻量会话,从 SDK 的 `init` 事件动态采集真实的 tools、skills、agents、mcp_servers 全集,缓存在内存中。
- 前端通过 `GET /api/catalog` 获取清单,用于 Agent 配置页面的多选框。
- 安装新 skill 或 SDK 升级后,管理员可调用 `POST /api/catalog/refresh` 重新采集,无需重启服务。
- 动态采集失败时,自动回退到 `backend/app/sdk/catalog.py` 中的硬编码兜底清单,保证接口可用。
### 项目级 skills 白名单
- 在「Agent 配置」中为某个配置勾选要加载的 skills,保存后该配置即携带 `skills_whitelist`。
- 会话绑定该 Agent 配置后,`SessionRunner` 只把白名单内的 skills 传给 SDK;其余 skills 不加载,显著降低上下文 token 消耗。
- 运行时会主动切断 SDK 默认 setting_sources(`~/.claude`),避免自动加载 40+ 默认 skills,确保白名单严格生效。
- 常用内置 skills 包括文档处理(`xlsx`/`docx`/`pptx`/`pdf`)、设计(`frontend-design`/`canvas-design`/`theme-factory`)、开发流程(`superpowers:*` 系列)等。
### 自定义 skills
- 项目工作目录内可放置 `.claude/skills/{skill_name}/SKILL.md`,作为项目级自定义 skill。
- 只要该 skill 被加入对应 Agent 配置的 `skills_whitelist`,当前项目会话即可调用。
## 系统截图
> 以下截图均来自 `docs/pic/` 目录下的样例图,可直接在 README 中预览。
### 项目工作空间
### 项目共享
### 会话历史
### 工具授权
### Agent 配置
### 用量看板
### 用户管理及限额
### 功能介绍视频
<video src="docs/pic/ccweb功能介绍.mp4" controls width="100%"></video>
## 架构
```
前端(单文件 SPA) → 应用层(FastAPI) → 能力层(claude-agent-sdk) → 模型层(Anthropic 兼容 API)
```
- **前端**:原生 JS + CDN(Chart.js/marked/dompurify),无构建步骤,由后端静态托管。
- **应用层**:FastAPI + SQLAlchemy 2.0 async + asyncpg,负责会话/项目/鉴权/计费/用量。
- **能力层**:`ClaudeSDKClient` 封装,挡住 SDK 原始类型,对外统一 `SdkEvent`。
- **模型层**:Anthropic 兼容 API(`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`),模型名全部走环境变量,代码不传 `model`。默认示例使用火山引擎端点。
## 快速开始(Docker Compose,推荐)
### 1. 准备环境
```bash
git clone https://github.com/zhangyifei1/ccWeb.git
cd ccWeb
cp .env.example .env
```
编辑 `.env`,至少填写以下必填项:
| 变量 | 说明 |
|---|---|
| `ANTHROPIC_AUTH_TOKEN` | Anthropic 兼容 API 的 Token/Key(会话认证用) |
| `BOOTSTRAP_ADMIN_PASSWORD` | 初始管理员密码,**首次启动前务必修改** |
| `JWT_SECRET` | JWT 签名密钥,生产环境请填固定长随机串 |
### 2. 启动
```bash
docker-compose up -d
```
- 首次构建约 3-5 分钟(含 `claude-agent-sdk` 自带的 ~227MB bundled CLI)。
- ccweb 会等待 PostgreSQL 健康检查通过后再启动,并**自动建表**(`init_db`,无需 alembic)。
- 访问 `http://<服务器IP>:8000`,用 `admin` + 你设置的密码登录。
查看日志:
```bash
docker-compose logs -f ccweb
```
### 3. 停止
```bash
docker-compose down
```
数据保存在 `./pgdata` 与 `./workspaces`,备份这两个目录即可。
更多部署细节(外部数据库、端口修改、升级、排错)见 [`DEPLOY.md`](DEPLOY.md)。
## 本地开发
```bash
cd backend
pip install -e ".[dev]"
cd ..
cp .env.example .env # 按需修改,本地 DATABASE_URL 默认连 localhost:5432
cd backend
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```
前端无构建步骤,后端启动后访问 http://127.0.0.1:8000/ 即可。
## 主要配置说明
`cp .env.example .env` 后按需修改。常见必填项:
| 变量 | 默认值 | 说明 |
|---|---|---|
| `ANTHROPIC_BASE_URL` | `https://ark.cn-beijing.volces.com/api/coding` | Anthropic 兼容端点(默认示例为火山引擎 Beijing 节点) |
| `ANTHROPIC_AUTH_TOKEN` | *(必填)* | Anthropic 兼容 API Token(注意是 `AUTH_TOKEN`,不是 `API_KEY`;火山引擎对应方舟 Token) |
| `ANTHROPIC_MODEL` | `glm-5.2` | 主模型 |
| `ANTHROPIC_DEFAULT_*_MODEL` | `deepseek-v4-pro` | Haiku/Sonnet/Opus 档位映射 |
| `BOOTSTRAP_ADMIN_USERNAME` | `admin` | 首次启动创建的管理员账号 |
| `BOOTSTRAP_ADMIN_PASSWORD` | *(必填)* | 首次启动创建的管理员密码 |
| `JWT_SECRET` | *(建议必填)* | JWT 签名密钥,空则每次重启生成临时密钥 |
| `AUTH_REQUIRED` | `true` | `false` 时关闭鉴权(仅过渡/本地调试用) |
| `ALLOW_REGISTRATION` | `false` | `false` 时禁止自由注册,由管理员分配账户 |
| `DEFAULT_DAILY/WEEKLY/MONTHLY_QUOTA` | 不限 | 新注册用户默认 token 配额 |
完整变量见 `.env.example` 内中文注释。
## 主要 API
全部挂在 `/api/` 下:
| 路由 | 说明 |
|---|---|
| `/api/auth` | 注册 / 登录 / 当前用户 |
| `/api/projects` | 项目 CRUD + 文件上传 / 树 / 预览 |
| `/api/projects/{id}/tokens` | 项目级 API Token(给外部系统接入) |
| `/api/sessions` | 会话 CRUD |
| `/api/sessions/{id}/chat` | SSE 流式对话 |
| `/api/chat` | 统一对话端点(不传 `session_id` 自动建新会话) |
| `/api/sessions/{id}/permission` | 工具授权回灌 |
| `/api/agent-configs` | Agent 配置(工具 / Skills / 权限模式) |
| `/api/usage` | 用量看板 |
| `/api/admin` | 用户管理(仅管理员) |
| `/api/catalog` | 工具 / Skills 清单 |
| `/api/health/credential` | 凭证健康(管理员) |
> 前端「项目」页点 **「📖 API」** 按钮可查看完整接口文档,顶部一键复制 Authorization / 项目 ID / 会话 ID / Agent 配置 ID。
## 目录结构
```
ccWeb/
├── backend/
│ ├── app/
│ │ ├── api/ # 路由(auth/projects/sessions/chat/admin/usage/catalog/permission/health)
│ │ ├── sdk/ # SDK 封装层(runner/permission/hooks/path_guard/registry/events)
│ │ ├── config.py # 配置加载
│ │ ├── security.py # 鉴权(JWT + 项目 token)
│ │ ├── models.py # ORM 模型(均带 user_id 前瞻设计)
│ │ ├── quota.py # 配额(日/周/月)
│ │ └── main.py # FastAPI 入口
│ ├── tests/ # pytest 套件
│ ├── workspaces/ # 运行时用户工作目录(gitignore)
│ └── pyproject.toml
├── frontend/
│ ├── index.html # 单文件 SPA
│ ├── login.html
│ ├── assets/ # logo 等静态资源
│ ├── app/ # 模块化 JS
│ └── styles/ # CSS
├── docker-compose.yml # 一键部署
├── Dockerfile
├── .env.example # 环境变量模板
└── LICENSE # 开源协议
```
## 关键设计
- **模型由环境变量控制**:代码不传 `model`,SDK 子进程注入 `ANTHROPIC_*` 环境变量。与前置 claude-web 配置一致。
- **能力层用 `ClaudeSDKClient`**:支持 `can_use_tool` 权限门、hooks、MCP、subagents 交互;`query()` 一次性函数只适合无交互场景。
- **软隔离(项目模式)**:对话必绑项目,工作目录 `{WORKSPACE_ROOT}/{user_id}/{project_id}/`。文件工具路径 resolve 后校验越界硬 deny;Bash 危险命令走授权门。**非进程级隔离**,按内部可信小团队设计;如需更高隔离请评估 M3 后的容器化方案。
- **表结构按 `user_id` 前瞻设计**:所有表带 `user_id`,M1 单用户占位,M3 接用户体系不改表。
- **计费是应用层账本**:拦截 SDK `usage`/`model_usage` 事件给用户算账 + 配限额,不追求与底层成本逐 token 对齐。
## 安全提示
- 生产环境务必将 `AUTH_REQUIRED` 设为 `true`,`ALLOW_REGISTRATION` 设为 `false`,并填写强 `JWT_SECRET`。
- `BOOTSTRAP_ADMIN_PASSWORD` 仅在首次启动创建 admin 时生效,请在部署前修改为强密码。
- `.env` 含敏感信息,已加入 `.gitignore`,请勿提交到仓库。
- 当前为**软隔离**,适合可信团队内部使用;不要直接暴露给不可信公网用户。
## License
ccWeb 采用**参考 Dify 的修改版 Apache License 2.0** 授权,核心附加条款:
- 可免费商用;但**多租户 SaaS 化服务**需向原作者取得商业授权。
- 使用 ccWeb 前端(`frontend/` 目录或 Docker 镜像中的前端静态资源)时,**不得移除或修改 LOGO 及版权信息**。
- 贡献者同意作者可调整开源协议,且贡献代码可用于商业用途。
完整协议见 [`LICENSE`](LICENSE)。
> 注意:该协议包含自定义商业限制条款,不是 OSI 认证的纯开源许可证;若你有 SaaS/多租户商业化需求,请先与我们联系取得授权。
## 致谢
- [Claude Agent SDK](https://github.com/anthropics/claude-code-sdk) —— 能力层核心
- [火山引擎](https://www.volcengine.com/) —— 默认模型接入示例
