failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/zh/agenteye/incidents.mdx

@@ -0,0 +1,50 @@
+---
+title: "事故"
+description: "当告警触发时，所有人都能看到事故已开启、负责人是谁，以及目前发生了什么——一条有归属标注的统一时间线。"
+---
+
+
+当告警触发时，第一个问题永远是"谁在处理？"事故功能给出了答案：一旦发生违规，所有人都能立即看到事故已开启、负责人是谁，以及目前已发生的一切——形成一份干净、有归属的记录，可以直接用于事后复盘。
+
+![事故收件箱：与告警关联的事故卡片和手动创建的事故卡片，按状态分组，每张卡片带有严重程度徽章和负责人信息](/agenteye/images/incidents.png)
+*收件箱按状态将未处理的事故分组，并支持按严重程度和负责人筛选，让你快速看到当前需要人工介入的内容。*
+
+## 一眼知道谁在负责
+
+再也不用在群聊里问"有人在看这个吗？"。违规发生时会自动创建事故并进入共享收件箱，按状态分组。确认事故后，你的名字就挂在上面，让团队其他成员知道已有人接手。确认操作支持多人同时进行：多名操作员可以各自确认同一个事故，每条记录独立保存，整个作战小组都能按名字显示，而不会互相覆盖。指定一名负责人进行分类处理，再按严重程度或负责人筛选收件箱，快速聚焦到属于自己的事故。
+
+## 完整故事，尽在一条时间线
+
+事故结束时，你已经有了现成的复盘素材。打开任意事故，你会看到违规证据、负责人和订阅者、用于协调沟通的评论线程，以及一条只能追加的活动时间线。
+
+![事故详情视图：父告警与违规摘要、负责人和订阅者、有归属标注的活动时间线，以及评论线程](/agenteye/images/incident-detail.png)
+*所有发生过的事，按时间顺序排列，每一行都标注了操作人。*
+
+每一个操作（开启、确认、解决等）都会写入时间线，且永远不会被编辑删除。每条记录都有归属：操作员按邮箱标注，由 Failproof AI Observability 自动执行的操作（例如在违规时自动开启事故）则标注为 **automated**。没有匿名记录，没有信息丢失，事后复盘几乎可以自动生成。
+
+## 事故的流转方式
+
+```mermaid
+stateDiagram-v2
+    [*] --> firing
+    firing --> acknowledged: an operator acks
+    firing --> resolved: an operator resolves
+    acknowledged --> resolved: an operator resolves
+    resolved --> [*]
+```
+
+- **未处理（firing）：** 违规触发事故创建，并向你的渠道发送一次通知。后续重复违规会折叠进同一个事故并刷新证据，不会反复通知。
+- **已确认（acknowledged）：** 操作员接手处理。事故保持开启状态，后续违规会静默更新证据。
+- **已解决（resolved）：** 操作员关闭事故。条件恢复正常后自动解决的功能在规划中，尚未启用，因此事故会保持开启直到有人手动解决——这确保了所有人对实际已恢复情况的诚实判断。之后同一告警可以再次创建新的事故。
+
+同一时间，一条告警最多只能有一个未关闭的事故，因此频繁抖动的规则不会让你淹没在重复事故中。你也可以手动创建事故：既可以是与任何告警无关的独立事故（用于捕捉告警未覆盖的情况），也可以关联到现有告警，前提是你拥有 `incidents:write` 权限。
+
+## 在哪里找到它
+
+事故功能位于 `/<org-slug>/incidents`。查看需要 **`incidents:read`** 权限；手动创建事故需要 **`incidents:write`** 权限；确认、分配、评论和解决需要 **`incidents:ack`** 权限。旧版密钥授予的已废弃 `alerts:ack` 权限仍然有效，因为它会被识别为 `incidents:ack`，所以你的值班轮换无需重新下发密钥。
+
+## 相关内容
+
+- [告警](/zh/agenteye/alerts)：当阈值被突破时触发事故的规则。
+- [错误追踪](/zh/agenteye/error-tracking)：在一处查看所有故障，并将其中一个提升为告警。
+- [审计](/zh/agenteye/audits)：定期运行的分析器，用于发现没有规则在监控的故障。

package/.next/standalone/docs-old/zh/agenteye/observability.mdx

@@ -0,0 +1,23 @@
+---
+title: "观察"
+description: "观察界面让你实时查看 Agent 的运行情况，并深入分析任意单次运行记录。"
+---
+
+
+观察界面让你实时查看 Agent 的运行情况，并深入分析任意单次运行记录。这里的所有内容都是实时的，以组织为范围，可按日期范围、环境、Agent 和会话进行筛选，让你能在几秒内从"感觉有点不对"定位到具体的运行记录。
+
+![实时事件流，按类型进行颜色标注，可按环境、Agent 和会话筛选](/agenteye/images/events-stream.png)
+
+四个界面，各有独立页面：
+
+- **[事件流](/zh/agenteye/event-stream)**：所有 Agent 每次运行的实时逐步追踪记录，最新在前。是你组织的首页，也是分诊排查的第一站。
+- **[会话与执行图](/zh/agenteye/sessions)**：将事件汇总为每次运行一行，并以类似 Git 的图形展示每次运行的展开过程。
+- **[性能指标](/zh/agenteye/telemetry)**：模型、工具和 Hook 的延迟热图及 p50/p95/p99 关键指标，让尾部毛刺从中位数中一眼凸显。
+- **[错误追踪](/zh/agenteye/error-tracking)**：统一呈现所有异常情况的分诊界面，一键从触发的告警跳转到出问题的运行记录。
+
+## 相关内容
+
+- [评估](/zh/agenteye/evaluations)：对每次运行进行质量评分。
+- [告警](/zh/agenteye/alerts)：将任意阈值转化为告警规则。
+- [审计](/zh/agenteye/audits)：让 Failproof AI Observability 自动为你发现跨会话的故障模式。
+- [CLI 与 Agent](/zh/agenteye/cli-and-agents)：在终端中获得同等的可观测能力。

package/.next/standalone/docs-old/zh/agenteye/openclaw-capture.mdx

@@ -0,0 +1,49 @@
+---
+title: "OpenClaw 会话捕获"
+description: "将团队本地的 OpenClaw 会话作为普通会话和事件接入 AgentEye，无需更改 OpenClaw 的运行方式。"
+---
+
+如果你的团队使用 [OpenClaw](https://docs.openclaw.ai)，OpenClaw 会话捕获功能可将这些会话作为普通会话和事件引入 AgentEye，方便你与其他观测数据一起进行搜索、回放和评估。该功能与 [Python SDK](/zh/agenteye/python-sdk) 互为补充：SDK 用于对你自行编写的 Agent 进行插桩，而本功能则捕获团队日常使用 OpenClaw 所产生的工作内容——无需改变任何使用习惯。
+
+一个轻量级后台采集器会在 OpenClaw 本地会话记录写入时实时读取，并将其传输至 AgentEye。其工作方式与 [Codex 捕获](/zh/agenteye/codex-capture) 相同，且同一采集器可同时捕获两者。
+
+---
+
+## 捕获内容
+
+机器上 OpenClaw 配置中的每个 Agent 都会被该机器的采集器捕获，无需针对单个 Agent 进行额外配置。
+
+每个 OpenClaw 会话对应 AgentEye 中的一个[会话](/zh/agenteye/sessions)；其用户消息、助手消息、工具调用及工具结果将成为对应的[事件](/zh/agenteye/event-stream)。
+
+---
+
+## 开启方式
+
+捕获功能默认关闭，需手动启用。使用具有 `events:add` 权限的 API 密钥（参见 [API 密钥](/zh/agenteye/api-keys)）安装采集器，并开启 OpenClaw 捕获：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --openclaw-enabled
+```
+
+该命令会安装采集器、将其注册为后台服务并开始捕获。确认服务正在运行：
+
+```bash
+agenteye-collector health
+```
+
+同一台机器上需捕获多个 Agent？在同一命令中添加各自的标志即可，例如 `--openclaw-enabled --codex-enabled`。
+
+首次运行时，已有的 OpenClaw 会话会被一次性回填，此后的新活动将在数秒内实时传输。OpenClaw 的本地文件仅供读取，不会被修改、移动或删除；每个会话即使跨越重启也只会被传输一次。
+
+---
+
+## 数据呈现位置
+
+捕获的会话显示在 **Sessions** 中，其事件显示在 **Events** 流中，与其他被观测的 Agent 完全一致——因此[会话回放](/zh/agenteye/sessions)、[搜索](/zh/agenteye/queries)、[评估](/zh/agenteye/evaluations)和[告警](/zh/agenteye/alerts)均适用。按 OpenClaw Agent 进行筛选可单独查看其数据。
+
+---
+
+## 隐私说明
+
+OpenClaw 记录包含完整的会话内容——包括命令输出、文件内容以及 Agent 读写的所有信息——可能涉及敏感数据。捕获的会话将原样传输，因此请仅在适合将相关内容集中存储至 AgentEye 的机器和团队中启用捕获功能，并将采集器的密钥权限限定为仅 `events:add`。有关数据隔离保护措施，请参阅[安全性](/zh/agenteye/security)。

package/.next/standalone/docs-old/zh/agenteye/overview.mdx

@@ -0,0 +1,108 @@
+---
+title: "Failproof AI：监控 Agent 故障"
+description: "Failproof AI Observability 是一个自托管平台，用于在生产环境中观测、评估和改进您的 AI agent。"
+---
+
+
+Failproof AI Observability 是一个自托管平台，用于在生产环境中观测、评估和改进您的 AI agent。它记录 agent 的所有行为（每次工具调用、模型请求、hook 和错误），对每次运行的质量进行评分，并在您自己基础设施内运行的仪表板中呈现您未曾预料到的故障。
+
+如果您正在部署 AI agent，并且厌倦了猜测某次运行出错的原因，这就是您的起点。本文将介绍 Failproof AI Observability 能为您提供什么，以及各模块如何协同工作——无需先安装任何东西。
+
+> **Failproof AI Observability 是 Failproof AI 的企业级产品。** 想亲眼看看它的效果？申请演示，请发邮件至 [nikita@befailproof.ai](mailto:nikita@befailproof.ai)。
+
+![Failproof AI Observability 会话以 git 风格的执行图呈现，旁边是事件时间线，右侧栏按运行维度展示工具、模型和 hook 的详细信息](/agenteye/images/session-detail.png)
+
+*每次 agent 运行均以 git 风格的执行图（左）呈现，旁边配有事件时间线。并行子 agent 各占独立泳道；右侧栏按运行维度列出工具、模型、hook 及 token 消耗明细。*
+
+---
+
+## 实际效果演示
+
+以下两段简短视频展示了团队最常用的两项功能：追踪单次运行，以及自动发现故障。
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Agent 追踪：逐步跟踪单次运行，从目标到工具调用，直至最终答案。*
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Watch: Automatically find where your agent is failing (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Failproof Audit：让 Failproof AI Observability 跨会话挖掘您的日志，并告诉您需要修复的问题。*
+
+---
+
+## 团队使用它的理由
+
+- **看清 agent 实际做了什么。** 每次运行都会生成一个可读的 git 风格执行图：哪些工具并行运行、哪些子 agent 分支启动、在哪里卡住，以及消耗了多少资源。
+- **自动捕获质量回归。** 接入一个小型评分服务后，Failproof AI Observability 会对每次完成的运行进行评分，帮助性下降或幻觉激增时会自动浮现。
+- **发现您未曾定义规则的故障。** 周期性审计跨会话挖掘日志，查找错误聚类、延迟异常值、低分运行和卡死任务，并将按优先级排序、附有证据支撑的发现呈现给您。
+- **在关键时刻收到告警。** 基于错误率、延迟、成本或评估分数的阈值规则会触发告警，生成可确认、分配和解决的事件。
+- **用自然语言提问。** 仪表板内置 AI 助手，可以用中文直接询问「本周生产环境的质量趋势如何？」，基于您自己的数据作答。任何变更均需审批方可生效。
+- **数据完全归您所有。** Failproof AI Observability 采用自托管方式：事件、提示词和分析数据始终保存在您掌控的基础设施中。
+
+---
+
+## 功能概览
+
+Failproof AI Observability 围绕三个核心理念组织：**观测（observe）**、**分析（analyze）** 和 **管理（admin）**，并在仪表板左侧边栏中一一对应。
+
+**观测**（运行的原始真相）：
+
+- **[事件流](/zh/agenteye/event-stream)**：每次运行的实时逐步记录（工具调用、模型调用、hook、错误）。
+- **[会话](/zh/agenteye/sessions)**：将这些事件汇总为每次运行一行，每行均可评分，并附有 git 风格的执行图。
+- **[性能指标](/zh/agenteye/telemetry)**：按维度划分的延迟热力图，以及模型、工具和 hook 的 p50/p95/p99 关键指标，让尾部延迟从中位数中一眼凸显。
+- **[错误追踪](/zh/agenteye/error-tracking)**：所有异常的统一分类界面，一键直达触发中的告警。
+
+![工具观测页：24 个时间段内的延迟热力图、百分位带和工具分布条形图](/agenteye/images/tools.png)
+
+*每个观测界面均将 p50/p95/p99 关键指标与延迟热力图及百分位带配对展示。图中所示：工具页。*
+
+**分析**（将活动转化为洞察）：
+
+- **[查询](/zh/agenteye/queries)** 和 **[仪表板](/zh/agenteye/dashboards)**：基于事件和评估数据的已保存 SQL 查询，以图表形式呈现在团队共享的组织级仪表板中。
+- **[评估](/zh/agenteye/evaluations)**：由您自己的评估服务产出的质量分数，附带每项评分的推理过程。
+- **[审计](/zh/agenteye/audits)**：周期性调查，跨会话发现故障模式。
+- **[告警](/zh/agenteye/alerts)** 和 **[事件](/zh/agenteye/incidents)**：触发通知的阈值规则，以及用于分类处理的事件工作流。
+
+**接口**（以您喜欢的方式访问数据）：
+
+- **[CLI](/zh/agenteye/cli-and-agents)**：通过终端或脚本驱动整个部署，也可以让编码 agent 用自然语言替您完成操作。
+- **[AI 助手](/zh/agenteye/assistant)**：直接在仪表板内用自然语言询问关于您 agent 的问题。
+- **REST API**：仪表板和 CLI 的所有功能均由 REST API 提供支持，您可以使用有权限范围限制的 [API 密钥](/zh/agenteye/api-keys) 直接调用——摄取事件、查询会话和评估数据、管理仪表板、告警、审计、用户和密钥，将 Failproof AI Observability 接入您自己的工具链。
+
+**管理**（为您的团队运维）：
+
+- **[API 密钥](/zh/agenteye/api-keys)**：适用于采集器、仪表板和助手的范围化令牌。
+- **用户**：基于邮件的无密码登录，支持白名单管理。
+- **设置**：组织级配置，包括模型上下文窗口覆盖项。
+
+---
+
+## 各模块如何协同
+
+数据沿单一方向流动，从您的 agent 代码流向仪表板：您的 agent（通过 Python SDK）将事件发送至 agenteye-collector，后者将事件传输至服务器，服务器再提供仪表板所需的数据。另有两个可选服务作为补充——评分服务（评估）和 AI 助手服务（仪表板内聊天）。
+
+- **Python SDK**：您在 agent 中添加少量 `agenteye.event.*` 调用，事件会在本地缓冲。
+- **agenteye-collector**：部署在每台 agent 机器上的轻量级守护进程，负责批量打包事件并传输至服务器。
+- **服务器**：接收您的事件，在您自有数据库中维护运营状态，并提供仪表板、CLI 及您自定义集成所使用的 REST API。
+- **仪表板**：您浏览一切数据的地方。
+- **可选服务**：评分服务（评估）和 AI 助手服务（仪表板内聊天）。
+
+有关文档中使用的术语（*事件、会话、评估、审计、发现、事件*），请参阅[概念](/zh/agenteye/concepts)。
+
+---
+
+## 获取 Failproof AI Observability
+
+Failproof AI Observability 是 Failproof AI 的企业级产品，与 Failproof AI Enforcement（策略与护栏产品）同属 Failproof AI 品牌，并可协同使用。它完全运行在您自己的环境中。如果您尚未获得软件包访问权限，请申请演示，我们将为您完成配置：发送邮件至 [nikita@befailproof.ai](mailto:nikita@befailproof.ai)。
+
+---
+
+## 后续步骤
+
+- [概念](/zh/agenteye/concepts)：Failproof AI Observability 术语的集中说明。
+- [可观测性](/zh/agenteye/observability)：逐次追踪您 agent 的行为。
+- [安全性](/zh/agenteye/security)：Failproof AI Observability 如何确保您的数据隔离并保持在您的掌控之下。

package/.next/standalone/docs-old/zh/agenteye/python-sdk-skill.mdx

@@ -0,0 +1,131 @@
+---
+title: "Failproof AI Observability Python SDK Agent Skill"
+description: "从未插桩的 Agent 到可观测的事件——让你的编码 Agent 找到插桩点、完成编写并验证落地。"
+---
+
+告诉你的编码 Agent *"为这个 Agent 添加 Failproof AI Observability"*，让它读取你的循环逻辑，找出插桩位置，完成编写，并在宣告任务完成之前验证事件是否正常产生。
+
+**Python SDK skill**（`agenteye-python-sdk`）是一个 *Agent Skill*：一个包含指令的文件夹，当任务与之匹配时，Claude Code 或 Codex 等编码 Agent 会按需加载它。它教会 Agent 使用 [Python SDK](/zh/agenteye/python-sdk)——它本身不是一个库，也不会改变 SDK 的任何工作方式。
+
+## 插桩容易写，也容易悄无声息地出错
+
+SDK 很小巧：十三个事件方法，全部仅支持关键字参数。编码 Agent 读完 [Python SDK](/zh/agenteye/python-sdk) 参考文档，一分钟内就能写出看似合理的插桩代码。
+
+问题在于，这个 SDK 在你出错时不会抛出异常，而错误的插桩和正确的插桩看起来一模一样——直到有人打开仪表板，发现什么都没有。真正浪费时间的错误都是「沉默型」的：
+
+| 错误类型 | 你看到的现象 |
+|---|---|
+| 缺少 `agent_start` | 每个事件都落地，零个 session。 |
+| 环境变量从未设置 | 一切正常运行，但都归档在 `dev` 下。 |
+| `outcome="failure"` | 运行显示绿色——只有 `failed`、`error`、`timeout`、`rejected` 才会被计入。 |
+| 字段名拼写错误 | 被接受并存储为新字段。 |
+| 从线程池中发送事件 | 被静默丢弃。 |
+
+这些错误都不会抛出异常，也不会在测试中暴露。每一种都已在 skill 中说明，并以合约形式附上对应的检测方法。
+
+## 它的执行步骤
+
+该 skill 会执行经验丰富的工程师会做的三个步骤：
+
+1. **规划。** 读取你的 Agent 循环，并提出只有你能回答的两个问题：什么算作一次运行（你的 `session_id`），以及哪些是可区分的执行者（你的 `agent_id`）。它会在开始写代码之前就这些问题达成共识，因为事后修改会导致历史数据分裂，趋势图也会随之断裂。
+2. **编写。** 在每次运行时绑定一次身份，而不是在每个调用点都传递一遍；并选择并发安全的实现方式——这一点很重要，因为看似简便的做法会悄悄地将两个并发运行混入同一个 session，而且毫无提示。
+3. **验证。** 运行你的 Agent，读取生成的事件文件，检查 `agent_start` 是否存在、环境是否正确、一次运行是否对应一个 session。
+
+第三步是人们最常跳过的。SDK 将事件写入本地文件，因此完整的集成可以在笔记本电脑上、无需服务器、无需 API 密钥、无需网络的情况下得到验证——这正是该 skill 坚持执行这一步的原因。
+
+## 它与其他 skill 的关系
+
+三个 skill，职责清晰划分：
+
+| Skill | 适用场景 | 操作范围 |
+|---|---|---|
+| **Python SDK skill**（本页） | 你想让 Agent *发出*遥测数据——"添加可观测性"、"为什么我的 Agent 没有出现？" | 在你 Agent 的代码仓库中写代码，不读取任何内容。 |
+| **[Evaluator skill](/zh/agenteye/evaluator-skill)** | 你想对运行结果*评分*——"我们到底该衡量什么？" | 在你的代码仓库中写代码；读取遥测数据。 |
+| **[CLI skill](/zh/agenteye/cli-skill)** | 你想*读取*发生了什么，或者操作你的部署 | 以你的身份驱动 CLI，包括变更操作。 |
+
+它们按顺序衔接：本 skill 让事件开始流动，evaluator 对其评分，CLI 读取结果。在你的 Agent 发出 session 之前，没有任何内容可评估，也没有任何内容可读取——所以如果你从零开始，就从这里开始。
+
+## 前置条件
+
+1. **Python 3.10+** 以及你想要插桩的 Agent 代码库。
+2. **SDK。** 它以私有 wheel 包的形式分发给客户，而非通过公共索引——你的入门指南会介绍如何获取和安装它。该 skill 知道安装路径，如果找不到，会向你询问，而不是自行猜测。
+3. **无需其他任何东西。** 不需要登录仪表板、不需要 API 密钥、不需要网络。该 skill 通过 SDK 写入的事件文件进行验证，因此可以在离线状态下完成工作并证明其有效性。
+
+## 获取方式
+
+该 skill 位于公开的 [`FailproofAI/skills`](https://github.com/FailproofAI/skills) 集合中：
+
+```bash
+npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code
+```
+
+添加 `-g` 可以为所有项目安装，而不仅限于当前项目；如果你的环境不支持符号链接，请添加 `--copy`。对于 Codex，请传入 `-a codex`。
+
+## 手动安装
+
+Agent Skill 是包含 `SKILL.md` 及相关引用文件的文件夹。如果你不想使用安装程序：
+
+- **Claude Code**：将 `agenteye-python-sdk/` 文件夹复制到 `~/.claude/skills/`（适用于所有项目）或 `<your-repo>/.claude/skills/`（仅适用于该仓库）。Claude Code 会自动发现它——查看 `/skills` 列表，或者直接提问一个与之匹配的问题。
+- **Codex**：Codex 读取相同的 `SKILL.md`。捆绑的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时会自动选中；否则可以通过 `$agenteye-python-sdk` 显式调用。
+
+**在包含你想要插桩的代码的仓库中**运行你的 Agent——该 skill 在提出任何建议之前会先读取你的 Agent 循环。
+
+## 一次对话示例
+
+```text
+you   ▸ Add Failproof AI Observability to this agent.
+
+agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic
+        wrapper in llm.py. Two questions before I write anything.
+
+        What counts as one run? You handle requests concurrently, so I'd
+        use the request id you already have in ctx.request_id — then a
+        session here and a request in your logs are the same string.
+
+        And who are the actors? I see a planner path and a researcher
+        path. Label them separately, or is that one agent to you?
+
+you   ▸ Request id is right. They're one agent, call it "assistant".
+
+agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and
+        agent_end bracket handle_request, including the error path. Used
+        a context-local for identity — your dispatcher runs tools in a
+        thread pool, and the simpler approach would have mixed concurrent
+        runs into one session without complaining.
+
+        Verified against a real run: 11 events across 4 files —
+        agent_start, model_request/response, tool_use/tool_result x3,
+        agent_end (outcome=success). environment=production, one session
+        per request, durations paired.
+
+        One thing I did NOT do: your worker pool in batch.py submits
+        straight to the executor, so events from there would be dropped.
+        Want me to fix those too?
+```
+
+值得关注的模式：它在提出建议之前先读取了代码，只问了你才能回答的问题，复用了你已有的 ID，*因为*看到了线程池而选择了并发安全的实现方式，并且通过**读取实际事件**来验证，而非直接宣告成功——然后还指出了那个已知会悄悄失败的地方。
+
+## 你可以问它什么
+
+- *"为什么我的 Agent 没有出现在仪表板上？"* → 逐层排查：事件是否在写入，`agent_start` 是否存在，环境是否正确，采集器是否在读取同一个位置。
+- *"所有数据都落在 dev 下。"* → 环境变量从未设置，或被后续调用重置了。
+- *"添加 token 追踪。"* → 找到你的 LLM wrapper，记录模型、停止原因和用量。
+- *"也为子 Agent 插桩。"* → 同一个 session，不同的 Agent 标签，嵌套在各自的父级下。
+- *"为插桩代码编写测试。"* → 将 SDK 指向一个临时目录，并对写入的事件进行断言。
+
+## 注意事项
+
+**让它执行验证。** 让这个 skill 物有所值的正是最后一步——运行你的 Agent 并读取事件。一个写完插桩就停下来的 Agent 只做了容易的那一半，而悄悄失败的恰恰是另一半。
+
+**在写代码之前先确定命名。** `session_id` 和 `agent_id` 是所有视图分组的轴。事后重命名会导致历史数据分裂：旧的运行保留旧标签，趋势图随之断裂。该 skill 会主动询问；这个问题值得花一分钟认真思考。
+
+**如果你的 Agent 提议从公共索引安装 SDK，说明 skill 没有加载。** SDK 是私有分发的。这个提议是一个可靠的信号，表明你的编码 Agent 在凭空猜测而非遵循 skill——在那里停下来，检查 skill 是否已正确安装。
+
+除此之外，它的影响范围很小：它在你的工作目录中写代码，在你指定的位置写事件文件。它不读取你的部署内容，也不对其做任何修改。
+
+## 下一步
+
+- **[Python SDK](/zh/agenteye/python-sdk)**：完整的事件参考——本 skill 所自动化的每种事件类型和字段。
+- **[Sessions](/zh/agenteye/sessions)**：事件落地后，你的插桩所产生的内容。
+- **[Evaluator Agent Skill](/zh/agenteye/evaluator-skill)**：运行数据开始积累后的下一步——对其评分。
+- **[CLI Agent Skill](/zh/agenteye/cli-skill)**：读取你的遥测数据。