refactor20260927(P2-05): 完成 config 与 utils 的职责拆分

.git-blame-ignore-revs

@@ -6,6 +6,11 @@
 5524a35241ba67ba061aa1a279fd943213601a2f
 7a90db6d94bf70e4e200cb39c0122bdb1fc7fa66
 
+# P2-05 纯搬迁与 include 规范化(2026-09-27 / 28)
+c33325c2047f7dee74e02a53cb1b1c30e6bd9b62
+3d4ab59cfbd57bd6bfbd4141a13c6a16e5f8d500
+124f5e1c942ddc5399b9f7ed56aab75ed55876af
+
 # P2-02 / P2-03 / P2-04 已合入本分支的纯搬迁与 include 改写
 4009835e29da6c901a0c4ea1ef13a6e99479bbf5
 bd8ac3ebd916eafbce1040cea39ff9d966bb3493

AGENT.md

@@ -157,7 +157,7 @@ On Linux desktop builds, install the WebKitGTK development package before config
 
 `src/lsp/` is a process-local LSP client pool. Queries and post-edit diagnostics must use the session cwd from `ToolContext`, not the daemon process cwd, and must `weakly_canonical` paths before workspace-boundary or slot-key compares. Servers are detected from PATH / the project; ACECode never downloads language servers.
 
-Permission modes live in `src/permissions.hpp`: `Default` (prompt writes/exec), `AcceptEdits` (auto-allow file writes, still prompt shell), `Yolo` (auto-allow tools), and `Plan` (explore / write only the active plan file). Memory writes stay path-locked even under broader modes. Non-loopback `--dangerous` is rejected.
+Permission modes live in `src/permissions/permissions.hpp`: `Default` (prompt writes/exec), `AcceptEdits` (auto-allow file writes, still prompt shell), `Yolo` (auto-allow tools), and `Plan` (explore / write only the active plan file). Memory writes stay path-locked even under broader modes. Non-loopback `--dangerous` is rejected.
 
 Other shared subsystems that are easy to miss: `src/gitinfo/` (prompt + REST git snapshots), `src/hooks/` (Codex-compatible lifecycle hooks), `src/pty/` (console dock, formerly the `web/pty/` subdirectory; `/api/pty` and `/ws/pty` are loopback-only), `src/loop/` (scheduled loop tasks), `src/experts/`, and `src/remote_control/`.
 

ARCHITECTURE.md

@@ -125,7 +125,7 @@ flowchart TB
 | [src/agent_loop.cpp](src/agent_loop.cpp) and [src/agent_loop.hpp](src/agent_loop.hpp) | Multi-turn agent state machine, streaming callbacks, tool-call loop, cancellation, max-iteration handling, and completion semantics. |
 | [src/provider/](src/provider) | `LlmProvider` implementations, provider factory/swap logic, Copilot auth integration, OpenAI-compatible streaming, model profiles, and context-window resolution. |
 | [src/tool/](src/tool) | Tool registry, built-in tools, tool result metadata, summaries, MCP bridge, skills tools, memory tools, and optional web-search tool. |
-| [src/permissions.hpp](src/permissions.hpp) | Permission modes and glob-style tool/path allow rules. |
+| [src/permissions/permissions.hpp](src/permissions/permissions.hpp) | Permission modes and glob-style tool/path allow rules. |
 | [src/session/](src/session) | Session JSONL persistence, metadata sidecars, replay, resume restore, rewind checkpoints, daemon session registry, and event dispatch. |
 | [src/commands/](src/commands) | Slash command registry and built-in command implementations. |
 | [src/config/](src/config) | Config load/save/validation, saved model profiles, and default schema behavior. |
@@ -198,7 +198,7 @@ Context-window resolution uses saved profile data, bundled models.dev metadata,
 
 `ToolExecutor` owns the authoritative tool registry. Built-ins include shell execution, file read/write/edit, grep, glob, task completion, structured user questions, skills, memory, optional web search, and MCP-provided tools.
 
-Permission behavior is centralized in [src/permissions.hpp](src/permissions.hpp):
+Permission behavior is centralized in [src/permissions/permissions.hpp](src/permissions/permissions.hpp):
 
 - `Default`: auto-allow read-only tools, prompt for writes and exec.
 - `AcceptEdits`: auto-allow file writes/edits, still prompt for shell commands.

CLAUDE.md

@@ -10,11 +10,13 @@ The Superpowers plugin is disabled for this repository. Do not invoke or follow
 
 ## Current Runtime Surfaces
 
+P2-05 状态存储边界:`utils/state_file` 仅管理通用 JSON 读写、跨进程文件锁与原子更新;模型探测缓存属于 `provider/model_probe_cache`,搜索地区缓存属于 `tool/web_search/region_cache`,桌面活跃 / 首页工作区记录属于 `desktop/workspace_state`,TUI 命令用量属于 `tui/slash_command_usage`。各模块复用同步事务,保留 `state.json` 字段与原有失败返回语义。
+
 ACECode ships one main executable with terminal TUI and daemon subcommands, plus an optional desktop shell target.
 
 - TUI mode starts from [main.cpp](main.cpp), configures provider/tools/commands, runs the FTXUI loop, and posts worker callbacks back into the UI event queue.
 - Daemon mode starts from [src/daemon/cli.cpp](src/daemon/cli.cpp), converges on `worker.cpp::run_worker`, writes runtime files, then serves [src/web/](src/web) routes and WebSocket events.
-- Headless print mode (`acecode -p "<prompt>"`, openspec add-headless-print-mode) starts from `main.cpp::dispatch_non_tui_command` → [src/headless/headless_runner.cpp](src/headless/headless_runner.cpp) — worker.cpp bootstrap 的精简复刻(无 run/ 文件、无心跳、无 Crow),会话走 SessionRegistry 正常落盘可 resume。进程级标记 `headless::active()`(src/headless/headless_mode) 有两个消费点:AgentLoop 权限门(默认自动拒绝并给模型解释文案,`--yolo` 全放行且不弹权限确认)与 AskUserQuestion(自动应答,优先于 goal unattended 分支);spawn_subagent 子会话同进程自动继承。stdout 只出最终 assistant 文本;退出码 0/1/64/130。Windows 下 -p 分支经 `CommandLineToArgvW` 重建 UTF-8 argv。**连续对话**(每轮新进程、磁盘续接,对齐 claude -p 家族一):`-c/--continue` 接当前 cwd 最近普通会话(跳过 subagent 子会话);`--resume <id>` 接指定会话 —— print 模式下 id 必填(裸 `--resume` 会把位置参数 prompt 吞成 id,与 TUI 语义刻意不同),显式给出的 `--model`/`--permission-mode` 覆盖会话保存值(`SessionRegistry::resume` 透传 + `make_entry_locked` 显式优先,web resume 不传这两个字段不受影响);`--session-id <id>` 自定新会话 id(`SessionOptions::preset_session_id`,字符集 `[A-Za-z0-9-_]{1,64}` 防路径穿越,撞已有 id 报错提示改用 --resume);`--output-format json` 成败都输出单个 `{"type":"result","session_id",...}` 对象供脚本链式调用。帮助:顶层 `acecode --help`(main.cpp `print_top_level_help`)+ `acecode -p --help`(`headless_options.cpp::print_mode_help`)。
+- Headless print mode (`acecode -p "<prompt>"`, openspec add-headless-print-mode) starts from `main.cpp::dispatch_non_tui_command` → [src/headless/headless_runner.cpp](src/headless/headless_runner.cpp) — worker.cpp bootstrap 的精简复刻(无 run/ 文件、无心跳、无 Crow),会话走 SessionRegistry 正常落盘可 resume。进程级标记 `headless::active()`(src/permissions/interaction_mode.hpp) 有两个消费点:AgentLoop 权限门(默认自动拒绝并给模型解释文案,`--yolo` 全放行且不弹权限确认)与 AskUserQuestion(自动应答,优先于 goal unattended 分支);spawn_subagent 子会话同进程自动继承。stdout 只出最终 assistant 文本;退出码 0/1/64/130。Windows 下 -p 分支经 `CommandLineToArgvW` 重建 UTF-8 argv。**连续对话**(每轮新进程、磁盘续接,对齐 claude -p 家族一):`-c/--continue` 接当前 cwd 最近普通会话(跳过 subagent 子会话);`--resume <id>` 接指定会话 —— print 模式下 id 必填(裸 `--resume` 会把位置参数 prompt 吞成 id,与 TUI 语义刻意不同),显式给出的 `--model`/`--permission-mode` 覆盖会话保存值(`SessionRegistry::resume` 透传 + `make_entry_locked` 显式优先,web resume 不传这两个字段不受影响);`--session-id <id>` 自定新会话 id(`SessionOptions::preset_session_id`,字符集 `[A-Za-z0-9-_]{1,64}` 防路径穿越,撞已有 id 报错提示改用 --resume);`--output-format json` 成败都输出单个 `{"type":"result","session_id",...}` 对象供脚本链式调用。帮助:顶层 `acecode --help`(main.cpp `print_top_level_help`)+ `acecode -p --help`(`headless_options.cpp::print_mode_help`)。
 - Headless capability policy (`openspec add-headless-tool-selection`, `add-headless-capability-discovery`):`-p` 新会话未传模型时走默认模型(resume 未传时沿用会话模型)、未传权限时固定 `default`、未传 `--max-turns` 时强制无限(不继承全局 cap)。工具面默认保留当前配置下实际注册的系统工具,Skill/MCP 均为空;`--disable-tools` 精确移除系统工具,`--enable-skills` 写入 runtime-only `SkillsConfig::allowed` 并只在非空时注册 `skills_list/skill_view`,`--enable-mcp` 先过滤本地 `mcp_servers` 副本再启动 runtime。三个参数都支持重复/逗号/等号形式,未知或全局 disabled 名称在 provider 前 exit 64。`--list-tools` 复用默认 headless 工具注册链并列出真正可被 `--disable-tools` 接受的 Builtin 名,`--list-skills` 列当前 cwd 真正可被 `--enable-skills` 接受的 Skill 名与描述,`--list-mcp` 列配置中未 disabled 的 MCP server 名；三者可组合且无需 prompt,发现分支在 stdin、startup hooks、model/session/LSP/MCP runtime 之前退出,不执行工具,与任何执行参数混用时报 usage error。SessionRegistry per-entry skill registry、skill tools、slash expansion 与 spawn_subagent 都复用本次过滤后的 config/executor；allowlist 不落盘。
 - Web UI code lives in [web/src/](web/src), builds with React 18, Vite, Tailwind v4, `markdown-it`, `highlight.js`, and `diff2html`, then gets embedded from `web/dist/` by CMake.
 - Desktop mode is opt-in through `-DACECODE_BUILD_DESKTOP=ON`; [src/desktop/](src/desktop) manages workspace registry, daemon pool, webview host, tray, notifications, and bridge calls.
@@ -271,7 +273,7 @@ worktree 落在**主仓根**的 `.acecode/worktrees/<slug>`,分支 `worktree-<fl
 
 CLI `--worktree [name]` / `-w`(TUI):启动即建 worktree,name 可为 PR 引用(`#123` / GitHub PR URL → fetch `pull/N/head`,slug=`pr-N`);此时 worktree 就是项目根(日志/workspace/会话存储都在里面),与工具中途进入的 throwaway 语义不同。TUI 退出时:无变更静默删除,有变更(或数不清)保留并提示,`--resume` 恢复进去。新建 worktree 的后处理:`core.hooksPath` 指回主仓(.husky 优先)、`config.worktree.symlink_directories` symlink、`.worktreeinclude`(gitignore 语法)声明的 gitignored 文件拷贝(`ls-files --directory` 折叠目录 + 按需展开,防大仓库全量遍历)。`config.worktree.sparse_paths` 走 sparse-checkout cone 模式。**未复刻**(有意偏离):tmux 集成(POSIX-only)、WorktreeCreate/Remove hook 替换 VCS、交互式退出对话框(现为"有变更即保留"的安全默认)。spawn_subagent 也不复刻 Claude Code 的 `isolation: worktree`(子代理各建 worktree),子会话**共享父会话的 worktree 并继承写边界**,见下段。测试:[tests/worktree/](tests/worktree/)(core 纯逻辑 + 真实 git 集成 + 工具端到端)。
 
-**写边界与子代理继承(fix-subagent-write-boundary)。** 起因是一次线上排障:同事的 LOOP 在 worktree 里派了 5 个子代理,IM 模块那个把改动写进了主 checkout。根因有三条,都是"隔离只罩住一个会话对象、不随会话树传递":(1) `spawn_subagent` 只把 `ctx.cwd`(worktree 路径)当普通 cwd 交给子会话,`loop_execution` / WorktreeSessionInfo 都不传,子会话的系统提示说自己 "Session worktree: inactive";(2) `is_cwd_validation_exempt` 让 Yolo 会话跳过全部路径校验,只有 LOOP 主会话被补回一道 `PathValidator(cwd_)` 边界,子会话继承了 Yolo 却不是 LOOP 会话,两头都不沾;(3) 项目指令加载器从 worktree 一路向上走到 HOME,把主 checkout 的 AGENTS.md 再加载一遍并带上绝对路径 Source 头,等于把主仓路径喂给模型。现在:`AgentLoop::write_root()`(会话 worktree > LOOP 策略 > 继承的 `inherited_write_root_`)非空即有写边界,Yolo 不再免除,只有 dangerous 整体放行;文件工具报 `Write boundary blocked`,bash 走 `agent_loop_shell_guard.hpp` 的可证明写目标守卫(Windows 上两侧先 weakly_canonical,junction 形态不同不误拦)。`spawn_subagent` 让子会话共享父会话的 worktree(`SessionOptions::inherited_worktree`,meta `worktree_session.inherited=true`,`entry->cwd` 取 `original_cwd` 与父会话同 project dir,AgentLoop cwd 切进 worktree)、继承 LOOP 策略与 `ToolContext::write_root`;`EnterWorktree` / `ExitWorktree` 对继承者拒绝;`wait_subagent` 用 `AgentLoop::last_turn_failed()` 把夭折的子会话报成 ChildFailed 而不是 completed;指令加载器在 linked worktree 根(`.git` 指针含 `/.git/worktrees/`)止步。事后兜底:spawn 在父会话处于 worktree 时记主 checkout 的 `git status --porcelain` 快照,wait 结束比对并把 worktree 之外新出现的路径附进结果(`metadata.workspace_touched`);LOOP 调度器对建了 worktree 的 run 做同样的事,结果进 `loop_runs.workspace_touched`(schema v3),Web 循环页显示警告。**守卫不是沙箱**:`cd 主仓 && node fix.js` 这类动态写入只能靠事后检测发现;进程级沙箱落地后 bash 守卫可退役,但文件工具那道边界要留 —— 它们在 daemon 进程内执行,沙箱管不到(Codex 的 apply_patch 绕过 `--add-dir` 就是同一个洞)。回归测试见 [docs/subagents.md](docs/subagents.md) 的测试地图。
+**写边界与子代理继承(fix-subagent-write-boundary)。** 起因是一次线上排障:同事的 LOOP 在 worktree 里派了 5 个子代理,IM 模块那个把改动写进了主 checkout。根因有三条,都是"隔离只罩住一个会话对象、不随会话树传递":(1) `spawn_subagent` 只把 `ctx.cwd`(worktree 路径)当普通 cwd 交给子会话,`loop_execution` / WorktreeSessionInfo 都不传,子会话的系统提示说自己 "Session worktree: inactive";(2) `is_cwd_validation_exempt` 让 Yolo 会话跳过全部路径校验,只有 LOOP 主会话被补回一道 `PathValidator(cwd_)` 边界,子会话继承了 Yolo 却不是 LOOP 会话,两头都不沾;(3) 项目指令加载器从 worktree 一路向上走到 HOME,把主 checkout 的 AGENTS.md 再加载一遍并带上绝对路径 Source 头,等于把主仓路径喂给模型。现在:`AgentLoop::write_root()`(会话 worktree > LOOP 策略 > 继承的 `inherited_write_root_`)非空即有写边界,Yolo 不再免除,只有 dangerous 整体放行;文件工具报 `Write boundary blocked`,bash 走 `permissions/shell_write_guard.hpp` 的可证明写目标守卫(Windows 上两侧先 weakly_canonical,junction 形态不同不误拦)。`spawn_subagent` 让子会话共享父会话的 worktree(`SessionOptions::inherited_worktree`,meta `worktree_session.inherited=true`,`entry->cwd` 取 `original_cwd` 与父会话同 project dir,AgentLoop cwd 切进 worktree)、继承 LOOP 策略与 `ToolContext::write_root`;`EnterWorktree` / `ExitWorktree` 对继承者拒绝;`wait_subagent` 用 `AgentLoop::last_turn_failed()` 把夭折的子会话报成 ChildFailed 而不是 completed;指令加载器在 linked worktree 根(`.git` 指针含 `/.git/worktrees/`)止步。事后兜底:spawn 在父会话处于 worktree 时记主 checkout 的 `git status --porcelain` 快照,wait 结束比对并把 worktree 之外新出现的路径附进结果(`metadata.workspace_touched`);LOOP 调度器对建了 worktree 的 run 做同样的事,结果进 `loop_runs.workspace_touched`(schema v3),Web 循环页显示警告。**守卫不是沙箱**:`cd 主仓 && node fix.js` 这类动态写入只能靠事后检测发现;进程级沙箱落地后 bash 守卫可退役,但文件工具那道边界要留 —— 它们在 daemon 进程内执行,沙箱管不到(Codex 的 apply_patch 绕过 `--add-dir` 就是同一个洞)。回归测试见 [docs/subagents.md](docs/subagents.md) 的测试地图。
 
 ### 多文件夹项目(「编辑项目」,仿 Codex)
 

CMakeLists.txt

@@ -105,7 +105,7 @@
 set(ACECODE_WEB_DIST "${CMAKE_SOURCE_DIR}/web/dist")
 set(ACECODE_WEB_EMBED_DIR "${ACECODE_WEB_DIST}")
 if(NOT EXISTS "${ACECODE_WEB_DIST}")
     message(WARNING
         "[acecode] web/dist/ not found — embedding a minimal fallback page. "
         "Run `pnpm install && pnpm build` inside web/ before re-configuring for the full UI.")
     set(ACECODE_WEB_EMBED_DIR "${CMAKE_BINARY_DIR}/generated/web-dist-fallback")
@@ -182,7 +182,7 @@
     ${CMAKE_SOURCE_DIR}/src/markdown)
 set(ACECODE_TUI_TESTABLE_SUBSETS
     commands/ resume/ path_reference/ markdown/
-    drag_scroll.cpp text_input_ops.cpp skill_commands.cpp)
+    drag_scroll.cpp text_input_ops.cpp skill_commands.cpp slash_command_usage.cpp)
 set(ACECODE_TUI_SOURCES)
 foreach(_tui_dir IN LISTS ACECODE_TUI_DIRS)
     if(NOT IS_DIRECTORY "${_tui_dir}")
@@ -222,7 +222,7 @@
     ${CMAKE_SOURCE_DIR}/src/config/model_provider_registry.cpp
     ${CMAKE_SOURCE_DIR}/src/config/request_headers.cpp
     ${CMAKE_SOURCE_DIR}/src/config/saved_models.cpp
-    ${CMAKE_SOURCE_DIR}/src/provider/builtin_model_catalog.cpp
+    ${CMAKE_SOURCE_DIR}/src/config/builtin_model_catalog.cpp
     ${CMAKE_SOURCE_DIR}/src/platform/process/os_process_posix.cpp
     ${CMAKE_SOURCE_DIR}/src/platform/process/os_process_windows.cpp
     ${CMAKE_SOURCE_DIR}/src/ipc/runtime_files.cpp
@@ -245,12 +245,13 @@
     ${CMAKE_SOURCE_DIR}/src/platform/clipboard.cpp
     ${CMAKE_SOURCE_DIR}/src/utils/cwd_hash.cpp
     ${CMAKE_SOURCE_DIR}/src/utils/encoding.cpp
-    ${CMAKE_SOURCE_DIR}/src/utils/model_capabilities.cpp
+    ${CMAKE_SOURCE_DIR}/src/config/model_capabilities.cpp
     ${CMAKE_SOURCE_DIR}/src/utils/paths.cpp
     ${CMAKE_SOURCE_DIR}/src/utils/state_file.cpp
 )
 
 set(ACECODE_DESKTOP_SUPPORT_SOURCES
+    ${CMAKE_SOURCE_DIR}/src/desktop/workspace_state.cpp
     ${CMAKE_SOURCE_DIR}/src/desktop/application_icon.cpp
     ${CMAKE_SOURCE_DIR}/src/desktop/linux_webview_scale_policy.cpp
     ${CMAKE_SOURCE_DIR}/src/desktop/daemon_pool.cpp

docs/ai_sugesstion.md

@@ -59,7 +59,7 @@ ACECode 已经有不错的 agent 底座：C++17 共享 agent core、TUI/daemon/w
 适配代码方向：
 
 - `src/tool/`：新增 `code_mode` 工具和 broker。
-- `src/permissions.hpp`：增加 brokered call 的权限上下文。
+- `src/permissions/permissions.hpp`：增加 brokered call 的权限上下文。
 - `src/session/`：记录脚本、子调用、审批和最终结果，便于 replay。
 
 候选 OpenSpec：`sandboxed-code-mode-tools`
@@ -126,7 +126,7 @@ AI coding agent 的安全边界不应只停留在“读工具自动、写工具
 
 适配代码方向：
 
-- `src/permissions.hpp`：风险模型和 grant scope。
+- `src/permissions/permissions.hpp`：风险模型和 grant scope。
 - `src/tool/`：工具定义附带风险 metadata。
 - `web/src/components/PermissionModal.jsx`、TUI confirm：展示参数 diff 和风险解释。
 

docs/help-source/group3.py

@@ -23,7 +23,7 @@
         figure("MD-02", "ACEModel 的模型选择", "展示 ACEModel Provider 和三个内置 Model ID，以及保存后的预设。API Key 必须隐藏，避免截入账号信息。")),
     section("verify", "验证能力与连接状态",
         '''<p>检查已保存模型的视觉、工具等能力标识，然后用真实的小任务验证所需功能。</p><p>认证失败时检查密钥和实际地址；模型不存在时核对 Model ID；有回答但不能完成工具任务时检查工具能力与权限。排查步骤见<a href="troubleshoot-models.html">模型连接与认证问题</a>。</p>''')
-], ["src/provider/builtin_model_catalog.cpp", "src/config/saved_models.cpp", "web/src/components/model-settings/ModelProfileDialog.jsx", "web/src/components/model-settings/ProviderCatalogPicker.jsx"]),
+], ["src/config/builtin_model_catalog.cpp", "src/config/saved_models.cpp", "web/src/components/model-settings/ModelProfileDialog.jsx", "web/src/components/model-settings/ProviderCatalogPicker.jsx"]),
 
 "providers": page("按实际接口协议选择 Provider，再填写服务给出的连接信息。不同服务商的认证方式和可选参数分别配置。", [
     section("openai", "OpenAI 兼容接口",