atomcode AGENTS.md

项目全局开发约束

适用范围与使用方式

本文件记录当前架构边界和长期开发约束，不再承担历史迁移进度报告的职责。历史方案、旧基线和已完成的 bridge 退役过程应留在 docs/，不得继续作为当前实现前提。

涉及以下范围时，设计或修改前必须先核对当前代码、调用方和近期 Git 历史：

• crates/atomcode-kernel/；
• crates/atomcode-capabilities/；
• crates/atomcode-coding/ 的 runtime、provider、session、controller；
• CLI、TUI、daemon、ACP、clix 的 runtime、session、command/event 接入；
• daemon 中保留的历史 core JSON 单向 importer 与兼容 DTO；
• 公共协议、持久化格式、审批、安全边界或跨 crate 依赖方向。

本文件描述的是约束，不是永远正确的现状快照。若约束中的事实与当前代码冲突，以当前代码为准；先说明差异，再修正文档或实现，不得按旧路径盲目补代码。

当前架构事实

当前 coding agent 的目标调用链是：

CLI / TUI / daemon / background / ACP / clix code
                    │
                    ▼
       CodingRuntimeHandle / DriverCommand
                    │
                    ▼
               CodingRuntime
                    │
                    ▼
          atomcode-kernel Agent

• CodingRuntime 是 coding agent 的运行时所有者；driver 不应重新持有或重建第二套 live agent 生命周期。
• kernel AgentCommand/AgentEvent 是运行时执行边界。coding 产品 driver 应使用 CodingRuntime；其他业务 driver 可以驱动其 L2 已装配的 kernel agent，但不得另建第二生命周期 owner，也不得把 provider、session、cd、goal、loop 等 coding 生命周期重新塞进 kernel 命令。
• core legacy AgentClient/AgentCommand/AgentEvent、v1 engine 和 atomcode-bridge 已退役。不得重新引入 bridge、双 endpoint、v1/v2 选择开关或 core driver fallback。
• atomcode-kernel、atomcode-capabilities、atomcode-coding 的生产依赖必须保持 core-free；尤其禁止 capabilities 反向依赖 core、L2 或前端。
• native SessionManager/SessionMeta/SessionSnapshot/PresentationFile 是唯一 session 持久化模型；core session 模块与持久化 API 已退役。历史 core JSON 只允许由 daemon 私有 DTO 单向导入，禁止恢复 legacy writer、core 磁盘投影或双向持久化转换。
• atomcode-core crate 已从 workspace 删除；生产代码不得重新依赖或重建同名兼容层。历史 core JSON 只由 daemon 私有 DTO 单向导入。
• daemon/TUI 的 live/provider/UI 投影必须直接使用 kernel/coding 中立类型；持久化读取必须先得到严格 native 聚合。不得借转换层恢复旧 engine 命令、第二 runtime owner、core session 磁盘模型或静默 fallback。

架构方向

• 目标是单一状态所有权、清晰依赖方向和可验证兼容性；已经删除的 core 不得以 facade、兼容 crate 或复制状态所有者的方式回流。
• driver 负责输入、展示、传输和明确的本地操作；coding runtime 负责业务生命周期；kernel 只负责中立 agent 循环；capabilities 提供可复用能力实现。
• 不需要运行中 conversation/provider/session 的本地查询或副作用，应留在 driver/local service。需要操作运行中状态的行为必须通过 runtime 定义清楚的命令、事件和终态。
• 新能力优先放入职责正确的现有层。不得把业务语义下沉到 kernel，也不得为了去 core 新建一个无边界的“杂物 crate”。
• 不预设必须先创建 atomcode-protocol。只有出现稳定跨进程 schema、非 Rust codegen 或独立版本契约的真实需求时，才拆纯协议叶子；否则复用现有 kernel/coding 中立类型。
• 不预设创建大而全的 atomcode-foundation。config、auth、plugin、session、transport、process utilities 应按内聚职责复用现有 crate 或独立拆分，避免产生新的 core。
• 版本号、发布配置和版本策略不属于默认架构收口范围；除非任务明确要求，不得顺带修改。
• 问题修复必须检查同一状态所有权、协议边界和受影响 driver，优先修复共同根因；不得只修点名入口而让其他入口继续使用错误路径。