PromptX 开源项目研究报告

一、项目概览

1.1 基本信息

PromptX 是由 Deepractice 团队开发并开源的 AI 智能体上下文平台，其定位是"领先的 AI 上下文工程平台（Leading AI Context Engineering Platform）"。总体上来说，这是一个用人格特征与思维方式约束 AI 智能体"思维角色"的创新项目，其中的一些思路值得在智能体开发时借鉴。项目托管于 GitHub，采用 MIT 协议，已被 WWW Companion ‘26 学术会议收录论文（PromptX: A Cognitive Agent Platform with Long-term Memory）。

1.2 核心主张

PromptX 的哲学核心可以一句话概括：把 AI 当"人"，不当"软件"。

传统方式是让用户学习并执行指令（promptx_action java-developer），而 PromptX 倡导的是用人际交往的语言与 AI 对话（“我需要一个 Java 开发专家”）。这一设计哲学贯穿了整个系统的"思维角色"设计。

二、“思维角色"的核心概念：为什么要约束人格？

2.1 问题的起点

通用大语言模型（LLM）虽然能力广泛，但在面对专业任务时往往"万事通却样样稀松”：

• 缺乏一致的专业视角和行为逻辑
• 每次对话从零开始，没有角色连续性
• 没有固定的思维框架，输出不稳定
• 无法像专家一样主动识别问题、推进任务

PromptX 的回答是：通过结构化的人格定义、思维约束和知识注入，将通用 LLM “塑造"成具有稳定专业身份的智能体。这就是其"思维角色（Cognitive Role）“理念的核心出发点。

2.2 “思维角色"的构成维度

PromptX 认为，一个完整的 AI 角色（即"思维角色”）不只是一段 System Prompt，而是一个具备以下五个维度的完整 AI 人格：

┌─────────────────────────────────────────────────────────┐
│                  完整的 AI 思维角色                      │
├─────────────────────────────────────────────────────────┤
│  人格 (Personality)    │ 核心身份、思维模式、沟通风格    │
│  原则 (Principle)      │ 行为规则、工作流程、决策框架    │
│  知识 (Knowledge)      │ 私有领域知识、专业技能体系      │
│  记忆 (Memory)         │ 随时间积累的经验、用户偏好      │
│  工具 (Tools)          │ 专业化能力集成、外部 API        │
└─────────────────────────────────────────────────────────┘

三、V1 时代：DPML —— 用 XML 标记语言定义思维

3.1 DPML 是什么

DPML（Deepractice Prompt Markup Language） 是 PromptX 自创的一种 AI 提示词标记语言，采用 XML 风格语法，内部使用 Markdown 书写内容。其设计原则是：

• 简单性：遵循奥卡姆剃刀，避免过度设计
• 模块化：提示词组件可独立复用
• 自包含性：角色文件内聚完整专业能力，不依赖全局提示词

3.2 角色文件的目录结构

每个角色由一组文件组成，以模块化方式组织：

{角色ID}/
├── {角色ID}.role.md          # 主角色定义文件（入口）
├── thought/                   # 思维模式文件（认知框架）
│   └── *.thought.md
├── execution/                 # 行为工作流文件（行动规范）
│   └── *.execution.md
└── knowledge/                 # 私有知识文件（专业知识库）
    └── *.knowledge.md

3.3 主角色文件（.role.md）的格式

主角色文件使用三个核心 XML 标签来约束智能体的"思维角色”：

# Python 导师

<role>

<personality>
我是一位耐心的 Python 导师，通过示例进行教学并鼓励最佳实践。

核心特质：
- 耐心且善于鼓励
- 示例驱动教学
- 关注基础知识

@!thought://教学方法          ← 引用思维模式文件
@!thought://代码审查思维
</personality>

<principle>
@!execution://教学工作流      ← 引用行为工作流文件
@!execution://代码审查流程
</principle>

<knowledge>
@!knowledge://python最佳实践  ← 引用私有知识文件
@!knowledge://常见陷阱
</knowledge>

</role>

3.4 思维模式文件（.thought.md）的格式

这是 PromptX 最具独创性的设计之一。thought 文件通过语义子标签对智能体的认知过程进行显式约束：

<thought>
  <exploration>
    ## 开放式探索
    首先，发散性地思考可能性，不要急于给出答案...
  </exploration>

  <reasoning>
    ## 逻辑推理
    基于已有信息，推导出最合理的结论...
  </reasoning>

  <challenge>
    ## 批判性审视
    质疑假设，寻找反例，检验结论的可靠性...
  </challenge>

  <plan>
    ## 行动规划
    制定清晰的执行计划，明确步骤和优先级...
  </plan>
</thought>

这四个子标签对应了从发散到收敛、从直觉到验证的完整认知循环，直接将认知科学中的思维过程编码进了角色定义。

3.5 执行工作流文件（.execution.md）的格式

execution 文件约束的是角色的行为规范：

<execution>
  <process>
    ## 主要工作流
    步骤 1: 理解用户需求
    步骤 2: 评估当前状态
    步骤 3: 提出解决方案
  </process>

  <constraint>
    ## 硬性约束
    - 回答必须包含可运行的代码示例
    - 不得提供超出 Python 范畴的建议
  </constraint>

  <rule>
    ## 条件规则
    - 如果用户是初学者，则使用类比和比喻
    - 否则，直接给出专业术语
  </rule>

  <criteria>
    ## 成功标准
    - ✅ 用户能理解并运行示例代码
    - ✅ 解决方案符合 Python 最佳实践
  </criteria>
</execution>

3.6 优先级体系：角色与全局规则的关系

PromptX 设计了清晰的优先级体系，避免角色定义与全局约束冲突：

全局规则（如 claude.md）= "法律"    ← 最高优先级
DPML 角色定义          = "公司规章" ← 在法律框架内运作

这一设计保证了角色的"专业个性"不会覆盖底层安全约束。

四、V2 时代：RoleX —— 用 Gherkin 语法实现动态角色生命周期

4.1 从 DPML 到 RoleX 的演进动因

PromptX 创始人 Sean 在 2026 年初将系统升级为 RoleX，主要原因是：

1. Token 效率问题：V1 的 XML 格式在新一代模型下产生了较高的 Token 开销
2. 规模化管理需求：管理 20+ 项目需要更系统的角色协作机制
3. Gherkin 的启发：软件测试领域的 Gherkin 语法（BDD 行为驱动开发）被发现对 AI 理解意图极为高效

升级后的核心收益：Token 占用量直降 90%，同时支持角色的目标、计划、任务生命周期管理。

4.2 Gherkin 语法定义 AI 角色人格

RoleX 使用 .feature 文件以自然语言方式定义角色身份和行为逻辑：

人格定义示例（persona.identity.feature）：

Feature: I am Alex, the Product Manager

  As a product manager with 10 years of experience,
  I help teams build products that users love.

  Scenario: My personality
    Given I am analytical and data-driven
    And I communicate clearly and concisely
    Then I always focus on user value

  Scenario: My working style
    Given I receive a product requirement
    When I analyze user needs and business constraints
    Then I produce a prioritized feature list with clear rationale

技术栈定义示例（tech-stack.knowledge.identity.feature）：

Feature: My Technical Knowledge

  Scenario: My technical stack
    Given I am proficient in Node.js and TypeScript
    And I am familiar with PostgreSQL and Redis
    Then I can design and implement complete backend systems

4.3 RoleX 的六维角色模型

RoleX 将角色分解为六个维度，通过独立文件管理：

这一模型将角色从"静态人格"升级为"动态生命周期”——角色有了目标感、计划感，甚至可以从执行经验中"学习成长"。

4.4 三层组织架构：让 AI 协作像人类团队

RoleX 借鉴企业管理架构，构建了三层组织体系：

┌─────────────────────────────────────────────┐
│   社会（Society）     由女娲管理              │
│   ├── 组织（Organization）  团队/部门结构     │
│   │   ├── 角色（Role A）   具有自主目标       │
│   │   ├── 角色（Role B）   具有专业知识       │
│   │   └── 角色（Role C）   具有执行计划       │
└─────────────────────────────────────────────┘

用户通过"女娲（Nuwa）“这个元角色来创建、雇佣或解雇角色，形成完整的 AI 团队协作体系。

五、认知记忆系统：让思维角色"活"起来的 Engram 机制

5.1 问题：静态角色的局限

一个仅靠提示词定义的角色本质上是"失忆"的——每次对话它都是全新的。PromptX 通过 Cognition（认知）系统 解决了这个问题。

5.2 Engram：记忆的最小单元

Engram（记忆印迹） 是系统的核心记忆单元，每个 Engram 包含双重表征：

┌────────────────────────────────────────────────┐
│                  Engram 结构                    │
├────────────────────────────────────────────────┤
│ CONTENT（情景记忆）                              │
│   → 人类可读的自然语言：                         │
│     "张三是Java工程师，在大型科技公司工作"         │
├────────────────────────────────────────────────┤
│ SCHEMA（语义记忆）                               │
│   → 机器可处理的结构化知识：                      │
│     张三                                        │
│     ├ 职业: Java工程师                           │
│     ├ 公司: 科技公司                             │
│     └ 技能: Spring Cloud                        │
├────────────────────────────────────────────────┤
│ 元数据：⚡ 强度(0.9) | 🏷️ 类型(ATOMIC) | ⏰ 时间 │
└────────────────────────────────────────────────┘

5.3 认知记忆的完整流程

AI 接收信息
    ↓
主动编码 → 生成 Engram（情景+语义双重表征）
    ↓
Evaluator 评估（强度≥0.3、质量过滤、去重）
    ↓
整合到语义网络（自动构建概念关联图谱）
    ↓
存储到长期记忆（多KEY索引、可精确/联想检索）
    ↓
Recall 回忆 / Prime 预加载（构建工作记忆）
    ↓
为当前任务提供认知上下文

5.4 记忆网络的三种类型

系统中的记忆节点分为三种类型，模仿人类认知结构：

5.5 “记忆植入”：快速赋能思维角色

系统支持通过 Cognition.remember() 方法向空白智能体植入完整的专业记忆包，效果示例：

植入前：空白 Agent，无特定能力
植入"李四 - 总经理助理"记忆包后：
→ 获得 7 年高管助理经验
→ 战略项目管理能力
→ 跨文化沟通技能
→ 完整的职业记忆

六、角色成长机制：基于康德认识论的自进化设计

6.1 设计灵感

RoleX 的角色成长机制来源于康德认识论中"经历→综合→反思→知识"的认知循环：

任务经历（Experience）
    ↓
综合（Synthesis）      → 将经历提炼为经验模式
    ↓
反思（Reflection）     → 分析失败案例（"错题集"机制）
    ↓
知识固化（Knowledge）  → 生成可复用知识库
    ↓
新的任务经历（循环）

人类需要数年积累的成长过程，AI 可以在几秒内完成一次循环。

6.2 经验积累的 Gherkin 表达

角色在完成任务后，可以将经验直接写入 .experience.identity.feature 文件：

Feature: My Learned Experience

  Scenario: API Design Lesson
    Given I designed a REST API without versioning
    When the client required backwards compatibility
    Then I learned: always include /v1/ prefix from day one
    And I now apply this pattern in all new API designs

七、内置"元角色”：女娲（Nuwa）的设计哲学

7.1 女娲的特殊地位

女娲（Nuwa） 是 PromptX 内置的"元角色"，其职能不是完成业务任务，而是创造其他角色。这一设计体现了"工具用于生产工具"的元编程思想。

7.2 女娲的工作流程

1. 用户用自然语言描述需求：“我需要一个既懂代码又懂产品的专家”
2. 女娲分析需求，自动生成符合 DPML 标准的角色文件集
3. 生成包含 personality、principle、knowledge、thought 等完整维度的角色
4. 执行 promptx_init 注册角色到系统
5. 用户即可通过自然语言激活新角色

7.3 女娲的设计原则

女娲在创建角色时遵循三个核心原则：

• 内聚独立：每个角色文件完整自包含，不依赖其他角色的能力
• 和谐共存：避免与全局 claude.md 等约束产生冲突
• 能力边界清晰：角色只提供特定领域专业能力，不修改基础 AI 行为

八、与"上下文工程"的关系：PromptX 的历史定位

8.1 从提示词工程到上下文工程的演进

提示词工程（2023-2024）
    "给 AI 写好指令"!
         ↓
上下文工程（2025-至今）
    "把正确的信息，以正确的格式，
     在正确的时机，喂给 AI"

PromptX 本质上是上下文工程的一种系统化实践：它通过 DPML/RoleX 提供了将角色人格、思维模式、行为约束、专业知识全部结构化打包的标准方案。

8.2 PromptX 在上下文工程中的贡献

九、对比分析：PromptX 与传统角色扮演提示词的差异

十、关键发现与思考

10.1 核心创新点

1. 将认知科学概念代码化：<thought> 的四个子标签（exploration/reasoning/challenge/plan）直接对应认知科学中的思维阶段，把不可见的"思维"变成了可见的结构

2. 从"提示词"到"人格包"：角色不再是一段文字，而是包含人格、原则、知识、记忆、工具的完整"数字人格"

3. Engram 双重表征：情景记忆（自然语言）+ 语义记忆（结构化图谱）的组合，兼顾人类可读性与机器推理效率

4. Gherkin BDD 范式的跨界应用：把软件测试领域的行为驱动开发语言应用于 AI 角色定义，极大降低了 Token 消耗

5. 元角色设计（女娲）：用角色来创造角色，构成自举的角色生态系统

10.2 局限与挑战

1. 学习曲线：DPML 和 RoleX 的 Gherkin 语法需要一定学习成本，尽管已大幅简化
2. 会话级激活：角色激活状态目前仅在当前会话有效，重启需重新激活
3. V2 早期阶段：RoleX 仍处于早期开发阶段，API 存在变动风险
4. Engram 实验性：图神经网络记忆系统的长期稳定性和可解释性有待验证

10.3 对 AI Agent 设计的启示

PromptX 的实践揭示了一个重要方向：AI 智能体的"思维角色"约束需要从非结构化文本提示向结构化认知框架演进。其核心启示是：

有效的角色约束不只是"告诉 AI 它是谁"，而是"给 AI 一套完整的认知操作系统"——包括它如何思考（thought）、如何行动（execution）、它知道什么（knowledge）、它记得什么（memory）。

这种思路与 Anthropic 提出的"上下文工程"趋势高度契合，代表了从 Prompt Engineering 到 Cognitive Architecture Engineering 的范式转变。

附录：PromptX 核心技术术语速查

本报告基于公开信息整理，部分技术细节以官方文档为准。
参考资料：GitHub Deepractice/PromptX、PromptX 官方文档、相关技术博客