@carllee1983/prompt工具包

MCP的快速存储库治理工具包

](https://github.com/CarlLee1983/prompts-tooling-sdk) ![Production Ready](https://github.com/CarlLee1983/prompts-tooling-sdk) ![License](LICENSE) ![TypeScript](https://www.typescriptlang.org/) ](https://nodejs.org/)

📋 引言

@carllee1983/prompt-toolkit 是一个 生产准备就绪 TypeScript工具包，用于验证和管理与模型上下文协议（MCP）一起使用的提示存储库。它为注册表文件、提示定义和部分目录提供了全面的验证，确保了提示存储库的完整性和正确性。

版本1.0.0 使用API稳定性保证标记稳定发布。从1.0.0开始，该工具包遵循语义版本控制，并在主要版本中保持向后兼容性。

✨ 特性

注册表验证：验证 registry.yaml 构造并确保所有引用的文件都存在
提示文件验证：根据架构定义验证单个提示YAML文件
部分验证：验证partials目录结构和文件是否存在
部分使用验证：检测模板中缺失的部分和循环依赖关系
存储库验证：验证所有组件的完整存储库验证工作流
类型安全：完全支持TypeScript和类型定义
架构验证：基于Zod的模式验证，用于健壮的类型检查
代码质量：ESLint配置，自动格式化
Git挂钩：用于自动修复棉绒的预提交挂钩
综合测试：88个全面覆盖的单元测试
生产就绪：具有语义版本控制保证的稳定API
API稳定性：主要版本内的向后兼容性

🚀 安装

作为一种依赖

# Using npm
npm install @carllee1983/prompt-toolkit

# Using pnpm
pnpm add @carllee1983/prompt-toolkit

# Using yarn
yarn add @carllee1983/prompt-toolkit

全局安装（CLI）

# Using npm
npm install -g @carllee1983/prompt-toolkit

# Using pnpm
pnpm add -g @carllee1983/prompt-toolkit

# Using yarn
yarn global add @carllee1983/prompt-toolkit

使用npx（无需安装）

# Run commands directly without installation
npx @carllee1983/prompt-toolkit validate repo

⚡ 快速入门（5分钟）

只需5分钟即可开始使用提示工具包！

步骤1：安装

npm install -g @carllee1983/prompt-toolkit

步骤2：导航到您的存储库

cd /path/to/your/prompt-repository

步骤3：验证

prompt-toolkit validate repo

步骤4：检查结果

成功：

✅ Repository validation passed!
Summary: 0 fatal(s), 0 error(s), 0 warning(s), 0 info(s)

发现错误： 该工具包将向您展示：

哪些文件有错误
错误代码和严重级别
解决问题的有用提示
文件位置

后续步骤

📖 阅读使用指南有关详细命令
🔍 探索错误代码了解验证结果
📚 结账例子适用于现实世界场景
🤝 了解与MCP提示管理器集成

💡 用例

CI/CD集成

在部署之前，验证CI/CD管道中的提示存储库以确保质量：

# .github/workflows/validate-prompts.yml
- name: Validate prompts
  run: prompt-toolkit validate repo --exit-code --severity error

看 CI/CD集成示例完整的工作流程。

地方发展

在开发过程中验证提示，以便及早发现错误：

# Watch mode (if implemented)
prompt-toolkit validate repo --watch

# Validate before commit
prompt-toolkit validate repo --exit-code

团队协作

确保所有团队成员遵循相同的提示结构：

# Validate and share results
prompt-toolkit validate repo --format json --output validation-results.json

自动化监控

与监控系统集成以跟踪存储库运行状况：

import { validatePromptRepo } from '@carllee1983/prompt-toolkit'

const result = validatePromptRepo('./prompts')
if (!result.passed) {
  // Send alert to monitoring system
  sendAlert(result.summary)
}

看集成示例更多场景。

📖 用法

CLI使用情况

该软件包包括一个CLI工具，用于从命令行验证和管理提示存储库。

安装

安装软件包后，CLI可用作 prompt-toolkit:

# Using npx (no installation needed)
npx @carllee1983/prompt-toolkit --help

# Or install globally
npm install -g @carllee1983/prompt-toolkit
prompt-toolkit --help

CLI命令

验证命令：

# Validate entire repository
prompt-toolkit validate repo [path]

# Validate registry.yaml
prompt-toolkit validate registry [path] --repo-root 

# Validate a single prompt file
prompt-toolkit validate file 

# Validate partials directory
prompt-toolkit validate partials [path] --partials-path

检查命令：

# Check partials usage (missing partials and circular dependencies)
prompt-toolkit check partials [path]

列出命令：

# List all prompts
prompt-toolkit list prompts [path] [--group ] [--enabled-only]

# List all groups
prompt-toolkit list groups [path] [--enabled-only]

统计数据：

# Show repository statistics
prompt-toolkit stats [path]

输出选项：

--format -输出格式（默认：文本）
--output -将输出写入文件
--exit-code -验证失败时以非零代码退出
--severity -要显示的最低严重级别（默认值：错误）

示例：

# Validate repository with JSON output
prompt-toolkit validate repo --format json

# Validate with severity filtering (show warnings and errors)
prompt-toolkit validate repo --severity warning

# Check partials and save results to file
prompt-toolkit check partials --format json --output results.json

# List all enabled prompts
prompt-toolkit list prompts --enabled-only

# Show statistics in JSON format
prompt-toolkit stats --format json

程序化使用

API稳定性

从1.0.0版本开始，所有公共API都是 稳定的 并遵循语义版本控制：

1.x.x：向后兼容-无中断更改
2.0.0+：重大变化（附迁移指南）

看 API稳定性文件了解详情。

从0.4.x迁移

从0.4.x升级到1.0.0需要 无代码更改 -API是完全向后兼容的。看迁移指南了解详情。

基础示例

import { validatePromptRepo } from '@carllee1983/prompt-toolkit'

// Validate entire repository
const result = validatePromptRepo('/path/to/prompt-repo')

if (result.passed) {
  console.log('Repository validation passed!')
  console.log('Summary:', result.summary)
} else {
  console.error('Validation errors:', result.errors)
  console.error('Summary:', result.summary)
}

验证注册表

import { validateRegistry } from '@carllee1983/prompt-toolkit'

const result = validateRegistry('/path/to/registry.yaml', '/path/to/repo-root')

if (result.success) {
  console.log('Registry is valid:', result.data)
} else {
  console.error('Registry validation failed:', result.error)
}

验证提示文件

import { validatePromptFile } from '@carllee1983/prompt-toolkit'

const result = validatePromptFile('/path/to/prompt.yaml')

if (result.success) {
  console.log('Prompt is valid:', result.data)
} else {
  console.error('Prompt validation failed:', result.error)
}

验证片段

import { validatePartials } from '@carllee1983/prompt-toolkit'

// Returns array of partial file paths, or empty array if partialPath is undefined
const partials = validatePartials('/path/to/repo-root', 'partials')

console.log('Found partials:', partials)

🔗 与MCP提示管理器集成

此工具包旨在与 MCP提示管理器.

工作流程

开发提示：在存储库中创建和编辑提示
本地验证：在提交之前使用此工具包进行验证

   prompt-toolkit validate repo

CI/CD验证：在CI/CD管道中自动验证
部署到MCP提示管理器：MCP提示管理器加载经过验证的提示

最佳实践

在推送到存储库之前验证提示
使用CI/CD自动捕获验证错误
监控验证结果以维护存储库运行状况
使用严重性过滤来关注关键问题

看集成示例查看详细的集成代码。

📚 api参考

`validatePromptRepo(repoRoot: string)`

验证整个提示存储库，包括注册表、所有提示文件和部分。

参数：

退货：

{
  passed: boolean
  errors: ToolkitError[]
  summary: {
    fatal: number
    error: number
    warning: number
    info: number
  }
}

`validateRegistry(registryPath: string, repoRoot: string)`

验证register.yaml文件结构，并确保所有引用的组和提示都存在。

参数：

registryPath：注册表.yaml文件的路径
repoRoot：存储库根目录的路径

退货：

ZodSafeParseReturnType

投掷：

Error 如果组文件夹或提示文件丢失

`validatePromptFile(filePath: string)`

根据提示模式验证单个提示YAML文件。

参数：

filePath：提示符YAML文件的路径

退货：

ZodSafeParseReturnType

`validatePartials(repoRoot: string, partialPath?: string)`

验证并返回指定目录中的所有部分文件。

参数：

repoRoot：存储库根目录的路径
partialPath：partials目录的可选路径（相对于repoRoot）

退货：

string[] // Array of file paths

投掷：

Error 如果partials文件夹不存在（当提供partialPath时）

🔍 错误代码和严重性

严重程度级别

该工具包使用四个严重性级别对验证错误进行分类：

fatal：阻止验证继续进行的关键错误。CLI将以代码1退出。
error：应修复的验证失败。默认的最低严重性级别。
warning：应审查的非关键问题。
info：信息消息和状态更新。

错误代码结构

所有错误代码都遵循以下模式： MODULE_PROBLEM_DESCRIPTION （例如。， REGISTRY_FILE_NOT_FOUND).

错误代码类别

注册表错误(`REGISTRY_*`)

REGISTRY_FILE_NOT_FOUND （致命）-注册表文件不存在
REGISTRY_SCHEMA_INVALID （错误）-注册表架构验证失败
REGISTRY_GROUP_NOT_FOUND （错误）-找不到组文件夹
REGISTRY_PROMPT_NOT_FOUND （错误）-未找到提示文件
REGISTRY_DISABLED_GROUP （信息）-组已禁用

提示错误(`PROMPT_*`)

PROMPT_SCHEMA_INVALID （错误）-提示架构验证失败
PROMPT_ID_DUPLICATED （错误）-提示ID重复
PROMPT_ARG_INVALID （错误）-提示参数验证失败
PROMPT_TEMPLATE_EMPTY （错误）-提示模板为空

部分错误(`PARTIAL_*`)

PARTIAL_NOT_FOUND （错误）-未找到部分文件
PARTIAL_UNUSED （警告）-部分文件已定义但未使用
PARTIAL_CIRCULAR_DEPENDENCY （错误）-检测到循环依赖关系
PARTIAL_PATH_INVALID （错误）-部分路径无效

存储库错误(`REPO_*`)

REPO_ROOT_NOT_FOUND （致命）-未找到存储库根路径
REPO_STRUCTURE_INVALID （错误）-存储库结构无效

文件错误(`FILE_*`)

FILE_READ_FAILED （致命）-读取文件失败
FILE_NOT_YAML （错误）-文件不是有效的YAML文件

CLI错误(`CLI_*`)

CLI_INVALID_ARGUMENT （致命）-CLI参数无效
CLI_UNKNOWN_COMMAND （致命）-未知CLI命令

错误对象结构

interface ToolkitError {
  code: string           // Error code (e.g., 'REGISTRY_FILE_NOT_FOUND')
  severity: Severity     // 'fatal' | 'error' | 'warning' | 'info'
  message: string        // Human-readable error message
  file?: string          // File path where error occurred
  hint?: string          // Helpful hint for resolving the error
  meta?: Record  // Additional error metadata
}

JSON输出示例

{
  "passed": false,
  "errors": [
    {
      "code": "REGISTRY_FILE_NOT_FOUND",
      "severity": "fatal",
      "message": "Registry file not found: /path/to/registry.yaml",
      "file": "/path/to/registry.yaml",
      "hint": "Ensure the registry.yaml file exists in the repository root",
      "meta": {
        "expectedPath": "/path/to/registry.yaml"
      }
    }
  ],
  "summary": {
    "fatal": 1,
    "error": 0,
    "warning": 0,
    "info": 0
  }
}

📝 模式定义

注册表架构

interface RegistryDefinition {
  version: number
  globals?: Record
  partials?: {
    enabled: boolean
    path: string
  }
  groups: Record
}

interface RegistryGroup {
  path: string
  enabled: boolean
  prompts: string[]
}

提示架构

interface PromptDefinition {
  id: string
  title: string
  description: string
  args: Record
  template: string
}

interface PromptArg {
  type: 'string' | 'number' | 'boolean' | 'object'
  description?: string
  required?: boolean
  default?: unknown
}

🧪 测试

# Run tests
pnpm test

# Run tests in watch mode
pnpm test

# Run tests once
pnpm test:run

# Generate coverage report (local development)
pnpm test:coverage

# Generate coverage report with thresholds (CI mode)
pnpm test:coverage:ci

# Generate coverage report and open HTML report
pnpm test:coverage:view

测试覆盖率

该项目通过以下阈值的全面测试覆盖率来保持高代码质量：

声明: ≥ 80%
线条: ≥ 75%
函数: ≥ 75%
分支: ≥ 70%

查看覆盖率报告

地方发展：运行 pnpm test:coverage:view 在浏览器中生成并自动打开HTML覆盖率报告。

CI/CD：覆盖率报告在CI中自动生成，并作为工件上传。您可以从GitHub Actions工作流运行中下载它们：

- 转到存储库中的“操作”选项卡 - 选择工作流运行 - 下载 coverage-reports 人工制品 - 提取并打开 coverage/index.html 在浏览器中

覆盖阈值：如果不满足覆盖阈值，CI管道将失败，确保在合并或发布之前保持代码质量标准。

🛠️ 发展

# Install dependencies
pnpm install

# Build the project
pnpm build

# Build in watch mode
pnpm dev

# Run linter
pnpm lint

# Auto-fix linting issues
pnpm lint:fix

🔧 代码质量

本项目使用ESLint来保证代码质量和一致性：

ESLint配置：现代平面配置格式（ESLint 9+）
TypeScript支持：完整的TypeScript linting @typescript-eslint
代码的风格：不强制使用分号、单引号和其他项目约定
预提交钩子：自动运行 lint:fix 每次使用Husky提交之前

预提交钩子

该项目包含一个预提交钩子，可以自动执行以下操作：

在提交之前对所有文件运行ESLint修复程序
将固定文件添加回暂存区
在提交之前确保代码质量

这是在您运行时自动设置的 pnpm install （通过 prepare 脚本）。

❓ 常见问题（FAQ）

常见问题

Q：什么是提示存储库？\ A：提示存储库是按组组织的提示模板的结构化集合，与模型上下文协议（MCP）系统一起使用。

Q：我需要全局安装吗？\ A：不，你可以用 npx @carllee1983/prompt-toolkit 无需安装，或将其作为项目依赖项安装。

Q：我可以在TypeScript中使用它吗？\ A：是的！该包包含完整的TypeScript类型定义。看 TypeScript示例关于使用模式。

验证问题

Q：如果验证失败怎么办？\ A： CLI将显示详细的错误信息，包括错误代码、严重级别、文件位置和提示。使用 --exit-code 使CI/CD管道在错误时失败。

Q：我可以按严重程度过滤错误吗？\ A：是的！使用 --severity 选项： prompt-toolkit validate repo --severity warning 显示警告和错误。

Q：如何验证多个存储库？\ A：在脚本中使用编程API。看批量验证示例.

错误处理

Q：致命、错误、警告和信息之间有什么区别？\ A.

致命的：阻止验证的关键错误（例如，缺少注册表文件）
错误：应修复的验证失败
警告：需要审查的非关键问题
信息：信息性消息

Q：如何处理特定的错误代码？\ A：使用 ERROR_CODE_CONSTANTS 并按代码过滤错误。看错误代码检查器示例.

CI/CD问题

Q：如何将其集成到GitHub Actions中？\ A：请参阅完整的工作流程。

Q：我可以获得JSON输出进行解析吗？\ A：是的！使用 --format json 要获得机器可读的输出： prompt-toolkit validate repo --format json.

Q：如何在验证错误时使CI失败？\ A：使用 --exit-code 标志： prompt-toolkit validate repo --exit-code.

故障排除

Q： “找不到注册表文件”错误\ A：确保 registry.yaml 存在于存储库根目录中。检查您正在验证的路径。

Q： “部分未找到”错误\ A：检查partials目录中是否存在部分文件，以及模板中的路径是否正确。

Q： “循环依赖”错误\ A：部分在循环中相互引用。检查你的部分依赖关系，打破循环。

有关更多故障排除帮助，请参阅故障排除指南.

🔧 故障排除

常见问题

找不到注册表文件

错误: REGISTRY_FILE_NOT_FOUND （致命）

解决方案:

确保 registry.yaml 存在于存储库根目录中
检查路径： prompt-toolkit validate repo /correct/path
验证文件权限

YAML语法无效

错误: FILE_NOT_YAML （错误）

解决方案:

使用在线YAML验证器验证YAML语法
检查缩进问题（YAML对空格敏感）
确保不使用制表符（使用空格代替）

失踪的游击队

错误: PARTIAL_NOT_FOUND （错误）

解决方案:

验证部分文件是否存在于 partials/ 目录
检查模板中的部分路径（例如。， {{> partial-name}})
确保partials目录路径正确 registry.yaml

循环依赖

错误: PARTIAL_CIRCULAR_DEPENDENCY （错误）

解决方案:

查看部分依赖关系
通过重组部分股权打破循环参考
使用错误 meta.chain 查看依赖循环

架构验证错误

错误: PROMPT_SCHEMA_INVALID 或 REGISTRY_SCHEMA_INVALID （错误）

解决方案:

检查模式定义章节
确保所有必填字段都存在
验证字段类型是否与架构匹配

获取帮助

📖 检查文档详细用法
🔍 审查错误代码错误含义
💡 看例子关于使用模式
🐛 打开一个问题如果你发现一个bug
💬 检查常见问题解答常见问题解答

📚 其他文件

API稳定性：API稳定性保证和版本控制策略
迁移指南：从0.4.x升级到1.0.0的指南
用例：真实世界的使用场景和示例
最佳实践：推荐的模式和做法
快速参考：快速命令和API参考
故障排除：常见问题和解决方案

📦 项目结构

prompts-tooling-sdk/
├── src/
│   ├── index.ts              # Main entry point
│   ├── validators/           # Validation functions
│   │   ├── validateRepo.ts
│   │   ├── validateRegistry.ts
│   │   ├── validatePromptFile.ts
│   │   ├── validatePartials.ts
│   │   └── validatePartialsUsage.ts
│   ├── partials/             # Partials utilities
│   │   ├── extractPartials.ts
│   │   ├── resolvePartialPath.ts
│   │   ├── buildPartialGraph.ts
│   │   └── detectCircular.ts
│   ├── schema/               # Zod schemas
│   │   ├── registry.schema.ts
│   │   └── prompt.schema.ts
│   ├── types/                # TypeScript type definitions
│   │   ├── registry.ts
│   │   └── prompt.ts
│   └── utils/                # Utility functions
│       ├── loadYaml.ts
│       └── walkDir.ts
├── test/                     # Test files
├── .husky/                   # Git hooks (pre-commit)
├── dist/                     # Build output
├── eslint.config.mjs         # ESLint configuration
└── package.json

📄 许可证

国际协调委员会

👤 作者

卡尔李1983

🤝 贡献

欢迎投稿！请随时提交拉取请求。

请阅读我们的贡献指南有关我们的行为准则和提交pull请求流程的详细信息。

📝 更新日志

\[0.4.0\]-错误代码和严重性系统

添加

具有标准化错误代码的综合错误代码系统
四级严重性系统：致命、错误、警告、信息
错误代码类别：注册表、PROMPT、PARTIAL、REPO、FILE、CLI
hint 错误对象中的字段有助于解决问题
meta 错误对象中用于附加错误元数据的字段
统计摘要 validatePromptRepo 结果（致命、错误、警告、信息计数）
命令行界面 --severity 按最低严重级别过滤错误的选项
致命错误处理总是导致CLI退出并返回代码1
使用颜色编码的严重级别增强错误格式（致命使用红色背景）
错误代码常量(ERROR_CODE_CONSTANTS)用于类型安全

改变

突发: Severity 类型已更改 'error' | 'warning' | 'info' | 'debug' 到 'fatal' | 'error' | 'warning' | 'info'
突发: ToolkitError 接口： details 字段重命名为 meta，添加 hint 领域
突发: validatePromptRepo 返回类型现在包括 summary 领域
为保持一致性而重命名的错误代码：

- PARTIAL_MISSING → PARTIAL_NOT_FOUND - PARTIAL_CIRCULAR → PARTIAL_CIRCULAR_DEPENDENCY - PARTIALS_FOLDER_NOT_FOUND → PARTIAL_PATH_INVALID

所有验证器现在都返回 ToolkitError[] 而不是抛出ZodError
loadYaml 现在投掷 ToolkitError 而不是原始错误
更新CLI命令以支持新的严重性系统

固定的

改进了文件操作中的错误处理
带有上下文提示的更好的错误消息
所有验证器的一致错误结构

\[0.3.1\]-CI/CD增强

添加GitHub操作CI工作流
自动化棉绒、测试和构建检查
提高开发工作流程的可靠性
合并前确保代码质量

\[0.3.0\]-CLI工具发布

添加了具有命令行界面的全面CLI工具
实现了验证命令（repo、注册表、文件、部分）
已实现的检查命令（部分使用）
已实现的列表命令（提示、组）
实现了用于存储库统计的stats命令
支持文本和JSON输出格式
彩色终端输出，带有加载动画
支持输出到文件和退出代码控制
添加了CLI文档和使用示例

\[0.2.0\]-代码质量和局部增强

添加了支持TypeScript的ESLint配置
为Husky添加了预提交挂钩，用于自动修复棉绒
添加了部分使用验证（缺少部分和循环依赖关系）
通过部分使用情况检查增强存储库验证
通过显式错误类型提高了类型安全性
为部分功能添加了全面的单元测试（总共82个测试）
添加了带有验证、检查、列表和统计命令的CLI工具
支持文本和JSON输出格式
已将包名称更新为 @carllee1983/prompt-toolkit

\[0.1.0\]-初始版本

提示工具sdk的初始版本
注册表验证功能
提示文件验证功能
Partials目录验证功能
完整的存储库验证工作流程
YAML加载和目录扫描实用程序
综合单元测试套件（28个测试用例）
TypeScript项目配置和构建设置

MCP Prompt Toolkit

快速接入

详细介绍

@carllee1983/prompt工具包

📋 引言

✨ 特性

🚀 安装

作为一种依赖

全局安装（CLI）

使用npx（无需安装）

⚡ 快速入门（5分钟）

步骤1：安装

步骤2：导航到您的存储库

步骤3：验证

步骤4：检查结果

后续步骤

💡 用例

CI/CD集成

地方发展

团队协作

自动化监控

📖 用法

CLI使用情况

安装

CLI命令

程序化使用

API稳定性

从0.4.x迁移

基础示例

验证注册表

验证提示文件

验证片段

更多示例

🔗 与MCP提示管理器集成

工作流程

最佳实践

📚 api参考

validatePromptRepo(repoRoot: string)

validateRegistry(registryPath: string, repoRoot: string)

validatePromptFile(filePath: string)

validatePartials(repoRoot: string, partialPath?: string)

🔍 错误代码和严重性

严重程度级别

错误代码结构

错误代码类别

注册表错误(REGISTRY_*)

提示错误(PROMPT_*)

部分错误(PARTIAL_*)

存储库错误(REPO_*)

文件错误(FILE_*)

CLI错误(CLI_*)

错误对象结构

JSON输出示例

📝 模式定义

注册表架构

提示架构

🧪 测试

测试覆盖率

查看覆盖率报告

🛠️ 发展

🔧 代码质量

预提交钩子

❓ 常见问题（FAQ）

常见问题

验证问题

错误处理

CI/CD问题

故障排除

🔧 故障排除

常见问题

找不到注册表文件

YAML语法无效

失踪的游击队

循环依赖

架构验证错误

获取帮助

📚 其他文件

📦 项目结构

📄 许可证

👤 作者

`validatePromptRepo(repoRoot: string)`

`validateRegistry(registryPath: string, repoRoot: string)`

`validatePromptFile(filePath: string)`

`validatePartials(repoRoot: string, partialPath?: string)`

注册表错误(`REGISTRY_*`)

提示错误(`PROMPT_*`)

部分错误(`PARTIAL_*`)

存储库错误(`REPO_*`)

文件错误(`FILE_*`)

CLI错误(`CLI_*`)