xly README
简介(Introduction)
这是一个用于测试和演示的VS Code扩展项目，旨在提供一系列开发辅助工具，涵盖代码格式化、项目初始化、版本控制、开发辅助和包管理等功能。
- 开发环境：Windows 10, VS Code
- 技术栈：TypeScript, JavaScript, Rust, Dart, C++, Jest测试框架
- 使用环境：VS Code
- 代码架构：模块化设计，命令按功能分类
Features
PDF 预览
- 在资源管理器中打开
.pdf（含单击预览、双击打开）时，中心编辑器默认显示 PDF 页面，而不是「二进制文件无法显示」提示
- 顶栏居中：
[页码] / 总页数 可编辑跳转；阅读位置后退 / 前进用 Alt + ← / Alt + →（会话内记忆，不持久化）；可选在每页底部显示悬浮「第 N 页」（顶栏「页码」或 xly.pdf.showPageOverlay，默认关闭）
- Ctrl + 滚轮 缩放（与 VS Code 编辑器一致）；Ctrl + 0 恢复适应宽度；状态栏提供 − / 比例 / + / 适应宽度
- 查找：
Ctrl+F（macOS 为 Cmd+F）打开与 VS Code 类似的查找栏，显示 当前 / 总数，可用 Enter / F3 跳转匹配处并黄色高亮；支持大小写 / 全字 / 正则
- PDF 内链 / 目录：点击页内链接或目录条目可跳转到对应位置
- 懒加载页：未渲染页显示加载 spinner；加载失败可点「重试」；指示器颜色跟随主题
- 页面背景主题：顶栏下拉或设置项
xly.pdf.pageTheme（跟随主题 / 纯白 / 护眼绿 / 羊皮纸），自动记住
- 顶栏左侧：选择（PDF.js 文本层，可选中 + Ctrl+C 复制）/ 手型（拖动平移）；
xly.pdf.toolMode 全局记住
- 文字标注与批注：选中文字后弹出悬浮工具条，可加 高亮 / 下划线 / 删除线（含固定调色板），并可直接 添加批注；悬停或点击已有标注打开气泡，支持回复、编辑、审阅状态与删除；有批注内容的划线末尾显示角标。顶栏批注拆分按钮：点气泡 展开 / 收起全部批注，点右侧小三角可 清除全部标注（命令面板仍可用
清除 PDF 全部标注）。改文件内容的操作支持 Ctrl+Z / Ctrl+Y（macOS 为 Cmd+Z / Cmd+Shift+Z）撤销重做，保存后仍可撤销；批注输入框内快捷键先撤文字。一次划选产生的多条高亮为单步；钉住单条气泡不进撤销栈
- 右键标注可复制批注 / 划线文字、回复、添加笔记、设置状态、展开隐藏、查看属性
- 标注以标准 PDF 对象（
Highlight / Underline / StrikeOut，回复与状态为 /Text + /IRT）写入文件，Ctrl+S 保存
- 跨工具互通：可显示并编辑 WPS / Acrobat 等写入的批注线程；作者名见设置
xly.pdf.annotationAuthor（空则回退 git / 系统用户名）
- 预览内已屏蔽 Ctrl+A 全选（页码输入框除外）
- 若已安装其他 PDF 扩展，可在标签页右键 Reopen Editor With 切换编辑器
Markdown Live Preview
- 打开单个
.md 默认进入 XLY Markdown Live Preview（Obsidian / Typora 式：非焦点块渲染样式，光标块显示 ###、| 等源码）；比较所选文件 / Git / 合并冲突始终是原生文本 diff
- 格式化工具栏：顶部工具条提供标题（H1–H3 / 正文）、加粗、斜体、删除线、行内代码、链接、引用、代码块、分隔线、有序 / 无序 / 任务列表、表格、撤销 / 重做（
xly.markdown.toolbar.enabled，默认开启）
- 编辑器标题栏「…」菜单第一层有一项「渲染 / 源码」切换，标签随当前视图变化：源码 tab 里是「[XLY] 切换到渲染模式」（回到 IR，同
xly.markdown.openLive），IR 里是「[XLY] 切换到源码模式」（切回 Monaco 纯文本，同 xly.markdown.openSource）；两项按编辑组自己的上下文键互斥，任何时候只出现一项，diff 里不出现。不再往标题栏放图标；旧版自动写进 Cursor cursor.general.pinnedTitleActions 的 XLY 条目会在首次启动时清掉（只删 XLY 的，其它保留，删空则移除该设置）
- 查找 / 替换：
Ctrl+F / Ctrl+H，对齐 VS Code find widget（大小写 / 全字 / 正则 / 计数 / 在选区中 / 保留大小写替换）；滚动条显示查找结果标记；命中在表格单元格里也会黄底高亮并滚到该格
- 新建临时文件：Live Preview 获得焦点时，
Ctrl+N（macOS 为 Cmd+N）可像原生编辑器一样新建 Untitled 文本标签
- 表格：非焦点表格块渲染为可视化表格（
xly.markdown.table.enabled，默认开启）；单元格内 Markdown 链接可点击
- Mermaid：非焦点
```mermaid 块渲染为 SVG 图表（xly.markdown.mermaid.enabled，默认开启）；可在侧栏 Mermaid 预览 面板缩放 / 平移
- 数学公式：
$...$ / $$...$$ 以 KaTeX 渲染
- 代码高亮：代码块用 Shiki 渲染并跟随 VS Code / Cursor 主题配色
- 链接跳转：点击渲染态链接，外部 URL 走系统浏览器，相对路径在工作区内打开；
#锚点 在本文档内滚动（含表格单元格与 HTML id）
- HTML 标题：单独成行的
<h1>–<h6> 预览为标题（隐藏标签）；光标进入该行仍可编辑源码
- 编辑实时写回同一
.md 文件，dirty / autoSave / Ctrl+S 与 Monaco 一致；外部（AI / 格式化 / Git）改动按最小差异增量同步，不跳顶、不丢光标，并保持文件原有行尾（CRLF / LF）
xly.markdown.openByDefault（默认 true）控制打开单个 .md 时是否自动升级为 Live Preview；比较所选文件、Git diff、合并冲突始终使用 VS Code 文本编辑器- 若仍安装
zaaack.markdown-editor，建议卸载或关闭其 *.md 关联，避免与 xly 冲突
- 首次克隆后需
npm run compile（含 Vite 构建 media/markdown/dist/）
代码格式化与修复
- JS/TS系列：自动修复代码风格问题（如缺少花括号）并格式化代码 (
Refine(Format) Js,Jsx,Ts,Tsx,Json,Css,Scss Files By Npm Command) - 需先安装npm install --save-dev eslint prettier
- Rust系列：自动修复和格式化 Rust 代码，支持递归查找项目 (
Refine(Fix/Format) Rust Code) - 对当前项目先后执行rust的clippy和format命令
- Dart系列：自动修复和格式化 Dart 代码，支持递归查找项目 (
Refine(Fix/Format) Dart Code) - 对当前项目先后执行Dart的fix --apply和format命令
- Python系列：自动修复import排序并格式化 Python 代码 (
Refine(Fix/Format) Python Code) - 对整个工作区执行ruff的import排序修复和代码格式化
项目初始化与配置
- C++/Qt项目：
- 创建基于 CMake 的终端/GUI项目，支持32/64位 (
Init C++/Qt Project)
- 添加类文件 (
Add A Cpp Class) - 创建一个C++类
- 添加配置文件：
- 调试和智能感知配置 (
Add C++/Qt Debug, Intellisense Files For Current Project) - 给当前C++项目配置专属debug和intellisense文件
- 完整配置 (
Add C++/Qt Debug, Intellisense And CMakeList Files For Current Project) - 给当前项目添加debug、intellisense和CMakeList文件
- CMakeList配置 (
Add CMakeList For Current Project) - 给当前项目配置CMakeList文件
- 支持一键调试(F5)和构建(Ctrl+Shift+B)
- Python项目：快速创建 Python 脚本项目 (
Init Python Project) - 创建一个python hello world项目
- Rust项目：
- 生成可执行文件或库项目及调试配置 (
Init RUST Project)
- 添加配置文件 (
Add Rust Config File For Current Project) - 给当前Rust项目配置专属debug和intellisense文件
- 工具链管理：
- 更新Stable工具链 (
Update Rust Stable ToolChain) - 使用rustup update stable更新Rust stable工具链
- 添加Nightly工具链 (
Add Nightly Toolchain For Current Project) - 给当前项目添加nightly工具链
- 添加Android工具链 (
Add Android Toolchain For Current Project) - 给当前项目添加安卓工具链
- 设置默认工具链 (
Set Default Toolchain (Stable Or Nightly)) - 设置默认的工具链（稳定、夜间）
- 测试与依赖管理：
- 运行测试 (
Run Cargo Test For Rust Code) - 对当前项目先后执行cargo test
- 刷新依赖 (
Fresh/Update The Rust Project's Cargo Modules) - 刷新当前项目的cargo模块
- 发布管理 (
Publish The Rust Crate To Crates.io) - 发布当前crate到crates.io
- Flutter项目：
- 改善Flutter项目配置 (
Refine Flutter Project Pubspec.yaml) - 自动更新pubspec.yaml文件的SDK版本和常用依赖项
- 打开Flutter Debug文件夹 (
Open Flutter Debug Folder) - 快速打开任何Dart/Flutter项目的Windows平台Debug构建目录，自动检测项目类型并提供个性化反馈
- Flutter Rust Bridge项目：
- 创建Flutter UI + Rust API的跨平台项目 (
Init Flutter Rust Bridge Project) - create 之后幂等补 Windows/Linux CMake 的 native_assets OPTIONAL，清 build/ 后不会再 MSB3073
- 完善FRB项目自动初始化流程并引入单元测试以保障初始化稳定性。
- 为已存在的FRB项目添加配置文件 (
Add Config Files To Existing FRB Project) - 覆盖 justfile 与 CI（clean 按锁拉回，本机 just check），并补同一条 CMake
- FRB项目版本管理 (
Update FRB Project Version) - 同步更新Flutter和Rust配置文件中的版本号
- FRB版本更新 (
Update Flutter Rust Bridge Version) - 同步 Dart / Cargo = / 本机 codegen 到同一版本
- 重置初始化状态 (
Reset FRB Project Initialization State) - 重置FRB项目的初始化状态，允许重新初始化
Git 版本控制
- 仓库初始化与远程配置：
- 初始化未记录的本地项目 (
Init Unrecorded Local Project) - 自动初始化本地Git仓库、创建GitHub远程仓库并推送，支持私有/公开选择
- 关联远程仓库 (
Link/Init Local Project With Git Repository) - 将本地项目强推到指定的远程仓库
- 分支管理：
- 创建并重置分支 (
Add/Create A New Branch And Reset To A Certain Commit) - 创建新分支并重置到指定提交
- 批量删除分支 (
Delete/Remove Branches) - 支持删除多个本地和远程分支
- 提交管理：
- 撤销最近提交 (
Reset/Revert Last Commit) - 重置上一次提交
- 强制更新到远程最新版本 (
Force Update Local To Remote Latest) - 会丢失本地更改
- 同步操作：
- 上游同步 (
Fetch And Reset To Remote Branch) - 获取并将上游代码重置到本地指定分支
- 版本控制信息：
- 清理版本控制信息 (
Delete/Remove Local Project Git Repository Info) - 完全删除当前项目的.git版本控制信息
开发辅助工具
- 文档助手：
- 清理非法字符 (
Replace Invalid Char With Space) - 将非法字符串用指定字符代替
- 生成文件夹树状结构 (
Generate Folder Tree Structure) - 右键文件夹菜单
- 生成项目大纲 (
Generate Project Outline Markdown) - 生成项目树状结构并保存到project_outline.md文件
- Flutter/Dart工具：
- 包管理：
- 修复pub缓存 (
Repair Flutter Pub Cache) - 使用flutter pub cache repair修复缓存问题
- 包版本更新 (
Update All Flutter Package To Main Versions) - 将所有flutter的包升级到主要版本
- Flutter版本更新 (
Update Flutter To Latest Version) - 使用flutter upgrade更新Flutter到最新版本
- 应用图标生成 (
Generate Dart/Flutter App Icons) - 为Dart/Flutter应用生成各平台图标（使用xly包的简化图标生成功能，支持文件选择器，自动检测主项目和example项目）
- 应用重命名 (
Rename Dart/Flutter App Name) - 重命名Dart/Flutter应用名称
- VSCode调试配置 (
Add VSCode Config For Existing Dart/Flutter Project) - 为已存在的Dart/Flutter/FRB项目添加VSCode调试配置文件
- Windows静默启动 (
Setup Windows Silent Startup) - 修补flutter_window.cpp以支持静默启动（仅Windows，一次性操作，基于xly包的win_setup命令）
- 修复构建 (
Fix Flutter/FRB Build) - 一键修复Flutter/FRB项目构建失败：先幂等补桌面 CMake 的 native_assets OPTIONAL，再深度清理缓存并重建（杀残留进程 + flutter clean + pub get；FRB项目额外清理rust/target/与生成文件、重置Cargo registry源码缓存并重新codegen）
- AI辅助工具：
- 诊断信息收集 (
Copy All Diagnostic Messages In Project) - 复制项目中所有诊断信息（错误/警告/信息/提示）到剪贴板，支持文件类型筛选功能，便于AI分析修复
- 终端内容收集 (
Copy All Content From a Terminal) - 复制某个终端中的所有信息到剪贴板，便于AI分析修复
- VSCode工具：
- 缓存清理 (
Clear VSCode Service Worker Cache) - 清除VSCode Service Worker缓存以解决WebView预览问题
- 新标签页打开 (
Open In New Tab) - 在新标签页中打开文件
- 浮动窗口 (
Show Floating Window) - 显示浮动窗口
包管理与发布
- Rust：
- 发布 crate (
Publish The Rust Crate To Crates.io) - 发布当前crate到crates.io
- 刷新依赖 (
Fresh/Update The Rust Project's Cargo Modules) - 刷新当前项目的cargo模块
- Dart/Flutter：
- 发布包 (
Publish Dart Package) - 发布Dart包到pub.dev
- 更新依赖 (
Update All Flutter Package To Main Versions) - 将所有flutter的包升级到主要版本
- 前端：
- 发布VSCode扩展 (
Publish VSCode Extension) - 打包后并行发布到 VS Code Marketplace 和 Open VSX Registry（Cursor 等编辑器使用），并立刻用刚打的 .vsix 装本机已检测到的编辑器。某一市场失败或该版本已存在，不会拦住另一市场或本机安装
TODO
笔记(Note)
- Jest测试框架：
- Jest已集成到本项目中，用于单元测试。
- 配置文件位于：
jest.config.js
- 测试文件通常位于
src/test/ 目录下，例如：src/test/flutter_rust_bridge.test.ts。
- 运行所有测试：在终端执行
npm test 或 npx jest。
copilot参考
Notes
Requirements
C++程序需要先安装微软的C++、cmake的vscode拓展。
| |
