@jdzhang225gmail/fontend-prompt 0.1.1 → 0.2.0

package/README.md

@@ -1,104 +1,79 @@
-# 前端提示词 Skills & MCP Server
+# 前端提示词 Skills (CLI)
 
-这是一个**前端开发辅助工具库**，它既可以作为 **Skills (CLI 工具)** 使用（零 Token 消耗，适合 Agent 直接调用），也可以作为标准的 **MCP Server** 使用。
+这是一个**前端开发辅助 CLI 工具**。它通过**零 Token 消耗**的本地分析，将模糊的需求转化为**专业、结构化、带审批流的前端开发方案**，供 Agent 或开发者直接使用。
 
-它致力于把模糊的需求转化为**专业、结构化、带审批流的前端开发方案**。
+## 🌟 核心特性
 
-## 🌟 核心理念：Skills vs MCP
-
--   **Skills (CLI 模式)**: 🚀 **推荐！** Agent 通过命令行直接运行工具。 **优点**：无需在 Prompt 中挂载巨量的工具定义，极大节省 Token；运行速度快；无常驻进程。
--   **MCP Server 模式**: 经典模式，适合 Claude Desktop 等标准 MCP 客户端。
+- **纯 CLI 工具**: 无需常驻服务，即用即走。
+- **节省 Token**: 本地扫描项目结构，无需将整个文件树塞入 Context。
+- **结构化输出**: 生成包含文件变更、审批关口、校验步骤的标准 Prompt。
 
 ---
 
-## 🚀 快速开始 (CLI / Skills)
+## 🚀 安装 (推荐)
+
+为了获得极速体验（避免每次 `npx` 下载），请**全局安装**：
+
+```bash
+npm install -g @jdzhang225gmail/fontend-prompt
+```
 
-无需安装，直接使用 `npx` 运行：
+安装后，即可使用 `fontend-prompt` 命令。
+
+---
+
+## 📖 使用指南
 
 ### 1. 扫描项目 (Scan)
 快速了解项目架构、技术栈与关键文件。
 
 ```bash
-npx @jdzhang225gmail/fontend-prompt scan
+fontend-prompt scan
 # 或指定目录
-npx @jdzhang225gmail/fontend-prompt scan --depth 2
+fontend-prompt scan --depth 2
 ```
 
 ### 2. 优化需求 (Optimize)
-将你的“一句话需求”转化为详细的开发方案（包含文件变更、审批关口等）。
+将你的“一句话需求”转化为详细的开发方案。
 
 ```bash
-npx @jdzhang225gmail/fontend-prompt optimize "给后台增加一个用户管理页面"
+fontend-prompt optimize "给后台增加一个用户管理页面"
 ```
 
 ### 3. 评分 (Score)
 看看你的 Prompt 写得好不好，缺什么信息。
 
 ```bash
-npx @jdzhang225gmail/fontend-prompt score "帮我写个页面"
+fontend-prompt score "帮我写个页面"
 ```
 
 ---
 
 ## 🤖 在 Agent 中使用 (Antigravity / Claude Code)
 
-### 方式一：作为 CLI 工具（最省 Token）
-
-告诉你的 Agent（或者写在 `.cursorrules` / `.agent/workflows` 中）：
-
-> "当需要理解项目结构时，请运行命令 `npx @jdzhang225gmail/fontend-prompt scan`。"
-> "当需要规划新功能时，请运行命令 `npx @jdzhang225gmail/fontend-prompt optimize '<需求>'`，并根据输出结果执行。"
-
-### 方式二：作为库集成
+为了让 Agent 更流畅地调用本工具，请告诉它直接使用命令行。
 
-如果你在编写 TS 脚本或 Agent 插件：
+**添加到 `.cursorrules` 或 Agent 系统提示词：**
 
-```typescript
-import { scanProject, optimizeFrontendPrompt } from "@jdzhang225gmail/fontend-prompt";
-
-const tree = await scanProject({ rootDir: "." });
-const plan = optimizeFrontendPrompt({ userPrompt: "..." });
-```
+> "当需要理解项目结构时，请运行命令 `fontend-prompt scan`。"
+> "当需要规划新功能时，请运行命令 `fontend-prompt optimize '<需求>'`，并根据输出结果执行。"
 
 ---
 
-## 📦 安装与构建
+## 📦 本地开发与构建
 
-如果你想本地部署或二次开发：
+如果你想二次开发：
 
 ```bash
 npm install
 npm run build
 
-# 本地运行 CLI
-npm run skill -- --help
-```
-
----
-
-## 🛠️ MCP Server 配置
-
-如果你仍希望在 Claude Desktop 中作为常驻服务使用：
-
-```json
-{
-  "mcpServers": {
-    "frontend-helper": {
-      "command": "npx",
-      "args": ["-y", "@jdzhang225gmail/fontend-prompt"]
-    }
-  }
-}
+# 本地测试
+node dist/cli.js --help
 ```
 
 ---
 
-## 功能特性
-
--   **中文优先**: 所有输出、文档、注释默认均为中文。
--   **Gate 机制**: 在关键节点（设计/计划/验收）生成审批关口，防止 AI 一条路走到黑。
--   **安全扫描**: 自动识别项目目录，但严格限制在 CWD 下访问。
-
 ## 许可
 
 MIT

package/dist/cli.js

@@ -7,7 +7,7 @@ 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.1.0";
+const version = "0.2.0";
 const cli = cac("fontend-skill");
 cli
     .command("scan [root]", "扫描项目目录结构与关键文件")

package/dist/index.js

@@ -1,181 +1,5 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { scanProject } from "./skills/scan.js";
-import { buildOptimizedPromptPackage } from "./skills/optimize.js";
-import { scoreFrontendPrompt } from "./skills/score.js";
-import { asNonEmptyString } from "./utils.js";
-// === 导出 Skills (作为库使用) ===
 export * from "./types.js";
 export * from "./utils.js";
 export { scanProject } from "./skills/scan.js";
 export { buildOptimizedPromptPackage as optimizeFrontendPrompt } from "./skills/optimize.js";
 export { scoreFrontendPrompt } from "./skills/score.js";
-// === MCP Server 实现 ===
-// 只有当文件被直接运行时才启动 Server
-// 简单的判断方式：看是否通过 import 导入
-// 在 Node.js 中，如果 entry point 是此文件，则启动
-const isMainModule = import.meta.url.endsWith(process.argv[1]) || (process.argv[1] && import.meta.url.includes(process.argv[1]));
-// 注意：ESM 中判断 isMain 比较麻烦，这里我们简化处理：
-// 如果是通过 `node dist/index.js` 启动，我们假设它是为了跑 server。
-// 如果作为库被 import，通常不会立即执行 await server.connect。
-// 但 MCP SDK 的 connect 是阻塞的吗？StdioServerTransport 是基于 stdio 的。
-// 为了安全起见，我们把 Server 启动逻辑封装在一个函数里，如果用户想跑 Server 可以显示调用，或者我们检测命令行参数。
-// 或者，为了兼容旧的 `npm start`，我们保留默认启动行为，但如果用户只想用库，可能会有副作用。
-// 更好的做法是：把 Server 逻辑拆分到 `src/server.ts`，`index.ts` 只做导出。
-// 但根据计划，我们尽量保持 index.ts 为入口。
-// 让我们依然默认启动 Server，因为这对 MCP 是标准行为。
-// 使用者如果只是 import { scanProject } from '...', 只要不执行到最后的 connect 就行。
-// 但顶层的代码会执行。
-// 修正方案：将 Server 逻辑包裹在 IIFE 或判断中。
-// 更加稳妥的方式：不做判断，假设这个文件就是 Server 入口。
-// 库的使用者应该 import from './skills/scan.js' 而不是 './index.js' 以避免副作用，或者我们把 index.js 变成纯导出，把 server 移到 server.ts。
-// 鉴于我不想改变 `dist/index.js` 的既定路径（README 里写了），我将保持 `index.ts` 为 Server。
-// 并新建 `src/lib.ts` 或直接让用户 import 子路径。
-// 为了完成任务 "Reorganized Structure"，我会把 Server 逻辑保留在 index.ts，但极其精简。
-const server = new Server({
-    name: "frontend-prompt-workflow-mcp",
-    version: "0.1.0",
-}, {
-    capabilities: {
-        tools: {},
-    },
-});
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: [
-            {
-                name: "scan_project",
-                description: "Scan project directory tree (read-only) and detect claude.md/CLAUDE.md. Intended for initial architecture understanding.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        rootDir: { type: "string" },
-                        maxDepth: { type: "number" },
-                        maxEntries: { type: "number" },
-                    },
-                },
-            },
-            {
-                name: "optimize_frontend_prompt",
-                description: "Standardize/optimize a raw user question into a frontend-dev prompt package (messages + guardrails + clarifying questions).",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        userPrompt: { type: "string" },
-                        projectContext: { type: "string" },
-                        techStack: { type: "string" },
-                        framework: { type: "string" },
-                        language: { type: "string", enum: ["ts", "js"] },
-                        styling: { type: "string" },
-                        stateManagement: { type: "string" },
-                        router: { type: "string" },
-                        constraints: { type: "array", items: { type: "string" } },
-                        taskType: {
-                            type: "string",
-                            enum: [
-                                "new_feature",
-                                "optimize_existing",
-                                "refactor",
-                                "bugfix",
-                                "performance",
-                                "ui_polish",
-                                "dependency_upgrade",
-                                "test_addition",
-                            ],
-                        },
-                        outputLanguage: { type: "string", enum: ["zh", "en"] },
-                        outputFormat: { type: "string", enum: ["step_by_step", "direct", "both"] },
-                        codeStyle: { type: "string", enum: ["diff", "full_files", "snippets"] },
-                        mustAskClarifyingQuestions: { type: "boolean" },
-                        requireApprovalGates: { type: "boolean" },
-                    },
-                    required: ["userPrompt"],
-                },
-            },
-            {
-                name: "score_frontend_prompt",
-                description: "Score a frontend prompt quality and suggest missing info / improvements.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        prompt: { type: "string" },
-                    },
-                    required: ["prompt"],
-                },
-            },
-        ],
-    };
-});
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    if (request.params.name === "scan_project") {
-        const rawArgs = (request.params.arguments ?? {});
-        const rootDir = asNonEmptyString(rawArgs.rootDir);
-        const maxDepth = typeof rawArgs.maxDepth === "number" ? rawArgs.maxDepth : undefined;
-        const maxEntries = typeof rawArgs.maxEntries === "number" ? rawArgs.maxEntries : undefined;
-        const result = await scanProject({ rootDir, maxDepth, maxEntries });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(result, null, 2),
-                },
-            ],
-        };
-    }
-    if (request.params.name === "optimize_frontend_prompt") {
-        const rawArgs = (request.params.arguments ?? {});
-        const userPrompt = asNonEmptyString(rawArgs.userPrompt);
-        if (!userPrompt) {
-            throw new Error("optimize_frontend_prompt: missing required argument 'userPrompt'");
-        }
-        const args = {
-            userPrompt,
-            projectContext: asNonEmptyString(rawArgs.projectContext),
-            techStack: asNonEmptyString(rawArgs.techStack),
-            framework: asNonEmptyString(rawArgs.framework),
-            language: asNonEmptyString(rawArgs.language) ?? undefined,
-            styling: asNonEmptyString(rawArgs.styling),
-            stateManagement: asNonEmptyString(rawArgs.stateManagement),
-            router: asNonEmptyString(rawArgs.router),
-            constraints: Array.isArray(rawArgs.constraints)
-                ? rawArgs.constraints.map((x) => String(x)).filter((x) => x.trim().length)
-                : undefined,
-            taskType: asNonEmptyString(rawArgs.taskType) ?? undefined,
-            outputLanguage: asNonEmptyString(rawArgs.outputLanguage) ?? undefined,
-            outputFormat: asNonEmptyString(rawArgs.outputFormat) ?? undefined,
-            codeStyle: asNonEmptyString(rawArgs.codeStyle) ?? undefined,
-            mustAskClarifyingQuestions: typeof rawArgs.mustAskClarifyingQuestions === "boolean" ? rawArgs.mustAskClarifyingQuestions : undefined,
-            requireApprovalGates: typeof rawArgs.requireApprovalGates === "boolean" ? rawArgs.requireApprovalGates : undefined,
-        };
-        const result = buildOptimizedPromptPackage(args);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(result, null, 2),
-                },
-            ],
-        };
-    }
-    if (request.params.name === "score_frontend_prompt") {
-        const rawArgs = (request.params.arguments ?? {});
-        const prompt = asNonEmptyString(rawArgs.prompt);
-        if (!prompt) {
-            throw new Error("score_frontend_prompt: missing required argument 'prompt'");
-        }
-        const result = scoreFrontendPrompt({ prompt });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(result, null, 2),
-                },
-            ],
-        };
-    }
-    throw new Error(`Unknown tool: ${request.params.name}`);
-});
-// 启动 Server
-const transport = new StdioServerTransport();
-await server.connect(transport);

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@jdzhang225gmail/fontend-prompt",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "bin": {
-    "fontend-prompt": "./dist/index.js",
-    "fontend-skill": "./dist/cli.js"
+    "fontend-prompt": "./dist/cli.js"
   },
   "files": [
     "dist",
@@ -17,11 +16,10 @@
   "scripts": {
     "dev": "tsx watch src/index.ts",
     "build": "tsc -p tsconfig.json",
-    "start": "node dist/index.js",
+    "start": "node dist/cli.js",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
     "cac": "^6.7.14",
     "npm": "^11.7.0"
   },