Magent 前端边界

Magent 只支持一个用户前端： agent-shell 。它通过进程内 ACP adapter 连接 Magent runtime。面向用户的文档和示例必须使用 magent-agent-shell.el 导出的命令，或者直接使用 agent-shell。

支持状态

magent-ui.el 和 magent-ui-legacy.el 中的代码目前不支持用于用户交互。不要把这些文件中的命令、快捷键、customization options 或 extension points 当作公共接口。它们只作为内部兼容代码和未完成的 legacy code 暂时保留，后续可能变更或移除，不提供兼容性保证。

当前源码树中的 legacy 实现名为 magent-ui-legacy.el 。如果其他 checkout 中存在 magent-legacy-ui.el 或匹配 magent-legacy-*.el 的 legacy UI 文件，或者清理期间引入了这些文件，它们同样属于不支持使用的范围。

受支持的模块

magent-agent-shell.el 注册 Magent agent-shell 配置，并提供受支持的交互入口。
magent-acp.el 实现进程内 ACP request、notification、response、permission 和 session/update adapter。
magent-runtime-api.el 是 frontend-neutral runtime/session API。
magent-runtime-queue.el 负责全局单执行队列和 session-scoped cancellation。

受支持的流程

使用 M-x magent-agent-shell-dwim 启动或复用 Magent；也可以先调用 magent-agent-shell-ensure-config 注册配置，再从 M-x agent-shell 中选择 Magent。
agent-shell 调用 magent-acp.el 中的进程内 ACP client。
ACP 分别规范化 text 和 resource blocks，把结构化 blocks 存入 turn metadata，再提交到 magent-runtime-api.el 。本地 file:// resource 还会提供 scoped request path；history 重建时 resource body 始终保持 user-role context。
runtime queue 每次只启动一个 active turn，创建带 :ui-visibility 'none 的 magent-request-context ，并调用 magent-agent-run-turn 。
agent loop 发出 Magent-native observer events； magent-acp.el 将其转换成发给 agent-shell 的 ACP session/update 消息。
ACP prompt request 会保持 pending，直到对应 Magent turn completed、failed 或 cancelled。

配置

magent-agent-shell-session-strategy 用于选择受支持前端的 new、latest 或 prompt session 流程。

开发边界

Core runtime behavior 不能依赖任何不受支持的 legacy UI workflow。Frontend-neutral 行为放在 magent-runtime-api.el ，ACP conversion 放在 magent-acp.el ，受支持的 frontend 行为放在 magent-agent-shell.el 。不要向 magent-ui.el 、 magent-ui-legacy.el 、 magent-legacy-ui.el 或 magent-legacy-*.el 增加新的用户入口。

当前限制

受支持的 frontend 硬依赖 agent-shell 和 acp 。
runtime execution 使用全局单执行队列。
cancellation 是 session-scoped：取消一个 ACP session 会取消该 session 的 active 和 queued submissions，但不会移除其他 session 的 queued work。
受支持的 frontend 已支持 per-request instruction skill overrides 和 skill commands；目前不暴露 per-request agent overrides。
ACP session config 暴露 Automatic capabilities ；关闭后，该 session 后续 turn 不再自动解析 contextual capabilities，但显式选择的 instruction skills 仍然生效。