# 开发指南

<cite>
**本文引用的文件**
- [CONTRIBUTING.md](file://CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](file://CODE_OF_CONDUCT.md)
- [Cargo.toml](file://Cargo.toml)
- [src/lib.rs](file://src/lib.rs)
- [src/main.rs](file://src/main.rs)
- [src/bin/native_linker_main.rs](file://src/bin/native_linker_main.rs)
- [loader/Cargo.toml](file://loader/Cargo.toml)
- [loader/src/main.rs](file://loader/src/main.rs)
- [runtime/Cargo.toml](file://runtime/Cargo.toml)
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
- [.github/workflows/ci.yml](file://.github/workflows/ci.yml)
- [.github/ISSUE_TEMPLATE/bug_report.md](file://.github/ISSUE_TEMPLATE/bug_report.md)
- [.github/ISSUE_TEMPLATE/feature_request.md](file://.github/ISSUE_TEMPLATE/feature_request.md)
- [.github/PULL_REQUEST_TEMPLATE/pull_request_template.md](file://.github/PULL_REQUEST_TEMPLATE/pull_request_template.md)
- [test_multi_entry/src/main.ts](file://test_multi_entry/src/main.ts)
</cite>

## 更新摘要
**所做更改**
- 新增详细的贡献者手册章节，包含完整的开发流程说明
- 增强贡献流程文档，涵盖代码规范、提交流程和问题报告
- 完善治理结构和行为准则说明
- 更新开发环境设置和测试指南
- 增加项目治理和联系方式说明

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [贡献者手册](#贡献者手册)
10. [开发流程](#开发流程)
11. [治理与行为准则](#治理与行为准则)
12. [结论](#结论)
13. [附录](#附录)

## 简介
本指南面向 ts-native 项目的开发者与贡献者，提供从环境搭建、构建与部署、调试与性能分析、测试与质量保障，到贡献流程与治理规范的完整开发手册。项目采用 Rust 生态，包含 TypeScript 编译器前端、中间表示与代码生成、Windows 平台上的运行时与加载器，以及可选的原生链接器。

## 项目结构
仓库采用多 crate 结构：
- 根 crate：提供 CLI 工具与库能力，包含 TypeScript 解析、中间表示、代码生成、COFF 输出、独立链接器等模块。
- loader crate：Windows 平台的运行时加载器，支持直接加载 COFF 或通过 DLL 编译后执行。
- runtime crate：以动态库形式提供的运行时插件，提供基础 JS 运行时函数与 Node.js 风格的文件系统等能力。

```mermaid
graph TB
subgraph "根项目"
CLI["CLI 工具<br/>ts-native / native-linker"]
LIB["库模块<br/>codegen/coff/project/*"]
SWC["SWC 变换层"]
end
subgraph "loader"
LDR_BIN["tsn-loader 可执行文件"]
LDR_LIB["运行时加载逻辑"]
end
subgraph "runtime"
RT_DLL["tsn_runtime 动态库"]
RT_IMPL["JS 运行时函数<br/>fs/json/dom 等占位实现"]
end
CLI --> LIB
LIB --> SWC
LDR_BIN --> LDR_LIB
LDR_LIB --> RT_DLL
RT_DLL --> RT_IMPL
```

**图表来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [loader/Cargo.toml:1-23](file://loader/Cargo.toml#L1-L23)
- [runtime/Cargo.toml:1-28](file://runtime/Cargo.toml#L1-L28)

**章节来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [loader/Cargo.toml:1-23](file://loader/Cargo.toml#L1-L23)
- [runtime/Cargo.toml:1-28](file://runtime/Cargo.toml#L1-L28)

## 核心组件
- CLI 工具与库
  - CLI：命令行工具，负责解析参数、调用 SWC 解析、生成 COFF 并输出。
  - 库：提供代码生成、COFF 处理、项目编译、独立链接器等模块。
- 运行时加载器（loader）
  - 支持两种模式：直接加载 COFF；通过 DLL 编译 TypeScript 后执行。
  - 提供插件加载、日志系统、阶段计时、内存分配与重定位应用。
- 运行时插件（runtime）
  - 提供基础 JS 类型系统（NaN-tagging）、数组/对象/字符串池、数学与字符串操作、JSON 简化实现、文件系统等占位函数。

**章节来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)
- [runtime/src/lib.rs:1-1532](file://runtime/src/lib.rs#L1-L1532)

## 架构总览
下图展示从用户输入到最终执行的关键路径：CLI 生成 COFF，或通过 DLL 编译后，loader 在 Windows 上加载并执行；运行时插件提供必要的运行时函数。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant CLI as "ts-native CLI"
participant DLL as "ts-native DLL"
participant LDR as "tsn-loader"
participant RT as "tsn_runtime 插件"
Dev->>CLI : "传入 TypeScript 源码"
CLI->>CLI : "SWC 解析/变换"
CLI->>CLI : "Cranelift 代码生成"
CLI-->>Dev : "输出 COFF(.obj)"
Dev->>LDR : "tsn-loader <file.ts>"
LDR->>DLL : "调用编译接口"
DLL-->>LDR : "返回编译结果/COFF"
LDR->>RT : "加载运行时插件"
LDR->>LDR : "分配可执行/数据内存"
LDR->>LDR : "应用重定位"
LDR-->>Dev : "执行入口并返回结果"
```

**图表来源**
- [src/main.rs:55-78](file://src/main.rs#L55-L78)
- [loader/src/main.rs:337-502](file://loader/src/main.rs#L337-L502)
- [runtime/src/lib.rs:135-200](file://runtime/src/lib.rs#L135-L200)

## 详细组件分析

### CLI 工具（ts-native）
- 功能要点
  - 参数解析：支持输入文件与输出目标，默认输出为同名 .obj。
  - 编译流程：调用 SWC 解析源码，生成中间表示，再由 CodeGen 生成 COFF。
  - 输出提示：打印生成的 COFF 路径，并给出使用 loader 执行的建议。
- 关键路径
  - 输入校验与默认输出推导。
  - 读取源码并解析。
  - 代码生成与二进制写盘。
- 注意事项
  - 若未指定输出扩展名，会自动补全 .obj。
  - 生成的 COFF 可直接交由 tsn-loader 执行。

```mermaid
flowchart TD
Start(["开始"]) --> ParseArgs["解析参数<br/>输入/输出"]
ParseArgs --> Validate{"输入有效？"}
Validate --> |否| ExitErr["退出并提示用法"]
Validate --> |是| ReadSrc["读取源码"]
ReadSrc --> ParseSWC["SWC 解析"]
ParseSWC --> GenCOFF["CodeGen 生成 COFF"]
GenCOFF --> WriteOut["写入 .obj 文件"]
WriteOut --> Done(["完成"])
ExitErr --> Done
```

**图表来源**
- [src/main.rs:10-78](file://src/main.rs#L10-L78)

**章节来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)

### 运行时加载器（tsn-loader）
- 功能要点
  - 模式选择：根据文件扩展名或显式参数决定编译模式。
  - 日志系统：基于 log + env_logger，支持多级别日志与时间戳。
  - 插件管理：动态加载 DLL 插件，缓存符号地址。
  - 内存与重定位：为代码与数据节区分配内存，应用 REL32/ADDR64 重定位。
  - 执行入口：定位 main 符号并调用。
- 关键路径
  - 参数解析与模式判定。
  - 编译或加载 COFF。
  - 分配内存、复制节区、应用重定位。
  - 调用入口并清理资源。
- 平台限制
  - 当前仅支持 Windows 平台。

```mermaid
sequenceDiagram
participant User as "用户"
participant Loader as "tsn-loader"
participant Compiler as "ts-native DLL"
participant Plugins as "插件集合"
participant ExecMem as "可执行内存"
User->>Loader : "启动并传入参数"
Loader->>Loader : "解析参数/选择模式"
alt 编译模式
Loader->>Compiler : "调用编译接口"
Compiler-->>Loader : "返回编译结果"
else 直接加载
Loader->>Loader : "解析 COFF 文件"
end
Loader->>Plugins : "加载插件并缓存符号"
Loader->>ExecMem : "分配代码/数据内存"
Loader->>ExecMem : "复制节区并应用重定位"
Loader-->>User : "调用入口并返回结果"
```

**图表来源**
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)
- [loader/src/main.rs:337-502](file://loader/src/main.rs#L337-L502)
- [loader/src/main.rs:537-743](file://loader/src/main.rs#L537-L743)

**章节来源**
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)

### 运行时插件（tsn_runtime）
- 功能要点
  - JS 值模型：使用 NaN-tagging 存储 number/string/object/boolean/undefined/null/function/array 等。
  - 容器管理：字符串池、数组池、对象属性映射。
  - 基础运算：加减乘除、取模、三角函数、随机数等。
  - JSON 简化实现：序列化/反序列化基础类型。
  - 文件系统占位：提供同步/异步读写、目录操作等接口。
- 设计特点
  - 大量 #[no_mangle] 导出，便于与编译器生成的外部符号对接。
  - 部分 Web/DOM API 为占位实现，满足最小可用性。

```mermaid
classDiagram
class RuntimePlugin {
+js_add(a,b) f64
+js_sub(a,b) f64
+js_mul(a,b) f64
+js_div(a,b) f64
+js_fmod(a,b) f64
+js_print(v) f64
+js_json_stringify(v) f64
+js_json_parse(text) f64
+js_fs_*(...) f64
+js_set_log_callback(cb)
}
class JsValue {
+tag : u64
+payload : u64
}
RuntimePlugin --> JsValue : "使用"
```

**图表来源**
- [runtime/src/lib.rs:135-200](file://runtime/src/lib.rs#L135-L200)
- [runtime/src/lib.rs:405-421](file://runtime/src/lib.rs#L405-L421)

**章节来源**
- [runtime/src/lib.rs:1-1532](file://runtime/src/lib.rs#L1-L1532)

### 独立链接器（native-linker）
- 功能要点
  - 支持多个 .o 输入合并为 PE（.exe）。
  - 配置导入表、入口点、子系统、堆栈与堆大小、自动注入运行时对象。
  - 支持 Windows 系统库导入（如 kernel32、ntdll、shell32）。
- 关键路径
  - 参数解析与默认输出推导。
  - 构建链接器配置并加载输入文件。
  - 执行链接并写入输出。

```mermaid
flowchart TD
A["解析参数"] --> B["构建链接器配置"]
B --> C["加载输入 .o"]
C --> D["执行链接生成 PE"]
D --> E["写入输出文件"]
```

**图表来源**
- [src/bin/native_linker_main.rs:24-162](file://src/bin/native_linker_main.rs#L24-L162)

**章节来源**
- [src/bin/native_linker_main.rs:1-163](file://src/bin/native_linker_main.rs#L1-L163)

## 依赖关系分析
- 根 crate 依赖
  - SWC 生态（解析/AST/访问器）。
  - Cranelift（JIT/代码生成）。
  - object（COFF 解析与重定位）。
  - clap（命令行解析）。
  - serde/serde_json（序列化）。
- 构建期依赖
  - cc（编译 C 源以生成运行时对象）。
- loader 与 runtime
  - loader 通过 Windows API 动态加载 DLL 并解析符号。
  - runtime 以 cdylib 形式提供导出函数。

```mermaid
graph LR
Root["根 crate"] --> SWC["swc_*"]
Root --> CL["cranelift-*"]
Root --> OBJ["object"]
Root --> CLAP["clap"]
Root --> SER["serde/serde_json"]
Root --> CC["cc (build.rs)"]
Loader["loader"] --> Win["Windows API"]
Loader --> RT["tsn_runtime"]
```

**图表来源**
- [Cargo.toml:26-56](file://Cargo.toml#L26-L56)
- [build.rs:4-32](file://build.rs#L4-L32)
- [loader/Cargo.toml:7-11](file://loader/Cargo.toml#L7-L11)
- [runtime/Cargo.toml:10-27](file://runtime/Cargo.toml#L10-L27)

**章节来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [build.rs:1-33](file://build.rs#L1-L33)
- [loader/Cargo.toml:1-23](file://loader/Cargo.toml#L1-L23)
- [runtime/Cargo.toml:1-28](file://runtime/Cargo.toml#L1-L28)

## 性能考虑
- 编译与链接
  - 使用 Cranelift 生成机器码，结合 LTO 优化与 panic=abort 配置提升运行时性能。
  - loader 在执行前进行阶段计时与统计，便于定位瓶颈。
- 内存与重定位
  - 代码节区按 PAGE_EXECUTE_READWRITE 分配，数据节区按 PAGE_READWRITE 分配。
  - 重定位类型 REL32/ADDR64 的应用直接影响执行效率与稳定性。
- 运行时
  - NaN-tagging 的 JS 值模型避免额外指针间接，减少内存占用。
  - 字符串/数组/对象池化减少频繁分配与 GC 压力。

**章节来源**
- [loader/Cargo.toml:17-22](file://loader/Cargo.toml#L17-L22)
- [loader/src/main.rs:202-222](file://loader/src/main.rs#L202-L222)
- [loader/src/main.rs:568-711](file://loader/src/main.rs#L568-L711)
- [runtime/src/lib.rs:7-24](file://runtime/src/lib.rs#L7-L24)

## 故障排查指南
- 常见问题
  - 缺少输入文件或输出路径：CLI 会在参数不足时提示用法并退出。
  - 未找到 COFF 文件：loader 报错并退出。
  - 无法加载 DLL：检查导出符号是否存在，确认 ABI 一致。
  - 重定位失败：检查符号表与导入表配置，确保内部/外部符号解析正确。
  - Windows 限制：loader 仅支持 Windows 平台。
- 调试建议
  - 使用 RUST_LOG 设置日志级别，结合阶段计时输出定位问题。
  - 在编译模式下，先查看 COFF 生成与符号/重定位统计。
  - 使用插件模式验证外部符号解析是否正常。
- 相关实现参考
  - CLI 参数与错误处理。
  - loader 的日志系统、阶段计时与错误返回。
  - 运行时导出函数的签名与实现。

**章节来源**
- [src/main.rs:10-40](file://src/main.rs#L10-L40)
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)
- [loader/src/main.rs:387-413](file://loader/src/main.rs#L387-L413)
- [loader/src/main.rs:632-711](file://loader/src/main.rs#L632-L711)

## 贡献者手册

### 开发环境设置
- 前置要求
  - Rust 1.95 或更高版本
  - Git 版本控制系统
  - C 编译器（用于运行时对象编译）
- 克隆和构建
  ```bash
  git clone https://github.com/itszzl-sudo/ts-native.git
  cd ts-native
  cargo build
  ```
- IDE 配置建议
  - 启用 rust-analyzer 插件
  - 配置自动格式化和代码检查
  - 设置合适的代码风格偏好

**章节来源**
- [CONTRIBUTING.md:5-29](file://CONTRIBUTING.md#L5-L29)

### 如何贡献
- 报告 Bug
  1. 检查现有 Issues 是否已存在相同问题
  2. 如果不存在，创建新 Issue，包含：
     - 清晰的问题描述
     - 详细的复现步骤
     - 期望行为说明
     - 实际行为描述
     - 环境信息（操作系统、Rust 版本、项目版本）
- 提交功能请求
  1. 创建 Issue 描述功能需求
  2. 说明功能的动机和解决的问题
  3. 提供使用示例代码
- 代码贡献流程
  1. Fork 仓库到个人账户
  2. 创建特性分支：`git checkout -b feature/your-feature-name`
  3. 提交改动：`git commit -m 'feat: add new feature'`
  4. 推送到远程分支：`git push origin feature/your-feature-name`
  5. 创建 Pull Request

**章节来源**
- [CONTRIBUTING.md:31-56](file://CONTRIBUTING.md#L31-L56)
- [.github/ISSUE_TEMPLATE/bug_report.md:1-37](file://.github/ISSUE_TEMPLATE/bug_report.md#L1-L37)
- [.github/ISSUE_TEMPLATE/feature_request.md:1-24](file://.github/ISSUE_TEMPLATE/feature_request.md#L1-L24)

### 代码规范
- Rust 代码规范
  - 使用 `cargo fmt` 进行代码格式化
  - 使用 `cargo clippy` 进行代码质量检查
  - 添加必要的文档注释
  - 遵循 Rust API 设计指南
- 提交信息规范
  - 使用清晰、描述性的标题
  - 第一行不超过 50 个字符
  - 如有必要，在正文详细说明变更内容
  - 使用以下前缀标识类型：
    - `feat:` 新功能
    - `fix:` Bug 修复
    - `docs:` 文档更新
    - `refactor:` 重构
    - `test:` 测试相关
    - `chore:` 其他改动

**章节来源**
- [CONTRIBUTING.md:57-78](file://CONTRIBUTING.md#L57-L78)

### 项目结构
```
ts-native/
├── src/
│   ├── main.rs          # 主 CLI 入口
│   ├── lib.rs           # 库模块入口
│   ├── codegen.rs       # 代码生成器
│   ├── coff.rs          # COFF 处理
│   ├── project.rs       # 项目管理
│   ├── project_compiler.rs # 项目编译器
│   ├── standalone_gen.rs # 独立生成器
│   ├── standalone_loader.rs # 独立加载器
│   ├── swc_transform.rs # SWC 变换层
│   ├── tsn_ffi.rs       # FFI 接口
│   └── bin/             # 二进制工具
├── runtime/             # 运行时库
├── loader/              # 加载器工具
├── test_multi_entry/    # 多入口测试
└── README.md            # 项目文档
```

**章节来源**
- [CONTRIBUTING.md:79-91](file://CONTRIBUTING.md#L79-L91)

### 测试指南
- 添加新测试
  1. 在测试目录创建 `test_feature.ts` 文件
  2. 编写测试代码验证功能
  3. 运行测试验证：`cargo run -- test_feature.ts && ./a.exe`
- 测试覆盖要求
  - 新增功能必须有对应的测试覆盖
  - 确保现有测试不被破坏
- 示例工程
  - test_multi_entry 提供多入口示例，可用于端到端验证

**章节来源**
- [CONTRIBUTING.md:93-104](file://CONTRIBUTING.md#L93-L104)
- [test_multi_entry/src/main.ts:1-15](file://test_multi_entry/src/main.ts#L1-L15)

### 发布流程
**注意：此流程仅适用于项目维护者**
1. 更新 CHANGELOG.md 记录变更内容
2. 更新版本号到 Cargo.toml 和相关文件
3. 创建 Git 标签：`git tag -a v0.x.x -m "Release 0.x.x"`
4. 推送标签到远程仓库：`git push origin v0.x.x`
5. 发布到 crates.io：`cargo publish`

**章节来源**
- [CONTRIBUTING.md:105-114](file://CONTRIBUTING.md#L105-L114)

## 开发流程

### 日常开发流程
1. **环境准备**
   - 确保 Rust 工具链已安装
   - 克隆项目并构建
   - 配置 IDE 和代码格式化工具

2. **功能开发**
   - 从主分支创建特性分支
   - 实现功能并编写测试
   - 运行本地测试验证
   - 提交代码并通过代码检查

3. **代码审查**
   - 创建 Pull Request
   - 回应审查意见
   - 修改代码直到通过审查

4. **合并发布**
   - 维护者合并代码
   - 运行 CI 测试
   - 准备发布版本

### 代码审查流程
- Pull Request 模板包含必需的检查清单
- 至少需要一位维护者审查批准
- CI 测试必须全部通过
- 代码风格和质量检查通过

**章节来源**
- [.github/PULL_REQUEST_TEMPLATE/pull_request_template.md:1-24](file://.github/PULL_REQUEST_TEMPLATE/pull_request_template.md#L1-L24)
- [CONTRIBUTING.md:115-125](file://CONTRIBUTING.md#L115-L125)

### 质量保证流程
- 本地测试：`cargo test`
- 代码格式化：`cargo fmt -- --check`
- 代码检查：`cargo clippy -- -D warnings`
- CI 自动检查：在 GitHub Actions 中运行

**章节来源**
- [.github/workflows/ci.yml:44-66](file://.github/workflows/ci.yml#L44-L66)

## 治理与行为准则

### 行为准则
项目遵循 Contributor Covenant v1.4，承诺营造开放、欢迎的环境：

**我们的承诺**
- 无论年龄、体型、残疾、种族、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教或性取向如何，参与项目和社区都将为每个人提供无骚扰的体验。

**我们标准**
- 使用友好和包容的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心和友善

**不可接受的行为**
- 使用性暗示语言或图像，或不受欢迎的性关注或调情
- 捣乱、侮辱/贬损评论以及人身或政治攻击
- 公开或私下骚扰
- 未经明确许可，发布他人的私人信息
- 在专业环境中可能被合理认为不适当的其他行为

**执行**
- 通过 Issues 联系项目团队报告不当行为
- 所有投诉都将被审查和调查
- 项目团队有义务对事件报告者保密
- 违规行为的详细信息可在单独提供

**章节来源**
- [CODE_OF_CONDUCT.md:1-49](file://CODE_OF_CONDUCT.md#L1-L49)

### 联系方式
- **GitHub Issues**：用于 Bug 报告和功能请求
- **Pull Requests**：用于代码贡献
- **邮件联系**：通过 Issues 联系维护团队

### 项目维护
- **维护者职责**
  - 审查和合并 Pull Request
  - 回答社区问题
  - 维护项目文档
  - 管理发布流程

- **贡献者等级**
  - 新贡献者：通过 Issues 和 PR 参与
  - 积极贡献者：获得代码审查权限
  - 维护者：拥有合并权限和项目决策权

**章节来源**
- [CONTRIBUTING.md:119-125](file://CONTRIBUTING.md#L119-L125)

## 结论
本指南覆盖了 ts-native 项目的开发全流程：从环境与工具链准备、构建与部署、调试与性能分析，到测试与质量保障、贡献流程与治理规范。建议在开发过程中优先使用 CLI 生成 COFF，再通过 loader 执行验证；在需要时使用 native-linker 生成可执行文件；同时充分利用运行时插件提供的基础能力。

项目采用开放的贡献模式，鼓励社区参与。通过遵循本文档的开发流程和行为准则，所有贡献者都可以有效地参与项目开发。

## 附录

### 开发环境设置
- **Rust 工具链**
  - 使用稳定通道工具链，CI 工作流展示了安装与缓存步骤
  - 支持版本：Rust 1.95 或更高版本
- **IDE 配置**
  - 建议启用 rust-analyzer，启用 clippy 与 rustfmt
  - 配置自动代码格式化和错误检查
- **依赖环境**
  - Windows 平台：loader 与 native-linker 依赖 Windows API 与链接器特性
  - 构建期 C 代码：通过 build.rs 使用 cc 编译 runtime/start 对象

**章节来源**
- [.github/workflows/ci.yml:20-22](file://.github/workflows/ci.yml#L20-L22)
- [build.rs:4-32](file://build.rs#L4-L32)

### 构建与部署
- **常规构建**
  - 开发构建：`cargo build`
  - 发布构建：`cargo build --release`
- **测试**
  - 运行所有测试：`cargo test`
  - 运行特定测试：`cargo test <test_name>`
- **发布**
  - CI 工作流在打上 v* 标签时发布至 crates.io（需凭令牌）
  - 维护者权限：仅限项目维护者执行发布操作
- **跨平台**
  - 当前 loader 与 native-linker 仅支持 Windows
  - 如需跨平台，需调整链接器与运行时部分

**章节来源**
- [.github/workflows/ci.yml:41-48](file://.github/workflows/ci.yml#L41-L48)
- [.github/workflows/ci.yml:74-82](file://.github/workflows/ci.yml#L74-L82)

### 质量保证与测试
- **单元与集成测试**
  - 在本地运行 `cargo test` 验证功能
  - 使用 `cargo test -- --nocapture` 查看详细输出
- **示例工程**
  - test_multi_entry 提供多入口示例，可用于端到端验证
  - 包含 CLI、库、工具函数等多种场景
- **CI 质量门禁**
  - CI 中包含测试与 lint 步骤，确保合并前质量
  - 自动格式化检查和代码质量检查

**章节来源**
- [.github/workflows/ci.yml:44-45](file://.github/workflows/ci.yml#L44-L45)
- [test_multi_entry/src/main.ts:1-15](file://test_multi_entry/src/main.ts#L1-L15)

### 常见开发任务
- **添加新功能**
  1. 创建新的模块文件
  2. 在 lib.rs 中添加模块声明
  3. 编写功能实现
  4. 添加单元测试
  5. 更新文档和示例
- **修复 Bug**
  1. 创建最小化复现示例
  2. 编写针对性测试
  3. 实现修复方案
  4. 运行完整测试套件
  5. 提交修复代码
- **性能优化**
  1. 使用性能分析工具识别瓶颈
  2. 实施优化方案
  3. 测量性能改进效果
  4. 确保功能正确性不受影响

**章节来源**
- [CONTRIBUTING.md:93-104](file://CONTRIBUTING.md#L93-L104)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)