@jdzhang225gmail/fontend-prompt 0.1.0 → 0.2.0

package/README.md

@@ -1,223 +1,79 @@
-# 前端提示词流程 MCP Server
+# 前端提示词 Skills (CLI)
 
-这是一个 Model Context Protocol（MCP）服务，用于**标准化前端开发的提示词与工作流**。
+这是一个**前端开发辅助 CLI 工具**。它通过**零 Token 消耗**的本地分析，将模糊的需求转化为**专业、结构化、带审批流的前端开发方案**，供 Agent 或开发者直接使用。
 
-它可以把质量参差不齐的用户问题，转换为更适合 AI 安全执行的**结构化、带审批关口（gate）的方案**：
+## 🌟 核心特性
 
-- **先理解项目**（扫描目录树）
-- **按任务类型套模板**（新功能 / 优化 / 重构 / 等）
-- **审批关口**（宿主在每个 gate 处拦截并让用户确认）
-- **TypeScript 校验 + 验收流程**
-- **条件触发的文档更新**（仅当存在 `claude.md/CLAUDE.md` 时）
-
-本服务使用 **stdio**（最主流、最容易配置的 MCP 部署方式），应由 MCP 宿主（例如 Claude Desktop）启动。
+- **纯 CLI 工具**: 无需常驻服务，即用即走。
+- **节省 Token**: 本地扫描项目结构，无需将整个文件树塞入 Context。
+- **结构化输出**: 生成包含文件变更、审批关口、校验步骤的标准 Prompt。
 
 ---
 
-## 环境要求
-
-- 建议 Node.js 18+
-
----
-
-## 安装与构建
-
-```bash
-npm install
-npm run build
-```
+## 🚀 安装 (推荐)
 
-运行（仅用于调试）：
+为了获得极速体验（避免每次 `npx` 下载），请**全局安装**：
 
 ```bash
-npm start
+npm install -g @jdzhang225gmail/fontend-prompt
 ```
 
-> 注意：直接运行该服务不会出现交互界面。MCP Server 通常会等待宿主通过 stdio 发送 JSON-RPC 消息。
+安装后，即可使用 `fontend-prompt` 命令。
 
 ---
 
-## 在 MCP 宿主中配置（stdio）
-
-### 推荐（最方便）：使用 npx 启动（无需下载源码）
-
-- **command**：`npx`（Windows 某些宿主需要写 `npx.cmd`）
-- **args**：`["-y", "<你的npm包名>@<版本>"]`
-
-```json
-{
-  "mcpServers": {
-    "frontend-prompt-workflow": {
-      "command": "npx",
-      "args": ["-y", "frontend-prompt-workflow-mcp@0.1.0"]
-    }
-  }
-}
-```
+## 📖 使用指南
 
-### 推荐（稳定）：运行构建后的产物
+### 1. 扫描项目 (Scan)
+快速了解项目架构、技术栈与关键文件。
 
-使用 **Node** 运行 `dist/index.js`。
-
-- **command**：`node`
-- **args**：`["d:/web/mcp/dist/index.js"]`
-
-### Claude Desktop 示例（Windows）
-
-在 Claude Desktop 的 MCP 配置中添加类似内容：
-
-```json
-{
-  "mcpServers": {
-    "frontend-prompt-workflow": {
-      "command": "node",
-      "args": ["d:/web/mcp/dist/index.js"]
-    }
-  }
-}
+```bash
+fontend-prompt scan
+# 或指定目录
+fontend-prompt scan --depth 2
 ```
 
-> Claude Desktop 配置文件的具体位置/名称可能随版本变化。关键是：**宿主通过 `node dist/index.js` 启动这个服务**。
-
----
-
-## 工具
-
-### 1) `scan_project`
-
-扫描项目目录（只读），输出目录树，并检测是否存在 `claude.md/CLAUDE.md`。
-
-**入参**
-
-```json
-{
-  "rootDir": ".",
-  "maxDepth": 4,
-  "maxEntries": 1200
-}
-```
+### 2. 优化需求 (Optimize)
+将你的“一句话需求”转化为详细的开发方案。
 
-**出参（JSON 文本）**
-
-- `tree`：目录树
-- `hasClaudeMd`：是否存在 `claude.md/CLAUDE.md`
-- `claudeMdPaths`：命中的路径
-- `suggestedFiles`：检测到的关键配置文件
-
-### 2) `optimize_frontend_prompt`
-
-将原始用户问题转换为一个**提示词包**，包含：
-
-- `messages`：可直接喂给 AI 的 `system` + `user` 消息
-- `workflow`：机器可解析的步骤与 gate
-- `guardrails`：约束与限制条件
-- `clarifyingQuestions`：继续执行前需要追问的澄清问题
-
-**关键入参**
-
-- `userPrompt`（必填）
-- `taskType`：
-  - `new_feature`
-  - `optimize_existing`
-  - `refactor`
-  - `bugfix`
-  - `performance`
-  - `ui_polish`
-  - `dependency_upgrade`
-  - `test_addition`
-- `requireApprovalGates`（默认 `true`）：强制在 gate 处停下等待用户确认
-- 可选的技术栈提示：`framework`、`language`、`styling`、`router` 等
-
-**示例入参**
-
-```json
-{
-  "userPrompt": "给后台新增一个用户列表页面，支持搜索、分页、编辑弹窗",
-  "taskType": "new_feature",
-  "language": "ts",
-  "framework": "React",
-  "styling": "TailwindCSS",
-  "requireApprovalGates": true
-}
+```bash
+fontend-prompt optimize "给后台增加一个用户管理页面"
 ```
 
-**重要出参字段（重要字段）**
-
-- `workflow.gates[]`：审批关口列表
-- `messages[]`：标准化后的提示词
-
-### 3) `score_frontend_prompt`
-
-对提示词质量评分，并识别缺失信息。
+### 3. 评分 (Score)
+看看你的 Prompt 写得好不好，缺什么信息。
 
-**入参**
-
-```json
-{ "prompt": "..." }
+```bash
+fontend-prompt score "帮我写个页面"
 ```
 
-**出参**
-
-- `score`（0-100）
-- `missing[]`
-- `suggestions[]`
-
 ---
 
-## 宿主编排（最佳实践）
-
-为了让 gate 更可靠、做到“像主流 MCP 一样好用”，建议采用：**由宿主拦截**。
-
-### Gate 标记（拦截信号）
-
-强制模板中包含机器可解析标记：
-
-- Gate 开始：
-
-```text
-<<<MCP:GATE id="new_feature_design" action="WAIT_FOR_USER_APPROVAL">>>
-```
-
-- Gate 停止（推荐把它作为宿主拦截触发信号）：
+## 🤖 在 Agent 中使用 (Antigravity / Claude Code)
 
-```text
-<<<MCP:WAIT gate_id="new_feature_design" action="WAIT_FOR_USER_APPROVAL">>>
-```
+为了让 Agent 更流畅地调用本工具，请告诉它直接使用命令行。
 
-### 推荐的宿主行为
+**添加到 `.cursorrules` 或 Agent 系统提示词：**
 
-1. 调用 `scan_project`（获取目录树 + `hasClaudeMd`）
-2. 调用 `optimize_frontend_prompt`
-3. 将返回的 `messages` 喂给你的 AI
-4. 当 AI 输出包含 `<<<MCP:WAIT ...>>>`：
-   - 宿主停止继续
-   - 询问用户：**同意 / 调整 / 取消**
-5. 用户同意后 -> 宿主开启下一轮 AI，对应 gate 之后的步骤继续执行
+> "当需要理解项目结构时，请运行命令 `fontend-prompt scan`。"
+> "当需要规划新功能时，请运行命令 `fontend-prompt optimize '<需求>'`，并根据输出结果执行。"
 
 ---
 
-## 说明 / 常见问题（FAQ）
-
-### 1) `scan_project` 的 rootDir
-
-出于安全考虑，`scan_project.rootDir` 必须位于**服务进程的工作目录（cwd）**之内。
-
-因此，通常建议宿主用**目标前端项目根目录作为工作目录（cwd）**来启动这个 MCP 服务。
-
-### 2) 为什么使用 stdio？
+## 📦 本地开发与构建
 
-stdio 是 MCP 宿主里支持最广、也最容易配置的传输方式。
-
----
-
-## 开发
+如果你想二次开发：
 
 ```bash
-npm run dev
+npm install
+npm run build
+
+# 本地测试
+node dist/cli.js --help
 ```
 
 ---
 
 ## 许可
 
-默认：私有 / 内部使用。
+MIT

package/dist/cli.js

@@ -1,2 +1,77 @@
 #!/usr/bin/env node
-import "./index.js";
+import { cac } from "cac";
+import { scanProject } from "./skills/scan.js";
+import { buildOptimizedPromptPackage } from "./skills/optimize.js";
+import { scoreFrontendPrompt } from "./skills/score.js";
+import * as fs from "fs/promises";
+// 读取 package.json 获取版本号
+// const pkg = JSON.parse(await fs.readFile(new URL("../package.json", import.meta.url), "utf-8"));
+// 为了避免 ESM 路径问题，暂时硬编码，或者用 simple import
+const version = "0.2.0";
+const cli = cac("fontend-skill");
+cli
+    .command("scan [root]", "扫描项目目录结构与关键文件")
+    .option("--depth <number>", "最大目录深度", { default: 4 })
+    .option("--entries <number>", "最大文件条目数", { default: 1200 })
+    .action(async (root, options) => {
+    try {
+        const result = await scanProject({
+            rootDir: root,
+            maxDepth: options.depth,
+            maxEntries: options.entries,
+        });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (e) {
+        console.error("扫描失败:", e.message);
+        process.exit(1);
+    }
+});
+cli
+    .command("optimize <prompt>", "将原始需求转化为结构化 Prompt")
+    .option("--context <string>", "项目上下文")
+    .option("--stack <string>", "技术栈")
+    .option("--framework <string>", "框架")
+    .option("--lang <string>", "语言 (ts/js)", { default: "ts" })
+    .option("--type <string>", "任务类型 (new_feature 等)")
+    .option("--save <path>", "将结果保存到文件")
+    .action(async (prompt, options) => {
+    try {
+        const args = {
+            userPrompt: prompt,
+            projectContext: options.context,
+            techStack: options.stack,
+            framework: options.framework,
+            language: options.lang,
+            taskType: options.type,
+            outputLanguage: "zh", // 强制默认中文
+        };
+        const result = buildOptimizedPromptPackage(args);
+        if (options.save) {
+            await fs.writeFile(options.save, JSON.stringify(result, null, 2), "utf-8");
+            console.log(`结果已保存至: ${options.save}`);
+        }
+        else {
+            console.log(JSON.stringify(result, null, 2));
+        }
+    }
+    catch (e) {
+        console.error("优化失败:", e.message);
+        process.exit(1);
+    }
+});
+cli
+    .command("score <prompt>", "对 Prompt 质量进行评分")
+    .action((prompt) => {
+    try {
+        const result = scoreFrontendPrompt({ prompt });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (e) {
+        console.error("评分失败:", e.message);
+        process.exit(1);
+    }
+});
+cli.help();
+cli.version(version);
+cli.parse();