★ FEATURED ARTICLE 开发工具Agent TracesAI 应用【免费下载链接】cli Entire CLI hooks into your Git workflow to capture AI agent sessions as you work. Sessions are indexed alongside commits, creating a searchable record of how code was written in your repo.项目地址https://gitcode.com/gh_mirrors/cli411/cli点击查看免费下载本指南讲解如何利用 E2E 测试套件自动捕获的产物Artifacts来诊断 Entire CLI 的缺陷。这些产物在每次运行时写入e2e/artifacts/也可以从 CIGitHub Actions下载掌握它们的目录结构、每个文件承载的信息以及标准排查步骤你就能从「测试失败」快速定位到「CLI 哪个环节出错」最终判断问题是真实 Bug、测试自身的 flaky还是 Agent 行为不确定。读完本文你将具备一套可复现的、从产物到根因的完整调试能力。1. 调试输入从哪两类目录开始用户提供的调试入口通常有两种形态对应的排查策略完全不同测试运行目录e2e/artifacts/{timestamp}/—— 用于批量 triage 一次运行中的所有失败。这种目录由本地运行或 CI 下载产生其顶层包含报告文件、测试事件流与版本信息。单个测试目录e2e/artifacts/{timestamp}/{TestName}-{agent}/—— 用于聚焦调试某一个测试例如TestSingleSessionManualCommit-claude-code。目录名由测试名与 Agent 名拼接而成测试名中的/会被替换为-见 e2e/testutil/artifacts.go 中的artifactDir实现。需要 CI 产物时可以直接通过 scripts/download-e2e-artifacts.sh 下载三种入参scripts/download-e2e-artifacts.sh latest # main 上最近一次失败的 E2E 运行 scripts/download-e2e-artifacts.sh 12345678 # 数字 run ID scripts/download-e2e-artifacts.sh RUN_URL # GitHub Actions 运行 URL脚本依赖ghCLI 且要求已认证它会用gh run download拉取产物并把e2e-artifacts-agent/包装目录扁平化为agent/同时写入.run-info.json包含run_id、run_url、commit、agents。stdout 的最后一行是下载目录的绝对路径请捕获它作为后续分析的产物根目录。2. Artifact 布局一次失败留下的完整现场无论本地还是 CI一次 E2E 运行结束后产物目录的标准结构如下e2e/artifacts/{timestamp}/ ├── report.nocolor.txt # 通过/失败/跳过汇总含错误行file:line 引用 ├── test-events.json # 原始 Go 测试事件NDJSON ├── entire-version.txt # 被测 CLI 版本 └── {TestName}-{agent}/ ├── PASS or FAIL # 状态标记文件 ├── console.log # 完整操作转录 ├── git-log.txt # git log --decorate --graph --all ├── git-tree.txt # ls-tree HEAD checkpoint 分支 ├── entire-logs/entire.log # CLI 结构化 JSON 日志 ├── checkpoint-metadata/ # Checkpoint Session 元数据 └── repo - /tmp/... # 指向保留仓库的符号链接仅 E2E_KEEP_REPOS1这些文件各自对应着 e2e/testutil/artifacts.go 中CaptureArtifacts的捕获逻辑git-log.txt抓取git log --decorate --graph --allgit-tree.txt抓取ls-tree -r HEAD并拼接 checkpoint 引用git-branch 后端为entire/checkpoints/v1git-refs 后端为for-each-ref枚举refs/entire/checkpoints/前缀下的全部引用两者以--- 引用名 ---分隔PASS/FAIL空文件标记测试最终状态随后依次调用captureCheckpointMetadata、captureEntireLogs和captureAgentArtifacts。几个值得注意的实现细节console.log是增量写入磁盘的RepoState持有*os.File见 e2e/testutil/repo.go因此即使测试因全局超时被杀转录依然完整存活。entire-logs/的内容来自被测仓库内的.entire/logs/目录见 e2e/testutil/artifacts.go逐文件复制进产物目录。captureAgentArtifacts会把 Agent 通过ArtifactCollector接口声明的额外产物如隔离 HOME 中 Agent 自己的日志目录复制进来使「Agent 进程内部的 CI 失败」仅凭产物即可诊断。关于report.nocolor.txt与test-events.json的产生方式mise run test:e2e任务用gotestsum --format dots --rerun-fails1生成test-events.json再用 e2e/cmd/testreport/main.go 渲染出report.txt带 ANSI 颜色与report.nocolor.txt剥离颜色后的纯文本供终端与脚本阅读。entire-version.txt由各测试包的TestMain在 preflight 阶段写入被测二进制与版本信息见 e2e/tests/main_test.go。3. Preserved Repo最强力的调试工具当测试运行设置了E2E_KEEP_REPOS1时每个测试的产物目录里会多出一个repo符号链接指向被保留的临时 git 仓库实际实现是os.Symlink(repoDir, artifactDir/repo)见 e2e/testutil/artifacts_unix.goWindows 构建标签下不生成该链接。请通过符号链接导航如{artifact-dir}/repo/而不是自行解析/tmp/...绝对路径——链接位于产物目录内部权限与路径语义保持一致。保留的仓库包含完整的 git 历史与所有分支main、entire/checkpoints/v1或 git-refs 下的 per-checkpoint 引用.entire/目录CLI 的状态、配置与原始日志.claude/目录当 Agent 是 Claude Code 时Agent 创建或修改的全部文件最终状态在此目录中你可以直接执行git log、git diff、git show检查.entire/内部结构亲眼看到 CLI 在仓库里留下了什么——这是「产物对比」之外唯一能拿到完整可变状态的手段。对应地环境变量E2E_KEEP_REPOS的控制点在 e2e/testutil/repo.go置为非空时临时目录不被清理日志会提示E2E_KEEP_REPOS: repo will be preserved at dir。4. 调试工作流六步从失败到根因4.1 第一步Triage拿到运行目录时读取report.nocolor.txt识别失败项与其错误信息。每一条目包含测试名、Agent、耗时与带file:line引用的失败输出。该报告还自动生成「重跑失败测试」的命令清单Rerun failed tests: mise run test:e2e --agent claude-code TestSingleSessionManualCommit这是 e2e/cmd/testreport/main.go 的固定行为只要存在失败就按失败的 (test, agent) 组合输出可直接执行的复跑命令。4.2 第二步阅读 console.log最重要console.log是每一次操作的完整转录按时间顺序记录了 claude -p ... ...—— Agent 提示词及其 stdout/stderr git add/commit/...—— git 命令 send: ...—— 交互式会话的输入写入逻辑集中在 e2e/testutil/repo.goRunPrompt记录 command及 stdout/stderrGit记录 git argsSend记录 send: inputWaitFor完成后还会追加 pane after WaitFor(...)的 tmux 面板内容。它回答「实际上发生了什么」这个问题。4.3 第三步阅读测试源码利用 report 中的file:line引用在e2e/tests/下找到对应测试。重点理解测试期望发生什么对照console.log中实际发生什么。注意测试运行在两种 checkpoint 后端之上git-branch单分支拓扑与git-refsper-checkpoint 引用拓扑部分断言会随后端不同而解析方式不同见 e2e/testutil/backend.go 中checkpointBlobSpec的实现阅读时留意testutil.UsingGitRefs()的守卫分支。4.4 第四步诊断 CLI 行为交叉比对console.log实际发生与测试应当发生聚焦 CLI 层面的问题。常见症状与对应的调查方向如下表症状CLI 调查方向Checkpoint 未创建 / 超时检查entire-logs/entire.log中的 hook 调用、阶段转换、错误Checkpoint 内容错误检查git-tree.txt中 checkpoint 分支的文件、checkpoint-metadata/中的 session 信息Hook 未触发检查entire-logs/entire.log是否缺少 hook 条目session-start、user-prompt-submit、stop、post-commitStash/unstash 问题检查entire-logs/entire.log中 stash 相关日志行、git-log.txt中的提交顺序文件追踪问题检查checkpoint-metadata/与 session 元数据中的files_touchedStrategy 不匹配检查entire-logs/entire.log的strategy字段核对 auto-commit 与 manual-commit 行为4.5 第五步深度挖掘文件entire-logs/entire.log结构化 JSON 日志覆盖 hook 生命周期、session 阶段转换active-idle-ended、警告与错误。关键字段component、hook、strategy、session_id。其中component字段由 cmd/entire/cli/logging/context.go 的WithComponent注入用于标识产生日志的子系统如hooks、strategy、session并由 cmd/entire/cli/logging/logger.go 附加到每条日志上——这是你能按子系统过滤日志的机制基础。git-log.txt提交图展示 main 分支、entire/checkpoints/v1或refs/entire/checkpoints/引用、checkpoint 初始化。git-tree.txtHEAD 与 checkpoint 分支的文件对比由--- entire/checkpoints/v1 ---分隔。git-refs 后端下该分隔线改为--- refs/entire/checkpoints/ ---并以for-each-ref --format%(refname) %(objectname)输出见 e2e/testutil/artifacts.go。checkpoint-metadata/metadata.json包含checkpoint_id、strategy、files_touched、token_usage和sessions数组session 子目录保存每个 session 的独立细节。其字段结构可直接对照 e2e/testutil/metadata.go 中的CheckpointMetadata、SessionRef与SessionMetadata定义——例如TokenUsage细分了input_tokens、cache_creation_tokens、cache_read_tokens、output_tokens、api_call_countSessionMetadata还带checkpoint_transcript_start字段标记该 checkpoint 在 transcript 中的起始偏移。4.6 第六步汇报发现判断问题归属并据此决定修复方向CLI hooksprepare-commit-msg、commit-msg、post-commitSession 管理阶段转换、session 追踪Checkpoint 创建分支管理、元数据写入文件追踪files touched、prompt 关联Strategy 逻辑auto-commit 与 manual-commit 行为5. 判定归属real-bug 还是 flaky完成上述六步后需要给出明确的分类结论这决定了后续动作。完整的判定流程定义在 .claude/skills/e2e/triage-ci.md 中核心原则是复跑结果是首要信号产物分析用于补充证据。强 real-bug 信号根因必须落在cmd/entire/cli/而非e2e/entire.log出现level:ERROR或来自 CLI 代码的 panic/堆栈Checkpoint 元数据结构性损坏JSON 畸形、缺少checkpoint_id/strategy预期存在的 session 状态文件缺失或畸形Hook 完全没有触发无hook invoked日志条目shadow/元数据分支树结构错误同一测试在 3 个以上 Agent 上以相同非超时症状失败错误指向 CLI 代码如cmd/entire/cli/中的 panic强 flaky 信号Agent 行为不确定signal: killed超时、context deadline exceeded、WaitForCheckpoint.*exceeded deadline、Agent 要求确认而非执行、文件写错路径/名称、Agent 未产生输出、不该提交时提交或反之、耗时接近超时上限测试自身 BugAgent Not logged in / 认证错误环境未传播认证凭据、环境变量未传入 Agent 会话tmux/测试脚手架 Bug、错误指向e2e/测试代码、断言/glob/期望值错误、测试搭建与清理问题git 配置缺失、临时目录清理、端口冲突边界情况的裁决仔细读entire.log——若 hook 正常触发且元数据有效倾向于 flaky若 hook 触发了但产生错误结果倾向于 real-bug。跨 Agent 相关性同一测试 3 Agent 复跑全部失败 → 强 real-bug多 Agent 失败但复跑通过 → flaky共享提示词问题单一 Agent 持续失败而其他通过 → Agent 专属问题复跑确认后仍算 real-bug。汇报时每个 testagent 对给出 findings 块格式如下## TestName (agent) -- classification **Re-run results:** originalFAIL, rerun1PASS, rerun2PASS **Evidence:** - 1-2 句失败摘要 - 关键产物证据entire.log 摘录、console.log 摘录等flaky 附带 proposed fix文件 改动描述real-bug 附带 root cause analysisComponent / Suspected location / Description / Proposed fix。常见 flaky 修复套路包括给提示词追加 Do not ask for confirmation、明确文件路径、加 Do not commit、增大WaitForCheckpoint超时、增大 per-test 超时、修正e2e/脚手架的环境传播等。6. 让现场更完整的实践建议复现时固定后端E2E_CHECKPOINT_STOREgit-branch/git-refs会映射为ENTIRE_CHECKPOINTS_PRIMARY并传递给每个子进程见 e2e/tests/main_test.go。调试时保持与失败运行相同的后端否则git-tree.txt的分隔线与checkpoint-metadata/的读取路径in-tree 前缀 vs 引用根目录都会改变。保留仓库诊断需要查看可变状态时用E2E_KEEP_REPOS1复跑仅看产物即可判断时无需开启避免堆积临时目录。不要盲跑 E2E真实 E2E 测试消耗 API token 并产生费用e2e/README.md 明确要求非必要不主动运行。优先分析已有产物确需复跑时用mise run test:e2e --agent agent TestName收敛范围并留意任务输出的artifacts: path行以定位新产物目录。结合 Agent 侧证据产物中的 Agent 附加文件如 Copilot 的COPILOT_HOME日志、Antigravity 的agy-hook-probe.log能区分「hook 未执行」与「hook 未加载」等微妙差异是判断 Agent 侧根因的关键。7. 小结Entire CLI 的 E2E 产物体系把一次失败运行「冻结」成可离线分析的完整现场report.nocolor.txt告诉你谁失败了、console.log告诉你发生了什么、git-log.txt与git-tree.txt告诉你仓库里留下了什么、entire.log告诉你 CLI 内部每个 hook 与阶段的状态、checkpoint-metadata/告诉你 checkpoints 与 sessions 的最终数据而E2E_KEEP_REPOS1保留的repo符号链接则把完整的可变状态交到你手里。按「Triage → console.log → 测试源码 → CLI 行为 → 深度文件 → 汇报」六步走配合复跑判定就能把大多数失败高效地归类为真实 Bugcmd/entire/cli/或 flakye2e/测试/Agent 行为并为每一类给出可执行的修复路径。赞分享开发工具Agent TracesAI 应用【免费下载链接】cli Entire CLI hooks into your Git workflow to capture AI agent sessions as you work. Sessions are indexed alongside commits, creating a searchable record of how code was written in your repo.项目地址https://gitcode.com/gh_mirrors/cli411/cli点击查看免费下载相关推荐Positron e2e 测试调试完全指南基于 debug-e2e-test 技能的失败归因与修复工作流Positron e2e 测试调试完全指南基于 debug e2e test 技能的失败归因与修复工作流 本篇技术指南以 Positron 仓库中的 .cla开发工具代码编辑器数据科学Chat2DB用自然语言查数据的开源数据库客户端与SQL工作区Chat2DB用自然语言查数据的开源数据库客户端与SQL工作区 业务方周一上午要一份季度销售数据你得先从五张表里拼出连表查询字段名还得逐个核对半小时就这数据库客户端AI 应用数据分析edgenext_base.in21k_ft_in1k与传统CNN/Transformer对比15.6M激活值带来的性能飞跃edgenext_base.in21k_ft_in1k与传统CNN/Transformer对比15.6M激活值带来的性能飞跃 edgenext_base.in上一篇folium 图标Icon完全指南旋转图标、自定义图片图标与 DivIcon 文本标签下一篇Bitnami KeyDB Helm Chart 版本演进全解析从 0.1.0 到 0.5.x 的关键变更与安全实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
