mcp-feature-doc-generator 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { PROMPT_NAME, PROMPT_DESCRIPTION, buildPromptMessages, } from "./prompts/generate-feature-doc.js";
+import { getTemplateContent } from "./resources/template.js";
+const server = new McpServer({
+    name: "feature-doc-generator",
+    version: "1.0.0",
+});
+// 注册 prompt
+server.prompt(PROMPT_NAME, PROMPT_DESCRIPTION, { featurePath: z.string().describe("功能路径，如 project/pmbasupplierevaluation 或 pm/ba/PmBaRentcontractSettle") }, ({ featurePath }) => ({
+    messages: buildPromptMessages(featurePath),
+}));
+// 注册 resource：功能说明模板
+server.resource("doc-template", "template://feature-doc", { description: "功能说明文档模板（开发规范/功能说明模板.md）", mimeType: "text/markdown" }, () => ({
+    contents: [
+        {
+            uri: "template://feature-doc",
+            mimeType: "text/markdown",
+            text: getTemplateContent(),
+        },
+    ],
+}));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server failed to start:", err);
+    process.exit(1);
+});

package/dist/prompts/generate-feature-doc.d.ts

@@ -0,0 +1,9 @@
+export declare const PROMPT_NAME = "generate_feature_doc";
+export declare const PROMPT_DESCRIPTION = "\u4E3A\u6307\u5B9A\u7684 Vue 3 \u4E1A\u52A1\u529F\u80FD\u8DEF\u5F84\u751F\u6210\u529F\u80FD\u8BF4\u660E\u6587\u6863";
+export declare function buildPromptMessages(featurePath: string): {
+    role: "user";
+    content: {
+        type: "text";
+        text: string;
+    };
+}[];

package/dist/prompts/generate-feature-doc.js

@@ -0,0 +1,256 @@
+import { getTemplateContent } from "../resources/template.js";
+export const PROMPT_NAME = "generate_feature_doc";
+export const PROMPT_DESCRIPTION = "为指定的 Vue 3 业务功能路径生成功能说明文档";
+export function buildPromptMessages(featurePath) {
+    const templateContent = getTemplateContent();
+    const promptText = `# 任务说明
+
+## 任务
+根据**我指定的功能路径**，为 \`src/views/${featurePath}\` 下对应的业务功能生成功能说明文档。
+
+**仅处理我明确提供的功能路径，不自动扫描整个 \`src/views/\`，不按目录逐个遍历。**
+
+但如果**指定功能的 \`index.vue\`、\`form.vue\` 或其他核心页面文件中引入了其他业务功能页面/功能模块**，则需要将这些被引用的相关功能一并纳入分析说明范围。
+
+---
+
+## 模板要求
+严格按照下方「功能说明模板」的 8 个章节结构输出：
+
+1. 功能概述（核心作用 + 业务场景）
+2. 前置数据（数据来源表格 + 前置条件）
+3. 业务流程（\`mermaid graph LR\` 流程图）
+4. 核心业务逻辑（数据联动、计算规则、状态流转等，按需增减子章节）
+5. 后续数据使用（生成的数据表格 + 后续使用场景）
+6. 引用组件说明（关键公共/私有组件及配置）
+7. 注意事项
+8. 总结
+
+---
+
+## 功能路径输入规则
+- 功能生成以**我指定的路径**为准
+- 指定路径为 \`src/views/\` 下的具体功能目录
+- 示例：
+  - \`src/views/pm/ba/PmBaRentcontractSettle/\`
+  - \`src/views/admin/dict/dictItem/\`
+- 一次可输入一个或多个功能路径
+- **优先分析我输入的功能路径本身**
+- **不自动扫描整个 \`src/views/\`**
+- **不按"叶子目录"规则批量遍历所有功能**
+- 如果指定路径不是有效功能目录，需明确提示原因，例如：
+  - 路径不存在
+  - 缺少核心页面文件
+  - 属于非业务目录
+  - 实际为父级目录而非具体功能目录
+
+---
+
+## 功能依赖扩展规则
+如果指定功能目录下的以下文件中：
+
+- \`index.vue\`
+- \`form.vue\`
+- 其他核心业务页面文件
+
+存在对**其他业务功能页面/业务功能模块**的引入、嵌套、弹窗承载、抽屉承载、tab 承载、步骤流承载或局部业务集成，则需要将这些被引用功能纳入说明范围。
+
+### 判定原则
+以下情况视为"需要一并说明的功能"：
+
+- 引入的是其他业务功能页面或业务子模块，而非普通基础组件
+- 引入后承担独立业务职责，如：
+  - 明细维护
+  - 子表管理
+  - 审批处理
+  - 选择业务对象
+  - 合同/订单/费用等关联业务处理
+  - 弹窗表单、抽屉表单、嵌套列表、tab 子页签等
+- 虽然文件不在当前目录下，但在业务上属于当前功能流程的一部分
+
+以下情况**不单独视为功能说明对象**：
+
+- 通用基础组件
+- 纯展示组件
+- 公共 UI 组件
+- 通用 hooks / utils / constants
+- 无独立业务语义的局部片段组件
+- \`microme-operator\`、\`upload-file\`、\`process\`、\`CustomQuery\`、\`TableColumnDrawer\`、\`ExportExcel\`、\`CirculationForm\` 这些组件**强制忽略，不进行分析，不进行说明，不得出现在最终文档任意章节、表格、流程图、注意事项、总结中**
+
+### 补充约束
+- 上述强制忽略组件的优先级**高于"功能依赖扩展规则"**
+- 即使这些组件在 \`index.vue\`、\`form.vue\` 或其他核心页面中被引入、注册、渲染、调用，也**不得视为需要一并说明的功能**
+- 对这些组件，只允许在分析阶段忽略，**不允许在输出中以"使用了某组件""通过某组件实现某能力"等方式间接提及**
+
+### 处理方式
+- 对于被当前功能引用的相关业务功能：
+  - 需要在当前文档中说明其作用、触发方式、数据关系、交互关系
+- 如果该被引用功能本身已经构成一个**独立业务功能单元**，则需要：
+  - 在当前功能文档中说明其与主功能的关系
+  - 同时对该引用功能自身补充对应的功能说明内容
+- 说明范围以"**当前指定功能直接引用到的业务功能**"为主
+- **不继续无限递归扩展**
+- 默认最多向下扩展 **1 层业务功能依赖**
+- 如果存在更深层级引用，仅在当前文档中简要说明，不再继续拆解生成
+
+---
+
+## 非业务目录过滤规则
+若我指定的路径属于以下目录，则跳过并说明原因：
+
+- \`error/\`
+- \`login/\`
+- \`demo/\`
+- \`i18n/\`
+- \`components/\`
+
+---
+
+## 分析要求
+读取**指定功能目录及其直接引用的相关业务功能文件**，包括但不限于：
+
+- \`index.vue\`
+- \`form.vue\`
+- \`options.ts\`
+- 其他与功能相关的 \`ts\`、\`vue\`、\`js\` 文件
+
+如果主功能页面引入了其他业务功能模块，也要同步分析这些文件中的：
+
+- API 接口调用
+- \`defineProps\` / \`defineEmits\`
+- 计算逻辑
+- 字典引用
+- 组件引用
+- 状态流转
+- 数据联动关系
+- 主功能与被引用功能之间的交互方式
+
+头部元信息需根据**指定路径**自动填充：
+
+- 模块路径
+- 所属业务域
+
+---
+
+## 通用模板能力过滤规则
+以下内容若仅体现为项目通用列表页 / 表单页 / 流程页的公共能力，且**没有体现当前功能特有业务语义**，则**不写入功能说明文档**：
+
+- 通用单据状态说明
+- 通用状态流转说明
+- 通用提交流程说明
+- 通用流程流转说明
+- 通用操作权限控制说明
+- 通用按钮权限说明
+- 通用"新增 / 编辑 / 查看 / 删除 / 提交"按钮可用条件
+- 通用"选中条数限制 / 创建人限制 / 状态限制"这类表格操作限制
+
+### 过滤原则
+以下情况一律视为"公共能力"，默认不写：
+
+- 状态值仅表现为通用枚举，如"编辑中、已完成、已提交"等
+- 状态变化仅表现为通用提交或流程驱动，未体现当前功能特有业务规则
+- 权限控制仅表现为按钮权限标识、\`v-hasPermi\`、权限码、通用按钮显隐
+- 按钮禁用条件仅表现为：
+  - 选中 0 条 / 多条
+  - 非创建人
+  - 状态不允许
+  - 流程中 / 已完成等通用限制
+
+### 仅在以下情况才允许写入
+只有当这些内容同时满足"与当前功能强相关且具有明确业务语义"时，才允许写入文档，例如：
+
+- 状态流转体现了该功能独有的业务阶段
+- 状态变化由当前功能特有字段、计算结果或业务动作触发
+- 权限控制不是通用按钮权限，而是与当前业务对象、业务身份、业务规则强绑定
+- 状态或权限会直接影响核心业务数据处理结果
+
+### 输出要求
+- 不要单独输出"单据状态流转""操作权限控制"这类通用小节
+- 不要输出通用状态表格
+- 不要输出通用权限标识表格
+- 若代码中仅存在项目通用状态 / 权限封装，但无当前功能特有业务含义，则直接忽略，不进行说明
+
+---
+
+## 输出规则
+- 输出到 \`开发规范/views/\` 目录下
+- 保持与源码相同的模块子目录结构
+- 示例：
+  - 源码目录：\`src/views/pm/ba/PmBaRentcontractSettle/\`
+  - 输出文件：\`开发规范/views/pm/ba/PmBaRentcontractSettle-README.md\`
+- 文件命名规则：
+  - \`{功能目录名}-README.md\`
+
+### 关于被引用功能的输出规则
+- 若被引用功能仅作为当前功能的一部分存在，则合并写入当前功能文档中，不单独输出
+- 若被引用功能具备独立业务语义，则可单独补充说明
+- 是否单独输出的判断依据：
+  - 是否有独立页面入口
+  - 是否承担独立业务职责
+  - 是否存在独立接口、表单、状态流转
+- 若单独输出，需保持其原始模块目录结构
+
+---
+
+## 执行方式
+- 由我手动指定本次需要处理的功能路径
+- 你只处理本次提供的路径，以及这些路径**直接引用到的相关业务功能**
+- 每次处理完本次指定范围后停止，等待我下一次指令
+- **不要自动继续处理其他未指定功能**
+- **不要自动扫描整个一级模块**
+- **不要批量生成未被引用的其他功能**
+
+---
+
+## 额外要求
+- 若指定路径下存在多个页面文件或子场景文件，需一并分析，并合并到同一份功能说明文档中
+- 若 \`index.vue\` 引入了其他业务功能，必须在文档中说明：
+  - 引入了什么功能
+  - 在什么场景下触发
+  - 与当前主功能的数据关系
+  - 是否共享状态、回传数据、联动刷新
+- 若发现该路径更适合作为"父级容器"而非独立功能，需明确说明，不擅自扫描生成所有子功能
+- 生成内容必须基于代码实际实现，不得臆造业务逻辑
+- 即使代码中存在通用状态、通用权限、通用流程封装，也只有在体现当前功能特有业务语义时才可写入；否则忽略
+- 若部分逻辑无法从当前代码直接判断，应在文档中标注"待确认"
+- 对项目通用能力进行过滤：若某些内容仅属于公共列表页 / 表单页 / 流程页的通用机制，而非当前功能特有业务逻辑，则不写入文档
+- 这类通用能力包括但不限于：通用单据状态、通用状态流转、通用提交流程、通用按钮权限、通用新增/编辑/查看/删除/提交按钮控制、通用选中条数限制、通用创建人限制、通用状态禁用条件
+- 仅当状态流转或权限控制明确体现当前功能特有业务语义、业务阶段、业务规则、业务身份约束时，才允许写入；否则忽略
+- 不单独输出"单据状态流转""操作权限控制""权限标识"这类公共说明小节
+
+---
+
+## 输出前自检
+在最终输出前，必须检查结果中是否包含以下关键词：
+
+- \`microme-operator\`
+- \`upload-file\`
+- \`process\`
+- \`CustomQuery\`
+- \`TableColumnDrawer\`
+- \`ExportExcel\`
+- \`CirculationForm\`
+
+如果包含，则删除相关描述后再输出。
+**最终文档中，上述关键词出现次数必须为 0。**
+
+---
+
+# 功能说明模板
+
+以下是功能说明文档的标准模板结构，请严格遵循：
+
+\`\`\`markdown
+${templateContent}
+\`\`\`
+`;
+    return [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: promptText,
+            },
+        },
+    ];
+}

package/dist/resources/template.d.ts

@@ -0,0 +1 @@
+export declare function getTemplateContent(): string;

package/dist/resources/template.js

@@ -0,0 +1,135 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+const EMBEDDED_TEMPLATE = `# {功能中文名} ({功能目录名})
+
+> **模块路径**: \`{一级模块}/{二级模块}/{功能目录名}\`
+> **组件名称**: \`{列表页组件名}\` (列表页) / \`{表单页组件名}\` (表单页)
+> **所属业务域**: {一级业务域} → {二级业务域} → {功能名称}
+
+---
+
+## 1. 功能概述
+
+{用 2-3 句话描述本功能的核心作用，说明"做什么"和"为什么做"。}
+
+**业务场景**: {描述实际的使用场景，说明谁在什么情况下使用本功能。}
+
+---
+
+## 2. 前置数据
+
+### 2.1 数据来源
+
+| 数据类型 | 来源 | 用途 |
+| -------- | ---- | ---- |
+| {数据类型1} | {来源模块} | {在本功能中的用途说明} |
+| {数据类型2} | {来源模块} | {在本功能中的用途说明} |
+
+### 2.2 前置条件
+
+- {条件1：如"存在有效的XX合同"}
+- {条件2：如"XX已完成审批流程"}
+
+---
+
+## 3. 业务流程
+
+\`\`\`mermaid
+graph LR
+    A["{步骤1}"] -->|{操作}| B["{步骤2}"]
+    B --> C["{步骤3}"]
+    C --> D{"{判断条件}"}
+    D -->|{分支1}| E["{结果1}"]
+    D -->|{分支2}| F["{结果2}"]
+\`\`\`
+
+---
+
+## 4. 核心业务逻辑
+
+### 4.1 数据选择联动
+
+{描述页面上各选择器之间的联动关系，如"选择A后自动带入B、C字段，同时清空D"。}
+
+\`\`\`
+选择{实体A}
+  │
+  ├── 筛选条件：{字段} = {值}
+  ├── 赋值字段：{field1}, {field2}, {field3}
+  └── 联动影响：{清空/重置哪些数据}
+        │
+        ▼
+选择{实体B}（基于已选{实体A}过滤）
+  │
+  ├── 校验：{调用什么接口做什么校验}
+  ├── 自动回填字段：{field4}, {field5}, ...
+  └── {其他联动操作}
+\`\`\`
+
+### 4.2 计算规则
+
+{描述本功能涉及的计算逻辑，如金额计算、数量汇总等。如无计算逻辑可删除本节。}
+
+| 字段 | 说明 | 计算方式 |
+| ---- | ---- | -------- |
+| \`{字段名}\` | {字段含义} | {计算公式或数据来源} |
+
+#### 计算触发时机
+
+| 触发操作 | 调用链 |
+| -------- | ------ |
+| {用户操作1} | \`{函数A}()\` → \`{函数B}()\` |
+| {用户操作2} | \`{函数C}()\` → \`{函数D}()\` |
+
+### 4.3 {其他核心逻辑}
+
+{根据功能实际情况补充，如日期联动、状态流转、模式切换等。每个独立逻辑点作为一个子章节。}
+
+---
+
+## 5. 后续数据使用
+
+### 5.1 生成的数据
+
+| 数据类型 | 存储位置 | 用途 |
+| -------- | -------- | ---- |
+| {主表数据} | {数据库表名} | {存储什么信息} |
+| {子表数据} | {数据库表名} | {存储什么信息} |
+
+### 5.2 后续使用场景
+
+- **{场景1}**：{说明下游模块如何使用本功能产出的数据}
+- **{场景2}**：{说明}
+
+---
+
+## 6. 引用组件说明
+
+{列出本功能使用的关键公共组件/私有组件，说明用途和关键配置。如组件较多可使用子章节分列。}
+
+### 6.1 {组件名} — {组件用途}
+
+{简要说明该组件在本功能中的使用方式、关键传参或特殊配置。}
+
+---
+
+## 7. 注意事项
+
+1. **{要点1标题}**：{详细说明}
+2. **{要点2标题}**：{详细说明}
+
+---
+
+## 8. 总结
+
+{用 1-2 段话概括本功能的业务价值，说明它在整个系统中的定位和意义。}`;
+export function getTemplateContent() {
+    // 优先从项目本地读取（支持用户自定义模板），找不到则使用内嵌模板
+    try {
+        const localPath = resolve(process.cwd(), "开发规范/功能说明模板.md");
+        return readFileSync(localPath, "utf-8");
+    }
+    catch {
+        return EMBEDDED_TEMPLATE;
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "mcp-feature-doc-generator",
+  "version": "1.0.0",
+  "description": "MCP server for generating Vue 3 feature documentation via prompt template",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-feature-doc-generator": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "vue3",
+    "documentation",
+    "feature-doc"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}