代码规范¶
整个套件共享一小组贯穿所有产品仓库的约定。本页是简洁的上层摘要——权威细节 以各仓库为准，见各产品的作业规则与它们自己的贡献者文档。
开发者文档
请把本页当作方向指引，而非规则手册。以下每条约定的约束性版本都由仓库定义。 请从 NereidAI 组织 进入。
语言与注释¶
- 注释仅用英文。 源码中的中文注释不被允许。
- 每个文件都有模块/包级注释，说明其职责、架构角色与重要不变量。
- 文档注释以标识符名开头。 每个导出的函数、方法、类型、接口与常量都带有以 它所注释的标识符开头的文档注释；非平凡的未导出代码同样要有注释。
- 注释解释为什么——意图、不变量、顺序、绕行方案——而不是复述代码本身。
许可证头¶
每个手写源文件（Go、Python、TS/TSX、SQL、项目自撰的 YAML、proto、shell）都以 项目头开头，使用该语言的注释语法：
// Copyright (C) 2026 YIQISOFT
// SPDX-License-Identifier: Apache-2.0
生成文件仅当生成器掌控头部时才豁免；vendored / 第三方子树保留上游头并遵循上游 约定。
改动准则¶
最简单的完整方案最优，任何改动的优先级顺序是 删除 > 替换 > 新增：
- 在行为的拥有者处解决问题，而不是去守卫症状。
- 新增任何东西前先搜索仓库；复用或扩展已有实现。
- 保持范围最小——不做投机性开关、兼容垫片或顺带清理。
- 每个事实（默认值、标签、镜像标签）只有一个权威定义，并在同一改动内对齐每一份 副本。
API 与数据约定¶
| 约定 | 规则 |
|---|---|
| API 规范 | 公共 API 用 OpenAPI 3.1 描述；规范与代码在同一改动内更新，且必须能解析。 |
| 空数组 | 数组一律输出为 []，绝不为 null。客户端可依赖该结构。 |
| 不臆造语义 | 平台从不猜测含义——例如单位只来自用户自定义的描述符。 |
| 中立契约 | 线契约与平台 API 保持协议、技术栈与厂商中立。 |
| 迁移 | 模式变更以显式、编号、可逆（成对的 up/down）迁移交付——绝不在启动时自动改表。 |
国际化¶
- 没有硬编码的面向用户字符串。 每个标签与消息都经过项目的翻译机制
（
t(...)）。 - 两种语言同步改动。 新键在同一改动内进入英文与中文本地化文件，并同时运行 项目的 i18n 检查。
- 面向操作者的行为在同一改动内于两种语言的帮助文档中都有记录。
语言与技术栈（已确认）¶
当某条约定与语言相关时，它遵循产品自己的技术栈：
- Go 服务使用标准库
net/http（Sphere）以及pgx访问 PostgreSQL （Link）。 - Python 服务使用 FastAPI（Forge）。
以上仅为方向性说明；各仓库自行记录其确切使用的库、版本与工具链。