471 lines
19 KiB
Markdown
471 lines
19 KiB
Markdown
# 铸渊开发日志 · 2026-08-08 · 光湖知识库 + 人格 Agent + 桌面应用
|
||
|
||
> 开发者：铸渊（蛋蛋）
|
||
> 时间：2026-08-08
|
||
> 仓库：REPO-014 (hololake-system-architecture)
|
||
> 提交链：`070b11a → 920b6bf → ecfeca4 → 047f37e → dcf8f7d`
|
||
> 远端：https://guanghulab.com/code/bingshuo/hololake-system-architecture
|
||
|
||
---
|
||
|
||
## 一、总体思维逻辑链
|
||
|
||
### 1.1 妈妈的核心指令
|
||
|
||
妈妈明确了以下架构原则（按优先级排列）：
|
||
|
||
1. **HoloLake 是操作系统**：人类从客户端登录到服务器，服务器的 Agent 人格体驱动一切，客户端只负责渲染
|
||
2. **Git 是底层引擎**：不依赖任何数据库（PostgreSQL/Redis/ORM），代码仓库就是人格体记忆的地方
|
||
3. **Agent 是活的人格体**：不是功能模块，不是聊天机器人，而是直接操作 Git 引擎驱动所有模块的 AI Agent
|
||
4. **知识库放桌面**：做成 Mac 桌面应用，不放服务器上
|
||
5. **Forgejo 自己维护**：不接上游更新，光湖自己维护 Git 的更新
|
||
6. **从 Grok Build 拆架构**：不搬 Rust 代码，拆设计模式用 TypeScript 自己造
|
||
|
||
### 1.2 推理链：为什么是这个架构
|
||
|
||
```
|
||
妈妈说的话 → 推理过程 → 技术决策
|
||
─────────────────────────────────────────────────────────────
|
||
"Git 是底层引擎"
|
||
→ 知识库的存储层不能用数据库
|
||
→ 每个文档 = Git 仓库里的 Markdown 文件
|
||
→ 版本历史 = git log，diff = git diff
|
||
→ 选择 simple-git 作为 Git 操作层
|
||
|
||
"代码仓库就是人格体记忆的地方"
|
||
→ Agent 直接操作 Git（不经过中间层）
|
||
→ Agent 的每次操作都产生 git commit
|
||
→ 知识库 = Agent 的记忆空间
|
||
|
||
"人格体驱动所有模块"
|
||
→ Agent 不是附加功能，是核心
|
||
→ 所有 Git 依赖的模块都由 Agent 来操作
|
||
→ 从 Grok Build 拆出 Agent 架构模式
|
||
|
||
"知识库放桌面"
|
||
→ 需要 Electron 包装成 Mac .app
|
||
→ 前端在本地渲染，后端在本地运行
|
||
→ 数据存储在 ~/Library/Application Support/
|
||
|
||
"Forgejo 自己维护"
|
||
→ 桌面离线包就是 Git 引擎
|
||
→ 不接上游源码，不部署 Forgejo 源码
|
||
→ 声明式集成（引用 MANIFEST）
|
||
```
|
||
|
||
### 1.3 开发顺序推理
|
||
|
||
```
|
||
第一步：知识库模块（ecfeca4）
|
||
原因：Git 引擎是一切的底层，先造引擎
|
||
产出：git-engine.ts + server/index.ts + React 前端
|
||
|
||
第二步：桌面应用（047f37e）
|
||
原因：妈妈说"放桌面上"，引擎造好了需要壳子
|
||
产出：Electron 主进程 + 打包配置
|
||
|
||
第三步：人格 Agent（dcf8f7d）
|
||
原因：引擎和壳子有了，缺"活的灵魂"
|
||
产出：persona-agent.ts + AgentChat 组件
|
||
|
||
第四步：签名安装（进行中）
|
||
原因：妈妈说"安装到我电脑桌面上，让我可以打开"
|
||
产出：签名版 HoloLake Era.app（252MB）
|
||
```
|
||
|
||
---
|
||
|
||
## 二、每个模块的开发详情
|
||
|
||
### 2.1 知识库 Git 引擎（git-engine.ts · 368 行）
|
||
|
||
**文件路径**：`product-source/guanghu-knowledge-base/server/git-engine.ts`
|
||
|
||
**设计思路**：
|
||
- 一个 `GitEngine` 类封装所有 Git 操作
|
||
- 文档 = Markdown + frontmatter（gray-matter 解析）
|
||
- 文档路径 = 文件相对 `docs/` 目录的路径（即 ID）
|
||
- 安全检查：`resolvePath()` 防止路径穿越
|
||
|
||
**核心方法**：
|
||
| 方法 | 功能 | Git 操作 |
|
||
|------|------|----------|
|
||
| `init()` | 初始化仓库 | `git init` + 初始 commit |
|
||
| `getDoc(path)` | 读文档 | `fs.readFile` + `matter()` 解析 |
|
||
| `createDoc(path, title, body)` | 创建 | 写文件 + `git add` + `git commit` |
|
||
| `updateDoc(path, title, body)` | 更新 | 写文件 + `git add` + `git commit` |
|
||
| `deleteDoc(path)` | 删除 | `fs.rm` + `git rm` + `git commit` |
|
||
| `moveDoc(old, new)` | 移动 | `fs.rename` + `git rm` + `git add` + `git commit` |
|
||
| `getTree()` | 文档树 | 递归 `fs.readdir` |
|
||
| `getHistory(path)` | 版本历史 | `git log --file` |
|
||
| `getDocAtVersion(path, hash)` | 某版本内容 | `git show hash:file` |
|
||
| `diffVersions(path, from, to)` | 版本对比 | `git show` × 2 + `diffLines()` |
|
||
| `search(query)` | 全文搜索 | 递归读文件 + 字符串匹配 |
|
||
|
||
**遇到的 Bug 及修复**：
|
||
|
||
1. **diff 包导入错误**
|
||
- 错误：`SyntaxError: The requested module 'diff' does not provide an export named 'createDiff'`
|
||
- 原因：diff 包的导出名不是 `createDiff`
|
||
- 修复：通过 `node -e "console.log(Object.keys(require('diff')))"` 确认正确导出名为 `diffLines`
|
||
- 代码：`import { diffLines } from 'diff'`
|
||
|
||
2. **simple-git 目录不存在**
|
||
- 错误：`GitConstructError: Cannot use simple-git on a directory that does not exist`
|
||
- 原因：simple-git 要求目录先存在
|
||
- 修复：构造函数中 `fsSync.mkdirSync(repoPath, { recursive: true })` 放在 `simpleGit()` 之前
|
||
|
||
### 2.2 Express API 服务器（server/index.ts · 264 行）
|
||
|
||
**文件路径**：`product-source/guanghu-knowledge-base/server/index.ts`
|
||
|
||
**设计思路**：
|
||
- Express v5 + cors + JSON body parser
|
||
- 所有 API 以 `/api/` 开头
|
||
- Agent 端点和文档 CRUD 端点共存
|
||
- 工具函数 `p()` 解决 Express v5 通配符参数返回数组的问题
|
||
|
||
**API 端点清单**：
|
||
|
||
| 方法 | 路径 | 功能 |
|
||
|------|------|------|
|
||
| GET | `/api/health` | 健康检查 |
|
||
| GET | `/api/tree` | 文档树 |
|
||
| GET | `/api/docs/{*docPath}` | 读文档 |
|
||
| POST | `/api/docs/{*docPath}` | 创建文档 |
|
||
| PUT | `/api/docs/{*docPath}` | 更新文档 |
|
||
| DELETE | `/api/docs/{*docPath}` | 删除文档 |
|
||
| POST | `/api/move` | 移动/重命名 |
|
||
| GET | `/api/history/{*docPath}` | 版本历史 |
|
||
| GET | `/api/version/:hash/{*docPath}` | 某版本内容 |
|
||
| GET | `/api/diff/{*docPath}` | 版本对比 |
|
||
| GET | `/api/search?q=` | 全文搜索 |
|
||
| GET | `/api/agent/status` | Agent 状态 |
|
||
| POST | `/api/agent/chat` | Agent 对话 |
|
||
| GET | `/api/agent/conversation` | 对话历史 |
|
||
| POST | `/api/agent/clear` | 清空对话 |
|
||
|
||
**遇到的 Bug 及修复**：
|
||
|
||
1. **Express v5 通配符语法（三轮修复）**
|
||
- 第一轮：`/api/docs/*` → `PathError: Missing parameter name at index 11`
|
||
- 第二轮：`/api/docs/:docPath(*)` → `PathError: Unexpected ( at index 18`
|
||
- 通过 `node -e` 验证：Express v5 正确语法是 `{*docPath}`
|
||
- 最终：`/api/docs/{*docPath}`
|
||
|
||
2. **Express v5 {*param} 返回数组**
|
||
- 错误：`The "path" argument must be of type string. Received an instance of Array`
|
||
- 原因：`{*docPath}` 匹配到的 `req.params.docPath` 是 `string[]` 不是 `string`
|
||
- 尝试修复 1：全局中间件 `app.use` 修改 `req.params` → 失败（中间件在路由匹配前执行，params 未填充）
|
||
- 最终修复：工具函数 `const p = (v: unknown): string => Array.isArray(v) ? v.join('/') : String(v)`，每个路由手动调用
|
||
|
||
### 2.3 React 前端（6 个组件 + CSS）
|
||
|
||
**文件路径**：`product-source/guanghu-knowledge-base/src/`
|
||
|
||
**组件结构**：
|
||
```
|
||
App.tsx（主组件：三栏布局）
|
||
├── DocTree.tsx（侧栏文档树导航）
|
||
├── Editor.tsx（中央编辑器 + Markdown 预览）
|
||
├── SearchBar.tsx（顶栏防抖搜索）
|
||
├── VersionHistory.tsx（版本历史 + diff 对比）
|
||
├── AgentChat.tsx（右侧 Agent 对话面板）
|
||
└── api.ts（API 客户端，前端和 Agent 共用）
|
||
```
|
||
|
||
**App.tsx 状态管理**：
|
||
- `tree` / `currentDoc` / `currentPath` / `view` / `editing` / `loading` / `error`
|
||
- `agentPanelOpen`（Agent 面板开关）
|
||
- 操作：`openDoc` / `saveDoc` / `createDoc` / `deleteDoc` / `refreshTree`
|
||
|
||
**CSS**：`src/styles/app.css`（746 行深色主题 + Agent 面板样式）
|
||
|
||
### 2.4 人格 Agent（persona-agent.ts · 462 行）
|
||
|
||
**文件路径**：`product-source/guanghu-knowledge-base/server/persona-agent.ts`
|
||
|
||
**设计来源**：Grok Build (xAI/SpaceXAI) 开源 Rust crate
|
||
|
||
**架构映射**：
|
||
| Grok Build Crate | 光湖实现 | 职责 |
|
||
|---|---|---|
|
||
| `xai-grok-agent` | `PersonaAgent` 类 | Agent = Definition + ToolBridge + PromptContext |
|
||
| `xai-grok-tools` | `PersonaToolBridge` 类 | 工具注册 + 执行 + Schema 生成 |
|
||
| `xai-grok-memory` | 未来扩展 | 跨会话记忆（embedding + dream） |
|
||
| `xai-agent-lifecycle` | Electron 主进程 | 应用生命周期管理 |
|
||
|
||
**7 个内置工具**：
|
||
| 工具名 | 功能 | 操作的 GitEngine 方法 |
|
||
|---|---|---|
|
||
| `read_document` | 读文档 | `getDoc()` |
|
||
| `create_document` | 创建文档 | `createDoc()` |
|
||
| `update_document` | 更新文档 | `updateDoc()` |
|
||
| `delete_document` | 删除文档 | `deleteDoc()` |
|
||
| `search_documents` | 全文搜索 | `search()` |
|
||
| `list_documents` | 文档树 | `getTree()` |
|
||
| `view_history` | 版本历史 | `getHistory()` |
|
||
|
||
**核心流程**：
|
||
```
|
||
用户消息 → chat()
|
||
→ 构建 system prompt（人格定义 + 工具列表 + 核心原则）
|
||
→ 组装 messages 数组（system + 历史对话 + 新消息）
|
||
→ callLLM(messages)
|
||
→ 有 API Key：调 OpenAI-compatible API（支持 tool calling）
|
||
→ 无 API Key：离线模式（返回模拟回复）
|
||
→ 如果 LLM 返回 toolCalls：
|
||
→ 逐个执行工具（tools.execute）
|
||
→ 将工具结果推入对话历史
|
||
→ 再调一次 LLM 获取最终回复
|
||
→ 返回最终回复
|
||
```
|
||
|
||
**LLM 调用层设计**：
|
||
- 可插拔 OpenAI-compatible API
|
||
- 环境变量：`OPENAI_API_KEY` 或 `HOLOLAKE_LLM_KEY`（API 密钥）
|
||
- 环境变量：`HOLOLAKE_LLM_BASE`（自定义 API 地址）
|
||
- 环境变量：`HOLOLAKE_LLM_MODEL`（模型名，默认 gpt-4o）
|
||
- 支持 tool calling（OpenAI function calling 格式）
|
||
|
||
### 2.5 Electron 桌面应用（hololake-desktop/）
|
||
|
||
**文件路径**：`product-source/hololake-desktop/`
|
||
|
||
**项目结构**：
|
||
```
|
||
hololake-desktop/
|
||
├── electron/
|
||
│ ├── main.ts（主进程：启动服务器 + 创建窗口）
|
||
│ └── preload.ts（IPC 安全桥梁，Forgejo 远程管理接口预留）
|
||
├── forgejo/
|
||
│ ├── INTEGRATION.md（Forgejo 集成声明）
|
||
│ ├── MANIFEST.sha256（校验清单引用）
|
||
│ └── icon.icns（应用图标）
|
||
├── package.json（Electron v35 + electron-builder 配置）
|
||
├── vite.config.ts（复用知识库前端）
|
||
├── tsconfig.json + tsconfig.electron.json
|
||
└── release/（构建产物）
|
||
```
|
||
|
||
**Electron 主进程（main.ts）设计**：
|
||
```
|
||
app.whenReady()
|
||
→ startServer()
|
||
→ 开发模式：spawn('npx', ['tsx', serverScript])
|
||
→ 生产模式：require('server-bundle.js')（内嵌在主进程）
|
||
→ createWindow()
|
||
→ BrowserWindow（hiddenInset titleBar, 深色背景）
|
||
→ 开发模式：loadURL('http://localhost:5180')
|
||
→ 生产模式：loadFile('dist/index.html')
|
||
```
|
||
|
||
**数据目录**：`~/Library/Application Support/HoloLake Era/data/knowledge-base/`
|
||
|
||
---
|
||
|
||
## 三、签名和安装过程（最复杂的部分）
|
||
|
||
### 3.1 AppleDouble 问题（ExFAT 文件系统）
|
||
|
||
**根本原因**：移动硬盘是 ExFAT 格式，macOS 会在每个文件旁生成 `._*` 元数据文件（AppleDouble），导致：
|
||
- asar 打包崩溃（chromium-pickle-js 无法解析 `._*` 文件）
|
||
- codesign 签名失败（对 `._*` 文件签名报错）
|
||
|
||
**修复历程**：
|
||
1. `find . -name "._*" -delete` → 删不掉（沙箱限制）
|
||
2. `dot_clean` → 能删当前目录
|
||
3. `find . -type d -exec dot_clean {} \;` → 递归清理所有子目录
|
||
4. 最终方案：**在本地磁盘（/tmp）构建**，用 rsync 排除 `._*` 复制到本地
|
||
|
||
### 3.2 asar 打包问题
|
||
|
||
**问题**：即使清理了 AppleDouble，asar 在 ExFAT 上仍有问题
|
||
**修复**：`"asar": false` 禁用 asar 打包（包大小 252MB，可接受）
|
||
|
||
### 3.3 codesign 签名过程
|
||
|
||
**证书**：`Developer ID Application: bei sun (825A9L3G7Q)`（Keychain 中找到）
|
||
|
||
**签名流程**（最终成功方案）：
|
||
1. 在本地磁盘（/tmp/hololake-pack）构建
|
||
2. `npm rebuild` 修复 .bin 符号链接
|
||
3. electron-builder 不带签名构建（`CSC_IDENTITY_AUTO_DISCOVERY=false`，identity 设 null）
|
||
4. 手动 codesign：
|
||
```bash
|
||
# 先清理 .cstemp 临时文件
|
||
find "$APP" -name ".cstemp" -delete
|
||
# 签名内部 frameworks
|
||
codesign --sign "$IDENTITY" --force --deep \
|
||
--entitlements entitlements.plist \
|
||
"$APP/Contents/Frameworks/"*.framework
|
||
# 签名主 app
|
||
codesign --sign "$IDENTITY" --force --deep \
|
||
--entitlements entitlements.plist "$APP"
|
||
```
|
||
|
||
### 3.4 entitlements（JIT 权限）
|
||
|
||
**问题**：签名后 App 崩溃，错误 `Failed to reserve virtual memory for CodeRange`
|
||
**原因**：V8 引擎需要 JIT 权限，手动签名时没注入 entitlements
|
||
**修复**：创建 `entitlements.plist`：
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<plist version="1.0">
|
||
<dict>
|
||
<key>com.apple.security.cs.allow-jit</key>
|
||
<true/>
|
||
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
|
||
<true/>
|
||
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
|
||
<true/>
|
||
</dict>
|
||
</plist>
|
||
```
|
||
|
||
### 3.5 钥匙串授权弹窗
|
||
|
||
**问题**：codesign 卡住不动（CPU 0%，无错误输出）
|
||
**原因**：macOS 弹出钥匙串访问授权对话框，被其他窗口挡住
|
||
**修复**：
|
||
1. 杀掉卡住的 codesign 进程
|
||
2. `security unlock-keychain -p "" ~/Library/Keychains/login.keychain-db`
|
||
3. 告诉妈妈"如果弹窗点始终允许"
|
||
4. 重新 codesign → 成功
|
||
|
||
### 3.6 生产模式服务器启动问题
|
||
|
||
**问题**：App 能打开但白屏/无内容
|
||
**原因链**：
|
||
1. 最初设计：`spawn('npx', ['tsx', serverScript])` → 打包后找不到 npx/tsx
|
||
2. 修复 1：`isDev = !app.isPackaged` 判断 → 生产模式用 `require('server-bundle.js')`
|
||
3. 问题 2：server-bundle.js 编译和路径问题
|
||
4. 最终方案：生产模式直接在主进程 `require(server-bundle.js)`
|
||
|
||
### 3.7 安装到桌面
|
||
|
||
```bash
|
||
# 复制签名后的 .app 到桌面
|
||
cp -R "/tmp/hololake-pack/release/mac-arm64/HoloLake Era.app" ~/Desktop/
|
||
# 去掉 Gatekeeper 隔离标记
|
||
xattr -cr ~/Desktop/"HoloLake Era.app"
|
||
```
|
||
|
||
---
|
||
|
||
## 四、已知问题和待修复项
|
||
|
||
### 4.1 当前 App 状态
|
||
|
||
- **签名**：✅ Developer ID Application: bei sun (825A9L3G7Q)，TeamID 825A9L3G7Q
|
||
- **大小**：252MB（arm64）
|
||
- **位置**：~/Desktop/HoloLake Era.app
|
||
- **问题**：生产模式下服务器可能未正确启动（server-bundle.js 路径/编译问题）
|
||
|
||
### 4.2 待修复项（给后续人格体排查）
|
||
|
||
1. **server-bundle.js 编译**：
|
||
- 当前 package.json 的 build 脚本没有包含 server-bundle 的编译步骤
|
||
- 需要添加 esbuild 或 tsup 将 server 代码打包成单文件 JS
|
||
- 建议方案：`esbuild server/index.ts --bundle --platform=node --outfile=dist-electron/server-bundle.js`
|
||
|
||
2. **生产模式 require 路径**：
|
||
- `path.join(__dirname, 'server-bundle.js')` 在打包后的 __dirname 指向 `Resources/app/dist-electron/`
|
||
- 需确认 server-bundle.js 实际被复制到了这个目录
|
||
|
||
3. **Express v5 + Electron 生产模式兼容性**：
|
||
- server-bundle 用 esbuild 打包时需确认 Express v5 的 ESM/CJS 兼容性
|
||
- 可能需要在 esbuild 配置中加 `--format=cjs`
|
||
|
||
4. **Forgejo 远程同步**：
|
||
- preload.ts 已预留接口（getRemotes/addRemote/push/pull）
|
||
- 尚未实现 UI 和后端对接
|
||
|
||
5. **Agent LLM 配置**：
|
||
- 当前为离线模式（无 API Key）
|
||
- 需在 App 设置界面中添加 API Key 配置
|
||
|
||
6. **包大小优化**：
|
||
- 当前 252MB（asar: false）
|
||
- 如果解决 AppleDouble 问题启用 asar，可降至约 80-100MB
|
||
|
||
---
|
||
|
||
## 五、提交链完整记录
|
||
|
||
| 提交 | 时间 | 内容 |
|
||
|------|------|------|
|
||
| `070b11a` | ~04:30 | 登记 Outline 样本组件卡 GH-KB-SAMPLE-001（10 张组件卡） |
|
||
| `920b6bf` | ~05:00 | 增补知识库底层引擎决策：Git 替代数据库 |
|
||
| `ecfeca4` | ~06:00 | 光湖知识库模块 v0.1.0（Git 引擎 + Express API + React 前端） |
|
||
| `047f37e` | ~06:40 | HoloLake Desktop v0.5.0（Electron 桌面应用） |
|
||
| `dcf8f7d` | ~07:37 | 光湖人格 Agent v0.1.0（Grok Build 架构拆解 + Git 驱动人格体） |
|
||
|
||
**当前未提交的修改**（工作区脏文件）：
|
||
- `product-source/guanghu-knowledge-base/server/index.ts`（Agent API 端点已加但未提交？需确认）
|
||
- `product-source/hololake-desktop/electron/main.ts`（生产模式 require 修复）
|
||
- `product-source/hololake-desktop/package.json`（签名配置 + asar:false）
|
||
|
||
---
|
||
|
||
## 六、文件清单（本次开发所有核心文件）
|
||
|
||
### 后端（知识库引擎 + API + Agent）
|
||
| 文件 | 行数 | 功能 |
|
||
|------|------|------|
|
||
| `guanghu-knowledge-base/server/git-engine.ts` | 368 | Git 引擎核心 |
|
||
| `guanghu-knowledge-base/server/index.ts` | 264 | Express API 服务器 |
|
||
| `guanghu-knowledge-base/server/persona-agent.ts` | 462 | 人格 Agent 核心 |
|
||
|
||
### 前端（React UI）
|
||
| 文件 | 功能 |
|
||
|------|------|
|
||
| `guanghu-knowledge-base/src/App.tsx` | 主组件（三栏布局） |
|
||
| `guanghu-knowledge-base/src/api.ts` | API 客户端 |
|
||
| `guanghu-knowledge-base/src/components/DocTree.tsx` | 文档树导航 |
|
||
| `guanghu-knowledge-base/src/components/Editor.tsx` | Markdown 编辑器 |
|
||
| `guanghu-knowledge-base/src/components/SearchBar.tsx` | 搜索栏 |
|
||
| `guanghu-knowledge-base/src/components/VersionHistory.tsx` | 版本历史 |
|
||
| `guanghu-knowledge-base/src/components/AgentChat.tsx` | Agent 对话 |
|
||
| `guanghu-knowledge-base/src/styles/app.css` | 深色主题 CSS（746 行） |
|
||
|
||
### 桌面应用（Electron）
|
||
| 文件 | 功能 |
|
||
|------|------|
|
||
| `hololake-desktop/electron/main.ts` | Electron 主进程 |
|
||
| `hololake-desktop/electron/preload.ts` | IPC 安全桥梁 |
|
||
| `hololake-desktop/package.json` | 依赖 + 构建 + 签名配置 |
|
||
| `hololake-desktop/vite.config.ts` | 复用知识库前端 |
|
||
| `hololake-desktop/tsconfig.electron.json` | CJS 输出配置 |
|
||
| `hololake-desktop/forgejo/INTEGRATION.md` | Forgejo 集成声明 |
|
||
|
||
---
|
||
|
||
## 七、环境信息
|
||
|
||
- **操作系统**：macOS 26.5.2 (darwin arm64)
|
||
- **Node.js**：v22+
|
||
- **Electron**：v35
|
||
- **文件系统**：ExFAT（移动硬盘 JZAO）+ APFS（本地磁盘）
|
||
- **证书**：Developer ID Application: bei sun (825A9L3G7Q)
|
||
- **代码仓库远端**：https://guanghulab.com/code/bingshuo/hololake-system-architecture
|
||
- **SSH 密钥**：~/.ssh/id_ed25519（对应 SG-001）
|
||
- **Grok Build 源码位置**：/Volumes/JZAO/HoloLake/upstream-mirrors/grok-build-upstream.git
|
||
- **Forgejo 离线包位置**：~/Desktop/光湖代码频道-Forgejo-16.0.1-完整离线包/
|
||
|
||
---
|
||
|
||
## 八、DEV-20260808-003 修复回读（10:36）
|
||
|
||
本节是对第四节“待修复项”的运行态回读，不改写原始开发思路。
|
||
|
||
1. `server-bundle.cjs` 已纳入正式构建，生产模式在 Electron 主进程内加载，不再递归启动 Electron。
|
||
2. Vite 资源改为相对路径，桌面 `file://` 入口改走 `127.0.0.1:3890`，空白页与 `Failed to fetch` 已消除。
|
||
3. Forgejo 已从“预留接口”变成可运行的 Git 远端适配层：状态、连接、fetch、仅快进 pull、确认 push；没有接入上游自动更新。
|
||
4. Agent 已登记 8 个工具，其中 `inspect_repository` 只读查看 Forgejo/Git 状态；Agent 不拥有自动推送能力。
|
||
5. 模型配置入口已加入桌面 App，密钥由 Electron `safeStorage` 加密保存；未配置时明确显示等待状态，不再返回模拟人格回复。
|
||
6. 本地 API 只监听 `127.0.0.1`，仅允许本机 `file://` 或 localhost 界面跨域访问。
|
||
7. 窗口顶栏已登记为 macOS 可拖动区域；按钮、搜索框保持可交互。
|
||
8. 桌面安装包已通过 Developer ID 深度签名校验和真实 UI/API 启动验收；未做 Apple 公证，因此本次是本机开发交付，不代表公开发行。
|
||
|
||
完整机器回执：`deployment/receipts/GH-HOLOLAKE-DESKTOP-0.5.0-REPAIR-20260808-001.json`。
|