# retention.sh：AI编程代理的始终在线工作流裁判系统

> 一个为AI编码代理设计的质量保障系统，通过四个始终在线的钩子（会话恢复、工作流检测、工具追踪、完成拦截）来捕获遗漏步骤、验证执行质量，并支持工作流回放以降低成本。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-09T23:40:42.000Z
- 最近活动: 2026-04-09T23:46:25.558Z
- 热度: 156.9
- 关键词: AI agent, workflow, QA, quality assurance, replay, cost optimization, OpenAI, Anthropic, LangChain, CrewAI, MCP
- 页面链接: https://www.zingnex.cn/forum/thread/retention-sh-ai
- Canonical: https://www.zingnex.cn/forum/thread/retention-sh-ai
- Markdown 来源: ingested_event

---

# retention.sh：AI编程代理的始终在线工作流裁判系统\n\n## 项目背景：AI代理的可靠性困境\n\n随着AI编程代理（如Claude Code、Cursor Composer等）的普及，开发者们逐渐意识到一个令人头疼的问题：代理经常"自信地犯错"。它们会声称任务已完成，但实际上跳过了测试、遗漏了关键步骤，或者忽略了重要的上下文信息。\n\nretention.sh项目正是为解决这一问题而生。它自称为"始终在线的工作流裁判"（always-on workflow judge），通过系统化的方式捕获AI代理遗漏的步骤，并在问题发生前进行拦截。\n\n## 核心定位：看见代理真正遗漏的东西\n\nretention.sh的核心理念可以用一句话概括："你的代理说'完成了'，retention.sh会展示它跳过的测试、遗忘的步骤和缺失的上下文——然后阻止这种情况再次发生。"\n\n这不是一个简单的日志记录工具，而是一个具有判断能力的质量保障系统。它会对代理的执行给出硬性裁决：通过（PASS）、失败（FAIL）或被拦截（BLOCKED）。\n\n## 三大核心功能\n\nretention.sh围绕三个核心功能构建，每个功能都针对AI代理使用中的具体痛点：\n\n### 1. 质量检查：看见代理做了什么、遗漏了什么\n\n这是系统的基础功能。retention.sh会全面追踪代理的执行过程，识别出：\n\n- 代理实际执行了哪些步骤\n- 哪些步骤被跳过或遗漏\n- 代理是否应该继续执行\n\n最终输出一个硬性裁决结果，让用户清楚地知道代理的工作质量。\n\n### 2. 工作流回放：降低成本的可复现执行\n\n这是retention.sh最具创新性的功能之一。系统可以捕获一次"昂贵"的工作流执行，然后在后续以60-70%的低成本进行回放。\n\n关键在于，系统配备了一个"严格裁判"（strict judge）来验证回放是否真正有效。这意味着用户不需要重复支付高昂的API费用来执行相同的工作流，同时又能确保结果的正确性。\n\n### 3. 完整追踪：可共享的执行证据链\n\nretention.sh提供每个工具调用的完整追踪，包括：\n\n- 屏幕截图\n- 执行证据\n- 每步成本分析\n\n这些追踪可以生成可分享的链接，方便团队成员查看代理实际做了什么、什么被跳过。\n\n## 四大始终在线的钩子机制\n\nretention.sh通过四个关键钩子实现其功能，这些钩子在代理执行的整个生命周期中始终运行，且无法被代理绕过：\n\n### on-session-start：会话启动钩子\n\n当新的代理会话开始时，这个钩子会恢复之前未完成的工作。它记住了什么工作被遗留，确保代理不会重复造轮子或遗漏上下文。\n\n### on-prompt：提示检测钩子\n\n在代理开始工作前，这个钩子会检测工作流类型，并在代理开始前注入必需的步骤。这确保了代理从一开始就遵循正确的流程。\n\n### on-tool-use：工具使用钩子\n\n每个工具调用都会被作为证据进行追踪。如果检测到步骤缺失，系统会发出提示。这种实时监控确保了代理不会偏离预定路径太远。\n\n### on-stop：完成拦截钩子\n\n这是最后的"大门"。如果强制性步骤尚未完成，这个钩子会拦截代理的完成声明，阻止其标记任务为"已完成"。\n\n## 多平台SDK支持\n\nretention.sh提供了广泛的SDK支持，可以集成到各种AI代理框架中：\n\n- **OpenAI**：原生支持OpenAI API调用追踪\n- **Anthropic**：支持Claude系列模型的追踪\n- **OpenAI Agents SDK**：专为OpenAI Agents设计\n- **LangChain**：支持LangChain框架集成\n- **CrewAI**：支持CrewAI多代理框架\n- **Claude Agent SDK**：支持Claude Agent SDK\n\n使用方式非常简单，只需一行代码：\n\n```python\nfrom retention import track\ntrack()  # 自动检测已安装的provider\n```\n\n或者指定特定provider：\n\n```python\ntrack(providers=[\"openai\", \"anthropic\"])\n```\n\n## 隐私保护的事件追踪\n\nretention.sh在追踪代理活动的同时，非常注重隐私保护。每个代理动作都会产生结构化的事件记录：\n\n```json\n{\n  \"event_type\": \"tool_call\",\n  \"tool_name\": \"bash\",\n  \"input_keys\": [\"command\"],\n  \"scrubbed_input\": {\"command\": \"[140c]\"},\n  \"timestamp\": \"2026-04-08T14:30:00\",\n  \"runtime\": \"anthropic\",\n  \"duration_ms\": 1200\n}\n```\n\n系统自动清理敏感数据：API密钥、令牌、密码、文件路径等。用户获得遥测数据的同时不会泄露机密信息。所有数据默认存储在本地`~/.retention/activity.jsonl`文件中。\n\n## 内置工具集\n\nretention.sh提供了一系列实用的内置工具：\n\n- **retention.qa_check(url)**：即时QA扫描，检测JS错误、可访问性问题、渲染问题\n- **retention.sitemap(url)**：带屏幕截图的交互式站点地图\n- **retention.diff_crawl(url)**：前后对比爬取\n- **retention.start_workflow(url)**：智能启动——如有保存的轨迹则自动回放\n- **retention.team.invite**：跨团队共享工作流记忆\n\n## 实际效果数据\n\n根据项目提供的真实数据（经过独立LLM裁判验证）：\n\n| 指标 | 结果 |\n|------|------|\n| 回放成本节省 | 63-73% |\n| 裁判一致率 | 89% |\n| 测试的工作流家族 | 3个 |\n| 使用retention.sh后需要的修正 | 0次 |\n\n这些数据表明，retention.sh不仅能显著降低成本，还能有效提高工作流的可靠性。\n\n## 团队协作功能\n\nretention.sh支持团队共享工作流记忆。通过简单的团队代码机制，团队成员可以：\n\n```bash\n# 人员A创建团队 -> 获得代码：K7XM2P\nretention.team.invite\n\n# 人员B使用团队代码加入\nRETENTION_TEAM=K7XM2P curl -sL retention.sh/install.sh | bash\n```\n\n这种设计让团队能够建立共享的质量标准和最佳实践。\n\n## 技术架构\n\nretention.sh采用多组件架构：\n\n- **backend/**：FastAPI后端（Python），包含API路由、代理和服务\n- **packages/retention-cli/**：CLI工具（npm）\n- **packages/retention-mcp/**：MCP服务器（TypeScript）\n- **packages/retention-sdk/**：Python SDK，包含7个provider包装器\n- **packages/tcwp/**：轨迹/检查点/工作流包\n- **frontend/**：React + Vite + Tailwind仪表板\n\n## 适用场景\n\nretention.sh针对三类主要用户群体：\n\n### 工程师\n\n痛点：代理总是跳过测试和搜索步骤。\n解决方案：捕获跳过的步骤，以更低成本回放重复工作流。\n\n### 团队负责人\n\n痛点：无法了解代理实际做了什么。\n解决方案：查看发生了什么、什么被遗漏、节省来自何处。\n\n### 创始人\n\n痛点：每次都手动重复昂贵的AI工作。\n解决方案：将重复工作转化为可复用的运营杠杆。\n\n## 安装与使用\n\nretention.sh的安装非常简单：\n\n```bash\n# 快速安装\ncurl -sL retention.sh/install.sh | bash\n\n# 然后使用\nretention.qa_check(url='http://localhost:3000')\n```\n\n或者通过pip安装Python SDK：\n\n```bash\npip install retention\n```\n\n## 结语\n\nretention.sh代表了AI代理质量保障领域的一个重要创新。它不仅提供了传统日志记录工具所缺乏的判断能力，还通过工作流回放功能实现了显著的成本优化。\n\n在AI代理从"实验性工具"走向"生产级基础设施"的过程中，像retention.sh这样的质量保障系统将扮演越来越重要的角色。对于依赖AI代理进行日常开发工作的工程师和团队来说，这是一个值得认真考虑的工具。\n\n项目的核心洞察是：AI代理需要的不只是更多的能力，还需要更好的监督和验证机制。retention.sh正是这种机制的一个有力实现。