接入编程代理

CtxCtl 实测的节省只有当 agent 真正用它时才会兑现。有两条一等公民接入路径：为 MCP 原生 agent 暴露原生 MCP 工具，或通过 skill 教 agent 使用 CLI。本页讲配置与取舍；背后的基准数据见基准测试。

路径一：原生 MCP 工具

ctxctl mcp 是一个可选适配器，把同样五个命令作为 MCP 工具经 stdio 提供。CLI 保持规范接口，行为不变。在任何支持启动 stdio 服务器的 MCP 客户端里加一条配置：

{
  "mcpServers": {
    "ctxctl": {
      "command": "ctxctl",
      "args": ["mcp"]
    }
  }
}

这种通用写法适用于 opencode、Cursor、Claude Desktop 以及其他 MCP 原生客户端。

服务器暴露恰好五个工具（tools/list 会为每个工具返回 JSON Schema 形式的 inputSchema）：

工具	包装的命令
`ctxctl_outline`	`outline <file>`
`ctxctl_symbol`	`symbol <file> --name <s>`
`ctxctl_read`	`read <file> --lines N-M`
`ctxctl_deps`	`deps <file>`
`ctxctl_exec`	`exec <cmd> [--keep <pat>]`

对 agent 有意义的行为细节：

结果是与 CLI 文本模式一致的纯文本，附带同样的 saved% 统计，包装为 { content: [{ type: "text", text }] }。
失败——文件不存在、符号未找到、参数错误——以 isError: true 结果返回，绝不是协议错误， agent 读到的是可读消息而不是传输层断裂。
ctxctl_exec 调用的被包裹命令以非零码退出时，文本前会加上 exit code N。
配置解析与 CLI 完全一致，包括 --config。
握手层面：initialize 以协议版本 2025-03-26 与服务器信息（name: "ctxctl"）响应； stdin 干净 EOF 时服务器以 0 退出。

完整协议细节（JSON-RPC 分帧、错误码、initialize 握手）见 MCP 适配器。

路径二：CLI + skill

对不支持 MCP 的 agent——或者你不想注册服务器时——安装 ctxctl-core skill。skill 把 outline / symbol / read / deps / exec 工作流作为普通 shell 命令教给 agent：

# List available skills
npx skills add Xuepoo/ctxctl-skills --list

# Install the core skill for all detected agents
npx skills add Xuepoo/ctxctl-skills --all

# Or use it once without installing
npx skills use Xuepoo/ctxctl-skills --skill ctxctl-core

CLI 本身无需任何配置：每次调用都无状态，项目偏好会自动从 .ctxctl/config.toml 解析（见命令）。

教工作流，而不只是工具

无论选哪条路径，agent 只有知道何时用才能用好 ctxctl。在你的 agent 指令（AGENTS.md、系统提示词或 rules 文件）里放一小段话就大有帮助：

Before reading a file whole:

1. ctxctl outline <file> — see what exists
2. ctxctl symbol <file> --name <s> — read only the needed symbol
3. ctxctl read <file> --lines A-B — for ranges outside symbols
4. ctxctl deps <file> — before jumping across files

Wrap verbose commands instead of running them raw:

5. ctxctl exec "<cmd>" --keep '<pattern>'

自带的 ctxctl-core skill 编码的正是这套策略，这也是为什么基准中 skill 驱动组不需要自定义提示词就能省 token。skill 安装支持按 agent 指定（--agent codex、--agent claude-code、--agent cursor、--agent github-copilot）， CLI 也接受 GitHub 简写、完整 URL 和本地路径。

因为 ctxctl 无状态，多个 agent、worktree 或并发会话之间没有任何需要共享或加锁的东西：两个 agent 探索不同分支时，每次调用都是新鲜解析，配置解析从各自会话的工作目录向上查找。

该选哪种接入方式

客户端支持时优先选原生 MCP 工具。 脚本化 agent 基准中，原生工具消除了 skill 驱动 CLI 用法的摩擦，带来最大的会话成本降幅（对比内置 read/bash 为 −33%）；通过工具驱动的切片探索 96 KB 文件最多削减未缓存输入 −86%。工具 schema 也让正确用法开箱即得——agent 连接时就看到每个工具的输入契约。

以下情况选 CLI + skill：

agent 或运行环境没有 MCP 客户端（很多沙箱和 CI runner）。
你想要零注册——skill 一条命令装好，跨 agent 通用。
你自己在 shell 管道里编排 ctxctl，此时 CLI 的退出码和 --json 契约才是对的接口。

两条路径共享同一套处理器、输出和配置，之后切换没有任何成本——一个会话甚至可以混用两者，不会出现不一致。

认清代价

基准中工具调用密集的 ctxctl 会话大约花了 2× 墙钟时间：几次小工具调用取代一次大读取。你用秒数换美元和缓存压力。对一次性脚本影响不大；对长时间 agent 会话通常仍是划算的交易。收益分布也不均匀：exec 类日志任务最稳（构建日志分析任务成本 −84%），文件探索的收益随文件体积放大——小文件上省得有限，96 KB 级别才能看到两位数的大幅削减。

接好之后，把探索陌生代码和压缩命令输出指给你的 agent，让它把工具用好；输出为何持续命中缓存见设计原则。