chore: establish YCode replication baseline and TODO

2026-10-17 02:43:49 +08:00
commit 6dc59f89ba
@@ -0,0 +1,71 @@
+# YCode
+
+借助 REA，按 WorkBuddy 的视觉、交互与功能进行 **1:1 复刻**（Windows 优先）。Electron + React；当前优先使用 OMP 内核，保留自建 OpenAI 兼容循环作为回退。
+
+> 所有查看 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 |
+| 模型接入 | OMP RPC sidecar（优先，独立 profile）；自建 `/chat/completions` + SSE 循环（回退） |
+| 存储 | 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/                   方案与验收记录
+```
+
+## 开发
+
+```bash
+npm install
+npm run dev          # 启动桌面窗口（含热更新）
+npm run build        # 类型检查 + 打包产物到 out/
+npm start            # 预览构建产物
+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:conversation-ipc # 分支、恢复、并行会话、附件和 localhost 转写
+npm run test:persistence # 实际 IPC → 会话 JSON 的顺序与终态
+npm run test:sessions # 并发读写、原子替换与冷加载
+npm run test:omp      # OMP 回合终态、取消、错误与监听清理
+npm run test:omp-session # OMP 持久会话参数与进程释放（假子进程）
+```
+
+## 首次运行
+
+1. OMP 路径通过 `YCODE_OMP_PATH` 或现有安装探测；使用 `ycode` profile。回退循环的上游地址、模型和 Key 在应用设置中配置；设置尚未同步 OMP profile。
+2. 选择**工作目录**；默认模式限制路径、写入需确认，命令执行需要明确开启完全访问。
+3. 回到对话区提问，例如「列出工作目录里有哪些文件」
+
+## 安全边界
+
+- 渲染进程没有 Node / fs / 网络能力，只能通过 preload 暴露的受限 API
+- API Key 用 Electron `safeStorage`（Windows DPAPI）加密；系统不支持时降级明文并在 UI 明确告警
+- 默认权限下工具路径做工作区逃逸检查，写入需审批；完全访问允许更广的路径与命令操作。该策略不等同于原版操作系统沙箱。
+- 外链一律交由系统浏览器打开