deepagents-code 无头 TUI 截图指南基于 Textual 测试框架将终端界面导出为 SVG【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本指南面向 deepagents-code本项目内的 Textual 终端应用即DeepAgentsApp及其它 Textual 应用的开发者讲解如何利用 Textual 自带的 headless 测试框架run_testpilotsave_screenshot在无桌面、无浏览器的环境下渲染真实应用界面并把指定状态导出为 SVG 图片。读完本文你将掌握一条无需操作系统级截图工具即可稳定复现、捕获 deepagents-code 任意界面包括/model命令、模态框、屏幕与组件的完整工作流。方案选型为什么选择 Textual headless 测试框架在需要为终端 UI 生成截图时常见做法是浏览器自动化或操作系统级截图工具。但对于 deepagents-code 这类纯 Textual 应用最可靠的方式是直接复用 Textual 自带的 headless 测试框架DeepAgentsApp本身是textual.app.App的子类见 libs/code/deepagents_code/app.py因此原生支持app.run_test(...)以无界面方式启动应用、用pilot驱动交互并通过app.save_screenshot(...)把合成后的终端画面保存为 SVG。该方案的优点在于渲染结果来自应用的真实组件树与样式CSS_PATH app.tcss见 libs/code/deepagents_code/app.py而不是对终端像素的粗暴截取因此画面与用户真实所见一致且完全不需要桌面环境或浏览器。捕获工作流七个关键步骤按以下顺序编写截图脚本可获得可复现、可审查的结果定位入口找到目标App类deepagents-code 中为DeepAgentsApp确定能够到达目标 UI 的最短可信本地启动路径。临时脚本隔离把截图脚本写在仓库之外例如/tmp/capture_dcode_ui.py生成的截图默认也放在仓库之外除非用户明确要求提交为仓库制品。确定性终端尺寸使用app.run_test(size(columns, rows))固定终端尺寸保证截图在不同机器上一致。驱动到目标状态启动后调用await pilot.pause()等待界面稳定此后每次改变可见状态的操作后都要再次pilot.pause()。优先用pilot.press(...)模拟真实按键路径聚焦于单一画面预览时也可以直接调用应用方法。导出画面在目标状态可见时调用app.save_screenshot(output_path)路径使用.svg后缀。检查产物查看生成的 SVG确认文件大小合理避免出现异常膨胀或空画面。清理现场临时脚本与截图用完即删。最小可用示例捕获 deepagents-code 的/model界面原技能文档给出了一个可直接运行的完整示例其中关键的隔离手段包括用TemporaryDirectory作为DEEPAGENTS_HOME、用MagicMock()替换 agent、在挂载前 patch 掉_post_paint_init。示例代码如下import asyncio import os from pathlib import Path from tempfile import TemporaryDirectory from unittest.mock import AsyncMock, MagicMock, patch async def main() - None: output Path(/tmp/dcode-ui.svg) with TemporaryDirectory() as profile: os.environ[DEEPAGENTS_HOME] profile from deepagents_code.app import DeepAgentsApp app DeepAgentsApp(agentMagicMock()) with patch.object(app, _post_paint_init, newAsyncMock()): async with app.run_test(size(110, 36)) as pilot: await pilot.pause() await app._handle_command(/model) await pilot.pause() app.save_screenshot(output) print(output) asyncio.run(main())脚本必须在libs/code目录下运行以保证项目环境与可编辑安装的包能被正确解析uv run python /tmp/capture_dcode_ui.py示例背后的源码依据上述示例中的每个调用点都能在仓库源码中找到对应实现DeepAgentsApp(agentMagicMock())DeepAgentsApp.__init__以关键字参数形式接收agent: Pregel | None None允许注入一个预配置的 agent本地Pregel或RemoteAgent或临时替身见 libs/code/deepagents_code/app.py。源码中大量测试同样采用DeepAgentsApp(agentMagicMock(), ...)构造方式例如 libs/code/tests/unit_tests/test_app.py证明这是受支持的用法。patch.object(app, _post_paint_init, ...)_post_paint_init是应用首帧渲染后才调用的启动收尾钩子——它负责启动 server、创建模型等后台工作且是通过call_after_refresh(self._post_paint_init)在分支解析完成后被调度见 libs/code/deepagents_code/app.py。在无头截图场景下它会产生不必要的副作用因此用AsyncMock替换是隔离环境的关键一步。app._handle_command(/model)_handle_command是 slash 命令的入口方法见 libs/code/deepagents_code/app.py输入框提交的/前缀命令都会经由此路由。直接调用它即可打开模型选择界面无需模拟完整键盘输入。app.run_test(size(110, 36))run_test是 Textual 提供的 headless 运行入口pilot负责驱动与等待。仓库测试套件中大量使用相同模式例如 libs/code/tests/unit_tests/test_app.py 的run_test(size(100, 40))、libs/code/tests/unit_tests/test_debug_console.py 的run_test(size(50, 40))等说明通过pilot驱动 UI 状态是项目的标准做法。适配其它 Textual 应用如果目标不是 deepagents-code而是一个独立的 Textual 应用只需要替换两个部分应用构造器与打开目标状态的动作。例如把DeepAgentsApp换成目标应用的App子类把await app._handle_command(/model)换成该应用打开目标画面所需的调用可能是pilot.press(...)按键序列或某个公开方法其余run_test/pilot.pause()/save_screenshot的流程完全一致。确定终端尺寸时同样从(110, 36)起步仅当目标界面被裁剪或空间严重浪费时再调整。可靠性与安全约束无头运行并不等于“惰性运行”以下几点必须遵守只使用可信的本地应用代码。headless 应用仍然可能执行启动钩子、拉起子进程或发起网络请求。对于DeepAgentsApp务必在import deepagents_code之前把DEEPAGENTS_HOME指向临时目录并在挂载前 mock 掉_post_paint_init——仅仅替换 agent 并不能隔离启动副作用。绝不捕获机密信息。禁止把密钥、凭据、私人会话内容或无关用户数据截进画面预览所需内容一律用合成的演示数据填充。限制终端尺寸。从(110, 36)开始只有目标内容被裁剪或空间浪费明显时才调整避免生成超大 SVG。等待而非盲等。动画、后台 worker 和模态框过渡都需要时间应额外增加await pilot.pause()而不是依赖任意的sleep()时长。截图不等于行为验证。SVG 只适合做视觉检查交互是否真正生效必须以常规 Textual 测试为准。run_test在项目中本来就被广泛用于行为断言见上文测试用例截图只是其副产品。不要手工编辑 SVG。发现画面不符合预期时应重新驱动应用到达正确的状态并重新截图手工改动会破坏其作为真实渲染产物的可信度。小结借助 Textual 的 headless 测试框架开发者可以在无桌面环境下为 deepagents-code 的任何界面生成与真实渲染一致的 SVG 截图。核心要点可归纳为四条用DEEPAGENTS_HOME临时目录和 mock_post_paint_init隔离启动副作用用run_test(size...)固定画面尺寸用pilot.pause()等待每个状态稳定最后用save_screenshot输出.svg。这套工作流既服务于文档与演示素材的生成也适合在 CI 中做快速的视觉回归预览。更多细节可查阅本技能文档 .agents/skills/textual-screenshot/SKILL.md 及 deepagents-code 的 TUI 测试套件。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考