Epoint Rules - AI 代码生成规范系统 (v3.0.4)

[!IMPORTANT] 最新版本 v3.0.4 (常用资料全套功能 & 笔记极简交互体验升级)：

• 📂 新增“常用资料”全套功能：在侧边栏引入独立资料页签，支持从 my_data.json 动态加载分类资料，支持快捷修改。
• � “日常笔记”极致交互修复：抛弃繁弱易丢失的图标，全面采用表情符号文本按钮（📄 复制 / ✏️ 修改 / 🗑️ 删除），UI大方且自适应各类长文本。
• �️ 后端安全拦截验证：所有笔记内含的 HTML、单双引号及多行 SQL 在传递至 Webview 前经过极致全量安全转义及拦截校验，彻底解决点击事件由于代码截断引发操作失效的恶性问题。
• � 原生通知代替阻塞：由于 Webview 拒绝原生弹窗拦截，所有的删除、执行确认提醒已移防至 VS Code Native Window 警告框，安全且自然。

📦 一、快速开始

1.1 环境要求与安装

[!NOTE] MCP 服务器运行在独立线程中，必须先进入 mcp_tools 目录安装依赖。

1.2 配置 MCP (AI 客户端集成)

[!IMPORTANT] v3.0.1 重大改进：一次配置，永久有效。 插件现在会自动在您的用户目录下创建一个固定的启动脚本：~/.epoint-rules/start-mcp.js。 请务必切换到此路径，从此插件升级将不再需要重新配置 MCP 路径。

1. 启动插件：在 VS Code 中安装并激活本插件。
2. 获取配置：点击侧边栏 "政务BG规范助手" -> "⚙️ 管理配置" 标签页 -> "复制配置信息"（该配置已包含稳定路径）。
3. 应用配置：将配置粘贴到 AI 助手（如 Cursor / Trae）。

🤖 二、专家流水线 (The Expert Pipeline)

系统核心是一个由 Workflow Engine 状态机管理的 6 位虚拟专家 组成的工业化流水线。

2.1 工业化开发流程图

graph LR
    %% --- 样式定义 ---
    classDef flow fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000;
    classDef skill fill:#fff9c4,stroke:#fbc02d,stroke-dasharray:5,color:#000,font-weight:normal;
    classDef gate fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px,color:#000;
    classDef startend fill:#f5f5f5,stroke:#616161,color:#000;
    classDef code fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000;

    %% --- 主流程 ---
    INPUT["用户需求 / OA链接"]:::startend --> START
    START["pipeline_start<br/>生成大纲"]:::flow --> REQ
    
    REQ["pipeline_1_requirement<br/>需求澄清 (BA)"]:::flow --> GATE1{"用户确认"}:::gate
    GATE1 --> SCAN
    
    SCAN["pipeline_2_scan<br/>项目勘测 (Scanner)"]:::flow --> GATE2{"用户确认"}:::gate
    GATE2 --> DESIGN
    
    DESIGN["pipeline_3_design<br/>架构设计 (Architect)"]:::flow --> GATE3{"用户确认"}:::gate
    GATE3 --> CODE
    
    CODE["pipeline_4_code<br/>代码落地 (Coder)"]:::code --> GATE4{"用户确认"}:::gate
    GATE4 --> SEDIMENT
    
    SEDIMENT["pipeline_5_sediment<br/>复利沉淀 (Reviewer)"]:::flow --> FINISH["交付上线"]:::startend

    %% --- 专家引用规则库 ---
    SKILL0("<b>需求分析指南</b><br/>关键字意图规则.mdc"):::skill -.-> REQ
    SKILL1("<b>项目结构规范</b><br/>包结构识别"):::skill -.-> SCAN
    SKILL2("<b>设计模板.mdc</b><br/>标准化设计约束"):::skill -.-> DESIGN
    SKILL4("<b>代码规范+QA规则</b><br/>边写边审约束"):::skill -.-> CODE
    SKILL5("<b>create_rule工具</b><br/>功能总结沉淀"):::skill -.-> SEDIMENT

2.2 新旧架构对比：为什么需要引入硬隔离（Hard Boundary）？

在 v3.0 初期，尽管我们使用了 Prompt 约束 AI 按步骤执行，但聪明的模型往往会“脑补”并强行一口气写完全部代码。因此，最新的 v3 版本彻底切碎了总路由，演进为 7 独立工具的硬物理隔离架构。

2.3 独立专家工具详解 (7 Tools)

为了实现物理隔离，原本单一的专家系统被划分为 2个系统控制工具 和 5个领域专家工具，AI 必须严格按序调用才能拿到模板并推进：

[!CAUTION] 绝对硬约束：任意专家工具（如 pipeline_3_design）被调用时，会立即检查 plan.md 上的前序步骤。如果此时未得到用户确认（非 done），MCP 服务器将直接向 AI 抛出异常并拒绝执行，从而彻底根治大模型的“多动症”。

2.4 OA 需求自动解析子流程 (v3.2)

当输入为 OA 链接时，系统通过 parse_oa_demand 工具实现一键直达。此时程序会自动加载 现有产品（如 AuditProject7.11）及框架基础规则库 启动动态推理。

sequenceDiagram
    autonumber
    participant U as 用户
    participant AI as AI 助手
    participant MCP as 插件服务
    participant PY as 文档解析器
    participant EP as 专家流水线

    U->>AI: 粘贴 OA 需求链接
    AI->>MCP: 发送解析命令
    activate MCP
    MCP->>PY: 启动解析脚本
    activate PY
    PY->>PY: 提取Word文档 + 抠出嵌入的附件
    PY-->>MCP: 返回解析后的需求上下文
    deactivate PY
    MCP->>EP: 带数据启动流水线
    activate EP
    
    rect rgb(230, 245, 230)
        Note right of EP: 🧠 启动动态推理引擎 (基于现有产品、框架规则库)
        EP->>EP: Step 1. 意图推理 (Infer Keywords)
        EP->>EP: Step 2. 规则检索 (Rule Expert)
        EP->>EP: Step 3. 双层盘点 (Check Coverage)
        EP->>EP: Step 4. 输出决策 (规格书/反问)
    end
    
    EP-->>MCP: 返回推理结果 (Prompt)
    deactivate EP
    MCP-->>AI: 透传 Prompt 并等待决策
    deactivate MCP
    
    alt AI 判定信息完备
        AI-->>U: 展示《SRS说明书》，请确认
    else AI 判定存在缺口
        AI-->>U: 柏拉图式反问，引导补充缺口
    end

2.6 复利价值与性能平衡 (Value & Performance)

🚀 规则驱动的复利效应 (Rule-Driven RAG)

随着规范库的不断完善，系统展现出显著的知识复用收益：

• 专家经验平权：新员工只需粘贴 OA 链接，即可获得与资深架构师一致的规范约束。
• 一致性治理：规范库越丰富，AI 编写的代码越具有“工厂标准”，彻底消除“一人一写法”的乱象。
• 自进化能力：Stage 5 会不断将新发现的坑点转化为规则，实现“一次踩坑，全员免疫”。

🧠 上下文压缩策略：为什么不会“爆显存”？

用户往往担心随着规范和需求内容的增加，AI 的上下文（Context Window）会不堪重负。本系统采用了 “按需加载 (JIT Context)” 策略：

• 高性能索引：就算你有几千条规范，热启动检索也只要 2ms。我们用了二级缓存和内存快照，完全不卡顿。

收益公式：规则越多，AI 越聪明，但反应速度依然是毫秒级。

✨ 三、核心功能

3.1 侧边栏助手 (Sidebar Helper)

• 📚 规范列表: 分组展示所有 .mdc/.md 文件，支持一键复制提示词。

• 🛠️ 快捷操作: 内置多种模板快速创建自定义规范。

• 管理配置: 可视化引导配置及 Git 稀疏检出同步。

3.2 MCP 工具集 (AI 可调用)

3.3 🎨 知识可视化大师 (Visualization Masters)

内置顶级架构师指令，将复杂逻辑一键转化为图表。

3.4 OA 需求自动化全景 (MindMap)

💡 [OA 需求解析一键直达]
│
├── 🎯 缘起与目的 (Why)
│   ├── ⚡ 提效：消除手动复制内容到对话框的繁杂步骤
│   ├── 📊 准确：全量提取 60+ 字段关系，规避漏读风险
│   └── 🧪 穿透：识别 Word 中嵌入的 Excel 对象（OLE 逆向提取）
│
├── ⚙️ 核心机制 (How)
│   ├── 🔗 MCP 工具：parse_oa_demand 直接调度
│   ├── 🐍 Python：利用 olefile + openpyxl 进行二进制剥离
│   └── 🏗️ 流水线注入：通过 [OA_PARSED] 标记接管 Stage 0 BA
│
└── 🚀 应用与实践 (Application)
    ├── 📥 输入：只需一个 URL
    ├── 🧠 推理：基于现有产品、框架规则库进行 1:1 循证映射
    ├── 🗂 归档：自动按“需求名称”创建项目文件夹
    └── 📑 产出：直接输出包含字段掩码脱敏规则的规格书

3.5 ⌨️ VS Code 命令

3.5 ⚙️ 个性化配置 (Settings)

🛡️ 四、核心规则与门禁

4.1 全阶段确认门禁 (Human-in-the-Loop)

系统内置硬性状态门禁。每个阶段产出物后，AI 严禁抢跑，必须等待用户输入 "确认" 指令方可进入下一环。

4.2 国产化适配专项工作流 (Localization Expert)

国产化适配是绕过普通 BA 流水线的专项独立流程。为了保证适配安全性与正确率，系统将接管所有处理逻辑：

graph LR
    Req(在对话框输入: 国产化适配) --> MCP[触发国产化专项向导]
    MCP --> Scan[执行全仓库扫描排查]
    Scan --> Checklist[生成/更新本地`.md`适配清单]
    Checklist --> Guide{AI 指引用户}
    Guide -->|单步模式| FixOne[每次提供一个文件的代码修改]
    Guide -->|连跑模式| AutoFix[AI 自动遍历清单修正剩余所有文件]
    FixOne --> Sync[强制修改 Checklist 打勾进度]
    Sync --> Verify[最终调用验证器复检]

• 🧠 工作流内置 (Built-in Logic)：无需挂载晦涩的规范文档。引擎直接解析关联数据库配置词典并引导 AI 修改，避免了大模型读飞或幻觉。
• ⚖️ 原逻辑物理保全：严禁修改原 SQL，所有适配必须通过环境判断（如 if (baseDao.isPostgresql())）以分支隔离实现，将原代码作为 else 分支留作 100% 不变的回退保险。
• ✅ 强制双向打卡：基于工作区内的状态推进。每次改完代码必须同步给清单打勾，否则无法进入下一步。
• 🤖 支持自动连跑：支持“单步确认（安全）”和“自动连跑（高效）”两种模式，多文件自动轮询适配。

📚 五、规范文件体系 (MDC)

文件名必须遵循 [业务领域/类名]-[场景描述].md 或 .mdc 范式。支持 globs 自动扫描：

globs: ["**/*Controller.java", "**/*.html"]

AI 识别到该规范时会自动定位并报告匹配的文件。

📝 更新日志

• v3.0.4 (2026-03-11):

  • � 新增“常用资料”全套功能：在侧边栏引入独立资料页签，支持从 my_data.json 动态加载分类资料。
  • � 一键复制与搜索：提供资料内容的快捷复制功能，并集成带高亮展开的全文搜索过滤。
  • ⚙️ 资料快捷编辑：支持直接通过界面跳转编辑 JSON 配置文件，实现零门槛资料同步。
  • 🚀 “日常笔记”系列 Bug 歼灭：
    • 修复了前端缺乏 copyContent 解析函数引起的上下文崩溃，彻底解决了删除笔记按钮点击无效的问题。
    • 对于包含单双引号和换行符的笔记内容，强制以 encodeURIComponent URL 编码装箱并在后端二次替换 %27 逃逸，完全排除了意外截断 HTML 渲染的可能性。
  • � UI 细节重构: 移除了旧版操作按钮的固定宽度图标渲染，彻底改为中文纯文本按钮（📄 复制 / ✏️ 修改 / �️ 删除），解决暗黑主题及环境差异下的图标渲染丢失问题，并增加自适应边距缓解挤压重叠。

• v3.0.3 (2026-03-07):

  • 🎨 视觉系统大升级：引入全新的 3D Claymorphism (黏土拟态) 风格图标。
  • 🪄 解放双手 (Hands-Free) 设计：在图标中嵌入了 "AUTO" 自动化开关与魔法手隐喻，直观传达“让 AI 接管重复劳动，解放程序员双手”的插件核心使命。
  • 📈 品牌语义强化：中心文案由抽象缩写调整为直观的 "Project Rules"，降低新用户的认知成本。

• v3.0.2 (2026-03-07):

  • 🛠️ 规范结构拆分解耦：将原庞大的代码生成规范分拆为严格的按代码层级（服务端实体层、服务端控制层、前端页面）加载机制，显著降低 AI 面临的无效上下文进而解决幻觉问题。
  • 🔧 修复配置更新提醒：解耦版本升级与 MCP 永久路径提醒逻辑，修复由于自动消除标志导致升级弹窗无法正常重出的 Bug（支持“阅后即焚”）。
  • 🐛 流水线指令动静分离：完全将专家流水线 prompt 模板中对规范的指称从字面量硬编码调整为依据当前环节的动态挂载，确保审查逻辑一一对应。

• v3.0.1 (2026-03-06):

  • 🚀 MCP 稳定路径方案 (Permanent Config)：引入 ~/.epoint-rules/start-mcp.js 永久启动脚本。解决 VS Code 插件升级后由于安装目录名变化（包含版本号）导致 AI 客户端（Cursor/Trae）配置失效的痛点。
  • 📢 更新引导提醒：插件升级后自动弹出通知，引导用户一键切换到稳定路径配置。
  • 📂 SQL 生成增强：修复了流水线 Stage 3 偶尔丢失建表语句的问题。

• v3.0.0 (2026-03-03):

  • 🧱 架构硬阻断 (Hard Boundary)：彻底抛弃旧版单体路由，将流水线重构为 7 个完全独立的 MCP 工具（包含系统的控制与确认锁），用硬代码彻底拦截大模型的跨步“偷跑”行为。
  • 📁 文件夹智能命名：新增 requirementName 入参提取，赋予 AI 原生提炼目录名称的能力，告别生硬的前 10 字符内容截断。
  • 💾 同步生成建表脚本：改进 Architect 架构设计阶段的约束 Prompt，强制在出具设计蓝图的同时旁路输出 2_建表语句.sql 脚本。

• v3.0.0 (2026-02-24):

  • 🔧 Frontmatter解析修复：使用 js-yaml 彻底替换旧版正则提取，完美解决含隐形 BOM 头或多层嵌套 YAML 导致的 category 读取失效问题。
  • 🚀 国产化适配自动连跑：升级 Localization Expert 工具模块，现全面支持逐个审查和“自动连跑”两种国产化处理模型，彻底释放手工点选。
  • 🧹 剔除多余文案：删除旧版 国产化适配规范.mdc，全面转向底层代码级自动化工作流。

• v3.0.0 (2026-02-13):

  • 🚀 性能大爆发：重构了规则发现引擎。引入二级缓存（路径+修改时间）和内存快照。现在加载几百条规则只要 2ms。
  • 🧠 意图识别增强：支持了 Java 驼峰命名分词（比如搜 AuditProject 能精准命中相关规则）。
  • 📝 需求澄清升级：BA 专家现在会第一时间先建好 SRS 草案。如果它找你确认需求，它会列出它是根据哪条规则来问你的（格式：- [规则名](https://github.com/epoint/epoint-project-rules/blob/HEAD/关联原因)）。

• v3.0.0 (2026-02-11):

  • 🚀 OA 链接一键直达：新增 parse_oa_demand MCP 工具，支持粘贴 OA 链接自动启动流水线。
  • 📦 OLE 二进制穿透：核心攻坚 Word 文档嵌入 Excel 的逆向提取，实现字段映射表 100% 自动解析。
  • 🏷️ 智能文件夹命名：解析过程自动提取文档内“需求名称”字段，动态创建需求归档目录。
  • ⚡ 流水线加速：新增 [OA_PARSED] 识别逻辑，OA 模式下自动加载产品规则库并跳过 Stage 0 追问，直接出规格书。

• v3.0.0 (2026-02-11):

  • 🕵️ BA 逆向反问增强：引入双层盘点模型（规则覆盖度 + 信息完备性），彻底杜绝 AI "空锅硬炒"。
  • 🔄 追问状态锁：在 WorkflowEngine 中新增 REQUIREMENT_CLARIFYING 状态，支持多轮追问（上限 5 轮）。
  • 🎨 知识可视化大师集成：内置思维导图大师、流程图大师、序列图专家三大高阶工作流。
  • 📚 领域知识库扩展：新增《需求分析指南》，固化 BA 专家的双层盘点逻辑与引导式反问话术。

• v3.0.0 (2026-02-08):

  • 🧘 融合 vibe-coding 方法论：引入道法术器开发哲学、Memory Bank 模式。
  • 📜 黄金准则 10 条：从 vibe-coding 105 条系统提示词中精选核心原则。
  • 🎭 八荣八耻：融入 Claude Code 行为准则。
  • 🚫 零降级策略：禁止 AI 引入 fallback / graceful degradation。
  • 🔧 防止过度设计：新增 KISS/YAGNI 强制约束，禁止"万一"功能。
  • 📋 验证阶段质量检查清单：代码交付前强制自检。
  • 🧠 需求理解 4 步框架：显性需求→隐性需求→技术路径→专家洞见。
  • 📊 可视化呈现原则：设计文档需提供 Mermaid 架构图。
  • 🔄 统一扩展名：新建规范文件默认使用 .md 扩展名。
  • 🧹 清理冗余：删除硬编码关联规范列表，依赖意图识别自动发现。

• v3.0.0 (2026-02-07):

  • 重构 5 阶段"工业化专家流水线"，引入 6 位虚拟专家。
  • 新增勘测员、造价师、复利专家三大角色。
  • 引入智能意图分类（二开识别）与对应约束。
  • 产出物全量中文化、文件夹自动归档。
  • 实现全阶段 Human-in-the-Loop 门禁。
  • 整合"边写边审"QA 规则注入。

• v2.5.0 (2026-02-05):

  • 审计工厂抽象，国产化适配强化。
  • 引入 SQL 验证脚本生成。
  • 修复 VSIX 环境寻址问题。