Epoint Rules - AI 代码生成规范系统

[!IMPORTANT] 最新版本 v2.5.1：

• 🎨 UI 升级：侧边栏目录管理区域新增 userRulesPath 可视化配置，支持直接浏览文件夹。
• ⚡ 交互优化：智能识别用户选择的路径，自动处理文件/目录层级。

📦 一、快速开始

1.1 环境要求

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

本插件内置了完善的 MCP (Model Context Protocol) 服务器，旨在让 AI 助手（如 Cursor, Windsurf, Claude Desktop）直接理解项目规范。

1. 启动插件：在 VS Code 中安装并激活本插件。
2. 获取配置：
   • 点击侧边栏 "政务BG规范助手"。
   • 切换到 "⚙️ 管理配置" 标签页。
   • 点击 "复制配置信息" 按钮。
3. 应用配置：
   • 将复制的 JSON 配置信息粘贴到您的 AI 客户端配置中（如 claude_desktop_config.json 或 Cursor 的 MCP 设置）。
4. 关键配置项：
   • EPOINT_RULES_PATH: 指向插件内置或您自定义的规范文件目录。
   • EPOINT_USER_RULES_PATH: 指向您个人/项目组的自定义扩展规范目录。

✨ 二、核心功能

2.1 侧边栏助手 (Sidebar Helper)

插件提供了一个可视化的侧边栏，方便开发者快速查阅和管理规范：

• 📚 规范列表:
  • 分组展示: 自动按类别（核心流程、基础规范、框架能力等）展示所有 .mdc 规范文件。
  • 智能搜索: 顶部搜索框支持实时过滤规范。
  • 一键复制提示词: 每个规范卡片带有“复制提示词”按钮，点击即可获取引导 AI 使用该规范的最佳提示词。
  • 快速以新标签页打开: 点击卡片即可在编辑器中查看规范详情。
• 🛠️ 快捷操作:
  • 新建规则: 内置“基础规范”、“代码生成”、“组件开发”、“API接口”四种模板，快速创建自定义规范。
  • 管理配置:
    • 🚀 操作指南: 新置可视化 5 步引导，涵盖从路径配置到 MCP 注册的全流程。
    • 同步规则: 支持 稀疏检出 (Sparse Checkout)，仅拉取仓库中的规范子目录，极致节省物理空间。
    • MCP 核心配置: 一键复制运行参数，支持 Trae 等 AI 客户端集成。

2.2 智能命令系统 (Commands)

插件注册了一系列 VS Code 命令，支持快捷键调用（Ctrl/Cmd + Shift + P 输入 Epoint）：

2.3 个性化配置 (Settings)

支持通过 VS Code 设置 (settings.json) 进行深度定制：

🤖 三、MCP 服务器与 AI Agent

本插件核心是一个强大的 MCP 服务器，为 AI 提供以下工具能力：

3.1 核心工具 (Tools)

3.2 AI 开发工作流

系统采用 Workflow Engine 状态机管理开发过程：

graph LR
    Start(用户需求) --> Intent{意图识别}
    Intent -->|明确| Designing(方案设计)
    Intent -->|模糊| Recommend[推荐相关规范]
    
    Designing --> Confirm1{用户确认设计?}
    Confirm1 -->|修改| Designing
    Confirm1 -->|通过| GenerateList(生成文件清单)
    
    GenerateList --> Confirm2{用户确认清单?}
    Confirm2 -->|修改| GenerateList
    Confirm2 -->|通过| Coding(代码生成)
    
    Coding --> Validation(验证与测试)
    Validation --> Finish(完成)

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

规范文件位于插件内置目录或用户自定义目录，采用 Markdown + YAML Frontmatter 格式。

核心规范一览：

• 核心流程: ai.mdc (总入口), 设计模板.mdc
• 基础规范: 项目结构与命名规范.mdc, 代码生成规范.mdc
• 前端开发: 前端API-开发手册.mdc, 左树右表开发规范.mdc, 手风琴布局开发规范.mdc
• 后端开发: REST接口开发规范.mdc, SqlConditionUtil使用规范.mdc, HttpUtil使用规范.mdc, 定时任务Job开发规范.mdc
• 框架服务API: IAttachService接口使用规范.mdc, ICodeItemsService接口使用规范.mdc, IConfigService接口使用规范.mdc, IMessagesCenterService接口使用规范.mdc, IOuService接口使用规范.mdc, IRoleService接口使用规范.mdc, IUserRoleRelationService接口使用规范.mdc, IUserService接口使用规范.mdc
• 功能组件: 附件上传开发规范.mdc, 关联配置弹窗开发规范.mdc

如何自定义技能？

方式一：在 userRulesPath 目录下手动新建 .mdc 文件：

[!IMPORTANT] 命名准则：文件名必须遵循 [业务领域/类名]-[场景描述].mdc 范式（例如：办件任务(IAuditTask)-接口规范.mdc）。严禁使用“通用”、“接口”等模糊名称。

---
description: 办件任务相关后端接口开发规范
category: 📦 后端服务
intent_keywords: [办件审核, 审核分页, IAuditTask, AuditTaskService]
---

# 办件任务(IAuditTask)-接口规范
这里写详细的业务规范、API 约束和代码示例...

[!TIP] 意图关键词 (Intent Keywords) 最佳实践：

• 精准度：避免使用“后端”、“接口”等通用词。
• 组合性：推荐 [业务实体] + [核心操作/类名] 的组合。
• 唯一性：如果一个关键词在多个规范中通用，请移除或细化它。

方式二：让 AI 自动创建规范（推荐）

对 AI 说："帮我基于 IAuditTask 提炼一份业务开发规范"，AI 会依据配置的准则自动生成高精准度的规范文件。

📝 更新日志

• v2.5.0 (架构优化与智能管家版):

  这一版本标志着插件从“辅助工具”向“智能管家”的转变，并实现了向“工业级性能”的跨越：

  • 🤖 智能管家体验：
    • 绝对服从：状态机硬拦截，流程严格受控。
    • 自我纠正：每一步都有导航引导，走错了自动拉回来。
    • 越用越强：用得越多，沉淀的规范越多，AI 越懂你的业务。
  • ⚡ 响应速度极速提升：
    • 异步 I/O 改造：底层文件读取全面转向 fs.promises 非阻塞模式，杜绝大规模规则扫描时的界面卡顿。
    • 规则元数据缓存：在 RulesMerger 引入精准缓存机制，元数据提取效率提升约 100%。
    • LRU 缓存增强：优化了 NodeCache 实现，规则内容读取速度提升 400x。
  • � 架构治理与能力增强：
    • aiAgentCore 动态识别：核心规则支持通过 frontmatter 动态定义，实现“零代码”规范扩展。
    • 工作流断点恢复：引入状态持久化机制，MCP 服务重启后开发进度可自动恢复。
    • Registry 模式：引入 ToolRegistry 注册器模式，统一管理工具定义，代码更整洁、更易维护。

  • 🛡️ 防幻觉体系：构建了“状态机硬拦截 + 工具返回值引导 + 极简指令”的三层防护网。
  • 📈 复利沉淀机制：集成 create_rule 引导将开发经验持续沉淀。
  • 🔄 规范继承：代码生成阶段自动加载核心规范（代码生成、命名规范、前端手册）。
  • 瘦身计划：修正 .vscodeignore 包含策略，插件运行更轻量。
  • UI 升级：可视化配置 userRulesPath，采用 Native Folder Picker 提供原子级交互体验。

• v2.4.7:

  • UI 体验翻新：增加了可视化任务引导区块。
  • 极致空间缩减：引入 Git 稀疏检出 (Sparse Checkout)，实现仅同步 projectrules 目录，不下拉无关源码。
  • 流程闭环：整合了刷新列表、重启环境与 MCP 注册的交互闭环。
  • 稳定性增强：彻底排除内置规则目录打包，杜绝本地过期文件干扰。

• v2.3.7:

  • UI 重构：全新的侧边栏视觉体验，支持分组折叠与实时搜索。
  • 功能增强：新增“管理配置”面板，一键复制 MCP 配置。

• v2.3.5: 规范体系重构，支持 putAll 组合查询。

• v2.3.0: 引入去中心化 Skills 方案。