本文件是本仓库的 AI 协作规则。任何 AI 在本项目中进行改写、续写、重构、修复、补测试或补文档时，都应优先遵守本文件。
- 本仓库的目标是实现
NeoCode Coding Agent。 - 系统已完成控制面与数据面解耦，当前主链路必须始终围绕以下闭环保持可用：
用户输入(TUI) -> 网关中继(Gateway) -> Agent推理(Runtime) -> 调用工具(Tools) -> 结果回传 -> UI展示 - 做改动时，优先保证主链路可运行、模块边界清晰、实现可验证。
- 不要为了"可能兼容旧版本"破坏当前架构；若新设计已确定，优先直接切换到新实现。
- 不允许过度设计、过度包装。
- 强制编码准则 (防乱码)：所有文件的读取、修改、重写操作必须强制使用标准 UTF-8 (无 BOM) 编码。严禁使用破坏多字节字符的正则替换；严禁在输出中文注释时出现截断或混入 GBK 等其他编码。发现乱码先修编码再修逻辑。
- 不要跨层直连；新功能默认沿
TUI -> Gateway -> Runtime -> Provider / Tool Manager主链路设计。 - 不要把模型厂商差异泄漏到
runtime、tui或上层调用方。 - 不要在
runtime或tui里直接写工具执行逻辑；所有可被模型调用的能力必须进入internal/tools。 - 不要把会话状态、消息历史、工具调用记录散落到 UI；这些状态优先由
runtime管理。 - 不要把明文 API Key 写入 YAML、样例配置、测试快照或提交内容。
- 代码为准：当本文件（或任何文档）的描述与代码实现冲突时，以代码实现为准，并同步更新文档。
- 分层隔离：上层只依赖下层契约，不依赖下层实现细节。
tui不感知 provider 协议，runtime不感知具体模型厂商字段。 - 能力入口收敛：任何模型可调用的能力，必须经过
internal/tools的 schema + execute 协议，不允许在runtime或tui中内嵌工具逻辑。 - 状态集中：会话状态、消息历史、工具调用记录由
runtime/session统一管理，不分散到 UI 或其他消费层。 - 配置先行：环境差异项（超时、路径、模型名、输出限制）优先通过配置注入，不硬编码。
- 接口优于实现：核心抽象上的导出类型、函数、接口应补充清晰注释；优先面向接口编程，不暴露具体厂商结构。
app只负责装配与依赖注入，不承载业务规则。config负责配置模型、加载、校验与环境变量名管理。tui只消费事件并负责展示，不存业务状态，不直接调用 provider，不直接执行 tools。gateway负责协议路由与边界隔离，是 TUI 与 Runtime 的通信边界。runtime负责会话编排与推理循环，不直接执行工具，不内嵌 prompt 构建逻辑。provider负责厂商协议适配，请求组装与响应解析；厂商差异不泄漏到上层。context负责 prompt 构建与上下文裁剪，不处理超出其职责范围的运行时决策。session负责会话领域模型与持久化。tools负责可被模型调用的能力的 schema、校验与执行，是工具能力的唯一入口。
如需了解当前各模块的具体实现细节（如 budget 闭环、事件协议、compact 策略），参考 docs/ 目录下对应文档，而非本文件。
- TUI v1 (
internal/tui/) 冻结不改；TUI v2 的新实现统一放在internal/tuiv2/。 - TUI v2 使用独立二进制入口
cmd/neocode-tuiv2/main.go，不复用或改写 TUI v1 入口。 - TUI v2 禁止 import
internal/runtime、internal/session、internal/repository或任何 SQLite 相关包。 - TUI v2 不直接使用真实 Gateway 内部 server；真实通信能力必须通过客户端适配器收敛。
- Fake 实现模拟的是 Gateway 客户端接口，不是
FakeRuntime。 - UI 组件不直接写死假数据，所有数据流必须从 Gateway 客户端接口进入。
- 先定位改动所属模块，再检查是否会破坏职责边界。
- 优先做最小闭环改动，避免无关重构。
- 如果新增能力会被模型调用，先设计
tools抽象，再接入runtime。 - 如果改动涉及 provider 协议，差异收敛在
internal/provider内，不向外扩散特定厂商字段。 - 如果改动涉及配置，统一经由
ConfigManager或现有配置管理入口处理。 - 如果新增目录、命令、配置项或模块职责，必须同步更新
README.md、docs/或本文件。
- 测试文件命名为
*_test.go，测试函数命名为TestXxx。 - 所有改动必须以整体测试覆盖率 100% 为硬性目标；新增、修改或修复的逻辑必须同步补齐测试，覆盖正常路径、边界条件、异常分支、回归场景以及必要的跨模块交互，确保测试场景完整、结果可验证。
- 修改
runtime时，重点覆盖：停止条件、tool result 回灌、事件派发、token 累积与上下文管理。 - 修改
context时，重点覆盖：Build 输入输出契约、上下文裁剪策略、消息列表边界、外部规则文件加载。 - 修改
config时，重点覆盖：新增配置项的校验、默认值和序列化/反序列化、配置加载向后兼容、超时控制、错误包装、工作目录限制。 - 修改
provider时，重点覆盖：请求组装、tool call 解析、异常响应处理、认证或限流错误映射。 - 修改
tools时，重点覆盖：参数校验、权限、超时、输出裁剪和错误格式。
- 遵循 Go 惯用风格。
- 包名使用短小、全小写名词。
- 导出标识符使用
PascalCase，未导出使用camelCase。 - 使用制表符缩进，尽量将单行控制在约 120 字符内。
- 核心抽象上的导出类型、函数、接口应补充清晰注释，尤其是
provider、runtime、tools。 - 在非测试文件中新增函数时，必须紧邻函数定义补充便于解读的注释，注释内容使用中文并以 UTF-8 编码保存；注释应说明函数职责、关键行为或上下文，避免空泛的模板化表述。
- 避免硬编码路径、URL、模型名、超时、输出长度限制和环境差异项，优先通过配置、参数或具名常量注入。
- 避免硬编码业务语义字符串或状态值（例如消息角色、事件类型、协议字段值）；如需复用，优先收敛到共享常量、类型或统一定义处。
- 优先写清晰、可替换的实现，不要为了"未来可能需要"提前引入复杂泛化。
- 不要擅自删除、改写或遗漏原有注释；若注释需要调整，应在理解原意后做等价更新，而不是直接移除。
- 如果有需要，可以使用文档块注释，并使用
//或/* */。 - 如果文件内容疑似乱码或编码异常，先尝试用其他编码方式查看和确认原文，再决定是否修改；未确认前不要擅自删除或重写相关内容。
- 配置文件默认路径为
~/.neocode/config.yaml。 - 配置中只保存环境变量名，不保存明文 API Key。
selected_provider、current_model、workdir、shell必须在启动阶段完成校验，非法配置应尽早失败。filesystem工具默认限制在工作目录内，禁止越界访问。bash工具必须限制超时、输出长度，并避免交互式阻塞命令。webfetch工具必须限制协议范围和响应大小，防止拉取不受控内容。- 本地运行数据、会话数据和真实密钥不得默认入库；相关目录和配置文件应加入
.gitignore。
- 修改说明性文档时，沿用目标文档当前已有的主语言。
- 当前文档如果以中文为主，则继续使用中文；若以英文为主，则继续使用英文。
- 仅在代码标识符、命令、路径、协议名、库名等不可避免的场景下保留英文原词。
- 文档必须反映真实实现；如果实现和文档冲突，修代码或修文档时至少修正其中一个，不要放任失真。
- 本文件只描述持久规则与原则；当前具体实现（如 budget 闭环、事件协议、compact 策略）应在
docs/中维护，实现变化时同步更新对应文档。
- 确认改动没有破坏
TUI / Gateway / Runtime / Provider / Tools / Config的职责分工。 - 确认新增能力已经接到正确层级，而不是临时跨层实现。
- 运行必要的格式化和测试。
- 确认本次改动对应的测试已补齐，并满足整体测试覆盖率 100% 目标，不得遗漏关键路径、边界分支和回归场景。
- 检查
git status，确保没有无关文件、密钥、本地配置或临时数据混入。
- 启动应用：
go run ./cmd/neocode - 编译全部包：
go build ./... - 运行测试：
go test ./... - 格式化代码：
gofmt -w ./cmd ./internal
- 任何 AI 在此仓库中工作时，都应优先保持主链路可用、边界清晰、配置安全、测试可验证，而不是追求无关的大改或过度设计。