仓库约定

这些规则是 Luna-Flow 文档标准在 linear-algebra 中的补充。手册描述当前分支中的真实实现；当前文档基线为 0.5.0。

页面与章节

• 概览说明当前的版本基线：该版本包含什么、从哪里开始阅读，以及各个包的定位。CHANGELOG.md 负责承载历史版本时间线和较旧的发布说明。
• 每个包在每一章各有一个页面，以其路径命名：api/immut.md 一并记录 Matrix、Vector 和 MatrixFn，api/container/adapters.md 记录 src/container/adapters。
• 内部包与工具包（internal、consistency、perf、perf_runner、perf_support）的页面较短，着重说明其职责与不变量。
• 可运行示例以 moonbit check 围起，并作为 src/doc_en_us 的测试编译，该包链接了每个页面。示例中的顶层名称在整个手册中必须唯一；请以页面名作前缀（例如 mut_tut_）。
• integration/ 章节说明外部类型如何接入 algebra 与 container 能力层。
• API 文档偏规格说明，tutorial 偏使用路径，design 偏职责边界与取舍，不要把三类文体混写
• 后端包装包需要说明平台约束、转换边界，以及相关行为是在本地实现还是委托给外部库内核
• 尽量使用短句、直述句，避免口语化、宣传式或版本说明式表达

mutable 与 immutable 的统一规范

API 对齐原则

• mutable 与 immutable 应尽可能提供相同的公开 API
• 当两个包都支持同一能力时，优先保持一致的函数名、参数顺序、返回语义与错误约定
• 如果因为实现约束无法完全一致，文档必须明确说明差异、原因以及推荐使用场景
• 新增公开接口时，默认同时评估是否应在两个包中都提供

immutable 包的设计原则

• 优先采用函数式、声明式、可组合的接口设计
• 优先返回新值，而不是暴露原地修改语义
• 避免让调用者感知隐藏状态、共享可变状态或时序敏感行为
• 文档应强调值语义、引用透明性与组合方式
• 如果存在性能上的妥协，仍应优先保持外部语义清晰、稳定、易推理

mutable 包的设计原则

• 优先关注性能、内存复用与底层执行效率
• 允许在库内部使用可变状态、原地更新和其他必要副作用
• 这些副作用应尽可能封装在实现内部，不应扩散到调用者的心智模型中
• 对外 API 仍应保持纯净、稳定、函数式风格，避免把内部可变实现直接暴露为接口约束
• 只有在性能收益明确且必要时，才引入与 immutable 不一致的特殊接口

文档写作要求

• 在 mutable 与 immutable 的 API 文档中，优先使用相同的小节结构与术语
• 对应接口应互相链接或交叉引用，方便读者比较两个包的语义与成本
• 文档需要明确区分“外部语义”与“内部实现策略”
• 缓存、复用、原地计算等性能细节应写入设计页面或 performance/ 章节，而不是写进 API 语义契约。
• 当某个 mutable 接口为了性能采取特殊行为时，必须明确写出其可观察影响，而不是只描述内部实现细节

翻译

• 中文译文应当是自然的书面技术汉语，避免逐词硬翻和不必要的中英夹杂。
• 日文译文应当是自然的技术文体，不应照搬中文或英文句式。