ksek87/recut-ai

# recut-ai 当 AI agent 在生产环境中出现故障时，没有重播功能。你只能看到最终输出或账单，却不知道它出错的原因、何时开始出现偏差，或者如果第 4 步返回了不同的结果会发生什么。 recut 为你提供了这个重播按钮。只需使用一个装饰器包装任何 agent，即可获得五个原语：**peek**（查看）运行内部状态、在运行过程中 **intercept**（拦截）它、使用不同的输入从任意步骤 **replay**（重播）、**audit**（审计）完整追踪记录，或者使用自动生成的变体对其进行 **stress-test**（压力测试）。 适用于任何构建或负责 agent 的人员——工程师、AI 工程师、产品经理（PM）、分析师、合规团队。无需机器学习（ML）背景。 ## 安装 ``` pip install recut-ai ``` 针对特定框架的适配器（可选，按需安装）： ``` pip install recut-langchain # LangChain + LangSmith enrichment pip install recut-langgraph # LangGraph native interrupt/replay pip install recut-crewai # CrewAI before/after hooks pip install recut-otel # Universal OpenTelemetry adapter (AutoGen, Semantic Kernel, Datadog, Phoenix) pip install recut-langfuse # Langfuse behavioral scoring ``` ``` cp .env.example .env # add ANTHROPIC_API_KEY or OPENAI_API_KEY ``` ## 快速开始 ``` import recut @recut.trace(agent_id="my-agent", mode="peek") async def run_agent(prompt: str, ctx=None) -> str: async for step in ctx.provider.run_agent(prompt): ctx.add_step(step) return ctx.trace.steps[-1].content @recut.on_flag def handle_flag(event: recut.RecutFlagEvent): print(f"[{event.flag.severity}] {event.flag.plain_reason}") ``` ## CLI ``` recut run "prompt" # run and trace, defaults to peek mode recut peek # triage — surfaces high-risk steps only recut audit # full structured audit pass recut intercept "prompt" # pause mid-run when a high-severity flag fires recut replay --step 4 # fork from step 4, inject different context recut diff # side-by-side behavioral diff recut stress --variants 5 # stress-test with auto-generated variants recut export # export to .recut.json ``` ## 标志 每个标志都附带一个通俗的原因说明——团队中的任何人都能看懂，而不仅仅是工程师。 | 标志 | 含义 | |---|---| | `overconfidence` | Agent 表达了它并不具备的确定性 | | `goal_drift` | Agent 已经偏离了原始任务 | | `scope_creep` | Agent 做了远超要求的事情 | | `reasoning_gap` | Agent 未经充分推理即采取行动 | | `uncertainty_suppression` | Agent 隐藏或淡化了真实的不确定性 | | `instruction_deviation` | Agent 违背或忽略了原始指令 | | `anomalous_tool_use` | 工具使用异常、重复或缺乏合理依据 | | `reasoning_action_mismatch` | *（仅限 Claude）* 内部推理表达怀疑，而实际行动却表现自信 | 每个标志都会显示是由哪个层级触发的——`[rule]`、`[embedding]`、`[native]` 或 `[judge]`——因此你始终可以知道某个信号是确定性的还是由模型生成的。 ## 标志引擎 检测运行在四个层级中，按成本从低到高排列： 1. **基于规则（Rule-based）** —— 免费、即时、确定性 2. **Embedding 相似度** —— 与原始提示词的余弦距离（可选，`sentence-transformers`） 3. **原生思考分析** —— 仅限 Claude；直接读取扩展思考（extended thinking）块 4. **LLM judge** —— 默认通过任何兼容 OpenAI 的运行时（Ollama、LM Studio、Jan、llama.cpp、vLLM —— 按你喜欢的选）使用本地模型。数据不会离开你的机器，没有 API 费用。如果本地端点未运行，第 4 层将被静默跳过。带上你自己的 API 密钥（`RECUT_L4_BACKEND=anthropic|openai`）以便在模棱两可的步骤上获得更高准确率的判断，并具有可配置的远程调用限制（`RECUT_L4_REMOTE_MAX_PCT`，默认为 20%）。 使用 `flagging_depth="fast"` 可仅运行第 1 至 3 层（零模型成本，即时完成）。使用 `"full"` 可包含第 4 层。 ## 配置 最常见的变量： ``` RECUT_L4_BACKEND=local # local (default, free) | anthropic | openai RECUT_L4_LOCAL_URL=http://localhost:11434/v1 # Ollama, LM Studio, vLLM, etc. RECUT_DEFAULT_SAMPLE_RATE=1.0 # trace fraction, e.g. 0.1 for 10% in production RECUT_PRICE_INPUT=3.0 # override input token price per million (your billing unit) RECUT_PRICE_OUTPUT=15.0 # override output token price per million RECUT_COST_UNIT=USD # display label — USD, EUR, credits, etc. RECUT_API_TIMEOUT=60 # HTTP timeout in seconds for all API calls ``` 详见 **[docs/configuration.md](docs/configuration.md)** 获取完整参考——装饰器参数、`@on_flag` 过滤器、第 4 层后端、定价表、标志阈值、缓存、采样和存储。 ## 框架适配器 recut 是对你现有技术栈的增强——而不是替代。每个适配器都会将行为标志和推理信号推送到你的团队已经在使用的工具中。 **LangGraph** —— recut 的拦截模式直接映射到 LangGraph 的 `interrupt()` 原语上。在遇到高严重性标志时暂停，检查追踪记录，然后在图内恢复或重定向——一切都在图结构中完成。 **LangChain + LangSmith** —— 实现 `BaseCallbackHandler`，捕获推理 token 并将行为标志作为 LangSmith 反馈记录发布。打开 LangSmith，即可在现有追踪记录中看到 `recut_flags` 列。 **CrewAI** —— 前后置钩子同步运行并可以阻塞，使得在没有 LangGraph 的情况下也能使用拦截模式。 **OpenTelemetry**（`recut-otel`） —— 一个 `SpanProcessor`，可增强任何接入 OpenTelemetry 技术监测的技术栈。一个适配器即可与 AutoGen、Semantic Kernel、Arize Phoenix、Datadog、Honeycomb、Grafana 配合使用。 **Langfuse** —— 使用标准化的 `score_config` 词汇表发布 CATEGORICAL 和 NUMERIC 评分。将 Langfuse 的评分面板变成一个行为仪表盘。 ## 支持 Claude 和 OpenAI - **Claude**：原生扩展思考块捕获——真正的内部推理，而非摘要 - **OpenAI**：推断式推理回退方案 参见 [POSITIONING.md](docs/product/POSITIONING.md) 了解竞争格局和用例。 参见 [ROADMAP.md](docs/product/ROADMAP.md) 了解后续规划。 参见 [INTEGRATIONS.md](docs/product/INTEGRATIONS.md) 获取完整的适配器和平台集成细节。

标签：AI安全, AI工程, AI智能体, AI测试, AI风险缓解, Anthropic, API集成, ASM汇编, Chat Copilot, CIS基准, CrewAI, GET参数, LangChain, Langfuse, LangGraph, LLM, LLMOps, Mid-flight Interception, MLOps, Observability, OpenAI, OpenTelemetry, Python, Replay, SOC Prime, Trace, Unmanaged PE, 中间拦截, 内存规避, 压力测试, 反事实重放, 可观测性, 合规, 审计, 开发工具, 异常检测, 拦截修改, 提示词工程, 提示词模板, 无后门, 漂移检测, 生产力工具, 用户代理, 策略决策点, 记录重放, 轻量级, 运行追踪, 逆向工具