55 lines
4.4 KiB
Markdown
55 lines
4.4 KiB
Markdown
# 代码规范
|
||
# import 规范
|
||
在从外部库进行导入时候，请遵循以下顺序：
|
||
1. 对于标准库和第三方库的导入，请按照如下顺序：
|
||
- 需要使用`from ... import ...`语法的导入放在前面。
|
||
- 直接使用`import ...`语法的导入放在后面。
|
||
- 对于使用`from ... import ...`导入的多个项，请**在保证不会引起import错误的前提下**，按照**字母顺序**排列。
|
||
- 对于使用`import ...`导入的多个项，请**在保证不会引起import错误的前提下**，按照**字母顺序**排列。
|
||
2. 对于本地模块的导入，请按照如下顺序：
|
||
- 对于同一个文件夹下的模块导入，使用相对导入，排列顺序按照**不发生import错误的前提下**，随便排列。
|
||
- 对于不同文件夹下的模块导入，使用绝对导入。这些导入应该以`from src`开头，并且按照**不发生import错误的前提下**，尽量使得第二层的文件夹名称相同的导入放在一起；第二层文件夹名称排列随机。
|
||
3. 标准库和第三方库的导入应该放在本地模块导入的前面。
|
||
4. 各个导入块之间应该使用一个空行进行分隔。
|
||
5. 对于现有的代码，如果导入顺序不符合上述规范，在重构代码时应该调整导入顺序以符合规范。
|
||
|
||
## 注释规范
|
||
1. 尽量保持良好的注释
|
||
2. 如果原来的代码中有注释，则重构的时候，除非这部分代码被删除，否则相同功能的代码应该保留注释（可以对注释进行修改以保持准确性，但不应该删除注释）。
|
||
3. 如果原来的代码中没有注释，则重构的时候，如果某个功能块的代码较长或者逻辑较为复杂，则应该添加注释来解释这部分代码的功能和逻辑。
|
||
## 类型注解规范
|
||
1. 重构代码时，如果原来的代码中有类型注解，则相同功能的代码应该保留类型注解（可以对类型注解进行修改以保持准确性，但不应该删除类型注解）。
|
||
2. 重构代码时，如果原来的代码中没有类型注解，则重构的时候，如果某个函数的功能较为复杂或者参数较多，则应该添加类型注解来提高代码的可读性和可维护性。（对于简单的变量，可以不添加类型注解）
|
||
3. 对于参数化泛型，应该使用`typing`模块中的类型注解来指定参数化泛型的类型。
|
||
- 例如，使用`List[int]`来表示一个包含整数的列表，使用`Dict[str, Any]`来表示一个键为字符串，值为任意类型的字典。
|
||
## 变量规范
|
||
1. 当确定某个变量/实例是某种类型的时候（优先按照类型注解确定，除非你分析出类型注解是错误的），可以不必使用`or`进行fallback。
|
||
- 例如，`bot_nickname = (global_config.bot.nickname or "").strip()` 可以改为 `bot_nickname = global_config.bot.nickname.strip()`，前提是我们确定`global_config.bot.nickname`一定是一个字符串。
|
||
## 类属性使用规范
|
||
1. 应该尽量减少使用getattr和setattr方法，除非是在对一个动态类进行处理或者使用Monkeypatch完成Pytest
|
||
2. 在重构代码时，如果遇到getattr和setattr，应该尝试检查这个类实例是否有这个属性，如果有，则直接替换为类属性访问写法。
|
||
- 举例：`v = getattr(instance, "value", "")` 在检查到`instance`有`value`属性后应该改为`v = instance.value`
|
||
|
||
# 运行/调试/构建/测试/依赖
|
||
优先使用uv
|
||
依赖项以 pyproject.toml 为准
|
||
|
||
|
||
# 语言规范
|
||
项目的首选语言为简体中文，无论是注释语言，日志展示语言，还是 WebUI 展示语言都首要以简体中文为首要实现目标
|
||
|
||
# 配置文件修改
|
||
如果你需要改动配置文件，不需要修改实际的bot_config.toml或者model_config.toml，只需要修改配置文件模版，并新增一个版本号即可，也不必要为配置改动创建测试文件。
|
||
|
||
|
||
# 关于 A_memorix 修改
|
||
如果修改涉及 `src/A_memorix`，请先阅读 `src/A_memorix/MODIFICATION_POLICY.md`。
|
||
|
||
默认原则：
|
||
1. `src/A_memorix` 的实现层改动应优先遵守 `src/A_memorix/MODIFICATION_POLICY.md` 中的归属约束。
|
||
2. 不要提交无边界的 `ruff`、格式化、导入整理或大面积实现整理。
|
||
3. 本地实验目录或依赖其运行的测试，除非明确说明并确认，否则不要进入共享历史。
|
||
|
||
# maibot插件开发文档
|
||
https://github.com/Mai-with-u/maibot-plugin-sdk/blob/main/docs/guide.md
|