Persona Prompt Compiler

面向 Vercel AI SDK / agent 工程 的上游 Prompt 编译器。

人格模块 + 世界规则 + 当前输入 → 编译成 Vercel AI SDK 可用的 system / prompt

安装

npm install persona-prompt-compiler

快速开始

import { createPersona, compilePrompt, file, inspectPrompt } from "persona-prompt-compiler";

// 1. 定义人格
type ZeroPersona = {
  "身份": string;
  "背景": string;
  "人格": string;
  "初始信息": string;
};

const zero = createPersona<ZeroPersona>({
  "身份": "./zero/identity.md",
  "背景": "./zero/background.md",
  "人格": "./zero/persona.md",
  "初始信息": "./zero/init.md",
});

// 2. 编译 prompt
const compiled = await compilePrompt({
  persona: zero,
  inherit: ["身份", "背景", "人格", "初始信息"],

  system: {
    "世界观": file("./world/base.md"),
    "剧情规则": file("./world/rules.md"),
  },

  input: [
    "根据当前剧情生成下一段 ADV 剧情。",
    file("./story/chapter-01.md"),
    {
      "好感": 70,
      "紧张度": 45,
      "当前场景": "废弃实验室",
    },
  ],
});

// 3. 调试查看
inspectPrompt(compiled);

// 4. 交给 Vercel AI SDK
import { generateText } from "ai";

const result = await generateText({
  model,
  system: compiled.system,
  prompt: compiled.prompt,
});

API

createPersona(modules)

定义一个人格对象。modules 的值为文件路径，每个 key 对应一个人格模块。

const zero = createPersona<ZeroPersona>({
  "身份": "./zero/identity.md",
  "背景": "./zero/background.md",
  "人格": "./zero/persona.md",
});

compilePrompt(options)

把人格、系统规则、当前输入编译成 { system, prompt, meta }。

type CompilePromptOptions<P> = {
  persona?: P;                          // 人格对象
  inherit?: readonly PersonaKey<P>[];   // 继承哪些模块（省略=全部，[]=不继承）
  system?: Record<string, PromptSource>; // 长期稳定内容（世界观、规则等）
  input?: InputItem | InputItem[];      // 本次任务、材料、状态
  cwd?: string;                         // 工作目录（默认 process.cwd()）
};

inherit 规则：

| 写法 | 语义 | |---|---| | 省略 | 继承全部人格模块 | | [] | 不继承任何人格模块 | | ["身份"] | 只继承指定模块 |

system 适合放： 世界观、剧情规则、项目规则、命名规范、长期写作风格、禁止事项

input 适合放： 本次任务、当前剧情文件、当前状态、用户选择、资源列表、临时上下文

input: [
  "生成下一段剧情。",                  // string → 内联文本
  file("./story/chapter-01.md"),       // FileRef → 读取文件内容
  { "好感": 70, "当前场景": "实验室" }, // Record → JSON 数据块
]

file(path)

显式声明某个值是文件路径。用于 system 和 input 中的文件引用。

file("./world/base.md")   // → { kind: "file", path: "./world/base.md" }

inspectPrompt(compiled)

控制台打印编译结果的结构摘要，方便调试。

Persona:
  - 身份
  - 背景
  - 人格

System:
  - 世界观
  - 剧情规则

Input:
  - inline: 根据当前剧情生成下一段 ADV 剧情。
  - file: ./story/chapter-01.md
  - data: 好感, 紧张度, 当前场景

编译输出结构

system

# Persona

## 身份
<identity.md 内容>

## 背景
<background.md 内容>

# System

## 世界观
<world/base.md 内容>

## 剧情规则
<world/rules.md 内容>

prompt

# Input

根据当前剧情生成下一段 ADV 剧情。

## File: ./story/chapter-01.md

<文件内容>

## Data

```json
{
  "好感": 70,
  "当前场景": "废弃实验室"
}

## 与 Vercel AI SDK 配合

### 普通生成

```ts
const compiled = await compilePrompt({ persona, system, input });

const result = await generateText({
  model,
  system: compiled.system,
  prompt: compiled.prompt,
});

结构化输出

const result = await generateText({
  model,
  system: compiled.system,
  prompt: compiled.prompt,
  output: Output.object({ schema: StoryChunkSchema }),
});

Agent（带 tools）

const result = await generateText({
  model,
  system: compiled.system,
  prompt: compiled.prompt,
  tools: { listBackgroundAssets, updateSceneBackground },
  output: Output.object({ schema: BgSelectionSchema }),
});

边界

这个库负责：

• ✅ 编译 system / prompt
• ✅ 读取 md / txt / json 文件
• ✅ 继承 persona 模块
• ✅ 记录 meta 信息

这个库不负责（交给 Vercel AI SDK / Mastra / LangGraph）：

• ❌ 模型调用
• ❌ stream / tools / agent loop
• ❌ workflow / memory / RAG
• ❌ structured output / JSON schema 校验

License

MIT