agentic-persona

agentic-persona

快速入门 · API 和命令 · 软件包

agentic-persona 是一款开源的角色档案和文本检查工具包，供构建 AI 内容工作流的开发者使用。 它会检查指定的语气短语、禁用短语和披露文本。 它的 Node.js 库、CLI 和模型上下文协议（MCP）服务还可构建图像、视频和说明文字的提示词字符串。

安装

npm install agentic-persona

需要 Node.js 18 或更高版本。包含 TypeScript 声明和两个运行时依赖项。

检查你的第一条说明文字

安装后，将此示例保存为 check-persona.mjs。运行 node check-persona.mjs。 无需 API 密钥、环境变量或加载 .env。

import { definePersona, consistencyCheck, promptPack } from 'agentic-persona';

const persona = definePersona({
  name: 'Ari', handle: '@ari', niche: 'sustainable fashion',
  voiceRules: ['warm', 'practical'], bannedPhrases: ['guaranteed'],
  disclosureLine: 'Created with AI assistance.',
  visualStyle: 'sunlit editorial portrait', voiceStyle: 'calm and conversational'
});
console.log(consistencyCheck(persona,
  'A warm, practical tip. Created with AI assistance.'));
console.log(promptPack(persona, 'repairing denim'));

检查结果会输出 score: 100、空标记，以及 missingDisclosure: false。 提示词包包含 imagePrompt、videoPrompt 和 captionPrompt。它生成的是文本，而非媒体资源。

工作原理

Profile -> validate and freeze -> persona
                                    |
                      +-------------+--------------+
                      |                            |
              caption substring checks     topic prompt templates
                      |                            |
              score and flags               image/video/caption strings

存在的意义

档案可以将身份字段和披露说明集中管理，以便在不同内容工作流中保持一致。 textlint 支持通用文本规则。Promptfoo 用于测试提示词和 AI 系统。 此软件包提供一个精简的本地档案检查器和固定提示词模板，无需调用模型。

对比

于 2026-10-14 根据 textlint 的源代码和 Promptfoo 的源代码进行核对。 这些工具可用于内容检查或提示词评估，适用范围各不相同。

范围	agentic-persona	textlint	Promptfoo
主要任务	角色档案和子字符串检查	自然语言 lint	提示词和 AI 系统评估
配置	档案对象或 JSON	已安装的规则和配置文件	声明式评估配置
执行方式	本地 JavaScript 函数	本地 CLI 和 API	CLI 和持续集成

覆盖范围

接口或适配器	状态	行为
角色档案	✓	验证字段并冻结档案值
说明文字检查	✓	不区分大小写的子字符串检查
提示词模板	✓	返回图像、视频和说明文字字符串
角色备注	✓	进程内备注存储
本地路由器	✓	SDK 创建回执，不进行外部投递
HTTP 路由器	✓	SDK 将 {text} 发送到指定的端点
模型提供商和社交平台发布器	—	不提供品牌专属集成

源代码导出六个角色函数和两个路由适配器。测试覆盖本地行为和模拟 HTTP 路由。 本次改写未对任何外部集成进行凭证验证。提示词模板不会调用图像、视频或语言模型。

常见用例

1. 内容开发者使用 Node.js 在审核前标记缺少披露文本的内容。
2. 品牌团队使用 JSON 档案和 CLI 检测说明文字中的禁用短语。
3. Agent 开发者使用 MCP 客户端根据共享档案构建提示词字符串。
4. 后端团队使用 TypeScript 在自己的内容管道旁存储角色身份字段。

功能

• **档案验证：**检查必需的字符串和数组，然后冻结档案。
• **一致性检查：**报告匹配的短语、禁用短语、缺少的披露文本和评分。
• **提示词包：**在三个提示词模板中包含身份和风格说明。
• **备注：**添加带时间戳的备注，并在进程内按时间从早到晚列出。
• **核心实用工具：**包含文本统计、日志记录、路由防护和派发成本计数器。

运行时界面

SDK 导出 definePersona、validatePersona、consistencyCheck、promptPack、addNote 和 listNotes。 它还导出共享的文本、守护、日志记录、路由和成本工具。

如需使用 CLI，请将快速入门配置文件对象保存为有效的 JSON，文件名为 persona.json。

npx agentic-persona create --profile persona.json
npx agentic-persona show --profile persona.json
npx agentic-persona check --profile persona.json --text 'A warm tip. Created with AI assistance.'
npx agentic-persona prompts --profile persona.json --topic 'repairing denim'
npx agentic-persona add-note --note 'Prefer natural light'
npx agentic-persona list-notes
npx agentic-persona costs
npx agentic-persona mcp

以下是八个 CLI 命令。帮助选项为 --help / -h；版本选项为 --version / -V。 create 和 show 会验证并打印提供的配置文件；不会保存它。 单独的笔记命令会启动独立进程，彼此之间不共享笔记。

专用的 agentic-persona-mcp 可执行文件也会启动 stdio 服务。 它的六个工具是 define_persona、validate_persona、consistency_check、prompt_pack、add_persona_note 和 list_persona_notes。 笔记共享进程内存；配置文件工具接收显式的配置文件输入，而不是已保存的活动角色设定。

内置的 Worker 入口提供 GET /health 和 POST /summarize，后者接收包含字符串 text 的 JSON。 它会计算文本统计信息，不包含角色设定路由。请自行部署；它不是托管服务，也不会从包根目录导出。

交付与行为限制

语气规则是字面短语。例如，规则 warm 会检查是否包含该子字符串；不会从语义上评估语气。 评分从匹配规则的百分比开始，每出现一个禁用短语扣 25 分，缺少披露内容扣 20 分。 语气规则列表为空时，初始分数为 100。此评分并非经过校准的质量或合规性衡量标准。 提示词会要求保持身份一致性；此软件包不会强制生成的人脸、声音或媒体风格保持一致。 笔记仅存在于进程内，在所有角色设定之间共享，且不会出现在生成的提示词中。进程重启后，笔记会消失。 此软件包不会发布社交媒体帖子、训练模型或提供持久的角色记忆。 HTTP 路由默认超时为 10 秒，且没有重试或身份验证配置。 除非提供 dryRun: true，否则 SDK 调度会实际执行。请预览每次调度；如果守护规则拒绝调度，请停止操作。 成本报告统计调度次数和字符数，不统计费用。角色设定函数不会记录调度成本。

集成指南

• Node.js 角色设定检查示例
• JSON 配置文件 CLI 和 MCP 参考
• 评分与记忆限制

状态

版本 0.1.0 处于早期阶段；接口可能会变更。本仓库目前尚未发布公开案例研究。 如需支持，请使用 GitHub issues。

常见问题

agentic-persona 会生成图像或视频吗？

agentic-persona 会返回提示词字符串。你需要提供生成服务并审核其输出。

哪些集成经过验证？

agentic-persona 通过了本地和模拟路由测试。此次重写没有对任何外部模型或发布集成进行凭据验证。

agentic-persona 提供托管的角色设定服务吗？

agentic-persona 在你自己的进程中运行。持久化存储、托管和模型服务都由你提供。

agentic-persona 与 textlint 有何不同？

agentic-persona 会检查配置文件中的短语并构建角色设定提示词包。textlint 使用已安装的规则检查自然语言文件。

agentic-persona 与 Promptfoo 有何不同？

agentic-persona 使用确定性的本地配置文件检查，不通过模型进行评估。Promptfoo 使用配置的测试来评估提示词和 AI 系统。

评分能衡量品牌语气的质量吗？

agentic-persona 根据字面短语匹配和扣分项评分。它不会衡量语义语气，也不会认证质量。

角色设定笔记在重启后会保留吗？

agentic-persona 会将笔记存储在进程内存中。你的应用需要自行提供持久化存储。

agentic-persona 会在生成的说明文字中添加披露内容吗？

agentic-persona 会在说明文字提示词中加入披露指令。其检查器会检测配置的子字符串；下游输出仍需审核。

许可证

MIT。