Feat/local filesystem shared read prefixes

[CyberXavier]

Close #2244

期望行为

为 LocalFilesystemSpec 增加共享目录前缀配置，并与 Remote 模式保持一致的语义：

• 所有租户均可读取共享目录中的文件。
• 租户写入采用 Copy-on-Write，不修改共享源文件。
• 租户覆盖文件按照 IsolationScope 隔离。
• 支持配置多个共享目录。
• 拒绝路径穿越及无效目录前缀。
• 保留 Local 模式原有的 Shell 执行能力。
• 未配置共享目录时，完全保持原有 Local 文件系统行为。

验收标准

• Local 和 Remote 模式均支持相同的共享目录配置项。
• Local 模式能够读取工作区中的共享目录。
• 租户写入不会修改共享源文件。
• 不同用户的覆盖文件相互隔离。
• AGENT 和 GLOBAL 作用域不会直接写入共享源目录。
• 支持共享目录前缀规范化和去重。
• 拒绝 .. 等路径穿越配置。
• 保持共享目录的配置顺序。
• 返回的共享目录配置集合不可修改。
• 未配置共享目录时保持原有行为。
• Local 模式继续支持 Shell 执行。
• 相关 Harness 和 Builder 测试通过。

新特性已更新到agentscope-builder示例项目且说明已更新对应参考文档

[CLAassistant]

All committers have signed the CLA.

[CyberXavier]

@jujn 你好，这个CI失败看起来是JUnit清理测试上下文时的偶发问题，我在本地测试可以正常通过。我好像没有重新运行CI的权限，能否麻烦帮忙重跑一下，谢谢！

[codecov]

Codecov Report

❌ Patch coverage is 89.47368% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ess/agent/filesystem/spec/LocalFilesystemSpec.java	87.95%	4 Missing and 6 partials ⚠️

📢 Thoughts on this report? Let us know!

[CyberXavier]

@jujn 目前所有 CI 检查均已通过。麻烦您有空时帮忙审阅一下，非常感谢！🙏

[jujn]

@jujn 目前所有 CI 检查均已通过。麻烦您有空时帮忙审阅一下，非常感谢！🙏

最近任务比较多。可能会稍晚一些哈。

[AgentScopeJavaBot]

🤖 AI Review

This PR adds shared read prefix (shared directory) support to LocalFilesystemSpec, aligning it with the existing RemoteFilesystemSpec semantics. The implementation uses a CompositeFilesystem + OverlayFilesystem layered routing architecture: each shared prefix maps to a LocalRouteOverlay route (upper layer = tenant CoW overlay, lower layer = shared read-only source), with LocalCompositeFilesystem handling route dispatch while preserving shell execution. The BuilderBootstrap cross-cutting configuration propagation was also refactored (configureDynamicAgent) so dynamically created user-defined agents get consistent filesystem/middleware config. Addresses issue #2244 with a complete implementation of all expected behaviors.

Recommendation: COMMENT

[AgentScopeJavaBot]

🤖 AI Review

This PR adds shared read prefix (shared directory) support to LocalFilesystemSpec, aligning it with the existing RemoteFilesystemSpec semantics. The implementation uses a CompositeFilesystem + OverlayFilesystem layered routing architecture: each shared prefix maps to a LocalRouteOverlay route (upper layer = tenant CoW overlay, lower layer = shared read-only source), with LocalCompositeFilesystem handling route dispatch while preserving shell execution. The BuilderBootstrap cross-cutting configuration propagation was also refactored (configureDynamicAgent) so dynamically created user-defined agents get consistent filesystem/middleware config. Addresses issue #2244 with a complete implementation of all expected behaviors.

Recommendation: COMMENT

[CyberXavier]

已针对复杂逻辑补充设计注释：
在 LocalFilesystemSpec.localOverlayRoute、LocalRouteOverlay 及其构造器处，补充了共享路由的分层设计说明，明确 upper 层负责租户隔离的可写覆盖、lower 层提供非命名空间的共享只读基线，以及 Overlay 的 CoW 读写语义。
补充了 LocalRouteOverlay 对 ls、grep、glob 返回路径进行转换的原因，说明其用于避免暴露租户命名空间或重复拼接共享前缀。
在 configureDynamicAgent 的 Javadoc 和调用点补充了调用顺序说明：应在 Agent 专属字段和 Toolkit 配置之后、build() 之前执行，以保持动态 Agent 与启动阶段 Agent 相同的全局配置传播和覆盖语义。
本次仅补充 Javadoc/内联注释，没有修改执行逻辑。Spotless 检查及相关 14 个测试均已通过。