XiuChengWu
8faa02c3d5
- New plugins_upper/ai_common/ static library: shared PluginConfig, ToolCallAccum, StreamContext, secure_zero, extract_host_port, serialize_tool_calls, free_chat_result - Refactored openai/anthropic plugins to use dstalk_ai:: namespace from ai_common - Fixed anthropic g_config raw pointer → std::atomic (data race) - Added SSE parse error counter with threshold abort (kMaxSseParseErrors=5) - Fixed missing closing brace in both plugins' error-body catch block - Updated test targets: ai_common include path + link, using namespace dstalk_ai - plugin_loader_test: added stub_unreg + service_registry.cpp for unregister_service - Includes pre-existing uncommitted changes from prior waves Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
139 lines
5.3 KiB
Markdown
139 lines
5.3 KiB
Markdown
# dstalk 编码规范和命名规范
|
||
|
||
## 一、编程语言
|
||
|
||
- 核心库和插件：C11 / C++20
|
||
- 插件边界：纯 C ABI（`extern "C"`），禁止跨 DLL 传递 C++ 对象
|
||
- 构建系统：CMake 3.21+，Ninja 生成器
|
||
|
||
## 二、注释规范
|
||
|
||
### 2.1 文件头注释（必须）
|
||
|
||
每个源文件（`.cpp` / `.hpp` / `.h`）开头必须有文件头注释，格式如下：
|
||
|
||
```cpp
|
||
/*
|
||
* @file 文件名.cpp
|
||
* @brief 英文简述。
|
||
* 中文简述。
|
||
* @version 0.1.1
|
||
* @date 2026-06-01
|
||
* Copyright (c) 2026 dstalk contributors. GPLv3.
|
||
*
|
||
* @changelog
|
||
* - 2026-06-01 v0.1.1: 修复线程安全问题 / Fix thread-safety issue
|
||
* - 2026-05-31 v0.1.0: 初始版本 / Initial version
|
||
*/
|
||
```
|
||
|
||
**规则说明**：
|
||
|
||
- `@version`: 当前文件版本号，必须与 `@changelog` 最新条目一致
|
||
- `@date`: 最后修改日期，与 `@version` 同步更新
|
||
- `@changelog`: **每次修改代码时，必须在最上方新增一行**，格式为 `- 日期 版本: 中文说明 / English description`
|
||
- 最新变更始终在第一行，方便快速查看文件当前版本和最近改动
|
||
- 仅记录功能性变更（bug修复、新功能、重构等），纯注释或格式调整不需要记录
|
||
- 版本号递增规则：修订号用于 bugfix，次版本号用于新功能，主版本号用于不兼容变更
|
||
|
||
### 2.2 函数注释（必须）
|
||
|
||
每个函数/方法定义上方必须有中英双语注释，格式：
|
||
|
||
```cpp
|
||
// 从 TOML 文件加载键值对 / Load key-value pairs from a TOML file
|
||
int ConfigStore::load_file(const char* path)
|
||
```
|
||
|
||
### 2.3 行内注释
|
||
|
||
- 复杂逻辑分块必须有中英双语注释
|
||
- 格式：`// 中文说明 / English description`
|
||
- 简单代码不需要注释
|
||
|
||
### 2.4 段落注释
|
||
|
||
代码段落分隔使用：
|
||
|
||
```cpp
|
||
// === 中文标题 / English Title ===
|
||
```
|
||
|
||
### 2.5 版本变更
|
||
|
||
文件头的 `@brief` 行简述当前功能即可，详细变更历史通过 git log 追溯，不在文件内维护 changelog。
|
||
|
||
## 三、命名规范
|
||
|
||
### 3.1 文件和目录
|
||
|
||
| 类型 | 规则 | 示例 |
|
||
|------|------|------|
|
||
| 目录名 | 小写英文 + 数字 + 下划线/连字符，字母或下划线开头 | `dstalk_core`、`file_io`、`plugins` |
|
||
| 源文件 | 小写英文 + 下划线，字母开头 | `config_store.cpp`、`openai_plugin.cpp` |
|
||
| 头文件 | 同源文件规则 | `dstalk_host.h`、`event_bus.hpp` |
|
||
| 测试文件 | `<模块名>_test.cpp` | `event_bus_test.cpp`、`openai_plugin_test.cpp` |
|
||
|
||
### 3.2 C 层（公共 API，跨 DLL）
|
||
|
||
| 类型 | 规则 | 示例 |
|
||
|------|------|------|
|
||
| 函数 | `dstalk_` 前缀 + snake_case | `dstalk_init()`、`dstalk_service_query()` |
|
||
| 类型 | `dstalk_` 前缀 + snake_case + `_t` 后缀 | `dstalk_message_t`、`dstalk_ai_service_t` |
|
||
| 宏 | `DSTALK_` 前缀 + UPPER_SNAKE_CASE | `DSTALK_API`、`DSTALK_API_VERSION` |
|
||
| 枚举值 | `DSTALK_` 前缀 + UPPER_SNAKE_CASE | `DSTALK_LOG_ERROR`、`DSTALK_EVENT_MESSAGE` |
|
||
| 回调类型 | `dstalk_` 前缀 + snake_case + `_fn` / `_cb` 后缀 | `dstalk_stream_cb`、`dstalk_tool_handler_fn` |
|
||
|
||
### 3.3 C++ 层（内部实现）
|
||
|
||
| 类型 | 规则 | 示例 |
|
||
|------|------|------|
|
||
| 命名空间 | 小写单词 | `dstalk` |
|
||
| 类名 | PascalCase | `ConfigStore`、`EventBus`、`PluginLoader` |
|
||
| 成员变量 | snake_case + `_` 后缀 | `mutex_`、`data_`、`next_id_` |
|
||
| 局部变量 | snake_case | `history_count`、`plugin_dir` |
|
||
| 全局变量 | `g_` 前缀 + snake_case | `g_ai`、`g_session`、`g_quit_requested` |
|
||
| 常量 | `k` 前缀 + PascalCase | `kWebUiHtml` |
|
||
|
||
### 3.4 插件命名
|
||
|
||
| 类型 | 规则 | 示例 |
|
||
|------|------|------|
|
||
| 插件目录 | 功能名，小写 + 下划线 | `plugins_upper/openai/`、`plugins_base/file_io/` |
|
||
| 插件源文件 | `<功能名>_plugin.cpp` | `openai_plugin.cpp`、`session_plugin.cpp` |
|
||
| CMake 目标 | `plugin_<功能名>` | `plugin_openai`、`plugin_network` |
|
||
| 服务注册名 | 小写 + 下划线 | `"ai_openai"`、`"http"`、`"session"` |
|
||
| 插件入口函数 | 固定为 `dstalk_plugin_init` | — |
|
||
|
||
### 3.5 禁止项
|
||
|
||
- 禁止纯数字命名（如 `123.cpp`）
|
||
- 禁止中文或特殊字符出现在文件名、变量名中
|
||
- 禁止在 C ABI 函数中抛出 C++ 异常（必须 try/catch 包裹）
|
||
- 禁止跨 DLL 边界传递 `std::string` 或其他 C++ 类型
|
||
|
||
## 四、代码组织
|
||
|
||
### 4.1 目录 README
|
||
|
||
- `dstalk/`（根目录）和所有二级目录（`dstalk_core/`、`dstalk_cli/`、`plugins_base/`、`plugins_middle/`、`plugins_upper/` 等）必须有 `README.md`
|
||
- 三级目录（如 `plugins_upper/openai/`）如内容简单可暂不添加
|
||
|
||
### 4.2 include 路径
|
||
|
||
- 公共头文件放在 `dstalk_core/include/dstalk/` 下
|
||
- 私有实现头文件放在 `dstalk_core/src/` 下
|
||
- 插件不得被 core 反向依赖（core 禁止 `#include` 插件目录下的文件）
|
||
|
||
### 4.3 内存管理
|
||
|
||
- 跨 DLL 的内存分配必须通过 `host->alloc` / `host->free` / `host->strdup`
|
||
- 禁止在一个 DLL 中 `malloc`，在另一个 DLL 中 `free`
|
||
- `dstalk_chat_result_t` 中的字符串字段由 `dstalk_strdup` 分配，调用方通过 `free_result()` 释放
|
||
|
||
## 五、构建规范
|
||
|
||
- 所有目标输出到 `${CMAKE_BINARY_DIR}/bin`（可执行文件）或 `${CMAKE_BINARY_DIR}/plugins`（插件 DLL）
|
||
- 新前端通过 `option(DSTALK_BUILD_XXX)` 控制，默认 OFF
|
||
- 插件在 `plugins_base/CMakeLists.txt`、`plugins_middle/CMakeLists.txt`、`plugins_upper/CMakeLists.txt` 中按依赖顺序 `add_subdirectory`
|