Skip to content

fix: scope local backend root '/' to workspace on Windows - #197

Merged
jubaoliang merged 1 commit into
TencentCloud:developfrom
Georgyhongbo:fix/windows-root-dir
Aug 9, 2026
Merged

fix: scope local backend root '/' to workspace on Windows#197
jubaoliang merged 1 commit into
TencentCloud:developfrom
Georgyhongbo:fix/windows-root-dir

Conversation

@Georgyhongbo

Copy link
Copy Markdown
Contributor

Summary

修复 Windows 上新建 agent 因 root_dir:"/"Path ... outside root directory 的问题。

背景 / 根因

屏幕截图 2026-08-07 140719 屏幕截图 2026-08-07 133221 屏幕截图 2026-08-07 135337

新建 agent 时,前端(dashboard/src/pages/Experts/components/agentBackendForm.ts)对本地后端默认写入 {"type":"local_shell","root_dir":"/","virtual_mode":true}。deepagents 的 FilesystemBackend/LocalShellBackendvirtual_mode 下把所有路径锚定在 root_dir,而 "/" 在 Windows 上会解析为当前进程所在盘的根目录(例如进程在 D 盘 → D:\)。agent 工作区通常位于另一盘符(C:\Users\<user>\.octop\agents\<id>),跨盘读取时 _resolve_path 会抛出 Path ... outside root directory

此问题仅影响 Windows(POSIX 下 / 就是真正的全盘根,工作区路径是其子路径,校验自然通过)。上游服务端 default_agent_backend_spec 在 Windows 上已把默认后端锚定到工作区,只是显式写入的 root_dir:"/" 绕过了该默认值。

改动

在服务端后端规格解析处做 Windows 归一化(服务端是唯一知道自己运行平台的位置;浏览器无法可靠探测服务器 OS,且前端修复会在 Linux 上造成全盘访问→工作区作用域的回归):

  • src/octop/infra/backend/resolver.py:新增 windows_neutralize_host_root(spec, *, workspace_dir)_is_host_root()。仅当 os.name == "nt" 且本地后端(local_shell / filesystem,或 composite 的 default)显式 root_dir/\"" 时,改写为 default_agent_backend_spec(workspace_dir)(工作区作用域)。
  • src/octop/infra/agents/manager.py_backend_spec_for_rowresolve_agent_backend_spec 之后接入归一化。

影响面

  • Linux / macOS 完全不受影响:os.name != "nt" 时函数原样返回 spec。
  • 显式盘符路径(如 D:\develop)、缺失 root_dir、composite 的 routes 子后端、以及 named/state/s3/postgres/cos 等非本地后端一律不动。
  • 技能包校验(_backend_supports_host_skill_packages / assert_backend_supports_skill_packages)把 / 根与工作区根视为等价可挂载宿主——与归一化前后 spec 的映射一致,校验与运行时不打架。

Target branch

  • Base is develop (feature / fix — default)
  • Base is main (release/* or hotfix/* only)

Type of change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation
  • Refactor / chore
  • Release / hotfix

Test plan

本地 Windows 环境(octop-venv,测试需 PYTHONPATH=src):

  • make all passes locally
  • Added/updated tests

验证明细:

  • 全量单测 PYTHONPATH=src python -m pytest tests/unit -q:1353 passed, 81 skipped。唯一失败 tests/unit/browser/test_browser_setup.py::test_ensure_profile_writable_recreates_when_not_writable 为 Windows 临时目录权限的既有环境问题,只依赖 octop.infra.browser.setup,与本次改动无代码路径交叉。
  • 受影响模块 pytest tests/unit/backend/test_resolver.py tests/unit/agents/test_agent_manager.py:61 passed, 2 skipped(新增 _is_host_root / windows_neutralize_host_root 8 个用例 + _backend_spec_for_row Windows 集成用例)。
  • ruff check 通过(含新增测试文件)。
  • mypy 无新增错误(4 个既有错误在 ssrf_guard.py:108/109、manager.py:1362,与本次无关)。

Checklist

  • Updated CHANGELOG.md (if user-facing)
  • README / docs updated (if needed)

@Georgyhongbo
Georgyhongbo force-pushed the fix/windows-root-dir branch from 4ff1782 to b13587b Compare August 8, 2026 09:31
@Georgyhongbo
Georgyhongbo changed the base branch from main to develop August 9, 2026 02:54
@jubaoliang
jubaoliang merged commit 68d17c5 into TencentCloud:develop Aug 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants