一个基于 Node.js 实现的工程型 AI Agent Framework。 当前版本:1.0.5 核心设计理念: LLM 负责理解任务和规划,Runtime 负责安全执行,XML Action 作为 Agent 与 Workspace 之间的通信协议。
Node.js >= 20.19 Windows 10 / 11 (x64) - 桌面版/打包版 Google Chrome 或 Microsoft Edge(Agent 通过 CDP 复用浏览器,不自带内核)
git clone https://github.com/wulishuhan/xml_agent.git
cd xml_agent
npm install
编辑 config/agent-config.js:
browser: {
// 浏览器类型:chrome(默认)| edge
browserType: "chrome",
// 留空表示按 browserType 自动探测常见安装路径
chromePath: "",
// Edge 专用路径(browserType 为 edge 时优先使用)
edgePath: "",
}
也可以完全留空,Agent 会按 browserType 自动探测本机已安装的 Chrome / Edge。
桌面版(Electron)与 Web 版都可以在界面里配置:点击右上角 Settings(Web 版显示为 Browser Settings),即可选择 Chrome / Edge、查看探测结果、设置各自 CDP 端口、保存并一键切换。Web 版的配置保存在 ~/.xml-agent/webui-browser.json,保存后会立即同步到运行环境,新任务即使用所选浏览器。
生产模式:
npm run webui
访问:http://localhost:3000/xml_agent_web/ 开发模式:
npm run webui:dev
参数说明:
--provider: 可选,默认 chatgpt,支持 chatgpt / qwen / deepseek / glm
--workspace: 必填,工作目录(必须存在)
示例:
node agent.js --workspace "D:\code\vue\ppl" "创建一个vue项目,是关于泡泡龙的游戏"
node agent.js --provider qwen --workspace "D:\code\vue\ppl" "创建一个vue项目,是关于泡泡龙的游戏"
XML Agent 通过 Chrome DevTools Protocol 连接已运行的浏览器(Chrome / Edge 均支持)。 Windows PowerShell(Chrome,默认端口 9222)示例:
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9222 `
--user-data-dir="$PWD\chrome-agent-profile"
Windows PowerShell(Edge,默认端口 9223)示例:
& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" `
--remote-debugging-port=9223 `
--user-data-dir="$PWD\edge-agent-profile"
启动后在该浏览器中登录以下任一平台: https://chatgpt.com https://chat.qwen.ai https://chat.deepseek.com https://chat.z.ai 注意: 登录后不要关闭该浏览器窗口。
开发调试:
npm run electron:dev
直接启动:
npm run electron:start
构建 Windows 安装包(安装版 + 便携版 + zip):
npm run electron:build
离线打包:将 winCodeSign / nsis / nsis-resources 的 .7z 放入 download/ 后执行:
npm run electron:offline-cache
npm run electron:build
产物位于 release/ 目录。
Edge 与 Chrome 同属 Chromium 内核,完整实现了 CDP 协议,因此可以直接复用现有的 CDP 连接与自动化能力。
config/agent-config.js 的 browser 块:
字段默认值说明browserTypechrome浏览器类型,可选 chrome / edgeedgePath""Edge 可执行文件路径,留空自动探测
桌面版配置持久化在用户数据目录的 settings.json,支持 cdpUrls: { chrome, edge } 分别保存两种浏览器的端口。
可通过环境变量覆盖:
BROWSER_TYPE=edge
BROWSER_EDGE_PATH=C:\...\msedge.exe
EDGE_PATH=...
Chrome 与 Edge 默认使用不同端口,避免互相占用:
Chrome:http://127.0.0.1:9222
Edge:http://127.0.0.1:9223
electron/settings.js 提供 DEFAULT_CDP_URLS 与 resolveCdpUrl(settings, browserType);写入设置采用原子写入(先写 .tmp 再 rename),并对非法 URL 回退默认端口。旧版仅含 cdpUrl 的配置会自动迁移。
electron/chrome-finder.js 与 providers/browser-agent.js 均内置 Edge 候选路径:
Windows:Program Files (x86)\Microsoft\Edge\Application\msedge.exe、Program Files\...、LOCALAPPDATA\...、Edge Beta / Dev / SxS
macOS:/Applications/Microsoft Edge.app/...
Linux:/usr/bin/microsoft-edge、/usr/bin/microsoft-edge-stable、/opt/microsoft/msedge/msedge 等
findBrowser({ browserType: "edge" }) / findEdge() 可按类型精确探测,findChrome() 保持向后兼容。
Edge 首次启动会尝试导入 Chrome 数据并弹出欢迎页,可能阻塞 CDP 就绪。electron/chrome-launcher.js 与 providers/browser-agent.js 会为 Edge 追加:
--no-startup-window
--disable-features=msEdgeSidebarV2,msEdgeIdentityFeatures,EdgeCollections
--disable-edge-shopping
Chrome / Edge 使用独立的 user-data-dir(chrome-agent-profile / edge-agent-profile),避免登录态互相覆盖。
getCdpVersionInfo(cdpUrl) 读取 /json/version 的 Browser 字段,识别当前 CDP 端点实际连接的是 Chrome 还是 Edge。
桌面版支持真正的浏览器切换(IPC browser:switch):
记录本应用启动的浏览器进程 pid / 类型 / cdpUrl;
切换时先关闭旧浏览器进程(Windows 使用 taskkill /T /F 关闭整棵进程树),等待旧端口释放;
再在目标浏览器对应的独立端口启动新浏览器。
browser:status 返回 cdpUrl、connectedBrowserType 与 typeMatches(实际连接类型是否与所选一致),Desktop Settings 会提示"Connected browser (different from selected)",并提供 "Switch to Chrome/Edge now" 按钮完成整套切换。
Web 版(用浏览器打开 WebUI)同样支持选择与切换浏览器,实现在 webui/browser-settings.js,不依赖 Electron。
配置保存位置:~/.xml-agent/webui-browser.json(原子写入,非法 URL 回退默认端口,旧 cdpUrl 字段自动迁移)。
保存后会自动同步到运行环境(applyToRuntime):写入 BROWSER_TYPE、BROWSER_CDP_URL、XML_AGENT_BROWSER_TYPE、XML_AGENT_CDP_URL 等环境变量,并更新已加载的 agentConfig 单例,因此新任务立即使用所选浏览器;服务启动时也会读取该配置并应用。
Web 版 API:
GET /api/browser/settings 读取浏览器配置
POST /api/browser/settings 保存浏览器配置(保存即生效)
GET /api/browser/detect?type=chrome|edge 探测浏览器可执行文件
GET /api/browser/status 浏览器 / CDP 状态(含 typeMatches)
POST /api/browser/launch 启动当前所选浏览器
POST /api/browser/switch 切换浏览器(body: { browserType })
切换行为:只关闭“由本服务启动并记录了 pid”的浏览器进程(Windows 使用 taskkill /T /F),再在目标浏览器的独立端口启动;若端口被外部手动启动的浏览器占用,会提示占用而不会误杀。
界面操作:右上角 Settings(Web 版显示 Browser Settings)→ 选择 Chrome / Edge → Save 保存,或点 Switch to Chrome/Edge now 完成切换。
同一 conversation 再次运行任务时,复用同一个 session(sessionId 不变),不会在侧边栏新增会话条目:
webui/server.js 的 /api/run 对同一 provider + conversation:
若已有运行中的 session,直接复用;
若已结束,调用 existing.resume(task) 在同一 session 内继续一次新运行(AgentSession.resume 会重置运行状态、更新 task、追加输出,runCount +1);
不存在则新建 session。
这样同一个 session 会累积多次运行的回复,供 History 与 Trace 回看。
webui/frontend/src/components/AgentConsole.vue 以 agent.started 事件为边界,把 output 拆分为 Run 1、Run 2……
默认只展示最近一次运行,Final Answer 也只基于当前运行计算,因此新任务开始后立即切换到本次运行,不会再停留在上一次的 answer;
工具栏提供 "All runs / Current run" 切换查看全部历史运行,顶部显示 "Run N · current"。
顶部 "History" 打开当前会话的回复历史(只针对左侧已选中的 session): 左栏为当前 session 的回复时间线(Reply 1、Reply 2…,含时间、标题、预览、状态); 右栏为选中回复的完整内容,Markdown 自动渲染;默认选中最新一条回复; 每条回复的标题基于其自身内容生成,同一会话内多条回复标题互不相同; 搜索框只过滤当前会话内的回复。
顶部 "Trace" 查看当前会话的执行轨迹,按"每次运行"分段(Run 1、Run 2…),每个 Run 内部再按 step 展示: Action parsed(解析出的 XML 动作) Runtime result(动作执行结果,带 ok / failed 徽标) Provider request / response、provider error / retry Agent started / completed / stopped / error(记录在 Run 级别) 可展开 "Details" 查看事件完整 JSON,支持 Expand all / Collapse all、Refresh。
整体流程:
User Task
|
v
Agent
|
| Prompt
v
LLM Provider
|
| XML Action
v
XML Parser
|
v
Runtime
|
+----------------+
| |
v v
Workspace Command
(read/write) (exec)
| |
v v
Runtime Result
|
v
Agent Continue
|
+---- answer
|
+---- done
入口:agent.js
职责:
接收用户任务
初始化 Workspace
加载 Provider
调用 LLM
解析 XML Action
调用 Runtime
管理 Agent 生命周期
文件:runtime.js
Runtime 是系统的执行核心,LLM 不直接操作电脑,所有操作必须通过 XML Action。
支持的 Action:
读取文件或目录:
<read path="package.json"/>
<read path="src"/>
写入文件(自动创建父目录,仅限 Workspace 内):
<write path="src/test.js"><![CDATA[
console.log("hello");
]]></write>
执行命令(工作目录固定为 Workspace,有超时限制):
<exec command="npm test"/>
返回最终答案:
<answer><![CDATA[
项目分析完成。
]]></answer>
结束 Agent 生命周期:
<done/>
目录:providers/
统一接口:
const provider = createProvider("chatgpt");
当前支持:ChatGPT、DeepSeek、Qwen、GLM。
BrowserAgent 内置页面自愈机制(ensurePageAlive),浏览器崩溃或标签页关闭时会自动重连恢复会话。浏览器类型可通过 browserType 选项或 BROWSER_TYPE 环境变量指定为 chrome 或 edge;CDP URL 优先使用主进程按浏览器类型解析后写入的环境变量(BROWSER_CDP_URL / XML_AGENT_CDP_URL)。
目录:prompts/
包含:
system-prompt.js:定义 Agent 基础能力与规则
first-prompt.js:首次调用时注入 Workspace、Manifest、用户任务
runtime-prompt.js:根据 Runtime 返回生成下一轮 Prompt
xml-error-prompt.js / send-error-prompt.js / done-prompt.js:异常与终止处理
Agent 操作的目标目录,所有路径必须是相对路径,禁止绝对路径或 ../ 越权访问。
会话数据保存在 ~/.xml-agent/webui-sessions/
工作区产物迁移至 ~/.xml-agent/workspaces/<hash>/,不再污染代码仓库
任务完成后自动生成执行报告
配置项位于 config/agent-config.js 的 session 块:
字段默认值说明maxSessions100最多保存的会话数量maxDiskBytes200MB会话存储目录最大占用warnThreshold0.8达到上限 80% 时触发告警
达到上限后创建新会话会返回明确提示(错误码 MAX_SESSIONS / MAX_DISK),需先删除旧会话。
WebUI 侧边栏提供存储占用指示条与告警提示,悬停可查看详细信息。
支持环境变量覆盖:
WEBUI_MAX_SESSIONS
WEBUI_MAX_DISK_BYTES
WEBUI_WARN_THRESHOLD
API:
GET /api/storage:查询存储状态
POST /api/storage/clean:清理临时文件与释放空间
启动时自动清理上次异常退出遗留的 .tmp 文件。
格式化:
npm run format # 格式化代码
npm run format:check # 检查格式
测试:
npm run test:electron # Electron 相关测试
npm run test:conversation # 会话测试
npm run test:conversation:all # 全量会话测试
node test/test-edge-cdp.js # Edge CDP 支持测试
node test/test-edge-settings-io.js
node test/test-edge-agent-config.js
node test/test-edge-settings-io.js
LLM 不直接执行:所有操作通过 XML Action 交由 Runtime 执行,避免权限失控。 Runtime 是安全边界:控制文件访问、命令执行、路径权限与超时。 Provider 与 Agent 解耦:新增模型无需修改 Agent 核心逻辑。 可审计:History 与 Trace 完整记录 Agent 行为,便于调试与回放。
✅ XML Agent 协议 ✅ Workspace 安全管理 ✅ 文件读写与命令执行 ✅ 多模型 Provider(ChatGPT / DeepSeek / Qwen / GLM) ✅ Runtime 与 XML 错误恢复 ✅ BrowserAgent 页面自愈 ✅ Chrome / Microsoft Edge CDP 支持(含自动探测与启动参数适配) ✅ Chrome / Edge 独立 CDP 端口与一键切换(桌面版 + Web 版均可配置) ✅ Web 版浏览器设置面板(选择浏览器、探测路径、独立端口、保存即生效) ✅ 同一会话复用 session 的多次运行(resume,累积回复) ✅ Agent Activity 按运行分段,实时显示当前运行 ✅ History 回复历史(按会话查看回复时间线、Markdown 渲染、内容化标题) ✅ Trace 执行轨迹(按运行分段,Run 头部显示该次运行任务以区分 Run1/2/3)
✅ 界面长标题/摘要统一以省略号收尾(工作区标题、History 详情标题、Trace Run/Step 摘要) ✅ 会话持久化与存储上限管理 ✅ Report 生成 ✅ Electron 桌面端(安装版 / 便携版 / zip) ✅ 离线打包支持 ✅ Prettier 代码风格统一
详见: RELEASE_NOTES_1.0.1.md RELEASE_NOTES_1.0.2.md RELEASE_NOTES_1.0.3.md RELEASE_NOTES_1.0.4.md RELEASE_NOTES_1.0.5.md
XML Agent 是一个轻量级工程 AI Agent Harness。 核心思想: 模型负责思考 Runtime 负责执行 XML 负责通信 Workspace 负责目标环境 通过这种架构,可以构建安全、可扩展、可审计的工程型 AI Agent。
本项目为个人学习与技术研究用途的参考学习项目,仅用于学习、研究、技术交流与自用,不用于任何商业用途,也不构成任何形式的产品或服务。
本项目通过浏览器自动化(CDP)操作第三方大模型平台的网页界面来演示 Agent 架构,属于技术探索与学习实践。
使用者应遵守各第三方平台(包括但不限于 ChatGPT、DeepSeek、Qwen、GLM 等)的用户协议、服务条款及相关法律法规。使用本项目所产生的任何后果由使用者自行承担,与项目作者无关。
本项目不隶属于、不代表、也未获得上述任何平台或其所属公司的授权、认可或赞助。相关名称、商标及知识产权归其各自所有者所有。
本项目按“现状”提供,不对可用性、稳定性、合规性作任何明示或暗示的担保。作者不对因使用本项目而导致的任何直接或间接损失承担责任。
如相关权利方认为本项目存在不当之处,请联系作者,作者将及时处理。