跳转至
SW Dev Spec · v1.0

软件开发规范 v1.0

代码风格 · Git 流程 · Review · 版本 · 发版 · 依赖 · 安全
文档编号：D1-B-SPEC-001 · 版本：v1.0 · 发布：2026-05-05
让每一行代码可追溯 · 每一次合并可回滚 · 每一次发版可复现
5
覆盖语言
Trunk
Git 主模式
100%
PR 必 Review

软件开发规范 v1.0

摘要

本规范是 Xisound 全公司软件研发的基础契约，适用于 XiStudio / XiForge / XiTune / XiTest / 后端服务 / CI 工具链等所有软件产品线。 覆盖 代码风格、Git 工作流、Code Review、版本号规范、发版流程、依赖管理、安全扫描 七大主题。 所有新立项的软件项目必须在 Kickoff 一周内完成本规范的全量落地；存量项目按"增量遵守、批量迁移"原则处理。

1. 适用范围

1.1 覆盖对象

  • 桌面应用：XiStudio（Windows/macOS）、XiForge（Web + Electron）、XiTune（便携版）
  • 后端服务：音频网关、DSP 编排、Mixer、认证、存储
  • 嵌入式软件：XiDSP 固件、XiBox 系统软件（符合 MISRA 部分另行约束）
  • 工具与脚本：CI、发版、数据处理、自动化测试框架
  • SDK / 库：XiAlgo C/C++ 库、XiStudio 插件 SDK

1.2 覆盖语言

语言 主要用途 风格参考
C / C++ XiDSP 固件、XiAlgo 核心、底层音频 Google C++ Style（裁剪） + MISRA C:2012（嵌入式）
C# XiStudio 桌面 + 后端服务 Microsoft .NET 编码约定
TypeScript / JavaScript XiForge 前端、Web 控制台、Electron Airbnb TypeScript Style + Prettier
Python 算法原型、数据处理、CI 脚本 PEP 8 + Ruff + Black
Rust 安全敏感工具、性能组件（选配） rustfmt + clippy（pedantic）

2. 代码风格

2.1 通用约定

七条底线

  1. 文件编码统一 UTF-8，换行符由 .gitattributes 统一（源码 LF / 脚本按平台）
  2. 所有新增文件必须含版权与 License 头部注释
  3. 禁止提交未经格式化的代码（CI 会 --check 格式化工具）
  4. 公共 API 必须有文档注释（Doxygen / XML Doc / JSDoc / docstring）
  5. TODO / FIXME 必须挂 Issue 编号，例如 // TODO(#1234): ...
  6. 禁止提交含调试 print / console.log 的正式代码
  7. 函数单体 ≤ 100 行，圈复杂度 ≤ 15（C/C++ DSP 路径可放宽到 200 / 20，但须 Review 批注）

2.2 C / C++

  • 风格基线：Google C++ Style Guide（裁剪版），保留 4 空格缩进（与 XiDSP 现有代码一致）
  • 命名：
  • 类/结构体：PascalCase
  • 函数：CamelCase（公共 API）/ snake_case（内部静态）
  • 常量：kConstantName
  • 宏：XI_XXX_YYY（强制前缀防冲突）
  • 头文件 include 顺序：自身头 → C 标准库 → C++ 标准库 → 第三方 → 本项目其他
  • 禁止：using namespace std;（.h 中）、裸 new/delete（用智能指针）、C 风格 cast

2.3 C

  • 风格基线：Microsoft .NET Coding Conventions + .editorconfig（项目根）
  • 命名：
  • 类/属性/方法：PascalCase
  • 私有字段：_camelCase
  • 参数/局部：camelCase
  • 接口：IXxxxx 前缀
  • 异步方法必须 Async 后缀，并传播 CancellationToken
  • 禁止：async void（事件处理器除外）、在 library 内部调用 .Result / .Wait()

2.4 TypeScript

  • 风格基线：Airbnb TypeScript + Prettier（项目根 .prettierrc）
  • 强制 strict: true、noImplicitAny: true、strictNullChecks: true
  • 组件：函数组件 + Hooks（React）；Vue 项目遵循官方 Composition API 风格
  • 禁止：any（必须用 unknown 或精确类型）、默认导出（导出命名，便于 IDE 重构）

2.5 Python

  • 风格基线：PEP 8，格式化工具 Black（line-length=100），Lint 工具 Ruff
  • 类型注解：所有公共函数必须有类型注解（mypy --strict 逐步推进）
  • 虚拟环境：统一 uv 或 poetry，禁止全局 pip install
  • 入口保护：if __name__ == "__main__":

2.6 格式化与 Lint 工具

语言 格式化 Lint CI 检查
C/C++ clang-format clang-tidy clang-format --dry-run -Werror
C# dotnet-format Roslyn Analyzers dotnet format --verify-no-changes
TypeScript Prettier ESLint prettier --check + eslint
Python Black Ruff + mypy black --check + ruff check

3. Git 工作流（Trunk-Based）

3.1 主模式选型

Xisound 采用 Trunk-Based Development + Short-lived Feature Branches 为全公司默认工作流。

为什么是 Trunk-based 而不是 GitFlow

  • Xisound 以 周粒度迭代，GitFlow 的 release/hotfix 双分支对我们过重。
  • Trunk-based 要求 CI 质量门禁严格，推动我们尽早投入自动化测试。
  • 芯片固件等长周期分支另行处理（见 §3.6）。

3.2 分支命名

分支 格式 举例 生命周期
主干 main main 永久
特性 feat/<issue-id>-<slug> feat/1234-drc-bypass ≤ 5 个工作日
修复 fix/<issue-id>-<slug> fix/1280-nan-in-eq ≤ 2 个工作日
重构 refactor/<scope> refactor/mixer-routing ≤ 5 个工作日
发版 release/<version> release/v1.3.0 冻结期 ≤ 7 天
长周期 track/<product>-<feature> track/xidsp-v2-rtl 与产品里程碑一致

3.3 工作流图

graph LR
    I[Issue 立项] --> B[feat 分支]
    B --> D[本地开发]
    D --> P[PR 提交]
    P --> CI[CI 流水线]
    CI --> R{Review 通过?}
    R -- 否 --> D
    R -- 是 --> M[Squash Merge 到 main]
    M --> T[打 tag / CD 发布]

    class I xyL0
    class B,D xyL2
    class P,CI xyL3
    class R xyWarn
    class M xySuccess
    class T xyL4

3.4 Commit 规范

采用 Conventional Commits：

<type>(<scope>): <subject>

<body>

<footer>
  • type：feat / fix / docs / refactor / perf / test / build / ci / chore
  • scope：模块名（如 mixer / xistudio-ui / xidsp-rtl）
  • subject：祈使句，≤ 72 字符，句末不加句号
  • footer：关联 Issue（Closes #1234）或 BREAKING CHANGE

3.5 PR 规则

PR 五条必守

  1. 单 PR ≤ 500 行差异（超过必须拆分）
  2. PR 标题遵循 Conventional Commits
  3. PR 描述必含：变更动机 / 变更点 / 测试方式 / 回滚策略
  4. 必须关联 Issue / 需求单
  5. CI 全绿 + 至少 1 位 Reviewer 批准才能合并

3.6 长周期分支（芯片固件类）

  • 用 track/ 前缀，每周至少一次 rebase / merge 回 main
  • 每月进行一次 Long-running Branch Health Review
  • 禁止长周期分支长期悬挂（> 3 个月需撰写 ADR）

4. Code Review 规则

4.1 Reviewer 责任

角色 责任
Author（作者） 准备 PR 描述、自测、回复每条评论
Primary Reviewer 代码正确性、架构合理性、测试充分性
Domain Reviewer（可选） 跨模块接口、跨团队影响
QA Reviewer（可选） 测试用例充分性（重要路径）

4.2 Review 四维度

  1. 正确性（Correctness）：逻辑是否正确，边界条件是否处理
  2. 可读性（Readability）：命名、注释、结构是否清晰
  3. 可维护性（Maintainability）：是否过度耦合，是否留下技术债
  4. 测试充分性（Test Coverage）：新增代码是否有对应测试（增量覆盖率 ≥ 70%）

4.3 Review SLA

  • Primary Reviewer 需在 24 小时内首轮响应（工作日）
  • 阻塞性评论（Blocker）需在 Author 修改后 8 小时内复检
  • 超过 3 个工作日无响应，Author 可在团队周会升级

4.4 评论等级

等级 含义 作者处理
Blocker 必须修复才能合 修改 + 回复
Major 强烈建议修复 修改 或 解释
Minor 建议改进 修改 或 挂 Follow-up Issue
Nit 吹毛求疵 随意处理
Question 求澄清 必须回复

5. 版本号规范（SemVer）

5.1 基础规则

遵循 Semantic Versioning 2.0.0：MAJOR.MINOR.PATCH

  • MAJOR：不兼容的 API 变更
  • MINOR：向后兼容的功能新增
  • PATCH：向后兼容的 Bug 修复

5.2 预发布与元数据

  • 预发布标识：-alpha.N / -beta.N / -rc.N（如 v1.2.0-rc.1）
  • 构建元数据：+build.<sha>（可选，仅用于内部追溯）

5.3 产品与版本对照

产品 当前大版本 发版频率
XiStudio v1.x 月度 Minor，周 Patch
XiForge v0.x（beta） 双周
XiTune v1.x 季度
XiTest v1.x 月度
XiAlgo 库 v2.x 随算法迭代
XiDSP 固件 v1.x 季度

5.4 Tag 规则

  • Tag 格式：v<MAJOR>.<MINOR>.<PATCH>（单产品仓）或 <product>-v<version>（monorepo）
  • 每个正式 Tag 必须同步：Release Notes / Changelog / 构建产物归档

6. 发版流程

6.1 发版类型

类型 触发 审批 示例
Nightly 每日 CI 自动 无 研发内部验证
Alpha 人工打包 研发 Leader 内部 QA
Beta 特性完成 产品 + 研发 种子客户
RC Beta 稳定 研发总监 回归测试
GA（正式） 全量测试通过 CTO + 产品总监 对外发布
Hotfix 线上严重 bug CTO 审批 紧急修复

6.2 发版流程图

graph LR
    A[特性冻结] --> B[建 release 分支]
    B --> C[回归测试]
    C --> D{通过?}
    D -- 否 --> F[Bug 修复]
    F --> C
    D -- 是 --> G[打 RC tag]
    G --> H[灰度]
    H --> I{灰度 OK?}
    I -- 否 --> F
    I -- 是 --> J[打 GA tag]
    J --> K[全量发布]
    K --> L[发版通告]

    class A xyL0
    class B,C xyL2
    class D,I xyWarn
    class F xyError
    class G,H xyL3
    class J,K xySuccess
    class L xyL4

6.3 发版清单（Release Checklist）

GA 发版必检 10 项

  • CI 全绿，回归测试 100% 通过
  • 变更日志（CHANGELOG.md）已更新
  • 版本号按 SemVer 正确递增
  • Tag 已打，构建产物已签名并归档
  • 安全扫描（SAST + 依赖扫描）无高危问题
  • 性能回归（关键指标）无 > 5% 劣化
  • 兼容性：最低支持的 OS / .NET / Node 版本已验证
  • 文档已同步（用户手册 / API Doc）
  • 回滚方案已确认（回滚脚本可执行）
  • 发版通告已草拟（内部 Wiki + 客户公告）

6.4 Hotfix 流程

  • 从最近 GA Tag 拉 hotfix/<version> 分支
  • 最小变更原则：只改引起问题的代码 + 对应测试
  • CI 全绿 + CTO 批准后合并 → 同步合并到 main
  • 发版 PATCH 号递增（如 v1.3.0 → v1.3.1）

7. 依赖管理

7.1 依赖引入原则

引入第三方依赖五问

  1. 是否有同等能力的标准库 / 公司已有组件？
  2. 许可证是否兼容（见 §7.3）？
  3. 维护活跃度如何（近 90 天有更新？）？
  4. 是否有已知高危漏洞（CVE）？
  5. 总依赖体积与编译时间增量是否可接受？

7.2 锁文件

  • C++：vcpkg.json + vcpkg-configuration.json 锁定版本
  • C#：Directory.Packages.props（Central Package Management）
  • TypeScript：package-lock.json 或 pnpm-lock.yaml 必须提交
  • Python：poetry.lock 或 uv.lock 必须提交

7.3 许可证白名单

级别 许可证 使用说明
Allow MIT / BSD-⅔ / Apache-2.0 / ISC / Zlib / MPL-2.0 自由使用
Review LGPL-2.⅓.0 / EPL 法务评审后使用
Forbid GPL-2.0/3.0 / AGPL / SSPL 禁止引入（商业产品）

GPL 零容忍

商业产品代码库严禁引入 GPL / AGPL / SSPL 代码；开源自家工具（OSS 项目）可按具体许可证另议。

7.4 升级策略

  • 安全升级：发现高危 CVE 后 7 天内完成升级与验证
  • 常规升级：季度统一升级次要版本
  • 大版本升级：走 ADR 评审

8. 安全扫描

8.1 扫描矩阵

类型 工具 触发 阻塞级别
静态代码分析（SAST） SonarQube / clang-tidy / Roslyn / ESLint PR High → 阻塞
依赖漏洞扫描（SCA） OWASP Dep-Check / Dependabot / npm audit PR + 每日 Critical → 阻塞
密钥扫描 gitleaks / trufflehog Pre-commit + CI 发现 → 阻塞
许可证扫描 license-checker / FOSSA Weekly 违反白名单 → 阻塞
容器镜像扫描 Trivy 构建 High → 阻塞

8.2 密钥与凭据

  • 零容忍提交：API Key / 密码 / 私钥 / 连接串
  • 本地开发用 .env.local（加入 .gitignore）
  • 生产凭据通过 Secret Manager（Azure Key Vault / AWS Secrets Manager / 公司内 Vault）下发
  • 一旦泄漏：立即 rotate + 评估影响 + 事件复盘

8.3 安全响应

  • CVE 定期订阅 → 研发 Leader 每周分类
  • P0（Critical 且已公开）：24 小时内出修复计划
  • P1（High）：7 天内完成升级
  • P2（Medium）：纳入下一迭代
  • P3（Low）：跟踪即可

9. 附录

9.1 PR 自检清单

Author 提交 PR 前必做 8 项

  1. 本地构建通过（Release + Debug）
  2. 本地单元测试全绿
  3. 格式化与 Lint 通过
  4. 新增代码覆盖率 ≥ 70%
  5. 无调试输出、无注释掉的死代码
  6. PR 描述完整（动机 / 变更 / 测试 / 回滚）
  7. 关联 Issue
  8. 不含密钥 / 凭据

9.2 关联文档

9.3 版本历史

版本 日期 要点
v1.0 2026-05-05 首版 · 基于研发中心章程 §4.2 展开

sw-dev-spec.md · D1-B-SPEC-001 · v1.0 · 2026-05-05 · Xisound 研发中心