# GSDJDesktop - 软件开发细节 (Ver 5.1.777)

[![Version](https://img.shields.io/badge/version-5.1.777-green.svg)](https://github.com/eug3/GSDJWorkspace)
[![Angular](https://img.shields.io/badge/Angular-22.2-red.svg)](https://angular.io/)
[![Electron](https://img.shields.io/badge/Electron-44.4-47848F.svg)](https://electronjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-24.18+-green.svg)](https://nodejs.org/)
[![MCP SDK](https://img.shields.io/badge/MCP-1.30+-purple.svg)](https://modelcontextprotocol.io/)
[![Syncfusion](https://img.shields.io/badge/Syncfusion-EJ2%2034-orange.svg)](https://www.syncfusion.com/)

更新日期 2026年10月2日

> 本文是面向开发者的技术细节文档。产品功能介绍请看 [项目介绍](/README.md) 与 [桌面客户端](/gsdjdesktop.md)。

---

## 1. 项目简介

**GSDJDesktop** 是怪兽的家资产评估工作套件的桌面主应用，基于 **Electron 44 + Angular 22** 构建，源码版本为 **5.1.777**（不等同于下载站安装包版本）。它集成了 20+ 专业评估工具、Deep Agent 执行引擎、MCP (Model Context Protocol) 服务器、.NET Sidecar (`GSDJSidecar` 承载 `GSDJEdge.Net`) 与 RAGFlow 知识库。

### 1.1 核心特色

| 特色                 | 描述                                     | 技术实现                              |
| -------------------- | ---------------------------------------- | ------------------------------------- |
| 🤖 **Deep Agent**    | 带约束的 AI 执行引擎                     | deepagents 1.10+、LangChain 1.4+      |
| 📁 **文件管理**      | 强大的文件系统操作和管理能力             | Node.js fs-extra 11+ + chokidar 5     |
| 🔗 **MCP 协议**      | 标准化的模型上下文协议                   | MCP SDK 1.30+                         |
| 📊 **专业计算**      | 评估工具数学计算                         | Rust WASM + .NET Sidecar              |
| 🌐 **跨平台**        | 支持 Windows、macOS、Linux               | Electron Forge 7 + electron-updater   |
| 🔐 **安全治理**      | 主进程 IPC 桥接 + 工具白名单             | Zod 4 schema 验证                     |
| ⚡ **Zoneless**       | Angular 22 zoneless 渲染 + signals 状态  | `provideZonelessChangeDetection()`    |
| 🧩 **Standalone**    | 全 standalone 组件 + `bootstrapApplication`| `main.ts` 直接启动，无 NgModule      |

---

## 2. 技术栈

### 2.1 前端框架（renderer）

| 技术               | 版本   | 作用                           |
| ------------------ | ------ | ------------------------------ |
| Angular            | 22.2+  | **standalone + zoneless** 模式 |
| Syncfusion EJ2     | 34.2+  | 企业级 UI 组件库（40+ 组件）   |
| TypeScript         | 6.0+   | 类型安全                       |
| RxJS               | 7+     | 响应式状态管理                 |
| Angular CDK        | 22.2+  | 组件基础设施                   |
| ECharts            | 6.1+   | 数据可视化                     |
| KaTeX / MathJax    | -      | 数学公式渲染                   |
| highlight.js       | 11.11+ | 代码高亮                       |
| Webpack            | 5.107+ | 模块打包                       |

### 2.2 桌面技术（main process）

| 技术               | 版本    | 作用                            |
| ------------------ | ------- | ------------------------------- |
| Electron           | 44.4+   | 跨平台桌面应用框架              |
| Electron Forge     | 7.11+   | 应用打包（deb/dmg/rpm/squirrel）|
| electron-updater   | 6.8+    | 自动更新                        |
| electron-log       | 5.4+    | 日志收集                        |
| electron-store     | 11+     | 持久化配置                      |
| **GSDJSidecar**    | -       | **自包含 .NET + Python 运行时子进程，替代 `electron-edge-js`** |
| Piscina            | -       | 线程池                          |
| Rust WASM          | -       | 高性能数学计算                  |

> 注：从 4.3 起，`.NET` 集成统一通过 **`GSDJSidecar` 子进程**承载，主进程通过 localhost HTTP 与之通信。旧的 `electron-edge-js` + `_Edge` 方案不再使用。

### 2.3 后端服务（embedded）

| 技术               | 版本   | 作用                           |
| ------------------ | ------ | ------------------------------ |
| Express            | 5.2+   | 嵌入式 HTTP 服务器             |
| Socket.io          | 4.8+   | 流式 AI 响应、文件变更推送     |
| SQLite + sql.js    | 1.14+  | 本地数据存储                   |
| TypeORM            | 1.0+   | ORM                            |
| axios              | 1.18+  | HTTP 客户端                    |

### 2.4 AI 与智能

| 技术               | 版本   | 作用                            |
| ------------------ | ------ | ------------------------------- |
| MCP SDK            | 1.30+  | Model Context Protocol 官方实现 |
| @langchain/core    | 1.2+   | LangChain 核心                  |
| @langchain/openai  | 1.5+   | OpenAI 兼容接口                 |
| @langchain/anthropic | 1.5+ | Anthropic Claude 接口           |
| langchain          | 1.4+   | AI 应用框架                     |
| deepagents         | 1.10+  | Deep Agent 执行引擎             |
| Zod                | 4.4+   | 运行时 schema 验证              |

### 2.5 文件与存储

| 技术                    | 版本    | 作用                                 |
| ----------------------- | ------- | ------------------------------------ |
| fs-extra                | 11.3+   | 增强文件系统                         |
| chokidar                | 5.0+    | 文件系统监听                         |
| cos-js-sdk-v5           | 1.10+   | 腾讯云 COS（浏览器端）               |
| cos-nodejs-sdk-v5       | 2.15+   | 腾讯云 COS（Node 端）                |
| cheerio / markdown-it   | -       | 文档解析                             |
| jspdf / html2canvas     | 4.x     | PDF 生成                             |
| fast-xml-parser         | 5.9+    | XML 解析                             |
| archiver / jszip        | -       | 压缩打包                             |
| iconv-lite / chardet    | -       | 文件编码识别                         |
| @extractus/article-extractor | 8.1+ | 网页正文提取（用于 `internet_fetch`） |
| file-type               | 22+     | 文件类型识别                         |

### 2.6 辅助

office-ui-fabric-core（图标）、pinyin 4.0（中文拼音）、opencv.js（计算机视觉）、financejs（金融计算）、http-proxy-middleware（HTTP 代理）、body-parser / cors / express 5 中间件。

---

## 3. 架构总览

```mermaid
graph TB
    subgraph Renderer["渲染进程 (Angular 22 standalone + zoneless)"]
        A1[Syncfusion UI 组件]
        A2[评估工具 tools/*]
        A3[Deep Agent 对话面板]
        A4[window.api IPC 代理]
    end

    subgraph Main["主进程 (Electron 44)"]
        B1[IpcService / IPC Handlers]
        B2[MCP Server mcp-bridge]
        B3[Deep Agent Harness]
        B4[Express HTTP Server]
        B5[Socket.io Streaming]
        B6[GSDJSidecar 子进程]
        B7[chokidar 文件监听]
        B8[Issue Inbox / Ui Agent]
    end

    subgraph Native["本地能力"]
        C1[Rust WASM 数学]
        C2[GSDJEdge.Net 通过 Sidecar]
        C3[SQLite 本地库]
        C4[腾讯云 COS]
    end

    subgraph Remote["远程服务"]
        D1[Workers planner]
        D2[RAGFlow 知识库]
        D3[OpenAI/Anthropic/Qwen]
        D4[Service Registry]
    end

    A4 --> B1
    A3 --> B3
    A3 --> B8
    B1 --> B2
    B1 --> B3
    B1 --> B6
    B2 --> C4
    B3 --> B2
    B3 --> D1
    B3 --> D2
    B3 --> D3
    B3 --> D4
    B6 --> C2
    B4 --> B5
    B7 --> A1
```

### 3.1 目录结构

```
GSDJDesktop/
├── src/
│   ├── index.ts                  # Electron 主进程入口
│   ├── mainlibrary/              # 主进程核心
│   │   ├── IpcService.ts
│   │   ├── deepagent/            # Deep Agent harness
│   │   ├── httpservices/         # Express + MCP + Socket.io + Sidecar
│   │   ├── ipcfunction/          # IPC handlers (database/httpServer/...)
│   │   ├── mcpclient/            # MCP 客户端
│   │   ├── workers/              # Piscina 线程池
│   │   ├── runtimesetup.ts       # _runtime 二进制部署 + 增量更新
│   │   └── ...
│   ├── preload/                  # preload 桥接（contextBridge）
│   ├── sharelibrary/             # 主进程/渲染进程共享类型与协议
│   ├── renderer/                 # Angular 渲染进程（standalone）
│   │   ├── main.ts               # bootstrapApplication(AppComponent, appConfig)
│   │   ├── app/
│   │   │   ├── app.config.ts     # provideZonelessChangeDetection + provideRouter
│   │   │   ├── app.routes.ts     # 路由表（实际上为空，走 Tab SPA）
│   │   │   ├── tools/            # 20+ 评估工具
│   │   │   ├── accounts/         # 财务工具
│   │   │   ├── projects/         # 项目管理（工作区）
│   │   │   ├── systems/          # 系统设置
│   │   │   ├── services/         # Angular 服务
│   │   │   ├── helper/general/menu-data.ts  # 主菜单定义
│   │   │   └── ...
│   │   └── ...
│   └── _runtime/                 # 未 git 跟踪：Sidecar + .NET + Python 二进制
├── crates/gsdj-wasm/             # Rust WASM 源码
├── dotnetlib/                    # 本地 .NET 集成（构建期同步到 _runtime）
├── patches/                      # 第三方依赖补丁
├── scripts/                      # 构建 / WASM / .NET 同步脚本
├── angular.json
├── forge.config.ts               # Electron Forge 配置
├── package.json
└── webpack.*.config.ts
```

> 主进程目录名为 `mainlibrary`（注意单 `l`），不是 `mainlibray`。

---

## 4. Deep Agent Harness

Deep Agent harness 的实现集中在 `src/mainlibrary/deepagent/`，入口 `deep-agent-engine.ts` 封装 LangChain Deep Agents SDK，集成 Worker 池、流式 event 适配、Human-in-the-Loop、订阅取消等能力。

### 4.1 架构关键点

- **不是裸模型调用**，而是带约束的 Agent 执行引擎
- system prompt = `default-system-prompt.ts` 基础提示词 + workflow 提示词 + skills 提示词 + UI capability 上下文 + runtime capability（沙箱可执行语言）+ 项目记忆/记忆图谱
- tools 组合（在 `deep-agent-engine.ts` 中拼装）：
  - **MCP 工具**：来自远程 MCP server 的工具，通过 `mcp-langchain-bridge.ts` 转 LangChain 工具
  - **工作区/文档工具**：`workspace-document-tools.ts` 操作底稿工作区
  - **UI capability 工具**：`ui-capability-tools.ts` + `uiAgent.ts` IPC，受 `getActiveUiCapabilitySnapshot()` 约束，模型只能调用注入的 action id
  - **联网搜索工具**：`internet-search-tools.ts` 提供 `internet_search`、`internet_fetch`
  - **RAGFlow 知识库**：`ragflow-tools.ts`
  - **记忆图谱工具**：`memory-graph-tools.ts`（实体/关系增删改查）
  **金融分析/计算工具**：`calculator-tool.ts`、`financial-analysis-tools.ts`、`excel-formula-analysis.ts`（受 `*-tool-policy.ts` 条件控制）
  - **沙箱（PythonRuntimeBackend）**：`python-runtime-backend.ts` 通过 Sidecar HTTP 端点 `/api/runtime/*` 执行 Python、ls/read/grep/glob/write/edit/upload/download
  - **JavaScript 运行时**：`javascript-runtime.ts` 在 Worker 内执行 JS（当 runtime capability 允许时暴露 `execute_javascript`）
  - **内置人机工具**：`report-issue-tool.ts`（向 Issue Inbox 申报问题）、`external-skill-installer-tool.ts`（安装外部 skill）、`read-skill-tool.ts`（读取 skill 元数据）
- 所有工具受 **Skills 白名单** 过滤（`skill-tools.ts` 的 `filterToolsBySkills()`）
- 模型支持：`ChatOpenAI`（OpenAI / Qwen 兼容）、`ChatAnthropic`（Claude）
- 配套部件：`createDeepAgent`、`MemorySaver` checkpointer、模型响应兼容 middleware、`PythonRuntimeBackend`、Human-in-the-Loop、`progressive-tool-loader.ts` 渐进式工具加载

#### 4.1.1 工作流控制与文件处理

- **工作流控制**：通过 `run-control.ts` 支持工作流**暂停 / 恢复 / 重启**，继续执行依赖可用的运行状态与检查点
- **紧凑状态检查点（compact checkpointing）**：`createSharedWorkflowCheckpoint(..., {compact:true})` 优化工作流状态的序列化与恢复体积
- **渐进式大文件加载**：`progressive-tool-loader.ts` 对超大文件渐进加载，二进制读取通道设有 **512 MiB** 上限；不代表所有文本读取或解码都在后台线程完成
- **Python venv 缓存**：预装常用 Python 包并持久化 venv 缓存，加速工作流工具执行

#### 4.1.2 宿主持久化与恢复边界

共享引擎提供运行控制与存储端口；Desktop 在 `deepagent/workflow-run-store-sqlite.ts` 实现 SQLite 存储，Sense 在 `src/lib/workflow-run-store-mongo.ts` 实现 MongoDB 存储。`GSDJAgentTrace` 记录执行轨迹，由各宿主单独保存。

当前 main 的 Sense 适配器在 BSON 文档超限时会移除 `thread_state`，仍超限时继续移除 `event_log` 后重试。因此能查到任务记录不等于具备完整断点或轨迹，不能承诺超大运行可在重启后恢复。

#### 4.1.3 同花顺 Excel / FT 数据链路

`thsfunction.service`、固定资产、find 和熵权工具通过 `ths-ft-client.ts` 统一请求 `window.api.thsData.request`。preload 转入 `ipcfunction/ths-data.ts`，主进程读取网页登录 Cookie；有 `thsserver` 时请求企业 `/ths_ft/request`，否则请求 FT 上游。

指标使用 `paramExcel` 并转换回业务层的 `tables`；交易日将 `THS_Date_Query` 转成 FT 日期查询表单，历史成员使用 `THS_DR` 数据池。FT `/quantapigw/` 路径中的 openapi 字样不代表旧 API token 模式。快查企业查询与问财服务不应按 API 字样一并替换。

强化登录在 `network.ts` 通过 iFinD Mac Excel 页面完成，并等待落地页换取会话。操作说明见 [桌面客户端](/gsdjdesktop.md)；代理协议依据仓库 `GSDJTHSDIGoProxy/DESKTOP_FT.md`。不在文档中保存 Cookie、令牌或实际组织地址。

### 4.2 服务端协同

- 本地执行前先调用 **Workers `planner`**，由服务端做 workflow 路由和缺失输入判断（`service-registry.ts` + `@gsdj/workflow-engine`），再由 Desktop 按 `WorkflowArtifact` 执行
- 服务端 Service Registry 通过 ETag 缓存浏览器 catalog/spec，避免重复拉取
- workflow/service 模式下，运行时只使用服务端下发的 remote skills；Desktop 本地 builtin/custom skills 不再参与 workflow 执行，便于统一升级、授权和治理
- Workflow 编译产物由 `workflow-graph-builder.ts` → `@gsdj/workflow-engine` 共享库负责拓扑排序、节点解析、参数模板渲染、Python tool script 解析

### 4.3 MCP 主进程桥接

- 所有 MCP 工具调用统一走主进程 `mcp-bridge` IPC（preload 侧 `mcpBridgeAPI`）
- Renderer 不直接创建 MCP SDK HTTP 传输连接
- 便于集中鉴权、网络治理、审计、错误观测

### 4.4 Issue Inbox（AI 问题申报）

Deep Agent 可通过 `report_issue` 工具将执行过程中遇到的问题写入 Issue Inbox：

- 数据存于 `issue-store.ts`（持久化），主进程通过 `issueInbox.ts` 暴露 IPC
- Renderer 侧 `SystemIssueInboxComponent` 渲染列表，并通过 `issueInboxAPI` / `ISSUE_INBOX_CHANGED` 频道接收变更推送

```mermaid
sequenceDiagram
    participant UI as Angular UI
    participant IPC as mcp-bridge (主进程)
    participant Agent as Deep Agent
    participant Planner as Workers planner
    participant MCP as MCP Server
    participant Model as AI 模型
    participant Sidecar as GSDJSidecar

    UI->>Agent: 发送任务
    Agent->>Planner: 请求 workflow 路由
    Planner-->>Agent: 返回结构化计划
    Agent->>Model: 调用模型 (流式)
    Model->>IPC: 请求工具调用
    IPC->>MCP: 执行 MCP 工具
    MCP-->>IPC: 工具结果
    IPC->>Sidecar: Python/ls/read (如需)
    Sidecar-->>IPC: 沙箱结果
    IPC-->>Model: 返回上下文
    Model-->>Agent: 生成最终答案
    Agent-->>UI: 流式输出（Socket.io）
```

---

## 5. MCP 工具清单

MCP server 实现位于 `src/mainlibrary/httpservices/mcpserver/`，工具注册在 `tools/index.ts`。工具按类别（`category`）分组，每类有 `order`，受构造器 `enabledTools` 参数控制是否暴露。默认启用：`file_operations`、`memory`、`ragflow`、`server_tools`、`internet_search`。

### 5.1 文件系统工具（`file_operations`）

| 工具                  | 功能                 |
| --------------------- | -------------------- |
| `read_file`           | 读取文本文件内容     |
| `write_file`          | 写入文件             |
| `list_directory`      | 列出目录（默认过滤隐藏项） |
| `create_directory`    | 创建目录             |
| `copy_item`           | 复制文件/目录        |
| `move_item`           | 移动/重命名          |
| `delete_item`         | 删除文件/目录        |
| `search_files`        | 按文件名搜索         |
| `get_file_info`       | 获取大小/时间/权限   |
| `open_document_in_tab`| 在软件标签页中打开预览（Word/Excel/Markdown/PDF/图片），**不是文档分析工具** |

> 所有路径都强制约束在 `contentRootPath`（当前项目底稿工作区根）内，防路径穿越。

### 5.2 记忆图谱工具（`memory`）

基于 `tools/memory-handler.ts` 的 `KnowledgeGraphManager`，按 `workspaceId` 持久化在 `contentRootPath` 下：

| 工具                    | 功能                          |
| ----------------------- | ----------------------------- |
| `create_entities`       | 创建多个实体                  |
| `create_relations`      | 在实体间建立主动语态关系      |
| `add_observations`      | 为实体添加观察                |
| `delete_entities`       | 删除实体                      |
| `delete_observations`   | 删除观察                      |
| `delete_relations`      | 删除关系                      |
| `read_graph`            | 读取完整图谱                  |
| `search_nodes`          | 按查询搜索节点                |
| `open_nodes`            | 按名称打开节点                |
| `memory_stats`          | 图谱统计                      |

### 5.3 知识库工具（`ragflow`）

需要预先 `configure_ragflow`，未配置时不暴露：

| 工具                       | 功能              |
| -------------------------- | ----------------- |
| `ragflow_list_datasets`    | 列举数据集        |
| `ragflow_retrieval`        | 知识检索          |
| `ragflow_health_check`     | 健康检查          |

### 5.4 联网搜索工具（`internet_search`）

| 工具               | 功能                                  |
| ------------------ | ------------------------------------- |
| `internet_search`  | 调用 SearxNG 多引擎搜索（引擎/类别/语言/时间过滤） |
| `internet_fetch`   | 抓取 URL 内容并提取正文，去除 HTML 标签 |

### 5.5 系统工具（`server_tools`）

| 工具                | 功能                                    |
| ------------------- | --------------------------------------- |
| `get_server_info`   | 获取服务器配置和能力                    |
| `configure_ragflow` | 配置/更新 RAGFlow 端点和密钥，启用对应知识库工具 |

### 5.6 工具类别顺序

`ListTools` 返回的 tools 按 category priority 排序：`SERVER_TOOLS(0)` → `FILE_MANAGEMENT(1)` → `INTERNET_SEARCH(2)` → `MEMORY(3)` → `KNOWLEDGE_BASE(4)`，类内再按 `order` 排序。

---

## 6. 评估与业务工具清单

主菜单定义在 `src/renderer/app/helper/general/menu-data.ts`，由 `TabHandlerService` 通过 `ViewContainerRef` 动态插入组件。菜单结构分为「系统 / 项目 / 财务 / 工具 / 数据 / Excel 操作 / 帮助」七个顶级项；下表按主菜单当前**实际启用**的入口整理（`menu-data.ts` 中被注释掉的选项未列出，但代码已实现）。

### 6.1 系统 / 项目 / 财务

| 菜单入口              | 组件 ID                                | 位置 |
| --------------------- | -------------------------------------- | ---- |
| 项目管理              | `WorkSpaceComponent`                   | systems |
| 系统设置              | `SystemSettingsPanelComponent`         | systems |
| 项目设置              | `ProjectsSettingComponent`             | projects |
| 底稿管理              | `MyfileManagerComponent`               | myfile-manager |
| 资料采集              | `ArchiveManagementComponent`           | archive-management |
| 数据管理查阅          | `AccountsDatamanagerComponent`         | accounts |
| 固定资产查询          | `AccountsFixedAssetsManagerComponent`  | accounts |
| 科目明细整理          | `AccountsReceivableAndPayableComponent`| accounts |
| 函证管理              | `AccountsConfirmationLetterCreationComponent` | accounts |

### 6.2 工具（评估专业工具）

实际启用的入口位于 `tools/` 目录下：

| 目录 | 工具 | 菜单文本 |
| --- | --- | --- |
| `tools-agents-mcp` | `ToolsAgentsMcpComponent` | （Deep Agent 入口，见 §4） |
| `tools-readwrite-with-ai` | `ToolsreadwritewithaiComponent` | 宏观及行业 |
| `tools-depreciation-table` | `DepreciationTableComponent` | 折旧摊销计算 |
| `tools-patent-life-cycle` | `PatentLifeCycleComponent` | 专利生命周期计算 |
| `tools-softwareproject-cost-estimation` | `ToolsSoftwareprojectCostEstimationComponent` | 软件项目成本(COCOMO)测算 |
| `tools-enterprise-value-entropy-method` | `ToolsEnterpriseValueEntropyMethodComponent` | EV/S（熵权法） |
| `tools-enterprise-value-ebitdalinear-regression-method` | `ToolsEnterpriseValueEBITDALinearRegressionMethodComponent` | EV/*.*（线性回归） |
| `tools-china-mrp-clac` | `ToolsChinaMrpClacComponent` | 中国MRP查询 |
| `tools-discountrate-realestate` | `ToolsDiscountrateRealestateComponent` | 实物资产报酬率测算 |
| `tools-discountrate-average-asianoption` | `ToolsDiscountrateAverageAsianoptionComponent` | 亚式期权(APP)流动性折扣率测算 |
| `tools-get-org-ipinfo` | `ToolsGetOrgIpinfoComponent` | 企业知识产权获取 |
| `tools-enterprise-equity` | `ToolsEnterpriseEquityComponent` | 企业股权穿透 |
| `tools-analytic-hierarchy-process` | `ToolsAnalyticHierarchyProcessComponent` | AHP层次分析 |
| `tools-esop` | `ToolsEsopComponent` | 员工持股计划(ESOP)估值 |

> 已实现但菜单暂未启用的组件：`tools-discountrate-european-option`、`tools-discountrate-intellectualproperty`、`tools-rdproject-cost-method`、`tools-report-generator-studio`，以及财务分析系列（现金流/毛利率/成本/收入分析）。这些保留在代码中以备启用。

### 6.3 数据 / Excel 操作 / 帮助

| 菜单入口              | 组件 ID                                |
| --------------------- | -------------------------------------- |
| 机器设备价格检索      | `DataMachineSearchComponent`           |
| 二手车辆价格检索      | `DataCarinfoSearchComponent`           |
| 园林苗木价格检索      | `DataMiaomuSearchComponent`            |
| Excel 余额表转申报    | `HelperExcelGeneralBatchtoolsComponent`|
| 智能表格合并          | `HelperExcelToolsMergeComponent`       |

### 6.4 文档查看器（features/document-viewers/）

`features/document-viewers/` 提供 4 类文档查看组件，供 `MyfileManagerComponent` / `open_document_in_tab` 复用：

- `ToolsWordEditorComponent`
- `ToolsExcelViewerComponent`
- `ToolsMarkdownEditorComponent`
- `ToolsPdfViewerComponent`

---

## 7. .NET Sidecar 后端 (GSDJSidecar / GSDJEdge.Net)

### 7.1 架构演进

4.3 起，`.NET` 集成从 **`electron-edge-js` in-process 模型** 迁移到 **`GSDJSidecar` 子进程模型**：

- `GSDJSidecar`（开源 .NET 自包含可执行，对应 `dotnetlib/GSDJSidecar`）作为独立子进程运行，承载 `GSDJEdge.Net.dll`
- 主进程通过 **localhost HTTP** 调用 Sidecar（`httpservices/gsdj-sidecar.ts` 启动/健康检查；`httpservices/gsdj-dotnet-client.ts` RPC + 事件回传）
- 渲染进程通过 `window.api.dotnetapi(args)` → IPC `DOTNET_API` → 主进程 Sidecar client → Sidecar HTTP → `IGSDJEdgeService.DotNetApiAsync` 完成调用
- Sidecar 同时承载 **bundled Python runtime**，Deep Agent 的 `PythonRuntimeBackend` 通过 `/api/runtime/*` 调用同一 Sidecar 进程

### 7.2 关键路径规则（已从 `_Edge` 改名为 `_runtime`）

- 二进制目录从 **`src/_Edge/`** 改名为 **`src/_runtime/`**（2026-06-14 全量重命名，见仓库 memory `edge-runtime-rename.md`）
- 对应函数：**`getEdgeAppRoot()` → `getRuntimeAppRoot()`**（`runtimesetup.ts`）
- `runtimesetup.ts` 负责把 `_runtime` 部署到可写路径并按 hash 做增量更新；ASAR 打包通过 `unpack` 规则解出
- **不再设置** `EDGE_USE_CORECLR=1`、不再引用 `electron-edge-js`
- `scripts/sync-dotnet-runtime.cjs` 负责把 `GSDJDesktop/dotnetlib` 中的 Sidecar 编译产物复制到 `_runtime`，并按 RID 分平台（`win-x64`/`win-arm64`/`osx-arm64`/`linux-x64`）
- Sidecar 启动会先调用 `cleanupOrphanedSidecars()` 清理上次崩溃残留的 `GSDJSidecar` 进程，以防端口占用

### 7.3 平台差异化

| 平台    | Sidecar 可执行        | 二进制目录可写位置              |
| ------- | --------------------- | ------------------------------- |
| Windows | `GSDJSidecar.exe`     | 应用驱动盘根目录 / `userData`  |
| macOS   | `GSDJSidecar`         | `app.getPath("userData")`       |
| Linux   | `GSDJSidecar`         | `app.getPath("userData")`       |

### 7.4 .NET 运行时兼容性

当前 `GSDJSidecar` 与 `GSDJEdge.Net` 工程均以 **net10.0** 为目标框架，开发构建需 .NET 10 SDK。Sidecar 按平台自包含发布，最终用户无需另装对应 .NET 运行时。

### 7.5 故意保留的 "Edge" 字样（不要改）

- `GSDJEdge.Net.dll` / `GSDJEdge.Net` 类库 / `IGSDJEdgeService` 接口名
- IPC 字符串值 `'app:app:edge-remote-update-status'`（运行时契约）

---

## 8. 自动更新与发布

- **electron-updater 6.8+**：增量更新
- **electron-forge/publisher-s3**：当前发布配置使用 Cloudflare R2（S3 兼容接口）
- **GitHub Actions**：`.github/workflows/main.yml`，push 到 `main` 或手动运行时触发工作流；版本更新与构建任务受提交信息中的 `[beta:N]` / `[release:N]` 条件控制。普通文档提交的发布任务跳过，不代表测试通过
- **Beta 渠道**：`make:beta` / `publish:beta` 通过 `PUBLISH_TARGET=beta` 区分

---

## 9. 环境要求与构建

### 9.1 开发环境

| 组件          | 要求                    | 备注                          |
| ------------- | ----------------------- | ----------------------------- |
| Node.js       | >=24.18 且 <25（**必须**） | 以 package.json engines 为准                           |
| PNPM          | >=11（**必须**）         | packageManager 固定 11.22.0；不用 npm/yarn            |
| TypeScript    | 6.0+                    |                               |
| Rust toolchain| -                       | 用于构建 WASM                 |
| .NET SDK      | 10              | GSDJEdge.Net 依赖             |
| OS            | Windows 10+/macOS/Linux | 64位                          |
| 内存          | 8GB+（推荐 16GB）       | ng build 需要 `NODE_OPTIONS=--max-old-space-size=8192` |

### 9.2 常用脚本

| 脚本                        | 说明                                                     |
| --------------------------- | -------------------------------------------------------- |
| `pnpm install`              | 安装依赖（自动执行 electron install + macOS alias 修复） |
| `pnpm run dev`              | 开发模式：Angular + Electron + WASM 监听并发             |
| `pnpm run full`             | 完整开发：Angular build + Electron start                 |
| `pnpm run start`            | Electron 静态启动（需先构建 Angular）                    |
| `pnpm run make`             | 生产构建（含 WASM + .NET sidecar）                       |
| `pnpm run make:beta`        | Beta 构建                                                |
| `pnpm run make:ci`          | CI 构建                                                  |
| `pnpm run publish`          | 发布到分发平台                                           |
| `pnpm run publish:beta`     | Beta 发布                                                |
| `pnpm run build:wasm`       | 构建 Rust WASM 模块                                      |
| `pnpm run watch:wasm`       | 监听 WASM 变化                                           |
| `pnpm run ensure:dotnet-sidecar` | 同步 .NET 运行时 sidecar                            |
| `pnpm run build:workflow-engine` | 构建 GSDJWorkflowEngine 与 GSDJAgentTrace                       |
| `pnpm run lint`             | ESLint 代码检查                                          |

### 9.3 预构建钩子

`premake` / `prefull` / `prestart` / `predev` / `prepublish` 等钩子会自动：
1. 构建 `@gsdj/workflow-engine` 与 `@gsdj/agent-trace`
2. 同步 .NET 运行时 sidecar（Debug 或 Release）并准备 EasyTier
3. 构建 WASM 模块

> 如果你直接 `pnpm run <script>` 不走 pre hook，需要自行执行这些准备步骤。

---

## 10. 安全与治理

| 方面               | 实现                                                   |
| ------------------ | ------------------------------------------------------ |
| 路径沙箱           | 文件操作严格限制在 `contentRootPath` 工作区，防路径穿越 |
| 工具白名单         | AI 工具调用受 Skills 白名单过滤（`filterToolsBySkills`）|
| Schema 验证        | 所有 AI 工具参数通过 Zod 验证（`zodToJsonSchema` 转 MCP schema） |
| 密钥隔离           | API Key 仅在主进程，不进入渲染进程 bundle              |
| 统一 IPC 桥接      | MCP / UI Agent / Issue Inbox 调用统一走主进程 IPC，便于鉴权审计 |
| UI capability 约束 | 模型只能调用主进程注入的 action id，不暴露任意 UI 接口 |
| ASAR 安全          | `_runtime` 本地模块通过 `getRuntimeAppRoot()` 定位，被 `unpack` 规则解包 |
| Sidecar 隔离       | .NET / Python 沙箱在独立子进程，主进程崩了不影响模型执行状态 |
| 孤儿进程清理       | 启动时 `cleanupOrphanedSidecars()` 清理残留 `GSDJSidecar` 进程 |
| 敏感配置           | `AuthKey_*.p8`、COS 凭据不提交到 bundle，不回显        |

---

## 11. Angular AI 实践

新增 AI 相关功能时遵循：

- **密钥只放服务端**：API Key 不进入 `environment.ts`，通过主进程代理 / MCP / Sidecar 中转
- **优先用主进程能力**：联网、文件系统、凭据访问走 `window.api.ipcRenderer` / `window.api.axios`、Socket.io 流式、MCP Server
- **工具白名单化**：只暴露最小必要工具，通过 Zod 校验，不允许模型直接访问任意 IPC 或路径
- **为非确定性设计回退**：必须具备 loading / error / retry / safe fallback
- **结构化输出**：模型优先返回结构化 JSON，服务层校验后映射到 UI
- **流式优先**：长文本/检索结果复用 Socket.io / MCP 流式
- **新 AI 页面状态**：优先用 signals / computed / `resource()` / `afterRenderEffect`（zoneless）
- **模板保持简单**：只展示 loading / error / success / retry，不拼复杂提示词
- **zoneless 注意事项**（详见仓库 memory `zoneless-migration.md`）：
  - 不要在异步回调内调用 `afterNextRender()`，会触发 `NG0203`；改用 signal + `afterRenderEffect` 在构造函数里注册
  - 周期性延迟用 `timer(N).pipe(takeUntilDestroyed)`，不要用 `setTimeout` 在视图相关代码里
  - 防抖走 `Subject().pipe(debounceTime(N), takeUntilDestroyed)`

---

## 12. 关联子项目

GSDJDesktop 是工作区核心，依赖以下子项目：

| 子项目                    | 作用                                     | 集成方式                                  |
| ------------------------- | ---------------------------------------- | ----------------------------------------- |
| `GSDJDesktop/dotnetlib`   | .NET 业务库、Excel、计算、AI、集成       | `GSDJSidecar` 子进程（承载 GSDJEdge.Net） |
| `GSDJWorkflowEngine`      | 共享 TypeScript 工作流引擎               | `@gsdj/workflow-engine` link              |
| `GSDJUserGo`              | 用户管理（Go）                        | HTTP API                                  |
| `GSDJOrgGo`               | 组织管理（Go）                        | HTTP API                                  |
| `GSDJWebServe`            | Web 前端（Angular 22）                   | HTTP API                                  |
| `GSDJWorkersDocker`       | Workers planner / Service Registry 远端  | HTTP API（带 Workers access token）       |
| `GSDJAgentTrace`         | 共享运行轨迹库                           | 宿主负责 SQLite / MongoDB 存储           |
| `GSDJTHSDIGoProxy`       | 同花顺 FT 网页登录代理与共享池             | `/ths_ft/request`                        |
| `GSDJHelpDocs`            | 文档站点                                 | -                                         |

---

## 13. 包管理规则

| 项目                | 包管理器 | 规则                          |
| ------------------- | -------- | ----------------------------- |
| GSDJDesktop         | **pnpm** | **绝不**用 npm / yarn          |
| GSDJWebServe        | npm      | 不要切换到 pnpm               |
| Python 服务         | pip      | Python >= 3.12                |
| GSDJMathGo          | go mod   | Go 1.24                       |
| GSDJDesktop/dotnetlib | dotnet | .NET 10               |

---

## 14. 常见陷阱

- **ASAR 路径**：`_runtime`（**不是** `_Edge`）必须用 `getRuntimeAppRoot()`（**不是** `getEdgeAppRoot()`），不能用 `__dirname + _runtime`
- **electron-edge-js 已废弃**：4.3 起改用 `GSDJSidecar` 子进程；如见到旧代码引用 `require('electron-edge-js')`，应迁移到 SidecarHTTP 客户端
- **`GSDJEdge.Net.*` 命名不要改**：DLL/类库/服务接口名保留 "Edge" 是历史 artifact，仅 `_Edge` 目录与 `getEdgeAppRoot` 函数名已被替换
- **ng serve 配置**：dev 模式使用 `angular.json` 的 `-c office` 配置（见 `pnpm dev` / `pnpm full`）
- **zoneless 迁移已完成**：不要在 view 代码里用裸 `setTimeout/setInterval`（见 §11 与 `zoneless-migration.md`）
- **standalone 化已完成**：不要再新建 NgModule；新组件直接 `standalone: true`，主入口走 `bootstrapApplication(AppComponent, appConfig)`，无需在 AppModule 注册
- **Tab SPA 而非路由**：`app.routes.ts` 路由数组为空，新功能页要在 `helper/general/menu-data.ts` 注册菜单项
- **GSDJMathGo vs GSDJMathMethod**：功能重叠，修改前先确认目标实现
- **生成目录**：忽略 `bin/`、`obj/`、`ngdist/`、`_runtime/`、`out/`、`dist/`，排查问题看源码
- **敏感文件**：`AuthKey_*.p8`、COS 凭据、发布配置，不要回显或提交

---

## 15. 参考文档

- 工作区总览：见工作区根目录 `README.md`
- 桌面项目详细：仓库根目录下的 `GSDJDesktop/README.md`
- 桌面 Copilot 指令：`GSDJDesktop/.github/copilot-instructions.md`
- Desktop IPC：`GSDJDesktop/src/mainlibrary/ipcfunction/README.md`
- Desktop MCP：`GSDJDesktop/src/mainlibrary/httpservices/mcpserver/README.md`
- Desktop MCP 架构：`GSDJDesktop/src/mainlibrary/httpservices/mcpserver/ARCHITECTURE.md`
- Socket 重构说明：`GSDJDesktop/src/mainlibrary/httpservices/SOCKET_REFACTOR_README.md`
- MCP 服务指南：`GSDJDesktop/src/mainlibrary/httpservices/MCP_SERVICES_GUIDE.md`
- .NET 详细说明：`GSDJDesktop/dotnetlib/` 与 `GSDJDesktop/scripts/sync-dotnet-runtime.cjs`
- `gxapp/` 文档描述另一套 Tauri 应用，不作为 GSDJDesktop 的进程架构依据。

---

## 联系方式

- 技术咨询：jun.yin@live.com
- 在线文档：/help/
- 官网：https://www.guaishoudejia.com