PromptScript：用TypeScript实现AI提示词工程化与团队协作

1. 项目概述与核心价值最近在折腾AI辅助编程工具链发现一个挺有意思的现象大家用Claude、Cursor、GitHub Copilot这些工具时往往都是临时起意在聊天框里敲一段指令然后祈祷模型能理解你的意图。这种“一次性”的提示词使用方式效率其实很低。同一个需求今天这么问明天那么问出来的代码风格、实现思路可能完全不同更别提在团队里统一规范了。这让我开始思考有没有一种方法能把我们和AI协作的“最佳实践”固化下来像管理代码一样去管理我们的提示词这就是我接触到PromptScript这个项目的契机。简单来说PromptScript 是一个用 TypeScript 写的开源工具它想解决的核心问题就是“提示词即代码”。它不是一个AI模型而是一个开发体验工具旨在为开发者特别是企业级团队提供一套编写、测试、复用和管理提示词的标准化框架。你可以把它想象成是专门为AI提示词设计的“Dockerfile”或“Kubernetes YAML”——通过声明式的脚本定义你与LLM交互的完整工作流包括输入、处理逻辑、输出格式甚至是多个模型调用之间的串联。对于日常重度依赖AI编程的开发者来说它的价值在于将零散、随机的提示词对话转变为可版本控制、可测试、可协作的工程化资产。无论是想为团队构建一套标准的代码审查提示词模板还是想创建一个复杂的、多步骤的代码生成流水线PromptScript 都提供了一个可靠的实现路径。接下来我就结合自己的实际踩坑和摸索带你彻底拆解这个工具看看它如何能实实在在地提升你的“人机协作”效率。2. 核心设计理念为什么是“提示词即代码”在深入具体操作之前我们必须先理解 PromptScript 背后的设计哲学。这不仅仅是又一个“提示词管理库”它引入的是一套完整的工程化思维。2.1 从临时对话到可编程工作流我们平时与Copilot或Claude的交互本质是一个黑盒输入一段自然语言得到一个结果。这个过程有幾個致命缺点不可重复微小的措辞变化可能导致输出天差地别难以稳定复现一个高质量结果。不可测试你无法像单元测试一样对一段提示词的输出进行断言和验证。难以协作你无法通过Git diff来审查队友对提示词的修改也无法进行有效的Code Review。缺乏组合性复杂的任务往往需要多轮对话或调用不同模型手动操作繁琐且易出错。PromptScript 的“脚本”概念正是为了解决这些问题。它将一次AI交互抽象为一个函数。这个函数有明确的输入参数、内部处理逻辑可能包含条件判断、循环、调用其他提示词函数和结构化的输出。这样一来提示词就从一段文本变成了一个可调用、可组合、可测试的程序单元。2.2 企业级治理与安全考量对于企业或稍大一点的团队“提示词治理”是一个现实需求。放任每个工程师随意向云端模型发送公司代码和业务数据存在数据泄露和成本失控的风险。PromptScript 在设计上考虑了这些“抗重力”因素——它帮助团队将AI能力“拉回”到可控的本地或私有化环境中进行编排。通过编写 PromptScript团队可以集中管理敏感信息将API密钥、模型端点等配置抽离避免硬编码在聊天记录里。标准化输出格式强制要求AI以JSON、YAML或特定代码格式返回便于下游系统集成。实现成本与用量监控因为每次调用都通过脚本发起可以方便地加入日志、计量和审计逻辑。构建内部知识库将经过验证的高效提示词脚本化并存入内部仓库形成团队的知识资产。这种设计使得AI能力不再是散兵游勇而是能够被集成到现有DevOps流程中的标准化服务。2.3 开发者体验优先作为一个给开发者用的工具PromptScript 选择了 TypeScript 作为实现语言这非常聪明。这意味着类型安全你可以为提示词的输入和输出定义TypeScript接口获得完美的IDE自动补全和类型检查。丰富的生态可以直接利用NPM上无数的工具库来处理字符串、调用HTTP接口、进行数据验证等。无缝集成可以轻松地将PromptScript脚本集成到现有的Node.js后端服务、CLI工具或构建流程中。它不是一个封闭的SaaS平台而是一个可以嵌入到你技术栈底层的开源库这种“低调”的定位反而赋予了它极大的灵活性。3. 环境准备与基础概念解析理论说再多不如上手试试。我们先从最基础的安装和核心概念开始。3.1 安装与初始化PromptScript 是一个Node.js库所以前提是你需要安装Node.js建议版本16。通过npm或yarn可以轻松安装# 在你的项目目录下 npm init -y npm install promptscript # 或者 yarn add promptscript安装完成后你不需要启动一个额外的服务。它就是一个库你可以在你的.js或.ts文件中直接导入使用。为了获得最好的开发体验我强烈建议在一个TypeScript项目中启用严格模式。3.2 核心构建块脚本、运行器与上下文理解PromptScript关键要搞懂三个核心概念它们的关系有点像拍电影脚本是剧本运行器是导演和剧组上下文是舞台和道具。脚本这是核心。一个脚本文件例如generate-code.ps.ts定义了一次或一组AI交互。它导出一个或多个异步函数函数内部使用PromptScript提供的DSL领域特定语言来描述与AI的对话。运行器这是执行引擎。你需要创建一个运行器实例并为其配置AI模型连接如OpenAI API、Anthropic Claude API或本地Ollama。运行器负责解析脚本、调用模型、管理对话状态。上下文这是数据容器。它贯穿整个脚本执行过程包含了输入参数、AI返回的中间结果、以及你自定义的变量。你可以从上下文中读取数据也可以写入数据供后续步骤使用。一个最简单的“Hello World”脚本长这样// hello.ps.ts import { prompt, script } from promptscript; export default script(async (context) { // 使用 prompt 函数定义要发送给AI的指令 const result await prompt请用JavaScript写一个函数返回“Hello, ${context.params.name}!”; // 将AI的结果存入上下文 context.set(greeting, result); return result; });执行这个脚本你需要创建一个运行器// runner.ts import { Runner } from promptscript; import helloScript from ./hello.ps.ts; async function main() { // 1. 创建运行器配置使用OpenAI的模型例如gpt-4 const runner new Runner({ provider: openai, apiKey: process.env.OPENAI_API_KEY, // 永远从环境变量读取密钥 model: gpt-4, }); // 2. 执行脚本并传入参数 const result await runner.run(helloScript, { params: { name: World } }); // 3. 获取输出 console.log(result); // 输出AI生成的代码 console.log(runner.context.get(greeting)); // 从上下文中读取存储的结果 } main().catch(console.error);实操心得一API密钥管理千万不要把apiKey硬编码在代码里务必使用环境变量.env文件配合dotenv库或秘密管理服务。这是安全红线。在团队项目中可以将运行器配置工厂化集中管理不同环境开发、测试、生产的模型配置。4. 编写你的第一个实用脚本代码审查机器人现在我们来点实际的。假设我们想为团队构建一个自动化的代码审查提示词它接收一段代码返回结构化的审查意见。用PromptScript实现你会感受到“提示词即代码”的威力。4.1 定义结构化输入与输出首先我们用TypeScript接口明确我们想要什么。这步至关重要它既是文档也是约束。// interfaces.ts // 输入要审查的代码及其元信息 export interface CodeReviewInput { code: string; language: javascript | typescript | python | go; purpose?: string; // 可选这段代码的意图 } // 输出结构化的审查结果 export interface CodeReviewIssue { type: BUG | SECURITY | PERFORMANCE | STYLE | MAINTAINABILITY; severity: LOW | MEDIUM | HIGH; line?: number; // 可选问题行号 description: string; suggestion: string; } export interface CodeReviewOutput { summary: string; // 总体评价 score: number; // 评分1-10分 issues: CodeReviewIssue[]; positiveAspects?: string[]; // 做得好的地方 }4.2 实现审查脚本接下来我们编写脚本。注意看我们如何将类型安全、逻辑判断和AI提示结合。// code-review.ps.ts import { prompt, script, conditional, log } from promptscript; import type { CodeReviewInput, CodeReviewOutput } from ./interfaces; export default script(async (context) { const { code, language, purpose } context.params as CodeReviewInput; // 1. 记录日志便于调试 log(开始审查${language}代码长度${code.length}字符); // 2. 构建动态提示词。根据是否有“目的”描述调整提示词。 const purposeContext purpose ? 这段代码的目的是${purpose}。 : ; const reviewPrompt 你是一个资深的${language}开发专家正在进行严格的代码审查。 ${purposeContext} 请仔细审查以下代码 \\\${language} ${code} \\\ 请从以下维度进行分析 1. **正确性与潜在缺陷**是否存在逻辑错误、边界条件处理不当、可能的运行时崩溃 2. **安全性**是否存在注入、敏感信息泄露、不安全的依赖或权限问题 3. **性能**是否存在低效算法、不必要的计算、内存泄漏风险 4. **代码风格与可读性**是否符合通用编码规范命名、注释、结构是否清晰 5. **可维护性**代码是否模块化耦合度是否过高是否有重复代码 **请严格按照以下JSON格式回复不要有任何额外的解释** { summary: 总体评价摘要, score: 1到10的整数评分, issues: [ { type: BUG|SECURITY|PERFORMANCE|STYLE|MAINTAINABILITY, severity: LOW|MEDIUM|HIGH, line: 可选行号, description: 问题描述, suggestion: 改进建议 } ], positiveAspects: [做得好的点1, 点2] } ; // 3. 调用AI模型并要求其以JSON格式解析结果 const aiResponse await prompt${reviewPrompt}.as(json); // 4. 结果验证与后处理 const reviewResult: CodeReviewOutput aiResponse; // 条件判断如果评分低于5分记录警告日志 await conditional(reviewResult.score 5, async () { log(⚠️ 代码审查评分较低建议重点修改); // 这里甚至可以扩展为发送通知到Slack等 }); // 5. 将最终结果存入上下文并返回 context.set(review, reviewResult); return reviewResult; });4.3 创建可执行的CLI工具为了让团队其他成员方便使用我们可以把它包装成一个CLI命令。// cli.ts #!/usr/bin/env node import { Runner } from promptscript; import { readFileSync } from fs; import codeReviewScript from ./code-review.ps.ts; async function runReview(codePath: string, language: string, purpose?: string) { const code readFileSync(codePath, utf-8); const runner new Runner({ provider: openai, apiKey: process.env.OPENAI_API_KEY!, model: gpt-4, temperature: 0.1, // 低温度让输出更确定、更专注于审查 }); try { const result await runner.run(codeReviewScript, { params: { code, language: language as any, purpose } }); // 漂亮地打印结果 console.log(\n 审查总结${result.summary}); console.log( 综合评分${result.score}/10\n); if (result.issues.length 0) { console.log(❌ 发现的问题); result.issues.forEach(issue { console.log( [${issue.type} - ${issue.severity}] ${issue.description}); console.log( 建议${issue.suggestion}\n); }); } if (result.positiveAspects result.positiveAspects.length 0) { console.log(✅ 做得好的地方); result.positiveAspects.forEach(aspect console.log( - ${aspect})); } } catch (error) { console.error(代码审查失败, error); process.exit(1); } } // 解析命令行参数 const args process.argv.slice(2); if (args.length 2) { console.log(用法node cli.js 代码文件路径 语言 [目的描述]); process.exit(1); } runReview(args[0], args[1], args[2]);然后在package.json中添加一个命令{ bin: { code-review: ./dist/cli.js }, scripts: { build: tsc, review: node ./dist/cli.js } }现在你的队友只需要在终端输入npx your-tool review ./myfile.js javascript 这是一个用户登录函数就能获得一份结构化的代码审查报告。实操心得二提示词设计是门艺术在编写reviewPrompt时我花了大量时间迭代。关键技巧角色设定明确告诉AI“你是什么专家”能显著提升输出质量。结构化输出强制要求JSON格式并给出精确的Schema描述能极大减少后续解析的麻烦。.as(json)方法会让PromptScript尝试自动解析。提供上下文purpose参数是可选的但提供后能让AI的审查更有针对性。控制“温度”在运行器配置中设置temperature: 0.1让模型输出更稳定、更可预测这对于审查、生成等任务非常重要。5. 进阶模式构建复杂多步骤工作流真正的威力在于组合。PromptScript 允许你将简单的脚本像乐高积木一样组装成复杂的工作流。假设我们要实现一个“智能代码重构助手”它先理解代码然后生成重构计划最后执行重构并生成测试用例。5.1 设计子脚本模块我们将任务拆解为三个独立的、可复用的脚本。// understand-code.ps.ts import { prompt, script } from promptscript; export default script(async (ctx) { const { code } ctx.params; const analysis await prompt 请分析以下代码的核心功能、数据结构、主要函数和外部依赖。 代码 \\\ ${code} \\\ 请用JSON格式输出包含summary, mainFunctions, dataStructures, dependencies。 .as(json); ctx.set(codeAnalysis, analysis); return analysis; }); // plan-refactor.ps.ts import { prompt, script } from promptscript; export default script(async (ctx) { const { code, analysis, goal } ctx.params; // goal: 如“提高性能”、“解耦” const plan await prompt 基于以下代码分析和重构目标制定一个详细的重构计划。 原始代码 \\\ ${code} \\\ 代码分析${JSON.stringify(analysis)} 重构目标${goal} 请输出一个JSON格式的重构计划包括refactoringSteps步骤数组 risks风险点 estimatedEffort预估工作量。 .as(json); ctx.set(refactorPlan, plan); return plan; }); // execute-refactor.ps.ts import { prompt, script, loop } from promptscript; export default script(async (ctx) { const { code, plan } ctx.params; let refactoredCode code; // 使用loop构造按计划步骤逐一执行重构 await loop(plan.refactoringSteps, async (step, index) { log(执行重构步骤 ${index 1}: ${step.description}); refactoredCode await prompt 请对以下代码执行重构操作${step.action} 当前代码 \\\ ${refactoredCode} \\\ 只输出重构后的完整代码不要解释。 ; ctx.set(step${index}_result, refactoredCode); }); // 最后基于重构后的代码生成测试 const testCode await prompt 为以下重构后的代码生成对应的单元测试使用Jest框架 \\\ ${refactoredCode} \\\ ; ctx.set(finalRefactoredCode, refactoredCode); ctx.set(generatedTests, testCode); return { refactoredCode, testCode }; });5.2 编排主工作流脚本现在我们创建一个主脚本按顺序调用这三个子脚本并传递上下文数据。// refactor-workflow.ps.ts import { script, sequence } from promptscript; import understandCode from ./understand-code.ps.ts; import planRefactor from ./plan-refactor.ps.ts; import executeRefactor from ./execute-refactor.ps.ts; export default script(async (context) { const { originalCode, refactorGoal } context.params; // 使用sequence构造顺序执行三个子脚本 const workflowResult await sequence( [ // 步骤1理解代码 async (ctx) { const analysis await ctx.run(understandCode, { params: { code: originalCode } }); return { analysis }; }, // 步骤2制定计划依赖上一步的analysis结果 async (ctx, prevResult) { const plan await ctx.run(planRefactor, { params: { code: originalCode, analysis: prevResult.analysis, goal: refactorGoal } }); return { plan }; }, // 步骤3执行重构依赖上一步的plan结果 async (ctx, prevResult) { const result await ctx.run(executeRefactor, { params: { code: originalCode, plan: prevResult.plan } }); return result; } ], { initialContext: context } // 共享主上下文 ); // workflowResult 包含了所有步骤的最终结果 context.merge(workflowResult); return { analysis: workflowResult.analysis, plan: workflowResult.plan, finalCode: workflowResult.refactoredCode, tests: workflowResult.testCode }; });这个refactor-workflow.ps.ts脚本清晰地定义了一个三步流水线数据像管道一样在步骤间传递。sequence和loop这样的控制流构造让复杂逻辑变得直观。实操心得三工作流调试技巧调试多步骤工作流时不要一次性跑完。利用log函数在每个关键步骤输出中间状态到控制台。PromptScript的上下文是持久化的你可以在任何步骤检查context.get()的内容。对于复杂的脚本我通常会先单独运行和调试每一个子脚本确保其输入输出符合预期再组装成完整工作流。此外为运行器配置一个较短的超时时间并在每一步做好错误捕获能避免因某个步骤卡死而浪费大量API调用费用。6. 集成与部署将PromptScript融入开发生命周期脚本写好了如何让它真正为团队所用这就需要把它集成到现有的开发流程中。6.1 与Git Hooks集成提交前自动审查我们可以利用Git的pre-commit钩子在代码提交前自动运行我们的代码审查脚本对暂存区的文件进行快速检查。#!/bin/bash # .git/hooks/pre-commit # 获取暂存区中所有.js和.ts文件 STAGED_FILES$(git diff --cached --name-only --diff-filterACM | grep -E \.(js|ts)$) if [ -n $STAGED_FILES ]; then echo 运行AI代码审查... for FILE in $STAGED_FILES do # 调用我们之前写的CLI工具 npx ts-node ./src/scripts/code-review-cli.ts $FILE typescript REVIEW_EXIT_CODE$? if [ $REVIEW_EXIT_CODE -ne 0 ]; then echo ❌ 文件 $FILE 审查未通过请根据提示修改。 exit 1 fi done echo ✅ AI代码审查通过。 fi exit 06.2 与CI/CD管道集成流水线中的质量关卡在GitLab CI、GitHub Actions或Jenkins中我们可以添加一个专门的“AI审查”阶段。# .github/workflows/ai-review.yml name: AI Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 - name: Install dependencies run: npm ci - name: Run AI Review on Changed Files env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} run: | # 获取PR中更改的文件 FILES$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- *.js *.ts *.py) for FILE in $FILES; do if [ -f $FILE ]; then LANGUAGEunknown case $FILE in *.js) LANGUAGEjavascript ;; *.ts) LANGUAGEtypescript ;; *.py) LANGUAGEpython ;; esac if [ $LANGUAGE ! unknown ]; then echo 审查文件: $FILE npm run review -- $FILE $LANGUAGE || echo 审查提示存在问题请人工复核。 fi fi done # 可选将审查结果以评论形式提交到PR - name: Comment on PR uses: actions/github-scriptv6 if: always() # 即使审查失败也评论 with: script: | // 这里可以读取上一步生成的审查报告调用GitHub API提交评论 github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: AI代码审查已完成。发现的问题已输出到日志。 });6.3 构建内部PromptScript仓库对于企业来说最终目标是建立一个内部的“提示词脚本库”。你可以创建一个独立的NPM包或者Git子模块来管理这些.ps.ts文件。prompt-scripts-repo/ ├── package.json ├── tsconfig.json ├── src/ │ ├── code-review/ │ │ ├── index.ps.ts # 主入口 │ │ ├── interfaces.ts │ │ └── cli.ts │ ├── refactor/ │ │ └── ... │ ├── document/ │ │ └── ... # 生成文档的脚本 │ └── utils/ │ └── ... # 公共工具函数如安全的上下文处理 └── templates/ # 可以存放一些脚本模板其他项目通过npm install your-company/prompt-scripts来引用实现提示词资产的跨项目复用和统一升级。实操心得四成本与性能优化在CI中大规模运行AI审查成本是必须考虑的问题。我的经验是缓存机制对于未更改的代码块可以计算其哈希值如果之前审查过且代码未变则跳过本次AI调用直接使用缓存结果。PromptScript的上下文可以配合外部存储如Redis实现这一点。模型选型非关键路径或简单审查可以使用更便宜、更快的模型如gpt-3.5-turbo。只在重要PR或复杂逻辑处使用gpt-4。超时与重试为运行器设置合理的超时如30秒并实现指数退避的重试逻辑以应对API的偶尔不稳定。采样审查在大型PR中不必审查所有文件可以按规则抽样或只审查改动行数最多的几个文件。7. 常见问题、排查与高级技巧在实际使用PromptScript构建生产级应用的过程中我踩过不少坑也总结了一些高级用法。7.1 常见问题速查表问题现象可能原因解决方案脚本执行时报Invalid provider运行器配置错误或provider字符串拼写错误。检查new Runner()中的provider选项确保是支持的值如openai,anthropic,ollama。AI返回结果无法解析为JSON提示词中要求了JSON格式但AI返回了额外文本或格式错误。1. 在提示词中更严格地要求“只输出JSON”。2. 使用.as(json)时PromptScript会尝试提取JSON如果失败检查原始响应aiResponse.raw进行调试。3. 使用temperature0并添加“Think step by step”指令提高输出稳定性。上下文数据在步骤间丢失可能错误地创建了新的、隔离的上下文而非共享上下文。在sequence或loop中确保通过{ initialContext: context }参数传递父上下文。在子脚本中使用context.set()和context.get()操作的是同一个上下文对象。API调用超时或频率限制网络问题或免费API密钥的速率限制。1. 增加运行器的timeout配置。2. 实现重试逻辑可使用retry库。3. 对于大批量任务在脚本中加入delay使用setTimeout包装。提示词脚本变得冗长难维护业务逻辑复杂所有提示词都写在一个文件里。遵循软件工程原则拆分。将大的脚本拆分成多个小的、单一职责的脚本文件通过import和ctx.run()组合。创建“工具脚本”库供复用。7.2 高级技巧动态提示词与函数调用PromptScript的真正强大之处在于你的提示词可以是动态生成的JavaScript字符串。// dynamic-prompt.ps.ts import { prompt, script } from promptscript; export default script(async (context) { const { userQuery, conversationHistory } context.params; // 基于历史记录动态构建系统指令 let systemMessage 你是一个有帮助的助手。; if (conversationHistory.length 10) { systemMessage 当前对话已较长请保持回复简洁。; } if (conversationHistory.some(msg msg.includes(代码))) { systemMessage 用户之前询问过代码问题请优先考虑提供代码示例。; } // 动态构建消息数组模拟Chat Completion格式 const messages [ { role: system, content: systemMessage }, ...conversationHistory.map(msg ({ role: user, content: msg })), { role: user, content: userQuery } ]; // 注意这里需要根据你使用的provider调整调用方式。 // 假设运行器支持直接传递消息数组 const response await prompt${JSON.stringify(messages)}.as(json); return response; });7.3 自定义模型与本地集成除了OpenAI和AnthropicPromptScript可以轻松集成本地模型比如通过Ollama。import { Runner } from promptscript; import myScript from ./my-script.ps.ts; const runner new Runner({ provider: custom, // 使用自定义provider async callModel(messages, options) { // 调用本地Ollama API const response await fetch(http://localhost:11434/api/generate, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ model: codellama:7b, prompt: messages[messages.length - 1].content, // 简单处理只取最后一条 stream: false }) }); const data await response.json(); return { content: data.response, // 可以在这里提取token用量等信息 usage: { total_tokens: 0 } // 本地模型可能不提供 }; } }); const result await runner.run(myScript, { params: { /* ... */ } });这种方式给了你极大的灵活性可以将任何兼容的AI API接入到PromptScript的框架中。8. 总结与个人体会折腾PromptScript这一套下来最大的感受是它把和AI协作从一种“艺术”或“运气”变成了一项可规划、可测量的“工程”。以前写提示词像是在黑暗中摸索现在则像是在编写一个有明确输入输出的函数心里踏实多了。对于个人开发者它能帮你沉淀那些经过无数次调试才打磨出来的“黄金提示词”避免重复劳动。对于团队它更是协作和治理的利器能让团队成员的AI使用水平快速拉齐并确保输出质量符合一定的标准。虽然初期需要投入一些学习成本来理解它的模式和编写脚本但长远来看这种投资在提升开发效率、保证代码质量和降低AI使用成本方面回报是显著的。最后一个小建议不要试图一开始就用它构建一个巨无霸工作流。从一个小的、具体的痛点开始比如我例子中的代码审查。先实现它用起来感受它带来的变化和可能的新问题然后再逐步扩展。工程化的道路本就是一步步迭代出来的。PromptScript提供的这套框架至少让我们在这条路上走得更稳、更快了。