46 lines
3.1 KiB
Markdown
46 lines
3.1 KiB
Markdown
# 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，例如 `<tianole/boot_info.h>`；同目录私有头文件使用 `"..."` include，例如 `"file.h"`。
|
||
- 不使用 `../foo.h` 这类相对 include；如果一个头需要跨目录使用，应先确认它是否应该成为公共接口。
|
||
- 长文件不是问题，职责混乱才是问题；一个文件可以较长，但必须代表一个清晰子系统、算法或驱动边界。
|
||
- 不为了降低行数拆出 `utils.c`、`helpers.c` 这类无边界文件；按职责、生命周期和调用边界拆分。
|
||
- 注释优先解释硬件约束、ABI 决策、内存所有权、并发语义和不明显的不变量；避免重复描述简单代码正在做什么。
|
||
- 文本文件使用 LF 行尾。
|
||
- `.clang-format` 是当前格式化约定；如果环境有 `clang-format`，新增或大改 C/H 文件后应按它格式化。
|
||
- 根 `Makefile` 只做总控和通用规则；架构配置放在 `arch/<arch>/Makefile`，目录自己的源文件列表放在对应目录的 `Makefile` 中。
|
||
- 本地维护入口是 `scripts/check.sh`；具体检查放在 `scripts/checks/`，公共脚本函数放在 `scripts/lib/`。
|
||
- GitHub Actions 应调用 `scripts/check.sh`，避免 CI 逻辑和本地逻辑分叉。
|