Cursor 编码开发主指南
1. 目标和交付口径
做一个可长期维护、可独立分发的 MooTool Next FX：使用 OpenJDK + JavaFX，在 macOS、Windows、Linux 上提供与冻结 Electron 1.1.4 尽量一致的布局、样式、功能和操作流程，并改善现代桌面 UI 体验。
用户优先级：日常工作流完整 → 数据与安装互不影响 → 布局/操作一致 → 视觉与键盘体验现代化 → 有证据的性能优化。不能只画出一个相似首页就结束，也不能为了“原生”删除随手记列编辑、JSON 检查器或多窗口。
当前已有独立 Maven 工程和 macOS x64 app-image（P0 待验收：桌面 IME/窗口转移证据未齐）。产品独立意味着允许技术、功能和版本各自演进；冻结对齐基线用于这一轮开发，不构成永久同步义务。
2. 范围
最终范围是 功能规格 的 F00–F25 和 A01–A03：首页、25 工具，11 类设置，导航/搜索/历史/收藏、窗口分离、文件库、Git、托盘、备份、更新与三语言。
必须保持：工具 ID、分组顺序、页面主面板关系、主要按钮顺序和方向、参数/默认值、输入输出语义、离线工具离线可用、有效结果与输入在切页/出错后保留。
可改善：对比度、间距、字体、焦点、命中区域、空/错/忙状态、窄窗口折叠、系统窗口装饰、性能和隐私默认值。将主动变化记为 FX-Dxxx，写清源行为、新行为、原因、影响和验证。不能把源实现漏洞或错误当作必须复制的正确结果。
不默认扩展：移动端、云账户、云同步后端、OCR、在线留言社区、跨产品共享模块、自动替换其他产品。已有服务配置和 Git 属于既定功能，不能用“不做云”删掉它们。
3. 确定的工程方向
- 开发语言 Java，OpenJDK 25 系列；OpenJFX 26.0.2；独立 Maven Wrapper 3.9.16。核验来源及版本调整规则见 基线。P0 固定实际 JDK vendor/patch、依赖和构建插件，禁用动态版本、EA/RC 生产依赖及 Java 预览语法。
- 首版单 Maven 工程、包内分层、程序化 JavaFX + 本地 CSS，不接根
pom.xml，不引入 Spring/大型 DI 框架。 - 主 UI 原生 JavaFX 控件，代码编辑器首选 RichTextFX 0.11.7；专门的 P0 实验决定编辑器最终方案。Markdown 预览允许受控 WebView。
- 自有 SQLite、JSON 配置、Vault 和凭据适配；
jlink+jpackage自带 runtime，普通使用无需系统 JDK。 - 26 入口懒加载；长期 I/O、CPU、数据库和外部进程有独立调度、取消及释放机制。
技术具体约束见 架构。依赖选择是本产品决策，不从其他产品复制整张依赖表。
4. 开发阶段和门槛
阶段是验收门槛，不是预估日程。先完成一个能持续扩展的真实纵向流程，再横向补齐工具。高风险技术在 P0 实验，完整业务在所属阶段交付。
| 阶段 | 实施范围 | 必须交付与通过条件 |
|---|---|---|
| P0 可行性与工程 | Maven/启动/最小打包、身份路径、编辑器、窗口装饰/转移、关键算法样本 | app-image 在无系统 Java 环境启动；中文/列编辑/undo/分离实验；protoc 动态 schema、Crypto 互通、JS/Java regex 差异样本；ADR 与基线证据 |
| P1 应用壳与设计系统 | 26 入口、6 分组、首页、主题、搜索、设置框架、组件目录、导航状态 | F00、A01 中基础设置；1440×920/1080×720 深浅主题；没有重叠/焦点丢失；未实现工具清楚标明开发中 |
| P2 第一条完整工作流 | JSON 核心 + 编辑器公共能力、历史、简单 Vault、会话/独立窗口、数据框架 | 输入→格式化/查询→保存→历史→分离/收回→重启恢复；F04 核心通过，但 JSON/Git 整体仍待 P6 |
| P3 本地文本与数值 | F02/F03/F06/F12/F13/F15/F16/F18/F21/F22 的本地部分 | 对比/格式化/配置/UA/编码/正则/Cron/时间/计算/颜色真实算法；通用收藏；三语言、错误与取消样本；屏幕取色待 P5 |
| P4 二进制与媒体 | F07/F14/F17/F23/F24 | Protobuf、Crypto、QR、图片库/水印/压缩/真 SVG、PDF；保存真实产物、交叉消费和取消；截图待 P5 |
| P5 网络与平台 | F08/F09/F10/F11/F19/F20/F25；截图/取色/托盘/系统主题/防休眠 | 受控集成服务 + 各平台实测；HTTP 集合/翻译单词本；权限失败可解释；系统操作范围明确 |
| P6 复杂工作区 | F01/F05；补齐 F04、Git/附件/编辑器高级能力、全设置与风格 | 随手记24操作/列编辑/附件、四运行环境、Git冲突；六风格和导航模式；多文档/多窗口/保存并发验证 |
| P7 产品发行 | 数据恢复/迁移、全部能力回归、性能、三平台包、更新与共存 | 所有功能要求有结论；目标平台真机/VM 证据；清单产品隔离；安装/升级/卸载互不影响；发布说明与许可清单 |
P0 只证明技术可行，不将实验按钮计入正式功能。P2 之后每一阶段持续使用完整壳和统一设计系统，不能把每个工具写成独立外观的小程序。P7 的范围不得用于拖延 P0 最小打包验证。
5. 第一轮可直接执行的任务
- 记录当前
git status，阅读参考源码与 UI 默认值；冻结 commit、相关工作树差异、样本和截图设置。仅操作本产品。 - 在本目录创建独立
pom.xml、Wrapper、Launcher、MooToolFxApplication、ProductIdentity、AppPaths、基础包和资源。开发版使用.dev身份/目录，避免后续正式版数据污染。 - 建立 26 项静态工具注册表、稳定 ID、懒加载工厂；展示基础主窗口和一个真实 JSON 格式化操作，其余明确未实现。
- 建立 Token、浅/深主题和组件样本页，先检查导航、编辑器、按钮、表格、树、弹窗、焦点与错误样式。
- 创建
EditorHost实验，完成中文输入、emoji/Tab/软换行、矩形编辑和撤销、多 MiB 文件、转移 Stage；失败就记录并测试架构中的备选路线，不带着未知问题铺开 25 个工具。 - 创建一个临时数据目录与 SQLite 往返、一次窗口状态恢复；通过测试注入，不修改真实用户数据。
- 生成本机 app-image 并启动，确认 JavaFX 原生库、编码/数据库驱动、工作进程启动器都被打包。开始其他平台构建探针，未测试的平台仍标待验证。
- 写
docs/adr/001-runtime-build.md、002-editor.md、003-windowing.md、004-algorithm-compatibility.md，更新 验收 的 P0 行和真实证据。
2026-09-09：第一轮 8 项工程任务已落地（见 docs/evidence/2026-09-09-p0/）。P1 壳、P2 JSON Vault、P3 F13 编码解码与 F15 正则已有实现。下一轮不要重建工程；从 P3 下一个本地工具或 1440/1080 截图继续。遇到本机无法提供的外部服务/系统权限，记录阻塞点并继续独立可做部分，不伪造成功。
6. 每个工具的实施模板
先读页面 TSX、算法 TS、服务/契约、对应测试和必要的 Java 算法，生成动作清单：入口、按钮/Tab、输入、选项、默认、输出、异常、快捷键、持久化、平台要求。每个动作关联 Fxx 子项和至少一个有效场景。
实现顺序：纯模型/算法与兼容 fixture → application service → repository/平台适配 → JavaFX ViewModel/View → 快捷键/空错忙状态 → 字体/主题/窗口 → 行为与视觉验收 → 更新矩阵。不要先堆出全部页面再补服务。
每个 PR/开发批次说明具体触发和新行为、源码参照、验证命令及结果、主动差异、已知限制。缺陷修复按失败原因补有价值的测试，不为改一条 CSS 写镜像测试。
7. 完成的定义
“已实现”至少要求真实输入产生真实结果；“已验收”还要求功能细项、平台范围、持久化、错误恢复、键盘/中文输入、视觉和共存测试有证据。未测试不等于通过；Electron 的 complete 也不等于 FX 的 complete。
不允许：引入另一产品作为运行时；用一张网页作为整个 JavaFX 主壳；把截图内嵌成 UI；用 TextArea 冒充完整代码编辑器；把位图嵌入 SVG 冒充矢量化；通过更新覆盖其他产品；以“允许独立演进”为由无记录地删除目标功能。