# Tianole Agent Guide 这个文件是仓库内 agent 文档的入口。 ## 文档位置 - 正式设计、路线图、架构说明放在 `docs/` - 面向 agent 的任务、会话记录、检查单放在 `docs/agents/` - Linux 顶层目录映射见 `docs/agents/linux-layout.md` ## 工作规则 - agent 修改代码前，先确认相关正式文档是否已经存在。 - agent 修改代码后，如果改动影响了架构边界、目录结构、构建方式、阶段计划或操作流程，必须同步更新 `docs/` 或 `docs/agents/`。 - 纯粹的小修复如果不改变这些信息，可以不额外补文档。 ## 推荐同步范围 - 结构变化：更新 `docs/roadmap.md` - agent 协作约定变化：更新 `docs/agents/README.md` - 阶段性实现记录：在 `docs/agents/` 下新增对应笔记 ## 当前约定 - 详细代码风格和文件组织规则见 `docs/agents/code-style.md`。 - 当前代码以“先做最小，但不把架构完全写死”为原则推进。 - `arch/` 放架构相关实现。 - `mm/` 放架构无关内存管理实现，和 Linux 一样作为顶层核心子系统维护。 - `include/tianole/` 放尽量与具体架构无关的共享接口。 - 入口文件只负责串联启动流程，不承载文件加载、ELF 解析、内存映射统计等功能细节。 - 检查式日志应该放在对应功能模块中，避免把 `kernel_main()` 变成临时测试脚本。 - 内部 C API 不加 `tianole_` 前缀；这是单一内核代码库，不把项目名重复进函数名和类型名。 - 架构目录内部不重复架构名前缀；跨通用层暴露的架构入口使用 `arch_` 前缀。 - 避免 `temp` / `tmp` 这类临时语义进入函数名、类型名和长期变量名；一次性局部变量可以用具体含义命名。 - C 代码风格参考 Linux：tabs 缩进，函数左花括号另起一行，`if/for/while` 左花括号留在行尾。 - 公共头文件使用 `<...>` include，例如 ``；同目录私有头文件使用 `"..."` include，例如 `"file.h"`。 - 不使用 `../foo.h` 这类相对 include；如果一个头需要跨目录使用，应先确认它是否应该成为公共接口。 - 长文件不是问题，职责混乱才是问题；一个文件可以较长，但必须代表一个清晰子系统、算法或驱动边界。 - 不为了降低行数拆出 `utils.c`、`helpers.c` 这类无边界文件；按职责、生命周期和调用边界拆分。 - 注释优先解释硬件约束、ABI 决策、内存所有权、并发语义和不明显的不变量；避免重复描述简单代码正在做什么。 - 文本文件使用 LF 行尾。 - `.clang-format` 是当前格式化约定；如果环境有 `clang-format`，新增或大改 C/H 文件后应按它格式化。 - 根 `Makefile` 只做总控和通用规则；架构配置放在 `arch//Makefile`，目录自己的源文件列表放在对应目录的 `Makefile` 中。 - 本地维护入口是 `scripts/check.sh`；具体检查放在 `scripts/checks/`，公共脚本函数放在 `scripts/lib/`。 - GitHub Actions 应调用 `scripts/check.sh`，避免 CI 逻辑和本地逻辑分叉。