epytor AGENTS.md

项目指令 — epytor

语言

• 始终用简体中文回复

---

需求

• 新功能设计文档放在 docs/specs/，文件名 YYYY-MM-DD-<功能名>.md
• 先写 spec 再开发——明确需求范围、交互边界、验收标准
• 配置项参考见开发 → 配置参考

---

开发

基本规则

• 包管理器：必须用 pnpm，禁止 npm/yarn
• 构建：修改代码后执行 pnpm build 验证编译无误
• 调试：F5 启动扩展调试实例（.vscode/launch.json）
• 语言：全部 TypeScript；Extension 端用 tsconfig.json，WebView 端用 tsconfig.webview.json
• 双目标构建：dist/extension.js（Node.js）+ dist/webview.js（Browser），由 esbuild.mjs 完成
• Git commit 规范：commit 描述用中文，类型前缀保留英文（feat:、fix:、refactor:、chore:、docs: 等）。例：feat: 新增XXXX功能、fix: 修复XXXX问题
• 逐项提交：todo list 中每完成一个独立任务必须单独 git commit，禁止多个 todo 混在一个 commit 中（方便出问题时精确回溯）
• 诚实原则：不确定的事直接说"不确定"，禁止编造 URL、issue 编号、API 接口、文档引用或任何事实性信息
• 优雅原则：禁止 hack 或补丁式写法，优先使用框架/库官方 API、CSS 变量、配置回调等正路方案
• 自检原则：代码移动/提取后必须搜索确认旧位置已删除，不得留有死代码或同名遮蔽；标记 roadmap 条目完成前逐项列出实际完成项与未完成项，不得将部分完成标记为整体完成
• 查证原则：引用文件位置、函数名、调用关系时，若不确定则先 grep 确认再写，禁止凭记忆编造

架构约束

• WebView ↔ Extension 通信只通过 webview/messaging.ts 中封装的函数
• WebView 侧不直接 import VSCode API，通过 acquireVsCodeApi() 获取句柄
• CSS 必须使用 --vscode-* 变量以适配亮/暗主题
• 不在模块外部维护全局状态（单例除外，如 editor view）

关键文件速查

src/extension.ts                         — 扩展入口，注册 CustomEditorProvider
src/MarkdownEditorProvider.ts            — Provider 核心（消息路由、自动保存、revert）
src/utils/getNonce.ts                    — CSP nonce 生成
src/utils/imageService.ts               — 图片本地保存（MD5 去重）+ 服务器上传
src/i18n/webviewTranslations.ts         — WebView 翻译数据
webview/index.ts                         — WebView 入口（消息路由、DOM 事件委托、品牌标识注入）
webview/editor.ts                        — CrepeBuilder 入口（Milkdown 7.21.2 + Crepe 原生功能注册）
webview/messaging.ts                     — WebView ↔ Extension 消息协议（唯一通信层）
webview/style.css                        — VSCode 主题全覆盖（--vscode-* CSS 变量，覆盖 Crepe 组件）
webview/i18n/index.ts                    — t() / kbd() 翻译函数
webview/ui/icons.ts                      — SVG 图标
webview/ui/tooltip.ts                    — Tooltip 组件
webview/utils/themeBus.ts               — Mermaid/CodeMirror 深浅主题统一事件总线
webview/components/selectionToolbar/index.ts — 选区变更回调（驱动源码行号映射）
webview/components/toc/index.ts         — 目录（TOC）面板（吸底工具栏下方、可固定、可拖拽宽度）
webview/components/imageView/index.ts   — 图片 NodeView（选中/lightbox/工具栏/缩放 handle）
webview/components/findBar/index.ts     — 编辑器内查找栏（Cmd/Ctrl+F）
webview/components/pathLink/            — 路径链接自动补全
webview/headingIds.ts                    — 标题 id 管理（不操作 DOM，仅保留签名）
docs/specs/                              — 功能 spec 文档
docs/roadmap.md                          — 项目路线图（面向用户的功能规划）
docs/tech-debt.md                        — 技术债务清单（面向开发者的代码改进）