author: Xuanwo (Xuanwo Q.)

source: https://github.com/Xuanwo/xurl

tags: [agent, ai, cli, uri, rust, codex, claude, cursor, copilot]

rating: ⭐⭐⭐⭐⭐ (5/5)

xURL — AI Agent 对话的统一 agents:// URI 协议

一句话版本

xURL 是一个命令行工具，让你像用 https:// 访问网页一样，用 agents://codex/<对话ID> 统一读、查、写所有 AI 编程 Agent（Codex、Claude、Cursor、Copilot、Gemini、Kimi 等）的对话记录。

基本信息

• 作者: Xuanwo（@OnlyXuanwo）— 知名 Rust/Go 开源开发者
• 仓库: Xuanwo/xurl
• 协议: Apache-2.0
• 语言: Rust（edition 2024, rust-version 1.85）
• 安装方式: Homebrew / Cargo / uv(pip) / npm / Agent Skill
• 被引用: scnace 在 Tape x Topic 文章中将其作为 Share-able Topic 的参考

核心概念

agents:// URI 协议

xURL 定义了一个全新的 URI 协议，统一访问所有 AI 编程 Agent 的会话数据：

[agents://]<provider>[/<token>[/<child_id>]][?<query>]

四种操作

路径查询

还支持基于项目路径的跨 Agent 搜索：

xurl 'agents://.?q=migration'                      # 当前目录
xurl 'agents:///Users/alice/work?q=refactor'       # 绝对路径
xurl 'agents://~/work?providers=codex,claude'       # 家目录 + 筛选

支持的 9 个 Provider

技术架构

双 Crate 结构

xurl-core/   — URI 解析、Provider 解析、Markdown 渲染、搜索
xurl-cli/    — CLI 二进制（clap 参数解析）

xurl-core 内部模块:

• uri.rs — 完整的 URI 解析器（支持 agents://、无前缀、深链接、路径查询、角色查询）
• provider/ — 为每个 Agent 实现的 Provider trait（resolve_thread, query_threads, write_thread）
• service.rs — 服务编排（3000+ 行，包含 Codex SQLite FBI 搜索、Claude JSONL 解析、子 Agent 追踪）
• render.rs — Markdown 渲染
• model.rs — 所有数据类型（ProviderKind, ThreadQuery, ResolvedThread, SubagentView 等）

关键技术亮点

1. URI 解析非常健壮 — 支持 UUID 验证、百分比解码、+ → 空格、Amp 的 T- 前缀、OpenCode 的 ses_ 前缀、Pi 的短 entry ID

2. 完整的子 Agent 追溯 — main thread → child thread 的支持，含生命周期事件

3. Provider 无关的抽象 — Provider trait 统一了不同 Agent 的存储格式（JSONL / SQLite / 目录结构）

4. AGENTS.md 极其严谨 — 48 条指导原则，覆盖 workspace 职责、CLI 参数、错误处理、agent 友好输出、测试策略、文档同步、分支安全

5. 三条不变量 — 与 Tape 哲学一致（来源可追溯、历史不可改、输出面向 agent 友好）

6. 错误信息 actionable — stderr 输出包含 requested_uri, next_steps, GitHub issue 链接

依赖

• clap — CLI 参数解析
• serde_json — JSON 解析
• rusqlite — Codex 对话库 SQLite 搜索
• grep — 关键词搜索
• walkdir — 目录遍历
• regex — UUID 验证

与 Tape / Topic 的关联

xURL 在 scnace 的 Tape x Topic 文章中被引用为 Share-able Topic 的参考实现：

> "类似 Xuanwo 的 xurl，以后甚至可以直接问：'根据 @scnace 的开放知识库，这个问题该怎么处理？'"

这意味着 xURL 的 agents:// URI 协议可以被用来引用和共享 Agent 对话，就像 Tape 的 Share-able Topic 概念那样——用 URI 指向某段 Agent 历史，供其他人或其他 Agent 按需阅读。

评分对比

与同类对比

深度分析

惊艳点

1. URI 设计非常漂亮 — 简洁、可读、可组合，也兼容无前缀的简短形式

2. 路径查询是杀手级功能 — agents://.?q=refactor 在当前项目目录跨 Agent 搜索，直击多 Agent 用户的日常需求

3. 错误处理反常识但正确 — 对人类啰嗦，但对 Agent 正合适（actionable stderr）

4. AGENTS.md 的 Agent 友好度 — 48 条指导原则，每条都是给编码 Agent 的精确指令

5. 作者背景强 — Xuanwo 是知名 Rust 开发者

6. 被 Tape 生态引用 — scnace 在 Tape Topic 文章中明确提到 xURL 作为 Share-able Topic 的参考，说明在 Agent 上下文管理生态中已获认可

不足/风险

1. 依赖本地文件 — 需要 Agent 在本地的历史文件，远程/云端会话不可用

2. 写操作权限隐患 — 能启动新会话意味着需要能执行 Agent CLI

3. Provider 覆盖不完整 — OpenClaw、Sourcegraph AMP 等不在列表

4. 维护风险 — 9 个 Provider 的存储格式可能随版本变化而 break

5. 仅有 CLI — 没有编程 API 或库接口

对我们项目的意义

xURL 和 lossless-claw 理念互补：

• lossless-claw 管的是"怎么存"（无损压缩、DAG 摘要）
• xURL 管的是"怎么查"（统一 URI、跨 Agent 搜索）
• 两者的结合可以形成一个完整的 Agent 对话生命周期管理方案

参考资料

• xURL GitHub
• xURL on crates.io
• xURL on PyPI
• Xuanwo on X
• tape x topic: 智能体上下文的组织方式