Skip to content

CONTRIBUTING_CN.md

Latest commit

 

History

History
169 lines (115 loc) · 7.92 KB

CONTRIBUTING_CN.md

File metadata and controls

169 lines (115 loc) · 7.92 KB
Raw

贡献指南

English

感谢你对 BitFun 的兴趣！BitFun 是一个由 Rust 与 TypeScript 驱动的多端 AI 编程环境，桌面端/CLI/Server 共享核心逻辑。本指南说明如何高效参与贡献。

行为准则

请保持尊重、友善与建设性沟通。我们欢迎不同背景与经验的贡献者。

快速开始

环境准备

  • Node.js 22.12+（建议 LTS 版本）
  • pnpm 10.15.0（建议通过 Corepack 使用）
  • Rust toolchain（通过 rustup 安装）
  • 桌面端开发需准备 Tauri 依赖

BitFun 将本地 JavaScript 构建和 CI 统一到 Node.js 22.12+。仓库里的 GitHub Actions 升级使用的是兼容 Node.js 24 的 action runtime，但项目脚本 默认仍以 Node.js 22.12+ 为基线，除非局部指南另有说明。从旧 Node.js 版本切换 后，请重新运行 pnpm install。

构建前置检查

当 cargo check --workspace、cargo check -p bitfun-desktop 或 pnpm 构建 命令报出难以理解的错误（如 "resource path doesn't exist" 或 sherpa-onnx 下载失败）时，运行前置检查以识别缺失的依赖并获取可操作的修复命令：

pnpm run check:build-prereqs           # 仅检查
pnpm run check:build-prereqs -- --fix  # 尝试自动修复缺失的前置依赖

检查项包括：

  • 缺少 node_modules（修复：pnpm install）
  • 缺少 src/mobile-web/dist（修复：pnpm run prepare:mobile-web — bitfun-desktop 的 Tauri 构建脚本将该目录作为资源引用，缺失时 cargo check -p bitfun-desktop 和 cargo check --workspace 会失败）
  • 缺少 sherpa-onnx 预编译库（sherpa-onnx-sys 构建脚本会在构建时从 GitHub 下载；若网络连通性差导致下载失败，设置 SHERPA_ONNX_LIB_DIR 指向 target/sherpa-onnx-prebuilt/ 下的预编译 lib 目录以使用本地副本）

安装依赖

pnpm install

常用命令

# Desktop（日常开发推荐）
pnpm run desktop:dev                # 完整热更新：Vite HMR + Rust 自动重编译并重启

# Desktop（轻量预览，无 Rust 自动重编译）
pnpm run desktop:preview:debug      # 复用预构建二进制 + Vite HMR；Rust 改动需手动重启

# Desktop（生产构建）
pnpm run desktop:build

# E2E
pnpm run e2e:test

desktop:dev 与 desktop:preview:debug 的区别：desktop:dev 运行 tauri dev，提供完整热更新 — 前端改动通过 Vite HMR 即时生效，Rust/后端改动会触发增量重编译并自动重启应用，是日常开发的首选方式。desktop:preview:debug 启动预构建的 debug 二进制和 Vite dev server；前端编辑仍可 HMR，但 Rust 侧改动不会自动重编译 — 需要手动停止并重新运行命令（或使用 --force-rebuild）。适合仅需迭代前端代码、或希望跳过 tauri dev 初始化以更快冷启动的场景。

完整脚本列表见 package.json。agent 专用命令、验证与架构规则见 AGENTS.md。

桌面端调试工具

桌面端 dev 构建会启用 devtools Cargo feature。F12 打开原生 webview DevTools；Cmd/Ctrl + Shift + I 切换 BitFun 元素检查器，Cmd/Ctrl + Shift + J 也可以打开原生 DevTools。面向最终用户的 release 构建不会启用这些工具。

代码规范与架构约束

架构敏感规则、模块边界和验证矩阵以 AGENTS.md 为准。面向贡献者只需把握：

  • 日志只使用英文，并保持必要、可读。
  • 用户可见文案走项目 i18n 流程；不要把 Web UI locale catalog 共享给较小产品形态。
  • shared core 必须保持平台无关；Desktop/Tauri 细节属于 app adapter，并通过类型化能力接口回流；需要事件投递时使用已有生产 transport adapter。
  • Tauri command 使用 snake_case 命令名和结构化 request 参数。
  • core 拆解、feature 边界、依赖边界和构建提速重构必须遵循 docs/architecture/product-architecture.md。
  • 功能级规则应放在离代码最近的模块 AGENTS.md 中。

重点关注的贡献方向

  1. 贡献好的想法/创意（功能、交互、视觉等），提交 Issue

    欢迎产品经理、UI 设计师通过 PI 快速提交创意，我们会帮助完善开发

  2. 优化 Agent 系统和效果
  3. 对提升系统稳定性和完善基础能力
  4. 扩展生态（Skills、MCP、LSP 插件，或者对某些垂域开发场景的更好支持）

贡献流程与 PR 约定

除功能/修复外的贡献方向

我们欢迎不仅限于功能或修复的 PR。示例包括：

贡献方向 位置/文件 示例说明
Prompts src/crates/assembly/core/src/agentic/agents/prompts/ 新增或优化提示词，并按需更新相关逻辑
Tools src/crates/assembly/core/src/agentic/tools/implementations/、src/crates/assembly/core/src/agentic/tools/registry.rs 新增工具实现，并在工具注册表中注册
Subagents src/crates/assembly/core/src/agentic/agents/custom_subagents/、src/crates/assembly/core/src/agentic/agents/registry.rs 新增子代理实现，并在子代理注册表中注册
模式贡献 src/crates/assembly/core/src/agentic/agents/*_mode.rs、src/crates/assembly/core/src/agentic/agents/prompts/*_mode.md、src/web-ui/src/locales/*/settings/modes.json 新增/优化 Agent 模式（例如 Plan/Debug/Agentic 或自定义模式）的逻辑与提示词，并同步前端模式文案
Code Agent 与 AIIde 场景指南 website/src/docs/ 补充流程、playbook 与真实场景说明（或从 README.md 链接）

开始前

  • 先开 Issue 说明问题或方案，尤其是较大改动，以避免重复与设计冲突
  • 新功能或 UI 变更建议先讨论设计方向，确保符合产品体验
  • 将 Issue 和 PR 模板作为填写指引；保持 PR 聚焦，必要时说明跳过了哪些验证以及原因。

PR 标题与描述

建议使用 Conventional Commits 风格，便于维护版本记录与自动化流程：

  • feat: 新功能
  • fix: 修复问题
  • docs: 文档变更
  • chore: 维护/依赖
  • refactor: 重构且不改行为
  • test: 测试相关

UI 改动请附前后对比截图或短录屏，方便快速评审。

如为 AI 辅助产出，请在 PR 中注明并说明测试程度（未测/轻测/已测），便于评审风险。

不要提交临时 AI prompt、本地绝对路径、生成的草稿文件、配对密钥、token、证书或无关产物。PR 应聚焦于本次产品或维护改动。

分支管理

main 分支为默认协作分支，并接受特性 PR。 本仓库欢迎产品经理、开发者使用 AI 生成代码进行快速验证或提交想法，因此 所有 PR 请直接提交到 main 分支。

变更范围

保持 PR 小而聚焦，避免混杂无关改动。

测试与验证

按改动文件和行为选择最小检查。完整构建和大范围测试由 CI 保护；只有改动影响构建、打包、发布行为， 或 CI 无法覆盖对应路径时，才在本地运行更重命令。

常见本地检查：

改动类型 常用验证
仓库元信息或 GitHub 配置 pnpm run check:repo-hygiene && pnpm run check:github-config && git diff --check
前端运行时或 UI pnpm run type-check:web；行为变化时再加最近的 focused test
Mobile web pnpm --dir src/mobile-web run type-check
Rust 共享 runtime 或 services cargo check --workspace；行为变化时再加 focused cargo test
Desktop/Tauri 集成 cargo check -p bitfun-desktop
i18n 资源或契约 使用 AGENTS.md 中匹配的 i18n 验证行

UI 改动在有帮助时附截图或短录屏。无法运行相关检查时，在 PR 中说明原因，并提供风险更低的手动验证路径。

安全与合规

  • 不要提交密钥、Token、证书或任何敏感信息
  • 新增依赖请确认许可证兼容并说明用途

感谢

每一份贡献都很重要，欢迎提交 Issue、PR 或建议！