feat: add direct sandbox workspace preview (#7316)

* feat: add direct sandbox workspace preview

* refactor: align sandbox preview claims with upstream

refactor: fix IDE agent internal ports

fix: decode sandbox proxy claims generically

ci: install Rust toolchain without third-party actions

* chore: keep sandbox proxy on one port by default

feat: split sandbox proxy preview port
fix: require sandbox preview proxy URL

Author: c121914yu

.agents/design/core/ai/sandbox/workspace-direct-preview.md

@@ -0,0 +1,145 @@
+# Agent Sandbox Workspace Direct Preview
+
+## 1. Goal
+
+Replace sandbox file S3 export with a short-lived, read-only URL:
+
+```text
+https://agent-proxy.fastgpt.cn/preview/{token}/test/preview.html
+```
+
+The token authenticates one sandbox workspace. The remaining URL is resolved as a workspace-relative
+path. File bytes flow from the sandbox IDE agent through `agent-sandbox-proxy`; FastGPT only authenticates
+the business session, signs the token, and resolves the provider endpoint.
+
+## 2. Scope
+
+- Replace HTML S3 preview with direct workspace preview.
+- Replace `sandbox_get_file_url` S3 uploads with direct workspace URLs.
+- Support `GET`, `HEAD`, content type, content length, ETag, and single byte ranges.
+- Preserve relative HTML references such as `./assets/app.js` and `../images/a.png`.
+- Keep existing `fs` and `terminal` WebSocket behavior unchanged.
+- Support provider endpoint resolution through `ISandbox.getEndpoint`.
+
+The existing S3 workspace archive lifecycle is unrelated and remains unchanged.
+
+## 3. Architecture
+
+```text
+Browser / model
+  -> GET /preview/{token}/{workspacePath}
+  -> agent-sandbox-proxy
+       1. verifies HMAC token locally
+       2. resolves the sandbox endpoint through FastGPT verifyTicket using an internal header
+       3. proxies an authenticated HTTP request to port 1319
+  -> fastgpt-ide-agent preview listener
+       1. validates the internal agent password
+       2. confines the path to FASTGPT_WORKDIR
+       3. streams the file response
+```
+
+## 4. Token Contract
+
+Preview tokens reuse `AGENT_SANDBOX_PROXY_SECRET` and the existing business identity claims:
+
+```ts
+{
+  sourceType,
+  sourceId,
+  userId,
+  chatId,
+  channel: 'preview',
+  permission: 'read',
+  exp
+}
+```
+
+The token never contains provider endpoints or the IDE agent password. The default lifetime remains two
+hours to preserve the existing `sandbox_get_file_url` contract.
+
+## 5. HTTP Contracts
+
+### 5.1 Public proxy
+
+```text
+GET|HEAD /preview/{token}/{*path}
+```
+
+- Preview may use an independent `PREVIEW_PORT`; when omitted it shares `PORT` with WebSocket routes.
+- `token` is one base64url JWT path segment.
+- `path` is workspace-relative.
+- Other methods return `405`.
+- The upstream host and port always come from FastGPT ticket resolution.
+
+### 5.2 Sandbox preview listener
+
+```text
+GET|HEAD /preview/{*path}
+X-FastGPT-Agent-Token: {agentPassword}
+```
+
+- Binds to the fixed internal address `0.0.0.0:1319`.
+- Uses `FASTGPT_WORKDIR` as the root.
+- Does not expose directory listings.
+- Rejects absolute paths, traversal, invalid encodings, and symlinks escaping the workspace.
+
+## 6. FastGPT Changes
+
+- Add reusable preview token signing and URL construction in the sandbox application layer.
+- Require `AGENT_SANDBOX_PREVIEW_PROXY_URL` as the public HTTP preview origin. It remains separate
+  from the required WebSocket `AGENT_SANDBOX_PROXY_URL` even when both URLs use the same port.
+- Change `getHtmlPreviewLink` to validate the session and return a preview URL without reading/uploading
+  the HTML file.
+- Change `sandbox_get_file_url` to return preview URLs without reading/uploading the files.
+- Extend internal ticket verification with `channel=preview` and endpoint port `1319`.
+- Update OpenAPI descriptions and tool descriptions to remove S3 semantics.
+
+## 7. Resource Reference Behavior
+
+Given:
+
+```text
+/preview/{token}/test/preview.html
+```
+
+- `./assets/app.js` resolves to `/preview/{token}/test/assets/app.js` and works.
+- `../images/a.png` resolves to `/preview/{token}/images/a.png` and works.
+- `/assets/app.js` loses the token prefix and is intentionally unsupported in this path-based version.
+
+The sandbox system prompt must require relative asset paths for generated previews.
+
+## 8. Security
+
+- A preview URL is a bearer capability for read-only access to the token's whole workspace.
+- Preview content uses the existing proxy origin, which must remain separate from the FastGPT app origin.
+- Responses set `Referrer-Policy: no-referrer`, `X-Content-Type-Options: nosniff`, and
+  `Cache-Control: private, no-store`.
+- Proxy and ingress logs must redact the token path segment.
+- The proxy sends tickets to FastGPT in `X-Sandbox-Ticket`, not the query string, so the main app's
+  request logs do not contain bearer tokens. FastGPT temporarily accepts the old query transport for rollout.
+- The proxy does not accept an upstream URL, host, scheme, or port from the client.
+- Cached endpoint resolution uses SHA-256 token keys and never bypasses local token expiration checks.
+
+## 9. Compatibility And Rollout
+
+- Sandbox runtime images must include the preview listener before FastGPT starts issuing preview URLs.
+- Default deployments expose one proxy port; split WebSocket and Preview ports only when explicitly configured.
+- Old sandboxes without port 1319 return a clear proxy error; local integration uses a freshly built image.
+- Upgrade FastGPT before agent-sandbox-proxy: the app accepts both old query tickets and new header tickets,
+  while the new proxy only uses the non-logging header transport.
+- `fs`, `terminal`, editor upload/download, and workspace S3 archive paths remain unchanged.
+- Local verification builds worktree images and runs them against the existing Docker dependencies.
+
+## 10. TODO
+
+- [x] Implement and test the IDE agent preview HTTP listener.
+- [x] Implement and test proxy preview routing and streaming relay.
+- [x] Add preview token signing, ticket verification, and URL helpers.
+- [x] Replace HTML preview S3 upload.
+- [x] Replace `sandbox_get_file_url` S3 upload.
+- [x] Update OpenAPI, environment/runtime contracts, prompt, and rollout notes.
+- [x] Build local sandbox and proxy images.
+- [x] Run TypeScript and Rust unit tests.
+- [x] Run an OpenSandbox end-to-end test with HTML, CSS, image, HEAD, Range, expiry, auth, and missing files.
+- [x] Cover traversal and escaping symlinks in unit tests.
+- [x] Run repository-wide final validation.

.forgejo/workflows/test-rust-agent.yaml

@@ -28,17 +28,15 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@4be7066ada62dd38de10e7b70166bc74ed198c30 # stable
-        with:
-          components: clippy, rustfmt
-
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
-        with:
-          shared-key: "fastgpt-rust-agent-cache"
-          workspaces: |
-            projects/agent-sandbox-proxy
-            projects/fastgpt-ide-agent
+        run: |
+          if ! command -v rustup >/dev/null 2>&1; then
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+              | sh -s -- -y --profile minimal
+            echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+            export PATH="$HOME/.cargo/bin:$PATH"
+          fi
+          rustup toolchain install stable --profile minimal --component clippy,rustfmt
+          rustup default stable
 
       # --- agent-sandbox-proxy Checks & Tests ---
       - name: Run agent-sandbox-proxy fmt check

.github/workflows/test-rust-agent.yaml

@@ -28,17 +28,15 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@4be7066ada62dd38de10e7b70166bc74ed198c30 # stable
-        with:
-          components: clippy, rustfmt
-
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
-        with:
-          shared-key: "fastgpt-rust-agent-cache"
-          workspaces: |
-            projects/agent-sandbox-proxy
-            projects/fastgpt-ide-agent
+        run: |
+          if ! command -v rustup >/dev/null 2>&1; then
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+              | sh -s -- -y --profile minimal
+            echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+            export PATH="$HOME/.cargo/bin:$PATH"
+          fi
+          rustup toolchain install stable --profile minimal --component clippy,rustfmt
+          rustup default stable
 
       # --- agent-sandbox-proxy Checks & Tests ---
       - name: Run agent-sandbox-proxy fmt check

deploy/version/v4.15/docker-compose.template.yml

@@ -75,6 +75,8 @@ x-agent-sandbox-config: &x-agent-sandbox-config
   AGENT_SANDBOX_PROXY_SECRET: *x-agent-sandbox-proxy-secret
   # 浏览器访问 agent-sandbox-proxy 的地址。启用 Agent/Skill 沙盒时，必须改成单独部署的 proxy 的 ws:// 或 wss:// 地址。
   AGENT_SANDBOX_PROXY_URL:
+  # 浏览器访问 sandbox preview 的 http:// 或 https:// 地址。默认单端口部署时与 WebSocket 使用相同端口。
+  AGENT_SANDBOX_PREVIEW_PROXY_URL:
   AGENT_SANDBOX_OPENSANDBOX_BASEURL:
   AGENT_SANDBOX_OPENSANDBOX_API_KEY:
   AGENT_SANDBOX_OPENSANDBOX_RUNTIME: docker

packages/global/core/ai/sandbox/constants.ts

@@ -62,4 +62,5 @@ export const SANDBOX_SYSTEM_PROMPT = `## 沙盒能力
 - 使用 ${SANDBOX_FIND_TOOL_NAME} 按 glob 搜索文件路径，优先于通过 shell 调用 find
 - 使用 ${SANDBOX_LS_TOOL_NAME} 列出目录内容，优先于通过 shell 调用 ls
 - 默认将生成文件保存在当前 sandbox 工作目录；若本轮 system-reminder 指定了更具体的产物目录或禁止目录，必须优先遵守
+- HTML 等多文件预览产物必须使用相对资源路径（例如 ./assets/app.js），不要使用 /assets/app.js 这类根路径
 - 若需要将生成的文件链接，可使用 ${SANDBOX_GET_FILE_URL_TOOL_NAME} 获取临时访问链接`;

packages/global/core/ai/sandbox/tools/getFileUrl.ts

@@ -13,17 +13,17 @@ export const SANDBOX_GET_FILE_URL_TOOL: ChatCompletionTool = {
   type: 'function',
   function: {
     name: SANDBOX_GET_FILE_URL_TOOL_NAME,
-    description: '从虚拟机读取指定文件，上传至云存储，返回 2 小时有效期的访问链接',
+    description: '为虚拟机 workspace 中的指定文件返回 2 小时有效期的直连访问链接',
     parameters: {
       type: 'object',
       properties: {
         paths: {
           type: 'array',
           items: {
             type: 'string',
-            description: '文件访问路径，例如: output.csv'
+            description: 'workspace 文件路径，例如: output.csv'
           },
-          description: '文件访问路径，例如: ["output.csv", "output.txt"]'
+          description: 'workspace 文件路径，例如: ["output.csv", "output.txt"]'
         }
       },
       required: ['paths']

packages/global/openapi/core/ai/sandbox/api.ts

@@ -131,12 +131,21 @@ export type SandboxGetTicketResponse = z.infer<typeof SandboxGetTicketResponseSc
  */
 export const SandboxGetHtmlPreviewLinkBodyRawSchema = createOutLinkChatTargetInputSchema({
   ...SandboxBaseShape,
-  filePath: z.string().describe('当前 Chat Session 下的 HTML 文件路径')
+  filePath: z.string().meta({
+    example: 'dist/index.html',
+    description: '当前 Chat Session 下的 HTML 文件路径'
+  })
 });
 export const SandboxGetHtmlPreviewLinkBodySchema = withSandboxTarget({
-  filePath: z.string().describe('当前 Chat Session 下的 HTML 文件路径')
+  filePath: z.string().meta({
+    example: 'dist/index.html',
+    description: '当前 Chat Session 下的 HTML 文件路径'
+  })
+});
+export const SandboxGetHtmlPreviewLinkResponseSchema = z.string().url().meta({
+  example: 'https://agent-proxy.example.com/preview/token/dist/index.html',
+  description: '由 agent-proxy 直接读取 sandbox workspace 的短期 HTML 预览链接'
 });
-export const SandboxGetHtmlPreviewLinkResponseSchema = z.string().describe('HTML 预览链接');
 export type SandboxGetHtmlPreviewLinkBody = z.input<typeof SandboxGetHtmlPreviewLinkBodySchema>;
 export type SandboxGetHtmlPreviewLinkRuntimeBody = z.output<
   typeof SandboxGetHtmlPreviewLinkBodySchema

packages/global/openapi/core/ai/sandbox/index.ts

@@ -70,7 +70,8 @@ export const SandboxPath: OpenAPIPath = {
   '/core/ai/sandbox/getHtmlPreviewLink': {
     post: {
       summary: '获取 HTML 文件预览链接',
-      description: '返回用于在浏览器中预览 HTML 文件的链接（S3 托管）',
+      description:
+        '校验文件后签发短期只读链接，由 agent-proxy 直接转发 sandbox workspace 内容，不复制到对象存储',
       tags: [DevApiTagsMap.sandbox],
       requestBody: {
         content: {