AgentInspect（agent-inspect）是一个面向 TypeScript AI 智能体的本地优先证据调试与轨迹测试工具包。它的定位是让开发者看清智能体实际做了什么、在 CI 中拦截错误的工具路径，并把证据保留在本地。其核心思路是把智能体运行记录为本地 JSONL，并基于同一份轨迹完成三件事：调试、预防和共享。
用途与主要能力
调试：将嵌套步骤、工具调用、LLM 调用、模型与 token 元数据、耗时、错误以及首个因果失败以可读执行树的形式展示，无需把轨迹发送到 AgentInspect 服务。轨迹可通过手动埋点、官方适配器、受支持的标准文件或已有结构化日志获得。
预防：检查是确定性的、不依赖模型提供方，同一轨迹与规则始终产生相同结果。可从预设开始，再按工作流扩展期望规则。使用 --fail-on-observation failed 仅在运行记录了显式 OUTCOME 事件时生效；轨迹检查不会从工具、LLM 或运行成功中推断结果。检查通过退出码为 0，规则失败退出码为 1，无效配置与不可读或不支持的输入使用单独文档化的退出码。当需要多于一个 CLI 检查时，可使用 TraceContract、suites、cohorts、Vitest/Jest reporters 或 --evidence-on fail。
共享：verify-safe 是本地尽力评估，可给出 SAFE、SAFE WITH WARNINGS、UNSAFE 或 UNKNOWN；bundle 写入经过脱敏的产物与清单，bundle verify 在离线状态下重新校验清单中列出的文件哈希。“Share-checked” 不是合规认证，附加到 PR、事件或支持交接前应人工复核产物。
使用方式
先安装并初始化：npm install agent-inspect 不会复制仓库示例，init 会把它们写入项目。生成的是合成、无密钥、本地的演示。复制打印出的 run ID 后进行检查。官方还提供带稳定 run id（demo-good、demo-regression、demo-pii）的好/回归/PII 固定演示，以及覆盖特定框架路径的精选入门示例。
程序化轨迹检查 API 还暴露 TraceFacts，用于对受支持轨迹进行有界、逻辑分析，详见程序化轨迹分析文档。
适用场景与限制
AgentInspect 负责从笔记本电脑到 PR 的证据闭环，与托管可观测性、生产轨迹留存和广义评测平台互补，而非替代它们。它不面向以下用途：维护者托管的 SaaS 或生产 APM 替代、托管轨迹留存、团队仪表盘服务或提示注册表、默认的 LLM-as-judge 或数据集平台、回放引擎、自动修复系统或合规认证。它也不是思维链记录器。
安全与网络行为
轨迹是位于 .agent-inspect/ 或 AGENT_INSPECT_TRACE_DIR 下的本地 JSONL。采集默认仅元数据，原始提示与输出需显式启用。写入时脱敏默认开启；redact 命令创建单独的脱敏副本，不修改源文件。核心采集与检查不需要 AgentInspect 账户、采集器或默认上传。脱敏与 verify-safe 是尽力而为的控制，不是隐私、安全或合规认证。可选的 MCP、标准导出与客户自有 Studio 界面是显式的，各有自己的网络边界。
可选的编码智能体循环
@agent-inspect/mcp-server 通过有界、只读工具向 MCP 客户端暴露已配置的本地证据，属可选且当前为 Preview；核心调试/检查/证据循环不依赖它。启用前应查看生成的 dry-run 配置与编码智能体循环指南。根包已足够支持自定义采集、CLI、检查与 Evidence 工作流；仅为使用的集成或界面安装可选包。agent-inspect-vscode 目前位于仓库中，并非已发布的 Marketplace 扩展。
状态与文档
当前发布基线为 6.31.21，持久化 schema 1.0，Node.js 版本要求不低于 20，采用 MIT 许可。旧版 v0.1 与 v0.2 轨迹仍可读取，当前发布版本以 npm 徽章与 changelog 为准。在 issue 或 PR 中发布轨迹前，应先用 redact 脱敏并复核。
