Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
205 lines (159 loc) · 7.38 KB

CONTRIBUTING.md

File metadata and controls

205 lines (159 loc) · 7.38 KB
Raw

贡献指南

感谢你对 CodeMUX 项目的关注！我们欢迎各种形式的贡献。

如何参与贡献

报告问题

使用 GitHub Issues 报告 Bug 或提出功能建议。

Bug 报告请包含：

  • 操作系统和版本（如 Windows 11 23H2、macOS 15.0、Ubuntu 24.04）
  • Node.js 版本（node --version）
  • Rust 版本（rustc --version）
  • 问题复现步骤
  • 预期行为与实际行为
  • 相关日志或截图

功能建议请包含：

  • 使用场景描述
  • 期望的交互方式
  • 是否愿意参与实现

提交代码

  1. Fork 本仓库到你的 GitHub 账号
  2. 克隆 你的 Fork： 
    git clone https://github.com/kfumi/codeMUX.git
cd codeMUX
  3. 创建分支： 
    git checkout -b feature/your-feature-name
  4. 安装依赖： 
    npm ci
cd apps/sidecar && npm ci && npm run build && cd ../..
  5. 开发与测试： 
    npm run dev:desktop
  6. 提交修改： 
    git add .
git commit -m "feat: your feature description"
  7. 推送并创建 PR： 
    git push origin feature/your-feature-name

Commit 规范

使用 Conventional Commits 格式：

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Type 类型

Type 说明
feat 新功能
fix Bug 修复
docs 文档更新
style 代码格式（不影响逻辑，如空格、分号等）
refactor 重构（既不修复 Bug 也不添加功能）
perf 性能优化
test 添加或修改测试
chore 构建流程、工具链变动
ci CI 配置变动
revert 回滚提交

Scope 范围（可选）

常用范围：agent、mcp、skills、ui、store、db、sidecar、config

示例

feat(mcp): add SSE transport support
fix(agent): prevent sidecar crash on empty response
docs(readme): add macOS setup instructions
refactor(store): simplify session state management
chore(deps): bump tauri to 2.1.0

代码规范

Rust

  • 使用 cargo fmt 格式化代码
  • 使用 cargo clippy 检查 lint
  • 提交前确保 cargo build 无错误

TypeScript / React

  • 遵循项目 ESLint 配置
  • 组件使用函数式组件 + Hooks
  • 状态管理使用 Zustand
  • 样式使用 Tailwind CSS，避免自定义 CSS

通用

  • 保持代码简洁，避免不必要的注释
  • 变量和函数命名清晰明了
  • 新功能请附带相关文档更新

项目结构速览

src/                        # React 渲染层（桌面 UI）
  components/agent/         # Agent 对话面板、工具卡片、权限卡片、上下文进度
  components/assistant-ui/  # assistant-ui 自定义组件（消息、Diff、Reasoning 等）
  components/settings/      # 设置页（Provider / MCP / Skills / 通知 / 使用统计 / 日志）
  components/workspace/     # Review / Terminal / Plan 等侧边面板
  components/browser/       # Browser Host 浏览页 UI（沙箱 webview）
  components/automation/    # daemon→壳受控自动化相关 UI
  components/companion/     # 配对与连接 UI（桌面与浏览器/手机网页端共用）
  components/dev/           # 开发模式性能诊断覆盖层
  features/update/          # 自动更新入口
  stores/                   # Zustand 状态（agent / session / mcp / skill 等）
  types/                    # TypeScript 类型
  lib/                      # 工具函数（通知、权限、模型、上下文计算等）
  hooks/                    # 自定义 Hooks（agent models / notifications / theme）

apps/
  desktop/                # Electron 桌面壳（窗口 / 托盘 / supervisor / Browser Host / updater）
    src/                  # main、preload、supervisor、browser-host、daemon-token 等
  sidecar/                # Node.js Agent Sidecar（Claude / Codex / OpenCode 运行时）
  cli/                    # 本机命令行 Daemon Client

crates/
  daemon/                 # Rust daemon crate（Tauri 壳已移除，目录由 src-tauri/ 改名）
    src/bin/              # codemux-daemon 入口（权威进程）
    src/daemon/           # daemon 装配与生命周期
    src/companion/        # Companion Server（REST/WS、鉴权、自动化接缝）
    src/agent/            # 会话生命周期、历史导入、Timeline 持久化
    src/agent_runtime/    # Claude / Codex / OpenCode / pi 运行时抽象
    src/mcp/adapters/     # MCP 各 Agent 适配器（claude / codex / gemini / opencode）
    src/skills/adapters/  # Skills 各 Agent 适配器
    src/model_providers/  # Model Provider 服务
    src/scheduled_tasks/  # 定时任务

架构背景（daemon 权威、Electron 壳 supervisor、Companion 协议）见 ADR：docs/adr/0011-daemon-authority-local-token.md、docs/adr/0012-daemon-process-electron-shell.md。

设计文档

项目的详细设计文档位于 docs/specs/ 目录，架构决策记录（ADR）位于 docs/adr/，阅读这些文档有助于理解架构决策：

  • 2026-05-27-ai-codeMUX.md — 项目整体设计
  • 2026-05-28-claude-agent-sdk-integration.md — Claude Agent SDK 集成设计
  • 2026-06-08-assistant-ui-runtime-adapter.md — assistant-ui 运行时适配设计
  • 2026-06-10-multi-agent-codex-integration.md — Codex 多 Agent 集成设计
  • 2026-06-13-mcp-management-refactor.md — MCP 管理重构设计
  • 2026-06-29-agent-permission-approval-alignment.md — Agent 权限审批对齐设计
  • 2026-07-01-updater-mechanism.md — 自动更新机制设计
  • 2026-07-03-agent-system-notifications.md — Agent 系统通知设计
  • 2026-07-03-git-branch-management.md — Git 分支管理设计
  • 2026-07-12-opencode-sdk-agent.md — OpenCode SDK Agent 接入设计
  • 2026-07-14-agent-provider-profile-refactor.md — Provider Profile 重构设计
  • 2026-07-23-dev-performance-diagnostics.md — 开发性能诊断设计
  • 2026-08-27-scheduled-tasks.md — 定时任务设计
  • 2026-09-01-shared-transcript-message-renderer.md — 共享消息渲染器设计
  • docs/adr/0011-daemon-authority-local-token.md — Daemon 权威与 Local Daemon Token
  • docs/adr/0012-daemon-process-electron-shell.md — Daemon 独立进程与 Electron 桌面壳

此外 docs/guides/ 下还有面向使用者的指南：agent-provider-profiles-guide.md、codex-routing-proxy-guide.md、mcp-unified-management-guide.md、skills-unified-management-guide.md、ai-agent-permission-approval-guide.md、desktop-release-guide.md。完整文档索引与写作规范见 docs/README.md。

Pull Request 检查清单

提交 PR 前请确认：

  • 代码已通过 cargo fmt 和 cargo clippy（Rust 部分）
  • 代码已通过 TypeScript 类型检查（npm run build，壳改动另跑 cd apps/desktop && npm run typecheck）
  • 功能在开发模式下测试通过（npm run dev:desktop）
  • 新功能已更新相关文档
  • Commit 消息符合 Conventional Commits 规范
  • PR 描述清晰说明了修改内容和原因

行为准则

  • 尊重每一位参与者
  • 建设性地提出意见和建议
  • 聚焦于技术讨论，避免人身攻击
  • 欢迎不同背景和经验水平的贡献者

有问题？

如有任何疑问，欢迎在 GitHub Discussions 中提问。

再次感谢你的贡献！🎉