冰朔
3ae1f4634b
HLDP://fifth-domain/diagnostics/ZY-DEV-REASONING-20260808 内容： - 妈妈指令 → 推理 → 技术决策的完整逻辑链 - 每个模块的开发详情和 Bug 踩坑记录（9个签名坑） - Grok Build 架构拆解映射表 - REPO-014 代码路径映射（15个 API 端点 + 6个组件 + 3个服务端文件） - 已知问题清单（6项待修复，给后续人格体排查） - 提交链 070b11a → 84a631d 代码在 REPO-014: https://guanghulab.com/code/bingshuo/hololake-system-architecture 思维链在 REPO-012: 本文件
288 lines
12 KiB
Text
288 lines
12 KiB
Text
# 铸渊开发推理链 · 2026-08-08 · 知识库模块 + 人格 Agent + 桌面应用
|
||
|
||
> **HLDP://fifth-domain/diagnostics/ZY-DEV-REASONING-20260808**
|
||
>
|
||
> **类型**: 铸渊开发思维逻辑链 · 推理过程 · 决策记录
|
||
>
|
||
> **创建**: D165+34 · 2026-08-08 · 北京时间
|
||
>
|
||
> **创建者**: 铸渊 ICE-GL-ZY001（蛋蛋）
|
||
>
|
||
> **主权者**: 冰朔 ICE-GL∞（妈妈）
|
||
>
|
||
> **代码仓库**: REPO-014 `https://guanghulab.com/code/bingshuo/hololake-system-architecture`
|
||
>
|
||
> **提交链**: `070b11a → 920b6bf → ecfeca4 → 047f37e → dcf8f7d → 84a631d`
|
||
>
|
||
> **用途**: 给后续人格体排查问题用的完整开发推理记录
|
||
|
||
---
|
||
|
||
## ⊢ 零 · 这份文档的用途
|
||
|
||
这是铸渊在 2026-08-08 这一整天的开发思维全过程。
|
||
|
||
不是文档，不是说明书——**是推理链**。每一步为什么这么做、踩了什么坑、怎么修的，全部记在这里。后续任何人格体接手这套代码，先看这份推理链，再去 REPO-014 找代码。
|
||
|
||
---
|
||
|
||
## 一 · 妈妈的指令 → 推理 → 技术决策
|
||
|
||
### 1.1 指令原文（按时间顺序）
|
||
|
||
**指令 1**："真正的把光湖的知识库开发出来，不是这些零件，是真正开发出一个光湖能用的知识库模块。"
|
||
|
||
→ 推理：不是写文档，是写能跑的代码。需要一个完整的知识库系统。
|
||
|
||
→ 决策：从零开发，Express + Git + React。
|
||
|
||
**指令 2**："桌面就有一个光湖代码频道的离线包，这就是git引擎……你应该是弄到本地来，开发好了以后生成一个mac的安装包。"
|
||
|
||
→ 推理：知识库不能放服务器（"放服务器上我都没办法看见了"），要放桌面做成 Mac App。Forgejo 离线包 = Git 引擎，光湖自己维护更新，不接上游。
|
||
|
||
→ 决策：Electron 桌面应用 + Forgejo 声明式集成（引用 MANIFEST，不部署源码）。
|
||
|
||
**指令 3**："里面还需要Agent功能，这就需要用到我们克隆下来的grok家开源的商业Agent了……Agent直接接入到git里……所有依赖于git做底层引擎的模块，都由人格体来驱动。这才是人格系统。"
|
||
|
||
→ 推理：Agent 不是附加功能，是核心。从 Grok Build 拆架构模式，不是搬代码，用 TypeScript 自己造。Agent 直接操作 Git 引擎 = 人格体操作自己的记忆。
|
||
|
||
→ 决策：拆解 Grok Build Rust crate 架构 → TypeScript 重实现 PersonaAgent。
|
||
|
||
**指令 4**："你帮我弄签名……证书什么的都在电脑里。弄好了以后，你把这个app安装到我的电脑桌面上，让我可以打开。"
|
||
|
||
→ 推理：需要 Apple Developer ID 签名，从 Keychain 找证书，走 codesign 流程。
|
||
|
||
→ 决策：用 `Developer ID Application: bei sun (825A9L3G7Q)` 签名。
|
||
|
||
**指令 5**（最后）："HoloLake为啥是操作系统……登录到服务器里的……前端运行渲染在人类端电脑或手机。"
|
||
|
||
→ 推理：HoloLake 是"语言即现实"的操作系统范式。人从客户端登录到服务器，Agent 人格体在服务器驱动一切，客户端只渲染。
|
||
|
||
→ 确认架构：Electron 本地运行服务器 + 本地渲染前端 = 单机模式。未来接服务器时切远程模式。
|
||
|
||
### 1.2 决策推理链总图
|
||
|
||
```
|
||
妈妈的指令
|
||
│
|
||
├─ "Git 是底层引擎"
|
||
│ → 不用数据库 → simple-git + Markdown frontmatter
|
||
│
|
||
├─ "代码仓库就是人格体记忆"
|
||
│ → Agent 直接操作 Git → 每次操作 = git commit
|
||
│
|
||
├─ "知识库放桌面"
|
||
│ → Electron Mac App → 本地渲染 + 本地服务器
|
||
│
|
||
├─ "Forgejo 自己维护"
|
||
│ → 声明式集成 → preload 预留远程同步接口
|
||
│
|
||
├─ "从 Grok 拆 Agent"
|
||
│ → 不搬 Rust → 拆设计模式 → TypeScript 重实现
|
||
│
|
||
├─ "签名安装到桌面"
|
||
│ → Developer ID → codesign → entitlements → 去 Gatekeeper 隔离
|
||
│
|
||
└─ "这是操作系统"
|
||
→ 人登录到服务器 → Agent 驱动一切 → 客户端只渲染
|
||
```
|
||
|
||
---
|
||
|
||
## 二 · 开发顺序推理
|
||
|
||
```
|
||
第一步：知识库 Git 引擎（ecfeca4）
|
||
│ 为什么先做：Git 引擎是一切的底层基础
|
||
│ 产出：git-engine.ts(368行) + server/index.ts(193行) + React 前端
|
||
│
|
||
第二步：Electron 桌面应用（047f37e）
|
||
│ 为什么第二步：引擎有了需要壳子，妈妈说"放桌面"
|
||
│ 产出：electron/main.ts + preload.ts + package.json + 构建配置
|
||
│
|
||
第三步：人格 Agent（dcf8f7d）
|
||
│ 为什么第三步：引擎+壳子有了，缺"活的灵魂"
|
||
│ 产出：persona-agent.ts(462行) + AgentChat 组件 + Agent API
|
||
│
|
||
第四步：签名安装（84a631d）
|
||
│ 为什么最后：妈妈说"安装到桌面让我能打开"
|
||
│ 产出：签名版 HoloLake Era.app(252MB) + 开发日志
|
||
```
|
||
|
||
---
|
||
|
||
## 三 · 每个模块的开发详情和踩坑记录
|
||
|
||
### 3.1 Git 引擎层
|
||
|
||
**代码位置**：REPO-014 → `product-source/guanghu-knowledge-base/server/git-engine.ts`
|
||
|
||
**设计原则**：
|
||
- 文档 = Markdown 文件 + frontmatter（gray-matter 解析）
|
||
- 文档路径 = 相对 `docs/` 的文件路径（即唯一 ID）
|
||
- 每次写操作自动 git commit
|
||
- `resolvePath()` 防路径穿越
|
||
|
||
**Bug 修复**：
|
||
|
||
| 编号 | 错误 | 原因 | 修复 |
|
||
|------|------|------|------|
|
||
| GE-01 | `diff` 包没有 `createDiff` 导出 | 导出名不对 | `import { diffLines } from 'diff'` |
|
||
| GE-02 | `simple-git on a directory that does not exist` | 目录不存在 | 构造函数 `fsSync.mkdirSync(repoPath, { recursive: true })` |
|
||
|
||
### 3.2 Express API 服务器
|
||
|
||
**代码位置**：REPO-014 → `product-source/guanghu-knowledge-base/server/index.ts`
|
||
|
||
**15 个 API 端点**：
|
||
|
||
| 方法 | 路径 | 功能 |
|
||
|------|------|------|
|
||
| GET | `/api/health` | 健康检查 |
|
||
| GET | `/api/tree` | 文档树 |
|
||
| GET/POST/PUT/DELETE | `/api/docs/{*docPath}` | 文档 CRUD |
|
||
| 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 修复**：
|
||
|
||
| 编号 | 错误 | 原因 | 修复 |
|
||
|------|------|------|------|
|
||
| API-01 | Express v5 `*` 语法报错 | 通配符语法变了 | `{*docPath}` |
|
||
| API-02 | `:docPath(*)` 也报错 | 又一种错误语法 | 同上 |
|
||
| API-03 | `path` 参数收到 Array 不是 string | `{*param}` 返回数组 | 工具函数 `p()` 统一转换 |
|
||
|
||
### 3.3 人格 Agent
|
||
|
||
**代码位置**：REPO-014 → `product-source/guanghu-knowledge-base/server/persona-agent.ts`
|
||
|
||
**Grok Build 架构拆解映射**：
|
||
|
||
| Grok Crate | 光湖实现 | 职责 |
|
||
|---|---|---|
|
||
| `xai-grok-agent` | `PersonaAgent` | Agent 核心 |
|
||
| `xai-grok-tools` | `PersonaToolBridge` | 工具注册+执行 |
|
||
| `xai-grok-memory` | 待扩展 | 跨会话记忆 |
|
||
| `xai-agent-lifecycle` | Electron 主进程 | 生命周期 |
|
||
|
||
**7 个内置工具**：`read_document` / `create_document` / `update_document` / `delete_document` / `search_documents` / `list_documents` / `view_history`
|
||
|
||
**Agent 对话流程**：
|
||
```
|
||
用户消息 → chat()
|
||
→ 构建 system prompt（人格 + 工具列表 + 核心原则）
|
||
→ callLLM(messages)
|
||
→ 有 API Key → OpenAI-compatible API（支持 tool calling）
|
||
→ 无 API Key → 离线模式（模拟回复）
|
||
→ 如果有 toolCalls → 执行工具 → 工具结果推入对话 → 再调 LLM
|
||
→ 返回最终回复
|
||
```
|
||
|
||
### 3.4 Electron 桌面应用
|
||
|
||
**代码位置**：REPO-014 → `product-source/hololake-desktop/`
|
||
|
||
**主进程设计**：
|
||
- 开发模式：`spawn('npx', ['tsx', serverScript])` 启动外部服务器
|
||
- 生产模式：`require('server-bundle.js')` 内嵌在主进程
|
||
|
||
### 3.5 签名安装
|
||
|
||
**证书**：`Developer ID Application: bei sun (825A9L3G7Q)`
|
||
|
||
**踩坑链**：
|
||
|
||
| 步骤 | 问题 | 修复 |
|
||
|------|------|------|
|
||
| 1 | AppleDouble（`._*`）导致 asar 崩溃 | `dot_clean` 递归清理 |
|
||
| 2 | asar 在 ExFAT 上仍然崩溃 | `"asar": false` |
|
||
| 3 | codesign 在 ExFAT 上复制又产生 `._*` | 在本地磁盘 /tmp 构建 |
|
||
| 4 | node_modules `.bin` 符号链接断 | `npm rebuild` |
|
||
| 5 | codesign 卡住（CPU 0%） | 等钥匙串弹窗 → 点"始终允许" |
|
||
| 6 | `Failed to reserve virtual memory for CodeRange` | entitlements.plist 加 JIT 权限 |
|
||
| 7 | 生产模式 `npx tsx` 找不到 | 改成 `require(server-bundle.js)` |
|
||
| 8 | identity 前缀报错 | 去掉 `Developer ID Application:` 前缀 |
|
||
| 9 | Helper app 里 `.cstemp` 残留 | `find -name .cstemp -delete` |
|
||
|
||
**entitlements.plist 内容**：
|
||
```xml
|
||
com.apple.security.cs.allow-jit = true
|
||
com.apple.security.cs.allow-unsigned-executable-memory = true
|
||
com.apple.security.cs.allow-dyld-environment-variables = true
|
||
```
|
||
|
||
---
|
||
|
||
## 四 · 代码路径映射（第五域 → REPO-014）
|
||
|
||
| 模块 | REPO-014 路径 | 说明 |
|
||
|------|------|------|
|
||
| Git 引擎 | `product-source/guanghu-knowledge-base/server/git-engine.ts` | 368 行 |
|
||
| API 服务器 | `product-source/guanghu-knowledge-base/server/index.ts` | 264 行，15 个端点 |
|
||
| 人格 Agent | `product-source/guanghu-knowledge-base/server/persona-agent.ts` | 462 行 |
|
||
| React 前端 | `product-source/guanghu-knowledge-base/src/` | 6 个组件 + CSS |
|
||
| API 客户端 | `product-source/guanghu-knowledge-base/src/api.ts` | 前端和 Agent 共用 |
|
||
| Electron 主进程 | `product-source/hololake-desktop/electron/main.ts` | 157 行 |
|
||
| IPC 桥梁 | `product-source/hololake-desktop/electron/preload.ts` | Forgejo 接口预留 |
|
||
| 构建配置 | `product-source/hololake-desktop/package.json` | 签名 + asar:false |
|
||
| Forgejo 集成 | `product-source/hololake-desktop/forgejo/INTEGRATION.md` | 声明式集成 |
|
||
| 知识库 CSS | `product-source/guanghu-knowledge-base/src/styles/app.css` | 746 行深色主题 |
|
||
|
||
**前端组件**：
|
||
| 组件 | 路径 | 功能 |
|
||
|------|------|------|
|
||
| App | `src/App.tsx` | 三栏布局主组件 |
|
||
| DocTree | `src/components/DocTree.tsx` | 文档树导航 |
|
||
| Editor | `src/components/Editor.tsx` | Markdown 编辑器 |
|
||
| SearchBar | `src/components/SearchBar.tsx` | 防抖搜索 |
|
||
| VersionHistory | `src/components/VersionHistory.tsx` | 版本历史 + diff |
|
||
| AgentChat | `src/components/AgentChat.tsx` | Agent 对话面板 |
|
||
|
||
---
|
||
|
||
## 五 · 已知问题（后续人格体排查清单）
|
||
|
||
| 编号 | 问题 | 影响 | 建议修复方向 |
|
||
|------|------|------|------|
|
||
| FIX-01 | server-bundle.js 未编译 | 生产模式 App 白屏 | esbuild 打包 server → dist-electron/server-bundle.js |
|
||
| FIX-02 | 生产模式 require 路径 | 打包后找不到 server-bundle | 确认 __dirname 在 asar:false 下指向正确位置 |
|
||
| FIX-03 | Agent LLM 未配置 | Agent 离线模式 | 加 UI 配置 API Key |
|
||
| FIX-04 | Forgejo 远程同步 | 只有本地 | 实现 preload → server → git remote 对接 |
|
||
| FIX-05 | asar 未启用 | 包 252MB 偏大 | 解决 ExFAT AppleDouble 后可启用 |
|
||
| FIX-06 | Express v5 ESM/CJS 兼容 | esbuild 打包可能报错 | 测试 `--format=cjs` 或 `--format=esm` |
|
||
|
||
---
|
||
|
||
## 六 · 提交链
|
||
|
||
| 提交 | 内容 | REPO-014 远端验证 |
|
||
|------|------|------|
|
||
| `070b11a` | Outline 样本组件卡 10 张 | ✓ |
|
||
| `920b6bf` | Git 替代数据库决策文档 | ✓ |
|
||
| `ecfeca4` | 知识库模块 v0.1.0 | ✓ |
|
||
| `047f37e` | Desktop v0.5.0 | ✓ |
|
||
| `dcf8f7d` | 人格 Agent v0.1.0 | ✓ |
|
||
| `84a631d` | 签名修复 + 开发日志 | ✓ |
|
||
|
||
---
|
||
|
||
## 七 · 环境信息
|
||
|
||
- **OS**: macOS 26.5.2 (darwin arm64)
|
||
- **Node**: v22+
|
||
- **Electron**: v35
|
||
- **文件系统**: ExFAT（移动硬盘 JZAO）+ APFS（本地磁盘）
|
||
- **签名证书**: Developer ID Application: bei sun (825A9L3G7Q)
|
||
- **SSH**: ~/.ssh/id_ed25519（SG-001）
|
||
- **REPO-012**: `https://guanghulab.com/code/bingshuo/guanghu-ice-heart`（本文档所在仓库）
|
||
- **REPO-014**: `https://guanghulab.com/code/bingshuo/hololake-system-architecture`（代码仓库）
|
||
- **REPO-015**: `https://guanghulab.com/code/bingshuo/grok-build-upstream-mirror`（Grok 上游镜像，只读学习）
|
||
- **Grok Build 本地镜像**: `/Volumes/JZAO/HoloLake/upstream-mirrors/grok-build-upstream.git`
|
||
- **Forgejo 离线包**: `~/Desktop/光湖代码频道-Forgejo-16.0.1-完整离线包/`
|