# zcode-src

**Repository Path**: lkts/zcode-src

## Basic Information

- **Project Name**: zcode-src
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZCode Desktop

**AI 编程助手桌面应用**：Electron 41（ESM）+ React 19。核心能力：多工作区管理、AI
聊天/任务会话、内嵌终端（xterm + node-pty）、Git 集成、内嵌浏览器 CUA 自动化、
远程开发（SSH / WSL / Docker / 远端 server）、cron / 错峰自动化任务、MCP / 插件 /
技能 / 子代理生态、Bots 通道（飞书/微信）。

> **仓库特殊性**：本仓库是从原应用 v3.7.6 构建产物（无 sourcemap）**逆向还原**出的
> TypeScript 源码工程。源码中的 minified 标识符与数字后缀文件（`workspace2.ts`…、
> `browser2~12.ts`）是还原产物的正常形态；`out/` 是原产物只读验收基线，`dist/` 是
> 新构建产物，两者目录树同构由 `pnpm verify:tree` 验收。方法论与事故教训见
> `docs/restore-notes.md`，仓库导览见 `AGENTS.md`。

## 进程模型

```
Electron 主进程 (apps/desktop/src/main)          —— 桌面壳：窗口/托盘/菜单/深链 zcode://
  │ utilityProcess.fork        │ MessagePort 转交          │ utilityProcess.fork
  ▼                            ▼                           ▼
host 进程 (packages/host)   渲染进程 (packages/renderer)  scheduler 进程 (packages/scheduler)
  真正的"后端"：33 个服务    React UI，sandbox +          cron / 错峰任务调度，
  经 MessagePort RPC 供渲染  contextIsolation，           node:sqlite 持久化；到点
  调用                       3 个 preload 入口            经主进程转发给 host 执行
  │
  ├── spawn detached glm 二进制（zcode-agent，每工作区一个，AI agent 运行时）
  └── ssh2 / ws → SSH 远程主机、远端 server 工作区、Web 远程控制中继
```

设计原则：**host 是后端**（渲染进程全部业务 IO 走 MessagePort RPC；主进程 IPC 只管
桌面壳职责）；**scheduler 只决定何时跑**（执行永远在 host）。

## Workspace 布局

pnpm workspace（根 + `apps/*` + `packages/*`），子包均为 `private`、`main` 直指 TS
源码，由根 esbuild / Vite 统一打包，无独立构建步骤：

| 包 | 职责 |
|---|---|
| `apps/desktop`（`@zcode/desktop-shell`） | Electron 主进程 + 3 个 preload 入口 + 应用图标，只装配不实现 |
| `packages/host` | host 服务容器（33 个服务：file/git/terminal/zcode-task…） |
| `packages/renderer` | React 渲染进程（约 270 文件：app/stores/components/hcu/intl…） |
| `packages/scheduler` | cron / 错峰任务调度（node:sqlite 持久化） |
| `packages/protocol` | IPC 通道枚举（约 120 个 `zcode:*`）与共享常量，三方契约单一事实来源 |
| `packages/rpc` | 自定义 VSCode 风格 RPC 编解码（VSBuffer 帧、VQL、ChannelServer/Client） |
| `packages/pptx-engine` | `@aiden0z/pptx-renderer` 的 strict 适配层 |
| `packages/test-utils` | vitest 公共设施（electron 桩：hijack-electron / electron-stub） |

每个子包有各自的 `README.md`。`dist/ out/ recovered/ release/ .e2e-smoke/` 均为
gitignore 的产物目录。

## 构建与运行

```bash
pnpm install        # 安装依赖（仅 electron 允许构建脚本）
pnpm build          # = build:node + build:renderer
pnpm typecheck      # tsc --noEmit（strict 全量）
pnpm test           # vitest --coverage + css 类名看护 + coverage-gate 棘轮
pnpm test:e2e       # e2e 聚合：冒烟 + model-select 探针 + command-palette 探针
pnpm verify:tree    # dist/ 与 out/ 目录树同构验收
pnpm start          # build + electron .
pnpm preview        # 直接 electron .（需已有 dist）
```

打包：`electron-builder.yml`（appId `zcode.desktop`，asar: true；mac 目前仅 `dir`
target → `release/mac-arm64/ZCode.app`）。自动更新由 electron-updater 运行时驱动。

## 验收纪律（改动后）

- 常规改动：`pnpm typecheck && pnpm test && pnpm build && pnpm verify:tree` 全绿才收
  （清单见 `docs/phase5-regression-checklist.md`）。
- vendor 替换 / 大块语义命名后：上述全套 + `pnpm smoke:e2e`。
- `styles/` 目录改动后跑 css-diff 看护；stores/hcu 的 barrel 映射改动后必跑
  model-select-probe。

## 关键契约索引

| 契约 | 位置 |
|---|---|
| IPC 通道枚举（~120 个 `zcode:*`） | `packages/protocol/src/ipcChannels.ts` |
| host 服务通道名（33 个） | `packages/host/src/providerRuntime/task2.ts` |
| RPC 协议（帧/编解码/消息类型） | `packages/rpc/src/` |
| preload 桥契约（`window.zcode` 113 键） | `apps/desktop/src/preload/index.ts` |
| vendor 共享 chunk 导出映射（412 符号） | `docs/hcu-face-mapping.md` |
| vendor 退役豁免清单 | `scripts/vendor-retired.list` |

## 文档

- `docs/architecture.md` — 架构总览（进程模型、通信、构建、测试）
- `docs/restore-notes.md` — 逆向还原方法论与事故教训
- `docs/naming-roadmap.md` / `workspace-roadmap.md` / `coverage-roadmap.md` /
  `test-milestones.md` — 命名 / 拆包 / 覆盖率 / 测试里程碑路线图（N / W / C / M 系列）
- `AGENTS.md` — AI 编码代理工程指南（含代码风格与批量改名铁律）