AGENTS.md · yaklang/yakit

Sections

1. 项目信息
2. 项目结构
3. 前置要求
4. 依赖安装
5. 启动开发环境
6. 多版本/多平台变体
7. 构建渲染端产物
8. 主进程工程化与手动重启
9. 常见问题排查
10. 代码规范
11. 关键脚本速查

First lines (shown under the repo's AGPL-3.0 license)

# Yakit 项目启动指南（Agent 背景文件）

本文件为所有 AI Agent（及新开发者）提供项目启动所需的背景知识。
阅读本文件后，你应能独立完成依赖安装与本地开发环境的启动。

## 项目信息

Yakit 是一个基于 Electron + React 的跨平台桌面应用，主要技术栈包括 Electron、React、TypeScript 等。项目通过 Vite 构建渲染端，使用 Yarn 作为包管理器。

## 项目结构

项目由三部分组成：

| 模块 | 路径 | 作用 | 端口 |
| --- | --- | --- | --- |
| Electron 主进程 | `app/main/` | 源码 index.js，构建入口 dist/electron/main/index.js，承载窗口、IPC、gRPC | - |
| 主渲染端 | `app/renderer/src/main/` | Vite 8 MPA 主界面 | `3000` |
| Link 渲染端 | `app/renderer/engine-link-startup/` | 引擎链接启动页 | `5173` |

> 主进程在开发模式下会分别加载：
> - 主窗口：`http://127.0.0.1:3000`（`app/main/index.js:247`）
> - 引擎链接窗口：`http://127.0.0.1:5173`（`app/main/index.js:143`）
>
> 因此**两个渲染端都必须成功启动后，才能启动 Electron 主进程**，否则窗口会白屏。

## 前置要求

- Node.js（版本以团队约定为准，仓库暂未提供 `.nvmrc`）
- Yarn（本项目使用 `yarn` 作为包管理器，根目录已提供 `yarn.lock`）
- macOS（Apple Silicon / M 芯片）如遇到原生依赖编译失败，可参考 `ELECTRON_GUIDE.md` 执行：
  ```bash
  brew install pkg-config pixman cairo pango
  ```
- 如需从国内镜像安装 Electron，可先在当前终端执行对应脚本设置镜像源：
  - macOS: `source scripts/set-electron-mirror-macos.sh`
  - Linux: `source scripts/set-electron-mirror-linux.sh`
  - Windows PowerShell: `. .\scripts\set-electron-mirror.ps1`
  - Windows CMD: `scripts\set-electron-mirror.cmd`

## 依赖安装

项目共有三个需要安装依赖的子项目。一条命令即可按顺序全部安装（根目录 → Link 渲染端 → 主渲染端）：

```bash
yarn cli install
# 等价于：yarn cli install electron && yarn cli install link && yarn cli install main
# 也可只装其中一个：yarn cli install electron | main | link
```

命令细节见 [`cli/README.md`](cli/README.md)。本仓库日常仍以 `yarn cli` 为例；`pnpm cli` / `npm run cli --` / `node ./cli/cli.mjs` 语义相同。

## 启动开发环境

> 开发模式下 Electron 主进程会分别加载主窗口 `http://127.0.0.1:3000` 与引擎链接窗口 `http://127.0.0.1:5173`，因此**两个渲染端都必须先成功启动**，再启动 Electron，否则对应窗口会白屏。

### 启动前依赖检查（重要）

启动项目前，先检查本地依赖是否与仓库一致（尤其是 `git pull` 之后，别人可能新增或升级了依赖）：

```bash
yarn check-deps
```

- 若提示「未安装依赖」：按提示先执行 `yarn cli install`。
- 若提示「依赖可能有更新」：**使用 `AskUserQuestion` 工具向用户弹选项框确认**是否重新安装对应子项目的依赖，而不是在回复里用文字描述选项让用户再答一遍。选项示例：
  - `重装全部依赖`（执行 `yarn cli install`）
  - `仅重装有改动的子项目`（按 check-deps 提示的列表：`yarn cli install electron` / `main` / `link`）
  - `跳过，直接启动`
- 若提示「依赖一致」：进入启动步骤。但若用户提到最近 `git pull` 过而未重装（见下文「常见问题排查」的盲区），**使用 `AskUserQuestion` 工具弹选项框**询问是否仍重跑 `yarn cli install`。

> 通用规则：**凡涉及需要用户决策的环节（是否重装依赖、启动哪个版本、是否跳过某步等），一律优先用 `AskUserQuestion` 工具弹出选项框让用户一键选择，不要在回复里用文字罗列选项让用户再答一遍。**

### 启动步骤

> 若用户未指定启动哪个版本，**使用 `AskUserQuestion` 工具弹选项框**让用户选择版本，不要默认替用户决定。
>
> ⚠️ `AskUserQuestion` 每个问题最多只能放 4 个选项（外加自动提供的「Other」自定义输入），而项目共有 6 个版本（见「多版本/多平台变体」表），无法一次性全部展示。采用**分层弹框**策略：
>
> 1. **第一层弹框**：选项只放 4 个主版本——`Yakit`（默认）、`enterprise`（企业版）、`irify`（IRify 社区版）、`memfit`（AI 精简版）。question 文本中完整列出全部 6 个版本名，提示 `simple-enterprise` 与 `irify-enterprise` 会根据后续选择追问。
> 2. **第二层弹框（按需追问）**：
>    - 若用户在第一层选了 `enterprise`，再弹一次选项框，让用户在 `enterprise`（企业版 EE）与 `simple-enterprise`（便携 / 简易企业版 SE）之间二选一。
>    - 若用户在第一层选了 `irify`，再弹一次选项框，让用户在 `irify`（IRify 社区版）与 `irify-enterprise`（IRify 企业版）之间二选一。
>    - 若用户选了 `Yakit` 或 `memfit`，无需追问，直接确定。
> 3. 这样既不超出工具单次 4 选项上限，又能覆盖全部 6 个版本，且用户全程点选、无需手动输入「Other」。

选完版本后，映射到 CLI `-v`（**不要**再跑已删除的 `start-renders*` / `pack-*`）：

| 用户选择 | CLI `-v` | 启动两端渲染 |
| --- | --- | --- |
| Yakit | `yakit` | `yarn cli start -v yakit` |
| enterprise | `yakitEE` | `yarn cli start -v yakitEE` |
| simple-enterprise | `yakitSE` | `yarn cli start -v yakitSE` |
| irify | `irify` | `yarn cli start -v irify` |
| irify-enterprise | `irifyEE` | `yarn cli start -v irifyEE` |
| memfit | `memfit` | `yarn cli start -v memfit` |

先启动两个渲染端（:3000 主渲染端 + :5173 Link 渲染端），例如社区版：

```bash
yarn cli start -v yakit
# 只启一端：yarn cli start -v yakit --main  或  --link
```

待两个渲染端**真正就绪**后，再启动 Electron 主进程：

```bash
yarn cli electron
```

> ⚠️ **重要：必须确认渲染端「真正就绪」后再启动 Electron，否则窗口会白屏。**
>
> 端口进入 LISTEN 状态 ≠ 渲染端加载完成。Vite / CRA 的 dev server 端口会很快开始监听，但此时首次编译可能尚未结束，Electron 此时加载会拿到不完整的页面导致白屏。
>
> 必须按以下两步确认就绪：
>
> 1. **端口检查**：确认 `3000` 与 `5173` 端口均在监听。
>    ```bash
>    lsof -i :3000 -sTCP:LISTEN
>    lsof -i :5173 -sTCP:LISTEN
>    ```
>
> 2. **内容轮询**：用 `curl` 轮询，直到两端都返回 HTTP 200 且响应体包含有效内容（如 `<script` 或 `<div id="root"`），才说明首次编译完成、页面真正可访问。
>    ```bash
>    # 轮询直到主渲染端（:3000）就绪
>    until curl -s http://127.0.0.1:3000 | grep -qE '<script|<div id="root"'; do sleep 2; done
>
>    # 轮询直到 Link 渲染端（:5173）就绪
>    until curl -s http://127.0.0.1:5173 | grep -qE '<script|<div id="root"'; do sleep 2; done
>    ```
>
> 两端都通过上述检查后，再执行 `yarn cli electron`。
>
> 也可用 `yarn cli dev -v <edition>` 一条命令（start + 页面内容检查 + 单次构建 + electron）。CLI 已内置 HTTP 200 和 HTML 内容检查；Agent 可用上面的 curl 额外诊断。

## 多版本/多平台变体

> 依赖安装步骤与版本无关，请先按上文「依赖安装」完成；版本差异只体现在 CLI `-v` 上。

发行版由 CLI 注入 `YAKIT_EDITION`（三端同一名字、同一取值），**不再**使用 `env-cmd` / `--mode` / `REACT_APP_PLATFORM` / `VITE_PLATFORM`。Electron 主进程不区分版本，它只加载当前已运行的渲染端地址。

| 用户选择（问询标签） | CLI `-v` | 产品名 | 性质 | 本地引擎端口 |
| --- | --- | --- | --- | --- |
| Yakit | `yakit` | Yakit | 社区版 CE | `9011` |
| enterprise | `yakitEE` | EnpriTrace | 企业版 EE | `9012` |
| simple-enterprise | `yakitSE` | EnpriTraceAgent | 便携 / 简易企业版 SE | `9013` |
| irify | `irify` | IRify | IRify 社区版 | `9014` |
| irify-enterprise | `irifyEE` | IRifyEnpriTrace | IRify 企业版 | `9015` |
| memfit | `memfit` | Memfit AI | AI Agent 精简版 | `9016` |

```bash
# 启动两端渲染（以企业版为例）
yarn cli start -v yakitEE

# 只启主渲染 / Link
yarn cli start -v yakitEE --main
yarn cli start -v yakitEE --link

# 按上文「启动步骤」确认两端真正就绪后
yarn cli electron