# @accordproject/template-engine 中文文档

规范地址：https://npmcn.com/package/%40accordproject/template-engine/

版本：5\.3\.0
npm 元数据更新时间：2026-10-19T20:26:27.786Z
中文译文更新时间：2026-11-06T09:23:33.962Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40accordproject/template-engine
原文对照：https://npmcn.com/package/%40accordproject/template-engine/?lang=original
项目主页：https://github.com/accordproject
源码仓库：https://github.com/accordproject/template-engine

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.6 MB，143 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：16 个
- peer 依赖：openai ^6\.42\.0，groq-sdk ^1\.3\.0，@google/genai ^2\.10\.0，@openrouter/sdk ^0\.13\.22，@anthropic-ai/sdk ^0\.100\.1，@mistralai/mistralai ^2\.4\.0
- 首次发布：2023-03-20T13:33:01.991Z
- 最新版本发布：2026-10-19T20:26:27.304Z
- 近 30 天下载量：3618（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 13 个）

## 中文简介

从模板Mark + JSON 数据生成协议马克

## 安装

```sh
npm install @accordproject/template-engine
```

也可以使用：`pnpm add @accordproject/template-engine`、`yarn add @accordproject/template-engine`、`bun add @accordproject/template-engine`

## README

# 模板引擎

这是 [协议项目](https://accordproject.org/) 模板引擎。 rich-text模板在TemplateMark中被定义(要么作为markdown文件,要么作为JSON文档),然后被与JSON数据合并生成出输出文件. 模板可能包含 [类型脚本](https://www.typescriptlang.org/) 表达.

## 资源

-   [获取开始视频](https://vimeo.com/manage/videos/845273411)
-   [模板播放场](https://playground.accordproject.org/)
-   [运行代码](https://replit.com/@dselman/AccordProjectTemplateEngine-Hello-World)

核心模板引擎是JSON到JSON的转换,将TemplateMark JSON +协议数据(JSON)转换为AccordMark JSON.

> 说明:使用 `@accordproject/markdown-transform` 项目将下标模板转换为模板Mark JSON并转换为输出格式(HTML,PDF,DOCX等). 用于命令行使用请使用 `@accordproject/template-cli`。 。 。 .

TemplateMark是一个描述丰富文本模板的文档对象模型,有嵌入式变量,有条件部分,公式等. TemplateMark使用嵌入式TypeScript表达式进行条件和计算.

> 模板马克和协议马克的格式使用 [音乐会](https://concerto.accordproject.org/) 数据建模语言.

在高层次上,模板引擎将模板Mark DOM转换为协议Mark DOM,评价有条件的节和公式的TypeScript表达式,并用所提供的协议数据的可变值来替换可变引用.

![Template Interpreter](https://npmcn.com/package/%40accordproject/template-engine/assets/template-interpreter.png)

## 执行管道概览

在内部,模板引擎通过结构化执行管道评价模板:

1.  **类型验证**  
    TemplateMark JSON文件和收到的协议数据根据各自的Concerto模型进行验证,以确保结构和类型正确.
    
2.  **类型脚本汇编**  
    嵌入式类型脚本表达式(如条件、条款和公式)使用 `TemplateMarkToJavaScriptCompiler`。 。 。 .
    
3.  **用户代码评价**  
    在协议生成过程中,使用 `JavaScriptEvaluator`。 。 。 .  
    评价员支持两项执行战略:
    
    -   `evalDangerously()` ——直接在当前进程内执行JavaScript. 这只应用于可信任的代码或沙盒环境中(如浏览器).
    -   `evalChildProcess()` ——执行JavaScript在一个孤立的Node.js子进程,以提高安全和隔离性,被推荐为服务器上不可信的模板内容.
4.  **协议马克生成**  
    TemplateMark文档被切换,评估值被插入到文档结构中,并生成了AccordMark JSON文档.
    
5.  **输出验证**  
    生成的协议马克文档在返回前被验证 .
    

这种分层结构确保类型安全、确定模板逻辑的执行以及运行时间评价期间的隔离.

## 你好,世界模板

让我们创造最简单的模板 想象,臭名昭著"你好世界"!

> 此测试的代码为: [https://github.com/accordproject/template-engine/blob/main/test/helloWorld.ts 页面存档备份,存于互联网档案馆](https://github.com/accordproject/template-engine/blob/main/test/HelloWorld.test.ts)

### 模板数据模型

首先在Concerto语法中创建模板数据模型. 数据模型定义了要与模板合并的数据的结构. 在这种情况下,模板模型包含一个属性 `message` 类型 `String`需要财产(不是 `optional`) (中文(简体) ).

```javascript
namespace helloworld@1.0.0

@template
concept TemplateData {
    o String message
}
```

### TemplateMark( 延长标记)

下一个定义模板的模板 Mark 。 这样的话,就是普通文字世界 `"Hello"` 后面是空格,然后是变量 `message` 接下来是 `"."`。 。 。 .

```markdown
Hello {{message}}.
```

> 请注意,在这种情况下,模板是使用扩展的标记下语法(富文本有嵌入变量等)定义的. 这个 `@accordproject/markdown-transform` 套件用于将标记降为模板Mark JSON,供模板引擎使用.

### 从数据生成协议马克( JSON)

定义一个 **实例** 会 议 日 程 和 议 程 `helloworld@1.0.0.TemplateData` 数据模型。 在此情况下,确定 `message` 属性到字符串“世界”.

```typescript
const data = {
    $class: 'helloworld@1.0.0.TemplateData',
    message: 'World',
};
```

### 产出协议马克(JSON)

当TemplateMark和数据JSON被传递到Template Engine上时,它就将两者合并起来,在这种情况下,只是简单地替换了引用 `message` 变量,并生成 AccordMark JSON 文档.

然后,可将本协议的Mark JSON文件转交给 `@accordproject/markdown-transform` 用于转换到下标、PDF、HTML的模块.

```json
{
    "$class": "org.accordproject.commonmark@0.5.0.Document",
    "xmlns": "http://commonmark.org/xml/1.0",
    "nodes": [
        {
        "$class": "org.accordproject.commonmark@0.5.0.Paragraph",
        "nodes": [
            {
            "$class": "org.accordproject.commonmark@0.5.0.Paragraph",
            "nodes": [
                {
                "$class": "org.accordproject.commonmark@0.5.0.Text",
                "text": "Hello "
                },
                {
                "$class": "org.accordproject.ciceromark@0.6.0.Variable",
                "value": "World",
                "name": "message",
                "elementType": "String"
                },
                {
                "$class": "org.accordproject.commonmark@0.5.0.Text",
                "text": "."
                }
            ]
            }
        ]
        }
    ]
}
```

## 下一步

"Hello World"的例子只是刮了可以完成的表面! TemplateMark可以定义可选部分,有条件部分,TypeScript公式/计算,甚至参考外部数据.

参见 [满](https://github.com/accordproject/template-engine/tree/main/test/templates/good/full) 详情请举出例子.

> 更详细的语法文档即将到来! 阅读现有文档: [https://docs.accordproject.org/docs/markup-templatemark.html 页面存档备份,存于互联网档案馆](https://docs.accordproject.org/docs/markup-templatemark.html)

## 为什么要创建新的模板引擎 ?

有许多巨大的开源模板引擎可用,例如 [胡子](https://mustache.github.io/), (中文(简体) ), [处理栏](https://handlebarsjs.com/) 或者说 [EJS (英语)](https://ejs.co/),那么为什么还要创造另一个呢?

### 1\. 输入和输出格式不可知论

大部分的模板引擎都是基本的 **基于文本** ——即将模板作为文本字符串,被颂"查找并替换"的机器. 这种方法在模板的输入格式(比如DOCX文件)和模板引擎的输出之间建立了耦合,在DOCX模板的情况下,模板引擎必须是DOCX文件. 这使得支持多种输入和输出格式变得困难.

Agree Project模板引擎会打破模板输入格式和引擎输出格式之间的耦合,将数据格式转换移出核心模板引擎. 引擎层面的模板为TemplateMark JSON文档,模板引擎的输出为AccordMark JSON文档. 单独的库用于将源模板转换为TemplateMark JSON,或者将AccordMark JSON转换为输出格式.

这种灵活性可以创建一个可被标记下模板,用于创建HTML,PDF或DOCX. 人们甚至可以想象使用DOCX模板来创建HTML或PDF文件,或其他情景.

### 2\. TemplateMark 作为定义格式

TemplateMark JSON是一个定义明确的文件格式,指可以创建强大的模板编辑器来定义它:包括用于定义条件区段的部件和用户经验,以及公式,并提供模板预览和综合测试. 我们认为,模板编辑比文字处理更接近编程.

我们鼓励这个领域的社区和商业创新!

### 3\. 充分逻辑支持

与一些禁止或尽量减少模板中逻辑的诱导系统不同,Accord Project模板完全包含可能包含复杂逻辑的模板:有条件的逻辑来决定要包含什么文本,甚至计算,例如根据抵押期限,金额和利率来计算抵押贷款的月付款.

### 4\. 类型安全

鉴于模板能够包含逻辑,必须确保模板 **保险** - 即当一个模板与结构良好的数据合并时,保证产生结构良好的输出.

太多的诱导引擎在运行时以不可预测的方式出故障,或者在提交数据时静悄悄地产生无效输出——这对企业的使用来说是不可接受的.

因此,项目模板 **强型**。模板中的逻辑用 [类型脚本](https://www.typescriptlang.org/). TypeScript是一种很强型的通用编程语言,由充满活力的开源和企业社区支持. TypeScript 编译为 JavaScript,以方便大多数平台的执行.

### 5\. 数据模型

带有模板变量的丰富文本与 [音乐会数据模型](https://concerto.accordproject.org/). Concerto数据模型定义了模板所需数据的结构,用于静态地编译模板并验证类型安全性,在运行时也用于确保所接入的数据结构完善.

### 6\. 汇编

模板可能被静态编译到TypeScript程序,强制进行类型安全,确保运行时不需要不安全的代码评价("eval"),并放宽对应用程序的整合.

模板编译器是一个单独的项目,在这里托管: [https://github.com/accordproject/template-compiller 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/accordproject/template-compiler)

## 安装

请注意,本模块主要针对工具作者,或开发者将模板引擎嵌入应用程序中. 关于命令行的使用,请参见 `@accordproject/template-cli` 软件包,可以执行一个完整的管道,将下调模板加上JSON数据转换为支持的输出格式,如HTML、DOCX或PDF.

```
npm install @accordproject/template-engine --save
```

要求节点.js >= 22.

## 浏览器使用量

软件包发布时有两个切入点:

-   `lib/index.js` ——节点js建设(`tsc` 输出,通过 `lib/index.d.ts`) (中文(简体) ).
-   `umd/template-engine.js` ——预建的UMD浏览器捆绑(参考: `browser` 字段,所以捆绑者会自动把它捡起来用于网页构建).

完全作者和运行的循环作品 **在浏览器中** 分析模板到模板Mark, 类型检查,将其嵌入式类型Script逻辑编译为JavaScript,并评价它——哪个 是什么权力 [模板播放场](https://playground.accordproject.org/)用于 方便的捆绑也再出口 `ModelManager` (音乐会)和 `TemplateMarkTransformer` 因此,一个单捆可以运行整个 `model -> template -> agreement` 流动 一个协奏曲实例:

```html
<script src="https://unpkg.com/@accordproject/template-engine/umd/template-engine.js"></script>
<script>
  const { ModelManager, TemplateMarkTransformer, TemplateMarkInterpreter } = window['template-engine'];
  const modelManager = new ModelManager();
  modelManager.addCTOModel('namespace test@1.0.0\n@template\nconcept TemplateData { o String name }');
  const templateMark = new TemplateMarkTransformer()
    .fromMarkdownTemplate({ content: 'Hello {{name}}!' }, modelManager, 'contract');
  const engine = new TemplateMarkInterpreter(modelManager, {});
  const agreement = await engine.generate(templateMark, { $class: 'test@1.0.0.TemplateData', name: 'World' });
</script>
```

关于浏览器限制的说明 :

-   进口的逻辑 **任意** 第三方包必须作为 **编译归档** (JavaScript逻辑,已捆绑的依赖性——由Node.js生产出离线). 在浏览器中, 源文件 (TypeScript logical) 根据一组固定的被支持的运行时间依赖性来编译.
-   `Template.fromDirectory()`编号 :`fromUrl()` 和子进程逻辑评价是仅节点 浏览器装入模板通过 `Template.fromArchive(buffer)` 并使用默认的流程评估器.

浏览器捆绑由 Playwright 测试在 `e2e/` 工作空间, 负载 `umd/template-engine.js` 变成无头铬并运行一个真正的 `generate()`。 。 。 .

## LLM 提供者

可选 [LLM 执行器](https://npmcn.com/package/%40accordproject/template-engine/docs/llm-executor.md) 通过官方与供应商交谈 SDKs (英语). 这些是 **可选同伴依赖关系** ——没有安装模板 因此,为您使用的每个供应商安装 SDK :

| 提供者 | 软件包 |
| --- | --- |
| `anthropic` | `@anthropic-ai/sdk` |
| `openai`, (中文(简体) ), `ollama`, (中文(简体) ), `openai-compatible` | `openai` |
| `groq` | `groq-sdk` |
| `google` | `@google/genai` |
| `mistral` | `@mistralai/mistralai` |
| `openrouter` | `@openrouter/sdk` |

```
npm install @anthropic-ai/sdk
```

在Node.js中,SDK在第一次使用时被包名加载. Bundlers (Vite, web package,.) 无法使用 解决该运行时间查询, 因此浏览器应用程序应该通过 `sdkLoaders` - 单字 `import()` 他们支持的每个提供者——所以他们的捆绑机包括SDK:

```ts
const processor = new TemplateArchiveProcessor(template, llmConfig, {
  anthropic: () => import('@anthropic-ai/sdk'),
  openai: () => import('openai'), // also used by `ollama` and `openai-compatible`
});
```

同样的装载器被接受 `new LLMExecutor(template, config, sdkLoaders)` 财务报告和审定财务报表 `createReasoner(providerConfig, sdkLoaders)`。 。 。 .

这个 `openai` SDK( 也由 `ollama` 财务报告和审定财务报表 `openai-compatible`)和 `@anthropic-ai/sdk` SDK 软件 拒绝在浏览器中运行, 除非提供者配置选择使用 `clientOptions: { dangerouslyAllowBrowser: true }`。只有当您接受 API 密钥时才会这样做 任何使用此页面的人都可以看到,例如,用户提供自己的密钥;否则就呼叫 服务器的提供者.

## 许可证

Accord Project源代码文件在位于LICENSE文件的Apache许可证2.0版本(Apache-2.0)下提供. 项目文件文件根据创用CC-BY-4.0国际许可证提供 [http://creativecommons.org/licenses/by/ 4.0/ 页面存档备份,存于互联网档案馆](http://creativecommons.org/licenses/by/4.0/)。 。 。 .

## 常见问题

### @accordproject/template-engine 是什么？

从模板Mark \+ JSON 数据生成协议马克

### 如何安装 @accordproject/template-engine？

在项目目录运行 npm install @accordproject/template-engine，或使用 pnpm add / yarn add / bun add。

### @accordproject/template-engine 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @accordproject/template-engine 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @accordproject/template-engine 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @accordproject/template-engine 可以商用吗？

@accordproject/template-engine 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @accordproject/template-engine 的下载量有多少？

根据 npm 官方下载统计，@accordproject/template-engine 在 2026/10/05 – 2026/11/03 这 30 天内被下载 3,618 次，日均约 121 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @accordproject/template-engine 还在维护吗？

最新版本 5\.3\.0 发布于 2026/10/20（18 天前）；至今共发布 56 个版本，其中过去 12 个月发布了 13 个；首次发布于 2023/03/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。