架构概览
ACECode 由共享智能体核心和多个使用入口组成。理解状态归属，有助于把修改放在正确模块。
入口与核心职责
| 模块 | 当前源码位置 | 职责 |
|---|---|---|
| 终端 TUI | src/main.cpp、src/tui/ | 终端输入、渲染、交互确认和本地会话。 |
| 无界面 CLI | src/headless/ | 参数、单轮执行、输出与退出状态。 |
| 后台 | src/daemon/ | 进程生命周期、会话托管与运行身份。 |
| HTTP / WebSocket | src/web/ | 路由、请求解析、响应与事件传输。 |
| Web 前端 | web/src/ | 任务界面、设置、消息与面板状态。 |
| 桌面壳 | src/desktop/ | 原生 WebView、后台托管和平台桥接。 |
| 智能体循环 | src/agent_loop.cpp | 模型请求、工具回合、进度与终态。 |
| 共享能力 | src/session/、src/provider/、src/tool/ | 会话持久化、模型适配和工具执行。 |
TUI 可以直接使用共享核心；桌面与 Web 通过后台管理会话。桌面原生浏览器和文件窗口通过桥接接入，不意味着所有浏览器客户端都具备同样能力。
DV-01
图片占位ACECode 运行架构图此处补充实际界面截图
一次任务如何流转
- 入口接收用户输入与上下文，并定位目标会话和工作目录。
- 保存用户消息，按当前模型绑定构造请求。
- Provider 将统一消息转换为对应服务协议，并返回文本、推理或工具调用。
- 工具经过权限与运行条件检查后执行，结果追加到会话。
- 智能体根据结果继续下一次模型调用，或生成最终回复。
- 终态、用量与消息通过事件更新前端，持久记录用于后续恢复。
用户界面中的“排队成功”只是输入被接受，任务完成还需要观察对应回合的终态。模型重试和上下文压缩也会产生状态变化，不能把每一次 busy 变化都视为成功完成。
修改时保持的边界
可复用的解析、校验和状态机放在对应共享模块，不把终端渲染对象带入后台接口。HTTP 处理应复用路由解析与错误响应辅助函数，模型变更应经过当前会话模型绑定路径。
Web 源码在 web/src，构建结果由工具生成。后台会话状态与前端临时草稿分开维护；文件修改又有独立的磁盘副作用，不能只更新界面就视作状态持久化。
新增行为需要检查 TUI、CLI、Web 和桌面是否使用了不同入口。协议变化同步维护 API 说明，关键持久字段补兼容性验证。