文档规范

本仓库文档描述当前分支中的真实实现。截至 2026-07-18，当前文档基线为 0.5.0。

文档类型与组织

主要文档类型

1. API 参考（api.md）：说明公开接口规格与可观察行为
2. 教程（tutorial.md）：提供面向使用者的示例和选择建议
3. 设计文档（design.md）：说明能力边界、职责与实现取舍

README.md 是当前基线文档，负责说明当前版本、包定位、入口和阅读路径。 CHANGELOG.md 负责维护历史版本时间线和较旧的发布说明。

组织原则

• 按真实包边界或能力边界组织子系统文档。
• 明确区分 api.md、tutorial.md 与 design.md 的用途。
• 只记录当前分支已经存在的 API 和行为。
• en_US、zh_CN、ja_JP 三种语言保持相同的 Markdown 文件集合。
• 除非代码事实要求不同结构，否则三种语言应保持一级、二级小节顺序一致。
• 以英文文档作为结构基准，再把相同事实自然地本地化为中文和日文。
• README.md 只聚焦当前基线，较旧版本摘要移入 CHANGELOG.md。

写作要求

• 不翻译标识符、类型名、trait 名、包名、路径、命令和版本号。
• 明确区分 API 保证、实现策略与已知限制。
• 如果某项能力只是接口边界，而内置实例没有实现全部可能语义，必须明确写出。
• 使用简短、直接的技术表述，避免宣传式发布文案。
• MoonBit 示例统一使用 Luna Flow 别名：Luna-Flow/luna-generic 使用 @lf_alg， Luna-Flow/arithmetic 使用 @lf_arith。
• 中文应使用自然的书面技术表达，日文应使用自然的技术文体，避免逐词硬译。