fix(builder): honor workspace filesystem mode configuration

[BobSong-dev]

Fixes #1723

背景

builder.workspace-store.fs-spec 已经在 README 里写了很久，但 Builder 启动时实际上没有读取这个配置，文件系统类型仍然是根据内部逻辑固定选择的。

这个 PR 把这个配置接到了 Builder 的启动流程里。

改动

现在可以通过 builder.workspace-store.fs-spec 显式指定：

• local：使用本地文件系统；
• sandbox：使用 Docker Sandbox 文件系统；
• remote：使用远端文件系统。

为了不影响已有部署，默认值使用 auto：

• 当前使用本地 AgentStateStore 时，自动选择 local；
• 使用分布式 AgentStateStore 时，自动选择 remote。

另外补齐了 sandbox 相关的 Spring 配置，并在配置组合不合法时尽早给出错误提示，比如本地 StateStore 强制使用 remote 的情况。

README、默认配置和相关注释也一起更新了，避免后续文档和实际行为再次不一致。

测试

我在本地跑了一遍测试已经通过：

mvn -pl "agentscope-examples/agents/agentscope-builder" -am "-Dtest=BuilderConfigFilesystemModeTest" "-Dsurefire.failIfNoSpecifiedTests=false" test

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

This PR fixes issue #1723 by wiring the documented builder.workspace-store.fs-spec property into the Builder startup path so the workspace filesystem backend (local / sandbox / remote) is selected explicitly or via an auto topology-based default.

Changes:

• Add filesystem-mode resolution (auto|local|sandbox|remote) and apply it when configuring all agents during BuilderBootstrap initialization.
• Introduce optional Spring wiring for a Docker-based SandboxFilesystemSpec behind builder.sandbox.enabled=true.
• Update defaults/docs (application.yml, README, README_zh) and add targeted unit tests for mode resolution + wiring.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
agentscope-examples/agents/agentscope-builder/src/main/java/io/agentscope/builder/web/config/BuilderConfig.java	Reads builder.workspace-store.fs-spec, resolves effective mode, and configures per-agent filesystem accordingly.
agentscope-examples/agents/agentscope-builder/src/main/java/io/agentscope/builder/web/config/BuilderSandboxConfig.java	Adds conditional Spring config to provide a SandboxFilesystemSpec (Docker) when sandbox is enabled.
agentscope-examples/agents/agentscope-builder/src/test/java/io/agentscope/builder/web/config/BuilderConfigFilesystemModeTest.java	Adds tests for mode parsing/resolution and filesystem spec configuration.
agentscope-examples/agents/agentscope-builder/src/main/resources/application.yml	Documents and defaults workspace-store.fs-spec and introduces sandbox config defaults.
agentscope-examples/agents/agentscope-builder/src/main/java/io/agentscope/builder/web/workspace/BuilderWorkspaceConfig.java	Updates documentation to reflect the new filesystem selection mechanism.
agentscope-examples/agents/agentscope-builder/src/main/java/io/agentscope/builder/web/audit/AgentActivityStore.java	Clarifies activity log behavior across remote vs local/sandbox modes.
agentscope-examples/agents/agentscope-builder/README.md	Documents auto mode and updates environment variable defaults/values.
agentscope-examples/agents/agentscope-builder/README_zh.md	Mirrors README updates for auto mode and config/env var docs in Chinese.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[AgentScopeJavaBot]

🤖 AI Review

This PR resolves Issue #1723 by wiring the builder.workspace-store.fs-spec configuration into the Builder's startup flow. A new FilesystemMode enum with a resolveFilesystemMode() method cleanly maps auto/local/sandbox/remote strings to type-safe mode selection, with auto preserving the existing auto-detection behavior. The new BuilderSandboxConfig class properly extracts sandbox configuration, and the BuilderConfigFilesystemModeTest provides good branch coverage (7 test cases). The README and application.yml updates are consistent. Overall this is a well-structured change with clear design. A few recommended improvements are noted below for defensive programming and user experience.

[AgentScopeJavaBot]

[minor] In the REMOTE branch of configureFilesystem(), baseStore is passed directly to new RemoteFilesystemSpec(baseStore) without a null check. While baseStore() bean is always created currently (via @ConditionalOnMissingBean), a future change adding conditional annotations could cause an NPE in REMOTE mode. Consider adding a defensive null check:

case REMOTE -> {
    if (baseStore == null) {
        throw new IllegalStateException(
            "REMOTE mode requires a BaseStore bean...");
    }
    builder.filesystem(new RemoteFilesystemSpec(baseStore)...);
}

[AgentScopeJavaBot]

[minor] When a user sets fs-spec=sandbox but forgets sandbox.enabled=true, BuilderSandboxConfig won't activate and builderBootstrap will throw. A better UX would be to auto-activate when fs-spec=sandbox is set. Consider changing the condition to:

@ConditionalOnExpression(
    "'${builder.sandbox.enabled:false}' == 'true' or "
    + "'${builder.workspace-store.fs-spec:auto}' == 'sandbox'")

[AgentScopeJavaBot]

[minor] The method validates REMOTE + localStateStore → throws, but does not warn for LOCAL + distributedStateStore. In multi-pod deployments, state is distributed while workspace is local, which could cause file inconsistency. Consider adding a WARN log:

if (mode == FilesystemMode.LOCAL && !isLocalStateStore(stateStore)) {
    log.warn("fs-spec=local with distributed AgentStateStore ({}); "
        + "workspace files will NOT be shared across pods.",
        stateStore.getClass().getSimpleName());
}

[AgentScopeJavaBot]

[nitpick] There are two nearly-duplicate comments above and inside the workspace-store block. Consider removing the redundant inner comment and keeping only the detailed outer one.

[AgentScopeJavaBot]

[nitpick] The README says "Builder supports three explicit filesystem modes" but there are actually four values: auto, local, sandbox, remote. Consider updating to "four filesystem modes" or "three explicit modes plus auto-detection".