{"owner":"yaklang","repo":"yakit","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Yakit 项目启动指南（Agent 背景文件）\n\n本文件为所有 AI Agent（及新开发者）提供项目启动所需的背景知识。\n阅读本文件后，你应能独立完成依赖安装与本地开发环境的启动。\n\n## 项目结构\n\nYakit 是一个 Electron 桌面应用，由三部分组成：\n\n| 模块 | 路径 | 说明 | 开发端口 |\n| --- | --- | --- | --- |\n| Electron 主进程 | `app/main/` | 入口 `app/main/index.js`，承载窗口、IPC、gRPC 通信等 | - |\n| 主渲染端 | `app/renderer/src/main/` | 基于 Vite 8（MPA：main/aux）的主界面渲染端 | `3000` |\n| Link 渲染端 | `app/renderer/engine-link-startup/` | 基于 Vite 的引擎链接启动页渲染端 | `5173` |\n\n> 主进程在开发模式下会分别加载：\n> - 主窗口：`http://127.0.0.1:3000`（`app/main/index.js:247`）\n> - 引擎链接窗口：`http://127.0.0.1:5173`（`app/main/index.js:143`）\n>\n> 因此**两个渲染端都必须成功启动后，才能启动 Electron 主进程**，否则窗口会白屏。\n\n## 前置要求\n\n- Node.js（版本以团队约定为准，仓库暂未提供 `.nvmrc`）\n- Yarn（本项目使用 `yarn` 作为包管理器，根目录已提供 `yarn.lock`）\n- macOS（Apple Silicon / M 芯片）如遇到原生依赖编译失败，可参考 `ELECTRON_GUIDE.md` 执行：\n  ```bash\n  brew install pkg-config pixman cairo pango\n  ```\n- 如需从国内镜像安装 Electron，可先 `source ./electron.env` 设置镜像源。\n\n## 依赖安装\n\n项目共有三个需要安装依赖的子项目，**务必按顺序全部安装**：\n\n```bash\n# 1. 根目录（Electron 主进程相关依赖，含 electron、electron-builder、concurrently、wait-on 等）\nyarn install\n\n# 2. 主渲染端（Vite 8）\nyarn install-render\n# 等价于：cd app/renderer/src/main && yarn install\n\n# 3. Link 渲染端（Vite）\nyarn install-link-render\n# 等价于：cd app/renderer/engine-link-startup && yarn install\n```\n\n\n## 启动开发环境\n\n> 开发模式下 Electron 主进程会分别加载主窗口 `http://127.0.0.1:3000` 与引擎链接窗口 `http://127.0.0.1:5173`，因此**两个渲染端都必须先成功启动**，再启动 Electron，否则对应窗口会白屏。\n\n### 启动前依赖检查（重要）\n\n启动项目前，先检查本地依赖是否与仓库一致（尤其是 `git pull` 之后，别人可能新增或升级了依赖）：\n\n```bash\nyarn check-deps\n```\n\n- 若提示「未安装依赖」：按提示先完成上文「依赖安装」三步曲。\n- 若提示「依赖可能有更新」：**使用 `AskUserQuestion` 工具向用户弹选项框确认**是否重新安装对应子项目的依赖，而不是在回复里用文字描述选项让用户再答一遍。选项示例：\n  - `重装全部依赖`（按顺序执行 `yarn install` / `yarn install-render` / `yarn install-link-render`）\n  - `仅重装有改动的子项目`（按 check-deps 提示的列表）\n  - `跳过，直接启动`\n- 若提示「依赖一致」：进入启动步骤。但若用户提到最近 `git pull` 过而未重装（见下文「常见问题排查」的盲区），**使用 `AskUserQuestion` 工具弹选项框**询问是否仍重跑依赖三步曲。\n\n> 通用规则：**凡涉及需要用户决策的环节（是否重装依赖、启动哪个版本、是否跳过某步等），一律优先用 `AskUserQuestion` 工具弹出选项框让用户一键选择，不要在回复里用文字罗列选项让用户再答一遍。**\n\n### 启动步骤\n\n> 若用户未指定启动哪个版本，**使用 `AskUserQuestion` 工具弹选项框**让用户选择版本，不要默认替用户决定。\n>\n> ⚠️ `AskUserQuestion` 每个问题最多只能放 4 个选项（外加自动提供的「Other」自定义输入），而项目共有 6 个版本（见「多版本/多平台变体」表），无法一次性全部展示。采用**分层弹框**策略：\n>\n> 1. **第一层弹框**：选项只放 4 个主版本——`Yakit`（默认）、`enterprise`（企业版）、`irify`（IRify 社区版）、`memfit`（AI 精简版）。question 文本中完整列出全部 6 个版本名，提示 `simple-enterprise` 与 `irify-enterprise` 会根据后续选择追问。\n> 2. **第二层弹框（按需追问）**：\n>    - 若用户在第一层选了 `enterprise`，再弹一次选项框，让用户在 `enterprise`（企业版 EE）与 `simple-enterprise`（便携 / 简易企业版 SE）之间二选一。\n>    - 若用户在第一层选了 `irify`，再弹一次选项框，让用户在 `irify`（IRify 社区版）与 `irify-enterprise`（IRify 企业版）之间二选一。\n>    - 若用户选了 `Yakit` 或 `memfit`，无需追问，直接确定。\n> 3. 这样既不超出工具单次 4 选项上限，又能覆盖全部 6 个版本，且用户全程点选、无需手动输入「Other」。\n\n先同时启动两个渲染端（:3000 主渲染端 + :5173 Link 渲染端）：\n\n```bash\nyarn start-renders\n# 等价于：concurrently \"yarn start-render\" \"yarn start-link-render\"\n```\n\n待两个渲染端**真正就绪**后，再启动 Electron 主进程：\n\n```bash\nyarn start-electron\n```\n\n> ⚠️ **重要：必须确认渲染端「真正就绪」后再启动 Electron，否则窗口会白屏。**\n>\n> 端口进入 LISTEN 状态 ≠ 渲染端加载完成。Vite / CRA 的 dev server 端口会很快开始监听，但此时首次编译可能尚未结束，Electron 此时加载会拿到不完整的页面导致白屏。\n>\n> 必须按以下两步确认就绪：\n>\n> 1. **端口检查**：确认 `3000` 与 `5173` 端口均在监听。\n>    ```bash\n>    lsof -i :3000 -sTCP:LISTEN\n>    lsof -i :5173 -sTCP:LISTEN\n>    ```\n>\n> 2. **内容轮询**：用 `curl` 轮询，直到两端都返回 HTTP 200 且响应体包含有效内容（如 `<script` 或 `<div id=\"root\"`），才说明首次编译完成、页面真正可访问。\n>    ```bash\n>    # 轮询直到主渲染端（:3000）就绪\n>    until curl -s http://127.0.0.1:3000 | grep -qE '<script|<div id=\"root\"'; do sleep 2; done\n>\n>    # 轮询直到 Link 渲染端（:5173）就绪\n>    until curl -s http://127.0.0.1:5173 | grep -qE '<script|<div id=\"root\"'; do sleep 2; done\n>    ```\n>\n> 两端都通过上述检查后，再执行 `yarn start-electron`。\n\n## 多版本/多平台变体\n\n> 依赖安装步骤与版本无关，请先按上文「依赖安装」完成；版本差异只体现在下面的启动 / 构建 / 打包命令上。\n\n项目通过 `--mode` / `env-cmd` 环境切换支持多个发行版本。开发时如无特殊需求，使用默认模式即可。\n\n版本由渲染端注入的 env 决定（主渲染端 `REACT_APP_PLATFORM`、Link 渲染端 `VITE_PLATFORM`），**Electron 主进程不区分版本**，它只加载当前已运行的渲染端地址。\n\n| 版本（脚本后缀） | 产品名 | 性质 | 本地引擎端口 | 同时启动两渲染端 | 构建两渲染端 | 对应平台打包 |\n| --- | --- | --- | --- | --- | --- | --- |\n| 默认 | Yakit | 社区版 CE | `9011` | `yarn start-renders` | `yarn build-renders` | `pack-mac` / `pack-win` / `pack-linux` |\n| `-enterprise` | EnpriTrace | 企业版 EE | `9012` | `yarn start-renders-enterprise` | `yarn build-renders-enterprise` | `pack-*-ee` |\n| `-simple-enterprise` | EnpriTraceAgent | 便携 / 简易企业版 SE | `9013` | `yarn start-renders-simple-enterprise` | `yarn build-renders-simple-enterprise` | `pack-*-se` |\n| `-irify` | IRify | IRify 社区版 | `9014` | `yarn start-renders-irify` | `yarn build-renders-irify` | `pack-*-irify` |\n| `-irify-enterprise` | IRifyEnpriTrace | IRify 企业版 | `9015` | `yarn start-renders-irify-enterprise` | `yarn build-renders-irify-enterprise` | `pack-*-irify-ee` |\n| `-memfit` | Memfit AI | AI Agent 精简版 | `9016` | `yarn start-renders-memfit` | `yarn build-renders-memfit` | `pack-*-memfit` |\n\n> 也可以只启动单个渲染端：主渲染端用 `yarn start-render-<后缀>`，Link 渲染端用 `yarn start-link-render-<后缀>`（默认版本无后缀）。\n\n### 启动某个版本（非默认版本无一键 dev）\n\n```bash\n# 1. 同时启动该版本的两个渲染端（:3000 主渲染端 + :5173 Link 渲染端）\nyarn start-renders-enterprise        # 以企业版为例，其它版本见上表\n\n# 2. 按上文「启动步骤」中的两步法确认两个渲染端真正就绪（端口监听 + curl 拿到有效内容）后，启动 Electron 主进程\nyarn start-electron\n```\n\n### 各版本功能差异（概要）\n\n- **默认 / Yakit**：完整社区版基线，所有功能开放。\n- **enterprise / EnpriTrace**：企业版，使用企业 token、企业远端配置、独立的企业数据库 `company-default-yakit.db`。\n- **simpleEE / EnpriTraceAgent**：便携 / 简易企业版，隶属企业系（`isEnterpriseOrSimpleEdition()` 为 true）。\n- **irify / IRify**：IRify 社区版，紫色主题，含 `irifyHome`、`irifyAiCodeAudit`（AI 代码审计）等专属页面。\n- **irifyEnterprise / IRifyEnpriTrace**：IRify 的企业版分支。\n- **memfit / Memfit AI**：面向 AI Agent 的精简版，菜单与界面元素最多精简（大量 `!isMemfit()` 守卫）。\n\n## 构建渲染端产物\n\n若需打包发布，需先构建两个渲染端的静态产物，再执行 electron-builder：\n\n```bash\n# 构建两个渲染端（默认版本）\nyarn build-renders\n# 等价于：run-s build-render build-link-render\n\n# 之后使用对应平台的打包命令，例如 macOS：\nyarn pack-mac\n```\n\n## 常见问题排查\n\n> 当用户带着启动 / 编译报错来询问时，**第一步应先跑 `yarn check-deps` 排查是否由依赖问题引起**，再去看具体报错。\n>\n> ⚠️ 注意 `yarn check-deps` 的盲区：它通过 `git diff HEAD -- yarn.lock` 判断依赖是否更新，**只能检测工作区未提交的 yarn.lock 改动**。若用户刚 `git pull` 拉到了别人**已提交**的新 yarn.lock 但没重新 `yarn install`，此时新 lock 已进 HEAD，`git diff HEAD` 为空，脚本会误报「依赖一致」而实际 `node_modules` 已滞后。\n>\n> 因此：**若用户最近 `git pull` 过但没重新安装依赖，即便 `check-deps` 报「依赖一致」，也应使用 `AskUserQuestion` 工具弹选项框**询问用户是否按顺序重跑依赖安装三步曲（`yarn install` / `yarn install-render` / `yarn install-link-render`）后再启动，而不是在回复里用文字描述让用户再答一遍。\n\n- **窗口白屏 / `ERR_CONNECTION_REFUSED`**：对应渲染端未就绪。注意端口监听 ≠ 加载完成，需按「启动步骤」用 `curl` 轮询确认两端返回有效 HTML 后再启动 Electron。\n- **启动 / 编译报错（模块找不到、API 报错、语法报错等）**：优先 `yarn check-deps` 排查依赖是否一致；结合上述盲区判断是否需要重装依赖。\n- **M1 芯片原生依赖编译失败**：执行 `brew install pkg-config pixman cairo pango`。\n- **Electron 下载慢 / 失败**：`source ./electron.env` 后重试。\n- **端口被占用**：确认没有残留的 vite / electron 进程，必要时 `lsof -i :3000` / `lsof -i :5173` 排查。\n\n## 代码规范\n\n- 强制使用 LF 换行符。\n- 缩进为 2 个空格。\n- 代码不使用分号，使用单引号。\n- 遵循项目中的 `.prettierrc.js` 和 `.editorconfig`。\n\n## 关键脚本速查\n\n**公共命令（与版本无关）**：\n\n| 命令 | 作用 |\n| --- | --- |\n| `yarn install` | 安装根目录依赖 |\n| `yarn install-render` | 安装主渲染端依赖 |\n| `yarn install-link-render` | 安装 Link 渲染端依赖 |\n| `yarn start-electron` | 启动 Electron 主进程（不区分版本） |\n| `yarn check-deps` | 检查本地依赖是否与仓库一致（启动前执行） |\n\n**各版本启动 / 构建 / 打包**（默认版本无后缀；后缀取值见「多版本/多平台变体」表）：\n\n| 命令模式 | 作用 |\n| --- | --- |\n| `yarn start-renders[-<后缀>]` | 同时启动两个渲染端（:3000 + :5173） |\n| `yarn start-render[-<后缀>]` | 仅启动主渲染端（:3000） |\n| `yarn start-link-render[-<后缀>]` | 仅启动 Link 渲染端（:5173） |\n| `yarn build-renders[-<后缀>]` | 构建两个渲染端静态产物 |\n| `yarn build-render[-<后缀>]` | 仅构建主渲染端 |\n| `yarn build-link-render[-<后缀>]` | 仅构建 Link 渲染端 |\n| `yarn pack-mac[-<后缀>]` / `pack-win[-<后缀>]` / `pack-linux[-<后缀>]` | 对应平台打包 |\n\n> 版本后缀对照：默认（无） / `-enterprise`（EE，打包为 `pack-*-ee`）/ `-simple-enterprise`（SE，`pack-*-se`）/ `-irify`（`pack-*-irify`）/ `-irify-enterprise`（`pack-*-irify-ee`）/ `-memfit`（`pack-*-memfit`）。\n"},"files":{"AGENTS.md":"# Yakit 项目启动指南（Agent 背景文件）\n\n本文件为所有 AI Agent（及新开发者）提供项目启动所需的背景知识。\n阅读本文件后，你应能独立完成依赖安装与本地开发环境的启动。\n\n## 项目结构\n\nYakit 是一个 Electron 桌面应用，由三部分组成：\n\n| 模块 | 路径 | 说明 | 开发端口 |\n| --- | --- | --- | --- |\n| Electron 主进程 | `app/main/` | 入口 `app/main/index.js`，承载窗口、IPC、gRPC 通信等 | - |\n| 主渲染端 | `app/renderer/src/main/` | 基于 Vite 8（MPA：main/aux）的主界面渲染端 | `3000` |\n| Link 渲染端 | `app/renderer/engine-link-startup/` | 基于 Vite 的引擎链接启动页渲染端 | `5173` |\n\n> 主进程在开发模式下会分别加载：\n> - 主窗口：`http://127.0.0.1:3000`（`app/main/index.js:247`）\n> - 引擎链接窗口：`http://127.0.0.1:5173`（`app/main/index.js:143`）\n>\n> 因此**两个渲染端都必须成功启动后，才能启动 Electron 主进程**，否则窗口会白屏。\n\n## 前置要求\n\n- Node.js（版本以团队约定为准，仓库暂未提供 `.nvmrc`）\n- Yarn（本项目使用 `yarn` 作为包管理器，根目录已提供 `yarn.lock`）\n- macOS（Apple Silicon / M 芯片）如遇到原生依赖编译失败，可参考 `ELECTRON_GUIDE.md` 执行：\n  ```bash\n  brew install pkg-config pixman cairo pango\n  ```\n- 如需从国内镜像安装 Electron，可先 `source ./electron.env` 设置镜像源。\n\n## 依赖安装\n\n项目共有三个需要安装依赖的子项目，**务必按顺序全部安装**：\n\n```bash\n# 1. 根目录（Electron 主进程相关依赖，含 electron、electron-builder、concurrently、wait-on 等）\nyarn install\n\n# 2. 主渲染端（Vite 8）\nyarn install-render\n# 等价于：cd app/renderer/src/main && yarn install\n\n# 3. Link 渲染端（Vite）\nyarn install-link-render\n# 等价于：cd app/renderer/engine-link-startup && yarn install\n```\n\n\n## 启动开发环境\n\n> 开发模式下 Electron 主进程会分别加载主窗口 `http://127.0.0.1:3000` 与引擎链接窗口 `http://127.0.0.1:5173`，因此**两个渲染端都必须先成功启动**，再启动 Electron，否则对应窗口会白屏。\n\n### 启动前依赖检查（重要）\n\n启动项目前，先检查本地依赖是否与仓库一致（尤其是 `git pull` 之后，别人可能新增或升级了依赖）：\n\n```bash\nyarn check-deps\n```\n\n- 若提示「未安装依赖」：按提示先完成上文「依赖安装」三步曲。\n- 若提示「依赖可能有更新」：**使用 `AskUserQuestion` 工具向用户弹选项框确认**是否重新安装对应子项目的依赖，而不是在回复里用文字描述选项让用户再答一遍。选项示例：\n  - `重装全部依赖`（按顺序执行 `yarn install` / `yarn install-render` / `yarn install-link-render`）\n  - `仅重装有改动的子项目`（按 check-deps 提示的列表）\n  - `跳过，直接启动`\n- 若提示「依赖一致」：进入启动步骤。但若用户提到最近 `git pull` 过而未重装（见下文「常见问题排查」的盲区），**使用 `AskUserQuestion` 工具弹选项框**询问是否仍重跑依赖三步曲。\n\n> 通用规则：**凡涉及需要用户决策的环节（是否重装依赖、启动哪个版本、是否跳过某步等），一律优先用 `AskUserQuestion` 工具弹出选项框让用户一键选择，不要在回复里用文字罗列选项让用户再答一遍。**\n\n### 启动步骤\n\n> 若用户未指定启动哪个版本，**使用 `AskUserQuestion` 工具弹选项框**让用户选择版本，不要默认替用户决定。\n>\n> ⚠️ `AskUserQuestion` 每个问题最多只能放 4 个选项（外加自动提供的「Other」自定义输入），而项目共有 6 个版本（见「多版本/多平台变体」表），无法一次性全部展示。采用**分层弹框**策略：\n>\n> 1. **第一层弹框**：选项只放 4 个主版本——`Yakit`（默认）、`enterprise`（企业版）、`irify`（IRify 社区版）、`memfit`（AI 精简版）。question 文本中完整列出全部 6 个版本名，提示 `simple-enterprise` 与 `irify-enterprise` 会根据后续选择追问。\n> 2. **第二层弹框（按需追问）**：\n>    - 若用户在第一层选了 `enterprise`，再弹一次选项框，让用户在 `enterprise`（企业版 EE）与 `simple-enterprise`（便携 / 简易企业版 SE）之间二选一。\n>    - 若用户在第一层选了 `irify`，再弹一次选项框，让用户在 `irify`（IRify 社区版）与 `irify-enterprise`（IRify 企业版）之间二选一。\n>    - 若用户选了 `Yakit` 或 `memfit`，无需追问，直接确定。\n> 3. 这样既不超出工具单次 4 选项上限，又能覆盖全部 6 个版本，且用户全程点选、无需手动输入「Other」。\n\n先同时启动两个渲染端（:3000 主渲染端 + :5173 Link 渲染端）：\n\n```bash\nyarn start-renders\n# 等价于：concurrently \"yarn start-render\" \"yarn start-link-render\"\n```\n\n待两个渲染端**真正就绪**后，再启动 Electron 主进程：\n\n```bash\nyarn start-electron\n```\n\n> ⚠️ **重要：必须确认渲染端「真正就绪」后再启动 Electron，否则窗口会白屏。**\n>\n> 端口进入 LISTEN 状态 ≠ 渲染端加载完成。Vite / CRA 的 dev server 端口会很快开始监听，但此时首次编译可能尚未结束，Electron 此时加载会拿到不完整的页面导致白屏。\n>\n> 必须按以下两步确认就绪：\n>\n> 1. **端口检查**：确认 `3000` 与 `5173` 端口均在监听。\n>    ```bash\n>    lsof -i :3000 -sTCP:LISTEN\n>    lsof -i :5173 -sTCP:LISTEN\n>    ```\n>\n> 2. **内容轮询**：用 `curl` 轮询，直到两端都返回 HTTP 200 且响应体包含有效内容（如 `<script` 或 `<div id=\"root\"`），才说明首次编译完成、页面真正可访问。\n>    ```bash\n>    # 轮询直到主渲染端（:3000）就绪\n>    until curl -s http://127.0.0.1:3000 | grep -qE '<script|<div id=\"root\"'; do sleep 2; done\n>\n>    # 轮询直到 Link 渲染端（:5173）就绪\n>    until curl -s http://127.0.0.1:5173 | grep -qE '<script|<div id=\"root\"'; do sleep 2; done\n>    ```\n>\n> 两端都通过上述检查后，再执行 `yarn start-electron`。\n\n## 多版本/多平台变体\n\n> 依赖安装步骤与版本无关，请先按上文「依赖安装」完成；版本差异只体现在下面的启动 / 构建 / 打包命令上。\n\n项目通过 `--mode` / `env-cmd` 环境切换支持多个发行版本。开发时如无特殊需求，使用默认模式即可。\n\n版本由渲染端注入的 env 决定（主渲染端 `REACT_APP_PLATFORM`、Link 渲染端 `VITE_PLATFORM`），**Electron 主进程不区分版本**，它只加载当前已运行的渲染端地址。\n\n| 版本（脚本后缀） | 产品名 | 性质 | 本地引擎端口 | 同时启动两渲染端 | 构建两渲染端 | 对应平台打包 |\n| --- | --- | --- | --- | --- | --- | --- |\n| 默认 | Yakit | 社区版 CE | `9011` | `yarn start-renders` | `yarn build-renders` | `pack-mac` / `pack-win` / `pack-linux` |\n| `-enterprise` | EnpriTrace | 企业版 EE | `9012` | `yarn start-renders-enterprise` | `yarn build-renders-enterprise` | `pack-*-ee` |\n| `-simple-enterprise` | EnpriTraceAgent | 便携 / 简易企业版 SE | `9013` | `yarn start-renders-simple-enterprise` | `yarn build-renders-simple-enterprise` | `pack-*-se` |\n| `-irify` | IRify | IRify 社区版 | `9014` | `yarn start-renders-irify` | `yarn build-renders-irify` | `pack-*-irify` |\n| `-irify-enterprise` | IRifyEnpriTrace | IRify 企业版 | `9015` | `yarn start-renders-irify-enterprise` | `yarn build-renders-irify-enterprise` | `pack-*-irify-ee` |\n| `-memfit` | Memfit AI | AI Agent 精简版 | `9016` | `yarn start-renders-memfit` | `yarn build-renders-memfit` | `pack-*-memfit` |\n\n> 也可以只启动单个渲染端：主渲染端用 `yarn start-render-<后缀>`，Link 渲染端用 `yarn start-link-render-<后缀>`（默认版本无后缀）。\n\n### 启动某个版本（非默认版本无一键 dev）\n\n```bash\n# 1. 同时启动该版本的两个渲染端（:3000 主渲染端 + :5173 Link 渲染端）\nyarn start-renders-enterprise        # 以企业版为例，其它版本见上表\n\n# 2. 按上文「启动步骤」中的两步法确认两个渲染端真正就绪（端口监听 + curl 拿到有效内容）后，启动 Electron 主进程\nyarn start-electron\n```\n\n### 各版本功能差异（概要）\n\n- **默认 / Yakit**：完整社区版基线，所有功能开放。\n- **enterprise / EnpriTrace**：企业版，使用企业 token、企业远端配置、独立的企业数据库 `company-default-yakit.db`。\n- **simpleEE / EnpriTraceAgent**：便携 / 简易企业版，隶属企业系（`isEnterpriseOrSimpleEdition()` 为 true）。\n- **irify / IRify**：IRify 社区版，紫色主题，含 `irifyHome`、`irifyAiCodeAudit`（AI 代码审计）等专属页面。\n- **irifyEnterprise / IRifyEnpriTrace**：IRify 的企业版分支。\n- **memfit / Memfit AI**：面向 AI Agent 的精简版，菜单与界面元素最多精简（大量 `!isMemfit()` 守卫）。\n\n## 构建渲染端产物\n\n若需打包发布，需先构建两个渲染端的静态产物，再执行 electron-builder：\n\n```bash\n# 构建两个渲染端（默认版本）\nyarn build-renders\n# 等价于：run-s build-render build-link-render\n\n# 之后使用对应平台的打包命令，例如 macOS：\nyarn pack-mac\n```\n\n## 常见问题排查\n\n> 当用户带着启动 / 编译报错来询问时，**第一步应先跑 `yarn check-deps` 排查是否由依赖问题引起**，再去看具体报错。\n>\n> ⚠️ 注意 `yarn check-deps` 的盲区：它通过 `git diff HEAD -- yarn.lock` 判断依赖是否更新，**只能检测工作区未提交的 yarn.lock 改动**。若用户刚 `git pull` 拉到了别人**已提交**的新 yarn.lock 但没重新 `yarn install`，此时新 lock 已进 HEAD，`git diff HEAD` 为空，脚本会误报「依赖一致」而实际 `node_modules` 已滞后。\n>\n> 因此：**若用户最近 `git pull` 过但没重新安装依赖，即便 `check-deps` 报「依赖一致」，也应使用 `AskUserQuestion` 工具弹选项框**询问用户是否按顺序重跑依赖安装三步曲（`yarn install` / `yarn install-render` / `yarn install-link-render`）后再启动，而不是在回复里用文字描述让用户再答一遍。\n\n- **窗口白屏 / `ERR_CONNECTION_REFUSED`**：对应渲染端未就绪。注意端口监听 ≠ 加载完成，需按「启动步骤」用 `curl` 轮询确认两端返回有效 HTML 后再启动 Electron。\n- **启动 / 编译报错（模块找不到、API 报错、语法报错等）**：优先 `yarn check-deps` 排查依赖是否一致；结合上述盲区判断是否需要重装依赖。\n- **M1 芯片原生依赖编译失败**：执行 `brew install pkg-config pixman cairo pango`。\n- **Electron 下载慢 / 失败**：`source ./electron.env` 后重试。\n- **端口被占用**：确认没有残留的 vite / electron 进程，必要时 `lsof -i :3000` / `lsof -i :5173` 排查。\n\n## 代码规范\n\n- 强制使用 LF 换行符。\n- 缩进为 2 个空格。\n- 代码不使用分号，使用单引号。\n- 遵循项目中的 `.prettierrc.js` 和 `.editorconfig`。\n\n## 关键脚本速查\n\n**公共命令（与版本无关）**：\n\n| 命令 | 作用 |\n| --- | --- |\n| `yarn install` | 安装根目录依赖 |\n| `yarn install-render` | 安装主渲染端依赖 |\n| `yarn install-link-render` | 安装 Link 渲染端依赖 |\n| `yarn start-electron` | 启动 Electron 主进程（不区分版本） |\n| `yarn check-deps` | 检查本地依赖是否与仓库一致（启动前执行） |\n\n**各版本启动 / 构建 / 打包**（默认版本无后缀；后缀取值见「多版本/多平台变体」表）：\n\n| 命令模式 | 作用 |\n| --- | --- |\n| `yarn start-renders[-<后缀>]` | 同时启动两个渲染端（:3000 + :5173） |\n| `yarn start-render[-<后缀>]` | 仅启动主渲染端（:3000） |\n| `yarn start-link-render[-<后缀>]` | 仅启动 Link 渲染端（:5173） |\n| `yarn build-renders[-<后缀>]` | 构建两个渲染端静态产物 |\n| `yarn build-render[-<后缀>]` | 仅构建主渲染端 |\n| `yarn build-link-render[-<后缀>]` | 仅构建 Link 渲染端 |\n| `yarn pack-mac[-<后缀>]` / `pack-win[-<后缀>]` / `pack-linux[-<后缀>]` | 对应平台打包 |\n\n> 版本后缀对照：默认（无） / `-enterprise`（EE，打包为 `pack-*-ee`）/ `-simple-enterprise`（SE，`pack-*-se`）/ `-irify`（`pack-*-irify`）/ `-irify-enterprise`（`pack-*-irify-ee`）/ `-memfit`（`pack-*-memfit`）。\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Yakit 项目启动指南（Agent 背景文件）\n\n本文件为所有 AI Agent（及新开发者）提供项目启动所需的背景知识。\n阅读本文件后，你应能独立完成依赖安装与本地开发环境的启动。\n\n## 项目结构\n\nYakit 是一个 Electron 桌面应用，由三部分组成：\n\n| 模块 | 路径 | 说明 | 开发端口 |\n| --- | --- | --- | --- |\n| Electron 主进程 | `app/main/` | 入口 `app/main/index.js`，承载窗口、IPC、gRPC 通信等 | - |\n| 主渲染端 | `app/renderer/src/main/` | 基于 Vite 8（MPA：main/aux）的主界面渲染端 | `3000` |\n| Link 渲染端 | `app/renderer/engine-link-startup/` | 基于 Vite 的引擎链接启动页渲染端 | `5173` |\n\n> 主进程在开发模式下会分别加载：\n> - 主窗口：`http://127.0.0.1:3000`（`app/main/index.js:247`）\n> - 引擎链接窗口：`http://127.0.0.1:5173`（`app/main/index.js:143`）\n>\n> 因此**两个渲染端都必须成功启动后，才能启动 Electron 主进程**，否则窗口会白屏。\n\n## 前置要求\n\n- Node.js（版本以团队约定为准，仓库暂未提供 `.nvmrc`）\n- Yarn（本项目使用 `yarn` 作为包管理器，根目录已提供 `yarn.lock`）\n- macOS（Apple Silicon / M 芯片）如遇到原生依赖编译失败，可参考 `ELECTRON_GUIDE.md` 执行：\n  ```bash\n  brew install pkg-config pixman cairo pango\n  ```\n- 如需从国内镜像安装 Electron，可先 `source ./electron.env` 设置镜像源。\n\n## 依赖安装\n\n项目共有三个需要安装依赖的子项目，**务必按顺序全部安装**：\n\n```bash\n# 1. 根目录（Electron 主进程相关依赖，含 electron、electron-builder、concurrently、wait-on 等）\nyarn install\n\n# 2. 主渲染端（Vite 8）\nyarn install-render\n# 等价于：cd app/renderer/src/main && yarn install\n\n# 3. Link 渲染端（Vite）\nyarn install-link-render\n# 等价于：cd app/renderer/engine-link-startup && yarn install\n```\n\n\n## 启动开发环境\n\n> 开发模式下 Electron 主进程会分别加载主窗口 `http://127.0.0.1:3000` 与引擎链接窗口 `http://127.0.0.1:5173`，因此**两个渲染端都必须先成功启动**，再启动 Electron，否则对应窗口会白屏。\n\n### 启动前依赖检查（重要）\n\n启动项目前，先检查本地依赖是否与仓库一致（尤其是 `git pull` 之后，别人可能新增或升级了依赖）：\n\n```bash\nyarn check-deps\n```\n\n- 若提示「未安装依赖」：按提示先完成上文「依赖安装」三步曲。\n- 若提示「依赖可能有更新」：**使用 `AskUserQuestion` 工具向用户弹选项框确认**是否重新安装对应子项目的依赖，而不是在回复里用文字描述选项让用户再答一遍。选项示例：\n  - `重装全部依赖`（按顺序执行 `yarn install` / `yarn install-render` / `yarn install-link-render`）\n  - `仅重装有改动的子项目`（按 check-deps 提示的列表）\n  - `跳过，直接启动`\n- 若提示「依赖一致」：进入启动步骤。但若用户提到最近 `git pull` 过而未重装（见下文「常见问题排查」的盲区），**使用 `AskUserQuestion` 工具弹选项框**询问是否仍重跑依赖三步曲。\n\n> 通用规则：**凡涉及需要用户决策的环节（是否重装依赖、启动哪个版本、是否跳过某步等），一律优先用 `AskUserQuestion` 工具弹出选项框让用户一键选择，不要在回复里用文字罗列选项让用户再答一遍。**\n\n### 启动步骤\n\n> 若用户未指定启动哪个版本，**使用 `AskUserQuestion` 工具弹选项框**让用户选择版本，不要默认替用户决定。\n>\n> ⚠️ `AskUserQuestion` 每个问题最多只能放 4 个选项（外加自动提供的「Other」自定义输入），而项目共有 6 个版本（见「多版本/多平台变体」表），无法一次性全部展示。采用**分层弹框**策略：\n>\n> 1. **第一层弹框**：选项只放 4 个主版本——`Yakit`（默认）、`enterprise`（企业版）、`irify`（IRify 社区版）、`memfit`（AI 精简版）。question 文本中完整列出全部 6 个版本名，提示 `simple-enterprise` 与 `irify-enterprise` 会根据后续选择追问。\n> 2. **第二层弹框（按需追问）**：\n>    - 若用户在第一层选了 `enterprise`，再弹一次选项框，让用户在 `enterprise`（企业版 EE）与 `simple-enterprise`（便携 / 简易企业版 SE）之间二选一。\n>    - 若用户在第一层选了 `irify`，再弹一次选项框，让用户在 `irify`（IRify 社区版）与 `irify-enterprise`（IRify 企业版）之间二选一。\n>    - 若用户选了 `Yakit` 或 `memfit`，无需追问，直接确定。\n> 3. 这样既不超出工具单次 4 选项上限，又能覆盖全部 6 个版本，且用户全程点选、无需手动输入「Other」。\n\n先同时启动两个渲染端（:3000 主渲染端 + :5173 Link 渲染端）：\n\n```bash\nyarn start-renders\n# 等价于：concurrently \"yarn start-render\" \"yarn start-link-render\"\n```\n\n待两个渲染端**真正就绪**后，再启动 Electron 主进程：\n\n```bash\nyarn start-electron\n```\n\n> ⚠️ **重要：必须确认渲染端「真正就绪」后再启动 Electron，否则窗口会白屏。**\n>\n> 端口进入 LISTEN 状态 ≠ 渲染端加载完成。Vite / CRA 的 dev server 端口会很快开始监听，但此时首次编译可能尚未结束，Electron 此时加载会拿到不完整的页面导致白屏。\n>\n> 必须按以下两步确认就绪：\n>\n> 1. **端口检查**：确认 `3000` 与 `5173` 端口均在监听。\n>    ```bash\n>    lsof -i :3000 -sTCP:LISTEN\n>    lsof -i :5173 -sTCP:LISTEN\n>    ```\n>\n> 2. **内容轮询**：用 `curl` 轮询，直到两端都返回 HTTP 200 且响应体包含有效内容（如 `<script` 或 `<div id=\"root\"`），才说明首次编译完成、页面真正可访问。\n>    ```bash\n>    # 轮询直到主渲染端（:3000）就绪\n>    until curl -s http://127.0.0.1:3000 | grep -qE '<script|<div id=\"root\"'; do sleep 2; done\n>\n>    # 轮询直到 Link 渲染端（:5173）就绪\n>    until curl -s http://127.0.0.1:5173 | grep -qE '<script|<div id=\"root\"'; do sleep 2; done\n>    ```\n>\n> 两端都通过上述检查后，再执行 `yarn start-electron`。\n\n## 多版本/多平台变体\n\n> 依赖安装步骤与版本无关，请先按上文「依赖安装」完成；版本差异只体现在下面的启动 / 构建 / 打包命令上。\n\n项目通过 `--mode` / `env-cmd` 环境切换支持多个发行版本。开发时如无特殊需求，使用默认模式即可。\n\n版本由渲染端注入的 env 决定（主渲染端 `REACT_APP_PLATFORM`、Link 渲染端 `VITE_PLATFORM`），**Electron 主进程不区分版本**，它只加载当前已运行的渲染端地址。\n\n| 版本（脚本后缀） | 产品名 | 性质 | 本地引擎端口 | 同时启动两渲染端 | 构建两渲染端 | 对应平台打包 |\n| --- | --- | --- | --- | --- | --- | --- |\n| 默认 | Yakit | 社区版 CE | `9011` | `yarn start-renders` | `yarn build-renders` | `pack-mac` / `pack-win` / `pack-linux` |\n| `-enterprise` | EnpriTrace | 企业版 EE | `9012` | `yarn start-renders-enterprise` | `yarn build-renders-enterprise` | `pack-*-ee` |\n| `-simple-enterprise` | EnpriTraceAgent | 便携 / 简易企业版 SE | `9013` | `yarn start-renders-simple-enterprise` | `yarn build-renders-simple-enterprise` | `pack-*-se` |\n| `-irify` | IRify | IRify 社区版 | `9014` | `yarn start-renders-irify` | `yarn build-renders-irify` | `pack-*-irify` |\n| `-irify-enterprise` | IRifyEnpriTrace | IRify 企业版 | `9015` | `yarn start-renders-irify-enterprise` | `yarn build-renders-irify-enterprise` | `pack-*-irify-ee` |\n| `-memfit` | Memfit AI | AI Agent 精简版 | `9016` | `yarn start-renders-memfit` | `yarn build-renders-memfit` | `pack-*-memfit` |\n\n> 也可以只启动单个渲染端：主渲染端用 `yarn start-render-<后缀>`，Link 渲染端用 `yarn start-link-render-<后缀>`（默认版本无后缀）。\n\n### 启动某个版本（非默认版本无一键 dev）\n\n```bash\n# 1. 同时启动该版本的两个渲染端（:3000 主渲染端 + :5173 Link 渲染端）\nyarn start-renders-enterprise        # 以企业版为例，其它版本见上表\n\n# 2. 按上文「启动步骤」中的两步法确认两个渲染端真正就绪（端口监听 + curl 拿到有效内容）后，启动 Electron 主进程\nyarn start-electron\n```\n\n### 各版本功能差异（概要）\n\n- **默认 / Yakit**：完整社区版基线，所有功能开放。\n- **enterprise / EnpriTrace**：企业版，使用企业 token、企业远端配置、独立的企业数据库 `company-default-yakit.db`。\n- **simpleEE / EnpriTraceAgent**：便携 / 简易企业版，隶属企业系（`isEnterpriseOrSimpleEdition()` 为 true）。\n- **irify / IRify**：IRify 社区版，紫色主题，含 `irifyHome`、`irifyAiCodeAudit`（AI 代码审计）等专属页面。\n- **irifyEnterprise / IRifyEnpriTrace**：IRify 的企业版分支。\n- **memfit / Memfit AI**：面向 AI Agent 的精简版，菜单与界面元素最多精简（大量 `!isMemfit()` 守卫）。\n\n## 构建渲染端产物\n\n若需打包发布，需先构建两个渲染端的静态产物，再执行 electron-builder：\n\n```bash\n# 构建两个渲染端（默认版本）\nyarn build-renders\n# 等价于：run-s build-render build-link-render\n\n# 之后使用对应平台的打包命令，例如 macOS：\nyarn pack-mac\n```\n\n## 常见问题排查\n\n> 当用户带着启动 / 编译报错来询问时，**第一步应先跑 `yarn check-deps` 排查是否由依赖问题引起**，再去看具体报错。\n>\n> ⚠️ 注意 `yarn check-deps` 的盲区：它通过 `git diff HEAD -- yarn.lock` 判断依赖是否更新，**只能检测工作区未提交的 yarn.lock 改动**。若用户刚 `git pull` 拉到了别人**已提交**的新 yarn.lock 但没重新 `yarn install`，此时新 lock 已进 HEAD，`git diff HEAD` 为空，脚本会误报「依赖一致」而实际 `node_modules` 已滞后。\n>\n> 因此：**若用户最近 `git pull` 过但没重新安装依赖，即便 `check-deps` 报「依赖一致」，也应使用 `AskUserQuestion` 工具弹选项框**询问用户是否按顺序重跑依赖安装三步曲（`yarn install` / `yarn install-render` / `yarn install-link-render`）后再启动，而不是在回复里用文字描述让用户再答一遍。\n\n- **窗口白屏 / `ERR_CONNECTION_REFUSED`**：对应渲染端未就绪。注意端口监听 ≠ 加载完成，需按「启动步骤」用 `curl` 轮询确认两端返回有效 HTML 后再启动 Electron。\n- **启动 / 编译报错（模块找不到、API 报错、语法报错等）**：优先 `yarn check-deps` 排查依赖是否一致；结合上述盲区判断是否需要重装依赖。\n- **M1 芯片原生依赖编译失败**：执行 `brew install pkg-config pixman cairo pango`。\n- **Electron 下载慢 / 失败**：`source ./electron.env` 后重试。\n- **端口被占用**：确认没有残留的 vite / electron 进程，必要时 `lsof -i :3000` / `lsof -i :5173` 排查。\n\n## 代码规范\n\n- 强制使用 LF 换行符。\n- 缩进为 2 个空格。\n- 代码不使用分号，使用单引号。\n- 遵循项目中的 `.prettierrc.js` 和 `.editorconfig`。\n\n## 关键脚本速查\n\n**公共命令（与版本无关）**：\n\n| 命令 | 作用 |\n| --- | --- |\n| `yarn install` | 安装根目录依赖 |\n| `yarn install-render` | 安装主渲染端依赖 |\n| `yarn install-link-render` | 安装 Link 渲染端依赖 |\n| `yarn start-electron` | 启动 Electron 主进程（不区分版本） |\n| `yarn check-deps` | 检查本地依赖是否与仓库一致（启动前执行） |\n\n**各版本启动 / 构建 / 打包**（默认版本无后缀；后缀取值见「多版本/多平台变体」表）：\n\n| 命令模式 | 作用 |\n| --- | --- |\n| `yarn start-renders[-<后缀>]` | 同时启动两个渲染端（:3000 + :5173） |\n| `yarn start-render[-<后缀>]` | 仅启动主渲染端（:3000） |\n| `yarn start-link-render[-<后缀>]` | 仅启动 Link 渲染端（:5173） |\n| `yarn build-renders[-<后缀>]` | 构建两个渲染端静态产物 |\n| `yarn build-render[-<后缀>]` | 仅构建主渲染端 |\n| `yarn build-link-render[-<后缀>]` | 仅构建 Link 渲染端 |\n| `yarn pack-mac[-<后缀>]` / `pack-win[-<后缀>]` / `pack-linux[-<后缀>]` | 对应平台打包 |\n\n> 版本后缀对照：默认（无） / `-enterprise`（EE，打包为 `pack-*-ee`）/ `-simple-enterprise`（SE，`pack-*-se`）/ `-irify`（`pack-*-irify`）/ `-irify-enterprise`（`pack-*-irify-ee`）/ `-memfit`（`pack-*-memfit`）。\n","category":"root","tokens":1906}]}