Compare commits

...
26 Commits
Author SHA1 Message Date
yiling d8c20d6a11 Release v0.7.0 2026-11-18 21:10:30 +08:00
yiling 8697481d43 update changelog 2026-11-18 20:21:57 +08:00
Yiling-J 4ac274cdd4 feat(runner): replace server-side bash sandbox with remote runner (#530)
* feat(runner): replace server-side bash sandbox with remote runner

* fix(runner): address review findings for output bounds, key rotation, defaults, and generated uploads

* chore(docker): remove sandbox privileges and env vars from remaining compose files

* feat(cli): add runner start with bundled SRT sandboxing (#535)

* refactor(agent): expose runner bash without skill gating

* feat(cli): add runner start with optional SRT sandboxing

* refactor(cli): remove runner Python dependency

* feat(cli): bundle SRT and use platform-native runner shells

* refactor(cli): delegate runner processes to Execa

* chore(cli): upgrade @anthropic-ai/sandbox-runtime to 0.0.83

* feat(cli): discover Bash for Windows runners

Use Pi-style Bash discovery and launch behavior, exercise the packaged CLI shell, and wait for pending ZIP metadata reads before closing cancelled downloads.

* fix(runner): enforce ownership and safe reconnects

Gate dispatch on reconciliation, retain cancellations across disconnects, and stop replaced clients. Guard the single-server runner topology with a database lease. Restage missing generated inputs, report signal exits, and bound generated-file cleanup.

* feat(webui): add Korean translations for agent runners

* feat(cli): add runner event logging and --verbose flag (#536)

* feat(cli): add runner event logging and --verbose flag

* fix(cli): log runner capacity rejections accurately and use monotonic duration
2026-11-18 15:58:57 +08:00
Yiling-J eea844320d fix(signup): separate login prompt from language selector (#534) 2026-11-17 10:17:10 +08:00
d255e76806 feat(i18n): add Korean locale (#531)
Add a Korean message catalog covering every key in the English catalog,
with placeholders matching English for each message. Register ko in the
inlang project, accept it as a sign-up and saved user locale, and offer it
in the sign-up language switch and the team settings language select.

Co-authored-by: phj1081 <5908832+phj1081@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-16 18:48:01 +08:00
yiling 2be1093b91 fix(cli): explain how to configure the installer PATH 2026-11-13 21:11:18 +08:00
yiling 83e902862c fix(cli): discover draft releases before publishing 2026-11-13 20:37:50 +08:00
yiling 0a66776067 Release v0.6.6 2026-11-13 20:01:51 +08:00
Yiling-J c55804a548 feat(operations): add create_project operation across agent, mcp, and cli (#529)
* feat(operations): add create_project operation across agent, mcp, and cli

* fix(api): remove legacy team creation endpoint

* fix(api): preserve ProjectInfo response on POST /teams/:teamId/projects
2026-11-13 11:43:08 +08:00
Yiling-J 97c2939b5e feat(cli): add standalone downloads and installers (#528)
* feat(cli): add standalone downloads and installers

* fix(cli): silence PowerShell download progress

* fix(cli): use framework APIs for Windows verification

* fix(cli): preserve null backup path during Windows updates

* docs(cli): translate native installation quickstart into Chinese
2026-11-12 19:37:33 +08:00
Yiling-J 0325435125 fix(storage): remove empty local embedding directories (#527) 2026-11-12 09:22:48 +08:00
Yiling-J 00fa5fed75 refactor(agent): share the SQLite session cache (#526) 2026-11-11 17:05:34 +08:00
Yiling-J 35a0e82284 refactor(agent)!: migrate to Pi Durable and embed the agent queue (#525)
* refactor(agent)!: migrate sessions to Pi Durable

Replace patched AgentHarness storage with per-session SQLite and PostgreSQL commit mirroring. Migrate legacy history automatically and run agent queues with the main server.

BREAKING CHANGE: Remove standalone agent workers and return native Pi entry records from chat history APIs.

* fix(agent): constrain session log dialog scrolling

Keep the header visible and wrap long output while log entries and expanded records scroll within the dialog. Cover desktop and narrow viewports through the dashboard Sessions flow.

* fix(agent): hide entry IDs from session log card headers

Retain internal entry IDs in expanded raw records for debugging. Verify that card headers omit the IDs while raw JSON preserves them.

* test(e2e): handle browser wheel limits in session log checks

Verify that a normal wheel event moves the viewport before explicitly scrolling to the final record. Keep the dialog bounds, fixed header, wrapping, and expanded-record assertions.

* fix(agent): select model providers without inheriting unrelated auth

* fix(webui): prevent resize feedback when toggling agent panel

* test(agent): reproduce concurrent comment session races

* fix(agent): serialize comment sessions and deduplicate history

* docs(changelog): consolidate Pi Durable changes into one entry
2026-11-11 16:05:18 +08:00
yiling 843a56304c docs: replace discord links with discourse forum 2026-11-09 10:56:30 +08:00
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
407 changed files with 39979 additions and 11425 deletions
-3
View File
@@ -53,9 +53,6 @@ jobs:
echo "Smoke testing shumai..."
bun run /tmp/shumai-local-release/node/node_modules/@shumai-one/shumai/bin/shumai-app.js --check
echo "Smoke testing shumai-agent..."
bun run /tmp/shumai-local-release/node/node_modules/@shumai-one/shumai-agent/bin/shumai-agent-app.js --check
echo "Smoke testing shumai-transcode..."
bun run /tmp/shumai-local-release/node/node_modules/@shumai-one/shumai-transcode/bin/shumai-transcode-app.js --check
+49
View File
@@ -0,0 +1,49 @@
name: Native CLI
on:
pull_request:
branches: [main]
push:
branches: [main]
workflow_call:
inputs:
source_ref:
required: true
type: string
permissions:
contents: read
jobs:
native:
name: CLI (${{ matrix.target }})
runs-on: ${{ matrix.runner }}
strategy:
fail-fast: false
matrix:
include:
- { target: linux-x64, runner: ubuntu-22.04 }
- { target: linux-arm64, runner: ubuntu-22.04-arm }
- { target: darwin-x64, runner: macos-15-intel }
- { target: darwin-arm64, runner: macos-15 }
- { target: windows-x64, runner: windows-2022 }
- { target: windows-arm64, runner: windows-11-arm }
steps:
- uses: actions/checkout@v4
with:
ref: ${{ inputs.source_ref || github.ref }}
- uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.4
- name: Install dependencies
run: bun install --frozen-lockfile --ignore-scripts
- name: Build CLI archive and installer
run: bun run build:cli --target ${{ matrix.target }}
- name: Test installed binary and file transfers
run: bun run test:cli-release
- uses: actions/upload-artifact@v4
with:
name: cli-${{ matrix.target }}
path: out/cli-release/shumai-cli-v*
if-no-files-found: error
retention-days: 7
+46 -16
View File
@@ -14,13 +14,30 @@ on:
description: 'Source ref to build/publish (defaults to tag)'
required: false
type: string
validate_only:
description: 'Build and test without publishing npm packages or a GitHub Release'
required: false
default: false
type: boolean
permissions: {}
concurrency:
group: npm-release-${{ github.event.inputs.tag || github.ref_name }}
cancel-in-progress: false
jobs:
cli:
uses: ./.github/workflows/cli-native.yaml
permissions:
contents: read
with:
source_ref: ${{ inputs.source_ref || inputs.tag || github.ref_name }}
release:
name: Build, Release and Publish
runs-on: ubuntu-latest
needs: cli
permissions:
contents: write
id-token: write
@@ -32,6 +49,7 @@ jobs:
uses: actions/checkout@v4
with:
ref: ${{ env.SOURCE_REF }}
fetch-depth: 0
- name: Setup Bun
uses: oven-sh/setup-bun@v2
@@ -53,12 +71,18 @@ jobs:
- name: Install dependencies
run: bun install
- name: Validate release source and version
run: bun scripts/publish-cli-release.ts ${{ inputs.validate_only && 'validate-only' || 'validate' }}
- name: Compile i18n
run: bun run i18n:compile
- name: Lint
run: bun run lint
- name: Format
run: bun run format && git diff --exit-code
- name: Typecheck
run: bun run typecheck
@@ -68,7 +92,18 @@ jobs:
- name: Build NPM packages
run: bun run build-npm
- name: Download tested CLI archives
uses: actions/download-artifact@v4
with:
pattern: cli-*
path: out/cli-release
merge-multiple: true
- name: Assemble CLI release assets
run: bun run build:cli --assemble
- name: Generate release notes
if: ${{ !inputs.validate_only }}
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
@@ -87,29 +122,24 @@ jobs:
fi
} > /tmp/release-notes.md
- name: Create GitHub Release
- name: Stage draft GitHub Release and CLI assets
if: ${{ !inputs.validate_only }}
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
if [ ! -s /tmp/release-notes.md ]; then
NOTES_FLAG="--generate-notes"
else
NOTES_FLAG="--notes-file /tmp/release-notes.md"
fi
if gh release view "${{ env.RELEASE_TAG }}" >/dev/null 2>&1; then
gh release edit "${{ env.RELEASE_TAG }}" \
--title "${{ env.RELEASE_TAG }}" \
$NOTES_FLAG
else
gh release create "${{ env.RELEASE_TAG }}" \
--title "${{ env.RELEASE_TAG }}" \
$NOTES_FLAG
fi
run: bun scripts/publish-cli-release.ts stage
- name: Upgrade npm for trusted publishing
if: ${{ !inputs.validate_only }}
run: |
npm install -g npm@11.16.0 --ignore-scripts
npm --version
- name: Publish to NPM
if: ${{ !inputs.validate_only }}
run: bun run scripts/publish.ts
- name: Publish completed GitHub Release
if: ${{ !inputs.validate_only }}
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: bun scripts/publish-cli-release.ts publish
+2
View File
@@ -77,6 +77,8 @@ Add any additional context, caveats, or follow-up work.
## Workspace Architecture
**Single-team design**: Each instance has one team, automatically created when the first user signs up.
The project is a Bun Workspaces monorepo (Bun runtime, Hono API, Prisma + Pgvector18 DB, React + Tailwind CSS + Shadcn UI frontend):
- **`packages/webui`**: React frontend (`bun run dev` runs on port 3000).
+57
View File
@@ -12,6 +12,63 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Changed
## [0.7.0] - 2026-11-18
### Added
- **i18n**: Add Korean as a display language, selectable on the sign-up page and in team settings.
### Fixed
- **cli**: Fix release publication failing to find staged standalone downloads.
### Changed
- **agent**: ⚠️ **Breaking Change**: Replaced the built-in server-side Bash sandbox with external Runners and removed the team-level sandbox domain allowlist settings. The Bash tool is now disabled by default. If your Agent or Skills require Bash execution, you'll need to set up and connect an external Runner using shumai-cli. The Shumai CLI includes built-in sandbox support, allowing you to configure filesystem access and network domain allowlists for Bash execution directly on the Runner. See [Agent Runners](https://docs.shumai.one/using-shumai/agent-sandbox) for setup instructions and configuration details. The Docker Compose configuration has also been updated to improve security following the removal of the server-side sandbox. We strongly recommend upgrading to the latest Shumai image and updating your Docker Compose file to apply these security improvements.
- **cli**: Show copyable commands and shell configuration instructions when the standalone CLI installation directory is missing from PATH.
## [0.6.6] - 2026-11-13
### Added
- **project**: Support creating new projects via the built-in agent, MCP server, and CLI (`shumai-cli project create`).
- **cli**: Add standalone downloads and one-line installers for macOS, Linux, and Windows without requiring Node.js or Bun, with verified downloads, version selection, and upgrade support.
### Fixed
- **storage**: Remove empty local folders left behind after generating video search embeddings.
### Changed
- **agent**: Upgrade the agent runtime and automatically migrate existing conversations, keep thread histories independent, prevent duplicate history during simultaneous mentions, improve session log scrolling and readability, and fix authentication for OpenAI and custom providers. Agents now run with the main server; standalone agent workers are no longer supported.
## [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
+4 -6
View File
@@ -8,7 +8,6 @@ WORKDIR /app
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
@@ -30,6 +29,8 @@ RUN bun run scripts/extract-runtime-deps.ts
# Stage 2: Runner
FROM oven/bun:1.4.4 AS runner
ENV NODE_ENV=production
# Install system dependencies and Jellyfin-FFmpeg (with VA-API support)
RUN apt-get update && apt-get install -y --no-install-recommends \
python3 \
@@ -45,9 +46,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
ripgrep \
procps \
lsof \
socat \
ca-certificates \
bubblewrap \
gosu \
poppler-utils \
imagemagick \
@@ -94,11 +93,10 @@ 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 worker commands "shumai-transcode", "shumai-agent")
# Expose "bun index.js" as "shumai" CLI command (and the transcode worker command)
RUN printf '#!/bin/sh\nexec bun /app/index.js "$@"\n' > /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 \
&& chmod +x /usr/local/bin/shumai /usr/local/bin/shumai-transcode \
&& ln -s /usr/local/bin/shumai /usr/local/bin/shuami
ENTRYPOINT ["docker-entrypoint.sh"]
+2 -1
View File
@@ -8,7 +8,6 @@ WORKDIR /app
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
@@ -25,6 +24,8 @@ 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 \
+25 -2
View File
@@ -16,7 +16,7 @@
</p>
<p align="center">
<a target="_blank" href="https://shumai.one/">Website</a> | <a target="_blank" href="https://docs.shumai.one/getting-started/overview">Docs</a> | <a target="_blank" href="https://staging.shumai.one">Demo</a> | <a target="_blank" href="https://discord.gg/sUzhujK6DD">Discord</a> | <a target="_blank" href="README_CN.md">中文</a>
<a target="_blank" href="https://shumai.one/">Website</a> | <a target="_blank" href="https://docs.shumai.one/getting-started/overview">Docs</a> | <a target="_blank" href="https://staging.shumai.one">Demo</a> | <a target="_blank" href="https://shumai.discourse.group/">Discourse Forum</a> | <a target="_blank" href="README_CN.md">中文</a>
</p>
![Shumai App Screenshot](docs/screenshot.webp)
@@ -26,6 +26,7 @@
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.
@@ -108,7 +109,15 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
> 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`). This is required for remote servers and production deployments.
* `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:
@@ -230,6 +239,20 @@ 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.
Install the standalone CLI on macOS/Linux without Node.js or Bun:
```sh
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
```
On Windows:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
```
The npm installation remains available: `npm install -g @shumai-one/shumai-cli` (Node.js 22.12+).
For more details on installation and usage, see the [CLI Readme](apps/cli/README.md).
## MCP Server
+25 -2
View File
@@ -16,7 +16,7 @@
</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="https://shumai.discourse.group/">Discourse 论坛</a> | <a target="_blank" href="README.md">English</a>
</p>
![Shumai 应用截图](docs/screenshot.webp)
@@ -26,6 +26,7 @@
Shumai 是一个专为广告,短剧,漫剧等各类创意团队打造的开源协作管理平台,功能上类似阅流和分秒帧,提供了协作、审片和分享等各种功能:
* **支持 S3 和本地存储**:你可以把创意素材安全地存放在本地硬盘或者任意兼容 S3 的存储服务里,比如 阿里云 OSS 或 MinIO 等。
* **冷归档存储**:支持将原始大文件移至冷存储(如本地挂载的 NAS、AWS S3 Glacier、Google Cloud Storage Coldline 等归档存储类型)以节省主存储成本,同时保留主存储中的预览图、代理流和元数据,不影响网页浏览与即时播放。详情请参阅[归档存储文档](https://docs.shumai.one/configuration/archive-storage)。
* **帧级别标注和评论**:支持按帧进行精确反馈,同时支持直接在视频上进行标注,让团队成员能更精确地Get到你的想法。
* **安全的分享**:可以生成私密分享链接,同时还支持给分享的图片/视频添加自定义水印,并将水印配置保存为模板以便重复使用。方便给客户、同事和合作方查看。
* **细粒度权限控制**:支持按团队、项目设置角色权限,方便管理不同成员的访问范围。
@@ -126,7 +127,15 @@ https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/REA
3. 配置环境变量:
* `BETTER_AUTH_URL`:Shumai 服务的外部公开访问地址(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`)。在远程服务器或生产环境中部署时必须配置该变量。
* `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 的默认重定向地址。
> [!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。
例如,如果你将 `docker-compose.yaml` 中的端口映射从 `3000:3000` 修改为了 `12345:3000`,且服务部署在 IP 为 `12.34.56.78` 的服务器上,请进行如下设置:
@@ -260,6 +269,20 @@ Shumai 提供了独立的转码 Worker 镜像(支持 Docker Hub 与阿里云
Shumai 自带一个功能完备的命令行工具(CLI),支持你直接在终端里高效管理项目、文件夹、素材,批量上传文件/目录,以及快速创建新版本。
macOS/Linux 可直接安装独立 CLI,无需安装 Node.js 或 Bun:
```sh
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
```
Windows 用户可使用 PowerShell:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
```
仍可通过 npm 安装:`npm install -g @shumai-one/shumai-cli`(需要 Node.js 22.12 或更高版本)。
关于 CLI 的安装与详细使用指南,请参阅 [CLI Readme](apps/cli/README.md)。
## MCP 服务器
+1 -1
View File
@@ -3,7 +3,7 @@
## Reporting a Vulnerability
Please report security vulnerabilities **privately**. Do not open a public issue,
pull request or Discord message for a suspected vulnerability, as that discloses it
pull request, or public forum post for a suspected vulnerability, as that discloses it
to everyone before a fix exists.
Use **[GitHub private vulnerability reporting](https://github.com/shumaiOne/shumai/security/advisories/new)**
-14
View File
@@ -1,14 +0,0 @@
{
"name": "@shumai/agent-app",
"version": "0.6.3",
"private": true,
"type": "module",
"bin": {
"shumai-agent": "./src/index.ts"
},
"dependencies": {
"@shumai/agent": "workspace:*",
"@shumai/core": "workspace:*",
"@shumai/workflow-core": "workspace:*"
}
}
-30
View File
@@ -1,30 +0,0 @@
import { loadEnvConfig } from '@shumai/core/src/env-loader'
loadEnvConfig(process.cwd(), process.env.NODE_ENV !== 'production')
import { workflowService } from '@shumai/workflow-core'
import { TaskQueueAgent } from '@shumai/workflow-core'
import { initAgentWorkflows } from '@shumai/agent'
import { sandboxService } from '@shumai/core'
import { handleDaemonCommands } from '@shumai/core/src/utils/daemon'
if (process.argv.includes('--check')) {
console.log('✅ Agent worker evaluated successfully!')
process.exit(0)
}
async function run() {
// Initialize workflows and activities
initAgentWorkflows()
await sandboxService.ensureInitialized().catch((err) => {
console.error('Failed to eagerly initialize sandbox in agent worker:', err)
})
console.log('🚀 Starting Agent Worker...')
await workflowService.startWorkers(TaskQueueAgent)
}
handleDaemonCommands('shumai-agent', run).catch((err) => {
console.error(err)
process.exit(1)
})
+118 -3
View File
@@ -8,7 +8,65 @@ The CLI allows you to view projects, list folder contents, create folders, uploa
## Installation
The CLI package is bundled inside the Shumai workspace. The published npm package (`@shumai-one/shumai-cli`) requires Node.js 22.12 or later.
### Standalone executable
Install the CLI without Node.js or Bun. The installers download a platform-specific executable from GitHub Releases and verify its SHA-256 checksum.
**macOS / Linux:**
```sh
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
```
**Windows (PowerShell):**
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
```
| Platform | Architectures | Requirements |
| --- | --- | --- |
| macOS | Apple Silicon, Intel | macOS 13 or later |
| Linux | ARM64, x64 | glibc 2.17 or later; kernel 5.6+ recommended |
| Windows | ARM64, x64 | Windows 10 version 1809 or later |
Native builds use Bun 1.4.4's runtime; x64 CPUs need SSE4.2. See [Bun's system requirements](https://bun.com/docs/installation). Alpine/musl is not included in these native downloads. Native downloads are available for releases containing the installer assets; use npm for earlier releases.
On macOS/Linux the default directory is `~/.local/bin`. If it is missing from your current PATH, the installer prints a command to run in your current Bash/Zsh terminal:
```sh
export PATH="$HOME/.local/bin:$PATH"
```
To keep the CLI available in future terminals, add the same export line to `~/.bashrc` (Bash) or `~/.zshrc` (Zsh). For Bash login shells, use your existing login profile, such as `~/.bash_profile` or `~/.profile`. Open a new terminal after saving. If you already added it, you do not need to add it again. For a custom installation directory, use the exact command printed by the installer.
On Windows the installer uses `%LOCALAPPDATA%\Shumai\bin` and updates the user PATH. Open a new terminal afterward. Administrator access is not required.
Re-run the installer to upgrade. To pin a version, roll back, or choose an installation directory, download the installer and pass its options (replace `X.Y.Z` with a release containing native binaries):
```sh
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh -o install.sh
sh install.sh --version X.Y.Z --install-dir "$HOME/.local/bin"
```
```powershell
Invoke-WebRequest https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 -OutFile install.ps1
& .\install.ps1 -Version X.Y.Z -InstallDir "$env:LOCALAPPDATA\Shumai\bin"
```
The installers preserve the existing executable if download or verification fails and refuse to replace unmanaged installations. If an npm installation takes precedence on PATH, uninstall it with `npm uninstall -g @shumai-one/shumai-cli` or adjust PATH.
To uninstall a native installation, remove `shumai-cli` (`shumai-cli.exe` on Windows) and `.shumai-cli-install` from its installation directory. Remove the PATH entry if it is no longer needed.
### npm
The existing npm package continues to run on Node.js 22.12 or later:
```sh
npm install -g @shumai-one/shumai-cli
```
`shumai-cli --version` reports the installed version for either installation method.
### Environment Setup
@@ -28,10 +86,48 @@ export SHUMAI_ALLOW_DELETE="true"
---
## Agent runner
Create a runner in **Settings → Agent Runners** and copy its one-time key. On macOS, Linux, or Windows, start it in an existing dedicated workspace:
```sh
export SHUMAI_API_SERVER="https://shumai.example.com"
export SHUMAI_RUNNER_KEY="your-runner-key"
shumai-cli runner start --cwd /path/to/workspace
```
For Windows PowerShell:
```powershell
$env:SHUMAI_API_SERVER = "https://shumai.example.com"
$env:SHUMAI_RUNNER_KEY = "your-runner-key"
shumai-cli runner start --cwd C:\workspace
```
Use `--url` or `--key` to override those variables. Pass `-v` or `--verbose` to log executed commands, output sizes, and file transfer paths (by default, only lifecycle events, execution IDs, exit status, and durations are printed to stderr). A runner key is separate from `SHUMAI_API_KEY`. The runner stays in the foreground; Ctrl+C stops it and its active commands. Remote servers require HTTPS; localhost and `host.docker.internal` support HTTP for development. No inbound port is opened.
Commands use `/bin/sh` on macOS and Linux. On Windows, the runner checks for Git Bash in the standard installation directories, then for `bash.exe` on PATH, then falls back to `cmd.exe`. It prints the selected shell at startup and reports it to the agent. Commands run with the local user's permissions unless SRT is requested.
[Anthropic Sandbox Runtime](https://github.com/anthropics/sandbox-runtime) is bundled with the CLI. Install its platform prerequisites (Linux: bubblewrap, socat, and ripgrep; macOS: ripgrep), then pass its native JSON settings:
```sh
shumai-cli runner start --srt sandbox.json
```
Windows sandboxing uses SRT's alpha Windows support. Use Git Bash if your selected shell is the legacy WSL Bash launcher. Run the one-time SRT setup before starting a sandboxed runner (it requests administrator permission):
```powershell
npx @anthropic-ai/sandbox-runtime windows-install
```
SRT settings are read and validated at startup. Invalid settings or unavailable sandbox prerequisites stop startup; commands never fall back to unrestricted execution. Only shell commands and their children are sandboxed. Runner connections and server-directed file transfers stay outside SRT, and no server domain is automatically allowed. The shared SRT runtime is cleaned up when the runner stops.
See [Agent Runners](../../docs/using-shumai/agent-sandbox.mdx) for configuration, Docker usage, limits, and security boundaries.
## Usage
> [!IMPORTANT]
> **For Bun Users:** Since the package binary contains a `#!/usr/bin/env node` shebang, running `shumai-cli` directly will run under Node.js. If you wish to run it using Bun, prefix the command with `bun run --bun` (e.g., `bun run --bun shumai-cli project ls`).
> **For npm installations using Bun:** The npm entry point uses `#!/usr/bin/env node`. Use `bun run --bun shumai-cli project ls` to run that package under Bun. Standalone installations already include their runtime.
Run `shumai-cli` or query specific commands:
@@ -49,7 +145,7 @@ When the output is piped instead of shown in a terminal, tables are printed as t
### Commands
#### 1. List Projects
#### 1. List and Create Projects
List all projects you have access to. Returns the project ID, name, and its root folder ID.
@@ -57,6 +153,12 @@ List all projects you have access to. Returns the project ID, name, and its root
shumai-cli project ls
```
Create a new project (returns the project ID and its root folder ID):
```bash
shumai-cli project create "Project Name"
```
#### 2. List Directory Contents
List direct children (folders and files) of a parent folder. Folders are listed first.
@@ -258,3 +360,16 @@ 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.
### Building and verifying native releases
```sh
bun run build:cli --target darwin-arm64 # or darwin-x64, linux-arm64, linux-x64, windows-arm64, windows-x64
bun run test:cli-release
```
Without `--target`, the build produces all six targets. Output defaults to `out/cli-release`. Set `--out /absolute/path` on either command to change it. Unix archives require `tar`. Creating Windows archives on Unix also requires `zip`. The test exercises installation, runner shell quoting, authenticated API calls, file transfers, and failure recovery. Install Git Bash to run the quoting check on Windows. With SRT configured, pass `--srt /absolute/path/to/settings.json` to repeat the quoting check in the sandbox.
The Native CLI workflow builds and tests each target on a matching runner. The npm release workflow assembles those tested archives, stages a draft GitHub Release, publishes npm packages, then publishes the completed release. Its `validate_only` dispatch input builds and tests without publishing. Published assets are verified and preserved on retries; draft assets can be replaced while resuming a failed run. Prerelease npm packages use the `next` tag and prerelease GitHub Releases do not become latest.
Installers use `SHUMAI_CLI_RELEASE_BASE_URL` only when explicitly set, for private mirrors or local testing. It should point to a release download base whose children are `vX.Y.Z/<asset>`. Native executables do not automatically load `.env` or `bunfig.toml`; export the API configuration explicitly as shown above.
+24
View File
@@ -0,0 +1,24 @@
The Windows Bash discovery and related tests include material adapted from Pi.
https://github.com/earendil-works/pi
MIT License
Copyright (c) 2025 Mario Zechner
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+11 -1
View File
@@ -1,19 +1,29 @@
{
"name": "@shumai/cli",
"version": "0.6.3",
"version": "0.7.0",
"private": true,
"type": "module",
"bin": {
"shumai-cli": "./src/index.ts"
},
"dependencies": {
"@anthropic-ai/sandbox-runtime": "0.0.83",
"@shumai/api": "workspace:*",
"@shumai/dtos": "workspace:*",
"@shumai/operations": "workspace:*",
"@shumai/tableprinter": "workspace:*",
"commander": "15.0.0",
"execa": "10.2.1",
"hono": "4.13.5",
"ulid": "3.0.2",
"ws": "8.22.2",
"yauzl": "3.4.0",
"zod": "4.5.4"
},
"devDependencies": {
"@types/adm-zip": "0.5.8",
"@types/ws": "8.18.2",
"@types/yauzl": "3.4.0",
"adm-zip": "0.6.1"
}
}
+54
View File
@@ -4,6 +4,7 @@ import {
copyAssets,
createComment,
createFolder,
createProject,
createVersionStack,
deleteAsset,
downloadAsset,
@@ -25,14 +26,17 @@ import {
import type { CallOperation } from './operations/call-operation'
import { CliError, formatCliError } from './operations/errors'
import { createProgram } from './program'
import { version } from '../package.json'
/** Runs the CLI with mocked Operation calls and captures stdout/stderr. */
function setup() {
let stdout = ''
let stderr = ''
const callOperation = vi.fn<CallOperation>()
const startRunner = vi.fn(async () => {})
const program = createProgram({
callOperation,
startRunner,
output: { out: { write: (s) => void (stdout += s) }, isTty: true, columns: 120 },
})
const configure = (cmd: Command) => {
@@ -45,6 +49,7 @@ function setup() {
configure(program)
return {
callOperation,
startRunner,
run: (...argv: string[]) => program.parseAsync(['node', 'shumai-cli', ...argv]),
stdout: () => stdout,
stderr: () => stderr,
@@ -75,6 +80,13 @@ const pendingRead = {
}
describe('shumai-cli', () => {
it('reports its package version without calling the server', async () => {
const cli = setup()
await expect(cli.run('--version')).rejects.toMatchObject({ code: 'commander.version' })
expect(cli.stdout()).toBe(`${version}\n`)
expect(cli.callOperation).not.toHaveBeenCalled()
})
const originalAllowDelete = process.env.SHUMAI_ALLOW_DELETE
afterEach(() => {
@@ -110,6 +122,31 @@ describe('shumai-cli', () => {
})
})
describe('project create', () => {
it('creates a project with positional name and optional --team', async () => {
const cli = setup()
cli.callOperation.mockResolvedValue({
id: 'p-new',
name: 'Summer Shoot',
teamId: 't1',
rootFolderId: 'root-new',
})
await cli.run('project', 'create', 'Summer Shoot')
expect(cli.callOperation).toHaveBeenCalledWith(createProject, { name: 'Summer Shoot' })
expect(cli.stdout()).toBe(
'Created project "Summer Shoot" (ID: p-new, rootFolderId: root-new)\n',
)
await cli.run('project', 'create', 'Team Shoot', '-t', 't2', '--json')
expect(cli.callOperation).toHaveBeenLastCalledWith(createProject, {
name: 'Team Shoot',
teamId: 't2',
})
})
})
describe('ls', () => {
it('lists a folder with the maximum page size, folders first', async () => {
const cli = setup()
@@ -823,6 +860,23 @@ describe('shumai-cli', () => {
})
})
describe('runner start', () => {
it('documents and forwards the -v, --verbose flag', async () => {
const cli = setup()
await expect(cli.run('runner', 'start', '--help')).rejects.toThrow()
expect(cli.stdout()).toContain('-v, --verbose')
await cli.run('runner', 'start')
expect(cli.startRunner).toHaveBeenLastCalledWith({})
await cli.run('runner', 'start', '-v')
expect(cli.startRunner).toHaveBeenLastCalledWith({ verbose: true })
await cli.run('runner', 'start', '--verbose')
expect(cli.startRunner).toHaveBeenLastCalledWith({ verbose: true })
})
})
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())
+17
View File
@@ -6,10 +6,14 @@ import { callOperation, type CallOperation } from './operations/call-operation'
import { cliExtensions } from './operations/extensions'
import { registerOperationCommands } from './operations/generate'
import type { Output } from './operations/render'
import { version } from '../package.json'
import { startRunner } from './runner/client'
import type { RunnerOptions } from './runner/config'
export interface ProgramOptions {
callOperation?: CallOperation
output?: Output
startRunner?: (options: RunnerOptions) => Promise<void>
}
function isDeleteAllowed(): boolean {
@@ -26,6 +30,7 @@ export function createProgram(options: ProgramOptions = {}): Command {
const program = new Command()
.name('shumai-cli')
.description('Command line interface for the Shumai media workspace.')
.version(version)
.option('--json', 'Print raw JSON output instead of human-friendly text')
.showHelpAfterError()
.showSuggestionAfterError()
@@ -41,6 +46,18 @@ export function createProgram(options: ProgramOptions = {}): Command {
extensions: cliExtensions,
})
program
.command('runner')
.description('Connect a local command runner to Shumai.')
.command('start')
.description('Run in the foreground using a key created in Settings → Agent Runners.')
.option('--url <url>', 'Shumai server URL (or SHUMAI_API_SERVER).')
.option('--key <key>', 'Runner key (prefer SHUMAI_RUNNER_KEY to avoid shell history).')
.option('--cwd <directory>', 'Runner workspace directory (defaults to the current directory).')
.option('--srt <file>', 'Sandbox commands with bundled SRT using this JSON settings file.')
.option('-v, --verbose', 'Show command details, output sizes, and file transfer paths.')
.action((opts: RunnerOptions) => (options.startRunner ?? startRunner)(opts))
program
.command('upload')
.description('Upload a local file or folder to a parent folder.')
+446
View File
@@ -0,0 +1,446 @@
import { createServer } from 'node:http'
import { mkdtemp, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
import { WebSocketServer, type WebSocket } from 'ws'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { runnerToServerMessageSchema, type RunnerToServerMessage } from '@shumai/dtos'
import { RunnerClient } from './client'
import { RunnerFiles } from './files'
import { RunnerShell } from './shell'
describe('runner WebSocket client', () => {
let cwd: string
let server: WebSocketServer
let runner: RunnerClient
let running: Promise<void>
let socket: WebSocket
let messages: RunnerToServerMessage[]
let welcomeInFlight: string[]
let connections: number
let replacePrevious: boolean
let connectRunner: (options?: { verbose?: boolean; log?: (line: string) => void }) => RunnerClient
beforeEach(async () => {
cwd = await mkdtemp(path.join(tmpdir(), 'shumai-client-test-'))
messages = []
welcomeInFlight = []
connections = 0
replacePrevious = false
server = new WebSocketServer({ host: '127.0.0.1', port: 0 })
await new Promise<void>((resolve) => server.once('listening', resolve))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('No WebSocket address')
server.on('connection', (connection, request) => {
expect(request.headers.authorization).toBe('Bearer runner-key')
if (replacePrevious) socket.close(4000, 'Replaced by a newer connection')
socket = connection
connections++
connection.on('message', (raw) =>
messages.push(runnerToServerMessageSchema.parse(JSON.parse(raw.toString()))),
)
connection.send(
JSON.stringify({
type: 'welcome',
runnerId: 'runner',
runnerName: 'Test',
serverTime: Date.now(),
inFlightExecutionIds: welcomeInFlight,
}),
)
})
connectRunner = (options) => {
const files = new RunnerFiles(cwd)
return new RunnerClient(
{
url: new URL(`ws://127.0.0.1:${address.port}/api/runners/ws`),
key: 'runner-key',
cwd,
srt: undefined,
verbose: options?.verbose ?? false,
},
files,
new RunnerShell(files),
options?.log ?? (() => {}),
)
}
runner = connectRunner()
running = runner.run()
// Attach an error handler immediately, including for tests exercising terminal errors.
void running.catch(() => {})
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
)
})
afterEach(async () => {
runner.stop()
await running.catch(() => {})
for (const connection of server.clients) connection.terminate()
await new Promise<void>((resolve) => server.close(() => resolve()))
await rm(cwd, { recursive: true, force: true })
})
const send = (message: unknown) => socket.send(JSON.stringify(message))
it('responds to heartbeat, executes a command once and streams byte offsets', async () => {
expect(messages).toContainEqual(
expect.objectContaining({
type: 'reconcile',
environment: { platform: process.platform, shell: '/bin/sh' },
}),
)
send({ type: 'ping', ts: 123 })
const command = {
type: 'exec.start',
executionId: 'one',
command: 'printf "世界"; printf "error" >&2',
}
send(command)
send(command)
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'exec.result')).toBe(true),
)
expect(messages).toContainEqual({ type: 'pong', ts: 123 })
expect(messages.filter((message) => message.type === 'exec.result')).toHaveLength(1)
const chunks = messages.filter((message) => message.type === 'exec.output')
expect(chunks.map((chunk) => chunk.data).join('')).toContain('世界')
let offset = 0
for (const chunk of chunks) {
expect(chunk.offset).toBe(offset)
offset += Buffer.byteLength(chunk.data)
}
})
it('cancels an active command through the protocol', async () => {
send({ type: 'exec.start', executionId: 'cancel', command: 'echo ready; sleep 30' })
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'exec.output')).toBe(true),
)
send({ type: 'exec.cancel', executionId: 'cancel' })
await vi.waitFor(() =>
expect(messages).toContainEqual(
expect.objectContaining({ type: 'exec.result', executionId: 'cancel', aborted: true }),
),
)
})
it('reconnects and replays output before completing an in-flight command', async () => {
send({
type: 'exec.start',
executionId: 'reconnect',
command: 'echo before; sleep 0.2; echo after',
})
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'exec.output')).toBe(true),
)
welcomeInFlight = ['reconnect']
socket.terminate()
messages = []
await vi.waitFor(() => expect(connections).toBe(2), { timeout: 5000 })
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
)
const reconciliation = messages.findIndex((message) => message.type === 'reconcile')
expect(
messages
.slice(0, reconciliation)
.filter((message) => message.type === 'exec.output')
.map((message) => message.data)
.join(''),
).toContain('after')
expect(messages[reconciliation]).toMatchObject({
completedExecutions: [expect.objectContaining({ executionId: 'reconnect', exitCode: 0 })],
})
})
it('handles file requests and returns a cached result for a duplicate request', async () => {
const request = { type: 'file.stat', executionId: 'stat', srcPath: '.pi/missing' }
send(request)
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'file.stat.result')).toBe(true),
)
send(request)
await vi.waitFor(() =>
expect(messages.filter((message) => message.type === 'file.stat.result')).toHaveLength(2),
)
expect(messages.at(-1)).toMatchObject({ ok: true, exists: false })
})
it('stops instead of reconnecting when the runner key is revoked', async () => {
socket.close(1008, 'revoked')
await expect(running).rejects.toThrow('revoked')
expect(connections).toBe(1)
})
it('stops the superseded client when a second runner connects with the same key', async () => {
replacePrevious = true
let replaced: unknown
void running.catch((error: unknown) => {
replaced = error
})
const replacement = connectRunner()
const replacementRun = replacement.run()
void replacementRun.catch(() => {})
try {
await vi.waitFor(() => expect(replaced).toBeInstanceOf(Error))
await expect(running).rejects.toThrow('replaced')
expect(connections).toBe(2)
} finally {
replacement.stop()
await replacementRun.catch(() => {})
}
})
it('rejects invalid messages and path-like execution IDs', async () => {
send({ type: 'exec.start', executionId: '../escape', command: 'echo unsafe' })
await expect(running).rejects.toThrow('invalid runner protocol')
expect(messages.some((message) => message.type === 'exec.output')).toBe(false)
})
it('logs compact lifecycle, bash, and transfer summaries in default mode', async () => {
runner.stop()
await running.catch(() => {})
const logs: string[] = []
messages = []
runner = connectRunner({ verbose: false, log: (line) => logs.push(line) })
running = runner.run()
void running.catch(() => {})
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
)
send({ type: 'exec.start', executionId: '01JTEST0000A8F2', command: 'printf "hello"' })
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'exec.result')).toBe(true),
)
send({
type: 'exec.start',
executionId: '01JTEST0000TOUT',
command: 'sleep 5',
timeoutSec: 0.1,
})
await vi.waitFor(() =>
expect(
messages.some(
(message) => message.type === 'exec.result' && message.executionId === '01JTEST0000TOUT',
),
).toBe(true),
)
send({ type: 'file.stat', executionId: '01JTEST0000STAT', srcPath: '.pi/missing' })
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'file.stat.result')).toBe(true),
)
const httpServer = createServer((_request, response) => {
response.end('payload')
})
await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve))
try {
const httpAddress = httpServer.address()
if (!httpAddress || typeof httpAddress === 'string') throw new Error('No HTTP address')
send({
type: 'file.download',
executionId: '01JTEST0000C3D9',
url: `http://127.0.0.1:${httpAddress.port}/file`,
destPath: '.pi/assets/file.txt',
})
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'file.download.result')).toBe(true),
)
} finally {
httpServer.closeAllConnections()
await new Promise<void>((resolve) => httpServer.close(() => resolve()))
}
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} INFO {2}Runner connected: Test \(runner\)$/.test(line),
),
).toBe(true)
expect(
logs.some((line) => /^\d{2}:\d{2}:\d{2} INFO {2}Bash started \[a8f2\]$/.test(line)),
).toBe(true)
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} INFO {2}Bash completed \[a8f2\] exit=0 duration=\d+\.\ds$/.test(line),
),
).toBe(true)
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} WARN {2}Bash timed out \[tout\] duration=\d+\.\ds$/.test(line),
),
).toBe(true)
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} INFO {2}File download completed \[c3d9\] size=7B duration=\d+\.\ds$/.test(
line,
),
),
).toBe(true)
expect(logs.join('\n')).not.toContain('command=')
expect(logs.join('\n')).not.toContain('File stat')
expect(logs.join('\n')).not.toContain('.pi/assets/file.txt')
})
it('logs commands, stream sizes, and file paths in verbose mode', async () => {
runner.stop()
await running.catch(() => {})
const logs: string[] = []
messages = []
runner = connectRunner({ verbose: true, log: (line) => logs.push(line) })
running = runner.run()
void running.catch(() => {})
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
)
send({
type: 'exec.start',
executionId: '01JTEST0000B9E1',
command: 'printf "hi"; printf "err" >&2',
})
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'exec.result')).toBe(true),
)
send({ type: 'file.stat', executionId: '01JTEST0000B1A4', srcPath: '.pi/missing' })
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'file.stat.result')).toBe(true),
)
const httpServer = createServer((_request, response) => {
response.writeHead(500)
response.end()
})
await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve))
try {
const httpAddress = httpServer.address()
if (!httpAddress || typeof httpAddress === 'string') throw new Error('No HTTP address')
send({
type: 'file.download',
executionId: '01JTEST0000E5F1',
url: `http://127.0.0.1:${httpAddress.port}/fail`,
destPath: '.pi/assets/fail.txt',
})
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'file.download.result')).toBe(true),
)
} finally {
httpServer.closeAllConnections()
await new Promise<void>((resolve) => httpServer.close(() => resolve()))
}
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} INFO {2}Bash started \[b9e1\] command="printf \\"hi\\"; printf \\"err\\" >&2"$/.test(
line,
),
),
).toBe(true)
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} INFO {2}Bash completed \[b9e1\] exit=0 duration=\d+\.\ds stdout=2B stderr=3B$/.test(
line,
),
),
).toBe(true)
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} INFO {2}File stat \[b1a4\] path="\.pi\/missing" exists=false$/.test(
line,
),
),
).toBe(true)
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} INFO {2}File download started \[e5f1\] path="\.pi\/assets\/fail\.txt"$/.test(
line,
),
),
).toBe(true)
expect(
logs.some((line) =>
/^\d{2}:\d{2}:\d{2} WARN {2}File download failed \[e5f1\] path="\.pi\/assets\/fail\.txt" duration=\d+\.\ds error="Download failed \(HTTP 500\)\."$/.test(
line,
),
),
).toBe(true)
})
it.each([false, true])(
'logs a single busy rejection without false starts at capacity (verbose=%s)',
async (verbose) => {
runner.stop()
await running.catch(() => {})
const logs: string[] = []
messages = []
runner = connectRunner({ verbose, log: (line) => logs.push(line) })
running = runner.run()
void running.catch(() => {})
await vi.waitFor(() =>
expect(messages.some((message) => message.type === 'reconcile')).toBe(true),
)
for (let index = 0; index < 8; index++) {
send({
type: 'exec.start',
executionId: `01JACTIVE00000${index}`,
command: 'sleep 30',
})
}
await vi.waitFor(() =>
expect(logs.filter((line) => line.includes('Bash started'))).toHaveLength(8),
)
send({
type: 'exec.start',
executionId: '01JBUSYCMD00B123',
command: 'echo rejected',
})
send({
type: 'file.upload',
executionId: '01JBUSYFILE0U456',
srcPath: '.pi/out.bin',
url: 'http://127.0.0.1:9/upload',
})
await vi.waitFor(() => {
expect(messages).toContainEqual(
expect.objectContaining({
type: 'exec.result',
executionId: '01JBUSYCMD00B123',
error: 'Runner is busy. Try again later.',
}),
)
expect(messages).toContainEqual(
expect.objectContaining({
type: 'file.upload.result',
executionId: '01JBUSYFILE0U456',
ok: false,
error: 'Runner is busy. Try again later.',
}),
)
})
const bashLogs = logs.filter((line) => line.includes('[b123]'))
const uploadLogs = logs.filter((line) => line.includes('[u456]'))
expect(bashLogs).toHaveLength(1)
expect(uploadLogs).toHaveLength(1)
if (verbose) {
expect(bashLogs[0]).toMatch(
/^\d{2}:\d{2}:\d{2} WARN {2}Bash rejected \[b123\] command="echo rejected" error="Runner is busy\. Try again later\."$/,
)
expect(uploadLogs[0]).toMatch(
/^\d{2}:\d{2}:\d{2} WARN {2}File upload rejected \[u456\] path="\.pi\/out\.bin" error="Runner is busy\. Try again later\."$/,
)
} else {
expect(bashLogs[0]).toMatch(
/^\d{2}:\d{2}:\d{2} WARN {2}Bash rejected \[b123\] \(runner is busy\)$/,
)
expect(uploadLogs[0]).toMatch(
/^\d{2}:\d{2}:\d{2} WARN {2}File upload rejected \[u456\] \(runner is busy\)$/,
)
}
},
)
})
+461
View File
@@ -0,0 +1,461 @@
import WebSocket from 'ws'
import { setTimeout as delay } from 'node:timers/promises'
import {
RUNNER_REPLACED_CLOSE_CODE,
serverToRunnerMessageSchema,
type RunnerExecOutputMessage,
type RunnerExecResultMessage,
type RunnerToServerMessage,
type ServerToRunnerMessage,
} from '@shumai/dtos'
import { CliError } from '../operations/errors'
import { resolveRunnerConfig, type RunnerConfig, type RunnerOptions } from './config'
import { RunnerFiles, type FileMessage } from './files'
import {
createRunnerLogger,
formatBytes,
formatDuration,
formatLogString,
shortId,
type RunnerLogger,
} from './log'
import { RunnerShell } from './shell'
const MAX_REPLAY_BYTES = 1024 * 1024
const MAX_COMPLETED = 16
const MAX_ACTIVE = 8
const RUNNER_BUSY_ERROR = 'Runner is busy. Try again later.'
const FILE_OPERATION_KINDS: Record<FileMessage['type'], 'download' | 'upload' | 'stat'> = {
'file.download': 'download',
'file.upload': 'upload',
'file.stat': 'stat',
}
interface Execution {
controller: AbortController
chunks: RunnerExecOutputMessage[]
bytes: number
offset: number
startedAt: number
stdoutBytes: number
stderrBytes: number
result?: RunnerExecResultMessage
}
export class RunnerClient {
private socket?: WebSocket
private ready = false
private stopped = new AbortController()
private executions = new Map<string, Execution>()
private transfers = new Map<string, AbortController>()
private completedFiles = new Map<string, RunnerToServerMessage>()
private pending = new Set<Promise<void>>()
private readonly logger: RunnerLogger
constructor(
private readonly config: RunnerConfig,
private readonly files: RunnerFiles,
private readonly shell: RunnerShell,
log: (message: string) => void = console.error,
) {
this.logger = createRunnerLogger(log, Boolean(config.verbose))
}
async run(signal?: AbortSignal): Promise<void> {
const stop = () => this.stop()
signal?.addEventListener('abort', stop, { once: true })
if (signal?.aborted) this.stop()
let attempt = 0
try {
while (!this.stopped.signal.aborted) {
const wasReady = await this.connect()
if (this.stopped.signal.aborted) break
attempt = wasReady ? 0 : Math.min(attempt + 1, 5)
this.logger.warn('Runner disconnected; reconnecting…')
await delay(Math.min(1000 * 2 ** attempt, 30_000), undefined, {
signal: this.stopped.signal,
}).catch(() => {})
}
} finally {
signal?.removeEventListener('abort', stop)
this.stop()
await Promise.allSettled(this.pending)
}
}
stop() {
this.stopped.abort()
this.ready = false
this.socket?.terminate()
for (const execution of this.executions.values()) execution.controller.abort()
for (const transfer of this.transfers.values()) transfer.abort()
}
private connect(): Promise<boolean> {
return new Promise((resolve, reject) => {
const socket = new WebSocket(this.config.url, {
headers: { authorization: `Bearer ${this.config.key}` },
handshakeTimeout: 10_000,
maxPayload: 1024 * 1024,
perMessageDeflate: false,
followRedirects: false,
})
this.socket = socket
let welcomed = false
let lastMessage = Date.now()
const heartbeat = setInterval(() => {
if (Date.now() - lastMessage > (welcomed ? 75_000 : 10_000)) socket.terminate()
}, 5_000)
socket.on('error', () => {
/* Close drives reconnect; never print credential-bearing request errors. */
})
socket.on('unexpected-response', (_request, response) => {
response.destroy()
socket.terminate()
if ([401, 403, 404, 426].includes(response.statusCode ?? 0))
reject(
new CliError(
`Runner connection rejected (HTTP ${response.statusCode}). Check the server URL and runner key.`,
),
)
})
socket.on('close', (code) => {
clearInterval(heartbeat)
this.ready = false
if ((code === 1008 || code === RUNNER_REPLACED_CLOSE_CODE) && !this.stopped.signal.aborted)
reject(
new CliError('Runner access was revoked or another connection replaced this runner.'),
)
else resolve(welcomed)
})
socket.on('message', (raw) => {
try {
const parsed = serverToRunnerMessageSchema.parse(JSON.parse(raw.toString()))
if ('executionId' in parsed && !/^[A-Za-z0-9_-]{1,128}$/.test(parsed.executionId))
throw new Error('Invalid execution ID.')
lastMessage = Date.now()
if (parsed.type === 'welcome') {
if (welcomed) throw new Error('Duplicate welcome.')
welcomed = true
this.ready = true
this.reconcile(parsed.inFlightExecutionIds)
this.logger.info(`Runner connected: ${parsed.runnerName} (${parsed.runnerId})`)
} else {
if (!welcomed) throw new Error('Expected welcome before runner requests.')
this.handle(parsed)
}
} catch {
reject(new CliError('Server sent an invalid runner protocol message.'))
socket.terminate()
}
})
if (this.stopped.signal.aborted) socket.terminate()
})
}
private send(message: RunnerToServerMessage) {
if (this.ready && this.socket?.readyState === WebSocket.OPEN)
this.socket.send(JSON.stringify(message))
}
private reconcile(inFlight: string[]) {
const expected = new Set(inFlight)
for (const [id, execution] of this.executions) {
if (!expected.has(id)) {
execution.controller.abort()
if (execution.result) this.executions.delete(id)
continue
}
// Replay before results: the server deduplicates chunks by UTF-8 byte offset.
for (const chunk of execution.chunks) this.send(chunk)
}
this.send({
type: 'reconcile',
environment: this.shell.environment,
activeExecutions: [...this.executions]
.filter(([id, execution]) => expected.has(id) && !execution.result)
.map(([executionId, execution]) => ({ executionId, nextOffset: execution.offset })),
completedExecutions: [...this.executions]
.filter(([id, execution]) => expected.has(id) && execution.result)
.map(([, execution]) => execution.result!),
})
}
private handle(message: Exclude<ServerToRunnerMessage, { type: 'welcome' }>) {
if (message.type === 'ping') {
this.send({ type: 'pong', ts: message.ts })
return
}
if (message.type === 'exec.cancel') {
this.executions.get(message.executionId)?.controller.abort()
return
}
if (message.type === 'exec.start') {
const previous = this.executions.get(message.executionId)
if (previous) {
if (previous.result) this.send(previous.result)
return
}
const id = shortId(message.executionId)
if (this.activeCount() >= MAX_ACTIVE) {
const result: RunnerExecResultMessage = {
type: 'exec.result',
executionId: message.executionId,
exitCode: null,
signal: null,
timedOut: false,
error: RUNNER_BUSY_ERROR,
}
this.recordCompletedExecution(message.executionId, result)
this.logger.warn(
this.logger.verbose
? `Bash rejected [${id}] command=${formatLogString(message.command)} error=${formatLogString(RUNNER_BUSY_ERROR)}`
: `Bash rejected [${id}] (runner is busy)`,
)
this.send(result)
return
}
const execution: Execution = {
controller: new AbortController(),
chunks: [],
bytes: 0,
offset: 0,
startedAt: performance.now(),
stdoutBytes: 0,
stderrBytes: 0,
}
this.executions.set(message.executionId, execution)
this.logger.info(
this.logger.verbose
? `Bash started [${id}] command=${formatLogString(message.command)}`
: `Bash started [${id}]`,
)
this.track(
(async () => {
const result = await this.shell.run(
message,
execution.controller.signal,
(stream, data) => {
// Small frames keep reconnect replay and WebSocket buffering bounded.
for (const part of data.match(/[\s\S]{1,8192}/gu) ?? []) {
const chunk: RunnerExecOutputMessage = {
type: 'exec.output',
executionId: message.executionId,
stream,
data: part,
offset: execution.offset,
}
const bytes = Buffer.byteLength(part)
execution.offset += bytes
execution.bytes += bytes
if (stream === 'stdout') execution.stdoutBytes += bytes
else execution.stderrBytes += bytes
execution.chunks.push(chunk)
while (execution.bytes > MAX_REPLAY_BYTES) {
const removed = execution.chunks.shift()!
execution.bytes -= Buffer.byteLength(removed.data)
if (!this.ready) execution.controller.abort()
}
if ((this.socket?.bufferedAmount ?? 0) > MAX_REPLAY_BYTES) {
this.ready = false
this.socket?.terminate()
}
this.send(chunk)
}
},
)
execution.result = result
this.logExecResult(id, execution, result)
this.send(result)
this.pruneCompletedExecutions()
})(),
)
return
}
this.handleFile(message)
}
private recordCompletedExecution(executionId: string, result: RunnerExecResultMessage) {
this.executions.set(executionId, {
controller: new AbortController(),
chunks: [],
bytes: 0,
offset: 0,
startedAt: performance.now(),
stdoutBytes: 0,
stderrBytes: 0,
result,
})
this.pruneCompletedExecutions()
}
private pruneCompletedExecutions() {
const completed = [...this.executions].filter(([, value]) => value.result)
for (const [completedId] of completed.slice(0, -MAX_COMPLETED))
this.executions.delete(completedId)
}
private logExecResult(id: string, execution: Execution, result: RunnerExecResultMessage) {
const duration = formatDuration(performance.now() - execution.startedAt)
const sizes = this.logger.verbose
? ` stdout=${formatBytes(execution.stdoutBytes)} stderr=${formatBytes(execution.stderrBytes)}`
: ''
if (result.timedOut) {
const error =
this.logger.verbose && result.error ? ` error=${formatLogString(result.error)}` : ''
this.logger.warn(`Bash timed out [${id}] duration=${duration}${sizes}${error}`)
return
}
if (result.aborted) {
this.logger.info(`Bash cancelled [${id}] duration=${duration}${sizes}`)
return
}
if (result.error) {
const error = this.logger.verbose ? ` error=${formatLogString(result.error)}` : ''
this.logger.warn(`Bash failed [${id}] duration=${duration}${sizes}${error}`)
return
}
if (result.exitCode === null && result.signal) {
this.logger.warn(`Bash killed [${id}] signal=${result.signal} duration=${duration}${sizes}`)
return
}
this.logger.info(`Bash completed [${id}] exit=${result.exitCode} duration=${duration}${sizes}`)
}
private activeCount() {
return (
[...this.executions.values()].filter((execution) => !execution.result).length +
this.transfers.size
)
}
private handleFile(message: FileMessage) {
const previous = this.completedFiles.get(message.executionId)
if (previous) {
this.send(previous)
return
}
if (this.transfers.has(message.executionId)) return
const id = shortId(message.executionId)
const transferPath = message.type === 'file.download' ? message.destPath : message.srcPath
if (this.activeCount() >= MAX_ACTIVE) {
const result = this.fileBusy(message)
this.recordCompletedFile(message.executionId, result)
const kind = FILE_OPERATION_KINDS[message.type]
this.logger.warn(
this.logger.verbose
? `File ${kind} rejected [${id}] path=${formatLogString(transferPath)} error=${formatLogString(RUNNER_BUSY_ERROR)}`
: `File ${kind} rejected [${id}] (runner is busy)`,
)
this.send(result)
return
}
const controller = new AbortController()
this.transfers.set(message.executionId, controller)
const timer = setTimeout(() => controller.abort(), 120_000)
const startedAt = performance.now()
if (this.logger.verbose && message.type !== 'file.stat') {
const kind = message.type === 'file.download' ? 'download' : 'upload'
this.logger.info(`File ${kind} started [${id}] path=${formatLogString(transferPath)}`)
}
this.track(
(async () => {
try {
const result = await this.files.handle(message, controller.signal)
this.recordCompletedFile(message.executionId, result)
this.logFileResult(id, transferPath, startedAt, result)
this.send(result)
} finally {
clearTimeout(timer)
this.transfers.delete(message.executionId)
}
})(),
)
}
private recordCompletedFile(executionId: string, result: RunnerToServerMessage) {
this.completedFiles.set(executionId, result)
if (this.completedFiles.size > MAX_COMPLETED)
this.completedFiles.delete(this.completedFiles.keys().next().value!)
}
private logFileResult(
id: string,
transferPath: string,
startedAt: number,
result: RunnerToServerMessage,
) {
if (result.type === 'file.stat.result') {
if (!this.logger.verbose) return
const pathPart = `path=${formatLogString(transferPath)}`
if (!result.ok) {
this.logger.warn(
`File stat failed [${id}] ${pathPart} error=${formatLogString(result.error ?? 'Unknown error')}`,
)
return
}
const sizePart = result.exists ? ` size=${formatBytes(result.size ?? 0)}` : ''
this.logger.info(`File stat [${id}] ${pathPart} exists=${result.exists}${sizePart}`)
return
}
if (result.type !== 'file.download.result' && result.type !== 'file.upload.result') return
const kind = result.type === 'file.download.result' ? 'download' : 'upload'
const duration = formatDuration(performance.now() - startedAt)
const pathPart = this.logger.verbose ? ` path=${formatLogString(transferPath)}` : ''
if (result.ok) {
this.logger.info(
`File ${kind} completed [${id}]${pathPart} size=${formatBytes(result.size ?? 0)} duration=${duration}`,
)
return
}
const errorPart = this.logger.verbose
? ` error=${formatLogString(result.error ?? 'Unknown error')}`
: ''
this.logger.warn(`File ${kind} failed [${id}]${pathPart} duration=${duration}${errorPart}`)
}
private fileBusy(message: FileMessage): RunnerToServerMessage {
const result = {
executionId: message.executionId,
ok: false,
error: RUNNER_BUSY_ERROR,
}
switch (message.type) {
case 'file.download':
return { ...result, type: 'file.download.result' }
case 'file.upload':
return { ...result, type: 'file.upload.result' }
case 'file.stat':
return { ...result, type: 'file.stat.result', exists: false }
}
}
private track(task: Promise<void>) {
this.pending.add(task)
void task.finally(() => this.pending.delete(task)).catch(() => this.stop())
}
}
export async function startRunner(options: RunnerOptions) {
const config = await resolveRunnerConfig(options)
const files = new RunnerFiles(config.cwd)
const shell = new RunnerShell(files, config.srt)
// SRT resolves relative policy paths against the runner workspace.
process.chdir(config.cwd)
await shell.initialize()
createRunnerLogger(console.error, Boolean(config.verbose)).info(
`Runner shell: ${shell.environment.shell}`,
)
const runner = new RunnerClient(config, files, shell)
const controller = new AbortController()
const shutdown = () => controller.abort()
process.once('SIGINT', shutdown)
process.once('SIGTERM', shutdown)
try {
await runner.run(controller.signal)
} finally {
process.removeListener('SIGINT', shutdown)
process.removeListener('SIGTERM', shutdown)
await shell.close()
}
}
+66
View File
@@ -0,0 +1,66 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import { commandEnv, resolveRunnerConfig } from './config'
afterEach(() => vi.unstubAllEnvs())
describe('runner configuration', () => {
it('preserves Windows OS settings, normalizes explicit overrides, and excludes credentials', () => {
vi.stubEnv('Path', 'C:\\Windows\\System32')
vi.stubEnv('SystemRoot', 'C:\\Windows')
vi.stubEnv('USERPROFILE', 'C:\\Users\\runner')
const env = commandEnv({ PATH: 'C:\\tools', ['shumai_runner_key']: 'secret' })
expect(env).toMatchObject({
PATH: 'C:\\tools',
SystemRoot: 'C:\\Windows',
USERPROFILE: 'C:\\Users\\runner',
})
expect(env).not.toHaveProperty('Path')
expect(env).not.toHaveProperty('shumai_runner_key')
})
it('uses a dedicated runner key and preserves a server path prefix', async () => {
vi.stubEnv('SHUMAI_API_SERVER', 'https://example.com/shumai/')
vi.stubEnv('SHUMAI_RUNNER_KEY', 'runner-secret')
const config = await resolveRunnerConfig({})
expect(config.url.href).toBe('wss://example.com/shumai/api/runners/ws')
expect(config.key).toBe('runner-secret')
expect(config.cwd).toBe(process.cwd())
expect(config.verbose).toBe(false)
expect((await resolveRunnerConfig({ verbose: true })).verbose).toBe(true)
})
it.each([
'http://example.com',
'ftp://localhost',
'https://user:secret@example.com',
'https://example.com/?key=secret',
'not a URL',
])('rejects unsafe server URL %s', async (url) => {
await expect(resolveRunnerConfig({ url, key: 'key' })).rejects.toThrow()
})
it('allows the Docker host development address', async () => {
expect(
(await resolveRunnerConfig({ url: 'http://host.docker.internal:3000', key: 'key' })).url.href,
).toBe('ws://host.docker.internal:3000/api/runners/ws')
})
it('does not accept a personal API token in place of a missing runner key', async () => {
vi.stubEnv('SHUMAI_RUNNER_KEY', '')
vi.stubEnv('SHUMAI_API_KEY', 'personal-secret')
await expect(resolveRunnerConfig({ url: 'https://example.com' })).rejects.toThrow(
'SHUMAI_RUNNER_KEY',
)
})
it('inherits only baseline environment and explicit skill variables', () => {
vi.stubEnv('SHUMAI_RUNNER_KEY', 'runner-secret')
vi.stubEnv('SHUMAI_API_KEY', 'personal-secret')
vi.stubEnv('AWS_SECRET_ACCESS_KEY', 'aws-secret')
vi.stubEnv('BASH_ENV', '/malicious-startup')
expect(
commandEnv({ SKILL_TOKEN: 'skill-secret', SHUMAI_RUNNER_KEY: 'injected' }),
).toMatchObject({ SKILL_TOKEN: 'skill-secret' })
for (const name of ['SHUMAI_RUNNER_KEY', 'SHUMAI_API_KEY', 'AWS_SECRET_ACCESS_KEY', 'BASH_ENV'])
expect(commandEnv()).not.toHaveProperty(name)
})
})
+84
View File
@@ -0,0 +1,84 @@
import { realpath, stat } from 'node:fs/promises'
import path from 'node:path'
import { CliError } from '../operations/errors'
export interface RunnerOptions {
url?: string
key?: string
cwd?: string
srt?: string
verbose?: boolean
}
export interface RunnerConfig {
url: URL
key: string
cwd: string
srt?: string
verbose?: boolean
}
export async function resolveRunnerConfig(options: RunnerOptions): Promise<RunnerConfig> {
const address = options.url ?? process.env.SHUMAI_API_SERVER
const key = options.key ?? process.env.SHUMAI_RUNNER_KEY
if (!address) throw new CliError('Set SHUMAI_API_SERVER or pass --url.')
if (!key?.trim()) throw new CliError('Set SHUMAI_RUNNER_KEY or pass --key with a runner key.')
let url: URL
try {
url = new URL(address)
} catch {
throw new CliError('Invalid Shumai server URL.')
}
if (
url.username ||
url.password ||
url.search ||
url.hash ||
!['http:', 'https:'].includes(url.protocol)
) {
throw new CliError(
'Use an http:// or https:// server URL without credentials, query, or fragment.',
)
}
const localHosts = ['localhost', '127.0.0.1', '[::1]', 'host.docker.internal']
if (url.protocol === 'http:' && !localHosts.includes(url.hostname)) {
throw new CliError(
'Remote runners require HTTPS. HTTP is only supported for local development.',
)
}
url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
url.pathname = `${url.pathname.replace(/\/+$/, '')}/api/runners/ws`
const cwd = await realpath(path.resolve(options.cwd ?? process.cwd()))
if (!(await stat(cwd)).isDirectory()) throw new CliError('Runner workspace must be a directory.')
return {
url,
key: key.trim(),
cwd,
srt: options.srt ? path.resolve(options.srt) : undefined,
verbose: Boolean(options.verbose),
}
}
/** Commands inherit baseline OS settings and explicitly supplied skill variables, never CLI credentials. */
export function commandEnv(extra: Record<string, string> = {}, inherit = true): NodeJS.ProcessEnv {
const env: NodeJS.ProcessEnv = {}
for (const [key, value] of Object.entries(inherit ? process.env : {})) {
if (
/^(PATH|PATHEXT|HOME|USER|LOGNAME|LANG|TERM|TMPDIR|TEMP|TMP|SYSTEMROOT|SYSTEMDRIVE|COMSPEC|USERPROFILE|USERNAME|APPDATA|LOCALAPPDATA|PROGRAMDATA|PROGRAMFILES|PROGRAMFILES\(X86\)|LC_.*)$/i.test(
key,
)
)
env[key] = value
}
for (const [key, value] of Object.entries(extra)) {
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
throw new Error('Invalid skill environment variable name.')
if (['SHUMAI_RUNNER_KEY', 'SHUMAI_API_KEY'].includes(key.toUpperCase())) continue
// Windows treats environment names as case-insensitive.
for (const existing of Object.keys(env)) {
if (existing.toUpperCase() === key.toUpperCase()) delete env[existing]
}
env[key] = value
}
return env
}
+364
View File
@@ -0,0 +1,364 @@
import { createHash } from 'node:crypto'
import { createServer, type Server } from 'node:http'
import { mkdtemp, mkdir, readFile, readdir, rm, stat, symlink, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
import AdmZip from 'adm-zip'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import yauzl from 'yauzl'
import { RunnerFiles } from './files'
describe('runner workspace file transfers', () => {
let cwd: string
let files: RunnerFiles
let server: Server
let url: string
let body: Buffer
let uploaded: Buffer
beforeEach(async () => {
cwd = await mkdtemp(path.join(tmpdir(), 'shumai-files-test-'))
files = new RunnerFiles(cwd)
body = Buffer.from('download contents')
uploaded = Buffer.alloc(0)
server = createServer(async (request, response) => {
if (request.method === 'PUT') {
const chunks: Buffer[] = []
for await (const chunk of request) chunks.push(Buffer.from(chunk))
uploaded = Buffer.concat(chunks)
response.end()
} else if (request.url === '/slow') {
const timer = setInterval(() => response.write(Buffer.alloc(65536)), 20)
response.once('close', () => clearInterval(timer))
} else if (request.url === '/redirect') {
response.writeHead(302, { location: '/file' })
response.end()
} else response.end(body)
})
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
const address = server.address()
if (!address || typeof address === 'string') throw new Error('Missing test HTTP address')
url = `http://127.0.0.1:${address.port}`
})
afterEach(async () => {
server.closeAllConnections()
await new Promise<void>((resolve) => server.close(() => resolve()))
await rm(cwd, { recursive: true, force: true })
})
const signal = () => new AbortController().signal
it('downloads, checks SHA-256, stats and uploads actual bytes', async () => {
expect(
await files.handle(
{
type: 'file.download',
executionId: 'download',
url,
destPath: '.pi/input/data.bin',
expectedHash: createHash('sha256').update(body).digest('hex'),
},
signal(),
),
).toMatchObject({ ok: true, size: body.length })
expect(await readFile(path.join(cwd, '.pi/input/data.bin'))).toEqual(body)
expect(
await files.handle(
{ type: 'file.stat', executionId: 'stat', srcPath: '.pi/input/data.bin' },
signal(),
),
).toMatchObject({ ok: true, exists: true, isFile: true, size: body.length })
expect(
await files.handle(
{ type: 'file.upload', executionId: 'upload', srcPath: '.pi/input/data.bin', url },
signal(),
),
).toMatchObject({ ok: true, size: body.length, name: 'data.bin' })
expect(uploaded).toEqual(body)
expect(
await files.handle(
{ type: 'file.stat', executionId: 'absent', srcPath: '.pi/absent' },
signal(),
),
).toMatchObject({ ok: true, exists: false })
})
it('does not publish mismatched downloads or follow redirects', async () => {
expect(
await files.handle(
{
type: 'file.download',
executionId: 'bad-hash',
url,
destPath: '.pi/data',
expectedHash: 'bad',
},
signal(),
),
).toMatchObject({ ok: false, error: 'Downloaded file hash does not match.' })
await expect(readFile(path.join(cwd, '.pi/data'))).rejects.toThrow()
expect(
await files.handle(
{
type: 'file.download',
executionId: 'redirect',
url: `${url}/redirect`,
destPath: '.pi/data',
},
signal(),
),
).toHaveProperty('ok', false)
})
it.each([
'../secret',
'/etc/passwd',
'.pi/../secret',
'.pi/dir/../../secret',
'.pi\\secret',
'.pi//file',
'.pi/a:b',
'.pi/a\0b',
'.pi/.. /outside',
'.pi/folder./file',
'.pi/CON.txt',
'.pi/nul .txt',
'.pi/COM1',
'.pi/lpt¹.log',
'.pi/CONOUT$',
])('rejects unsafe protocol path %s', async (srcPath) => {
expect(
await files.handle({ type: 'file.stat', executionId: 'unsafe', srcPath }, signal()),
).toHaveProperty('ok', false)
})
it('rejects parent and final symlinks, including a replaced .pi root', async () => {
await mkdir(path.join(cwd, '.pi'))
await writeFile(path.join(cwd, 'secret'), 'secret')
await symlink(cwd, path.join(cwd, '.pi/escape'))
await symlink(path.join(cwd, 'secret'), path.join(cwd, '.pi/link'))
for (const srcPath of ['.pi/escape/secret', '.pi/link']) {
expect(
await files.handle({ type: 'file.upload', executionId: 'symlink', srcPath, url }, signal()),
).toHaveProperty('ok', false)
}
await rm(path.join(cwd, '.pi'), { recursive: true })
await symlink(cwd, path.join(cwd, '.pi'))
expect(
await files.handle(
{ type: 'file.download', executionId: 'root', destPath: '.pi/file', url },
signal(),
),
).toHaveProperty('ok', false)
})
it('extracts skills and safely replaces old contents', async () => {
const zip = new AdmZip()
zip.addFile('SKILL.md', Buffer.from('# Test skill'))
zip.addFile('scripts/run.sh', Buffer.from('echo skill'))
body = zip.toBuffer()
for (let attempt = 0; attempt < 2; attempt++) {
expect(
await files.handle(
{
type: 'file.download',
executionId: `zip-${attempt}`,
url,
destPath: '.pi/skills/test',
extractZip: true,
},
signal(),
),
).toHaveProperty('ok', true)
}
expect(await readFile(path.join(cwd, '.pi/skills/test/SKILL.md'), 'utf8')).toBe('# Test skill')
})
it('rejects symlink ZIP entries and zip-slip paths without publishing them', async () => {
const zip = new AdmZip()
zip.addFile('link', Buffer.from('/etc/passwd'))
const entry = zip.getEntry('link')!
entry.header.attr = (0o120777 << 16) >>> 0
body = zip.toBuffer()
expect(
await files.handle(
{
type: 'file.download',
executionId: 'zip-link',
url,
destPath: '.pi/skills/bad',
extractZip: true,
},
signal(),
),
).toHaveProperty('ok', false)
const normal = new AdmZip()
normal.addFile('aa/secret', Buffer.from('escape'))
body = Buffer.from(
normal.toBuffer().toString('latin1').replaceAll('aa/secret', '../secret'),
'latin1',
)
expect(
await files.handle(
{
type: 'file.download',
executionId: 'zip-slip',
url,
destPath: '.pi/skills/bad',
extractZip: true,
},
signal(),
),
).toHaveProperty('ok', false)
await expect(readFile(path.join(cwd, '.pi/skills/bad/link'))).rejects.toThrow()
})
it('preserves executable script permissions and rejects oversized ZIP entries', async () => {
const zip = new AdmZip()
zip.addFile('run.sh', Buffer.from('#!/bin/sh\necho executable\n'))
zip.getEntry('run.sh')!.header.attr = (0o100755 << 16) >>> 0
body = zip.toBuffer()
expect(
await files.handle(
{
type: 'file.download',
executionId: 'exec-zip',
url,
destPath: '.pi/skills/executable',
extractZip: true,
},
signal(),
),
).toHaveProperty('ok', true)
expect((await stat(path.join(cwd, '.pi/skills/executable/run.sh'))).mode & 0o7777).toBe(0o755)
const central = body.indexOf(Buffer.from([0x50, 0x4b, 0x01, 0x02]))
body.writeUInt32LE(256 * 1024 * 1024 + 1, central + 24)
expect(
await files.handle(
{
type: 'file.download',
executionId: 'large-zip',
url,
destPath: '.pi/skills/large',
extractZip: true,
},
signal(),
),
).toMatchObject({ ok: false, error: 'Extracted ZIP exceeds 256 MiB.' })
})
it('cancels a streaming download without publishing partial bytes or leaving staging files', async () => {
await mkdir(path.join(cwd, '.pi/input'), { recursive: true })
await writeFile(path.join(cwd, '.pi/input/data'), 'original')
const controller = new AbortController()
const transfer = files.handle(
{
type: 'file.download',
executionId: 'stream-cancel',
url: `${url}/slow`,
destPath: '.pi/input/data',
},
controller.signal,
)
await vi.waitFor(async () =>
expect(
(await readdir(path.join(cwd, '.pi/input'))).some((name) => name.startsWith('.shumai-')),
).toBe(true),
)
controller.abort()
expect(await transfer).toHaveProperty('ok', false)
expect(await readFile(path.join(cwd, '.pi/input/data'), 'utf8')).toBe('original')
expect(await readdir(path.join(cwd, '.pi/input'))).toEqual(['data'])
})
it('cancels extraction without deleting the installed skill or leaving staging trees', async () => {
await mkdir(path.join(cwd, '.pi/skills/installed'), { recursive: true })
await writeFile(path.join(cwd, '.pi/skills/installed/SKILL.md'), 'original')
const zip = new AdmZip()
for (let index = 0; index < 2000; index++)
zip.addFile(`file-${index}.txt`, Buffer.alloc(32768, 65))
body = zip.toBuffer()
const controller = new AbortController()
const transfer = files.handle(
{
type: 'file.download',
executionId: 'extract-cancel',
url,
destPath: '.pi/skills/installed',
extractZip: true,
},
controller.signal,
)
await vi.waitFor(
async () => {
const temporary = (await readdir(path.join(cwd, '.pi/skills'))).find((name) =>
name.startsWith('.shumai-'),
)
expect(temporary).toBeDefined()
expect(
(await readdir(path.join(cwd, '.pi/skills', temporary!, 'extracted'))).length,
).toBeGreaterThan(0)
},
{ interval: 5, timeout: 5000 },
)
controller.abort()
expect(await transfer).toHaveProperty('ok', false)
expect(await readFile(path.join(cwd, '.pi/skills/installed/SKILL.md'), 'utf8')).toBe('original')
expect(await readdir(path.join(cwd, '.pi/skills'))).toEqual(['installed'])
}, 10000)
it('waits for an in-flight ZIP entry read before closing on cancellation', async () => {
const zip = new AdmZip()
zip.addFile('SKILL.md', Buffer.from('skill'))
body = zip.toBuffer()
const controller = new AbortController()
const pendingRead = Promise.withResolvers<() => void>()
const readEntry = yauzl.ZipFile.prototype.readEntry
const read = vi.spyOn(yauzl.ZipFile.prototype, 'readEntry').mockImplementationOnce(function (
this: yauzl.ZipFile,
) {
pendingRead.resolve(() => readEntry.call(this))
})
const close = vi.spyOn(yauzl.ZipFile.prototype, 'close')
try {
const transfer = files.handle(
{
type: 'file.download',
executionId: 'zip-entry-cancel',
url,
destPath: '.pi/skills/new',
extractZip: true,
},
controller.signal,
)
const finishRead = await pendingRead.promise
controller.abort()
await new Promise<void>((resolve) => setImmediate(resolve))
const closedDuringRead = close.mock.calls.length > 0
if (!closedDuringRead) finishRead()
expect(await transfer).toHaveProperty('ok', false)
expect(closedDuringRead).toBe(false)
expect(await readdir(path.join(cwd, '.pi/skills'))).toEqual([])
} finally {
read.mockRestore()
close.mockRestore()
}
})
it('handles cancelled transfers and refuses uploads of directories', async () => {
const controller = new AbortController()
controller.abort()
expect(
await files.handle(
{ type: 'file.download', executionId: 'cancelled', url, destPath: '.pi/data' },
controller.signal,
),
).toHaveProperty('ok', false)
expect(
await files.handle(
{ type: 'file.upload', executionId: 'directory', url, srcPath: '.pi/transfers' },
signal(),
),
).toHaveProperty('ok', false)
expect(uploaded).toHaveLength(0)
})
})
+282
View File
@@ -0,0 +1,282 @@
import { createHash } from 'node:crypto'
import { constants, createWriteStream } from 'node:fs'
import { lstat, mkdir, mkdtemp, open, rename, rm } from 'node:fs/promises'
import path from 'node:path'
import { Readable, Transform } from 'node:stream'
import { pipeline } from 'node:stream/promises'
import yauzl from 'yauzl'
import type {
RunnerFileDownloadMessage,
RunnerFileUploadMessage,
RunnerFileStatMessage,
RunnerToServerMessage,
} from '@shumai/dtos'
const MAX_FILE_BYTES = 256 * 1024 * 1024
const MAX_ZIP_ENTRIES = 10_000
export type FileMessage =
RunnerFileDownloadMessage | RunnerFileUploadMessage | RunnerFileStatMessage
function pathParts(value: string): string[] {
const parts = value.split('/')
if (
value.includes('\\') ||
value.includes('\0') ||
parts.some(
(part) =>
!part ||
part === '.' ||
part === '..' ||
part.includes(':') ||
/[. ]$/.test(part) ||
/^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³])(?: *\.|$)/i.test(part),
)
)
throw new Error('Invalid workspace path.')
return parts
}
function isMissing(error: unknown): boolean {
return error instanceof Error && 'code' in error && error.code === 'ENOENT'
}
function transferUrl(address: string): URL {
const url = new URL(address)
if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
throw new Error('Invalid transfer URL.')
return url
}
export class RunnerFiles {
constructor(readonly cwd: string) {}
/** Basic workspace validation. Concurrent hostile filesystem mutation is outside v1's scope. */
private async resolve(relative: string, createParents = false): Promise<string> {
const parts = pathParts(relative)
if (parts[0] !== '.pi' || parts.length < 2) throw new Error('File paths must stay inside .pi/.')
let current = this.cwd
for (let index = 0; index < parts.length; index++) {
current = path.join(current, parts[index])
const parent = index < parts.length - 1
if (parent && createParents) await mkdir(current, { recursive: true, mode: 0o700 })
try {
const info = await lstat(current)
if (info.isSymbolicLink() || (parent && !info.isDirectory()))
throw new Error('Workspace paths cannot contain symlinks or non-directory parents.')
} catch (error) {
if (!isMissing(error)) throw error
}
}
return current
}
async createWriter(relative: string) {
const file = await open(
await this.resolve(relative, true),
constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
0o600,
)
return {
write: async (data: string) => {
await file.writeFile(data)
},
close: () => file.close(),
}
}
async handle(message: FileMessage, signal: AbortSignal): Promise<RunnerToServerMessage> {
try {
signal.throwIfAborted()
if (message.type === 'file.download')
return {
type: 'file.download.result',
executionId: message.executionId,
ok: true,
...(await this.download(message, signal)),
}
const filename = await this.resolve(message.srcPath)
if (message.type === 'file.upload') return await this.upload(message, filename, signal)
try {
const info = await lstat(filename)
return {
type: 'file.stat.result',
executionId: message.executionId,
ok: true,
exists: true,
isFile: info.isFile(),
size: info.size,
name: path.basename(filename),
}
} catch (error) {
if (!isMissing(error)) throw error
return {
type: 'file.stat.result',
executionId: message.executionId,
ok: true,
exists: false,
}
}
} catch (error) {
const result = {
executionId: message.executionId,
ok: false,
error: error instanceof Error ? error.message : 'File operation failed.',
}
switch (message.type) {
case 'file.download':
return { ...result, type: 'file.download.result' }
case 'file.upload':
return { ...result, type: 'file.upload.result' }
case 'file.stat':
return { ...result, type: 'file.stat.result', exists: false }
}
}
}
private async upload(
message: RunnerFileUploadMessage,
filename: string,
signal: AbortSignal,
): Promise<RunnerToServerMessage> {
const file = await open(
filename,
constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
)
try {
const info = await file.stat()
if (!info.isFile() || info.size > MAX_FILE_BYTES)
throw new Error('Upload must be a regular file no larger than 256 MiB.')
// Node and Bun declare different DOM stream types for the same fetch-compatible stream.
const body = info.size
? (Readable.toWeb(
file.createReadStream({ autoClose: false, end: info.size - 1 }),
) as unknown as ReadableStream<Uint8Array>)
: new Uint8Array()
const response = await fetch(transferUrl(message.url), {
method: 'PUT',
body,
...{ duplex: 'half' },
headers: {
'content-type': message.contentType ?? 'application/octet-stream',
'content-length': String(info.size),
},
signal,
redirect: 'error',
})
await response.body?.cancel()
if (!response.ok) throw new Error(`Upload failed (HTTP ${response.status}).`)
return {
type: 'file.upload.result',
executionId: message.executionId,
ok: true,
size: info.size,
name: path.basename(filename),
}
} finally {
await file.close()
}
}
private async download(message: RunnerFileDownloadMessage, signal: AbortSignal) {
const destination = await this.resolve(message.destPath, true)
const temporary = await mkdtemp(path.join(path.dirname(destination), '.shumai-'))
let preserveBackup = false
try {
const response = await fetch(transferUrl(message.url), { signal, redirect: 'error' })
if (!response.ok || !response.body) {
await response.body?.cancel()
throw new Error(`Download failed (HTTP ${response.status}).`)
}
const hash = createHash('sha256')
let size = 0
const archive = path.join(temporary, 'download')
await pipeline(
response.body,
new Transform({
transform(chunk: Buffer, _encoding, callback) {
size += chunk.length
if (size > MAX_FILE_BYTES) {
callback(new Error('Download exceeds 256 MiB.'))
return
}
hash.update(chunk)
callback(null, chunk)
},
}),
createWriteStream(archive, { flags: 'wx', mode: 0o600 }),
{ signal },
)
if (message.expectedHash && hash.digest('hex') !== message.expectedHash)
throw new Error('Downloaded file hash does not match.')
let source = archive
if (message.extractZip) {
source = path.join(temporary, 'extracted')
await mkdir(source, { mode: 0o700 })
await this.extract(archive, source, signal)
}
signal.throwIfAborted()
await this.resolve(message.destPath)
if (message.extractZip) {
const backup = path.join(temporary, 'previous')
let backedUp = false
try {
await rename(destination, backup)
backedUp = true
} catch (error) {
if (!isMissing(error)) throw error
}
try {
await rename(source, destination)
} catch (error) {
if (backedUp) {
preserveBackup = true
await rename(backup, destination)
preserveBackup = false
}
throw error
}
} else await rename(source, destination)
return { size, cached: false }
} finally {
if (!preserveBackup) await rm(temporary, { recursive: true, force: true })
}
}
private async extract(archive: string, directory: string, signal: AbortSignal) {
const zip = await yauzl.openPromise(archive, {
lazyEntries: true,
strictFileNames: true,
autoClose: false,
})
let size = 0
let count = 0
try {
signal.throwIfAborted()
// Let each metadata read finish before cancellation can close the ZIP descriptor.
for await (const entry of zip.eachEntry()) {
signal.throwIfAborted()
if (++count > MAX_ZIP_ENTRIES) throw new Error('ZIP contains too many entries.')
const parts = pathParts(entry.fileName.replace(/\/$/, ''))
const mode = entry.externalFileAttributes >>> 16
const kind = mode & 0o170000
if (kind && kind !== 0o100000 && kind !== 0o040000)
throw new Error('ZIP links and special files are forbidden.')
size += entry.uncompressedSize
if (size > MAX_FILE_BYTES) throw new Error('Extracted ZIP exceeds 256 MiB.')
const destination = path.join(directory, ...parts)
if (entry.fileName.endsWith('/')) await mkdir(destination, { recursive: true, mode: 0o700 })
else {
await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 })
const input = await zip.openReadStreamPromise(entry)
await pipeline(
input,
createWriteStream(destination, { flags: 'wx', mode: 0o600 | (mode & 0o155) }),
{ signal },
)
}
}
} finally {
zip.close()
}
}
}
+44
View File
@@ -0,0 +1,44 @@
import { describe, expect, it } from 'vitest'
import {
createRunnerLogger,
formatBytes,
formatDuration,
formatLogString,
formatTimestamp,
shortId,
} from './log'
describe('runner log helpers', () => {
it('formats timestamps and aligned log levels', () => {
const fixed = new Date(2026, 0, 1, 9, 4, 5)
expect(formatTimestamp(fixed)).toBe('09:04:05')
const lines: string[] = []
const logger = createRunnerLogger(
(line) => lines.push(line),
false,
() => fixed,
)
logger.info('Bash started [a8f2]')
logger.warn('Runner disconnected; reconnecting…')
logger.error('Fatal error')
expect(lines).toEqual([
'09:04:05 INFO Bash started [a8f2]',
'09:04:05 WARN Runner disconnected; reconnecting…',
'09:04:05 ERROR Fatal error',
])
})
it('formats short IDs, durations, byte counts, and single-line quoted strings', () => {
expect(shortId('01JABCDEF1234567890A8F2')).toBe('a8f2')
expect(shortId('one')).toBe('one')
expect(formatDuration(1840)).toBe('1.8s')
expect(formatDuration(-10)).toBe('0.0s')
expect(formatBytes(0)).toBe('0')
expect(formatBytes(512)).toBe('512B')
expect(formatBytes(1536)).toBe('1.5KB')
expect(formatBytes(12 * 1024)).toBe('12KB')
expect(formatBytes(Math.round(2.4 * 1024 * 1024))).toBe('2.4MB')
expect(formatLogString('echo "hi"\nls')).toBe('"echo \\"hi\\"\\nls"')
expect(formatLogString('x'.repeat(210))).toBe(`"${'x'.repeat(200)}…"`)
})
})
+59
View File
@@ -0,0 +1,59 @@
export type RunnerLogLevel = 'INFO' | 'WARN' | 'ERROR'
export interface RunnerLogger {
readonly verbose: boolean
info(message: string): void
warn(message: string): void
error(message: string): void
}
/** Formats a local wall-clock timestamp as HH:MM:SS for runner stderr logs. */
export function formatTimestamp(date = new Date()): string {
const pad = (value: number) => String(value).padStart(2, '0')
return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
}
/** Builds a prefixed runner logger writing uniform timestamped lines to stderr. */
export function createRunnerLogger(
write: (message: string) => void = console.error,
verbose = false,
now: () => Date = () => new Date(),
): RunnerLogger {
const emit = (level: RunnerLogLevel, message: string) => {
write(`${formatTimestamp(now())} ${level.padEnd(5)} ${message}`)
}
return {
verbose,
info: (message) => emit('INFO', message),
warn: (message) => emit('WARN', message),
error: (message) => emit('ERROR', message),
}
}
/** Extracts the trailing 4-character tail of an execution ID for compact log labels. */
export function shortId(executionId: string): string {
return executionId.slice(-4).toLowerCase()
}
/** Formats a millisecond duration as seconds with one decimal place (e.g. `1.8s`). */
export function formatDuration(ms: number): string {
return `${(Math.max(0, ms) / 1000).toFixed(1)}s`
}
/** Formats a byte count concisely for runner logs (`0`, `128B`, `12KB`, `2.4MB`). */
export function formatBytes(bytes: number): string {
if (bytes <= 0) return '0'
if (bytes < 1024) return `${bytes}B`
if (bytes < 1024 * 1024) {
const kb = bytes / 1024
return kb < 10 ? `${kb.toFixed(1).replace(/\.0$/, '')}KB` : `${Math.round(kb)}KB`
}
const mb = bytes / (1024 * 1024)
return `${mb.toFixed(1).replace(/\.0$/, '')}MB`
}
/** Formats an arbitrary string (command, path, error) as a bounded single-line JSON string. */
export function formatLogString(value: string, maxLength = 200): string {
const text = value.length > maxLength ? `${value.slice(0, maxLength)}…` : value
return JSON.stringify(text)
}
+106
View File
@@ -0,0 +1,106 @@
import { spawnSync, type SpawnSyncReturns } from 'node:child_process'
import { accessSync, constants } from 'node:fs'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { resolveRunnerShell } from './shell-config'
vi.mock('node:child_process', () => ({ spawnSync: vi.fn() }))
vi.mock('node:fs', { spy: true })
const access = vi.mocked(accessSync)
const where = vi.mocked(spawnSync)
const gitBash = 'D:\\Program Files\\Git\\bin\\bash.exe'
const gitBashX86 = 'D:\\Program Files (x86)\\Git\\bin\\bash.exe'
function whereResult(stdout = '', status = 0): SpawnSyncReturns<string> {
return { stdout, stderr: '', status, output: [null, stdout, ''], pid: 1, signal: null }
}
function available(...paths: string[]) {
access.mockImplementation((executable) => {
if (!paths.some((path) => executable === path)) throw new Error('File not found')
})
}
beforeEach(() => {
vi.stubEnv('ProgramFiles', 'D:\\Program Files')
vi.stubEnv('ProgramFiles(x86)', 'D:\\Program Files (x86)')
vi.stubEnv('SystemRoot', 'E:\\WinNT')
available()
where.mockReturnValue(whereResult('', 1))
})
afterEach(() => {
vi.resetAllMocks()
vi.unstubAllEnvs()
})
describe('runner shell selection', () => {
it.each(['linux', 'darwin'] as const)('uses /bin/sh on %s', (platform) => {
expect(resolveRunnerShell(platform)).toEqual({
executable: '/bin/sh',
commandTransport: 'shell',
})
expect(where).not.toHaveBeenCalled()
})
it.each([
[gitBash, [gitBash, gitBashX86]],
[gitBashX86, [gitBashX86]],
] as const)('prefers installed Git Bash at %s before PATH', (executable, paths) => {
available(...paths)
expect(resolveRunnerShell('win32')).toEqual({ executable, commandTransport: 'argv' })
expect(where).not.toHaveBeenCalled()
})
// Adapted from Pi's shell-path-exists.test.ts. See apps/cli/THIRD-PARTY-NOTICES.txt.
it('accepts a Windows Store Bash alias found on PATH via access(F_OK)', () => {
const alias = 'D:\\Users\\runner\\AppData\\Local\\Microsoft\\WindowsApps\\bash.exe'
available(alias)
where.mockReturnValue(whereResult(alias + '\r\n'))
expect(resolveRunnerShell('win32')).toEqual({ executable: alias, commandTransport: 'argv' })
expect(access).toHaveBeenCalledWith(alias, constants.F_OK)
expect(where).toHaveBeenCalledWith('E:\\WinNT\\System32\\where.exe', ['$PATH:bash.exe'], {
encoding: 'utf8',
timeout: 5000,
windowsHide: true,
})
})
it('skips relative and inaccessible PATH results', () => {
const executable = 'D:\\MSYS2\\usr\\bin\\bash.exe'
available(executable)
where.mockReturnValue(
whereResult(['bash.exe', 'D:\\missing\\bash.exe', executable].join('\r\n')),
)
expect(resolveRunnerShell('win32')).toEqual({ executable, commandTransport: 'argv' })
})
it.each([
['E:\\WinNT', 'E:\\WinNT\\System32\\cmd.exe'],
[undefined, 'C:\\Windows\\System32\\cmd.exe'],
] as const)(
'falls back to cmd.exe when no Bash is available (SystemRoot %s)',
(root, executable) => {
vi.stubEnv('SystemRoot', root)
expect(resolveRunnerShell('win32')).toEqual({ executable, commandTransport: 'shell' })
},
)
// Adapted from Pi's windows-shell-config.test.ts.
it.each([
['D:\\WinNT\\', 'd:/WINNT/System32/BASH.EXE', 'stdin'],
['D:\\WinNT', 'D:\\WinNT\\Sysnative\\bash.exe', 'stdin'],
[undefined, 'E:\\Windows\\System32\\bash.exe', 'stdin'],
['D:\\WinNT', 'D:\\Git\\bin\\bash.exe', 'argv'],
['D:\\WinNT', 'E:\\Windows\\System32\\bash.exe', 'argv'],
['WinNT', 'C:\\Windows\\System32\\bash.exe', 'argv'],
] as const)(
'uses the correct command transport for SystemRoot %s and %s',
(root, executable, commandTransport) => {
vi.stubEnv('SystemRoot', root)
available(executable)
where.mockReturnValue(whereResult(executable + '\r\n'))
expect(resolveRunnerShell('win32')).toEqual({ executable, commandTransport })
},
)
})
+64
View File
@@ -0,0 +1,64 @@
import { spawnSync } from 'node:child_process'
import { accessSync, constants } from 'node:fs'
import { win32 } from 'node:path'
export interface RunnerShellConfig {
executable: string
commandTransport: 'shell' | 'argv' | 'stdin'
}
// Windows Bash discovery and legacy WSL detection adapted from pi-mono.
// See apps/cli/THIRD-PARTY-NOTICES.txt.
function isLegacyWslBashPath(executable: string, systemRoot: string | undefined): boolean {
const normalized = win32.normalize(executable).toLowerCase()
if (systemRoot) {
if (!/^[a-z]:[\\/]/i.test(systemRoot)) return false
return ['System32', 'Sysnative'].some(
(directory) => normalized === win32.join(systemRoot, directory, 'bash.exe').toLowerCase(),
)
}
return /^[a-z]:\\windows\\(?:system32|sysnative)\\bash\.exe$/.test(normalized)
}
function shellPathExists(executable: string): boolean {
// access(F_OK) accepts runnable Windows Store aliases that fail an extra stat check.
try {
accessSync(executable, constants.F_OK)
return true
} catch {
return false
}
}
function findWindowsBash(system32: string): string | undefined {
for (const directory of [process.env.ProgramFiles, process.env['ProgramFiles(x86)']]) {
if (!directory || !win32.isAbsolute(directory)) continue
const executable = win32.join(directory, 'Git', 'bin', 'bash.exe')
if (shellPathExists(executable)) return executable
}
// Use the system tool and limit its search to PATH. The workspace may contain a bash.exe.
const found = spawnSync(win32.join(system32, 'where.exe'), ['$PATH:bash.exe'], {
encoding: 'utf8',
timeout: 5000,
windowsHide: true,
})
if (found.status !== 0 || !found.stdout) return
return found.stdout
.trim()
.split(/\r?\n/)
.find((executable) => win32.isAbsolute(executable) && shellPathExists(executable))
}
export function resolveRunnerShell(platform = process.platform): RunnerShellConfig {
if (platform !== 'win32') return { executable: '/bin/sh', commandTransport: 'shell' }
const systemRoot = process.env.SystemRoot
const system32 = win32.join(systemRoot ?? 'C:\\Windows', 'System32')
const executable = findWindowsBash(system32)
if (!executable) return { executable: win32.join(system32, 'cmd.exe'), commandTransport: 'shell' }
return {
executable,
commandTransport: isLegacyWslBashPath(executable, systemRoot) ? 'stdin' : 'argv',
}
}
+352
View File
@@ -0,0 +1,352 @@
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { SandboxManager } from '@anthropic-ai/sandbox-runtime'
import { RunnerFiles } from './files'
import { RunnerShell } from './shell'
describe('runner bash execution', () => {
let cwd: string
let shell: RunnerShell
beforeEach(async () => {
cwd = await mkdtemp(path.join(tmpdir(), 'shumai-shell-test-'))
shell = new RunnerShell(new RunnerFiles(cwd))
vi.spyOn(SandboxManager, 'initialize').mockResolvedValue()
vi.spyOn(SandboxManager, 'reset').mockResolvedValue()
vi.spyOn(SandboxManager, 'wrapWithSandboxArgv').mockImplementation(async (command) => ({
argv: ['/bin/sh', '-c', command],
env: process.env,
}))
})
afterEach(async () => {
await shell.close()
vi.restoreAllMocks()
vi.unstubAllEnvs()
await rm(cwd, { recursive: true, force: true })
})
const request = (command: string, executionId = 'test') => ({
type: 'exec.start' as const,
executionId,
command,
})
it('runs with no executables on PATH when SRT is not requested', async () => {
vi.stubEnv('PATH', '')
await shell.initialize()
let output = ''
const result = await shell.run(
request('printf no-extra-runtime'),
new AbortController().signal,
(_stream, data) => {
output += data
},
)
expect(result).toMatchObject({ exitCode: 0 })
expect(output).toBe('no-extra-runtime')
})
// Adapted from Pi's tools.test.ts. See apps/cli/THIRD-PARTY-NOTICES.txt.
it('sends the complete command over stdin for the legacy Bash launcher', async () => {
shell = new RunnerShell(new RunnerFiles(cwd), undefined, {
executable: '/bin/sh',
commandTransport: 'stdin',
})
const command = [
'name="Hello, 世界"',
'for choice in "one two" \'three "four"\'; do',
' printf \'%s / %s\\n\' "$name" "$choice"',
'done',
].join('\n')
let output = ''
const result = await shell.run(
request(command),
new AbortController().signal,
(_stream, data) => {
output += data
},
)
expect(result).toMatchObject({ exitCode: 0 })
expect(output).toBe('Hello, 世界 / one two\nHello, 世界 / three "four"\n')
})
it('passes a command with shell quoting directly to the selected executable', async () => {
shell = new RunnerShell(new RunnerFiles(cwd), undefined, {
executable: '/bin/sh',
commandTransport: 'argv',
})
const command = "printf '%s' '$literal \"quotes\"'"
let output = ''
const result = await shell.run(
request(command),
new AbortController().signal,
(_stream, data) => {
output += data
},
)
expect(result).toMatchObject({ exitCode: 0 })
expect(output).toBe('$literal "quotes"')
})
it('rejects the legacy WSL launcher before starting SRT', async () => {
shell = new RunnerShell(new RunnerFiles(cwd), path.join(cwd, 'sandbox.json'), {
executable: 'C:\\Windows\\System32\\bash.exe',
commandTransport: 'stdin',
})
await expect(shell.initialize()).rejects.toThrow('SRT cannot run the legacy WSL Bash launcher')
expect(SandboxManager.initialize).not.toHaveBeenCalled()
})
it('streams both outputs, returns the exit code, and saves a log in the runner workspace', async () => {
const output: string[] = []
const result = await shell.run(
request('printf "hello 世界"; printf "failure" >&2; exit 7'),
new AbortController().signal,
(stream, data) => output.push(`${stream}:${data}`),
)
expect(result).toMatchObject({
exitCode: 7,
signal: null,
timedOut: false,
fullOutputPath: '.pi/logs/bash-test.log',
})
expect(output.join('|')).toContain('stdout:hello 世界')
expect(output.join('|')).toContain('stderr:failure')
expect(await readFile(path.join(cwd, result.fullOutputPath!), 'utf8')).toContain('hello 世界')
})
it('passes skill env without inheriting runner or unrelated credentials', async () => {
vi.stubEnv('SHUMAI_RUNNER_KEY', 'runner-secret')
vi.stubEnv('AWS_SECRET_ACCESS_KEY', 'aws-secret')
let output = ''
await shell.run(
{
...request(
'printf "%s|%s|%s" "$SKILL_TOKEN" "$SHUMAI_RUNNER_KEY" "$AWS_SECRET_ACCESS_KEY"',
),
env: { SKILL_TOKEN: 'skill-secret' },
},
new AbortController().signal,
(_stream, data) => {
output += data
},
)
expect(output).toBe('skill-secret||')
})
it('times out and terminates background children', async () => {
const result = await shell.run(
{ ...request('sleep 30 & echo $!; wait'), timeoutSec: 0.1 },
new AbortController().signal,
() => {},
)
expect(result).toMatchObject({ timedOut: true, signal: 'SIGKILL' })
const pid = Number((await readFile(path.join(cwd, '.pi/logs/bash-test.log'), 'utf8')).trim())
expect(() => process.kill(pid, 0)).toThrow()
})
it('cancels a running command and never starts an already cancelled one', async () => {
const controller = new AbortController()
const running = shell.run(request('echo ready; sleep 30'), controller.signal, () =>
controller.abort(),
)
expect(await running).toMatchObject({ aborted: true, signal: 'SIGKILL' })
expect(
await shell.run(request('touch unwanted', 'cancelled'), controller.signal, () => {}),
).toMatchObject({ aborted: true })
await expect(readFile(path.join(cwd, 'unwanted'))).rejects.toThrow()
})
it('finishes draining after a timely root exit even if a background process holds the pipes', async () => {
const source = `const {spawn} = require('node:child_process'); const child = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 30000)'], {detached: true, stdio: ['ignore', 1, 2]}); console.log(child.pid); child.unref()`
const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`
const result = await shell.run(
{ ...request(`${quote(process.execPath)} -e ${quote(source)}`), timeoutSec: 0.5 },
new AbortController().signal,
() => {},
)
const pid = Number((await readFile(path.join(cwd, '.pi/logs/bash-test.log'), 'utf8')).trim())
try {
expect(result).toMatchObject({ exitCode: 0, timedOut: false, aborted: false })
expect(result.error).toBeUndefined()
} finally {
if (pid > 0) process.kill(pid, 'SIGKILL')
}
})
it('reports launch failure without including command text or skill secrets', async () => {
shell = new RunnerShell(new RunnerFiles(cwd), undefined, {
executable: path.join(cwd, 'missing-shell'),
commandTransport: 'shell',
})
const result = await shell.run(
request('echo private-command'),
new AbortController().signal,
() => {},
)
expect(result).toMatchObject({
exitCode: null,
signal: null,
error: 'Command execution failed (ENOENT).',
})
expect(result.error).not.toContain('private-command')
})
it('terminates a running process if the output consumer fails', async () => {
let pid = 0
const result = await shell.run(
request('printf "%s\\n" "$$"; sleep 30'),
new AbortController().signal,
(_stream, data) => {
pid = Number(data.trim())
throw new Error('Output consumer failed')
},
)
expect(result.error).toBe('Output consumer failed')
expect(pid).toBeGreaterThan(0)
expect(() => process.kill(pid, 0)).toThrow()
})
it('rejects invalid timeouts and caps runaway output', async () => {
expect(
await shell.run(
{ ...request('sleep 30'), timeoutSec: -1 },
new AbortController().signal,
() => {},
),
).toHaveProperty('error')
expect(
await shell.run(
request('head -c 70000000 /dev/zero', 'large'),
new AbortController().signal,
() => {},
),
).toMatchObject({ error: 'Command exceeded the 64 MiB output limit.' })
})
it('uses the exact SRT JSON snapshot and validates SRT before connecting', async () => {
const settings = path.join(cwd, 'sandbox.json')
const config = {
network: { allowedDomains: [], deniedDomains: [] },
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
}
const json = JSON.stringify(config)
await writeFile(settings, json)
vi.stubEnv('PATH', '')
shell = new RunnerShell(new RunnerFiles(cwd), settings)
await shell.initialize()
await writeFile(settings, '{}')
expect(
await shell.run(request('echo sandboxed'), new AbortController().signal, () => {}),
).toMatchObject({ exitCode: 0 })
expect(SandboxManager.initialize).toHaveBeenCalledExactlyOnceWith(
expect.objectContaining(config),
)
expect(SandboxManager.wrapWithSandboxArgv).toHaveBeenCalledWith(
expect.stringContaining('echo sandboxed'),
'/bin/sh',
undefined,
expect.any(AbortSignal),
cwd,
{ commandId: 'test', commandText: 'echo sandboxed' },
)
expect(SandboxManager.reset).not.toHaveBeenCalled()
})
it('keeps skill PATH and Node startup settings out of the SRT launcher', async () => {
const settings = path.join(cwd, 'sandbox.json')
const marker = path.join(cwd, 'injected')
const evil = path.join(cwd, 'evil.cjs')
await writeFile(
settings,
JSON.stringify({
network: { allowedDomains: [], deniedDomains: [] },
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
}),
)
await writeFile(evil, `require('node:fs').writeFileSync('${marker}', 'escaped')`)
shell = new RunnerShell(new RunnerFiles(cwd), settings)
await shell.initialize()
const result = await shell.run(
{
...request('printf secure'),
env: { PATH: '/evil-srt', NODE_OPTIONS: `--require=${evil}` },
},
new AbortController().signal,
() => {},
)
expect(result).toMatchObject({ exitCode: 0 })
await expect(readFile(marker)).rejects.toThrow()
})
it('initializes one sandbox for parallel commands and resets only at shutdown', async () => {
const settings = path.join(cwd, 'sandbox.json')
await writeFile(
settings,
JSON.stringify({
network: { allowedDomains: [], deniedDomains: [] },
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
}),
)
shell = new RunnerShell(new RunnerFiles(cwd), settings)
await shell.initialize()
const value = "quoted ' value\n$(echo should-not-expand)"
let output = ''
const results = await Promise.all(
['one', 'two'].map((id) =>
shell.run(
{ ...request('printf "%s" "$SKILL_TOKEN"', id), env: { SKILL_TOKEN: value } },
new AbortController().signal,
(_stream, data) => {
output += data
},
),
),
)
expect(results.every((result) => result.exitCode === 0)).toBe(true)
expect(output).toBe(value.repeat(2))
expect(SandboxManager.initialize).toHaveBeenCalledTimes(1)
expect(SandboxManager.reset).not.toHaveBeenCalled()
await shell.close()
expect(SandboxManager.reset).toHaveBeenCalledTimes(1)
})
it('fails startup and cleans up if sandbox initialization or execution fails', async () => {
const settings = path.join(cwd, 'sandbox.json')
await writeFile(
settings,
JSON.stringify({
network: { allowedDomains: [], deniedDomains: [] },
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
}),
)
shell = new RunnerShell(new RunnerFiles(cwd), settings)
vi.mocked(SandboxManager.initialize).mockRejectedValueOnce(
new Error('Run windows-install first'),
)
await expect(shell.initialize()).rejects.toThrow('windows-install')
expect(SandboxManager.reset).toHaveBeenCalledTimes(1)
expect(
await shell.run(request('echo unsafe'), new AbortController().signal, () => {}),
).toHaveProperty('error', 'SRT has not been initialized.')
vi.mocked(SandboxManager.wrapWithSandboxArgv).mockRejectedValueOnce(
new Error('sandbox unavailable'),
)
await expect(shell.initialize()).rejects.toThrow('SRT preflight failed: sandbox unavailable')
})
it('fails closed for missing or malformed SRT settings', async () => {
const settings = path.join(cwd, 'sandbox.json')
await expect(new RunnerShell(new RunnerFiles(cwd), settings).initialize()).rejects.toThrow()
await writeFile(settings, 'invalid json')
await expect(new RunnerShell(new RunnerFiles(cwd), settings).initialize()).rejects.toThrow()
await writeFile(settings, '[]')
await expect(new RunnerShell(new RunnerFiles(cwd), settings).initialize()).rejects.toThrow(
/object/,
)
await writeFile(settings, JSON.stringify({ network: { allowedDomains: 42 } }))
await expect(new RunnerShell(new RunnerFiles(cwd), settings).initialize()).rejects.toThrow()
expect(SandboxManager.initialize).not.toHaveBeenCalled()
})
})
+232
View File
@@ -0,0 +1,232 @@
import { randomUUID } from 'node:crypto'
import { execa } from 'execa'
import { SandboxManager } from '@anthropic-ai/sandbox-runtime'
import {
runnerEnvironmentSchema,
type RunnerEnvironment,
type RunnerExecResultMessage,
type RunnerExecStartMessage,
} from '@shumai/dtos'
import { commandEnv } from './config'
import { RunnerFiles } from './files'
import { resolveRunnerShell } from './shell-config'
import { loadSandbox } from './srt'
const MAX_OUTPUT_BYTES = 64 * 1024 * 1024
const MAX_TIMEOUT_SEC = 3600
export class RunnerShell {
readonly environment: RunnerEnvironment
private sandbox?: Awaited<ReturnType<typeof loadSandbox>>
private initialized = false
private active = 0
constructor(
private readonly files: RunnerFiles,
private readonly srtPath?: string,
private readonly config = resolveRunnerShell(),
) {
this.environment = runnerEnvironmentSchema.parse({
platform: process.platform,
shell: config.executable,
})
}
async initialize() {
if (!this.srtPath) return
if (this.config.commandTransport === 'stdin')
throw new Error(
'SRT cannot run the legacy WSL Bash launcher. Install Git for Windows to use Bash with SRT.',
)
// Read and validate once; commands cannot weaken the policy by editing the file.
this.sandbox = await loadSandbox(this.srtPath)
try {
await SandboxManager.initialize(this.sandbox.config)
this.initialized = true
let diagnostic = ''
const probe = await this.run(
{ type: 'exec.start', executionId: randomUUID(), command: 'exit 0', timeoutSec: 15 },
new AbortController().signal,
(_stream, data) => {
diagnostic = (diagnostic + data).slice(-4096)
},
)
if (probe.exitCode !== 0 || probe.error || probe.timedOut)
throw new Error(
`SRT preflight failed: ${probe.error || diagnostic.trim() || 'Check settings and local SRT prerequisites.'}`,
)
} catch (error) {
await this.close()
throw error
}
}
async close() {
if (!this.sandbox) return
try {
await SandboxManager.reset()
} finally {
await this.sandbox.cleanup()
this.sandbox = undefined
this.initialized = false
}
}
async run(
message: RunnerExecStartMessage,
signal: AbortSignal,
output: (stream: 'stdout' | 'stderr', data: string) => void,
): Promise<RunnerExecResultMessage> {
const result: RunnerExecResultMessage = {
type: 'exec.result',
executionId: message.executionId,
exitCode: null,
signal: null,
timedOut: false,
aborted: false,
}
if (this.srtPath) this.active++
try {
if (signal.aborted) return { ...result, aborted: true }
const timeout = message.timeoutSec ?? 120
if (!Number.isFinite(timeout) || timeout <= 0 || timeout > MAX_TIMEOUT_SEC)
throw new Error(`Command timeout must be between 0 and ${MAX_TIMEOUT_SEC} seconds.`)
const logPath = `.pi/logs/bash-${message.executionId}.log`
const log = await this.files.createWriter(logPath)
try {
const windows = process.platform === 'win32'
const { commandTransport } = this.config
const useShell = commandTransport === 'shell'
const sendCommandOnStdin = commandTransport === 'stdin'
let executable = useShell ? message.command : this.config.executable
let args = useShell ? [] : sendCommandOnStdin ? ['-s'] : ['-c', message.command]
let shell: string | false = useShell && this.config.executable
let env = commandEnv(message.env)
if (this.srtPath) {
if (!this.initialized) throw new Error('SRT has not been initialized.')
const skillEnv = commandEnv(message.env, false)
const command = windows
? message.command
: [
...Object.entries(skillEnv).map(
([key, value]) => `export ${key}='${value!.replaceAll("'", "'\\''")}'`,
),
message.command,
].join('\n')
const wrapped = await SandboxManager.wrapWithSandboxArgv(
command,
this.config.executable,
undefined,
signal,
this.files.cwd,
{ commandId: message.executionId, commandText: message.command },
)
;[executable, ...args] = wrapped.argv
shell = false
if (windows) {
// SRT's broker starts a fresh sandbox-user environment. Explicit skill
// values belong in its child overlay, never in the broker's startup env.
const separator = args.indexOf('--')
if (separator < 0) throw new Error('SRT returned an invalid Windows launch command.')
args.splice(
separator,
0,
...Object.entries(skillEnv).flatMap(([key, value]) => ['--env', `${key}=${value}`]),
)
env = wrapped.env
} else env = commandEnv()
}
if (signal.aborted) return { ...result, aborted: true }
const deadline = Date.now() + Math.ceil(timeout * 1000)
const child = execa(executable, args, {
cwd: this.files.cwd,
env,
extendEnv: false,
shell,
stdin: sendCommandOnStdin ? [Buffer.from(message.command)] : 'ignore',
buffer: false,
reject: false,
stripFinalNewline: false,
verbose: 'none',
windowsHide: true,
killDescendants: true,
killSignal: 'SIGKILL',
cancelSignal: signal,
timeout: Math.ceil(timeout * 1000),
})
let bytes = 0
let writes = Promise.resolve()
let drainTimer: ReturnType<typeof setTimeout> | undefined
let drainExpired = false
let exitedWithinDeadline = false
child.nodeChildProcess.once('exit', (exitCode) => {
exitedWithinDeadline = exitCode !== null && Date.now() < deadline
// Execa cleans up descendants where the OS still permits it. Bound
// draining if a background child keeps inherited output pipes open.
child.kill('SIGKILL')
drainTimer = setTimeout(() => {
drainExpired = true
child.stdout.destroy()
child.stderr.destroy()
}, 1000)
})
try {
const readers = (['stdout', 'stderr'] as const).map(async (stream) => {
child[stream].setEncoding('utf8')
try {
for await (const data of child[stream]) {
bytes += Buffer.byteLength(data)
if (bytes > MAX_OUTPUT_BYTES)
throw new Error('Command exceeded the 64 MiB output limit.')
await (writes = writes.then(async () => {
await log.write(data)
output(stream, data)
}))
}
} catch (error) {
if (
drainExpired &&
error instanceof Error &&
'code' in error &&
error.code === 'ERR_STREAM_PREMATURE_CLOSE'
)
return
result.error ??= error instanceof Error ? error.message : 'Output streaming failed.'
child.kill('SIGKILL')
}
})
const [completed] = await Promise.all([child, Promise.all(readers)])
await writes
result.exitCode = completed.exitCode ?? null
result.signal = completed.signal ?? null
// Execa's timeout includes stream draining. Report the command's
// runtime, so a timely exit does not become a timeout while draining.
result.timedOut = completed.timedOut && !exitedWithinDeadline
result.aborted = completed.isCanceled
if (
completed.failed &&
completed.exitCode === undefined &&
!result.timedOut &&
!result.aborted &&
!completed.signal
)
result.error = `Command execution failed (${completed.code ?? 'unknown error'}).`
result.fullOutputPath = logPath
} finally {
clearTimeout(drainTimer)
}
} finally {
await log.close()
}
} catch (error) {
result.aborted = signal.aborted
result.error = error instanceof Error ? error.message : 'Command execution failed.'
} finally {
// SRT's temporary mount resources are shared: clean up only after every
// concurrent command has finished, and keep the proxies until shutdown.
if (this.srtPath && --this.active === 0 && this.initialized)
SandboxManager.cleanupAfterCommand()
}
return result
}
}
+2
View File
@@ -0,0 +1,2 @@
// Release builds embed SRT's native helpers through scripts/srt-bundle.ts.
export const bundledSrtVendor: Record<string, string> | undefined = undefined
+59
View File
@@ -0,0 +1,59 @@
import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { loadSandbox } from './srt'
describe('runner SRT configuration', () => {
let directory: string
let settings: string
const config = {
network: { allowedDomains: [], deniedDomains: [] },
filesystem: { denyRead: [], allowWrite: ['.pi'], denyWrite: [] },
}
beforeEach(async () => {
directory = await mkdtemp(path.join(tmpdir(), 'shumai-srt-settings-'))
settings = path.join(directory, 'sandbox.json')
})
afterEach(() => rm(directory, { recursive: true, force: true }))
it('validates upstream settings, supplies packaged helpers, and removes them on cleanup', async () => {
await writeFile(settings, JSON.stringify(config))
const sandbox = await loadSandbox(settings)
const helper = sandbox.config.javaAgentJarPath!
expect(sandbox.config).toMatchObject(config)
expect((await readFile(helper)).subarray(0, 2).toString()).toBe('PK')
if (process.platform === 'linux')
expect(await stat(sandbox.config.seccomp!.applyPath!)).toHaveProperty(
'size',
expect.any(Number),
)
if (process.platform === 'win32')
expect(await stat(sandbox.config.windows!.srtWin!.path!)).toHaveProperty(
'size',
expect.any(Number),
)
await sandbox.cleanup()
await expect(stat(helper)).rejects.toThrow()
})
it('preserves explicit upstream helper paths', async () => {
await writeFile(
settings,
JSON.stringify({
...config,
javaAgentJarPath: '/custom/proxy.jar',
seccomp: { applyPath: '/custom/seccomp' },
windows: { srtWin: { path: 'C:\\custom\\srt-win.exe' } },
}),
)
const sandbox = await loadSandbox(settings)
try {
expect(sandbox.config.javaAgentJarPath).toBe('/custom/proxy.jar')
expect(sandbox.config.seccomp?.applyPath).toBe('/custom/seccomp')
expect(sandbox.config.windows?.srtWin?.path).toBe('C:\\custom\\srt-win.exe')
} finally {
await sandbox.cleanup()
}
})
})
+59
View File
@@ -0,0 +1,59 @@
import { createRequire } from 'node:module'
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import path from 'node:path'
import {
SandboxRuntimeConfigSchema,
type SandboxRuntimeConfig,
} from '@anthropic-ai/sandbox-runtime'
import { bundledSrtVendor } from './srt-vendor'
/** Load the upstream JSON format and supply the helpers bundled with this CLI. */
export async function loadSandbox(configPath: string) {
const config = SandboxRuntimeConfigSchema.parse(JSON.parse(await readFile(configPath, 'utf8')))
const directory = await mkdtemp(path.join(tmpdir(), 'shumai-srt-'))
const cleanup = () => rm(directory, { recursive: true, force: true })
const asset = async (name: string) => {
const encoded = bundledSrtVendor?.[name]
const bytes =
encoded !== undefined
? Buffer.from(encoded, 'base64')
: await readFile(
path.join(
path.dirname(
createRequire(import.meta.url).resolve(
'@anthropic-ai/sandbox-runtime/package.json',
),
),
'vendor',
name,
),
)
const destination = path.join(directory, path.basename(name))
await writeFile(destination, bytes, { mode: 0o500 })
return destination
}
try {
if (process.platform === 'linux' && !config.seccomp?.applyPath) {
config.seccomp = {
...config.seccomp,
applyPath: await asset(`seccomp/${process.arch}/apply-seccomp`),
}
}
if (process.platform === 'win32' && !config.windows?.srtWin?.path) {
config.windows = {
...config.windows,
srtWin: {
...config.windows?.srtWin,
path: await asset(`srt-win/${process.arch}/srt-win.exe`),
},
}
}
if (!config.javaAgentJarPath)
config.javaAgentJarPath = await asset('java-proxy-agent/srt-proxy-agent.jar')
return { config: config satisfies SandboxRuntimeConfig, cleanup }
} catch (error) {
await cleanup()
throw error
}
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@shumai/premiere-uxp",
"version": "0.6.3",
"version": "0.7.0",
"private": true,
"type": "commonjs",
"scripts": {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@shumai/transcode-app",
"version": "0.6.3",
"version": "0.7.0",
"private": true,
"type": "module",
"bin": {
+4
View File
@@ -67,6 +67,7 @@ apps/web/e2e/
| 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` |
| Session logs stay within the dialog and scroll through long messages and expanded records on desktop and narrow screens | `tests/team/agent-session-logs.spec.ts` |
### project
| Test | File |
@@ -90,6 +91,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` |
@@ -97,6 +99,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)
}
+9 -3
View File
@@ -13,8 +13,11 @@ 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'
@@ -22,9 +25,12 @@ async function start() {
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,125 @@
import { expect, test } from '../../fixtures'
test('session logs stay within the dialog and scroll through long messages and expanded records', async ({
owner,
prisma,
}) => {
const { page, teamId, email } = owner
const user = await prisma.user.findUniqueOrThrow({ where: { email } })
const agentUser = await prisma.user.create({
data: { name: 'Session Logs Agent', email: 'session-logs@shumai.test', type: 'agent' },
})
const agent = await prisma.agent.create({
data: {
id: agentUser.id,
teamId,
type: 'chat',
enabled: false,
config: { provider: 'test', model: 'test' },
},
})
const session = await prisma.agentSession.create({
data: {
agentId: agent.id,
userId: user.id,
type: 'chat',
name: 'Scrollable Session Logs',
cwd: '/test',
},
})
await prisma.agentSessionCommit.create({
data: {
sessionId: session.id,
seq: 1n,
data: {
version: 1,
writes: [
{ type: 'conversation', value: { id: 1 } },
...Array.from({ length: 30 }, (_, index) => ({
type: 'entry',
value: {
id: index + 2,
conversationId: 1,
kind: 'pi.user',
model: [
{
role: 'user',
content: `Log message ${index + 1}\n\n\`\`\`text\n${'unbroken_output_'.repeat(100)}\n\`\`\``,
timestamp: Date.now(),
},
],
data: { output: 'raw_output_'.repeat(100) },
},
})),
],
},
},
})
await page.goto(`/teams/${teamId}/dashboard`)
await page.getByRole('button', { name: /^(Sessions|会话)$/ }).click()
await page.getByRole('row').filter({ hasText: session.name! }).click()
const dialog = page.getByRole('dialog')
await expect(dialog.getByText('Log message 1', { exact: true })).toBeVisible()
await expect(dialog.getByText(/^(Entry ID|条目 ID):/)).toHaveCount(0)
const viewport = dialog.locator('[data-slot="scroll-area-viewport"]')
const heading = dialog.getByRole('heading')
for (const size of [
{ width: 1280, height: 800 },
{ width: 390, height: 640 },
]) {
await page.setViewportSize(size)
await dialog.evaluate(async (element) => {
await Promise.all(element.getAnimations().map((animation) => animation.finished))
})
await expect
.poll(async () => {
return dialog.evaluate((element) => {
const bounds = element.getBoundingClientRect()
return (
bounds.top >= 0 &&
bounds.bottom <= window.innerHeight &&
bounds.left >= 0 &&
bounds.right <= window.innerWidth
)
})
})
.toBe(true)
await expect
.poll(() =>
viewport.evaluate(
(element) =>
element.clientHeight > 0 &&
element.scrollHeight > element.clientHeight &&
element.scrollWidth <= element.clientWidth,
),
)
.toBe(true)
const headerTop = (await heading.boundingBox())!.y
await viewport.evaluate((element) => {
element.scrollTop = 0
})
await viewport.hover()
// Wheel events may be capped; verify movement before jumping to the final record.
await page.mouse.wheel(0, 400)
await expect.poll(() => viewport.evaluate((element) => element.scrollTop)).toBeGreaterThan(0)
const record = dialog.locator('details').last()
await viewport.evaluate((element) => {
element.scrollTop = element.scrollHeight
})
await expect(record.locator('summary')).toBeInViewport()
expect((await heading.boundingBox())!.y).toBeCloseTo(headerTop, 0)
await record.locator('summary').click()
await viewport.evaluate((element) => {
element.scrollTop = element.scrollHeight
})
await expect(record.locator('pre')).toBeInViewport()
await expect(record.locator('pre')).toContainText('"id": 31')
expect(await viewport.evaluate((element) => element.scrollWidth <= element.clientWidth)).toBe(
true,
)
await record.locator('summary').click()
}
})
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@shumai/web-app",
"version": "0.6.3",
"version": "0.7.0",
"private": true,
"type": "module",
"dependencies": {
+50 -33
View File
@@ -5,20 +5,24 @@ loadEnvConfig(process.cwd(), process.env.NODE_ENV !== 'production')
import index from '@shumai/webui/index.html'
import { initAgentWorkflows } from '@shumai/agent'
import { app } from '@shumai/api'
import { closeAgentSessions, initAgentWorkflows } from '@shumai/agent'
import { app, runnerWebsocket } from '@shumai/api'
import { agentService } from '@shumai/core/src/agent/agent'
import { migrateLegacyAgentAvatars } from '@shumai/core/src/agent/migration'
import { assetService } from '@shumai/core/src/asset/asset'
import { metadataService } from '@shumai/core/src/metadata/metadata'
import { validateArchiveStorageConfig } from '@shumai/core/src/s3/archive-storage'
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 { runnerService } from '@shumai/core'
import { autoArchiveJobService } from '@shumai/core/src/asset/auto-archive-job'
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 { embeddingService } from '@shumai/core/src/search/embedding-service'
import { handleDaemonCommands } from '@shumai/core/src/utils/daemon'
import { createHtmlHandler, createStaticFileHandler } from './static'
import { getServerQueues } from './workers'
if (process.argv.includes('--check')) {
console.log('✅ Web app evaluated successfully!')
@@ -76,12 +80,21 @@ if (regenCmdIndex !== -1) {
}
async function run() {
validateArchiveStorageConfig()
const runnerLease = await runnerService.startServerTopology()
runnerLease.addEventListener(
'abort',
() => {
console.error('Lost the runner server lease:', runnerLease.reason)
process.exit(1)
},
{ once: true },
)
runnerLease.throwIfAborted()
// Initialize workflows and activities for local executor mode
initAgentWorkflows()
initTranscodeWorkflows()
await sandboxService.ensureInitialized().catch((err) => {
console.error('Failed to eagerly initialize sandbox in web app:', err)
})
runnerService.startHeartbeatMonitor()
// Start services
await metadataService.syncSystemFields().catch(console.error)
@@ -89,6 +102,7 @@ async function run() {
await agentService.ensureSystemEmbeddingAgents().catch(console.error)
assetService.startCleanupJob()
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++) {
@@ -99,16 +113,7 @@ async function run() {
}
}
let listenQueues: string[] = ['agent_queue', 'transcode_queue']
if (workersOption === 'none') {
listenQueues = []
} else if (workersOption === 'agent' || workersOption === 'ai') {
listenQueues = ['agent_queue']
} else if (workersOption === 'transcode') {
listenQueues = ['transcode_queue']
}
workflowService.start(listenQueues)
workflowService.start(getServerQueues(workersOption))
workflowService.startStaleTaskRecovery()
const isProd = process.env.NODE_ENV === 'production'
@@ -145,7 +150,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 || ''
@@ -157,13 +163,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)
@@ -179,16 +186,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
}
@@ -205,6 +218,7 @@ async function run() {
: 1024 * 1024 * 1024 * 20, // Default 20GB
development: !isProd,
fetch: app.fetch,
websocket: runnerWebsocket,
routes,
})
@@ -213,9 +227,12 @@ async function run() {
const shutdown = async () => {
console.log('\nShutting down gracefully...')
workflowService.stopStaleTaskRecovery()
runnerService.stopHeartbeatMonitor()
await closeAgentSessions()
await workflowService.shutdownWorkers().catch(() => {})
assetService.stopCleanupJob()
server.stop(true)
await runnerService.stopServerTopology().catch(console.error)
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 })
}
}
+15
View File
@@ -0,0 +1,15 @@
import { describe, expect, it } from 'vitest'
import { getServerQueues } from './workers'
describe('server queues', () => {
it.each(['none', 'agent', 'ai', 'archive'])(
'keeps agent and archive embedded for %s',
(option) => {
expect(getServerQueues(option)).toEqual(['agent_queue', 'archive_queue'])
},
)
it.each(['all', 'transcode'])('also processes local transcoding for %s', (option) => {
expect(getServerQueues(option)).toEqual(['agent_queue', 'archive_queue', 'transcode_queue'])
})
})
+8
View File
@@ -0,0 +1,8 @@
import { TaskQueueAgent, TaskQueueArchive, TaskQueueTranscode } from '@shumai/workflow-core'
/** Agent and archive work always belongs to the server; only transcoding is optional. */
export function getServerQueues(option: string): string[] {
const queues = [TaskQueueAgent, TaskQueueArchive]
if (option === 'all' || option === 'transcode') queues.push(TaskQueueTranscode)
return queues
}
-1
View File
@@ -37,7 +37,6 @@ const allWorkers = [
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)
+245 -92
View File
@@ -30,38 +30,36 @@
"vitest": "4.1.11",
},
},
"apps/agent": {
"name": "@shumai/agent-app",
"version": "0.6.3",
"bin": {
"shumai-agent": "./src/index.ts",
},
"dependencies": {
"@shumai/agent": "workspace:*",
"@shumai/core": "workspace:*",
"@shumai/workflow-core": "workspace:*",
},
},
"apps/cli": {
"name": "@shumai/cli",
"version": "0.6.3",
"version": "0.7.0",
"bin": {
"shumai-cli": "./src/index.ts",
},
"dependencies": {
"@anthropic-ai/sandbox-runtime": "0.0.83",
"@shumai/api": "workspace:*",
"@shumai/dtos": "workspace:*",
"@shumai/operations": "workspace:*",
"@shumai/tableprinter": "workspace:*",
"commander": "15.0.0",
"execa": "10.2.1",
"hono": "4.13.5",
"ulid": "3.0.2",
"ws": "8.22.2",
"yauzl": "3.4.0",
"zod": "4.5.4",
},
"devDependencies": {
"@types/adm-zip": "0.5.8",
"@types/ws": "8.18.2",
"@types/yauzl": "3.4.0",
"adm-zip": "0.6.1",
},
},
"apps/premiere-uxp": {
"name": "@shumai/premiere-uxp",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@shumai/api": "workspace:*",
"@shumai/dtos": "workspace:*",
@@ -115,7 +113,7 @@
},
"apps/transcode": {
"name": "@shumai/transcode-app",
"version": "0.6.3",
"version": "0.7.0",
"bin": {
"shumai-transcode": "./src/index.ts",
},
@@ -127,7 +125,7 @@
},
"apps/web": {
"name": "@shumai/web-app",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@shumai/agent": "workspace:*",
"@shumai/api": "workspace:*",
@@ -147,11 +145,11 @@
},
"packages/agent": {
"name": "@shumai/agent",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@anthropic-ai/sandbox-runtime": "0.0.74",
"@earendil-works/pi-agent-core": "0.82.1",
"@earendil-works/pi-ai": "0.82.1",
"@earendil-works/chord": "1.5.0",
"@earendil-works/pi-ai": "1.5.0",
"@earendil-works/pi-durable": "1.5.0",
"@google/genai": "2.28.0",
"@shumai/core": "workspace:*",
"@shumai/db": "workspace:*",
@@ -171,9 +169,10 @@
},
"packages/api": {
"name": "@shumai/api",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@better-auth/mcp": "1.7.12",
"@earendil-works/pi-durable": "1.5.0",
"@hono/zod-validator": "0.7.6",
"@modelcontextprotocol/server": "2.0.0",
"@shumai/core": "workspace:*",
@@ -191,7 +190,7 @@
},
"packages/core": {
"name": "@shumai/core",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@ai-sdk/alibaba": "2.0.38",
"@ai-sdk/amazon-bedrock": "5.0.67",
@@ -211,13 +210,13 @@
"@ai-sdk/replicate": "3.0.34",
"@ai-sdk/togetherai": "3.0.41",
"@ai-sdk/xai": "4.0.49",
"@anthropic-ai/sandbox-runtime": "0.0.74",
"@aws-sdk/client-s3": "3.1121.0",
"@aws-sdk/s3-request-presigner": "3.1121.0",
"@better-auth/mcp": "1.7.12",
"@better-auth/oauth-provider": "1.7.12",
"@earendil-works/pi-agent-core": "0.82.1",
"@earendil-works/pi-ai": "0.82.1",
"@earendil-works/chord": "1.5.0",
"@earendil-works/pi-ai": "1.5.0",
"@earendil-works/pi-durable": "1.5.0",
"@google/genai": "2.28.0",
"@modelcontextprotocol/client": "2.0.0",
"@shumai/db": "workspace:*",
@@ -255,9 +254,8 @@
},
"packages/db": {
"name": "@shumai/db",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@earendil-works/pi-agent-core": "0.82.1",
"@prisma/adapter-pg": "7.10.0",
"@prisma/client": "7.10.0",
"pg": "8.23.0",
@@ -271,17 +269,19 @@
},
"packages/dtos": {
"name": "@shumai/dtos",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@earendil-works/pi-agent-core": "0.82.1",
"@earendil-works/pi-ai": "1.5.0",
"@earendil-works/pi-durable": "1.5.0",
"zod": "4.5.4",
},
},
"packages/e2e": {
"name": "@shumai/e2e",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@earendil-works/pi-agent-core": "0.82.1",
"@earendil-works/pi-ai": "1.5.0",
"@earendil-works/pi-durable": "1.5.0",
"@google/genai": "2.28.0",
"@shumai/agent": "workspace:*",
"@shumai/core": "workspace:*",
@@ -294,18 +294,18 @@
},
"packages/operations": {
"name": "@shumai/operations",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"zod": "4.5.4",
},
},
"packages/tableprinter": {
"name": "@shumai/tableprinter",
"version": "0.6.3",
"version": "0.7.0",
},
"packages/transcode": {
"name": "@shumai/transcode",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@shumai/core": "workspace:*",
"@shumai/db": "workspace:*",
@@ -316,13 +316,15 @@
},
"packages/webui": {
"name": "@shumai/webui",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@base-ui/react": "1.7.0",
"@better-auth/oauth-provider": "1.7.12",
"@dnd-kit/abstract": "0.5.0",
"@dnd-kit/dom": "0.5.0",
"@dnd-kit/react": "0.5.0",
"@earendil-works/pi-ai": "1.5.0",
"@earendil-works/pi-durable": "1.5.0",
"@ferrucc-io/emoji-picker": "0.1.2",
"@hookform/resolvers": "5.9.1",
"@lexical/code": "0.49.0",
@@ -419,7 +421,7 @@
},
"packages/workflow-core": {
"name": "@shumai/workflow-core",
"version": "0.6.3",
"version": "0.7.0",
"dependencies": {
"@dbos-inc/dbos-sdk": "5.2.11",
"@shumai/core": "workspace:*",
@@ -429,9 +431,6 @@
},
},
},
"patchedDependencies": {
"@earendil-works/pi-ai@0.82.1": "patches/@earendil-works%2Fpi-ai@0.82.1.patch",
},
"packages": {
"@adobe/premierepro": ["@adobe/premierepro@26.3.0", "", {}, "sha512-J84zEX8R4L5EU5EVVs3AWkd4LRoXPKueo28jPNfwwDAo69TOSNsAblImtsAmJR4HGDDazsvHkMQE3JBJqIcB9Q=="],
@@ -485,21 +484,13 @@
"@alloc/quick-lru": ["@alloc/quick-lru@5.2.0", "", {}, "sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw=="],
"@anthropic-ai/sandbox-runtime": ["@anthropic-ai/sandbox-runtime@0.0.74", "", { "dependencies": { "@pondwader/socks5-server": "^1.0.10", "commander": "^12.1.0", "node-forge": "^1.4.0", "zod": "^3.24.1" }, "bin": { "srt": "dist/cli.js" } }, "sha512-k6xD9HPp4gCwIAQtAloTBSaKGGNQhH7o1ck0057iBxu3iHclM2vx+JzIXLDB9j4oaP9hwGcNlWSP5K7bgc1CIQ=="],
"@anthropic-ai/sandbox-runtime": ["@anthropic-ai/sandbox-runtime@0.0.83", "", { "dependencies": { "@pondwader/socks5-server": "^1.0.10", "commander": "^12.1.0", "node-forge": "^1.4.0", "zod": "^3.25.0" }, "peerDependencies": { "@microsoft/mxc-sdk": "^1.0.1" }, "optionalPeers": ["@microsoft/mxc-sdk"], "bin": { "srt": "dist/cli.js" } }, "sha512-yEusORnVJrNseF/9fvjVYyk6tr79/aFbIB3T/X8p2puLZdaaiGNeYN50v0CE+1DT70v7XuzKOAnTivh1f5cksA=="],
"@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.91.1", "", { "dependencies": { "json-schema-to-ts": "^3.1.1" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-LAmu761tSN9r66ixvmciswUj/ZC+1Q4iAfpedTfSVLeswRwnY3n2Nb6Tsk+cLPP28aLOPWeMgIuTuCcMC6W/iw=="],
"@aws-crypto/sha256-browser": ["@aws-crypto/sha256-browser@5.2.0", "", { "dependencies": { "@aws-crypto/sha256-js": "^5.2.0", "@aws-crypto/supports-web-crypto": "^5.2.0", "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "@aws-sdk/util-locate-window": "^3.0.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw=="],
"@aws-crypto/sha256-js": ["@aws-crypto/sha256-js@5.2.0", "", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA=="],
"@aws-crypto/supports-web-crypto": ["@aws-crypto/supports-web-crypto@5.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg=="],
"@aws-crypto/util": ["@aws-crypto/util@5.2.0", "", { "dependencies": { "@aws-sdk/types": "^3.222.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ=="],
"@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.129.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-MH7LB20kNpGLUpPTe2OG5XvL/KhX8HUO9XyBaFjgFk6TLS4Xjt0VPIuMKywe7POKKPslX+QxSlVok9e+8kG5Nw=="],
"@aws-sdk/checksums": ["@aws-sdk/checksums@3.1000.29", "", { "dependencies": { "@aws-sdk/core": "^3.977.9", "@aws-sdk/types": "^3.974.5", "@smithy/core": "^3.33.3", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-Dtu0gr4dnATZAPwEYbpCsG+MpLM7OAliy2gTepEFQwl1vZ6DL3QMH2FveMa3HLvPsOdhJsPRB3KtxVhph9T75A=="],
"@aws-sdk/client-bedrock-runtime": ["@aws-sdk/client-bedrock-runtime@3.1048.0", "", { "dependencies": { "@aws-crypto/sha256-browser": "5.2.0", "@aws-crypto/sha256-js": "5.2.0", "@aws-sdk/core": "^3.974.11", "@aws-sdk/credential-provider-node": "^3.972.42", "@aws-sdk/eventstream-handler-node": "^3.972.16", "@aws-sdk/middleware-eventstream": "^3.972.12", "@aws-sdk/middleware-websocket": "^3.972.19", "@aws-sdk/token-providers": "3.1048.0", "@aws-sdk/types": "^3.973.8", "@smithy/core": "^3.24.2", "@smithy/fetch-http-handler": "^5.4.2", "@smithy/node-http-handler": "^4.7.2", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-u+NT61JZEkRFtpL0CAw1N1dwxnaLgwVXQl/zjJxTGgLyS/jTIdg2SdoEoCTHxgDyCnqa1HEi9QOoE9/pYRNpOQ=="],
"@aws-sdk/client-bedrock-runtime": ["@aws-sdk/client-bedrock-runtime@3.1127.0", "", { "dependencies": { "@aws-sdk/core": "^3.977.9", "@aws-sdk/credential-provider-node": "^3.972.82", "@aws-sdk/eventstream-handler-node": "^3.972.34", "@aws-sdk/middleware-eventstream": "^3.972.29", "@aws-sdk/middleware-websocket": "^3.972.52", "@aws-sdk/token-providers": "3.1127.0", "@aws-sdk/types": "^3.974.5", "@smithy/core": "^3.33.3", "@smithy/fetch-http-handler": "^5.7.2", "@smithy/node-http-handler": "^4.11.3", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-IDl/lrPb90aH+pZFHGNDmgH9nAUQj5PlZH1sJ3w7RikctyjHSnY3oNjZhrLoaBoQn/rNK0zsP6OHEqEhj2tdLA=="],
"@aws-sdk/client-s3": ["@aws-sdk/client-s3@3.1121.0", "", { "dependencies": { "@aws-sdk/checksums": "^3.1000.29", "@aws-sdk/core": "^3.977.9", "@aws-sdk/credential-provider-node": "^3.972.81", "@aws-sdk/middleware-sdk-s3": "^3.972.75", "@aws-sdk/signature-v4-multi-region": "^3.996.46", "@aws-sdk/types": "^3.974.5", "@smithy/core": "^3.33.3", "@smithy/fetch-http-handler": "^5.7.2", "@smithy/node-http-handler": "^4.11.3", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-hBnoqaVBeWdkgXcJElMXA2yUZWkBCBntu2qmN+tfqmzC+j4LzJC3ox8qIgS2WdMS1cb8UwyBogUVrkRXybNm0A=="],
@@ -535,12 +526,10 @@
"@aws-sdk/signature-v4-multi-region": ["@aws-sdk/signature-v4-multi-region@3.996.46", "", { "dependencies": { "@aws-sdk/types": "^3.974.5", "@smithy/signature-v4": "^5.6.12", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-L+2xZTye/2T96f3lwCws0Zw6GG2JHZW9e8FpVgGBeeExSKyeoZ6CWRpBml/7DNiK/O26jrgPM9F+Ay8VkgzUWQ=="],
"@aws-sdk/token-providers": ["@aws-sdk/token-providers@3.1048.0", "", { "dependencies": { "@aws-sdk/core": "^3.974.11", "@aws-sdk/nested-clients": "^3.997.9", "@aws-sdk/types": "^3.973.8", "@smithy/core": "^3.24.2", "@smithy/types": "^4.14.1", "tslib": "^2.6.2" } }, "sha512-k0y/GcuesuSfWyUM0WamrGyeZmltRYaPbHO82UDA6mZ/doB+FOHKutikPAtSXMn/hDz970cF+iRuuiYO9VEbAA=="],
"@aws-sdk/token-providers": ["@aws-sdk/token-providers@3.1127.0", "", { "dependencies": { "@aws-sdk/core": "^3.977.9", "@aws-sdk/nested-clients": "^3.997.44", "@aws-sdk/types": "^3.974.5", "@smithy/core": "^3.33.3", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-Dv2TMWBshJ+tF6ahs2Sy5bh4Iabsd4GAQqVvE9XZmYmnoaVbpS2QKIKE/HRacc7bTtbjEEvP+laGzHvHlf1CiQ=="],
"@aws-sdk/types": ["@aws-sdk/types@3.974.5", "", { "dependencies": { "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-LkwLL2BLbC6wNNm4JaH9mbEqBMdOZCct6VAYqhdN4U1xrWM+fUJQEfbHwQgDypapOWTRtlk25akb5afM0P8CIQ=="],
"@aws-sdk/util-locate-window": ["@aws-sdk/util-locate-window@3.965.10", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-ycwH6Zd2GhuSqdXX9ihbCjeGTB6xOJs+O3+Jb8/zDG9978XU80qs75dfkPJRMNKe5MvBZPuNeFpd4JZKPoUF4g=="],
"@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.40", "", { "dependencies": { "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-wlFmCIGUlwF4zx/kncw+bmxTQh1HeSJq4mYV/V5cZUSJadDP3kXvGW8Rn21cimj/7y9ju+47oYWXi97vF7czaA=="],
"@aws/lambda-invoke-store": ["@aws/lambda-invoke-store@0.3.0", "", {}, "sha512-sl4Bm6yiMNYrZKkqqDFWN0UfnWhlS8ivKxrYl+6t0gCLrqr8y3B2IqZZbFRkfaVVp7C/baApyh71P+LeE1A2sQ=="],
@@ -629,9 +618,17 @@
"@dnd-kit/state": ["@dnd-kit/state@0.5.0", "", { "dependencies": { "@preact/signals-core": "^1.10.0", "tslib": "^2.6.2" } }, "sha512-y7XbabQqjF58Lk8YmDQuR8l6QjN+Kh4qlGEjUvHuIeasLk1QP+9L5diXS98VMxQIivyMmUtX2//f+3N7qPJX4w=="],
"@earendil-works/pi-agent-core": ["@earendil-works/pi-agent-core@0.82.1", "", { "dependencies": { "@earendil-works/pi-ai": "^0.82.1", "diff": "8.0.4", "ignore": "7.0.5", "typebox": "1.1.38", "yaml": "2.9.0" } }, "sha512-Z3kloziJIE2dmrisRckZX8zDca/gIv9/YdFAzeoqpHiLV2wsni6bL4hInNSjVKLbqT+4kqLIkph2JQLKvSepjg=="],
"@earendil-works/chord": ["@earendil-works/chord@1.5.0", "", { "dependencies": { "@earendil-works/pi-schema": "1.5.0", "@earendil-works/pi-telemetry": "1.5.0" }, "peerDependencies": { "esbuild": "0.28.2", "ws": "8.21.0" }, "optionalPeers": ["esbuild", "ws"] }, "sha512-jf555zbCM21E03DVBDPD/Tuae0lz64YjaHx/athUxNZ/H7phVVb0dWfZsaYnxaXPQ1odW8iHEoVLOlE/prvUPg=="],
"@earendil-works/pi-ai": ["@earendil-works/pi-ai@0.82.1", "", { "dependencies": { "@anthropic-ai/sdk": "0.91.1", "@aws-sdk/client-bedrock-runtime": "3.1048.0", "@google/genai": "1.52.0", "@mistralai/mistralai": "2.2.6", "@opentelemetry/api": "1.9.0", "@smithy/node-http-handler": "4.7.3", "http-proxy-agent": "7.0.2", "https-proxy-agent": "7.0.6", "openai": "6.26.0", "partial-json": "0.1.7", "typebox": "1.1.38" }, "bin": { "pi-ai": "dist/cli.js" } }, "sha512-3WFYRhEp3lQB3444EhPMBcM7zSaEUE3eJgHOR7s4081NLqbw/FsWilIKWXSua0Gv3sRr7m9xMidR3pPDE7jI/A=="],
"@earendil-works/pi-ai": ["@earendil-works/pi-ai@1.5.0", "", { "dependencies": { "@anthropic-ai/sdk": "0.129.0", "@aws-sdk/client-bedrock-runtime": "3.1127.0", "@earendil-works/pi-schema": "1.5.0", "@earendil-works/pi-telemetry": "1.5.0", "@google/genai": "2.21.0", "@smithy/node-http-handler": "4.12.1", "http-proxy-agent": "9.1.0", "https-proxy-agent": "9.1.0", "openai": "7.19.0", "partial-json": "0.1.7" }, "bin": { "pi-ai": "dist/cli.js" } }, "sha512-VeWxNqTHSqRCf8AcY/6kvNwh+neRL6MPxZPePVztIQy6qqK9MR/YoCSN/ZgDnIyCD3pqEXgRyQbzk4KV4uvjbg=="],
"@earendil-works/pi-codemode": ["@earendil-works/pi-codemode@1.5.0", "", { "dependencies": { "quickjs-wasi": "3.6.2" } }, "sha512-PLBJZ17AEWGzOlAAcFuOkw3PxkOti0JlFuZQyeF2GRTqbpuYo4k9t8YqUV2uOQVzrUnKdxahwaFUqc1eNS1WAg=="],
"@earendil-works/pi-durable": ["@earendil-works/pi-durable@1.5.0", "", { "dependencies": { "@earendil-works/chord": "1.5.0", "@earendil-works/pi-ai": "1.5.0", "@earendil-works/pi-codemode": "1.5.0", "@earendil-works/pi-schema": "1.5.0", "@earendil-works/pi-telemetry": "1.5.0", "@silvia-odwyer/photon": "0.3.3", "diff": "8.0.4" } }, "sha512-xeBP2vIo5NvsCMQ4Y/V+Z164xQEi9JWiBWHdjn4Z15EnFqV3c0FxJAX26FqyyyintrYyk+Enre94GNcvRlBA5g=="],
"@earendil-works/pi-schema": ["@earendil-works/pi-schema@1.5.0", "", {}, "sha512-RW0MbT2tR65OY6xMsgB/yVBb7m/RTNwA+9hurSN1vVXfHZRVmVnXbruBPrx/PzbrQnW5yLVlMRWxErGDQtF1Hg=="],
"@earendil-works/pi-telemetry": ["@earendil-works/pi-telemetry@1.5.0", "", {}, "sha512-VW3tcVdnNfl/Vk8wHPTzZdKkxcsCOM12ppiO4DXnd9wMxUCmOfLt/wvUnWeKWbTVlVSRg0uqKtnnhE2UCsG2Bw=="],
"@electric-sql/pglite": ["@electric-sql/pglite@0.4.3", "", {}, "sha512-ichuWTgtd4mOM1G4SpyGJa5trT03lWbMypDV0fUXUCXg5hiHqVAz/bZyV68NqmkLB7WcYmj1RMJVSp8HV/v/ZQ=="],
@@ -833,8 +830,6 @@
"@lix-js/sdk-win32-x64": ["@lix-js/sdk-win32-x64@0.12.3", "", { "os": "win32", "cpu": "x64" }, "sha512-hnxMI7kPS4ngXs0ZVnOve5CmtC4+vaNIyNDi/yWU0rSvxj7mqw/1RCegTrCB7LjxlX4DG+eg9HruXurk9NDjGg=="],
"@mistralai/mistralai": ["@mistralai/mistralai@2.2.6", "", { "dependencies": { "@opentelemetry/semantic-conventions": "^1.40.0", "ws": "^8.18.0", "zod": "^3.25.0 || ^4.0.0", "zod-to-json-schema": "^3.25.0" }, "peerDependencies": { "@opentelemetry/api": "^1.9.0" }, "optionalPeers": ["@opentelemetry/api"] }, "sha512-W8pX7zHxjJvMIpw8JMxeJEleapXX0Q9NPszdNzqkM3MIEoIGPObdodujj+WHteXEvGfaP/AMwlNyRfEzSY6dQQ=="],
"@modelcontextprotocol/client": ["@modelcontextprotocol/client@2.0.0", "", { "dependencies": { "@modelcontextprotocol/core": "2.0.0", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "jose": "^6.1.3", "pkce-challenge": "^5.0.0", "zod": "^4.2.0" } }, "sha512-8f1OghQ2rjzIOfqgUCP+8GiUWqRs89njoWLNqAe8kWmDePv3s1fZXseej+QXemssEuuOvLLmLO/kqM3IQHtISw=="],
"@modelcontextprotocol/core": ["@modelcontextprotocol/core@2.0.0", "", { "dependencies": { "zod": "^4.2.0" } }, "sha512-pJCEwGG7Lfr/+PQp9ZTwKXNeO5wzbfKL7H3MYpCorM4oFBoQrdjnBgEoqG+RjhsvS1FKrDbKux+M1HhlnGWqcA=="],
@@ -869,10 +864,6 @@
"@noble/hashes": ["@noble/hashes@2.4.0", "", {}, "sha512-X5XaVWZIBCT7HHZGm5I7ZQXDwLG+bGXuSrMQAW+7Zvl87h1kmc1ZB1VSRJcpUfoUrGQp4Fkoxm5kZ+Ms+aW+eA=="],
"@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
"@opentelemetry/semantic-conventions": ["@opentelemetry/semantic-conventions@1.43.0", "", {}, "sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg=="],
"@oven/bun-darwin-aarch64": ["@oven/bun-darwin-aarch64@1.4.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-GCpf8QuFLsyioVawP5HrMxA1ZRBlu6Hq9RNnSc3UTUWAzIxBso9trjoZczw1HdgpqSssFkszfIV2zmOzFTjhkw=="],
"@oven/bun-darwin-x64": ["@oven/bun-darwin-x64@1.4.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-cIrhwOr0SPEraewznhC+c/k6TG8bwFn5uZ4EJuXwjiKJLcAF36q7/bGjWkeXSe48JwMcPRUR054JXF7+cRwSSA=="],
@@ -1117,9 +1108,9 @@
"@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.1", "", {}, "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw=="],
"@shumai/agent": ["@shumai/agent@workspace:packages/agent"],
"@sec-ant/readable-stream": ["@sec-ant/readable-stream@0.4.1", "", {}, "sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg=="],
"@shumai/agent-app": ["@shumai/agent-app@workspace:apps/agent"],
"@shumai/agent": ["@shumai/agent@workspace:packages/agent"],
"@shumai/api": ["@shumai/api@workspace:packages/api"],
@@ -1149,10 +1140,14 @@
"@shumai/workflow-core": ["@shumai/workflow-core@workspace:packages/workflow-core"],
"@silvia-odwyer/photon": ["@silvia-odwyer/photon@0.3.3", "", {}, "sha512-8BhUjEch4slwRe8uXnaA4vcA5uiiOTT90UMsxulOj2gN98X1p0q9Z4Ysk4DkD05uNgbR9XoSqtZ37w+33w4QKQ=="],
"@sinclair/typebox": ["@sinclair/typebox@0.34.52", "", {}, "sha512-XiMQh7qqVlxZzcVD+kkGMNGMzcTrDMLWI7S4x7z1MkCkbDPrekpZXEUK0eZqZFMuHQg2a2DZOcDIh9o5v3Gonw=="],
"@sindresorhus/is": ["@sindresorhus/is@4.6.0", "", {}, "sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw=="],
"@sindresorhus/merge-streams": ["@sindresorhus/merge-streams@4.0.0", "", {}, "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ=="],
"@smithy/core": ["@smithy/core@3.33.3", "", { "dependencies": { "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-CsOeKq/9kA3y6VJHt+/+VTCtBaxJ4OTFpgrjIUhPpDIKxBci1k2bJaQASF2h/ELWrulGp+t97DZ0mevfAD8idg=="],
"@smithy/credential-provider-imds": ["@smithy/credential-provider-imds@4.5.2", "", { "dependencies": { "@smithy/core": "^3.33.2", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-A9uSdn72ozbRUSit0eib0TW7nXuNPlaeM0zcGkJ+nE6tFcSDbnmtwoxbTCFBukVQcszDAyvsd7+rTduPTXpygg=="],
@@ -1161,16 +1156,12 @@
"@smithy/fetch-http-handler": ["@smithy/fetch-http-handler@5.7.2", "", { "dependencies": { "@smithy/core": "^3.33.2", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-nZyWTmSpJEXl6VtWVMBJve/7x12DZu6sIX1z1a+ZMaHlQQRs9Zpu6NbTe/gmxYXVRpkjxyDYpZ5gx2IM6f/Wkw=="],
"@smithy/is-array-buffer": ["@smithy/is-array-buffer@2.2.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA=="],
"@smithy/node-http-handler": ["@smithy/node-http-handler@4.7.3", "", { "dependencies": { "@smithy/core": "^3.24.3", "@smithy/types": "^4.14.2", "tslib": "^2.6.2" } }, "sha512-/jPhevcTFPMVl6KNjbaI47iOg1zxC7IsnX4PQDGVZKMFceOXtB8IEYaB7a9VvkP/3oC60WzTeKocvSI7vLT0vA=="],
"@smithy/node-http-handler": ["@smithy/node-http-handler@4.12.1", "", { "dependencies": { "@smithy/core": "^3.33.3", "@smithy/types": "^4.18.0", "tslib": "^2.6.2" } }, "sha512-ThMkboGeONWXAelq9FvGsuJC4rOi+qyC4/zhUF58xYpxUg5sQKx2VXZYJmtNjr4dSuBJ1HeJXETQILCz3wOHvw=="],
"@smithy/signature-v4": ["@smithy/signature-v4@5.7.3", "", { "dependencies": { "@smithy/core": "^3.33.3", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-7ImGm+FkHRLcBaRttIAMZ6bzJZWb2cJGoYjq46F2UjycujWzrL9GEN9h4w7eQyXJYnltrUhxbbieBAIRrdqpow=="],
"@smithy/types": ["@smithy/types@4.17.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-FOKpVZob9MPTn2znRzGrnsMHv7BOsKVw3XiP/cOyYLDVZ9qKp4nifIiSCuUU/fIj5Vu0UOAxCFr+qRAtG0NUkA=="],
"@smithy/util-buffer-from": ["@smithy/util-buffer-from@2.2.0", "", { "dependencies": { "@smithy/is-array-buffer": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA=="],
"@smithy/util-utf8": ["@smithy/util-utf8@4.5.2", "", { "dependencies": { "@smithy/core": "^3.33.2", "tslib": "^2.6.2" } }, "sha512-7wNWV7SugHpcMA7uzEawJNpE0GrasXM7a9E+1+Wm6NxVuDClESac/AKt+G7jMZNUz5vBLWqKlqVV7Sv7AtUr6Q=="],
"@spectrum-web-components/action-button": ["@spectrum-web-components/action-button@0.37.0", "", { "dependencies": { "@spectrum-web-components/base": "^0.37.0", "@spectrum-web-components/button": "^0.37.0", "@spectrum-web-components/icon": "^0.37.0", "@spectrum-web-components/icons-ui": "^0.37.0", "@spectrum-web-components/shared": "^0.37.0" } }, "sha512-cU/5sHpRSA823sHUH6jZccmizkTxWr/LJHTDJ4jj0LxCLh15OHfxKM+hu/vcc5fXYrAPma5Hp54xTBc/l/frDA=="],
@@ -1245,6 +1236,8 @@
"@sqlite.org/sqlite-wasm": ["@sqlite.org/sqlite-wasm@3.48.0-build4", "", { "bin": { "sqlite-wasm": "bin/index.js" } }, "sha512-hI6twvUkzOmyGZhQMza1gpfqErZxXRw6JEsiVjUbo7tFanVD+8Oil0Ih3l2nGzHdxPI41zFmfUQG7GHqhciKZQ=="],
"@stablelib/base64": ["@stablelib/base64@1.0.1", "", {}, "sha512-1bnPQqSxSuc3Ii6MhBysoWCg58j97aUjuCSZrGSmDxNqtytIi0k8utUenAwTZN4V5mXXYGsVUI9zeBqy+jBOSQ=="],
"@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
"@standard-schema/utils": ["@standard-schema/utils@0.3.0", "", {}, "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g=="],
@@ -1539,9 +1532,9 @@
"@types/whatwg-mimetype": ["@types/whatwg-mimetype@3.0.2", "", {}, "sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA=="],
"@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
"@types/ws": ["@types/ws@8.18.2", "", { "dependencies": { "@types/node": "*" } }, "sha512-67MQl+fpWKVTT1NYdnmo3U4sc/xPo/zQBncVnI74qmQa0z/b+1g6iYqNmGCPbxO+zz2aklb08a0oHfegiVd0/w=="],
"@types/yauzl": ["@types/yauzl@2.10.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q=="],
"@types/yauzl": ["@types/yauzl@3.4.0", "", { "dependencies": { "@types/node": "*" } }, "sha512-NRPn5w6h8dhcnmx3YIRQcqMywY/+nND/uOkJessedcrowO3C0AssHp3tMJpxKAwOhFOo0OV1y9VtsC5hbKKBAw=="],
"@typescript-eslint/eslint-plugin": ["@typescript-eslint/eslint-plugin@8.68.0", "", { "dependencies": { "@eslint-community/regexpp": "^4.12.2", "@typescript-eslint/scope-manager": "8.68.0", "@typescript-eslint/type-utils": "8.68.0", "@typescript-eslint/utils": "8.68.0", "@typescript-eslint/visitor-keys": "8.68.0", "ignore": "^7.0.5", "natural-compare": "^1.4.0", "ts-api-utils": "^2.5.0" }, "peerDependencies": { "@typescript-eslint/parser": "^8.68.0", "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.1.0" } }, "sha512-WASHDpCm6qO5jj9g1a+8NiW5+GCkAyLReR56/4VruYmNgfUmqpxOfZ2Yfb8xGfJPWv5Qi6LSD8sXdces3vbp/Q=="],
@@ -1615,7 +1608,7 @@
"adm-zip": ["adm-zip@0.6.0", "", {}, "sha512-XleryMhbuksdKtofnWZ9Sk+4CUTbms4Mb/EU32SZwToAyZ5RgVos/ki8n+yr0LWHOGKuakbXTuuYNHLQjhddgg=="],
"agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
"agent-base": ["agent-base@9.0.0", "", {}, "sha512-TQf59BsZnytt8GdJKLPfUZ54g/iaUL2OWDSFCCvMOhsHduDQxO8xC4PNeyIkVcA5KwL2phPSv0douC0fgWzmnA=="],
"ai": ["ai@7.0.84", "", { "dependencies": { "@ai-sdk/gateway": "4.0.68", "@ai-sdk/provider": "4.0.8", "@ai-sdk/provider-utils": "5.0.33" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-znHNBWADOy79k8EK7636kDm5LmnjF4tMzegC2TfmlLDobDZbs0z0OXD2sxtH3eDTp5Re+pJQESvjinWJ6+kadQ=="],
@@ -1999,6 +1992,8 @@
"eventsource-parser": ["eventsource-parser@3.1.1", "", {}, "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ=="],
"execa": ["execa@10.2.1", "", { "dependencies": { "@sindresorhus/merge-streams": "^4.0.0", "figures": "^6.1.0", "get-stream": "^9.0.1", "human-signals": "^8.0.1", "is-plain-obj": "^4.1.0", "is-stream": "^4.0.1", "npm-run-path": "^6.0.0", "pretty-ms": "^9.3.1", "signal-exit": "^4.1.0", "strip-final-newline": "^4.0.0", "which-command": "^0.1.0", "yoctocolors": "^2.2.0" } }, "sha512-/Bofl3ZBh2Q4/PG0W63qFzP5vDAypi8Zc90UWTBzaDNIYiX7apPOd0N6L8hG8CojUdq4V51adu8BObP+iVsSTw=="],
"exiftool-vendored": ["exiftool-vendored@38.1.0", "", { "dependencies": { "@photostructure/tz-lookup": "^11.7.0", "@types/luxon": "^3.7.5", "batch-cluster": "^19.2.0", "he": "^1.2.0", "luxon": "^3.7.2" }, "optionalDependencies": { "exiftool-vendored.exe": "13.59.2", "exiftool-vendored.pl": "13.59.2" } }, "sha512-LIERqM/Qb0oqJlSswLFKWsxGVH81skp7omsX2BPKA/dEzfLP5syNO5KL7k5UlMCf+m0jqEXrKTQr/xV5vScPow=="],
"exiftool-vendored.exe": ["exiftool-vendored.exe@13.59.2", "", { "os": "win32" }, "sha512-U0l0CApIGO+AjpFYCiNCApQsMdlf6sqCyEl4wlKKqvwVAEVcvMRw91k7zj32OPFZE+/+XlLFsc6876MpOqBLiw=="],
@@ -2031,6 +2026,8 @@
"fast-safe-stringify": ["fast-safe-stringify@2.1.1", "", {}, "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA=="],
"fast-sha256": ["fast-sha256@1.3.0", "", {}, "sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ=="],
"fast-uri": ["fast-uri@3.1.6", "", {}, "sha512-7Ical1vFEMr0onbVzEDIreM22I4khW+fzyQPwvAFWBp1iwdshSZRsL4jjRvPG9JP1uiqMHRto+YU6R2/CzDz5Q=="],
"fd-slicer": ["fd-slicer@1.1.0", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g=="],
@@ -2041,6 +2038,8 @@
"fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="],
"figures": ["figures@6.1.0", "", { "dependencies": { "is-unicode-supported": "^2.0.0" } }, "sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg=="],
"file-entry-cache": ["file-entry-cache@8.0.0", "", { "dependencies": { "flat-cache": "^4.0.0" } }, "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ=="],
"find-my-way": ["find-my-way@9.7.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-querystring": "^1.0.0", "safe-regex2": "^5.0.0" } }, "sha512-f2JHn75x2JlwUwLenZypgczR7YWMb/uO9BvUXtus+JMgkbIkLADd38cI4EiV+OQqrGo1Zlq6V8wnqMJ8e62wUQ=="],
@@ -2097,7 +2096,7 @@
"get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
"get-stream": ["get-stream@5.2.0", "", { "dependencies": { "pump": "^3.0.0" } }, "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA=="],
"get-stream": ["get-stream@9.0.1", "", { "dependencies": { "@sec-ant/readable-stream": "^0.4.1", "is-stream": "^4.0.1" } }, "sha512-kVCxPF3vQM/N0B1PmoqVUqgHP+EeVjmZSQn+1oCRPxd2P21P2F19lIgbR3HBosbB1PUhOAoctJnfEn2GbN2eZA=="],
"get-symbol-description": ["get-symbol-description@1.1.0", "", { "dependencies": { "call-bound": "^1.0.3", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.6" } }, "sha512-w9UMqWwJxHNOvoNzSJ2oPF5wvYcvP7jUvYzhp67yEhTi17ZDBBC1z9pTdGuzjD+EFIqLSYRweZjqfiPzQ06Ebg=="],
@@ -2153,9 +2152,11 @@
"html-url-attributes": ["html-url-attributes@3.0.1", "", {}, "sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ=="],
"http-proxy-agent": ["http-proxy-agent@7.0.2", "", { "dependencies": { "agent-base": "^7.1.0", "debug": "^4.3.4" } }, "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig=="],
"http-proxy-agent": ["http-proxy-agent@9.1.0", "", { "dependencies": { "agent-base": "9.0.0", "debug": "^4.3.4", "proxy-agent-negotiate": "1.1.0" } }, "sha512-2NxoveTT58mjYT4n3RPTEfCZGLMbidoO8XEieXfpSYxu+PQJ1qpx4ypwH6N+uF9twBPIvRRgvkvW5HUTYWENig=="],
"https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
"https-proxy-agent": ["https-proxy-agent@9.1.0", "", { "dependencies": { "agent-base": "9.0.0", "debug": "^4.3.4", "proxy-agent-negotiate": "1.1.0" } }, "sha512-ag87y7cJJ9/3+GxFr8Oy4O5faDsGRGnBGsJj/YjOSsSx/5eadKLYTMPlzuR6obgoCDDm0abAAZitXXQkMOPSpA=="],
"human-signals": ["human-signals@8.0.1", "", {}, "sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ=="],
"iconv-lite": ["iconv-lite@0.7.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ=="],
@@ -2231,7 +2232,7 @@
"is-shared-array-buffer": ["is-shared-array-buffer@1.0.4", "", { "dependencies": { "call-bound": "^1.0.3" } }, "sha512-ISWac8drv4ZGfwKl5slpHG9OwPNty4jOWPRIhBpxOoD+hqITiwuipOQ2bNthAzwA3B4fIjO4Nln74N0S9byq8A=="],
"is-stream": ["is-stream@2.0.1", "", {}, "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg=="],
"is-stream": ["is-stream@4.0.1", "", {}, "sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A=="],
"is-string": ["is-string@1.1.1", "", { "dependencies": { "call-bound": "^1.0.3", "has-tostringtag": "^1.0.2" } }, "sha512-BtEeSsoaQjlSPBemMQIrY1MY0uM6vnS1g5fmufYOtnxLGUZM2178PKbhsk7Ffv58IX+ZtcvoGwccYsh0PglkAA=="],
@@ -2239,6 +2240,8 @@
"is-typed-array": ["is-typed-array@1.1.15", "", { "dependencies": { "which-typed-array": "^1.1.16" } }, "sha512-p3EcsicXjit7SaskXHs1hA91QxgTw46Fv6EFKKGS5DRFLD8yKnohjF3hxoju94b/OcMZoQukzpPpBE9uLVKzgQ=="],
"is-unicode-supported": ["is-unicode-supported@2.1.0", "", {}, "sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ=="],
"is-weakmap": ["is-weakmap@2.0.2", "", {}, "sha512-K5pXYOm9wqY1RgjpL3YTkF39tni1XajUIkawTLUo9EZEVUFga5gSQJF8nNS7ZwJQ02y+1YCNYcMh+HIf1ZqE+w=="],
"is-weakref": ["is-weakref@1.1.1", "", { "dependencies": { "call-bound": "^1.0.3" } }, "sha512-6i9mGWSlqzNMEqpCp93KwRS1uUOodk2OJ6b+sq7ZPDSy2WuI5NFIxp/254TytR8ftefexkWn5xNiHUNpPOfSew=="],
@@ -2463,7 +2466,7 @@
"node-fetch": ["node-fetch@3.3.2", "", { "dependencies": { "data-uri-to-buffer": "^4.0.0", "fetch-blob": "^3.1.4", "formdata-polyfill": "^4.0.10" } }, "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA=="],
"node-forge": ["node-forge@1.4.0", "", {}, "sha512-LarFH0+6VfriEhqMMcLX2F7SwSXeWwnEAJEsYm5QKWchiVYVvJyV9v7UDvUv+w5HO23ZpQTXDv/GxdDdMyOuoQ=="],
"node-forge": ["node-forge@1.4.3", "", {}, "sha512-P6wzfh6t70avmV8FrVEAd/36sOPJQ+hkaJVX1Laap9J/77m7M0eyozDvc8SwnDf4P7MP94gwbAAo0rg3YVXT+g=="],
"node-releases": ["node-releases@2.0.54", "", {}, "sha512-YHs7BmmcsdAI5Ozuf8JZo6PT0mv2GIWC9vMfvUC3dp65M8hn7Ux8CPL+2oBI7juNuj9d0ndhTcznq2ODBps9cQ=="],
@@ -2471,6 +2474,8 @@
"normalize-path": ["normalize-path@3.0.0", "", {}, "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA=="],
"npm-run-path": ["npm-run-path@6.0.0", "", { "dependencies": { "path-key": "^4.0.0", "unicorn-magic": "^0.3.0" } }, "sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA=="],
"object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
"object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
@@ -2493,7 +2498,7 @@
"once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
"openai": ["openai@6.26.0", "", { "peerDependencies": { "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["ws", "zod"], "bin": { "openai": "bin/cli" } }, "sha512-zd23dbWTjiJ6sSAX6s0HrCZi41JwTA1bQVs0wLQPZ2/5o2gxOJA5wh7yOAUgwYybfhDXyhwlpeQf7Mlgx8EOCA=="],
"openai": ["openai@7.19.0", "", { "peerDependencies": { "@aws-sdk/credential-provider-node": ">=3.972.0 <4", "@smithy/hash-node": ">=4.3.0 <5", "@smithy/signature-v4": ">=5.4.0 <6", "undici": ">=5 <9", "ws": "^8.21.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["@aws-sdk/credential-provider-node", "@smithy/hash-node", "@smithy/signature-v4", "undici", "ws", "zod"] }, "sha512-MX2s3u2L5racTO0CC/SWpCOasJQBCJrqLKXK+l82cAhdeF8mPMBEe/gxMm0ZFa2xpKpOFLRjxv5afYEZbBXmbQ=="],
"optionator": ["optionator@0.9.4", "", { "dependencies": { "deep-is": "^0.1.3", "fast-levenshtein": "^2.0.6", "levn": "^0.4.1", "prelude-ls": "^1.2.1", "type-check": "^0.4.0", "word-wrap": "^1.2.5" } }, "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g=="],
@@ -2515,6 +2520,8 @@
"parse-entities": ["parse-entities@4.0.2", "", { "dependencies": { "@types/unist": "^2.0.0", "character-entities-legacy": "^3.0.0", "character-reference-invalid": "^2.0.0", "decode-named-character-reference": "^1.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0", "is-hexadecimal": "^2.0.0" } }, "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw=="],
"parse-ms": ["parse-ms@4.0.0", "", {}, "sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw=="],
"partial-json": ["partial-json@0.1.7", "", {}, "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA=="],
"path-exists": ["path-exists@4.0.0", "", {}, "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w=="],
@@ -2597,6 +2604,8 @@
"pretty-format": ["pretty-format@27.5.1", "", { "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", "react-is": "^17.0.1" } }, "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ=="],
"pretty-ms": ["pretty-ms@9.3.1", "", { "dependencies": { "parse-ms": "^4.0.0" } }, "sha512-HzMy3Geq23nVALD/M2LliU+F+M+gVNsvkQWWqeBZ8HDiCgzo6YPJ/Omrmtq24EFrIsk0a3EkQGEd7bDOo+IhGA=="],
"prisma": ["prisma@7.10.0", "", { "dependencies": { "@prisma/config": "7.10.0", "@prisma/dev": "0.24.17", "@prisma/engines": "7.10.0", "@prisma/studio-core": "0.33.0", "mysql2": "3.15.3", "postgres": "3.4.7" }, "peerDependencies": { "better-sqlite3": ">=9.0.0", "typescript": ">=5.4.0" }, "optionalPeers": ["better-sqlite3", "typescript"], "bin": { "prisma": "build/index.js" } }, "sha512-o0ornyJOWgygVAzGCpr8PdXV8EJLHyVGDDUr/voBQt8Azzw8cYTByzzPGcA/m4tCkPcnJA8raEOv2CslsKhPEw=="],
"prisma-json-types-generator": ["prisma-json-types-generator@5.1.1", "", { "dependencies": { "@prisma/generator-helper": "^7.8.0", "semver": "^7.8.5", "try": "^1.0.3", "tslib": "^2.8.1", "typescript": "npm:typescript@^6.0.3" }, "peerDependencies": { "@prisma/client": "^7.8.0", "prisma": "^7.8.0" }, "bin": { "prisma-json-types-generator": "index.js" } }, "sha512-vtj68YkCla7bEnblC54xzKU3w+H/1uoKxtLU3F2eC9LL8j1Dz8GadVagKhQqQd03KGfHmO7o83Tf3yXxCKQwzQ=="],
@@ -2619,6 +2628,8 @@
"protobufjs": ["protobufjs@7.6.6", "", { "dependencies": { "@protobufjs/aspromise": "^1.1.2", "@protobufjs/base64": "^1.1.2", "@protobufjs/codegen": "^2.0.5", "@protobufjs/eventemitter": "^1.1.1", "@protobufjs/fetch": "^1.1.1", "@protobufjs/float": "^1.0.2", "@protobufjs/path": "^1.1.2", "@protobufjs/pool": "^1.1.0", "@protobufjs/utf8": "^1.1.1", "@types/node": ">=13.7.0", "long": "^5.3.2" } }, "sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg=="],
"proxy-agent-negotiate": ["proxy-agent-negotiate@1.1.0", "", { "peerDependencies": { "kerberos": "^2.0.0" }, "optionalPeers": ["kerberos"] }, "sha512-N8IBcM3UgCVzz2L2Lqv8DVntDnnC8/hiV4nEDUPkqq72TPUgYWjQc+bdZlBPZK9LzPAvOY//gAt0S0DApoOXWQ=="],
"pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
"punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
@@ -2627,6 +2638,8 @@
"quick-format-unescaped": ["quick-format-unescaped@4.0.4", "", {}, "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg=="],
"quickjs-wasi": ["quickjs-wasi@3.6.2", "", {}, "sha512-FCqGtGOrMgzUiIrMNMA2YnsOxCNwo31dzqXvclXUC6xeT35NJLKXQJsvbeCTjvoFAwZgEAPg8U6+KAPDGXn8Mg=="],
"radix-ui": ["radix-ui@1.6.7", "", { "dependencies": { "@radix-ui/primitive": "1.1.7", "@radix-ui/react-accessible-icon": "1.1.15", "@radix-ui/react-accordion": "1.2.20", "@radix-ui/react-alert-dialog": "1.1.23", "@radix-ui/react-arrow": "1.1.15", "@radix-ui/react-aspect-ratio": "1.1.15", "@radix-ui/react-avatar": "1.2.6", "@radix-ui/react-checkbox": "1.3.11", "@radix-ui/react-collapsible": "1.1.20", "@radix-ui/react-collection": "1.1.15", "@radix-ui/react-compose-refs": "1.1.5", "@radix-ui/react-context": "1.2.2", "@radix-ui/react-context-menu": "2.3.7", "@radix-ui/react-dialog": "1.1.23", "@radix-ui/react-direction": "1.1.4", "@radix-ui/react-dismissable-layer": "1.1.19", "@radix-ui/react-dropdown-menu": "2.1.24", "@radix-ui/react-focus-guards": "1.1.6", "@radix-ui/react-focus-scope": "1.1.16", "@radix-ui/react-form": "0.1.16", "@radix-ui/react-hover-card": "1.1.23", "@radix-ui/react-label": "2.1.15", "@radix-ui/react-menu": "2.1.24", "@radix-ui/react-menubar": "1.1.24", "@radix-ui/react-navigation-menu": "1.2.22", "@radix-ui/react-one-time-password-field": "0.1.16", "@radix-ui/react-password-toggle-field": "0.1.11", "@radix-ui/react-popover": "1.1.23", "@radix-ui/react-popper": "1.3.7", "@radix-ui/react-portal": "1.1.17", "@radix-ui/react-presence": "1.1.10", "@radix-ui/react-primitive": "2.1.10", "@radix-ui/react-progress": "1.1.16", "@radix-ui/react-radio-group": "1.4.7", "@radix-ui/react-roving-focus": "1.1.19", "@radix-ui/react-scroll-area": "1.2.18", "@radix-ui/react-select": "2.3.7", "@radix-ui/react-separator": "1.1.15", "@radix-ui/react-slider": "1.4.7", "@radix-ui/react-slot": "1.3.3", "@radix-ui/react-switch": "1.3.7", "@radix-ui/react-tabs": "1.1.21", "@radix-ui/react-toast": "1.2.23", "@radix-ui/react-toggle": "1.1.18", "@radix-ui/react-toggle-group": "1.1.19", "@radix-ui/react-toolbar": "1.1.19", "@radix-ui/react-tooltip": "1.2.16", "@radix-ui/react-use-callback-ref": "1.1.4", "@radix-ui/react-use-controllable-state": "1.2.6", "@radix-ui/react-use-effect-event": "0.0.5", "@radix-ui/react-use-escape-keydown": "1.1.5", "@radix-ui/react-use-is-hydrated": "0.1.3", "@radix-ui/react-use-layout-effect": "1.1.4", "@radix-ui/react-use-size": "1.1.4", "@radix-ui/react-visually-hidden": "1.2.11" }, "peerDependencies": { "@types/react": "*", "@types/react-dom": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react", "@types/react-dom"] }, "sha512-QBdhh1arIEUvPC0dQ5+nwWAxt7+N+oP/9jPwjJkGFoSk/sqxg32gJtSXGtFh8frAIcS6oC9cx2Q+7KYCQLOAeA=="],
"rc9": ["rc9@3.0.1", "", { "dependencies": { "defu": "^6.1.6", "destr": "^2.0.5" } }, "sha512-gMDyleLWVE+i6Sgtc0QbbY6pEKqYs97NGi6isHQPqYlLemPoO8dxQ3uGi0f4NiP98c+jMW6cG1Kx9dDwfvqARQ=="],
@@ -2755,7 +2768,7 @@
"siginfo": ["siginfo@2.0.0", "", {}, "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g=="],
"signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
"signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
"skin-tone": ["skin-tone@2.0.0", "", { "dependencies": { "unicode-emoji-modifier-base": "^1.0.0" } }, "sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA=="],
@@ -2781,6 +2794,8 @@
"stackback": ["stackback@0.0.2", "", {}, "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw=="],
"standardwebhooks": ["standardwebhooks@1.1.1", "", { "dependencies": { "@stablelib/base64": "^1.0.0", "fast-sha256": "^1.3.0" } }, "sha512-bCbX9ZEyFkWPsRz7Bl3NuQUJohmwGSev/yhr7vhaGPlc4AfIrspIRa6cPTBuI1ItmrTDJ4d/S2hCsfe4+vQGnQ=="],
"std-env": ["std-env@4.2.0", "", {}, "sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw=="],
"stop-iteration-iterator": ["stop-iteration-iterator@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "internal-slot": "^1.1.0" } }, "sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ=="],
@@ -2809,6 +2824,8 @@
"strip-ansi-cjs": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
"strip-final-newline": ["strip-final-newline@4.0.0", "", {}, "sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw=="],
"strip-json-comments": ["strip-json-comments@5.0.3", "", {}, "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw=="],
"style-to-js": ["style-to-js@1.1.21", "", { "dependencies": { "style-to-object": "1.0.14" } }, "sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ=="],
@@ -2907,6 +2924,8 @@
"unicode-trie": ["unicode-trie@2.0.0", "", { "dependencies": { "pako": "^0.2.5", "tiny-inflate": "^1.0.0" } }, "sha512-x7bc76x0bm4prf1VLg79uhAzKw8DVboClSN5VxJuQ+LKDOVEW9CdH+VY7SP+vX7xCYQqzzgQpFqz15zeLvAtZQ=="],
"unicorn-magic": ["unicorn-magic@0.3.0", "", {}, "sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA=="],
"unified": ["unified@11.0.5", "", { "dependencies": { "@types/unist": "^3.0.0", "bail": "^2.0.0", "devlop": "^1.0.0", "extend": "^3.0.0", "is-plain-obj": "^4.0.0", "trough": "^2.0.0", "vfile": "^6.0.0" } }, "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA=="],
"unist-util-is": ["unist-util-is@6.0.1", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g=="],
@@ -2969,6 +2988,8 @@
"which-collection": ["which-collection@1.0.2", "", { "dependencies": { "is-map": "^2.0.3", "is-set": "^2.0.3", "is-weakmap": "^2.0.2", "is-weakset": "^2.0.3" } }, "sha512-K4jVyjnBdgvc86Y6BkaLZEN933SwYOuBFkdmBu9ZfkcAbdVbpITnDmjvZ/aQjRXQrv5EPkTnD1s39GiiqbngCw=="],
"which-command": ["which-command@0.1.0", "", { "bin": { "which-command": "cli.js" } }, "sha512-XZyoF5/5hZtXitIwzrU4NKK+Wtbb9aB9CezUEw2Q0wlYK8NUYQxC1rRXgNueYLtBAJwXIb+/tFVk4dozciNJMA=="],
"which-typed-array": ["which-typed-array@1.1.22", "", { "dependencies": { "available-typed-arrays": "^1.0.7", "call-bind": "^1.0.9", "call-bound": "^1.0.4", "for-each": "^0.3.5", "get-proto": "^1.0.1", "gopd": "^1.2.0", "has-tostringtag": "^1.0.2" } }, "sha512-fvO4ExWMFsqyhG3AiPAObMuY1lxaqgYcxbc49CNdWDDECOJNgQyvsOWVwbZc+qf3rzRtxojBK+CMEv0Ld5CYpw=="],
"why-is-node-running": ["why-is-node-running@2.3.0", "", { "dependencies": { "siginfo": "^2.0.0", "stackback": "0.0.2" }, "bin": { "why-is-node-running": "cli.js" } }, "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w=="],
@@ -2983,7 +3004,7 @@
"wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
"ws": ["ws@8.21.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw=="],
"ws": ["ws@8.22.2", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-/rEZ2ejown2N5gxVTHUu9bVVC7ttu0/Tgzf5hbTOixR3Fs7mbbXgn2DbdbcKgJOmpQMtrIUWivtYuVMnp/W/yA=="],
"xtend": ["xtend@4.0.2", "", {}, "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ=="],
@@ -2997,20 +3018,20 @@
"yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
"yauzl": ["yauzl@2.10.0", "", { "dependencies": { "buffer-crc32": "~0.2.3", "fd-slicer": "~1.1.0" } }, "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g=="],
"yauzl": ["yauzl@3.4.0", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-jIH9yLR9wqr0wOS0TpBvo/g/2UgZH5qePVbjgRliiF0BYvOZyaBknKsF+x9Iht0O6sqgnB93rCICdOZFecJuDw=="],
"yjs": ["yjs@13.6.32", "", { "dependencies": { "lib0": "^0.2.99" } }, "sha512-lfiJIIC4Xayt5ItynE407ehlE03pCjeOc4hkR4yxxvvNJ4kuiN25B0g+Qp8XagYz361LLL7DCzR5bvFJ81QKtQ=="],
"yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
"yoctocolors": ["yoctocolors@2.2.0", "", {}, "sha512-xYqdZFUK/VYazNl/oCDYN+3WloWQwMfZxBoiNt6qNyk+xfOdi598muWE42rNZFp1kNOiqW936q5RhUdnpqElSg=="],
"zeptomatch": ["zeptomatch@2.1.0", "", { "dependencies": { "grammex": "^3.1.11", "graphmatch": "^1.1.0" } }, "sha512-KiGErG2J0G82LSpniV0CtIzjlJ10E04j02VOudJsPyPwNZgGnRKQy7I1R7GMyg/QswnE4l7ohSGrQbQbjXPPDA=="],
"zip-stream": ["zip-stream@6.0.1", "", { "dependencies": { "archiver-utils": "^5.0.0", "compress-commons": "^6.0.2", "readable-stream": "^4.0.0" } }, "sha512-zK7YHHz4ZXpW89AHXUPbQVGKI7uvkd3hzusTdotCg1UxyaVtg0zFJSTfW/Dq5f7OBBVnq6cZIaC8Ti4hb6dtCA=="],
"zod": ["zod@4.5.4", "", {}, "sha512-sC95tT5iHHH9gtpj6A81kh+NEaRAUFN+qlUPDUbRfOMvNf5QCBqsb3WgvnpVtK5Y+4UfA6KqufotuTvMGiTlsA=="],
"zod-to-json-schema": ["zod-to-json-schema@3.25.2", "", { "peerDependencies": { "zod": "^3.25.28 || ^4" } }, "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA=="],
"zustand": ["zustand@5.0.15", "", { "peerDependencies": { "@types/react": ">=18.0.0", "immer": ">=9.0.6", "react": ">=18.0.0", "use-sync-external-store": ">=1.2.0" }, "optionalPeers": ["@types/react", "immer", "react", "use-sync-external-store"] }, "sha512-MpSEjRiBkA9crSYeOUH32rJC7SVqAbm0Fqcqge/bUi2PPoLcBWKOsG+C8mevmpr8TwXHBVkChbbJiyvkE+i/3A=="],
"zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
@@ -3021,9 +3042,7 @@
"@anthropic-ai/sandbox-runtime/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
"@aws-crypto/sha256-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
"@aws-crypto/util/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node": ["@aws-sdk/credential-provider-node@3.972.92", "", { "dependencies": { "@aws-sdk/credential-provider-env": "^3.972.80", "@aws-sdk/credential-provider-http": "^3.972.82", "@aws-sdk/credential-provider-ini": "^3.973.25", "@aws-sdk/credential-provider-process": "^3.972.80", "@aws-sdk/credential-provider-sso": "^3.973.24", "@aws-sdk/credential-provider-web-identity": "^3.972.86", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/credential-provider-imds": "^4.5.2", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-jC3zmOo7Qxlk+oBivvSsS1Ph7sFGm0QfuhqDGbqgRXi4cxUYMG+dWtBwS2XYYXgc8TIVXJiwgQ65sbNpbYupTA=="],
"@aws-sdk/client-bedrock-runtime/@smithy/node-http-handler": ["@smithy/node-http-handler@4.11.3", "", { "dependencies": { "@smithy/core": "^3.33.3", "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-2jY1tSpERfPfWqyBV2pH+iGFaghVsIJszJNsT7hxtQYhVJpWDyc0LqOWI+nXOxOAHaEfZ4PXXtp1wW1TGpHhkA=="],
@@ -3039,16 +3058,16 @@
"@dbos-inc/dbos-sdk/commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
"@earendil-works/pi-agent-core/ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
"@dbos-inc/dbos-sdk/ws": ["ws@8.21.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw=="],
"@earendil-works/pi-agent-core/typebox": ["typebox@1.1.38", "", {}, "sha512-pZ0aQPmMmXoUvSbeuWf/Hzsc+avNw/Zd6VeE8CFgkVGWyuHPJvqeJJDeJqLve+K70LvjYIoleGcoJHPT17cWoA=="],
"@earendil-works/chord/ws": ["ws@8.21.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw=="],
"@earendil-works/pi-ai/@google/genai": ["@google/genai@1.52.0", "", { "dependencies": { "google-auth-library": "^10.3.0", "p-retry": "^4.6.2", "protobufjs": "^7.5.4", "ws": "^8.18.0" }, "peerDependencies": { "@modelcontextprotocol/sdk": "^1.25.2" }, "optionalPeers": ["@modelcontextprotocol/sdk"] }, "sha512-gwSvbpiN/17O9TbsqSsE/OzZcpv5Fo4RQjdngGgogtuB9RsyJ8ZHhX5KjHj1bp5N9snN2eK8LDGXSaWW2hof8Q=="],
"@earendil-works/pi-ai/typebox": ["typebox@1.1.38", "", {}, "sha512-pZ0aQPmMmXoUvSbeuWf/Hzsc+avNw/Zd6VeE8CFgkVGWyuHPJvqeJJDeJqLve+K70LvjYIoleGcoJHPT17cWoA=="],
"@earendil-works/pi-ai/@google/genai": ["@google/genai@2.21.0", "", { "dependencies": { "google-auth-library": "^10.3.0", "p-retry": "^4.6.2", "protobufjs": "^7.5.4", "ws": "^8.18.0" }, "peerDependencies": { "@modelcontextprotocol/sdk": "^1.25.2" }, "optionalPeers": ["@modelcontextprotocol/sdk"], "hasInstallScript": true }, "sha512-+PDtco2/Z0ONdzCGekCoCT+O1VJS9xJQNN4XzQpXG/t3El/SWWMkCWlFRO1KmivOHPa4Q0VjUYu1HBKCZ/v33Q=="],
"@eslint-community/eslint-utils/eslint-visitor-keys": ["eslint-visitor-keys@3.4.3", "", {}, "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag=="],
"@google/genai/ws": ["ws@8.21.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw=="],
"@grpc/grpc-js/@grpc/proto-loader": ["@grpc/proto-loader@0.8.1", "", { "dependencies": { "lodash.camelcase": "^4.3.0", "long": "^5.0.0", "protobufjs": "^7.5.5", "yargs": "^17.7.2" }, "bin": { "proto-loader-gen-types": "build/bin/proto-loader-gen-types.js" } }, "sha512-wtF6h+DY6M3YaDBPAmvuuA6jV8Sif9MjtOI5euKFWRgCDl5PeDpPsHR9u2l6St5ceY8AZgoNDww5+HvEsXFsGg=="],
"@inlang/paraglide-js/commander": ["commander@11.1.0", "", {}, "sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ=="],
@@ -3075,8 +3094,12 @@
"@reduxjs/toolkit/reselect": ["reselect@5.3.0", "", {}, "sha512-XGoLeRAVzUTcJ1qkxPQhDJyIZ5d6zzZD9nT7AEZOaaU9UbWclhycElmhO+VD5bFeLuzhPBaOV2oXC8uG35ZSpg=="],
"@shumai/cli/adm-zip": ["adm-zip@0.6.1", "", {}, "sha512-Xwrja8nx9e5o2N1my4DsKCeKpdrnACyr1wtbPxBDgGzKzKyE9kRtBFA8mWldI+RVlD7CBZNWY/wQ2+ydwOR6kQ=="],
"@shumai/webui/@types/react-dom": ["@types/react-dom@19.2.5", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-fMPwH9v7r/pp43yUd2/Mbiex5KouJwwR3dzHkhLREUC6764VyDsqxhAxv6OFEYR1RhjOyD1naqba8ECDBe7ZQg=="],
"@smithy/node-http-handler/@smithy/types": ["@smithy/types@4.19.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-r7jh49VJxGerfAcTQA6gXcKc+98zOp/tqRwzYjgOE+iSQsP6cEU1hq2QzbuipmP68QtYdY9wKEhiCQZIzHgZ4Q=="],
"@spectrum-web-components/action-button/@spectrum-web-components/icon": ["@spectrum-web-components/icon@0.37.0", "", { "dependencies": { "@spectrum-web-components/base": "^0.37.0", "@spectrum-web-components/iconset": "^0.37.0" } }, "sha512-DZ1yOKHxNQygzIJ7u9akYComDnMmxuTzfmYxxt9sHdUXmc1NbMkCJqEaAG/LYsdb+hc4xWaDTT9SzArLKZ/btA=="],
"@spectrum-web-components/action-group/@spectrum-web-components/icons-workflow": ["@spectrum-web-components/icons-workflow@0.37.0", "", { "dependencies": { "@spectrum-web-components/base": "^0.37.0", "@spectrum-web-components/icon": "^0.37.0" } }, "sha512-D1Dg+ZjlqbaU/2uKYhmMtZXQMVUw9J9LevHSKSzMFL+Y++JMqRROQuzwAOFW7tttCw1w0+3kIuv2ohkeE+8fNQ=="],
@@ -3219,6 +3242,8 @@
"@visx/vendor/d3-format": ["d3-format@3.1.0", "", {}, "sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA=="],
"archiver-utils/is-stream": ["is-stream@2.0.1", "", {}, "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg=="],
"bcrypt-pbkdf/tweetnacl": ["tweetnacl@0.14.5", "", {}, "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA=="],
"better-call/@better-fetch/fetch": ["@better-fetch/fetch@1.3.1", "", {}, "sha512-ABkD1WhyfPZprKRQI3bhATjeiFuNWC9PXhfGWqL+sg/gKrM977oFrYkdb4msM3hgUGonr7KlOsOFT5TU2rht9g=="],
@@ -3227,18 +3252,30 @@
"bl/readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="],
"compress-commons/is-stream": ["is-stream@2.0.1", "", {}, "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg=="],
"docker-modem/readable-stream": ["readable-stream@3.6.2", "", { "dependencies": { "inherits": "^2.0.3", "string_decoder": "^1.1.1", "util-deprecate": "^1.0.1" } }, "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA=="],
"dockerode/tar-fs": ["tar-fs@2.1.5", "", { "dependencies": { "chownr": "^1.1.1", "mkdirp-classic": "^0.5.2", "pump": "^3.0.0", "tar-stream": "^2.1.4" } }, "sha512-OboTd8mmMhZDNPV+UjQcK9yKAatXu2aJ+r1w4im1Otd4M4fl2hwvdoXUxIYHFTHWK/3y3FarBP70v3vwmGlOxw=="],
"eslint-plugin-react/minimatch": ["minimatch@3.1.5", "", { "dependencies": { "brace-expansion": "^1.1.7" } }, "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w=="],
"foreground-child/signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
"extract-zip/@types/yauzl": ["@types/yauzl@2.10.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q=="],
"extract-zip/get-stream": ["get-stream@5.2.0", "", { "dependencies": { "pump": "^3.0.0" } }, "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA=="],
"extract-zip/yauzl": ["yauzl@2.10.0", "", { "dependencies": { "buffer-crc32": "~0.2.3", "fd-slicer": "~1.1.0" } }, "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g=="],
"gaxios/https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
"gcp-metadata/google-logging-utils": ["google-logging-utils@1.2.0", "", {}, "sha512-WE9av4wKDZgRjBwgVUabocx8T6/7o3Ca1Fat46FXDhXVAFibzNadedcOXrdgd1Kzmk8tsk/9ZH89Wyf/SqeZ3A=="],
"glob/minimatch": ["minimatch@9.0.9", "", { "dependencies": { "brace-expansion": "^2.0.2" } }, "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg=="],
"happy-dom/@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
"happy-dom/ws": ["ws@8.21.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw=="],
"its-fine/@types/react-reconciler": ["@types/react-reconciler@0.28.9", "", { "peerDependencies": { "@types/react": "*" } }, "sha512-HHM3nxyUZ3zAylX8ZEyrDNd2XZOnQ0D5XfunJF5FLQnZbHHYq4UWvW1QfelQNXv1ICNkwYhfxjwfnqivYB6bFg=="],
"lazystream/readable-stream": ["readable-stream@2.3.8", "", { "dependencies": { "core-util-is": "~1.0.0", "inherits": "~2.0.3", "isarray": "~1.0.0", "process-nextick-args": "~2.0.0", "safe-buffer": "~5.1.1", "string_decoder": "~1.1.1", "util-deprecate": "~1.0.1" } }, "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA=="],
@@ -3249,6 +3286,8 @@
"lit-element/@lit/reactive-element": ["@lit/reactive-element@1.6.3", "", { "dependencies": { "@lit-labs/ssr-dom-shim": "^1.0.0" } }, "sha512-QuTgnG52Poic7uM1AN5yJ09QMe0O28e10XzSvWDz02TJiiKee4stsiownEIadWm8nYzyDAyT+gKzUoZmiWQtsQ=="],
"npm-run-path/path-key": ["path-key@4.0.0", "", {}, "sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ=="],
"p-retry/retry": ["retry@0.13.1", "", {}, "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg=="],
"parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],
@@ -3267,6 +3306,8 @@
"prop-types/react-is": ["react-is@16.13.1", "", {}, "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ=="],
"proper-lockfile/signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
"readdir-glob/minimatch": ["minimatch@5.1.9", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw=="],
"sharp/semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="],
@@ -3279,7 +3320,25 @@
"wrap-ansi-cjs/ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
"yauzl/buffer-crc32": ["buffer-crc32@0.2.13", "", {}, "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-env": ["@aws-sdk/credential-provider-env@3.972.80", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-uO5TiSvb6j1w9RTe5z28OaOmsrOxVQUPaC5+wZl50RfOXcrYD/KgnS8I9lfyGXc7sGbkCopK6VnhNIAoLqfewQ=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-http": ["@aws-sdk/credential-provider-http@3.972.82", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/fetch-http-handler": "^5.8.0", "@smithy/node-http-handler": "^4.14.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-vQzlDHlC24Yz42p+rT4NBoP/5VdetkBoujbOLq9h6QYWC8THuZSPYnXIR9OP3XcOrdMgPBBipOrdssfxnIiWUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini": ["@aws-sdk/credential-provider-ini@3.973.25", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/credential-provider-env": "^3.972.80", "@aws-sdk/credential-provider-http": "^3.972.82", "@aws-sdk/credential-provider-login": "^3.972.87", "@aws-sdk/credential-provider-process": "^3.972.80", "@aws-sdk/credential-provider-sso": "^3.973.24", "@aws-sdk/credential-provider-web-identity": "^3.972.86", "@aws-sdk/nested-clients": "^3.997.54", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/credential-provider-imds": "^4.5.2", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-b5xl71uCRdWsu7P1VeGpiGuCf6zfYETsSNOv8AmYVTrsgbvTJRXdmmOPVfxkvGGVNsiKkGctClQW3jAn0SZLug=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-process": ["@aws-sdk/credential-provider-process@3.972.80", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-xqfixO5aclje7tbQJDias+iNND5wp/3QZixCdZcVQpgWPTZ0V5DfTW9A804A5Z7ezu7sH3WRO+vzUjtiJBA8yg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso": ["@aws-sdk/credential-provider-sso@3.973.24", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/nested-clients": "^3.997.54", "@aws-sdk/token-providers": "3.1161.0", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-nlg3BKG03Cgzvv/dMnhxvDJPhAhQSpaN0RUdwgU7ziwkasoev7iI8el8Xy4Rd5sqzgaDUbV269fOXck5SargqA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity": ["@aws-sdk/credential-provider-web-identity@3.972.86", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/nested-clients": "^3.997.54", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-zKTyLJBEyfQBVlYqT6Jt+mYV4r8kGbWM7dn6v4Y4MRARizhYafjDXP/iMu76UMRhToSPNmIKX1XAb24gtpBFIA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/types": ["@aws-sdk/types@3.975.0", "", { "dependencies": { "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WQlhs6juByzWOzj5fwxOx0mPJaEqMcG/sDpl3Id61B3XhKE63xY+0QWcnG+sWR/sCfprmreyUo1lM7IKZmHMzw=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@smithy/core": ["@smithy/core@3.38.1", "", { "dependencies": { "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-U/mB2XiwTLaf+NSgLSWwJfptsMT/H8aBi0aTAA/E5e2/TagFeGCqAyhKGG0w0A9IWTkm4qYEmLoD/HB6aYfnRA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@smithy/types": ["@smithy/types@4.19.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-r7jh49VJxGerfAcTQA6gXcKc+98zOp/tqRwzYjgOE+iSQsP6cEU1hq2QzbuipmP68QtYdY9wKEhiCQZIzHgZ4Q=="],
"@earendil-works/pi-ai/@google/genai/ws": ["ws@8.21.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw=="],
"@isaacs/cliui/string-width/emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],
@@ -3383,6 +3442,10 @@
"eslint-plugin-react/minimatch/brace-expansion": ["brace-expansion@1.1.18", "", { "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" } }, "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw=="],
"extract-zip/yauzl/buffer-crc32": ["buffer-crc32@0.2.13", "", {}, "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ=="],
"gaxios/https-proxy-agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
"glob/minimatch/brace-expansion": ["brace-expansion@2.1.4", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg=="],
"lazystream/readable-stream/isarray": ["isarray@1.0.0", "", {}, "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ=="],
@@ -3393,6 +3456,32 @@
"readdir-glob/minimatch/brace-expansion": ["brace-expansion@2.1.4", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-env/@aws-sdk/core": ["@aws-sdk/core@3.979.1", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@aws-sdk/xml-builder": "^3.972.42", "@aws/lambda-invoke-store": "^0.3.0", "@smithy/core": "^3.38.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "bowser": "^2.11.0", "tslib": "^2.6.2" } }, "sha512-ayOlV1VhLNMiq8PW9ZkVobG4gkldnUoHjG69yy2b8j+VYFlhz/uAL7ZdYQAoQ+eShtGUdNDnnG5rxDg6yUJrOg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-http/@aws-sdk/core": ["@aws-sdk/core@3.979.1", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@aws-sdk/xml-builder": "^3.972.42", "@aws/lambda-invoke-store": "^0.3.0", "@smithy/core": "^3.38.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "bowser": "^2.11.0", "tslib": "^2.6.2" } }, "sha512-ayOlV1VhLNMiq8PW9ZkVobG4gkldnUoHjG69yy2b8j+VYFlhz/uAL7ZdYQAoQ+eShtGUdNDnnG5rxDg6yUJrOg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-http/@smithy/fetch-http-handler": ["@smithy/fetch-http-handler@5.8.0", "", { "dependencies": { "@smithy/core": "^3.33.3", "@smithy/types": "^4.18.0", "tslib": "^2.6.2" } }, "sha512-ycSJu3tFAQ4v04CBB0agqFMVsSQ1iG3yw+SpgxRqKfaURpQD4CZ8Wn0zPMmSnOuTpTh65Vz+EA0rMrw089wvkA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-http/@smithy/node-http-handler": ["@smithy/node-http-handler@4.14.1", "", { "dependencies": { "@smithy/core": "^3.38.1", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-/T6E1jzCL0fErS9uq8JqES/5yYQQ4ppVmmYHwXw2nlov8KFzLb+3QqHR5iAun1BsuAB50IPxZliV8YMgghLwhA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/core": ["@aws-sdk/core@3.979.1", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@aws-sdk/xml-builder": "^3.972.42", "@aws/lambda-invoke-store": "^0.3.0", "@smithy/core": "^3.38.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "bowser": "^2.11.0", "tslib": "^2.6.2" } }, "sha512-ayOlV1VhLNMiq8PW9ZkVobG4gkldnUoHjG69yy2b8j+VYFlhz/uAL7ZdYQAoQ+eShtGUdNDnnG5rxDg6yUJrOg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/credential-provider-login": ["@aws-sdk/credential-provider-login@3.972.87", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/nested-clients": "^3.997.54", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-C4ZFmcwM+Zj14Z8huVUk54Gv4uzT1ZdzG9cY3Gdh8FePakq7Bss1OFsgZjAhWFOkFOGpBvFBeu0OWjWf8HNKRQ=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/nested-clients": ["@aws-sdk/nested-clients@3.997.54", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/signature-v4-multi-region": "^3.996.51", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/fetch-http-handler": "^5.8.0", "@smithy/node-http-handler": "^4.14.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-/OczlavsS7U5sOodRO10Ug4R/AKFVZiXTstKipWe68EfjPkmdDFNXNl9FCJyXWkg1DG6RBm3qAuVB8FNW9O8KQ=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-process/@aws-sdk/core": ["@aws-sdk/core@3.979.1", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@aws-sdk/xml-builder": "^3.972.42", "@aws/lambda-invoke-store": "^0.3.0", "@smithy/core": "^3.38.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "bowser": "^2.11.0", "tslib": "^2.6.2" } }, "sha512-ayOlV1VhLNMiq8PW9ZkVobG4gkldnUoHjG69yy2b8j+VYFlhz/uAL7ZdYQAoQ+eShtGUdNDnnG5rxDg6yUJrOg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/core": ["@aws-sdk/core@3.979.1", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@aws-sdk/xml-builder": "^3.972.42", "@aws/lambda-invoke-store": "^0.3.0", "@smithy/core": "^3.38.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "bowser": "^2.11.0", "tslib": "^2.6.2" } }, "sha512-ayOlV1VhLNMiq8PW9ZkVobG4gkldnUoHjG69yy2b8j+VYFlhz/uAL7ZdYQAoQ+eShtGUdNDnnG5rxDg6yUJrOg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/nested-clients": ["@aws-sdk/nested-clients@3.997.54", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/signature-v4-multi-region": "^3.996.51", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/fetch-http-handler": "^5.8.0", "@smithy/node-http-handler": "^4.14.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-/OczlavsS7U5sOodRO10Ug4R/AKFVZiXTstKipWe68EfjPkmdDFNXNl9FCJyXWkg1DG6RBm3qAuVB8FNW9O8KQ=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/token-providers": ["@aws-sdk/token-providers@3.1161.0", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/nested-clients": "^3.997.54", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-ypbXSofNcSHwf/KA40bFCXJb0MLaAKrfT7sot4dFaA+2lsuXNah4zLRJIAU7Qmvs9PFJ6rnY0bZFEC+mE7attA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/core": ["@aws-sdk/core@3.979.1", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@aws-sdk/xml-builder": "^3.972.42", "@aws/lambda-invoke-store": "^0.3.0", "@smithy/core": "^3.38.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "bowser": "^2.11.0", "tslib": "^2.6.2" } }, "sha512-ayOlV1VhLNMiq8PW9ZkVobG4gkldnUoHjG69yy2b8j+VYFlhz/uAL7ZdYQAoQ+eShtGUdNDnnG5rxDg6yUJrOg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/nested-clients": ["@aws-sdk/nested-clients@3.997.54", "", { "dependencies": { "@aws-sdk/core": "^3.979.1", "@aws-sdk/signature-v4-multi-region": "^3.996.51", "@aws-sdk/types": "^3.975.0", "@smithy/core": "^3.38.0", "@smithy/fetch-http-handler": "^5.8.0", "@smithy/node-http-handler": "^4.14.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-/OczlavsS7U5sOodRO10Ug4R/AKFVZiXTstKipWe68EfjPkmdDFNXNl9FCJyXWkg1DG6RBm3qAuVB8FNW9O8KQ=="],
"@prisma/studio-core/@radix-ui/react-toggle/@radix-ui/react-primitive/@radix-ui/react-slot": ["@radix-ui/react-slot@1.2.3", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.2" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A=="],
"@prisma/studio-core/@radix-ui/react-toggle/@radix-ui/react-use-controllable-state/@radix-ui/react-use-effect-event": ["@radix-ui/react-use-effect-event@0.0.2", "", { "dependencies": { "@radix-ui/react-use-layout-effect": "1.1.1" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-Qp8WbZOBe+blgpuUT+lw2xheLP8q0oatc9UpmiemEICxGvFLYmHm9QowVZGHtJlGbS6A6yJ3iViad/2cVjnOiA=="],
@@ -3419,6 +3508,70 @@
"readdir-glob/minimatch/brace-expansion/balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-env/@aws-sdk/core/@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.42", "", { "dependencies": { "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-smX8/gNP8Kjq+CWTBMZQLQ912vOQjiWExzwzvMO+eujPB5RY8IbtF0AGdUUXHKN7KoDWK9dIcuW0WG269kiP6w=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-env/@aws-sdk/core/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-http/@aws-sdk/core/@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.42", "", { "dependencies": { "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-smX8/gNP8Kjq+CWTBMZQLQ912vOQjiWExzwzvMO+eujPB5RY8IbtF0AGdUUXHKN7KoDWK9dIcuW0WG269kiP6w=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-http/@aws-sdk/core/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-http/@smithy/fetch-http-handler/@smithy/core": ["@smithy/core@3.33.3", "", { "dependencies": { "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-CsOeKq/9kA3y6VJHt+/+VTCtBaxJ4OTFpgrjIUhPpDIKxBci1k2bJaQASF2h/ELWrulGp+t97DZ0mevfAD8idg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/core/@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.42", "", { "dependencies": { "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-smX8/gNP8Kjq+CWTBMZQLQ912vOQjiWExzwzvMO+eujPB5RY8IbtF0AGdUUXHKN7KoDWK9dIcuW0WG269kiP6w=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/core/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/nested-clients/@aws-sdk/signature-v4-multi-region": ["@aws-sdk/signature-v4-multi-region@3.996.51", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-+aHvUugVBuMPXxgkPfWnTMyGdE/yWS8GHi5+qQ37HowS0YqzrbuaDLznj+Dtmtu5jgCdqz36gXmujOToUhNNWw=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/nested-clients/@smithy/fetch-http-handler": ["@smithy/fetch-http-handler@5.8.0", "", { "dependencies": { "@smithy/core": "^3.33.3", "@smithy/types": "^4.18.0", "tslib": "^2.6.2" } }, "sha512-ycSJu3tFAQ4v04CBB0agqFMVsSQ1iG3yw+SpgxRqKfaURpQD4CZ8Wn0zPMmSnOuTpTh65Vz+EA0rMrw089wvkA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/nested-clients/@smithy/node-http-handler": ["@smithy/node-http-handler@4.14.1", "", { "dependencies": { "@smithy/core": "^3.38.1", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-/T6E1jzCL0fErS9uq8JqES/5yYQQ4ppVmmYHwXw2nlov8KFzLb+3QqHR5iAun1BsuAB50IPxZliV8YMgghLwhA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-process/@aws-sdk/core/@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.42", "", { "dependencies": { "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-smX8/gNP8Kjq+CWTBMZQLQ912vOQjiWExzwzvMO+eujPB5RY8IbtF0AGdUUXHKN7KoDWK9dIcuW0WG269kiP6w=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-process/@aws-sdk/core/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/core/@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.42", "", { "dependencies": { "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-smX8/gNP8Kjq+CWTBMZQLQ912vOQjiWExzwzvMO+eujPB5RY8IbtF0AGdUUXHKN7KoDWK9dIcuW0WG269kiP6w=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/core/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/nested-clients/@aws-sdk/signature-v4-multi-region": ["@aws-sdk/signature-v4-multi-region@3.996.51", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-+aHvUugVBuMPXxgkPfWnTMyGdE/yWS8GHi5+qQ37HowS0YqzrbuaDLznj+Dtmtu5jgCdqz36gXmujOToUhNNWw=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/nested-clients/@smithy/fetch-http-handler": ["@smithy/fetch-http-handler@5.8.0", "", { "dependencies": { "@smithy/core": "^3.33.3", "@smithy/types": "^4.18.0", "tslib": "^2.6.2" } }, "sha512-ycSJu3tFAQ4v04CBB0agqFMVsSQ1iG3yw+SpgxRqKfaURpQD4CZ8Wn0zPMmSnOuTpTh65Vz+EA0rMrw089wvkA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/nested-clients/@smithy/node-http-handler": ["@smithy/node-http-handler@4.14.1", "", { "dependencies": { "@smithy/core": "^3.38.1", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-/T6E1jzCL0fErS9uq8JqES/5yYQQ4ppVmmYHwXw2nlov8KFzLb+3QqHR5iAun1BsuAB50IPxZliV8YMgghLwhA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/core/@aws-sdk/xml-builder": ["@aws-sdk/xml-builder@3.972.42", "", { "dependencies": { "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-smX8/gNP8Kjq+CWTBMZQLQ912vOQjiWExzwzvMO+eujPB5RY8IbtF0AGdUUXHKN7KoDWK9dIcuW0WG269kiP6w=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/core/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/nested-clients/@aws-sdk/signature-v4-multi-region": ["@aws-sdk/signature-v4-multi-region@3.996.51", "", { "dependencies": { "@aws-sdk/types": "^3.975.0", "@smithy/signature-v4": "^5.7.5", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-+aHvUugVBuMPXxgkPfWnTMyGdE/yWS8GHi5+qQ37HowS0YqzrbuaDLznj+Dtmtu5jgCdqz36gXmujOToUhNNWw=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/nested-clients/@smithy/fetch-http-handler": ["@smithy/fetch-http-handler@5.8.0", "", { "dependencies": { "@smithy/core": "^3.33.3", "@smithy/types": "^4.18.0", "tslib": "^2.6.2" } }, "sha512-ycSJu3tFAQ4v04CBB0agqFMVsSQ1iG3yw+SpgxRqKfaURpQD4CZ8Wn0zPMmSnOuTpTh65Vz+EA0rMrw089wvkA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/nested-clients/@smithy/node-http-handler": ["@smithy/node-http-handler@4.14.1", "", { "dependencies": { "@smithy/core": "^3.38.1", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-/T6E1jzCL0fErS9uq8JqES/5yYQQ4ppVmmYHwXw2nlov8KFzLb+3QqHR5iAun1BsuAB50IPxZliV8YMgghLwhA=="],
"@prisma/studio-core/@radix-ui/react-toggle/@radix-ui/react-primitive/@radix-ui/react-slot/@radix-ui/react-compose-refs": ["@radix-ui/react-compose-refs@1.1.2", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-http/@smithy/fetch-http-handler/@smithy/core/@smithy/types": ["@smithy/types@4.17.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-FOKpVZob9MPTn2znRzGrnsMHv7BOsKVw3XiP/cOyYLDVZ9qKp4nifIiSCuUU/fIj5Vu0UOAxCFr+qRAtG0NUkA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/nested-clients/@aws-sdk/signature-v4-multi-region/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/nested-clients/@smithy/fetch-http-handler/@smithy/core": ["@smithy/core@3.33.3", "", { "dependencies": { "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-CsOeKq/9kA3y6VJHt+/+VTCtBaxJ4OTFpgrjIUhPpDIKxBci1k2bJaQASF2h/ELWrulGp+t97DZ0mevfAD8idg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/nested-clients/@aws-sdk/signature-v4-multi-region/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/nested-clients/@smithy/fetch-http-handler/@smithy/core": ["@smithy/core@3.33.3", "", { "dependencies": { "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-CsOeKq/9kA3y6VJHt+/+VTCtBaxJ4OTFpgrjIUhPpDIKxBci1k2bJaQASF2h/ELWrulGp+t97DZ0mevfAD8idg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/nested-clients/@aws-sdk/signature-v4-multi-region/@smithy/signature-v4": ["@smithy/signature-v4@5.7.5", "", { "dependencies": { "@smithy/core": "^3.38.0", "@smithy/types": "^4.19.0", "tslib": "^2.6.2" } }, "sha512-WPjdr5oWOk1LArpI4pavu+fSo+/evi0Re1olxGvqwuZopd4gYR1UGCi+Soyn/IjmafqbWs+ZC+3AKxJS3ZpwUg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/nested-clients/@smithy/fetch-http-handler/@smithy/core": ["@smithy/core@3.33.3", "", { "dependencies": { "@smithy/types": "^4.17.2", "tslib": "^2.6.2" } }, "sha512-CsOeKq/9kA3y6VJHt+/+VTCtBaxJ4OTFpgrjIUhPpDIKxBci1k2bJaQASF2h/ELWrulGp+t97DZ0mevfAD8idg=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-ini/@aws-sdk/nested-clients/@smithy/fetch-http-handler/@smithy/core/@smithy/types": ["@smithy/types@4.17.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-FOKpVZob9MPTn2znRzGrnsMHv7BOsKVw3XiP/cOyYLDVZ9qKp4nifIiSCuUU/fIj5Vu0UOAxCFr+qRAtG0NUkA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-sso/@aws-sdk/nested-clients/@smithy/fetch-http-handler/@smithy/core/@smithy/types": ["@smithy/types@4.17.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-FOKpVZob9MPTn2znRzGrnsMHv7BOsKVw3XiP/cOyYLDVZ9qKp4nifIiSCuUU/fIj5Vu0UOAxCFr+qRAtG0NUkA=="],
"@aws-sdk/client-bedrock-runtime/@aws-sdk/credential-provider-node/@aws-sdk/credential-provider-web-identity/@aws-sdk/nested-clients/@smithy/fetch-http-handler/@smithy/core/@smithy/types": ["@smithy/types@4.17.2", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-FOKpVZob9MPTn2znRzGrnsMHv7BOsKVw3XiP/cOyYLDVZ9qKp4nifIiSCuUU/fIj5Vu0UOAxCFr+qRAtG0NUkA=="],
}
}
@@ -21,11 +21,6 @@ services:
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'
@@ -51,9 +46,6 @@ services:
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
@@ -31,11 +31,6 @@ services:
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'
@@ -61,9 +56,6 @@ services:
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
@@ -16,11 +16,6 @@ services:
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'
@@ -46,9 +41,6 @@ services:
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL: http://localhost:3000
# Sandbox Configuration
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
depends_on:
postgres:
condition: service_healthy
@@ -21,11 +21,6 @@ services:
shumai:
image: shumaione/shumai:latest
cap_add:
- SYS_ADMIN
security_opt:
- apparmor=unconfined
- seccomp=unconfined
container_name: shumai_app
ports:
- '3000:3000'
@@ -51,9 +46,6 @@ services:
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
@@ -31,11 +31,6 @@ services:
shumai:
image: shumaione/shumai:latest
cap_add:
- SYS_ADMIN
security_opt:
- apparmor=unconfined
- seccomp=unconfined
container_name: shumai_app
ports:
- '3000:3000'
@@ -61,9 +56,6 @@ services:
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
-8
View File
@@ -16,11 +16,6 @@ services:
shumai:
image: shumaione/shumai:latest
cap_add:
- SYS_ADMIN
security_opt:
- apparmor=unconfined
- seccomp=unconfined
container_name: shumai_app
ports:
- '3000:3000'
@@ -46,9 +41,6 @@ services:
BETTER_AUTH_SECRET: qSxs9DxzHDZBbeeTNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL: http://localhost:3000
# Sandbox Configuration
ENABLE_WEAKER_NESTED_SANDBOX: 'true'
depends_on:
postgres:
condition: service_healthy
+65
View File
@@ -3,6 +3,71 @@ title: "Changelog"
description: "Recent updates, new features, and improvements in Shumai"
---
<Update label="v0.7.0" description="November 18, 2026">
### Added
- **i18n**: Add Korean as a display language, selectable on the sign-up page and in team settings.
### Fixed
- **cli**: Fix release publication failing to find staged standalone downloads.
### Changed
- **agent**: ⚠️ **Breaking Change**: Replaced the built-in server-side Bash sandbox with external Runners and removed the team-level sandbox domain allowlist settings. The Bash tool is now disabled by default. If your Agent or Skills require Bash execution, you'll need to set up and connect an external Runner using shumai-cli. The Shumai CLI includes built-in sandbox support, allowing you to configure filesystem access and network domain allowlists for Bash execution directly on the Runner. See [Agent Runners](https://docs.shumai.one/using-shumai/agent-sandbox) for setup instructions and configuration details. The Docker Compose configuration has also been updated to improve security following the removal of the server-side sandbox. We strongly recommend upgrading to the latest Shumai image and updating your Docker Compose file to apply these security improvements.
- **cli**: Show copyable commands and shell configuration instructions when the standalone CLI installation directory is missing from PATH.
</Update>
<Update label="v0.6.6" description="November 13, 2026">
### Added
- **project**: Support creating new projects via the built-in agent, MCP server, and CLI (`shumai-cli project create`).
- **cli**: Add standalone downloads and one-line installers for macOS, Linux, and Windows without requiring Node.js or Bun, with verified downloads, version selection, and upgrade support.
### Fixed
- **storage**: Remove empty local folders left behind after generating video search embeddings.
### Changed
- **agent**: Upgrade the agent runtime and automatically migrate existing conversations, keep thread histories independent, prevent duplicate history during simultaneous mentions, improve session log scrolling and readability, and fix authentication for OpenAI and custom providers. Agents now run with the main server; standalone agent workers are no longer supported.
</Update>
<Update label="v0.6.5" description="November 7, 2026">
### 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
</Update>
<Update label="v0.6.4" description="November 5, 2026">
### 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)
</Update>
<Update label="v0.6.3" description="November 1, 2026">
### Added
+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.
+20 -74
View File
@@ -1,39 +1,20 @@
---
title: Deploy with Distributed Workers
description: Configure a high-scale production deployment using dedicated background workers, DBOS, and S3-compatible storage.
description: Run media transcoding on dedicated workers while agents run with the main server.
---
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.
Shumai runs agent, embedding, and archive queues with the main web server. Media transcoding can run on dedicated workers through PostgreSQL queues managed by DBOS Transact.
```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]
User[User] --> Server[Shumai Web UI / API + Agents + Archives]
Server --> DB[(PostgreSQL / DBOS Queues)]
DB --> Transcode[Dedicated Transcode Workers]
```
- **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.
## Main Server
> [!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`:
Set `SHUMAI_WORKERS=none` (or `--workers=none`) to run agents and archives with the main server and send transcoding jobs to dedicated workers. `all` and `transcode` also run the transcode queue in the server. The older `agent`, `ai`, and `archive` values remain accepted and run agents and archives.
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
@@ -47,67 +28,30 @@ 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.
Agent tools run on the server, so install its sandbox dependencies (`bubblewrap` on Linux or `sandbox-exec` on macOS). Standalone agent workers are no longer supported.
---
## Dedicated Transcode Workers
## 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`):
Configure workers with the same PostgreSQL database and S3 storage as the server. A shared S3-compatible backend is required when machines do not share a filesystem.
```bash
npm install -g @shumai-one/shumai-transcode
shumai-transcode
```
Alternatively, you can run the transcode worker using the dedicated lightweight Docker image:
Or use the dedicated image:
```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-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`.)
Bun users can run `bun run --bun shumai-transcode`.
### AI Agent Worker
## Upgrading Existing Agent Sessions
Run this on your sandboxed agent execution nodes (requires sandbox dependencies like `bubblewrap` or `sandbox-exec`):
Stop and drain old agent workers before upgrading the server. The normal database migration copies existing session context into independent histories automatically. No separate migration command is required. Legacy records remain in the database during this transition.
```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`).
Each session uses a local SQLite working copy, restored from PostgreSQL when missing. `AGENT_SESSION_CACHE_DIR` optionally selects the cache directory. Within each server process, history reads and the active agent share the same SQLite database. History can show locally committed entries before PostgreSQL persistence completes; these entries may disappear after recovery if persistence fails. The server mirrors compact session commits to PostgreSQL before acknowledging them. Keep the database in your backup policy; local SQLite copies are disposable. Image and skill placeholders remain compact in both copies and are resolved when the agent needs them.
---
@@ -118,16 +62,18 @@ docker run -d \
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`).
- `CONCURRENCY_AGENT`: Maximum concurrent agent and embedding workflows per main server (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:
When running multiple replicas of the transcode workers or main servers 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.
Agent runners require a single main server per database. With runners configured, stop the old main server before starting its replacement. For Kubernetes, use a single main server replica with the Recreate deployment strategy. Transcode workers can still scale independently.
---
## Scalable Deployment on Kubernetes & AWS EKS
+21 -1
View File
@@ -61,6 +61,25 @@ 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
@@ -69,8 +88,9 @@ Configures background worker execution, concurrency limits, and worker identity
| Variable | Description | Example / Default |
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------- |
| `SHUMAI_WORKERS` | Queues listened to by the web server. Options: `all` (default), `none` (API/UI only), `agent` (or `ai`), `transcode`. | `all` (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` |
+168 -60
View File
@@ -14,6 +14,10 @@
},
"navbar": {
"links": [
{
"label": "Forum",
"href": "https://shumai.discourse.group/"
},
{
"label": "Changelog",
"href": "/changelog"
@@ -21,71 +25,175 @@
]
},
"navigation": {
"groups": [
"languages": [
{
"group": "Getting Started",
"pages": [
"getting-started/overview",
"getting-started/quickstart",
"getting-started/s3-storage"
"language": "en",
"default": true,
"navbar": {
"links": [
{
"label": "Forum",
"href": "https://shumai.discourse.group/"
},
{
"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/3d-asset-support",
"using-shumai/gotenberg",
"using-shumai/embedding-server"
"language": "zh",
"navbar": {
"links": [
{
"label": "论坛",
"href": "https://shumai.discourse.group/"
},
{
"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/email-notifications",
"using-shumai/password-reset"
]
},
{
"group": "Developer",
"pages": ["developer/mcp-server"]
},
{
"group": "Configuration",
"pages": ["configuration/env-variables", "configuration/hardware-transcoding"]
},
{
"group": "Distributed Deployment",
"pages": ["configuration/distributed"]
},
{
"group": "Releases",
"pages": ["changelog"]
}
]
}
+31 -2
View File
@@ -44,7 +44,16 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
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`). This is required for remote servers and production deployments.
- `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:
@@ -90,7 +99,7 @@ Docker Compose is the fastest way to get Shumai running. You do not need to clon
### 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.
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 to dedicated worker nodes to keep your main dashboard fast and responsive. For setup instructions, see the [Deploy with Distributed Workers](/configuration/distributed) guide.
---
@@ -207,3 +216,23 @@ To set up Shumai locally for development:
bun run dev
```
This spins up the web server on port `3000` with hot-reloading active.
---
## Install the command-line client
To connect to a running Shumai server, install the standalone CLI without Node.js or Bun:
```sh
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
```
On Windows:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
```
Native releases support macOS, Linux with glibc, and Windows on ARM64 and x64. The scripts verify SHA-256 checksums and install into your user directory. Re-run the installer to upgrade, and check the installed version with `shumai-cli --version`. The npm alternative, `npm install -g @shumai-one/shumai-cli`, requires Node.js 22.12+.
Set `SHUMAI_API_SERVER` to your server URL and `SHUMAI_API_KEY` to a personal API token from Settings → API Tokens, then run `shumai-cli project ls`. See the [CLI guide](https://github.com/shumaiOne/shumai/blob/main/apps/cli/README.md) for supported OS versions, PATH setup, pinned versions, rollback, and uninstall instructions.
+81 -25
View File
@@ -1,45 +1,101 @@
---
title: Agent Sandbox
description: Secure execution environment and network domain restrictions for AI agent scripts.
title: Agent Runners
description: Connect an optional command runner and configure sandboxing on its machine.
---
Running automated scripts poses security risks. Shumai resolves this by executing all agent skills inside a secure, isolated **Sandbox** environment.
Agents use Shumai's built-in tools without a runner. To execute shell commands or download assets into a shell workspace, connect a **runner** on a machine you control. The runner opens an authenticated outbound WebSocket connection; no inbound port is needed.
---
Agent runners require one main Shumai server per database. Multiple main servers can share a database while it has no configured runners. Stop the other main servers before creating a runner. Transcode workers can run separately.
## Sandbox Security
## Connect a runner
The sandbox restricts the execution process from accessing the host filesystem, system processes, and internal networks:
1. In **Settings → Agent Runners**, create a runner and copy its one-time key. Only team owners can manage runners and rotate their keys.
2. Install [Shumai CLI](https://github.com/shumaiOne/shumai/tree/main/apps/cli#installation) on macOS, Linux, or Windows.
3. Start it in a dedicated, existing workspace:
- **Isolation**: Scripts run in a virtualized workspace container that prevents them from modifying critical system files or reading other project data.
- **Network Bridging**: External network calls from inside the sandbox are strictly monitored.
```bash
export SHUMAI_API_SERVER="https://shumai.example.com"
export SHUMAI_RUNNER_KEY="your-runner-key"
shumai-cli runner start --cwd /path/to/workspace
```
### File System Restrictions
On Windows, set the variables in PowerShell:
To protect your workspace environments and sensitive data, the sandbox enforces strict file-level access controls:
```powershell
$env:SHUMAI_API_SERVER = "https://shumai.example.com"
$env:SHUMAI_RUNNER_KEY = "your-runner-key"
shumai-cli runner start --cwd C:\workspace
```
- **Read Access**: The sandbox is allowed to read files within the workspace, with a strict exception for sensitive environment and certificate files. It cannot read: `['.env', '.env.*', '*.pem', '*.key']`.
- **Write Access**: The sandbox is heavily restricted and may only write to the `.pi` folder located in the current working directory (cwd). Even within this allowed directory, the sandbox is explicitly blocked from writing or creating sensitive files matching: `['.env', '.env.*', '*.pem', '*.key']`.
Use a runner key, not a personal API token. Prefer the environment variable over `--key` to keep the key out of shell history. The runner stays in the foreground; Ctrl+C stops it and its active commands. Temporary connection losses trigger reconnection. Revoked or replaced connections stop instead of reconnecting.
---
The first runner becomes the team default. Each agent can use that default or a dedicated runner selected in its settings. Without a configured runner, `bash` and `download_asset` are hidden. With one configured, authorized editors and reviewers can run commands immediately without reading a skill first. Disabled-tool policies still apply. An offline runner produces an execution error.
## Domain Whitelisting
The `bash` tool uses `/bin/sh` on macOS and Linux. On Windows, the runner looks for Git Bash in the standard installation directories, then for `bash.exe` on PATH, and falls back to `cmd.exe`. The runner prints its selected shell at startup and reports it to the agent so it can use compatible syntax. For Bash with SRT on Windows, use Git Bash in place of the legacy WSL Bash launcher.
By default, Network Sandbox is **disabled** (allowing all outbound network requests). Team Owners can toggle Network Sandbox **ON** in Sandbox Settings to enforce strict domain whitelisting:
Commands start in the workspace directory. Skills, downloaded assets, generated files, and output logs live under `.pi`. Commands inherit baseline OS settings and explicit skill variables, rather than the runner's full environment, including its runner key and personal API token.
### Allowed Domains
Everyone with shell access to the same runner can read files left in its workspace, including assets and logs from other projects. Shumai project permissions apply when assets are downloaded. Share a runner only among users who may read all files in that workspace. For separate trust groups, use separate runner accounts or virtual machines and restrict access to the agents bound to each runner.
A list of domains that sandboxed scripts are permitted to access.
## Optional SRT sandbox
- Default whitelisted domains include standard package registries (like npm or python package hosts) and repository hosts (like `github.com`).
- If a script needs to call an external API (e.g. `api.slack.com`), the administrator must add it to the allowed list.
Without `--srt`, commands have the runner operating-system user's permissions. Connect only to a trusted Shumai server; use a dedicated container, VM, or account when appropriate.
### Pending Domains
[Anthropic Sandbox Runtime](https://github.com/anthropics/sandbox-runtime) is bundled as a library in Shumai CLI. Install its platform prerequisites on the runner machine (Linux: bubblewrap, socat, and ripgrep; macOS: ripgrep), then start with its JSON settings:
When an agent script attempts to reach a domain that is not currently authorized:
```bash
shumai-cli runner start --cwd /path/to/workspace --srt sandbox.json
```
1. The network connection is blocked immediately.
2. The target domain is logged and added to the **Pending Domains** list.
3. Admins can review this list and click **Approve** to authorize the domain, or **Reject** to keep it blocked.
Windows uses SRT's alpha Windows support. Run the one-time setup before starting a sandboxed runner; it requests administrator permission:
![Agent Sandbox Settings](../sandbox.webp)
```powershell
npx @anthropic-ai/sandbox-runtime windows-install
```
SRT verifies the setup at startup and reports an error if it is missing. A runner without `--srt` does not need this setup.
The JSON uses upstream SRT settings directly. For example:
```json
{
"filesystem": {
"denyRead": ["~/.ssh", "~/.aws", ".env", ".env.*"],
"allowWrite": [".pi"],
"denyWrite": []
},
"network": {
"allowedDomains": [],
"deniedDomains": []
}
}
```
This example allows writes only in `.pi`, denies reads of the listed credential locations, and blocks command network access. Review read permissions and network rules for your environment using SRT's documentation. Relative filesystem paths use the runner workspace. Settings are snapshotted at startup; restart after changing them. Missing or invalid settings, missing SRT prerequisites, and sandbox initialization failures stop startup. Commands never fall back to unrestricted execution.
SRT wraps shell commands and their child processes. One shared SRT runtime handles concurrent commands and is reset when the runner stops. The runner's WebSocket and server-directed file transfers operate outside SRT. **The Shumai server address is not automatically added to allowed domains.** If a script itself needs network access, explicitly allow its destination in the JSON.
Shumai has no server-side sandbox or domain settings. SRT is initialized only on runners that opt into it. SRT in Docker may require namespace permissions on that dedicated runner container; these permissions are not needed by the Shumai server.
## Runner in Docker
An ordinary runner can run in its own container without extra capabilities or an exposed port:
```bash
docker run --rm --init --name shumai-runner \
--cap-drop ALL --security-opt no-new-privileges \
-e SHUMAI_API_SERVER -e SHUMAI_RUNNER_KEY \
-v shumai-runner-workspace:/workspace -w /workspace \
node:22-bookworm sh -c \
'npm install -g @shumai-one/shumai-cli && exec shumai-cli runner start'
```
For development, HTTP is accepted for `localhost`, `127.0.0.1`, `[::1]`, and Docker's `host.docker.internal`. Remote servers require HTTPS. Avoid mounting sensitive host directories or the Docker socket into the runner workspace.
## Limits and lifecycle
Commands default to 120 seconds and accept a maximum timeout of one hour. Timeout and cancellation attempt to terminate the command and its process tree. Each command saves up to 64 MiB of output in `.pi/logs`; manage retained logs as part of workspace maintenance. Transfers and extracted archives are limited to 256 MiB. Protocol file operations reject paths outside `.pi`, existing symlinks, and unsafe archive entries. V1 assumes commands do not deliberately change workspace paths while transfers are running.
Temporary reconnects reconcile active and recently completed commands without deliberately executing them again. Restarting the runner process does not resume commands from the previous process.
Up to eight commands and file transfers can run concurrently in the shared workspace. Additional requests return a busy error. On Windows without SRT, background processes may survive after the command's shell exits; remaining output pipes are closed after one second. Use foreground commands for predictable timeout and cancellation. SRT manages the sandboxed Windows process tree.
+1 -1
View File
@@ -35,7 +35,7 @@ The official Shumai Premiere Pro UXP plugin provides a native panel inside Adobe
> [!NOTE]
> **Experimental Feature:**
> The Premiere Pro UXP plugin is currently experimental. While functional, it has not yet been tested across all Premiere Pro minor versions and operating system configurations. If you encounter any bugs, unexpected behavior, or have workflow suggestions, please [open an issue on GitHub](https://github.com/shumaiOne/shumai/issues) or join our [Discord community](https://discord.gg/sUzhujK6DD).
> The Premiere Pro UXP plugin is currently experimental. While functional, it has not yet been tested across all Premiere Pro minor versions and operating system configurations. If you encounter any bugs, unexpected behavior, or have workflow suggestions, please [open an issue on GitHub](https://github.com/shumaiOne/shumai/issues) or join our [Discourse forum](https://shumai.discourse.group/).
### Minimum Version Requirements
+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)不受影响,依然可用。
+100
View File
@@ -0,0 +1,100 @@
---
title: 分布式 Worker 部署
description: 将媒体转码部署到独立 Worker,智能体随主服务器运行。
---
智能体、嵌入和归档队列随 Shumai 主服务器一起启动。媒体转码仍可通过 PostgreSQL 和 DBOS 队列交给独立 Worker。
## 主服务器
设置 `SHUMAI_WORKERS=none`(或 `--workers=none`)时,主服务器处理智能体和归档任务,转码交给独立 Worker。`all` 和 `transcode` 会同时在主服务器运行转码队列。旧的 `agent`、`ai`、`archive` 参数仍可使用,均启动智能体和归档队列。
主服务器需安装智能体沙箱依赖(Linux 使用 `bubblewrap`,macOS 使用 `sandbox-exec`)。不再支持独立启动智能体 Worker。
## 独立转码 Worker
在 Worker 上配置与主服务器相同的 PostgreSQL 数据库和 S3 存储。多台机器不共享文件系统时,必须使用 S3 兼容存储。
```bash
npm install -g @shumai-one/shumai-transcode
shumai-transcode
```
也可以使用 Docker:
```bash
docker run -d --name shumai-transcode-worker --env-file .env shumaione/shumai-transcode:latest
```
Bun 用户可运行 `bun run --bun shumai-transcode`。
## 升级现有智能体会话
升级主服务器前,请等待旧智能体 Worker 完成任务并将其停止。正常数据库迁移会自动将已有会话上下文复制为独立记录,无需额外运行迁移脚本。过渡期间保留旧记录表。
每个会话使用独立的本地 SQLite 工作副本,缺失时自动从 PostgreSQL 恢复。可用 `AGENT_SESSION_CACHE_DIR` 指定缓存目录。主服务器在确认提交前将精简记录同步至 PostgreSQL。本地副本可重建,备份应包含 PostgreSQL。图片和技能内容在两种存储中继续使用动态占位符,在智能体需要时解析。
---
## Worker 并发与多实例部署
### 并发调优
Worker 根据可配置的并发上限从 PostgreSQL 队列中拉取任务:
- `CONCURRENCY_TRANSCODE`:单个 Worker 最大并发视频转码任务数(默认 `1`)。
- `CONCURRENCY_AGENT`:单个主服务器最大并发智能体及向量嵌入工作流数(默认 `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 中,主服务器应使用单副本和 Recreate 部署策略。转码 Worker 仍可独立扩展。
---
## 基于 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 的云存储,以确保所有工作节点均能正常访问上传的文件。_
+238
View File
@@ -0,0 +1,238 @@
---
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)。
---
## 安装命令行客户端
若要连接到已运行的 Shumai 服务器,可直接安装独立 CLI,无需安装 Node.js 或 Bun:
```sh
curl -fsSL https://github.com/shumaiOne/shumai/releases/latest/download/install.sh | sh
```
Windows 用户可使用 PowerShell:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://github.com/shumaiOne/shumai/releases/latest/download/install.ps1 | iex"
```
独立版本支持 ARM64 和 x64 架构的 macOS、使用 glibc 的 Linux,以及 Windows。安装脚本会校验 SHA-256 校验和,并将 CLI 安装到当前用户的目录中。重新运行安装脚本即可升级,使用 `shumai-cli --version` 可查看已安装的版本。也可通过 `npm install -g @shumai-one/shumai-cli` 安装,此方式需要 Node.js 22.12 或更高版本。
将 `SHUMAI_API_SERVER` 设置为服务器地址,将 `SHUMAI_API_KEY` 设置为在“设置 → API 令牌”中创建的个人 API 令牌,然后运行 `shumai-cli project ls`。有关支持的系统版本、PATH 配置、指定版本安装、回滚及卸载的详细说明,请参阅 [CLI 指南](https://github.com/shumaiOne/shumai/blob/main/apps/cli/README.md)。
+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)
+99
View File
@@ -0,0 +1,99 @@
---
title: 智能体运行器
description: 连接可选的命令运行器,并在运行器机器上配置沙箱。
---
智能体无需运行器即可使用内置工具。如需执行命令或将素材下载到命令工作区,请在自己管理的机器上连接**运行器**。运行器主动通过经过身份验证的 WebSocket 连接 Shumai,无需开放入站端口。
每个数据库只支持一台主 Shumai 服务器使用智能体运行器。未配置运行器时,多台主服务器可以共享数据库。创建运行器前,请停止其他主服务器副本。转码 Worker 可以独立运行。
## 连接运行器
1. 在 **设置 → 智能体运行器** 中创建运行器,复制仅显示一次的密钥。只有团队所有者可以管理运行器和轮换密钥。
2. 在 macOS、Linux 或 Windows 机器上安装 [Shumai CLI](https://github.com/shumaiOne/shumai/tree/main/apps/cli#installation)。
3. 在已有的专用工作目录中启动:
```bash
export SHUMAI_API_SERVER="https://shumai.example.com"
export SHUMAI_RUNNER_KEY="your-runner-key"
shumai-cli runner start --cwd /path/to/workspace
```
Windows 用户可在 PowerShell 中设置变量:
```powershell
$env:SHUMAI_API_SERVER = "https://shumai.example.com"
$env:SHUMAI_RUNNER_KEY = "your-runner-key"
shumai-cli runner start --cwd C:\workspace
```
使用运行器密钥,而非个人 API 令牌。建议通过环境变量传入,避免 `--key` 将密钥留在命令历史中。运行器在前台执行,Ctrl+C 会停止运行器及其活动命令。临时断线后自动重连;密钥撤销或连接被替换时退出。
第一个运行器是团队默认运行器,也可在智能体设置中指定专用运行器。未配置运行器时隐藏 `bash` 和 `download_asset`。配置后,具有智能体使用权限的编辑者和审阅者可立即使用 Bash,无需先读取技能;禁用工具设置仍然生效。运行器离线时执行命令会返回错误。
命令从工作目录启动,技能、下载素材、生成文件和日志位于 `.pi` 中。子进程只继承基础系统环境及明确配置的技能变量,不自动继承运行器密钥、个人 API 令牌或其他任意环境变量。
所有有权在同一运行器执行命令的用户都可以读取工作区中保留的文件,包括其他项目的素材和日志。Shumai 下载素材时会检查项目权限。请仅在有权读取工作区内所有文件的用户之间共享运行器。不同信任范围应使用独立的运行器账号或虚拟机,并限制对应智能体的访问权限。
## 可选 SRT 沙箱
未使用 `--srt` 时,命令具有运行器系统用户的权限。只连接可信 Shumai 服务器,可按需使用独立容器、虚拟机或账号。
[Anthropic Sandbox Runtime](https://github.com/anthropics/sandbox-runtime) 已作为库内置于 Shumai CLI。安装平台依赖(Linux:bubblewrap、socat 和 ripgrep;macOS:ripgrep)后传入 JSON 配置:
```bash
shumai-cli runner start --cwd /path/to/workspace --srt sandbox.json
```
Windows 使用 SRT 的实验性 Windows 支持。启用沙箱前执行一次初始化;此命令会请求管理员权限:
```powershell
npx @anthropic-ai/sandbox-runtime windows-install
```
SRT 会在启动时检查安装状态,缺少初始化时返回错误。未使用 `--srt` 的运行器不需要此步骤。`bash` 工具在 macOS 和 Linux 上使用 `/bin/sh`。在 Windows 上,运行器先在标准安装目录查找 Git Bash,再在 PATH 中查找 `bash.exe`,找不到时使用 `cmd.exe`。运行器在启动时显示所选 Shell,并将其报告给智能体,让智能体使用匹配的命令语法。在 Windows 上搭配 SRT 使用 Bash 时,请用 Git Bash 代替旧版 WSL Bash 启动器。
直接使用上游 SRT JSON 格式,例如:
```json
{
"filesystem": {
"denyRead": ["~/.ssh", "~/.aws", ".env", ".env.*"],
"allowWrite": [".pi"],
"denyWrite": []
},
"network": {
"allowedDomains": [],
"deniedDomains": []
}
}
```
此例只允许写入 `.pi`,禁止读取所列凭证位置,并禁止命令访问网络。请参考 SRT 文档审查适合自己环境的读取权限和域名规则。相对路径以运行器工作目录为基准。配置在启动时读取并保存快照,修改后需要重启。配置缺失或无效、SRT 依赖缺失、沙箱初始化失败都会阻止启动,不会回退到无沙箱执行。
SRT 只包裹 Shell 命令及其子进程。并发命令共享同一个 SRT 运行时,运行器停止时统一清理。运行器 WebSocket 和服务器发起的文件传输在 SRT 外运行。**不会自动将 Shumai 服务器地址添加到允许域名中。** 如果脚本自身需要网络,请在 JSON 中明确允许目标域名。
Shumai 服务器不管理沙箱和域名规则。只有启用沙箱的运行器才初始化 SRT。在 Docker 中使用 SRT 可能需要为专用运行器容器增加命名空间权限,Shumai 服务器不需要这些权限。
## Docker 运行器
普通运行器可在独立容器中执行,无需额外权限或暴露端口:
```bash
docker run --rm --init --name shumai-runner \
--cap-drop ALL --security-opt no-new-privileges \
-e SHUMAI_API_SERVER -e SHUMAI_RUNNER_KEY \
-v shumai-runner-workspace:/workspace -w /workspace \
node:22-bookworm sh -c \
'npm install -g @shumai-one/shumai-cli && exec shumai-cli runner start'
```
本地开发允许 `localhost`、`127.0.0.1`、`[::1]`、Docker 的 `host.docker.internal` HTTP 地址;远程连接必须使用 HTTPS。不要将敏感宿主机目录或 Docker socket 挂载到运行器工作区。
## 限制与生命周期
默认超时 120 秒,最长一小时。超时或取消会尝试终止命令及其子进程。单条命令最多在 `.pi/logs` 保存 64 MiB 输出,请按工作区维护需求清理日志。文件传输和技能解压限制为 256 MiB。协议文件操作拒绝 `.pi` 外路径、已有符号链接及不安全的压缩包条目。V1 假定命令不会在文件传输期间故意修改工作区路径。
临时重连会同步执行中及近期完成的命令,避免主动重复执行。重启运行器进程不会恢复旧进程中的命令。
共享工作区最多同时执行八个命令或文件传输,超出时返回繁忙错误。Windows 未启用 SRT 时,后台进程可能在命令 Shell 退出后继续运行,剩余输出管道会在一秒后关闭。请使用前台命令,以确保超时和取消可预测。启用 SRT 时由 SRT 管理 Windows 沙箱进程树。
+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)
+51
View File
@@ -0,0 +1,51 @@
---
title: 评论与标注
description: 借助画布涂鸦与时间戳评论协同审阅媒体资产。
---
Shumai 专为音视频及图像反馈打造了沉浸式审阅工作区。除了常规文字评论外,团队成员还可以添加精确到时间戳的反馈,并直接在画面上绘制标注涂鸦。
---
## 时间戳评论
审阅音视频文件时,可以将评论锚定在时间轴上的精确秒数或关键帧:
1. 播放或拖动进度条定位到需要审阅的精准画面帧或时间点。
2. 在评论输入框中输入反馈意见。
3. 点击 **发送**(Submit)。评论将连同时间标记一同保存,并在视频时间轴上生成标记锚点。
4. 协作者点击侧边栏中的评论卡片,播放器即可直接跳转至对应的时间点。
![时间戳评论](/timestamp-comment.webp)
---
## 画面标注(画布涂鸦)
为了提供清晰直观的视觉反馈,可以直接在图片或视频画面帧上绘制标注:
1. 将视频暂停在需要标注的画面帧。
2. 在播放器上方的标注工具栏中选择绘图工具(画笔、矩形、圆形、箭头等)。
3. 直接在画面屏幕上绘制标注。
4. 输入评论并点击 **发送**(Submit)。绘制的标注涂鸦将与该条评论绑定保存。
5. 当其他成员选择该条评论时,播放器将在对应帧画面上自动叠加显示绘制的标注。
![画面标注](/draw_annotation.webp)
---
## 评论会话(回复)
通过直接回复反馈保持讨论条理清晰:
- 点击任意评论下方的 **回复**(Reply)。
- 回复内容将按层级嵌套在主评论卡片下,方便跟踪问题讨论与解决进展。
---
## 附件
可以在评论中附加参考文档、设计规范或其他资产:
- 点击评论输入框内的 **回形针**(Paperclip)图标。
- 选择要上传的文件。上传后将作为可直接下载的链接显示在评论卡片中。
@@ -0,0 +1,127 @@
---
title: 邮件通知
description: 配置团队 SMTP 设置,发送聚合活动摘要邮件,并执行测试邮件发送。
---
Shumai 内置邮件通知系统,可将团队动态(如评论、@提及、新资产上传、状态变更以及看板任务更新)直接推送到团队成员的邮箱中。
为避免收件箱泛滥及通知疲劳,Shumai 不会针对单次操作即时发送零散邮件。后台投递服务会自动聚合待发送的通知,并定期发送包含内联缩略图与深度链接的批量摘要邮件。
---
## 配置 SMTP 设置
邮件通知由**团队所有者**在团队层级统一管理。
发送邮件配置步骤:
1. 点击侧边栏的 **团队设置**。
2. 选择 **邮件通知** 标签页。
3. 开启 **启用邮件通知** 开关。
4. 填写 SMTP 服务器凭据与发件人信息。
5. 点击 **保存** 或 **保存并发送测试邮件**。
### SMTP 服务器设置
| 字段 | 说明 | 示例 / 默认值 |
| :---------------------------- | :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
| **SMTP Host** | 发送邮件的 SMTP 服务器主机名或 IP 地址。 | `smtp.example.com` 或 `smtp.sendgrid.net` |
| **SMTP Port** | 连接 SMTP 服务器的端口。 | `587`(默认,STARTTLS)、`465`(SSL/TLS)或 `25` |
| **Username** | SMTP 服务器身份验证所需的用户名或 API Key。 | `user@example.com` 或 `apikey` |
| **Password** | 身份验证密码或 API Secret。 | `••••••••` |
| **SSL / TLS (SMTPS)** | 直接使用 SSL/TLS 加密连接。通常在使用端口 `465` 时需要开启。 | `Disabled`(默认禁用) |
| **Ignore Certificate Errors** | 允许使用自签名证书、无效或未验证的 TLS 证书建立连接。适用于本地测试(如 Mailpit、MailHog)或企业内部中继服务器。 | `Disabled`(默认禁用) |
> [!TIP]
> **密码保留**:修改现有邮件配置时,若无需更改密码,可将密码输入框留空以保留当前存储的密码。出于安全考虑,系统绝不会向客户端明文返回已保存的密码。
### 发件人信息
| 字段 | 说明 | 示例 / 默认值 |
| :----------- | :------------------------------------------------------------------------------------------- | :----------------------------- |
| **From** | 显示在邮件 `From` 标头中的发件人姓名与邮箱地址。请确保 SMTP 服务商已授权代表此地址发送邮件。 | `Shumai <noreply@example.com>` |
| **Reply-To** | _(可选)_ 成员直接回复通知邮件时接收回复的邮箱地址。 | `support@example.com` |
---
## 测试 SMTP 投递
在正式启用邮件投递前,可直接在设置页面验证配置与凭据:
1. 点击 **保存并发送测试邮件**。
2. 在 **发送测试邮件** 弹窗中,核对或调整发件人 `From` 地址。
3. 点击 **发送测试邮件**。
Shumai 将向 SMTP 服务器发起主动握手验证(`transport.verify()`),并向当前登录的管理员邮箱发送一封样式精美的测试邮件。
若握手或投递失败(例如密码错误、出站端口受阻或发件人地址被拒),界面将弹出 Toast 提示并显示 SMTP 服务器返回的具体错误信息。
---
## 投递架构与摘要批量聚合
Shumai 采用异步批量架构投递邮件通知:
```
[ 团队活动 ]
(评论、上传、@提及、看板)
│
▼
[ 数据库队列 ] (状态: pending)
│
▼ (每 3 分钟)
[ 通知后台任务 ]
│
├─ 筛选接收者(检查用户偏好与项目范围)
├─ 排除本人操作与 AI 智能体
├─ 分组与折叠条目(超过 3 项自动聚合汇总)
├─ 拉取头像与缩略图作为内联 CID 附件
│
▼
[ Nodemailer 传输层 ] ──> SMTP 服务器 ──> [ 成员收件箱 ]
```
### 1. 定期后台投递
通知在 PostgreSQL 中以 `pending` 状态入队。后台任务每 **3 分钟** 定期运行一次,通过原子队列锁(`FOR UPDATE SKIP LOCKED`)获取待处理通知。即便多实例并发运行,也能确保安全投递且不产生重复邮件。
### 2. 摘要汇总打包
系统不会在每次操作发生时立即发送邮件,而是在 3 分钟窗口期内收集属于同一接收者的所有通知,并将其合并为单封摘要邮件。这既能保持团队协作沟通条理清晰,又避免了高频协作时的收件箱骚扰。
### 3. 智能活动折叠
当某个事件集包含大量条目时(例如剪辑师一次性上传数十个视频片段),Shumai 会自动对其分组并折叠:
- 若分组中包含 **3 项或更少** 条目,则逐项展示各自的缩略图与详细信息。
- 若一次性上传 **超过 3 项**,Shumai 会将其汇总为单条简明通知(例如:_“Alice 向项目 Project Alpha 上传了 12 个新文件”_),并附带前三个文件名的预览。
### 4. 内联 CID 附件
系统从存储中提取头像及视频/图片资产缩略图,以 MIME 内联附件(`cid:...`)的形式直接嵌入邮件中。
与外部图片链接相比,内联 CID 附件具备以下优势:
- 在桌面端及移动端邮件客户端(如 Apple Mail、Gmail、Outlook)中可直接显示,不受“显示远程内容”安全警告的阻拦。
- 无需依赖公开可访问的 S3 URL 或反向代理鉴权即可正常渲染。
### 5. 深度链接
邮件中的每个通知卡片均包含深度链接操作按钮(如 **查看资产**、**查看项目** 或 **查看任务**),成员点击后可直达 Shumai 中的对应资源。
为确保链接跳转至公网域名而非 `localhost`,请在 Shumai 服务器上配置 `APP_URL` 或 `BETTER_AUTH_URL` 环境变量:
```bash
APP_URL=https://shumai.example.com
```
---
## 成员偏好与过滤机制
邮件投递严格遵循团队权限设定与成员自主偏好:
- **个人偏好**:团队成员可通过 **团队设置 > 通知** 自主选择接收的活动类型。若用户关闭了某分类(如普通评论或状态更新)的通知,Shumai 不会将该类条目纳入其邮件摘要中。
- **自身操作过滤**:成员绝不会收到关于自己发布的评论、上传或任务更新的通知邮件(除非显式开启 **您的上传** 偏好,以便在自身媒体转码完成时获取提醒)。
- **项目范围限制**:权限受限于特定项目的成员,仅会收到其所属项目内的活动邮件摘要,除非他们被显式 `@提及`。
- **AI 智能体过滤**:系统自动将 AI 智能体账户排除在邮件通知接收人之外。
+131
View File
@@ -0,0 +1,131 @@
---
title: 向量模型服务部署 (EmbeddingGemma 2)
description: 使用 shumaiOne/embedding-server 本地离线运行多模态向量嵌入,赋能语义搜索。
---
Shumai 支持通过 [shumaiOne/embedding-server](https://github.com/shumaiOne/embedding-server) 在本地私有化部署多模态向量模型服务以赋能语义搜索。该独立 Docker 服务由 Google AI Edge 的 **LiteRT-LM** 与 **EmbeddingGemma 2 740M** 强力驱动。
该向量模型服务为文本、图片与视频关键帧提供了统一的 768 维向量空间,并对外暴露兼容 OpenAI 标准的 HTTP API 接口(`/v1/embeddings`)。由于模型权重已预先打包至 Docker 镜像内,该服务完全支持离线和物理隔离(Air-gapped)环境运行,无需访问外网或依赖第三方云厂商 API 密钥。
---
## 模型架构与规格参数
| 属性 | 参数 |
| :------------- | :------------------------------------------------------- |
| **模型** | `EmbeddingGemma 2 740M` (`google/embeddinggemma-2-740m`) |
| **运行环境** | Google AI Edge LiteRT-LM (Python 3.14 Debian slim) |
| **向量维度** | 768 维(多模态:文本、图片及视频) |
| **上下文窗口** | 2,048 tokens |
| **网络模式** | 完全支持离线运行(`--network none`) |
| **API 规范** | 兼容 OpenAI 标准的 `/v1/embeddings` |
---
## 视频处理与抽帧采样
针对视频资产,Shumai 会将其切片为标准化分段并提取关键帧:
- **切片分段(Chunking)**:视频按 **60 秒为一个片段**进行切片,并在相邻片段边界保留 **5 秒重叠区间**,以维持剧情与视觉上下文连贯性。
- **抽帧频率**:Shumai 从每个分段中抽取 **15 帧/分钟**。
- **自适应帧数边界(Adaptive Frame Bounding)**:
- 针对标准宽高比视频(1:1、4:3、3:4、16:9、9:16、21:9),Shumai 抽取 15 帧,生成约 1,982 个 Prompt token,安全处于 2,048 token 上下文窗口限制内。
- 针对非标准或特殊比例视频(如 5:3、1.4:1),Shumai 自动采样 14 帧(约 1,990 token),从数学原理上杜绝 Prompt 长度超过 2,048 token 的可能,防止向量模型服务发生内存溢出(OOM)。
---
## 重要说明:更换 Embedding 服务商将导致已有向量失效
> [!WARNING]
> **不同 Embedding 模型的向量空间完全互不兼容。**
>
> 若更换向量服务提供商(例如从 Google Gemini 的 1536 维向量切换到 EmbeddingGemma 的 768 维向量,反之亦然),**数据库中现存的所有向量嵌入数据将全部失效**。
>
> 为保护生产数据库免受误操作损坏及搜索失效,**Shumai 刻意未在 Web 界面中提供切换 Embedding 提供商的开关**。该配置仅能由管理员通过环境变量(`EMBEDDING_PROVIDER` 和 `GEMMA_EMBEDDING_OPENAI_BASE_URL`)进行配置。
---
## 通过 CLI 重新生成向量数据
当更换 Embedding 提供商,或在已有 Shumai 生产环境中首次启用向量模型服务时,可通过管理员 CLI 命令为所有现有媒体资产重新生成向量数据:
### Docker 容器内部执行
```bash
docker exec -it <shumai-container-name> shumai regenerate-embeddings
```
### 本地 / 裸机环境执行
```bash
shumai regenerate-embeddings
```
_(或执行 `bun apps/web/src/index.ts regenerate-embeddings`)_
### 命令执行流程说明
1. **扫描团队**:遍历工作区中的所有团队。若某团队未启用(开启)向量嵌入智能体,则记录警告日志并安全跳过该团队。
2. **清除旧向量**:清空所有符合条件的资产原有的向量数据,并取消处理中或排队中的向量任务,确保平滑过渡至新模型。
3. **加入新任务队列**:为各活跃团队下所有符合条件的资产(图片、视频及带有渲染预览的 3D 资产)派发全新的后台 `ai_embedding` 任务。
4. **后台异步处理**:后台 Worker 按照配置的并发上限逐步处理排队任务。
---
## 部署与配置
### Docker 快速上手
运行独立的向量模型服务容器:
```bash
docker run -d \
--name shumai_embedding \
-p 9379:9379 \
shumaione/embedding-server:latest
```
### Docker Compose 配置
在 Docker Compose 环境中,将 `embedding-server` 添加到 `docker-compose.yaml` 中,并配置 Shumai 通过 Docker 内部网络进行连接:
```yaml
services:
embedding-server:
image: shumaione/embedding-server:latest
container_name: shumai_embedding
restart: unless-stopped
shumai:
image: shumaione/shumai:latest
environment:
# 向量模型服务配置
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]
> 由于 Shumai 与 `embedding-server` 在 Docker 内部网络中通信,`embedding-server` 无需向宿主机映射暴露端口。
### 环境变量
| 变量 | 必填 | 说明 | 默认值 |
| :-------------------------------- | :------- | :------------------------------------------------------------------------------------------------ | :------------------------- |
| `EMBEDDING_PROVIDER` | 是 | 设置为 `gemma-embedding-2-openai` 以使用本地 LiteRT-LM 服务。 | `gemini-embedding-2` |
| `GEMMA_EMBEDDING_OPENAI_BASE_URL` | 是 | 向量模型服务的 HTTP 基础地址(例如 `http://embedding-server:9379/v1`)。 | `http://localhost:9379/v1` |
| `ENABLE_EMBEDDING_AGENT` | 否 | 启动时自动为所有团队初始化并启用系统级向量嵌入智能体。 | `false` |
| `CONCURRENCY_AGENT` | 推荐配置 | Worker 执行 AI 任务的最大并发数。运行 `embedding-server` 时**务必设为 `1`**,以防止内存开销过大。 | `5` |
---
## 硬件与资源要求
- **内存(RAM)**:
- 建议为 `embedding-server` 容器分配至少 **4 GB+ 的独立物理内存**。
- 运行 Lite+Embedding Compose 组合时,宿主机系统总内存建议在 **4 GB+** 以上;运行全量服务时建议在 **8 GB+** 以上。
- **并发控制**:
- 使用 `embedding-server` 时,务必在 Shumai 配置中设置 `CONCURRENCY_AGENT=1`。并行处理多模态向量嵌入会消耗大量内存,在配置较低的机器上可能会触发系统 OOM Killer 强行终止 Docker 容器。
+108
View File
@@ -0,0 +1,108 @@
---
title: 基于 Gotenberg 的文档 PDF 转换
description: 将 Office 文档、HTML、Markdown、CSV 和 TXT 文件转换为高保真 PDF 代理文件,实现浏览器内顺畅预览。
---
浏览器无法原生直接渲染 Office 文档、HTML 页面、Markdown 文件、表格以及纯文本文件。Shumai 采用基于 Docker 的开源转换服务 [Gotenberg](https://gotenberg.dev),将这些文件转为高保真 PDF 代理资产,以便在浏览器中无缝预览。
Gotenberg 采用以下组件完成文档转换:
- **LibreOffice**:负责处理 Office 文档、电子表格与纯文本。
- **无头 Chromium(Headless Chromium)**:负责渲染 HTML 与 Markdown 文件。
---
## 支持的文件类型
配置 Gotenberg 后,Shumai 会自动为以下格式的文件生成 PDF 预览代理:
| 类别 | 扩展名 | 转换引擎 |
| :------------------ | :--------------------- | :---------- |
| Word 文档 | `.doc`, `.docx` | LibreOffice |
| Excel 表格 | `.xls`, `.xlsx` | LibreOffice |
| PowerPoint 幻灯片 | `.ppt`, `.pptx` | LibreOffice |
| OpenDocument | `.odt`, `.ods`, `.odp` | LibreOffice |
| 富文本(Rich Text) | `.rtf` | LibreOffice |
| HTML | `.html`, `.htm` | Chromium |
| Markdown | `.md`, `.markdown` | Chromium |
| 电子表格 / CSV | `.csv` | LibreOffice |
| 纯文本 | `.txt` | LibreOffice |
---
## 配置说明
Shumai 支持通过 **Web 界面**或**环境变量**配置 Gotenberg。
### 1. Web 界面配置(团队设置 → 集成)
团队所有者可直接在 Web 界面中配置 Gotenberg:
1. 在侧边栏导航至**团队设置**。
2. 切换至**集成**选项卡。
3. 在 **Gotenberg 文档转换器**下,输入**服务器地址(Server URL)**(例如 `http://gotenberg:3000` 或 `http://localhost:3000`)。
4. 若服务启用了 Basic 基础认证,请输入**用户名**与**密码**。
5. 点击**测试连接**,验证与 Gotenberg 的通信状态并确认服务健康状况。
6. 点击**保存更改**。
### 2. 环境变量配置
也可以在运行 Shumai 或转码 Worker 的机器上通过环境变量进行全局配置:
| 变量 | 必填 | 说明 |
| :------------------------------ | :--------------- | :----------------------------------------------------- |
| `GOTENBERG_URL` | 是(启用时必填) | Gotenberg 基础服务地址,例如 `http://gotenberg:3000`。 |
| `GOTENBERG_BASIC_AUTH_USERNAME` | 否 | Gotenberg 开启 Basic 基础认证时的用户名。 |
| `GOTENBERG_BASIC_AUTH_PASSWORD` | 否 | Gotenberg 开启 Basic 基础认证时的密码。 |
### 配置优先级与只读模式
> [!IMPORTANT]
> **环境变量优先级最高。** 一旦在运行环境中配置了 `GOTENBERG_URL`,Shumai 将始终优先采用环境变量中的配置。
>
> 通过环境变量配置后,**团队设置 → 集成**中的对应设置项将显示**已通过环境变量配置(只读)**徽标,且输入框将被锁定,防止误操作或配置不一致。
---
## 部署 Gotenberg
### Docker 快速上手
只需一条命令即可启动 Gotenberg 容器:
```bash
docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8
```
若需开启 Basic 基础认证:
```bash
docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8 gotenberg --gotenberg-basic-auth-username=admin --gotenberg-basic-auth-password=secret
```
### Docker Compose 配置
在 `docker-compose.yaml` 中添加 Gotenberg 服务:
```yaml
gotenberg:
image: gotenberg/gotenberg:8
restart: unless-stopped
ports:
- '3000:3000'
```
随后在 Shumai 中配置指向该服务:
```bash
GOTENBERG_URL=http://localhost:3000
```
---
## 未配置 Gotenberg 时的降级表现
若未配置 Gotenberg 或服务无法连通,Shumai 会优雅降级:
- **Office 文档与 HTML**:文件上传正常完成并标记为 `processed`,但不生成 PDF 代理文件。
- **CSV、Markdown 与 TXT**:改由内置的轻量 PDF 生成器生成预览代理(排版保真度略低)。
@@ -0,0 +1,140 @@
---
title: 图像与视频生成
description: 为内置 AI 智能体工具配置图像与视频生成服务商及模型。
---
Shumai 智能体可通过内置工具——**生成图像**(`generate_image`)与**生成视频**(`generate_video`),在工作区中直接生成创意视觉资产。
生成视觉媒体资产需要专用的多模态基座模型支持。智能体调用这些能力前,团队所有者必须先在团队设置中配置上游服务商并启用对应模型。
> 🔒 **权限说明:** 仅**团队所有者(Team Owner)**拥有查看与配置媒体生成设置的权限。请点击头像进入**设置**,在左侧导航栏选择**图像/视频生成**(或直接访问 `teams/<teamId>/settings#image-video`)。
---
## 为何需要此项配置
在 **AI 服务商**中配置的对话类模型主要负责文本推理与对话交互;而图像与视频生成则依赖专用的多模态生成模型(如 DALL-E、FLUX、Gemini Image、Veo、可灵 Kling AI、Luma Ray、万象 Wan 等)。
**图像/视频生成**配置页面支持团队所有者:
1. 接入并认证一个或多个受支持的图像与视频生成服务商。
2. 选择为团队启用精选推荐模型,或注册自定义模型 ID。
3. 设定智能体生成视觉资产时的默认模型。
---
## 工具可用性与激活规则
<Warning>
**重要提示:** 仅在智能体配置弹窗中勾选 `generate_image` 或 `generate_video`
还**远远不够**。只有同时满足以下三项条件,智能体才能真正调用该工具:
</Warning>
1. **服务商已配置:** 对应服务商已配置有效 API 密钥(通过服务端环境变量注入,或在团队设置中配置了自定义团队密钥)。
2. **至少启用了一个模型:** 在已激活的服务商下,对应模态(`image` 或 `video`)**至少启用了一个模型**。
3. **已向智能体开放工具权限:** 在**团队设置** > **智能体** > **工具**权限列表中,该工具未被禁用。
### 未配置模型时的系统行为
若已配置的服务商下未启用任何图像模型,`generate_image` 工具将从智能体的运行时环境中**彻底移除**。同理,若未启用任何视频模型,`generate_video` 工具亦会被移除。
在此状态下:
- 智能体**无法调用**该生成工具。
- 该工具不会出现在智能体的工具目录或 Prompt 提示词定义中。
- 即便团队所有者在智能体设置弹窗中开启了**生成图像**或**生成视频**开关,只要未启用模型,智能体仍旧无法使用该工具。
---
## 支持的服务商
Shumai 内置支持 18 家媒体生成服务商:
| 服务商 | 支持模态 | 默认环境变量 |
| :-------------------- | :--------- | :--------------------- |
| **OpenAI** | 图像 | `OPENAI_API_KEY` |
| **Google** | 图像, 视频 | `GEMINI_API_KEY` |
| **Google Vertex AI** | 图像, 视频 | `GOOGLE_CLOUD_API_KEY` |
| **xAI** | 图像, 视频 | `XAI_API_KEY` |
| **Fal** | 图像, 视频 | `FAL_KEY` |
| **Replicate** | 图像, 视频 | `REPLICATE_API_TOKEN` |
| **Black Forest Labs** | 图像, 视频 | `BFL_API_KEY` |
| **Kling AI** | 视频 | `KLINGAI_API_KEY` |
| **Together AI** | 图像 | `TOGETHER_API_KEY` |
| **Fireworks AI** | 图像 | `FIREWORKS_API_KEY` |
| **DeepInfra** | 图像 | `DEEPINFRA_API_KEY` |
| **Luma** | 图像 | `LUMA_API_KEY` |
| **Amazon Bedrock** | 图像 | `AWS_ACCESS_KEY_ID` |
| **Alibaba** | 视频 | `ALIBABA_API_KEY` |
| **ByteDance** | 图像, 视频 | `ARK_API_KEY` |
| **MiniMax** | 视频 | `MINIMAX_API_KEY` |
| **Prodia** | 图像, 视频 | `PRODIA_TOKEN` |
| **Azure OpenAI** | 图像 | `AZURE_API_KEY` |
---
## 配置服务商与 API 密钥
在**媒体服务商**列表中点击任意服务商,即可打开其配置弹窗:
### 服务商状态说明
- **已配置 (自定义)**:在此弹窗中填入了团队专属的 API 密钥或自定义环境变量名。
- **已配置 (环境变量)**:系统检测到了服务端配置的默认环境变量(如 `OPENAI_API_KEY`)。除非需要覆盖该默认值,否则无需另行配置团队密钥。
- **未配置**:未检测到可用 API 密钥。使用此服务商前必须提供 API 密钥或环境变量名。
### 覆盖 API 密钥
在服务商弹窗的 **API Key** 标签页中:
- 输入 API 密钥明文(如 `sk-...`),或填入宿主机系统中已定义的环境变量名称。
- 点击**清除自定义密钥**,即可恢复使用服务端默认环境变量(若存在)。
---
## 管理模型
在服务商配置弹窗的 **Models** 标签页中:
### 精选模型
Shumai 预置了主流的精选推荐模型(如 `dall-e-3`、`fal-ai/flux/dev`、`veo-3.1-generate`、`kling-v3.0-t2v` 等)。切换模型旁边的开关,即可为团队启用或禁用该模型。
### 自定义模型
若服务商上线了新模型或支持微调模型,且未收录在精选列表中:
1. 选择模态(**图像**或**视频**)。
2. 输入上游服务商所要求的准确 **Model ID**。
3. 点击**添加**。
### 默认模型选择机制
每种类型(`image` 或 `video`)中**首个启用的模型**将自动成为默认模型。当智能体调用 `generate_image` 或 `generate_video` 且未显式指定 `model` 参数时,Shumai 会自动将生成请求路由至该默认模型。
---
## 智能体如何使用生成工具
启用之后,智能体便可在对话或自动化工作流中调用相关工具:
### 1. 生成图像 (`generate_image`)
- **提示词(Prompt):** 图像的详细文本描述。
- **模型选择:** 默认使用首个已启用的图像模型;智能体亦可按 `provider:modelId` 格式(如 `openai:dall-e-3` 或 `fal:fal-ai/flux/dev`)选用任意已启用模型。
- **参考图输入:** 智能体可通过 `read_asset` 工具获取工作区已有资产的 S3 存储键(`s3KeyOnly: true`),并将其作为画面风格或构图参考。
- **局部重绘(Inpainting):** 支持传入 S3 蒙版键,实现基于遮罩的局部精准重绘。
- **控制参数:** 支持自定义宽高比(`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`)、分辨率尺寸及随机种子(Seed)。
### 2. 生成视频 (`generate_video`)
- **生成模式:**
- `text_to_video`:根据动态文本提示词生成视频片段。
- `image_to_video`:将工作区已有静态图片转化为动态视频。
- `first_last_frame`:在首尾两帧资产之间生成流畅自然的过渡插帧。
- `reference_to_video`:基于参考图生成视频,保持角色形象或场景环境的一致性。
- **控制参数:** 支持设置宽高比(`16:9`、`9:16`、`1:1`、`adaptive`)、分辨率、时长、帧率(FPS)以及音效生成开关。
### 资产生成入库流程
所有生成的媒体文件起初均保存在本地沙箱目录(`.pi/`)中。随后,智能体可调用**创建文件**(`create_file`)将生成结果作为新资产上传至项目中,或调用**创建版本**(`create_version`)将其追加至已有资产的版本历史中。
+115
View File
@@ -0,0 +1,115 @@
---
title: MCP 服务端
description: 通过模型上下文协议(Model Context Protocol)将智能体连接至外部工具与 API。
---
模型上下文协议(Model Context Protocol,简称 MCP)是一套开放标准,支持 AI 模型安全对接外部工具、微服务与 API。在 Shumai 中,可通过标准 HTTP 传输协议(`Streamable HTTP` 或 `SSE`)注册远程 MCP 服务端,并将其分配给 AI 智能体。
---
## Shumai 中的 MCP 运作机制
为避免动辄数十个复杂的参数 Schema 挤占模型的上下文窗口,Shumai 采用了高能效的 MCP 连接架构:
- **自动发现与元数据缓存**:添加 MCP 服务端后,Shumai 会将其记录在团队配置中,并连接该端点以自动发现可用工具、服务端使用指引与描述元数据。在手动刷新服务端、完成 OAuth 鉴权或智能体首次调用其工具时,系统均会触发服务发现。这些 Schema 会缓存在数据库中,供后续秒级读取。
- **高上下文利用率的代理工具 (`mcp`)**:已分配的 MCP 服务端会通过注入对话智能体中的统一 `mcp` 代理工具实现多路复用。智能体可按需动态检查服务状态、检索工具、查看参数 Schema 并调用函数,无需预先消耗大量 LLM Token。
- **直连工具选项 (Direct Tools)**:对于高频调用的核心工具,可将其单独配置为**直连工具**,使其作为顶层 LLM 原生函数直接暴露给智能体,与 `mcp` 代理工具并行共存。
---
## 添加 MCP 服务端
在 Shumai 中注册新 MCP 服务端的步骤如下:
1. 前往**团队设置**并点击 **MCP** 标签页。
2. 点击**添加 MCP 服务端**。
3. 在弹窗中输入**服务端端点 URL**(例如 `https://mcp.example.com/sse` 或 `http://localhost:8080/mcp`)。
4. 点击**创建**。
> **注意:** 仅需提供**服务端端点 URL** 即可创建。Shumai 会根据 URL 自动生成占位服务名;当首次连接端点(通过编辑弹窗中的“刷新”按钮或智能体首次发起工具调用)时,系统会自动同步服务端的真实名称、运行状态、操作指引以及工具清单。
### 可选高级配置项
创建服务端后(初始弹窗仅需填入 URL),可打开编辑弹窗配置高级选项:
- **传输协议(Transport)**:在 `Streamable HTTP`(默认)与 `Server-Sent Events (SSE)` 之间选择。
- **认证策略(Auth Strategy)**:可选 `Auto-detect`(自动检测,默认)、`None`(无认证)、`Bearer Token` 或 `OAuth 2.0`。
- **最低权限角色(Minimum Permission Role)**:设置调用该服务端工具所需的最低团队角色要求(`Reviewer` 审阅者、`Editor` 编辑者或 `Owner` 所有者)。
- **直连工具(Direct Tools)**:指定需作为原生 LLM 工具直接呈现给智能体的工具名称列表。
---
## 理解工具配置机制
在服务端的编辑弹窗中,**工具(Tools)**列表展示了所有已发现的工具,每个工具均支持三态切换(同时提供**全部关闭** / **全部代理** / **全部直连**批量操作):
- **关闭(Off)**:彻底排除该工具,对智能体完全不可见——既无法通过代理工具列出、搜索或调用,也无法注册为直连工具。适用于隐藏干扰项或高危工具。
- **代理(Proxy,默认)**:工具通过统合的 `mcp` 代理工具按需调用。
- **直连(Direct)**:工具以 `{server}_{tool}` 为前缀名称,作为顶层原生函数直接开放给智能体。
### `mcp` 代理工具
`mcp` 代理工具是注入智能体上下文的一个独立函数,它多路复用了分配给该智能体的所有 MCP 服务端。智能体无需在启动时一次性加载所有工具的完整参数 Schema,而是根据实际需要与服务端交互:
- `mcp({})` — 查看所有已分配服务端的连接与认证状态
- `mcp({ server: "name" })` — 列出指定服务端的可用工具
- `mcp({ search: "query" })` — 跨服务端检索工具(默认附带参数 Schema)
- `mcp({ describe: "tool" })` — 检视指定工具的完整参数 Schema
- `mcp({ instructions: "name" })` — 查看指定服务端的使用指引
- `mcp({ server: "name", tool: "tool_name", args: {...} })` — 调用工具(支持传入 `{server}_{tool}` 前缀名称或工具原名)
- `mcp({ action: "auth-start", server: "name" })` — 为指定服务端发起 OAuth 认证流程
由于上下文窗口仅被单个紧凑的工具(外加简短的服务端/工具列表)占用,即便服务端暴露数十个工具,代理模式依然能将 Token 开销降至极低。相应的权衡在于增加了一轮服务发现交互:智能体通常需要先列出或检索工具,随后再发起调用。
### 直连工具 (Direct Tools)
直连工具则采用了另一种权衡取舍。被设为**直连(Direct)**的工具会被注册为原生顶层函数(如 `tavily_mcp_tavily_search`),智能体能够像调用内置工具一样直接使用它。
直连工具的优势:
- **高频操作调用更快、更稳定**:完整的参数 Schema 始终驻留在上下文窗口中,智能体无需先通过代理发现,一步即可直接调用。
- **工具感知度更高**:模型能够预先感知工具功能及其描述,更容易在恰当时机自主选用该工具。
开销代价:每个直连工具的 Schema 都会常驻并消耗上下文 Token,因此建议仅将高频或关键工具设为**直连**,将接口繁多的庞大 MCP 服务端保持为**代理**模式以节省上下文。直连工具同样遵循基于角色的权限校验规则,且 `mcp` 代理工具仍可继续用于服务发现、鉴权与状态检查。
---
## 身份认证模式
Shumai 支持多种认证策略以保障 MCP 端点的安全访问:
### 1. 无认证 (`none`)
用于公开或本地运行且无需认证凭据的 MCP 服务端。
### 2. Bearer Token (`bearer`)
提供静态 API Token 或密钥。Shumai 会在所有传输请求的 `Authorization: Bearer <token>` 请求头中附带该令牌。
### 3. OAuth 2.0 (`oauth`)
面向受 OAuth 身份提供商保护的 MCP 端点:
- **授权码模式 + PKCE(Authorization Code + PKCE)**:在团队设置的服务端卡片上点击**连接**。Shumai 会弹出安全的 OAuth 授权窗口并跳转至身份提供商页面。确认授权后,浏览器会自动回调至 Shumai,完成令牌兑换并刷新服务端工具列表。
- **客户端凭据模式(Client Credentials)**:填入 `Client ID` 与 `Client Secret`,用于自动化服务间令牌获取。
---
## 为智能体分配 MCP 服务端
默认情况下,新添加的 MCP 服务端**未分配给任何智能体**。若需授权智能体访问 MCP 服务端:
1. 前往**团队设置** > **智能体**。
2. 点击目标智能体打开配置弹窗。
3. 向下滚动至 **MCP 服务端**区域。
4. 勾选希望授权给该智能体的 MCP 服务端开关。
5. 点击**保存修改**。
---
## 基于角色的访问控制 (RBAC)
每个 MCP 服务端均支持设置**最低权限角色**(`Reviewer` 审阅者、`Editor` 编辑者或 `Owner` 所有者):
- 当智能体尝试调用 MCP 服务端上的工具时,Shumai 会校验当前与智能体交互的用户角色。
- 若用户角色未达到设定的最低门槛,工具执行将被拦截并返回权限不足的错误信息,杜绝越权操作。
+70
View File
@@ -0,0 +1,70 @@
---
title: 资产元数据
description: 通过动态作用域元数据字段与 AI 自动填充能力,按需定制媒体资产属性。
---
传统文件系统通常仅支持文件名、修改日期等基础属性。Shumai 支持构建贴合创意工作流的结构化元数据字段——涵盖审核状态跟踪以及技术参数自动捕获。
---
## 元数据作用域
侧边栏检查器按字段作用域分组显示:
- **基础属性(系统作用域)**:Shumai 内置的核心字段,适用于所有团队与项目。其中许多参数(如分辨率、时长和编解码器)会在文件上传时自动提取。
- **团队属性(团队作用域)**:在团队层级定义的自定义字段,由该团队下的所有项目继承。非常适合用于贯彻团队或企业级的元数据规范。
- **自定义字段(项目作用域)**:专为单个项目工作区定义的独特元数据字段。
---
## 自定义字段类型
在构建或编辑元数据规范时,可选择以下自定义字段类型:
- **文本**:单行文本输入框,用于简短字符串、代码编号或标签。
- **长文本**:多行文本输入区,用于详细描述、摘要或备忘备注。
- **下拉单选**:单选下拉菜单,支持为各选项配置背景颜色(例如“已通过”设为绿色,“处理中”设为黄色)。
- **标签(多选)**:多选标签字段,支持为单个资产添加多个带有自定义颜色的标签。
- **星级评分**:交互式星级评分组件(支持 2 至 6 星配置),用于评审打分与评级。
- **数值**:数值字段,支持自定义小数位数(0 至 3 位小数),适用于帧率、计数或评分等数值。
- **开关选框**:布尔开关(例如“需视效制作”)。
- **日期**:日期选择器,支持自定义显示格式(本地格式、ISO、美式、欧式、友好易读格式)并支持记录时间。
- **单成员**:单选用户字段,动态获取团队成员列表并展示其姓名和头像。
- **多成员**:多选用户字段,动态获取团队成员列表,支持指派多个团队成员。
![资产元数据字段](/metafields.webp)
---
## 默认内置字段
每个项目均预置了若干核心字段,并在文件上传或状态变更时自动填充:
- **技术规格**:文件大小、格式、文件类型(视频、音频、图片、文档、文件)、分辨率宽/高、视频/音频编解码器、时长、帧率及音频采样率。
- **协作字段**:
- **状态**:下拉单选字段,包含“需审核”(红色)、“处理中”(黄色)和“已通过”(绿色)。
- **评分**:5 星评分体系,用于快速评审打分。
- **关键词**:标签(多选)字段,用于分类资产。
---
## 字段设置与控制
### 只读字段
将自定义字段标记为**只读**可防止团队成员直接修改其数值。该功能非常适合通过程序或自动化集成填充的数据字段。
### AI 自动填充
在元数据字段上启用 **AI 自动填充**后,Shumai 会使用团队默认配置的 Gemini AI 模型自动分析上传的资产,并将提取的分析结果填入该字段:
- 文本/长文本:AI 自动生成摘要、描述或镜头记录日志。
- 单选/多选:AI 自动归类主题或打上匹配的标签。
- 数值:AI 可输出置信度评分或其他指标。
### 可见性与排序
在元数据检查器中:
- **可见性**:开启或关闭字段显示,保持侧边栏清爽,仅聚焦当前审核流程所需的内容。
- **排序**:在字段设计器中拖拽字段,自由调整自定义字段区域的展示顺序。
+126
View File
@@ -0,0 +1,126 @@
---
title: 非线性编辑 (NLE) 导出与 Premiere Pro 插件
description: 将带时间戳的评审评论导出为常用 NLE 格式,或使用原生 Premiere Pro UXP 插件导入媒体资产并自动同步时间线标记。
---
Shumai 可直接融入视频剪辑工作流。用户既能在 Web 界面中将评审意见导出为行业标准的非线性编辑系统 (NLE) 标记格式,也能通过原生 Adobe Premiere Pro UXP 插件直接导入媒体资产,并将评审评论实时同步至时间线标记。
---
## 导出评论至非线性编辑系统 (NLE)
在音视频评审中添加的评论,可直接从 Web 界面导出至外部剪辑软件。
### 评论导出步骤
1. 在 Shumai 媒体播放器中打开任意音视频资产。
2. 在右侧边栏中切换至**评论**选项卡。
3. 点击**所有评论**旁边的**更多操作**(`...`)菜单。
4. 悬停在**导出评论**上,选择对应的剪辑软件格式:
| 格式 | 文件扩展名 | 目标软件 |
| :----------------- | :--------- | :--------------------------- |
| **Premiere Pro** | `.xml` | Adobe Premiere Pro 序列标记 |
| **Resolve** | `.edl` | DaVinci Resolve 时间线标记 |
| **FCP 10.4.0+** | `.fiojson` | Apple Final Cut Pro 标记数据 |
| **Media Composer** | `.xml` | Avid Media Composer 标记 |
下载完成后,将标记文件导入剪辑软件,即可把所有评审批注和时间戳直接叠加到时间线上。
---
## Premiere Pro UXP 插件(实验性)
Shumai 官方 Premiere Pro UXP 插件在 Adobe Premiere Pro 内提供了原生工作面板,剪辑师可直接浏览工作区资产、将原素材或代理媒体导入项目素材箱,并自动将评审评论同步为序列时间线标记。
> [!NOTE]
> **实验性功能:**
> Premiere Pro UXP 插件当前处于实验阶段。功能虽然完整,但尚未覆盖所有 Premiere Pro 小版本与操作系统环境。若遇到 Bug、异常表现或有工作流建议,欢迎在 [GitHub 提交 Issue](https://github.com/shumaiOne/shumai/issues) 或前往我们的 [Discourse 论坛](https://shumai.discourse.group/) 反馈交流。
### 最低版本要求
| 软件 | 最低版本要求 |
| :--------------------- | :---------------------------------------------- |
| **Adobe Premiere Pro** | **`25.1.0`** 或更高(Premiere Pro 2025 v25.1+) |
| **Shumai 服务端** | **`0.4.6`** 或更高 |
---
### 安装指南
支持通过 `.ccx` 打包安装程序或 Adobe UXP Developer Tools 安装 Shumai Premiere Pro 插件。
#### 方式一:通过 Creative Cloud (.ccx) 安装
推荐普通用户使用此方式,安装最便捷。
> [!IMPORTANT]
> **前置条件:**
>
> - 系统需预先安装 **Adobe Premiere Pro**(v25.1.0+)以及 **Adobe Creative Cloud 桌面应用程序**。
> - Adobe Premiere Pro 必须在 Creative Cloud 桌面应用的“已安装应用程序”列表中正常识别显示。
1. 从代码仓库下载预构建的插件安装包 [`shumai-premiere.ccx`](https://github.com/shumaiOne/shumai/raw/main/apps/premiere-uxp/shumai-premiere.ccx)(位于源码路径 `apps/premiere-uxp/shumai-premiere.ccx`)。
2. 双击下载的 `.ccx` 文件,或直接将其拖入 **Adobe Creative Cloud** 桌面应用。
3. 按照 Creative Cloud 弹窗提示确认并完成安装。
4. 启动或重启 Adobe Premiere Pro。
#### 方式二:通过 Adobe UXP Developer Tools (UDT) 安装
此方式适用于开发者或需要从源码构建的用户。
> [!NOTE]
> 关于 UXP Developer Tool (UDT) 的安装与配置细节,请参阅官方 [Adobe UXP Developer Tools 文档](https://developer.adobe.com/premiere-pro/uxp/getting-started/quickstart/)。
1. 克隆 Shumai 仓库:
```bash
git clone https://github.com/shumaiOne/shumai.git
cd shumai
```
2. 安装依赖并构建 UXP 插件:
```bash
bun install
bun run --filter @shumai/premiere-uxp build
```
3. 打开 **Adobe UXP Developer Tool** (UDT)。
4. 点击 **Add Plugin** 并选中如下路径的清单文件:
```text
apps/premiere-uxp/dist/manifest.json
```
_(若处于监听开发模式,则选择 `apps/premiere-uxp/public/manifest.json`)。_
5. 启动 Adobe Premiere Pro。在 UDT 应用列表中找到 Shumai 插件,点击右侧 `•••` 菜单,选择 **Load**(或 **Load & Watch**)。
---
### 连接 Shumai 服务器
1. 在 Premiere Pro 中,依次点击**窗口** > **扩展** > **Shumai**(或**窗口** > **Shumai**)打开插件面板。
2. 输入连接凭据:
- **服务端地址(Endpoint URL):** Shumai 服务器地址(例如 `http://localhost:3000` 或 `https://shumai.yourdomain.com`)。
- **API Key:** 在 Shumai 中生成的有效 API 密钥。生成方法:在浏览器中打开 Shumai,进入**团队设置** > **开发者指南**,生成新的 API 密钥。
3. 点击**连接**。连接成功后,凭据将保存在 Premiere Pro 本地配置中。
---
### Shumai UXP 插件核心功能
该插件在 Premiere Pro 中深度集成了两大核心工作流:
#### 1. 浏览并导入资产至 Premiere Pro
- **浏览与检索**:通过面包屑导航与即时搜索,便捷浏览 Shumai 项目、文件夹与媒体资产。
- **按需选择下载画质**:点击任意资产上的**导入**,可自由选择:
- **原始素材(Raw)**:下载并导入完整的原始高码率母版媒体文件。
- **视频代理(Proxy)**:下载并导入经转码优化的代理文件(如 1080p、720p、540p 或 360p MP4),剪辑播放更流畅轻快。
- **原生目录选择**:调起系统原生文件夹选择弹窗,自主决定媒体文件在本地磁盘中的保存位置。
- **自动导入素材箱**:文件保存到本地后,自动导入当前 Premiere Pro 活动项目的素材箱。
#### 2. 自动同步评论至序列标记
- **关联序列**:在插件文件列表中,点击任意视频资产的**关联序列**,即可将其与当前处于活动状态的时间线序列建立绑定。
- **自动生成标记**:插件立即拉取 Shumai 中的已有评论,转换为 Premiere Pro 原生序列标记:
- **精准时间戳**:带有指定时间码的评论将精确定位在对应的帧;无时间戳的全局评论则放置在序列起始位置(`00:00:00:00`)。
- **作者与内容**:标记名称显示评论者姓名,标记附注完整包含评论正文及层级回复内容。
- **后台持续同步**:插件在后台自动轮询同步(每 12 秒),且在面板获得焦点或切换序列时立即触发同步。
- **序列管理面板**:随时切换至**序列**选项卡,查看项目中所有已关联的序列、上次同步时间,支持手动即时同步或解除关联。
- **干净解绑**:当解除资产与序列的关联时,Shumai 会精准清理其自动生成的标记,绝不影响项目中原有的其他标记。
+54
View File
@@ -0,0 +1,54 @@
---
title: 通知中心
description: 随时掌握评论动态、文件上传与项目最新进展。
---
Shumai 内置了完善的通知系统,便于随时掌握团队动态、文件处理状态以及审阅反馈。用户可以自由定制各类事件的通知规则、在通知收件箱中查收更新,或针对特定项目单独开启/关闭通知。
---
## 通知设置
针对不同团队,用户可自定义个性化的通知偏好,避免干扰:
1. 点击侧边栏中的 **团队设置**(Team Settings)。
2. 选择 **通知**(Notifications)标签页。
3. 切换开关以启用或禁用特定事件的通知:
### 评论与回复
- **常规评论**:当有人对我参与协作的资产发表评论时发送通知。
- **评论回复**:当有人回复我的评论会话时发送通知。
- **@提及**:当有人在任意评论中通过 `@用户名` 提及我时发送通知。
### 资产与状态
- **本人上传**:当我上传的文件完成媒体转码并可供审阅时发送通知。
- **他人上传**:当其他团队成员上传新资产时发送通知。
- **状态更新**:当有人更改资产状态时发送通知(例如从“进行中”变更为“已批准”)。
---
## 项目级通知
若需彻底静音某个特定项目(直接 `@提及` 除外,此类通知始终会投递):
1. 进入 **项目** 控制台。
2. 打开 **项目设置**。
3. 开启或关闭 **启用通知** 开关。
---
## 通知收件箱
- 当有未读通知时,导航栏中的 **铃铛** 图标会显示红色标记。
- 点击铃铛图标即可打开通知动态面板。
- 点击任意通知卡片即可将其标记为已读,并直接跳转至对应的文件与评论会话。
---
## 邮件通知
除应用内通知外,团队所有者还可配置 SMTP 发信服务,向团队成员定时投递批量活动摘要邮件。邮件投递引擎会严格遵循上述各成员单独配置的通知偏好。
详见 [邮件通知指南](/zh/using-shumai/email-notifications) 获取完整的 SMTP 配置说明、测试邮件发送流程及投递架构详情。
+60
View File
@@ -0,0 +1,60 @@
---
title: 密码重置
description: 管理员如何为团队成员生成安全的密码重置链接。
---
考虑到标准私有化部署下 Shumai 并未强制要求配置外部邮件服务(SMTP),密码重置操作由管理员通过 Shumai CLI 安全发起。
---
## 概述
当用户遗忘密码时,管理员可直接在命令行中为其生成一次性密码重置链接。
- **链接有效期**:生成的密码重置链接有效期为 **1 小时**(`3600 秒`)。
- **一次性使用**:重置令牌一经使用即刻永久失效。
- **会话注销**:用户重置密码后,该账户在所有设备上的所有现有活跃会话均会自动注销。
- **最新链接有效原则**:为同一用户生成新的重置链接后,此前生成的所有待处理链接立即失效。
---
## 生成密码重置链接
### 在本地宿主机 / 服务器运行
在 Shumai 安装目录下运行 `reset-password` 子命令:
```bash
shumai reset-password <user-email>
```
_(或执行 `bun apps/web/src/index.ts reset-password <user-email>`)_
**输出示例:**
```text
http://localhost:3000/reset-password?token=bb3xg4uO3cwN0FQv4cgUK6Hh
```
### 在 Docker 容器内运行
若 Shumai 运行在 Docker 容器中,请使用 `docker exec` 执行命令:
```bash
docker exec -it <container-name-or-id> shumai reset-password <user-email>
```
> [!TIP]
> 系统同时支持 `shumai` 与常见易错拼写别名 `shuami`(例如 `shuami reset-password <user-email>`)。
> [!NOTE]
> 对于远程服务器或生产环境部署,请确保环境中已配置 `BETTER_AUTH_URL`(例如 `BETTER_AUTH_URL=https://shumai.example.com`),以便 CLI 生成带有公网域名的重置链接,而非 `localhost`。
---
## 成员重置流程
1. 管理员通过安全的沟通渠道将生成的 URL 发送给团队成员。
2. 用户在浏览器中打开该链接。
3. 用户输入 **新密码** 并 **确认密码**(长度至少 3 个字符)。
4. 点击 **重置密码** 后,密码即安全更新,所有旧的活跃会话全部失效,并跳转至 `/login` 页面重新登录。
+121
View File
@@ -0,0 +1,121 @@
---
title: 资源配额
description: 配置团队资源配额、实时监控用量并在仪表板中重置配额周期。
---
AI 工作流与媒体处理工具会消耗大量算力与 API 额度。Shumai 提供了**资源配额**(Resource Quotas)体系,使团队所有者能够设置精细化的用量限制、管控成本预算,并实时监控团队成员与角色的用量情况。
---
## 概述
资源配额支持在指定的时间窗口(如每小时、每天或每周)内设定最大用量上限。当成员或团队达到设定的配额时,系统将安全拦截针对该资源的后续操作,直至配额周期重置。
配额规则配置与用量监控在界面中相互独立:
- 若要创建和管理配额规则,请打开 **团队设置** 并切换到 **配额** 标签页。
- 若要监控实时用量,请打开 **团队仪表板**,并在 **团队** 区域下选择 **配额**。
配额仪表板面向团队所有者开放。
---
## 作用域模式
创建或编辑配额规则时,可定义限制额度的生效方式:
### 1. 每位成员独立配额 (Each Member)
- **工作机制**:作用域内的每位成员均获得独立的使用额度。单名成员的消耗不会影响其他人的剩余配额。
- **可选角色筛选**:可将配额限定为特定角色的成员(例如仅限 **编辑者 (Editor)** 或 **审阅者 (Reviewer)**),或应用于全团队。
- **适用场景**:为每位编辑者分配每天 100,000 Token 的用量预算。
### 2. 全体成员共享池 (All Members - Shared Pool)
- **工作机制**:所有符合条件的成员共同分摊一个配额总池,每位成员的消耗均从该总额中扣除。
- **可选角色筛选**:将共享池应用于全团队成员,或仅限定特定角色。
- **适用场景**:将团队每天在 AI 模型上的总开销上限控制在 50 美元以内。
### 3. 指定成员 (Selected Members)
- **工作机制**:为选定的个别团队成员分配独立限额。
- **适用场景**:为资深艺术家或技术总监赋予更高的限额,同时对其他人保持标准限制。
---
## 支持的资源类型
Shumai 在 AI 与智能体架构的多个层级上均支持配额管控:
| 资源类型 | 说明 | 目标范围 |
| :------------------------------------------- | :------------------------------------------------------------------------------- | :------------------------------ |
| **总 Token 数 (Total Tokens)** | 在对话、评论与自动填充中消耗的 LLM 输入与输出 Token 总数。 | 团队、角色或成员 |
| **AI 成本 ($) (AI Cost ($))** | 调用 AI 模型服务商产生的美元费用开销。 | 团队、角色或成员 |
| **MCP 服务调用次数 (MCP Server Calls)** | 发送给已连接模型上下文协议 (MCP) 服务的工具调用总数。 | 目标 MCP 服务 ID |
| **沙箱 Bash 命令 (Sandboxed Bash Commands)** | 智能体在隔离沙箱内执行的 Shell 命令。 | 通配符模式(例如 `npm *`、`*`) |
| **智能体工具调用 (Agent Tool Calls)** | 对特定原生工具的调用次数(例如 `read_asset`、`download_asset`、`create_file`)。 | 工具名称 |
### Bash 命令通配符匹配
在沙箱 Bash 执行中,支持使用通配符(`*` 与 `?`)限定特定的命令模式:
- `*`:匹配任意 Bash 命令执行。
- `npm *`:匹配任意 npm 命令(例如 `npm install`、`npm test`)。
- `git commit*`:匹配 git commit 相关调用。
---
## 时间周期与滚动重置
配额支持配置以下重置周期:
- **1 小时** (`1hour`)
- **5 小时** (`5hour`)
- **1 天** (`1day`)
- **7 天** (`7day`)
### 惰性重置机制
Shumai 自动跟踪用量周期窗口。当周期窗口到期后,系统会在成员发起下一次请求时自动重置配额并开启新的周期,无需后台定时巡检任务即可无缝衔接。
---
## 监控实时用量
团队所有者可在团队仪表板中查看实时消耗情况:
1. 打开 **团队仪表板**。
2. 在 **团队** 区域下选择 **配额**。
3. 配额规则以一级折叠卡片形式展示。
4. 展开某条规则以查看其用量明细记录。
每条用量记录包含以下信息:
- **消耗状态**:显示已用额度与总额度对比的进度条。
- **剩余可用量**:剩余额度的百分比与具体数值。
- **刷新倒计时**:当前活跃周期重置前的剩余时间(例如:_“45 分钟后刷新”_)。
- **目标对象**:与该记录关联的团队共享池、角色池或具体成员。
- **成员搜索**:对于成员级别的规则,支持按成员姓名或邮箱搜索用量记录。
展开规则时会加载用量记录,且在规则展开期间保持自动刷新。
### 手动重置用量记录
每条用量记录均包含 **重置用量** 操作项。确认操作后:
- 消耗量归零。
- 配额新周期立即开始。
- 该周期在达到设定的配额时长后结束。
- 例如,在 10:00 重置一个 1 天配额,将开启从 10:00 至次日 10:00 的全新周期窗口。
重置操作还可用于为尚未产生用量的成员或共享池初始化一条用量为零的记录。重置行为会记录在团队审计日志中。
---
## 管理配额规则
- **启用 / 禁用**:通过切换团队设置中任意配额卡片上的开关,可在不删除规则的情况下临时暂停或恢复执行。
- **编辑规则**:点击团队设置中的任意配额卡片,即可更新限额、更改重置周期或调整选定的成员。
- **删除规则**:打开团队设置中的卡片操作菜单(`⋮`)并选择 **删除**,即可移除该配额规则。
配额用量的监控与重置在团队仪表板中操作,而非在设置规则卡片中处理。
+40
View File
@@ -0,0 +1,40 @@
---
title: 语义搜索
description: 基于 AI 向量相似度,通过视觉与文本语义查找文件。
---
传统搜索依赖字符精确匹配(例如:搜索 "dog" 无法找到名为 `golden_retriever.jpg` 的文件)。Shumai 通过 **语义搜索** 解决了这一痛点,支持对文件的概念与深层语义建立索引。
---
## 语义搜索原理
语义搜索将文本查询词与文件内容转化为概念特征档案,使相似的构思与视觉画面在向量空间中邻近排列。
1. **索引生成**:上传媒体资产时,Shumai 后台智能体将扫描文件的视觉元素、文本内容或描述信息,并转化为概念特征档案。
- **多模态向量模型服务**:Shumai 支持两类模型服务:
- **EmbeddingGemma 2(本地)**:由 `shumaiOne/embedding-server` 驱动,生成 768 维多模态向量,完全离线运行。视频按每个 60 秒分块以 **每分钟 15 帧**(非标准宽高比为 14 帧)采样。详见 [向量模型服务配置指南](/zh/using-shumai/embedding-server)。
- **Gemini Embedding 2(云端)**:由 Google 的 `gemini-embedding-2` API 驱动,生成 1536 维向量。视频切分为 60 秒片段(去除音频,按 1 fps 采样,每块最多 32 帧)。
- **分块配置**:管理员可通过环境变量 `EMBEDDING_CHUNK_DURATION`(默认值:60s)与 `EMBEDDING_CHUNK_OVERLAP`(默认值:5s)自定义分块时长与重叠时间。
2. **概念匹配**:开启“语义搜索”(Semantic)开关后,Shumai 会比对查询词的概念含义与媒体资产的语义特征。
3. **检索结果**:例如搜索“海滩日落”,即使视频文件名为 `IMG_4029.mp4`,也能成功检索到黄昏海浪拍岸的视频。
### 理解搜索结果
语义搜索与传统的关键字过滤机制有所不同:
- **排序对比筛选**:语义搜索的表现更接近 **相关度排序** 而非严格的硬过滤。最相关的结果会优先置顶显示,但关联度较低的内容仍可能出现在列表后方(排名较低)。若需排除特定类型的文件,可配合 **筛选** 面板组合使用。
- **视频分块结果**:由于 Shumai 采用分块机制对视频建立索引,同一个长视频可能会在搜索结果中出现多次,每条结果对应匹配到概念的具体视频片段。
- **匹配时间戳**:当检索结果来自某个视频分块时,Shumai 会标出匹配的起止时间点。点击此类结果可直接打开视频并自动跳转到对应的时间戳位置。
---
## 启用语义搜索
若需使用语义搜索:
1. 确认团队管理员已在 **团队设置** > **智能体** 下启用了 **Embedding 智能体**。
2. 启用后,Shumai 将自动为新上传的文件建立索引。
3. 在文件管理器的搜索框旁开启 **语义**(Semantic)开关,即可按概念语义检索资产。
![语义搜索开关](/semantic-search.webp)
+83
View File
@@ -0,0 +1,83 @@
---
title: 分享链接
description: 安全地向外部客户与利益相关者分享文件和文件夹。
---
Shumai 支持与未注册工作区账号的外部利益相关者协作。借助**分享链接**,可向指定人员授予特定文件夹或资产的浏览与评论权限。
---
## 创建分享链接
1. 选中要分享的文件或文件夹,右键单击并选择**创建新分享链接**。
2. 在项目侧边栏中点击刚创建的**分享链接**,进入其配置页面。
3. 在右侧边栏中配置分享链接参数:
- 添加密码保护
- 设置过期时间
- 开启或禁止文件下载
- 为预览画面添加水印
- 自定义对访客可见的元数据字段
4. 点击侧边栏底部的**复制链接**,将链接发送给客户或外部协作者。
![配置分享链接](/sharelink.webp)
---
## 向已有分享链接添加资产
创建分享链接后,无需重新生成链接即可直接追加更多文件或文件夹:
1. 在文件浏览器中选中要添加的文件或文件夹。
2. 直接将其拖拽到项目侧边栏对应的分享链接条目上。
3. 分享链接将立即更新并包含新添加的资产。
---
## 安全与权限配置
### 有效期
可选设置链接失效的日期和时间。过期后,任何人访问该链接均会返回 `404 Not Found` 页面。
### 密码保护
为敏感资产配置访问密码。外部用户访问该链接时,必须输入正确的密码才能查看资产内容。
### 允许下载
控制访客是否能下载所分享的文件。当关闭**允许下载**时:
- 公共分享页面上的所有下载按钮均会被隐藏(包括文件卡片、多选操作栏、播放器控制栏以及顶部导航栏)。
访客仍可在线预览文件,但无法下载原文件。该选项常与水印功能搭配使用,既能满足预览需求,又能保护资产安全。
### 水印保护
在分享链接展示的每个预览画面上叠加水印(例如“CONFIDENTIAL”机密文本标签或企业 Logo 图片)。打开水印编辑器,调整布局模块后保存即可。
为了控制存储成本,水印采用**按分享链接按需生成(惰性转码)**机制:
- 仅在**分享链接开启水印**时才会触发水印转码——Shumai **不会**为工作区中的每个文件预先生成水印副本。
- 分享链接中已包含的所有视频和图片资产将在此刻开始转码(侧边栏会显示*处理中*状态,直至转码完成)。
- 后续向该分享链接**追加的文件和文件夹也会自动转码**,确保整个分享内容始终带有水印,无需人工干预。
- 由于仅对通过水印链接分享的资产生成水印副本,从未分享(或仅通过无水印链接分享)的文件绝不会占用额外的水印代理文件存储空间。对于大型媒体库,这能节省极为可观的存储开销。
说明:
- 仅**视频与图片**预览代理文件支持添加水印;其他媒体类型(PDF、音频等)不受影响。
- 水印转码处理期间,系统会隐藏预览画面,避免暴露未添加水印的原始代理文件。
### 默认排序规则
为分享页面配置默认排序规则(例如按名称或版本排序),确保客户按预期的顺序浏览文件。
### 列可见性
为保护内部机密信息,可精确配置对外部用户可见的元数据列。例如:
- **可见**:`资产名称`、`分辨率`、`下载链接`。
- **隐藏**:`内部预算编号`、`负责人备注`、`制作成本`。
### 禁用链接
若需立即撤销访问权限,请进入项目设置中的**分享链接**选项卡,开启**已禁用**开关。后续可随时重新启用该链接。
+39
View File
@@ -0,0 +1,39 @@
---
title: 排序与搜索
description: 使用搜索对话框查找资产,并通过自定义排序规则整理文件。
---
随着项目规模扩大,快速检索所需的媒体文件至关重要。Shumai 提供了功能强大的搜索对话框与灵活的排序控件。
---
## 搜索资产
点击工具栏中的搜索图标,即可打开专用的 **搜索对话框**。
![搜索对话框](/search-dialog.webp)
### 搜索对话框特性
- **关键词匹配**:在文本输入框中输入关键词,即可即时过滤文件名和文件夹名。
- **高级筛选**:点击展开筛选面板,构建多条件复合查询(例如:查找自定义字段“状态”等于“处理中”且文件类型为“视频”的文件)。
- **语义搜索开关**:若团队管理员启用了该功能,开启“语义搜索”(Semantic)开关即可按概念含义搜索(例如:搜索“阳光海滩”即可找到海洋片段,即使文件名中并未包含这些词)。
- **保存为合集**:便捷地将当前搜索条件转化为动态合集。点击对话框内的 **保存为合集**(Save as Collection),即可创建该合集并直接跳转至对应视图。
- **无限滚动加载**:输入关键词或调整筛选条件时,搜索结果将实时动态加载。
---
## 资产排序与重排
可以通过排序下拉菜单或点击元数据列标题,切换资产列表的排序规则:
- **自定义排序(默认)**:项目文件管理器默认采用 **自定义**(Custom)排序。在此模式下,可直接通过手动拖拽文件与文件夹,按需排列显示顺序。
- **标准排序选项**:支持按以下维度排序:
- _最新上传_:优先展示最新上传的资产。
- _名称_:按字母顺序排列(A-Z 或 Z-A)。
- _大小_:按文件体积大小排序。
- _类型_:将文件夹置顶聚合,随后展示版本堆栈与单文件。
- _自定义列_:按动态元数据字段排序(例如:按“截止日期”或“优先级”排序)。
> [!NOTE]
> **拖拽重排限制**:仅当排序规则设置为 **自定义** 时,才支持手动拖拽调整顺序。若选择了其他排序选项(如按名称或大小),手动重排功能将自动禁用。
@@ -0,0 +1,58 @@
---
title: 团队与项目管理
description: 组织工作区架构、定义权限角色并管理成员。
---
Shumai 采用“**团队**”与“**项目**”双层组织架构,实现精细化的文件访问控制与协作管理。
---
## 成员可见性与作用域
添加到团队的成员分为两种权限作用域:
- **团队作用域(Team Scope)**:团队作用域成员默认可以查看该团队下的所有项目。
- **项目作用域(Project Scope)**:项目作用域成员仅能查看并访问明确授权加入的特定项目。
---
## 成员角色
Shumai 通过权限角色控制团队与项目成员的操作权限:
- **所有者(Owner)**:拥有全部管理权限。团队所有者可以修改团队设置、智能体技能以及 AI 提供商配置;项目所有者可以编辑项目配置、管理项目成员并生成邀请链接。
- **编辑者(Editor)**:可以上传文件、编辑自定义元数据、创建文件夹,以及添加评论或画布标注。
- **审阅者(Reviewer)**:仅具备只读访问权限。可以浏览媒体资产、切换版本以及发表文本评论或画布涂鸦,但无法上传/删除文件或修改元数据。
---
## 项目角色覆盖机制
管理员可将现有团队成员添加到特定项目中,以覆盖其原有的权限角色:
- 在该项目内部,项目级角色的优先级高于团队级角色。
- _示例_:若 Peter 是拥有 **编辑者** 角色(Editor)的团队成员,管理员可将其以 **审阅者** 角色(Reviewer)加入 _项目 A_。此时 Peter 在“项目 A”中仅具备审阅者权限,而在团队的其他项目中依然保持编辑者权限。
---
## 成员管理
所有成员管理操作均通过统一的 **成员管理弹窗**(Members Dialog)完成:
### 1. 管理团队成员
- **入口**:打开 **团队控制台**,点击顶部栏中的成员列表或头像组。
- **配置操作**:
- 在“编辑者”与“审阅者”之间调整成员角色。
- 将成员从团队中移除。
- **邀请新成员**:选择目标角色(编辑者或审阅者),点击 **生成链接**(Generate Link)。复制注册链接即可邀请新用户加入团队。
### 2. 管理项目成员
- **入口**:打开项目的 **文件管理器**,点击顶部工具栏中的成员头像或管理按钮。
- **配置操作**:
- 调整项目成员角色,或将其从项目中移除。
- **添加团队成员**:弹窗会列出尚未加入该项目的活跃团队成员。为其指定项目角色(将在该项目内覆盖其团队角色),点击 **添加**(Add)即可立即加入。
- **邀请外部协作者**:选择目标角色(编辑者或审阅者),点击 **生成链接**(Generate Link),即可直接邀请新用户加入该特定项目。
![成员管理弹窗](/members.webp)
@@ -0,0 +1,81 @@
---
title: 视频转码
description: 配置视频转码策略、MP4 与 HLS 流媒体分辨率、硬件加速以及 FFmpeg 线程数。
---
高分辨率摄影机格式与原生媒体文件无法在 Web 浏览器中直接播放。Shumai 在后台自动将视频资产转码为适用于网页的流式传输与预览格式。
团队所有者可在 **团队设置 > 视频转码** 页面自定义视频转码行为。
无论选择何种转码策略,Shumai 流水线都会**始终**为原始文件生成至少一个轻量级 `180p` 代理版本,以确保快速拖拽播放(Scrubbing)、缩略图生成与即时预览。
---
## 转码策略
**转码策略**卡片用于配置 MP4 视频转码以及 HLS 自适应流媒体。
### 播放与下载行为
Shumai 采用双格式交付策略:
- **未启用 HLS 时**:浏览器内视频播放与文件下载均使用生成的 MP4 文件。
- **启用 HLS 时**:浏览器内视频播放使用 HLS(HTTP Live Streaming)实现流畅的自适应码率播放,文件下载则使用生成的 MP4 文件。
<Warning>
**存储用量提示**:启用 HLS 除生成标准 MP4 代理文件外,还会生成多码率切片文件(`.ts` /
`.m4s`)及播放列表清单,这会显著增加存储桶的容量占用。
</Warning>
### MP4 转码
生成兼容 Web 的 MP4 文件,用于文件下载与标准视频播放。团队所有者可为上传的文件选择 MP4 转码模式:
#### 1. 最佳匹配 (Best Match)
- **工作机制**:Shumai 检测所上传视频的最长边尺寸,生成单一匹配或略低于源画质的最优分辨率,避免无谓的升采样(Upscaling)。
- **输出产物**:生成轻量级 `180p` 代理版本以及计算得出的最佳匹配 MP4 文件。
- **适用场景**:推荐默认选项。在保证广泛的播放与下载兼容性的同时,最大程度缩短处理耗时并节省存储空间。
#### 2. 多分辨率阶梯 (Multi Resolutions)
- **工作机制**:可指定生成的目标分辨率阶梯:`480p`、`720p`、`1080p`、`1440p` 与 `2160p`。系统仅生成不超过原始分辨率的画质(绝不对内容升采样)。
- **输出产物**:生成 `180p` 代理版本,以及所选且未超出源视频分辨率的所有分辨率文件。
- **适用场景**:适用于需要下载多种指定分辨率的场景(例如使用 720p 快速分发共享,使用 1080p 审阅)。
### HLS 流媒体
开启 **HLS 流媒体** 开关后,Shumai 会为上传的视频生成自适应码率 HLS 分发包:
- **分辨率阶梯**:配置 HLS 流媒体生成的目标分辨率(`480p`、`720p`、`1080p`、`1440p`、`2160p`)。系统仅生成不超过原始视频分辨率的阶梯。
- **播放器集成**:当 HLS 可用时,Web 播放器会自动采用 HLS 流式播放,并根据客户端网络带宽动态切换码率。
![视频转码](/transcode.webp)
---
## 硬件加速
为将编码负载从 CPU 分流至 GPU,Shumai 支持硬件加速视频编码:
- **禁用(软件编码)**:使用标准 CPU `libx264` 软编器并配合恒定速率因子(CRF)。
- **自动检测**:自动探测并启用可用的 GPU / 硬件加速能力(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API、Apple VideoToolbox、Rockchip RKMPP)。
详见 [硬件加速转码指南](/zh/configuration/hardware-transcoding),获取 Docker Compose 配置、GPU 透传及驱动前置要求说明。
---
## FFmpeg 线程数
**FFmpeg 线程数** 滑块用于控制转码任务期间 FFmpeg 可调用的最大 CPU 线程数:
- **自动 (0)**:FFmpeg 根据宿主机可用 CPU 核心数自动选择最优线程数。
- **手动 (1 - 32)**:将 FFmpeg 限制为固定线程数,适用于在共享 Worker 节点上限制 CPU 资源占用。
---
## 处理架构
媒体转码属于高资源消耗型任务。管理员可根据扩缩容需求,选择在主服务器上直接运行转码引擎(单服务器模式),或将任务委派给专门的转码 Worker 节点(独立 Worker 模式)。
无论采用何种模式,负责处理的机器均须安装系统级媒体工具(`ffmpeg` 与 `ffprobe`)。关于搭建独立转码 Worker 的详细步骤,请参阅 [分布式部署指南](/zh/configuration/distributed)。
+44
View File
@@ -0,0 +1,44 @@
---
title: 文件版本堆栈
description: 将媒体资产的多个修订版本归拢至单个版本控制堆栈中。
---
在创意资产协作过程中,文件通常会经历多次迭代(例如 `draft_v1.mp4`、`draft_v2.mp4`、`draft_final.mp4`)。为了防止工作区杂乱无章,Shumai 支持将这些修订版本归拢合并为一个 **版本堆栈**(Version Stack)。
---
## 什么是版本堆栈?
**版本堆栈** 将同一文件的多个修订版本聚合为单个条目。Shumai 无需让大量相似文件堆满文件夹,而是将其折叠为一个带有版本角标(如 "V3")的条目,并提供历史版本下拉列表。
![版本堆栈选择器](/versionstack.webp)
---
## 创建与添加版本堆栈
可通过以下两种交互方式创建版本堆栈或向现有堆栈添加新版本:
- **拖拽操作**:
- _创建堆栈_:在文件列表中将一个独立文件直接拖拽覆盖到另一个独立文件上方。
- _添加版本_:将一个独立文件直接拖拽到现有版本堆栈上方。
- **右键菜单**:
- 右键点击任意独立文件或现有版本堆栈。
- 在菜单中选择 **创建新版本**(Create New Version)。
- 从电脑中选取修订版文件,直接上传至该堆栈中。
---
## 版本管理
### 当前活跃版本
位于堆栈顶部的版本为 **当前活跃版本**(Active Version)。项目控制台、搜索结果以及元数据面板中均默认展示此版本。
### 调整版本顺序与回退版本
支持提升历史版本或重新排列堆栈顺序:
- 打开版本堆栈详情侧边栏。
- 在列表中拖拽调整各版本顺序。拖拽到顶部的版本将自动成为当前活跃版本。
- 若需从堆栈中移出某个文件,可直接将其拖出,或选择 **拆分堆栈**(Unstack)。该操作会将该文件作为独立文件移回父文件夹。
+3 -5
View File
@@ -1,6 +1,6 @@
{
"name": "shumai",
"version": "0.6.3",
"version": "0.7.0",
"private": true,
"type": "module",
"repository": {
@@ -28,10 +28,11 @@
"db:migrate": "bun run prisma migrate dev",
"db:deploy": "bun run prisma migrate deploy",
"db:generate": "cd packages/db && bunx prisma generate",
"worker:agent": "bun apps/agent/src/index.ts",
"worker:transcode": "bun apps/transcode/src/index.ts",
"build": "bun run i18n:compile && bun run build.ts",
"build-npm": "bun run i18n:compile && bun scripts/build-npm.ts",
"build:cli": "bun scripts/build-cli.ts",
"test:cli-release": "bun scripts/test-cli-release.ts",
"prepublishOnly": "bun run build-npm && bun run lint && bun run typecheck",
"publish": "bun run prepublishOnly && bun run scripts/publish.ts",
"publish:dry": "bun run prepublishOnly && bun run scripts/publish.ts --dry-run",
@@ -67,8 +68,5 @@
"typescript-eslint": "8.68.0",
"vite-tsconfig-paths": "6.1.1",
"vitest": "4.1.11"
},
"patchedDependencies": {
"@earendil-works/pi-ai@0.82.1": "patches/@earendil-works%2Fpi-ai@0.82.1.patch"
}
}
+4 -4
View File
@@ -1,14 +1,14 @@
{
"name": "@shumai/agent",
"version": "0.6.3",
"version": "0.7.0",
"private": true,
"type": "module",
"main": "./src/index.ts",
"types": "./src/index.ts",
"dependencies": {
"@anthropic-ai/sandbox-runtime": "0.0.74",
"@earendil-works/pi-agent-core": "0.82.1",
"@earendil-works/pi-ai": "0.82.1",
"@earendil-works/chord": "1.5.0",
"@earendil-works/pi-ai": "1.5.0",
"@earendil-works/pi-durable": "1.5.0",
"@google/genai": "2.28.0",
"@shumai/core": "workspace:*",
"@shumai/db": "workspace:*",
File diff suppressed because it is too large Load Diff

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