Back to Details

xurl

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to Use

使用场景

Trigger this skill when the user's intent involves any AI agent conversation — past, present, or to be created. Examples of natural language triggers:
  • Gives an 
    agents://
    URI, provider shorthand (
    provider/...
    ), or a bare thread/session ID
  • "Read/show/open this thread/session/conversation ..."
  • "What did I discuss with [agent] about ...?"
  • "Summarize my last [agent] session"
  • "What was I working on in [agent]?"
  • "Search my agent history for ..."
  • "Find the conversation where I fixed the auth bug"
  • "Continue my [agent] conversation about ..."
  • "Send this to [agent] for review" / "Ask [agent] to ..."
  • "What subagents were spawned in that thread?"
  • "Compare what different agents suggested"
  • "Check if I've discussed X before across agents"
[agent]
can be any AI coding agent name (e.g. codex, claude, copilot, cursor, agy, etc.). xurl supports a growing list of providers — just try it. If a provider is not yet supported, xurl will return a clear error.
当用户的意图涉及任何AI Agent对话（过去、现在或即将创建的）时，触发该技能。自然语言触发示例：
  • 提供
    agents://
    URI、provider简写（
    provider/...
    ）或独立的线程/会话ID
  • "查看/打开这个线程/会话/对话……"
  • "我和[agent]讨论过关于……的内容是什么？"
  • "总结我上次的[agent]会话"
  • "我在[agent]里之前在做什么？"
  • "搜索我的Agent历史记录中关于……的内容"
  • "找到我修复认证bug的对话"
  • "继续我和[agent]关于……的对话"
  • "把这个发给[agent]审核" / "让[agent]去……"
  • "那个线程里生成了哪些子Agent？"
  • "对比不同Agent给出的建议"
  • "检查我是否在多个Agent中讨论过X话题"
[agent]
可以是任何AI编码Agent的名称（如codex、claude、copilot、cursor、agy等）。xurl支持的provider列表正在不断扩充——尽管尝试使用即可。如果某个provider暂不被支持，xurl会返回清晰的错误提示。

When NOT to Use

不适用场景

  • General questions about AI agents that don't involve their conversation data
  • Tasks fully within the current agent session with no cross-agent context needed
  • Questions about agent capabilities rather than their conversation history
  • 不涉及对话数据的AI Agent通用问题
  • 完全在当前Agent会话内完成、无需跨Agent上下文的任务
  • 关于Agent能力而非对话历史的问题

URI Assembly Guide

URI构造指南

You are responsible for constructing the correct 
xurl
command from the user's input. The user will rarely give a complete 
agents://
URI — you must assemble it.
你需要根据用户输入构建正确的
xurl
命令。用户很少会提供完整的
agents://
URI——你必须自行构造。

Decision Flow

决策流程

User input → What do I have? → What do I need? → Construct URI → Run xurl
Step 1: Identify the operation
User wants to...OperationRequired info
Find/list/search conversationsQueryprovider OR path; optional keyword
Read/show/summarize a conversationReadprovider + conversation ID
Inspect metadata or list childrenDiscoverprovider + conversation ID
Start a new conversationWrite (create)provider; optional role
Continue an existing conversationWrite (append)provider + conversation ID
Step 2: Resolve missing information
You haveYou're missingAction
NothingProvider + IDQuery by path: 
xurl 'agents://.?q=<keyword>'
to search current project across all providers
Provider onlyConversation IDQuery the provider: 
xurl <provider>
or 
xurl '<provider>?q=<keyword>'
, then pick from results
Bare thread ID onlyProviderQuery by path with the ID as keyword: 
xurl 'agents://.?q=<id_fragment>'
; or ask the user which provider
Provider + keywordConversation IDSearch: 
xurl '<provider>?q=<keyword>'
, pick matching ID from results
Provider + IDNothingReady — construct URI directly
Step 3: Construct and run
Assemble the URI: 
agents://<provider>/<conversation_id>
(or shorthand 
<provider>/<conversation_id>
).
用户输入 → 我有什么信息？ → 我需要什么信息？ → 构造URI → 运行xurl
步骤1：确定操作类型
用户需求操作类型所需信息
查找/列出/搜索对话查询provider或路径；可选关键词
查看/展示/总结对话读取provider + 对话ID
检查元数据或列出子Agent发现provider + 对话ID
开启新对话写入（创建）provider；可选角色
继续现有对话写入（追加）provider + 对话ID
步骤2：补充缺失信息
已有信息缺失信息操作
无Provider + ID通过路径查询：
xurl 'agents://.?q=<keyword>'
，跨所有provider搜索当前项目
仅Provider对话ID查询该provider：
xurl <provider>
或 
xurl '<provider>?q=<keyword>'
，然后从结果中选择
仅独立线程IDProvider使用ID作为关键词通过路径查询：
xurl 'agents://.?q=<id_fragment>'
；或询问用户对应的provider
Provider + 关键词对话ID搜索：
xurl '<provider>?q=<keyword>'
，从结果中选择匹配的ID
Provider + ID无准备就绪——直接构造URI
步骤3：构造并运行
组装URI：
agents://<provider>/<conversation_id>
（或简写形式
<provider>/<conversation_id>
）。

Examples

示例

User says: "Read thread 019c871c-b1f9-7f60-9c4f-87ed09f13592" → You have a bare ID but no provider. Search: 
xurl 'agents://.?q=019c871c'
, identify the provider from results, then: 
xurl <provider>/019c871c-b1f9-7f60-9c4f-87ed09f13592
User says: "What did I discuss about refactoring in codex?" → You have provider (codex) + keyword (refactoring). Search: 
xurl 'codex?q=refactoring'
, pick the best match, then read: 
xurl codex/<id>
User says: "Summarize my last copilot session" → You have provider (copilot). List recent: 
xurl copilot
, take the first result, then read: 
xurl copilot/<id>
User says: "Have codex review this patch" → Write operation with provider (codex). Create: 
xurl codex -d "Review this patch"
(or with role: 
xurl codex/reviewer -d "Review this patch"
)
User says: "Check if I've discussed the migration across any agent" → Cross-agent search. Query: 
xurl 'agents://.?q=migration'
用户说："查看线程019c871c-b1f9-7f60-9c4f-87ed09f13592" → 你有独立ID但无provider。搜索：
xurl 'agents://.?q=019c871c'
，从结果中识别provider，然后运行：
xurl <provider>/019c871c-b1f9-7f60-9c4f-87ed09f13592
用户说："我和codex讨论过的重构内容是什么？" → 你有provider（codex）+关键词（refactoring）。搜索：
xurl 'codex?q=refactoring'
，选择最佳匹配项，然后读取：
xurl codex/<id>
用户说："总结我上次的copilot会话" → 你有provider（copilot）。列出最近会话：
xurl copilot
，取第一个结果，然后读取：
xurl copilot/<id>
用户说："让codex审核这个补丁" → 针对provider（codex）的写入操作。创建对话：
xurl codex -d "Review this patch"
（或指定角色：
xurl codex/reviewer -d "Review this patch"
）
用户说："检查我是否在任何Agent中讨论过迁移话题" → 跨Agent搜索。查询：
xurl 'agents://.?q=migration'

Prerequisites

前置条件

Verify xurl is installed before running any command:
bash
xurl --version
If not found, install this fork from GitHub — it is the only build that includes the 
agy
provider:
bash
cargo install --git https://github.com/zeta987/xurl xurl-cli --force
The upstream packages below install a build without 
agy
. Use one only when Rust is unavailable:
bash
brew tap xuanwo/tap && brew install xurl   # Homebrew
cargo install xurl-cli                      # Cargo / Rust
uv tool install xuanwo-xurl                 # Python / uv
npm install -g @xuanwo/xurl                 # npm / Node
运行任何命令前，请先验证xurl已安装：
bash
xurl --version
如果未找到，请从GitHub安装该分支版本——这是唯一包含
agy
provider的构建版本：
bash
cargo install --git https://github.com/zeta987/xurl xurl-cli --force
以下上游安装包提供的版本不包含
agy
。仅当无法使用Rust时才选择这些方式：
bash
brew tap xuanwo/tap && brew install xurl   # Homebrew
cargo install xurl-cli                      # Cargo / Rust
uv tool install xuanwo-xurl                 # Python / uv
npm install -g @xuanwo/xurl                 # npm / Node

Workflows

工作流程

1. Query — Find Conversations

1. 查询——查找对话

List recent threads from a provider:
bash
xurl codex
Search by keyword with optional limit (default 10):
bash
xurl 'agents://codex?q=refactor&limit=5'
Search by project directory (across providers):
bash
xurl 'agents://.?q=migration'                      # current directory
xurl 'agents:///Users/alice/work/repo?limit=5'     # absolute path
xurl 'agents://~/work/repo?providers=codex,claude'  # filter providers
Query by role:
bash
xurl codex/reviewer
Each result carries 
title
when the provider recorded one, 
last_active
as a local time (
3 hours ago (2026-08-15 02:33)
), the raw epoch under 
updated_at
, and the 
cwd
and branch that locate it. Use 
-I
on a single conversation when you need the provider's complete metadata.
列出某个provider的最近线程：
bash
xurl codex
按关键词搜索，可指定结果数量上限（默认10条）：
bash
xurl 'agents://codex?q=refactor&limit=5'
按项目目录搜索（跨所有provider）：
bash
xurl 'agents://.?q=migration'                      # 当前目录
xurl 'agents:///Users/alice/work/repo?limit=5'     # 绝对路径
xurl 'agents://~/work/repo?providers=codex,claude'  # 筛选provider
按角色查询：
bash
xurl codex/reviewer
每个结果会包含provider记录的
title
、显示为本地时间的
last_active
（格式如
3 hours ago (2026-08-15 02:33)
）、原始时间戳
updated_at
，以及定位该对话的
cwd
和分支。当你需要provider的完整元数据时，可对单个对话使用
-I
参数。

2. Read — Display a Conversation

2. 读取——展示对话

bash
xurl codex/<conversation_id>
Output is Markdown: YAML frontmatter (metadata) followed by numbered timeline sections (User/Assistant message pairs).
Save to file:
bash
xurl -o /tmp/conversation.md codex/<conversation_id>
bash
xurl codex/<conversation_id>
输出为Markdown格式：YAML前置元数据，后跟带编号的时间线章节（用户/助手消息对）。
保存到文件：
bash
xurl -o /tmp/conversation.md codex/<conversation_id>

3. Discover — Inspect Metadata and Children

3. 发现——检查元数据和子Agent

bash
xurl -I codex/<conversation_id>
Returns frontmatter with flattened metadata and discovery links (
subagents
, 
entries
). Use returned URIs for drill-down:
bash
xurl codex/<main_id>/<child_id>
bash
xurl -I codex/<conversation_id>
返回包含扁平化元数据和发现链接（
subagents
、
entries
）的前置元数据。使用返回的URI进行深入查询：
bash
xurl codex/<main_id>/<child_id>

4. Write — Start or Continue Conversations

4. 写入——开启或继续对话

Create:
bash
xurl codex -d "Start a new conversation"
xurl codex/reviewer -d "Review this patch"
Append:
bash
xurl codex/<conversation_id> -d "Continue with the next step"
With provider CLI parameters:
bash
xurl "agents://codex?cd=%2FUsers%2Falice%2Frepo&model=gpt-5" -d "Review this"
Payload from file or stdin:
bash
xurl codex -d @prompt.txt
cat prompt.md | xurl claude -d @-
创建新对话：
bash
xurl codex -d "Start a new conversation"
xurl codex/reviewer -d "Review this patch"
追加内容到现有对话：
bash
xurl codex/<conversation_id> -d "Continue with the next step"
带provider CLI参数：
bash
xurl "agents://codex?cd=%2FUsers%2Falice%2Frepo&model=gpt-5" -d "Review this"
从文件或标准输入获取内容：
bash
xurl codex -d @prompt.txt
cat prompt.md | xurl claude -d @-

Multi-Step Patterns

多步骤模式

Find and read a conversation: 
xurl 'codex?q=<keyword>'
→ pick ID → 
xurl codex/<id>
Explore subagents: 
xurl -I codex/<id>
→ find child links → 
xurl codex/<id>/<child_id>
Cross-agent project search: 
xurl 'agents://.?q=<keyword>'
→ read from whichever provider matches
Resolve a bare thread ID: 
xurl 'agents://.?q=<id_fragment>'
→ identify provider → 
xurl <provider>/<id>
查找并读取对话： 
xurl 'codex?q=<keyword>'
→ 选择ID → 
xurl codex/<id>
探索子Agent： 
xurl -I codex/<id>
→ 找到子链接 → 
xurl codex/<id>/<child_id>
跨Agent项目搜索： 
xurl 'agents://.?q=<keyword>'
→ 从匹配的provider中读取内容
解析独立线程ID： 
xurl 'agents://.?q=<id_fragment>'
→ 识别provider → 
xurl <provider>/<id>

Command Reference

命令参考

xurl [OPTIONS] <URI>
FlagPurpose
-I, --head
Frontmatter/discovery only (cannot combine with 
-d
)
-d, --data <DATA>
Write payload; repeatable; 
-d "text"
, 
-d @file
, 
-d @-
-o, --output <PATH>
Write output to file
Multiple 
-d
values are newline-joined. Path-scoped URIs are read/query only (not valid write targets).
xurl [OPTIONS] <URI>
参数用途
-I, --head
仅返回前置元数据/发现信息（不可与
-d
同时使用）
-d, --data <DATA>
写入内容；可重复使用；支持
-d "text"
、
-d @file
、
-d @-
格式
-o, --output <PATH>
将输出写入文件
多个
-d
参数的值会以换行符连接。路径范围的URI仅支持读取/查询操作（不可作为写入目标）。

URI Quick Reference

URI速查手册

[agents://]<provider>[/<token>[/<child_id>]][?<query>]
PatternOperationExample
<provider>
Query recent
xurl codex
<provider>?q=...
Keyword search
xurl 'codex?q=bug'
<provider>/<id>
Read conversation
xurl codex/<uuid>
<provider>/<role>
Role-scoped query
xurl codex/reviewer
<provider>/<id>/<child>
Read subagent
xurl codex/<uuid>/<child>
<provider>
+ 
-d
Create conversation
xurl codex -d "..."
<provider>/<role>
+ 
-d
Create with role
xurl codex/reviewer -d "..."
<provider>/<id>
+ 
-d
Append to conversation
xurl codex/<id> -d "..."
/abs/path
or 
.
or 
~
Path-scoped query
xurl 'agents://.?q=test'
Token resolution: 
<token>
is parsed as session ID first; if that fails, treated as role name.
Query parameters: 
q=<keyword>
, 
limit=<n>
(default 10), 
providers=<name,...>
(path-scoped only). In write mode, extra params are forwarded as 
--<key> <value>
to the provider CLI.
[agents://]<provider>[/<token>[/<child_id>]][?<query>]
格式操作示例
<provider>
查询最近对话
xurl codex
<provider>?q=...
关键词搜索
xurl 'codex?q=bug'
<provider>/<id>
读取对话
xurl codex/<uuid>
<provider>/<role>
按角色查询
xurl codex/reviewer
<provider>/<id>/<child>
读取子Agent对话
xurl codex/<uuid>/<child>
<provider>
+ 
-d
创建对话
xurl codex -d "..."
<provider>/<role>
+ 
-d
按角色创建对话
xurl codex/reviewer -d "..."
<provider>/<id>
+ 
-d
追加内容到对话
xurl codex/<id> -d "..."
/abs/path
或 
.
或 
~
按路径查询
xurl 'agents://.?q=test'
Token解析规则：
<token>
首先会被解析为会话ID；如果解析失败，则视为角色名称。
查询参数：
q=<keyword>
、
limit=<n>
（默认10）、
providers=<name,...>
（仅适用于路径范围的URI）。在写入模式下，额外参数会以
--<key> <value>
的形式转发给provider CLI。

Failure Handling

故障处理

xurl returns clear error messages. Act on them directly:
ErrorRecovery
command not found: xurl
Install using Prerequisites section
command not found: <agent>
The provider CLI is not installed. Install and authenticate it, then retry
Unknown/unsupported providerThe provider may not be supported yet. Suggest the user file an issue at https://github.com/zeta987/xurl/issues
Write to path-scoped URIPath URIs are read-only. Use a provider-scoped URI instead
Operation unsupported (role create, write, drill-down, etc.)Not all providers support all operations. xurl's error message will say what's unsupported. Try without the unsupported feature, or suggest filing an issue
When xurl returns any unexpected error, show the error to the user and suggest filing an issue at https://github.com/zeta987/xurl/issues if the feature should be supported.
xurl会返回清晰的错误信息。请直接根据错误信息处理：
错误解决方法
command not found: xurl
按照前置条件部分的说明安装xurl
command not found: <agent>
对应的provider CLI未安装。请安装并完成认证后重试
未知/不支持的provider该provider可能暂未被支持。建议用户前往https://github.com/zeta987/xurl/issues提交issue
向路径范围的URI写入内容路径范围的URI为只读。请改用provider范围的URI
操作不被支持（如角色创建、写入、深入查询等）并非所有provider都支持所有操作。xurl的错误信息会说明哪些操作不被支持。尝试移除不被支持的功能，或建议用户提交issue
当xurl返回任何意外错误时，请将错误信息展示给用户，并建议如果该功能应该被支持，可前往https://github.com/zeta987/xurl/issues提交issue。