95 lines
5.2 KiB
Markdown
95 lines
5.2 KiB
Markdown
# YCode
|
||
|
||
借助 REA，按 WorkBuddy 的视觉、交互与功能进行 **1:1 复刻**（Windows 优先）。Electron + React；当前聊天执行路径使用 Claude Agent SDK；历史 OMP 文档不代表当前入口。
|
||
|
||
> 所有查看 WorkBuddy 实现的工作统一通过 REA。当前实现包含 mock 与未完成项，尚未达到完整 1:1；现行约定见 `AGENTS.md`，最新对话状态见 [八类对齐记录](docs/对话区域-八类对齐-2026-10-15.md)，基础证据见 [统一字体与间距](docs/统一字体与间距-2026-10-15.md)、[图表、图片与文件](docs/对话区域-图表图片文件-2026-10-15.md) 和 [对话渲染源码还原](docs/源码还原-对话渲染-2026-10-15.md)。
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 选型 |
|
||
| --- | --- |
|
||
| 桌面壳 | Electron 37（`contextIsolation` + `sandbox`，无 `nodeIntegration`） |
|
||
| 前端 | React 19 + Vite 8 + TypeScript 7 + Zustand 5 |
|
||
| 构建 | electron-vite 5 |
|
||
| 模型接入 | Claude Agent SDK（`src/main/agent/claude`），通过当前会话执行服务接入 |
|
||
| 存储 | MVP 为 JSON（`userData/`），后续替换为 SQLite |
|
||
|
||
## 目录
|
||
|
||
```
|
||
src/
|
||
main/ Electron 主进程
|
||
index.ts 窗口与生命周期
|
||
ipc.ts IPC 契约实现（唯一对外边界）
|
||
config.ts 配置持久化 + safeStorage 加密 Key
|
||
sessions.ts 会话与消息存储
|
||
gateway/ 自建模型网关
|
||
index.ts OpenAI 兼容流式请求 + 工具调用组装
|
||
sse.ts SSE 解析
|
||
agent/
|
||
loop.ts Agent 循环（模型 ↔ 工具）
|
||
tools/ 受控读写、命令、问答与任务计划
|
||
preload/index.ts contextBridge 暴露受控 API
|
||
renderer/ React 界面
|
||
shared/ 主/渲染共享类型与 IPC 契约
|
||
docs/ 方案与验收记录
|
||
```
|
||
|
||
## 日常操作与新会话
|
||
|
||
已打开本仓库后，可直接说“拉取代码”“运行 dev”“启动最新代码”“重启 dev”“停止 dev”“构建”“打包”“查看状态”。助手按 [日常操作 SOP](docs/协作/日常操作SOP.md) 调用固定入口，不先跑全量测试；新会话尚未打开仓库时，先提供项目路径。SOP 内含可复制的首条消息、动作表与阻塞处理规则。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
npm ci --legacy-peer-deps
|
||
npm run dev # 启动桌面窗口（含热更新）
|
||
npm run build # 类型检查 + 打包产物到 out/
|
||
npm start # 预览构建产物
|
||
npm run test:alignment # 十项对齐的离线状态/宿主回归，不启动模型
|
||
npm run typecheck # 仅类型检查
|
||
npm run test:markdown # 正文、表格、代码块与源文本规则
|
||
npm run test:recovered # 还原的解析器、源码处理、缓存、代码组件与数学
|
||
npm run test:media # Mermaid、图片和路径渲染恢复
|
||
npm run test:resources # 本地文件、图片、下载与实际 IPC
|
||
npm run test:font-size # 六档字号、CSS 覆盖、固定区域与动态样式
|
||
npm run test:chat # 消息顺序、发送状态与工具输出适配
|
||
npm run test:conversation # 专用工具、问答/审批、消息操作、输入与真实文件执行
|
||
npm run test:persistence # 实际 IPC → 会话 JSON 的顺序与终态
|
||
npm run test:sessions # 并发读写、原子替换与冷加载
|
||
```
|
||
|
||
## 测试组织
|
||
|
||
默认离线基线使用 `npm test`；按改动选择专项，不遍历执行整个脚本目录。测试、真实窗口验收、REA 恢复和历史工具的边界见 [脚本入口与测试范围](scripts/README.md)。`test:alignment:dom` 明确要求 DOM 依赖，不允许无声跳过后当成交互通过。
|
||
|
||
## Windows 打包
|
||
|
||
使用 Windows x64、Node.js 24.x 和 npm。当前源码构建与本次验收边界见 [十项对齐实现与验收](docs/对话输入统一对齐实现与验收-2026-10-21.md)。[旧打包 SOP](docs/打包流程SOP-2026-10-18.md) 中 OMP 与旧版本信息仅作历史参照。
|
||
|
||
~~~powershell
|
||
npm run dist:installer
|
||
~~~
|
||
|
||
该命令构建主进程/预加载/渲染器，再生成 NSIS 安装程序到 `release/`。当前配置打包 Windows Claude SDK 可执行文件；不要从 Linux 复制 `node_modules` 到 Windows，也不要省略 optional dependencies。本次只验证 Linux 源码构建，Windows 安装包和实际启动仍需本机验收，未宣称已签名或可直接覆盖生产安装。
|
||
|
||
## 首次运行
|
||
|
||
先在独立数据目录测试，避免使用生产配置：
|
||
|
||
```powershell
|
||
$env:YCODE_USER_DATA_DIR = Join-Path $env:TEMP 'ycode-alignment-review'
|
||
npm run dev
|
||
```
|
||
|
||
1. 在应用设置配置真实模型和凭据；不要把凭据放入源码或 Git。
|
||
2. 选择测试工作目录，按实际工具请求审阅授权；plan/ask 限制和默认拒绝仍有效。
|
||
3. 回到对话区提问，例如「列出工作目录里有哪些文件」
|
||
|
||
## 安全边界
|
||
|
||
- 渲染进程没有 Node / fs / 网络能力，只能通过 preload 暴露的受限 API
|
||
- API Key 用 Electron `safeStorage`（Windows DPAPI）加密；系统不支持时降级明文并在 UI 明确告警
|
||
- 当前授权由宿主与 Claude SDK 协作处理；完全访问影响工具权限。工作目录不是操作系统安全隔离，勿把未验证的 SDK 规则或旧沙箱说明当成保证。
|
||
- 外链一律交由系统浏览器打开
|