8.7 KiB
Project Constitution — VibeCoding English
项目宪章 · 不可轻易修改 · 所有决策的最高准则 版本：v1.0 | 生效日期：2026-05-26
一、项目身份
| 项 | 值 |
|---|---|
| 项目名称 | VibeCoding English |
| 一句话定位 | 让中国程序员在 Vibe Coding 中无感学英语 |
| 目标用户 | 使用 AI 编程工具（Claude Code / OpenCode / Cursor 等）的中国程序员 |
| 核心场景 | 编码过程中遇到生词 → 选中即翻译 → 自动积累 → 间隔复习 |
二、不可妥协的原则
原则 1：Offline First（离线优先）
基础翻译功能必须在完全无网络的环境下可用。 LLM 等在线功能是锦上添花，而非生存必需。
判断标准：断网后，选中一个常用英文单词按快捷键，翻译正常显示。
原则 2：Zero Friction（零摩擦）
用户从"看到生词"到"获得翻译"的操作步骤 ≤ 2 步。 理想路径：选中 → 快捷键（1步）。 可接受路径：选中 → 右键 → 点击（2步）。
判断标准：从看到生词到看到翻译 ≤ 3 秒。
原则 3：Data Sovereignty（数据主权）
用户的单词本数据完全本地存储，永不上传任何服务器。 用户可随时导出全部数据，可随时删除全部数据。
判断标准：抓包工具检测，插件不向任何外部服务器发送单词本数据。
原则 4：Context Matters（语境为王）
翻译不能脱离上下文。同一个词在不同语境下给出不同释义。 技术术语给出技术含义，普通用语给出通用含义。
判断标准：同一个词（如 resolve）在代码上下文和普通文本上下文中，给出不同释义。
原则 5：Progressive Enhancement（渐进增强）
功能分层：基础功能 100% 可用 → 网络功能尽力可用 → AI 功能可选可用。 每个增强层失败时，优雅降级到下一层。
判断标准：LLM API 挂了，离线词典仍然能正常工作。
三、技术原则
原则 6：Core Once, Adapter Everywhere
核心业务逻辑编写一次（
@vibecoding-english/core），各平台仅编写适配层。 Core Library 不依赖任何平台特定 API。
原则 7：Test Before Code（测试驱动）
任何新功能的开发顺序：写测试 → 测试失败 → 写实现 → 测试通过 → 重构。 核心模块单元测试覆盖率 ≥ 80%。
原则 8：Fail Gracefully（优雅失败）
任何错误不能导致插件崩溃或 VS Code 无响应。 每个 try-catch 必须有降级策略。
原则 9：Type Safety（类型安全）
整个项目使用 TypeScript strict 模式。 禁止
any（除非有充分理由并注释说明）。
原则 10：Small Modules（小模块）
每个文件 ≤ 300 行，每个函数 ≤ 50 行，每个类 ≤ 10 个公共方法。 超过则拆分为子模块。
四、设计原则
原则 11：Native Feel（原生感）
UI 遵循 VS Code 设计语言，使用 VS Code 主题变量。 不引入自定义 UI 框架的视觉风格。
原则 12：Keyboard First（键盘优先）
所有核心功能有快捷键，鼠标操作是辅助。 快捷键设计避免与 VS Code 内置快捷键冲突。
原则 13：Minimal Configuration（最小配置）
开箱即用，零配置可完成核心翻译流程。 高级功能（LLM 翻译）需要配置 API Key。
五、协作原则
原则 14：AI-First Development（AI 优先开发）
本项目本身就是 Vibe Coding 的产物 —— 使用 AI 工具辅助开发本工具。 每个阶段的开发任务优先使用 AI Agent 完成，人工负责审核和决策。
原则 15：Documentation Lives with Code（文档即代码）
所有文档与代码放在同一仓库。 架构变更必须同步更新文档。 CHANGELOG 按 Keep a Changelog 规范维护。
原则 16：Continuous Knowledge（持续知识积累）
每次解决问题后，将经验写入
knowledge/目录。 每个 AI 对话中的重要发现写入MEMORY.md。 Skills 随项目成长而积累。
原则 17：Comment for Understanding（注释即理解）
本项目核心开发者具有 Java 背景，对 TypeScript/VS Code 插件生态需要学习。 代码注释不仅是文档，更是知识传递的桥梁。
注释强度要求：
| 注释类型 | 要求 | 示例 |
|---|---|---|
| 文件头注释 | 每个文件顶部说明模块用途、对应 Java 中的类似概念 | // 翻译调度器 —— 类似 Java 的 Chain of Responsibility 模式 |
| 公共 API (JSDoc) | 所有 export 的函数/类/接口必须有完整 JSDoc | @param, @returns, @throws, @example |
| 接口注释 | 说明接口的角色，对比 Java 中的 interface/abstract class | // ITranslateEngine —— 类似 Java 的 Function<T, R> 接口 |
| 复杂逻辑 | 超过 5 行的逻辑块需要"先注释思路，再写代码" | 先写 // 步骤1: ... 步骤2: ... 再写实现 |
| TypeScript 特性 | 使用 TS 独有特性时必须注释解释（对 Java 开发者） | // Pick<T, K> 类似 Java 中手动提取字段创建新 DTO |
| VS Code API | 使用 VS Code API 时注释其作用和生命周期 | // vscode.window.createOutputChannel —— 类似 Java 的 Logger |
| 魔鬼数字/正则 | 任何魔法值必须注释来源和含义 | // BNC 词频 ≥ 10000 视为高频词（经验阈值） |
注释语言：
- JSDoc / 公共 API 注释：英文（国际化规范）
- 模块级架构说明、复杂逻辑解释：中文（帮助 Java 开发者理解）
- TypeScript 对比 Java 的类比注释：中文
原则 18：Honest Fallback（诚实兜底）
Fallback（兜底/降级）的本质是"Plan B"，不是"假装 Plan A 成功"。 当主方案不可用时，兜底方案必须满足以下标准，否则宁可留空。
Fallback 合法性三条件（必须同时满足）：
| 条件 | 含义 | 反例 |
|---|---|---|
| 1. 可验证 | 兜底结果的正确性可被独立验证 | 硬编码 50 个词的音标，无法覆盖新词 |
| 2. 准确性 ≥ 95% | 兜底结果在实际使用中的准确率足够高 | 用规则猜测音标，准确率低 |
| 3. 透明标注 | 用户明确知道这是兜底结果，非主方案产出 | 悄悄用本地词表替换 LLM 音标 |
不满足条件时的处理优先级：
1. 联网检索最佳实践 → 汇报结果，让用户决策
2. 在结果中明确标注"[缺少兜底策略]" → 用户自行判断
3. 留空 / 不显示 → 诚实比错误好
Fallback 偏离检查：
如果 Fallback 结果与原有 Prompt/需求有偏差可能（如缺少字段、准确度下降）， 必须在输出中强制标注
⚠️[Fallback]标识，说明：
- 原始方案是什么
- 为什么走了 Fallback
- Fallback 的局限是什么
判断标准：用户看到结果时，能一眼区分"这是正常结果"还是"这是降级结果"。
六、禁止事项
| # | 禁止 | 原因 |
|---|---|---|
| 1 | 将用户单词本数据发送到任何服务器 | 原则 3：数据主权 |
| 2 | 在未经用户确认的情况下自动发送代码到外部 API | 安全 + 隐私 |
| 3 | 使用 eval() 或类似动态执行代码的方式 | 安全 |
| 4 | 硬编码 API Key 或密钥 | 安全 |
| 5 | 在主线程执行超过 50ms 的同步操作 | 原则 2：零摩擦 |
| 6 | 吞掉异常不处理（空的 catch 块） | 原则 8：优雅失败 |
| 7 | 跳过测试直接合并到 main | 原则 7：测试驱动 |
| 8 | 修改本宪章的原则而不经过讨论和版本更新 | 原则稳定性 |
| 9 | Phase 完成后不更新迭代记录和 memory.md | 原则 16：持续知识积累 |
| 10 | 使用不可验证/不准确的 Fallback（硬编码猜测、规则推断） | 原则 18：诚实兜底 |
七、决策框架
当面临技术/产品决策时，按以下优先级判定：
1. 是否违反宪章不可妥协原则？
→ 是：否决
→ 否：继续
2. 是否有利于"零摩擦"用户体验？
→ 打分 1-5
3. 实现成本和维护成本是否可接受？
→ 打分 1-5
4. 综合评分 = 体验分 × 2 + 成本分
→ ≥ 10 分：执行
→ 7-9 分：讨论
→ < 7 分：否决
八、版本历史
| 版本 | 日期 | 变更 |
|---|---|---|
| v1.0 | 2026-05-26 | 初始版本，定义 16 条原则 |
| v1.1 | 2026-05-26 | 新增原则 17：Comment for Understanding，注释规范 |
| v1.2 | 2026-05-27 | 新增原则 18：Honest Fallback，Fallback 合法性三条件 + 禁止事项 #10 |
本宪章是项目的"宪法"。所有代码、文档、决策都必须符合以上原则。 修改宪章需要：创建 PR → 团队讨论 → 至少 2 人同意 → 更新版本号。