[开源] Architext: 定义上下文工程新范式——像架构师一样思考你的 Prompt
<p><strong>Architext</strong> (源自 “Architecture” + “Text”) 是一个为大语言模型（LLM）应用设计的、专注于<strong>上下文工程 (Context Engineering)</strong> 的 Python 库。它提供了一套优雅、强大且面向对象的工具，让您能够像软件工程师设计架构一样，精确、动态地构建和重组 LLM 的输入上下文。</p><p>告别散乱的字符串拼接和复杂的构建逻辑，进入一个将上下文视为<strong>可操作、可组合、可演进的工程化实体</strong>的新时代。</p>
<p><em><strong>GitHub：https://github.com/yym68686/architext</strong></em><br />
<img src="https://images.bigseek.com//forum/202509/03/132736wjcvwvedj3gj3gwc.png" alt="21e102dd500e166cb7cd9498ebe97d1ff8999a88_2_690x344.png" title="21e102dd500e166cb7cd9498ebe97d1ff8999a88_2_690x344.png" /></p>
<h2>什么是上下文工程 (Context Engineering)？</h2>
<p>在构建复杂的 AI Agent 时，提供给 LLM 的上下文（即 <code>messages</code> 列表）的<strong>质量和结构</strong>直接决定了其性能的上限。上下文工程是一门新兴的学科，它关注于：</p>
<ul>
<li><strong>结构化（Structuring）</strong>: 如何将来自不同数据源（文件、代码、数据库、API）的信息，组织成 LLM 最易于理解的结构？</li>
<li><strong>动态化（Dynamism）</strong>: 如何根据对话的进展，实时地添加、移除或重排上下文内容，以保持其相关性和时效性？</li>
<li><strong>优化（Optimization）</strong>: 如何在有限的上下文窗口内，智能地筛选和呈现最高价值的信息，以最大化性能并最小化成本？</li>
</ul>
<p><code>Architext</code> 正是为解决这些工程化挑战而生。</p>
<p>随着 Agent 上下文越来越庞大，管理上下文变得越来越困难。下面我们通过几个场景来说明 Architext 如何解决这些痛点。</p>
<h2>场景1</h2>
<p>有时候agent在windows电脑上运行后，跑到 mac 上面跑，但是系统里面里面已经初始化好了一开始是在Windows上跑的，此时想要修改系统提示很麻烦，开发者需要自己去历史记录里面的字符串手动修改。但是 Architext 可以简化这一切：</p>
<pre><code class="language-python">import json
import time
import asyncio
import platform
from datetime import datetime
from architext import Messages, SystemMessage, Texts
async def example_1():
messages = Messages(
SystemMessage(f"You are a helpful assistant that can help with code. OS: {Texts(lambda: platform.platform())}, Time: {Texts(lambda: datetime.now().isoformat())}")
)
new_messages = await messages.render_latest()
print(json.dumps(new_messages, indent=4, ensure_ascii=False))
time.sleep(1)
# 假设换了系统继续跑
new_messages = await messages.render_latest()
print(json.dumps(new_messages, indent=4, ensure_ascii=False))
asyncio.run(example_1())
# 运行结果
# [
# {
# "role": "system",
# "content": "You are a helpful assistant that can help with code. OS: macOS-15.6.1-arm64-arm-64bit, Time: 2025-09-01T21:18:51.572491"
# }
# ]
# [
# {
# "role": "system",
# "content": "You are a helpful assistant that can help with code. OS: win-10-10.0.22621-amd64-x86_64, Time: 2025-09-01T21:18:52.573421"
# }
# ]
</code></pre>
<p>看到了吗？无需任何手动干预，<code>platform.platform()</code> 和 <code>datetime.now()</code> 就像被赋予了生命，在每次渲染时都动态地提供最新信息。这正是 Architext F-String 的魔力所在：<strong>它将静态的、命令式的字符串拼接，彻底革命为动态的、声明式的上下文构建。</strong> 你不再需要编写繁琐的更新逻辑，只需在字符串中声明“这里需要什么信息”，Architext 就会在运行时为你精准地注入最新状态。这是一个真正的“杀手级”功能，它将开发者从繁重的上下文管理中解放出来，回归到业务逻辑本身。</p>
<h2>场景2</h2>
<p>如果agent读了很多文件，你不得不维护一个列表来记录读了哪些文件，然后为了节省上下文，你不得不放在系统提示里面，而每次请求API都需要将最新的文件内容拼接到系统提示里面。Architext 解决了这个痛点：</p>
<pre><code class="language-python">import json
import asyncio
from architext import Messages, UserMessage, Files, SystemMessage
async def example_2():
messages = Messages(
SystemMessage("You are a helpful assistant that can help with code.", Files()),
UserMessage("hi")
)
# 此时读取了某个文件
messages.provider("files").update("main.py")
new_messages = await messages.render_latest()
print(json.dumps(new_messages, indent=4, ensure_ascii=False))
asyncio.run(example_2())
# 运行结果
# [
# {
# "role": "system",
# "content": "You are a helpful assistant that can help with code.<latest_file_content><file><file_path>main.py</file_path><file_content>print('hello')</file_content></file>\n</latest_file_content>"
# },
# {
# "role": "user",
# "content": "hi"
# }
# ]
</code></pre>
<p>Architext 另外一个很强大的功能就是，人会在agent运行期间修改文件内容，大多数 agent 并不知道，这会导致无法及时获得最新的文件内容，但是 messages.render_latest() 确保每次都能获得最新的文件内容。</p>
<h2>场景3</h2>
<p>有时我想将系统提示里面的文件内容放在第一个 user消息里面，传统方法先从系统提示里面通过正则匹配文件所在的块，然后删除，转移到第一个user消息，此时开发者的心智负担很重，需要操作各种列表，content 字段有时还有列表或者字符串等情况，甚至content里面还有图片，要考虑的情况非常多，开发者无法专注于业务逻辑的开发，被各种边缘情况无限内耗。但是Architext 实现这个需求将非常简单，只需要两行代码，并且能自动处理有图片内容的情况：</p>
<pre><code class="language-python">import json
import asyncio
from architext import Messages, UserMessage, Files, SystemMessage, Images
async def example_3():
messages = Messages(
SystemMessage("You are a helpful assistant that can help with code.", Files()),
UserMessage("hi", Images("image.png"))
)
# 此时读取了某个文件
messages.provider("files").update("main.py")
new_messages = await messages.render_latest()
print(json.dumps(new_messages, indent=4, ensure_ascii=False))
# 转移整个文件块到user message中
files = messages.pop("files")
messages.append(files)
new_messages = await messages.render_latest()
print(json.dumps(new_messages, indent=4, ensure_ascii=False))
asyncio.run(example_3())
# 运行结果
# [
# {
# "role": "system",
# "content": "You are a helpful assistant that can help with code.<latest_file_content><file><file_path>main.py</file_path><file_content>print('hello')</file_content></file>\n</latest_file_content>"
# },
# {
# "role": "user",
# "content": [
# {
# "type": "text",
# "text": "hi"
# },
# {
# "type": "image_url",
# "image_url": {
# "url": "data:image/png;base64,VGhpcyBpcyBhIGR1bW15IGltYWdlIGZpbGUu"
# }
# }
# ]
# }
# ]
# [
# {
# "role": "system",
# "content": "You are a helpful assistant that can help with code."
# },
# {
# "role": "user",
# "content": [
# {
# "type": "text",
# "text": "hi"
# },
# {
# "type": "image_url",
# "image_url": {
# "url": "data:image/png;base64,VGhpcyBpcyBhIGR1bW15IGltYWdlIGZpbGUu"
# }
# },
# {
# "type": "text",
# "text": "<latest_file_content><file><file_path>main.py</file_path><file_content>print('hello')</file_content></file>\n</latest_file_content>"
# }
# ]
# }
# ]
</code></pre>
<p>当然如果你想添加到第一个消息前面只需要 <code>messages = files + messages</code>可以说非常直观。你可能注意到 files = messages.pop(“files”) 开发者并不需要知道files文本块在哪里，这是 Architext 最强大的地方，就是无论该名字的块在 messages 数组的任何地方都能直接pop出来。</p>
<h2>场景4</h2>
<p>前段时间 gemini 免费 key总是截断，很多人想了很多办法防截断，对于agent应用来说，截断是致命的，因为很可能一个tool use还没闭合就结束了，导致 llm觉得自己已经调用过工具的幻觉。我本人利用 Architext完美解决了截断问题，在我的解决方案里面，一个很重要的需求就是我只需要最后一个消息显示防截断提示词：<code>Your message **must** end with to signify the end of your output.</code> 示例代码：</p>
<pre><code class="language-python">import json
import asyncio
from architext import Messages, SystemMessage, Texts, UserMessage, AssistantMessage
async def example_4():
messages = Messages(
SystemMessage(f"You are a helpful assistant that can help with code."),
UserMessage("hi", Texts("\n\nYour message **must** end with to signify the end of your output.", name="done")),
AssistantMessage("hello"),
UserMessage("hi again", Texts("\n\nYour message **must** end with to signify the end of your output.", name="done")),
)
messages.provider("done").visible = False
messages.provider("done")[-1].visible = True
new_messages = await messages.render_latest()
print(json.dumps(new_messages, indent=4, ensure_ascii=False))
asyncio.run(example_4())
# 运行结果
# [
# {
# "role": "system",
# "content": "You are a helpful assistant that can help with code."
# },
# {
# "role": "user",
# "content": "hi"
# },
# {
# "role": "assistant",
# "content": "hello"
# },
# {
# "role": "user",
# "content": "hi again\n\nYour message **must** end with to signify the end of your output."
# }
# ]
</code></pre>
<p>只需要对所有的相同字符串取一样的名字，然后只需要一行就能隐藏所有名字一样的字符串，并通过所有指定只有最后一行才显示防截断字符串。</p>
<h2>远不止于此</h2>
<p>通过以上场景，我们仅仅揭开了 <code>Architext</code> 能力的冰山一角。它代表了一种全新的、将上下文视为<strong>可操作、可组合、可演进的工程化实体</strong>的思维方式。</p>
<p>除了上述功能，<code>Architext</code> 还提供了更多强大的特性等待你去探索：</p>
<ul>
<li><strong>智能消息合并</strong>：当你 <code>append</code> 一个与上一条消息角色相同的消息时，<code>Architext</code> 会自动将它们合并。这彻底解决了许多 API 不允许连续发送相同角色消息的格式规范问题。</li>
<li><strong>完整的工具使用支持</strong>：通过 <code>ToolCalls</code> 和 <code>ToolResults</code>，优雅地处理现代 Agent 的工具调用与结果返回流程。</li>
<li><strong>会话持久化</strong>：使用 <code>messages.save()</code> 和 <code>Messages.load()</code>，轻松实现 Agent 状态的保存和恢复，构建健壮、可中断的长时间任务。</li>
<li><strong>Pythonic 的接口</strong>：享受自然的编码体验，比如用 <code>+</code> 拼接消息，用切片 (<code>messages</code>) 操作消息列表。</li>
<li><strong>智能缓存</strong>：内置的缓存机制只在数据源变化时才刷新内容，兼顾了性能与数据的实时性。</li>
</ul>
<p>通过将软件工程的架构思维引入到 Prompt 构建中，可以极大地解放生产力，让开发者专注于真正重要的业务逻辑。</p>
<p><strong>立即开始你的上下文工程之旅吧！</strong></p>
感谢大佬 感谢分享
标记 管理提示上下文 从表面上看，二者极为相似，但核心区别在于，模板引擎的最终目的是输出静态字符串，而这仅仅是 Architext 的起点。
Architext 输出的是一个可操作的、类似于 DOM 的实时对象结构。
正因如此，你能够实现模板引擎无法做到的事情，例如在运行时动态重组上下文。
Architext 并非一个文本渲染工具，而是一个用于管理上下文结构的工具。 这……周末试一下 厉害了我的老哥 哈哈，感谢支持，我自己也是 cerebr 的重度用户，后续会持续进行改进的。 不太清楚该怎么把它融入到自己的工作流程里，不过先点个赞再说。 是的，现有的任何智能体项目应该都能用。不过要是你还没想到要用，那可能是还没碰到这个痛点。一般只有在将智能体规模化之后，才会感觉很痛苦，用这个框架就会舒心很多。不过可以先收藏起来以备后用。后面遇到需要构建复杂上下文的情况时，就可以再试试看。 都有吧，用于管理agent上下文。主要是为了方便开发者。 模板引擎？ 大佬这是开源了一个框架是吧？有没有现成的超棒工作流？
页:
[1]