开发者指南

Nola Translator 由 Electron 主进程、preload、React 渲染器、Python 引擎和浏览器扩展组成。文档演示和 Toy 复用实际页面，通过内存 bridge 模拟数据；真实推理由桌面端控制。

本节供修改源代码、维护协议和构建发布的开发者使用。普通使用者应先阅读开始入门。

一、按任务选择入口

任务	阅读位置	应完成的验证
第一次运行项目	开发环境配置	依赖、界面、真实引擎分层检查
配置提交来源验证	GPG 签名配置	本地签名与 GitHub 账户关联
修改跨进程调用	API 文档	类型、schema、Python 和失败路径
提交文档或代码	如何贡献	聚焦差异、相应检查和 PR 说明

二、理解架构边界

渲染组件通过 store action 请求操作，store 访问注入的 NolaBridge；preload 暴露受控方法，主进程负责会话、文件、凭据和组件管理，再通过 JSONL 调用 Python。

浏览器通过 Native Messaging 与当前用户命名管道连接，使用受限契约。它不能取得凭据、任意文件或模型管理权限。桌面与浏览器共用单会话控制，不可各自启动独立资源路径。

三、区分环境

环境	用途	不能证明什么
文档内存演示	检查页面、导航和模拟交互	不能证明实际采集和模型运行
根目录 .venv	Python 开发与测试	不自动成为 Electron 的引擎解释器
engine/dist/NolaPythonEngine	桌面启动基础环境	不自动包含全部推理组件和权重
Windows 安装包	面向用户部署	构建成功不等于所有设备已验收

出现“开发环境可以、桌面不可以”时，先确认两边实际使用的解释器、搜索路径和组件，避免对错误环境反复安装依赖。

四、遵守项目规范

根目录 AGENTS.md 规定类型、目录、状态、事件、i18n、日志、模型和浏览器限制；DESIGN.MD 规定主题和组件约定。文档按编写规范组织，注释用英文说明原因和限制。

修改共享类型时不能只让一个端编译通过；修改日志时不能引入音频、字幕、译文或凭据；修改资源时不能提前释放仍由原生任务使用的模型。

五、验证与兼容性

内部 bridge 和引擎协议不是稳定公共 SDK。新增或调整接口前，明确调用方、返回值、事件顺序、取消与清理路径，以及浏览器旧消息晚到的处理。

按范围运行 TypeScript、Vitest、Python、扩展和构建检查，再做实际音源、设备或浏览器验证。没有目标硬件时说明未验证范围，不把 mock 或页面演示写成兼容性结论。