为 Jiey 做贡献

Jiey 主要有两部分可参与贡献：

Agent — AI 功能、UI 与浏览器自动化（TypeScript/React）
Browser — 定制 Chromium 构建（C++/Python）

多数贡献者从 Agent 入手，因为环境搭建简单得多。

快捷链接

贡献方式

报告缺陷 — 提交 Issue，说明复现步骤、预期与实际行为，并附截图。

建议功能 — 在 GitHub 或 Discord 分享想法。

改进文档 — 文档位于 docs/，使用 Mintlify。编辑页面，并更新 docs/docs.json 中的导航。

---

路径 1：Agent 开发

Agent 是包含 3 个组件的 monorepo：

组件	路径	作用
Agent UI	`apps/app`	Chrome 扩展 — 聊天界面、设置、侧边栏
Server	`apps/server`	Bun 服务器 — Agent 循环、MCP 工具、API 端点
Controller	`apps/controller-ext`	Chrome 扩展 — 将 `chrome.*` API 桥接到服务器

架构

环境搭建


# 克隆仓库
git clone https://github.com/YOUR-USERNAME/Jiey.git
cd Jiey/packages/browseros-agent

# 安装依赖
bun install

# 复制环境文件
cp apps/server/.env.example apps/server/.env.development
cp apps/app/.env.example apps/app/.env.development

本地运行


# 终端 1：启动服务器
bun run start:server

# 终端 2：启动 Agent 扩展（开发模式）
bun run start:agent

然后在 Jiey 中加载扩展：

1. 打开 chrome://extensions/

2. 启用 Developer mode

3. 点击 Load unpacked，选择 apps/app/dist/ 文件夹

命令

命令	说明
`bun run start:server`	启动服务器
`bun run start:agent`	启动 Agent 扩展（开发模式）
`bun run build:server`	构建生产版服务器
`bun run build:agent`	构建 Agent 扩展
`bun run build:ext`	构建 Controller 扩展
`bun run test`	运行测试
`bun run lint`	使用 Biome 检查
`bun run typecheck`	TypeScript 检查

---

路径 2：Browser 开发

仅在处理 Chromium 级功能（如浏览器本身补丁）时再走这条路径。

要求：

约 100GB 磁盘空间
建议 16GB+ 内存
首次构建约 3 小时以上

前置条件

macOS

安装了 Xcode 与 Command Line Tools 的 macOS
Python 3.12+
UV（Python 包管理器）
Git

Linux

Ubuntu 20.04+ 或同类发行版
build-essential 包
Python 3.12+
UV
Git

Windows

Windows 10/11
带 C++ 工作负载的 Visual Studio 2022
Python 3.12+
UV
Git

构建说明

1. 克隆 Chromium 源码

按官方 Chromium: Get the Code 指南操作。这会配置 depot_tools 并拉取约 100GB 源码。

记下克隆路径（例如 ~/chromium/src）。

2. 安装 UV 与依赖


# 安装 UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# 进入构建系统
cd packages/browseros

# 安装依赖
uv sync

3. 构建 debug 版本


uv run browseros build \
  --chromium-src <your-chromium-src-path> \
  --setup \
  --prep \
  --build \
  --build-type debug

--setup 与 --prep 仅首次构建需要。之后增量构建只需 --build：


uv run browseros build --chromium-src <path> --build --build-type debug

4. 运行 Jiey

macOS (ARM64)


    <chromium-src>/out/Default_arm64/Jiey\ Dev.app/Contents/MacOS/Jiey\ Dev \
      --enable-logging=stderr \
      --use-mock-keychain \
      --user-data-dir=/tmp/test-profile

macOS (x64)


    <chromium-src>/out/Default_x64/Jiey\ Dev.app/Contents/MacOS/Jiey\ Dev \
      --enable-logging=stderr \
      --use-mock-keychain \
      --user-data-dir=/tmp/test-profile

Windows


    <chromium-src>\out\Default_x64\Jiey Dev.exe \
      --enable-logging=stderr \
      --user-data-dir=%TEMP%\test-profile

Linux


    <chromium-src>/out/Default_x64/browseros \
      --enable-logging=stderr \
      --user-data-dir=/tmp/test-profile

构建参数

参数	说明
`--chromium-src`	Chromium 源码目录路径
`--setup`	运行 setup 阶段（仅首次构建）
`--prep`	运行 prep 阶段（仅首次构建）
`--build`	运行编译阶段
`--build-type`	`debug` 或 `release`
`--sign`	对构建产物签名
`--package`	打包以便分发

故障排除

构建因缺少依赖失败 — 请确认已按对应平台完整执行 Chromium 构建指南中的步骤。

磁盘空间不足 — Chromium 约需 100GB。可用 df -h 检查。

构建耗时过长 — 可使用 ccache、更多 CPU 核心，或坚持用 debug 构建。

找不到 UV 命令 — 安装 UV 后请重启终端。

---

提交第一个 PR

1. 在 GitHub 上 Fork 仓库

2. 在本地 Clone 你的 fork

3. 创建分支：git checkout -b feature/your-feature

4. 修改并测试

5. 提交：git commit -m "feat: add your feature"

6. 推送：git push origin feature/your-feature

7. 打开 PR，并写清楚说明

签署 CLA

首次提交 PR 时，机器人会请你签署 Contributor License Agreement。评论如下即可：


I have read the CLA Document and I hereby sign the CLA

---

代码规范

TypeScript：

使用严格类型，避免 any
用 Zod schema，而不是 TypeScript interface
使用路径别名（@/lib），不要用相对路径（../）
命名：类用 PascalCase，函数用 camelCase

React：

仅使用 Tailwind CSS（不用 SCSS 或 CSS modules）
Hooks 只能在顶层调用
使用 Vitest 测试

通用：

函数保持简短（少于 20 行）
为新功能编写测试
妥善处理错误

---

获取帮助

Discord — discord.gg/YKwjt5vuKr
GitHub Issues — github.com/browseros-ai/BrowserOS/issues
GitHub Discussions — github.com/browseros-ai/BrowserOS/discussions

---

参与贡献即表示你同意贡献内容以 AGPL-3.0 许可。