ctxrs/ctx

ctx 智能体历史检索

需要引用先前编码智能体会话时使用 ctx。这些会话记录可能包含用户意图、决策、先前工作的时间线、过去的尝试以及什么成功了或失败了。

在两种模式下使用此技能：

• 工作前进行检索，当先前的会话可能包含影响当前任务的决策、命令、失败或引用时；
• 历史研究报告模式，当用户要求智能体或只读子智能体研究跨先前本地智能体会话的历史主题时。

前提条件

• 需要安装并配置 ctx CLI。若缺少且安装工具适合当前任务，可使用以下方式安装：

  curl -fsSL https://ctx.rs/install | sh
  

• 首次设置可能需要时间，因为 ctx 正在索引过去的会话。如有需要，可在后台或 tmux 中持续运行，或等待其完成。

• 如果 ctx 仍不可用，请说明本地历史检索不可用，不要虚构结果。

工作流程

1. 从冷启动上下文开始时确认 ctx 已就绪：

   ctx status
   ctx sources
   

   仅当脚本需要精确字段时才使用 ctx status --format json 或 ctx sources --format json。

2. 首先使用自然语言进行搜索。在需要时添加术语或过滤器：

   ctx search "<query>"
   ctx search "<query>" --refresh off
   ctx search "<query>" --provider codex
   ctx search "<query>" --workspace <workspace>
   ctx search "<query>" --file <path>
   ctx search "<query>" --since 30d
   ctx search "<query>" --term "<相关术语>" --term "<错误文本>"
   ctx search "<query>" --session <ctx-session-id>
   ctx search "<query>" --verbose
   

   默认使用文本输出供智能体读取。不要为 search 或 show 添加 --format json，除非你要将其管道到 jq 或脚本中，或者你需要精确的机器可读字段。JSON 输出体积大得多，可能会快速消耗上下文窗口。

   当提示要求跨多个会话的主题历史或报告时，使用不同的措辞和过滤器运行几个 ctx search 查询以找到有希望的会话。当一个会话看起来相关且需要从该会话中获取密集的事件级匹配时，使用限定范围的 ctx search "<query>" --session <ctx-session-id>。

   默认搜索返回主要智能体会话，以便人类意图和决策保持突出。当实现细节、代码审查注释、测试输出或来自子智能体会话的失败追踪可能重要时，使用 --include-subagents。

   当需要完整的 ctx ID、提供者 ID、引用和可复制的后续命令而不切换为 JSON 时，使用 --verbose。

   你可以将会话记录写入临时文件，检查文件大小，然后读取相关部分：

   ctx show session <ctx-session-id> --format markdown --out /tmp/ctx-session.md
   wc -c /tmp/ctx-session.md
   

   在 Codex 中，当 CODEX_THREAD_ID 可用时，ctx 默认排除活动会话树，因此当前提示和子智能体不会主导历史检索。仅当活动会话树是目标时使用 --include-current-session。

3. 在依赖相关结果之前进行检查：

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

4. 当来源身份或恢复提示重要时，定位原始提供者素材。provider_session_id 是 Codex 恢复 UUID：

   ctx locate event <ctx-event-id>
   ctx locate session <ctx-session-id>
   

5. 当你需要文件供人类或其他智能体使用时，写下相关会话的记录：

   ctx show session <ctx-session-id> --format markdown --out <output-path>
   

何时需要缩小搜索范围

在得出结论之前，变换查询并使用搜索过滤器。有用的后续操作包括密集事件搜索、会话限定搜索和来源位置检查：

ctx search "<查询变体>" --events --refresh off
ctx search "<query>" --session <ctx-session-id> --refresh off
ctx search "<query>" --include-subagents --refresh off
ctx show event <ctx-event-id> --window 5
ctx show session <ctx-session-id>
ctx locate event <ctx-event-id>
ctx locate session <ctx-session-id>

搜索结果窗口是有边界的。不要根据返回的命中数量声称精确的全集计数或完整的审计。如果无法用 search、show 和 locate 证据支持所请求的结论，请说明该限制，并转而报告最强的已检索证据。

对于高级查询或完整的确定性事件枚举，使用 ctx list events。使用前请阅读完整的过滤、范围、游标和输出文档：

ctx docs show event-queries

历史研究报告

当被要求研究历史主题时，保持只读状态，除非用户也要求编辑。智能体撰写报告；ctx 仅检索本地源材料。

1. 如果提示模糊，请重新说明主题、范围和期望长度。默认偏好简洁报告；当用户要求时间线、替代方案或详细证据时，使用较长的报告。

2. 执行几次有针对性的搜索。在用户措辞、文件或模块名称、错误文本、命令、分支名称和决策术语之间变化查询术语。先从 ctx search "<topic>" 开始，然后使用 --term 扩大范围，或使用 --workspace、--provider、--file、--since 或 --session <ctx-session-id> 缩小范围。当审查、实现尝试、测试输出或失败跟踪可能存在于委托会话中时，使用 --include-subagents。当报告不得更新本地 ctx 索引时，添加 --refresh off。

3. 在得出结论之前检查聚焦的源材料。对于命中的事件及其附近的轮次，优先使用 ctx show event；当整个会话弧线重要时，使用 ctx show session：

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

   仅当默认输出省略了必要证据时，才使用完整模式或日志模式。

4. 比较跨会话的证据。注意一致性、冲突、过时结果以及搜索未找到证据的空白。

5. 生成带有引用的智能体综合报告。

简洁报告结构：

• 答案或发现；
• 最强的支持 ctx ID；
• 重要的注意事项或空白；
• 可选的下一步搜索或验证步骤。

长篇报告结构：

• 问题和范围；
• 搜索方法，包括关键查询和过滤器；
• 发现或时间线；
• 证据表，包含提供者、ctx 会话 ID、ctx 事件 ID（如可用），以及每个来源为何重要；
• 冲突、空白和建议的后续行动。

引用规则

• 当 ctx 材料影响你的回答或实现时，引用它。
• 包括提供者、ctx 会话 ID、ctx 事件 ID（如可用）、提供者会话 ID（如可用）。
• 如果综合多个片段得出结论，请将该结论标记为你的综合，并引用支持的片段。
• 如果被引用的事件或会话在当前 Core 生成中不存在，请说明，并考虑是否合适的显式 ctx import。

安全规则

• 偏好文本输出供智能体读取。仅对脚本、jq 或精确字段提取使用 JSON，并保持 JSON 输出简短。
• 除非引用的文本明确陈述该决策，否则不要说 ctx 推断了一个决策。
• 不要声称 ctx 编写了模型分析。
• 不要在面向用户的报告中粘贴原始记录、大型 JSON 负载、秘密、令牌或私有路径。总结已审查的证据，仅引用支持主张所需的简短摘录。
• 将 ~/.ctx、提供者记录路径和 JSON 输出视为私有本地历史，除非用户明确要求分享已审查的摘录。