# https://github.com/shumaiOne/shumai 项目说明书

生成时间：2026-06-23 13:12:33 UTC

## 目录

- [Shumai 概览与系统架构](#page-1)
- [核心平台、数据模型与 API](#page-2)
- [AI Agent、工具与 Temporal 工作流](#page-3)
- [Web UI、CLI 与部署运维](#page-4)

<a id='page-1'></a>

## Shumai 概览与系统架构

### 相关页面

相关主题：[核心平台、数据模型与 API](#page-2), [AI Agent、工具与 Temporal 工作流](#page-3), [Web UI、CLI 与部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/shumaiOne/shumai/blob/main/README.md)
- [package.json](https://github.com/shumaiOne/shumai/blob/main/package.json)
- [apps/cli/README.md](https://github.com/shumaiOne/shumai/blob/main/apps/cli/README.md)
- [apps/cli/src/index.ts](https://github.com/shumaiOne/shumai/blob/main/apps/cli/src/index.ts)
- [apps/web/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/web/package.json)
- [apps/cli/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/cli/package.json)
- [apps/agent/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/agent/package.json)
- [apps/transcode/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/transcode/package.json)
- [packages/api/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/api/package.json)
- [packages/core/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/core/package.json)
- [packages/agent/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/agent/package.json)
- [packages/transcode/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/transcode/package.json)
- [packages/workflow-core/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/workflow-core/package.json)
- [packages/dtos/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/package.json)
- [packages/tableprinter/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/tableprinter/package.json)
- [packages/api/src/project.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/project.test.ts)
- [packages/api/src/metadata.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/metadata.test.ts)
- [packages/api/src/versionStack.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/versionStack.test.ts)
</details>

# Shumai 概览与系统架构

## 项目定位与核心能力

Shumai 是一个面向创意协作的开源平台，用于集中管理媒体资产、协作反馈与 AI 增强的工作流。资料来源：[README.md:1-30]()。

平台围绕以下几类核心能力构建：

- **S3 兼容与本地存储**：支持本地文件系统或任意 S3 兼容对象存储（AWS S3、Cloudflare R2、MinIO 等）保存图片与视频素材。
- **帧级注释与时间戳评论**：在视频与图片上提供逐帧绘制工具与时间码评论，便于精确反馈。
- **安全分享与媒体集合**：通过安全公开链接与策展集合对外协作。
- **细粒度访问控制**：团队级与项目级两层 RBAC。
- **基于 Temporal 的分布式转码**：将重负载的视频转码任务卸载至 Temporal worker 池。
- **自定义资产元数据**：支持按管线定义动态字段。
- **Shumai Agent**：在工作空间内提供上下文感知的 AI 对话、可注册的脚本/工具、沙箱执行（基于 Anthropic 沙箱运行时）、Google Gemini 元数据自动填充以及基于向量嵌入的语义检索。

最新版本 `v0.1.1` 在 Docker 入口处增加了数据卷的权限降级（PR #151），强化容器化部署时持久化卷的主机侧安全边界。资料来源：[v0.1.1 发布说明](https://github.com/shumaiOne/shumai/compare/v0.1.0...v0.1.1)。

## 技术栈与运行时依赖

Shumai 基于 Bun 与 TypeScript 生态构建，由根 [package.json](package.json) 通过 `workspaces: ["packages/*", "apps/*"]` 将仓库组织为 Monorepo。Web 入口由 `bun run --hot apps/web/src/index.ts` 启动；后台 worker 由 `worker:agent` 与 `worker:transcode` 脚本启动；测试通过 Vitest 运行并依赖 `@testcontainers/postgresql` 拉起真实数据库实例。资料来源：[package.json:1-50]()。

各子包的核心依赖反映了其职责：

- `@shumai/api` 使用 `hono` 框架、`@hono/zod-validator` 与 `zod` 做请求校验、`pino` 输出结构化日志、`ulid` 生成 ID。资料来源：[packages/api/package.json:1-20]()。
- `@shumai/core` 聚合了鉴权（`better-auth`）、图像处理（`sharp`）、加密（`tweetnacl`）、压缩解压（`adm-zip`、`extract-zip`）、顺序索引（`jittered-fractional-indexing`）、时间处理（`date-fns`）以及 YAML 解析（`yaml`）。资料来源：[packages/core/package.json:1-40]()。
- `@shumai/agent` 引入 `@google/genai`、`@anthropic-ai/sandbox-runtime` 与 `@earendil-works/pi-agent-core`/`pi-ai`，负责 AI 对话、工具注册与沙箱执行。资料来源：[packages/agent/package.json:1-25]()。
- `@shumai/transcode` 与 `@shumai/workflow-core` 通过 `@temporalio/{activity,workflow,worker,client}` 进行后台任务编排。资料来源：[packages/transcode/package.json:1-15]()、[packages/workflow-core/package.json:1-15]()。
- `@shumai/cli` 复用 `@shumai/api` 与 `@shumai/tableprinter`，并以 `hono` 与 `ulid` 作为底层工具。资料来源：[apps/cli/package.json:1-15]()。
- 数据层由 Prisma 管理，通过 `db:migrate`、`db:deploy`、`db:generate` 脚本运行迁移与客户端生成。资料来源：[package.json:10-25]()。

## Monorepo 工作区结构与运行时拓扑

各子包之间通过 `workspace:*` 协议相互引用。下图展示了主要的运行时进程与包依赖关系：

```mermaid
graph LR
  Web["apps/web<br/>@shumai/web-app"]
  CLI["apps/cli<br/>@shumai/cli"]
  AgentApp["apps/agent<br/>@shumai/agent-app"]
  TranscodeApp["apps/transcode<br/>@shumai/transcode-app"]

  subgraph Packages
    API["packages/api"]
    Core["packages/core"]
    DB["packages/db"]
    DTOs["packages/dtos"]
    WebUI["packages/webui"]
    Workflow["packages/workflow-core"]
    Agent["packages/agent"]
    Transcode["packages/transcode"]
    TP["packages/tableprinter"]
  end

  Web --> API
  Web --> WebUI
  Web --> Workflow
  Web --> Agent
  Web --> Transcode
  Web --> Core
  Web --> DB
  Web --> DTOs

  CLI --> API
  CLI --> Core
  CLI --> DTOs
  CLI --> TP

  AgentApp --> Agent
  AgentApp --> Core
  AgentApp --> Workflow

  TranscodeApp --> Transcode
  TranscodeApp --> Core
  TranscodeApp --> Workflow

  API --> Core
  API --> DB
  API --> DTOs
  Core --> DB
  Core --> DTOs
  Agent --> DB
  Agent --> DTOs
  Agent --> Core
  Transcode --> DB
  Transcode --> DTOs
  Transcode --> Core
  Workflow --> DB
  Workflow --> DTOs
  Workflow --> Core
```

从图中可以看出三类运行时进程：Web 服务面向浏览器与外部 API 调用方；后台 worker 由 Temporal 调度，可在容器中横向扩展；CLI 客户端通过 `SHUMAI_API_SERVER` 与 `SHUMAI_API_KEY` 与 API 通信。资料来源：[apps/cli/README.md:1-30]()、[apps/web/package.json:1-15]()、[apps/agent/package.json:1-10]()、[apps/transcode/package.json:1-10]()。

## 关键子系统设计

### API 层

`@shumai/api` 基于 Hono 构建，路由文件中通过 `authMiddleware` 在请求上下文注入用户对象，并以此驱动后续的服务调用。资料来源：[packages/api/src/project.test.ts:1-30]()。

权限模型由 `authzService.hasPermission` 配合 `Permission` 与 `ResourceType` 枚举实现，涵盖 Read、Edit、Admin 三档动作以及 Project、Asset 等资源类型。资料来源：[packages/api/src/versionStack.test.ts:1-30]()。

`@shumai/dtos` 是 API、Worker、CLI 共享的 Zod schema 与类型定义，避免在多个进程间重复维护校验逻辑。资料来源：[packages/dtos/package.json:1-10]()。

### 领域核心与基础设施

`@shumai/core` 是所有上层应用共用的业务服务层。它将鉴权、媒体处理、加密、压缩、顺序索引等横切能力封装为可复用的服务接口，避免在 API 与 Worker 中重复实现。资料来源：[packages/core/package.json:15-40]()。

CLI 入口位于 [apps/cli/src/index.ts](apps/cli/src/index.ts)，负责解析 `project ls`、`ls`、`mkdir`、`upload`、`create-version` 等子命令，其中后四项必须通过 `-p/--parent` 指定父目录或资产 ID。命令输出经过 `@shumai/tableprinter` 渲染为表格，提升终端可读性。资料来源：[apps/cli/src/index.ts:1-50]()、[packages/tableprinter/package.json:1-10]()。

### 工作流与后台任务

转码与 Agent 任务均通过 Temporal 编排。`@shumai/workflow-core` 提供共享的 Temporal 客户端与 worker 装配逻辑，使业务包（`@shumai/transcode` 与 `@shumai/agent`）只需专注于 activity 实现。`apps/agent/src/index.ts` 与 `apps/transcode/src/index.ts` 是两个独立的可执行入口，对应根 [package.json](package.json) 中的 `worker:agent` 与 `worker:transcode` 脚本。资料来源：[packages/workflow-core/package.json:1-15]()、[packages/transcode/package.json:1-15]()、[packages/agent/package.json:15-25]()。

## 部署、运维与故障排查

- **开发与构建**：根 [package.json](package.json) 提供 `dev`、`typecheck`、`lint`、`test`、`format`、`build` 等脚本，覆盖类型检查、Lint、Vitest 单元测试、Prettier 格式化与产物构建。
- **数据库**：`db:migrate`、`db:deploy`、`db:generate` 三条脚本分别对应开发迁移、生产部署与 Prisma Client 生成。资料来源：[package.json:10-25]()。
- **容器安全**：v0.1.1 在 Docker 入口脚本中加入了 root 权限降级逻辑，确保写入持久化数据卷时使用非特权用户。资料来源：[PR #151](https://github.com/shumaiOne/shumai/pull/151)。
- **常见失败模式**：若未先部署 Temporal 服务就启动 `worker:transcode` 或 `worker:agent`，后台任务将无法被调度；CLI 报错时需先确认 `SHUMAI_API_SERVER` 与 `SHUMAI_API_KEY` 已正确导出。资料来源：[apps/cli/README.md:10-25]()。

## See Also

- 内部 API 路由实现：[packages/api/src/](packages/api/src/)
- 工作流与 worker 实现：[packages/workflow-core/](packages/workflow-core/)、[apps/transcode/](apps/transcode/)、[apps/agent/](apps/agent/)
- CLI 使用方式与命令列表：[apps/cli/README.md](apps/cli/README.md)、[apps/cli/src/index.ts](apps/cli/src/index.ts)
- 版本发布记录：[GitHub Releases](https://github.com/shumaiOne/shumai/releases)

---

<a id='page-2'></a>

## 核心平台、数据模型与 API

### 相关页面

相关主题：[Shumai 概览与系统架构](#page-1), [AI Agent、工具与 Temporal 工作流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/shumaiOne/shumai/blob/main/README.md)
- [package.json](https://github.com/shumaiOne/shumai/blob/main/package.json)
- [packages/dtos/src/index.ts](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/index.ts)
- [packages/dtos/src/team.ts](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/team.ts)
- [packages/dtos/src/provider.ts](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/provider.ts)
- [packages/api/src/project.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/project.test.ts)
- [packages/api/src/metadata.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/metadata.test.ts)
- [packages/api/src/agent.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/agent.test.ts)
- [packages/core/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/core/package.json)
- [packages/api/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/api/package.json)
- [packages/agent/src/activities/agent.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/activities/agent.ts)
- [apps/cli/README.md](https://github.com/shumaiOne/shumai/blob/main/apps/cli/README.md)
</details>

# 核心平台、数据模型与 API

## 一、平台整体架构

Shumai 是一个面向创意协作场景的开源平台，提供资产存储、标注评论、安全共享、权限管理、分布式转码以及 AI Agent 等能力 [README.md:1-40](https://github.com/shumaiOne/shumai/blob/main/README.md)。代码以 monorepo 形式组织，使用 Bun 作为运行时与构建工具，并在根目录中通过 `workspaces` 字段统一管理 `packages/*` 与 `apps/*` [package.json:8-10](https://github.com/shumaiOne/shumai/blob/main/package.json)。仓库中定义了多个顶层脚本，例如 `dev`、`build`、`db:migrate`、`worker:agent` 与 `worker:transcode`，分别覆盖本地开发、生产构建、数据库迁移以及后台 Worker 启动等场景 [package.json:12-30](https://github.com/shumaiOne/shumai/blob/main/package.json)。

平台在逻辑上可以划分为三个层次：

- **数据与领域层**：`packages/db`（Prisma 持久化）、`packages/dtos`（Zod 校验的领域模型）。
- **核心服务层**：`packages/core`（资产、S3、鉴权等核心服务）以及基于 Hono 的 `packages/api`。
- **应用与 Worker 层**：`apps/web`（Web 入口）、`apps/cli`（命令行工具）、`apps/transcode`（转码 Worker）以及 `apps/agent`（Agent Worker）。

各包之间通过 `workspace:*` 协议互相依赖，例如 `packages/api` 依赖 `@shumai/core`、`@shumai/db`、`@shumai/dtos` [packages/api/package.json:10-15](https://github.com/shumaiOne/shumai/blob/main/packages/api/package.json)；`apps/transcode` 则依赖 `@shumai/transcode`、`@shumai/core` 和 `@shumai/workflow-core` [apps/transcode/package.json:9-14](https://github.com/shumaiOne/shumai/blob/main/apps/transcode/package.json)。`@shumai/core` 内部集成了 better-auth、sharp、adm-zip、hono、tweetnacl 等库，承担权限、图片处理、压缩、HTTP 服务等横切职责 [packages/core/package.json:9-25](https://github.com/shumaiOne/shumai/blob/main/packages/core/package.json)。

## 二、数据模型与 DTO 设计

`@shumai/dtos` 是整个平台共享契约的中心：所有 API 请求、响应与持久化对象都通过 Zod Schema 描述，并在前后端、CLI、Worker 之间复用 [packages/dtos/src/index.ts:1-20](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/index.ts)。该包统一导出了 `agent`、`ai`、`asset`、`auth`、`collection`、`folder`、`invite`、`metadata`、`notification`、`pagination`、`project`、`provider`、`s3`、`search`、`share`、`skill`、`team`、`upload`、`user-metadata`、`versionStack` 等模块，每个模块对应一个核心领域实体 [packages/dtos/src/index.ts:1-20](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/index.ts)。

以团队（Team）模型为例，`teamInfoSchema` 描述了 `id`、`name`、`rootFolder`、`updatedAt` 等字段，并通过 Zod 的 `infer` 直接生成 TS 类型，便于在 API 和数据库层共享同一个契约 [packages/dtos/src/team.ts:7-15](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/team.ts)。`getMeResponseSchema` 明确把用户角色枚举约束在 `owner`、`editor`、`reviewer`、`bot`、`unknown` 五种取值之内 [packages/dtos/src/team.ts:34-43](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/team.ts)。`paginationParamsSchema` 与 `paginationPageInfoSchema` 则提供统一的分页协议，被 `getUserTeamsRequestSchema`、`getUserTeamsResponseSchema` 复用，避免每个接口重复定义分页结构 [packages/dtos/src/team.ts:1-30](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/team.ts)。

模型提供方（Provider）部分，DTO 抽象出可序列化的 `providerModelConfigSchema`，包含推理开关、输入模态、上下文窗口、最大 Token 以及按输入/输出/缓存读写细分的费用结构 [packages/dtos/src/provider.ts:11-25](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/provider.ts)。`KNOWN_APIS` 枚举目前覆盖 `openai-completions`、`anthropic-messages`、`google-generative-ai`、`bedrock-converse-stream` 等主流大模型接入协议，平台可在不改动上层业务的前提下替换底层模型 [packages/dtos/src/provider.ts:3-13](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/provider.ts)。`providerConfigSchema` 使用 `z.string().url()` 校验 `baseUrl`，确保外部服务地址合法 [packages/dtos/src/provider.ts:27-40](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/provider.ts)。

## 三、API 层与权限控制

`@shumai/api` 基于 Hono 框架构建，通过 `@hono/zod-validator` 把 DTO Schema 翻译为运行时校验，配合 `pino` 输出结构化日志 [packages/api/package.json:12-19](https://github.com/shumaiOne/shumai/blob/main/packages/api/package.json)。从测试代码可见，API 在路由层统一挂载了 `authMiddleware` 把 `user` 写入 Hono 的 `Variables` 上下文，再由 `authzService` 执行 `hasPermission` 鉴权，随后委托给领域服务完成业务 [packages/api/src/project.test.ts:1-40](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/project.test.ts)。

以 `metadataRoute` 为例，调用方传入团队 ID 后，路由先读取当前用户，再调用 `authzService.hasPermission` 判断是否具备 `ResourceType` 上对应权限，最后委托给 `metadataService` 返回 `fields`、`readOnly`、`aiAutofill` 等结构 [packages/api/src/metadata.test.ts:1-30](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/metadata.test.ts)。`agentRoute` 测试中展示了创建与更新 Agent 的典型模式：`POST /teams/:teamId/agents` 校验 `name`、`type`、`providerId`、`modelId`、`thinkingLevel`、`systemPrompt`、`soul`、`skills` 字段，缺一即返回 400 [packages/api/src/agent.test.ts:1-30](https://github.com/shumaiOne/shumai/blob/main/packages/api/src/agent.test.ts)。

CLI 工具 `apps/cli` 直接复用 `packages/api` 的路由与 DTO，通过环境变量 `SHUMAI_API_SERVER` 与 `SHUMAI_API_KEY` 与服务端通信，命令包括 `project ls`、`folder ls`、`upload` 等 [apps/cli/README.md:1-60](https://github.com/shumaiOne/shumai/blob/main/apps/cli/README.md)。

## 四、后台 Worker 与执行流

除同步 API 外，平台通过 Temporal 调度两类长时间任务：转码与 Agent 推理。`packages/transcode` 与 `apps/transcode` 共同封装 `@temporalio/worker`、`@temporalio/workflow`、`@temporalio/activity`，把视频转码从 API 路径剥离到后台 [packages/transcode/package.json:9-17](https://github.com/shumaiOne/shumai/blob/main/packages/transcode/package.json)。

Agent Worker 端，核心执行流由 `executeAgentPrompt` 协调：当用户发起聊天或元数据自动填充请求时，Worker 先通过 `initializeAgentSessionActivity` 确保 Agent 用户在 Prisma 中存在并以 `type='agent'` 标识，再调用大模型并把工具调用结果回写数据库 [packages/agent/src/activities/agent.ts:1-60](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/activities/agent.ts)。自动填充（autofill_metadata）任务会把抽取结果以 JSON 形式回传到 Temporal 活动，由持久化层继续写入 `MetadataField` 表 [packages/agent/src/activities/agent.ts:1-40](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/activities/agent.ts)。

```mermaid
flowchart LR
    Client[Web / CLI] --> API[Hono API]
    API --> Core[core services]
    Core --> DB[(Prisma DB)]
    API --> Temporal[Temporal]
    Temporal --> Agent[Agent Worker]
    Temporal --> Transcode[Transcode Worker]
    Agent --> Provider[LLM Provider]
    Transcode --> S3[(S3 / 本地存储)]
    Core --> S3
```

## 五、近期变更

最新版本 v0.1.1 中，社区合入了 #151 提交：为 Docker 镜像增加了根用户入口脚本并在挂载数据卷时完成权限降级，从而避免容器内进程以 root 身份直接读写宿主目录 [README.md:1-40](https://github.com/shumaiOne/shumai/blob/main/README.md)。这一改动对所有使用 Docker Compose 部署的用户都会产生影响，建议在升级后重新确认数据卷挂载点的属主与权限。

## See Also

- [资产与 S3 存储](S3存储.md)
- [AI Agent 与工作流](AI-Agent-工作流.md)
- [权限与团队管理](权限与团队管理.md)

---

<a id='page-3'></a>

## AI Agent、工具与 Temporal 工作流

### 相关页面

相关主题：[核心平台、数据模型与 API](#page-2), [Web UI、CLI 与部署运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/agent/src/index.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/index.ts)
- [packages/agent/src/activities/agent.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/activities/agent.ts)
- [packages/agent/src/activities/agent.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/activities/agent.test.ts)
- [packages/agent/src/workflows/agent-chat-prompt-builder.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/workflows/agent-chat-prompt-builder.test.ts)
- [packages/agent/src/workflows/agent-chat.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/workflows/agent-chat.test.ts)
- [packages/agent/src/tools/create-file.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/tools/create-file.ts)
- [packages/agent/src/tools/create-version.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/tools/create-version.ts)
- [packages/agent/src/index.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/index.test.ts)
- [packages/dtos/src/index.ts](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/index.ts)
- [packages/dtos/src/provider.ts](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/provider.ts)
- [apps/agent/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/agent/package.json)
- [package.json](https://github.com/shumaiOne/shumai/blob/main/package.json)
- [README.md](https://github.com/shumaiOne/shumai/blob/main/README.md)
</details>

# AI Agent、工具与 Temporal 工作流

## 概述与设计目标

Shumai 是一个面向创意协作的开源平台，其 AI Agent 子系统旨在为项目工作区提供上下文感知的对话助手，并支持 AI 自动元数据填充、向量检索与脚本沙箱执行。Agent 的核心入口在 `packages/agent/src/index.ts` 中导出，通过 `createAgentSession` 创建可被 Temporal 工作流调用的会话实例，并依赖 `@earendil-works/pi-agent-core` 与 `SandboxManager` 协同完成模型调用、工具调度与安全隔离。资料来源：[packages/agent/src/index.ts:1-30]()。

整个 Agent 体系的设计目标在 `README.md` 中被概括为四项：协作式 AI 对话、可扩展的自定义技能与工具、隔离的沙箱执行环境，以及基于 Google Gemini 的 AI 元数据自动填充与语义检索。资料来源：[README.md:30-44]()。

## 核心架构

Agent 子系统采用「Temporal 工作流 + 活动函数 + 工具库」三层结构。Temporal 工作流负责编排长时任务与重试策略，活动函数承载具体的副作用调用（如会话初始化、评论创建、嵌入生成），工具库则通过 `AgentTool` 抽象暴露给模型调用。

```mermaid
flowchart LR
  User[用户评论/聊天] --> WF[agent-chat / agent-autofill 工作流]
  WF --> ACT[Activities: agent / ai]
  ACT --> Session[createAgentSession]
  Session --> Harness[AgentHarness + Model]
  Harness --> Tools[AgentTool 工具集]
  Tools -->|create_file| FS[云端文件系统]
  Tools -->|screenshot| SC[截图服务]
  Tools -->|sandboxed_bash| SB[SandboxManager]
  ACT --> Embed[generateEmbedding]
  WF --> Result[评论/元数据/嵌入结果]
```

工作流与活动均通过 `executeActivity` 与 `getActivities` 注入到测试环境，这一模式在 `packages/agent/src/workflows/agent-chat.test.ts` 中通过 `vi.mock('@shumai/workflow-core')` 显式验证。资料来源：[packages/agent/src/workflows/agent-chat.test.ts:1-30]()。

## Agent 会话与提示词构建

`createAgentSession` 在 `packages/agent/src/index.ts` 中接收 `teamId`、`agentId`、`providerName`、`modelId` 等参数，并使用 `DatabaseSessionStorage` 将对话历史持久化到 Prisma 数据库。系统提示词在 `packages/agent/src/activities/agent.ts` 中拼接：基础说明 + 平台行为规范 + `agent.soul` 人格定义 + 上下文指令。资料来源：[packages/agent/src/activities/agent.ts:30-100]()。

`AgentChatPromptBuilder` 是会话提示词的可组合构建器，支持 `withExplicitMention`、`withPathContext`、`withAssetDetails` 等链式调用，按资产类型（图片或视频）动态注入工具建议（例如图片资产触发 `analyze_image`，视频资产触发 `screenshot`）。该行为在 `packages/agent/src/workflows/agent-chat-prompt-builder.test.ts` 中通过单测明确锁定。资料来源：[packages/agent/src/workflows/agent-chat-prompt-builder.test.ts:1-30]()。

`initializeAgentSessionActivity` 会在数据库中补齐 `agent` 类型用户与 `Agent` 记录，确保 AI 在评论流中以独立身份出现。资料来源：[packages/agent/src/activities/agent.ts:130-180]()。

## Agent 工具系统

工具以 `AgentTool` 类型实现，统一通过 `Type.Object` 定义输入 schema。`packages/agent/src/index.ts` 中可见的工具包括：`analyze-image`、`screenshot`、`create-file`、`create-folder`、`create-version`、`list-assets`、`read-skill` 与 `sandboxed-bash`，全部通过 `executeAgentToolWorkflow` 桥接到 Temporal 工作流。资料来源：[packages/agent/src/index.ts:60-120]()。

| 工具 | 主要用途 | 关键依赖 |
|------|---------|---------|
| `create-file` / `create-version` | 上传本地文件至云端资产，生成 ULID 并通过 S3 写入 | `s3Service`、`detectSupportedMimeType` |
| `sandboxed-bash` | 在 `SandboxManager` 隔离环境中执行用户提交的脚本 | `@anthropic-ai/sandbox-runtime` |
| `analyze-image` / `screenshot` | 图像分析与视频帧截图 | 模型视觉能力 |
| `list-assets` / `read-skill` | 枚举资产与读取团队技能 | Prisma 读取 |

`create-file` 与 `create-version` 共享相同的 MIME 探测与回退表（`.png`、`image/png`、`.mov`、`video/quicktime` 等），表明二者源自同一上传管道但落地语义不同。资料来源：[packages/agent/src/tools/create-file.ts:1-50]()、资料来源：[packages/agent/src/tools/create-version.ts:1-50]()。沙箱安全模型在 `packages/agent/src/index.test.ts` 中通过 `SandboxAskCallback` 模拟验证。资料来源：[packages/agent/src/index.test.ts:1-40]()。

模型与供应商配置通过 Zod schema 序列化在 `packages/dtos/src/provider.ts` 中定义，支持 OpenAI、Anthropic、Google、Bedrock 等多种 API 形态，并通过 `providerModelConfigSchema` 描述 `contextWindow`、`maxTokens` 与成本字段。资料来源：[packages/dtos/src/provider.ts:1-40]()。

## Temporal 工作流编排

根 `package.json` 暴露两条 worker 启动脚本：`worker:agent` 与 `worker:transcode`，分别对应 `apps/agent/src/index.ts` 与 `apps/transcode/src/index.ts`，表明 Agent 与转码均为独立的 Temporal worker 进程。资料来源：[package.json:30-50]()。`apps/agent/package.json` 通过 `bin.shumai-agent` 暴露可执行入口，便于在容器中以最小权限启动。资料来源：[apps/agent/package.json:1-12]()。

工作流核心文件导出列表（`agent-autofill`、`agent-chat`、`agent-embedding`、`agent-tool-call`、`query-embedding-for-search`）显示 Agent 子系统同时承担对话、自动填充、嵌入生成、工具调用与语义检索五类长时任务。资料来源：[packages/agent/src/index.ts:1-30]()。`agentChatActivity` 与 `autofillAiActivity` 在 `packages/agent/src/activities/agent.test.ts` 中通过 mock `AgentHarness.prompt` 验证提示注入路径。资料来源：[packages/agent/src/activities/agent.test.ts:1-40]()。

需要注意的是，`agent.provider` 或 `agent.modelRef` 缺失时会以 `nonRetryable: true` 抛出 `ApplicationFailure`，避免 Temporal 对配置错误进行无限重试。资料来源：[packages/agent/src/activities/agent.ts:50-90]()。

## See Also

- 项目首页与功能总览：[README.md](https://github.com/shumaiOne/shumai/blob/main/README.md)
- DTO 与模型配置：[packages/dtos/src/index.ts](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/index.ts)
- 工作流测试基线：[packages/agent/src/workflows/agent-chat.test.ts](https://github.com/shumaiOne/shumai/blob/main/packages/agent/src/workflows/agent-chat.test.ts)
- Agent Worker 启动入口：[apps/agent/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/agent/package.json)
- 最新发布说明（v0.1.1，Docker 入口权限收敛）：[GitHub Releases](https://github.com/shumaiOne/shumai/releases)

---

<a id='page-4'></a>

## Web UI、CLI 与部署运维

### 相关页面

相关主题：[Shumai 概览与系统架构](#page-1), [AI Agent、工具与 Temporal 工作流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/shumaiOne/shumai/blob/main/README.md)
- [package.json](https://github.com/shumaiOne/shumai/blob/main/package.json)
- [apps/web/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/web/package.json)
- [apps/cli/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/cli/package.json)
- [apps/cli/README.md](https://github.com/shumaiOne/shumai/blob/main/apps/cli/README.md)
- [apps/transcode/package.json](https://github.com/shumaiOne/shumai/blob/main/apps/transcode/package.json)
- [packages/core/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/core/package.json)
- [packages/api/package.json](https://github.com/shumaiOne/shumai/blob/main/packages/api/package.json)
- [packages/dtos/src/index.ts](https://github.com/shumaiOne/shumai/blob/main/packages/dtos/src/index.ts)
</details>

# Web UI、CLI 与部署运维

本页聚焦 Shumai 在「用户交互层」与「运维层」的工程实现：Web 前端入口、命令行工具 (CLI) 的安装与用法，以及基于 Docker 的部署和后台 Worker 进程编排。

## 1. 仓库结构与工作区

Shumai 是一个使用 Bun 工作区（Bun workspaces）组织的 monorepo 项目。从根目录 `package.json` 可知，工作区声明覆盖了 `packages/*` 与 `apps/*` 两个目录，整个仓库统一启用 ESM（`"type": "module"`），便于跨包直接 import TypeScript 源码。 资料来源：[package.json:1-19]()

在 `packages/` 目录下集中放置可复用业务包：

- `@shumai/core`：核心业务能力、权限、存储与图像处理；依赖 `better-auth`、`sharp`、`adm-zip`、`hono` 等关键库。 资料来源：[packages/core/package.json:1-32]()
- `@shumai/api`：基于 Hono 的 HTTP API 路由层。 资料来源：[packages/api/package.json:1-19]()
- `@shumai/dtos`：使用 Zod 定义的统一 DTO，涵盖 `agent`、`asset`、`auth`、`collection`、`folder`、`metadata`、`project`、`share`、`skill`、`team` 等模块。 资料来源：[packages/dtos/src/index.ts:1-19]()

`apps/` 下则是可独立运行的入口应用：`web`、`cli`、`transcode` 等。

## 2. Web UI 应用

`apps/web` 是面向最终用户的前端入口应用，它自身只承担 HTTP 服务端引导与请求转发，业务逻辑由工作区包提供。其依赖列表显式声明了 `@shumai/api`、`@shumai/core`、`@shumai/db`、`@shumai/dtos`、`@shumai/workflow-core`、`@shumai/agent`、`@shumai/transcode`、`@shumai/webui` 等内部包。 资料来源：[apps/web/package.json:1-15]()

开发模式下，根脚本使用 Bun 的 `--hot` 热重载能力启动 Web 服务：

```bash
bun run dev   # 等价于 bun run --hot apps/web/src/index.ts
```

数据库相关脚本同样在根 `package.json` 中集中管理：`db:migrate`（开发态）、`db:deploy`（生产态）、`db:generate`（生成 Prisma Client）。 资料来源：[package.json:7-15]()

## 3. CLI 工具

`apps/cli` 是一个独立命令行工具，bin 字段声明入口名为 `shumai-cli`，通过内部 `@shumai/api`、`@shumai/core`、`@shumai/dtos` 与 `@shumai/tableprinter` 等工作区包与 Hono 客户端访问 API。 资料来源：[apps/cli/package.json:1-14]()

使用前必须设置两个环境变量完成认证： 资料来源：[apps/cli/README.md:13-21]()

- `SHUMAI_API_SERVER`：Shumai API 服务地址，例如 `http://localhost:3000`。
- `SHUMAI_API_KEY`：在 WebUI「Settings → Developer」选项卡下生成的开发者 Token。

CLI 支持的能力包括：列出项目（`project ls`）、列出目录内容、创建文件夹、上传文件或目录、以及为既有文件创建新版本。需要特别注意的是，因为 CLI 入口文件使用 `#!/usr/bin/env node` shebang，**Bun 用户**需要在命令前加 `bun run --bun` 前缀，否则会落到 Node.js 运行时。 资料来源：[apps/cli/README.md:26-30]()

## 4. 部署与运维

### 4.1 Docker Compose 快速部署

官方推荐使用 Docker Compose 作为最快上手方式：新建一个目录，下载 `docker-compose.yaml`，然后执行 `docker compose up -d` 即可。 资料来源：[README.md:42-49]()
该方式默认使用本地文件系统作为存储后端，避免了 S3 等外部依赖。

### 4.2 后台 Worker 进程

根 `package.json` 暴露了若干 Worker 启动脚本，按职责分离后台任务： 资料来源：[package.json:18-19]()

| 脚本 | 入口 | 职责 |
| --- | --- | --- |
| `worker:agent` | `apps/agent/src/index.ts` | Agent 对话、元数据自动填充等任务 |
| `worker:transcode` | `apps/transcode/src/index.ts` | 视频转码工作流消费 |

`apps/transcode` 作为独立可执行入口，依赖 `@shumai/transcode`、`@shumai/core`、`@shumai/workflow-core`，由此可推断转码任务由 Temporal 工作流驱动，并交由专门的 worker 进程消费。 资料来源：[apps/transcode/package.json:1-12]()

### 4.3 v0.1.1 关键运维变更（PR #151）

最新发布 v0.1.1 引入了一个与部署直接相关的改进：`feat(docker): add root entrypoint with privilege dropping for data volumes`（[#151](https://github.com/shumaiOne/shumai/pull/151)）。该 PR 在 Docker 入口脚本中以 root 身份完成数据卷挂载目录的初始化，再降权到非特权用户运行主进程，从而在保留容器启动便利性的同时提升了数据卷场景下的安全性。 资料来源：[README.md](https://github.com/shumaiOne/shumai/blob/main/README.md)

### 4.4 构建与发布

仓库根脚本还提供了完整的发布链路：`build`、`build-npm`、`publish`、`release:patch|minor|major` 等。其中 `prepublishOnly` 会在发布前依次执行 `build-npm`、`lint`、`typecheck`，作为发布前的质量门禁。 资料来源：[package.json:22-34]()

## 5. 小结

- **Web UI**：由 `apps/web` 启动，业务能力来自 `@shumai/webui`、`@shumai/api` 等工作区包；通过 `bun run dev` 进入开发模式。
- **CLI**：`apps/cli` 通过 Hono 客户端调用 REST API，需配置 `SHUMAI_API_SERVER` 与 `SHUMAI_API_KEY`；Bun 用户须使用 `bun run --bun` 前缀。
- **部署**：推荐 Docker Compose 一键拉起；后台按需启动 `worker:agent` 与 `worker:transcode`。
- **v0.1.1**：Docker 入口脚本增加了 root 初始化后降权的能力，强化了数据卷场景下的安全模型。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：shumaione/shumai

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=48642686 | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48642686 | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48642686 | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48642686 | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48642686 | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48642686 | release_recency=unknown

<!-- canonical_name: shumaione/shumai; human_manual_source: deepwiki_human_wiki -->