Skip to content

Commit d9bd0d0

Browse files
authored
docs(project): 新增项目本地化开发规范并优化文档格式 (#420)
- 为什么改:提升项目文档的可读性和开发团队的中文使用规范,确保项目文档质量标准化 - 改了什么: - 新增"本地化规范"章节,明确要求代码注释、测试用例描述、技术文档使用中文编写 - 在各章节间增加空行,优化文档排版和可读性 - 强调变量和函数名继续保持英文编程惯例 - 影响范围:仅影响CLAUDE.md项目文档,不涉及代码功能变更 - 验证方式:文档内容审查,确认新增的本地化规范说明清晰完整,无语法错误
1 parent 30123f7 commit d9bd0d0

File tree

1 file changed

+18
-1
lines changed

1 file changed

+18
-1
lines changed

CLAUDE.md

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
## 开发命令
66

77
### 构建和测试
8+
89
- `pnpm build` - 构建项目(包括 Web 构建和 TypeScript 编译)
910
- `pnpm dev` - 开发模式(带监视功能)
1011
- `pnpm test` - 运行一次测试
@@ -13,6 +14,7 @@
1314
- `pnpm test:silent` - 静默运行测试(用于 CI)
1415

1516
### 代码质量
17+
1618
- `pnpm lint` - 运行 Biome linter 并自动修复
1719
- `pnpm format` - 使用 Biome 格式化代码
1820
- `pnpm type:check` - 运行 TypeScript 类型检查
@@ -21,6 +23,7 @@
2123
- `pnpm check:all` - 运行所有质量检查(lint、typecheck、spellcheck、duplicate check)
2224

2325
### 其他质量工具
26+
2427
- `pnpm spell:check` - 使用 cspell 检查拼写
2528
- `pnpm duplicate:check` - 使用 jscpd 检查重复代码
2629
- `pnpm docs:dev` - 启动文档开发服务器
@@ -32,21 +35,25 @@
3235
### 核心组件
3336

3437
1. **CLI 层** (`src/cli/`) - 使用 Commander.js 的命令行界面
38+
3539
- 入口点:`src/cli/index.ts`
3640
- 依赖注入容器:`src/cli/Container.ts`
3741
- 命令注册和处理
3842

3943
2. **核心 MCP 层** (`src/core/`) - MCP 协议实现
44+
4045
- `UnifiedMCPServer.ts` - 主要 MCP 服务器实现
4146
- `ServerFactory.ts` - 用于创建不同服务器类型的工厂
4247
- `MCPMessageHandler.ts` - 消息处理和路由
4348

4449
3. **传输层** (`src/transports/`) - 通信适配器
50+
4551
- `WebSocketAdapter.ts` - WebSocket 通信
4652
- `HTTPAdapter.ts` - HTTP 通信
4753
- `StdioAdapter.ts` - 标准 I/O 通信
4854

4955
4. **服务层** (`src/services/`) - 连接和服务管理
56+
5057
- `IndependentXiaozhiConnectionManager.ts` - 独立多接入点连接管理器
5158
- `MCPServiceManager.ts` - MCP 服务管理器
5259
- `XiaozhiConnectionManagerSingleton.ts` - 全局单例管理器
@@ -75,6 +82,7 @@
7582
### 配置
7683

7784
主配置文件是 `xiaozhi.config.json`,支持:
85+
7886
- `mcpEndpoint` - 单个端点字符串或端点数组
7987
- `mcpServers` - MCP 服务器配置对象
8088
- `modelscope` - ModelScope API 配置
@@ -84,6 +92,7 @@
8492
### 入口点
8593

8694
项目构建三个主要入口点:
95+
8796
- `dist/cli.js` - CLI 工具(主入口点)
8897
- `dist/mcpServerProxy.js` - MCP 服务器代理,用于集成到其他客户端
8998
- `dist/WebServerStandalone.js` - 独立 Web 服务器
@@ -110,10 +119,18 @@
110119
- 2 空格缩进
111120
- 行结尾:LF
112121

122+
### 本地化规范
123+
124+
- **注释信息**:请使用中文编写所有代码注释
125+
- **测试用例描述**`describe``it` 函数的参数请使用中文描述
126+
- **文档和说明**:README、技术文档等说明性内容优先使用中文
127+
- **变量和函数名**:继续使用英文命名(符合编程惯例)
128+
- **目的**:有助于中国开发团队的持续维护和代码理解,降低沟通成本
129+
113130
### 重要说明
114131

115132
- 项目完全使用 ESM 模块
116133
- 配置了路径别名以实现更清晰的导入(`@cli/*` 等)
117134
- 外部依赖不打包(ws、express、commander 等)
118135
- 模板目录复制到 dist 用于项目脚手架
119-
- Web UI 在 `web/` 目录中单独构建
136+
- Web UI 在 `web/` 目录中单独构建

0 commit comments

Comments
 (0)