Compare commits

...
107 Commits
Author SHA1 Message Date
yiling 1050024fff Release v0.6.5 2026-11-07 19:55:05 +08:00
Yiling-J 403e209359 fix(webui): prevent duplicate name in sort/filter selectors and add toolbar quick actions (#523) 2026-11-07 18:35:49 +08:00
Yiling-J 0359733637 fix(share,file-browser): improve public share opening and multi-selection interactions (#522)
* fix(share,file-browser): improve public share opening and multi-selection interactions

* docs(changelog): merge release notes into single entry with Frame.io behavior change details

* fix(file-browser,share): prevent duplicate double-click navigation and fix stale range anchor
2026-11-07 11:18:47 +08:00
Yiling-J 2d2ea51668 docs(i18n): add Chinese documentation (#520) 2026-11-06 11:46:53 +08:00
yiling a71723d455 docs: add BETTER_AUTH_SECRET to docker-compose environment variables 2026-11-06 10:50:18 +08:00
yiling ab250a9f0a docs: clarify BETTER_AUTH_URL usage and scope 2026-11-06 10:36:22 +08:00
yiling 0c0b887b8d Release v0.6.4 2026-11-05 22:45:25 +08:00
Yiling-J f304caea00 fix(auth,web): gracefully degrade MCP on remote HTTP and cache production static assets (#519)
* fix: gracefully handle remote HTTP URLs for MCP and cache production static assets

* test(mcp): add remote http mcp integration test and fix static etag normalization and fallback error
2026-11-05 22:21:11 +08:00
Yiling-J 65e2ac1383 fix(security): improve access control and storage security (#518)
* fix(security): improve access control and storage security

* fix(security): set NODE_ENV in dockerfiles and sign local storage get urls with lru cache
2026-11-05 20:49:38 +08:00
Yiling-J 0dc0bbeb03 feat(file-browser): add context-aware copy submenu (#517)
* feat(file-browser): add context-aware copy submenu

* refactor(file-browser): address code review feedback for copy submenu

* fix(webui): align submenu trigger text and widen file context menu

* test(e2e): guard clipboard permissions in copy-menu spec for cross-browser support
2026-11-05 09:57:34 +08:00
Yiling-J 2ecbd49d18 feat(storage): add team auto-archive assets policy and background job (#516)
* feat(storage): add team auto-archive assets policy and background job

* fix(storage): address code review feedback on lock safety, starvation, and permissions

* docs: update readme and expand archive storage documentation with auto-archive details

* feat(storage): log info message on auto-archive job start and finish with archived count

* style(storage): stack age threshold and grace period vertically with updated grace period description

* fix(storage): only log auto-archive info messages when candidate assets are found to process
2026-11-04 14:40:44 +08:00
Yiling-J ba3c6dbfee feat(storage): add archive storage support for assets (#514)
* feat(storage): add archive storage support for assets

* fix(webui): show archive icon in front of file name in breadcrumb bar

* fix(webui): display archive icon in breadcrumbs when restoring

* refactor(transcode): simplify restore asset workflow to single while loop

* docs(configuration): add archive storage documentation and readme entries

* fix(webui): show archive icon in front of version names and prevent version card overflow

* fix(webui): fix overflow in manage versions dialog scroll area

* fix(webui): prevent manage versions dialog overflow on long file names

* docs(configuration): fix archive storage environment variables and defaults

* fix(storage): address code review findings for archive storage
2026-11-03 20:31:56 +08:00
yiling 49a2d7c380 Release v0.6.3 2026-11-01 19:52:23 +08:00
Yiling-J 6292f3c792 Revise changelog for upload and agent behavior changes
Updated changelog to reflect important behavior changes in file uploads and agent comments.
2026-11-01 17:19:08 +08:00
Yiling-J 20ad0abeba feat(upload): simplify upload file list display and add live speed & ETA (#513)
* feat(upload): simplify upload file list display and add live speed and ETA

* fix(upload): retain authoritative server search results and handle local failed upload state gracefully
2026-11-01 13:29:52 +08:00
Yiling-J fbff404b9b feat(file): optimize upload and transcoding status polling with batch api (#512)
* feat(file): optimize upload and transcoding status polling with batch api

* fix(webui): throttle search invalidation during upload and fix stuck 100% progress ring

* fix(webui): deduplicate upload search invalidation and stabilize batch polling
2026-10-31 20:11:31 +08:00
Yiling-J c2348b0e68 feat(upload): allow canceling in-progress upload tasks from sidebar (#511)
* feat(upload): allow canceling in-progress upload tasks from sidebar

* fix(upload): resolve concurrent confirmation race and store counter issues on cancellation

* fix(webui): immediately remove cancelled upload files from file list view
2026-10-31 16:39:54 +08:00
Yiling-J ff3d71ed3d feat(agent)!: suppress success comments for autofill and embedding agents (#510)
* feat(agent)!: suppress success comments for autofill and embedding agents

* fix(agent): ensure createCommentActivity runs on workflow cancellation
2026-10-31 12:02:30 +08:00
Yiling-J 77bd1422d8 feat(upload): state-based retry tracking and resilient gateway error handling (#509)
* feat(upload): state-based retry tracking and resilient gateway error handling

* fix(upload): check non-retryable statuses before offline state in isNetworkIssue
2026-10-31 10:37:35 +08:00
Yiling-J 9529c63c0a feat(upload): add 12-hour upload expiration and continuous backoff retry (#508)
* feat(upload): add 12-hour upload expiration and continuous backoff retry

* fix(upload): clamp jittered backoff delay to maxDelayMs and update presign JSDoc
2026-10-30 16:06:34 +08:00
Yiling-J 3b00a42a89 fix(webui): show clear toast when upload fails due to localhost s3 endpoint (#507)
* fix(webui): show clear toast when upload fails due to localhost s3 endpoint

* fix(webui): center empty state in file browser list area
2026-10-30 14:16:34 +08:00
yiling f0bdccf713 Release v0.6.2 2026-10-29 20:29:50 +08:00
yiling 5b7fc04b02 docs: document MCP OAuth support and simplify unreleased changelog 2026-10-29 17:52:45 +08:00
Yiling-J 687b5a79d8 fix(core): strip trailing slashes when normalizing auth and MCP resource URLs (#506)
* fix(core): strip trailing slashes when normalizing auth and MCP resource URLs

* docs: document BETTER_AUTH_URL in README and quickstart guides

* docs: prioritize AWS_ENDPOINT_URL_S3 and clarify applicability to local storage

* docs: refine AWS_ENDPOINT_URL_S3 guidance for local storage deployments
2026-10-29 17:24:31 +08:00
Yiling-J baf30730af feat(mcp): add OAuth 2.1 support (#505)
* feat(mcp): add OAuth 2.1 support with dynamic client registration

* feat(api): alias bare oauth-authorization-server discovery endpoint

* fix(auth): preserve user session on OAuth sign-in redirect to consent
2026-10-29 15:39:37 +08:00
yiling 96539207d0 update readme 2026-10-28 11:41:28 +08:00
yiling 43f95a2fa2 update cn compose 2026-10-28 11:38:07 +08:00
yiling 0f92a5377f update readme 2026-10-28 10:30:13 +08:00
Yiling-J 4e3e17a547 docs: simplify AGENTS.md developer guide (#501) 2026-10-27 15:26:42 +08:00
Yiling-J b3cae4f2b0 feat: move MCP to /mcp and add teammate operations (#500)
* feat(operations): move MCP to /mcp and add search, comment, metadata, version, and upload operations

- Serve the MCP server at /mcp instead of /api/mcp
- Add search_assets, copy_assets, get_folder_instructions, list_comments,
  create_comment, resolve_comment, list_metadata_fields,
  update_asset_metadata, create_version_stack, list_versions, and
  remove_version on the agent, MCP, and CLI
- Add create_file and create_version (agent, MCP) with Creation Context
  metadata, and complete_upload (MCP) for presigned two-step uploads
- Replace the native agent create_file/create_version tools with
  Operation-backed ones
- Route the comment-complete, metadata, copy, version stack, and
  AGENTS.md read REST endpoints through their Operations

* docs(readme): add built-in MCP server and CLI to features list
2026-10-27 14:37:26 +08:00
Yiling-J 50fbd97953 feat: expose read_asset and download_asset on MCP and the CLI (#499)
* feat(asset-read): expose read_asset on MCP and the CLI

Enable the mcp and cli surfaces for read_asset and get_asset_render.

- MCP: add per-Operation tool extensions. The read presenter attaches up
  to 8 images (2 MB each) inline, lists image links, supports
  inlineImages: false, and tells the model to call get_asset_render when
  a render is pending. Storage keys are stripped from the result.
- CLI: generated commands can flatten object inputs into prefixed flags
  (cli.flatten) and omit fields (cli.omit); add per-command extensions.
  New `read` and `render` commands print image links, download them with
  --out, and support --no-wait with a printed `render <taskId>` hint.
- Round frame timestamps in labels to 3 decimals.

* fix(mcp): make tool input schemas portable to single-type dialects

Nullable inputs were emitted as `type: ["number", "null"]` (or a `null`
anyOf branch), which clients that map tool schemas onto an OpenAPI-style
subset (e.g. Gemini function declarations) may reject.

- Make read_asset's startPage, endPage, and degree optional instead of
  nullable.
- Move null handling into a shared dropNullOptionals helper in
  @shumai/operations that also strips nulls inside nested config
  objects. The agent uses it, and the MCP server applies it before the
  SDK validates arguments, so models that send null keep working.
- Test that no Operation input schema (and no listed MCP tool) uses a
  nullable type.

* feat(asset-download): share download_asset across agent, MCP and CLI

Turn the agent-only download_asset tool into an Operation on all three
surfaces.

- download_asset takes up to 50 file or version stack IDs and returns
  presigned links. proxy (default true) picks the web preview when there
  is one, as the agent always did; proxy: false returns the original.
  Folders are rejected. Read is checked on every ID before anything runs.
- Agent: an extension saves the files into the .pi sandbox and keeps the
  agent-only storage key mode (e.g. frames from read_asset). Agent tool
  extensions gain description, parameterOverrides and intercept.
- CLI: `shumai-cli download <assetId...> [--out <dir>] [--original]`
  streams files to disk without overwriting existing names.
- read_asset's unsupported-type error now names the right way to
  download on each surface (download_asset, or `shumai-cli download`).
- Add the Download Asset toggle to agent settings.
2026-10-27 08:09:11 +08:00
Yiling-J 155fb95a0e feat(asset-read): rewrite read_asset as a reader registry and Operations (#498)
Replace the monolithic agent read_asset tool with a reader registry in
@shumai/core/src/asset-read (model3d, image, video, document) behind a
shared pipeline that handles access checks, version stacks, annotations,
render tasks, and waiting.

- Add read_asset and get_asset_render Operations (agent surface only).
  Renders that outlast the caller's wait budget return "pending" with the
  workflow task ID; the read request is stored on the task payload so
  get_asset_render works across restarts and instances (requester only).
- Add workflowService.waitFor and presign expiry support.
- Keep agent output compatible via an agent tool extension (s3KeyOnly,
  image blocks, session image details); autofill keeps its team-scoped tool.
- Cap video frames at 20 per call; add the get_asset_render agent toggle.
2026-10-27 08:09:10 +08:00
Yiling-J e44938cb8f feat(cli): generate shumai-cli commands from Operations with commander (#496)
Rebuild the CLI on commander. Commands for every cli-surface Operation
(project ls, ls, mkdir, rename, move/mv, delete/rm) are generated from
@shumai/operations: positionals, options, choices, numeric parsing and
help text come from the Zod input schema. They call POST /api/ops/:name
with x-shumai-client: cli.

Existing invocations keep working. Adds --json, ls --type/--first/
--after, typo suggestions, and generated help. upload and create-version
stay hand-written. Drops the unused @shumai/core dependency.
2026-10-27 08:09:10 +08:00
Yiling-J 4d61786799 feat(mcp): serve Operations over MCP and a generic /api/ops endpoint (#495)
Add a stateless Streamable HTTP MCP server at /api/mcp that exposes every
mcp-surface Operation with its input/output schemas and annotations, and
POST /api/ops/:name for the CLI. Both require an API token (session
cookies are rejected), run Operations as the token's user, honor demo
read-only mode, and record via mcp/cli/api in audit logs.

Also make list_projects toggleable in agent settings and document MCP
client setup.
2026-10-27 08:09:09 +08:00
Yiling-J 76057ccd21 feat(operations): add shared Operation layer for agent capabilities (#494)
Introduce @shumai/operations (pure definitions: Zod schemas, metadata,
CLI hints) and @shumai/core/src/operations (implementOperation and the
runOperation pipeline: validate, authorize, prepare, execute, validate
output, audit).

Migrate list_assets, create_folder, rename_asset, move_assets and
delete_asset to Operations, and add list_projects. The agent now builds
these tools from the registry, and the folder create/rename, file
rename and reparent routes call the same Operations.

Audit logs gain a nullable via column recording the surface. A lint
rule keeps the Prisma client out of Operation implementations.
2026-10-27 08:09:09 +08:00
Yiling-J 47ee794ae4 fix(agent): enforce access checks in read_thread and before file uploads (#493)
read_thread returned any comment thread by ID. It now requires Read on
the thread's asset for the acting user, and confines system agents
without a user to their own team.

create_file and create_version uploaded to storage before checking Edit
permission, leaving orphaned objects on denied calls. The permission
check now runs first.
2026-10-26 11:14:37 +08:00
Yiling-J 22486b893b feat(api-token): store API tokens as SHA-256 hashes (#492)
New tokens are 32 random bytes with a shumai_ prefix and are returned
only once at creation. The list endpoint returns a 4-character hint
instead of the plaintext. A migration hashes existing tokens in place so
they keep authenticating.
2026-10-26 11:08:46 +08:00
yiling c2af7494ec Release v0.6.1 2026-10-24 13:21:50 +08:00
yiling b7d2748b00 docs(changelog): add bun 1.4.4 upgrade to unreleased changes 2026-10-24 12:02:22 +08:00
Yiling-J 3467c0d92b chore(docker): update Aliyun compose images and document transcode worker scaling in README_CN (#491) 2026-10-24 11:51:37 +08:00
Yiling-J 22fede0290 fix(webui): prevent clipping of long text overlay and date picker in cards (#490)
* fix(webui): prevent clipping of long text overlay and date picker in cards

* docs: update DeepWiki badge url in README and README_CN

* fix(webui): preserve expanded overlay height and textarea style in LongTextField

* fix(webui): add bottom padding to file list to prevent screen clipping of expanded fields

* fix(webui): expand directly into edit mode on single click for LongTextField

* fix(webui): prevent file selection when interacting with metadata fields in cards and list rows
2026-10-24 11:40:47 +08:00
Yiling-J d87fe43b0f feat(dashboard): add workflow tasks monitoring and stopping to team dashboard (#489)
* feat(dashboard): add workflow tasks monitoring and stopping to team dashboard

* fix(asset): retain workflow tasks on asset purge and mark active tasks as failed

* style(webui): add edge padding to audit logs and workflow tasks tables

* fix(workflow): atomically update asset status to failed when task is stopped

* fix(workflow): propagate cancellation errors, guard concurrent task stop, and localize UI

* docs(changelog): keep only added log for workflow tasks dashboard

* test(provider): mock upstream catalog api calls using saved fixtures

* feat(dashboard): show file name, size, and project name in workflow tasks list
2026-10-23 16:44:52 +08:00
Yiling-J 7a0ffca629 Add feedback invitation to README
Added a feedback section to encourage user engagement.
2026-10-22 20:39:56 +08:00
Yiling-J 5cf6d31794 chore(deps): upgrade bun to 1.4.4 and migrate to bun fmt (#488)
- Upgrade Bun to 1.4.4 across Dockerfiles, CI workflows, and release configurations.
- Update @types/bun and bun-types.
- Remove eslint-plugin-prettier and update format script to use native bun fmt.
- Configure .prettierignore to exclude packages/webui/public and minified files.
2026-10-22 20:25:54 +08:00
Yiling-J 0d5fe48a3a docs(docker): add guide for scaling transcoding workers horizontally (#486) 2026-10-21 12:45:09 +08:00
Yiling-J 19eed521ae fix(webui): prevent unwanted redirects to login on reset-password page (#487)
* fix(webui): allow reset-password route with token when stale auth exists

* fix(webui): prevent 401 redirect to login on reset-password page
2026-10-21 12:12:25 +08:00
yiling e05a23bcc2 Release v0.6.0 2026-10-20 20:02:34 +08:00
Yiling-J d957ab2339 fix(webui): fix loading skeleton layout mismatches and keep left carousel visible (#485)
* fix(webui): fix loading skeleton layout mismatches and keep left carousel visible

* fix(webui): update mobile file list skeleton to match card layout

* fix(webui): blur video poster before playback with instant cut on play

* docs: consolidate webui changelog entries into single line
2026-10-20 17:39:40 +08:00
Yiling-J 1fcd7245ea fix(transcode): ensure durable file exchange and crash recovery across workflow steps (#484)
* fix(transcode): ensure durable file exchange and crash recovery across workflow steps

* fix(transcode): recognize AWS SDK NoSuchKey by name and add workflow E2E recovery test
2026-10-20 11:29:22 +08:00
Yiling-J 176b7f0eab feat(workflow): migrate workflow engine from temporal to dbos (#481)
* feat(workflow): migrate workflow engine from temporal to dbos

Replace Temporal and LocalExecutor with DBOS Transact (@dbos-inc/dbos-sdk) as the unified workflow engine. Background tasks, media transcoding, and AI agent workflows now execute with durable steps and task queues directly against PostgreSQL, eliminating the need for an external Temporal cluster and separate polling executors.

* fix(workflow): submit tasks via DBOSClient to allow enqueueing from steps

Enqueuing workflows using DBOS.enqueueWorkflowWithOptions threw a
DBOSInvalidWorkflowTransitionError when triggered from within a running
step or activity (e.g. creating embedding or autofill tasks during
video transcoding).

Use DBOSClient to submit and cancel workflow tasks directly against the
system database, detaching execution from the ambient workflow/step
context.

* feat(web): support SHUMAI_WORKERS environment variable

* fix(workflow): ensure CLI tasks are enqueued to DBOS and run DBOS migrations in global setup

- Initialize workflows and wait for pending DBOS submissions in shumai regenerate-embeddings CLI
- Remove no-op submit bypass and enqueue tasks via DBOSClient in producer and CLI contexts
- Add DBOS migration runner in test global setup to avoid concurrent migration deadlocks across test forks
- Update changelog and add regression tests

* fix(workflow): ensure unique per-instance executor identity for worker replicas

- Derive unique per-instance DBOS executor IDs across worker replicas

- Support SHUMAI_WORKER_ID, DBOS__VMID, and POD_NAME (Kubernetes Downward API)

- Disambiguate multi-replica bare metal/container deployments with host, PID, and instance suffix

- Prevent startup recovery from re-enqueueing workflows actively executed by other live workers

- Add multi-instance startup recovery tests and update deployment documentation

* fix(workflow): only register listened queues and update concurrency on change

- Only register queues that the executor instance actively listens to

- Use always_update conflict resolution so environment variable changes take effect on restart

- Prevent dedicated workers from overwriting unmanaged queue concurrency configurations

- Add tests verifying concurrency updates and queue isolation across worker roles

* refactor(workflow): simplify activities to use defineStep and direct calls (#482)

* refactor(workflow): simplify activities to use defineStep and direct calls

- Wrap activities using defineStep from @shumai/workflow-core
- Remove obsolete getActivities, registerActivities, dynamic activity proxies, and workerQueue arguments
- Remove executor.ts and registry.ts, consolidating workflow registration into workflow.ts
- Call activities directly across transcode and agent workflows
- Update all corresponding workflow tests and developer guide documentation

* fix(workflow): properly detect DBOSWorkflowCancelledError in runOnCancel fallback

- DBOSWorkflowCancelledError in DBOS SDK does not set name, inheriting 'Error'
- Implement isDbosWorkflowCancelledError checking instanceof, constructor.name, and dbosErrorCode
- Update unit tests to verify real DBOS SDK cancellation error instances

* docs(workflow): update documentation and readme for dbos migration

- Rename docs/configuration/temporal.mdx to docs/configuration/distributed.mdx
- Document DBOS-based distributed worker architecture and task queues
- Remove obsolete docker-compose/temporal/
- Update environment variables documentation in docs/configuration/env-variables.mdx
- Update references in README.md, README_CN.md, docs/docs.json, and related guides

* feat(deploy): implement KEDA ScaledJob and scale-to-zero On-Demand transcoding (#483)

* feat(deploy): add shumai-transcode docker image and k8s autoscaling example with garage s3

* docs(k8s): document port-forwarding and in-cluster s3 domain mapping

* feat(storage): support public s3 endpoint for browser uploads and update k8s example

* fix(k8s): configure s3 bucket cors rules in garage initialization

* fix(k8s): increase transcode worker memory limit to 4Gi for 4K video encoding

* feat(deploy): add AWS EKS deployment with Graviton3 Spot nodegroups and autoscaling

* docs(deploy): redesign EKS documentation, rename k8s to eks, and add scalable deployment feature

* docs: rephrase DBOS feature bullet to Durable Workflows via DBOS

* docs(eks): upgrade default instances to Graviton5 c9g.large and c9g.xlarge

* feat(eks): use On-Demand for general nodegroup and add spot capacity diversification

* docs(eks): fix Architecture diagram to locate all transcode worker pods in Transcode Compute Pool

* feat(deploy): implement KEDA ScaledJob and scale-to-zero On-Demand transcoding

* feat(transcode): support idle-timeout auto-drain for KEDA scaled jobs

* fix(deploy): fix EKS deployment manifests and documentation based on cluster verification
2026-10-19 15:35:08 +08:00
yiling f7ed3bafdf Release v0.5.3 2026-10-16 22:50:47 +08:00
Yiling-J 9f76e61e23 Add documentation for LiteRT-LM Embedding Server setup
Updated documentation for LiteRT-LM Embedding Server setup and other features.
2026-10-16 22:42:07 +08:00
Yiling-J 7c297895e5 feat(embedding): add compose tiers, docs, and regenerate-embeddings CLI (#480)
* feat(embedding): update compose tiers, docs, and add regenerate-embeddings CLI

- Add Lite, Embedding, and Full Docker Compose configurations (and Aliyun mirrors)
- Set CONCURRENCY_AGENT to 1 for compose files containing embedding-server
- Update README and README_CN with compose options, recommended RAM, and semantic search links
- Add LiteRT-LM Embedding Server setup guide in docs/using-shumai/embedding-server.mdx
- Add shumai regenerate-embeddings CLI command and EmbeddingService to regenerate embeddings across teams
- Add comprehensive test coverage for EmbeddingService

* fix(docker): remove basic auth for turntable-renderer in full compose

* fix(agent): lock and disable embedding agent when ENABLE_EMBEDDING_AGENT is false

Ensure that when ENABLE_EMBEDDING_AGENT is set to 'false', existing embedding agents are automatically disabled on startup, marked as read-only, and blocked from manual API modifications or creations. Additionally guard background task creation and semantic search when the environment variable disables embedding agents.

* test(upload): remove flaky status assertion on workflow tasks
2026-10-16 21:20:25 +08:00
Yiling-J 0f318b4050 feat(search): render results in responsive card grid with sprite preview and new-tab navigation (#479)
* feat(search): render results in responsive card grid with sprite preview and new-tab navigation

* fix(search): align semantic matched duration badge style with standard duration badge

* fix(webui): use pointer cursor instead of crosshair cursor for sprite scrubber on hover
2026-10-16 10:42:32 +08:00
Yiling-J 1a46f63160 fix(agent): adaptively set video embedding frame count based on aspect ratio (#477)
* fix(agent): adaptively set video embedding frame count based on aspect ratio

Adjust sampled video frame counts between 15 and 14 based on the video's aspect ratio. Standard aspect ratios (1:1, 4:3, 3:4, 16:9, 9:16, 21:9) stay within the 2048 token signature bucket when using 15 frames, while non-standard or custom aspect ratios use 14 frames to guarantee that sequence length never exceeds 2048 tokens, preventing out-of-memory errors on the embedding server.

* feat(agent): persist video chunk embeddings incrementally and resume on retry (#478)
2026-10-16 08:36:51 +08:00
Yiling-J 6cc90bf973 feat(search): generate query embeddings directly for semantic search (#476)
* feat(search): generate query embeddings directly for semantic search

* fix(search): resolve embedding provider from env, redact query logs, and preserve case in cache
2026-10-15 20:49:45 +08:00
Yiling-J b7271777e0 feat(agent): support gemma-embedding-2-openai provider (#475)
* feat(agent): support gemma-embedding-2-openai provider

Add support for local LiteRT-LM Gemma Embedding 2 provider with 768-dimensional vector embeddings, environment-configured read-only embedding agents, 16-frame uniform sampling for video chunks, and automatic WebP-to-JPEG conversion.

* refactor(agent): remove unused legacy generateEmbeddingActivity

* chore(agent): align sharp version to 0.35.4

* refactor(agent): rename embedding server env to GEMMA_EMBEDDING_OPENAI_BASE_URL

* refactor(agent,transcode): use native Bun.Archive for video chunk frames

* fix(transcode,agent): populate buffer entries in Bun.Archive and validate frame sizes
2026-10-15 15:49:24 +08:00
yiling c302c162a0 Release v0.5.2 2026-10-13 21:03:51 +08:00
Yiling-J 432be04a96 Update CHANGELOG to remove fixed and changed entries
Removed fixed and changed entries related to 3D visual markup and settings adjustments.
2026-10-13 20:18:03 +08:00
yiling 6c95d14fb3 fix(webui): reverse 3D sprite scrubbing and remove container volumes from turntable doc 2026-10-13 16:49:42 +08:00
Yiling-J 3263580e89 fix(webui): clear markup annotations when rotating 3d model (#474) 2026-10-13 15:21:12 +08:00
yiling f3da916905 fix(asset): remove unbundled GLTF format from supported 3D models 2026-10-13 11:38:25 +08:00
Yiling-J fe8d404a44 feat(agent): support 3D degree comments, markup annotations, and config3d in read_asset (#473)
* feat(agent): support AI embedding, autofill, and read_asset for 3D assets

* feat(agent): support 3D degree comments, markup annotations, and config3d in read_asset

* fix(agent): resolve 3D session annotations to turntable degree frame time
2026-10-13 00:03:21 +08:00
Yiling-J 0f9d213b1d docs: update 3D asset and Gotenberg integration guides (#472) 2026-10-12 16:55:20 +08:00
Yiling-J f952318b34 feat(team): add integrations settings with turntable and gotenberg (#471)
* feat(team): add integrations settings with turntable and gotenberg

* fix(upload): pass teamId to gotenberg availability check during upload preflight
2026-10-12 15:38:15 +08:00
Yiling-J 43a2eced75 feat(transcode): add 3D asset support and turntable viewer (#454)
* feat(transcode): add 3D asset support and turntable viewer

* perf(turntable): stream file via Bun.file and increase upload timeout

* feat(turntable): increase upload timeout to 15m to support 5GB uploads

* fix(webui): align 3D model viewer layout and full-width control bar with video viewer

* feat(webui): unify 3D viewer bottom bar and redesign cyclic ruler slider

- Place RulerSlider in single row with playback and zoom controls, centered with max 320px width
- Flank RulerSlider with minus and plus buttons to step angle by 15°
- Redesign RulerSlider with fixed center indicator and moving cyclic track with continuous 360° wrapping
- Render major ticks longer at 60° intervals without numeric text labels on track
- Display floating degree tooltip above center indicator only during dragging

* fix(webui): prevent RulerSlider from collapsing to 0px width in control bar

- Use flex layout with flex-1 on left and right clusters to preserve center cluster width
- Enforce min-w-[140px] and w-full on RulerSlider
- Fix tooltip positioning and remove outer overflow-hidden

* feat(webui): snap RulerSlider track directly to discrete 15° ticks during drag

* fix(webui): prevent ruler snap-back caused by floating point second truncation

- Use Math.round instead of Math.floor in secondToDegree to avoid 0.999996 dropping to previous frame
- Ensure final dragDegree is committed on pointer up

* fix(webui): fix arrow key frame rounding and duplicate event bubbling

- Use Math.round instead of Math.floor for keyboard arrow frame navigation in ModelViewer
- Add e.stopPropagation() to RulerSlider keyboard events to prevent duplicate bubbling to window listener

* feat(webui): redesign RulerSlider with encapsulated step buttons and capsule pill track

* feat(webui): make RulerSlider responsive on mobile and remove bottom bar reset button

* fix(webui): load 3d video directly without poster and invert drag rotation to counterclockwise

* fix(webui): fix 3d asset viewer frame seeking and drag jitter

* feat(transcode): show 3D asset poster preview immediately after render start

* fix(viewer): synchronize 3D turntable playback via frame callback to prevent skipped degrees

* fix(viewer): handle touchpad zoom gestures and prevent page zoom in 3D viewer

* fix(viewer): eliminate 3D model rotation jitter at 345 degrees

* fix(share): watermark 3D asset turntable video on share links

* fix(share): preserve video transcode resolution on watermarked share links

* fix(viewer): download original 3D model file instead of rendered turntable MP4
2026-10-11 21:32:28 +08:00
Christopher BuzickyandBristopher e894457275 fix(transcode): apply EXIF orientation to non-RAW image transcodes and reported size (#461)
* fix(transcode): apply EXIF orientation to image transcodes and reported size

Cameras and phones store portrait shots as landscape pixels plus an EXIF
orientation tag. sharp ignores the tag and the webp output drops it, so
thumbnails, previews, watermarked share-link images and annotated snapshots
came out sideways, and getImageInfo reported width and height swapped
(a 5152x7728 portrait recorded as 7728x5152).

RAW previews keep their existing handling: transcodeImage still rotates them
from the RAW container orientation and only auto-orients inputs without one,
so RAW and non-RAW images are never rotated twice.

- transcodeImage: autoOrient non-RAW input and size previews from the
  oriented dimensions.
- getImageInfo: report metadata.autoOrient dimensions for non-RAW images.
- compositeOverlayToWebpFile and overlayAnnotationsOnBuffer: autoOrient
  the original, and draw annotations in the displayed coordinate space.
- Tests: service tests that reproduce the bug and guard against double
  rotation of RAW, and a workflow e2e case with a real 600x400 JPEG tagged
  orientation 6 that must come out 400x600.

* refactor(transcode): share orientation helper and test all 8 EXIF orientations

Move the autoOrient decision and the displayed-size lookup into orientedSharpOptions and displayedDimensions so getImageInfo, transcodeImage, compositeOverlayToWebpFile and overlayAnnotationsOnBuffer share one rule: auto-orient unless a RAW container orientation was already applied. Behavior is unchanged.

Add transcode.orientation.test.ts, which runs real sharp over a quadrant-colored JPEG tagged with each of the 8 EXIF orientations and checks the reported and transcoded size plus the top-left and bottom-right corner colors.

* fix(transcode): never auto-orient dcraw output

The dcraw_emu fallback reports orientation undefined because LibRaw already rotates upright, so transcodeImage applied autoOrient to the TIFF and could rotate twice if it kept an Orientation tag. extractAndValidateRawPreview now flags the fallback result as orientationApplied and transcodeImage treats it as already oriented (autoOrient false). Tests cover both the dcraw path and an embedded preview with no container orientation.

---------

Co-authored-by: Bristopher <Bristopher@users.noreply.github.com>
2026-10-10 15:41:49 +08:00
4b1b64fe2b feat(kanban): link related assets to their file or folder (#453)
Related assets in the task edit dialog were plain rows with no way to
open them. Add an opt-in `linkable` prop to TaskRelatedAssets that turns
each row's thumbnail and name into a router Link to the asset in its
project (files -> /projects/$projectId/files/$fileId, folders ->
/projects/$projectId/folders/$folderId), falling back to the task's
project when the asset has none. The edit dialog opts in; the create
dialog does not, so a click cannot discard an unsaved draft.

Co-authored-by: Frederic De Decker <hello@trinity.video>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:14:36 +08:00
yiling f8beb195dd Release v0.5.1 2026-10-06 22:29:50 +08:00
yiling a97996cb59 docs(changelog): note clickable notification cards 2026-10-06 22:18:18 +08:00
jorgeandYiling-J f870ca9b49 feat(asset): link to assets on notification cards. (#451)
* feat(asset): link to assets on notification cards.

* Update packages/webui/components/notification-card.tsx

Co-authored-by: Yiling-J <njjyl723@gmail.com>

---------

Co-authored-by: Yiling-J <njjyl723@gmail.com>
2026-10-06 22:14:11 +08:00
Yiling-J 2e5ff281a8 feat(transcode): add hardware decoding support for nvenc, qsv, and rkmpp (#452)
* feat(transcode): add hardware decoding support for nvenc, qsv, and rkmpp

* refactor(transcode): eliminate redundant hardware decode gating and dead condition
2026-10-06 17:35:14 +08:00
yiling de8decf113 fix(ci): prevent tagging main on PR workflow_dispatch docker builds 2026-10-06 11:49:49 +08:00
Cameron HarrisandClaude Opus 5.5 dd57fb9ed2 feat(transcode): decode and scale on the GPU for hardware transcodes (VA-API) (#449)
* feat(transcode): decode and scale on the GPU for VA-API transcodes

When the selected encoder is h264_vaapi, decode with -hwaccel vaapi and
scale with scale_vaapi so frames stay in GPU memory, instead of decoding
and scaling on the CPU and hwupload-ing before the encoder. On a Haswell
iGPU this makes 4K proxy/HLS renditions 3-5x faster.

Fallback order: GPU decode + VA-API encode -> software decode + VA-API
encode (previous behavior) -> libx264. Watermark overlays, HDR sources
and rotated sources skip GPU decode: ffmpeg cannot auto-insert its
rotation filter on hardware frames, so rotated input would otherwise come
out sideways instead of failing. SHUMAI_VAAPI_HW_DECODE=false disables it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(transcode): document VA-API GPU decoding and SHUMAI_VAAPI_HW_DECODE

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(transcode): generic hardware decode config, stall watchdog, reuse probed rotation

Follow-ups from comparing with Immich and Jellyfin:

- Replace the VA-API-specific helpers with a per-encoder HW_DECODE_CONFIGS
  table (input args, output args, GPU scale filter) and build the MP4 and
  HLS input/filter graph in one shared method so the paths cannot drift.
  Only h264_vaapi has an entry; other backends can be added once tested on
  real hardware. The opt-out is now SHUMAI_HW_DECODE=false.
- Kill a GPU-decode attempt with SIGKILL when its output stops growing for
  SHUMAI_HW_DECODE_STALL_TIMEOUT (default 120s) and fall back, since some
  VA-API driver failures hang ffmpeg instead of exiting (immich#31933).
- Add -noautoscale on the GPU-decode path so a mid-stream decoder reinit
  (e.g. 1080 -> 1088) cannot auto-insert a software scaler into the GPU
  graph (jellyfin#17133).
- Pass the rotation already probed into MediaMetadata through the workflow
  and activities as sourceRotation; ffprobe only runs when it is missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 12:00:01 +08:00
Yiling-J 9a640632aa ci(release): allow manual Docker image build from external PR (#450) 2026-10-05 09:48:48 +08:00
yiling e61641d7ec fix(workflow): increase activity startToCloseTimeout to 120 minutes 2026-10-04 10:22:31 +08:00
Yiling-J 7ca8ba8b2a fix(transcode): resolve RAW transcoding hang in Docker deployments (#447) 2026-10-03 12:45:12 +08:00
Yiling-J 8805d5799a feat(transcode): add dcraw_emu fallback for RAW image preview generation (#446) 2026-10-03 11:03:31 +08:00
yiling 013c4a8156 Release v0.5.0 2026-10-02 20:28:37 +08:00
Yiling-J 20b5ebeefd fix(asset): mark asset as failed and display failure state in webui when transcoding fails (#445)
* fix(asset): mark asset as failed and display failure state in webui when transcoding fails

* fix(transcode): do not mark asset as failed if media processing already succeeded

* test(workflow): add e2e test for video transcode failure status transition

* fix(webui): update failed file card badge to top-right Transcoding Failed label with error tooltip
2026-10-02 20:09:32 +08:00
Yiling-J daa20aed20 fix(webui): add video loading state and poster placeholder (#444)
* fix(webui): add video loading state and poster placeholder

* fix(webui): prevent buffer progress events from canceling stall indicator
2026-10-02 16:19:49 +08:00
Yiling-J 3564d4d164 fix(transcode): avoid selecting attached picture streams for video transcoding (#443)
* fix(transcode): avoid selecting attached picture streams for video transcoding

Filter out attached picture streams (disposition.attached_pic) during video probing and stream selection, matching Immich's default and bitrate selection strategy. Forward explicit primary video and audio stream indices to FFmpeg pipelines to prevent picking embedded cover art or thumbnail streams.

* fix(transcode): skip poster and sprite generation for audio-only assets and add multi-stream e2e tests

* test(workflow): scope pixel format to h264 stream and use yuvj420p for mjpeg cover art
2026-10-02 13:51:17 +08:00
Yiling-J 206763e966 feat(auth): add demo user login button and update demo description (#442)
* feat(auth): add demo user login button and update description

* feat(auth): move demo hint below button and add discord link
2026-10-01 22:04:15 +08:00
Yiling-J 4e4da595a6 feat(settings): redesign video transcoding settings into dedicated cards and rename team AI settings (#441)
* feat(settings): redesign video transcoding settings into dedicated cards and rename team AI settings

* feat(settings): rename Video Strategy to MP4 Transcoding with sub-description
2026-10-01 21:19:25 +08:00
Yiling-J a21a0c9655 fix(settings): prevent deselecting last ladder and coalesce rapid toggles (#440) 2026-10-01 16:35:47 +08:00
Yiling-J fc7282581f fix(share): prevent unwatermarked HLS playback on public shares before transcode completion (#439) 2026-10-01 15:41:45 +08:00
Yiling-J e007054f47 feat(transcode): add multi-resolution strategy with configurable ladders and fallback (#438)
* feat(transcode): add multi-resolution strategy with configurable ladders and fallback

* feat(settings): show toast on settings update and add manual verification plan to PR template

* fix(webui): preserve video resolution and fix 480p label in download dropdowns

* fix(webui): display standard short-side resolution for vertical videos in seekbar

* fix(webui): fix portrait transcode resolution labeling and serialize settings toggles
2026-10-01 13:27:50 +08:00
Yiling-J a84da8678e feat(webui): switch from video.js to hls.js and native video player (#437)
* feat(webui): switch from video.js to hls.js and native video player

* fix(webui): prevent stale seek hijacking and guard native HLS compare mode
2026-09-30 20:23:44 +08:00
Yiling-J 123a8cb5f4 feat(transcode): add HLS live streaming support (#436)
* feat(transcode): add HLS live streaming support

* fix(hls): resolve version stacks for public HLS and add workflow E2E test
2026-09-30 16:31:40 +08:00
Yiling-J 5fe22ac52c feat(transcode): add initial camera RAW image support (#435)
- Add centralized RAW file extension set and detection helper for 23 common camera RAW formats
- Update getProxyType and EXTENSION_MIME_TYPES to route RAW formats into the image pipeline
- Add exiftool-vendored runtime dependency and mark as external in build-npm script
- Implement embedded JPEG extraction to temporary file with priority JpgFromRaw2 -> JpgFromRaw -> PreviewImage
- Read and apply EXIF orientation from RAW container to prevent rotation/mirroring issues
- Integrate into TranscodeService.getImageInfo and transcodeImage with proper temporary file cleanup
- Add hasUsablePreview guard in transcodeImageWorkflow to gracefully handle RAW files without embedded previews
- Add unit, service, workflow, and E2E tests for RAW processing
2026-09-29 21:09:27 +08:00
Yiling-J 11d21444cf fix(trash): prevent empty trash dialog from closing before API call completes (#434)
AlertDialogAction from Radix UI auto-closes the dialog on click.
Added e.preventDefault() so the dialog stays open and shows the
'Deleting...' loading state until the operation finishes.

Fixes both desktop and mobile file browsers.
2026-09-29 10:40:13 +08:00
yiling f2b0415580 Release v0.4.9 2026-09-28 20:17:50 +08:00
Yiling-J c9d0b476cd feat(transcode): fallback to software encoding when hardware transcode fails (#433) 2026-09-28 16:45:28 +08:00
yiling bf5ac566b6 refactor(notification): simplify email wording and remove redundant team references 2026-09-28 13:37:16 +08:00
Yiling-J af8f24aa95 docs(settings): add email notifications documentation to team settings (#432)
* docs(settings): add email notification documentation to team settings

* fix(notification): use correct webui route URLs for project and asset links in emails
2026-09-28 11:27:59 +08:00
Yiling-J d98f486c9d feat(notification): add email notification infrastructure, smtp configuration, and periodic background delivery job (#431)
* feat(notification): add email notification support and dedicated workflow

* feat(webui): add team email notification settings and test email dialog

* refactor(webui): remove redundant card header from email notification settings

* fix(notification): prevent sending notification emails to AI agents

* feat(notification): display project, avatar, upload time and resolve mention names in notification emails

* refactor(notification): remove uploadDebounceSeconds and naive workflow sleep

* refactor(notification): remove temporal notification workflow and keep email infrastructure

* fix(team): prevent leaking email notification settings and credentials in team settings

* feat(notification): add periodic background job for batched email notification delivery

* fix(notification): embed avatars and thumbnails as inline cid attachments
2026-09-28 09:58:59 +08:00
Yiling-J 94ea4c917a feat(transcode): add VA-API hardware acceleration support (#430)
* feat(transcode): add VA-API hardware acceleration support

* fix(docker): switch to jellyfin-ffmpeg 8.1.2-5 for VA-API support

* fix(transcode): probe hardware encoder usability to skip uninitialized drivers

* ci(release): add workflow_dispatch trigger with custom tag input

* fix(transcode): use 256x256 frame dimension for encoder usability probe

* feat(docker): add hwaccel transcoding compose presets matching immich

* docs: add hardware transcoding documentation and quickstart references

* feat(transcode): prioritize h264_vaapi before h264_qsv on Linux

* fix(docker): extend device permission loop to rkmpp and wsl accelerator nodes
2026-09-26 20:55:57 +08:00
Yiling-J 941bf0fd1b feat(transcode): smart poster frame selection and decoupled generation (#428)
* feat(transcode): smart poster frame selection and decoupled generation

* fix(transcode): detect MPEG-TS extension from URL pathname for signed remote sources
2026-09-25 16:37:16 +08:00
Yiling-J 59742dde78 feat(transcode): optimize video sprite generation with seek pool and compositing (#427)
* feat(transcode): optimize video sprite generation with seek pool and compositing

* fix(transcode): handle abort signal during and after sharp compositing
2026-09-25 15:06:15 +08:00
yiling 29cd5d807c test(scripts): find release by version in changelog integration test 2026-09-24 20:34:53 +08:00
yiling f6e27095a5 Release v0.4.8 2026-09-24 20:26:23 +08:00
Yiling-J 55637bc9a8 feat(transcode): optimize video proxy quality and fix videotoolbox first-frame blocking (#426)
- Fix first-frame macroblocking on VideoToolbox hardware acceleration by avoiding -maxrate/-bufsize which triggers Apple's DataRateLimits initial rate controller starvation, applying target -b:v instead.
- Optimize software encoding (libx264) quality by adjusting CRF from 26 to 23.
- Disable B-frames (-bf 0) for libx264 proxies to ensure zero-latency frame stepping (JKL) and scrubbing, matching Frame.io review proxy standards.
- Update unit tests to verify the new encoder configurations and bitrate calculation logic.
2026-09-24 17:16:02 +08:00
Yiling-J 0d6671c3e1 fix(webui): show play button and darken tint only before initial playback (#425)
* fix(webui): remove paused play button overlay and darken cover from video players

* fix(webui): show play button and darken tint only before initial playback
2026-09-24 15:19:46 +08:00
Yiling-J c3375ee935 feat(transcode): add HDR video proxy support and playback (#424)
* feat(transcode): add HDR output proxy support

* fix(transcode): auto-detect MoltenVK Vulkan ICD on macOS for libplacebo filters

* fix(transcode): split filter in generateSprite to ensure poster uses tone-mapped stream

* docs(changelog): update docs/changelog.mdx and ignore in prettier

* fix(transcode): respect video rotation metadata to preserve display aspect ratio

* fix(webui): render native video with hardware EDR acceleration instead of 2D canvas

* fix(webui): show HDR label on mobile video control bar

* fix(share): preserve hdr flag on watermarked video transcodes

* fix(webui): differentiate HDR download options in video player

* fix(transcode): handle Dolby Vision Profile 5 via standard HDR pipeline without libplacebo

* fix(transcode): prepend setparams filter to prevent zscale colorspace path error for DV P5

* refactor(transcode): simplify HDR proxies to always produce HDR without SDR setting
2026-09-24 14:32:47 +08:00
Yiling-J f579947770 feat(docs): add changelog section to mintlify documentation (#422) 2026-09-22 21:02:27 +08:00
Yiling-J 53c9485f10 fix(core): only manage PID files in daemon mode (#421) 2026-09-22 20:31:38 +08:00
Yiling-J 75bf9b3b88 fix(docker): stop publishing postgres port in compose files (#420)
The bundled PostgreSQL service published port 5432 on the host, which caused
docker compose up to fail when that port was already in use. A failed start
leaves the container without a network endpoint, so subsequent runs reuse the
broken container and the app cannot reach the database (Prisma P1001).

The app only needs the database inside the compose network, so the host port
mapping is unnecessary. Remove it from all local and temporal compose files.
2026-09-20 11:46:13 +08:00
674 changed files with 101093 additions and 17014 deletions
+4 -4
View File
@@ -24,7 +24,7 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.2
bun-version: 1.4.4
- name: Install dependencies
run: bun install
@@ -81,7 +81,7 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.2
bun-version: 1.4.4
- name: Install dependencies
run: bun install
@@ -126,7 +126,7 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.2
bun-version: 1.4.4
- name: Install dependencies
run: bun install
@@ -163,7 +163,7 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.2
bun-version: 1.4.4
- name: Install dependencies
run: bun install
+1 -1
View File
@@ -36,7 +36,7 @@ jobs:
- name: Setup Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.2
bun-version: 1.4.4
- name: Setup Node.js
uses: actions/setup-node@v6
+46 -1
View File
@@ -4,6 +4,16 @@ on:
push:
branches: ['main']
tags: ['v*']
workflow_dispatch:
inputs:
tag:
description: 'Docker image tag (e.g. feature-vaapi)'
required: false
type: string
pr:
description: 'Pull request number (e.g. 449)'
required: false
type: string
jobs:
build-and-push:
@@ -14,7 +24,10 @@ jobs:
steps:
- name: Checkout repository
id: checkout
uses: actions/checkout@v4
with:
ref: ${{ inputs.pr && format('refs/pull/{0}/head', inputs.pr) || github.ref }}
# Set up Docker Buildx
- name: Set up Docker Buildx
@@ -45,7 +58,11 @@ jobs:
crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai
tags: |
type=semver,pattern={{version}}
type=ref,event=branch
type=ref,event=branch,enable=${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !inputs.pr && !inputs.tag) }}
type=raw,value=pr-${{ inputs.pr }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.pr != '' && inputs.tag == '' }}
type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }}
labels: |
org.opencontainers.image.revision=${{ steps.checkout.outputs.commit }}
# Build and push Docker image
- name: Build and push Docker image
@@ -57,3 +74,31 @@ jobs:
provenance: false
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
# Extract metadata for Docker (Transcode Worker)
- name: Extract metadata for Docker (Transcode Worker)
id: meta-transcode
uses: docker/metadata-action@v5
with:
images: |
shumaione/shumai-transcode
crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai-transcode
tags: |
type=semver,pattern={{version}}
type=ref,event=branch,enable=${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !inputs.pr && !inputs.tag) }}
type=raw,value=pr-${{ inputs.pr }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.pr != '' && inputs.tag == '' }}
type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }}
labels: |
org.opencontainers.image.revision=${{ steps.checkout.outputs.commit }}
# Build and push Docker image (Transcode Worker)
- name: Build and push Docker image (Transcode Worker)
uses: docker/build-push-action@v7
with:
platforms: linux/amd64,linux/arm64
context: .
file: ./Dockerfile.transcode
push: true
provenance: false
tags: ${{ steps.meta-transcode.outputs.tags }}
labels: ${{ steps.meta-transcode.outputs.labels }}
+2
View File
@@ -25,3 +25,5 @@ code_quality.md
# Paraglide JS
packages/webui/paraglide
runner-package.json
+5 -1
View File
@@ -7,4 +7,8 @@ packages/core/src/generated
src/ui/components/ui
packages/webui/paraglide
*.md
**/*.md
**/*.md
docs/changelog.mdx
packages/webui/public
**/*.min.*
+74 -413
View File
@@ -10,14 +10,11 @@ Before starting any task, create and switch to a new feature branch:
git checkout -b <branch-name>
```
Complete the task on that branch.
After finishing the work and verifying that all checks pass:
1. Update `CHANGELOG.md` under `## [Unreleased]` for user-facing changes (see [Changelog Guidelines](#changelog-guidelines)).
2. Stage and commit your changes.
3. Push the branch to `origin`.
4. Open a pull request using the GitHub CLI.
2. Stage and commit your changes following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) (`<type>[optional scope]: <description>` in imperative mood, e.g., `feat(auth): add OAuth login support`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, and `!` or `BREAKING CHANGE:` for breaking changes).
3. Push the branch to `origin` and open a pull request using the GitHub CLI:
```bash
git add .
@@ -26,55 +23,15 @@ git push origin <branch-name>
gh pr create --title "<pull-request-title>" --body "<pull-request-body>"
```
---
## Commit Messages
We follow the Conventional Commits specification.
Commit messages MUST be formatted as:
```text
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
Example:
```text
feat(auth): add OAuth login support
```
The commit contains the following structural elements, to communicate intent to the consumers of your library:
1. `fix:` a commit of the type `fix` patches a bug in your codebase.
2. `feat:` a commit of the type `feat` introduces a new feature to the codebase.
3. `BREAKING CHANGE:` a footer or `!` after the type/scope introduces a breaking API change.
4. Additional types are allowed (for example: `docs:`, `refactor:`, `test:`, `chore:`).
Write commit messages in the imperative mood and keep descriptions concise and specific.
Reference:
https://www.conventionalcommits.org/en/v1.0.0/#summary
---
## Changelog Guidelines
We maintain `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
We maintain `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Before opening a pull request, add an entry under `## [Unreleased]` for any user-facing changes:
Before opening a pull request, add an entry under `## [Unreleased]` for any user-facing changes:
- **End-User Friendly**: Make entries easy to understand for end users. For new features, explain what they actually do in plain language without heavy technical jargon. For bug fixes, describe what the bug was in a friendly, relatable way rather than focusing on internal code mechanics, file paths, or private symbols.
- **End-User Friendly**: Write in plain language for end users without heavy technical jargon, internal file paths, or private symbols.
- **Formatting**: `- **<scope>**: <Description>` (e.g. `- **asset**: Fix an issue where moving a video to trash while it was still transcoding could cause it to lose its trashed status`).
- **No PR Numbers**: Do not include PR numbers or links; the release pipeline automatically appends the detailed PR list.
- **No PR Numbers**: Do not include PR numbers or links; the release pipeline appends them automatically.
- **Internal Changes**: Routine refactors, test additions, or internal chores without external behavior changes may omit changelog updates.
---
## Pull Request Template
```md
@@ -92,6 +49,13 @@ Briefly describe what this PR changes and why.
- Describe the checks or tests you ran.
- Include relevant outputs if applicable.
## Manual Verification Plan
- Provide concise instructions for manually verifying this change.
- Assume familiarity with the project and existing development workflow.
- Skip boilerplate steps (e.g. starting the app, logging in, opening common pages) unless they are part of the change.
- Focus on what needs to be verified, including scenarios, edge cases, and expected results.
## Notes
Add any additional context, caveats, or follow-up work.
@@ -99,7 +63,7 @@ Add any additional context, caveats, or follow-up work.
## Submission Rules
- **Strict Requirement**: A submission is considered complete **only** when there is a single final code state in which **all** of the following pass **simultaneously**:
- **Strict Requirement**: A submission is complete **only** when there is a single final code state in which **all** of the following pass **simultaneously** (do not submit intermediate states where some checks fail):
- `bun run lint`
- `bun run format`
- `bun run typecheck`
@@ -107,392 +71,89 @@ Add any additional context, caveats, or follow-up work.
- `bun run test:e2e:app`
- `bun run test:e2e:webui`
- `bun run test:e2e:workflow`
- **Backend Testing Mandate**: Every backend feature, service method, workflow, and activity MUST be accompanied by comprehensive tests. Logic-heavy code without corresponding test coverage is considered incomplete.
- Fixes must be iterated until **no check causes any other check to fail**.
- **Type Safety**: The use of explicit `any` is strictly forbidden and will result in lint errors. You should use `unknown` instead when the type is not known. If you absolutely must use `any` due to a limitation (e.g. interacting with an untyped 3rd party library), you must add an eslint-disable comment (e.g., `// eslint-disable-next-line @typescript-eslint/no-explicit-any`) and include a comment directly above it clearly explaining _why_ we cannot be type-safe here.
- Do **not** submit intermediate states where some checks pass and others fail, even temporarily.
- **Cleanup Requirement**: Remove all verification related files (scripts, screenshots, `verification/` folder) before submit.
## Backend Architecture
The backend is built with:
- **Runtime**: Bun
- **Framework**: Hono
- **ORM**: Prisma (with Pgvector18)
- **Database**: Pgvector18
- **Backend Testing Mandate**: Every backend feature, service method, workflow, and activity MUST have comprehensive tests.
- **Type Safety**: Explicit `any` is strictly forbidden. Use `unknown` when the type is unknown. If `any` is unavoidable (e.g., untyped 3rd-party library), add `// eslint-disable-next-line @typescript-eslint/no-explicit-any` with a comment directly above explaining why.
- **Cleanup Requirement**: Remove all temporary verification files, scripts, screenshots, and the `verification/` folder before submitting.
## Workspace Architecture
The project is a monorepo managed by **Bun Workspaces**. It follows a strictly decoupled architecture where each domain or layer is its own package:
The project is a Bun Workspaces monorepo (Bun runtime, Hono API, Prisma + Pgvector18 DB, React + Tailwind CSS + Shadcn UI frontend):
- **WebUI (`packages/webui`)**: React-based frontend.
- **API (`packages/api`)**: Hono-based HTTP entry point. Handles requests and calls Core services.
- **Core (`packages/core`)**: Business logic, services, and infrastructure utilities.
- **Database (`packages/db`)**: Prisma client, schema, and migrations.
- **DTOs (`packages/dtos`)**: Shared type definitions and Zod schemas used by both API and WebUI.
- **Workers**: Specialized packages for background task execution:
- `@shumai/workflow-core`: Common workflow engine logic.
- `@shumai/agent`: AI agent workflows and activities.
- `@shumai/transcode`: Media processing workflows and activities.
- **`packages/webui`**: React frontend (`bun run dev` runs on port 3000).
- **`packages/api`**: Hono HTTP entry point and MCP server.
- **`packages/core`**: Business logic, services, operations, and asset readers.
- **`packages/db`**: Prisma client, schema, and migrations.
- **`packages/dtos`**: Shared Zod schemas and TypeScript types (do not append `Dto` suffix to type names).
- **`packages/operations`**: Shared Operation definitions (`@shumai/operations`) used by agent tools, MCP, and `apps/cli`.
- **Workers**: `@shumai/workflow-core` (DBOS engine), `@shumai/agent` (AI agent workflows/activities), and `@shumai/transcode` (media workflows/activities).
### Layered Communication Rules
### Layered Communication & Code Patterns
1. **API Layer** calls **Core Layer**. Do not access the database directly in the API layer.
2. **Core Layer** calls **Database Layer** and other Core services.
3. **DTO Layer** is imported by all layers to ensure end-to-end type safety.
4. **No Direct DB Leak**: Do not return Prisma objects directly from the API; always map them to DTOs.
1. **API → Core → DB**: API routes (`packages/api/src/`) call Core services (`packages/core/src/`), which call `@shumai/db`. Never access `prisma` directly in the API layer, and never return raw Prisma objects from API routes (always map to DTOs).
2. **Services**: Define service logic as instance methods on a class and export a singleton instance (check existing services in `packages/core/src/`).
3. **Hono Routes**: Always chain `.get()` / `.post()` on a Hono instance using `zValidator` and export the chained route as default to preserve Hono RPC type inference (check `packages/api/src/`).
4. **Operations First**: If an Operation exists for an action, API routes must call it via `runOperation` instead of re-implementing permission checks and audit logging. UI-only routes keep calling services directly.
5. **Dependencies & Imports**:
- Declare runtime `dependencies` in each package's local `package.json` (`workspace:*` for internal packages). Keep root `package.json` strictly for shared `devDependencies` and scripts.
- Never edit `package.json` manually to add dependencies; run `bun add <package> --filter <workspace>` from the root without an explicit version.
- Use absolute workspace imports across packages (e.g., `@shumai/db`, `@shumai/core/src/...`). When adding a new package, add its path mappings to the root `tsconfig.json`.
## Dependency Management
## Operations & Asset Readers
We follow Bun's monorepo conventions for dependency management:
### Operations
1. **Self-Contained Packages**: Every workspace package MUST declare its own runtime `dependencies` in its local `package.json`. Do not rely on dependencies being available via the root.
2. **Shared DevDependencies**: Common development tools (e.g., `typescript`, `eslint`, `vitest`, `prettier`, `prisma`) MUST be declared in the root `package.json` to ensure version consistency across the workspace.
3. **Local DevDependencies**: Tools specific to a single package (e.g., `@vitejs/plugin-react` for `webui`) should be declared in that package's local `package.json`.
4. **Workspace Imports**: Use `workspace:*` for internal package dependencies.
5. **Clean Root**: The root `package.json` must not contain runtime `dependencies`. It is reserved for shared `devDependencies` and workspace-wide `scripts`.
6. **Adding Packages**: Never edit `package.json` manually to add new dependencies. Always use `bun add` (e.g., `bun add <package> --filter <workspace>`) from the root without specifying an explicit version, letting Bun resolve the correct version.
An **Operation** is defined once and exposed across built-in agent tools, the MCP server, and `shumai-cli`. Check existing definitions in `packages/operations/src/` and implementations in `packages/core/src/operations/`.
## TypeScript Configuration
- **Definition (`packages/operations/src/**`)**: Keep free of server dependencies (no `@shumai/core` or `@shumai/db`). Every Zod input/output field must have `.describe()`. Object input fields must be listed in `cli.flatten` or `cli.omit`.
- **Implementation (`packages/core/src/operations/**`)**: Use `implementOperation(definition, { authz, prepare?, execute, audit? })`.
- `authz` returns all required permissions (checked before any side effect).
- `execute` calls Core services only (**importing `prisma` in Operations is forbidden by lint**).
- `audit` resolves team/project from the affected asset, never trusting caller input.
- Outputs must be DTOs matching the output schema.
- **Register & Run**: Register in both `packages/operations/src/registry.ts` and `packages/core/src/operations/registry.ts`. Execute only via `runOperation(op, { userId, via, agentId? }, input)`.
- **Surface Extensions**: For surface-specific parameters or rendering, check `packages/agent/src/operation-extensions/`, `packages/api/src/mcp-extensions/`, and `apps/cli/src/operations/extensions/`.
We use a root-level `tsconfig.json` to manage path mappings for the entire workspace. This ensures that imports across packages resolve correctly during typechecking and in the IDE.
### Asset Readers
1. **Path Mappings**: All workspace packages MUST have an entry in the `paths` object in the root `tsconfig.json`.
```json
"paths": {
"@shumai/core": ["packages/core/src/index.ts"],
"@shumai/core/src/*": ["packages/core/src/*"]
}
```
2. **Package tsconfig**: Each package should have its own `tsconfig.json` that extends the root configuration and defines its specific `include`/`exclude` rules.
3. **Cross-Package Resolution**: When adding a new package, you MUST update the root `tsconfig.json` path mappings to ensure it can be imported by other packages.
`read_asset` is backed by readers in `packages/core/src/asset-read/readers/` registered in `packages/core/src/asset-read/registry.ts` (order matters: first matching reader wins). To add or modify a reader, check existing readers in `packages/core/src/asset-read/readers/` and option schemas in `packages/operations/src/asset/read-asset.ts`. Use `badRequest(...)` for invalid input and return storage keys in `ReadResult`.
### Service Layer Patterns
## Frontend Rules (`packages/webui`)
- **Instance Methods**: Define service logic as instance methods on a class, not static methods.
- **Singleton Export**: Export a singleton instance of the service class.
```typescript
export class MyService {
async doSomething() { ... }
}
export const myService = new MyService()
```
- **Usage**: Import and use the exported instance.
```typescript
import { myService } from '@shumai/core/src/services/myService'
await myService.doSomething()
```
- **System Colors**: Prefer semantic design tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, etc.) over hardcoded Tailwind colors for light/dark theme support.
- **Route Code-Splitting**: Split all routes into `[route].tsx` (route definition and loaders) and `[route].lazy.tsx` (UI component and heavy imports).
- **Radix / Shadcn UI**: Set `modal={false}` on `<DropdownMenu>` when triggering a `Dialog` or `AlertDialog` from inside it to prevent focus-trap UI freezes. Use `ScrollArea` (`@/ui/components/ui/scroll-area`) for scrollable containers.
- **Pagination & Infinite Scroll**: Use `useInfiniteQuery` + `react-intersection-observer` with default `limit: 20` and the API's `total` field. Backend list APIs use `paginateQuery` from `packages/core/src/pagination.ts` (default `limit: 20`).
- **Internationalization (i18n)**: Hardcoded UI text is strictly forbidden. Add `snake_case` keys to both `packages/webui/messages/en.json` and `packages/webui/messages/zh.json`, run `bun run i18n:compile` (or `bun run i18n:watch`), and import `m` from `@/ui/paraglide/messages.js`.
### Hono API Definitions
## Database & Prisma (`packages/db`)
- **Route Chaining**: Always define API routes using method chaining on a Hono instance. This ensures that the type definitions for inputs and outputs are correctly inferred and preserved in the exported type.
- **Export Pattern**: Export the chained route instance as the default export.
```typescript
const app = new Hono()
const route = app
.get('/', ...)
.post('/', ...)
export default route
```
- **Type Safety**: Use `zValidator` for request validation (query, json, form) to ensure full end-to-end type safety with the Hono RPC client.
- **Schema & Config**: Schema at `packages/db/prisma/schema.prisma`, config at `prisma.config.ts`, generated client at `packages/db/src/generated/prisma`.
- **ULIDs & Sorting**: All models (except key-value stores like `Setting`) must use `@default(ulid())`. Do not manually generate DB IDs in application code. Order all list queries by `orderBy: { id: 'desc' }` (do not sort by unindexed `createdAt`).
- **Strict JSON Typing**: Annotate `Json` columns with `/// [TypeName]` in `schema.prisma` and define the type under the global `PrismaJson` namespace in `packages/db/src/prisma-json-types.ts`. Use type guards/narrowing instead of `as any`.
- **Migrations**:
- Commands: `bun --bun run prisma migrate dev`, `bun --bun run prisma migrate deploy`, `bun --bun run prisma generate`.
- Never hand-write DDL migration files; always generate them via `prisma migrate dev` (use `--create-only` for custom data migration SQL).
- **Never run `prisma migrate reset --force`** automatically. If migrations are out of sync or require a reset, stop and ask the user.
## Frontend Architecture
## DBOS Workflows & Activities
The frontend is built with:
Check existing workflows and activities in `packages/agent/src/{workflows,activities}`, `packages/transcode/src/{workflows,activities}`, and `packages/workflow-core/src/`.
- **Runtime**: Bun (Bundler & Runner)
- **Framework**: React
- **Styling**: Tailwind CSS + Shadcn UI (Components)
### UI Rules
- **Prefer System Colors**: Always prefer using semantic system color design tokens (e.g., `bg-background`, `text-foreground`, `text-sidebar-primary`, `text-muted-foreground`, etc.) over hardcoded color utilities (e.g., `bg-blue-50`, `text-emerald-600`, `bg-emerald-500`). This ensures seamless compatibility with light and dark themes.
### Route Code-Splitting
To optimize initial bundle size, all routes must be code-split into `[route].tsx` (lightweight route definition and loaders) and `[route].lazy.tsx` (UI component and heavy imports).
### Development
- **Run Dev**: `bun run dev` (Runs on port 3000)
## Testing
We use **Vitest** for testing (via `bun run test`). **Do not use `bun test`** as it uses Bun's native test runner which is not compatible with this project's test suite.
### Bug Fixes
- **Mandatory Reproduction**: When fixing a backend bug, you MUST first write a test case that reproduces the bug (demonstrates the failure) before applying the fix. This ensures the bug is truly understood and prevents future regressions.
### Test Maintenance Rule
- **Do not delete tests** unless the feature or code being tested is permanently removed from the codebase.
- When refactoring code, you must also refactor the corresponding tests to ensure they pass with the new implementation.
- This ensures we maintain regression coverage and do not silently break features.
### Service Tests
- Located in `packages/core/src/**/*.test.ts`.
- For comprehensive testing against a real database instance, we use `Testcontainers` alongside a `PrismaTestingHelper` which wraps each test within an automatic PostgreSQL transaction rollback boundary.
- All service tests must use `setupTestDbHooks()` from `@shumai/db` to initialize the database boundaries for each test suite inside the `describe` block. This automatically registers `beforeEach` and `afterEach` hooks to manage transaction state.
- Import `prisma` from `@shumai/db` directly to interact with the database in tests. The testing helper automatically proxies it.
```typescript
import { describe, it, expect } from 'vitest'
import { prisma, setupTestDbHooks } from '@shumai/db'
import { teamService } from '@shumai/core/src/team/team'
describe('TeamService', () => {
setupTestDbHooks()
it('works with db', async () => {
const user = await prisma.user.create({
data: { name: 'Test User', password: 'pw' },
})
const team = await teamService.ensureDefaultTeam()
expect(team).toBeDefined()
expect(team.name).toBe('Default Team')
})
})
```
The `bunfig.toml` is configured to run `setup-tests.ts` automatically as a preload step. This initializes the `Testcontainers` PostgreSQL instance and applies migrations before the tests begin running.
### API Tests
- Located in `packages/api/src/**/*.test.ts`.
- Mock the Service layer using `vi.spyOn(service, 'method')` or `vi.mock('@shumai/core/src/team/team')`.
- Verify that the API calls the Service methods correctly.
```typescript
import { describe, it, expect, vi } from 'vitest'
import { teamService } from '@shumai/core/src/team/team'
import app from './team'
describe('Team API', () => {
it('calls service', async () => {
const mockEnsureDefaultTeam = vi
.spyOn(teamService, 'ensureDefaultTeam')
.mockResolvedValue({ id: '1', name: 'Default Team' } as any)
// ... test logic ...
expect(mockEnsureDefaultTeam).toHaveBeenCalled()
mockEnsureDefaultTeam.mockRestore()
})
})
```
### Workflow E2E Tests
- Located in `packages/e2e/workflow/**/*.test.ts`.
- Run via `bun run test:e2e:workflow` (which executes tests against both `local` and `temporal` executors dynamically).
- **Mandatory test coverage**: When creating or updating workflows or activities, you MUST create or update the corresponding E2E tests.
- **Mocking**: Mock ONLY AI API calls. Do not mock S3, databases, or media/transcode extraction services.
- Mock the AI response by spying on `AgentHarness.prototype.prompt`:
### Web App E2E Tests
- Located in `apps/web/e2e/**/*.spec.ts`, organized by domain under `tests/<domain>/` (e.g. `auth`, `project`).
- Run via `bun run test:e2e:app`.
- **Fixtures**: Use the `owner`, `project`, and `file` fixtures for setup — they seed data through API calls/DB (no slow UI setup). You can add more fixtures if necessary.
- **Documentation**: Every test case MUST be documented in [`apps/web/e2e/README.md`](apps/web/e2e/README.md). Add or update the corresponding entry in the README whenever you add, rename, or remove a spec.
## Prisma Configuration & Migrations
- Schema: `packages/db/prisma/schema.prisma`
- Generated Client: `packages/db/src/generated/prisma`
- Config: `prisma.config.ts` (Required for Prisma 7+)
### Strict JSON Typing
We use `prisma-json-types-generator` to enforce strict type-safety for Prisma `Json` columns, rather than typing them as generic `JsonValue`.
- **Defining Types**: In `packages/db/prisma/schema.prisma`, annotate the JSON column with a triple-slash comment specifying the type name from `packages/db/src/prisma-json-types.ts`:
```prisma
model WorkflowTask {
/// [WorkflowTaskPayload]
payload Json?
}
```
- **Declaring Types**: All typed JSON shapes must be defined in `packages/db/src/prisma-json-types.ts` under the global `PrismaJson` namespace:
```typescript
declare global {
namespace PrismaJson {
export type WorkflowTaskPayload = Record<string, unknown> | TaskSpec | AiTaskPayload
}
}
```
- **Usage**: When accessing these columns on the Prisma client (e.g. `task.payload`), the field will automatically be typed as the declared shape (e.g., `PrismaJson.WorkflowTaskPayload | null`).
- **Accessing Properties**: When working with union types or custom structures in the JSON payload, use proper narrowing or type guards instead of casting to `any`. Direct `as any` casting should be avoided.
### Migration Workflow
- Development: Use `bun --bun run prisma migrate dev` to create and apply migrations during development.
- Production: Use `bun --bun run prisma migrate deploy` to apply pending migrations in production environments.
- **No Manual DDL Creation**: Never hand-write **schema (DDL) migration** files or directories. Always generate them with Prisma CLI (`bun --bun run prisma migrate dev --create-only` to create a template, then edit it if needed, or `bun --bun run prisma migrate dev` to apply) so Prisma correctly tracks migration metadata and checksums.
- **Data Migrations Are Allowed**: Pure **data migration** SQL (no schema change) may be written by hand, but it MUST live inside a migration generated via `bun --bun run prisma migrate dev --create-only` so it is tracked and applied automatically.
- **No Automatic Dev DB Reset**: Do not run `prisma migrate reset --force` or commands that force-reset the database automatically. If migrations become out of sync or a reset is required, stop executing, report the situation to the user, and present suggested manual cleanup/reset steps for the user to execute.
### Commands
- Generate Client: `bun --bun run prisma generate`
- Apply Migrations (Dev): `bun --bun run prisma migrate dev`
- Deploy Migrations (Prod): `bun --bun run prisma migrate deploy`
## ID Generation & Sorting
- **ULID Default**: All models (except key-value stores like `Setting`) must use `@default(ulid())` for the `id` field in `schema.prisma`.
```prisma
model Example {
id String @id @default(ulid())
}
```
- **No Manual Assignment**: Do not manually generate or assign ULIDs in application code (e.g., `packages/core/src/*.ts`) for creating database records. Let Prisma handle it via the schema default.
- Exception: File names generated by `FileService` may still use `ulid()` internally, but this is separate from the database ID.
- **Sorting**: All list APIs must order results by `id` descending (`orderBy: { id: 'desc' }`) to ensure consistent, time-based sorting (since ULIDs are sortable). Do not sort by `createdAt` as it is not indexed.
## Infinite Scroll & Pagination
- **Frontend**: For paginated APIs (which contain `pageInfo` and `total` fields), the UI MUST use an auto infinite scroll style design using `useInfiniteQuery` from `@tanstack/react-query` and `react-intersection-observer`. Use the `total` count from the API response instead of counting the results locally.
- The default `limit` should be **20**.
- **Backend**:
- Most list APIs support cursor pagination using opaque tokens (via `hyrumtoken` logic) using the `paginateQuery` helper function.
- Pass `PaginationParams` containing `first` (limit) and `after` (cursor).
- The default `limit` should be **20**.
- Always use the `paginateQuery` helper function from `packages/core/src/pagination.ts` for consistent cursor pagination.
## Temporal Workflow & Activities
We use a custom workflow engine that supports both **Local** (polling-based) and **Temporal** (production-grade) execution.
### Architecture
1. **Workflows**: Orchestrate multiple activities. They must be deterministic and compatible with Temporal's V8 isolate. Defined in worker packages (e.g., `@shumai/agent/src/workflows`, `@shumai/transcode/src/workflows`).
2. **Activities**: Perform the actual work (DB updates, API calls, media processing). Grouped by domain in worker packages (e.g., `@shumai/agent/src/activities`, `@shumai/transcode/src/activities`).
3. **Executors**:
- `LocalExecutor` (in `@shumai/workflow-core`): Polls the database for `pending` tasks and executes them directly.
- `TemporalExecutor` (in `@shumai/workflow-core`): Submits tasks to a Temporal cluster.
4. **Automatic Submission**: New `WorkflowTask` records are automatically submitted to the `WorkflowService` via a Prisma Client Extension defined in `@shumai/db`.
### Dynamic Registration
To avoid circular dependencies, workflows and activities are dynamically registered onto the `LocalExecutor` registry at bootstrap time via initializer functions (e.g., `initAgentWorkflows()`, `initTranscodeWorkflows()`).
### Non-Retryable Error Handling
To prevent Temporal from indefinitely retrying fatal, expected business validation failures (e.g., missing records, invalid configurations, missing parameters), **never throw standard `Error` objects from workflow or activity logic.** Instead, throw a non-retryable `ApplicationFailure`.
**Mandatory Requirement**: You **MUST** set `nonRetryable: true` in the options object passed to `ApplicationFailure.create`. Standard errors or `ApplicationFailure` objects without `nonRetryable: true` will cause Temporal to retry the activity or workflow indefinitely.
- **Workflow Boundary**: In workflows, import `ApplicationFailure` from `@temporalio/workflow`:
```typescript
import { ApplicationFailure } from '@temporalio/workflow'
throw ApplicationFailure.create({ message: 'agentId missing in payload', nonRetryable: true })
```
- **Activity Boundary**: In activities, import `ApplicationFailure` from `@temporalio/activity`:
```typescript
import { ApplicationFailure } from '@temporalio/activity'
throw ApplicationFailure.create({
message: 'no autofill agent found for team',
nonRetryable: true,
})
```
### Temporal Workflow Patterns
- **Definition**: Define workflows as exported async functions.
```typescript
export async function myWorkflow(task: WorkflowTask): Promise<void> {
const { activityA, activityB } = getActivities()
await activityA({ ... })
await activityB({ ... })
}
```
- **Environment Compatibility**: Always use `getActivities()` from `@shumai/workflow-core` to ensure the code works in both Local and Temporal environments.
- **Activity Access**: Activities should be accessed via `getActivities()` within a workflow. Do not call services directly inside a workflow function to maintain Temporal compatibility.
- **Queue Redirection**: Production Temporal workers use worker-specific unique queues for data locality (e.g., local disk access) and consistent state.
- Every workflow MUST first call `getAgentWorkerQueueActivity` or `getTranscodeWorkerQueueActivity` via the shared domain queue (e.g., `TaskQueueAgent` or `TaskQueueTranscode`) to obtain the specific queue name for that worker instance.
- ALL subsequent activities (including shared DB activities like updating task status) MUST be executed on that specific discovered queue.
- The shared domain worker ONLY registers the queue discovery activities. All other activities (shared and domain-specific) are registered on the specific worker.
### Activity Patterns
- **Implementation**: Activities _can_ and _should_ call other services (e.g., `aiService`, `transcodeService`) or interact with the database directly. Database (Prisma) queries or updates are allowed in all activity types (e.g., agent or transcode) for simplicity.
## Import conventions
- When importing across workspace packages, always use absolute workspace imports (e.g. `import { prisma } from '@shumai/db'`, `import { teamService } from '@shumai/core/src/team/team'`).
- **DTO Naming**: Do not append the `Dto` suffix to types or interfaces (e.g. use `JoinRequest` instead of `JoinRequestDto`).
## Radix UI / Shadcn UI Patterns
- **Modal Overlays**: When triggering a dialog (e.g., `Dialog`, `AlertDialog`) from inside a `DropdownMenu`, you must set `modal={false}` on the `<DropdownMenu>` component. Failing to do so will cause the UI to freeze due to conflicting focus management between the two modal components.
- **Scrollable Content**: Always use the Shadcn `ScrollArea` component (`@/ui/components/ui/scroll-area`) for scrollable content containers to ensure consistent custom scrollbar UI across the application.
- **Patterns**: Workflows are exported async functions registered at bootstrap (`initAgentWorkflows`, `initTranscodeWorkflows`) and auto-enqueued when `WorkflowTask` records are created. Wrap activity functions with `defineStep` from `@shumai/workflow-core` (activities may call services or query `prisma` directly).
- **Non-Retryable Errors**: Never throw standard `Error` objects for fatal validation or business failures in workflows/activities. Always throw `ApplicationFailure.create({ message: '...', nonRetryable: true })` from `@shumai/workflow-core`.
- **Durable Step File Exchange**: Save intermediate files passed across steps to S3, fetch them in consuming steps via `ensureLocalMediaFile` (never assume local `/tmp` persists across steps), and clean up temporary S3 files in a `finally` block.
## Logging
We use **pino** for logging. Always use **structured logging** to ensure logs are easily searchable and machine-readable.
Use structured **pino** logging via `import { logger } from '@shumai/core/src/logger'`. Pass metadata object first and message string second: `logger.info({ userId, projectId }, 'Project deleted')`.
- **Import**: `import { logger } from '@shumai/core/src/logger'`
- **Usage**: Pass an object as the first argument containing the metadata, and a string as the second argument for the descriptive message.
```typescript
logger.info({ userId: user.id, projectId }, 'Project deleted successfully')
```
- **Levels**: Use appropriate levels: `debug`, `info`, `warn`, `error`.
## Testing
## Internationalization (i18n)
Use **Vitest** via `bun run test` (**never** use `bun test`).
All user-facing text in the WebUI (`packages/webui`) MUST be internationalized using **Paraglide JS**. Hardcoded text in UI components is strictly forbidden.
### Message Definition
1. Define your English message strings in [packages/webui/messages/en.json](packages/webui/messages/en.json).
2. Define the corresponding Chinese translation strings in [packages/webui/messages/zh.json](packages/webui/messages/zh.json).
3. Keys should use `snake_case`.
Example (`en.json`):
```json
{
"my_key": "My English Text"
}
```
### Compilation
When you add or update translation keys, you must compile them to regenerate the type-safe functions:
```bash
# Compile once (generates type-safe TS/JS functions on disk)
bun run i18n:compile
# Watch and recompile on change during development
bun run i18n:watch
```
### Usage in Components
Import the compiled message namespace `m` and call it as a function:
```typescript
import { m } from '@/ui/paraglide/messages.js'
export function MyComponent() {
return (
<div>
<h1>{m.my_key()}</h1>
</div>
)
}
```
Always use the absolute workspace alias path `@/ui/paraglide/messages.js` (or `runtime.js` for runtime features) when importing Paraglide outputs.
- **Bug Fixes**: Always write a test case that reproduces the bug (demonstrates failure) before applying a backend fix.
- **Test Maintenance**: Never delete tests unless the tested feature is permanently removed; update existing tests when refactoring.
- **Service & Operation Tests (`packages/core/src/**/*.test.ts`)**: Call `setupTestDbHooks()` from `@shumai/db` inside `describe` for per-test PostgreSQL transaction rollback, and use `prisma` from `@shumai/db`. Every Operation requires real-DB tests covering success, permission denial (no side effects), and audit entries.
- **API Tests (`packages/api/src/**/*.test.ts`)**: Mock Core services using `vi.spyOn` or `vi.mock`.
- **Workflow E2E Tests (`packages/e2e/workflow/**/*.test.ts`)**: Run via `bun run test:e2e:workflow`. Mandatory when adding/updating workflows or activities. Mock **only** AI API calls (spy on `AgentHarness.prototype.prompt`); do not mock S3, DB, or media/transcode services.
- **Web App E2E Tests (`apps/web/e2e/**/*.spec.ts`)**: Run via `bun run test:e2e:app`. Use `owner`, `project`, and `file` fixtures for setup, and document every added, renamed, or removed spec in `apps/web/e2e/README.md`.
+187
View File
@@ -12,6 +12,193 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Changed
## [0.6.5] - 2026-11-07
### Added
### Fixed
### Changed
- **file-browser**: ⚠️ **Behavior Change**: Align asset selection and click behavior with Frame.io: single-clicking file or folder cards on public share links always opens or enters the asset even when already selected, clicking an already-selected card in workspace file lists preserves multi-selection, checkboxes independently toggle individual items without clearing other selections, and Shift-click range selection is supported on public share links
## [0.6.4] - 2026-11-05
### Added
- **storage**: Add optional archive storage support (`local` folder/NAS or `s3` with configurable storage class and Glacier restore) allowing editors and owners to archive and restore original files while keeping previews, proxy streams, comments, and metadata available in main storage
- **storage**: Add team-level automatic asset archival based on age policies (creation time or last modified time) with configurable post-restore grace periods, an hourly background scanning worker, and a dedicated Storage settings page displaying read-only archive backend status and policy configurations
### Fixed
- **security**: ⚠️ Several security improvements and access control hardenings. Upgrading to this release is strongly recommended.
- **mcp**: Gracefully disable MCP OAuth 2.1 with an error log when deploying on remote HTTP IP addresses without breaking the main server or API token MCP access
- **web**: Add immutable cache headers and conditional 304 Not Modified support for production JavaScript and CSS chunks to prevent unnecessary refetches on page reload
### Changed
- **file-browser**: Replace the legacy combined "Copy name and download link" action with a context-aware Copy submenu in file browser context menus and card action dropdowns, enabling users to copy image, asset names, in-app links, download links, IDs, Markdown links and storage paths(team-owner only)
## [0.6.3] - 2026-11-01
### Added
- **upload**: Allow users to cancel running upload tasks directly from the upload tasks sidebar with a confirmation dialog, preserving already completed files while discarding incomplete assets
- **upload**: Improve upload resilience during network drops, device sleep, and transient gateway errors by adding state-based exponential backoff retries and extending upload link expiration to 12 hours
### Fixed
- **upload**: Display a clear diagnostic error toast when remote file uploads fail due to an unconfigured or localhost S3 storage endpoint
### Changed
- **upload**: ⚠️ **Important Behavior Change**: Uploading files now appear in their correct sorted position in the file list, following the current sort setting, instead of being pinned to the top and jumping into place after the upload finishes. Cards no longer move when an upload completes. Note that if you sort by name, an uploading file may land outside your current view. Local uploads also show remaining time and transfer speed (e.g. `8m left (390.88 KB/s)`), and other users viewing the folder see `[User] is uploading...`.
- **agent**: ⚠️ **Important Behavior Change**: Autofill and Embedding agents will no longer post completion comments when finishing successfully to prevent clutter in asset comment feeds. Comments are now only posted if a task encounters an error.
## [0.6.2] - 2026-10-29
### Added
* **mcp**: Add a built-in MCP server supporting OAuth 2.1 and API tokens, allowing external AI agents (such as Claude Code, Cursor, or Kiro) to browse projects, manage and upload files, inspect media contents (images, video frames, PDF pages, 3D models, and text), search assets, manage review comments, update metadata, and organize version stacks
* **cli**: Add `shumai-cli` commands to download files (`download`), view and render media contents (`read`, `render`), search and copy files (`search`, `copy`), manage review comments (`comment`), view and update metadata (`field ls`, `meta set`), organize version stacks (`version`), and view folder instructions (`instructions`)
* **agent**: The built-in agent can now list accessible projects, search files by name, meaning, or metadata, read and post review comments, update metadata, copy files, stack and unstack versions, and read folder instructions (`AGENTS.md`), with configurable permissions per agent
### Fixed
### Changed
## [0.6.1] - 2026-10-24
### Added
* **dashboard**: Add Workflow Tasks section to the Team Dashboard allowing team owners to monitor background workflow jobs, inspect execution payloads and outputs, and stop in-flight tasks
### Fixed
* **metadata**: Fix an issue where clicking to edit a metadata field on a card or list row inadvertently selected the file, and prevent expanded text overlays or date pickers from being clipped by container borders
### Changed
* **deps**: Upgrade Bun to 1.4.4
## [0.6.0] - 2026-10-20
### Added
* **deploy**: Add dedicated `shumaione/shumai-transcode` Docker image and a complete AWS EKS deployment example (`eks/`) featuring KEDA queue-driven autoscaling, idle-timeout auto-drain worker mode, and Scale-to-Zero On-Demand Graviton5 instances for media processing
* **storage**: Support configuring a separate public endpoint (`AWS_PUBLIC_ENDPOINT_URL_S3`) for browser-facing presigned URLs while preserving internal cluster endpoints for backend workers
### Fixed
* **transcode**: Fix an issue where PDF, 3D model, and image background transcode workflows could fail with missing temporary file errors if a worker restarted or recovered midway through processing
* **webui**: Improve file list and detail loading with matching skeleton layouts, a persistent sidebar carousel to eliminate layout shift, and smoothed video poster previews
### Changed
* **workflow**: Migrate the background workflow engine to DBOS, unifying all-in-one and dedicated worker deployments using the existing PostgreSQL database without requiring a separate Temporal cluster
## [0.5.3] - 2026-10-16
### Added
* **cli**: Add administrative `shumai regenerate-embeddings` command to regenerate multimodal vector embeddings for all existing media files across active teams
* **docker**: Provide three Docker Compose deployment tiers (Lite, with Embedding Server, and Full) with recommended memory specifications
* **agent**: Save video chunk embeddings incrementally to the database as each chunk finishes, preserving completed progress on failure and resuming from where it left off on retry
* **agent**: Add support for local LiteRT-LM Gemma Embedding 2 (`gemma-embedding-2-openai`) provider and environment-enforced read-only embedding agents with automatic 768-dimensional vector search indexing
### Fixed
### Changed
* **search**: Display search results in a responsive card grid with interactive hover video sprite scrubbing, semantic match chunk time range previews, and new-tab opening on click
* **search**: Significantly improve semantic search response times by generating query text embeddings directly with in-memory caching instead of dispatching background tasks
## [0.5.2] - 2026-10-13
### Added
* **3d asset**: Add support for 3D model files (.glb, .gltf, .obj, .fbx, .stl, .dae, .usd, .usda, .usdc, .usdz) with automated turntable video rendering, hover sprite scrubbing, and an interactive 3D turntable viewer featuring 360° ruler scrubbing and degree-based markup comments
* **kanban**: Related assets on a task are now clickable, taking you directly to that file or folder in its project
* **settings**: Add an Integrations section to Team Settings with dedicated configuration for Gotenberg Document Converter, supporting connection testing and environment variable override protection
### Fixed
* **transcode**: Fix an issue where portrait photos from cameras and phones appeared sideways in thumbnails, previews, watermarked share links and annotated snapshots, and were listed with their width and height swapped
### Changed
## [0.5.1] - 2026-10-06
### Added
* **notification**: Notification cards are now clickable, taking you directly to the relevant file
* **transcode**: Add hardware decoding and GPU scaling support for NVIDIA NVENC, Intel QuickSync Video (QSV), Rockchip (RKMPP), and VA-API (Intel and AMD GPUs), significantly speeding up video proxy and HLS rendition generation across supported platforms. Set `SHUMAI_HW_DECODE=false` to turn hardware decoding off
* **transcode**: Add `dcraw_emu` fallback to generate WebP previews for camera RAW files without embedded JPEG previews
### Fixed
### Changed
## [0.5.0] - 2026-10-02
### Added
* **transcode**: Add configurable target resolution ladders (480p, 720p, 1080p, 1440p, 2160p) for MP4 Multi Resolutions transcoding in team settings, with unified resolution matching and lowest-resolution fallback for both MP4 and HLS
* **transcode**: Add HLS live streaming with fMP4/CMAF adaptive bitrate ladders (480p, 720p, 1080p, 1440p, 2160p), configurable in Transcode Settings, with automatic quality switching, manual resolution selection in the video viewer, seamless rendition switching, and full watermarking support for shared links
* **transcode**: Add basic camera RAW image support for popular camera formats (including Sony ARW, Canon CR2/CR3, Nikon NEF, Adobe DNG, Fujifilm RAF, and Panasonic RW2), extracting high-quality embedded JPEG previews and automatically applying camera orientation for fast thumbnail and proxy generation
### Fixed
- **asset**: Fix an issue where media files remained stuck in a perpetual "Preparing..." state when transcoding failed, by displaying a clear failed status and error details in the file list and file viewer
* **transcode**: Fix an issue where videos or audio-only files containing attached cover art or picture streams could cause transcoding to fail during poster generation or select a single static image instead of the video
* **webui**: Fix inconsistent video resolution labels across download menus, mobile file headers, and the video player by correctly deriving resolutions from the video's short side, including portrait videos and 480p videos
* **trash**: Fix an issue where the "Empty Trash" confirmation dialog would close immediately instead of showing a loading state while files were being permanently deleted
### Changed
* **settings**: Redesign team Video Transcoding settings with dedicated cards for Transcode Policy, Hardware Acceleration, and FFmpeg Threads, clearly explaining MP4 and HLS playback vs download behavior and storage implications
* **settings**: Rename AI Settings group to Team AI Settings in settings navigation
## [0.4.9] - 2026-09-28
### Added
- **notification**: You can now receive notifications via email, with batched digest emails and configurable team-level SMTP settings
- **transcode**: Add VA-API hardware acceleration support for Linux hosts and Docker environments with Intel and AMD GPUs, featuring automatic DRI render node discovery, variable bitrate control, and structured transcoding observability logs
- **transcode**: Add automatic fallback to software transcoding (libx264) when hardware-accelerated video encoding encounters GPU resolution constraints or runtime driver errors
- **docker**: Add modular hardware-accelerated transcoding presets matching Immich's compose configuration via `hwaccel.transcoding.yaml` with support for NVENC, QuickSync, RKMPP, and VA-API
### Fixed
### Changed
- **transcode**: Improve video poster selection using intelligent scene detection and color variance filtering to automatically skip black frames, fade-ins, and blank intros in favor of representative video content
- **transcode**: Optimize video sprite generation for large and long videos using a concurrent fast-seek pool and image compositing, avoiding full-video decoding while preserving instant single-pass generation for short clips
## [0.4.8] - 2026-09-24
### Added
- **transcode**: Add HDR video proxy support: HDR videos automatically generate HDR video proxies and preview videos preserving HDR color characteristics, tone-mapped SDR thumbnails and posters, and automatic HDR player playback on supported displays with hardware EDR acceleration
- **docs**: Add a Changelog section to the documentation site so users can explore release notes and updates directly in Mintlify
### Fixed
- **webui**: Only show the center play button and darkened tint on initial video open before playback starts; once played, pausing or scrubbing back to start keeps the video canvas clean and unobstructed for review
- **transcode**: Fix an issue where videos with orientation or rotation metadata (such as smartphone vertical videos) were incorrectly displayed with stretched aspect ratios in the video player
- **cli**: Only manage and check PID files in daemon mode, preventing stale PID files, crash-loop conflicts, or spurious process checks during normal foreground and Docker execution
### Changed
- **transcode**: Improve video proxy visual quality and disable B-frames for smoother frame-by-frame seeking and scrubbing
## [0.4.7] - 2026-09-19
### Added
+25 -10
View File
@@ -1,6 +1,6 @@
#syntax=docker/dockerfile:1.7-labs
# Stage 1: Builder
FROM oven/bun:1.4.2 AS builder
FROM oven/bun:1.4.4 AS builder
WORKDIR /app
@@ -28,13 +28,11 @@ RUN bun run build.ts
RUN bun run scripts/extract-runtime-deps.ts
# Stage 2: Runner
FROM oven/bun:1.4.2 AS runner
FROM oven/bun:1.4.4 AS runner
# Install ffmpeg/ffprobe
COPY --from=mwader/static-ffmpeg:8.1 /ffmpeg /usr/local/bin/
COPY --from=mwader/static-ffmpeg:8.1 /ffprobe /usr/local/bin/
ENV NODE_ENV=production
# Install system dependencies for sandbox runtime and agent
# Install system dependencies and Jellyfin-FFmpeg (with VA-API support)
RUN apt-get update && apt-get install -y --no-install-recommends \
python3 \
make \
@@ -56,11 +54,26 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
poppler-utils \
imagemagick \
fonts-noto-cjk \
libraw-bin \
libimage-exiftool-perl \
&& . /etc/os-release \
&& TARGETARCH=$(dpkg --print-architecture) \
&& FFMPEG_VERSION="8.1.2-5" \
&& curl -fsSL -o /tmp/jellyfin-ffmpeg.deb "https://github.com/jellyfin/jellyfin-ffmpeg/releases/download/v${FFMPEG_VERSION}/jellyfin-ffmpeg8_${FFMPEG_VERSION}-${VERSION_CODENAME}_${TARGETARCH}.deb" \
&& apt-get install -y --no-install-recommends /tmp/jellyfin-ffmpeg.deb \
&& rm -f /tmp/jellyfin-ffmpeg.deb \
&& ldconfig /usr/lib/jellyfin-ffmpeg/lib \
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/local/bin/ffmpeg \
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/local/bin/ffprobe \
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/bin/ffmpeg \
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/bin/ffprobe \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
# Set up working directory and make it owned by the bun user
RUN mkdir -p /app/data && chown -R bun:bun /app
# Set up working directory and make it owned by the bun user, ensure video/render group access
RUN usermod -a -G video,render bun 2>/dev/null || true \
&& mkdir -p /app/data \
&& chown -R bun:bun /app
# Switch to the non-root bun user
USER bun
@@ -83,9 +96,11 @@ USER root
COPY scripts/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
# Expose "bun index.js" as "shumai" CLI command (and alias "shuami")
# Expose "bun index.js" as "shumai" CLI command (and worker commands "shumai-transcode", "shumai-agent")
RUN printf '#!/bin/sh\nexec bun /app/index.js "$@"\n' > /usr/local/bin/shumai \
&& chmod +x /usr/local/bin/shumai \
&& printf '#!/bin/sh\nexec bun /app/transcode-worker.js "$@"\n' > /usr/local/bin/shumai-transcode \
&& printf '#!/bin/sh\nexec bun /app/agent-worker.js "$@"\n' > /usr/local/bin/shumai-agent \
&& chmod +x /usr/local/bin/shumai /usr/local/bin/shumai-transcode /usr/local/bin/shumai-agent \
&& ln -s /usr/local/bin/shumai /usr/local/bin/shuami
ENTRYPOINT ["docker-entrypoint.sh"]
+82
View File
@@ -0,0 +1,82 @@
#syntax=docker/dockerfile:1.7-labs
# Stage 1: Builder
FROM oven/bun:1.4.4 AS builder
WORKDIR /app
# Copy package files
COPY package.json bun.lock ./
COPY --parents packages/*/package.json ./
COPY --parents apps/*/package.json ./
COPY patches/ ./patches/
# Install dependencies (including devDependencies for build tools)
RUN bun install --frozen-lockfile
# Copy source code
COPY . .
# Build transcode worker bundle
RUN bun run build.ts transcode
# Generate runner-package.json for the runner stage
RUN bun run scripts/extract-runtime-deps.ts
# Stage 2: Runner
FROM oven/bun:1.4.4 AS runner
ENV NODE_ENV=production
# Install transcoding system dependencies and Jellyfin-FFmpeg (with VA-API/hardware acceleration support)
RUN apt-get update && apt-get install -y --no-install-recommends \
curl \
ca-certificates \
gosu \
poppler-utils \
imagemagick \
fonts-noto-cjk \
libraw-bin \
libimage-exiftool-perl \
&& . /etc/os-release \
&& TARGETARCH=$(dpkg --print-architecture) \
&& FFMPEG_VERSION="8.1.2-5" \
&& curl -fsSL -o /tmp/jellyfin-ffmpeg.deb "https://github.com/jellyfin/jellyfin-ffmpeg/releases/download/v${FFMPEG_VERSION}/jellyfin-ffmpeg8_${FFMPEG_VERSION}-${VERSION_CODENAME}_${TARGETARCH}.deb" \
&& apt-get install -y --no-install-recommends /tmp/jellyfin-ffmpeg.deb \
&& rm -f /tmp/jellyfin-ffmpeg.deb \
&& ldconfig /usr/lib/jellyfin-ffmpeg/lib \
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/local/bin/ffmpeg \
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/local/bin/ffprobe \
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffmpeg /usr/bin/ffmpeg \
&& ln -sf /usr/lib/jellyfin-ffmpeg/ffprobe /usr/bin/ffprobe \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
# Set up working directory and make it owned by the bun user, ensure video/render group access
RUN usermod -a -G video,render bun 2>/dev/null || true \
&& mkdir -p /app/data \
&& chown -R bun:bun /app
# Switch to the non-root bun user
USER bun
WORKDIR /app
# Install runtime dependencies with exact matching versions extracted from the builder stage
COPY --chown=bun:bun --from=builder /app/runner-package.json ./package.json
RUN bun install
# Copy build artifacts
COPY --chown=bun:bun --from=builder /app/dist ./
# Switch back to root at the end so the container runs the entrypoint as root
USER root
COPY scripts/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
# Expose "bun transcode-worker.js" as "shumai-transcode" CLI command
RUN printf '#!/bin/sh\nexec bun /app/transcode-worker.js "$@"\n' > /usr/local/bin/shumai-transcode \
&& chmod +x /usr/local/bin/shumai-transcode
ENTRYPOINT ["docker-entrypoint.sh"]
# Default command: start transcode worker
CMD ["shumai-transcode"]
+107 -197
View File
@@ -12,7 +12,7 @@
<a href="https://hub.docker.com/r/shumaione/shumai"><img alt="Docker pulls" src="https://img.shields.io/docker/pulls/shumaione/shumai" /></a>
<a href="https://github.com/shumaiOne/shumai/releases"><img alt="GitHub latest release" src="https://img.shields.io/github/v/release/shumaiOne/shumai" /></a>
<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue" /></a>
<a target="_blank" href="https://deepwiki.com/shumaiOne/shumai"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg" /></a>
<a target="_blank" href="https://deepwiki.com/shumaiOne/shumai"><img alt="Ask DeepWiki" src="https://img.shields.io/badge/Ask-DeepWiki-6E56CF" /></a>
</p>
<p align="center">
@@ -26,15 +26,20 @@
Shumai is an open-source Frame.io alternative built for creative teams to collaborate and share media with ease:
* **S3-Compatible & Local Storage**: Store and serve creative assets securely using the local filesystem or any S3-compatible storage service, including AWS S3, Cloudflare R2, and MinIO.
* **Archive Storage & Auto-Archival**: Offload original master media files to secondary local storage or cold S3 storage—manually or automatically via team lifecycle policies—to save on storage costs while keeping proxies for instant browsing and playback. See [Archive Storage documentation](https://docs.shumai.one/configuration/archive-storage).
* **Frame-by-Frame Annotations & Comments**: Leave precise feedback with frame-specific drawing tools and timestamped comments on both video and image assets.
* **Secure Sharing & Collections**: Create private share links and curated media collections for clients, stakeholders, and collaborators.
* **Granular Access Control**: Manage workspace permissions with team-level and project-level role-based access control.
* **Distributed Transcoding via Temporal**: Offload resource-intensive video transcoding to a background worker pool orchestrated by Temporal.
* **Durable Workflows via DBOS**: Run background tasks and AI agent workflows orchestrated reliably by DBOS on PostgreSQL with automatic recovery and fault tolerance.
* **Scalable Deployment on Docker or Kubernetes**: Horizontally autoscale video transcoding on multiple instances. See [EKS Deployment Example](eks/README.md).
* **Custom Asset Metadata**: Define dynamic metadata fields tailored to your production pipeline.
* **Share Link Watermarking**: Protect shared media with customizable text and image watermarks, and save watermark as reusable templates.
* **Wide File Format Support**: Preview common creative file formats, including images (with PSD support), videos, audio, and documents, while allowing any file type to be uploaded and stored.
* **3D Asset Turntable Previews**: Generate interactive 3D model turntable previews and videos for formats like GLB, FBX, OBJ, STL, USD, and DAE using [turntable-renderer](https://docs.shumai.one/using-shumai/3d-asset-support).
* **Office & Document PDF Proxying via Gotenberg**: Convert Word, PowerPoint, Excel, Markdown, HTML, and CSV documents to high-quality PDF proxies for in-browser previewing using [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg).
* **Semantic Search**: Find assets by visual or conceptual meaning using vector embeddings. See [documentation](https://docs.shumai.one/using-shumai/semantic-search).
* **NLE Export & Premiere Pro Plugin (Experimental)**: Export timestamped review comments to your favorite non-linear editor (Premiere Pro XML, DaVinci Resolve EDL, Final Cut Pro, Avid Media Composer) or use the experimental Premiere Pro UXP plugin to import media assets and auto-sync comments directly to sequence timeline markers. See [documentation](https://docs.shumai.one/using-shumai/nle-and-premiere).
* **Built-in MCP Server & CLI**: Connect external AI agents to Shumai via `/mcp` or manage projects, assets, comments, and metadata from the terminal with `shumai-cli`.
But Shumai goes beyond being a Frame.io alternative. With modern models like GPT-Image-2 and Seedance 2.5, AI can already handle a surprising amount of creative work. That means you can create or update videos and images from a simple prompt without having to jump back into Photoshop, Premiere or Houdini. That is why Shumai includes a powerful agent system:
@@ -46,7 +51,6 @@ But Shumai goes beyond being a Frame.io alternative. With modern models like GPT
* **Model Context Protocol (MCP)**: Connect agents to external tools and APIs through remote MCP servers, with OAuth authentication and per-agent MCP access.
* **Isolated Sandbox Execution**: Run agent-submitted scripts safely in a sandboxed environment.
* **AI Metadata Autofill**: Automatically fill in custom metadata for new assets.
* **Semantic Search**: Find assets by visual or conceptual meaning using vector embeddings (Gemini Embedding 2).
* **Resource Quotas**: Set usage limits on AI tokens, costs, and tool execution per member, role, or team-wide, with real-time tracking.
Here is a short demo video showing what the Shumai agent can do:
@@ -68,11 +72,13 @@ The ultimate goal is an **agentic Kanban**, where agents and team members can wo
> * **For Images:** Shumai generates a high-quality WebP proxy at the exact same resolution as your original file for optimized viewing.
> * **For Videos:** It generates at least one proxy video (depending on your transcoding settings), alongside a sprite image and a small preview video (capped at 1600 frames) to enable fast timeline scrubbing and lightning-quick previews.
---
Have feedback or ideas? [Share them with us](https://github.com/shumaiOne/shumai/issues/328), and if you find Shumai useful, please give us a ⭐ or recommend Shumai to someone who might find it useful, it really helps!
## Installation
Below is a quickstart guide for running Shumai with local storage. For advanced configuration options (including S3-compatible storage and Temporal workflow orchestration), see our [Documentation](https://docs.shumai.one/getting-started/overview).
Below is a quickstart guide for running Shumai with local storage. For advanced configuration options (including S3-compatible storage and distributed worker orchestration), see our [Documentation](https://docs.shumai.one/getting-started/overview).
### Option 1: Docker Compose
@@ -82,14 +88,47 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
```bash
mkdir shumai && cd shumai
```
2. Download the `docker-compose.yaml` file:
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
```
3. Configure environment variables (optional):
2. Download your preferred `docker-compose.yaml` configuration based on your needs and available RAM:
* `SHUMAI_SERVER_PORT` controls the port the Shumai server listens on. The default is `3000`.
* By default, Shumai uses the bundled local storage service in this Docker Compose setup. To use an external S3-compatible storage instead, configure the environment variables for your S3 provider. Here are examples for AWS S3 and Cloudflare R2:
* **Lite (Suggested RAM: 2 GB+)**: Minimal deployment containing Shumai and PostgreSQL database.
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
```
* **With Embedding Server (Suggested RAM: 4 GB+)**: Adds local multimodal semantic search powered by `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`).
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.embedding.yaml
```
* **Full (Suggested RAM: 8 GB+)**: All-in-one setup including `embedding-server`, `turntable-renderer` (3D previews), and `Gotenberg` (document PDF proxying).
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.full.yaml
```
> [!NOTE]
> By default, the Docker Compose setups use CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the [Hardware Transcoding Guide](https://docs.shumai.one/configuration/hardware-transcoding).
3. Configure environment variables:
* `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). It is used for:
* **Password reset links**: Generates CLI and user password reset URLs (`{BETTER_AUTH_URL}/reset-password?token=...`).
* **Email notification deep links**: Default base URL for notification emails (if `APP_URL` is unset).
* **Session cookie security**: Determines whether to issue session cookies with `Secure` flags and `__Secure-` prefixes for HTTPS deployments.
* **MCP OAuth 2.1 & discovery**: Sets the OAuth resource identifier (`{BETTER_AUTH_URL}/mcp`), discovery endpoints (`/.well-known/...`), and default redirect URI for outbound MCP OAuth.
> [!NOTE]
> **Email/password Web UI login** works over plain HTTP/IP even if `BETTER_AUTH_URL` is omitted. However, setting it is strongly recommended for production, custom domains, or HTTPS deployments. Note that remote deployments must use HTTPS for MCP OAuth 2.1 (RFC 9728); if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional.
* `BETTER_AUTH_SECRET`: A random secret key used to sign session cookies, JWTs, and presigned file upload/download URLs (in local storage mode). A default placeholder is included in the template for instant local trials, but **you must generate a unique secret for production or public deployments** (e.g., run `openssl rand -base64 32`).
* `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files.
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
```yaml
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
```
This value must be reachable from client browsers and should include the externally exposed port.
* `SHUMAI_SERVER_PORT`: Controls the port the Shumai server listens on. The default is `3000`.
* **External S3 Storage**: By default, Shumai uses the bundled local storage service in this Docker Compose setup. To use an external S3-compatible storage instead, configure the environment variables for your S3 provider. Here are examples for AWS S3 and Cloudflare R2:
**AWS S3 Example:**
```yaml
@@ -109,204 +148,46 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
```
* By default, `AWS_ENDPOINT_URL_S3` is set to: `http://localhost:{SHUMAI_SERVER_PORT}`, if you use local storage and expose Shumai on a custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that browsers will use to upload files.
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
```
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
```
This value must be reachable from client browsers and should include the externally exposed port.
5. Start the services in detached mode:
4. Start the services in detached mode:
```bash
docker compose up -d
```
6. Open your browser and access Shumai at `http://localhost:3000` (or `http://<your-server-ip>:3000` for remote deployments).
5. Open your browser and access Shumai at `http://localhost:3000` (or `http://<your-server-ip>:3000` for remote deployments).
### Option 2: Install via NPM / Package Manager
#### **Scaling Transcode Workers (Parallel Processing)**
Shumai is published as `@shumai-one/shumai` on NPM. This option allows you to run Shumai globally or locally.
By default, the Docker Compose deployment transcodes videos one-by-one. This is by design, as video transcoding is compute-intensive and can saturate available CPU or GPU resources.
#### Step 1: Start PostgreSQL with pgvector
However, when uploading large batches (e.g., 100+ videos at once) or massive raw camera files that take hours to process and block subsequent uploads, you can scale transcoding throughput across additional machines. Each machine still processes tasks sequentially, but adding more worker instances increases overall parallel capacity.
Shumai requires PostgreSQL with the `pgvector` extension. Start a pre-configured database container using Docker:
Shumai makes this seamless with a dedicated [`shumaione/shumai-transcode`](https://hub.docker.com/r/shumaione/shumai-transcode) Docker image:
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d pgvector/pgvector:pg18
```
1. **Connect**: Launch a temporary machine and ensure network access to your PostgreSQL database and storage backend (e.g., S3 or shared storage).
2. **Start the worker**: Run the container with matching database and storage credentials:
#### Step 2: Create a workspace folder
```bash
docker run -d --name shumai_transcode_worker \
-e DATABASE_URL="postgres://shumai:shumai_password@<postgres-host>:5432/shumai_db?sslmode=disable" \
-e STORAGE_BACKEND="s3" \
-e S3_BUCKET="your-bucket-name" \
-e AWS_ENDPOINT_URL_S3="https://s3.us-east-1.amazonaws.com" \
-e S3_ACCESS_KEY_ID="your-access-key-id" \
-e S3_SECRET_ACCESS_KEY="your-secret-access-key" \
shumaione/shumai-transcode:latest
```
Create a dedicated directory to store your environment configuration and media files (which are saved in a `./data` directory by default):
The worker will automatically attach to the task queue and begin processing pending transcode jobs in parallel with your primary instance.
```bash
mkdir shumai && cd shumai
```
3. **Stop anytime**: Once the transcoding backlog finishes (or whenever you no longer need the extra compute), simply stop or remove the worker:
#### Step 3: Install Platform-Specific Dependencies
```bash
docker stop shumai_transcode_worker
```
#### Linux
There is no downtime or impact on the main Shumai application.
Shumai requires the following system packages on Linux:
- **`ffmpeg`** – Used for media transcoding and metadata extraction.
- **`poppler`** (`poppler-utils`) – Used for PDF page image extraction and PDF sprite preview generation (`pdftoppm`).
- **`imagemagick`** – Used for PSD format transcoding and color profile conversion to sRGB.
- **`bubblewrap`**, **`socat`**, and **`ripgrep`** – Required by the AI agent sandbox (`anthropic-experimental/sandbox-runtime`) for process isolation, networking, and workspace search.
Install all required packages with one command:
> Ubuntu/Debian
```bash
sudo apt install -y ffmpeg poppler-utils imagemagick bubblewrap socat ripgrep
```
> Fedora
```bash
sudo dnf install -y ffmpeg poppler-utils ImageMagick bubblewrap socat ripgrep
```
> Arch Linux
```bash
sudo pacman -S --noconfirm ffmpeg poppler imagemagick bubblewrap socat ripgrep
```
> [!NOTE]
> **Ubuntu 24.04+** restricts unprivileged user namespaces by default. This prevents `anthropic-experimental/sandbox-runtime` from using `bubblewrap` for sandbox isolation.
>
> To temporarily allow user namespaces:
>
> ```bash
> sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
> ```
>
> Alternatively, configure an AppArmor profile that grants the required `userns` permission to the relevant binaries.
---
#### macOS
Shumai requires:
- **`ffmpeg`** – Used for media transcoding and metadata extraction.
- **`poppler`** – Used for PDF page image extraction and PDF sprite preview generation (`pdftoppm`).
- **`imagemagick`** – Used for PSD format transcoding and color profile conversion to sRGB.
- **`ripgrep`** – Required by the AI agent sandbox (`anthropic-experimental/sandbox-runtime`).
Install the required packages with Homebrew:
```bash
brew install ffmpeg poppler imagemagick ripgrep
```
---
#### Windows (alpha)
> [!WARNING]
> Windows support in anthropic-experimental/sandbox-runtime is **alpha and the design is in flux**.
>
> The current implementation provides:
> - Network egress filtering via the **Windows Filtering Platform (WFP)**.
> - File read/write denial via **ACL stamping**.
>
> However, it is **not a security boundary against a deliberately adversarial sandboxed process**.
>
> The sandbox implementation will be substantially revised in a future release, where sandboxed processes will run under a dedicated sandbox user account.
Shumai requires:
- **`ffmpeg`** – Used for media transcoding and metadata extraction.
- **`imagemagick`** – Used for PSD format transcoding and color profile conversion to sRGB.
Install required packages using your preferred package manager:
**winget**
```powershell
winget install Gyan.FFmpeg ImageMagick.ImageMagick
```
**Chocolatey**
```powershell
choco install ffmpeg imagemagick
```
#### Step 4: Install Shumai globally
Install Shumai globally using your preferred package manager:
```bash
# NPM
npm install -g @shumai-one/shumai
# PNPM
pnpm add -g @shumai-one/shumai
# Bun
bun add -g @shumai-one/shumai
```
#### Step 5: Configure Environment Variables
Create a `.env` file in your workspace folder (`shumai/`) and add the following configuration:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
STORAGE_BACKEND=local
SHUMAI_SERVER_PORT=3000
AWS_ENDPOINT_URL_S3=http://localhost:3000
# Optional: base URL for MCP OAuth redirects (defaults to BETTER_AUTH_URL)
MCP_OAUTH_REDIRECT_BASE_URL=http://localhost:3000
```
> [!NOTE]
> `SHUMAI_SERVER_PORT` sets the port the server starts on, while `AWS_ENDPOINT_URL_S3` is used by the browser to build file upload URLs.
> If deploying on a remote server (e.g. `http://123.456.7.8`) with a mapped port (e.g. `12345:3000` in docker-compose), set `AWS_ENDPOINT_URL_S3` to `http://123.456.7.8:12345`.
> `MCP_OAUTH_REDIRECT_BASE_URL` is only needed when MCP servers use OAuth: the authorization redirect URI defaults to `{BETTER_AUTH_URL}/api/mcp/oauth/callback`; set it to an externally reachable URL if the app is served behind a proxy.
#### Step 6: Run Shumai
> [!IMPORTANT]
> **For Bun Users:** Since the published package binaries contain a `#!/usr/bin/env node` shebang, running the global command directly (e.g., `shumai`) will execute under Node.js. If you installed with Bun and want to run under the Bun runtime, you must prefix all commands with `bun run --bun` (e.g., `bun run --bun shumai`, `bun run --bun shumai -d`, `bun run --bun shumai stop`).
Start the application from your workspace folder:
```bash
shumai
```
Alternatively, you can run and manage Shumai in daemon mode:
- **Start in daemon mode**:
```bash
shumai -d
```
- **Stop Shumai**:
```bash
shumai stop
```
- **Restart Shumai**:
```bash
shumai restart
```
- **Show/tail logs**:
```bash
shumai logs
```
On startup, Shumai will automatically run database migrations and start the web server at `http://localhost:3000`.
---
### Option 3: Run from Source (Development)
### Option 2: Run from Source (Development)
To set up Shumai locally for development:
@@ -316,8 +197,24 @@ To set up Shumai locally for development:
cd shumai
bun install
```
2. Start the `pgvector` database container (as described in **Option 2, Step 1**).
3. Create a `.env` file at the root of the workspace using the configuration from **Option 2, Step 5**.
2. Start the `pgvector` database container:
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d pgvector/pgvector:pg18
```
3. Create a `.env` file at the root of the workspace:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL=http://localhost:3000
STORAGE_BACKEND=local
SHUMAI_SERVER_PORT=3000
AWS_ENDPOINT_URL_S3=http://localhost:3000
```
4. Generate i18n translation files:
```bash
bun run i18n:compile
@@ -333,6 +230,9 @@ To set up Shumai locally for development:
bun run dev
```
> [!NOTE]
> Looking to install Shumai globally via NPM or your package manager? See our [NPM Installation Guide](https://docs.shumai.one/getting-started/quickstart).
---
## Command Line Interface (CLI)
@@ -340,3 +240,13 @@ To set up Shumai locally for development:
Shumai provides a Command Line Interface (CLI) tool to manage projects, folders, and assets, upload files/folders, and create new versions directly from your terminal.
For more details on installation and usage, see the [CLI Readme](apps/cli/README.md).
## MCP Server
Shumai includes a built-in MCP server at `/mcp`, so external agents such as Claude Code, Cursor, or Kiro can browse and organize your projects with OAuth or an API token. See the [MCP server guide](docs/developer/mcp-server.mdx) for setup.
---
## Community
Thanks to [LINUX DO](https://linux.do/) for providing a community for open-source discussions and feedback.
+156 -260
View File
@@ -5,46 +5,51 @@
<h1 align="center">Shumai</h1>
<p align="center">
<strong>为创意工作打造的开源协作平台。</strong>
<strong>开源版 阅流 / 分秒帧 - 专为创意与视频团队打造的审片与管理平台。</strong>
</p>
<p align="center">
<a href="https://hub.docker.com/r/shumaione/shumai"><img alt="Docker pulls" src="https://img.shields.io/docker/pulls/shumaione/shumai" /></a>
<a href="https://github.com/shumaiOne/shumai/releases"><img alt="GitHub latest release" src="https://img.shields.io/github/v/release/shumaiOne/shumai" /></a>
<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue" /></a>
<a target="_blank" href="https://deepwiki.com/shumaiOne/shumai"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg" /></a>
<a target="_blank" href="https://deepwiki.com/shumaiOne/shumai"><img alt="Ask DeepWiki" src="https://img.shields.io/badge/Ask-DeepWiki-6E56CF" /></a>
</p>
<p align="center">
<a target="_blank" href="https://shumai.one/">官方网站</a> | <a target="_blank" href="https://docs.shumai.one/getting-started/overview">文档</a> | <a target="_blank" href="https://staging.shumai.one">在线演示</a> | <a target="_blank" href="README.md">English</a>
<a target="_blank" href="https://shumai.one/">官方网站</a> | <a target="_blank" href="https://docs.shumai.one/getting-started/overview">文档(英文)</a> | <a target="_blank" href="https://staging.shumai.one">在线演示</a> | <a target="_blank" href="README.md">English</a>
</p>
![Shumai 应用截图](docs/screenshot.webp)
## 功能
Shumai 是一个开源的 Frame.io 替代方案,专为创意团队打造,让大家能更轻松地协作、审片和分享素材:
Shumai 是一个专为广告,短剧,漫剧等各类创意团队打造的开源协作管理平台,功能上类似阅流和分秒帧,提供了协作、审片和分享等各种功能:
* **支持 S3 和本地存储**:你可以把创意素材安全地存到本地文件系统,或者任意兼容 S3 的存储服务里,比如 AWS S3、Cloudflare R2、MinIO 等。
* **逐帧标注和评论**:支持按帧进行精确反馈,可以直接在视频和图片素材上画重点、写评论,还能留下时间戳。
* **安全分享和合集管理**:可以生成私密分享链接,也能整理成精选合集,方便给客户、同事和合作方查看。
* **支持 S3 和本地存储**:你可以把创意素材安全地存放在本地硬盘或者任意兼容 S3 的存储服务里,比如 阿里云 OSS 或 MinIO 等。
* **冷归档存储**:支持将原始大文件移至冷存储(如本地挂载的 NAS、AWS S3 Glacier、Google Cloud Storage Coldline 等归档存储类型)以节省主存储成本,同时保留主存储中的预览图、代理流和元数据,不影响网页浏览与即时播放。详情请参阅[归档存储文档](https://docs.shumai.one/configuration/archive-storage)。
* **帧级别标注和评论**:支持按帧进行精确反馈,同时支持直接在视频上进行标注,让团队成员能更精确地Get到你的想法。
* **安全的分享**:可以生成私密分享链接,同时还支持给分享的图片/视频添加自定义水印,并将水印配置保存为模板以便重复使用。方便给客户、同事和合作方查看。
* **细粒度权限控制**:支持按团队、项目设置角色权限,方便管理不同成员的访问范围。
* **基于 Temporal 的分布式转码**:把吃资源的视频转码任务交给后台 worker 池处理,由 Temporal 统一调度。
* **基于 DBOS 的持久化工作流**:视频转码任务由 DBOS 统一持久化编排与调度,具备自动恢复和容错能力。
* **Docker/K8s 弹性扩缩容部署**:支持在多个实例上横向自动扩缩容视频转码工作负载。详见 [EKS 部署示例](eks/README.md)。
* **自定义素材元数据**:可以按你的制作流程,自由定义动态元数据字段。
* **分享链接水印**:通过可自定义的文字和图片水印保护共享媒体,并将水印配置保存为模板以便重复使用。
* **丰富的文件格式支持**:支持预览常见创意文件格式,包括图片(支持 PSD)、视频、音频和文档,同时可上传和存储任意类型的文件。
* **基于 Gotenberg 的文档 PDF 转码代理**:通过集成 [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg) 支持将 Word、PowerPoint、Excel、Markdown、HTML 和 CSV 文档高质量转换为 PDF 代理文件进行在线预览。
* **非编剪辑导出与 Premiere 插件(实验性)**:支持将时间戳审阅评论导出至常用非编软件(Premiere Pro XML、DaVinci Resolve EDL、Final Cut Pro、Avid Media Composer),或使用实验性的 Premiere Pro 原生 UXP 插件导入媒体素材并将评论自动同步为时间轴标记。详见[相关文档](https://docs.shumai.one/using-shumai/nle-and-premiere)。
* **3D 素材预览**:通过集成 [turntable-renderer](https://docs.shumai.one/using-shumai/3d-asset-support) 支持给 GLB、FBX、OBJ、STL、USD 和 DAE 等 3D 模型生成高质量的交互式转盘预览。
* **Office 与文档在线预览**:通过集成 [Gotenberg](https://docs.shumai.one/using-shumai/gotenberg),自动将 Word、PPT、Excel、Markdown、HTML 和 CSV 高质量转换为 PDF,直接在浏览器里丝滑预览。
* **语义搜索**:支持按画面内容或概念含义搜索素材,详见[相关文档](https://docs.shumai.one/using-shumai/semantic-search)。
* **非编剪辑导出与 Premiere 插件(测试版)**:支持将时间戳审阅评论导出至常用非编软件(Premiere Pro XML、DaVinci Resolve EDL、Final Cut Pro、Avid Media Composer),或使用实验性的 Premiere Pro 原生 UXP 插件导入媒体素材并将评论自动同步为时间轴标记。详见[相关文档](https://docs.shumai.one/using-shumai/nle-and-premiere)。
* **内置 MCP 服务端与 CLI 工具**:支持通过 `/mcp` 将外部 AI Agent 接入 Shumai,或使用 `shumai-cli` 在终端中管理项目、素材、评论与元数据。
但 Shumai 不仅仅只满足于 Frame.io 的开源替代。随着 GPT-Image-2、Seedance 2.5 这类强大模型的问世,AI已经生成产品级的图片/视频。很多时候,你只要给一句提示词,就能直接生成或修改图片和视频,而不用再打开 Photoshop、Premiere 或者 Houdini。也正因为这样,Shumai 才把 AI Agent 做成了核心能力:
Shumai 不仅仅只满足于「阅流」和「分秒帧」的开源替代。随着 GPT-Image-2、Seedance 2.5 这类强大视频/图片生成模型的问世,AI已经能够生成产品级的创意素材。只需要一句提示词,AI就能直接生成或修改图片和视频,而不用再打开 Photoshop、Premiere 或者 Houdini。因此Shumai也添加了Agent相关功能:
* **Agent 就像团队成员**:你可以在素材评论区里直接用 `@` 提到 AI Agent,像拉一个真实同事进来一起看稿一样。
> **AI 功能完全可选。** 你完全可以把 Shumai 当作纯粹的开源版「阅流 / 分秒帧」来用;如果团队不需要 AI,直接忽略即可。
* **Agent 是你的团队成员**:你可以在素材评论区里直接用 `@` 提到 AI Agent,像拉一个真实同事进来一起看稿一样。
* **Agent 也能当你的私聊助手**:你可以单独和它聊天,让它帮你查东西、做任务。
* **自定义技能和工具**:你可以给 Agent 接上自己的脚本、工具和自动化能力。
* **Model Context Protocol (MCP) 支持**:通过远程 MCP 服务端为 Agent 接入外部工具与 API,支持 OAuth 鉴权与按 Agent 独立分配访问权限。
* **自定义技能和工具**:你可以给 Agent 添加自己的脚本、工具和自动化能力。
* **接入外部 MCP 工具 (Model Context Protocol)**:通过远程 MCP 服务端为 Agent 接入外部工具与 API,支持 OAuth 鉴权与按 Agent 独立分配访问权限。
* **沙箱隔离执行**:Agent 生成的脚本会在隔离环境里运行,更安全。
* **AI 自动补全元数据**:新素材上传后,系统可以自动帮你补一些元数据。
* **语义搜索**:支持按画面内容或语义找素材,底层用的是向量 embedding(Gemini Embedding 2)。
* **AI 自动打标与补全元数据**:新素材上传后,AI 可根据画面内容自动识别并填写自定义元数据字段,省去手动归档打标的麻烦。
* **资源配额**:支持按成员、角色或全团队对 AI Token、成本和工具调用设置使用上限与实时用量监控。
下面是一个简短的 demo 视频,展示了 Shumai Agent 能做什么:
@@ -64,15 +69,17 @@ Shumai 也将项目管理融入了创意工作流程。 内置的看板可以帮
> * **图片:** 会生成一份与原图分辨率完全一致的高质量 WebP 转码版本,在保证画质的同时提升浏览性能。
> * **视频:** 会根据转码配置生成至少一个代理视频,同时生成雪碧图(Sprite)和一段最长 1600 帧的低分辨率转码视频,用于实现快速拖动时间轴和即时视频预览。
如果你有任何反馈或想法,欢迎在 [Issue #329](https://github.com/shumaiOne/shumai/issues/329) 中和我们交流。如果 Shumai 对你有帮助,希望能给我们点个 ⭐,或者安利给身边做视频/创意的朋友。
---
## 安装指南
以下是使用本地存储运行 Shumai 的快速上手指南。如需了解高级配置(包括 S3 兼容存储配置、Temporal 工作流编排等),请参阅我们的[官方文档](https://docs.shumai.one/getting-started/overview)。
以下是使用本地存储的快速安装指南。如需了解高级配置(包括 S3 兼容存储配置、分布式 worker 编排等),请参阅我们的[官方文档](https://docs.shumai.one/getting-started/overview)。
### 方案一:使用 Docker Compose(推荐)
<details>
<summary>复制这个提示词,让agent帮你安装</summary>
```
@@ -90,54 +97,75 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA
```
</details>
使用 Docker Compose 是运行 Shumai 最快的方式。您无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/),然后按照以下步骤操作:
使用 Docker Compose 是运行 Shumai 最快的方式。你无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/),然后按照以下步骤操作:
1. 创建并进入一个新目录,用于存放配置文件和数据卷:
1. 创建一个新文件夹,用于存放配置文件和数据:
```bash
mkdir shumai && cd shumai
```
2. 下载 `docker-compose.yaml` 配置文件:
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.yaml
2. 根据你的需求和机器可用内存,下载对应的 `docker-compose.yaml` 配置文件(注意所有镜像都是阿里云源,想要使用dockerhub源请参考不带aliyun的compose文件):
```
* **轻量版(建议内存:2 GB+)**:包含 Shumai 核心应用与 PostgreSQL 数据库。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.yaml
```
* **集成语义搜索版(建议内存:4 GB+)**:新增基于 `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`) 的本地多模态语义搜索能力。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.embedding.yaml
```
* **完整版(建议内存:8 GB+)**:一站式全功能版本,包含 `embedding-server`、`turntable-renderer`(3D 模型交互转盘预览)与 `Gotenberg`(文档与表格 PDF 代理转码)。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.full.yaml
```
> [!NOTE]
> 默认的 Docker Compose 配置使用基于 CPU 的软件转码。如果你的服务器支持硬件加速(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API 或 Rockchip RKMPP),请参考 [硬件加速转码配置文档](https://docs.shumai.one/configuration/hardware-transcoding)。
3. 配置环境变量(可选):
* `SHUMAI_SERVER_PORT` 用于控制 Shumai 服务监听的端口,默认值为 `3000`。
* 默认情况下,该 Docker Compose 部署会自动启用集成的本地存储。若想切换至外部 S3 兼容存储,请在 `environment` 中配置 S3 提供商的环境变量。以下是 AWS S3 和 Cloudflare R2 的配置示例:
3. 配置环境变量:
* `BETTER_AUTH_URL`:Shumai 服务的外部公开访问基础地址(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`),主要用于:
* **密码重置链接**:生成 CLI 及管理员重置密码链接(`{BETTER_AUTH_URL}/reset-password?token=...`)。
* **邮件通知跳转链接**:作为通知邮件中深度跳转链接的基础地址(若未配置 `APP_URL` 则回退至此)。
* **会话 Cookie 安全标记**:根据是否以 `https://` 开头决定是否为浏览器会话 Cookie 启用 `Secure` 属性和 `__Secure-` 前缀。
* **MCP OAuth 2.1 与元数据发现**:配置 MCP OAuth 资源标识符(`{BETTER_AUTH_URL}/mcp`)、元数据发现端点,以及外部 MCP OAuth 的默认重定向地址。
**AWS S3 示例:**
```yaml
STORAGE_BACKEND: s3
S3_BUCKET: your-bucket-name
S3_ACCESS_KEY_ID: your-access-key-id
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.com
```
> [!NOTE]
> **Web UI 的邮箱/密码基础登录**在私有 IP 或局域网 HTTP 环境下即使未配置该变量也可正常使用。但在生产环境、绑定域名或启用 HTTPS 时强烈建议配置。注意:MCP OAuth 2.1 依赖 HTTPS(本地 loopback 除外);若远程部署使用 HTTP,系统会优雅禁用 MCP OAuth 2.1 并记录日志,Web UI 与基于 API Token 的 MCP 访问不受影响。
* `BETTER_AUTH_SECRET`:用于对浏览器会话 Cookie、JWT 以及本地存储模式下的预签名上传/下载链接进行 HMAC 签名加密的随机密钥。模板中提供了一个默认占位值以便本地快速体验,**但在生产或公开部署环境中务必生成独立的随机密钥**(例如通过命令 `openssl rand -base64 32` 生成)。
* `AWS_ENDPOINT_URL_S3`:默认情况下指向 `http://localhost:{SHUMAI_SERVER_PORT}`。当你使用本地存储(即默认配置 `STORAGE_BACKEND: local`)并在远程服务器、自定义域名或自定义端口上公开访问 Shumai 时,请将 `AWS_ENDPOINT_URL_S3` 设置为客户端浏览器上传和下载文件所使用的外部 URL。
**Cloudflare R2 示例:**
```yaml
STORAGE_BACKEND: s3
S3_BUCKET: your-bucket-name
S3_REGION: auto
S3_ACCESS_KEY_ID: your-access-key-id
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
```
例如,如果你将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置:
```yaml
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
```
* 默认情况下 `AWS_ENDPOINT_URL_S3` 指向 `http://localhost:{SHUMAI_SERVER_PORT}`。如果您使用本地存储,但希望在自定义的主机名或端口上公开访问 Shumai,请务必将 `AWS_ENDPOINT_URL_S3` 修改为浏览器访问该服务时所使用的外部 URL。
例如,如果您将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置:
```
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
此地址必须能够从客户端浏览器正常访问,且必须包含对外暴露的实际端口号。
* `SHUMAI_SERVER_PORT` 用于控制 Shumai 服务监听的端口,默认值为 `3000`。
* **外部 S3 存储**:默认情况下,该 Docker Compose 部署会自动启用集成的本地存储。若想切换至外部 S3 兼容存储,请在 `environment` 中配置 S3 提供商的环境变量。以下是 AWS S3 和 Cloudflare R2 的配置示例:
```
**AWS S3 示例:**
```yaml
STORAGE_BACKEND: s3
S3_BUCKET: your-bucket-name
S3_ACCESS_KEY_ID: your-access-key-id
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.com
```
此地址必须能够从客户端浏览器正常访问,且必须包含对外暴露的实际端口号。
**Cloudflare R2 示例:**
```yaml
STORAGE_BACKEND: s3
S3_BUCKET: your-bucket-name
S3_REGION: auto
S3_ACCESS_KEY_ID: your-access-key-id
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
```
4. 在后台启动所有服务:
@@ -147,233 +175,91 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA
```
5. 打开浏览器,访问 `http://localhost:3000` 即可开始使用(若是远程部署,请访问 `http://<您的服务器IP>:3000`)。
5. 打开浏览器,访问 `http://localhost:3000` 即可开始使用(若是远程部署,请访问 `http://<你的服务器IP>:3000`)。
### 方案二:通过 NPM / 包管理器安装
#### **扩展转码 Worker(并行处理)**
通过 NPM 上的 `@shumai-one/shumai` 进行安装。
默认情况下,Docker Compose 部署会按顺序逐个处理视频转码任务。这是出于系统设计考虑,因为视频转码属于计算密集型任务,容易耗尽可用的 CPU 或 GPU 资源。
#### 第一步:启动带 pgvector 支持的 PostgreSQL
但在批量上传(例如一次性上传 100+ 个视频)或处理需要耗费数小时的大型原始视频素材时,长时间的转码任务可能会阻塞后续文件的处理。此时,你可以通过增加额外的机器来横向扩展转码吞吐量。每台机器依然按顺序执行任务,但增加 worker 实例能够显著提升整体的并行处理能力。
Shumai 依赖支持 `pgvector` 扩展的 PostgreSQL 数据库。您可以使用 Docker 快速启动一个预配置好的数据库容器:
Shumai 提供了独立的转码 Worker 镜像(支持 Docker Hub 与阿里云镜像源):
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d docker.m.daocloud.io/pgvector/pgvector:pg18
1. **连接准备**:启动一台临时机器,确保其能够正常访问你的 PostgreSQL 数据库和存储。
2. **启动 Worker**:配置相同的数据库与存储连接凭据并运行容器:
```
**阿里云镜像(国内推荐):**
```bash
docker run -d --name shumai_transcode_worker \
-e DATABASE_URL="postgres://shumai:shumai_password@<postgres-host>:5432/shumai_db?sslmode=disable" \
-e STORAGE_BACKEND="s3" \
-e S3_BUCKET="your-bucket-name" \
-e AWS_ENDPOINT_URL_S3="https://s3.us-east-1.amazonaws.com" \
-e S3_ACCESS_KEY_ID="your-access-key-id" \
-e S3_SECRET_ACCESS_KEY="your-secret-access-key" \
crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai-transcode:latest
```
#### 第二步:创建工作区目录
Worker 启动后会自动接入任务队列,并与主实例并行消费并处理积压的转码任务。
创建一个专属目录用来存放环境配置和媒体文件(媒体文件默认会保存在 `./data` 目录下):
3. **随时停止**:当转码队列处理完毕(或不再需要额外的算力)时,只需停止或移除 Worker 容器:
```bash
mkdir shumai && cd shumai
```bash
docker stop shumai_transcode_worker
```
```
主 Shumai 服务的运行不会受到任何影响,不需要停机。
#### 步骤 3:安装平台依赖
### 方案二:源码编译运行(开发环境)
#### Linux
在 Linux 上运行 Shumai 需要安装以下系统依赖:
- **`ffmpeg`** —— 用于媒体转码和元数据提取。
- **`poppler`** (`poppler-utils`) —— 用于 PDF 页面图像提取和 PDF 雪碧图预览生成 (`pdftoppm`)。
- **`imagemagick`** —— 用于 PSD 格式图像转码和 sRGB 色彩空间转换。
- **`bubblewrap`**、**`socat`** 和 **`ripgrep`** —— AI Agent 沙箱(`anthropic-experimental/sandbox-runtime`)所需,用于进程隔离、网络通信和工作区搜索。
可以使用以下命令一次性安装所有依赖:
> Ubuntu/Debian
```bash
sudo apt install -y ffmpeg poppler-utils imagemagick bubblewrap socat ripgrep
```
> Fedora
```bash
sudo dnf install -y ffmpeg poppler-utils ImageMagick bubblewrap socat ripgrep
```
> Arch Linux
```bash
sudo pacman -S --noconfirm ffmpeg poppler imagemagick bubblewrap socat ripgrep
```
> [!NOTE]
> **Ubuntu 24.04+** 默认限制非特权用户创建 User Namespace,这会导致 `anthropic-experimental/sandbox-runtime` 无法使用 `bubblewrap` 提供沙箱隔离。
>
> 如需临时启用 User Namespace,请执行:
>
> ```bash
> sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
> ```
>
> 或者,配置 AppArmor Profile,为相关可执行文件授予所需的 `userns` 权限。
---
#### macOS
在 macOS 上运行 Shumai 需要:
- **`ffmpeg`** —— 用于媒体转码和元数据提取。
- **`poppler`** —— 用于 PDF 页面图像提取和 PDF 雪碧图预览生成 (`pdftoppm`)。
- **`imagemagick`** —— 用于 PSD 格式图像转码和 sRGB 色彩空间转换。
- **`ripgrep`** —— AI Agent 沙箱(`anthropic-experimental/sandbox-runtime`)所需。
使用 Homebrew 安装所需依赖:
```bash
brew install ffmpeg poppler imagemagick ripgrep
```
---
#### Windows(Alpha)
> [!WARNING]
> anthropic-experimental/sandbox-runtime 的 Windows 支持目前仍处于 **Alpha** 阶段,整体设计仍在持续调整中。
>
> 当前实现提供了以下能力:
> - 通过 **Windows Filtering Platform (WFP)** 实现网络出口(egress)过滤。
> - 通过 **ACL Stamping** 实现文件读写权限限制。
>
> **但这并不能作为针对恶意沙箱进程的安全边界(security boundary)**。
>
> 未来版本将对沙箱机制进行重大调整,届时沙箱进程将运行在独立的沙箱用户账户下。
在 Windows 上运行 Shumai 需要:
- **`ffmpeg`** —— 用于媒体转码和元数据提取。
- **`imagemagick`** —— 用于 PSD 格式图像转码和 sRGB 色彩空间转换。
使用你偏好的包管理器安装所需依赖:
**winget**
```powershell
winget install Gyan.FFmpeg ImageMagick.ImageMagick
```
**Chocolatey**
```powershell
choco install ffmpeg imagemagick
```
#### 第四步:全局安装 Shumai
使用您常用的包管理器进行全局安装:
```bash
# 使用 NPM
npm install -g @shumai-one/shumai
# 使用 PNPM
pnpm add -g @shumai-one/shumai
# 使用 Bun
bun add -g @shumai-one/shumai
```
#### 第五步:配置环境配置
在刚才创建的工作区目录(`shumai/`)下新建一个 `.env` 文件,并填入以下配置:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
STORAGE_BACKEND=local
SHUMAI_SERVER_PORT=3000
AWS_ENDPOINT_URL_S3=http://localhost:3000
```
> [!NOTE]
> `SHUMAI_SERVER_PORT` 用于设置 Web 服务的启动端口,而 `AWS_ENDPOINT_URL_S3` 供浏览器端构建文件上传链接。
> 如果您部署在远程服务器(如 `http://123.456.7.8`)并且做了端口映射(如 Docker 中的 `12345:3000`),请将 `AWS_ENDPOINT_URL_S3` 设置为 `http://123.456.7.8:12345`。
#### 第六步:启动 Shumai
> [!IMPORTANT]
> **Bun 用户特别提示:** 由于发布的包二进制文件包含 `#!/usr/bin/env node` 头部声明(Shebang),直接在终端执行全局命令(例如 `shumai`)默认会通过 Node.js 运行。如果您是用 Bun 安装的并且希望调用 Bun 运行时,请在所有命令前加上 `bun run --bun` 前缀(例如:`bun run --bun shumai`、`bun run --bun shumai -d`、`bun run --bun shumai stop`)。
在您的工作区目录下执行以下命令启动应用:
```bash
shumai
```
您也可以让 Shumai 在后台以守护进程(Daemon)模式运行和管理:
* **后台模式启动**:
```bash
shumai -d
```
* **停止服务**:
```bash
shumai stop
```
* **重启服务**:
```bash
shumai restart
```
* **查看并跟踪实时日志**:
```bash
shumai logs
```
启动时,Shumai 会自动执行数据库迁移(Migration)并在 `http://localhost:3000` 拉起 Web 服务。
---
### 方案三:源码编译运行(开发环境)
如果您希望在本地参与 Shumai 的开发,请按以下步骤配置开发环境:
如果你希望在本地参与 Shumai 的开发,请按以下步骤配置开发环境:
1. 克隆代码仓库并安装依赖项:
```bash
git clone [https://github.com/shumaiOne/shumai.git](https://github.com/shumaiOne/shumai.git)
cd shumai
bun install
```bash
git clone https://github.com/shumaiOne/shumai.git
cd shumai
bun install
```
```
2. 启动 `pgvector` 数据库容器:
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d docker.m.daocloud.io/pgvector/pgvector:pg18
```
3. 在项目根目录下创建一个 `.env` 文件,填入以下基础配置:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL=http://localhost:3000
STORAGE_BACKEND=local
SHUMAI_SERVER_PORT=3000
AWS_ENDPOINT_URL_S3=http://localhost:3000
```
2. 启动 `pgvector` 数据库容器(参考**方案二中的第一步**)。
3. 参照**方案二中的第五步**,在项目根目录下创建一个 `.env` 文件。
4. 生成多语言国际化(i18n)代码:
```bash
bun run i18n:compile
```
> [!TIP]
> 在前端开发过程中,可以在单独的终端窗口中运行 `bun run i18n:watch`,在修改 `packages/webui/messages/` 下的翻译文案时自动重新编译。
```bash
bun run i18n:compile
```
> [!TIP]
> 在前端开发过程中,可以在单独的终端窗口中运行 `bun run i18n:watch`,在修改 `packages/webui/messages/` 下的翻译文案时自动重新编译。
5. 执行数据库结构迁移:
```bash
bun run db:migrate
```
```bash
bun run db:migrate
```
6. 启动本地开发服务器:
```bash
bun run dev
```
```bash
bun run dev
```
> [!NOTE]
> 如需通过 NPM 或包管理器全局安装运行 Shumai,请参考[官方 NPM 安装指南](https://docs.shumai.one/getting-started/quickstart)。
@@ -381,6 +267,16 @@ bun run dev
## 命令行工具 (CLI)
Shumai 自带一个功能完备的命令行工具(CLI),支持您直接在终端里高效管理项目、文件夹、资产,批量上传文件/目录,以及快速创建新版本。
Shumai 自带一个功能完备的命令行工具(CLI),支持你直接在终端里高效管理项目、文件夹、素材,批量上传文件/目录,以及快速创建新版本。
关于 CLI 的安装与详细使用指南,请参阅 [CLI Readme](https://www.google.com/search?q=apps/cli/README.md)。
关于 CLI 的安装与详细使用指南,请参阅 [CLI Readme](apps/cli/README.md)。
## MCP 服务器
Shumai 内置 MCP 服务器(地址为 `/mcp`),Claude Code、Cursor、Kiro 等外部智能体可以使用 API 令牌连接,浏览并整理你的项目。配置方法请参阅 [MCP 服务器指南](docs/developer/mcp-server.mdx)。
---
## 社区
感谢 [LINUX DO](https://linux.do/) 提供开源交流社区,欢迎佬友交流使用体验与改进建议。
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@shumai/agent-app",
"version": "0.4.7",
"version": "0.6.5",
"private": true,
"type": "module",
"bin": {
+1 -10
View File
@@ -21,16 +21,7 @@ async function run() {
console.log('🚀 Starting Agent Worker...')
const options: { workflowBundle?: unknown; workflowsPath?: string } = {}
if (process.env.NODE_ENV === 'production') {
// @ts-ignore: Bun temporal plugin macro
const { default: workflowBundle } = await import('./workflows.ts:::workflow')
options.workflowBundle = workflowBundle
} else {
options.workflowsPath = new URL('./workflows.ts', import.meta.url).pathname
}
await workflowService.startWorkers(TaskQueueAgent, options)
await workflowService.startWorkers(TaskQueueAgent)
}
handleDaemonCommands('shumai-agent', run).catch((err) => {
-4
View File
@@ -1,4 +0,0 @@
export * from '@shumai/agent/src/workflows/agent-autofill'
export * from '@shumai/agent/src/workflows/agent-chat'
export * from '@shumai/agent/src/workflows/agent-embedding'
export * from '@shumai/agent/src/workflows/query-embedding-for-search'
+130 -4
View File
@@ -2,13 +2,13 @@
A Command Line Interface (CLI) tool for interacting with your Shumai instance.
The CLI allows you to view projects, list folder contents, create folders, upload files and directories, and create new versions of existing files directly from the terminal.
The CLI allows you to view projects, list folder contents, create folders, upload files and directories, create new versions of existing files, and look at images, video frames, and document pages directly from the terminal.
---
## Installation
The CLI package is bundled inside the Shumai workspace.
The CLI package is bundled inside the Shumai workspace. The published npm package (`@shumai-one/shumai-cli`) requires Node.js 22.12 or later.
### Environment Setup
@@ -18,7 +18,8 @@ Before using the CLI, you must set the following environment variables to authen
# The endpoint of your Shumai API server (e.g. http://localhost:3000)
export SHUMAI_API_SERVER="http://localhost:3000"
# Your personal API Token (Generate this in the WebUI via Settings -> Developer tab)
# Your personal API Token (Generate this in the WebUI via Settings -> API Tokens tab).
# The token is shown only once when it is created, so copy it right away.
export SHUMAI_API_KEY="your-developer-api-token"
# Optional: Enable asset deletion capability (disabled by default for safety)
@@ -38,6 +39,14 @@ Run `shumai-cli` or query specific commands:
shumai-cli <command> [arguments] [options]
```
Run `shumai-cli --help` to list all commands, and `shumai-cli <command> --help` for a command's arguments and options.
### Global Options
- `--json`: Print the raw JSON result instead of human-friendly text, for scripts and tools like `jq`. Example: `shumai-cli ls -p <parentId> --json | jq '.data[].id'`.
When the output is piped instead of shown in a terminal, tables are printed as tab-separated values without headers.
### Commands
#### 1. List Projects
@@ -50,7 +59,7 @@ shumai-cli project ls
#### 2. List Directory Contents
List direct children (folders and files) of a parent folder.
List direct children (folders and files) of a parent folder. Folders are listed first.
```bash
shumai-cli ls -p <parentId>
@@ -58,6 +67,9 @@ shumai-cli ls -p <parentId>
- **Options:**
- `-p`, `--parent <id>`: The parent folder ID (required).
- `--type <type>`: Only list `file`, `folder`, or `all` (default).
- `--first <n>`: Maximum number of items to list (default and maximum: 200).
- `--after <cursor>`: Continue a long listing. When more items exist, `ls` prints the cursor to pass here.
#### 3. Create a New Folder
@@ -123,6 +135,116 @@ shumai-cli delete <assetId>
shumai-cli rm <assetId>
```
#### 9. Read an Asset
Look at a file: an image, video frames, PDF pages, a 3D model view, or the text of a text file. Prints a summary and a link to each image (links are valid for about an hour), or the file's text.
```bash
# An image, or the 4-view overview of a 3D model
shumai-cli read <assetId>
# 5 evenly spaced frames between 0s and 30s of a video, downloaded into ./frames
shumai-cli read <assetId> --video-start 0 --video-end 30 --video-count 5 --out frames
# Pages 1 to 3 of a PDF, or the text of a text file
shumai-cli read <assetId> --doc-mode pages --doc-start-page 1 --doc-end-page 3
shumai-cli read <assetId> --doc-mode text
# A 3D model at 90°
shumai-cli read <assetId> --degree 90
```
- **Options:**
- `--video-start <s>`, `--video-end <s>`, `--video-count <n>`: Video frames to extract (up to 20).
- `--doc-mode <pages|text>`, `--doc-start-page <n>`, `--doc-end-page <n>`: PDF pages to render (up to 20), or `text` to read a text file.
- `--degree <deg>`: 3D model angle (0, 15, 30, ..., 345).
- `--annotation-id <id>`: Draw a comment's markup on the image, frame, or page.
- `-o`, `--out <dir>`: Download the images into a folder and print their paths. With `--json`, each image also gets a `path`.
- `--max-wait-seconds <s>`, `--no-wait`: Rendering frames or pages can take a while. `read` waits up to 2 minutes; use these to wait less or return right away. If the render isn't done, `read` prints the `render` command to run next.
#### 10. Get a Render
Get the result of a `read` that was still rendering. Takes the same `--out`, `--max-wait-seconds`, and `--no-wait` options as `read`.
```bash
shumai-cli render <taskId> --out frames
```
#### 11. Download Files
Download up to 50 files at once. By default it saves the web preview version when there is one (for example the transcoded video or the web image), which is smaller; use `--original` for the uploaded file. A version stack downloads its latest version. Folders aren't supported: download the files inside them. Files keep their names; if a name is taken, the new file gets a number, like `clip (2).mp4`.
```bash
shumai-cli download <assetId...> --out ./downloads
shumai-cli download <assetId> --original
```
- **Options:**
- `-o`, `--out <dir>`: Folder to save the files in (default: the current folder). With `--json`, each file also gets a `path`.
- `--original`: Download the original uploaded files instead of the web previews.
#### 12. Search Files
Search a folder and all of its subfolders by name, or by meaning with `--semantic` (when AI search is enabled for the team).
```bash
shumai-cli search <query> -p <folderId>
shumai-cli search "a calm beach at sunset" -p <folderId> --semantic
```
- **Options:**
- `-p`, `--parent <id>`: The folder to search in (required).
- `--type <file|folder>`: Search files (default) or folders.
- `--first <n>`, `--after <cursor>`: Page through many results.
#### 13. Copy Assets
Copy files or folders into another folder of the same team. Prints the IDs of the copies.
```bash
shumai-cli copy <assetId...> -p <parentId> [--with-comments]
# or using the short alias:
shumai-cli cp <assetId...> -p <parentId>
```
#### 14. Comments
```bash
# List the comments on a file, with their replies
shumai-cli comment ls <assetId>
# Comment on a file, optionally at a timecode (seconds), or reply to a comment
shumai-cli comment add <assetId> "The logo is too small" --at 12.5
shumai-cli comment add <assetId> "Fixed in v2" --reply-to <commentId>
# Mark a comment as resolved, or unresolved again
shumai-cli comment resolve <commentId>
shumai-cli comment resolve <commentId> --reopen
```
#### 15. Metadata
```bash
# List a project's metadata fields and their choices
shumai-cli field ls <projectId>
# Set metadata values on a file, as JSON keyed by field key (select fields take an option id)
shumai-cli meta set <assetId> --values '{"status": "approved", "rating": 4}'
```
#### 16. Version Stacks
```bash
# Stack files in the same folder as versions; the first file is the latest
shumai-cli version stack <fileId...>
# List the versions in a stack, latest first
shumai-cli version ls <stackId>
# Take a version out of its stack (the file is kept)
shumai-cli version unstack <versionId>
```
#### 17. Folder Instructions
Show a folder's instructions for AI agents (its AGENTS.md).
```bash
shumai-cli instructions <folderId>
```
---
## Development
@@ -132,3 +254,7 @@ To run the CLI in development mode inside the repository source code:
```bash
bun run apps/cli/src/index.ts project ls
```
### Adding Commands
Most commands are generated from the shared Operation definitions in `packages/operations` (see "Operations" in `AGENTS.md`). An Operation with the `cli` surface and a `cli` spec becomes a command automatically, with arguments, options, and help text derived from its input schema (key/value inputs such as `meta set --values` take a JSON object). It is also available to Shumai's built-in agent and MCP server. Behavior that needs the local machine, such as downloading files, goes in a CLI extension in `src/operations/extensions/` (extra options, input mapping, and output). Only commands that stream local files (`upload`, `create-version`) are written by hand in `src/program.ts`; the `create_file`, `create_version`, and `complete_upload` Operations are for the agent and MCP only.
+5 -3
View File
@@ -1,6 +1,6 @@
{
"name": "@shumai/cli",
"version": "0.4.7",
"version": "0.6.5",
"private": true,
"type": "module",
"bin": {
@@ -8,10 +8,12 @@
},
"dependencies": {
"@shumai/api": "workspace:*",
"@shumai/core": "workspace:*",
"@shumai/dtos": "workspace:*",
"@shumai/operations": "workspace:*",
"@shumai/tableprinter": "workspace:*",
"commander": "15.0.0",
"hono": "4.13.5",
"ulid": "3.0.2"
"ulid": "3.0.2",
"zod": "4.5.4"
}
}
+14 -2
View File
@@ -1,7 +1,13 @@
import { hc } from 'hono/client'
import type { AppType } from '@shumai/api'
export function getClient() {
export interface CliConfig {
apiServer: string
apiKey: string
}
/** Reads the server URL and API token from the environment, exiting with guidance if missing. */
export function getCliConfig(): CliConfig {
const apiKey = process.env.SHUMAI_API_KEY
const apiServer = process.env.SHUMAI_API_SERVER
@@ -12,11 +18,17 @@ export function getClient() {
if (!apiKey) {
console.error(
'Error: SHUMAI_API_KEY environment variable is not set. Please generate a token in the Settings -> Developer tab.',
'Error: SHUMAI_API_KEY environment variable is not set. Please generate a token in the Settings -> API Tokens tab.',
)
process.exit(1)
}
return { apiServer: apiServer.replace(/\/+$/, ''), apiKey }
}
/** Typed REST client, used by commands that are not Operations yet (upload, create-version). */
export function getClient() {
const { apiServer, apiKey } = getCliConfig()
return hc<AppType>(apiServer, {
headers: {
Authorization: `Bearer ${apiKey}`,
+1 -261
View File
@@ -1,13 +1,7 @@
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
import { projectLs } from './project'
import { ls } from './ls'
import { mkdir } from './mkdir'
import { getClient } from '../client'
import { upload } from './upload'
import { createVersion } from './create-version'
import { rename } from './rename'
import { move } from './move'
import { deleteAsset } from './delete'
import fs from 'node:fs'
import http from 'node:http'
@@ -21,7 +15,7 @@ vi.mock('node:http', () => ({
},
}))
describe('CLI Commands', () => {
describe('CLI upload commands', () => {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
let logSpy: any
// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -103,72 +97,6 @@ describe('CLI Commands', () => {
}
})
describe('project ls', () => {
it('prints list of projects correctly', async () => {
mockClient.api.projects.$get.mockResolvedValue({
ok: true,
json: async () => ({
data: [
{ id: 'p1', name: 'Proj 1', rootFolder: 'root1' },
{ id: 'p2', name: 'Proj 2', rootFolder: 'root2' },
],
}),
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
await projectLs()
expect(mockClient.api.projects.$get).toHaveBeenCalledWith({
query: { first: '200' },
})
expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('Proj 1'))
expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('Proj 2'))
})
})
describe('ls', () => {
it('queries folders and files and displays table', async () => {
mockClient.api.folders[':folderId'].children.$get
.mockResolvedValueOnce({
ok: true,
json: async () => ({
data: [{ id: 'subfolder1', name: 'Sub 1', type: 'folder', sizeByte: 0 }],
}),
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
.mockResolvedValueOnce({
ok: true,
json: async () => ({
data: [{ id: 'file1', name: 'doc.pdf', type: 'file', sizeByte: 1024 }],
}),
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
await ls('parentId123')
expect(mockClient.api.folders[':folderId'].children.$get).toHaveBeenCalledTimes(2)
expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('Sub 1'))
expect(writeSpy).toHaveBeenCalledWith(expect.stringContaining('doc.pdf'))
})
})
describe('mkdir', () => {
it('calls POST /folders and prints the folder ID', async () => {
mockClient.api.folders.$post.mockResolvedValue({
ok: true,
json: async () => ({ id: 'new_folder_ulid' }),
// eslint-disable-next-line @typescript-eslint/no-explicit-any
} as any)
await mkdir('NewFolder', 'parent_ulid')
expect(mockClient.api.folders.$post).toHaveBeenCalledWith({
json: { name: 'NewFolder', parentId: 'parent_ulid' },
})
expect(logSpy).toHaveBeenCalledWith('Created folder with ID: new_folder_ulid')
})
})
describe('upload', () => {
it('uploads a file successfully and confirms the task', async () => {
const tempFile = 'temp-test-file.txt'
@@ -383,192 +311,4 @@ describe('CLI Commands', () => {
}
})
})
describe('rename', () => {
it('exits with error when assetId or newName is missing', async () => {
await expect(rename('', 'new-name')).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Asset ID is required'))
await expect(rename('asset-1', '')).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('New name is required'))
})
it('renames a folder when asset type is folder', async () => {
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: true,
json: async () => ({ id: 'f-1', type: 'folder' }),
} as unknown as Response)
mockClient.api.folders[':folderId'].$put.mockResolvedValue({
ok: true,
json: async () => ({ id: 'f-1', name: 'Renamed Folder' }),
} as unknown as Response)
await rename('f-1', 'Renamed Folder')
expect(mockClient.api.folders[':folderId'].$put).toHaveBeenCalledWith({
param: { folderId: 'f-1' },
json: { name: 'Renamed Folder' },
})
expect(logSpy).toHaveBeenCalledWith('Renamed asset f-1 to "Renamed Folder"')
})
it('renames a file when asset type is file', async () => {
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: true,
json: async () => ({ id: 'file-1', type: 'file' }),
} as unknown as Response)
mockClient.api.files[':fileId'].$put.mockResolvedValue({
ok: true,
json: async () => ({ id: 'file-1', name: 'new.mp4' }),
} as unknown as Response)
await rename('file-1', 'new.mp4')
expect(mockClient.api.files[':fileId'].$put).toHaveBeenCalledWith({
param: { fileId: 'file-1' },
json: { name: 'new.mp4' },
})
expect(logSpy).toHaveBeenCalledWith('Renamed asset file-1 to "new.mp4"')
})
it('exits with error when asset fetch fails', async () => {
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: false,
json: async () => ({ error: 'Asset not found' }),
} as unknown as Response)
await expect(rename('unknown-id', 'name')).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith('Error: Asset not found')
})
})
describe('move', () => {
it('exits with error when assetIds or parentId is missing', async () => {
await expect(move([], 'parent-1')).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining('At least one asset ID is required'),
)
await expect(move(['a-1'], '')).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining('Option -p/--parent <parentId> is required'),
)
})
it('successfully moves assets', async () => {
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: true,
json: async () => ({ id: 'parent-1', projectId: 'proj-1' }),
} as unknown as Response)
mockClient.api.projects[':projectId'].reparent.$post.mockResolvedValue({
ok: true,
} as unknown as Response)
await move(['a-1', 'a-2'], 'parent-1')
expect(mockClient.api.projects[':projectId'].reparent.$post).toHaveBeenCalledWith({
param: { projectId: 'proj-1' },
json: {
assetIds: ['a-1', 'a-2'],
newParentId: 'parent-1',
},
})
expect(logSpy).toHaveBeenCalledWith('Moved 2 asset(s) to parent parent-1')
})
it('exits with error when destination parent is not found', async () => {
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: false,
json: async () => ({ error: 'Folder not found' }),
} as unknown as Response)
await expect(move(['a-1'], 'missing-parent')).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith('Error: Folder not found')
})
})
describe('deleteAsset', () => {
it('exits with error when SHUMAI_ALLOW_DELETE is not set or not true', async () => {
delete process.env.SHUMAI_ALLOW_DELETE
await expect(deleteAsset(['a-1'])).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith(
'Error: Asset deletion is disabled in this environment.',
)
})
it('exits with error when assetIds is empty', async () => {
process.env.SHUMAI_ALLOW_DELETE = 'true'
await expect(deleteAsset([])).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Asset ID is required'))
})
it('exits with error when more than one asset ID is passed', async () => {
process.env.SHUMAI_ALLOW_DELETE = 'true'
await expect(deleteAsset(['a-1', 'a-2'])).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith('Error: Can only delete one asset at a time.')
})
it('exits with error when asset is not found', async () => {
process.env.SHUMAI_ALLOW_DELETE = 'true'
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: false,
json: async () => ({ error: 'Asset not found' }),
} as unknown as Response)
await expect(deleteAsset(['a-1'])).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith('Error: Asset not found')
})
it('successfully deletes a file when SHUMAI_ALLOW_DELETE is true', async () => {
process.env.SHUMAI_ALLOW_DELETE = 'true'
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: true,
json: async () => ({ id: 'a-1', type: 'file' }),
} as unknown as Response)
mockClient.api.files.$delete.mockResolvedValue({
ok: true,
} as unknown as Response)
await deleteAsset(['a-1'])
expect(mockClient.api.files.$delete).toHaveBeenCalledWith({
json: { ids: ['a-1'] },
})
expect(mockClient.api.folders.$delete).not.toHaveBeenCalled()
expect(logSpy).toHaveBeenCalledWith('Deleted asset a-1')
})
it('successfully deletes a folder when SHUMAI_ALLOW_DELETE is 1', async () => {
process.env.SHUMAI_ALLOW_DELETE = '1'
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: true,
json: async () => ({ id: 'folder-1', type: 'folder' }),
} as unknown as Response)
mockClient.api.folders.$delete.mockResolvedValue({
ok: true,
} as unknown as Response)
await deleteAsset(['folder-1'])
expect(mockClient.api.folders.$delete).toHaveBeenCalledWith({
json: { ids: ['folder-1'] },
})
expect(logSpy).toHaveBeenCalledWith('Deleted asset folder-1')
})
it('exits with error when delete API returns an error', async () => {
process.env.SHUMAI_ALLOW_DELETE = 'true'
mockClient.api.folders[':folderId'].$get.mockResolvedValue({
ok: true,
json: async () => ({ id: 'a-1', type: 'file' }),
} as unknown as Response)
mockClient.api.files.$delete.mockResolvedValue({
ok: false,
json: async () => ({ error: 'Failed to delete' }),
} as unknown as Response)
await expect(deleteAsset(['a-1'])).rejects.toThrow('process.exit(1)')
expect(errorSpy).toHaveBeenCalledWith('Error: Failed to delete')
})
})
})
-62
View File
@@ -1,62 +0,0 @@
import { getClient } from '../client'
export async function deleteAsset(assetIds: string[]) {
const isAllowed =
process.env.SHUMAI_ALLOW_DELETE === 'true' || process.env.SHUMAI_ALLOW_DELETE === '1'
if (!isAllowed) {
console.error('Error: Asset deletion is disabled in this environment.')
process.exit(1)
}
if (!assetIds || assetIds.length === 0) {
console.error('Error: Asset ID is required. Usage: shumai-cli delete <assetId>')
process.exit(1)
}
if (assetIds.length > 1) {
console.error('Error: Can only delete one asset at a time.')
process.exit(1)
}
const assetId = assetIds[0]
const client = getClient()
try {
// Inspect asset to determine whether it is a folder or file
const getRes = await client.api.folders[':folderId'].$get({
param: { folderId: assetId },
})
if (!getRes.ok) {
const err = (await getRes.json().catch(() => ({ error: 'Asset not found' }))) as {
error?: string
}
console.error(`Error: ${err.error || 'Asset not found'}`)
process.exit(1)
}
const asset = await getRes.json()
const isFolder = asset.type === 'folder'
const res = isFolder
? await client.api.folders.$delete({
json: { ids: [assetId] },
})
: await client.api.files.$delete({
json: { ids: [assetId] },
})
if (!res.ok) {
const err = (await res.json().catch(() => ({ error: 'Failed to delete asset' }))) as {
error?: string
}
console.error(`Error: ${err.error || 'Failed to delete asset'}`)
process.exit(1)
}
console.log(`Deleted asset ${assetId}`)
} catch (err) {
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
process.exit(1)
}
}
-87
View File
@@ -1,87 +0,0 @@
import { newTablePrinter, withTruncate } from '@shumai/tableprinter'
import type { AssetInfo } from '@shumai/dtos'
import { getClient } from '../client'
function formatSize(bytes: number): string {
if (bytes === 0) return '-'
const k = 1024
const sizes = ['B', 'KB', 'MB', 'GB', 'TB']
const i = Math.floor(Math.log(bytes) / Math.log(k))
return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i]
}
export async function ls(parentId: string) {
if (!parentId) {
console.error('Error: Parent ID (-p/--parent) is required.')
process.exit(1)
}
const client = getClient()
try {
const [foldersRes, filesRes] = await Promise.all([
client.api.folders[':folderId'].children.$get({
param: { folderId: parentId },
query: { assetType: 'folder', first: '200' },
}),
client.api.folders[':folderId'].children.$get({
param: { folderId: parentId },
query: { assetType: 'file', first: '200' },
}),
])
if (!foldersRes.ok) {
const err = (await foldersRes.json().catch(() => ({ error: 'Unknown error' }))) as {
error?: string
}
console.error(`Error: ${err.error || 'Failed to list folders'}`)
process.exit(1)
}
if (!filesRes.ok) {
const err = (await filesRes.json().catch(() => ({ error: 'Unknown error' }))) as {
error?: string
}
console.error(`Error: ${err.error || 'Failed to list files'}`)
process.exit(1)
}
const foldersData = await foldersRes.json()
const filesData = await filesRes.json()
const folders = foldersData.data || []
const files = filesData.data || []
const items = [
...folders.map((f: AssetInfo) => ({ ...f, typeDisplay: 'folder' as const })),
...files.map((f: AssetInfo) => ({ ...f, typeDisplay: 'file' as const })),
]
if (items.length === 0) {
console.log('No assets found in this folder.')
return
}
const isTty = process.stdout.isTTY
const maxWidth = process.stdout.columns || 80
const tp = newTablePrinter(process.stdout, isTty, maxWidth)
tp.addHeader(['ID', 'Name', 'Type', 'Size'])
for (const item of items) {
tp.addField(item.id || '', withTruncate(null))
tp.addField(item.name || '')
tp.addField(item.typeDisplay, withTruncate(null))
tp.addField(
item.typeDisplay === 'folder' ? '-' : formatSize(item.sizeByte || 0),
withTruncate(null),
)
tp.endRow()
}
tp.render()
} catch (err) {
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
process.exit(1)
}
}
-32
View File
@@ -1,32 +0,0 @@
import { getClient } from '../client'
export async function mkdir(name: string, parentId: string) {
if (!name) {
console.error('Error: Folder name is required.')
process.exit(1)
}
if (!parentId) {
console.error('Error: Parent ID (-p/--parent) is required.')
process.exit(1)
}
const client = getClient()
try {
const res = await client.api.folders.$post({
json: { name, parentId },
})
if (!res.ok) {
const err = (await res.json().catch(() => ({ error: 'Unknown error' }))) as { error?: string }
console.error(`Error: ${err.error || 'Failed to create folder'}`)
process.exit(1)
}
const created = await res.json()
console.log(`Created folder with ID: ${created.id}`)
} catch (err) {
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
process.exit(1)
}
}
-59
View File
@@ -1,59 +0,0 @@
import { getClient } from '../client'
export async function move(assetIds: string[], parentId: string) {
if (!assetIds || assetIds.length === 0) {
console.error(
'Error: At least one asset ID is required. Usage: shumai-cli move <assetId...> -p <parentId>',
)
process.exit(1)
}
if (!parentId) {
console.error('Error: Option -p/--parent <parentId> is required.')
process.exit(1)
}
const client = getClient()
try {
// Fetch destination folder to get its projectId
const parentRes = await client.api.folders[':folderId'].$get({
param: { folderId: parentId },
})
if (!parentRes.ok) {
const err = (await parentRes.json().catch(() => ({ error: 'Parent folder not found' }))) as {
error?: string
}
console.error(`Error: ${err.error || 'Parent folder not found'}`)
process.exit(1)
}
const parentInfo = await parentRes.json()
const projectId = parentInfo.projectId
if (!projectId) {
console.error('Error: Destination parent folder is not associated with a project.')
process.exit(1)
}
const res = await client.api.projects[':projectId'].reparent.$post({
param: { projectId },
json: {
assetIds,
newParentId: parentId,
},
})
if (!res.ok) {
const err = (await res.json().catch(() => ({ error: 'Failed to move assets' }))) as {
error?: string
}
console.error(`Error: ${err.error || 'Failed to move assets'}`)
process.exit(1)
}
console.log(`Moved ${assetIds.length} asset(s) to parent ${parentId}`)
} catch (err) {
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
process.exit(1)
}
}
-42
View File
@@ -1,42 +0,0 @@
import { newTablePrinter } from '@shumai/tableprinter'
import { getClient } from '../client'
export async function projectLs() {
const client = getClient()
try {
const res = await client.api.projects.$get({
query: { first: '200' },
})
if (!res.ok) {
const err = (await res.json().catch(() => ({ error: 'Unknown error' }))) as { error?: string }
console.error(`Error: ${err.error || 'Failed to list projects'}`)
process.exit(1)
}
const { data: projects } = await res.json()
if (projects.length === 0) {
console.log('No projects found.')
return
}
const isTty = process.stdout.isTTY
const maxWidth = process.stdout.columns || 80
const tp = newTablePrinter(process.stdout, isTty, maxWidth)
tp.addHeader(['ID', 'Name', 'Root Folder ID'])
for (const p of projects) {
tp.addField(p.id || '')
tp.addField(p.name || '')
tp.addField(p.rootFolder || '')
tp.endRow()
}
tp.render()
} catch (err) {
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
process.exit(1)
}
}
-55
View File
@@ -1,55 +0,0 @@
import { getClient } from '../client'
export async function rename(assetId: string, newName: string) {
if (!assetId) {
console.error('Error: Asset ID is required. Usage: shumai-cli rename <assetId> <newName>')
process.exit(1)
}
if (!newName) {
console.error('Error: New name is required. Usage: shumai-cli rename <assetId> <newName>')
process.exit(1)
}
const client = getClient()
try {
// Determine whether asset is a folder or a file
const getRes = await client.api.folders[':folderId'].$get({
param: { folderId: assetId },
})
if (!getRes.ok) {
const err = (await getRes.json().catch(() => ({ error: 'Asset not found' }))) as {
error?: string
}
console.error(`Error: ${err.error || 'Asset not found'}`)
process.exit(1)
}
const asset = await getRes.json()
const isFolder = asset.type === 'folder'
const updateRes = isFolder
? await client.api.folders[':folderId'].$put({
param: { folderId: assetId },
json: { name: newName },
})
: await client.api.files[':fileId'].$put({
param: { fileId: assetId },
json: { name: newName },
})
if (!updateRes.ok) {
const err = (await updateRes.json().catch(() => ({ error: 'Failed to rename asset' }))) as {
error?: string
}
console.error(`Error: ${err.error || 'Failed to rename asset'}`)
process.exit(1)
}
console.log(`Renamed asset ${assetId} to "${newName}"`)
} catch (err) {
console.error('Error connecting to API server:', err instanceof Error ? err.message : err)
process.exit(1)
}
}
+7 -138
View File
@@ -1,140 +1,9 @@
import { projectLs } from './commands/project'
import { ls } from './commands/ls'
import { mkdir } from './commands/mkdir'
import { upload } from './commands/upload'
import { createVersion } from './commands/create-version'
import { rename } from './commands/rename'
import { move } from './commands/move'
import { deleteAsset } from './commands/delete'
import { formatCliError } from './operations/errors'
import { createProgram } from './program'
function printHelp() {
console.log(`
Usage: shumai-cli <command> [arguments] [options]
Commands:
project ls List all projects (returns id, name, root folder id)
ls -p <parentId> List direct children of a parent folder (returns id, name, type, size)
mkdir <name> -p <parentId> Create a new folder in a parent folder
upload <path> -p <parentId> Upload a local file or folder to a parent folder
create-version <path> -p <id> Create a new version of an existing file or version stack
rename <assetId> <newName> Rename an existing file or folder
move <assetIds...> -p <target> Move one or more assets to a destination parent folder (alias: mv)
delete <assetId> Delete a single file or folder (alias: rm)
Options:
-p, --parent <id> The parent folder/asset ID (required for ls, mkdir, upload, create-version, move)
-h, --help Show help details
`)
}
async function main() {
const args = process.argv.slice(2)
if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
printHelp()
process.exit(0)
}
const cmd = args[0]
let parentId = ''
const parentIdx = args.findIndex((a) => a === '-p' || a === '--parent')
if (parentIdx !== -1 && parentIdx + 1 < args.length) {
parentId = args[parentIdx + 1]
}
const cleanArgs: string[] = []
for (let i = 0; i < args.length; i++) {
if (args[i] === '-p' || args[i] === '--parent') {
i++
} else {
cleanArgs.push(args[i])
}
}
if (cmd === 'project' && cleanArgs[1] === 'ls') {
await projectLs()
} else if (cmd === 'ls') {
if (!parentId) {
console.error('Error: Option -p/--parent <parentId> is required.')
process.exit(1)
}
await ls(parentId)
} else if (cmd === 'mkdir') {
const name = cleanArgs[1]
if (!name) {
console.error(
'Error: Folder name is required. Usage: shumai-cli mkdir <folderName> -p <parentId>',
)
process.exit(1)
}
if (!parentId) {
console.error('Error: Option -p/--parent <parentId> is required.')
process.exit(1)
}
await mkdir(name, parentId)
} else if (cmd === 'upload') {
const localPath = cleanArgs[1]
if (!localPath) {
console.error(
'Error: File/folder path is required. Usage: shumai-cli upload <localPath> -p <parentId>',
)
process.exit(1)
}
if (!parentId) {
console.error('Error: Option -p/--parent <parentId> is required.')
process.exit(1)
}
await upload(localPath, parentId)
} else if (cmd === 'create-version') {
const localPath = cleanArgs[1]
if (!localPath) {
console.error(
'Error: Local file path is required. Usage: shumai-cli create-version <localPath> -p <parentAssetId>',
)
process.exit(1)
}
if (!parentId) {
console.error('Error: Option -p/--parent <parentAssetId> is required.')
process.exit(1)
}
await createVersion(localPath, parentId)
} else if (cmd === 'rename') {
const assetId = cleanArgs[1]
const newName = cleanArgs[2]
if (!assetId || !newName) {
console.error(
'Error: Asset ID and new name are required. Usage: shumai-cli rename <assetId> <newName>',
)
process.exit(1)
}
await rename(assetId, newName)
} else if (cmd === 'move' || cmd === 'mv') {
const assetIds = cleanArgs.slice(1)
if (assetIds.length === 0) {
console.error(
'Error: At least one asset ID is required. Usage: shumai-cli move <assetId...> -p <parentId>',
)
process.exit(1)
}
if (!parentId) {
console.error('Error: Option -p/--parent <parentId> is required.')
process.exit(1)
}
await move(assetIds, parentId)
} else if (cmd === 'delete' || cmd === 'rm') {
const assetIds = cleanArgs.slice(1)
if (assetIds.length === 0) {
console.error('Error: Asset ID is required. Usage: shumai-cli delete <assetId>')
process.exit(1)
}
await deleteAsset(assetIds)
} else {
console.error(`Error: Unknown command "${cmd}". Run "shumai-cli --help" for usage.`)
createProgram()
.parseAsync(process.argv)
.catch((err: unknown) => {
console.error(formatCliError(err))
process.exit(1)
}
}
main().catch((err) => {
console.error('Unexpected error:', err)
process.exit(1)
})
})
@@ -0,0 +1,78 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { createFolder, listProjects } from '@shumai/operations'
import { callOperation } from './call-operation'
import { CliError } from './errors'
describe('callOperation', () => {
const env = { ...process.env }
const fetchMock = vi.fn<typeof fetch>()
beforeEach(() => {
process.env.SHUMAI_API_SERVER = 'http://shumai.test/'
process.env.SHUMAI_API_KEY = 'shumai_token'
vi.stubGlobal('fetch', fetchMock)
})
afterEach(() => {
process.env = { ...env }
vi.unstubAllGlobals()
fetchMock.mockReset()
})
const json = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), {
status,
headers: { 'Content-Type': 'application/json' },
})
it('posts the input to /api/ops/:name with the token and CLI attribution', async () => {
const folder = { id: 'f1', name: 'Renders', type: 'folder', size: 0, projectId: 'p1' }
fetchMock.mockResolvedValue(json(folder))
const output = await callOperation(createFolder, { parent: 'root', name: 'Renders' })
expect(output).toEqual(folder)
const [url, init] = fetchMock.mock.calls[0]
expect(url).toBe('http://shumai.test/api/ops/create_folder')
expect(init).toMatchObject({
method: 'POST',
headers: {
Authorization: 'Bearer shumai_token',
'Content-Type': 'application/json',
'x-shumai-client': 'cli',
},
body: JSON.stringify({ parent: 'root', name: 'Renders' }),
})
})
it('throws the server error message', async () => {
fetchMock.mockResolvedValue(json({ error: 'User is not a member of the team' }, 403))
await expect(callOperation(listProjects, {})).rejects.toEqual(
new CliError('User is not a member of the team'),
)
})
it('falls back to the status when the error body is not JSON', async () => {
fetchMock.mockResolvedValue(new Response('Bad gateway', { status: 502 }))
await expect(callOperation(listProjects, {})).rejects.toThrow('Request failed with status 502')
})
it('reports connection failures', async () => {
fetchMock.mockRejectedValue(new TypeError('fetch failed'))
await expect(callOperation(listProjects, {})).rejects.toMatchObject({
message: 'Error connecting to API server: fetch failed',
prefixed: true,
})
})
it('rejects responses that do not match the output schema', async () => {
fetchMock.mockResolvedValue(json({ unexpected: true }))
await expect(callOperation(listProjects, {})).rejects.toThrow(
'Unexpected response from server for list_projects',
)
})
})
+55
View File
@@ -0,0 +1,55 @@
import type { z } from 'zod'
import type { AnyOperationDefinition } from '@shumai/operations'
import { getCliConfig } from '../client'
import { CliError } from './errors'
/** Header that attributes invocations to the CLI (`via: cli`) in audit logs. */
const CLIENT_HEADER = 'x-shumai-client'
/** Signature used by generated commands, which only see type-erased definitions. */
export type CallOperation = (
definition: AnyOperationDefinition,
input: Record<string, unknown>,
) => Promise<unknown>
/** Runs an Operation on the server via `POST /api/ops/:name`. */
export async function callOperation<TDef extends AnyOperationDefinition>(
definition: TDef,
input: z.output<TDef['input']>,
): Promise<z.output<TDef['output']>> {
const { apiServer, apiKey } = getCliConfig()
let res: Response
try {
res = await fetch(`${apiServer}/api/ops/${definition.name}`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
[CLIENT_HEADER]: 'cli',
},
body: JSON.stringify(input),
})
} catch (err) {
throw new CliError(
`Error connecting to API server: ${err instanceof Error ? err.message : String(err)}`,
{ prefixed: true },
)
}
const body: unknown = await res.json().catch(() => undefined)
if (!res.ok) {
const message =
body && typeof body === 'object' && 'error' in body && typeof body.error === 'string'
? body.error
: `Request failed with status ${res.status}`
throw new CliError(message)
}
const parsed = definition.output.safeParse(body)
if (!parsed.success) {
throw new CliError(`Unexpected response from server for ${definition.name}`)
}
// safeParse on the generic schema type loses the concrete shape; the schema guarantees it.
return parsed.data as z.output<TDef['output']>
}
+18
View File
@@ -0,0 +1,18 @@
/** An expected failure, printed as `Error: <message>` with exit code 1. */
export class CliError extends Error {
/** When true, the message already carries its own prefix and is printed as-is. */
readonly prefixed: boolean
constructor(message: string, options: { prefixed?: boolean } = {}) {
super(message)
this.name = 'CliError'
this.prefixed = options.prefixed ?? false
}
}
export function formatCliError(err: unknown): string {
if (err instanceof CliError) {
return err.prefixed ? err.message : `Error: ${err.message}`
}
return `Unexpected error: ${err instanceof Error ? err.message : String(err)}`
}
@@ -0,0 +1,103 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import * as path from 'node:path'
import type { DownloadAssetOutput } from '@shumai/operations'
import { CliError } from '../errors'
import { downloadAssetExtension, safeFileName, uniquePath } from './download-asset'
const output: DownloadAssetOutput = {
files: [
{
assetId: 'a-1',
name: 'clip.mp4',
kind: 'proxy',
size: 2048,
mimeType: 'video/mp4',
url: 'https://files.example/a-1',
},
{
assetId: 'a-2',
name: 'clip.mp4',
kind: 'original',
size: 10,
mimeType: 'video/mp4',
url: 'https://files.example/a-2',
},
],
}
describe('download CLI extension', () => {
let dir: string
let written: string
beforeEach(async () => {
dir = await mkdtemp(path.join(tmpdir(), 'shumai-cli-download-'))
written = ''
vi.stubGlobal(
'fetch',
vi.fn(async (url: string) => new Response(`bytes of ${url}`, { status: 200 })),
)
})
afterEach(async () => {
vi.unstubAllGlobals()
await rm(dir, { recursive: true, force: true })
})
const o = () => ({ out: { write: (s: string) => void (written += s) }, isTty: true, columns: 80 })
it('saves every file, numbering names that are already taken', async () => {
await writeFile(path.join(dir, 'clip.mp4'), 'existing')
await downloadAssetExtension.present(output, { opts: { out: dir }, json: false, output: o() })
expect((await readdir(dir)).sort()).toEqual(['clip (2).mp4', 'clip (3).mp4', 'clip.mp4'])
expect(await readFile(path.join(dir, 'clip.mp4'), 'utf8')).toBe('existing')
expect(await readFile(path.join(dir, 'clip (2).mp4'), 'utf8')).toBe(
'bytes of https://files.example/a-1',
)
expect(written).toBe(
`Saved ${path.join(dir, 'clip (2).mp4')} (2 KB, proxy)\nSaved ${path.join(dir, 'clip (3).mp4')} (10 B, original)\n`,
)
})
it('creates the folder and prints JSON with the saved paths', async () => {
const out = path.join(dir, 'nested', 'files')
await downloadAssetExtension.present(output, { opts: { out }, json: true, output: o() })
const printed = JSON.parse(written) as { files: Array<{ path: string; url: string }> }
expect(printed.files.map((f) => f.path)).toEqual([
path.join(out, 'clip.mp4'),
path.join(out, 'clip (2).mp4'),
])
expect(printed.files[0].url).toBe('https://files.example/a-1')
})
it('fails clearly when a download fails', async () => {
vi.stubGlobal(
'fetch',
vi.fn(async () => new Response('gone', { status: 403 })),
)
await expect(
downloadAssetExtension.present(output, { opts: { out: dir }, json: false, output: o() }),
).rejects.toThrow(new CliError('Failed to download "clip.mp4" (status 403).'))
})
it('keeps file names inside the target folder', () => {
expect(safeFileName('../../etc/passwd')).toBe('_.._etc_passwd')
expect(safeFileName('a\\b.txt')).toBe('a_b.txt')
expect(safeFileName('...')).toBe('file')
const taken = new Set<string>()
expect(uniquePath(dir, 'notes', taken)).toBe(path.join(dir, 'notes'))
expect(uniquePath(dir, 'notes', taken)).toBe(path.join(dir, 'notes (2)'))
})
it('maps --original to proxy false', () => {
expect(downloadAssetExtension.toInput!({ assetIds: ['a'] }, { original: true })).toEqual({
assetIds: ['a'],
proxy: false,
})
expect(downloadAssetExtension.toInput!({ assetIds: ['a'] }, {})).toEqual({ assetIds: ['a'] })
})
})
@@ -0,0 +1,58 @@
import { existsSync } from 'node:fs'
import { mkdir } from 'node:fs/promises'
import * as path from 'node:path'
import { Option } from 'commander'
import type { DownloadAssetOutput } from '@shumai/operations'
import type { CliCommandExtension } from '../generate'
import { formatSize } from '../render'
import { saveUrlToFile } from './save-url'
/** A file name that is safe to create inside the target folder (no paths or control chars). */
export function safeFileName(name: string): string {
const safe = name
// eslint-disable-next-line no-control-regex
.replace(/[\x00-\x1f\x7f/\\]/g, '_')
.replace(/^[\s.]+|[\s.]+$/g, '')
return safe || 'file'
}
/** `name.ext`, or `name (2).ext`, `name (3).ext`, ... if taken on disk or in this download. */
export function uniquePath(dir: string, name: string, taken: Set<string>): string {
const ext = path.extname(name)
const stem = ext ? name.slice(0, -ext.length) : name
for (let n = 1; ; n++) {
const candidate = path.join(dir, n === 1 ? name : `${stem} (${n})${ext}`)
if (!taken.has(candidate) && !existsSync(candidate)) {
taken.add(candidate)
return candidate
}
}
}
/** `download`: saves each file into `--out` (the current folder by default). */
export const downloadAssetExtension: CliCommandExtension = {
options: () => [
new Option('-o, --out <dir>', 'Folder to save the files in.').default('.'),
new Option('--original', 'Download the original uploaded files instead of the web previews.'),
],
toInput: (input, opts) => (opts.original === true ? { ...input, proxy: false } : input),
async present(raw, { opts, json, output: o }) {
const output = raw as DownloadAssetOutput
const dir = typeof opts.out === 'string' ? opts.out : '.'
await mkdir(dir, { recursive: true })
const taken = new Set<string>()
const saved: string[] = []
for (const file of output.files) {
const filePath = uniquePath(dir, safeFileName(file.name), taken)
await saveUrlToFile(file.url, filePath, file.name)
saved.push(filePath)
if (!json) {
o.out.write(`Saved ${filePath} (${formatSize(file.size)}, ${file.kind})\n`)
}
}
if (json) {
const files = output.files.map((file, i) => ({ ...file, path: saved[i] }))
o.out.write(`${JSON.stringify({ files }, null, 2)}\n`)
}
},
}
@@ -0,0 +1,10 @@
import type { CliCommandExtension } from '../generate'
import { downloadAssetExtension } from './download-asset'
import { getAssetRenderExtension, readAssetExtension } from './read-asset'
/** CLI-specific behavior for generated commands, by Operation name. */
export const cliExtensions: ReadonlyMap<string, CliCommandExtension> = new Map([
['read_asset', readAssetExtension],
['get_asset_render', getAssetRenderExtension],
['download_asset', downloadAssetExtension],
])
@@ -0,0 +1,98 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { mkdtemp, readFile, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import * as path from 'node:path'
import type { AssetReadOutput } from '@shumai/operations'
import { CliError } from '../errors'
import { downloadImages, imageFileName, readAssetExtension } from './read-asset'
const output: AssetReadOutput = {
status: 'ready',
summary: 'Rendered 2 page(s) of "deck.pdf" (Pages 1 to 2):',
asset: { id: 'doc-1', name: 'deck.pdf', kind: 'document', mediaType: 'application/pdf' },
details: [],
images: [
{ label: 'Page 1', mimeType: 'image/webp', url: 'https://files.example/p1' },
{ label: 'Page 2', mimeType: 'image/png', url: 'https://files.example/p2' },
],
}
describe('read / render CLI extension', () => {
let dir: string
let written: string
beforeEach(async () => {
dir = await mkdtemp(path.join(tmpdir(), 'shumai-cli-read-'))
written = ''
vi.stubGlobal(
'fetch',
vi.fn(async (url: string) => new Response(`bytes of ${url}`, { status: 200 })),
)
})
afterEach(async () => {
vi.unstubAllGlobals()
await rm(dir, { recursive: true, force: true })
})
const o = () => ({ out: { write: (s: string) => void (written += s) }, isTty: true, columns: 80 })
it('names files after the asset, position, and label', () => {
expect(imageFileName('vid-1', 0, { label: 'Frame at 2.5s', mimeType: 'image/webp' })).toBe(
'vid-1-1-frame-at-2.5s.webp',
)
expect(imageFileName('m-1', 3, { label: 'View at 90°', mimeType: 'image/jpeg' })).toBe(
'm-1-4-view-at-90.jpg',
)
})
it('downloads every image with --out and prints the saved paths', async () => {
const out = path.join(dir, 'pages')
await readAssetExtension.present(output, { opts: { out }, json: false, output: o() })
const first = path.join(out, 'doc-1-1-page-1.webp')
const second = path.join(out, 'doc-1-2-page-2.png')
expect(await readFile(first, 'utf8')).toBe('bytes of https://files.example/p1')
expect(await readFile(second, 'utf8')).toBe('bytes of https://files.example/p2')
expect(written).toBe(`${output.summary}\n- Page 1: ${first}\n- Page 2: ${second}\n`)
})
it('adds the saved path to each image in --json mode', async () => {
await readAssetExtension.present(output, { opts: { out: dir }, json: true, output: o() })
const printed = JSON.parse(written) as { images: Array<{ path: string }> }
expect(printed.images.map((i) => i.path)).toEqual([
path.join(dir, 'doc-1-1-page-1.webp'),
path.join(dir, 'doc-1-2-page-2.png'),
])
})
it('fails clearly when a download fails', async () => {
vi.stubGlobal(
'fetch',
vi.fn(async () => new Response('gone', { status: 403 })),
)
await expect(downloadImages(output, dir)).rejects.toThrow(
new CliError('Failed to download "Page 1" (status 403).'),
)
})
it('does not download anything for a pending render', async () => {
await readAssetExtension.present(
{ ...output, status: 'pending', images: [], taskId: 't-1', retryAfterSeconds: 5 },
{ opts: { out: dir }, json: false, output: o() },
)
expect(fetch).not.toHaveBeenCalled()
expect(written).toContain(`shumai-cli render t-1 --out ${JSON.stringify(dir)}`)
})
it('maps --no-wait to maxWaitSeconds 0', () => {
expect(readAssetExtension.toInput!({ assetId: 'a' }, { wait: false })).toEqual({
assetId: 'a',
maxWaitSeconds: 0,
})
expect(readAssetExtension.toInput!({ assetId: 'a' }, { wait: true })).toEqual({
assetId: 'a',
})
})
})
@@ -0,0 +1,116 @@
import { mkdir } from 'node:fs/promises'
import * as path from 'node:path'
import { Option } from 'commander'
import type { AssetReadOutput } from '@shumai/operations'
import { CliError } from '../errors'
import { saveUrlToFile } from './save-url'
import type { CliCommandExtension } from '../generate'
import type { Output } from '../render'
const EXTENSIONS: Record<string, string> = {
'image/webp': 'webp',
'image/png': 'png',
'image/jpeg': 'jpg',
'image/gif': 'gif',
'image/avif': 'avif',
}
function slug(value: string): string {
return (
value
.toLowerCase()
.replace(/[^a-z0-9.]+/g, '-')
.replace(/^-+|-+$/g, '') || 'image'
)
}
/** File name for the n-th image of a read, e.g. `01ABC-1-frame-at-2s.webp`. */
export function imageFileName(
assetId: string,
index: number,
image: AssetReadOutput['images'][number],
): string {
const ext = EXTENSIONS[image.mimeType] ?? image.mimeType.split('/')[1] ?? 'bin'
return `${assetId}-${index + 1}-${slug(image.label).replace(/\.+$/, '')}.${ext}`
}
/** Downloads every image of a ready read into `dir`; returns the saved paths in order. */
export async function downloadImages(output: AssetReadOutput, dir: string): Promise<string[]> {
await mkdir(dir, { recursive: true })
const saved: string[] = []
for (const [index, image] of output.images.entries()) {
if (!image.url) {
throw new CliError(`No download link was returned for "${image.label}".`)
}
const filePath = path.join(dir, imageFileName(output.asset.id, index, image))
await saveUrlToFile(image.url, filePath, image.label)
saved.push(filePath)
}
return saved
}
function renderCommand(taskId: string, out: unknown): string {
const outArg = typeof out === 'string' ? ` --out ${JSON.stringify(out)}` : ''
return `shumai-cli render ${taskId}${outArg}`
}
function writeReady(output: AssetReadOutput, paths: string[] | null, o: Output): void {
const lines = [output.summary, ...output.details]
output.images.forEach((image, i) => {
lines.push(`- ${image.label}: ${paths ? paths[i] : (image.url ?? '')}`)
})
o.out.write(`${lines.join('\n')}\n`)
if (output.text) {
o.out.write(`\n${output.text.content}`)
if (!output.text.content.endsWith('\n')) o.out.write('\n')
if (output.text.truncated) {
o.out.write(
`\n[Content truncated: showing the first part of a ${output.text.size}-byte file. Run \`shumai-cli download ${output.asset.id}\` to get the whole file.]\n`,
)
}
}
}
/**
* `read` and `render`: images are printed as links (valid for about an hour) or downloaded
* with `--out`; a render that takes longer than the wait prints the `render` command to run.
*/
function readExtension(noWaitHelp: string): CliCommandExtension {
return {
options: () => [
new Option('-o, --out <dir>', 'Download the images into this folder and print their paths.'),
new Option('--no-wait', noWaitHelp),
],
toInput: (input, opts) => (opts.wait === false ? { ...input, maxWaitSeconds: 0 } : input),
async present(raw, { opts, json, output: o }) {
const output = raw as AssetReadOutput
if (output.status === 'pending') {
if (json) {
o.out.write(`${JSON.stringify(output, null, 2)}\n`)
return
}
o.out.write(
`${output.summary}\nRun this to get the result: ${renderCommand(output.taskId ?? '', opts.out)}\n`,
)
return
}
const paths = typeof opts.out === 'string' ? await downloadImages(output, opts.out) : null
if (json) {
const images = output.images.map((image, i) =>
paths ? { ...image, path: paths[i] } : image,
)
o.out.write(`${JSON.stringify({ ...output, images }, null, 2)}\n`)
return
}
writeReady(output, paths, o)
},
}
}
export const readAssetExtension = readExtension(
'Return right away with a task ID if the asset needs rendering.',
)
export const getAssetRenderExtension = readExtension(
'Check once and return right away if the render is still running.',
)
@@ -0,0 +1,32 @@
import { createWriteStream } from 'node:fs'
import { rm } from 'node:fs/promises'
import { Readable } from 'node:stream'
import { pipeline } from 'node:stream/promises'
import type { ReadableStream as WebReadableStream } from 'node:stream/web'
import { CliError } from '../errors'
/** Streams a download link to `filePath` (large files never sit in memory). */
export async function saveUrlToFile(url: string, filePath: string, label: string): Promise<void> {
let res: Response
try {
res = await fetch(url)
} catch (err) {
throw new CliError(
`Failed to download "${label}": ${err instanceof Error ? err.message : String(err)}`,
)
}
if (!res.ok || !res.body) {
throw new CliError(`Failed to download "${label}" (status ${res.status}).`)
}
try {
await pipeline(
Readable.fromWeb(res.body as unknown as WebReadableStream<Uint8Array>),
createWriteStream(filePath),
)
} catch (err) {
await rm(filePath, { force: true })
throw new CliError(
`Failed to save "${label}" to ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
)
}
}
+269
View File
@@ -0,0 +1,269 @@
import { Command, InvalidArgumentError, Option } from 'commander'
import { z } from 'zod'
import type { AnyOperationDefinition } from '@shumai/operations'
import type { CallOperation } from './call-operation'
import { CliError } from './errors'
import { renderOutput, type Output } from './render'
/**
* CLI-specific behavior for one Operation's command, for things a definition can't describe
* (it must stay free of I/O): extra options, input mapping, and output that downloads files.
*/
export interface CliCommandExtension {
/** Extra options only the CLI has; their values are passed to `toInput` and `present`. */
options?(): Option[]
/** Adjust the Operation input using the command's options. */
toInput?(input: Record<string, unknown>, opts: Record<string, unknown>): Record<string, unknown>
/** Writes the output, including in `--json` mode. Replaces the default rendering. */
present(
output: unknown,
ctx: { opts: Record<string, unknown>; json: boolean; output: Output },
): Promise<void>
}
export interface GenerateDeps {
callOperation: CallOperation
output: Output
/** Whether destructive Operations are allowed (SHUMAI_ALLOW_DELETE). */
allowDestructive: () => boolean
/** CLI extensions by Operation name. */
extensions?: ReadonlyMap<string, CliCommandExtension>
}
type FieldKind =
| { type: 'string' }
| { type: 'number' }
| { type: 'boolean' }
| { type: 'enum'; values: string[] }
| { type: 'array' }
/** A key/value object (`z.record`), passed as a JSON object. */
| { type: 'json' }
interface FieldInfo {
name: string
kind: FieldKind
required: boolean
description: string
}
/** Strip optional/nullable/default wrappers to find the field's base schema. */
function unwrap(schema: z.ZodType): z.ZodType {
let current = schema
while (
current instanceof z.ZodOptional ||
current instanceof z.ZodNullable ||
current instanceof z.ZodDefault
) {
current = current.unwrap() as z.ZodType
}
return current
}
function describeField(definition: AnyOperationDefinition, name: string): FieldInfo {
return describeSchema(definition, name, definition.input.shape[name] as z.ZodType)
}
function describeSchema(
definition: AnyOperationDefinition,
name: string,
schema: z.ZodType,
): FieldInfo {
const base = unwrap(schema)
let kind: FieldKind
if (base instanceof z.ZodNumber) kind = { type: 'number' }
else if (base instanceof z.ZodBoolean) kind = { type: 'boolean' }
else if (base instanceof z.ZodEnum) kind = { type: 'enum', values: base.options.map(String) }
else if (base instanceof z.ZodArray) kind = { type: 'array' }
else if (base instanceof z.ZodString) kind = { type: 'string' }
else if (base instanceof z.ZodRecord) kind = { type: 'json' }
else {
throw new Error(`${definition.name}.${name}: unsupported input type for the CLI`)
}
return {
name,
kind,
required: !schema.safeParse(undefined).success,
description: schema.description ?? base.description ?? '',
}
}
/**
* Input errors name the input path (e.g. `videoConfig.end`). For flattened fields, name the
* flag the user typed instead (e.g. `--video-end`).
*/
function formatInputError(
error: z.ZodError,
options: ReadonlyArray<{ path: [string] | [string, string]; option: Option }>,
): string {
const flagFor = (path: PropertyKey[]): string | undefined =>
options.find((o) => o.path.length === 2 && o.path[0] === path[0] && o.path[1] === path[1])
?.option.long
if (!error.issues.some((issue) => flagFor(issue.path))) {
return z.prettifyError(error)
}
return error.issues
.map((issue) => {
const flag = flagFor(issue.path)
return flag ? `✖ ${flag}: ${issue.message}` : z.prettifyError(new z.ZodError([issue]))
})
.join('\n')
}
function parseNumber(value: string): number {
const parsed = Number(value)
if (value.trim() === '' || Number.isNaN(parsed)) {
throw new InvalidArgumentError('Not a number.')
}
return parsed
}
function parseJsonObject(value: string): Record<string, unknown> {
let parsed: unknown
try {
parsed = JSON.parse(value)
} catch {
throw new InvalidArgumentError('Not valid JSON.')
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw new InvalidArgumentError('Expected a JSON object, e.g. \'{"key": "value"}\'.')
}
return parsed as Record<string, unknown>
}
function kebab(name: string): string {
return name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
}
/** Find or create the subcommand path, e.g. `project` for `project ls`. */
function ensureParent(program: Command, path: readonly string[]): Command {
let parent = program
for (const segment of path) {
parent =
parent.commands.find((c) => c.name() === segment) ??
parent.command(segment).description(`Manage ${segment}s.`)
}
return parent
}
/** Registers one command for each definition with a `cli` spec. */
export function registerOperationCommands(
program: Command,
definitions: readonly AnyOperationDefinition[],
deps: GenerateDeps,
): void {
for (const definition of definitions) {
const cli = definition.cli
if (!cli || !definition.surfaces.includes('cli')) continue
const parent = ensureParent(program, cli.command.slice(0, -1))
const cmd = parent
.command(cli.command[cli.command.length - 1])
.description(cli.description ?? definition.description)
if (cli.aliases) cmd.aliases([...cli.aliases])
const positional = (cli.positional ?? []).map((name) => describeField(definition, name))
for (const field of positional) {
const placeholder = field.kind.type === 'array' ? `${field.name}...` : field.name
cmd.argument(field.required ? `<${placeholder}>` : `[${placeholder}]`, field.description)
}
const positionalNames = new Set(positional.map((f) => f.name))
const omitted = new Set<string>(cli.omit ?? [])
const flatten = (cli.flatten ?? {}) as Record<string, string | undefined>
// `path` is where the value goes in the input: `[field]` or `[field, subField]`.
const options: Array<{ path: [string] | [string, string]; option: Option }> = []
const addOption = (
path: [string] | [string, string],
field: FieldInfo,
spellings: readonly string[],
) => {
const valueHint =
field.kind.type === 'boolean'
? ''
: field.kind.type === 'array'
? ` <${field.name}...>`
: field.kind.type === 'json'
? ` <json>`
: ` <${field.name}>`
const option = new Option(`${spellings.join(', ')}${valueHint}`, field.description)
if (field.kind.type === 'number') option.argParser(parseNumber)
if (field.kind.type === 'json') option.argParser(parseJsonObject)
if (field.kind.type === 'enum') option.choices(field.kind.values)
if (field.required) option.makeOptionMandatory()
cmd.addOption(option)
options.push({ path, option })
return option
}
for (const name of Object.keys(definition.input.shape)) {
if (positionalNames.has(name) || omitted.has(name)) continue
const prefix = flatten[name]
if (prefix !== undefined) {
const schema = definition.input.shape[name] as z.ZodType
const base = unwrap(schema)
if (!(base instanceof z.ZodObject)) {
throw new Error(`${definition.name}.${name}: only object fields can be flattened`)
}
const parentRequired = !schema.safeParse(undefined).success
for (const [subName, subSchema] of Object.entries(base.shape)) {
const field = describeSchema(definition, `${name}.${subName}`, subSchema as z.ZodType)
field.name = subName
// Sub-fields are only mandatory when the object itself is.
field.required = parentRequired && field.required
const flag = prefix ? `--${prefix}-${kebab(subName)}` : `--${kebab(subName)}`
addOption([name, subName], field, [flag])
}
continue
}
const field = describeField(definition, name)
const option = addOption([name], field, cli.flags?.[name] ?? [`--${kebab(name)}`])
const cliDefault = (cli.defaults as Record<string, unknown> | undefined)?.[name]
if (cliDefault !== undefined) option.default(cliDefault)
}
const extension = deps.extensions?.get(definition.name)
for (const option of extension?.options?.() ?? []) cmd.addOption(option)
cmd.action(async (...args: unknown[]) => {
const command = args[args.length - 1] as Command
const input: Record<string, unknown> = { ...cli.defaults }
positional.forEach((field, i) => {
if (args[i] !== undefined) input[field.name] = args[i]
})
const opts = command.opts()
for (const { path, option } of options) {
const value = opts[option.attributeName()]
if (value === undefined) continue
if (path.length === 1) {
input[path[0]] = value
} else {
const parent = (input[path[0]] ?? {}) as Record<string, unknown>
input[path[0]] = { ...parent, [path[1]]: value }
}
}
if (definition.annotations.destructive && !deps.allowDestructive()) {
throw new CliError(
`${definition.title} is disabled in this environment. Set SHUMAI_ALLOW_DELETE=true to enable it.`,
)
}
const parsed = definition.input.safeParse(
extension?.toInput ? extension.toInput(input, opts) : input,
)
if (!parsed.success) {
throw new CliError(formatInputError(parsed.error, options))
}
const output = await deps.callOperation(definition, parsed.data)
const json = Boolean(command.optsWithGlobals().json)
if (extension) {
await extension.present(output, { opts, json, output: deps.output })
} else if (json) {
deps.output.out.write(`${JSON.stringify(output, null, 2)}\n`)
} else {
renderOutput(definition, output, deps.output)
}
})
}
}
+68
View File
@@ -0,0 +1,68 @@
import { describe, expect, it } from 'vitest'
import { z } from 'zod'
import { defineOperation, listAssets, renameAsset } from '@shumai/operations'
import { formatSize, renderOutput, type Output } from './render'
function capture(isTty = true): Output & { text: () => string } {
let text = ''
return { out: { write: (s) => void (text += s) }, isTty, columns: 120, text: () => text }
}
const page = {
data: [{ id: 'd1', name: 'Renders', type: 'folder', size: 0, projectId: 'p' }],
pageInfo: { hasNextPage: true, endCursor: 'CUR' },
total: 2,
}
describe('renderOutput', () => {
it('shows the next-page cursor only on a terminal', () => {
const tty = capture(true)
renderOutput(listAssets, page, tty)
expect(tty.text()).toContain('Next page: --after CUR')
const piped = capture(false)
renderOutput(listAssets, page, piped)
expect(piped.text()).toBe('d1\tRenders\tfolder\t-\n')
})
it('uses the definition formatter when there is no table renderer', () => {
const o = capture()
renderOutput(renameAsset, { id: 'a1', name: 'new', type: 'file', size: 1, projectId: null }, o)
expect(o.text()).toBe('Renamed asset a1 to "new"\n')
})
it('falls back to tables for lists and key/value lines for objects', () => {
const generic = defineOperation({
name: 'generic_thing',
title: 'Generic',
description: 'Generic output.',
input: z.object({}),
output: z.unknown(),
surfaces: ['agent'],
annotations: { readOnly: true, destructive: false },
})
const list = capture(false)
renderOutput(generic, { data: [{ id: 'x', tags: ['a'] }] }, list)
expect(list.text()).toBe('x\t["a"]\n')
const empty = capture()
renderOutput(generic, [], empty)
expect(empty.text()).toBe('No results.\n')
const object = capture()
renderOutput(generic, { id: 'x', count: 2, note: null }, object)
expect(object.text()).toBe('id: x\ncount: 2\nnote: \n')
})
})
describe('formatSize', () => {
it.each([
[0, '-'],
[512, '512 B'],
[1536, '1.5 KB'],
[5 * 1024 * 1024, '5 MB'],
])('formats %d bytes as %s', (bytes, expected) => {
expect(formatSize(bytes)).toBe(expected)
})
})
+121
View File
@@ -0,0 +1,121 @@
import { newTablePrinter, withTruncate, type Writer } from '@shumai/tableprinter'
import type {
AnyOperationDefinition,
AssetSummary,
PageInfo,
ProjectSummary,
} from '@shumai/operations'
export interface Output {
out: Writer
isTty: boolean
columns: number
}
export function formatSize(bytes: number): string {
if (bytes === 0) return '-'
const k = 1024
const sizes = ['B', 'KB', 'MB', 'GB', 'TB']
const i = Math.floor(Math.log(bytes) / Math.log(k))
return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i]
}
function renderAssets(output: { data: AssetSummary[]; pageInfo: PageInfo }, o: Output): void {
if (output.data.length === 0) {
o.out.write('No assets found in this folder.\n')
return
}
// Folders first, as in the file browser's default listing
const items = [...output.data].sort(
(a, b) => Number(b.type === 'folder') - Number(a.type === 'folder'),
)
const tp = newTablePrinter(o.out, o.isTty, o.columns)
tp.addHeader(['ID', 'Name', 'Type', 'Size'])
for (const item of items) {
const isFolder = item.type === 'folder'
tp.addField(item.id, withTruncate(null))
tp.addField(item.name)
tp.addField(isFolder ? 'folder' : 'file', withTruncate(null))
tp.addField(isFolder ? '-' : formatSize(item.size), withTruncate(null))
tp.endRow()
}
tp.render()
// Piped output is TSV for scripts (use --json for pagination metadata); keep it clean.
if (o.isTty && output.pageInfo.hasNextPage && output.pageInfo.endCursor) {
o.out.write(`\nMore assets available. Next page: --after ${output.pageInfo.endCursor}\n`)
}
}
function renderProjects(output: { data: ProjectSummary[] }, o: Output): void {
if (output.data.length === 0) {
o.out.write('No projects found.\n')
return
}
const tp = newTablePrinter(o.out, o.isTty, o.columns)
tp.addHeader(['ID', 'Name', 'Root Folder ID'])
for (const p of output.data) {
tp.addField(p.id)
tp.addField(p.name)
tp.addField(p.rootFolderId ?? '')
tp.endRow()
}
tp.render()
}
/** Table renderers for list Operations; other Operations use their `cli.format` or the fallback. */
const tableRenderers = new Map<string, (output: never, o: Output) => void>([
['list_assets', renderAssets],
['list_projects', renderProjects],
])
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
function cell(value: unknown): string {
if (value === null || value === undefined) return ''
return typeof value === 'object' ? JSON.stringify(value) : String(value)
}
/** Generic rendering: `{ data: [...] }` and arrays as tables, objects as `key: value` lines. */
function renderFallback(output: unknown, o: Output): void {
const rows = Array.isArray(output)
? output
: isRecord(output) && Array.isArray(output.data)
? output.data
: null
if (rows) {
if (rows.length === 0) {
o.out.write('No results.\n')
return
}
const keys = Object.keys(isRecord(rows[0]) ? rows[0] : { value: rows[0] })
const tp = newTablePrinter(o.out, o.isTty, o.columns)
tp.addHeader(keys)
for (const row of rows) {
for (const key of keys) tp.addField(cell(isRecord(row) ? row[key] : row))
tp.endRow()
}
tp.render()
return
}
if (isRecord(output)) {
for (const [key, value] of Object.entries(output)) o.out.write(`${key}: ${cell(value)}\n`)
return
}
o.out.write(`${cell(output)}\n`)
}
/** Writes an Operation's output in human-friendly form. */
export function renderOutput(definition: AnyOperationDefinition, output: unknown, o: Output): void {
const table = tableRenderers.get(definition.name)
if (table) {
table(output as never, o)
return
}
if (definition.cli?.format) {
o.out.write(`${definition.cli.format(output)}\n`)
return
}
renderFallback(output, o)
}
+844
View File
@@ -0,0 +1,844 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { Command } from 'commander'
import {
copyAssets,
createComment,
createFolder,
createVersionStack,
deleteAsset,
downloadAsset,
getAssetRender,
getFolderInstructions,
readAsset,
listAssets,
listComments,
listMetadataFields,
listProjects,
listVersions,
moveAssets,
removeVersion,
renameAsset,
resolveComment,
searchAssets,
updateAssetMetadata,
} from '@shumai/operations'
import type { CallOperation } from './operations/call-operation'
import { CliError, formatCliError } from './operations/errors'
import { createProgram } from './program'
/** Runs the CLI with mocked Operation calls and captures stdout/stderr. */
function setup() {
let stdout = ''
let stderr = ''
const callOperation = vi.fn<CallOperation>()
const program = createProgram({
callOperation,
output: { out: { write: (s) => void (stdout += s) }, isTty: true, columns: 120 },
})
const configure = (cmd: Command) => {
cmd.exitOverride().configureOutput({
writeOut: (s) => void (stdout += s),
writeErr: (s) => void (stderr += s),
})
cmd.commands.forEach(configure)
}
configure(program)
return {
callOperation,
run: (...argv: string[]) => program.parseAsync(['node', 'shumai-cli', ...argv]),
stdout: () => stdout,
stderr: () => stderr,
}
}
const folder = { id: 'f-1', name: 'Renders', type: 'folder', size: 0, projectId: 'p-1' }
const frames = {
status: 'ready',
summary: 'Extracted 2 frame(s) from "clip.mp4" (0s - 4s):',
asset: { id: 'vid-1', name: 'clip.mp4', kind: 'video', mediaType: 'video/mp4' },
details: [],
images: [
{ label: 'Frame at 0s', mimeType: 'image/webp', url: 'https://files.example/0.webp' },
{ label: 'Frame at 4s', mimeType: 'image/webp', url: 'https://files.example/4.webp' },
],
}
const pendingRead = {
status: 'pending',
summary: 'Rendering is still in progress for "clip.mp4".',
asset: frames.asset,
details: [],
images: [],
taskId: 'task-1',
retryAfterSeconds: 5,
}
describe('shumai-cli', () => {
const originalAllowDelete = process.env.SHUMAI_ALLOW_DELETE
afterEach(() => {
if (originalAllowDelete === undefined) delete process.env.SHUMAI_ALLOW_DELETE
else process.env.SHUMAI_ALLOW_DELETE = originalAllowDelete
})
describe('project ls', () => {
it('lists projects with their root folder', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
data: [
{ id: 'p1', name: 'Proj 1', teamId: 't1', rootFolderId: 'root1' },
{ id: 'p2', name: 'Proj 2', teamId: 't1', rootFolderId: 'root2' },
],
})
await cli.run('project', 'ls')
expect(cli.callOperation).toHaveBeenCalledWith(listProjects, {})
expect(cli.stdout()).toContain('Root Folder ID')
expect(cli.stdout()).toMatch(/p1\s+Proj 1\s+root1/)
expect(cli.stdout()).toContain('Proj 2')
})
it('reports when there are no projects', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({ data: [] })
await cli.run('project', 'ls')
expect(cli.stdout()).toBe('No projects found.\n')
})
})
describe('ls', () => {
it('lists a folder with the maximum page size, folders first', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
data: [
{ id: 'file1', name: 'doc.pdf', type: 'file', size: 1024, projectId: 'p' },
{ id: 'sub1', name: 'Sub 1', type: 'folder', size: 0, projectId: 'p' },
],
pageInfo: { hasNextPage: false, endCursor: null },
total: 2,
})
await cli.run('ls', '-p', 'parentId123')
expect(cli.callOperation).toHaveBeenCalledWith(listAssets, {
parent: 'parentId123',
first: 200,
})
const out = cli.stdout()
expect(out.indexOf('Sub 1')).toBeLessThan(out.indexOf('doc.pdf'))
expect(out).toMatch(/file1\s+doc\.pdf\s+file\s+1 KB/)
expect(out).not.toContain('More assets available')
})
it('passes pagination and type flags and prints the next-page cursor', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
data: [{ id: 'sub1', name: 'Sub 1', type: 'folder', size: 0, projectId: 'p' }],
pageInfo: { hasNextPage: true, endCursor: 'cur-2' },
total: 3,
})
await cli.run('ls', '--parent', 'p1', '--type', 'folder', '--first', '1', '--after', 'cur-1')
expect(cli.callOperation).toHaveBeenCalledWith(listAssets, {
parent: 'p1',
type: 'folder',
first: 1,
after: 'cur-1',
})
expect(cli.stdout()).toContain('Next page: --after cur-2')
})
it('requires the parent option', async () => {
const cli = setup()
await expect(cli.run('ls')).rejects.toThrow()
expect(cli.stderr()).toContain("required option '-p, --parent <parent>' not specified")
expect(cli.callOperation).not.toHaveBeenCalled()
})
it('rejects an invalid type and a non-numeric page size', async () => {
const cli = setup()
await expect(cli.run('ls', '-p', 'x', '--type', 'video')).rejects.toThrow()
expect(cli.stderr()).toContain('Allowed choices are file, folder, all')
await expect(cli.run('ls', '-p', 'x', '--first', 'many')).rejects.toThrow()
expect(cli.stderr()).toContain('Not a number')
expect(cli.callOperation).not.toHaveBeenCalled()
})
})
describe('mkdir', () => {
it('creates a folder and prints its ID', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({ ...folder, id: 'new_folder_ulid' })
await cli.run('mkdir', 'NewFolder', '-p', 'parent_ulid')
expect(cli.callOperation).toHaveBeenCalledWith(createFolder, {
name: 'NewFolder',
parent: 'parent_ulid',
})
expect(cli.stdout()).toBe('Created folder with ID: new_folder_ulid\n')
})
it('requires a folder name', async () => {
const cli = setup()
await expect(cli.run('mkdir', '-p', 'parent_ulid')).rejects.toThrow()
expect(cli.stderr()).toContain("missing required argument 'name'")
})
})
describe('rename', () => {
it('renames an asset', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({ ...folder, name: 'Renamed Folder' })
await cli.run('rename', 'f-1', 'Renamed Folder')
expect(cli.callOperation).toHaveBeenCalledWith(renameAsset, {
assetId: 'f-1',
name: 'Renamed Folder',
})
expect(cli.stdout()).toBe('Renamed asset f-1 to "Renamed Folder"\n')
})
it('requires both the asset ID and the new name', async () => {
const cli = setup()
await expect(cli.run('rename', 'f-1')).rejects.toThrow()
expect(cli.stderr()).toContain("missing required argument 'name'")
})
})
describe('move', () => {
it.each(['move', 'mv'])('moves assets with %s', async (command) => {
const cli = setup()
cli.callOperation.mockResolvedValue({
movedAssetIds: ['a-1', 'a-2'],
newParentId: 'parent-1',
})
await cli.run(command, 'a-1', 'a-2', '-p', 'parent-1')
expect(cli.callOperation).toHaveBeenCalledWith(moveAssets, {
assetIds: ['a-1', 'a-2'],
newParentId: 'parent-1',
})
expect(cli.stdout()).toBe('Moved 2 asset(s) to parent parent-1\n')
})
it('requires at least one asset and a destination', async () => {
const cli = setup()
await expect(cli.run('move', '-p', 'parent-1')).rejects.toThrow()
expect(cli.stderr()).toContain("missing required argument 'assetIds'")
await expect(cli.run('move', 'a-1')).rejects.toThrow()
expect(cli.stderr()).toContain("required option '-p, --parent <newParentId>' not specified")
})
})
describe('delete', () => {
it.each([undefined, 'false'])(
'refuses to delete when SHUMAI_ALLOW_DELETE is %s',
async (value) => {
if (value === undefined) delete process.env.SHUMAI_ALLOW_DELETE
else process.env.SHUMAI_ALLOW_DELETE = value
const cli = setup()
const error = await cli.run('delete', 'a-1').catch((err: unknown) => err)
expect(formatCliError(error)).toBe(
'Error: Delete Asset is disabled in this environment. Set SHUMAI_ALLOW_DELETE=true to enable it.',
)
expect(cli.callOperation).not.toHaveBeenCalled()
},
)
it.each([
['delete', 'true'],
['rm', '1'],
])('deletes with %s when SHUMAI_ALLOW_DELETE=%s', async (command, value) => {
process.env.SHUMAI_ALLOW_DELETE = value
const cli = setup()
cli.callOperation.mockResolvedValue({ deletedAssetId: 'a-1' })
await cli.run(command, 'a-1')
expect(cli.callOperation).toHaveBeenCalledWith(deleteAsset, { assetId: 'a-1' })
expect(cli.stdout()).toBe('Deleted asset a-1\n')
})
it('deletes only one asset at a time', async () => {
process.env.SHUMAI_ALLOW_DELETE = 'true'
const cli = setup()
await expect(cli.run('delete', 'a-1', 'a-2')).rejects.toThrow()
expect(cli.stderr()).toContain('too many arguments')
expect(cli.callOperation).not.toHaveBeenCalled()
})
})
describe('read', () => {
it('maps flattened reader flags onto the config objects and prints image links', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue(frames)
await cli.run(
'read',
'vid-1',
'--video-start',
'0',
'--video-end',
'4',
'--video-count',
'2',
'--annotation-id',
'c-1',
)
expect(cli.callOperation).toHaveBeenCalledWith(readAsset, {
assetId: 'vid-1',
annotationId: 'c-1',
videoConfig: { start: 0, end: 4, count: 2 },
})
expect(cli.stdout()).toBe(
[
'Extracted 2 frame(s) from "clip.mp4" (0s - 4s):',
'- Frame at 0s: https://files.example/0.webp',
'- Frame at 4s: https://files.example/4.webp',
'',
].join('\n'),
)
})
it.each([
[
['--doc-mode', 'pages', '--doc-start-page', '1', '--doc-end-page', '3'],
{ docConfig: { mode: 'pages', startPage: 1, endPage: 3 } },
],
[['--doc-mode', 'text'], { docConfig: { mode: 'text' } }],
[['--degree', '90'], { config3d: { degree: 90 } }],
[[], {}],
])('reads with %j', async (flags, config) => {
const cli = setup()
cli.callOperation.mockResolvedValue({ ...frames, images: [] })
await cli.run('read', 'a-1', ...flags)
expect(cli.callOperation).toHaveBeenCalledWith(readAsset, { assetId: 'a-1', ...config })
})
it('names the flag that is missing from a reader config', async () => {
const cli = setup()
const error = await cli
.run('read', 'vid-1', '--video-start', '0', '--video-count', '2')
.catch((err: unknown) => err)
expect(formatCliError(error)).toContain('--video-end')
expect(cli.callOperation).not.toHaveBeenCalled()
})
it('prints text content after the summary', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
...frames,
summary: 'Document "notes.md" (ID: d-1):',
images: [],
text: {
content: '# Notes\nhello',
truncated: true,
size: 90000,
mimeType: 'text/markdown',
},
})
await cli.run('read', 'd-1', '--doc-mode', 'text')
expect(cli.stdout()).toBe(
'Document "notes.md" (ID: d-1):\n\n# Notes\nhello\n\n[Content truncated: showing the first part of a 90000-byte file. Run `shumai-cli download vid-1` to get the whole file.]\n',
)
})
it('returns right away with --no-wait and prints the render command', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue(pendingRead)
await cli.run(
'read',
'vid-1',
'--video-start',
'0',
'--video-end',
'4',
'--video-count',
'2',
'--no-wait',
'--out',
'frames',
)
expect(cli.callOperation).toHaveBeenCalledWith(readAsset, {
assetId: 'vid-1',
videoConfig: { start: 0, end: 4, count: 2 },
maxWaitSeconds: 0,
})
expect(cli.stdout()).toBe(
'Rendering is still in progress for "clip.mp4".\nRun this to get the result: shumai-cli render task-1 --out "frames"\n',
)
})
it('prints the raw output with --json', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue(frames)
await cli.run('--json', 'read', 'vid-1')
expect(JSON.parse(cli.stdout())).toEqual(frames)
})
})
describe('render', () => {
it('fetches a pending render by task ID', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue(frames)
await cli.run('render', 'task-1')
expect(cli.callOperation).toHaveBeenCalledWith(getAssetRender, { taskId: 'task-1' })
expect(cli.stdout()).toContain('- Frame at 4s: https://files.example/4.webp')
})
it('checks once with --no-wait', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue(pendingRead)
await cli.run('render', 'task-1', '--no-wait')
expect(cli.callOperation).toHaveBeenCalledWith(getAssetRender, {
taskId: 'task-1',
maxWaitSeconds: 0,
})
expect(cli.stdout()).toContain('Run this to get the result: shumai-cli render task-1\n')
})
})
describe('download', () => {
it('downloads the web previews by default, or the originals with --original', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({ files: [] })
await cli.run('download', 'a-1', 'a-2')
expect(cli.callOperation).toHaveBeenLastCalledWith(downloadAsset, {
assetIds: ['a-1', 'a-2'],
})
await cli.run('download', 'a-1', '--original')
expect(cli.callOperation).toHaveBeenLastCalledWith(downloadAsset, {
assetIds: ['a-1'],
proxy: false,
})
})
it('requires at least one asset ID and documents its options', async () => {
const cli = setup()
await expect(cli.run('download')).rejects.toThrow()
expect(cli.stderr()).toContain("missing required argument 'assetIds'")
await expect(cli.run('download', '--help')).rejects.toThrow()
expect(cli.stdout()).toContain('-o, --out <dir>')
expect(cli.stdout()).toContain('--original')
expect(cli.stdout()).not.toContain('--proxy')
})
})
describe('--json', () => {
it('prints the raw Operation output', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue(folder)
await cli.run('mkdir', 'Renders', '-p', 'root', '--json')
expect(JSON.parse(cli.stdout())).toEqual(folder)
})
it('works before the command too', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({ data: [] })
await cli.run('--json', 'project', 'ls')
expect(JSON.parse(cli.stdout())).toEqual({ data: [] })
})
})
describe('errors', () => {
it('surfaces server errors for the entry point to print', async () => {
const cli = setup()
cli.callOperation.mockRejectedValue(new CliError('User is not a member of the team'))
const error = await cli.run('mkdir', 'x', '-p', 'root').catch((err: unknown) => err)
expect(formatCliError(error)).toBe('Error: User is not a member of the team')
})
it('validates input against the Operation schema before calling the server', async () => {
const cli = setup()
const error = await cli.run('mkdir', '', '-p', 'root').catch((err: unknown) => err)
expect(error).toBeInstanceOf(CliError)
expect(cli.callOperation).not.toHaveBeenCalled()
})
it('suggests similar commands for typos', async () => {
const cli = setup()
await expect(cli.run('mkidr', 'x')).rejects.toThrow()
expect(cli.stderr()).toContain('Did you mean mkdir?')
})
})
describe('help', () => {
it('lists every command, including generated ones', async () => {
const cli = setup()
await expect(cli.run('--help')).rejects.toThrow()
const help = cli.stdout()
for (const command of [
'project',
'ls',
'mkdir',
'rename',
'move|mv',
'delete|rm',
'read',
'render',
'download',
'upload',
'create-version',
]) {
expect(help).toContain(command)
}
expect(help).toContain('--json')
})
it('documents generated options from the Operation schema', async () => {
const cli = setup()
await expect(cli.run('ls', '--help')).rejects.toThrow()
const help = cli.stdout()
expect(help).toContain('-p, --parent <parent>')
expect(help).toContain('The parent folder ID to list assets from.')
expect(help).toContain('--type <type>')
expect(help).toContain('choices: "file", "folder", "all"')
expect(help).toContain('(default: 200)')
expect(help).toContain('List the files and folders inside a parent folder.')
})
it('documents flattened reader options for read', async () => {
const cli = setup()
await expect(cli.run('read', '--help')).rejects.toThrow()
const help = cli.stdout()
for (const flag of [
'--video-start <start>',
'--video-end <end>',
'--video-count <count>',
'--doc-mode <mode>',
'--doc-start-page <startPage>',
'--doc-end-page <endPage>',
'--degree <degree>',
'--annotation-id <annotationId>',
'-o, --out <dir>',
'--no-wait',
]) {
expect(help).toContain(flag)
}
expect(help).not.toContain('--include-content')
expect(help).not.toContain('--image')
})
})
describe('search', () => {
it('searches a folder by name with the maximum page size', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
data: [{ id: 'f1', name: 'sunset.png', type: 'file', size: 10, projectId: 'p' }],
pageInfo: { hasNextPage: false, endCursor: null },
total: 1,
})
await cli.run('search', 'sunset', '-p', 'root-1')
expect(cli.callOperation).toHaveBeenCalledWith(searchAssets, {
parent: 'root-1',
query: 'sunset',
first: 200,
})
expect(cli.stdout()).toContain('sunset.png')
})
it('searches by meaning with --semantic', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
data: [],
pageInfo: { hasNextPage: false, endCursor: null },
total: 0,
})
await cli.run('search', 'a calm beach', '-p', 'root-1', '--semantic')
expect(cli.callOperation).toHaveBeenCalledWith(
searchAssets,
expect.objectContaining({ query: 'a calm beach', semantic: true }),
)
})
})
describe('copy', () => {
it.each(['copy', 'cp'])('copies assets with %s', async (command) => {
const cli = setup()
cli.callOperation.mockResolvedValue({ copiedAssetIds: ['c-1', 'c-2'], newParentId: 'f-2' })
await cli.run(command, 'a-1', 'a-2', '-p', 'f-2', '--with-comments')
expect(cli.callOperation).toHaveBeenCalledWith(copyAssets, {
assetIds: ['a-1', 'a-2'],
newParentId: 'f-2',
withComments: true,
})
expect(cli.stdout()).toBe('Copied 2 asset(s) to parent f-2: c-1, c-2\n')
})
})
describe('comment', () => {
const thread = {
id: 'c-1',
message: 'Too dark here',
author: { id: 'u-1', name: 'Ana' },
second: 12.5,
hasMarkup: false,
attachmentCount: 0,
createdAt: '2026-01-01T00:00:00.000Z',
resolved: true,
replies: [
{
id: 'c-2',
message: 'Fixed in v2',
author: { id: 'u-2', name: 'Bo' },
second: null,
hasMarkup: false,
attachmentCount: 0,
createdAt: '2026-01-02T00:00:00.000Z',
},
],
}
it('lists threads with their replies', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
data: [thread],
pageInfo: { hasNextPage: false, endCursor: null },
total: 1,
})
await cli.run('comment', 'ls', 'vid-1')
expect(cli.callOperation).toHaveBeenCalledWith(listComments, {
assetId: 'vid-1',
first: 200,
})
expect(cli.stdout()).toBe(
'c-1 @12.5s [resolved] Ana: Too dark here\n ↳ c-2 Bo: Fixed in v2\n',
)
})
it('posts a reply at a timecode', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({ id: 'c-3', assetId: 'vid-1', replyToId: 'c-1' })
await cli.run('comment', 'add', 'vid-1', 'Looks good now', '--reply-to', 'c-1', '--at', '3')
expect(cli.callOperation).toHaveBeenCalledWith(createComment, {
assetId: 'vid-1',
message: 'Looks good now',
replyToId: 'c-1',
second: 3,
})
expect(cli.stdout()).toBe('Posted comment c-3\n')
})
it('resolves and reopens comments', async () => {
const cli = setup()
cli.callOperation.mockResolvedValueOnce({ commentId: 'c-1', resolved: true })
cli.callOperation.mockResolvedValueOnce({ commentId: 'c-1', resolved: false })
await cli.run('comment', 'resolve', 'c-1')
await cli.run('comment', 'resolve', 'c-1', '--reopen')
expect(cli.callOperation).toHaveBeenNthCalledWith(1, resolveComment, { commentId: 'c-1' })
expect(cli.callOperation).toHaveBeenNthCalledWith(2, resolveComment, {
commentId: 'c-1',
reopen: true,
})
expect(cli.stdout()).toBe('Comment c-1 is resolved\nComment c-1 is unresolved\n')
})
})
describe('meta set', () => {
it('passes --values as a JSON object', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({ assetId: 'a-1', updatedKeys: ['status', 'rating'] })
await cli.run('meta', 'set', 'a-1', '--values', '{"status":"approved","rating":4}')
expect(cli.callOperation).toHaveBeenCalledWith(updateAssetMetadata, {
assetId: 'a-1',
values: { status: 'approved', rating: 4 },
})
expect(cli.stdout()).toBe('Updated status, rating on a-1\n')
})
it.each([
['{not json', 'Not valid JSON.'],
['["status"]', 'Expected a JSON object'],
])('rejects --values %s', async (value, message) => {
const cli = setup()
await expect(cli.run('meta', 'set', 'a-1', '--values', value)).rejects.toThrow()
expect(cli.stderr()).toContain(message)
expect(cli.callOperation).not.toHaveBeenCalled()
})
})
describe('field ls', () => {
it("lists a project's fields with their choices", async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
fields: [
{
key: 'status',
name: 'Status',
type: 'select',
description: '',
readOnly: false,
creationContext: false,
options: [{ id: 'approved', name: 'Approved' }],
},
{
key: 'prompt',
name: 'Prompt',
type: 'text',
description: '',
readOnly: false,
creationContext: true,
},
],
})
await cli.run('field', 'ls', 'p-1')
expect(cli.callOperation).toHaveBeenCalledWith(listMetadataFields, { projectId: 'p-1' })
expect(cli.stdout()).toBe(
'status Status (select) [approved=Approved]\nprompt Prompt (text, creation)\n',
)
})
})
describe('version', () => {
it('stacks files, lists versions, and unstacks one', async () => {
const cli = setup()
cli.callOperation.mockResolvedValueOnce({
id: 's-1',
name: 'cut_v2.mp4',
type: 'version_stack',
size: 20,
projectId: 'p-1',
})
cli.callOperation.mockResolvedValueOnce({
versions: [
{
id: 'v-2',
version: 2,
name: 'cut_v2.mp4',
current: true,
createdAt: '2026-01-02T00:00:00.000Z',
creator: null,
agent: null,
},
{
id: 'v-1',
version: 1,
name: 'cut_v1.mp4',
current: false,
createdAt: '2026-01-01T00:00:00.000Z',
creator: null,
agent: null,
},
],
})
cli.callOperation.mockResolvedValueOnce({ versionId: 'v-1', stackId: 's-1' })
await cli.run('version', 'stack', 'v-2', 'v-1')
await cli.run('version', 'ls', 's-1')
await cli.run('version', 'unstack', 'v-1')
expect(cli.callOperation).toHaveBeenNthCalledWith(1, createVersionStack, {
fileIds: ['v-2', 'v-1'],
})
expect(cli.callOperation).toHaveBeenNthCalledWith(2, listVersions, { stackId: 's-1' })
expect(cli.callOperation).toHaveBeenNthCalledWith(3, removeVersion, { versionId: 'v-1' })
expect(cli.stdout()).toBe(
'Created version stack s-1\n' +
'v2 (current) v-2 cut_v2.mp4\nv1 v-1 cut_v1.mp4\n' +
'Removed v-1 from version stack s-1\n',
)
})
})
describe('instructions', () => {
it("prints a folder's instructions, or says it has none", async () => {
const cli = setup()
cli.callOperation.mockResolvedValueOnce({ folderId: 'f-1', content: '# Rules' })
cli.callOperation.mockResolvedValueOnce({ folderId: 'f-2', content: null })
await cli.run('instructions', 'f-1')
await cli.run('instructions', 'f-2')
expect(cli.callOperation).toHaveBeenCalledWith(getFolderInstructions, { folderId: 'f-1' })
expect(cli.stdout()).toBe('# Rules\n(This folder has no instructions.)\n')
})
})
it('has no upload Operation commands: upload and create-version stream local files', () => {
const program = createProgram({ callOperation: vi.fn<CallOperation>() })
const names = program.commands.map((c) => c.name())
expect(names).not.toContain('complete-upload')
expect(names.filter((n) => n === 'create-version')).toHaveLength(1)
})
})
describe('formatCliError', () => {
beforeEach(() => vi.restoreAllMocks())
it('formats expected and unexpected errors', () => {
expect(formatCliError(new CliError('boom'))).toBe('Error: boom')
expect(
formatCliError(new CliError('Error connecting to API server: x', { prefixed: true })),
).toBe('Error connecting to API server: x')
expect(formatCliError(new TypeError('bad'))).toBe('Unexpected error: bad')
})
})
+59
View File
@@ -0,0 +1,59 @@
import { Command } from 'commander'
import { operationDefinitions } from '@shumai/operations'
import { createVersion } from './commands/create-version'
import { upload } from './commands/upload'
import { callOperation, type CallOperation } from './operations/call-operation'
import { cliExtensions } from './operations/extensions'
import { registerOperationCommands } from './operations/generate'
import type { Output } from './operations/render'
export interface ProgramOptions {
callOperation?: CallOperation
output?: Output
}
function isDeleteAllowed(): boolean {
const value = process.env.SHUMAI_ALLOW_DELETE
return value === 'true' || value === '1'
}
/**
* Builds the `shumai-cli` program. Operation commands (ls, mkdir, rename, move, delete,
* read, render, project ls, ...) are generated from `@shumai/operations`; upload and create-version stream
* local files and are defined here.
*/
export function createProgram(options: ProgramOptions = {}): Command {
const program = new Command()
.name('shumai-cli')
.description('Command line interface for the Shumai media workspace.')
.option('--json', 'Print raw JSON output instead of human-friendly text')
.showHelpAfterError()
.showSuggestionAfterError()
registerOperationCommands(program, operationDefinitions, {
callOperation: options.callOperation ?? callOperation,
output: options.output ?? {
out: process.stdout,
isTty: Boolean(process.stdout.isTTY),
columns: process.stdout.columns || 80,
},
allowDestructive: isDeleteAllowed,
extensions: cliExtensions,
})
program
.command('upload')
.description('Upload a local file or folder to a parent folder.')
.argument('<path>', 'Local file or folder to upload.')
.requiredOption('-p, --parent <parentId>', 'The parent folder ID to upload into.')
.action((localPath: string, opts: { parent: string }) => upload(localPath, opts.parent))
program
.command('create-version')
.description('Upload a local file as a new version of an existing file or version stack.')
.argument('<path>', 'Local file to upload as the new version.')
.requiredOption('-p, --parent <parentId>', 'The file or version stack ID to add a version to.')
.action((localPath: string, opts: { parent: string }) => createVersion(localPath, opts.parent))
return program
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@shumai/premiere-uxp",
"version": "0.4.7",
"version": "0.6.5",
"private": true,
"type": "commonjs",
"scripts": {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@shumai/transcode-app",
"version": "0.4.7",
"version": "0.6.5",
"private": true,
"type": "module",
"bin": {
+76 -9
View File
@@ -14,18 +14,85 @@ async function run() {
// Initialize workflows and activities
initTranscodeWorkflows()
console.log('🚀 Starting Transcode Worker...')
let idleTimeoutMs = process.env.SHUMAI_WORKER_IDLE_TIMEOUT_MS
? parseInt(process.env.SHUMAI_WORKER_IDLE_TIMEOUT_MS, 10)
: 0
const options: { workflowBundle?: unknown; workflowsPath?: string } = {}
if (process.env.NODE_ENV === 'production') {
// @ts-ignore: Bun temporal plugin macro
const { default: workflowBundle } = await import('./workflows.ts:::workflow')
options.workflowBundle = workflowBundle
} else {
options.workflowsPath = new URL('./workflows.ts', import.meta.url).pathname
const idleTimeoutArg = process.argv.find((arg) => arg.startsWith('--idle-timeout='))
if (idleTimeoutArg) {
const val = parseInt(idleTimeoutArg.split('=')[1], 10)
if (!isNaN(val)) idleTimeoutMs = val
}
await workflowService.startWorkers(TaskQueueTranscode, options)
if (idleTimeoutMs > 0) {
console.log(
`🚀 Starting Transcode Worker with idle timeout (${idleTimeoutMs / 1000}s auto-drain)...`,
)
} else {
console.log('🚀 Starting Transcode Worker (persistent daemon mode)...')
}
await workflowService.startWorkers(TaskQueueTranscode)
let isShuttingDown = false
let idleTimer: Timer | null = null
let activeWorkflows = 0
const shutdown = async () => {
if (isShuttingDown) return
isShuttingDown = true
if (idleTimer) {
clearTimeout(idleTimer)
idleTimer = null
}
console.log('Shutting down Transcode Worker gracefully...')
try {
await workflowService.shutdownWorkers()
} catch (err) {
console.error('Error during Transcode Worker shutdown:', err)
}
process.exit(0)
}
if (idleTimeoutMs > 0) {
const resetIdleTimer = () => {
if (idleTimer) {
clearTimeout(idleTimer)
idleTimer = null
}
if (activeWorkflows === 0 && !isShuttingDown) {
idleTimer = setTimeout(async () => {
console.log(
`[Transcode Worker] Inactive for ${idleTimeoutMs / 1000}s with no active workflows, shutting down.`,
)
await shutdown()
}, idleTimeoutMs)
}
}
// Start idle timer immediately on startup in case no tasks are enqueued
resetIdleTimer()
workflowService.getExecutor().on('workflowStarted', (task) => {
activeWorkflows++
console.log(
`[Transcode Worker] Claimed task ${task.id} (active: ${activeWorkflows}), cancelling idle timer.`,
)
if (idleTimer) {
clearTimeout(idleTimer)
idleTimer = null
}
})
workflowService.getExecutor().on('workflowFinished', async ({ taskId }) => {
activeWorkflows = Math.max(0, activeWorkflows - 1)
console.log(`[Transcode Worker] Completed task ${taskId} (active: ${activeWorkflows}).`)
resetIdleTimer()
})
}
process.on('SIGINT', shutdown)
process.on('SIGTERM', shutdown)
}
handleDaemonCommands('shumai-transcode', run).catch((err) => {
-1
View File
@@ -1 +0,0 @@
export * from '@shumai/transcode/src/workflows/transcode'
+4
View File
@@ -66,6 +66,7 @@ apps/web/e2e/
| Owner removes a member via the members dialog; the membership is deleted from the DB | `tests/team/remove-member.spec.ts` |
| Owner changes a team member role in the members dialog and permissions update | `tests/team/change-member-role.spec.ts` |
| Owner manages resource quotas in settings and resets usage from the dashboard | `tests/team/quotas-settings.spec.ts` |
| Owner creates an API token that is shown once, listed by hint, and authenticates API calls | `tests/team/api-tokens.spec.ts` |
### project
| Test | File |
@@ -89,6 +90,7 @@ apps/web/e2e/
| Owner removes version from 2-version stack which dissolves into standalone files | `tests/project/version-stack-manage.spec.ts` |
| Dissolving a shared version stack renders the remaining standalone file name on the share page | `tests/project/version-stack-manage.spec.ts` |
| Moving a shared file into a shared version stack leaves only 1 stack card on the share page | `tests/project/version-stack-manage.spec.ts` |
| Manage versions dialog constrains card width and truncates long file names without dialog overflow | `tests/project/version-stack-manage.spec.ts` |
| Owner searches the file list by an English name keyword | `tests/project/search-file-list.spec.ts` |
| Owner searches the file list by Chinese, Japanese, and Korean name keywords | `tests/project/search-file-list.spec.ts` |
| Owner searches the file list with a keyword and a filter condition | `tests/project/search-file-list.spec.ts` |
@@ -96,6 +98,8 @@ apps/web/e2e/
| Image share with watermark + download disabled: no download buttons on public list/detail pages, watermarked proxy served, download-url rejected | `tests/project/share-watermark-no-download.spec.ts` |
| Video share with watermark + download disabled: no download buttons on public list/detail pages, watermarked proxy served, download-url rejected | `tests/project/share-watermark-no-download.spec.ts` |
| Owner views a file and it appears in recents | `tests/project/recents.spec.ts` |
| Owner archives a file to archive storage and restores it back to main storage | `tests/project/archive-restore.spec.ts` |
| Owner opens Copy submenu in context menu and copies file name | `tests/project/copy-menu.spec.ts` |
### file
| Test | File |
+9
View File
@@ -10,12 +10,16 @@ export default async function globalTeardown() {
if (fs.existsSync(envPath)) {
const content = fs.readFileSync(envPath, 'utf8')
let bucketName: string | undefined
let archiveRoot: string | undefined
content.split('\n').forEach((line) => {
const parts = line.split('=')
if (parts.length >= 2 && parts[0].trim() === 'S3_BUCKET') {
bucketName = parts.slice(1).join('=').trim()
}
if (parts.length >= 2 && parts[0].trim() === 'ARCHIVE_LOCAL_ROOT') {
archiveRoot = parts.slice(1).join('=').trim()
}
})
if (bucketName) {
@@ -26,6 +30,11 @@ export default async function globalTeardown() {
}
}
if (archiveRoot && fs.existsSync(archiveRoot)) {
console.log(`Cleaning up E2E archive storage root: ${archiveRoot}`)
fs.rmSync(archiveRoot, { recursive: true, force: true })
}
// Delete the temp .env.e2e file
fs.unlinkSync(envPath)
}
+10 -3
View File
@@ -13,17 +13,24 @@ async function start() {
// Generate a random S3 bucket name
const randomSuffix = randomBytes(4).toString('hex')
const bucketName = `shumai-e2e-${randomSuffix}`
const archiveRoot = path.resolve('data', `shumai-e2e-archive-${randomSuffix}`)
process.env.S3_BUCKET = bucketName
process.env.ARCHIVE_STORAGE_BACKEND = 'local'
process.env.ARCHIVE_LOCAL_ROOT = archiveRoot
process.env.SHUMAI_SERVER_PORT = '5200'
process.env.BETTER_AUTH_URL = 'http://localhost:5200'
process.env.NODE_ENV = 'development'
process.env.SHUMAI_E2E = 'true'
process.env.ENABLE_EMBEDDING_AGENT = 'false'
// Write variables to .env.e2e file so the teardown can load them
const envContent = [`DATABASE_URL=${process.env.DATABASE_URL}`, `S3_BUCKET=${bucketName}`].join(
'\n',
)
const envContent = [
`DATABASE_URL=${process.env.DATABASE_URL}`,
`S3_BUCKET=${bucketName}`,
`ARCHIVE_STORAGE_BACKEND=local`,
`ARCHIVE_LOCAL_ROOT=${archiveRoot}`,
].join('\n')
fs.writeFileSync(path.resolve(currentDir, '.env.e2e'), envContent)
console.log(`E2E env file written. Starting Web App...`)
@@ -0,0 +1,65 @@
import { expect, test } from '../../fixtures'
import { fileCard } from '../../helpers/files'
test('owner archives a file to archive storage and restores it back to main storage', async ({
file,
prisma,
}) => {
const { page, projectId, fileName, fileId } = file
await page.goto(`/projects/${projectId}`)
const card = fileCard(page, fileName)
await expect(card).toBeVisible()
// 1. Archive via context menu + confirmation dialog
await card.click({ button: 'right' })
await page.getByTestId('context-menu-archive').click()
const confirmDialog = page.getByTestId('archive-confirm-dialog')
await expect(confirmDialog).toBeVisible()
await page.getByTestId('archive-confirm-submit').click()
// Wait for the DBOS archive workflow to finish and the card badge to settle to Archived
await expect(card.getByTestId('file-card-archived-badge')).toBeVisible({ timeout: 15000 })
const archivedAsset = await prisma.asset.findUniqueOrThrow({
where: { id: fileId },
include: { storageKey: true },
})
expect(archivedAsset.status).toBe('archived')
expect(archivedAsset.storageKey?.isArchived).toBe(true)
// 2. Open detail page and verify Archived header badge + disabled original download button
await card.dblclick()
await expect(page.getByTestId('detail-header-archived-badge')).toBeVisible()
await expect(page.getByTestId('default-viewer-download-button')).toBeDisabled()
// 3. Return to project file list and restore from archive
await page.goto(`/projects/${projectId}`)
await expect(card.getByTestId('file-card-archived-badge')).toBeVisible()
await card.click({ button: 'right' })
await page.getByTestId('context-menu-restore-archive').click()
await expect(confirmDialog).toBeVisible()
await page.getByTestId('archive-confirm-submit').click()
// Wait for the DBOS restore workflow to finish and the Archived badge to disappear
await expect(card.getByTestId('file-card-archived-badge')).not.toBeVisible({ timeout: 15000 })
await expect
.poll(
async () => {
const restored = await prisma.asset.findUnique({
where: { id: fileId },
include: { storageKey: true },
})
return {
status: restored?.status,
isArchived: restored?.storageKey?.isArchived,
}
},
{ timeout: 10000 },
)
.toEqual({ status: 'processed', isArchived: false })
})
@@ -0,0 +1,43 @@
import { expect, test } from '../../fixtures'
import { fileCard } from '../../helpers/files'
test('owner sees Copy submenu in context menu and copies file name', async ({
file,
browserName,
}) => {
const { page, projectId, fileName } = file
if (browserName === 'chromium') {
await page.context().grantPermissions(['clipboard-read', 'clipboard-write'])
}
await page.goto(`/projects/${projectId}`)
await expect(fileCard(page, fileName)).toBeVisible()
// Right-click context menu
await fileCard(page, fileName).click({ button: 'right' })
const copySubTrigger = page.getByRole('menuitem', { name: /^Copy$|^复制$/i })
await expect(copySubTrigger).toBeVisible()
await copySubTrigger.click()
// Verify submenu items are visible
await expect(page.getByRole('menuitem', { name: /^Name$|^名称$/i })).toBeVisible()
await expect(page.getByRole('menuitem', { name: /^Link$|^链接$/i })).toBeVisible()
await expect(page.getByRole('menuitem', { name: /^Download link$|^下载链接$/i })).toBeVisible()
await expect(page.getByRole('menuitem', { name: /^ID$/i })).toBeVisible()
await expect(
page.getByRole('menuitem', { name: /^Markdown link$|^Markdown 链接$/i }),
).toBeVisible()
await expect(page.getByRole('menuitem', { name: /^Storage path$|^存储路径$/i })).toBeVisible()
// Click "Name"
await page.getByRole('menuitem', { name: /^Name$|^名称$/i }).click()
const toast = page.locator('[data-sonner-toast]').filter({
hasText: /Copied name to clipboard|已复制名称到剪贴板/i,
})
await expect(toast).toBeVisible()
if (browserName === 'chromium') {
const clipboardText = await page.evaluate(() => navigator.clipboard.readText())
expect(clipboardText).toBe(fileName)
}
})
@@ -231,3 +231,76 @@ test('moving a shared file into a shared version stack leaves only 1 stack card
const updatedShareRoot = await prisma.asset.findUnique({ where: { id: share.rootFolderId } })
expect(updatedShareRoot?.fileCount).toBe(1)
})
test('manage versions dialog constrains card width and truncates long file names without dialog overflow', async ({
project,
prisma,
}) => {
const { page, projectId, rootFolderId } = project
const longName =
'super-extremely-long-asset-name-for-testing-manage-versions-dialog-card-overflow-issue-that-keeps-expanding-without-truncating-properly.mp4'
const fileA = await seedFile(prisma, projectId, rootFolderId, longName)
const fileB = await seedFile(prisma, projectId, rootFolderId, `short-${Date.now()}.mp4`)
await page.goto(`/projects/${projectId}`)
await expect(fileCard(page, fileA.name)).toBeVisible()
await expect(fileCard(page, fileB.name)).toBeVisible()
// Create version stack: drag B on A
await dragCard(page, fileCard(page, fileB.name), fileCard(page, fileA.name))
await expect(page.getByText('v2', { exact: true })).toBeVisible()
const stack = await prisma.asset.findFirstOrThrow({
where: { projectId, parentId: rootFolderId, type: 'version_stack' },
})
// Navigate to file viewer for the stack
await page.goto(`/projects/${projectId}/files/${stack.id}`)
// Open breadcrumb menu and click "Manage versions..."
await page.getByRole('button', { name: new RegExp(fileB.name) }).click()
await page.getByRole('menuitem', { name: 'Versions', exact: true }).hover()
await page.getByRole('button', { name: /manage versions$/i }).click()
const dialog = page.getByRole('dialog')
await expect(dialog).toBeVisible()
const rowA = dialog.locator('div.group', { hasText: longName })
await expect(rowA).toBeVisible()
// Measure the dialog and version row
const metrics = await page.evaluate(() => {
const dialogEl = document.querySelector('[role="dialog"]') as HTMLElement | null
if (!dialogEl) return null
const row = dialogEl.querySelector('div.group') as HTMLElement | null
return {
dialogScrollWidth: dialogEl.scrollWidth,
dialogClientWidth: dialogEl.clientWidth,
dialogOffsetWidth: dialogEl.offsetWidth,
rowScrollWidth: row?.scrollWidth,
rowClientWidth: row?.clientWidth,
}
})
expect(metrics).not.toBeNull()
// Dialog should not horizontally scroll or overflow
expect(metrics!.dialogScrollWidth).toBeLessThanOrEqual(metrics!.dialogClientWidth)
// Row clientWidth should be bounded within the dialog
expect(metrics!.rowClientWidth).toBeLessThanOrEqual(metrics!.dialogClientWidth)
expect(metrics!.rowScrollWidth).toBeLessThanOrEqual(metrics!.rowClientWidth!)
// Hover over the row and verify the more-options button is visible and within bounds
await rowA.hover()
const moreButton = rowA.getByRole('button', { name: 'More options' })
await expect(moreButton).toBeVisible()
const moreBtnBox = await moreButton.boundingBox()
const dialogBox = await dialog.boundingBox()
expect(moreBtnBox).not.toBeNull()
expect(dialogBox).not.toBeNull()
expect(moreBtnBox!.x + moreBtnBox!.width).toBeLessThanOrEqual(dialogBox!.x + dialogBox!.width)
// Click more options button and verify menu opens
await moreButton.click()
await expect(page.getByRole('menuitem', { name: /remove from stack/i })).toBeVisible()
})
@@ -0,0 +1,61 @@
import { createHash } from 'node:crypto'
import { expect, test } from '../../fixtures'
import { E2E_APP_URL } from '../../helpers/auth'
test('owner creates an API token that is shown once, listed by hint, and authenticates API calls', async ({
owner,
prisma,
playwright,
}) => {
const { page, teamId } = owner
// 1. Open the API Tokens settings tab
await page.goto(`/teams/${teamId}/settings`)
await page.getByRole('button', { name: /^(API Tokens|API 令牌)$/i }).click()
await expect(page.getByText(/No API tokens found|未找到 API 令牌/i)).toBeVisible()
// 2. Generate a token
await page.fill('#tokenName', 'e2e-cli')
await page.getByRole('button', { name: /^(Generate|生成)$/i }).click()
// 3. The plaintext is shown once in a dialog
const dialog = page.getByRole('dialog')
await expect(dialog.getByText(/Save your API token|保存您的 API 令牌/i)).toBeVisible()
const tokenInput = dialog.getByRole('textbox')
await expect(tokenInput).toHaveValue(/^shumai_[A-Za-z0-9_-]{43}$/)
const token = await tokenInput.inputValue()
await dialog.getByRole('button', { name: /^(Done|完成)$/i }).click()
await expect(dialog).toBeHidden()
// 4. The list identifies the token by name and hint only
const hint = token.slice(-4)
const row = page.getByRole('row', { name: /e2e-cli/ })
await expect(row).toBeVisible()
await expect(row.getByText(`…${hint}`)).toBeVisible()
await expect(page.getByText(token)).toHaveCount(0)
// 5. Only the hash is stored
const stored = await prisma.apiToken.findFirstOrThrow({ where: { name: 'e2e-cli' } })
expect(stored.tokenHash).toBe(createHash('sha256').update(token, 'utf8').digest('hex'))
expect(stored.tokenHint).toBe(hint)
// 6. The token authenticates a request that carries no session cookie
const tokenClient = await playwright.request.newContext({
// eslint-disable-next-line @typescript-eslint/naming-convention
baseURL: E2E_APP_URL,
})
try {
const ok = await tokenClient.get('/api/projects', {
headers: { Authorization: `Bearer ${token}` },
})
expect(ok.status()).toBe(200)
const rejected = await tokenClient.get('/api/projects', {
headers: { Authorization: `Bearer ${stored.tokenHash}` },
})
expect(rejected.status()).toBe(401)
} finally {
await tokenClient.dispose()
}
})
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@shumai/web-app",
"version": "0.4.7",
"version": "0.6.5",
"private": true,
"type": "module",
"dependencies": {
+84 -35
View File
@@ -8,14 +8,20 @@ import index from '@shumai/webui/index.html'
import { initAgentWorkflows } from '@shumai/agent'
import { app } from '@shumai/api'
import { assetService } from '@shumai/core/src/asset/asset'
import { validateArchiveStorageConfig } from '@shumai/core/src/s3/archive-storage'
import { metadataService } from '@shumai/core/src/metadata/metadata'
import { initTranscodeWorkflows } from '@shumai/transcode'
import { workflowService } from '@shumai/workflow-core'
import { migrateLegacyAgentAvatars } from '@shumai/core/src/agent/migration'
import { agentService } from '@shumai/core/src/agent/agent'
import { handleDaemonCommands } from '@shumai/core/src/utils/daemon'
import { authService } from '@shumai/core/src/auth/auth'
import { embeddingService } from '@shumai/core/src/search/embedding-service'
import { sandboxService } from '@shumai/core'
import { notificationJobService } from '@shumai/core/src/notification/notification-job'
import { autoArchiveJobService } from '@shumai/core/src/asset/auto-archive-job'
import { createHtmlHandler, createStaticFileHandler } from './static'
if (process.argv.includes('--check')) {
console.log('✅ Web app evaluated successfully!')
@@ -46,7 +52,34 @@ if (resetCmdIndex !== -1) {
}
}
const regenCmdIndex = cliArgs.findIndex((arg) => arg === 'regenerate-embeddings')
if (regenCmdIndex !== -1) {
try {
initAgentWorkflows()
initTranscodeWorkflows()
console.log('🔄 Regenerating embeddings...')
const result = await embeddingService.regenerateEmbeddings()
await workflowService.waitForPendingSubmissions()
console.log(
`✅ Successfully queued ${result.tasksCreated} embedding tasks for ${result.totalAssets} assets.`,
)
if (result.skippedTeams.length > 0) {
console.warn(
`⚠️ Skipped ${result.skippedTeams.length} team(s) without an active embedding agent.`,
)
}
console.log('The background workers will process the embedding tasks.')
process.exit(0)
} catch (err: unknown) {
const message = err instanceof Error ? err.message : 'Unknown error'
console.error(`Error: ${message}`)
process.exit(1)
}
}
async function run() {
validateArchiveStorageConfig()
// Initialize workflows and activities for local executor mode
initAgentWorkflows()
initTranscodeWorkflows()
@@ -57,31 +90,34 @@ async function run() {
// Start services
await metadataService.syncSystemFields().catch(console.error)
await migrateLegacyAgentAvatars().catch(console.error)
await agentService.ensureSystemEmbeddingAgents().catch(console.error)
assetService.startCleanupJob()
workflowService.start()
if (process.env.WORKFLOW_EXECUTOR === 'temporal') {
const args = process.argv.slice(2)
let workersOption = ''
for (let i = 0; i < args.length; i++) {
if (args[i] === '--workers') {
workersOption = args[i + 1] || ''
} else if (args[i].startsWith('--workers=')) {
workersOption = args[i].split('=')[1]
}
notificationJobService.start()
autoArchiveJobService.start()
const args = process.argv.slice(2)
let workersOption = process.env.SHUMAI_WORKERS || 'all'
for (let i = 0; i < args.length; i++) {
if (args[i] === '--workers') {
workersOption = args[i + 1] || workersOption
} else if (args[i].startsWith('--workers=')) {
workersOption = args[i].split('=')[1] || workersOption
}
const queuesToStart: string[] = []
if (workersOption === 'agent' || workersOption === 'ai') {
queuesToStart.push('agent_queue')
} else if (workersOption === 'transcode') {
queuesToStart.push('transcode_queue')
} else if (workersOption === 'all') {
queuesToStart.push('agent_queue', 'transcode_queue')
}
Promise.all(queuesToStart.map((q) => workflowService.startWorkers(q))).catch(console.error)
}
let listenQueues: string[] = ['agent_queue', 'transcode_queue', 'archive_queue']
if (workersOption === 'none') {
listenQueues = []
} else if (workersOption === 'agent' || workersOption === 'ai') {
listenQueues = ['agent_queue', 'archive_queue']
} else if (workersOption === 'transcode') {
listenQueues = ['transcode_queue']
} else if (workersOption === 'archive') {
listenQueues = ['archive_queue']
}
workflowService.start(listenQueues)
workflowService.startStaleTaskRecovery()
const isProd = process.env.NODE_ENV === 'production'
const port = process.env.SHUMAI_SERVER_PORT ? parseInt(process.env.SHUMAI_SERVER_PORT) : 3000
@@ -105,6 +141,9 @@ async function run() {
const routes: Record<string, any> = {
'/api/*': app.fetch,
'/files/*': app.fetch,
'/.well-known/*': app.fetch,
// Shumai's MCP server; without this entry the SPA catch-all (`/*`) would serve it HTML.
'/mcp': app.fetch,
}
if (isProd) {
@@ -113,7 +152,8 @@ async function run() {
for (const file of bundle.files) {
const routePath = file.path.startsWith('.') ? file.path.slice(1) : file.path
const filePath = join(import.meta.dir, file.path)
routes[routePath] = () => new Response(Bun.file(filePath), { headers: file.headers })
const isHtml = file.loader === 'html' || file.path.endsWith('.html')
routes[routePath] = createStaticFileHandler(filePath, file.headers, !isHtml)
}
const sampleFile = bundle.files[0]?.path || bundle.index || ''
@@ -125,13 +165,14 @@ async function run() {
const routePath = '/' + pdfWorkerFile
const filePath = join(bundleDir, pdfWorkerFile)
const bunFile = Bun.file(filePath)
routes[routePath] = () =>
new Response(bunFile, {
headers: {
'content-type': 'text/javascript;charset=utf-8',
etag: `"${bunFile.size}-${bunFile.lastModified}"`,
},
})
routes[routePath] = createStaticFileHandler(
filePath,
{
'content-type': 'text/javascript;charset=utf-8',
etag: `"${bunFile.size}-${bunFile.lastModified}"`,
},
true,
)
}
} catch (err) {
console.warn('Failed to register pdf.worker route:', err)
@@ -147,16 +188,22 @@ async function run() {
.replaceAll('href="./', 'href="/')
.replaceAll('src="./', 'src="/')
.replaceAll('content="./', 'content="/')
const serveMainHtml = () => new Response(mainHtmlText, { headers: mainHtmlHeaders })
const serveMainHtml = createHtmlHandler(mainHtmlText, mainHtmlHeaders)
routes['/'] = serveMainHtml
routes['/*'] = serveMainHtml
} else {
const fallbackHtmlPath = join(import.meta.dir, 'shumai-app.html')
const serveFallbackHtml = () =>
new Response(Bun.file(fallbackHtmlPath), {
headers: { 'content-type': 'text/html;charset=utf-8' },
})
const fallbackHtmlFile = Bun.file(fallbackHtmlPath)
if (!(await fallbackHtmlFile.exists())) {
throw new Error(
`Production HTML bundle is missing: neither bundle.files nor ${fallbackHtmlPath} exists.`,
)
}
const fallbackRaw = await fallbackHtmlFile.text()
const serveFallbackHtml = createHtmlHandler(fallbackRaw, {
'content-type': 'text/html;charset=utf-8',
})
routes['/'] = serveFallbackHtml
routes['/*'] = serveFallbackHtml
}
@@ -178,8 +225,10 @@ async function run() {
console.log(`🚀 Server running at ${server.url}`)
const shutdown = () => {
const shutdown = async () => {
console.log('\nShutting down gracefully...')
workflowService.stopStaleTaskRecovery()
await workflowService.shutdownWorkers().catch(() => {})
assetService.stopCleanupJob()
server.stop(true)
process.exit(0)
+175
View File
@@ -0,0 +1,175 @@
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { writeFileSync, unlinkSync } from 'node:fs'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
import { createHtmlHandler, createStaticFileHandler, isEtagMatching, normalizeEtag } from './static'
describe('Static Asset Serving & Caching', () => {
const tempChunkPath = join(tmpdir(), `test-chunk-${Date.now()}.js`)
const chunkContent = 'console.log("chunk loaded");'
beforeAll(() => {
writeFileSync(tempChunkPath, chunkContent, 'utf8')
})
afterAll(() => {
try {
unlinkSync(tempChunkPath)
} catch {
// Ignore cleanup error if already deleted
}
})
describe('normalizeEtag', () => {
it('quotes unquoted ETags according to RFC 9110', () => {
expect(normalizeEtag('hHRmXFeFVSk')).toBe('"hHRmXFeFVSk"')
expect(normalizeEtag('ACJrxcts9Iw')).toBe('"ACJrxcts9Iw"')
})
it('preserves already-quoted strong and weak ETags', () => {
expect(normalizeEtag('"hHRmXFeFVSk"')).toBe('"hHRmXFeFVSk"')
expect(normalizeEtag('W/"hHRmXFeFVSk"')).toBe('W/"hHRmXFeFVSk"')
})
it('returns undefined for empty or missing ETags', () => {
expect(normalizeEtag(undefined)).toBeUndefined()
expect(normalizeEtag('')).toBeUndefined()
expect(normalizeEtag(' ')).toBeUndefined()
})
})
describe('isEtagMatching', () => {
it('matches exact etag string', () => {
expect(isEtagMatching('"12345"', '"12345"')).toBe(true)
})
it('matches weak etag to strong or weak candidates', () => {
expect(isEtagMatching('W/"12345"', '"12345"')).toBe(true)
expect(isEtagMatching('"12345"', 'W/"12345"')).toBe(true)
expect(isEtagMatching('W/"12345"', 'W/"12345"')).toBe(true)
})
it('matches wildcard *', () => {
expect(isEtagMatching('"12345"', '*')).toBe(true)
})
it('matches comma-separated candidate lists', () => {
expect(isEtagMatching('"12345"', '"old-etag", "12345", "other"')).toBe(true)
expect(isEtagMatching('"12345"', '"old-etag", "mismatch"')).toBe(false)
})
it('returns false when etag or ifNoneMatch is missing or empty', () => {
expect(isEtagMatching(undefined, '"12345"')).toBe(false)
expect(isEtagMatching('"12345"', null)).toBe(false)
expect(isEtagMatching('', '"12345"')).toBe(false)
expect(isEtagMatching('"12345"', '')).toBe(false)
})
})
describe('createStaticFileHandler', () => {
it('sets immutable Cache-Control for immutable content-hashed assets', async () => {
const handler = createStaticFileHandler(
tempChunkPath,
{ 'content-type': 'text/javascript;charset=utf-8', etag: '"chunk-hash-1"' },
true,
)
const req = new Request('http://localhost/chunk-123.js')
const res = handler(req)
expect(res.status).toBe(200)
expect(res.headers.get('content-type')).toBe('text/javascript;charset=utf-8')
expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
expect(res.headers.get('etag')).toBe('"chunk-hash-1"')
expect(await res.text()).toBe(chunkContent)
})
it('returns 304 Not Modified when If-None-Match matches the file etag', async () => {
const handler = createStaticFileHandler(
tempChunkPath,
{ 'content-type': 'text/javascript;charset=utf-8', etag: '"chunk-hash-1"' },
true,
)
const req = new Request('http://localhost/chunk-123.js', {
headers: { 'if-none-match': '"chunk-hash-1"' },
})
const res = handler(req)
expect(res.status).toBe(304)
expect(res.headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
expect(res.headers.get('etag')).toBe('"chunk-hash-1"')
expect(await res.text()).toBe('')
})
it('sets no-cache Cache-Control for non-immutable static assets', async () => {
const handler = createStaticFileHandler(
tempChunkPath,
{ 'content-type': 'text/plain', etag: '"plain-1"' },
false,
)
const req = new Request('http://localhost/robots.txt')
const res = handler(req)
expect(res.status).toBe(200)
expect(res.headers.get('cache-control')).toBe('no-cache')
})
it('normalizes unquoted manifest ETags to quoted RFC 9110 strings', async () => {
const handler = createStaticFileHandler(
tempChunkPath,
{ 'content-type': 'text/javascript;charset=utf-8', etag: 'hHRmXFeFVSk' },
true,
)
const req = new Request('http://localhost/chunk-123.js')
const res = handler(req)
expect(res.status).toBe(200)
expect(res.headers.get('etag')).toBe('"hHRmXFeFVSk"')
const revalidateRes = handler(
new Request('http://localhost/chunk-123.js', {
headers: { 'if-none-match': '"hHRmXFeFVSk"' },
}),
)
expect(revalidateRes.status).toBe(304)
expect(revalidateRes.headers.get('etag')).toBe('"hHRmXFeFVSk"')
})
})
describe('createHtmlHandler', () => {
const htmlText = '<!DOCTYPE html><html><head><title>Shumai</title></head><body></body></html>'
it('sets no-cache and generates deterministic ETag for HTML', async () => {
const handler = createHtmlHandler(htmlText, { 'content-type': 'text/html;charset=utf-8' })
const req = new Request('http://localhost/')
const res = handler(req)
expect(res.status).toBe(200)
expect(res.headers.get('content-type')).toBe('text/html;charset=utf-8')
expect(res.headers.get('cache-control')).toBe('no-cache')
const etag = res.headers.get('etag')
expect(etag).toBeTruthy()
expect(await res.text()).toBe(htmlText)
})
it('returns 304 Not Modified when HTML If-None-Match matches', async () => {
const handler = createHtmlHandler(htmlText, { 'content-type': 'text/html;charset=utf-8' })
const initialRes = handler(new Request('http://localhost/'))
const etag = initialRes.headers.get('etag')!
const revalidateReq = new Request('http://localhost/', {
headers: { 'if-none-match': etag },
})
const revalidateRes = handler(revalidateReq)
expect(revalidateRes.status).toBe(304)
expect(revalidateRes.headers.get('cache-control')).toBe('no-cache')
expect(await revalidateRes.text()).toBe('')
})
})
})
+106
View File
@@ -0,0 +1,106 @@
/**
* Helpers for serving static production assets with caching headers and ETag revalidation.
*/
/**
* Checks whether an incoming `If-None-Match` header matches the asset's ETag.
* Supports weak ETags (`W/"..."`), exact matches, and comma-separated lists.
*/
export function isEtagMatching(etag: string | undefined, ifNoneMatch: string | null): boolean {
if (!etag || !ifNoneMatch) {
return false
}
const cleanTarget = etag.trim().replace(/^W\//, '').replace(/^"|"$/g, '')
if (!cleanTarget) {
return false
}
const candidates = ifNoneMatch
.split(',')
.map((candidate) => candidate.trim().replace(/^W\//, '').replace(/^"|"$/g, ''))
return candidates.includes(cleanTarget) || candidates.includes('*')
}
/**
* Normalizes an ETag to ensure it is enclosed in quotes according to RFC 9110.
* Preserves weak validators (`W/"..."`).
*/
export function normalizeEtag(etag: string | undefined): string | undefined {
if (!etag) {
return undefined
}
const trimmed = etag.trim()
if (!trimmed) {
return undefined
}
if (trimmed.startsWith('W/"') && trimmed.endsWith('"')) {
return trimmed
}
if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
return trimmed
}
return `"${trimmed.replace(/^"|"$/g, '')}"`
}
/**
* Creates a route handler for a static file on disk.
* Content-hashed assets (e.g. `chunk-*.js`, `chunk-*.css`) should be marked `isImmutable: true`
* to be aggressively cached locally by browsers across page reloads.
*/
export function createStaticFileHandler(
filePath: string,
baseHeaders: Record<string, string>,
isImmutable: boolean,
): (req: Request) => Response {
const bunFile = Bun.file(filePath)
const rawEtag = baseHeaders.etag || baseHeaders.ETag
const normalizedEtag = normalizeEtag(rawEtag)
const headers: Record<string, string> = {
...baseHeaders,
...(normalizedEtag ? { etag: normalizedEtag } : {}),
'cache-control': isImmutable ? 'public, max-age=31536000, immutable' : 'no-cache',
}
const etag = headers.etag
return (req: Request): Response => {
const ifNoneMatch = req.headers.get('if-none-match')
if (etag && isEtagMatching(etag, ifNoneMatch)) {
return new Response(null, {
status: 304,
headers,
})
}
return new Response(bunFile, { headers })
}
}
/**
* Creates a route handler for in-memory transformed HTML entry points.
* Sets `cache-control: no-cache` with a deterministic ETag, allowing browsers to cache locally
* while always revalidating to ensure new chunk hashes are picked up immediately after deployment.
*/
export function createHtmlHandler(
htmlText: string,
baseHeaders: Record<string, string>,
): (req: Request) => Response {
const rawEtag = baseHeaders.etag || baseHeaders.ETag
const etag = normalizeEtag(rawEtag) || `"${Bun.hash(htmlText).toString(16)}"`
const headers: Record<string, string> = {
...baseHeaders,
etag,
'cache-control': 'no-cache',
}
return (req: Request): Response => {
const ifNoneMatch = req.headers.get('if-none-match')
if (isEtagMatching(etag, ifNoneMatch)) {
return new Response(null, {
status: 304,
headers,
})
}
return new Response(htmlText, { headers })
}
}
+45 -34
View File
@@ -3,47 +3,58 @@ import { bunPluginPino } from 'bun-plugin-pino'
import tailwindPlugin from 'bun-plugin-tailwind'
import { existsSync } from 'fs'
import { rm } from 'fs/promises'
import { temporalWorkflow } from './packages/workflow-core/src/bun-temporal-plugin'
console.log('\n🚀 Starting build process...\n')
const outdir = 'dist'
const target = process.argv[2] || 'all'
if (existsSync(outdir)) {
if (existsSync(outdir) && target === 'all') {
console.log(`🗑️ Cleaning previous build at ${outdir}`)
await rm(outdir, { recursive: true, force: true })
}
await Bun.build({
entrypoints: ['./apps/web/src/index.ts'],
root: '.',
target: 'bun',
outdir: outdir,
minify: true,
splitting: true,
naming: '[name].[ext]',
plugins: [
temporalWorkflow({
bundleOptions: {},
}),
tailwindPlugin,
bunPluginPino({ transports: ['pino-pretty'] }),
],
external: [
'@temporalio/activity',
'@temporalio/client',
'@temporalio/worker',
'@temporalio/workflow',
'pdfkit',
],
// compile: {
// outfile: 'Shumai',
// autoloadBunfig: true,
// autoloadDotenv: true,
// autoloadTsconfig: true,
// autoloadPackageJson: true,
// },
define: {
'process.env.NODE_ENV': JSON.stringify('production'),
if (target === 'all' || target === 'web') {
await Bun.build({
entrypoints: ['./apps/web/src/index.ts'],
root: '.',
target: 'bun',
outdir: outdir,
minify: true,
splitting: true,
naming: '[name].[ext]',
plugins: [tailwindPlugin, bunPluginPino({ transports: ['pino-pretty'] })],
external: ['@dbos-inc/dbos-sdk', 'pg', 'pdfkit'],
define: {
'process.env.NODE_ENV': JSON.stringify('production'),
},
})
}
const allWorkers = [
{
name: 'transcode',
entrypoint: './apps/transcode/src/index.ts',
naming: 'transcode-worker.[ext]',
},
})
{ name: 'agent', entrypoint: './apps/agent/src/index.ts', naming: 'agent-worker.[ext]' },
]
const workersToBuild = target === 'all' ? allWorkers : allWorkers.filter((w) => w.name === target)
for (const worker of workersToBuild) {
await Bun.build({
entrypoints: [worker.entrypoint],
root: '.',
target: 'bun',
outdir: outdir,
minify: true,
splitting: false,
naming: worker.naming,
plugins: [bunPluginPino({ transports: ['pino-pretty'] })],
external: ['@dbos-inc/dbos-sdk', 'pg', 'pdfkit'],
define: {
'process.env.NODE_ENV': JSON.stringify('production'),
},
})
}
+108 -308
View File
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,70 @@
services:
postgres:
image: docker.m.daocloud.io/pgvector/pgvector:pg18
container_name: shumai_postgres
environment:
POSTGRES_USER: shumai
POSTGRES_PASSWORD: shumai_password
POSTGRES_DB: shumai_db
volumes:
- postgres_data:/var/lib/postgresql/18/docker
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
interval: 5s
timeout: 5s
retries: 5
embedding-server:
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/embedding-server:latest
container_name: shumai_embedding
restart: unless-stopped
shumai:
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai:latest
cap_add:
- SYS_ADMIN
security_opt:
- apparmor=unconfined
- seccomp=unconfined
container_name: shumai_app
ports:
- '3000:3000'
volumes:
- ./data:/app/data
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
# Uncomment the extends section below for hardware acceleration:
# extends:
# file: hwaccel.transcoding.yaml
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
environment:
# Database Configuration
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
# Server Configuration
SHUMAI_SERVER_PORT: 3000
# S3 Configuration
STORAGE_BACKEND: local
AWS_ENDPOINT_URL_S3: http://localhost:3000
# Better Auth
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL: http://localhost:3000
# Sandbox Configuration
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
# Embedding Configuration
EMBEDDING_PROVIDER: gemma-embedding-2-openai
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
ENABLE_EMBEDDING_AGENT: 'true'
CONCURRENCY_AGENT: 1
depends_on:
postgres:
condition: service_healthy
embedding-server:
condition: service_started
volumes:
postgres_data:
@@ -0,0 +1,90 @@
services:
postgres:
image: docker.m.daocloud.io/pgvector/pgvector:pg18
container_name: shumai_postgres
environment:
POSTGRES_USER: shumai
POSTGRES_PASSWORD: shumai_password
POSTGRES_DB: shumai_db
volumes:
- postgres_data:/var/lib/postgresql/18/docker
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
interval: 5s
timeout: 5s
retries: 5
embedding-server:
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/embedding-server:latest
container_name: shumai_embedding
restart: unless-stopped
turntable-renderer:
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/turntable-renderer:latest
container_name: shumai_turntable
restart: unless-stopped
gotenberg:
image: docker.m.daocloud.io/gotenberg/gotenberg:8
container_name: shumai_gotenberg
restart: unless-stopped
shumai:
image: crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai:latest
cap_add:
- SYS_ADMIN
security_opt:
- apparmor=unconfined
- seccomp=unconfined
container_name: shumai_app
ports:
- '3000:3000'
volumes:
- ./data:/app/data
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
# Uncomment the extends section below for hardware acceleration:
# extends:
# file: hwaccel.transcoding.yaml
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
environment:
# Database Configuration
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
# Server Configuration
SHUMAI_SERVER_PORT: 3000
# S3 Configuration
STORAGE_BACKEND: local
AWS_ENDPOINT_URL_S3: http://localhost:3000
# Better Auth
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL: http://localhost:3000
# Sandbox Configuration
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
# Embedding Configuration
EMBEDDING_PROVIDER: gemma-embedding-2-openai
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
ENABLE_EMBEDDING_AGENT: 'true'
CONCURRENCY_AGENT: 1
# 3D Turntable Renderer Configuration
TURNTABLE_RENDERER_URL: http://turntable-renderer:3000
# Gotenberg Document Converter Configuration
GOTENBERG_URL: http://gotenberg:3000
depends_on:
postgres:
condition: service_healthy
embedding-server:
condition: service_started
turntable-renderer:
condition: service_started
gotenberg:
condition: service_started
volumes:
postgres_data:
@@ -6,8 +6,6 @@ services:
POSTGRES_USER: shumai
POSTGRES_PASSWORD: shumai_password
POSTGRES_DB: shumai_db
ports:
- '5432:5432'
volumes:
- postgres_data:/var/lib/postgresql/18/docker
healthcheck:
@@ -28,6 +26,11 @@ services:
- '3000:3000'
volumes:
- ./data:/app/data
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
# Uncomment the extends section below for hardware acceleration:
# extends:
# file: hwaccel.transcoding.yaml
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
environment:
# Database Configuration
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
@@ -41,6 +44,7 @@ services:
# Better Auth
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL: http://localhost:3000
# Sandbox Configuration
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
@@ -0,0 +1,70 @@
services:
postgres:
image: pgvector/pgvector:pg18
container_name: shumai_postgres
environment:
POSTGRES_USER: shumai
POSTGRES_PASSWORD: shumai_password
POSTGRES_DB: shumai_db
volumes:
- postgres_data:/var/lib/postgresql/18/docker
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
interval: 5s
timeout: 5s
retries: 5
embedding-server:
image: shumaione/embedding-server:latest
container_name: shumai_embedding
restart: unless-stopped
shumai:
image: shumaione/shumai:latest
cap_add:
- SYS_ADMIN
security_opt:
- apparmor=unconfined
- seccomp=unconfined
container_name: shumai_app
ports:
- '3000:3000'
volumes:
- ./data:/app/data
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
# Uncomment the extends section below for hardware acceleration:
# extends:
# file: hwaccel.transcoding.yaml
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
environment:
# Database Configuration
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
# Server Configuration
SHUMAI_SERVER_PORT: 3000
# S3 Configuration
STORAGE_BACKEND: local
AWS_ENDPOINT_URL_S3: http://localhost:3000
# Better Auth
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL: http://localhost:3000
# Sandbox Configuration
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
# Embedding Configuration
EMBEDDING_PROVIDER: gemma-embedding-2-openai
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
ENABLE_EMBEDDING_AGENT: 'true'
CONCURRENCY_AGENT: 1
depends_on:
postgres:
condition: service_healthy
embedding-server:
condition: service_started
volumes:
postgres_data:
@@ -0,0 +1,90 @@
services:
postgres:
image: pgvector/pgvector:pg18
container_name: shumai_postgres
environment:
POSTGRES_USER: shumai
POSTGRES_PASSWORD: shumai_password
POSTGRES_DB: shumai_db
volumes:
- postgres_data:/var/lib/postgresql/18/docker
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
interval: 5s
timeout: 5s
retries: 5
embedding-server:
image: shumaione/embedding-server:latest
container_name: shumai_embedding
restart: unless-stopped
turntable-renderer:
image: shumaione/turntable-renderer:latest
container_name: shumai_turntable
restart: unless-stopped
gotenberg:
image: gotenberg/gotenberg:8
container_name: shumai_gotenberg
restart: unless-stopped
shumai:
image: shumaione/shumai:latest
cap_add:
- SYS_ADMIN
security_opt:
- apparmor=unconfined
- seccomp=unconfined
container_name: shumai_app
ports:
- '3000:3000'
volumes:
- ./data:/app/data
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
# Uncomment the extends section below for hardware acceleration:
# extends:
# file: hwaccel.transcoding.yaml
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
environment:
# Database Configuration
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
# Server Configuration
SHUMAI_SERVER_PORT: 3000
# S3 Configuration
STORAGE_BACKEND: local
AWS_ENDPOINT_URL_S3: http://localhost:3000
# Better Auth
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL: http://localhost:3000
# Sandbox Configuration
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
# Embedding Configuration
EMBEDDING_PROVIDER: gemma-embedding-2-openai
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
ENABLE_EMBEDDING_AGENT: 'true'
CONCURRENCY_AGENT: 1
# 3D Turntable Renderer Configuration
TURNTABLE_RENDERER_URL: http://turntable-renderer:3000
# Gotenberg Document Converter Configuration
GOTENBERG_URL: http://gotenberg:3000
depends_on:
postgres:
condition: service_healthy
embedding-server:
condition: service_started
turntable-renderer:
condition: service_started
gotenberg:
condition: service_started
volumes:
postgres_data:
+6 -2
View File
@@ -6,8 +6,6 @@ services:
POSTGRES_USER: shumai
POSTGRES_PASSWORD: shumai_password
POSTGRES_DB: shumai_db
ports:
- '5432:5432'
volumes:
- postgres_data:/var/lib/postgresql/18/docker
healthcheck:
@@ -28,6 +26,11 @@ services:
- '3000:3000'
volumes:
- ./data:/app/data
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
# Uncomment the extends section below for hardware acceleration:
# extends:
# file: hwaccel.transcoding.yaml
# service: cpu # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] for accelerated transcoding
environment:
# Database Configuration
DATABASE_URL: postgres://shumai:shumai_password@shumai_postgres:5432/shumai_db?search_path=public&sslmode=disable
@@ -41,6 +44,7 @@ services:
# Better Auth
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL: http://localhost:3000
# Sandbox Configuration
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
@@ -0,0 +1,44 @@
# Configurations for hardware-accelerated transcoding
services:
cpu: {}
nvenc:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
- compute
- video
quicksync:
devices:
- /dev/dri:/dev/dri
rkmpp:
security_opt: # enables full access to /sys and /proc, still far better than privileged: true
- systempaths=unconfined
- apparmor=unconfined
group_add:
- video
devices:
- /dev/rga:/dev/rga
- /dev/dri:/dev/dri
- /dev/dma_heap:/dev/dma_heap
- /dev/mpp_service:/dev/mpp_service
vaapi:
devices:
- /dev/dri:/dev/dri
vaapi-wsl: # use this for VAAPI if running in WSL2
devices:
- /dev/dri:/dev/dri
- /dev/dxg:/dev/dxg
volumes:
- /usr/lib/wsl:/usr/lib/wsl
environment:
- LIBVA_DRIVER_NAME=d3d12
@@ -1,86 +0,0 @@
services:
# --- Shumai Application Services ---
postgres:
image: pgvector/pgvector:pg18
container_name: shumai_postgres
environment:
POSTGRES_USER: shumai
POSTGRES_PASSWORD: shumai_password
POSTGRES_DB: shumai_db
ports:
- '5432:5432'
volumes:
- postgres_data:/var/lib/postgresql
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U shumai -d shumai_db']
interval: 5s
timeout: 5s
retries: 5
shumai:
image: shumaione/shumai:latest
container_name: shumai_app
ports:
- '3000:3000'
volumes:
- shumai_data:/app/data
environment:
DATABASE_URL: postgres://shumai:shumai_password@postgres:5432/shumai_db?search_path=public&sslmode=disable
STORAGE_BACKEND: s3
AWS_ENDPOINT_URL_S3: S3_ENDPOINT_URL
S3_REGION: S3_REGION
S3_BUCKET: BUCKET_NAME
S3_ACCESS_KEY_ID: ID
S3_SECRET_ACCESS_KEY: KEY
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
WORKFLOW_EXECUTOR: temporal
TEMPORAL_ADDRESS: temporal:7233
GEMINI_API_KEY: KEY
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
depends_on:
postgres:
condition: service_healthy
temporal:
condition: service_healthy
# --- Temporal Services ---
temporal:
image: temporalio/auto-setup:latest
container_name: temporal_server
environment:
- DB=postgres12
- DB_PORT=5432
- POSTGRES_USER=shumai
- POSTGRES_PWD=shumai_password
- POSTGRES_SEEDS=postgres
- BIND_ON_IP=0.0.0.0
ports:
- '7233:7233'
healthcheck:
test:
[
'CMD-SHELL',
'temporal operator cluster health --address localhost:7233 || temporal operator cluster health --address $$(hostname -i):7233',
]
interval: 5s
timeout: 5s
start_period: 30s
retries: 10
depends_on:
postgres:
condition: service_healthy
temporal-ui:
image: temporalio/ui:latest
container_name: temporal_ui
environment:
- TEMPORAL_ADDRESS=temporal:7233
ports:
- '8080:8080'
depends_on:
temporal:
condition: service_healthy
volumes:
postgres_data:
shumai_data:
+1006
View File
File diff suppressed because it is too large Load Diff
+250
View File
@@ -0,0 +1,250 @@
---
title: Archive Storage
description: Configure secondary cold storage to offload raw media files while preserving in-browser proxy playback and previews.
---
High-resolution camera footage, RAW image sequences, master audio stems, and large 3D assets quickly consume primary storage. Shumai's **Archive Storage** feature enables creative teams to offload heavy master original files to cost-effective cold storage (such as a local NAS, AWS S3 Glacier, or Google Cloud Storage Coldline) while keeping all proxy media, preview images, waveform files, and metadata in primary storage.
Team members can continue to browse, search, scrub, and review archived assets in the web browser without interruption. When the original raw file is needed for mastering or color grading, it can be restored back to primary storage with a single click.
---
## How It Works
1. **Original-Only Archiving**: Only the original raw file is moved to archive storage. Previews, thumbnails, and transcoded proxies (e.g., 180p scrubbing proxies, 1080p streamable MP4s, WebP posters) remain in primary storage.
2. **Durable Asynchronous Workflows**: Moving and restoring files is handled by background worker tasks on a dedicated queue (`archive_queue`) managed by DBOS. Tasks automatically survive network interruptions, slow S3 transfers, and server restarts.
3. **Transparent Asset Lifecycle**:
- When an asset is being archived, its status transitions to `archiving` and settles at `archived`.
- When an asset is being restored, its status transitions to `restoring` and returns to `processed` once the original file is back in primary storage.
- Trashed assets that are permanently purged automatically delete their original file from archive storage as well.
4. **Folder & Version Stack Support**: Archiving a folder or version stack recursively archives all contained file assets. Restoring a folder or version stack restores all archived files inside it.
---
## Storage Topologies
Shumai supports flexible storage configurations where primary storage and archive storage can use different backends or storage providers:
| Topology | Main Storage | Archive Storage | Description |
| :------------------------------------ | :----------- | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Local NAS / Directory** | Local or S3 | `local` | Offload files to a mounted network folder (NFS / SMB) or a secondary cold disk array. |
| **Separate S3 Bucket / Provider** | S3 or Local | `s3` | Stream files to a dedicated archive bucket on AWS S3, Wasabi, Backblaze B2, or Google Cloud Storage. |
| **Same S3 Bucket (In-Place Tiering)** | AWS S3 | `s3` | Re-tier objects in-place on AWS S3 using cold storage classes (`GLACIER`, `GLACIER_IR`, `DEEP_ARCHIVE`) without re-uploading bytes over the network. |
---
## Configuration Variables
Configure archive storage by adding the following environment variables to your `.env` file or Docker Compose configuration.
### General Configuration
| Variable | Description | Required | Default |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :--------------- |
| `ARCHIVE_STORAGE_BACKEND` | Storage backend for archives: `local` or `s3`. When unset, archive functionality is disabled in the WebUI. | No | Unset (Disabled) |
| `CONCURRENCY_ARCHIVE` | Maximum concurrent archive and restore tasks executed by background workers. | No | `5` |
| `SHUMAI_WORKERS` | Worker queues listened to by the application server: `all` (default), `none`, `agent` (or `ai`), `transcode`, `archive`. Set to `all` or `archive` to process tasks. | No | `all` |
| `AUTO_ARCHIVE_INTERVAL_MINUTES` | Frequency (in minutes) of the background auto-archive scanner job. Accepts decimal numbers (e.g. `0.02` for testing). | No | `60` (1 hour) |
### Local Archive Storage
Used when `ARCHIVE_STORAGE_BACKEND=local`:
| Variable | Description | Required | Default |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :--------------- |
| `ARCHIVE_LOCAL_ROOT` | Host filesystem directory path where archived files are stored. Must not overlap with main local storage directory (`./data` or `./data/<S3_BUCKET>`). | Yes | Unset (Required) |
### S3 Archive Storage
Used when `ARCHIVE_STORAGE_BACKEND=s3`. Note that archive storage maintains its own configuration and **never falls back** to the primary `S3_*` environment variables:
| Variable | Description | Required | Default |
| :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------------------------------------ |
| `ARCHIVE_S3_BUCKET` | Destination S3 bucket for archived files (can be a dedicated bucket or the same bucket as `S3_BUCKET` for in-place tiering). | Yes | Unset (Required) |
| `ARCHIVE_S3_ACCESS_KEY_ID` | Access key ID for the archive S3 service. | Yes | Unset (Required) |
| `ARCHIVE_S3_SECRET_ACCESS_KEY` | Secret access key for the archive S3 service. | Yes | Unset (Required) |
| `ARCHIVE_AWS_ENDPOINT_URL_S3` | S3 endpoint URL for archive storage (e.g. MinIO, Cloudflare R2, Google Cloud Storage). | No | Unset (AWS standard endpoint) |
| `ARCHIVE_S3_REGION` | S3 region for the archive bucket. | No | `auto` |
| `ARCHIVE_S3_FORCE_PATH_STYLE` | Use path-style S3 URLs (`true` for MinIO/path-style, `false` for virtual-hosted style). | No | `true` |
| `ARCHIVE_S3_STORAGE_CLASS` | S3 storage class to apply to archived objects (e.g. `GLACIER`, `GLACIER_IR`, `DEEP_ARCHIVE`, `COLDLINE`). Required and must not be `STANDARD` when archiving to the same S3 bucket. | No | Unset |
| `ARCHIVE_S3_USE_RESTORE_OBJECT` | Controls whether S3 `RestoreObject` is called before reading archived objects (`auto`, `true`, or `false`). | No | `auto` |
| `ARCHIVE_S3_RESTORE_DAYS` | Number of days a restored temporary copy remains readable in S3 for asynchronous Glacier restores. | No | `1` |
| `ARCHIVE_S3_RESTORE_TIER` | S3 Glacier retrieval tier (`Expedited`, `Standard`, or `Bulk`). Omit when using providers that do not require asynchronous retrieval. | No | Unset |
| `ARCHIVE_RESTORE_POLL_INTERVAL_MS` | Milliseconds between status checks while waiting for an asynchronous cold storage restore. | No | `60000` (1 min initial, 5 min steady) |
---
## Configuration Examples
### 1. Local NAS / Mounted Path
Ideal for self-hosted teams with on-premises Network Attached Storage (Synology, QNAP, TrueNAS, or an NFS/SMB share mounted to the host machine):
```env
# Main storage on local disk or S3
STORAGE_BACKEND=local
LOCAL_STORAGE_PATH=./storage
# Archive storage pointing to your mounted NAS directory
ARCHIVE_STORAGE_BACKEND=local
ARCHIVE_LOCAL_ROOT=/mnt/nas/shumai-archive
```
In `docker-compose.yaml`, mount the host NAS volume into the container:
```yaml
services:
shumai:
volumes:
- /mnt/nas/shumai-archive:/mnt/nas/shumai-archive
environment:
ARCHIVE_STORAGE_BACKEND: local
ARCHIVE_LOCAL_ROOT: /mnt/nas/shumai-archive
```
---
### 2. AWS S3 Glacier Instant Retrieval (Archive)
AWS S3 Glacier Instant Retrieval (`GLACIER_IR`) offers cold storage pricing with **millisecond retrieval latency**. Because objects in `GLACIER_IR` do not require an asynchronous `RestoreObject` request, restoring an asset to main storage is instantaneous.
#### Same-Bucket In-Place Tiering (Fast Path)
If your main storage is AWS S3, you can tier files into `GLACIER_IR` within the **same bucket** without re-uploading bytes over the network:
```env
# Main Storage
STORAGE_BACKEND=s3
S3_BUCKET=my-shumai-production
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
# Archive Storage (same bucket & credentials with cold storage class)
ARCHIVE_STORAGE_BACKEND=s3
ARCHIVE_S3_BUCKET=my-shumai-production
ARCHIVE_S3_REGION=us-east-1
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
ARCHIVE_S3_STORAGE_CLASS=GLACIER_IR
```
#### Dedicated Archive Bucket
If you prefer keeping archived media in a separate S3 bucket:
```env
# Archive Storage in a separate bucket
ARCHIVE_STORAGE_BACKEND=s3
ARCHIVE_S3_BUCKET=my-shumai-archive-glacier-ir
ARCHIVE_S3_REGION=us-east-1
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
ARCHIVE_S3_STORAGE_CLASS=GLACIER_IR
```
---
### 3. AWS S3 Glacier Flexible Archive (Cold Storage)
For maximum cost savings on rarely accessed footage, AWS S3 Flexible Archive (`GLACIER`) or Deep Archive (`DEEP_ARCHIVE`) stores data at the lowest storage rates.
When a user restores an asset from Glacier, Shumai initiates a `RestoreObject` request, puts the background workflow into durable DBOS sleep, and periodically checks until AWS completes the retrieval:
```env
ARCHIVE_STORAGE_BACKEND=s3
ARCHIVE_S3_BUCKET=my-shumai-cold-archive
ARCHIVE_S3_REGION=us-east-1
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
ARCHIVE_S3_STORAGE_CLASS=GLACIER
# Keep the restored temporary copy accessible for 7 days
ARCHIVE_S3_RESTORE_DAYS=7
# Glacier retrieval tier: Standard (3-5 hours), Expedited (1-5 min), or Bulk (5-12 hours)
ARCHIVE_S3_RESTORE_TIER=Standard
```
> [!NOTE]
> During a Glacier restore, DBOS schedules durable sleep timers in PostgreSQL. The worker thread is completely freed and does not consume concurrency slots while waiting for AWS to thaw the file.
---
### 4. Google Cloud Storage Coldline (Archive)
Google Cloud Storage (GCS) provides S3-compatible XML APIs and low-cost storage classes such as `COLDLINE` and `ARCHIVE`. Like Glacier Instant Retrieval, GCS Coldline provides **immediate access** without requiring an asynchronous thaw step:
```env
# Main storage (e.g. Cloudflare R2, MinIO, or standard GCS)
STORAGE_BACKEND=s3
S3_BUCKET=shumai-main
...
# Archive storage on GCS Coldline
ARCHIVE_STORAGE_BACKEND=s3
ARCHIVE_S3_BUCKET=shumai-coldline-archive
ARCHIVE_S3_ACCESS_KEY_ID=GOOG1EXAMPLETOCKENKEY
ARCHIVE_S3_SECRET_ACCESS_KEY=your-gcs-hmac-secret-access-key
ARCHIVE_AWS_ENDPOINT_URL_S3=https://storage.googleapis.com
ARCHIVE_S3_STORAGE_CLASS=COLDLINE
```
> [!TIP]
> Google Cloud Storage objects are readable immediately and do not accept AWS Glacier retrieval parameters. Do not set `ARCHIVE_S3_RESTORE_TIER`. If using GCS's `ARCHIVE` storage class, set `ARCHIVE_S3_USE_RESTORE_OBJECT=false` to bypass S3 `RestoreObject` calls.
---
## Automatic Asset Archival
In addition to manual on-demand archival, Shumai allows teams to automate cold storage tiering based on asset age lifecycle policies. This ensures heavy original master files are automatically offloaded to secondary cold storage without requiring manual housekeeping from creative staff or administrators.
### WebUI Configuration
Team owners can configure automatic archival under **Team Settings > Storage**:
1. **Archive Storage Status Overview**:
- Displays the current system archive storage backend (`local` or `s3`), endpoint, bucket, or root directory configured on the server.
- If archive storage is not configured in server environment variables, a warning alert is displayed, and auto-archive controls are disabled.
- For security, credentials and private server settings are not exposed to client browsers.
2. **Automatic Asset Archival Policy**:
- **Enable Auto Archive**: Toggle automated background archival on or off for the team (disabled by default; requires an active archive storage backend).
- **Archive Criteria (`method`)**:
- **Not modified for specified days (`not_updated`)**: Evaluates the last modification timestamp (`updatedAt`). Ideal for active production workflows—files stay in fast primary storage as long as team members are actively commenting, annotating, or modifying them. Once no modifications have occurred for the configured duration, the asset is moved to cold storage.
- **After creation for specified days (`after_created`)**: Evaluates the initial upload/creation timestamp (`createdAt`). Ideal for strict retention or compliance pipelines where footage is tiered based on its age (e.g., 60 or 90 days after delivery) regardless of recent review comments.
- **Age Threshold (`days`)**: The threshold in days (between 1 and 3,650 days) after which eligible assets are queued for archival.
- **Post-Restore Grace Period (`postRestoreGraceDays`)**:
- When an asset is restored from archive back to primary storage, its modification date is refreshed to the restore time.
- When using the **After creation** rule, an asset older than the threshold (e.g. 100 days old) would otherwise be immediately picked up and re-archived by the very next hourly scan.
- The post-restore grace period (default: 30 days) guarantees that restored files remain in primary storage for at least the specified number of days before becoming eligible for automated archival again. This value should be set smaller than the Age Threshold. Under this policy, only files that are older than the Age Threshold and have also surpassed the Post-Restore Grace Period since restoration are auto-archived.
### Sibling Deduplication & Safety
Shumai uses content-addressable storage keys (`storage_keys`) to deduplicate identical files across projects and folders:
- **Sibling Protection**: If multiple asset records reference the same underlying storage object (e.g., copied or duplicated files across folders or projects), the auto-archive scanner inspects all sibling assets.
- **Strict Consensus**: The underlying storage file is **only** archived if **all active sibling files** satisfy the team's auto-archive criteria and are in a stable `processed` state.
- **Starvation-Free Scheduling**: If any sibling copy was modified recently or is currently in an active workflow, the storage key is safely skipped without blocking other eligible assets from being archived.
### Background Scanner & Execution Semantics
The auto-archive job runs periodically in the background:
- **Scan Frequency**: Configured via the `AUTO_ARCHIVE_INTERVAL_MINUTES` environment variable (defaults to `60` minutes; accepts decimal values such as `0.02` for automated testing).
- **Distributed Leader Election**: Uses PostgreSQL transaction-scoped advisory locks (`pg_try_advisory_xact_lock`) during the candidate discovery phase. In multi-pod or multi-replica container deployments, only one server instance performs the scan per interval while other replicas cleanly skip.
- **Race Condition Prevention**: During archival, candidate assets transition atomically via conditional SQL (`UPDATE assets SET status = 'archiving' WHERE status = 'processed'`) protected by row-level `storage_keys FOR UPDATE` locks. This guarantees zero race conditions with concurrent manual user archival, restoration, or file deletion.
---
## WebUI Behavior & Permissions
- **Permissions**: Only team **Owners** and **Editors** can archive or restore assets.
- **Context Menus**: Right-click any file, folder, or version stack in the file browser to select **Archive** or **Restore from Archive**.
- **Visual Badges**: Archived items display an `Archived` badge on grid cards and list rows. Inside the file viewer, an archive icon is displayed in front of the file name in the breadcrumb bar.
- **Playback & Previews**: Video streaming, scrubbers, waveform audio, PDF rendering, and image viewing remain fully functional using cached proxies.
- **Download Restrictions**: The download button for the original raw file is disabled with a tooltip explaining that the raw file is archived. Transcoded proxy downloads (e.g. 1080p MP4) remain available.
+173
View File
@@ -0,0 +1,173 @@
---
title: Deploy with Distributed Workers
description: Configure a high-scale production deployment using dedicated background workers, DBOS, and S3-compatible storage.
---
For production environments or workloads with high-volume video processing and heavy AI agent usage, running background tasks on a single server can cause bottlenecks. Shumai resolves this by decoupling the web dashboard from background processing through dedicated worker nodes orchestrated by **DBOS Transact**.
All background tasks (media transcoding, AI embeddings, agent tasks) are dispatched to durable task queues (`transcode_queue` and `agent_queue`) hosted directly in PostgreSQL. No separate external cluster (like Temporal) is required.
---
## How it Works
In a distributed deployment, the core Shumai web application handles user requests, database updates, and file uploads, while delegating durable background workflows to specialized worker instances via PostgreSQL task queues.
```mermaid
graph TD
UserUpload[User Uploads Video / Triggers Agent] --> WebApp[Shumai Web UI / API]
WebApp -->|Enqueue Task| DB[(PostgreSQL / DBOS Queues)]
DB -->|Queue: transcode_queue| TranscodeWorker[Transcode Worker Machine]
DB -->|Queue: agent_queue| AgentWorker[Agent Worker Machine]
```
- **Transcoding Workers**: Can be run on GPU-accelerated or high-CPU compute instances.
- **AI Agent Workers**: Can be run on isolated, sandboxed hosts to safely execute automation scripts.
> [!IMPORTANT]
> **Storage Requirement**: Because the core application and the background workers run on separate machines in a distributed setup, **you must configure an S3-compatible storage backend** (such as AWS S3, Cloudflare R2, or MinIO). Local storage (`STORAGE_BACKEND=local`) is not supported in this mode because the workers and the web application do not share a common filesystem.
---
## Step 1: Deploy the Core Web Application
On your primary host machine, run PostgreSQL and the main Shumai web application.
To instruct the main web application to handle only API and UI traffic without running background worker queues locally, set `SHUMAI_WORKERS=none`:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
STORAGE_BACKEND=s3
AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com
S3_BUCKET=shumai
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
SHUMAI_WORKERS=none
BETTER_AUTH_SECRET=your-random-32-character-secret-key
```
When started with `SHUMAI_WORKERS=none` (or `--workers=none`), the web server starts immediately without polling or consuming tasks from the transcode or agent queues.
---
## Step 2: Configure & Run Dedicated Workers
On your specialized worker machines, configure each worker with a `.env` file referencing the shared PostgreSQL database and S3 storage:
```env
DATABASE_URL=postgresql://shumai:shumai_password@<primary-host-ip>:5432/shumai_db?schema=public
STORAGE_BACKEND=s3
AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com
S3_BUCKET=shumai
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
CONCURRENCY_TRANSCODE=1
CONCURRENCY_AGENT=5
```
### Media Transcoding Worker
Run this on your media processing nodes (requires system installations of `ffmpeg` and `ffprobe`):
```bash
npm install -g @shumai-one/shumai-transcode
shumai-transcode
```
Alternatively, you can run the transcode worker using the dedicated lightweight Docker image:
```bash
docker run -d \
--name shumai-transcode-worker \
--env-file .env \
shumaione/shumai-transcode:latest
```
(You can also use the all-in-one image: `docker run -d --name shumai-transcode-worker --env-file .env shumaione/shumai:latest shumai-transcode`.)
### AI Agent Worker
Run this on your sandboxed agent execution nodes (requires sandbox dependencies like `bubblewrap` or `sandbox-exec`):
```bash
npm install -g @shumai-one/shumai-agent
shumai-agent
```
Alternatively, you can run the agent worker using the official Docker image:
```bash
docker run -d \
--name shumai-agent-worker \
--env-file .env \
--cap-add=SYS_ADMIN \
shumaione/shumai:latest shumai-agent
```
> [!IMPORTANT]
> **For Bun Users:** Since the worker package binaries contain a `#!/usr/bin/env node` shebang, running `shumai-transcode` or `shumai-agent` directly will run under Node.js. If you wish to run them using Bun, prefix the commands with `bun run --bun` (e.g., `bun run --bun shumai-transcode` or `bun run --bun shumai-agent`).
---
## Worker Concurrency & Multi-Instance Deployments
### Concurrency Tuning
Workers pull tasks from PostgreSQL queues based on configurable concurrency limits:
- `CONCURRENCY_TRANSCODE`: Maximum concurrent video transcoding jobs per worker (defaults to `1`).
- `CONCURRENCY_AGENT`: Maximum concurrent agent and embedding workflows per worker (defaults to `5`, recommend setting to `1` when paired with a local `embedding-server`).
### Replica Identity
When running multiple replicas of the transcode or agent worker across multiple machines or pods:
- `DbosExecutor` automatically derives a unique per-instance ID from the machine hostname and process ID to ensure startup recovery only re-enqueues tasks belonging to that specific instance.
- **Custom Worker ID**: Set `SHUMAI_WORKERS_ID` (or `SHUMAI_WORKER_ID`) if you wish to assign an explicit identifier.
- **Kubernetes**: In Kubernetes Pods, set `POD_NAME` (via Downward API `fieldRef: { fieldPath: metadata.name }`) to provide stable, unique per-pod identity across pod restarts.
---
## Scalable Deployment on Kubernetes & AWS EKS
For production cloud deployments requiring high-throughput media processing, Shumai can be deployed on Kubernetes or **AWS Elastic Kubernetes Service (AWS EKS)** with automated scale-to-zero queue-driven scaling via **KEDA (Kubernetes Event-driven Autoscaling)**.
```mermaid
graph TD
User([User / Web Browser]) -->|Port 80/3000| Server[Pod: shumai-server<br/>SHUMAI_WORKERS=agent]
Server -->|Enqueue to transcode_queue| DB[(PostgreSQL: pgvector18<br/>dbos.workflow_status)]
Server -->|Direct Uploads / Stream Proxies| Storage[(S3 / Garage Storage)]
KEDA[KEDA ScaledJob<br/>PostgreSQL Trigger<br/>min: 0, max: 10] -.->|Monitors Queue| DB
KEDA -->|Spawns Jobs for queue| Job1[Job: shumai-transcode-1<br/>Auto-drain worker]
KEDA -->|Spawns Jobs for queue| JobN[Job: shumai-transcode-N<br/>Auto-drain worker]
Job1 -->|Fetch Source / Store Proxies| Storage
JobN -->|Fetch Source / Store Proxies| Storage
Job1 -->|Mark Complete & Exit 0| DB
JobN -->|Mark Complete & Exit 0| DB
CA[Cluster Autoscaler / Karpenter] -.->|Scale-to-Zero On-Demand Nodes<br/>0 to 10 instances| JobN
```
### Key Architectural Highlights
- **Decoupled Stateless Workers**: The main web and API server, database, and storage run on reliable On-Demand compute (`c9g.large`, `SHUMAI_WORKERS=agent`), delegating media transcoding to background workers orchestrated via DBOS task queues in PostgreSQL.
- **Dedicated Graviton5 On-Demand Compute (`c9g.xlarge`)**: Media encoding runs on 4 vCPU / 8 GiB RAM AWS Graviton5 On-Demand instances (~$0.174/hr), utilizing ARM64 vector optimizations and high-speed DDR5 memory without involuntary Spot interruptions.
- **Queue-Driven Scale-to-Zero via KEDA**: KEDA monitors `dbos.workflow_status` for enqueued and pending transcode tasks and dynamically provisions Kubernetes `ScaledJob` resources (scaling 0 to 10). When the queue is empty, transcode nodes scale down to zero (`minSize: 0`), incurring **$0/hr** in worker costs.
- **Idle-Timeout Auto-Drain**: Worker pods continuously process queued tasks with concurrency `1`. When the queue is fully drained and a pod has been idle for 10 seconds (`SHUMAI_WORKER_IDLE_TIMEOUT_MS=10000`), it exits `0` cleanly so the node can scale down, processing batch uploads without cold-start pod churn.
- **Automated Stale Task Recovery**: The core web server runs an integrated recovery sweep that detects stale or orphaned tasks (e.g. from node crash) and resumes them automatically in DBOS, with a 3-attempt cap to safely handle poison-pill media.
### Complete Deployment Example & Source Code
For the full, production-ready manifests, declarative `eksctl` cluster configuration, and step-by-step walkthrough, see the **[EKS Deployment Example](https://github.com/shumaiOne/shumai/tree/main/eks)** in the Shumai repository:
👉 **[View the EKS Deployment Guide & Manifests on GitHub](https://github.com/shumaiOne/shumai/tree/main/eks)**
The repository includes:
- [`eks/eks-cluster.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/eks-cluster.yaml): Complete `eksctl` ClusterConfig with compute tiering.
- [`eks/kustomization.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/kustomization.yaml): Single-command Kustomize deployment for all services.
- Detailed instructions for setting up public endpoints, automated Cluster Autoscaler, and zero-downtime graceful shutdown.
+82 -21
View File
@@ -24,12 +24,13 @@ Shumai is configured via environment variables. You can define these variables i
---
## Authentication Config
## Authentication & Application Config
| Variable | Description | Example / Default |
| :------------------- | :--------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | A secure, random 32-byte secret used to sign session cookies and JWTs. | Generate with `openssl rand -base64 32` |
| `BETTER_AUTH_URL` | The public URL of your Hono backend API. Used for redirect flows. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback) |
| Variable | Description | Example / Default |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | A secure, random 32-byte secret used to sign session cookies and JWTs. | Generate with `openssl rand -base64 32` |
| `BETTER_AUTH_URL` | The public URL of your Shumai server. Used for MCP OAuth 2.1 discovery, redirect flows, password reset links, and email notifications. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback) |
| `APP_URL` | The public URL of the web application. Used for notification email deep links (falls back to `BETTER_AUTH_URL`). | `https://shumai.example.com` |
---
@@ -37,15 +38,16 @@ Shumai is configured via environment variables. You can define these variables i
Shumai supports storing files locally or on S3-compatible endpoints.
| Variable | Description | Example / Default |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------ |
| `STORAGE_BACKEND` | Storage type. Use `local` for local file system storage, or `s3` for S3-compatible cloud storage. | `local` (default) or `s3` |
| `AWS_ENDPOINT_URL_S3` | Endpoint for S3 storage or local storage. Used by the browser to build file upload URLs. Must include port if deploying remotely or using custom ports. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback if unset) |
| `S3_BUCKET` | S3 bucket name. | `shumai` (default) |
| `S3_ACCESS_KEY_ID` | Access key credentials for S3. | `minioadmin` (default) |
| `S3_SECRET_ACCESS_KEY` | Secret key credentials for S3. | `minioadmin` (default) |
| `S3_REGION` | S3 storage region. | `auto` (default) |
| `PRESIGNED_URL_EXPIRES_IN` | Number of hours for which generated presigned download/upload links are valid. | `5` (default) |
| Variable | Description | Example / Default |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------ |
| `STORAGE_BACKEND` | Storage type. Use `local` for local file system storage, or `s3` for S3-compatible cloud storage. | `local` (default) or `s3` |
| `AWS_ENDPOINT_URL_S3` | Endpoint for S3 storage or local storage. Used by the browser to build file upload URLs. Must include port if deploying remotely or using custom ports. | `http://localhost:3000` (respects `SHUMAI_SERVER_PORT` fallback if unset) |
| `S3_BUCKET` | S3 bucket name. | `shumai` (default) |
| `S3_ACCESS_KEY_ID` | Access key credentials for S3. | `minioadmin` (default) |
| `S3_SECRET_ACCESS_KEY` | Secret key credentials for S3. | `minioadmin` (default) |
| `S3_REGION` | S3 storage region. | `auto` (default) |
| `PRESIGNED_URL_EXPIRES_IN` | Number of hours for which generated presigned download links are valid. | `5` (default) |
| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | Number of hours for which generated presigned upload links are valid. Falls back to `PRESIGNED_URL_EXPIRES_IN` if unset. | `12` (default) |
### Local Storage Port Configuration
@@ -59,18 +61,51 @@ For example, if you deploy Shumai on a remote server at `http://123.456.7.8` and
- Set `SHUMAI_SERVER_PORT` to `3000`.
- Set `AWS_ENDPOINT_URL_S3` to `http://123.456.7.8:12345`.
### Archive Storage Config
Shumai supports configuring an optional **Archive Storage** tier (`local` NAS/directory or `s3` bucket/storage class) for moving original raw files while keeping proxies, previews, thumbnails, and metadata in main storage.
| Variable | Description | Example / Default |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------- |
| `ARCHIVE_STORAGE_BACKEND` | Archive storage type. Leave unset to disable archive storage, or set to `local` or `s3`. | Unset (disabled), `local`, or `s3` |
| `ARCHIVE_LOCAL_ROOT` | Required when `ARCHIVE_STORAGE_BACKEND=local`. Root directory (e.g., a mounted NAS folder) where archived original files are stored directly under `<ARCHIVE_LOCAL_ROOT>/<key>`. | `/mnt/nas/shumai-archive` |
| `ARCHIVE_AWS_ENDPOINT_URL_S3` | Optional custom S3 endpoint for archive storage when `ARCHIVE_STORAGE_BACKEND=s3` (independent of `AWS_ENDPOINT_URL_S3`). | `https://s3.us-east-1.amazonaws.com` |
| `ARCHIVE_S3_BUCKET` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. Target S3 bucket for archived files (can be a dedicated bucket or the same bucket as `S3_BUCKET` with a cold storage class). | `shumai-archive` |
| `ARCHIVE_S3_ACCESS_KEY_ID` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. S3 access key ID for archive storage. | `AKIA...` |
| `ARCHIVE_S3_SECRET_ACCESS_KEY` | Required when `ARCHIVE_STORAGE_BACKEND=s3`. S3 secret access key for archive storage. | `...` |
| `ARCHIVE_S3_REGION` | S3 region for archive storage when `ARCHIVE_STORAGE_BACKEND=s3`. | `auto` (default) |
| `ARCHIVE_S3_STORAGE_CLASS` | Optional S3 `StorageClass` header applied when archiving objects (accepts any standard or provider-specific class string; required and must not be `STANDARD` for same-bucket tiering). | `GLACIER_IR`, `GLACIER`, `DEEP_ARCHIVE`, `STANDARD_IA` |
| `ARCHIVE_S3_USE_RESTORE_OBJECT` | Controls whether S3 `RestoreObject` is called before reading archived objects (`auto`, `true`, or `false`). | `auto` (default) |
| `ARCHIVE_S3_RESTORE_DAYS` | Number of days a restored copy of a cold S3 object remains readable during restoration. | `1` (default) |
| `ARCHIVE_S3_RESTORE_TIER` | Optional S3 Glacier retrieval tier (`Expedited`, `Standard`, `Bulk`). Omitted when unset for S3-compatible providers that reject `GlacierJobParameters`. | Unset (default) |
| `AUTO_ARCHIVE_INTERVAL_MINUTES` | Frequency (in minutes) of the background auto-archive scanner job. Accepts decimal values (e.g. `0.02` for testing). | `60` (1 hour default) |
---
## Workflow Config
Configures whether background transcoding and AI agents are executed locally or offloaded to a Temporal cluster.
Configures background worker execution, concurrency limits, and worker identity for DBOS Transact queues.
| Variable | Description | Example / Default |
| :------------------------- | :------------------------------------------------------------------------------------------------- | :------------------------------ |
| `WORKFLOW_EXECUTOR` | Engine choice. Use `local` for in-process database polling, or `temporal` for distributed workers. | `local` (default) or `temporal` |
| `TEMPORAL_ADDRESS` | Host and port of the Temporal cluster gRPC service. | `localhost:7233` (default) |
| `EMBEDDING_CHUNK_DURATION` | The duration in seconds for each video chunk when generating video embeddings. | `60.0` (default) |
| `EMBEDDING_CHUNK_OVERLAP` | The duration in seconds to overlap video chunks when generating video embeddings. | `5.0` (default) |
| Variable | Description | Example / Default |
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------- |
| `SHUMAI_WORKERS` | Queues listened to by the web server. Options: `all` (default), `none` (API/UI only), `agent` (or `ai`), `transcode`, `archive`. | `all` (default) |
| `CONCURRENCY_TRANSCODE` | Maximum concurrent media transcoding tasks executed by workers. | `1` (default) |
| `CONCURRENCY_ARCHIVE` | Maximum concurrent archive and restore tasks executed by workers. | `5` (default) |
| `CONCURRENCY_AGENT` | Maximum concurrent AI tasks executed by workers. Set to `1` when running local `embedding-server`. | `5` (default) |
| `SHUMAI_WORKER_ID` | Optional explicit instance ID for worker replicas in multi-node deployments (auto-derived from hostname and process ID if unset). | `worker-1` |
| `POD_NAME` | Kubernetes pod name, used to provide stable per-pod worker identity across StatefulSet restarts. | `transcode-pod-0` |
---
## Embedding Config
| Variable | Description | Example / Default |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------ | :-------------------------------- |
| `EMBEDDING_PROVIDER` | Multimodal embedding provider. Options: `gemini-embedding-2`, `gemma-embedding-2-openai`. | `gemini-embedding-2` (default) |
| `GEMMA_EMBEDDING_OPENAI_BASE_URL` | Base URL of the OpenAI-compatible LiteRT-LM embedding server. | `http://embedding-server:9379/v1` |
| `ENABLE_EMBEDDING_AGENT` | When set to `true`, automatically provisions and enables the system embedding agent for all teams on startup. | `false` (default) |
| `EMBEDDING_CHUNK_DURATION` | The duration in seconds for each video chunk when generating video embeddings. | `60.0` (default) |
| `EMBEDDING_CHUNK_OVERLAP` | The duration in seconds to overlap video chunks when generating video embeddings. | `5.0` (default) |
## Sandbox Config
@@ -98,3 +133,29 @@ API keys to AI providers on startup.
| `GEMINI_API_KEY` | API key for Google Gemini provider. | `AIzaSy...` |
| `OPENAI_API_KEY` | API key for OpenAI provider. | `sk-proj-...` |
| `ANTHROPIC_API_KEY` | API key for Anthropic provider. | `sk-ant-...` |
---
## External Integrations Config
Environment variables can configure external microservices globally. When set, these environment variables take precedence over any team-level settings configured in **Team Settings → Integrations**, and lock the corresponding settings fields in the WebUI to read-only.
### Gotenberg Document Converter
Used to convert Office documents, HTML, Markdown, and CSV files into high-fidelity PDF proxies for in-browser previewing. See the [Gotenberg Guide](/using-shumai/gotenberg) for setup instructions.
| Variable | Description | Example / Default |
| :------------------------------ | :----------------------------------------------------------------------- | :---------------------- |
| `GOTENBERG_URL` | Base URL of the external Gotenberg conversion API. | `http://gotenberg:3000` |
| `GOTENBERG_BASIC_AUTH_USERNAME` | Username when Basic Authentication is enabled on the Gotenberg instance. | `admin` |
| `GOTENBERG_BASIC_AUTH_PASSWORD` | Password when Basic Authentication is enabled on the Gotenberg instance. | `secret` |
### 3D Turntable Renderer
Used to convert 3D model files (GLB, OBJ, FBX, USD, STL, DAE) into interactive 360° turntable video proxies, posters, and hover sprites. See the [3D Asset Support Guide](/using-shumai/3d-asset-support) for setup instructions.
| Variable | Description | Example / Default |
| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :------------------------------- |
| `TURNTABLE_RENDERER_URL` | Base URL of the external turntable-renderer service. | `http://turntable-renderer:3000` |
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | Username when Basic Authentication is enabled on the turntable renderer (alias: `TURNTABLE_RENDERER_USERNAME`). | `admin` |
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | Password when Basic Authentication is enabled on the turntable renderer (alias: `TURNTABLE_RENDERER_PASSWORD`). | `secret` |
+233
View File
@@ -0,0 +1,233 @@
---
title: Hardware Transcoding
description: Accelerate video transcoding and reduce CPU load with GPU hardware acceleration.
---
High-resolution camera recordings, phone videos, and animation media files require proxy transcoding to play smoothly in web browsers. Shumai transcodes these assets in the background, generating a universal `180p` proxy for instant scrubbing alongside full-resolution preview streams.
Hardware-accelerated transcoding allows you to offload video encoding to a dedicated or integrated GPU, dramatically speeding up processing and freeing host CPU cores for other services.
Shumai includes a built-in usability probe that tests hardware encoders at startup, alongside automatic runtime fallback during video processing. If GPU drivers or device nodes are unavailable, or if a hardware encoder encounters hardware limits (such as resolution or dimension constraints on certain GPUs) or runtime driver errors, Shumai seamlessly falls back to software encoding (`libx264`) without failing user tasks.
---
## Supported Backends
| Backend | Hardware Platform | Container Driver / Devices |
| :-------------- | :--------------------------------- | :----------------------------------------------- |
| **`nvenc`** | NVIDIA GPUs | NVIDIA Container Toolkit (`gpu, compute, video`) |
| **`quicksync`** | Intel Integrated & Arc GPUs | `/dev/dri` render nodes |
| **`vaapi`** | AMD & Intel GPUs | `/dev/dri` render nodes |
| **`rkmpp`** | Rockchip ARM SoCs (e.g. RK3588) | `/dev/rga`, `/dev/dri`, `/dev/mpp_service` |
| **`vaapi-wsl`** | Windows Subsystem for Linux (WSL2) | `/dev/dri`, `/dev/dxg`, `/usr/lib/wsl` |
---
## Limitations
- The instructions on this page focus on **Docker Compose**. Other container orchestrators (such as Kubernetes or Podman) require equivalent device passthrough configurations.
- **Docker Desktop on macOS** runs inside a Linux virtual machine and does not support Apple Silicon VideoToolbox passthrough. (VideoToolbox hardware acceleration is supported when running Shumai natively via NPM or from source).
- Hardware transcoding produces slightly different bitrate characteristics compared to software encoding. Shumai uses adaptive variable bitrate (VBR) rate control tailored to web streaming to maintain visual fidelity.
---
## Prerequisites
### NVENC (NVIDIA)
1. Ensure the official NVIDIA graphics driver is installed on the host:
```bash
nvidia-smi
```
2. Install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) on the host and restart Docker:
```bash
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```
### QuickSync & VA-API (Intel / AMD)
1. Verify that the Linux kernel has initialized the Direct Rendering Infrastructure (DRI) render node:
```bash
ls -la /dev/dri
```
You should see `card0` and `renderD128` (or similar).
2. Shumai's Docker image automatically adjusts group permissions on container startup so the non-root application user can access host `/dev/dri` devices without permission errors.
#### GPU decoding
With VA-API, Shumai decodes and resizes video on the GPU as well as encoding it, so frames never leave GPU memory. This is much faster than decoding on the CPU, especially for 4K sources on integrated graphics. (Other backends currently decode on the CPU and encode on the GPU.)
Some videos automatically use CPU decoding with GPU encoding instead:
- Codecs your GPU cannot decode, such as HEVC or 10-bit video on older Intel chips. Shumai tries the GPU first and retries on the CPU within a second.
- Rotated videos, such as portrait phone recordings, so they keep the correct orientation.
- Watermarked share links and HDR sources.
If a GPU-decode attempt stops making progress for 2 minutes (some driver bugs make ffmpeg hang instead of failing), Shumai stops it and retries on the CPU. Change the limit with `SHUMAI_HW_DECODE_STALL_TIMEOUT` (in seconds).
To always decode on the CPU, set `SHUMAI_HW_DECODE=false` on the `shumai` service.
### WSL2 (Windows)
- Ensure you are running Windows 11 with WSL2 and have installed the appropriate GPU drivers on the Windows host.
- Use the `vaapi-wsl` preset which maps `/dev/dxg` and `/usr/lib/wsl` into the container.
---
## Setup with Docker Compose
Shumai uses a modular `hwaccel.transcoding.yaml` companion file to configure hardware devices.
### Step 1: Download Configuration Files
In your Shumai deployment directory, download the companion `hwaccel.transcoding.yaml` alongside `docker-compose.yaml`:
```bash
# Global / Official
curl -o hwaccel.transcoding.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml
# Accelerated Mirror (Mainland China)
curl -o hwaccel.transcoding.yaml https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml
```
### Step 2: Enable Hardware Acceleration in Docker Compose
Open `docker-compose.yaml` (or `docker-compose-aliyun.yaml`), find the commented `extends` block under the `shumai` service, and uncomment it:
```yaml
services:
shumai:
# ...
# Hardware Acceleration (NVENC / QuickSync / VA-API / RKMPP)
extends:
file: hwaccel.transcoding.yaml
service: nvenc # set to one of [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl]
```
Replace `nvenc` with your target backend:
- `nvenc` for NVIDIA GPUs
- `quicksync` for Intel Quick Sync
- `vaapi` for AMD or Intel VA-API
- `rkmpp` for Rockchip SoCs
- `vaapi-wsl` for WSL2 on Windows
### Step 3: Start the Stack
Restart or recreate the Shumai container:
```bash
docker compose up -d
```
---
## Single Compose File Setup (Unraid / Portainer)
If your environment or container manager does not support multi-file `extends`, you can inline the hardware configuration directly into the `shumai` service in `docker-compose.yaml`:
<AccordionGroup>
<Accordion title="NVIDIA NVENC">
```yaml
services:
shumai:
# ...
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
- compute
- video
```
</Accordion>
<Accordion title="Intel QuickSync / AMD VA-API">
```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri ```
</Accordion>
<Accordion title="WSL2 (Windows)">
```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri - /dev/dxg:/dev/dxg volumes: -
/usr/lib/wsl:/usr/lib/wsl environment: - LIBVA_DRIVER_NAME=d3d12 ```
</Accordion>
<Accordion title="Rockchip RKMPP">
```yaml
services:
shumai:
# ...
security_opt:
- systempaths=unconfined
- apparmor=unconfined
group_add:
- video
devices:
- /dev/rga:/dev/rga
- /dev/dri:/dev/dri
- /dev/dma_heap:/dev/dma_heap
- /dev/mpp_service:/dev/mpp_service
```
</Accordion>
</AccordionGroup>
---
## Web UI Settings
In the Shumai Web UI, navigate to **Team Settings** > **Transcoding Settings**.
- **Auto (Recommended)**: Shumai automatically probes candidate hardware encoders in optimal order (`h264_nvenc` &rarr; `h264_vaapi` &rarr; `h264_qsv` &rarr; `h264_amf` &rarr; `libx264`). If hardware acceleration is unavailable, it gracefully uses software encoding.
- **Explicit Encoder**: You can pin the transcode pipeline to a specific encoder (e.g. `NVENC`, `Quick Sync`, `VA-API`).
- **Off**: Forces CPU software encoding (`libx264`) for all video jobs.
---
## Verification & Monitoring
### Check Transcode Logs
When video transcoding begins on an uploaded asset, Shumai writes a structured log indicating the chosen encoder:
```bash
docker compose logs -f shumai
```
Look for the `Starting video transcoding` log entry:
```json
{
"level": 30,
"time": 1790414665096,
"encoder": "h264_nvenc",
"hardwareAcceleration": "auto",
"inputFile": "/tmp/transcode-.../video.mp4",
"outputFile": "/tmp/transcode-.../video-180p.mp4",
"msg": "Starting video transcoding"
}
```
If hardware acceleration was successfully initialized, `encoder` will show `h264_nvenc`, `h264_vaapi`, or `h264_qsv`.
### Monitor GPU Utilization
While transcoding a video, you can observe hardware utilization on the host:
- **NVIDIA**:
```bash
nvidia-smi
# or
nvtop
```
- **Intel**:
```bash
sudo intel_gpu_top
```
- **AMD**:
```bash
sudo radeontop
```
-85
View File
@@ -1,85 +0,0 @@
---
title: Deploy with Temporal
description: Configure a high-scale production deployment using Temporal and S3-compatible storage.
---
For production environments or workloads with high-volume video processing and heavy AI agent usage, running background tasks on a single server can cause bottlenecks. Shumai resolves this by offloading task queue management, retries, and background executions to **Temporal**.
This allows you to decouple workloads and run specialized worker nodes on separate, dedicated machines.
---
## How it Works
When configured for Temporal, the core Shumai web application does not process background jobs itself. Instead, it publishes tasks to a Temporal Cluster queue.
```mermaid
graph TD
UserUpload[User Uploads Video] --> WebApp[Shumai Web UI / API]
WebApp -->|Register Task| Temporal[Temporal Cluster]
Temporal -->|Queue: Transcoding| TranscodeWorker[Transcode Worker Machine]
Temporal -->|Queue: AI Agents| AgentWorker[Agent Worker Machine]
```
- **Transcoding Workers**: Can be run on GPU-accelerated or high-CPU compute instances.
- **AI Agent Workers**: Can be run on isolated, sandboxed hosts to safely execute automation scripts.
> [!IMPORTANT]
> **Storage Requirement**: Because the core application and the background workers run on separate machines in a distributed setup, **you must configure an S3-compatible storage backend** (such as AWS S3, Cloudflare R2, or MinIO). Local storage (`STORAGE_BACKEND=local`) is not supported in this mode because the workers and the web application do not share a common filesystem.
---
## Step 1: Deploy the Core Stack
On your primary host machine, spin up the database, Temporal cluster services, and the main Shumai web application:
1. **Download the Temporal Stack Configuration**:
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/temporal/docker-compose.yaml
```
2. **Configure S3 Settings**:
Open the `docker-compose.yaml` file and set your S3 credentials and endpoint environment variables under the `shumai` service.
3. **Start the Services**:
```bash
docker compose up -d
```
This exposes the web application on port `3000`, the database on `5432`, the Temporal gRPC service on `7233`, and the Temporal management dashboard on `8080`.
---
## Step 2: Configure & Run Workers
On your specialized worker machines, you will run the dedicated background worker services. Each worker requires a `.env` file referencing the database, S3 storage, and the Temporal cluster:
```env
DATABASE_URL=postgresql://shumai:shumai_password@<primary-host-ip>:5432/shumai_db?schema=public
WORKFLOW_EXECUTOR=temporal
TEMPORAL_ADDRESS=<primary-host-ip>:7233
STORAGE_BACKEND=s3
AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com
S3_BUCKET=shumai
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
```
### Media Transcoding Worker
Run this on your media processing nodes (requires system installations of `ffmpeg` and `ffprobe`):
```bash
npm install -g @shumai-one/shumai-transcode
shumai-transcode
```
### AI Agent Worker
Run this on your sandboxed agent execution nodes (requires sandbox dependencies like `bubblewrap` or `sandbox-exec`):
```bash
npm install -g @shumai-one/shumai-agent
shumai-agent
```
> [!IMPORTANT]
> **For Bun Users:** Since the worker package binaries contain a `#!/usr/bin/env node` shebang, running `shumai-transcode` or `shumai-agent` directly will run under Node.js. If you wish to run them using Bun, prefix the commands with `bun run --bun` (e.g., `bun run --bun shumai-transcode` or `bun run --bun shumai-agent`).
+222
View File
@@ -0,0 +1,222 @@
---
title: Shumai MCP Server
description: Let external AI agents such as Claude Code, Cursor, or Kiro work with your Shumai projects.
---
Shumai includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. Any MCP-compatible agent can connect to it and browse projects, look at images, videos, and documents, create folders, and organize assets on your behalf, using the same tools as Shumai's built-in agent.
<Note>
This page is about connecting **external agents to Shumai**. To connect Shumai's own agents to
other tools, see [MCP Servers](/using-shumai/mcp-servers).
</Note>
---
## Connecting a Client
The MCP server uses the Streamable HTTP transport at:
```
https://<your-shumai-host>/mcp
```
Shumai supports **OAuth 2.1** (recommended for seamless browser-based authentication) and **API tokens** (for headless environments or clients that do not support OAuth).
Pick your client below to get started:
### Claude Code
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) natively supports remote MCP servers with OAuth authentication. Add Shumai to your Claude Code configuration by running:
```bash
claude mcp add shumai --transport http https://<your-shumai-host>/mcp
```
When you start a new conversation, Claude Code will open a browser window for you to sign in and authorize access to your Shumai account. No manual API token is required.
Alternatively, you can manually configure `.claude/settings.json`:
```json
{
"mcpServers": {
"shumai": {
"type": "http",
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
Or connect stdio via `mcp-remote`:
```bash
claude mcp add shumai -- npx -y mcp-remote https://<your-shumai-host>/mcp
```
### Cursor
Add Shumai to your Cursor MCP configuration (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
When Cursor connects to the server, it will prompt you in the browser to complete the OAuth sign-in and authorize access.
To authenticate with an API token instead, pass the `Authorization` header:
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp",
"headers": {
"Authorization": "Bearer <your-api-token>"
}
}
}
}
```
### Codex
```bash
codex mcp add shumai --url https://<your-shumai-host>/mcp
codex mcp login shumai
```
### VS Code
```bash
code --add-mcp '{"name":"shumai","type":"http","url":"https://<your-shumai-host>/mcp"}'
```
Start the server from your **MCP Servers** list in VS Code and sign in to Shumai when prompted.
### Other Clients
**Remote (HTTP)**
If your client natively supports remote HTTP MCP servers:
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
**Local Bridge (`mcp-remote` / stdio)**
For clients that only support local (stdio) MCP servers, use `mcp-remote` to connect to Shumai's remote HTTP endpoint:
```json
{
"mcpServers": {
"shumai": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://<your-shumai-host>/mcp"]
}
}
}
```
---
## Authentication
Shumai's MCP server supports two authentication methods:
### OAuth 2.1 (Recommended)
Shumai implements OAuth 2.1 with Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) and OAuth Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) / [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)).
- **Seamless Sign-in**: Supported MCP clients automatically discover authorization endpoints and complete the OAuth handshake in your browser.
- **Access Control**: External agents act with your permissions in Shumai. Actions are attributed to your user account and logged in the team audit log with `via: mcp`.
- **Clearing OAuth Cache**: If you need to re-authenticate or clear stored credentials in CLI tools such as `mcp-remote` or Claude Code, remove the local authentication cache:
```bash
rm -rf ~/.mcp-auth
```
### API Tokens
API tokens are ideal for automated CI/CD pipelines, headless environments, or clients that do not support interactive OAuth.
1. In Shumai, open **Team Settings** → **API Tokens**.
2. Enter a name (for example, `ci-agent` or `cursor-token`) and click **Generate**.
3. Copy the token from the dialog. It is only shown once.
4. Pass the token in the `Authorization: Bearer <your-api-token>` header (or `x-api-key` header).
<Warning>
An API token acts as you: the agent can do anything your account can do in Shumai. Store it like a
password, use a separate token per client, and revoke tokens you no longer use from **Team
Settings** → **API Tokens**.
</Warning>
---
## Available Tools
| Tool | What it does |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `list_projects` | Lists the projects you can access, with each project's root folder. |
| `list_assets` | Lists files and folders in a folder, page by page. |
| `search_assets` | Searches a folder and its subfolders by name, by meaning (when AI search is enabled), or by metadata. |
| `create_folder` | Creates a folder. |
| `rename_asset` | Renames a file or folder. |
| `move_assets` | Moves files or folders into another folder. |
| `copy_assets` | Copies files or folders into another folder of the same team. |
| `delete_asset` | Moves a file or folder to the project trash. Marked as destructive so clients can ask you to confirm. |
| `read_asset` | Looks at a file: an image, video frames, PDF pages, a 3D model view, or the text of a text file. |
| `get_asset_render` | Gets the result of a `read_asset` call that was still rendering. |
| `download_asset` | Gets download links for up to 50 files: the web preview version by default, or the original with `proxy: false`. |
| `get_folder_instructions` | Reads a folder's instructions for AI agents (its AGENTS.md). |
| `create_file` | Starts uploading a new file into a folder (see [Uploading Files](#uploading-files)). |
| `create_version` | Starts uploading a new version of a file. |
| `complete_upload` | Finishes an upload started with `create_file` or `create_version`. |
| `list_comments` | Lists the review comments on a file, with their replies. |
| `create_comment` | Comments on a file (optionally at a timecode) or replies to a comment. |
| `resolve_comment` | Marks a comment as resolved, or unresolved again. |
| `list_metadata_fields` | Lists a project's metadata fields, such as status, rating, and custom fields, with their choices. |
| `update_asset_metadata` | Sets metadata values on a file. |
| `create_version_stack` | Stacks files in the same folder as versions of one asset. |
| `list_versions` | Lists the versions in a version stack, latest first. |
| `remove_version` | Takes a version out of its stack. The file is kept. |
### Reading Files
`read_asset` attaches the images to the result so the AI model can see them: up to 8 images per call, each up to 2 MB. Any other images are listed as links only. Every result also includes a link to each image, valid for about an hour. Pass `inlineImages: false` to get links only, for example when your client can't show images.
Rendering video frames or PDF pages can take a while. If it takes longer than about 20 seconds, `read_asset` returns `status: "pending"` with a `taskId`, and the model calls `get_asset_render` with that `taskId` to get the result. Only the user who started the read can get its result.
### Uploading Files
Uploading takes three steps, so large files never pass through the AI model:
1. `create_file` (or `create_version`) returns an `uploadUrl` and an `uploadId`.
2. The agent uploads the file's bytes to `uploadUrl` with an HTTP `PUT`, for example `curl -T video.mp4 "<uploadUrl>"`.
3. `complete_upload` with the `uploadId` creates the file and starts processing it (previews, transcoding).
The upload URL and ID are valid for about an hour, and only you can complete your upload. If the project has **Creation Context** metadata fields (for example, the prompt or model used to make a file), pass their values as `metadata` to `create_file` or `create_version`; `list_metadata_fields` shows which fields they are.
The agent must be able to reach the upload URL. With Shumai's local storage, it points to your Shumai server; with S3 storage, to your S3 endpoint.
Every call runs with your permissions: for example, a **Reviewer** can list assets but cannot create or rename them. Actions are recorded in the team audit log and attributed to you, marked as coming from MCP.
---
## Troubleshooting
- **OAuth Authorization Expired or Invalid**: Clear your client's local OAuth session cache (`rm -rf ~/.mcp-auth`) and restart your MCP client to re-authenticate.
- **401 Unauthorized**: The API token or OAuth access token is missing, expired, mistyped, or revoked. For API tokens, generate a new token under **Team Settings** → **API Tokens** and update your client configuration.
- **Permission errors on a tool call**: Your role in that team or project does not allow the action.
+164 -49
View File
@@ -12,61 +12,176 @@
"light": "#F5B895",
"dark": "#A8384D"
},
"navbar": {
"links": [
{
"label": "Changelog",
"href": "/changelog"
}
]
},
"navigation": {
"groups": [
"languages": [
{
"group": "Getting Started",
"pages": [
"getting-started/overview",
"getting-started/quickstart",
"getting-started/s3-storage"
"language": "en",
"default": true,
"navbar": {
"links": [
{
"label": "Changelog",
"href": "/changelog"
}
]
},
"groups": [
{
"group": "Getting Started",
"pages": [
"getting-started/overview",
"getting-started/quickstart",
"getting-started/s3-storage"
]
},
{
"group": "Using Shumai",
"pages": [
"using-shumai/asset-management",
"using-shumai/comments",
"using-shumai/version-stack",
"using-shumai/sort-and-search",
"using-shumai/semantic-search",
"using-shumai/team-project-management",
"using-shumai/notifications",
"using-shumai/metadata",
"using-shumai/collections",
"using-shumai/share-links",
"using-shumai/nle-and-premiere",
"using-shumai/3d-asset-support",
"using-shumai/gotenberg",
"using-shumai/embedding-server"
]
},
{
"group": "Shumai Agent Settings",
"pages": [
"using-shumai/agent-providers",
"using-shumai/image-video-generation",
"using-shumai/agents",
"using-shumai/agents-md",
"using-shumai/agent-skills",
"using-shumai/agent-tools",
"using-shumai/mcp-servers",
"using-shumai/agent-sandbox"
]
},
{
"group": "Team Settings",
"pages": [
"using-shumai/transcode-settings",
"using-shumai/quotas-settings",
"using-shumai/email-notifications",
"using-shumai/password-reset"
]
},
{
"group": "Developer",
"pages": ["developer/mcp-server"]
},
{
"group": "Configuration",
"pages": [
"configuration/env-variables",
"configuration/hardware-transcoding",
"configuration/archive-storage"
]
},
{
"group": "Distributed Deployment",
"pages": ["configuration/distributed"]
},
{
"group": "Releases",
"pages": ["changelog"]
}
]
},
{
"group": "Using Shumai",
"pages": [
"using-shumai/asset-management",
"using-shumai/comments",
"using-shumai/version-stack",
"using-shumai/sort-and-search",
"using-shumai/semantic-search",
"using-shumai/team-project-management",
"using-shumai/notifications",
"using-shumai/metadata",
"using-shumai/collections",
"using-shumai/share-links",
"using-shumai/nle-and-premiere",
"using-shumai/gotenberg"
"language": "zh",
"navbar": {
"links": [
{
"label": "Changelog",
"href": "/changelog"
}
]
},
"groups": [
{
"group": "快速入门",
"pages": [
"zh/getting-started/overview",
"zh/getting-started/quickstart",
"zh/getting-started/s3-storage"
]
},
{
"group": "使用指南",
"pages": [
"zh/using-shumai/asset-management",
"zh/using-shumai/comments",
"zh/using-shumai/version-stack",
"zh/using-shumai/sort-and-search",
"zh/using-shumai/semantic-search",
"zh/using-shumai/team-project-management",
"zh/using-shumai/notifications",
"zh/using-shumai/metadata",
"zh/using-shumai/collections",
"zh/using-shumai/share-links",
"zh/using-shumai/nle-and-premiere",
"zh/using-shumai/3d-asset-support",
"zh/using-shumai/gotenberg",
"zh/using-shumai/embedding-server"
]
},
{
"group": "Agent 智能体配置",
"pages": [
"zh/using-shumai/agent-providers",
"zh/using-shumai/image-video-generation",
"zh/using-shumai/agents",
"zh/using-shumai/agents-md",
"zh/using-shumai/agent-skills",
"zh/using-shumai/agent-tools",
"zh/using-shumai/mcp-servers",
"zh/using-shumai/agent-sandbox"
]
},
{
"group": "团队设置",
"pages": [
"zh/using-shumai/transcode-settings",
"zh/using-shumai/quotas-settings",
"zh/using-shumai/email-notifications",
"zh/using-shumai/password-reset"
]
},
{
"group": "开发者指南",
"pages": ["zh/developer/mcp-server"]
},
{
"group": "系统配置",
"pages": [
"zh/configuration/env-variables",
"zh/configuration/hardware-transcoding",
"zh/configuration/archive-storage"
]
},
{
"group": "分布式部署",
"pages": ["zh/configuration/distributed"]
}
]
},
{
"group": "Shumai Agent Settings",
"pages": [
"using-shumai/agent-providers",
"using-shumai/image-video-generation",
"using-shumai/agents",
"using-shumai/agents-md",
"using-shumai/agent-skills",
"using-shumai/agent-tools",
"using-shumai/mcp-servers",
"using-shumai/agent-sandbox"
]
},
{
"group": "Team Settings",
"pages": [
"using-shumai/transcode-settings",
"using-shumai/quotas-settings",
"using-shumai/password-reset"
]
},
{
"group": "Configuration",
"pages": ["configuration/env-variables"]
},
{
"group": "Temporal Deployment",
"pages": ["configuration/temporal"]
}
]
}
+1 -1
View File
@@ -32,6 +32,6 @@ Ideal for small teams, local development, or low-volume workflows. In this setup
### 2. High-Scale Distributed Deployment
Recommended for production environments with high-volume video uploads. In this setup, background tasks are managed via a centralized queue (Temporal). This allows you to offload heavy workloads to specialized worker machines (for example, putting video transcoding tasks on high-CPU/GPU machines and AI agents on separate sandboxed environments).
Recommended for production environments with high-volume video uploads. In this setup, background tasks are managed via durable queues (orchestrated by DBOS directly in PostgreSQL). This allows you to offload heavy workloads to specialized worker machines (for example, putting video transcoding tasks on high-CPU/GPU machines and AI agents on separate sandboxed environments).
_Note: S3-compatible cloud storage is required for distributed deployments so that all workers can access the uploaded files._
+119 -19
View File
@@ -9,22 +9,97 @@ We support three installation options. For most administrators, **Docker Compose
## Option 1: Docker Compose (Recommended)
Docker Compose automatically configures and spins up all required services (the web application, a database, and local storage).
Docker Compose is the fastest way to get Shumai running. You do not need to clone the repository or install packages manually. Ensure you have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed, then follow these steps:
1. **Create Directory**:
Create and navigate to a new directory for your configuration and data volumes:
1. **Download the Configuration**:
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
mkdir shumai && cd shumai
```
2. **Start the Services**:
2. **Download the Configuration**:
Download your preferred `docker-compose.yaml` configuration based on your needs and available RAM:
- **Lite (Suggested RAM: 2 GB+)**: Minimal deployment containing Shumai and PostgreSQL database.
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
```
- **With Embedding Server (Suggested RAM: 4 GB+)**: Adds local multimodal semantic search powered by `shumaiOne/embedding-server` (`EmbeddingGemma 2 740M`).
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.embedding.yaml
```
- **Full (Suggested RAM: 8 GB+)**: All-in-one setup including `embedding-server`, `turntable-renderer` (3D previews), and `Gotenberg` (document PDF proxying).
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.full.yaml
```
> [!NOTE]
> By default, the Docker Compose setups use CPU software transcoding. If your server has a GPU (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, or Rockchip RKMPP) and you want to enable GPU hardware acceleration, check the [Hardware Transcoding Guide](/configuration/hardware-transcoding).
3. **Configure Environment Variables**:
Open `docker-compose.yaml` to adjust environment variables for your deployment:
- `BETTER_AUTH_URL`: The public base URL of your Shumai server (e.g., `https://shumai.example.com` or `http://12.34.56.78:3000`). It is used for:
- **Password reset links**: Generates CLI and user password reset URLs (`{BETTER_AUTH_URL}/reset-password?token=...`).
- **Email notification deep links**: Default base URL for notification emails (if `APP_URL` is unset).
- **Session cookie security**: Determines whether to issue session cookies with `Secure` flags and `__Secure-` prefixes for HTTPS deployments.
- **MCP OAuth 2.1 & discovery**: Sets the OAuth resource identifier (`{BETTER_AUTH_URL}/mcp`), discovery endpoints (`/.well-known/...`), and default redirect URI for outbound MCP OAuth.
> [!NOTE]
> **Email/password Web UI login** works over plain HTTP/IP even if `BETTER_AUTH_URL` is omitted. However, setting it is strongly recommended for production, custom domains, or HTTPS deployments. Note that remote deployments must use HTTPS for MCP OAuth 2.1 (RFC 9728); if an HTTP IP address or domain is used, MCP OAuth 2.1 is gracefully disabled while the Web UI and MCP API tokens remain functional.
- `BETTER_AUTH_SECRET`: A random secret key used to sign session cookies, JWTs, and presigned file upload/download URLs (in local storage mode). A default placeholder is included in the template for instant local trials, but **you must generate a unique secret for production or public deployments** (e.g., run `openssl rand -base64 32`).
- `AWS_ENDPOINT_URL_S3`: By default, `AWS_ENDPOINT_URL_S3` is set to `http://localhost:{SHUMAI_SERVER_PORT}`. When you use local storage (the default storage backend with `STORAGE_BACKEND: local`) and expose Shumai on a remote server, custom domain, or custom host/port combination, set `AWS_ENDPOINT_URL_S3` to the external URL that client browsers will use to upload and download files.
For example, if you change the port mapping in `docker-compose.yaml` from `3000:3000` to `12345:3000` and deploy on a server with IP address `12.34.56.78`, set:
```yaml
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
```
This value must be reachable from client browsers and should include the externally exposed port.
- `SHUMAI_SERVER_PORT`: Controls the port the Shumai server listens on. The default is `3000`.
- **External S3 Storage**: By default, Shumai uses the bundled local storage service in this Docker Compose setup. To use an external S3-compatible storage instead, configure the environment variables for your S3 provider. Here are examples for AWS S3 and Cloudflare R2:
**AWS S3 Example:**
```yaml
STORAGE_BACKEND: s3
S3_BUCKET: your-bucket-name
S3_ACCESS_KEY_ID: your-access-key-id
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.com
```
**Cloudflare R2 Example:**
```yaml
STORAGE_BACKEND: s3
S3_BUCKET: your-bucket-name
S3_REGION: auto
S3_ACCESS_KEY_ID: your-access-key-id
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
```
4. **Start the Services**:
```bash
docker compose up -d
```
3. **Access the Dashboard**:
Open your browser and navigate to **`http://localhost:3000`** to access the Shumai Web UI.
### Production Deployments (Temporal)
5. **Access the Dashboard**:
Open your browser and navigate to **`http://localhost:3000`** (or `http://<your-server-ip>:3000` for remote deployments) to access the Shumai Web UI.
If you are deploying Shumai for a production team with high-volume video uploads, we recommend setting up a distributed deployment using **Temporal** and an S3-compatible storage backend. This offloads resource-heavy video transcoding and AI agents to separate, dedicated worker nodes to keep your main dashboard fast and responsive. For setup instructions, see the [Deploy with Temporal](/configuration/temporal) guide.
### Production Deployments (Distributed Workers)
If you are deploying Shumai for a production team with high-volume video uploads, we recommend setting up a distributed deployment using dedicated workers and an S3-compatible storage backend. This offloads resource-heavy video transcoding and AI agents to separate, dedicated worker nodes to keep your main dashboard fast and responsive. For setup instructions, see the [Deploy with Distributed Workers](/configuration/distributed) guide.
---
@@ -39,6 +114,9 @@ To handle media processing and security isolation, the host machine must have th
- **FFmpeg & FFprobe**: Required for video transcoding and metadata extraction.
- _macOS_: `brew install ffmpeg`
- _Linux (Ubuntu/Debian)_: `sudo apt-get install ffmpeg`
- **dcraw_emu (LibRaw)**: Required for camera RAW image decoding and preview generation.
- _macOS_: `brew install libraw`
- _Linux (Ubuntu/Debian)_: `sudo apt-get install libraw-bin`
- **Agent Sandbox Utilities**: Used to run custom automation scripts securely.
- _macOS_: `brew install ripgrep`
- _Linux (Ubuntu/Debian)_: `sudo apt-get install bubblewrap socat ripgrep`
@@ -71,12 +149,13 @@ To handle media processing and security isolation, the host machine must have th
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=your-random-32-character-secret-key
BETTER_AUTH_URL=http://localhost:3000
STORAGE_BACKEND=local
AWS_ENDPOINT_URL_S3=http://localhost:3000
```
> [!TIP]
> `AWS_ENDPOINT_URL_S3` must include the scheme and port (e.g. `http://localhost:3000`) where Shumai is publicly accessible. This URL is used directly by client browsers for file uploads.
> `BETTER_AUTH_URL` should be set to your public server address for remote or production deployments. `AWS_ENDPOINT_URL_S3` must include the scheme and port (e.g. `http://localhost:3000` or `http://12.34.56.78:3000`) where Shumai is publicly accessible, as client browsers use this URL directly for file uploads.
4. **Start Shumai**:
@@ -93,25 +172,46 @@ To handle media processing and security isolation, the host machine must have th
## Option 3: Run from Source (For Developers)
If you wish to run Shumai locally to customize the platform or contribute:
To set up Shumai locally for development:
1. **Clone the Repository**:
1. **Clone the Repository and Install Dependencies**:
```bash
git clone https://github.com/shumaiOne/shumai.git
cd shumai
```
2. **Install Dependencies**:
```bash
bun install
```
3. **Start a Database**:
Launch a local database container (as described in the NPM section above).
4. **Run Migrations**:
Set up your `.env` file at the root, then apply database migrations:
2. **Start a Database**:
Launch a local database container (as described in the NPM section above):
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d pgvector/pgvector:pg18
```
3. **Create Environment File**:
Create a `.env` file at the root of the workspace:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL=http://localhost:3000
STORAGE_BACKEND=local
SHUMAI_SERVER_PORT=3000
AWS_ENDPOINT_URL_S3=http://localhost:3000
```
4. **Generate i18n Translations**:
```bash
bun run i18n:compile
```
> [!TIP]
> During frontend development, you can run `bun run i18n:watch` in a separate terminal to automatically recompile translation files whenever you edit strings in `packages/webui/messages/`.
5. **Run Migrations**:
Apply database schema migrations:
```bash
bun run db:migrate
```
5. **Start the Dev Server**:
6. **Start the Dev Server**:
```bash
bun run dev
```
+10 -9
View File
@@ -13,15 +13,16 @@ Using external S3 storage is highly recommended for production teams. It allows
To enable S3-compatible storage, update the following environment variables in your `.env` file or Docker Compose configuration:
| Variable | Description | Required | Default / Example |
| :------------------------- | :------------------------------------------------------------------------ | :------- | :----------------------------------- |
| `STORAGE_BACKEND` | Set to `s3` to enable S3 compatible storage. | Yes | `s3` |
| `S3_BUCKET` | The name of the S3 bucket where files will be stored. | Yes | `shumai-bucket` |
| `S3_REGION` | The region of your S3 bucket. | No | `auto` |
| `S3_ACCESS_KEY_ID` | The access key ID for your storage service. | Yes | `your-access-key-id` |
| `S3_SECRET_ACCESS_KEY` | The secret access key for your storage service. | Yes | `your-secret-access-key` |
| `AWS_ENDPOINT_URL_S3` | The endpoint URL of your S3 compatible storage provider. | Yes | `https://s3.us-east-1.amazonaws.com` |
| `PRESIGNED_URL_EXPIRES_IN` | Duration in hours before generated presigned download/upload URLs expire. | No | `5` |
| Variable | Description | Required | Default / Example |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------- | :----------------------------------- |
| `STORAGE_BACKEND` | Set to `s3` to enable S3 compatible storage. | Yes | `s3` |
| `S3_BUCKET` | The name of the S3 bucket where files will be stored. | Yes | `shumai-bucket` |
| `S3_REGION` | The region of your S3 bucket. | No | `auto` |
| `S3_ACCESS_KEY_ID` | The access key ID for your storage service. | Yes | `your-access-key-id` |
| `S3_SECRET_ACCESS_KEY` | The secret access key for your storage service. | Yes | `your-secret-access-key` |
| `AWS_ENDPOINT_URL_S3` | The endpoint URL of your S3 compatible storage provider. | Yes | `https://s3.us-east-1.amazonaws.com` |
| `PRESIGNED_URL_EXPIRES_IN` | Duration in hours before generated presigned download URLs expire. | No | `5` |
| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | Duration in hours before generated presigned upload URLs expire. Falls back to `PRESIGNED_URL_EXPIRES_IN` if unset. | No | `12` |
---
+153
View File
@@ -0,0 +1,153 @@
---
title: 3D Asset Support with Turntable Renderer
description: Render interactive 3D model turntable previews, sprite scrubbing, and video proxies using turntable-renderer.
---
3D models and mesh assets cannot always be rendered consistently or inspected reliably across diverse client web browsers and mobile devices. Shumai integrates with [turntable-renderer](https://github.com/shumaiOne/turntable-renderer) — a standalone service that executes isolated, headless Blender 5.2 LTS subprocesses — to convert 3D model uploads into standardized, high-fidelity turntable previews.
Turntable Renderer automatically produces:
- **1080×1080 Turntable Video (`turntable.mp4`)**: A 4-second, 24-frame, 6 fps video rotating the model 360° (15° per frame) clockwise under dark studio lighting with a pure black background.
- **Poster Image (`poster.webp`)**: A crisp still poster for grid cards and immediate file display.
- **Hover Sprite Sheet (`sprite.webp`)**: A fast scrubbing sheet allowing users to rotate and inspect the model directly from the file browser on hover.
- **Interactive 3D Viewer**: A specialized web viewer featuring 360° ruler scrubbing, rotation angle control (0° to 345°), playback controls, and angle-specific review comments and visual markups.
---
## Supported File Types
When turntable-renderer is configured, Shumai automatically generates 3D turntable proxies for the following formats:
| Format / Standard | Extensions |
| --------------------------- | --------------------------------- |
| Binary glTF | `.glb` |
| Universal Scene Description | `.usd`, `.usda`, `.usdc`, `.usdz` |
| Autodesk FBX | `.fbx` |
| Wavefront OBJ | `.obj` |
| Stereolithography (STL) | `.stl` |
| COLLADA | `.dae` |
---
## Configuration
Shumai supports configuring the turntable renderer either through the **WebUI** or via **Environment Variables**.
### 1. WebUI (Team Settings → Integrations)
Team owners can configure the turntable renderer directly from the web interface:
1. Navigate to **Team Settings** from the sidebar.
2. Select the **Integrations** tab.
3. Under **3D Turntable Renderer**, enter the **Server URL** (e.g. `http://turntable-renderer:3000` or `http://localhost:3003`).
4. Enter the **Username** and **Password** if Basic Authentication is enabled on the service.
5. Click **Test Connection** to verify that Shumai can communicate with the renderer and check the detected Blender version.
6. Click **Save Changes**.
### 2. Environment Variables
You can also configure turntable-renderer globally across the system using environment variables on the machine running Shumai or the transcode workers:
| Variable | Required | Description |
| ---------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
| `TURNTABLE_RENDERER_URL` | Yes (to enable) | Base URL of the turntable renderer service, e.g. `http://turntable-renderer:3000`. |
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | No | Username when Basic Authentication is enabled (alias: `TURNTABLE_RENDERER_USERNAME`). |
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | No | Password when Basic Authentication is enabled (alias: `TURNTABLE_RENDERER_PASSWORD`). |
### Configuration Priority & Read-Only Mode
> [!IMPORTANT]
> **Environment variables take highest priority.** If `TURNTABLE_RENDERER_URL` is set in your environment, Shumai will always use the environment variable configuration.
>
> When configured via environment variables, the settings in **Team Settings → Integrations** will display a **Configured via environment variables (Read-only)** badge, and the input fields will be locked to prevent accidental changes or configuration drift.
---
## Deploying Turntable Renderer
### Docker Quickstart
The easiest way to run `turntable-renderer` is using the prebuilt Docker image:
```bash
docker run -d --rm \
--name turntable-renderer \
-p 3003:3000 \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
shumaione/turntable-renderer:latest
```
> **Note**: Host port `3003` maps to internal container port `3000`.
### Docker Compose Setup
Add a `turntable-renderer` service to your `docker-compose.yaml`:
```yaml
services:
turntable-renderer:
image: shumaione/turntable-renderer:latest
restart: unless-stopped
ports:
- '3003:3000'
environment:
TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME: admin
TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD: your_password
```
Then point Shumai at it:
```bash
TURNTABLE_RENDERER_URL=http://localhost:3003
TURNTABLE_RENDERER_BASIC_AUTH_USERNAME=admin
TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD=your_password
```
_(If both Shumai and turntable-renderer run within the same Docker Compose network, use `http://turntable-renderer:3000` as the URL)._
### GPU Acceleration
A dedicated GPU is optional — turntable-renderer's CPU rendering pipeline is fast enough for modest hardware. When a GPU is passed into the container, it is automatically detected and leveraged.
#### Intel / AMD (Open Source Drivers)
Pass the DRI render node:
```bash
docker run -d --rm \
--name turntable-renderer \
--shm-size=1gb \
-p 3003:3000 \
--device /dev/dri \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
shumaione/turntable-renderer:latest
```
#### NVIDIA (Proprietary Drivers)
Requires host driver 580+ and the NVIDIA Container Toolkit (`--runtime nvidia`):
```bash
docker run -d --rm \
--name turntable-renderer \
--shm-size=1gb \
-p 3003:3000 \
--runtime nvidia \
--gpus all \
--device /dev/nvidia-modeset \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
shumaione/turntable-renderer:latest
```
---
## Behavior Without Turntable Renderer
If turntable-renderer is not configured or unreachable:
- The 3D model upload completes successfully with status `processed`.
- No turntable video proxy, sprite, or poster is generated.
- The original raw 3D file is safely preserved and can be downloaded by team members.
+78 -12
View File
@@ -34,59 +34,125 @@ The following tools can be individually toggled in the agent configuration dialo
- **Description:** Allows the agent to inspect images, extract still frames from video files, render PDF document pages, and read text/markdown documents.
- **Why it matters:** Enables multimodal agents to view visual media assets uploaded to Shumai, extract frame-by-frame video screenshots, inspect document layouts, and answer questions about uploaded creative assets.
- **Limits:** Up to 20 video frames or PDF pages per call. If rendering takes longer than about a minute, the tool tells the agent the render is still in progress instead of failing.
### 4. Browse Shumai (`list_assets`)
### 4. Get Asset Render (`get_asset_render`)
- **Description:** Allows the agent to list folders and browse files in Shumai.
- **Description:** Allows the agent to pick up video frames or document pages that were still rendering when `read_asset` returned.
- **Why it matters:** Long videos and large documents can take a while to render. With this tool the agent can come back for the result instead of starting over. It only returns renders that `read_asset` started for the same user.
### 5. Browse Shumai (`list_assets`)
- **Description:** Allows the agent to list folders and browse files in Shumai. Large folders are returned page by page.
- **Why it matters:** Gives the agent visual mapping of the project structure so it can search for other files or locate related assets.
### 5. Create Folder (`create_folder`)
### 6. List Projects (`list_projects`)
- **Description:** Allows the agent to list the projects you have access to across your teams, including each project's root folder.
- **Why it matters:** Lets the agent find the right project and its root folder on its own before browsing or creating files.
### 7. Create Folder (`create_folder`)
- **Description:** Allows the agent to create new folders in Shumai.
- **Why it matters:** Needed if the agent organizes outputs or places files in custom subdirectory folders.
### 6. Create File (`create_file`)
### 8. Create File (`create_file`)
- **Description:** Allows the agent to create and upload new files to Shumai.
- **Why it matters:** Allows the agent to generate new assets (e.g. text logs, transcoded clips, reports) and save them directly back into your project.
### 7. Create Version (`create_version`)
### 9. Create Version (`create_version`)
- **Description:** Allows the agent to upload and stack a new version of an existing file in Shumai.
- **Why it matters:** Allows the agent to update files in a clean, non-destructive way by stacking revisions rather than creating duplicate files.
### 8. Generate Image (`generate_image`)
### 10. Generate Image (`generate_image`)
- **Description:** Allows the agent to generate still images from text prompts and reference images using configured AI image models.
- **Why it matters:** Enables agents to create concept art, mockups, textures, and illustrations directly inside Shumai.
- **Prerequisite:** This tool requires at least one image model to be configured and enabled in [Image / Video Generation](/using-shumai/image-video-generation). If no image models are enabled under a configured provider, this tool is omitted from the agent session even if enabled in the agent settings dialog.
### 9. Generate Video (`generate_video`)
### 11. Generate Video (`generate_video`)
- **Description:** Allows the agent to generate video clips from text prompts, image animation, or transition keyframes using configured AI video models.
- **Why it matters:** Enables agents to produce short animated clips, camera motion shots, and video transitions.
- **Prerequisite:** This tool requires at least one video model to be configured and enabled in [Image / Video Generation](/using-shumai/image-video-generation). If no video models are enabled under a configured provider, this tool is omitted from the agent session even if enabled in the agent settings dialog.
### 10. Download Asset (`download_asset`)
### 12. Download Asset (`download_asset`)
- **Description:** Allows the agent to download a workspace asset or specific storage S3 key to the local `.pi` directory for processing with local scripts or bash commands.
- **Description:** Allows the agent to download up to 50 workspace files, or a specific storage S3 key (such as a frame from `read_asset`), to the local `.pi` directory for processing with local scripts or bash commands. By default it downloads the web preview version when there is one (for example the transcoded video or the web image); the agent can ask for the original uploaded file instead. Folders are not supported.
- **Why it matters:** Enables agents executing custom skill scripts to fetch files or intermediate transcode artifacts to local disk.
### 11. Rename Asset (`rename_asset`)
### 13. Rename Asset (`rename_asset`)
- **Description:** Allows the agent to rename an existing file or folder in Shumai.
- **Why it matters:** Enables agents to keep project files neatly named and organized according to workspace naming conventions. Enabled by default.
### 12. Move Assets (`move_assets`)
### 14. Move Assets (`move_assets`)
- **Description:** Allows the agent to move one or more assets to a destination parent folder.
- **Why it matters:** Enables agents to reorganize workspace structures, relocate generated outputs, or tidy up project folders. Enabled by default.
### 13. Delete Asset (`delete_asset`)
### 15. Delete Asset (`delete_asset`)
- **Description:** Allows the agent to delete a single file or folder by moving it to the Trash bin.
- **Why it matters:** Provides agents with the ability to clean up outdated or redundant assets. To prevent accidental data loss, this tool is **disabled by default** and strictly limited to deleting one asset at a time. Team Owners must explicitly enable this tool for an agent.
### 16. Search Assets (`search_assets`)
- **Description:** Allows the agent to search a folder and its subfolders by name, by meaning (when AI search is enabled for the team), or by metadata such as status.
- **Why it matters:** Lets the agent find the files a request is about without browsing folder by folder.
### 17. Copy Assets (`copy_assets`)
- **Description:** Allows the agent to copy files or folders, with everything inside them, into another folder of the same team.
- **Why it matters:** Lets the agent reuse assets across projects or set up working copies while keeping the originals unchanged.
### 18. Read Folder Instructions (`get_folder_instructions`)
- **Description:** Allows the agent to read a folder's instructions for AI agents (its AGENTS.md).
- **Why it matters:** Lets the agent follow the team's conventions, such as naming rules or deliverable specs, before adding files to a folder.
### 19. Read Comments (`list_comments`)
- **Description:** Allows the agent to read the review comments and replies on a file, including their timecodes.
- **Why it matters:** Lets the agent act on review feedback, for example to summarize open notes or address them in a new version.
### 20. Post Comment (`create_comment`)
- **Description:** Allows the agent to comment on a file, optionally at a timecode, or reply to a comment. Comments are posted as the user the agent works for; the audit log records that the agent wrote them.
- **Why it matters:** Lets the agent take part in reviews like a teammate. Mentions in the agent's comments don't start other agents.
### 21. Resolve Comment (`resolve_comment`)
- **Description:** Allows the agent to mark comments as resolved, or reopen them.
- **Why it matters:** Lets the agent close the feedback it has addressed.
### 22. List Metadata Fields (`list_metadata_fields`)
- **Description:** Allows the agent to see a project's metadata fields, such as status, rating, and custom fields, with their choices.
- **Why it matters:** Tells the agent which values it can search by or set.
### 23. Update Metadata (`update_asset_metadata`)
- **Description:** Allows the agent to set metadata values on a file, such as its status or tags. Read-only fields can't be changed.
- **Why it matters:** Lets the agent keep a file's review status and other fields up to date.
### 24. Create Version Stack (`create_version_stack`)
- **Description:** Allows the agent to stack existing files in the same folder as versions of one asset.
- **Why it matters:** Lets the agent tidy up loose revisions (for example `cut_v1.mp4` and `cut_v2.mp4`) into one versioned asset.
### 25. List Versions (`list_versions`)
- **Description:** Allows the agent to list the versions in a version stack, latest first.
- **Why it matters:** Lets the agent compare a file with earlier versions.
### 26. Remove Version (`remove_version`)
- **Description:** Allows the agent to take a version out of its stack. The file isn't deleted; it goes back into the folder as a separate file.
- **Why it matters:** Lets the agent fix a version that was stacked by mistake.
---
## Restricting Tools
+127
View File
@@ -0,0 +1,127 @@
---
title: Email Notifications
description: Configure team SMTP settings, deliver batched activity digest emails, and send test emails.
---
Shumai includes a built-in email notification system that delivers updates on team activities—such as comments, mentions, new asset uploads, status changes, and Kanban tasks—directly to team members' inboxes.
To prevent inbox clutter and notification fatigue, Shumai does not send emails for every single action individually. Instead, a background delivery service aggregates pending notifications and sends periodic, batched digest emails with inline thumbnails and deep links.
---
## Configuring SMTP Settings
Email notification settings are managed at the team level by **Team Owners**.
To configure outgoing mail:
1. Click on **Team Settings** in the sidebar.
2. Select the **Email Notifications** tab.
3. Turn on the **Enable Email Notifications** switch.
4. Fill in your SMTP server credentials and sender information.
5. Click **Save** or **Save and Send Test Email**.
### SMTP Server Settings
| Field | Description | Example / Default |
| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------- |
| **SMTP Host** | The hostname or IP address of your outgoing SMTP server. | `smtp.example.com` or `smtp.sendgrid.net` |
| **SMTP Port** | The port used to connect to your SMTP server. | `587` (default, STARTTLS), `465` (SSL/TLS), or `25` |
| **Username** | The username or API key required to authenticate with the SMTP server. | `user@example.com` or `apikey` |
| **Password** | The authentication password or API secret. | `••••••••` |
| **SSL / TLS (SMTPS)** | Connect directly using SSL/TLS encryption. Typically required when connecting over port `465`. | `Disabled` (default) |
| **Ignore Certificate Errors** | Allows connections with self-signed, invalid, or unverified TLS certificates. Useful for local testing (e.g. Mailpit, MailHog) or private corporate relays. | `Disabled` (default) |
> [!TIP]
> **Password Retention**: When updating existing email settings, you can leave the password input blank to keep the currently stored password. For security, stored passwords are never returned in cleartext to the client.
### Sender Information
| Field | Description | Example / Default |
| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |
| **From** | The sender name and email address that will appear in the `From` header. Ensure your SMTP provider is authorized to send on behalf of this address. | `Shumai <noreply@example.com>` |
| **Reply-To** | _(Optional)_ An email address to receive replies if members respond directly to a notification email. | `support@example.com` |
---
## Testing SMTP Delivery
Before relying on email delivery, you can verify your configuration and credentials directly from the settings page:
1. Click **Save and Send Test Email**.
2. In the **Send Test Email** modal, verify or adjust the sender `From` address.
3. Click **Send Test Email**.
Shumai will perform an active handshake verification (`transport.verify()`) against your SMTP server and dispatch a styled test message to the email address of the currently logged-in administrator.
If the handshake or delivery fails (for example, due to an invalid password, blocked outbound port, or rejected sender address), an error toast is displayed with the exact message returned by the SMTP server.
---
## Delivery Architecture & Digest Batching
Shumai uses an asynchronous, batched architecture for email delivery:
```
[ Team Activity ]
(Comments, Uploads, Mentions, Kanban)
│
▼
[ Database Queue ] (status: pending)
│
▼ (Every 3 minutes)
[ Notification Background Job ]
│
├─ Filter recipients (check user preferences & project scope)
├─ Exclude self-actions and AI agents
├─ Group & collapse items (clusters > 3 summarized)
├─ Fetch avatars & thumbnails as inline CID attachments
│
▼
[ Nodemailer Transport ] ──> SMTP Server ──> [ Member Inboxes ]
```
### 1. Periodic Background Delivery
Notifications are queued in PostgreSQL with a `pending` status. A background job runs periodically every **3 minutes**, acquiring pending notifications using atomic queue locking (`FOR UPDATE SKIP LOCKED`). This ensures safe delivery without duplicate emails even when multiple server instances run concurrently.
### 2. Digest Bundling
Rather than sending an email immediately for each action, all notifications collected for a recipient during the 3-minute window are combined into a single digest email. This keeps team communication organized and eliminates inbox spam during heavy collaboration sessions.
### 3. Smart Activity Collapsing
When an event cluster contains a high volume of items (for example, when an editor uploads dozens of video clips at once), Shumai automatically groups and collapses the items:
- If **3 or fewer** items are in a group, each item is displayed with its individual thumbnail and details.
- If **more than 3** items are uploaded together, Shumai summarizes them into a single concise notification (e.g., _"Alice uploaded 12 new files to Project Alpha"_) with a preview of the first three file names.
### 4. Inline CID Attachments
Avatars and video/image asset thumbnails are retrieved from storage and embedded directly into the email as inline MIME attachments (`cid:...`).
Unlike external image links, inline CID attachments:
- Display immediately in desktop and mobile email clients (such as Apple Mail, Gmail, and Outlook) without being blocked by "show remote content" security warnings.
- Do not require publicly accessible S3 URLs or reverse-proxy authentication to render.
### 5. Deep Linking
Every notification card in the email includes deep-linking action buttons (such as **View Asset**, **View Project**, or **View Task**) that navigate members straight to the corresponding resource in Shumai.
To ensure links point to your public domain instead of `localhost`, configure the `APP_URL` or `BETTER_AUTH_URL` environment variable on your Shumai server:
```bash
APP_URL=https://shumai.example.com
```
---
## Member Preferences & Filtering
Email delivery respects team permissions and member choices:
- **Personal Preferences**: Team members can independently choose which types of activities they receive by opening **Team Settings > Notifications**. If a user disables notifications for a category (e.g. general comments or status updates), Shumai will not include those items in their email digests.
- **Self-Action Suppression**: Members never receive notification emails for their own comments, uploads, or task updates (unless they explicitly enable the **Your Uploads** preference to be notified when their own media transcoding completes).
- **Project Scope**: Members whose access is restricted to specific projects only receive email digests for activities within those assigned projects, unless they are explicitly `@mentioned`.
- **AI Agents**: Automated AI agent accounts are automatically excluded from receiving email notifications.
+131
View File
@@ -0,0 +1,131 @@
---
title: Embedding Server Setup (EmbeddingGemma 2)
description: Run local, offline multimodal vector embeddings for semantic search using shumaiOne/embedding-server.
---
Shumai supports local, self-hosted multimodal vector embeddings for semantic search through [shumaiOne/embedding-server](https://github.com/shumaiOne/embedding-server) — a standalone Docker service powered by Google AI Edge's **LiteRT-LM** and **EmbeddingGemma 2 740M**.
The embedding server provides a unified 768-dimensional vector space across text, images, and video frames with an OpenAI-compatible HTTP API (`/v1/embeddings`). Because the model weights are pre-baked directly into the Docker image, the server operates completely offline and air-gapped without requiring external network access or third-party cloud API keys.
---
## Model Architecture & Specs
| Property | Value |
| :------------------------ | :------------------------------------------------------- |
| **Model** | `EmbeddingGemma 2 740M` (`google/embeddinggemma-2-740m`) |
| **Runtime** | Google AI Edge LiteRT-LM (Python 3.14 Debian slim) |
| **Vector Dimensionality** | 768 dimensions (multimodal: text, image, and video) |
| **Context Window** | 2,048 tokens |
| **Network Mode** | Completely offline capable (`--network none`) |
| **API Standard** | OpenAI-compatible `/v1/embeddings` |
---
## Video Processing & Sampling
For video assets, Shumai breaks videos into standardized segments and extracts keyframes:
- **Chunking**: Videos are divided into **60-second chunks** with a **5-second overlap** at segment boundaries to preserve narrative and visual context.
- **Frame Extraction Rate**: Shumai extracts **15 frames per minute** from each chunk.
- **Adaptive Frame Bounding**:
- For standard aspect ratios (1:1, 4:3, 3:4, 16:9, 9:16, 21:9), Shumai extracts 15 frames, which produces ~1,982 prompt tokens and stays safely within the 2,048-token context window.
- For non-standard or custom aspect ratios (e.g. 5:3, 1.4:1), Shumai automatically samples 14 frames (~1,990 tokens) to mathematically guarantee that prompt length never exceeds 2,048 tokens, preventing out-of-memory errors on the embedding server.
---
## Important: Changing Embedding Providers Breaks Existing Embeddings
> [!WARNING]
> **Vector spaces from different embedding models are completely incompatible.**
>
> If you change your embedding provider (for example, switching from Google Gemini's 1536-dimensional embeddings to EmbeddingGemma's 768-dimensional embeddings, or vice versa), **all existing vector embeddings in your database become invalid**.
>
> To protect production databases from accidental corruption and search failures, **Shumai intentionally does not provide a WebUI toggle to change the embedding provider**. The provider can only be configured by an administrator via environment variables (`EMBEDDING_PROVIDER` and `GEMMA_EMBEDDING_OPENAI_BASE_URL`).
---
## Regenerating Embeddings via CLI
When you do switch embedding providers or configure the embedding server on an existing Shumai deployment, you can regenerate embeddings for all existing media files using the administrative CLI command:
### Inside Docker
```bash
docker exec -it <shumai-container-name> shumai regenerate-embeddings
```
### Local / Bare Metal
```bash
shumai regenerate-embeddings
```
_(Alternatively, `bun apps/web/src/index.ts regenerate-embeddings`)_
### What the Command Does
1. **Scans Teams**: Checks all teams in your workspace. If a team does not have an active (enabled) embedding agent, it logs a warning and safely skips that team.
2. **Clears Existing Embeddings**: Purges all previous embeddings and cancels any pending/in-progress embedding tasks for eligible assets to ensure a clean transition to the new provider.
3. **Enqueues Fresh Tasks**: Queues new background `ai_embedding` tasks for all eligible assets (images, videos, and 3D assets with rendered previews) across active teams.
4. **Background Execution**: Background workers process the queued tasks according to your configured concurrency limits.
---
## Deployment & Configuration
### Docker Quickstart
To run the standalone embedding server container:
```bash
docker run -d \
--name shumai_embedding \
-p 9379:9379 \
shumaione/embedding-server:latest
```
### Docker Compose Setup
In Docker Compose environments, add `embedding-server` to your `docker-compose.yaml` and configure Shumai to connect to it over Docker's internal network:
```yaml
services:
embedding-server:
image: shumaione/embedding-server:latest
container_name: shumai_embedding
restart: unless-stopped
shumai:
image: shumaione/shumai:latest
environment:
# Embedding Server Configuration
EMBEDDING_PROVIDER: gemma-embedding-2-openai
GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1
ENABLE_EMBEDDING_AGENT: 'true'
CONCURRENCY_AGENT: 1
depends_on:
- embedding-server
```
> [!NOTE]
> Since Shumai communicates with `embedding-server` over Docker's internal network, `embedding-server` does not need to expose any ports to the host machine.
### Environment Variables
| Variable | Required | Description | Default |
| :-------------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------- | :------------------------- |
| `EMBEDDING_PROVIDER` | Yes | Set to `gemma-embedding-2-openai` to use the local LiteRT-LM server. | `gemini-embedding-2` |
| `GEMMA_EMBEDDING_OPENAI_BASE_URL` | Yes | HTTP base URL of the embedding server (e.g. `http://embedding-server:9379/v1`). | `http://localhost:9379/v1` |
| `ENABLE_EMBEDDING_AGENT` | No | Automatically provisions and enables the system embedding agent for all teams on startup. | `false` |
| `CONCURRENCY_AGENT` | Recommended | Maximum concurrent AI tasks executed by workers. **Set to `1`** when running `embedding-server` to prevent high memory usage. | `5` |
---
## Hardware & Resource Requirements
- **Memory (RAM)**:
- We recommend at least **4 GB+ of dedicated system RAM** for the `embedding-server` container.
- Overall host system memory should be **4 GB+** when running the Lite+Embedding compose stack, and **8 GB+** for the full stack.
- **Concurrency**:
- Always set `CONCURRENCY_AGENT=1` in your Shumai configuration when using `embedding-server`. Parallel multimodal embedding generations consume significant memory and can cause Docker containers to be terminated by the OS Out-Of-Memory (OOM) killer on low-resource machines.
+25 -1
View File
@@ -32,7 +32,22 @@ When Gotenberg is configured, Shumai automatically generates a PDF proxy for the
## Configuration
Gotenberg support is opt-in and controlled by the following environment variables on the machine running the transcode workers:
Shumai supports configuring Gotenberg either through the **WebUI** or via **Environment Variables**.
### 1. WebUI (Team Settings → Integrations)
Team owners can configure Gotenberg directly from the web interface:
1. Navigate to **Team Settings** from the sidebar.
2. Select the **Integrations** tab.
3. Under **Gotenberg Document Converter**, enter the **Server URL** (e.g. `http://gotenberg:3000` or `http://localhost:3000`).
4. Enter the **Username** and **Password** if Basic Authentication is enabled on the service.
5. Click **Test Connection** to test communication with Gotenberg and verify its health.
6. Click **Save Changes**.
### 2. Environment Variables
Gotenberg can also be configured globally across the system using environment variables on the machine running Shumai or the transcode workers:
| Variable | Required | Description |
| ------------------------------- | --------------- | ---------------------------------------------------------------- |
@@ -40,6 +55,15 @@ Gotenberg support is opt-in and controlled by the following environment variable
| `GOTENBERG_BASIC_AUTH_USERNAME` | No | Username when Basic Authentication is enabled on Gotenberg. |
| `GOTENBERG_BASIC_AUTH_PASSWORD` | No | Password when Basic Authentication is enabled on Gotenberg. |
### Configuration Priority & Read-Only Mode
> [!IMPORTANT]
> **Environment variables take highest priority.** If `GOTENBERG_URL` is set in your environment, Shumai will always use the environment variable configuration.
>
> When configured via environment variables, the settings in **Team Settings → Integrations** will display a **Configured via environment variables (Read-only)** badge, and the input fields will be locked to prevent accidental changes or configuration drift.
### Deploying Gotenberg
### Docker Quickstart
You can start a Gotenberg container with a single command:
+8
View File
@@ -44,3 +44,11 @@ If you want to mute a specific project entirely (except for direct `@mentions` w
- The **Bell** icon in the navigation bar displays a red badge when you have unread notifications.
- Click the bell to open your notification feed panel.
- Click any notification card to mark it as read and jump directly to the relevant file and comment thread.
---
## Email Notifications
In addition to in-app notifications, Team Owners can configure outgoing SMTP settings to deliver batched activity digest emails to team members. The email delivery engine honors each member's individual notification preferences configured above.
See the [Email Notifications Guide](/using-shumai/email-notifications) for full SMTP setup instructions, test email workflows, and delivery architecture details.
+4 -5
View File
@@ -12,11 +12,10 @@ Traditional search relies on matching exact characters (e.g., searching "dog" wi
Semantic search translates text queries and file contents into conceptual profiles. Similar ideas and visuals are mapped near each other.
1. **Index Generation**: When you upload an asset, Shumai's background agent scans the file's visual elements, text contents, or descriptions, translating them into a concept profile.
- **Video Processing**: Shumai uses **gemini-embedding-2** for video indexing.
- **Chunking**: For long videos, Shumai breaks them into chunks to ensure high-quality indexing. By default, chunks are **60 seconds** long with a **5-second overlap** to ensure no context is lost at the boundaries.
- **Sampling**: The model processes a maximum of 32 frames per chunk: short chunks (≤32s) are sampled at 1 fps, while longer chunks are uniformly sampled to 32 frames.
- **Optimization**: To optimize processing, Shumai automatically transcodes each chunk to **1 FPS** and **removes the audio track** before sending it to the embedding agent.
- **Configuration**: Administrators can customize these settings using the `EMBEDDING_CHUNK_DURATION` and `EMBEDDING_CHUNK_OVERLAP` environment variables.
- **Multimodal Embedding Providers**: Shumai supports two embedding providers:
- **EmbeddingGemma 2 (Local)**: Powered by `shumaiOne/embedding-server` with 768-dimensional multimodal vectors running completely offline. Videos are sampled at **15 frames per minute** (14 frames for non-standard aspect ratios) per 60-second chunk. See the [Embedding Server Setup Guide](./embedding-server) for full details.
- **Gemini Embedding 2 (Cloud)**: Powered by Google's `gemini-embedding-2` API with 1536-dimensional vectors. Videos are chunked into 60-second segments (sampled up to 32 frames per chunk at 1 fps with audio stripped).
- **Chunking Configuration**: Administrators can customize chunk duration and overlap using the `EMBEDDING_CHUNK_DURATION` (default: 60s) and `EMBEDDING_CHUNK_OVERLAP` (default: 5s) environment variables.
2. **Concept Matching**: When you search with the "Semantic" toggle enabled, Shumai matches the conceptual meaning of your query against your assets.
3. **Result**: Searching "sunset at the beach" will successfully find a video file of ocean waves at dusk, even if the filename is `IMG_4029.mp4`.
+62 -16
View File
@@ -1,36 +1,82 @@
---
title: Media Transcoding Settings
description: Configure video transcode strategies and preview proxy generation.
title: Video Transcoding
description: Configure video transcode policies, MP4 and HLS streaming resolutions, hardware acceleration, and FFmpeg threads.
---
High-resolution camera formats and raw media files cannot be rendered natively in web browsers. Shumai transcodes these assets into web-friendly streaming formats in the background.
High-resolution camera formats and raw media files cannot be rendered natively in web browsers. Shumai transcodes video assets into web-friendly streaming and preview formats in the background.
Team Owners can customize video transcoding behavior from the **Team Settings > Video Transcoding** page.
Regardless of the selected transcoding strategy, Shumai's pipeline will **always** generate at least one lightweight `180p` proxy version of the raw file to ensure fast scrubbing, thumbnail generation, and instant previews.
---
## Video Transcode Strategies
## Transcode Policy
Team Owners can select how the transcoding engine handles uploaded files. Shumai evaluates the original file's dimensions against its standard target resolutions (2160p, 1080p, 720p, 540p, and 360p) to determine the output.
The **Transcode Policy** card configures both MP4 video transcoding and HLS adaptive streaming.
### 1. Best Match
### Playback and Download Behavior
- **Behavior**: Shumai checks the longest dimension (width or height) of the uploaded file. It then finds the highest standard resolution that is equal to or smaller than the original file, preventing unnecessary upscaling. If the original video is exceptionally small, it defaults to a minimum target of `360p`.
- **Output**: Generates exactly two web-optimized files: the universal `180p` proxy and the single calculated "best match" resolution.
- **Use Case**: This is the recommended option. It ensures web compatibility without wasting processing time and storage space on redundant lower-resolution versions.
Shumai uses a dual-format strategy for video delivery:
### 2. Transcode All
- **When HLS is disabled**: Both in-browser video playback and file downloads will use the generated MP4 file(s).
- **When HLS is enabled**: In-browser video playback uses HLS (HTTP Live Streaming) for smooth, adaptive bitrate playback, while file downloads will use the generated MP4 file(s).
- **Behavior**: Shumai calculates the "best match" resolution exactly as it does in the previous strategy. However, instead of stopping at one version, it processes the video into the best match _and_ every standard resolution smaller than it.
- **Output**: Generates a full cascade of files. For example, if the best match for an upload is `1080p`, Shumai will generate the `180p` proxy, `1080p`, `720p`, `540p`, and `360p` versions.
- **Use Case**: Ideal for environments requiring adaptive bitrate streaming, ensuring consistent playback performance across all client devices regardless of varying network conditions.
<Warning>
**Storage Usage Notice**: Enabling HLS generates multi-bitrate segment files (`.ts` / `.m4s`) and
playlist manifests in addition to standard MP4 proxies. This can significantly increase storage
consumption on your storage bucket.
</Warning>
![Transcode Settings](../transcode.webp)
### MP4 Transcoding
Generate web-compatible MP4 files for file downloads and standard video playback. Team Owners can select how MP4 transcodes are generated for uploaded files:
#### 1. Best Match
- **Behavior**: Shumai checks the longest dimension of the uploaded video and generates a single optimal resolution matching or smaller than the source quality, preventing unnecessary upscaling.
- **Output**: Generates the lightweight `180p` proxy and the calculated best-match MP4 file.
- **Use Case**: Recommended default. Minimizes processing time and storage space while ensuring universal playback and download compatibility.
#### 2. Multi Resolutions
- **Behavior**: Select specific target resolution ladders to generate: `480p`, `720p`, `1080p`, `1440p`, and `2160p`. Resolutions are only generated up to the source video resolution (content is never upscaled).
- **Output**: Generates the `180p` proxy plus all selected resolution ladders that do not exceed the source resolution.
- **Use Case**: Ideal when users need to download multiple specific resolutions (e.g. 720p for fast sharing and 1080p for review).
### HLS Streaming
When **HLS Streaming** is toggled on, Shumai produces an adaptive bitrate HLS package for uploaded videos:
- **Resolution Ladders**: Configure which resolutions to generate for HLS streaming (`480p`, `720p`, `1080p`, `1440p`, `2160p`). Ladders are only generated up to the original video resolution.
- **Player Integration**: The web player will automatically stream via HLS when available, dynamically switching bitrates based on client network bandwidth.
![Video Transcoding](../transcode.webp)
---
## Hardware Acceleration
To offload encoding workloads from CPUs to GPUs, Shumai supports hardware-accelerated video encoding:
- **Disabled (Software)**: Uses the standard CPU `libx264` software encoder with Constant Rate Factor (CRF).
- **Auto Detect**: Automatically probes and leverages available GPU/hardware acceleration (NVIDIA NVENC, Intel QuickSync, AMD/Intel VA-API, Apple VideoToolbox, Rockchip RKMPP).
See the [Hardware Transcoding Guide](/configuration/hardware-transcoding) for Docker Compose configuration, GPU passthrough, and driver prerequisites.
---
## FFmpeg Threads
The **FFmpeg Threads** slider controls the maximum number of CPU threads used by FFmpeg during transcoding tasks:
- **Auto (0)**: FFmpeg automatically selects the optimal thread count based on host CPU core availability.
- **Manual (1 - 32)**: Restricts FFmpeg to a fixed number of threads, useful for throttling CPU consumption on shared worker nodes.
---
## Processing Architecture
Transcoding is resource-intensive. Depending on your scaling needs, your administrator can run the transcode engine on the main server (Single-Server mode) or delegate tasks to specialized transcoding worker machines (Temporal Worker mode).
Transcoding is resource-intensive. Depending on your scaling needs, your administrator can run the transcode engine on the main server (Single-Server mode) or delegate tasks to specialized transcoding worker machines (Dedicated Worker mode).
Note: In all modes, the processing machine must have the standard system media utilities (`ffmpeg` and `ffprobe`) installed.
In all modes, the processing machine must have system media utilities (`ffmpeg` and `ffprobe`) installed. See the [Distributed Deployment Guide](/configuration/distributed) for setting up dedicated transcoding workers.
+250
View File
@@ -0,0 +1,250 @@
---
title: 归档存储
description: 配置二级冷存储以归档迁移原生媒体文件,同时完整保留浏览器内代理播放与即时预览。
---
高分辨率摄影机素材、RAW 序列帧、母带分轨音频以及庞大的 3D 资产会迅速耗尽主存储空间。Shumai 的**归档存储**(冷存储)功能支持创作团队将庞大的母盘原始文件分流至低成本的冷存储(例如本地 NAS、AWS S3 Glacier 或 Google Cloud Storage Coldline),同时将所有媒体代理版本、预览图、音频波形文件及元数据完整保留在主存储中。
团队成员可在 Web 浏览器中无缝浏览、搜索、拖拽预览并审阅已归档的资产。当需要母盘制作或调色而调用原始文件时,只需一键即可将其恢复解冻至主存储。
---
## 核心工作机制
1. **仅归档原始文件**:系统仅将原始素材文件迁移至归档存储。预览图、缩略图及转码代理文件(如 180p 拖拽代理、1080p 可流式播放 MP4、WebP 海报图)均保留在主存储中。
2. **高可靠持久化异步工作流**:文件的归档与恢复操作由 DBOS 管理的独立 Worker 任务队列(`archive_queue`)在后台处理。任务能够抵御网络中断、缓慢的 S3 传输以及服务器重启。
3. **透明的资产生命周期**:
- 资产归档过程中,其状态流转为 `archiving`(归档中),完成后定格为 `archived`(已归档)。
- 资产解冻恢复过程中,状态流转为 `restoring`(恢复中),原始文件恢复至主存储后变回 `processed`(已处理)。
- 移至废纸篓并被永久清空的资产,其在归档存储中的原始文件也会被自动同步彻底删除。
4. **支持文件夹与版本堆栈**:对文件夹或版本堆栈执行归档,将以递归方式归档其包含的所有文件资产;恢复文件夹或版本堆栈则会一并恢复其中包含的所有已归档文件。
---
## 存储拓扑
Shumai 支持灵活多样的存储架构,主存储与归档存储可分别采用不同的底层后端或服务商:
| 拓扑模式 | 主存储 | 归档存储 | 说明 |
| :----------------------------- | :---------- | :------- | :---------------------------------------------------------------------------------------------------------------------- |
| **本地 NAS / 挂载目录** | Local 或 S3 | `local` | 将文件迁移至已挂载的网络共享目录(NFS / SMB)或二级冷备磁盘阵列。 |
| **独立 S3 存储桶 / 服务商** | S3 或 Local | `s3` | 将文件流式传输至 AWS S3、Wasabi、Backblaze B2 或 Google Cloud Storage 上的专属归档存储桶。 |
| **同一 S3 存储桶(原位分层)** | AWS S3 | `s3` | 在 AWS S3 同一存储桶内,利用冷存储类型(`GLACIER`、`GLACIER_IR`、`DEEP_ARCHIVE`)就地重新分层,无需跨网络重新上传数据。 |
---
## 配置变量
在 `.env` 文件或 Docker Compose 配置中添加以下环境变量即可启用和配置归档存储。
### 通用配置
| 变量 | 说明 | 是否必填 | 默认值 |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ | :------- | :------------- |
| `ARCHIVE_STORAGE_BACKEND` | 归档存储后端:`local` 或 `s3`。未设置时,WebUI 中的归档功能保持禁用。 | 否 | 未设置(禁用) |
| `CONCURRENCY_ARCHIVE` | 后台 Worker 执行归档与恢复任务的最大并发数。 | 否 | `5` |
| `SHUMAI_WORKERS` | 应用服务器监听的 Worker 任务队列:`all`(默认)、`none`、`agent`(或 `ai`)、`transcode`、`archive`。需设置为 `all` 或 `archive` 以处理归档任务。 | 否 | `all` |
| `AUTO_ARCHIVE_INTERVAL_MINUTES` | 后台自动归档扫描任务的执行频率(单位:分钟)。支持小数值(例如测试时设为 `0.02`)。 | 否 | `60`(1 小时) |
### 本地归档存储
当 `ARCHIVE_STORAGE_BACKEND=local` 时生效:
| 变量 | 说明 | 是否必填 | 默认值 |
| :------------------- | :--------------------------------------------------------------------------------------------------- | :------- | :------------- |
| `ARCHIVE_LOCAL_ROOT` | 存储归档文件的宿主机文件系统目录路径。切勿与主存储本地目录(`./data` 或 `./data/<S3_BUCKET>`)重叠。 | 是 | 未设置(必填) |
### S3 归档存储
当 `ARCHIVE_STORAGE_BACKEND=s3` 时生效。请注意归档存储维护专属的独立配置,**绝不会回退**至主存储的 `S3_*` 环境变量:
| 变量 | 说明 | 是否必填 | 默认值 |
| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :---------------------------------------- |
| `ARCHIVE_S3_BUCKET` | 归档文件的目标 S3 存储桶(可为独立存储桶,也可在同存储桶分层时与 `S3_BUCKET` 相同)。 | 是 | 未设置(必填) |
| `ARCHIVE_S3_ACCESS_KEY_ID` | 归档 S3 服务的 Access Key ID。 | 是 | 未设置(必填) |
| `ARCHIVE_S3_SECRET_ACCESS_KEY` | 归档 S3 服务的 Secret Access Key。 | 是 | 未设置(必填) |
| `ARCHIVE_AWS_ENDPOINT_URL_S3` | 归档存储的 S3 服务端点 URL(例如 MinIO、Cloudflare R2、Google Cloud Storage)。 | 否 | 未设置(AWS 标准端点) |
| `ARCHIVE_S3_REGION` | 归档存储桶所在的 S3 区域。 | 否 | `auto` |
| `ARCHIVE_S3_FORCE_PATH_STYLE` | 采用路径风格 (Path-Style) S3 URL(MinIO / 路径风格设为 `true`,虚拟主机风格设为 `false`)。 | 否 | `true` |
| `ARCHIVE_S3_STORAGE_CLASS` | 赋予归档对象的 S3 存储类别(例如 `GLACIER`、`GLACIER_IR`、`DEEP_ARCHIVE`、`COLDLINE`)。归档至同一个 S3 存储桶时此项必填且不可为 `STANDARD`。 | 否 | 未设置 |
| `ARCHIVE_S3_USE_RESTORE_OBJECT` | 控制在读取已归档对象前是否调用 S3 `RestoreObject` 接口(`auto`、`true` 或 `false`)。 | 否 | `auto` |
| `ARCHIVE_S3_RESTORE_DAYS` | 异步 Glacier 解冻恢复时,解冻的临时副本在 S3 中保持可读状态的天数。 | 否 | `1` |
| `ARCHIVE_S3_RESTORE_TIER` | S3 Glacier 解冻检索层级(`Expedited`、`Standard` 或 `Bulk`)。若所用服务商无需异步解冻,可省略此参数。 | 否 | 未设置 |
| `ARCHIVE_RESTORE_POLL_INTERVAL_MS` | 等待异步冷存储解冻期间,状态轮询检查的间隔毫秒数。 | 否 | `60000`(初始 1 分钟,后续稳定为 5 分钟) |
---
## 配置示例
### 1. 本地 NAS / 挂载路径
适合配备本地网络附加存储(如群晖 Synology、威联通 QNAP、TrueNAS,或挂载至宿主机的 NFS/SMB 共享目录)的私有化部署团队:
```env
# 主存储配置(本地磁盘或 S3)
STORAGE_BACKEND=local
LOCAL_STORAGE_PATH=./storage
# 归档存储配置(指向挂载的 NAS 目录)
ARCHIVE_STORAGE_BACKEND=local
ARCHIVE_LOCAL_ROOT=/mnt/nas/shumai-archive
```
在 `docker-compose.yaml` 中,将宿主机 NAS 卷挂载至容器中:
```yaml
services:
shumai:
volumes:
- /mnt/nas/shumai-archive:/mnt/nas/shumai-archive
environment:
ARCHIVE_STORAGE_BACKEND: local
ARCHIVE_LOCAL_ROOT: /mnt/nas/shumai-archive
```
---
### 2. AWS S3 Glacier 即时检索 (Instant Retrieval)
AWS S3 Glacier Instant Retrieval (`GLACIER_IR`) 在提供冷存储低廉费率的同时具备**毫秒级检索延迟**。由于处于 `GLACIER_IR` 状态的对象不需要发起异步 `RestoreObject` 请求,将资产恢复至主存储可即时完成。
#### 同存储桶原位分层(快速路径)
若主存储已使用 AWS S3,可在**同一个存储桶**内将文件分层归档至 `GLACIER_IR`,无需在网络中重新上传数据:
```env
# 主存储配置
STORAGE_BACKEND=s3
S3_BUCKET=my-shumai-production
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
# 归档存储配置(复用相同的存储桶与凭据,搭配冷存储类别)
ARCHIVE_STORAGE_BACKEND=s3
ARCHIVE_S3_BUCKET=my-shumai-production
ARCHIVE_S3_REGION=us-east-1
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
ARCHIVE_S3_STORAGE_CLASS=GLACIER_IR
```
#### 专属归档存储桶
若倾向于将归档媒体文件存放在独立的 S3 存储桶中:
```env
# 归档存储配置(独立存储桶)
ARCHIVE_STORAGE_BACKEND=s3
ARCHIVE_S3_BUCKET=my-shumai-archive-glacier-ir
ARCHIVE_S3_REGION=us-east-1
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
ARCHIVE_S3_STORAGE_CLASS=GLACIER_IR
```
---
### 3. AWS S3 Glacier 灵活检索(深度冷存储)
对于极少访问的归档素材,AWS S3 Flexible Archive (`GLACIER`) 或 Deep Archive (`DEEP_ARCHIVE`) 可提供最大程度的存储成本节约。
当用户从 Glacier 恢复资产时,Shumai 会发起 `RestoreObject` 请求,将后台工作流转入 DBOS 持久化等待状态,并定期检查直至 AWS 完成文件解冻:
```env
ARCHIVE_STORAGE_BACKEND=s3
ARCHIVE_S3_BUCKET=my-shumai-cold-archive
ARCHIVE_S3_REGION=us-east-1
ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
ARCHIVE_S3_STORAGE_CLASS=GLACIER
# 解冻后的临时副本保持可访问状态 7 天
ARCHIVE_S3_RESTORE_DAYS=7
# Glacier 检索层级:Standard(标准,3-5 小时)、Expedited(快速,1-5 分钟)或 Bulk(批量,5-12 小时)
ARCHIVE_S3_RESTORE_TIER=Standard
```
> [!NOTE]
> 在 Glacier 解冻恢复期间,DBOS 会在 PostgreSQL 中调度持久化等待定时器。等待 AWS 解冻文件期间,Worker 线程将完全释放,不占用任何并发执行槽位。
---
### 4. Google Cloud Storage Coldline 归档
Google Cloud Storage (GCS) 提供兼容 S3 的 XML API 以及 `COLDLINE`、`ARCHIVE` 等低成本存储类别。与 Glacier Instant Retrieval 类似,GCS Coldline 提供**即时访问**能力,无需异步解冻阶段:
```env
# 主存储配置(例如 Cloudflare R2、MinIO 或标准 GCS)
STORAGE_BACKEND=s3
S3_BUCKET=shumai-main
...
# 基于 GCS Coldline 的归档存储
ARCHIVE_STORAGE_BACKEND=s3
ARCHIVE_S3_BUCKET=shumai-coldline-archive
ARCHIVE_S3_ACCESS_KEY_ID=GOOG1EXAMPLETOCKENKEY
ARCHIVE_S3_SECRET_ACCESS_KEY=your-gcs-hmac-secret-access-key
ARCHIVE_AWS_ENDPOINT_URL_S3=https://storage.googleapis.com
ARCHIVE_S3_STORAGE_CLASS=COLDLINE
```
> [!TIP]
> Google Cloud Storage 对象可直接读取,不接受 AWS Glacier 解冻检索参数。切勿设置 `ARCHIVE_S3_RESTORE_TIER`。若使用 GCS 的 `ARCHIVE` 存储类别,请配置 `ARCHIVE_S3_USE_RESTORE_OBJECT=false` 以跳过 S3 `RestoreObject` 调用。
---
## 资产自动归档
除手动按需归档外,Shumai 还支持团队基于资产生命周期策略实现冷存储自动分层。这样可以自动将庞大的原始素材文件迁移至二级冷存储,无需创作者或管理员反复手动清理。
### Web 端配置
团队所有者可在 **团队设置 > 存储** 下配置自动归档策略:
1. **归档存储状态概览**:
- 展示服务器当前配置的归档存储后端(`local` 或 `s3`)、服务端点、存储桶或根目录。
- 若服务端环境变量中未配置归档存储,界面将显示警告提示,且自动归档控制项保持禁用。
- 出于安全原因,凭据与服务器私密配置不会向客户端浏览器暴露。
2. **资产自动归档策略**:
- **启用自动归档**:为团队开启或关闭后台自动归档功能(默认关闭;需要已配置有效的归档存储后端)。
- **归档条件 (`method`)**:
- **超过指定天数未修改 (`not_updated`)**:以最后修改时间戳(`updatedAt`)作为判定标准。非常适合高频协作的生产工作流——只要团队成员仍在持续评论、批注或修改,文件就会保留在快速的主存储中。一旦在设定时间内未发生任何修改,资产便会自动移至冷存储。
- **创建超过指定天数 (`after_created`)**:以初始上传/创建时间戳(`createdAt`)作为判定标准。适合有严格留存周期要求或合规场景的流水线,无论近期是否有审阅评论,素材在达到指定时间(如交付后 60 天或 90 天)后均会自动分层归档。
- **保留时长阈值 (`days`)**:符合归档条件的资产在达到该天数阈值(介于 1 至 3650 天之间)后,将被排入归档队列。
- **恢复后保护缓冲期 (`postRestoreGraceDays`)**:
- 当资产从归档存储恢复至主存储时,其修改时间会刷新为恢复时刻。
- 若采用 **创建超过指定天数** 规则,早已超出阈值的文件(例如已创建 100 天的文件)原本会在下一次每小时扫描中立刻被再次归档。
- 恢复后保护缓冲期(默认 30 天)可确保恢复的文件在主存储中至少保留指定天数后,才重新具备自动归档资格。该数值应设置得小于保留时长阈值。在此策略下,只有既超过创建保留天数、且恢复时间也已超出保护缓冲期的文件,才会被自动归档。
### 副本去重与安全保证
Shumai 利用基于内容寻址的存储键(`storage_keys`),在项目与文件夹之间实现相同文件的去重:
- **副本保护机制**:若多条资产记录引用底层同一个存储对象(例如在文件夹或项目间复制、克隆的文件),自动归档扫描程序会检查所有关联的同源资产(Sibling Assets)。
- **严格共识机制**:仅当**所有活跃的关联同源文件**均满足团队的自动归档条件,且处于稳定的 `processed` 状态时,底层存储文件才会执行归档。
- **无饥饿调度**:若任一同源副本近期发生过修改或当前正处于活跃工作流中,系统将安全跳过该存储键,且不会阻塞其他符合条件资产的正常归档。
### 后台扫描与执行语义
自动归档任务在后台定期运行:
- **扫描频率**:通过环境变量 `AUTO_ARCHIVE_INTERVAL_MINUTES` 配置(默认 `60` 分钟;支持小数值如 `0.02` 用于自动化测试)。
- **分布式选主机制**:在候选扫描发现阶段使用 PostgreSQL 事务级咨询锁(`pg_try_advisory_xact_lock`)。在多 Pod 或多副本容器部署环境中,每个周期仅有单台服务器实例执行扫描,其他副本实例平稳跳过。
- **竞态条件防范**:在归档过程中,候选资产通过条件 SQL 语句(`UPDATE assets SET status = 'archiving' WHERE status = 'processed'`)配合行级 `storage_keys FOR UPDATE` 锁实现原子状态流转。这彻底避免了与用户并发执行的手动归档、恢复或文件删除发生竞态冲突。
---
## Web 端表现与权限
- **权限控制**:仅团队 **所有者 (Owner)** 与 **编辑者 (Editor)** 可执行资产的归档与恢复操作。
- **右键菜单**:在文件浏览器中右键点击任意文件、文件夹或版本堆栈,即可选择 **归档** 或 **从归档中恢复**。
- **状态标识**:已归档的条目在网格卡片与列表行中均带有 `已归档` 徽标。在文件查看器中,面包屑导航栏的文件名前会显示归档图标。
- **播放与预览**:借助主存储保留的缓存代理,视频流媒体播放、拖拽进度条、音频波形、PDF 渲染以及图片查看功能依然完全可用。
- **下载限制**:原片下载按钮将变为禁用状态,并带有气泡提示说明原始文件已被归档。转码代理版本下载(如 1080p MP4)不受影响,依然可用。
+173
View File
@@ -0,0 +1,173 @@
---
title: 分布式 Worker 部署
description: 通过独立的后台 Worker、DBOS 与兼容 S3 的对象存储配置大规模生产级部署。
---
在面对高并发视频处理或重度 AI 智能体调用的生产环境中,若将所有后台任务集中在单台服务器上运行,极易引发性能瓶颈。Shumai 通过由 **DBOS Transact** 统一编排的独立 Worker 节点,将 Web 控制台与后台处理彻底解耦,轻松化解瓶颈。
所有后台任务(媒体转码、AI 向量嵌入、智能体任务)均分发至直接托管在 PostgreSQL 中的持久化任务队列(`transcode_queue` 与 `agent_queue`)。无需部署额外的外部集群(如 Temporal)。
---
## 核心工作原理
在分布式部署中,Shumai 核心 Web 应用负责处理用户请求、数据库更新和文件上传,并通过 PostgreSQL 任务队列将持久化后台工作流委派给专用的 Worker 实例。
```mermaid
graph TD
UserUpload[用户上传视频 / 触发智能体] --> WebApp[Shumai Web UI / API]
WebApp -->|入队任务| DB[(PostgreSQL / DBOS 队列)]
DB -->|队列: transcode_queue| TranscodeWorker[转码 Worker 机器]
DB -->|队列: agent_queue| AgentWorker[智能体 Worker 机器]
```
- **转码 Worker**:可在配备 GPU 加速或高配 CPU 的计算实例上运行。
- **AI 智能体 Worker**:可在隔离沙箱环境中运行,以安全执行自动化脚本。
> [!IMPORTANT]
> **存储配置硬性要求**:由于在分布式部署下核心应用与后台 Worker 分别运行在不同机器上,**必须配置兼容 S3 的对象存储后端**(例如 AWS S3、Cloudflare R2 或 MinIO)。此模式下不支持本地存储(`STORAGE_BACKEND=local`),因为 Worker 节点与 Web 应用无法共享本地文件系统。
---
## 第 1 步:部署核心 Web 应用
在主服务器上运行 PostgreSQL 和 Shumai 核心 Web 应用。
若需指示核心 Web 应用仅处理 API 和前端 UI 流量,而不本地消费后台 Worker 队列任务,请设置 `SHUMAI_WORKERS=none`:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
STORAGE_BACKEND=s3
AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com
S3_BUCKET=shumai
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
SHUMAI_WORKERS=none
BETTER_AUTH_SECRET=your-random-32-character-secret-key
```
当使用 `SHUMAI_WORKERS=none`(或启动参数 `--workers=none`)启动时,Web 服务器将即刻启动,不会轮询或消费来自转码或智能体队列的任务。
---
## 第 2 步:配置并运行专属 Worker
在专用 Worker 机器上,配置各 Worker 的 `.env` 文件以指向共享的 PostgreSQL 数据库与 S3 存储:
```env
DATABASE_URL=postgresql://shumai:shumai_password@<primary-host-ip>:5432/shumai_db?schema=public
STORAGE_BACKEND=s3
AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com
S3_BUCKET=shumai
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
CONCURRENCY_TRANSCODE=1
CONCURRENCY_AGENT=5
```
### 媒体转码 Worker
在媒体处理计算节点上运行(需要预先在系统上安装 `ffmpeg` 与 `ffprobe`):
```bash
npm install -g @shumai-one/shumai-transcode
shumai-transcode
```
或者,可以使用轻量级专属 Docker 镜像运行转码 Worker:
```bash
docker run -d \
--name shumai-transcode-worker \
--env-file .env \
shumaione/shumai-transcode:latest
```
(亦可使用一体化全功能镜像:`docker run -d --name shumai-transcode-worker --env-file .env shumaione/shumai:latest shumai-transcode`。)
### AI 智能体 Worker
在沙箱化智能体执行节点上运行(需要安装 `bubblewrap` 或 `sandbox-exec` 等沙箱依赖项):
```bash
npm install -g @shumai-one/shumai-agent
shumai-agent
```
或者,可以使用官方 Docker 镜像运行智能体 Worker:
```bash
docker run -d \
--name shumai-agent-worker \
--env-file .env \
--cap-add=SYS_ADMIN \
shumaione/shumai:latest shumai-agent
```
> [!IMPORTANT]
> **Bun 用户须知**:由于 Worker 依赖包的二进制可执行文件包含 `#!/usr/bin/env node` Shebang,直接运行 `shumai-transcode` 或 `shumai-agent` 将在 Node.js 下执行。若希望使用 Bun 运行,请在命令前加上 `bun run --bun`(例如 `bun run --bun shumai-transcode` 或 `bun run --bun shumai-agent`)。
---
## Worker 并发与多实例部署
### 并发调优
Worker 根据可配置的并发上限从 PostgreSQL 队列中拉取任务:
- `CONCURRENCY_TRANSCODE`:单个 Worker 最大并发视频转码任务数(默认 `1`)。
- `CONCURRENCY_AGENT`:单个 Worker 最大并发智能体及向量嵌入工作流数(默认 `5`,若搭配本地 `embedding-server` 建议设为 `1`)。
### 副本实例标识
当在多台机器或 Pod 上运行转码或智能体 Worker 的多个副本时:
- `DbosExecutor` 会自动基于机器主机名与进程 ID 派生唯一的单实例标识,确保启动恢复时仅重新入队属于该实例的任务。
- **自定义 Worker ID**:若需显式指定标识符,可设置 `SHUMAI_WORKERS_ID`(或 `SHUMAI_WORKER_ID`)。
- **Kubernetes 环境**:在 Kubernetes Pod 中,可通过 Downward API(`fieldRef: { fieldPath: metadata.name }`)设置 `POD_NAME`,以在 Pod 重启期间保持稳定且唯一的单 Pod 身份标识。
---
## 基于 Kubernetes 与 AWS EKS 的弹性扩展部署
对于需要高吞吐媒体处理能力的生产级云端部署,Shumai 可部署在 Kubernetes 或 **AWS Elastic Kubernetes Service (AWS EKS)** 上,并借助 **KEDA (Kubernetes Event-driven Autoscaling)** 实现基于队列驱动的缩容至零(Scale-to-Zero)自动弹性伸缩。
```mermaid
graph TD
User([用户 / Web 浏览器]) -->|端口 80/3000| Server[Pod: shumai-server<br/>SHUMAI_WORKERS=agent]
Server -->|入队到 transcode_queue| DB[(PostgreSQL: pgvector18<br/>dbos.workflow_status)]
Server -->|直传 / 播放代理流| Storage[(S3 / Garage 存储)]
KEDA[KEDA ScaledJob<br/>PostgreSQL 触发器<br/>min: 0, max: 10] -.->|监控队列| DB
KEDA -->|为队列派发任务| Job1[Job: shumai-transcode-1<br/>自动排空 Worker]
KEDA -->|为队列派发任务| JobN[Job: shumai-transcode-N<br/>自动排空 Worker]
Job1 -->|获取源文件 / 存储代理文件| Storage
JobN -->|获取源文件 / 存储代理文件| Storage
Job1 -->|标记完成并退出 0| DB
JobN -->|标记完成并退出 0| DB
CA[Cluster Autoscaler / Karpenter] -.->|缩容至零按需节点<br/>0 到 10 实例| JobN
```
### 架构核心优势
- **解耦的无状态 Worker**:核心 Web 与 API 服务、数据库以及对象存储均运行在可靠的按需计算节点上(`c9g.large`,`SHUMAI_WORKERS=agent`),媒体转码任务则委派给由 PostgreSQL 中 DBOS 任务队列统一编排的后台 Worker。
- **专用 Graviton5 按需计算实例 (`c9g.xlarge`)**:媒体编码运行在 4 vCPU / 8 GiB 内存的 AWS Graviton5 按需实例上(约 0.174 美元/小时),充分利用 ARM64 向量优化与高速 DDR5 内存,且免受竞价实例(Spot)非预期中断的影响。
- **基于 KEDA 的队列驱动缩容至零**:KEDA 持续监听 `dbos.workflow_status` 中已入队与待处理的转码任务,并动态创建 Kubernetes `ScaledJob` 资源(支持 0 到 10 弹性伸缩)。当队列排空时,转码节点完全缩容至零(`minSize: 0`),转码计算成本降至 **0 美元/小时**。
- **空闲超时自动排空**:Worker Pod 以并发数 `1` 持续处理排队任务。当队列彻底排空且 Pod 持续空闲 10 秒(`SHUMAI_WORKER_IDLE_TIMEOUT_MS=10000`)后,Pod 将以状态码 `0` 正常退出以触发节点缩容,在批量上传时避免了 Pod 频繁冷启动的开销。
- **停滞任务自动恢复**:核心 Web 服务器运行内置的恢复巡检机制,可自动检测停滞或孤儿任务(例如因节点崩溃导致的任务中断)并在 DBOS 中自动恢复执行,同时设有最多 3 次重试上限以安全防范毒丸异常素材(Poison-Pill Media)。
### 完整部署示例与源码
生产就绪的完整清单文件、声明式 `eksctl` 集群配置以及分步操作指引,请参阅 Shumai 仓库中的 **[EKS 部署示例](https://github.com/shumaiOne/shumai/tree/main/eks)**:
👉 **[在 GitHub 上查看 EKS 部署指南与清单文件](https://github.com/shumaiOne/shumai/tree/main/eks)**
仓库包含:
- [`eks/eks-cluster.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/eks-cluster.yaml):包含分层计算配置的完整 `eksctl` ClusterConfig。
- [`eks/kustomization.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/kustomization.yaml):用于所有服务的一键式 Kustomize 部署文件。
- 详细说明了如何配置公网端点、自动化 Cluster Autoscaler 以及零停机平滑停机(Graceful Shutdown)。
+161
View File
@@ -0,0 +1,161 @@
---
title: 环境变量
description: Shumai 全量配置参数参考指南。
---
Shumai 通过环境变量配置。可以在应用工作区根目录的 `.env` 文件中定义这些变量,也可在启动 Docker 容器时直接传入。
---
## 数据库配置
| 变量 | 说明 | 示例 / 默认值 |
| :------------- | :------------------------------------------------------------ | :------------------------------------------------------- |
| `DATABASE_URL` | PostgreSQL 连接 URL。目标数据库必须预先安装 `pgvector` 扩展。 | `postgresql://user:pass@localhost:5432/db?schema=public` |
---
## 服务器配置
| 变量 | 说明 | 示例 / 默认值 |
| :---------------------- | :------------------------------------------------------------------ | :------------- |
| `SHUMAI_SERVER_PORT` | Shumai Web 服务器监听的端口。 | `3000`(默认) |
| `MAX_REQUEST_BODY_SIZE` | 允许的最大请求体大小(例如用于大文件上传),单位为字节。默认 10GB。 | `10737418240` |
---
## 认证与应用配置
| 变量 | 说明 | 示例 / 默认值 |
| :------------------- | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | 用于对会话 Cookie 和 JWT 签名的安全随机 32 字节密钥。 | 可通过 `openssl rand -base64 32` 生成 |
| `BETTER_AUTH_URL` | Shumai 服务器的公网访问 URL。用于 MCP OAuth 2.1 端点发现、重定向流程、密码重置链接以及邮件通知。 | `http://localhost:3000`(未设置时回退至 `SHUMAI_SERVER_PORT`) |
| `APP_URL` | Web 前端应用的公网访问 URL。用于通知邮件中的深度链接(未设置时回退至 `BETTER_AUTH_URL`)。 | `https://shumai.example.com` |
---
## 存储配置
Shumai 支持将文件存储在本地文件系统或兼容 S3 的对象存储中。
| 变量 | 说明 | 示例 / 默认值 |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------- |
| `STORAGE_BACKEND` | 存储类型。使用 `local` 表示本地文件系统存储,使用 `s3` 表示兼容 S3 的云对象存储。 | `local`(默认)或 `s3` |
| `AWS_ENDPOINT_URL_S3` | S3 存储或本地存储的服务端点。浏览器据此生成文件上传链接。在远程部署或使用自定义端口时,必须包含端口号。 | `http://localhost:3000`(未设置时回退至 `SHUMAI_SERVER_PORT`) |
| `S3_BUCKET` | S3 存储桶名称。 | `shumai`(默认) |
| `S3_ACCESS_KEY_ID` | S3 访问凭据 Access Key ID。 | `minioadmin`(默认) |
| `S3_SECRET_ACCESS_KEY` | S3 访问凭据 Secret Access Key。 | `minioadmin`(默认) |
| `S3_REGION` | S3 存储区域。 | `auto`(默认) |
| `PRESIGNED_URL_EXPIRES_IN` | 生成的预签名下载链接的有效时长(单位:小时)。 | `5`(默认) |
| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | 生成的预签名上传链接的有效时长(单位:小时)。未设置时回退至 `PRESIGNED_URL_EXPIRES_IN`。 | `12`(默认) |
### 本地存储端口配置
当 `STORAGE_BACKEND` 设为 `local`(默认值)时:
- `SHUMAI_SERVER_PORT` 用于配置 Shumai Web 服务器启动并监听的端口。
- `AWS_ENDPOINT_URL_S3` 用于配置客户端浏览器上传和下载文件所用的公网/外部访问端点。必须包含协议头(Scheme)与端口。
例如,若在远程服务器 `http://123.456.7.8` 上部署 Shumai,且在 Docker Compose 中配置了端口映射 `12345:3000`(即内部端口 3000 映射为宿主机外部端口 12345):
- 将 `SHUMAI_SERVER_PORT` 设为 `3000`。
- 将 `AWS_ENDPOINT_URL_S3` 设为 `http://123.456.7.8:12345`。
### 归档存储配置
Shumai 支持配置可选的**归档存储**(冷存储)层级(`local` NAS/挂载目录或 `s3` 存储桶/存储类型),用于将原始素材文件归档迁移,同时在主存储中保留代理版本、预览图、缩略图和元数据。
| 变量 | 说明 | 示例 / 默认值 |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------- |
| `ARCHIVE_STORAGE_BACKEND` | 归档存储类型。留空表示禁用归档存储,可选 `local` 或 `s3`。 | 未设置(禁用)、`local` 或 `s3` |
| `ARCHIVE_LOCAL_ROOT` | 当 `ARCHIVE_STORAGE_BACKEND=local` 时必填。归档原始文件的根目录(例如挂载的 NAS 目录),文件将直接存储在 `<ARCHIVE_LOCAL_ROOT>/<key>` 下。 | `/mnt/nas/shumai-archive` |
| `ARCHIVE_AWS_ENDPOINT_URL_S3` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时的自定义 S3 归档端点(独立于 `AWS_ENDPOINT_URL_S3`)。 | `https://s3.us-east-1.amazonaws.com` |
| `ARCHIVE_S3_BUCKET` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时必填。归档文件的目标 S3 存储桶(可为独立存储桶,也可与 `S3_BUCKET` 相同并配合冷存储类型使用)。 | `shumai-archive` |
| `ARCHIVE_S3_ACCESS_KEY_ID` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时必填。归档存储的 S3 Access Key ID。 | `AKIA...` |
| `ARCHIVE_S3_SECRET_ACCESS_KEY` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时必填。归档存储的 S3 Secret Access Key。 | `...` |
| `ARCHIVE_S3_REGION` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时归档存储的 S3 区域。 | `auto`(默认) |
| `ARCHIVE_S3_STORAGE_CLASS` | 归档对象时附加的可选 S3 `StorageClass` 标头(支持任意标准或厂商特定的存储类型字符串;在同存储桶分层场景下必填且不可为 `STANDARD`)。 | `GLACIER_IR`、`GLACIER`、`DEEP_ARCHIVE`、`STANDARD_IA` |
| `ARCHIVE_S3_USE_RESTORE_OBJECT` | 控制在读取已归档对象前是否调用 S3 `RestoreObject` 接口(`auto`、`true` 或 `false`)。 | `auto`(默认) |
| `ARCHIVE_S3_RESTORE_DAYS` | S3 冷存储对象解冻恢复后,解冻副本保持可读状态的天数。 | `1`(默认) |
| `ARCHIVE_S3_RESTORE_TIER` | 可选的 S3 Glacier 解冻检索层级(`Expedited`、`Standard`、`Bulk`)。未设置时省略该参数,适用于拒绝 `GlacierJobParameters` 的兼容 S3 服务商。 | 未设置(默认) |
| `AUTO_ARCHIVE_INTERVAL_MINUTES` | 后台自动归档扫描任务的执行频率(单位:分钟)。支持小数值(例如测试时设为 `0.02`)。 | `60`(默认 1 小时) |
---
## 工作流配置
用于配置 DBOS Transact 队列的后台 Worker 执行、并发限制及 Worker 实例标识。
| 变量 | 说明 | 示例 / 默认值 |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :---------------- |
| `SHUMAI_WORKERS` | Web 服务器监听的任务队列。可选值:`all`(默认,监听全部队列)、`none`(仅作为 API/UI 服务)、`agent`(或 `ai`)、`transcode`、`archive`。 | `all`(默认) |
| `CONCURRENCY_TRANSCODE` | Worker 执行媒体转码任务的最大并发数。 | `1`(默认) |
| `CONCURRENCY_ARCHIVE` | Worker 执行归档与解冻任务的最大并发数。 | `5`(默认) |
| `CONCURRENCY_AGENT` | Worker 执行 AI 任务的最大并发数。在运行本地 `embedding-server` 时建议设为 `1`。 | `5`(默认) |
| `SHUMAI_WORKER_ID` | 多节点部署中 Worker 副本的可选显式实例 ID(未设置时根据主机名和进程 ID 自动派生)。 | `worker-1` |
| `POD_NAME` | Kubernetes Pod 名称,用于在 StatefulSet 重启时保持稳定的各 Pod Worker 身份标识。 | `transcode-pod-0` |
---
## 向量模型配置
| 变量 | 说明 | 示例 / 默认值 |
| :-------------------------------- | :------------------------------------------------------------------------------- | :-------------------------------- |
| `EMBEDDING_PROVIDER` | 多模态向量模型服务商。可选值:`gemini-embedding-2`、`gemma-embedding-2-openai`。 | `gemini-embedding-2`(默认) |
| `GEMMA_EMBEDDING_OPENAI_BASE_URL` | 兼容 OpenAI 协议的 LiteRT-LM 向量模型服务 Base URL。 | `http://embedding-server:9379/v1` |
| `ENABLE_EMBEDDING_AGENT` | 设为 `true` 时,在启动时自动为所有团队置备并启用系统向量智能体。 | `false`(默认) |
| `EMBEDDING_CHUNK_DURATION` | 生成视频向量时每个视频切片的时长(单位:秒)。 | `60.0`(默认) |
| `EMBEDDING_CHUNK_OVERLAP` | 生成视频向量时各个视频切片的重叠时长(单位:秒)。 | `5.0`(默认) |
## 沙箱配置
| 变量 | 说明 | 示例 / 默认值 |
| :----------------------------- | :--------------------------------------------------------------------------- | :-------------- |
| `ENABLE_WEAKER_NESTED_SANDBOX` | 为缺少用户命名空间权限的环境(例如某些 Docker 容器)启用弱隔离嵌套沙箱模式。 | `false`(默认) |
---
## 日志配置
| 变量 | 说明 | 示例 / 默认值 |
| :----------- | :------------------------------------------------------------------------- | :------------- |
| `LOG_LEVEL` | Pino 日志输出级别。可选值:`debug`、`info`、`warn`、`error`。 | `info`(默认) |
| `LOG_FORMAT` | 日志输出格式风格。生产环境推荐使用 `json`,终端直观查看推荐使用 `pretty`。 | `json`(默认) |
---
## 大语言模型 API 密钥
启动时预配给 AI 服务商的 API Key。
| 变量 | 说明 | 示例 / 默认值 |
| :------------------ | :------------------------------- | :------------ |
| `GEMINI_API_KEY` | Google Gemini 服务商的 API Key。 | `AIzaSy...` |
| `OPENAI_API_KEY` | OpenAI 服务商的 API Key。 | `sk-proj-...` |
| `ANTHROPIC_API_KEY` | Anthropic 服务商的 API Key。 | `sk-ant-...` |
---
## 外部集成配置
环境变量可用于全局配置外部微服务。设置后,这些环境变量的优先级高于在 **团队设置 → 集成** 中配置的任何团队级设置,并将 WebUI 中的对应设置字段锁定为只读状态。
### Gotenberg 文档转换服务
用于将 Office 文档、HTML、Markdown 和 CSV 文件转换为高保真 PDF 代理文件,以供浏览器内直接预览。安装配置步骤请参阅 [Gotenberg 指南](/zh/using-shumai/gotenberg)。
| 变量 | 说明 | 示例 / 默认值 |
| :------------------------------ | :-------------------------------------------- | :---------------------- |
| `GOTENBERG_URL` | 外部 Gotenberg 转换服务的 API Base URL。 | `http://gotenberg:3000` |
| `GOTENBERG_BASIC_AUTH_USERNAME` | Gotenberg 实例启用 Basic 身份验证时的用户名。 | `admin` |
| `GOTENBERG_BASIC_AUTH_PASSWORD` | Gotenberg 实例启用 Basic 身份验证时的密码。 | `secret` |
### 3D 转台渲染服务
用于将 3D 模型文件(GLB、OBJ、FBX、USD、STL、DAE)转换为交互式 360° 旋转转台视频代理、封面图以及悬浮预览雪碧图。安装配置步骤请参阅 [3D 资产支持指南](/zh/using-shumai/3d-asset-support)。
| 变量 | 说明 | 示例 / 默认值 |
| :--------------------------------------- | :------------------------------------------------------------------------------------ | :------------------------------- |
| `TURNTABLE_RENDERER_URL` | 外部 turntable-renderer 服务的 Base URL。 | `http://turntable-renderer:3000` |
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | 3D 转台渲染服务启用 Basic 身份验证时的用户名(别名:`TURNTABLE_RENDERER_USERNAME`)。 | `admin` |
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | 3D 转台渲染服务启用 Basic 身份验证时的密码(别名:`TURNTABLE_RENDERER_PASSWORD`)。 | `secret` |
@@ -0,0 +1,233 @@
---
title: 硬件加速转码
description: 利用 GPU 硬件加速显著提升视频转码速度并降低 CPU 负载。
---
高分辨率摄影机录像、手机拍摄视频以及动画媒体文件需要转码为代理格式,方可在 Web 浏览器中流畅播放。Shumai 在后台自动转码这些资产,生成用于即时拖拽播放(Scrubbing)的通用 `180p` 代理文件以及全分辨率预览流。
硬件加速转码支持将视频编码负载分流至独立显卡或集成 GPU,大幅缩短处理耗时,并为其他系统服务释放宿主机的 CPU 核心资源。
Shumai 内置可用性探测机制,在系统启动时自动测试硬件编码器,并在视频处理期间提供运行时自动回退保障。若 GPU 驱动或设备节点不可用,亦或硬件编码器达到硬件物理限制(例如某些 GPU 对特定分辨率或长宽比例的限制)乃至发生驱动运行时错误,Shumai 均能无缝回退至 CPU 软件编码(`libx264`),确保用户任务不会中断失败。
---
## 支持的硬件加速后端
| 后端 | 硬件平台 | 容器驱动 / 设备节点 |
| :-------------- | :----------------------------------- | :----------------------------------------------- |
| **`nvenc`** | NVIDIA GPU | NVIDIA Container Toolkit (`gpu, compute, video`) |
| **`quicksync`** | Intel 核显与 Arc 独显 | `/dev/dri` 渲染节点 |
| **`vaapi`** | AMD 与 Intel GPU | `/dev/dri` 渲染节点 |
| **`rkmpp`** | 瑞芯微 Rockchip ARM SoC(如 RK3588) | `/dev/rga`、`/dev/dri`、`/dev/mpp_service` |
| **`vaapi-wsl`** | Windows 适用于 Linux 的子系统 (WSL2) | `/dev/dri`、`/dev/dxg`、`/usr/lib/wsl` |
---
## 使用限制与注意事项
- 本文说明以 **Docker Compose** 为准。若使用其他容器编排工具(如 Kubernetes 或 Podman),需配置等效的设备透传参数。
- **macOS 上的 Docker Desktop** 运行在 Linux 虚拟机内,不支持 Apple Silicon 的 VideoToolbox 设备透传。(直接通过 NPM 或源码在本地原生运行 Shumai 时支持 VideoToolbox 硬件加速)。
- 硬件加速转码生成的视频码率特征与软件编码略有差异。Shumai 采用针对 Web 流媒体优化的自适应可变码率(VBR)速率控制策略,以确保画面保真度。
---
## 前置要求
### NVENC (NVIDIA)
1. 确认宿主机已安装 NVIDIA 官方显卡驱动:
```bash
nvidia-smi
```
2. 在宿主机上安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) 并重启 Docker:
```bash
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```
### QuickSync 与 VA-API (Intel / AMD)
1. 验证 Linux 内核已初始化 Direct Rendering Infrastructure (DRI) 渲染节点:
```bash
ls -la /dev/dri
```
输出中应包含 `card0` 和 `renderD128`(或类似节点)。
2. Shumai 的 Docker 镜像在容器启动时会自动调整用户组权限,非 root 应用用户无需手动调整即可直接访问宿主机的 `/dev/dri` 设备,避免权限错误。
#### GPU 解码
采用 VA-API 模式时,Shumai 会在 GPU 上同时完成视频解码与尺寸缩放,帧数据全程保留在 GPU 显存内。这种方式显著快于 CPU 解码,尤其是在集成显卡上处理 4K 片源时提升尤为明显。(其他后端目前采用 CPU 解码并由 GPU 负责编码。)
部分视频会自动切换为“CPU 解码 + GPU 编码”模式:
- GPU 无法解码的编码格式,例如老款 Intel 芯片上的 HEVC 或 10-bit 视频。Shumai 会先尝试 GPU 解码,并在 1 秒内自动重试切换至 CPU 解码。
- 带有旋转元数据的视频(如手机竖屏录像),以确保输出画面朝向正确。
- 带有水印的分享链接视频以及 HDR 片源。
若某次 GPU 解码卡死超过 2 分钟(某些显卡驱动缺陷会导致 FFmpeg 进程挂起而非报错退出),Shumai 会中止该尝试并使用 CPU 重新解码。可通过 `SHUMAI_HW_DECODE_STALL_TIMEOUT`(单位:秒)调整此超时限制。
若希望全局始终使用 CPU 解码,可在 `shumai` 服务上配置环境变量 `SHUMAI_HW_DECODE=false`。
### WSL2 (Windows)
- 确保系统运行 Windows 11 与 WSL2,且已在 Windows 宿主机上安装相应的 GPU 显卡驱动。
- 使用 `vaapi-wsl` 预设,该预设会将 `/dev/dxg` 与 `/usr/lib/wsl` 映射进容器内。
---
## 使用 Docker Compose 部署配置
Shumai 采用模块化的 `hwaccel.transcoding.yaml` 辅助配置文件来定义硬件设备。
### 第 1 步:下载配置文件
在 Shumai 部署目录下,将 `hwaccel.transcoding.yaml` 下载至 `docker-compose.yaml` 旁:
```bash
# 全球官方源
curl -o hwaccel.transcoding.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml
# 中国大陆加速镜像源
curl -o hwaccel.transcoding.yaml https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml
```
### 第 2 步:在 Docker Compose 中启用硬件加速
打开 `docker-compose.yaml`(或 `docker-compose-aliyun.yaml`),找到 `shumai` 服务下被注释的 `extends` 代码块,并取消注释:
```yaml
services:
shumai:
# ...
# 硬件加速 (NVENC / QuickSync / VA-API / RKMPP)
extends:
file: hwaccel.transcoding.yaml
service: nvenc # 设置为 [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] 之一
```
将 `nvenc` 替换为目标硬件后端:
- `nvenc`:适用于 NVIDIA GPU
- `quicksync`:适用于 Intel Quick Sync
- `vaapi`:适用于 AMD 或 Intel VA-API
- `rkmpp`:适用于瑞芯微 Rockchip SoC
- `vaapi-wsl`:适用于 Windows WSL2
### 第 3 步:启动服务
重启或重新创建 Shumai 容器:
```bash
docker compose up -d
```
---
## 单文件 Compose 配置 (Unraid / Portainer)
若所处的容器编排管理工具不支持跨文件的 `extends` 语法,可直接将硬件配置内联写入 `docker-compose.yaml` 中的 `shumai` 服务:
<AccordionGroup>
<Accordion title="NVIDIA NVENC">
```yaml
services:
shumai:
# ...
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
- compute
- video
```
</Accordion>
<Accordion title="Intel QuickSync / AMD VA-API">
```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri ```
</Accordion>
<Accordion title="WSL2 (Windows)">
```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri - /dev/dxg:/dev/dxg volumes: -
/usr/lib/wsl:/usr/lib/wsl environment: - LIBVA_DRIVER_NAME=d3d12 ```
</Accordion>
<Accordion title="瑞芯微 Rockchip RKMPP">
```yaml
services:
shumai:
# ...
security_opt:
- systempaths=unconfined
- apparmor=unconfined
group_add:
- video
devices:
- /dev/rga:/dev/rga
- /dev/dri:/dev/dri
- /dev/dma_heap:/dev/dma_heap
- /dev/mpp_service:/dev/mpp_service
```
</Accordion>
</AccordionGroup>
---
## Web 端设置
在 Shumai Web 端,前往 **团队设置** > **转码设置**。
- **自动(推荐)**:Shumai 按最优优先级顺序自动探测候选硬件编码器(`h264_nvenc` &rarr; `h264_vaapi` &rarr; `h264_qsv` &rarr; `h264_amf` &rarr; `libx264`)。若硬件加速不可用,则平滑降级至软件编码。
- **指定编码器**:可将转码流水线显式锁定到指定编码器(如 `NVENC`、`Quick Sync`、`VA-API`)。
- **关闭**:对所有视频任务强制使用 CPU 软件编码(`libx264`)。
---
## 验证与监控
### 查看转码日志
当上传资产开始视频转码时,Shumai 会记录一条结构化日志,明确标明所选用的编码器:
```bash
docker compose logs -f shumai
```
查找包含 `Starting video transcoding` 的日志记录:
```json
{
"level": 30,
"time": 1790414665096,
"encoder": "h264_nvenc",
"hardwareAcceleration": "auto",
"inputFile": "/tmp/transcode-.../video.mp4",
"outputFile": "/tmp/transcode-.../video-180p.mp4",
"msg": "Starting video transcoding"
}
```
若硬件加速已成功初始化,`encoder` 字段将显示 `h264_nvenc`、`h264_vaapi` 或 `h264_qsv`。
### 监控 GPU 负载利用率
视频转码执行期间,可在宿主机上观察硬件资源占用情况:
- **NVIDIA**:
```bash
nvidia-smi
# 或
nvtop
```
- **Intel**:
```bash
sudo intel_gpu_top
```
- **AMD**:
```bash
sudo radeontop
```
+222
View File
@@ -0,0 +1,222 @@
---
title: Shumai MCP 服务
description: 让 Claude Code、Cursor 或 Kiro 等外部 AI 智能体与 Shumai 项目协同工作。
---
Shumai 内置了 [模型上下文协议](https://modelcontextprotocol.io)(MCP)服务。任何兼容 MCP 协议的智能体均可接入该服务,代表用户浏览项目、查看图片、视频与文档、创建文件夹以及整理资产,且调用与 Shumai 原生内置智能体完全相同的工具集。
<Note>
本页面介绍如何将 **外部智能体连接至 Shumai**。若需了解如何将 Shumai
自带智能体连接至其他外部工具,请参阅 [MCP 服务](/zh/using-shumai/mcp-servers)。
</Note>
---
## 连接客户端
MCP 服务采用 Streamable HTTP 传输协议,访问端点为:
```
https://<your-shumai-host>/mcp
```
Shumai 支持 **OAuth 2.1**(推荐方式,提供无缝的浏览器授权体验)以及 **API Token**(适用于无头环境或不支持 OAuth 的客户端)。
请根据所使用的客户端选择相应配置指南:
### Claude Code
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 原生支持具备 OAuth 身份验证的远程 HTTP MCP 服务。运行以下命令即可将 Shumai 添加至 Claude Code 配置:
```bash
claude mcp add shumai --transport http https://<your-shumai-host>/mcp
```
启动新对话时,Claude Code 会打开浏览器窗口供登录并授予 Shumai 账户访问权限,无需手动配置 API Token。
或者,可手动配置 `.claude/settings.json`:
```json
{
"mcpServers": {
"shumai": {
"type": "http",
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
或通过 `mcp-remote` 桥接 stdio:
```bash
claude mcp add shumai -- npx -y mcp-remote https://<your-shumai-host>/mcp
```
### Cursor
将 Shumai 添加至 Cursor 的 MCP 配置(`~/.cursor/mcp.json` 或项目级 `.cursor/mcp.json`):
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
当 Cursor 连接到服务时,会在浏览器中提示完成 OAuth 登录并授权访问。
若改用 API Token 验证身份,请在请求标头中传递 `Authorization`:
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp",
"headers": {
"Authorization": "Bearer <your-api-token>"
}
}
}
}
```
### Codex
```bash
codex mcp add shumai --url https://<your-shumai-host>/mcp
codex mcp login shumai
```
### VS Code
```bash
code --add-mcp '{"name":"shumai","type":"http","url":"https://<your-shumai-host>/mcp"}'
```
在 VS Code 的 **MCP Servers** 列表中启动该服务,并根据提示登录 Shumai。
### 其他客户端
**远程服务 (HTTP)**
若客户端原生支持远程 HTTP MCP 服务:
```json
{
"mcpServers": {
"shumai": {
"url": "https://<your-shumai-host>/mcp"
}
}
}
```
**本地桥接 (`mcp-remote` / stdio)**
对于仅支持本地 (stdio) MCP 服务的客户端,可使用 `mcp-remote` 连接 Shumai 的远程 HTTP 端点:
```json
{
"mcpServers": {
"shumai": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://<your-shumai-host>/mcp"]
}
}
}
```
---
## 身份验证
Shumai 的 MCP 服务支持两种身份验证方式:
### OAuth 2.1(推荐)
Shumai 实现了基于动态客户端注册(Dynamic Client Registration, [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))与 OAuth 受保护资源元数据(OAuth Protected Resource Metadata, [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) / [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414))规范的 OAuth 2.1。
- **无缝登录**:受支持的 MCP 客户端可自动发现授权端点并在浏览器中完成 OAuth 握手。
- **访问控制**:外部智能体以调用方在 Shumai 中的既有权限执行操作。所有行为均归属于该用户账户,并在团队审计日志中标记为 `via: mcp`。
- **清除 OAuth 缓存**:若需要在 `mcp-remote` 或 Claude Code 等 CLI 工具中重新鉴权或清除已保存的凭据,请删除本地认证缓存:
```bash
rm -rf ~/.mcp-auth
```
### API Token
API Token 适用于自动化 CI/CD 流水线、无头环境或不支持交互式 OAuth 的客户端。
1. 在 Shumai 中,打开 **团队设置** → **API Token**。
2. 输入名称(例如 `ci-agent` 或 `cursor-token`),然后点击 **生成**。
3. 在弹窗中复制 Token。该 Token 仅展示一次。
4. 在请求头中传递该 Token:`Authorization: Bearer <your-api-token>`(或通过 `x-api-key` 请求头)。
<Warning>
API Token 拥有与用户本人完全相同的操作权限:智能体可执行该账户在 Shumai
中所能执行的任意操作。请像保管密码一样妥善保管 Token,建议为每个客户端单独生成独立
Token,若不再使用,请前往 **团队设置** → **API Token** 及时吊销。
</Warning>
---
## 可用工具列表
| 工具 | 功能说明 |
| ------------------------- | --------------------------------------------------------------------------------------- |
| `list_projects` | 列出当前可访问的项目及其根目录文件夹。 |
| `list_assets` | 分页列出指定文件夹内的文件与子文件夹。 |
| `search_assets` | 按名称、语义含义(需启用 AI 搜索)或元数据搜索文件夹及其子文件夹。 |
| `create_folder` | 创建文件夹。 |
| `rename_asset` | 重命名文件或文件夹。 |
| `move_assets` | 将文件或文件夹移动至另一个文件夹。 |
| `copy_assets` | 将文件或文件夹复制至同团队下的另一个文件夹。 |
| `delete_asset` | 将文件或文件夹移至项目废纸篓。此操作标记为破坏性操作,客户端可据此要求用户确认。 |
| `read_asset` | 查看文件内容:图片、视频帧、PDF 页面、3D 模型视图或文本文件内容。 |
| `get_asset_render` | 获取此前仍在渲染中的 `read_asset` 任务结果。 |
| `download_asset` | 获取最多 50 个文件的下载链接:默认获取 Web 预览版本,指定 `proxy: false` 可获取原文件。 |
| `get_folder_instructions` | 读取文件夹中面向 AI 智能体的指引文件(AGENTS.md)。 |
| `create_file` | 发起向文件夹上传新文件的流程(详见 [上传文件](#上传文件))。 |
| `create_version` | 发起为已有文件上传新版本的流程。 |
| `complete_upload` | 完成由 `create_file` 或 `create_version` 发起的上传流程。 |
| `list_comments` | 列出文件上的审阅评论及其回复。 |
| `create_comment` | 在文件上添加评论(可指定时间码)或回复评论。 |
| `resolve_comment` | 将评论标记为已解决或恢复为未解决。 |
| `list_metadata_fields` | 列出项目的元数据字段(如状态、评分及自定义字段)及其候选值。 |
| `update_asset_metadata` | 设置文件的元数据值。 |
| `create_version_stack` | 将同目录下的多个文件打包为单个资产的版本堆栈。 |
| `list_versions` | 按倒序列出版本堆栈中的所有版本。 |
| `remove_version` | 将指定版本移出版本堆栈(保留原文件)。 |
### 读取文件
`read_asset` 会将图片附加至调用结果中,以便 AI 模型直接识别:每次调用最多支持 8 张图片,每张大小不超过 2 MB。超出部分的图片仅以链接形式列出。每条返回结果均包含指向各图片的访问链接,有效期约为 1 小时。若客户端无法直接渲染图片,可传入 `inlineImages: false` 仅获取链接。
渲染视频帧或 PDF 页面通常耗时较长。若渲染耗时超过约 20 秒,`read_asset` 将返回状态 `status: "pending"` 与对应的 `taskId`;随后模型可携带该 `taskId` 调用 `get_asset_render` 获取最终渲染结果。仅发起读取任务的用户本人可获取其渲染结果。
### 上传文件
上传过程分为三个阶段,以确保大文件内容无需经由 AI 模型中转:
1. `create_file`(或 `create_version`)返回 `uploadUrl` 与 `uploadId`。
2. 智能体通过 HTTP `PUT` 请求将文件二进制数据上传至 `uploadUrl`,例如使用 `curl -T video.mp4 "<uploadUrl>"`。
3. 携带 `uploadId` 调用 `complete_upload` 完成文件创建并触发后续处理(如生成预览、媒体转码)。
上传 URL 与 ID 的有效期约为 1 小时,且仅允许发起者本人确认完成上传。若项目配置了**创建上下文 (Creation Context)** 元数据字段(例如生成该文件所使用的 Prompt 或模型),可在调用 `create_file` 或 `create_version` 时将其作为 `metadata` 传入;通过 `list_metadata_fields` 可查询当前支持的字段。
智能体必须能够直接访问上传 URL。若 Shumai 配置了本地存储,该 URL 指向 Shumai 服务器;若配置了 S3 存储,则直接指向 S3 端点。
每次调用均遵循用户的实际权限执行:例如拥有 **审阅者 (Reviewer)** 角色的成员可以列出资产,但无法创建或重命名资产。所有操作均记录在团队审计日志中并归属至该用户,来源标记为 MCP。
---
## 故障排查
- **OAuth 授权已过期或失效**:清理客户端本地 OAuth 会话缓存(`rm -rf ~/.mcp-auth`),并重启 MCP 客户端重新完成鉴权。
- **401 Unauthorized**:API Token 或 OAuth 访问令牌缺失、过期、拼写错误或已被吊销。若使用 API Token,请前往 **团队设置** → **API Token** 重新生成,并更新客户端配置。
- **工具调用出现权限错误 (Permission errors)**:当前用户在对应团队或项目中的角色无权执行该操作。
+37
View File
@@ -0,0 +1,37 @@
---
title: 概览
description: 了解 Shumai —— 现代化媒体资产协作与审阅平台。
---
## 什么是 Shumai?
**Shumai** 是一款专为创意团队、视频剪辑师、设计师及客户打造的自托管媒体协作平台。它提供集中式工作区,支持实时上传、组织与审阅各类资产(视频、音频、图像和文档)。依托内置的 AI 能力与后台转码系统,Shumai 能显著简化媒体资产管理与审阅反馈流程。
![Shumai 控制台](/screenshot.webp)
---
## 核心特性
- **安全存储**:既支持在本地服务器存储创意资产,也可直接对接任意兼容 S3 协议的云存储服务商(如 AWS S3、Cloudflare R2 或 MinIO)。
- **媒体批注与画笔**:提供精准到帧的评论工具与画笔标注,可直接在视频画面或图像上绘制草图,大幅加快审阅迭代周期。
- **版本控制**:支持将同一文件的多个历史版本折叠至单条资产记录(版本堆栈)中,保持工作区井然有序,并可随时追踪修改历史。
- **AI 智能标签与搜索**:借助 Google Gemini 在上传时自动为文件生成标签,并支持根据视觉特征或概念语义精准检索资产。
- **自定义自动化**:支持编写定制脚本构建专属后台工作流,自动化处理团队日常重复性操作。
- **代理转码**:在后台自动将大容量摄影机原片与设计文件转换为适合 Web 端流畅播放的流媒体格式。
---
## 部署规模
根据团队规模与制作吞吐量,Shumai 支持以下两种运行模式:
### 1. 单机部署(默认)
适用于小型团队、本地开发或轻量级工作流。该模式下,Web 主服务、数据库以及后台任务(如媒体转码与 AI 标签生成)均运行在单台主机上。
### 2. 大规模分布式部署
推荐用于视频上传量巨大的生产环境。该模式下,后台任务通过持久化队列管理(基于 PostgreSQL 由 DBOS 统一编排调度)。重度负载可轻松分流至专用工作节点(例如将视频转码任务交由配备高规格 CPU/GPU 的机器执行,将 AI 智能体置于独立的沙箱环境中运行)。
_注意:分布式部署需要使用兼容 S3 的云存储,以确保所有工作节点均能正常访问上传的文件。_
+218
View File
@@ -0,0 +1,218 @@
---
title: 快速入门
description: 了解如何通过 Docker、NPM 或源码快速部署并运行 Shumai。
---
Shumai 提供三种安装方式。对于大多数管理员,推荐使用 **Docker Compose**,这是部署 Shumai 最便捷迅速的方式。
---
## 方案一:Docker Compose(推荐)
使用 Docker Compose 是运行 Shumai 最快捷的方式。无需克隆仓库或手动安装依赖包。请确保已安装 [Docker](https://docs.docker.com/get-docker/) 与 [Docker Compose](https://docs.docker.com/compose/install/),随后执行以下步骤:
1. **创建工作目录**:
为配置文件与数据卷创建并进入新的目录:
```bash
mkdir shumai && cd shumai
```
2. **下载配置文件**:
根据实际需求与可用内存(RAM)选择并下载对应的 `docker-compose.yaml` 配置文件:
- **精简版(建议内存 2 GB+)**:轻量级部署方案,仅包含 Shumai 主服务与 PostgreSQL 数据库。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
```
- **含向量模型服务版(建议内存 4 GB+)**:引入基于 `shumaiOne/embedding-server`(`EmbeddingGemma 2 740M`)的本地多模态语义搜索能力。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.embedding.yaml
```
- **完整版(建议内存 8 GB+)**:全功能一体化配置,包含 `embedding-server`、`turntable-renderer`(3D 预览渲染)以及 `Gotenberg`(文档 PDF 预览代理)。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.full.yaml
```
> [!NOTE]
> Docker Compose 默认采用 CPU 软解转码。如果服务器配备了 GPU(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API 或 Rockchip RKMPP)并希望启用 GPU 硬件加速,请参阅[硬件转码指南](/zh/configuration/hardware-transcoding)。
3. **配置环境变量**:
打开 `docker-compose.yaml`,根据部署环境调整环境变量:
- `BETTER_AUTH_URL`:Shumai 服务器的公开访问基准 URL(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`)。主要用于:
- **密码重置链接**:生成 CLI 及用户的密码重置 URL(`{BETTER_AUTH_URL}/reset-password?token=...`)。
- **邮件通知深度链接**:通知邮件中的默认基准跳转 URL(当未设置 `APP_URL` 时生效)。
- **会话 Cookie 安全策略**:在 HTTPS 部署环境下决定是否为会话 Cookie 附加 `Secure` 标记及 `__Secure-` 前缀。
- **MCP OAuth 2.1 与服务发现**:设置 OAuth 资源标识符(`{BETTER_AUTH_URL}/mcp`)、服务发现端点(`/.well-known/...`)以及出站 MCP OAuth 的默认重定向 URI。
> [!NOTE]
> 即使未配置 `BETTER_AUTH_URL`,**邮箱/密码方式的 Web UI 登录**仍可在纯 HTTP/IP 环境下正常工作。但在生产环境、自定义域名或 HTTPS 部署中,强烈建议显式配置该变量。请注意,根据 RFC 9728 规范,远程部署使用 MCP OAuth 2.1 时必须启用 HTTPS;若使用 HTTP IP 地址或域名,MCP OAuth 2.1 将优雅降级禁用,但 Web UI 及 MCP API Token 仍可正常使用。
- `BETTER_AUTH_SECRET`:用于对会话 Cookie、JWT 以及预签名文件上传/下载 URL(本地存储模式下)进行签名的随机密钥。模板中已包含一个用于本地临时体验的默认占位符,但在**生产环境或公开网络部署中,必须生成独立的密钥**(例如执行 `openssl rand -base64 32` 生成)。
- `AWS_ENDPOINT_URL_S3`:默认配置为 `http://localhost:{SHUMAI_SERVER_PORT}`。当使用本地存储(`STORAGE_BACKEND: local` 默认模式)并将 Shumai 部署在远程服务器、自定义域名或非默认端口时,请将 `AWS_ENDPOINT_URL_S3` 设置为客户端浏览器用于上传和下载文件的外部访问 URL。
例如,若将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为 `12345:3000`,且部署服务器 IP 地址为 `12.34.56.78`,则应配置为:
```yaml
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
```
该地址必须能从客户端浏览器直接访问,并包含对外暴露的端口号。
- `SHUMAI_SERVER_PORT`:控制 Shumai 服务监听的端口,默认为 `3000`。
- **外部 S3 存储**:在此 Docker Compose 配置中,Shumai 默认使用内置的本地存储服务。若需改用外部兼容 S3 的存储,请配置对应的 S3 环境变量。以下为 AWS S3 与 Cloudflare R2 的配置示例:
**AWS S3 示例:**
```yaml
STORAGE_BACKEND: s3
S3_BUCKET: your-bucket-name
S3_ACCESS_KEY_ID: your-access-key-id
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.com
```
**Cloudflare R2 示例:**
```yaml
STORAGE_BACKEND: s3
S3_BUCKET: your-bucket-name
S3_REGION: auto
S3_ACCESS_KEY_ID: your-access-key-id
S3_SECRET_ACCESS_KEY: your-secret-access-key
AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
```
4. **启动服务**:
```bash
docker compose up -d
```
5. **访问控制台**:
打开浏览器并访问 **`http://localhost:3000`**(若为远程部署则访问 `http://<服务器-IP>:3000`),即可进入 Shumai Web UI。
### 生产环境部署(分布式工作节点)
如果团队视频上传量较大,建议采用基于独立工作节点与兼容 S3 存储后端的分布式部署方案。该方案可将高消耗的视频转码与 AI 智能体任务分流至专用的工作节点,确保主控制台始终保持敏捷流畅。详细配置步骤请参阅[分布式工作节点部署](/zh/configuration/distributed)指南。
---
## 方案二:通过 NPM 安装
可通过 Node 包管理器(NPM)将 Shumai 作为全局服务运行。
### 系统前置依赖
为支持媒体处理与安全隔离能力,宿主机系统必须安装以下系统工具:
- **FFmpeg 与 FFprobe**:视频转码与元数据提取所必需。
- _macOS_:`brew install ffmpeg`
- _Linux (Ubuntu/Debian)_:`sudo apt-get install ffmpeg`
- **dcraw_emu (LibRaw)**:相机 RAW 格式图片解码与预览生成所必需。
- _macOS_:`brew install libraw`
- _Linux (Ubuntu/Debian)_:`sudo apt-get install libraw-bin`
- **智能体沙箱工具**:用于安全隔离并执行自定义自动化脚本。
- _macOS_:`brew install ripgrep`
- _Linux (Ubuntu/Debian)_:`sudo apt-get install bubblewrap socat ripgrep`
### 详细安装步骤
1. **启动数据库**:
Shumai 需要搭载 `pgvector` 扩展的 PostgreSQL 数据库。启动数据库容器:
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d pgvector/pgvector:pg18
```
2. **安装 Shumai**:
```bash
npm install -g @shumai-one/shumai
```
3. **配置环境变量**:
创建新目录并进入,随后创建 `.env` 文件:
```bash
mkdir shumai && cd shumai
```
创建包含以下变量的 `.env` 文件:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=your-random-32-character-secret-key
BETTER_AUTH_URL=http://localhost:3000
STORAGE_BACKEND=local
AWS_ENDPOINT_URL_S3=http://localhost:3000
```
> [!TIP]
> 远程或生产环境部署时,应将 `BETTER_AUTH_URL` 设置为服务器的公网地址。`AWS_ENDPOINT_URL_S3` 则必须包含对外访问的协议协议头与端口(例如 `http://localhost:3000` 或 `http://12.34.56.78:3000`),客户端浏览器将直接使用该地址上传文件。
4. **启动 Shumai**:
> [!IMPORTANT]
> **Bun 用户请注意:** 发布的 npm 包二进制文件包含 `#!/usr/bin/env node` Shebang,因此直接执行 `shumai` 将由 Node.js 运行。若使用 Bun 安装并希望在 Bun 运行时环境下运行,请在命令前添加 `bun run --bun`(例如 `bun run --bun shumai`)。
```bash
shumai
```
在浏览器中打开 `http://localhost:3000` 即可。
---
## 方案三:源码运行(适合开发者)
若要在本地搭建 Shumai 开发环境:
1. **克隆仓库并安装依赖**:
```bash
git clone https://github.com/shumaiOne/shumai.git
cd shumai
bun install
```
2. **启动数据库**:
启动本地数据库容器(同上述 NPM 部署步骤):
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d pgvector/pgvector:pg18
```
3. **创建环境配置文件**:
在工作区根目录下创建 `.env` 文件:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL=http://localhost:3000
STORAGE_BACKEND=local
SHUMAI_SERVER_PORT=3000
AWS_ENDPOINT_URL_S3=http://localhost:3000
```
4. **编译国际化(i18n)语言包**:
```bash
bun run i18n:compile
```
> [!TIP]
> 在前端开发过程中,可在独立终端窗口运行 `bun run i18n:watch`。当修改 `packages/webui/messages/` 中的文案时,系统会自动重新编译语言包。
5. **执行数据库迁移**:
应用数据库架构迁移:
```bash
bun run db:migrate
```
6. **启动开发服务器**:
```bash
bun run dev
```
命令执行后将在 `3000` 端口启动 Web 服务,并已开启热重载(Hot-Reloading)。
+126
View File
@@ -0,0 +1,126 @@
---
title: 兼容 S3 的对象存储
description: 为 Shumai 配置 AWS S3 或任意兼容 S3 协议的对象存储服务(Cloudflare R2、MinIO、Google Cloud Storage 等)。
---
Shumai 采用 Bun 原生高性能 S3 客户端存储与分发创意资产。借助标准化 S3 API,Shumai 能够无缝对接任意兼容 S3 协议的存储提供商,包括 AWS S3、Cloudflare R2、MinIO、Google Cloud Storage 等。
生产团队强烈建议配置独立的外部 S3 存储。这样既能将存储与应用服务解耦、支持独立弹性扩容,也可为分布式媒体转码提供共享存储支持。
---
## 配置变量
若要启用兼容 S3 的存储,请在 `.env` 文件或 Docker Compose 配置中更新以下环境变量:
| 变量名 | 说明 | 必填 | 默认值 / 示例 |
| :-------------------------------- | :------------------------------------------------------------------------------------------ | :--- | :----------------------------------- |
| `STORAGE_BACKEND` | 设为 `s3` 以启用兼容 S3 的存储后端。 | 是 | `s3` |
| `S3_BUCKET` | 存放文件的 S3 存储桶名称。 | 是 | `shumai-bucket` |
| `S3_REGION` | S3 存储桶所在地域(Region)。 | 否 | `auto` |
| `S3_ACCESS_KEY_ID` | 存储服务的访问密钥 ID(Access Key ID)。 | 是 | `your-access-key-id` |
| `S3_SECRET_ACCESS_KEY` | 存储服务的私有访问密钥(Secret Access Key)。 | 是 | `your-secret-access-key` |
| `AWS_ENDPOINT_URL_S3` | 兼容 S3 的存储服务端点 URL。 | 是 | `https://s3.us-east-1.amazonaws.com` |
| `PRESIGNED_URL_EXPIRES_IN` | 生成的预签名下载链接有效期(单位:小时)。 | 否 | `5` |
| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | 生成的预签名上传链接有效期(单位:小时)。若未指定,则回退继承 `PRESIGNED_URL_EXPIRES_IN`。 | 否 | `12` |
---
## 存储服务商配置示例
以下是主流 S3 存储服务商的配置模板。可将这些变量添加至 `.env` 文件,或置于 `docker-compose.yaml` 的 `environment` 配置项中。
### AWS S3
使用标准 AWS S3 时,配置对应的服务区域端点 URL:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-shumai-bucket
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
```
### Cloudflare R2
Cloudflare R2 需要配合 Cloudflare Account ID 拼接端点 URL,并将地域设置为 `auto`:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-shumai-bucket
S3_ACCESS_KEY_ID=your-r2-access-key-id
S3_SECRET_ACCESS_KEY=your-r2-secret-access-key
AWS_ENDPOINT_URL_S3=https://<account-id>.r2.cloudflarestorage.com
```
### MinIO(自托管)
针对本地开发或自托管 MinIO 环境,将端点指向 MinIO 服务地址与端口(通常为 `9000`):
```env
STORAGE_BACKEND=s3
S3_BUCKET=shumai
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
AWS_ENDPOINT_URL_S3=http://localhost:9000
```
### Google Cloud Storage (GCS)
Google Cloud Storage 提供了兼容 S3 协议的 XML API。配置 HMAC 凭据并将端点设为标准 GCS 存储域名:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-gcs-bucket
S3_ACCESS_KEY_ID=GOOG1EXAMPLETOCKENKEY
S3_SECRET_ACCESS_KEY=your-gcs-hmac-secret-access-key
AWS_ENDPOINT_URL_S3=https://storage.googleapis.com
```
### DigitalOcean Spaces
使用 DigitalOcean Spaces 时,请将端点 URL 设置为空间对应的地域:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-spaces-bucket
S3_ACCESS_KEY_ID=your-spaces-access-key-id
S3_SECRET_ACCESS_KEY=your-spaces-secret-access-key
AWS_ENDPOINT_URL_S3=https://nyc3.digitaloceanspaces.com
```
### Supabase Storage
若要通过 S3 协议连接 Supabase Storage,请确保已在 Supabase 控制台中开启 S3 连接支持(`Settings > Storage > Enable connection via S3 protocol`)。从该设置页面复制对应的端点 URL 与地域信息:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-supabase-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-supabase-access-key-id
S3_SECRET_ACCESS_KEY=your-supabase-secret-access-key
AWS_ENDPOINT_URL_S3=https://<account-id>.supabase.co/storage/v1/s3
```
---
## 跨域资源共享(CORS)配置
由于 Shumai 通过预签名 URL 直接从用户浏览器上传文件至存储桶,因此必须在存储桶上配置**跨域资源共享(CORS)**。若未配置 CORS,文件上传将因跨域安全限制导致网络错误或源错误(Origin Error)。
请确保存储桶的 CORS 策略允许来自 Shumai 应用 URL(例如 `http://localhost:3000` 或 `https://app.shumai.one`)的请求:
### CORS JSON 策略示例(AWS S3、R2、GCS)
```json
[
{
"AllowedHeaders": ["*"],
"AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
"AllowedOrigins": ["http://localhost:3000", "https://your-shumai-domain.com"],
"ExposeHeaders": ["ETag"],
"MaxAgeSeconds": 3000
}
]
```
+153
View File
@@ -0,0 +1,153 @@
---
title: 基于 Turntable Renderer 的 3D 资产支持
description: 使用 turntable-renderer 渲染交互式 3D 模型转盘预览、雪碧图快擦预览与视频代理。
---
3D 模型与网格资产在各类浏览器和移动设备上往往难以实现一致的渲染效果与可靠的检查体验。Shumai 集成了 [turntable-renderer](https://github.com/shumaiOne/turntable-renderer) 独立服务——该服务通过隔离的无头 Blender 5.2 LTS 子进程,将上传的 3D 模型转换为标准化、高保真的转盘(Turntable)预览。
Turntable Renderer 会自动生成:
- **1080×1080 转盘视频(`turntable.mp4`)**:时长 4 秒、共 24 帧、6 fps 的视频,在纯黑背景与暗调摄影棚布光下顺时针 360°(每帧 15°)旋转展示模型。
- **海报缩略图(`poster.webp`)**:清晰的高清静态封面海报,用于网格卡片展示与文件即时呈现。
- **悬停预览雪碧图(`sprite.webp`)**:快速擦动(Scrubbing)雪碧图,支持在文件列表中悬停鼠标直接旋转预览并检查模型。
- **交互式 3D 播放器**:专用的 Web 检视器,提供 360° 标尺擦动、旋转角度微调(0° 至 345°)、播放控制,并支持针对特定角度添加评审评论与视觉批注。
---
## 支持的文件类型
配置 turntable-renderer 后,Shumai 会自动为以下格式生成 3D 转盘代理:
| 格式 / 标准 | 扩展名 |
| :-------------------------------- | :-------------------------------- |
| 二进制 glTF | `.glb` |
| Universal Scene Description (USD) | `.usd`, `.usda`, `.usdc`, `.usdz` |
| Autodesk FBX | `.fbx` |
| Wavefront OBJ | `.obj` |
| 实体光刻 (STL) | `.stl` |
| COLLADA | `.dae` |
---
## 配置说明
Shumai 支持通过 **Web 界面**或**环境变量**配置 Turntable Renderer。
### 1. Web 界面配置(团队设置 → 集成)
团队所有者可直接在 Web 界面中配置 Turntable Renderer:
1. 在侧边栏导航至**团队设置**。
2. 切换至**集成**选项卡。
3. 在 **3D Turntable Renderer** 下,输入**服务器地址(Server URL)**(例如 `http://turntable-renderer:3000` 或 `http://localhost:3003`)。
4. 若服务启用了 Basic 基础认证,请输入**用户名**与**密码**。
5. 点击**测试连接**,验证 Shumai 与渲染服务的通信状态并检查检测到的 Blender 版本。
6. 点击**保存更改**。
### 2. 环境变量配置
也可以在运行 Shumai 或转码 Worker 的机器上通过环境变量进行全局配置:
| 变量 | 必填 | 说明 |
| :--------------------------------------- | :--------------- | :----------------------------------------------------------------------- |
| `TURNTABLE_RENDERER_URL` | 是(启用时必填) | Turntable Renderer 基础服务地址,例如 `http://turntable-renderer:3000`。 |
| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | 否 | 开启 Basic 基础认证时的用户名(别名:`TURNTABLE_RENDERER_USERNAME`)。 |
| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | 否 | 开启 Basic 基础认证时的密码(别名:`TURNTABLE_RENDERER_PASSWORD`)。 |
### 配置优先级与只读模式
> [!IMPORTANT]
> **环境变量优先级最高。** 一旦在运行环境中配置了 `TURNTABLE_RENDERER_URL`,Shumai 将始终优先采用环境变量中的配置。
>
> 通过环境变量配置后,**团队设置 → 集成**中的对应设置项将显示**已通过环境变量配置(只读)**徽标,且输入框将被锁定,防止误操作或配置不一致。
---
## 部署 Turntable Renderer
### Docker 快速上手
运行 turntable-renderer 最便捷的方式是使用官方预构建的 Docker 镜像:
```bash
docker run -d --rm \
--name turntable-renderer \
-p 3003:3000 \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
shumaione/turntable-renderer:latest
```
> **说明**:宿主机端口 `3003` 映射至容器内部端口 `3000`。
### Docker Compose 配置
在 `docker-compose.yaml` 中添加 `turntable-renderer` 服务:
```yaml
services:
turntable-renderer:
image: shumaione/turntable-renderer:latest
restart: unless-stopped
ports:
- '3003:3000'
environment:
TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME: admin
TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD: your_password
```
随后在 Shumai 中配置指向该服务:
```bash
TURNTABLE_RENDERER_URL=http://localhost:3003
TURNTABLE_RENDERER_BASIC_AUTH_USERNAME=admin
TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD=your_password
```
_(若 Shumai 与 turntable-renderer 运行在同一个 Docker Compose 网络中,服务地址请填 `http://turntable-renderer:3000`)。_
### GPU 硬件加速
独立 GPU 为可选配置——turntable-renderer 的 CPU 渲染流水线在普通硬件配置下已具备足够快的处理速度。当向容器传入 GPU 资源时,系统会自动检测并启用硬件加速。
#### Intel / AMD(开源驱动)
透传 DRI 渲染节点设备:
```bash
docker run -d --rm \
--name turntable-renderer \
--shm-size=1gb \
-p 3003:3000 \
--device /dev/dri \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
shumaione/turntable-renderer:latest
```
#### NVIDIA(专有闭源驱动)
宿主机需安装 580+ 版本显卡驱动及 NVIDIA Container Toolkit(`--runtime nvidia`):
```bash
docker run -d --rm \
--name turntable-renderer \
--shm-size=1gb \
-p 3003:3000 \
--runtime nvidia \
--gpus all \
--device /dev/nvidia-modeset \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \
-e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \
shumaione/turntable-renderer:latest
```
---
## 未配置 Turntable Renderer 时的系统行为
若未配置 turntable-renderer 或服务无法连通:
- 上传的 3D 模型仍可正常处理完成,状态标记为 `processed`。
- 不会生成转盘视频代理、雪碧图与海报缩略图。
- 原始 3D 文件安全完整保存,团队成员可正常下载原文件。
+49
View File
@@ -0,0 +1,49 @@
---
title: AI 模型服务商
description: 将 Shumai 连接至 OpenAI、Anthropic、Gemini 或自定义 LLM 网关。
---
创建用于对话或元数据自动填充的智能体时,需要选择底层的 AI 模型。可用模型与服务商在团队设置中集中统一配置。
> 🔒 **权限说明:** 仅**团队所有者(Team Owner)**拥有管理 AI 模型服务商的权限。若需调整配置,请点击头像进入**设置**,并在左侧导航栏中选择**服务商(Providers)**。
---
## 内置模型服务商
Shumai 预置了主流 LLM 服务商的配置。由于 Shumai 采用 [Pi](https://github.com/earendil-works/pi) 作为底层核心智能体框架,系统支持的服务商与模型配置会自动与 Pi 的功能生态保持同步。
团队所有者可自由编辑、删除或添加新服务商。所有已配置的服务商与模型参数均会在运行时直接注入 Pi 框架。
---
## 配置参考
### 服务商配置项
配置服务商时需指定以下字段:
| 字段 | 说明 | 示例 / 备注 |
| :------------------------------ | :----------------------------------- | :-------------------------------------------------------------------------------------------- |
| **服务商名称(Provider Name)** | 唯一且易于辨识的服务商标识。 | `Ollama-Local`、`Enterprise-Gateway` |
| **基础 URL(Base URL)** | 目标 API 端点地址。 | `http://localhost:11434/v1` |
| **API 协议(API Protocol)** | 流式传输与请求载荷协议格式。 | 大多数兼容 OpenAI 的网关使用 `openai-completions`。 |
| **API 密钥(API Key)** | 身份认证令牌。本地无鉴权环境可留空。 | 支持直接填入密钥明文(`sk-...`),或指定宿主机环境变量名称(如 `MY_API_KEY`)以安全读取凭据。 |
### 模型配置项
每个服务商下均可挂载多个模型。每个模型支持配置以下属性:
| 字段 | 说明 | 示例 / 备注 |
| :-------------------------------------- | :---------------------------------------------------- | :------------------------------------- |
| **模型 ID(Model ID)** | 上游 API 所要求的精确模型标识符。 | `gpt-4o`、`claude-3-5-sonnet-20240620` |
| **显示名称(Display Name)** | 下拉菜单中面向用户展示的自定义友好名称(可选)。 | `GPT-4 Omni`、`Claude 3.5` |
| **深度推理支持(Reasoning Support)** | 开关选项,用于启用深度思考(Extended Thinking)协议。 | 适用于具备原生推理能力的模型。 |
| **上下文窗口(Context Window)** | 模型支持的最大 Token 总容量(输入 + 输出)。 | |
| **最大输出 Token(Max Output Tokens)** | 单次请求生成回复的 Token 上限。 | |
| **输入成本(Input Cost)** | 每百万输入 Token 的单价。 | 可选,用于统计使用开销与用量指标。 |
| **输出成本(Output Cost)** | 每百万输出 Token 的单价。 | 可选,用于统计使用开销与用量指标。 |
---
![AI 服务商列表](/providers.webp)
+45
View File
@@ -0,0 +1,45 @@
---
title: 智能体沙箱
description: AI 智能体脚本的安全执行环境与网络域名限制规范。
---
运行自动化脚本存在潜在的安全风险。Shumai 通过在安全且隔离的**沙箱(Sandbox)**环境中执行所有智能体技能来化解这一隐患。
---
## 沙箱安全机制
沙箱严格限制执行进程访问宿主机文件系统、系统进程及内部网络:
- **环境隔离**:脚本在虚拟化的工作区容器中运行,无法篡改系统核心文件或读取其他项目数据。
- **网络桥接管控**:来自沙箱内部的外部网络请求会受到严格监控。
### 文件系统访问限制
为保障工作区环境与敏感数据安全,沙箱实施了严密的文件级访问控制策略:
- **读取权限**:沙箱允许读取工作区内的普通文件,但严格禁止访问敏感环境配置与证书密钥文件。禁止读取的文件模式包括:`['.env', '.env.*', '*.pem', '*.key']`。
- **写入权限**:沙箱的写入权限受到极为严苛的限制,仅允许写入当前工作目录(cwd)下的 `.pi` 文件夹。即便在该受信任的目录内部,沙箱也严禁写入或创建匹配以下模式的敏感文件:`['.env', '.env.*', '*.pem', '*.key']`。
---
## 域名白名单
默认情况下,网络沙箱处于**关闭**状态(允许所有出站网络请求)。团队所有者可在沙箱设置中开启网络沙箱,以强制推行严格的域名白名单管控:
### 允许的域名 (Allowed Domains)
允许沙箱内脚本正常访问的域名清单。
- 默认白名单包含标准软件包注册表(如 npm、Python 官方源等)以及代码托管平台(如 `github.com`)。
- 若脚本需要调用外部 API(如 `api.slack.com`),管理员须预先将其添加至白名单中。
### 待审批域名 (Pending Domains)
当智能体脚本尝试访问未经授权的域名时:
1. 网络连接将被即刻拦截。
2. 系统会记录目标域名并将其加入**待审批域名**列表。
3. 管理员可审阅该列表,点击**批准**将其加白,或点击**拒绝**保持拦截。
![智能体沙箱设置](/sandbox.webp)
+54
View File
@@ -0,0 +1,54 @@
---
title: 智能体技能
description: 通过自定义自动化工具扩展智能体能力。
---
原生 AI 模型通常仅具备文本与图像处理能力。在 Shumai 中,可通过注册**技能(Skills)**为**对话智能体**与**自动填充智能体**扩展能力边界——技能即智能体在执行任务时可调用的自定义脚本。
---
## 技能运作机制
技能由用户自行定义,并授权给 AI 智能体使用。
- **面向 AI 的元数据描述**:注册技能后,AI 智能体会读取其元数据描述,理解在何种场景下、以何种方式调用该工具来解决具体问题。
- **执行与本地缓存**:当智能体决定调用某项技能时,Shumai 会负责调度执行。新添加的技能数据首先同步至数据库;执行时,智能体会从数据库下载并在本地缓存技能文件,确保高效稳定的访问速度。
---
## 添加技能
向 Shumai 安装新技能的步骤如下:
1. 前往**设置**页面并切换至**技能(Skills)**标签页。
2. 点击**添加技能**按钮。
3. 在弹出的对话框中选择安装方式:
- **本地上传**:选择并上传包含技能文件的 `.zip` 压缩包。
- **GitHub 导入**:填入合法的 GitHub 仓库路径。
> **重要提示:** 无论采用哪种安装方式,技能包根目录下必须包含 `SKILL.md` 文件。
### 更新现有技能
若需更新技能,只需按上述步骤重新安装新版本,并保持技能名称完全一致,Shumai 便会自动覆盖旧版本。
---
## 配置环境变量
若自定义技能依赖环境变量(如 API 密钥、外部 Token)才能运行:
1. 在技能列表中点击已安装的**技能卡片**打开配置弹窗。
2. 添加所需的环境变量。
3. _(可选)_ 为环境变量设定默认值。若未指定默认值,技能将在运行时动态读取宿主机系统环境变量。
---
## 为智能体启用技能
**所有技能默认均处于禁用状态。** 仅安装技能并不会赋予智能体调用权限。若需授权智能体调用已安装的技能:
1. 前往对应的**智能体设置**。
2. 勾选希望授权给该智能体的技能。
![技能列表视图](/skills.webp)
+164
View File
@@ -0,0 +1,164 @@
---
title: 智能体工具
description: 为各智能体配置允许调用的工具与能力。
---
Shumai 智能体配备了丰富的内置工具,支持直接操作文件系统、查看文件、提取视频帧以及执行终端命令。
默认情况下,新建智能体已开启绝大多数常用工具;而高危或破坏性工具(如**删除资产**)则默认禁用。团队所有者可按需开启或关闭特定工具,精准收敛智能体的操作权限。
<Warning>
**注意:**
禁用工具可能导致智能体或某些技能执行失败。例如,若禁用**沙箱终端**工具,几乎所有依赖命令行或脚本环境的自定义技能都将无法运行。除非团队有明确的安全策略或权限隔离要求,否则建议保持默认开启。
</Warning>
---
## 可用工具清单
可在智能体配置弹窗中单独启闭以下工具:
### 1. 沙箱终端 (`bash`)
- **说明:** 允许智能体在高度隔离的环境中执行终端与 Shell 命令。
- **重要性:** 运行自定义脚本、处理磁盘文件或调用标准 Unix 工具的核心基础。若禁用此工具,智能体将无法执行命令行代码。
### 2. 读取技能 (`read_skill`)
- **说明:** 允许智能体加载并读取技能定义,以执行专属任务。
- **重要性:** 使智能体在执行前能够审阅工作区中注册的自定义技能指令与配置。
### 3. 读取资产 (`read_asset`)
- **说明:** 允许智能体检视图片、提取视频逐帧画面、渲染 PDF 文档页面以及读取文本/Markdown 文档内容。
- **重要性:** 赋予多模态智能体查看 Shumai 中上传素材的能力,支持按帧提取视频截图、检视文档排版,并就上传的创意资产解答疑问。
- **限制:** 单次调用最多获取 20 个视频帧或 PDF 页面。若渲染耗时超过约 1 分钟,工具会告知智能体渲染仍在处理中,而非直接报错中断。
### 4. 获取资产渲染结果 (`get_asset_render`)
- **说明:** 允许智能体获取此前调用 `read_asset` 时仍在后台渲染的视频帧或文档页面。
- **重要性:** 长视频与大体积文档渲染通常需要一定时间。借助此工具,智能体可在渲染完成后回溯获取结果,无需重头开始。该工具仅返回同一用户此前通过 `read_asset` 发起的渲染任务。
### 5. 浏览资产 (`list_assets`)
- **说明:** 允许智能体列出 Shumai 中的文件夹并浏览文件。大型文件夹支持分页返回。
- **重要性:** 为智能体呈现项目结构全貌,便于检索其他文件或定位相关资产。
### 6. 列出项目 (`list_projects`)
- **说明:** 允许智能体列出当前用户在各团队中有权访问的项目,包含每个项目的根文件夹信息。
- **重要性:** 便于智能体在浏览或创建文件前,自主查找目标项目及其根目录。
### 7. 创建文件夹 (`create_folder`)
- **说明:** 允许智能体在 Shumai 中新建文件夹。
- **重要性:** 当智能体需要整理产出内容或在自定义子目录中归档文件时不可或缺。
### 8. 创建文件 (`create_file`)
- **说明:** 允许智能体在 Shumai 中创建并上传新文件。
- **重要性:** 支持智能体生成新资产(如文本日志、转码片段、分析报告等)并直接回存至项目中。
### 9. 创建版本 (`create_version`)
- **说明:** 允许智能体上传新版本并将其堆叠至 Shumai 中已有的文件上。
- **重要性:** 支持智能体以无损方式迭代文件,通过追加版本堆栈而非生成同名重复文件来保留历史记录。
### 10. 生成图像 (`generate_image`)
- **说明:** 允许智能体借助已配置的 AI 图像模型,基于文本提示词与参考图生成静态图片。
- **重要性:** 支持智能体在 Shumai 中直接创作概念图、设计效果图、纹理贴图及插画素材。
- **前置条件:** 必须在[图像与视频生成](/zh/using-shumai/image-video-generation)中至少配置并启用一个图像模型。若已配置的服务商下未启用任何图像模型,即便在智能体设置中开启了该工具,会话中也会自动隐藏该工具。
### 11. 生成视频 (`generate_video`)
- **说明:** 允许智能体借助已配置的 AI 视频模型,基于文本提示词、静态图片动画化或关键帧过渡生成视频片段。
- **重要性:** 支持智能体生成简短动态动画、运镜镜头及视频转场。
- **前置条件:** 必须在[图像与视频生成](/zh/using-shumai/image-video-generation)中至少配置并启用一个视频模型。若已配置的服务商下未启用任何视频模型,即便在智能体设置中开启了该工具,会话中也会自动隐藏该工具。
### 12. 下载资产 (`download_asset`)
- **说明:** 允许智能体单次最多下载 50 个工作区文件,或下载特定的 S3 存储键(如来自 `read_asset` 的视频帧)至本地 `.pi` 目录,供本地脚本或 Shell 命令进一步处理。当存在网页预览版本时,默认下载预览版(例如转码代理视频或网页压缩图);智能体亦可明确请求下载原始上传文件。不支持直接下载文件夹。
- **重要性:** 便于执行自定义技能脚本的智能体将素材文件或转码中间产物拉取至本地磁盘。
### 13. 重命名资产 (`rename_asset`)
- **说明:** 允许智能体修改 Shumai 中已有文件或文件夹的名称。
- **重要性:** 支持智能体按照工作区的规范命名规则整理项目文件。默认开启。
### 14. 移动资产 (`move_assets`)
- **说明:** 允许智能体将一个或多个资产移动到目标父文件夹中。
- **重要性:** 支持智能体整理工作区目录层级、归档生成结果或重组项目文件夹。默认开启。
### 15. 删除资产 (`delete_asset`)
- **说明:** 允许智能体将单个文件或文件夹移入废纸篓。
- **重要性:** 赋予智能体清理陈旧或冗余资产的能力。为防止数据误删,该工具**默认处于禁用状态**,且严格限制每次只能删除单个资产。必须由团队所有者显式开启。
### 16. 搜索资产 (`search_assets`)
- **说明:** 允许智能体按名称、语义含义(当团队开启 AI 语义搜索时)或状态等元数据检索指定文件夹及其子目录。
- **重要性:** 便于智能体直接定位任务所需的目标文件,无需逐层遍历目录。
### 17. 复制资产 (`copy_assets`)
- **说明:** 允许智能体将文件或文件夹(连同内部所有内容)完整复制到同团队下的另一个文件夹中。
- **重要性:** 便于智能体在跨项目复用资产或创建工作副本时,保持原始文件不受改动。
### 18. 读取文件夹指令 (`get_folder_instructions`)
- **说明:** 允许智能体读取文件夹中针对 AI 智能体设置的专属指令文件(AGENTS.md)。
- **重要性:** 使智能体在向文件夹添加文件前,能够遵循团队预设的规范要求(如命名规则或交付物指标)。
### 19. 读取评论 (`list_comments`)
- **说明:** 允许智能体读取文件上的审阅评论与回复内容,包括时间码信息。
- **重要性:** 便于智能体根据审阅意见采取行动,例如汇总待处理问题或在新版本中落实修改建议。
### 20. 发表评论 (`create_comment`)
- **说明:** 允许智能体在文件上发表评论(可指定时间码)或回复已有评论。评论将以智能体所服务用户的身份发布,并在审计日志中明确记录系智能体生成。
- **重要性:** 支持智能体像真人团队成员一样参与审片协作。智能体在评论中提及其他成员或智能体时不会触发二次联动。
### 21. 解决评论 (`resolve_comment`)
- **说明:** 允许智能体将评论标记为已解决,或重新打开已解决的评论。
- **重要性:** 支持智能体在完成修改后及时闭环对应的反馈事项。
### 22. 列出元数据字段 (`list_metadata_fields`)
- **说明:** 允许智能体查看项目支持的元数据字段定义(如状态、评级及自定义字段)与其可选项。
- **重要性:** 告知智能体哪些字段支持检索或赋值。
### 23. 更新元数据 (`update_asset_metadata`)
- **说明:** 允许智能体修改文件的元数据属性,例如更新状态或标签。只读字段不可更改。
- **重要性:** 支持智能体实时维护文件的审阅状态及其他关键元数据属性。
### 24. 创建版本堆栈 (`create_version_stack`)
- **说明:** 允许智能体将同一文件夹下的多个散落文件整合为一个资产的各版本。
- **重要性:** 便于智能体将零散的文件版本(例如 `cut_v1.mp4` 与 `cut_v2.mp4`)整理归纳为单一版本化资产。
### 25. 列出版本历史 (`list_versions`)
- **说明:** 允许智能体按时间倒序(最新版本在前)列出版本堆栈中的所有历史版本。
- **重要性:** 便于智能体对比当前文件与历史版本之间的差异。
### 26. 移除版本 (`remove_version`)
- **说明:** 允许智能体从版本堆栈中剥离某个版本。该操作不会删除文件,而是将其还原为所在文件夹中的独立文件。
- **重要性:** 便于智能体纠正错误堆叠的版本。
---
## 配置工具权限
若需调整智能体可调用的工具:
1. 前往**团队设置** > **智能体**(注意:仅团队所有者有权查看和修改此项配置)。
2. 点击需要配置的目标智能体。
3. 向下滚动至**技能(Skills)**区域下方,即可看到**工具(Tools)**配置面板。
4. 切换各个工具旁边的开关以启用或禁用。
5. 点击**保存修改**。
+53
View File
@@ -0,0 +1,53 @@
---
title: AGENTS.md 上下文与指令
description: 为 AI 智能体提供层级化、针对特定文件夹的指令与上下文支持。
---
除全局智能体系统提示词与技能外,Shumai 还支持通过 **`AGENTS.md`** 为项目与文件夹定义层级化上下文指令。
当 AI 智能体(如对话智能体或自动填充智能体)在项目或文件夹中执行任务时,Shumai 会自动加载对应的 `AGENTS.md` 文件,为智能体注入上下文背景、操作规范与项目专属知识。
---
## 层级遍历与上下文继承
Shumai 对 `AGENTS.md` 采用层级化上下文继承机制:
- **向上回溯遍历**:当智能体处理某个文件或文件夹时,Shumai 会从当前目录沿目录树一路向上遍历,直至**项目根目录**。
- **合并注入上下文**:沿途检索到的所有 `AGENTS.md` 文件会按序(从项目根目录至当前子目录)加载至智能体的上下文窗口中。
- **规则分层沉淀**:可在项目根目录的 `AGENTS.md` 中约定通用的全局准则与规范,并在嵌套的各级子文件夹 `AGENTS.md` 中补充专属规则、术语词汇或自动填充指引。
---
## AGENTS.md 的典型编写内容
可以在 `AGENTS.md` 中编写希望智能体在当前项目或文件夹中遵循的各类指令:
- **项目与文件夹概览**:阐述当前文件夹存放的资产类型,以及该文件夹在整个项目结构中的定位与作用。
- **智能体行为准则**:明确智能体回答问题或发表评论时的安全红线、语气风格、排版格式要求,以及允许或禁止执行的操作。
- **行业术语与领域知识**:约定专业词汇、缩写、品牌规范名称或项目专属行话术语。
- **元数据与自动填充指引**:指导**自动填充智能体**如何针对本文件夹内的文件归纳摘要、生成标签或填充特定的自定义元数据字段。
---
## 查看与编辑 AGENTS.md
### 打开编辑器
若需查看或编辑 `AGENTS.md`:
1. 在 Shumai Web 应用中打开任意项目或文件夹。
2. 点击顶部导航工具栏中的 **`AGENTS.md`** 按钮,或在文件列表中右键点击任意文件夹并选择 **AGENTS.md**。
3. 系统将弹出专属的所见即所得 Markdown 编辑器,完整支持标题、列表、代码块、粗体/斜体以及链接等排版格式。
### 自动保存
在编辑器中修改内容时,Shumai 会在后台自动保存更改,并通过直观的状态指示器提示保存进度(`Saving...`、`Saved`)。
---
## 权限控制与只读模式
- **查看权限**:拥有项目只读及以上访问权限的所有团队成员均可查看 `AGENTS.md`。
- **编辑权限**:**仅团队所有者(Team Owner)**有权创建、编辑或删除 `AGENTS.md` 文件。
- **只读状态提示**:非团队所有者成员在工具栏中会看到明确的只读提示,告知只有团队所有者才能修改该文件的指令内容。
+51
View File
@@ -0,0 +1,51 @@
---
title: AI 智能体
description: 创建与配置专用于对话、元数据自动填充及向量索引生成的 AI 智能体。
---
Shumai 借助各类专属 AI 智能体执行后台自动化任务、对话交互工作流以及语义索引构建。**仅团队所有者(Team Owner)**拥有创建、管理和修改智能体配置的权限。
---
## 智能体类型
Shumai 支持以下三种类型的智能体:
### 1. 对话智能体 (Chat Agent)
活跃于项目工作区中的交互式对话助手。
- 支持按需创建任意数量的对话智能体。
- 支持在文件评论中直接使用 “@” 提及对话智能体。
- 具备上下文感知能力:能够读取文件内容、检索项目文件夹、检查元数据以及阅读评论会话。
- 支持为对话智能体挂载“技能”,使其能够代为写入文件、运行脚本或调用外部 API。
### 2. 自动填充智能体 (Autofill Agent)
负责监听文件上传的后台智能体。系统**仅允许创建 1 个**自动填充智能体。
- 创建并启用后,只要上传的文件类型符合要求(图片或视频),Shumai 便会自动触发该智能体。
- 它会深入分析文件内容(多模态图像特征、文字描述等),并自动填充所有开启了“AI 自动填充”标记的元数据字段。
### 3. 向量索引智能体 (Embedding Agent)
专用于处理资产并构建搜索索引的工具型智能体。系统**仅允许创建 1 个**向量索引智能体。
- 创建并启用后,若新上传的文件类型符合要求(图片或视频),Shumai 会自动生成向量嵌入(Embedding)。
- 生成的搜索索引将持久化保存,为 Shumai 的自然语言语义搜索功能提供底层支持。
- **注意:** 向量索引智能体底层固定采用 `google-embedding-2` 模型,因此不支持自定义服务商或模型。请确保已在服务端配置 `GEMINI_API_KEY` 环境变量以保证其正常运转。
- **切片时长(Chunk Duration):** 长视频索引时的视频切片时长可通过 `EMBEDDING_CHUNK_DURATION` 环境变量配置(默认值为 60 秒)。
---
## 配置智能体
若需新建或编辑智能体,请前往**团队设置** > **智能体**(注意:仅团队所有者有权修改这些配置):
- **头像(Avatar)**:在预设头像列表中为智能体挑选专属头像。
- **启用 / 禁用开关**:控制智能体的启停状态。若禁用向量索引智能体,语义搜索索引构建将被暂停。
- **系统提示词 / 人设(Soul)**:定义智能体行为准则、格式规范及操作边界的核心指令。
- **模型服务商(Model Provider)**:选择智能体运行所依托的已注册服务商与模型。_(注:向量索引智能体不开放此选项)_。
- **分配技能(Assigned Skills)**:勾选允许该智能体调用的自定义技能。
![智能体配置面板](/agents.webp)
+54
View File
@@ -0,0 +1,54 @@
---
title: 资产管理
description: 了解如何在工作区中上传、整理、删除与恢复媒体资产。
---
Shumai 支持便捷地将创意媒体素材导入工作区,按文件夹分类整理,并全流程管理从上传到删除的完整资产生命周期。
---
## 上传资产
可以通过以下三种方式将文件和文件夹上传至 Shumai:
1. **拖拽上传**:从电脑的文件管理器中直接拖拽文件或整个文件夹,释放到 Shumai 控制台界面的任意位置。
2. **按钮上传**:点击工具栏中的 **上传文件** 或 **上传文件夹** 按钮。
3. **复制粘贴**:从其他网站、应用程序或剪贴板复制图片或文件,直接在 Shumai 浏览器窗口中粘贴(`Ctrl+V` 或 `Cmd+V`)即可立即上传。
![资产管理 - 拖拽上传](/dragdrop.webp)
---
## 文件夹组织
上传整个文件夹时,Shumai 会在项目中完整保留并重建原始文件夹层级结构:
- 自动创建所有子文件夹。
- 嵌套文件保留在各自对应的子文件夹中。
- 支持任意深度的文件夹层级嵌套上传。
---
## 上传与处理状态
上传启动后,资产将历经以下几种状态:
- **上传中(Uploading)**:文件正在传输到存储服务器,界面实时显示传输进度百分比。
- **处理中(Processing)**:文件已成功上传。Shumai 正在提取媒体参数(如分辨率、视频时长和音频编解码器)并生成便于 Web 在线流畅播放的预览代理(Proxy)。
- **就绪(Ready)**:处理完毕。资产已完全可见、支持在线播放,并可随时添加评论、标记元数据或搜索。
---
## 删除与恢复资产
若某些资产不再需要,可以将其删除以整理工作区:
### 回收站(最近删除)
- 删除文件或文件夹后,相应资产将移至项目设置中的 **最近删除**(Recently Deleted)标签页。
- 已删除资产会在回收站中保留 **30 天**。在此期间,可选中任意资产并点击 **恢复**(Recover)将其还原至原始位置。
- 若需立即释放存储空间,可打开“最近删除”标签页并点击 **清空回收站**(Empty Trash)永久清除文件。
### 永久删除
在回收站保留 **30 天** 后,资产将自动永久清除。清除完成后,相关记录会从数据库中移除,文件也会从存储后端(本地文件系统或 S3 存储桶)彻底删除且无法恢复。
+55
View File
@@ -0,0 +1,55 @@
---
title: 收藏集
description: 基于元数据过滤规则与搜索条件构建动态虚拟视图。
---
无需将文件复制到静态文件夹中,Shumai 采用基于查询的动态虚拟视图——**收藏集**。收藏集能根据特定条件实时动态聚合匹配的文件。
---
## 什么是收藏集?
**收藏集**不会在磁盘上重复存储文件,而是针对项目的资产数据库执行预定义的过滤查询。每当上传新文件或更新元数据且匹配收藏集的查询条件时,该文件就会自动呈现于该收藏集中。
---
## 创建收藏集
支持通过以下两种方式创建收藏集:
- **侧边栏入口**:点击项目侧边栏中**收藏集**旁的 `+` 图标打开查询构建器,配置检索规则后保存。
- **搜索弹窗入口**:在搜索弹窗中检索和筛选文件时,点击弹窗底部的**保存为收藏集**按钮,即可将当前的搜索条件直接转换为动态收藏集。
---
## 配置收藏集过滤规则
创建或编辑收藏集时,需指定名称并在构建器中设置过滤查询:
### 1. 源文件夹
指定起始文件夹路径。收藏集将以递归方式扫描该文件夹及其所有下级子目录。
### 2. 运算符与条件
- **逻辑运算符**:使用 **AND**(满足所有条件)或 **OR**(满足任一条件)组合多个过滤规则。
- **字段范围**:支持标准基础字段(文件名、类型、大小)或自定义元数据字段(如“状态”或“审核结果”)。
- **匹配规则**:
- _等于 / 不等于_:精确匹配指定值。
- _包含 / 不包含_:模糊匹配文本子串。
- _大于 / 小于_:设置数值或日期范围(例如上传时间在昨天之后)。
- _为空 / 不为空_:检查字段是否存在取值。
### 3. 收藏集默认排序
为收藏集单独指定自定义排序规则(如按自定义字段“发布日期”升序排列),以覆盖项目的默认排序规则。
---
## 典型应用场景
- **审核工作台**:创建名为“待审核”的收藏集,筛选 `状态` 为 `审核中` 的资产。
- **每日交付物**:过滤最近 24 小时内上传的文件。
- **已批准资产**:筛选符合 `标签` 包含 `marketing` 且 `已批准` 为 `是` 的资产。
![创建收藏集](/collection.webp)

Some files were not shown because too many files have changed in this diff Show More