Files
tutti/CONTRIBUTING.zh-CN.md
agent-radar 2ed3415fb7
Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s
源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
2026-09-01 20:17:27 +08:00

193 lines
6.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 为 Tutti 做贡献
[English](CONTRIBUTING.md) | [简体中文](CONTRIBUTING.zh-CN.md) | [繁體中文](CONTRIBUTING.zh-TW.md)
感谢你有兴趣为 Tutti 做贡献!本指南涵盖搭建开发环境、遵循项目规范以及让你的改动被合并所需的全部内容。
参与本项目即表示你同意遵守我们的[行为准则](CODE_OF_CONDUCT.md)。
> 注:本代码库使用内部代号 `tutti`,你会在目录和二进制命名中看到它(如 `services/tuttid`)。
## 仓库结构
- `apps/desktop`:Electron 桌面外壳、渲染器 UI、preload 桥接层和原生桌面集成
- `services/tuttid`:长驻本地守护进程,核心业务所在
- `packages/clients/*`:共享的领域客户端
- `packages/configs/*`:共享的工程配置
- `packages/ui/*`:共享的视觉系统边界
## 开发环境
推荐的本地环境:
- Node.js `24` 或更高;`.node-version` 固定了项目基线
- pnpm `10.11.0`
- Go `1.24`
- `golangci-lint` `v2.12.0`
安装 workspace 依赖:
```sh
pnpm install
```
对于新建的链接 Git worktree,请改用:
```sh
pnpm setup:worktree
```
该命令会安装 workspace 依赖,再在并行测试运行前预热 Electron。它会复用共享的
Electron 下载缓存,并把运行时解压到新 worktree;不会复用其他 worktree 的
`Electron.app`。
安装固定版本的 `golangci-lint`:
```sh
pnpm install:golangci-lint
```
检查本地环境:
```sh
pnpm setup:dev
```
以带前置检查和预构建 `tuttid` 的方式启动桌面应用开发:
```sh
make dev-gui
```
如果你已有可用的 daemon 二进制,只想跑原始的 Electron/Vite 循环,`pnpm dev:desktop` 仍然可用。
## 常用命令
```sh
make dev-gui
pnpm build
pnpm typecheck
pnpm lint
pnpm lint:ts
pnpm lint:go
pnpm test:ts
pnpm test:go
pnpm check:golangci-version
pnpm install:golangci-lint
pnpm generate:defaults
pnpm check:defaults-generated
```
完整验证入口:
```sh
pnpm check:full
```
## 仓库规则
- 业务逻辑归属 `services/tuttid`
- UI 与桌面集成归属 `apps/desktop`
- 只有存在真实共享边界时,代码才应进入 `packages/`
- 业务代码文件应保持在 `800` 行以内;超过即为重构信号
深入参考:
- 架构总览:[docs/architecture/README.md](docs/architecture/README.md)
- 项目结构:[docs/architecture/project-structure.md](docs/architecture/project-structure.md)
- 仓库约定:[docs/conventions/README.md](docs/conventions/README.md)
- 静态分析与 lint 规则:[docs/conventions/static-analysis.md](docs/conventions/static-analysis.md)
- Agent 贡献者说明:[AGENTS.md](AGENTS.md)
## 提交规范
我们遵循 [Conventional Commits](https://www.conventionalcommits.org/):
```
<type>(<scope>): <subject>
```
本仓库中的示例:
```
fix(workspace-files): avoid protected directory prefetch
fix(agent): preserve provider permission defaults
```
常用类型:`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
## 开发者原创证书(DCO)
我们要求贡献者签署 [Developer Certificate of Origin](https://developercertificate.org/)。这是一份轻量声明,表明你有权以本项目的协议(Apache-2.0)提交你的贡献。
用 `-s` 参数为每个 commit 签名:
```sh
git commit -s -m "feat(scope): add something"
```
这会在 commit message 末尾追加一行 `Signed-off-by: Your Name <your@email>`。
## Pull Request 流程
1. Fork 仓库并从 `main` 创建分支。建议的分支命名:`feat/...`、`fix/...`、`docs/...`
2. 完成你的改动;每个 PR 只关注一件事
3. 提交 PR,清晰描述动机与改动内容
4. CI 会根据变更文件运行相关的 TypeScript、Go、包和工具检查;所有选中的检查必须通过
5. 维护者会 review 你的 PR;请回应反馈,并把讨论保留在 PR 中
本地钩子使用 `husky`:
- `pre-commit` 运行暂存区格式化和 UI 边界检查
- `pre-push` 通过 `pnpm check:changed -- --push-ready` 运行变更感知的推送检查
## Pull Request 评审门禁
Tutti 使用 `external-pr-review-gate` workflow 区分内部团队改动和外部贡献。官方作者由组织变量 `TUTTI_RD_MEMBERS` 定义;GitHub 团队 `tutti-rd` 是外部 PR 的 review 请求目标。
- `tutti-rd` 成员发起的 PR 不会自动请求 reviewer,也不需要额外官方 approve 即可通过评审门禁
- 非 `tutti-rd` 作者发起的 PR 会自动请求 `@tutti-os/tutti-rd` review
- 外部 PR 只有在当前 head commit 获得 `tutti-rd` 成员 approve 后才能合并
- 推送新提交会刷新门禁;新的 head commit 需要重新获得通过评审
- 官方团队成员变化时,维护者必须同时更新 `TUTTI_RD_MEMBERS` 和 `tutti-rd` 团队
```mermaid
---
config:
layout: dagre
theme: redux
look: neo
---
flowchart TB
A["PR 打开 / 重新打开 / 标记为可评审 / 推送新提交"] --> B{"PR 作者是否在官方成员名单?"}
B -- 是 --> C["不自动请求 Reviewer"]
C --> P["✅ 通过"]
P --> M["可以合并"]
B -- 否 --> D["自动请求 @tutti-os/tutti-rd Review"]
D --> E{"当前 head commit 是否有官方 Review?"}
E -- 已 Approve --> P
E -- 没有通过评审 --> F["❌ 未通过"]
F --> N["不能合并"]
G["外部贡献者推送新提交"] --> A
G@{ shape: rounded}
```
## 文档语言策略
- `README.*` 和 `CONTRIBUTING.*` 以英文、简体中文、繁体中文三语维护
- **英文版是唯一基准(source of truth)**——修改 `README.md` 或 `CONTRIBUTING.md` 时,须在同一个 PR 中同步更新 `*.zh-CN.md` 和 `*.zh-TW.md`
- 译文与英文版冲突时,以英文版为准
- `LICENSE`、`NOTICE`、`CODE_OF_CONDUCT.md`、`SECURITY.md` 与 `docs/` 目录只维护英文
## 反馈问题
- Bug 报告与功能请求:使用 [issue 模板](.github/ISSUE_TEMPLATE)
- 安全漏洞:**请勿提交公开 issue**——参见 [SECURITY.md](SECURITY.md)
## 协议
向 Tutti 提交贡献,即表示你同意你的贡献以 [Apache License 2.0](LICENSE) 授权。
> 翻译说明:本文档与英文版内容同步,如有出入,以[英文版](CONTRIBUTING.md)为准。