CANNBot-Insight完全指南Next.js 16Prisma打造的AI编码代理会话可观测性工具【免费下载链接】cannbay2项目地址: https://ai.gitcode.com/guanxinghua/cannbay2本文是 CANNBot-Insight 的完整使用指南。CANNBot-Insight 是一款基于 Next.js 16 与 Prisma 构建的AI 编码代理会话可观测性工具它能把 Claude Code、OpenCode 等编码代理的完整会话记录采集、归一化并可视化帮你看清每一次 AI 调试到底发生了什么。1. 为什么你需要 AI 编码代理会话可观测性 如果你日常在用 AI 编码代理干活大概率遇到过这三种灵魂拷问任务为什么失败了Agent 跑了 40 分钟最后报错退出但它中间做过哪些决策、调过哪些工具谁也说不清。Token 花到哪去了账单上数字很惊人却不知道哪一轮对话把上下文塞爆、缓存命中又有多少。子代理在干什么Agent 派出的 subagent 像黑盒一样独立执行中途失败了你根本无从复盘。会话可观测性解决的就是这些问题把 AI 编码代理的黑盒执行过程变成可回放的监控录像。而 CANNBot-Insight 正是为这个场景打造的可观测性工具——它通过本地代理层拦截 LLM 请求记录每一轮对话的完整上下文、工具调用、token 用量和响应延迟再配合 Web 面板让你快速检索、回放和分析历史会话。一句话概括让每一次 AI 编码会话都留痕、可查、可复盘。2. CANNBot-Insight 能做什么2.1 全量会话记录每一轮对话turn都被完整记录用户输入、AI 回复、模型名称、时间戳、响应耗时、停止原因以及输入/输出 token 数和缓存命中量。会话数据以 JSONL 格式逐行存储一个文件对应一个会话天然适合流式写入和事后回放。2.2 子代理Subagent追踪现代编码代理会派出 subagent 并行执行子任务。CANNBot-Insight 会为每个 subagent 单独建档记录它的类型agentType、任务名称name和所属会话 ID让你能区分主会话做了什么和子代理干了什么定位长任务中的问题环节。2.3 多框架统一采集不同编码代理的会话格式各不相同。CANNBot-Insight 通过统一的元数据规范x_cannbay字段把它们归一化Claude Code、OpenCode 等不同框架的会话都能落到同一套数据结构里用producer字段区分来源如 insight-export、cpx 等。2.4 Web 可视化与检索基于 Next.js 16 的 Web 面板 Prisma 数据层把大体量的会话记录变成可查询、可统计的数据——按模型、时间、会话 ID 快速定位问题会话分析 token 消耗趋势。3. 技术栈Next.js 16 Prisma 如何协作CANNBot-Insight 的架构可以用一句话讲清采集靠代理存储靠 JSONL查询靠 Prisma展示靠 Next.js。组件角色本地 LLM 代理拦截编码代理与模型服务之间的流量采集每一轮请求/响应JSONL 会话文件逐行追加的结构化日志一个会话一个文件容错且易回放Prisma将会话元数据映射到关系数据库支撑快速检索与统计Next.js 16提供 Web 可视化面板展示会话列表、对话回放与用量指标这种文件为主、数据库为辅的设计很务实原始日志用轻量的 JSONL 落地即使体量达到几十 MB 也不会丢数据而需要频繁查询的元信息交给 Prisma 建索引兼顾了可靠性与查询性能。4. 会话数据结构速览CANNBot-Insight 的数据目录遵循清晰的组织规则理解它有助于你手动导出数据目录结构sessions/ └── 会话ID/ ├── 会话ID.jsonl # 主会话对话日志 ├── 会话ID.meta.json # 会话元数据 └── subagents/ # 子代理记录如有 ├── subagentID.jsonl └── subagentID.meta.json元数据里都有什么以一份会话的.meta.json为例x_cannbay字段包含schema/version元数据规范与版本如cc-session-metaproducer数据来源insight-export 表示经 Insight 代理采集cpx 表示第三方客户端导出framework编码代理框架如opencode、claude-codeccVersion框架版本号sid会话唯一 ID每一行 JSONL 日志中assistant 消息还会携带 token 用量usage、响应耗时duration_ms和停止原因stopReason这些正是做用量分析和性能复盘的关键字段。5. 快速开始5 分钟跑通 CANNBot-Insight前置条件Node.js 18 或更高版本一个本地可用的数据库Prisma 连接目标至少一个在用的编码代理如 OpenCode、Claude Code步骤一克隆仓库git clone https://gitcode.com/guanxinghua/cannbay2.git步骤二安装依赖并配置环境cd cannbay2 npm install cp .env.example .env # 填入数据库连接串等配置步骤三初始化数据库npx prisma migrate dev步骤四启动服务npm run dev启动后打开本地 Web 面板把编码代理的模型端点指向 CANNBot-Insight 提供的本地代理地址之后的每一次会话就会被自动记录下来面板中即可检索和回放。6. 典型使用场景 ️失败任务复盘长任务中途失败时按会话 ID 回放完整对话定位 AI 在哪一步走偏。成本分析统计各模型、各会话的 token 消耗与缓存命中率找到开销最大的使用模式。子代理审计查看 subagent 的执行轨迹确认并行子任务是否按预期完成。团队共享借助 Git LFS 管理大体量会话文件仓库已对多种二进制格式启用 LFS 跟踪方便把典型会话归档进代码库做经验沉淀。7. 常见问题 FAQ支持哪些编码代理通过framework字段可见已覆盖 OpenCode、Claude Code 等主流框架且多框架统一走同一套x_cannbay元数据规范。会话数据存在哪默认在本地sessions/目录下按会话 ID → JSONL meta subagents组织数据库层由 Prisma 管理索引信息原始数据始终可离线回放。大体量会话几十 MB怎么处理JSONL 是追加式日志写入开销低归档或上传时由 Git LFS 托管避免仓库被大文件拖垮。8. 总结CANNBot-Insight 用Next.js 16 Prisma这套现代技术栈把 AI 编码代理的会话黑盒变成了透明可查的观测面板全量轮次记录、子代理追踪、多框架统一采集、用量与延迟指标一个工具全包。如果你正在高频使用 AI 编码代理不妨花 5 分钟跑通它——下次任务再莫名失败时你手里就有完整的监控录像可以复盘了。【免费下载链接】cannbay2项目地址: https://ai.gitcode.com/guanxinghua/cannbay2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考