atomcode: Instructions file for Codex

项目全局开发约束

适用范围与使用方式

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

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

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

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

当前架构事实

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

CLI / TUI / daemon / background / ACP 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 是唯一 session 存储（SessionMeta 索引、PresentationFile 等旁挂）；会话内容是 kernel session 词汇的事件日志，SessionSnapshot 只是它的投影读法（见下一条与 0024）；core session 模块与持久化 API 已退役。历史 core JSON 只允许由 daemon 私有 DTO 单向导入，禁止恢复 legacy writer、core 磁盘投影或双向持久化转换。
• atomcode-core crate 已从 workspace 删除；生产代码不得重新依赖或重建同名兼容层。历史 core JSON 只由 daemon 私有 DTO 单向导入。
• coding 的装配只有一套：parts::prepare 建能力图，runtime::mount 挂成 plexus 行清单（on_harness + host_rows）。手写的 kernel 中间件/钩子链(parts::assemble / build_coding_agent)与 ATOMCODE_ENGINE 开关已删除，不得重建第二套装配或引擎选择开关。链式当年的事件流录在 crates/atomcode-coding/tests/golden/differential/，差分台对着它回归；那些 golden 不可重录（录它的引擎已经没了），要改就改文件本身并在 commit 里说明理由。
• coding runtime 里会话的唯一权威是 harness 事件日志（docs/adr/0024-the-session-log-is-the-authority.md）：SessionManager 存事件格式会话——<id>.events（头一行 + 每条事实 {seq, at, event}，流式片段不落盘）与 <id>.index（元数据，提交点），旁挂 .ui / .rewind / .rewind.txn / .todos；文件名一律避开已发布版本扫描的后缀，回滚不会读到半个会话。日志由 coding 的 session-store 行（coding/src/session_store.rs，host 把它 swap 进 session-persistence-jsonl 的位置，排在建 agent 的行之前）在 runtime 持有的租约下逐条同步追加，第一次写失败即停（上报 uncertain commit，runtime fail-close），之后一条都不再写；session-native 的 resume 就是重放这份日志，不得回退到快照或任何别的来源。撤销 / rewind / 恢复是追加事实（Rewound，目标不是已有前缀时整段撤回再提交目标对话，SessionManager::append_conversation_change），不重写日志；唯一的例外是重建失败时回滚自己刚追加、尚无 agent 读过的那段（truncate_events）。已发布版本存成快照的会话在打开时读时转换一次（open_for_resume / open_as_events），旧文件加 .migrated 挪开、不删。SnapshotHook / TranscriptHook 对事件会话只写索引与旁挂，不写快照与 transcript。harness 自己的 JSONL 行在本产品里关闭；sessions/harness/ 下的旧 journal 不读。
  • 读者：recall / /worklog 用 events::turn_records 从日志折出每回合记录（撤回的回合标 undone），网页历史读日志里的回合时间，Claude Code hooks 的 transcript_path 指向 <id>.events；TranscriptHook 已删。daemon 的无状态撤销与压缩也是追加事实（plan_conversation_change），每回合统计按 visible_turns 取舍。人取消时半截回复是 PartialReply 事实。索引记 format_version，比本构建新的会话在目录里标 needs_newer_version、拒绝 resume；读到不认识的事件种类同样按「更新的版本」拒读。
  • 团队成员与 task 子 agent 的会话同样落盘：各是一个事件会话，存成 storage_id（<lead>/<name> 的 / 换成 ~），索引记 parent，所以目录 / picker / --continue / recall 都不列、单独打开被拒、删 lead 时连带删；session-store 在 agent 创建时给它取一份自己的租约、移除时放掉，取不到就不让它运行。成员的创建参数在日志头 member 里，stop 等成员空闲后提交 Stopped 再移除；resume lead 时 team 行按 children(lead) 把没有 Stopped 的成员带回（角色按当前定义重算）。判据：harness/tests/team.rs 的 a_resumed_lead_brings_back_the_members_it_did_not_stop 等、coding/tests/runtime_criteria.rs::a_team_is_kept_and_comes_back_with_its_lead、capabilities 的 a_delegated_session_is_kept_under_its_parent。
• describe_self 告诉模型的每一句都由实现那件事的行（或读 patch/flag 的启动器）经 self_knowledge::describes / describes_live 登记，self_knowledge 自己不假定挂了哪些行、不替任何领域开专用注册表。替换掉一行（swap/disable）就要接过它该说的话：session-native 描述原生会话、skills-host/mcp-host 描述 SKILLS/MCP、model 行描述 /model 都是这么来的。工具自己的 description() 每次请求都会发给模型，不要再为工具往 describe_self 里写第二份；describe_self 只补工具描述覆盖不到的：会话、人如何添加/配置能力、前端命令、配置文件（身份已在系统提示里由 persona 行说，不重复）。config.toml 的说明写在读它的代码旁边（coding/src/config.rs::describe_config_file，由 config-file 行登记；可安全编辑的设置目录由 atomcode_config::settings::describe_catalog 渲染）。判据在 harness/tests/self_knowledge.rs 与 coding/tests/runtime_criteria.rs 的 the_agent_is_told_where_its_session_really_is、a_capability_the_runtime_mounts_itself_still_describes_itself、a_runtime_configured_from_a_file_describes_the_file。
• 凭据（API key、token）绝不进入行配置：配置树是可打印的数据（dump_runtime 原样渲染每行 config），也绝不进入 describe_self 的任何回答。需要凭据的行由宿主注册一个持有凭据的插件实例并 swap 过去（tool-web-keyed 是范例）。判据 coding/tests/mount_wiring.rs::a_configured_credential_never_enters_the_config_tree。
• 产品目录是宿主交进来的数据：库（kernel/capabilities/coding/harness 行/review/auth/codingplan/tui）不写 .atomcode 字面量、不读 ATOMCODE_HOME，只收 atomcode_capabilities::ProductDirs（或从它取出的目录）；harness 行经 product-dirs 缝取（atomcode_harness::product_dirs(ctx)）。解析环境只在宿主：atomcode_coding::config::product_dirs_from_env()。名字只在 atomcode-config/src/distribution.rs 写一次，gates/product-dir.sh 基线为 0。判据 coding/tests/runtime_criteria.rs::a_runtime_under_another_name_keeps_to_its_own_dirs。
• daemon/TUI 的 live/provider/UI 投影必须直接使用 kernel/coding 中立类型；持久化读取必须先得到严格 native 聚合。不得借转换层恢复旧 engine 命令、第二 runtime owner、core session 磁盘模型或静默 fallback。