{
"canonical_name": "wandb/weave",
"compilation_id": "pack_71dada01f0ef4e1d875c28bd30031a96",
"created_at": "2026-05-16T23:57:52.967302+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install weave` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install weave",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_6e742e2ab05e47028421732ad1270a07"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_cb07f6e8b0b86963c226b37dc0fc7a6f",
"canonical_name": "wandb/weave",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/wandb/weave",
"slug": "weave",
"source_packet_id": "phit_ce29fa9adc214019a0eb90c79014403d",
"source_validation_id": "dval_9fbabae17bfc4405b789bcd9ac701642"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 151,
"github_stars": 1093,
"one_liner_en": "Weave is a toolkit for developing AI-powered applications, built by Weights & Biases.",
"one_liner_zh": "Weave is a toolkit for developing AI-powered applications, built by Weights & Biases.",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "weave",
"title_zh": "weave 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_ce29fa9adc214019a0eb90c79014403d",
"page_model": {
"artifacts": {
"artifact_slug": "weave",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install weave",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/wandb/weave#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"流程自动化",
"断点恢复流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Weave is a toolkit for developing AI-powered applications, built by Weights & Biases."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.52.31",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5abf422dae9b416fa8f2c65c21c2a4cd | https://github.com/wandb/weave/releases/tag/v0.52.31 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.31",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.52.40",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ac47498581a248b0b6be5e90b060b5ec | https://github.com/wandb/weave/releases/tag/v0.52.40 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.40",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.30",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_8279f2b8caaa46f893597430a4238d93 | https://github.com/wandb/weave/releases/tag/v0.52.30 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.30",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.35",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_82d6e8a0c7804ed9875e5d4df6cfbf3f | https://github.com/wandb/weave/releases/tag/v0.52.35 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.35",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.36",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_0347e61db43c4471a16dabca6f9d4b7f | https://github.com/wandb/weave/releases/tag/v0.52.36 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.36",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:650377372 | https://github.com/wandb/weave | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.52.38",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_e6ca52f3493342d3b958dd3159f4f8fe | https://github.com/wandb/weave/releases/tag/v0.52.38 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.38",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:650377372 | https://github.com/wandb/weave | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:650377372 | https://github.com/wandb/weave | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:650377372 | https://github.com/wandb/weave | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.52.33",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_c4f93114a48d4bee972dce582d09d376 | https://github.com/wandb/weave/releases/tag/v0.52.33 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.33",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.52.37",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_c68137d6b888458d83ba2b477f463aaa | https://github.com/wandb/weave/releases/tag/v0.52.37 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.37",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.52.39",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_de6a7e38f1644ad9ae7b67c43f2baad3 | https://github.com/wandb/weave/releases/tag/v0.52.39 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.52.39",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:650377372 | https://github.com/wandb/weave | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:650377372 | https://github.com/wandb/weave | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v0.52.31。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 111,
"forks": 151,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1093
},
"source_url": "https://github.com/wandb/weave",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Weave is a toolkit for developing AI-powered applications, built by Weights & Biases.",
"title": "weave 能力包",
"trial_prompt": "# weave - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 weave 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. system_architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. trace_flow：追踪数据流。围绕“追踪数据流”模拟一次用户任务，不展示安装或运行结果。\n4. tracing：函数追踪机制。围绕“函数追踪机制”模拟一次用户任务，不展示安装或运行结果。\n5. evaluation：评估系统。围绕“评估系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system_architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. trace_flow\n输入：用户提供的“追踪数据流”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. tracing\n输入：用户提供的“函数追踪机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. evaluation\n输入：用户提供的“评估系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / system_architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / trace_flow：Step 3 必须围绕“追踪数据流”形成一个小中间产物，并等待用户确认。\n- Step 4 / tracing：Step 4 必须围绕“函数追踪机制”形成一个小中间产物，并等待用户确认。\n- Step 5 / evaluation：Step 5 必须围绕“评估系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/wandb/weave\n- https://github.com/wandb/weave#readme\n- .claude/skills/bump-version/SKILL.md\n- .claude/skills/publish-pypi/SKILL.md\n- README.md\n- weave/__init__.py\n- weave/trace/weave_client.py\n- weave/trace_server/clickhouse_trace_server_batched.py\n- weave/trace_server_bindings\n- weave/trace/call.py\n- weave/trace/log_call.py\n- weave/trace/op_accumulator.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 weave 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v0.52.40（https://github.com/wandb/weave/releases/tag/v0.52.40）；github/github_release: v0.52.39（https://github.com/wandb/weave/releases/tag/v0.52.39）；github/github_release: v0.52.38（https://github.com/wandb/weave/releases/tag/v0.52.38）；github/github_release: v0.52.37（https://github.com/wandb/weave/releases/tag/v0.52.37）；github/github_release: v0.52.36（https://github.com/wandb/weave/releases/tag/v0.52.36）；github/github_release: v0.52.35（https://github.com/wandb/weave/releases/tag/v0.52.35）；github/github_release: v0.52.33（https://github.com/wandb/weave/releases/tag/v0.52.33）；github/github_release: v0.52.32（https://github.com/wandb/weave/releases/tag/v0.52.32）；github/github_release: v0.52.31（https://github.com/wandb/weave/releases/tag/v0.52.31）；github/github_release: v0.52.30（https://github.com/wandb/weave/releases/tag/v0.52.30）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v0.52.40",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.40"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.39",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.39"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.38",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.38"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.37",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.37"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.36",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.36"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.35",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.35"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.33",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.33"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.32",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.32"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.31",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.31"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.52.30",
"url": "https://github.com/wandb/weave/releases/tag/v0.52.30"
}
],
"status": "已收录 10 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Weave is a toolkit for developing AI-powered applications, built by Weights & Biases.",
"effort": "安装已验证",
"forks": 151,
"icon": "code",
"name": "weave 能力包",
"risk": "可发布",
"slug": "weave",
"stars": 1093,
"tags": [
"知识检索",
"知识库问答",
"流程自动化",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/wandb/weave 项目说明书\n\n生成时间：2026-05-16 23:32:03 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [安装与快速开始](#installation)\n- [系统架构](#system_architecture)\n- [追踪数据流](#trace_flow)\n- [函数追踪机制](#tracing)\n- [评估系统](#evaluation)\n- [评分器模块](#scorers)\n- [模型供应商集成](#vendor_integrations)\n- [框架集成](#framework_integrations)\n- [数据序列化](#serialization)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装与快速开始](#installation), [系统架构](#system_architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/wandb/weave/blob/main/README.md)\n- [weave/integrations/README.md](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n- [sdks/node/README.md](https://github.com/wandb/weave/blob/main/sdks/node/README.md)\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [weave/trace/serialization/README.md](https://github.com/wandb/weave/blob/main/weave/trace/serialization/README.md)\n \n\n# 项目介绍\n\n## 概述\n\nWeave 是一个用于追踪和监控 AI 应用程序的库，由 W&B（Weights & Biases）开发维护。它提供了一套完整的工具集，帮助开发者追踪 AI 模型的调用、执行过程，并支持对 AI 应用进行评估和可视化。\n\n资料来源：[README.md:1]()\n\n## 核心架构\n\n### 整体架构\n\nWeave 项目主要由以下几个核心部分组成：\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Weave SDK]\n B --> C[Op 追踪层]\n C --> D[Trace Server]\n D --> E[W&B UI]\n \n F[Python SDK] --> B\n G[Node.js SDK] --> B\n \n H[集成支持] --> B\n H --> I[OpenAI]\n H --> J[Anthropic]\n H --> K[Mistral]\n```\n\n### 主要组件\n\n| 组件 | 位置 | 功能描述 |\n|------|------|----------|\n| trace | `weave/trace/` | Python 追踪核心实现 |\n| trace_server | `weave/trace_server/` | 追踪服务器接口 |\n| integrations | `weave/integrations/` | 第三方库集成支持 |\n| flow | `weave/flow/` | 评估工作流 |\n| Node SDK | `sdks/node/` | JavaScript/TypeScript SDK |\n\n资料来源：[README.md:20-25]()\n\n## 核心概念\n\n### Op（操作）\n\nOp 是 Weave 的核心抽象概念，用于包装和追踪函数调用。它支持：\n\n- **异步函数追踪**：自动处理 async/await 模式\n- **流式响应处理**：支持流式输出的追踪和聚合\n- **调用元数据记录**：记录调用参数、返回值、执行时间等信息\n\n```mermaid\ngraph LR\n A[原始函数] -->|createOpWrapper| B[Op 包装器]\n B --> C{调用执行}\n C -->|追踪| D[Call 对象]\n C -->|返回| E[原始返回值]\n D --> F[Trace Server]\n```\n\n资料来源：[sdks/node/src/opType.ts:1-30]()\n\n### Op 类型定义\n\n```typescript\nexport type Op any> = {\n __isOp: true;\n __wrappedFunction: T;\n __boundThis?: WeaveObject;\n __name: string;\n __savedRef?: OpRef | Promise;\n __parameterNames?: ParameterNamesOption;\n invoke: CallMethod;\n} & T;\n```\n\n资料来源：[sdks/node/src/opType.ts:3-18]()\n\n### 调用方法（CallMethod）\n\nCallMethod 接口定义了 Op 的调用行为，返回一个 Promise，包含原始返回值和 Call 对象：\n\n```typescript\nexport interface CallMethod any> {\n (\n this: any,\n ...params: Parameters\n ): Promise<[Awaited>, Call]>;\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:62-68]()\n\n### 调用对象（Call）\n\nCall 对象用于存储追踪信息，包括：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| callId | string | 唯一调用标识符 |\n| opName | string | 操作名称 |\n| inputs | object | 输入参数 |\n| outputs | object | 输出结果 |\n| summary | object | 调用摘要 |\n| error | Error | 错误信息（如有） |\n\n## Op 装饰器\n\nWeave 支持两种装饰器模式：现代 Stage 3 装饰器和传统装饰器语法。\n\n### 现代装饰器语法（Stage 3）\n\n```javascript\nclass TestClass {\n @weave.op\n async logImage(image: WeaveImage) {\n // 方法实现\n }\n}\n```\n\n### 传统装饰器语法\n\n```javascript\nclass TestClass {\n @weave.op({ name: 'customName' })\n async logImage(image: WeaveImage) {\n // 方法实现\n }\n}\n```\n\n### 装饰器选项\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| name | string | 自定义操作名称 |\n| streamReducer | StreamReducer | 流式响应聚合器 |\n| callDisplayName | function | 动态显示名称生成 |\n| summarize | function | 结果摘要生成函数 |\n| bindThis | WeaveObject | 绑定 this 上下文 |\n| parameterNames | string[] | 参数名称配置 |\n| opKind | string | 操作类型分类 |\n| opColor | string | UI 显示颜色 |\n\n资料来源：[sdks/node/src/opType.ts:71-87]()\n\n## 集成系统\n\n### 隐式集成\n\n当隐式集成启用（默认）时，Weave 会自动检测并追踪支持的第三方库。用户只需初始化 Weave 项目：\n\n```python\nimport weave\nweave.init(\"my-project\")\nimport openai # 自动被追踪！\n```\n\n### 显式集成\n\n通过设置 `implicitly_patch_integrations=False` 禁用隐式集成，然后手动调用 patch 函数：\n\n```python\nimport weave\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\nweave.integrations.patch_openai()\nweave.integrations.patch_anthropic()\n```\n\n资料来源：[weave/integrations/README.md:1-50]()\n\n### 可用集成\n\n| 集成 | Patch 函数 | 说明 |\n|------|------------|------|\n| OpenAI | `patch_openai()` | OpenAI API 调用追踪 |\n| Anthropic | `patch_anthropic()` | Anthropic Claude API 追踪 |\n| Mistral | `patch_mistral()` | Mistral API 追踪 |\n\n### 开发新集成\n\n开发新的供应商集成需要创建以下文件结构：\n\n```\nweave/integrations//\n├── __init__.py\n├── _sdk.py\n└── _test.py\n```\n\n集成开发流程：\n\n1. 创建供应商文件夹\n2. 实现 `get__patcher()` 函数\n3. 返回 `MultiPatcher` 或 `NoOpPatcher` 对象\n4. 在 `AutopatchSettings` 中注册设置\n\n```python\nfrom weave.integrations.patcher import SymbolPatcher, MultiPatcher, NoOpPatcher\nfrom weave.trace.autopatch import IntegrationSettings\n\ndef get__patcher(\n settings: IntegrationSettings | None = None,\n) -> MultiPatcher | NoOpPatcher:\n if settings is None:\n settings = IntegrationSettings()\n if not settings.enabled:\n return NoOpPatcher()\n \n global __patcher\n if __patcher is None:\n # 实现符号替换逻辑\n __patcher = MultiPatcher([...])\n return __patcher\n```\n\n资料来源：[weave/integrations/README.md:100-140]()\n\n## 序列化系统\n\n### 序列化机制\n\nWeave 提供两种序列化方式：\n\n| 方式 | 适用场景 | 说明 |\n|------|----------|------|\n| 文件序列化 | 大型值（图片等） | 通过 `MemTraceFilesArtifact` 存储 |\n| 内联序列化 | 小型值（datetime 等） | 直接嵌入序列化信息 |\n\n资料来源：[weave/trace/serialization/README.md:1-30]()\n\n### 自定义类型支持\n\n用户可以注册自定义的 `save` 和 `load` 方法：\n\n```python\nfrom weave import register_serializer\n\n@register_serializer(MyCustomClass)\nclass MyCustomSerializer:\n def save(self, obj):\n # 自定义序列化逻辑\n return {...}\n \n def load(self, data):\n # 自定义反序列化逻辑\n return MyCustomClass(...)\n```\n\n### 内置类型\n\nWeave 内置以下类型的序列化支持：\n\n| 类型 | 模块 | 说明 |\n|------|------|------|\n| 图像 | PIL.Image.Image | 图片序列化 |\n| 音频 | wave.Wave_read | 音频序列化 |\n| Op | weave.Op | 操作序列化 |\n| 日期时间 | datetime.datetime | 时间戳序列化 |\n| Markdown | rich.markdown.Markdown | Markdown 内容序列化 |\n\n## 评估工作流\n\n### 评估系统架构\n\n```mermaid\ngraph TD\n A[评估数据集] --> B[评估运行器]\n B --> C[并行执行]\n C --> D[结果聚合]\n D --> E[评分计算]\n E --> F[结果展示]\n \n G[预测函数] --> B\n G --> H[Op 追踪]\n H --> I[Trace Server]\n I --> E\n```\n\n### Callable 接口\n\n评估系统基于 `Callable` 接口设计：\n\n```typescript\nexport interface Callable {\n run: (input: I) => Promise;\n}\n```\n\n资料来源：[sdks/node/src/fn.ts:10-13]()\n\n## SDK 使用\n\n### Python SDK\n\n#### 初始化项目\n\n```python\nimport weave\nweave.init(\"my-project\")\n```\n\n#### 追踪函数\n\n```python\nimport weave\n\n@weave.op()\ndef extract_fruit(sentence):\n # 函数实现\n return fruit\n```\n\n### Node.js SDK\n\n#### 安装\n\n```bash\nnpm install weave\n```\n\n#### 初始化和追踪\n\n```javascript\nimport {init, op, wrapOpenAI} from 'weave';\nimport {OpenAI} from 'openai';\n\nconst openai = wrapOpenAI(new OpenAI());\n\nasync function extractDinos(input) {\n const response = await openai.chat.completions.create({\n model: 'gpt-4o',\n messages: [{role: 'user', content: input}],\n });\n return response.choices[0].message.content;\n}\n\nconst extractDinosOp = op(extractDinos);\n\nasync function main() {\n await init('weave-quickstart');\n const result = await extractDinosOp('输入文本');\n console.log(result);\n}\n```\n\n资料来源：[sdks/node/README.md:1-60]()\n\n## 配置选项\n\n### Weave 初始化配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| project_name | string | 必填 | 项目名称 |\n| settings | dict | None | 配置字典 |\n| entity | string | None | 团队/用户名称 |\n| host | string | api.wandb.ai | API 主机地址 |\n\n### 集成设置\n\n| 设置 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| implicitly_patch_integrations | bool | True | 是否启用隐式集成 |\n| enabled | bool | True | 是否启用特定集成 |\n\n## 项目结构\n\n```\nweave/\n├── __init__.py # 主入口\n├── trace/ # 追踪核心\n│ ├── autopatch.py # 自动集成\n│ ├── ops.py # Op 定义\n│ └── serialization/ # 序列化系统\n├── trace_server/ # 服务端接口\n├── integrations/ # 第三方集成\n│ ├── openai/ # OpenAI 集成\n│ ├── anthropic/ # Anthropic 集成\n│ └── mistral/ # Mistral 集成\n└── flow/ # 评估工作流\n\nsdks/\n└── node/ # JavaScript SDK\n ├── src/\n │ ├── op.ts # Op 实现\n │ ├── opType.ts # 类型定义\n │ └── evaluation.ts # 评估功能\n └── README.md # Node SDK 文档\n```\n\n资料来源：[README.md:15-30]()\n\n## 快速开始\n\n### Python 快速开始\n\n1. 安装 Weave：`pip install weave`\n2. 初始化项目并追踪函数\n3. 查看追踪结果在 W&B 仪表板\n\n### Node.js 快速开始\n\n1. 安装：`npm install weave`\n2. 配置 `~/.netrc` 中的 W&B API 密钥\n3. 使用 `op()` 包装函数\n4. 运行并查看结果\n\n## 贡献指南\n\n项目当前处于代码整理阶段。核心代码位置：\n\n- **追踪代码**：`weave/trace` 和 `weave/trace_server`\n- **评估代码**：`weave/flow`\n\n资料来源：[README.md:27-30]()\n\n---\n\n\n\n## 安装与快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction), [函数追踪机制](#tracing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/wandb/weave/blob/main/pyproject.toml)\n- [weave/trace/weave_init.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_init.py)\n- [weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n- [weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n- [sdks/node/README.md](https://github.com/wandb/weave/blob/main/sdks/node/README.md)\n- [weave/integrations/README.md](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n\n \n\n# 安装与快速开始\n\n## 概述\n\nWeave 是一个用于 AI 应用追踪（Tracing）和监控的库，由 W&B（Weights & Biases）提供。该库支持 Python 和 Node.js 两个主要 SDK，能够自动捕获和记录 AI 应用的执行过程，帮助开发者追踪函数调用、分析性能、调试问题。\n\n安装与快速开始模块是用户接触 Weave 的第一步，涵盖了环境准备、SDK 安装、项目初始化、基础追踪操作等核心流程。资料来源：[README.md:1-5]()\n\n## 环境要求\n\n### Python SDK 系统要求\n\n| 要求类型 | 最低版本 | 说明 |\n|---------|---------|------|\n| Python | 3.8+ | 支持 Python 3.8 及以上版本 |\n| pip | 最新版本 | 推荐使用最新版本的 pip 进行安装 |\n\n### Node.js SDK 系统要求\n\n| 要求类型 | 最低版本 | 说明 |\n|---------|---------|------|\n| Node.js | 18+ | 支持 Node.js 18 及以上版本 |\n| npm | 最新版本 | 用于安装 weave 包 |\n\n### 网络要求\n\n- 需要访问 W&B API 服务（api.wandb.ai）\n- 部分功能需要有效的 W&B API Key\n- 测试环境支持本地 Trace Server（localhost）\n\n资料来源：[sdks/node/README.md:1-20]()\n\n## Python SDK 安装\n\n### 使用 pip 安装\n\n```bash\npip install weave\n```\n\n### 验证安装\n\n安装完成后，可通过以下命令验证：\n\n```python\nimport weave\nprint(weave.__version__)\n```\n\n资料来源：[pyproject.toml](https://github.com/wandb/weave/blob/main/pyproject.toml)\n\n## Node.js SDK 安装\n\n### 使用 npm 安装\n\n```bash\nnpm install weave\n```\n\n### 配置认证\n\n在 `~/.netrc` 文件中添加 W&B API Key：\n\n```\nmachine api.wandb.ai\n login user\n password \n```\n\nAPI Key 可从 [W&B 授权页面](https://wandb.ai/authorize) 获取。\n\n资料来源：[sdks/node/README.md:1-25]()\n\n## 项目初始化\n\n### Python 初始化流程\n\n使用 `weave.init()` 函数初始化项目：\n\n```python\nimport weave\n\n# 初始化项目\nweave.init(\"my-project\")\n```\n\n### Node.js 初始化流程\n\n```javascript\nimport {init} from 'weave';\n\n// 初始化项目\nawait init('my-awesome-ai-project');\n```\n\n### 初始化参数说明\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|-------|------|-----|-------|------|\n| project | string | 是 | - | 项目名称 |\n| entity | string | 否 | 当前用户 | W&B 实体/团队名称 |\n| settings | dict/Settings | 否 | None | 高级配置选项 |\n\n### 配置选项（Settings）\n\n初始化时可通过 `settings` 参数进行高级配置：\n\n```python\nimport weave\n\nweave.init(\"my-project\", settings={\n 'implicitly_patch_integrations': True, # 自动注入集成\n 'print_call_link': True, # 打印调用链接\n})\n```\n\n资料来源：[weave/trace/weave_init.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_init.py)\n\n## 追踪操作入门\n\n### 使用 op 装饰器追踪函数\n\n#### Python 示例\n\n```python\nimport weave\n\n@weave.op()\ndef extract_fruit(sentence: str) -> str:\n \"\"\"提取句子中的水果名称\"\"\"\n return \"apple\"\n\n# 调用追踪函数\nresult = extract_fruit(\"I love apples and oranges\")\n```\n\n#### Node.js 示例\n\n```javascript\nimport {op} from 'weave';\n\nconst extractDinosOp = op(async function extractDinos(input) {\n // 你的逻辑\n return result;\n});\n```\n\n资料来源：[sdks/node/README.md:30-55]()\n\n### 类方法追踪\n\n#### Python 类方法\n\n```python\nimport weave\n\nclass MyAgent:\n @weave.op()\n async def analyze(self, text: str) -> dict:\n return {\"sentiment\": \"positive\", \"text\": text}\n\nagent = MyAgent()\nresult = await agent.analyze(\"This is great!\")\n```\n\n#### Node.js 类装饰器\n\n```javascript\nimport * as weave from \"weave\";\n\nclass TestClass {\n @weave.op\n async logImage(image) {\n // 方法逻辑\n }\n}\n```\n\n资料来源：[sdks/node/README.md:55-70]()\n\n## 自动集成与注入\n\n### 隐式注入（默认启用）\n\n当隐式注入启用时，Weave 会在支持的库被导入时自动应用追踪补丁：\n\n```python\nimport weave\nweave.init(\"my-project\")\nimport openai # 自动追踪已启用！\n```\n\n### 显式控制\n\n如需显式控制，可禁用隐式注入：\n\n```python\nimport weave\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\n\n# 显式启用特定集成\nweave.integrations.patch_openai()\nweave.integrations.patch_anthropic()\nweave.integrations.patch_mistral()\n```\n\n### 支持的集成列表\n\n| 集成名称 | 库名称 | patch 函数 |\n|---------|-------|-----------|\n| OpenAI | openai | `weave.integrations.patch_openai()` |\n| Anthropic | anthropic | `weave.integrations.patch_anthropic()` |\n| Mistral | mistral | `weave.integrations.patch_mistral()` |\n| LlamaIndex | llama_index | `weave.integrations.patch_llama_index()` |\n| Langchain | langchain | `weave.integrations.patch_langchain()` |\n\n资料来源：[weave/integrations/README.md:1-50]()\n\n## 快速开始示例\n\n### Python 完整示例\n\n```python\nimport weave\n\n# 1. 初始化项目\nweave.init(\"quickstart-demo\")\n\n# 2. 定义追踪函数\n@weave.op()\ndef extract_fruit(sentence: str) -> str:\n \"\"\"从句子中提取水果名称\"\"\"\n fruits = [\"apple\", \"banana\", \"cherry\", \"date\"]\n for fruit in fruits:\n if fruit in sentence.lower():\n return fruit\n return \"未找到水果\"\n\n# 3. 调用函数\nresult = extract_fruit(\"I love eating apples\")\nprint(f\"结果: {result}\")\n\n# 4. 获取追踪结果\ncalls = list(weave_client.get_calls())\nprint(f\"追踪到的调用数: {len(calls)}\")\n```\n\n### Node.js 完整示例\n\n创建 `predict.mjs` 文件：\n\n```javascript\nimport {OpenAI} from 'openai';\nimport {init, op, wrapOpenAI} from 'weave';\n\nconst openai = wrapOpenAI(new OpenAI());\n\nasync function extractDinos(input) {\n const response = await openai.chat.completions.create({\n model: 'gpt-4o',\n messages: [{role: 'user', content: `提取恐龙信息: ${input}`}],\n });\n return response.choices[0].message.content;\n}\n\nconst extractDinosOp = op(extractDinos);\n\nasync function main() {\n await init('weave-quickstart');\n const result = await extractDinosOp('T. rex 追逐三角龙');\n console.log(result);\n}\n\nmain();\n```\n\n运行：\n\n```bash\nnode predict.mjs\n```\n\n资料来源：[sdks/node/README.md:30-65]()\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 Weave SDK] --> B{选择运行环境}\n B -->|Python| C[使用 pip 安装]\n B -->|Node.js| D[使用 npm 安装]\n C --> E[配置 W&B API Key]\n D --> E\n E --> F[初始化项目 weave.init]\n F --> G{定义追踪操作}\n G -->|函数| H[使用 @weave.op 装饰器]\n G -->|类方法| I[使用 @weave.op 装饰方法]\n H --> J[调用追踪函数]\n I --> J\n J --> K[查看追踪结果]\n K --> L{启用集成追踪?}\n L -->|是| M[隐式/显式注入集成]\n L -->|否| K\n```\n\n## 常见问题与解决方案\n\n### 1. 追踪未生效\n\n**问题**：调用函数后没有追踪记录。\n\n**解决方案**：\n- 确保在调用函数前已调用 `weave.init()`\n- 检查是否禁用了隐式注入\n- 确认使用了正确的装饰器语法\n\n### 2. API Key 配置错误\n\n**问题**：无法连接到 W&B 服务。\n\n**解决方案**：\n- 验证 `~/.netrc` 文件中的 API Key 格式正确\n- 确认 API Key 具有有效权限\n- 检查网络连接和代理设置\n\n### 3. 集成库未被追踪\n\n**问题**：使用第三方库（如 OpenAI）时未记录调用。\n\n**解决方案**：\n- 确认集成库已安装：`pip install openai`\n- 显式调用 patch 函数：`weave.integrations.patch_openai()`\n- 或确保隐式注入已启用\n\n资料来源：[weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n\n## 下一步\n\n完成安装和快速开始后，你可以：\n\n| 进阶主题 | 说明 |\n|---------|------|\n| 高级追踪配置 | 自定义追踪行为、属性和显示方式 |\n| 评估与测试 | 使用 Weave 构建 AI 评估流程 |\n| 自定义序列化 | 添加自定义类型的序列化支持 |\n| 集成开发 | 为新的供应商库开发集成支持 |\n\n资料来源：[weave/trace/serialization/README.md:1-30]()\n\n## 相关文档链接\n\n- [Python SDK 源码](https://github.com/wandb/weave/tree/main/weave/trace)\n- [Node.js SDK 源码](https://github.com/wandb/weave/tree/main/sdks/node/src)\n- [集成开发指南](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n- [W&B 官方文档](https://docs.wandb.ai/)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[追踪数据流](#trace_flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/trace/weave_client.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_client.py)\n- [weave/trace_server/clickhouse_trace_server_batched.py](https://github.com/wandb/weave/blob/main/weave/trace_server/clickhouse_trace_server_batched.py)\n- [weave/trace_server_bindings](https://github.com/wandb/weave/blob/main/weave/trace_server_bindings)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n- [weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n \n\n# 系统架构\n\n## 概述\n\nWeave 是一个用于追踪和监控 AI 应用程序的库，支持 Python 和 Node.js 双端 SDK。其核心设计围绕**追踪（Tracing）**和**评估（Evaluations）**两大功能模块展开，旨在为 AI 应用提供可观测性和性能分析能力。\n\n系统架构采用分层设计，包含以下核心层次：\n\n```graph TD\n A[用户代码] --> B[Weave SDK 层]\n B --> C[追踪客户端层]\n C --> D[Trace Server 接口层]\n D --> E[Trace Server 实现层]\n E --> F[(ClickHouse 数据库)]\n \n G[集成模块] --> B\n H[自动补丁模块] --> G\n```\n\n资料来源：[weave/trace/weave_client.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_client.py)\n\n## 核心组件\n\n### SDK 层架构\n\nWeave SDK 提供 Python 和 Node.js 两种实现，共同遵循相同的架构理念：\n\n| SDK 类型 | 主要语言 | 核心文件 | 功能定位 |\n|---------|---------|---------|---------|\n| Python SDK | Python | `weave/trace/weave_client.py` | 服务端追踪数据处理 |\n| Node.js SDK | TypeScript | `sdks/node/src/op.ts` | 客户端函数包装与追踪 |\n\nPython SDK 侧重于服务端 trace 数据的接收、存储和查询，而 Node.js SDK 则专注于客户端操作的包装和追踪。\n\n资料来源：[sdks/node/src/op.ts:1-50](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n\n### 追踪客户端层\n\n`WeaveClient` 是 Python SDK 的核心类，负责管理追踪会话和调用记录：\n\n```mermaid\nclassDiagram\n class WeaveClient {\n +project_id: str\n +settings: WeaveStorageSettings\n +pushNewCall() CallContext\n +finishCall() None\n +finishCallWithException() None\n +waitForBatchProcessing() None\n }\n \n class CallContext {\n +currentCall: Call\n +parentCall: Call | None\n +newStack: list\n }\n```\n\n客户端通过 `pushNewCall()` 创建新的调用上下文，跟踪操作的执行状态和层级关系。\n\n资料来源：[weave/trace/weave_client.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_client.py)\n\n### Op 包装机制\n\nOp（操作）是 Weave 追踪的基本单元，通过 `op()` 函数包装用户函数：\n\n```graph TD\n A[用户定义函数 fn] --> B[op(fn) 包装]\n B --> C[创建 Op 对象]\n C --> D[注入追踪逻辑]\n D --> E[返回包装后的函数]\n \n E --> F[同步函数处理]\n E --> G[异步函数处理]\n E --> H[流式响应处理]\n \n F --> I[直接返回结果]\n G --> J[Promise 包装]\n H --> K[AsyncIterator 代理]\n```\n\nOp 对象保留原函数的所有特性，同时添加追踪能力：\n\n```typescript\nexport type Op any> = {\n __isOp: true;\n __wrappedFunction: T;\n __boundThis?: WeaveObject;\n __name: string;\n __savedRef?: OpRef | Promise;\n __parameterNames?: ParameterNamesOption;\n invoke: CallMethod;\n} & T;\n```\n\n资料来源：[sdks/node/src/opType.ts:1-30](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n\n### Trace Server 接口层\n\n`trace_server_bindings` 定义了 Weave 与后端服务之间的接口契约：\n\n| 接口方法 | 功能描述 | 数据格式 |\n|---------|---------|---------|\n| `calls/stream_query` | 流式查询调用记录 | NDJSON |\n| `call/upsert_batch` | 批量创建/更新调用 | JSON |\n| `obj/*` | 对象管理 | JSON |\n| `table/*` | 表格数据管理 | JSON |\n| `file/*` | 文件存储管理 | 二进制 |\n\n接口层采用 RESTful 设计，兼容生产环境和测试环境。\n\n资料来源：[weave/trace_server_bindings](https://github.com/wandb/weave/blob/main/weave/trace_server_bindings)\n\n### Trace Server 实现层\n\n`clickhouse_trace_server_batched.py` 实现了基于 ClickHouse 的 trace 服务器：\n\n```mermaid\ngraph LR\n A[批量请求接收] --> B[请求队列管理]\n B --> C[批处理优化]\n C --> D[ClickHouse 写入]\n D --> E[查询接口]\n E --> F[NDJSON 流式响应]\n```\n\n批量处理机制显著提高了数据写入效率，降低了数据库连接开销。\n\n资料来源：[weave/trace_server/clickhouse_trace_server_batched.py](https://github.com/wandb/weave/blob/main/weave/trace_server/clickhouse_trace_server_batched.py)\n\n## 集成模块架构\n\n### 自动补丁系统\n\nWeave 的自动补丁系统通过 `sys.meta_path` 拦截导入，自动应用追踪补丁：\n\n```graph TD\n A[import vendor_lib] --> B[Meta Path 钩子]\n B --> C{patch_ 可用?}\n C -->|是| D[调用 patch_]\n C -->|否| E[跳过补丁]\n D --> F[修改 vendor_lib 函数]\n F --> G[注入追踪调用]\n```\n\n用户可通过配置控制隐式补丁行为：\n\n```python\n# 启用隐式补丁（默认）\nweave.init('my-project')\n\n# 禁用隐式补丁\nweave.init('my-project', settings={'implicitly_patch_integrations': False})\n\n# 或通过环境变量\n# export WEAVE_IMPLICITLY_PATCH_INTEGRATIONS=false\n```\n\n资料来源：[weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n\n### 支持的集成\n\n自动补丁系统支持主流 AI 服务商的 SDK：\n\n| 集成名称 | 补丁函数 | 追踪范围 |\n|---------|---------|---------|\n| OpenAI | `patch_openai()` | Chat completions, Embeddings |\n| Anthropic | `patch_anthropic()` | Messages, Completions |\n| Mistral | `patch_mistral()` | Chat endpoints |\n\n每个集成都有对应的 `get__patcher()` 函数用于获取补丁器实例。\n\n资料来源：[weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n\n## 数据流架构\n\n### 调用追踪数据流\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant SDK as Weave SDK\n participant Client as WeaveClient\n participant Server as Trace Server\n participant DB as ClickHouse\n \n User->>SDK: 调用 op 包装函数\n SDK->>Client: pushNewCall()\n Client->>Client: 创建 CallContext\n User->>SDK: 执行业务逻辑\n SDK->>Client: finishCall(result)\n Client->>Server: upsert_batch(calls)\n Server->>DB: 批量写入\n DB-->>Server: 确认写入\n Server-->>Client: 响应\n```\n\n### 流式响应处理\n\n对于支持流式输出的 AI API，Weave 通过代理模式拦截 `AsyncIterator`：\n\n```typescript\nconst proxy = new Proxy(result, {\n get: (target, prop) => {\n if (prop === Symbol.asyncIterator) {\n return WeaveIterator;\n }\n return Reflect.get(target, prop);\n },\n});\n```\n\n流式处理结合 `StreamReducer` 实现状态聚合和最终结果记录：\n\n```typescript\nexport interface StreamReducer {\n initialStateFn: () => R;\n reduceFn: (state: R, chunk: T) => R;\n finalizeFn: (state: R) => void;\n}\n```\n\n资料来源：[sdks/node/src/op.ts:150-200](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n\n## 配置系统\n\n### 初始化配置\n\nWeave 通过 `init()` 函数初始化追踪环境：\n\n```python\nweave.init(\n project_id: str, # 项目标识符\n settings: dict | None = None # 配置字典\n)\n```\n\n### 自动补丁配置\n\n`AutopatchSettings` 类定义了各集成的独立配置：\n\n```python\nclass AutopatchSettings(BaseModel):\n openai: IntegrationSettings = Field(default_factory=IntegrationSettings)\n anthropic: IntegrationSettings = Field(default_factory=IntegrationSettings)\n mistral: IntegrationSettings = Field(default_factory=IntegrationSettings)\n # ... 其他集成\n```\n\n### 客户端设置\n\n`WeaveStorageSettings` 控制客户端行为：\n\n| 设置项 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| `implicitly_patch_integrations` | bool | `True` | 是否启用隐式集成补丁 |\n| `should_print_call_link` | bool | `True` | 是否打印调用链接 |\n\n## 测试架构\n\n### Mock Trace Server\n\n`trace_server_mock` 提供轻量级的内存 trace 服务器用于测试：\n\n```graph TD\n A[测试用例] --> B[启动 Mock Server]\n B --> C[设置环境变量]\n C --> D[执行测试逻辑]\n D --> E[查询 /test/getCalls]\n E --> F[断言验证]\n F --> G[清理 Mock Server]\n```\n\nMock 服务器支持以下测试专用端点：\n\n| 端点 | 方法 | 用途 |\n|-----|------|-----|\n| `/test/health` | GET | 健康检查 |\n| `/test/getCalls` | GET | 查询已记录的调用 |\n| `/test/reset` | POST | 重置测试数据 |\n\n资料来源：[trace_server_mock/README.md](https://github.com/wandb/weave/blob/main/trace_server_mock/README.md)\n\n### VCR 录制机制\n\n集成测试使用 `pytest-recording` 和 `vcrpy` 录制网络请求：\n\n```python\n@pytest.mark.vcr(\n filter_headers=[\"authorization\"],\n allowed_hosts=[\"api.wandb.ai\", \"localhost\"],\n)\ndef test__quickstart(\n client: weave.weave_client.WeaveClient,\n patch_: None,\n) -> None:\n # 测试逻辑\n```\n\n录制模式支持 `--record-mode=rewrite` 重新生成录制文件。\n\n## 序列化和反序列化\n\n### 序列化架构\n\nWeave 支持自定义类型的序列化和反序列化：\n\n```mermaid\ngraph LR\n A[Python 对象] -->|save| B[MemTraceFilesArtifact]\n B --> C[序列化数据]\n C --> D[HTTP 上传]\n \n D --> E[Trace Server]\n E --> F[ClickHouse 存储]\n \n F --> G[加载请求]\n G --> H[反序列化函数]\n H --> I[load_my_type]\n I --> J[Python 对象]\n```\n\n自定义类型需通过 `serializer.register_serializer()` 注册保存和加载函数。\n\n资料来源：[weave/trace/serialization/README.md](https://github.com/wandb/weave/blob/main/weave/trace/serialization/README.md)\n\n## 关键设计模式\n\n### 1. 代理模式\n\nOp 包装使用 JavaScript `Proxy` 拦截 `AsyncIterator` 访问，实现流式响应的透明追踪。\n\n### 2. 工厂模式\n\n各集成通过 `get__patcher()` 工厂函数获取统一的 `Patcher` 实例。\n\n### 3. 装饰器模式\n\nNode.js SDK 支持 `@weave.op` 装饰器用于类方法的追踪包装：\n\n```typescript\nclass TestClass {\n @weave.op\n async logImage(image: WeaveImage) {\n // 方法实现\n }\n}\n```\n\n### 4. 批量处理模式\n\nTrace Server 采用批量写入优化，减少数据库 I/O 开销。\n\n## 总结\n\nWeave 系统架构围绕追踪核心，采用分层和模块化设计：\n\n1. **SDK 层**：提供 Python/Node.js 双端 API\n2. **客户端层**：管理调用上下文和追踪状态\n3. **接口层**：定义统一的 trace 数据交换协议\n4. **服务端层**：实现高效的数据存储和查询\n5. **集成层**：支持主流 AI 服务的自动追踪\n\n架构设计强调**透明性**（无需修改业务代码）和**可扩展性**（支持自定义集成和类型），为 AI 应用提供无缝的可观测性能力。\n\n---\n\n\n\n## 追踪数据流\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [数据序列化](#serialization)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [sdks/node/src/evaluation.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/evaluation.ts)\n- [sdks/node/src/fn.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/fn.ts)\n- [weave/integrations/README.md](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n- [weave/trace/serialization/README.md](https://github.com/wandb/weave/blob/main/weave/trace/serialization/README.md)\n- [trace_server_mock/README.md](https://github.com/wandb/weave/blob/main/trace_server_mock/README.md)\n- [README.md](https://github.com/wandb/weave/blob/main/README.md)\n \n\n# 追踪数据流\n\n## 概述\n\n追踪数据流（Trace Data Flow）是 Weave 框架中负责捕获、记录和传递 AI 应用执行信息的核心机制。它通过在函数调用前后插入钩子（Hook），将每次操作的输入、输出、执行时间和上下文信息收集起来，形成完整的调用链路追踪。\n\nWeave 的追踪系统主要分为两个层面：\n\n1. **Python SDK 层**：基于 `weave/trace` 目录下的核心组件，负责 Python 环境和第三方库的集成追踪\n2. **Node SDK 层**：基于 `sdks/node/src/` 目录下的 TypeScript 实现，为 JavaScript/TypeScript 环境提供追踪能力\n\n资料来源：[README.md:1-20]()\n\n## 核心数据类型\n\n### Op 类型定义\n\nOp（Operation）是 Weave 追踪的基本单位，表示一个被追踪的函数或方法。其核心类型定义如下：\n\n```typescript\nexport type Op any> = {\n __isOp: true; // 类型标记\n __wrappedFunction: T; // 原始函数引用\n __boundThis?: WeaveObject; // 绑定的 this 对象\n __name: string; // 操作名称\n __savedRef?: OpRef | Promise; // Op 的持久化引用\n __parameterNames?: ParameterNamesOption;// 参数名称配置\n invoke: CallMethod; // 调用方法\n} & T;\n```\n\n资料来源：[sdks/node/src/opType.ts:3-17]()\n\n### Call 类型\n\nCall 表示一次函数调用的完整记录，包含调用 ID、时间戳、输入输出等信息：\n\n```typescript\nexport interface Call {\n id: string;\n traceId?: string;\n parentId?: string;\n startedAt: Date;\n endedAt?: Date;\n inputs?: Record;\n outputs?: Record;\n summary?: CallSummary;\n attributes?: Record;\n opName?: string;\n opRef?: OpRef;\n}\n```\n\n### OpRef 类型\n\nOpRef 是操作的持久化引用，用于在 UI 中定位和分享特定的操作版本：\n\n```typescript\nexport class OpRef {\n constructor(\n public projectId: string,\n public objectId: string,\n public digest: string\n ) {}\n\n public uri() {\n return `weave:///${this.projectId}/op/${this.objectId}:${this.digest}`;\n }\n\n public ui_url() {\n const domain = getGlobalDomain();\n return `https://${domain}/${this.projectId}/weave/ops/${this.objectId}/versions/${this.digest}`;\n }\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:65-85]()\n\n## 追踪流程架构\n\n### 整体数据流图\n\n```mermaid\ngraph TD\n A[用户调用被追踪函数] --> B[Op Wrapper 拦截调用]\n B --> C[创建 InternalCall 对象]\n C --> D[推入新调用栈]\n D --> E[记录开始时间戳]\n E --> F[执行原始函数]\n F --> G[收集返回值]\n G --> H[记录结束时间戳]\n H --> I[构建 Call 对象]\n I --> J[发送到 Trace Server]\n J --> K[返回结果给调用方]\n \n L[异步迭代器场景] --> M[StreamReducer 处理]\n M --> N[增量收集流式输出]\n N --> O[组装完整输出]\n O --> H\n```\n\n### 调用上下文管理\n\nWeave 使用全局客户端和上下文栈来管理调用层级关系：\n\n```typescript\ninterface CallContext {\n currentCall: Call;\n parentCall: Call | null;\n newStack: boolean;\n}\n\nclass WeaveClient {\n // 推送新调用并获取上下文\n pushNewCall(): CallContext {\n // 创建新的 Call 对象\n // 建立父子调用关系\n // 返回上下文信息\n }\n}\n```\n\n资料来源：[sdks/node/src/op.ts:30-80]()\n\n## Op 创建与包装\n\n### 创建流程\n\n当用户使用 `@weave.op` 装饰器或 `op()` 函数包装函数时，Weave 执行以下步骤：\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant O as op() 函数\n participant CP as createOpWrapper\n participant IC as InternalCall\n participant C as WeaveClient\n\n U->>O: op(myFunction, options?)\n O->>CP: createOpWrapper(myFunction, options)\n CP->>IC: new InternalCall()\n IC->>C: pushNewCall()\n C-->>IC: 返回 CallContext\n IC-->>CP: wrapped function\n CP-->>O: Op 对象\n O-->>U: 可追踪的函数\n```\n\n### Op Wrapper 实现\n\n核心的函数包装逻辑位于 `createOpWrapper` 函数中：\n\n```typescript\nconst opWrapper = async function (\n this: any,\n ...params: Parameters\n): Promise>> {\n const client = getGlobalClient();\n \n // 检查客户端是否初始化\n if (!client) {\n warnOnce('weave-not-initialized', 'WARNING: Weave is not initialized...');\n return await fn.apply(thisArg, params);\n }\n\n // 创建调用上下文\n const {currentCall, parentCall, newStack} = client.pushNewCall();\n const startTime = new Date();\n \n // 打印调用链接（可选）\n if (client.settings.shouldPrintCallLink && parentCall == null) {\n console.log(`${TRACE_CALL_EMOJI} https://${domain}/${client.projectId}/r/call/${currentCall.callId}`);\n }\n\n // 执行原始函数\n const result = await fn.apply(thisArg, params);\n \n // 记录完成信息并发送\n // ...\n return result;\n};\n```\n\n资料来源：[sdks/node/src/op.ts:50-100]()\n\n### 装饰器支持\n\nWeave 支持两种装饰器模式：\n\n| 装饰器类型 | 使用方式 | 代码示例 |\n|-----------|---------|---------|\n| Stage 3 装饰器 | `@weave.op` | `@weave.op async method()` |\n| Legacy 装饰器 | `@weave.op()` | `@weave.op() async method()` |\n| 装饰器工厂 | `@weave.op(options)` | `@weave.op({name: 'custom'}) async method()` |\n\n```typescript\n// Stage 3 装饰器处理\nfunction handleModernDecorator any>(\n originalMethod: T,\n context: ClassMethodDecoratorContext,\n factoryOptions?: Partial>\n): T {\n const derivedName = `${String(context.name)}`;\n const options = {\n ...factoryOptions,\n isDecorator: true,\n originalFunction: originalMethod,\n context: context,\n };\n return createOpWrapper(originalMethod, options);\n}\n```\n\n资料来源：[sdks/node/src/op.ts:150-200]()\n\n## 异步迭代器支持\n\n### StreamReducer 接口\n\n对于返回异步迭代器的函数（如流式 LLM 输出），Weave 使用 `StreamReducer` 接口进行处理：\n\n```typescript\nexport interface StreamReducer {\n initialStateFn: () => R; // 初始状态工厂\n reduceFn: (state: R, chunk: T) => R; // 归约函数\n finalizeFn: (state: R) => void; // 最终化函数\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:18-24]()\n\n### 并行流式处理\n\n对于评估场景中的并行流式处理，Weave 提供了以下机制：\n\n```typescript\nasync function* asyncParallelMap(\n asyncIterator: AsyncIterable,\n fn: (item: T, ...args: any[]) => Promise,\n fnParams: (item: T) => any[],\n maxConcurrency: number\n) {\n const itemPromiseMap: Map}>> = new Map();\n \n for await (const item of asyncIterator) {\n // 控制并发数量\n if (itemPromiseMap.size >= maxConcurrency) {\n const done = await Promise.race(itemPromiseMap.values());\n itemPromiseMap.delete(done.item);\n yield { ...done, nRunning: itemPromiseMap.size, nDone: ++nDone };\n }\n const prom = runOne(item);\n itemPromiseMap.set(item, prom);\n }\n // 处理剩余项目...\n}\n```\n\n资料来源：[sdks/node/src/evaluation.ts:40-70]()\n\n## 集成追踪机制\n\n### 隐式补丁模式\n\nWeave 通过 `sys.meta_path` 拦截机制实现隐式补丁：\n\n```mermaid\ngraph LR\n A[import vendor_lib] --> B[meta_path 拦截]\n B --> C[调用 patch_()]\n C --> D[SymbolPatcher 替换符号]\n D --> E[vendor_lib 函数被追踪]\n```\n\n### 显式补丁模式\n\n当隐式补丁被禁用时，用户需要显式调用补丁函数：\n\n```python\nimport weave\n\n# 初始化，禁用隐式补丁\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\n\n# 显式启用追踪\nweave.integrations.patch_openai()\nweave.integrations.patch_anthropic()\nweave.integrations.patch_mistral()\n```\n\n资料来源：[weave/integrations/README.md:30-60]()\n\n### Patch 函数结构\n\n每个集成需要实现 `get__patcher` 函数：\n\n```python\ndef get__patcher(\n settings: IntegrationSettings | None = None,\n) -> MultiPatcher | NoOpPatcher:\n if settings is None:\n settings = IntegrationSettings()\n\n if not settings.enabled:\n return NoOpPatcher()\n\n global __patcher\n if __patcher is None:\n __patcher = MultiPatcher([\n # 添加具体的补丁对象...\n ])\n return __patcher\n```\n\n## 追踪服务端交互\n\n### 批量上传接口\n\n追踪数据通过 HTTP API 批量上传到 Trace Server：\n\n```mermaid\nsequenceDiagram\n participant SDK as Weave SDK\n participant TS as Trace Server\n participant DB as In-Memory Store\n\n SDK->>TS: POST /call/upsert_batch\n TS->>DB: 存储调用记录\n DB-->>TS: 确认存储\n TS-->>SDK: 200 OK\n\n Note over SDK,TS: 支持生产环境 API 格式\n```\n\n### 模拟服务器\n\n测试环境使用轻量级模拟 Trace Server：\n\n```bash\nREADY=http://127.0.0.1:NNNN\n```\n\n**主要端点：**\n\n| 端点 | 方法 | 用途 |\n|-----|------|-----|\n| `/call/upsert_batch` | POST | 批量上传调用记录 |\n| `/calls/stream_query` | POST | 流式查询调用 |\n| `/test/health` | GET | 健康检查 |\n| `/test/getCalls` | GET | 获取调用列表（测试专用） |\n| `/test/reset` | POST | 重置存储（测试专用） |\n\n资料来源：[trace_server_mock/README.md:15-30]()\n\n## Callable 抽象\n\n### CallableObject 基类\n\nWeave 提供了 `CallableObject` 抽象类，用于构建可追踪的自定义类型：\n\n```typescript\nexport interface Callable {\n run: (input: I) => Promise;\n}\n\nexport abstract class CallableObject\n extends WeaveObject\n implements Callable\n{\n abstract run(input: I): Promise;\n}\n```\n\n### 参数映射\n\n提供了 `mapArgs` 工具函数用于参数重映射：\n\n```typescript\nexport function mapArgs<\n T extends Record,\n M extends Record,\n>(input: T, mapping: M): {[K in keyof M]: T[M[K]]} {\n const result: Partial<{[K in keyof M]: T[M[K]]}> = {};\n\n for (const [newKey, oldKey] of Object.entries(mapping)) {\n if (oldKey in input) {\n result[newKey as keyof M] = input[oldKey];\n }\n }\n return result as {[K in keyof M]: T[M[K]]};\n}\n```\n\n资料来源：[sdks/node/src/fn.ts:1-30]()\n\n## 初始化与配置\n\n### 项目初始化\n\n使用 `init` 函数初始化追踪项目：\n\n```typescript\nimport {init} from 'weave';\n\nawait init('my-awesome-ai-project');\n```\n\n### 追踪选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `shouldPrintCallLink` | boolean | - | 是否打印调用链接到控制台 |\n| `implicitly_patch_integrations` | boolean | true | 是否启用隐式集成补丁 |\n| `callDisplayName` | function | undefined | 自定义调用名称生成器 |\n| `opKind` | string | undefined | 操作类型标识 |\n| `opColor` | string | undefined | UI 显示颜色 |\n\n### 操作装饰器选项\n\n```typescript\ninterface OpOptions any> {\n name?: string;\n callDisplayName?: (args: Parameters) => string;\n bindThis?: any;\n isDecorator?: boolean;\n shouldAdoptThis?: boolean;\n originalFunction?: F;\n context?: ClassMethodDecoratorContext;\n opKind?: string;\n opColor?: string;\n}\n```\n\n## 数据序列化\n\n### 序列化策略\n\n追踪数据支持多种序列化策略：\n\n| 策略 | 适用场景 | 说明 |\n|-----|---------|------|\n| 文件序列化 | 大型对象（如图片） | 通过 `MemTraceFilesArtifact` 存储 |\n| 内联序列化 | 小型对象（如 datetime） | 直接存储在 Call 对象中 |\n\n### 内置序列化类型\n\nWeave 内置以下第一类序列化器：\n\n- **图片**: `PIL.Image.Image`\n- **音频**: `wave.Wave_read`\n- **操作**: `weave.Op`\n- **日期时间**: `datetime.datetime`\n- **Markdown**: `rich.markdown.Markdown`\n\n资料来源：[weave/trace/serialization/README.md:20-35]()\n\n## 调用链路追踪\n\n### 父子调用关系\n\n每次函数调用都会建立父子调用关系：\n\n```mermaid\ngraph TD\n A[根调用: extract_dinos] --> B[子调用: openai.chat.completions.create]\n B --> C[子调用: model.invoke]\n A --> D[子调用: post_process]\n C --> D\n```\n\n### 调用链接打印\n\n当 `shouldPrintCallLink` 启用且为根调用时，系统会打印追踪链接：\n\n```typescript\nconst TRACE_CALL_EMOJI = '🔍';\nconsole.log(\n `${TRACE_CALL_EMOJI} https://${domain}/${client.projectId}/r/call/${currentCall.callId}`\n);\n```\n\n## 错误处理\n\n### 未初始化警告\n\n当 Weave 未初始化时，追踪调用会被静默跳过：\n\n```typescript\nif (!client) {\n warnOnce(\n 'weave-not-initialized',\n 'WARNING: Weave is not initialized, so calls wont be tracked. Call `weave.init` to initialize before calling ops.'\n );\n return await fn.apply(thisArg, params);\n}\n```\n\n### 补丁失败处理\n\n对于未成功加载的集成，返回 `NoOpPatcher`：\n\n```python\nif not settings.enabled:\n return NoOpPatcher()\n```\n\n## 总结\n\nWeave 的追踪数据流通过以下关键组件实现：\n\n1. **Op 抽象层**：提供统一的函数包装和追踪接口\n2. **Call 上下文管理**：维护调用栈和父子关系\n3. **集成补丁系统**：支持第三方库的自动和手动追踪\n4. **异步迭代器处理**：支持流式输出的增量追踪\n5. **序列化层**：处理复杂数据类型的持久化\n\n整个系统在 Python SDK 和 Node SDK 之间保持了架构一致性，同时针对各语言特性进行了优化适配。\n\n---\n\n\n\n## 函数追踪机制\n\n### 相关页面\n\n相关主题：[追踪数据流](#trace_flow), [模型供应商集成](#vendor_integrations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/trace/op.py](https://github.com/wandb/weave/blob/main/weave/trace/op.py)\n- [weave/trace/op_caller.py](https://github.com/wandb/weave/blob/main/weave/trace/op_caller.py)\n- [weave/trace/op_protocol.py](https://github.com/wandb/weave/blob/main/weave/trace/op_protocol.py)\n- [weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n \n\n# 函数追踪机制\n\n## 概述\n\n函数追踪机制（Function Tracing Mechanism）是 Weave 框架的核心能力之一，用于自动捕获、记录和监控 AI 应用程序中函数的执行情况。该机制通过将普通函数包装为可追踪的 Op（操作）对象，实现对函数调用链路、输入输出、执行时间等关键信息的完整记录。\n\nWeave 的函数追踪机制主要包含以下特性：\n\n- **透明包装**：通过装饰器或显式包装，将现有函数转换为可追踪的 Op\n- **调用链路**：自动维护父子调用关系，构建完整的调用树\n- **属性标注**：支持为操作添加分类标签（如 `llm`、`agent`、`tool`）和自定义颜色\n- **流式支持**：兼容异步生成器，可追踪流式输出的中间结果\n- **集成支持**：通过自动补丁机制，无缝集成第三方 SDK（如 OpenAI、Anthropic）\n\n---\n\n## 核心概念\n\n### Op（操作）\n\nOp 是 Weave 追踪系统的基本单位。每个被追踪的函数都会被包装为一个 Op 对象，它包含以下核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `__isOp` | boolean | 标识该对象为 Op |\n| `__wrappedFunction` | Function | 被包装的原始函数 |\n| `__name` | string | 操作名称 |\n| `__boundThis` | WeaveObject | 绑定的 `this` 上下文 |\n| `__parameterNames` | string[] | 参数名称列表 |\n| `invoke` | CallMethod | 异步调用方法 |\n\nOp 的类型定义同时支持同步函数和异步函数：\n\n```typescript\nexport type Op any> = {\n __isOp: true;\n __wrappedFunction: T;\n __boundThis?: WeaveObject;\n __name: string;\n __savedRef?: OpRef | Promise;\n __parameterNames?: ParameterNamesOption;\n invoke: CallMethod;\n} & T &\n ((\n ...args: Parameters\n ) => ReturnType extends AsyncIterable\n ? AsyncIterable>\n : Promise>>);\n```\n\n资料来源：[sdks/node/src/opType.ts:1-35]()\n\n### Call（调用记录）\n\nCall 是 Op 实际执行时的记录对象，包含以下关键信息：\n\n| 字段 | 说明 |\n|------|------|\n| `callId` | 调用唯一标识符 |\n| `parentCallId` | 父调用 ID（用于构建调用树） |\n| `opId` | 关联的 Op 标识 |\n| `inputs` | 函数输入参数 |\n| `outputs` | 函数输出结果 |\n| `summary` | 摘要信息 |\n| `attributes` | 自定义属性（如 kind、opColor） |\n\n### OpRef（操作引用）\n\nOpRef 是对已保存 Op 的引用，用于持久化和跨会话追踪：\n\n```typescript\nexport class OpRef {\n constructor(\n public projectId: string,\n public objectId: string,\n public digest: string\n ) {}\n\n public uri() {\n return `weave:///${this.projectId}/op/${this.objectId}:${this.digest}`;\n }\n\n public ui_url() {\n const domain = getGlobalDomain();\n return `https://${domain}/${this.projectId}/weave/ops/${this.objectId}/versions/${this.digest}`;\n }\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:78-92]()\n\n---\n\n## 架构设计\n\n### 组件交互图\n\n```mermaid\ngraph TD\n subgraph \"用户代码层\"\n A[Python/JS 函数] --> B[@weave.op 装饰器]\n A --> C[op wrapper 函数]\n A --> D[wrapOpenAI 等集成函数]\n end\n\n subgraph \"Op 创建层\"\n B --> E[createOpWrapper]\n C --> E\n D --> F[get__patcher]\n F --> G[SymbolPatcher/MultiPatcher]\n end\n\n subgraph \"追踪管理层\"\n E --> H[Op 对象]\n G --> H\n H --> I[WeaveClient]\n I --> J[Trace Server]\n end\n\n subgraph \"调用执行层\"\n K[调用 Op] --> L[opWrapper]\n L --> M[pushNewCall]\n M --> N[记录 Call]\n N --> O[返回结果]\n end\n```\n\n### 调用流程图\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant O as Op Wrapper\n participant C as WeaveClient\n participant T as Trace Server\n\n U->>O: 调用追踪函数\n O->>C: pushNewCall()\n C->>C: 生成 callId, parentCallId\n C->>T: 记录调用开始\n O->>O: 执行原函数 fn.apply()\n O->>C: 记录 inputs\n O->>C: 记录 outputs/summary\n O-->>U: 返回执行结果\n```\n\n---\n\n## Op 创建机制\n\n### 装饰器模式\n\nWeave 支持两种装饰器语法：**现代装饰器（Stage 3）** 和 **传统装饰器（Legacy）**。\n\n#### 现代装饰器（Stage 3）\n\n```typescript\nclass MyClass {\n @weave.op({ name: 'customName', opKind: 'llm' })\n async myMethod(input: string): Promise {\n // 实现\n }\n}\n```\n\n#### 传统装饰器\n\n```typescript\nclass MyClass {\n @weave.op('customName')\n async myMethod(input: string): Promise {\n // 实现\n }\n}\n```\n\n装饰器处理器会根据参数自动识别装饰器类型：\n\n```typescript\nfunction isModernDecorator(args: any[]): args is [T, ClassMethodDecoratorContext] {\n return (\n args.length === 2 &&\n (typeof args[0] === 'object' || typeof args[0] === 'function') &&\n (typeof args[1] === 'string' || typeof args[1] === 'symbol')\n );\n}\n```\n\n资料来源：[sdks/node/src/op.ts:20-30]()\n\n### Op 包装函数\n\n`createOpWrapper` 是创建 Op 的核心函数：\n\n```typescript\nexport function createOpWrapper any>(\n fn: T,\n options?: Partial>\n): Op {\n const call = new InternalCall();\n\n const opWrapper = async function (\n this: any,\n ...params: Parameters\n ): Promise>> {\n const client = getGlobalClient();\n const thisArg = options?.isDecorator || options?.shouldAdoptThis\n ? this\n : options?.bindThis;\n\n if (!client) {\n warnOnce('weave-not-initialized', 'WARNING: Weave is not initialized...');\n return await fn.apply(thisArg, params);\n }\n\n const {currentCall, parentCall, newStack} = client.pushNewCall();\n // ... 记录调用详情\n return await fn.apply(thisArg, params);\n };\n\n return opWrapper as Op;\n}\n```\n\n资料来源：[sdks/node/src/op.ts:100-150]()\n\n### 配置选项\n\n`OpOptions` 接口定义了创建 Op 时的所有可配置项：\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 自定义操作名称 |\n| `streamReducer` | StreamReducer | 流式输出的 reducer 函数 |\n| `originalFunction` | T | 原始函数引用 |\n| `callDisplayName` | function | 动态生成调用显示名 |\n| `summarize` | function | 结果摘要生成函数 |\n| `bindThis` | WeaveObject | 绑定的 this 对象 |\n| `isDecorator` | boolean | 是否为装饰器模式 |\n| `shouldAdoptThis` | boolean | 是否采用原函数 this |\n| `parameterNames` | ParameterNamesOption | 参数名称 |\n| `opKind` | string | 操作类型分类 |\n| `opColor` | string | UI 显示颜色 |\n\n资料来源：[sdks/node/src/opType.ts:130-155]()\n\n---\n\n## 自动补丁机制\n\n自动补丁机制允许 Weave 在第三方 SDK 导入时自动注入追踪代码，无需用户显式修改业务代码。\n\n### 工作原理\n\n```mermaid\ngraph LR\n A[import openai] --> B[Import Hook]\n B --> C[sys.meta_path]\n C --> D[detect openai module]\n D --> E[调用 patch_openai]\n E --> F[SymbolPatcher.patch]\n F --> G[替换目标方法]\n G --> H[返回原始导入]\n```\n\n### 集成注册\n\n在 `weave/integrations/patch.py` 中注册新的集成：\n\n```python\ndef patch_(settings: IntegrationSettings | None = None) -> None:\n \"\"\"Enable Weave tracing for .\"\"\"\n from weave.integrations.._sdk import get__patcher\n\n if settings is None:\n settings = IntegrationSettings()\n get__patcher(settings).attempt_patch()\n```\n\n每个集成需要实现 `get__patcher` 函数，返回一个 `MultiPatcher` 或 `NoOpPatcher` 对象。\n\n### 补丁器类型\n\n| 类型 | 说明 |\n|------|------|\n| `SymbolPatcher` | 单符号补丁器 |\n| `MultiPatcher` | 多符号补丁器 |\n| `NoOpPatcher` | 空操作补丁器（禁用时使用） |\n\n### 隐式补丁控制\n\n用户可以通过以下方式禁用隐式补丁：\n\n```python\n# 方式一：通过设置参数\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\n\n# 方式二：通过环境变量\n# export WEAVE_IMPLICITLY_PATCH_INTEGRATIONS=false\n```\n\n禁用后，用户需要显式调用补丁函数：\n\n```python\nweave.integrations.patch_openai() # 启用 OpenAI 追踪\nweave.integrations.patch_anthropic() # 启用 Anthropic 追踪\nweave.integrations.patch_mistral() # 启用 Mistral 追踪\n```\n\n资料来源：[weave/trace/autopatch.py](), [weave/integrations/patch.py]()\n\n---\n\n## 集成设置\n\n### IntegrationSettings\n\n每个集成可以通过 `IntegrationSettings` 进行配置：\n\n```python\nclass IntegrationSettings(BaseModel):\n enabled: bool = True # 启用/禁用该集成\n # 其他集成特定配置\n```\n\n### AutopatchSettings\n\n在 `weave/trace/autopatch.py` 的 `AutopatchSettings` 类中注册集成：\n\n```python\nclass AutopatchSettings(BaseModel):\n implicitly_patch_integrations: bool = True\n # 其他字段...\n openai: IntegrationSettings = Field(default_factory=IntegrationSettings)\n anthropic: IntegrationSettings = Field(default_factory=IntegrationSettings)\n mistral: IntegrationSettings = Field(default_factory=IntegrationSettings)\n```\n\n---\n\n## 使用示例\n\n### Python 端\n\n#### 装饰器模式\n\n```python\nimport weave\n\n@weave.op\ndef extract_fruit(sentence: str) -> list:\n \"\"\"从句子中提取水果名称\"\"\"\n fruits = [\"apple\", \"banana\", \"cherry\"]\n return [f for f in fruits if f in sentence.lower()]\n\nweave.init(\"my-project\")\nresult = extract_fruit(\"I ate an apple and a banana\")\n```\n\n#### 带配置的 Op\n\n```python\n@weave.op(name=\"custom-extract\", op_kind=\"tool\")\nasync def extract_entities(text: str) -> dict:\n \"\"\"提取命名实体\"\"\"\n # 实现\n return {\"entities\": []}\n```\n\n### JavaScript/TypeScript 端\n\n#### 基础用法\n\n```typescript\nimport {init, op} from 'weave';\n\nconst extractDinos = op(async function extractDinos(input: string) {\n // 业务逻辑\n return result;\n});\n\nawait init('my-project');\nconst result = await extractDinos('Tyrannosaurus rex');\n```\n\n#### 类装饰器用法\n\n```typescript\nimport * as weave from \"weave\";\n\nclass MyAgent {\n @weave.op\n async process(input: string): Promise {\n return `Processed: ${input}`;\n }\n}\n```\n\n#### 集成追踪\n\n```typescript\nimport {OpenAI} from 'openai';\nimport {init, wrapOpenAI} from 'weave';\n\nawait init('my-project');\nconst openai = wrapOpenAI(new OpenAI());\n\nconst response = await openai.chat.completions.create({\n model: 'gpt-4o',\n messages: [{role: 'user', content: 'Hello!'}]\n});\n```\n\n---\n\n## 流式输出支持\n\nWeave 的函数追踪机制完整支持异步生成器（AsyncGenerator），用于处理流式输出场景。\n\n### StreamReducer 配置\n\n```typescript\nexport interface StreamReducer {\n initialStateFn: () => R; // 初始状态\n reduceFn: (state: R, chunk: T) => R; // 累积函数\n finalizeFn: (state: R) => void; // 最终处理\n}\n```\n\n### Op 类型中的流式支持\n\nOp 的返回类型会根据原函数是否为异步生成器自动适配：\n\n```typescript\nexport type Op any> = {\n // ...\n} & T &\n ((\n ...args: Parameters\n ) => ReturnType extends AsyncIterable\n ? AsyncIterable>\n : Promise>>);\n```\n\n资料来源：[sdks/node/src/opType.ts:15-20]()\n\n---\n\n## 调用方法\n\nOp 对象提供两种调用方式：\n\n### 直接调用\n\n```typescript\nconst result = await myOp(arg1, arg2);\n```\n\n### 通过 invoke 方法调用\n\n```typescript\nconst [result, call] = await myOp.invoke(arg1, arg2);\n// call 对象包含详细的调用信息\n```\n\n`invoke` 方法返回 `[结果, Call]` 元组，方便访问调用记录：\n\n```typescript\nexport interface CallMethod any> {\n (\n this: any,\n ...params: Parameters\n ): Promise<[Awaited>, Call]>;\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:100-108]()\n\n---\n\n## 最佳实践\n\n### 命名规范\n\n| 场景 | 推荐命名 | 示例 |\n|------|----------|------|\n| 普通函数 | 使用动词/动词短语 | `extract_entities` |\n| LLM 调用 | 使用 `llm` kind | `@weave.op({opKind: 'llm'})` |\n| Agent 方法 | 使用 `agent` kind | `@weave.op({opKind: 'agent'})` |\n| 工具函数 | 使用 `tool` kind | `@weave.op({opKind: 'tool'})` |\n\n### 性能考虑\n\n1. **避免在热路径中创建大量 Op**：Op 创建有轻微开销\n2. **使用 summarize 精简输出**：对于大对象，使用摘要而非完整记录\n3. **合理设置参数名称**：有助于调试和可读性\n\n### 调试建议\n\n1. 使用 `callDisplayName` 动态生成更详细的调用名称\n2. 检查 `WEAVE_DEBUG` 环境变量启用调试日志\n3. 使用 `weave.integrations.patch_()` 手动控制补丁应用\n\n---\n\n\n\n## 评估系统\n\n### 相关页面\n\n相关主题：[评分器模块](#scorers)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/flow/scorer.py](https://github.com/wandb/weave/blob/main/weave/flow/scorer.py)\n- [weave/evaluation/eval.py](https://github.com/wandb/weave/blob/main/weave/evaluation/eval.py)\n- [weave/evaluation/eval_imperative.py](https://github.com/wandb/weave/blob/main/weave/evaluation/eval_imperative.py)\n- [weave/flow/leaderboard.py](https://github.com/wandb/weave/blob/main/weave/flow/leaderboard.py)\n \n\n# 评估系统\n\n## 概述\n\n评估系统（Evaluation System）是 Weave 项目中用于评测 AI 模型和应用性能的核心模块。根据项目文档，评估相关代码主要位于 `weave/flow` 目录下，包括评分器（Scorer）、评估运行器（Evaluator）和排行榜（Leaderboard）三个主要组件。\n\n评估系统的主要功能包括：\n\n- 对模型输出进行自动化评分\n- 支持自定义评分逻辑\n- 运行批量评估任务\n- 追踪和比较不同模型版本的表现\n- 提供排行榜功能用于结果展示\n\n资料来源：[README.md](https://github.com/wandb/weave/blob/main/README.md)\n\n---\n\n## 系统架构\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[用户定义数据集] --> B[Evaluation 运行器]\n B --> C[Scorer 评分器]\n C --> D[评分结果]\n D --> E[Leaderboard 排行榜]\n F[Weave Client] --> B\n G[Trace Server] --> D\n```\n\n### 组件职责\n\n| 组件 | 文件位置 | 职责描述 |\n|------|----------|----------|\n| Scorer | `weave/flow/scorer.py` | 定义评分逻辑，对模型输出进行评估 |\n| Evaluation | `weave/evaluation/eval.py` | 评估运行器，管理评估流程 |\n| EvaluationImperative | `weave/evaluation/eval_imperative.py` | 命令式评估接口 |\n| Leaderboard | `weave/flow/leaderboard.py` | 结果汇总和排行榜展示 |\n\n资料来源：[weave/flow/scorer.py](https://github.com/wandb/weave/blob/main/weave/flow/scorer.py)\n\n---\n\n## Scorer 评分器\n\n### 功能描述\n\nScorer 是评估系统的核心组件，负责定义和应用评分逻辑。它允许用户通过自定义函数或预置评分器对模型输出进行评估。\n\n### 评分器类型\n\n评估系统支持多种类型的评分器：\n\n| 评分器类型 | 用途 |\n|-----------|------|\n| 函数评分器 | 用户自定义 Python 函数作为评分逻辑 |\n| 准确率评分器 | 计算正确答案的比例 |\n| 匹配评分器 | 检查输出是否匹配预期结果 |\n| 自定义评分器 | 支持复杂的多维度评分 |\n\n### 使用方式\n\n```python\nfrom weave.flow.scorer import Scorer, accuracy_scorer\n\n# 使用预置评分器\nscorer = accuracy_scorer()\n\n# 或创建自定义评分器\ndef custom_scorer(output, expected):\n return {\"score\": 1.0 if output == expected else 0.0}\n\ncustom = Scorer(custom_scorer)\n```\n\n资料来源：[weave/flow/scorer.py](https://github.com/wandb/weave/blob/main/weave/flow/scorer.py)\n\n---\n\n## Evaluation 运行器\n\n### 功能描述\n\nEvaluation 运行器负责协调整个评估流程，包括数据输入、模型调用、评分执行和结果收集。\n\n### 评估工作流\n\n```mermaid\ngraph LR\n A[输入数据] --> B[初始化评估]\n B --> C[遍历样本]\n C --> D[调用被评估函数]\n D --> E[执行评分]\n E --> F[收集结果]\n F --> G{是否完成}\n G -->|否| C\n G -->|是| H[生成报告]\n```\n\n### 核心方法\n\n| 方法名 | 功能 |\n|--------|------|\n| `run` | 运行完整评估流程 |\n| `evaluate` | 评估单个样本 |\n| `get_results` | 获取评估结果 |\n| `summary` | 生成评估摘要 |\n\n资料来源：[weave/evaluation/eval.py](https://github.com/wandb/weave/blob/main/weave/evaluation/eval.py)\n\n---\n\n## 命令式评估接口\n\n### 功能描述\n\n`EvaluationImperative` 提供了更灵活的命令式评估接口，允许用户逐步控制评估过程。\n\n### 接口特点\n\n- 支持分步执行评估任务\n- 允许在评估过程中插入自定义逻辑\n- 提供更细粒度的结果控制\n\n### 基本用法\n\n```python\nfrom weave.evaluation.eval_imperative import EvaluationImperative\n\nevaluator = EvaluationImperative()\n\n# 添加单个评估样本\nevaluator.add_sample(input_data, expected_output)\n\n# 运行评估\nresults = evaluator.run(scorer=my_scorer)\n```\n\n资料来源：[weave/evaluation/eval_imperative.py](https://github.com/wandb/weave/blob/main/weave/evaluation/eval_imperative.py)\n\n---\n\n## Leaderboard 排行榜\n\n### 功能描述\n\nLeaderboard 用于汇总和展示评估结果，支持不同模型/版本之间的性能比较。\n\n### 特性\n\n| 特性 | 描述 |\n|------|------|\n| 多维度评分 | 支持展示多个评分维度 |\n| 版本追踪 | 记录不同版本的评估结果 |\n| 排序展示 | 按评分高低排序展示 |\n\n### 数据模型\n\n```mermaid\nclassDiagram\n class Leaderboard {\n +str name\n +List~EvaluationResult~ results\n +add_result(result)\n +get_rankings()\n +export(format)\n }\n \n class EvaluationResult {\n +str version\n +Dict scores\n +timestamp\n }\n \n Leaderboard \"1\" --> \"*\" EvaluationResult\n```\n\n资料来源：[weave/flow/leaderboard.py](https://github.com/wandb/weave/blob/main/weave/flow/leaderboard.py)\n\n---\n\n## 数据流\n\n### 完整评估数据流\n\n```mermaid\nflowchart TD\n subgraph 输入层\n A[测试数据集]\n B[评估函数]\n C[评分器定义]\n end\n \n subgraph 处理层\n D[Evaluation 运行器]\n E[模型调用]\n F[结果收集]\n end\n \n subgraph 输出层\n G[评估结果]\n H[Leaderboard]\n I[Trace Server]\n end\n \n A --> D\n B --> D\n C --> D\n D --> E\n E --> F\n F --> G\n G --> H\n G --> I\n```\n\n### Trace Server 集成\n\n评估结果会自动发送到 Weave Trace Server 进行持久化存储，支持后续分析和可视化。\n\n资料来源：[weave/evaluation/eval.py](https://github.com/wandb/weave/blob/main/weave/evaluation/eval.py)\n\n---\n\n## 配置选项\n\n### 评估配置参数\n\n| 参数名 | 类型 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `project` | string | 必填 | Weave 项目名称 |\n| `entity` | string | 可选 | 用户或团队名称 |\n| `scorer` | Scorer | 必填 | 评分器实例 |\n| `max_workers` | int | 4 | 并行评估的线程数 |\n| `save_results` | bool | true | 是否保存结果 |\n\n---\n\n## 与 Node SDK 的集成\n\n### TypeScript 评估支持\n\nNode SDK (`sdks/node`) 提供了评估相关的基础设施，虽然核心评估逻辑主要在 Python 端实现，但 Node SDK 支持：\n\n- 使用 `weave` 装饰器追踪评估过程\n- 通过 `op` 函数包装评估目标\n- 与 Trace Server 通信获取评估结果\n\n```javascript\nimport {op} from 'weave';\n\nconst evaluateModel = op(async function evaluateModel(input) {\n // 评估逻辑\n return result;\n});\n```\n\n资料来源：[sdks/node/src/evaluation.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/evaluation.ts)\n\n---\n\n## 使用示例\n\n### 完整评估流程\n\n```python\nimport weave\nfrom weave.flow.scorer import Scorer, accuracy_scorer\nfrom weave.evaluation.eval import Evaluation\n\n# 初始化 Weave\nweave.init('my-evaluation-project')\n\n# 定义评分器\nscorer = accuracy_scorer()\n\n# 定义评估数据\ntest_data = [\n {\"input\": \"What is 2+2?\", \"expected\": \"4\"},\n {\"input\": \"What is 3+3?\", \"expected\": \"6\"},\n]\n\n# 创建并运行评估\nevaluation = Evaluation(\n name=\"math-evaluation\",\n scorer=scorer,\n)\n\nresults = evaluation.run(\n dataset=test_data,\n evaluate_fn=my_model_fn\n)\n\n# 查看排行榜\nleaderboard = evaluation.get_leaderboard()\nprint(leaderboard)\n```\n\n资料来源：[weave/flow/scorer.py](https://github.com/wandb/weave/blob/main/weave/flow/scorer.py)\n\n---\n\n## 最佳实践\n\n### 1. 评分器设计\n\n- 保持评分逻辑简单和可测试\n- 使用确定性评分器确保结果可复现\n- 为复杂评分场景实现多维度评分\n\n### 2. 评估执行\n\n- 使用适当的并行度加速评估\n- 确保测试数据质量，避免脏数据影响评估\n- 定期校准评分标准\n\n### 3. 结果分析\n\n- 关注评分分布而非单一指标\n- 使用 Leaderboard 追踪模型改进\n- 结合 Trace Server 进行深入分析\n\n---\n\n## 相关资源\n\n| 资源 | 位置 | 描述 |\n|------|------|------|\n| 评分器模块 | `weave/flow/scorer.py` | 评分逻辑定义 |\n| 评估运行器 | `weave/evaluation/eval.py` | 评估流程管理 |\n| 命令式接口 | `weave/evaluation/eval_imperative.py` | 灵活评估接口 |\n| 排行榜模块 | `weave/flow/leaderboard.py` | 结果展示 |\n| Node SDK 评估 | `sdks/node/src/evaluation.ts` | TypeScript 评估支持 |\n\n---\n\n\n\n## 评分器模块\n\n### 相关页面\n\n相关主题：[评估系统](#evaluation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/scorers](https://github.com/wandb/weave/blob/main/weave/scorers)\n- [weave/scorers/llm_as_a_judge_scorer.py](https://github.com/wandb/weave/blob/main/weave/scorers/llm_as_a_judge_scorer.py)\n- [weave/scorers/classification_scorer.py](https://github.com/wandb/weave/blob/main/weave/scorers/classification_scorer.py)\n- [weave/scorers/scorer_types.py](https://github.com/wandb/weave/blob/main/weave/scorers/scorer_types.py)\n \n\n# 评分器模块\n\n## 概述\n\n根据对 Weave 仓库的分析，评分器模块（Scorers Module）是 Weave 评估系统的核心组件之一，负责对 AI 应用的输出结果进行量化评估。该模块位于 `weave/scorers` 目录下，为开发者提供了标准化的评估接口和多种开箱即用的评分器实现。\n\n根据仓库结构，Weave 的评估代码主要集中在 `weave/flow` 目录中。资料来源：[README.md:54]()\n\n评分器模块的主要职责包括：\n\n1. **结果评分**：对 LLM、Agent、Tool 等操作的输出进行标准化评分\n2. **多维度评估**：支持单一指标和多维度综合评估\n3. **自定义扩展**：允许开发者创建自定义评分器以满足特定业务需求\n4. **评估流程集成**：与 Weave 的追踪系统无缝集成，支持端到端的可观测性\n\n## 核心架构\n\n### 模块目录结构\n\n```\nweave/scorers/\n├── __init__.py\n├── scorer_types.py # 评分器类型定义\n├── llm_as_a_judge_scorer.py # LLM 评判评分器\n├── classification_scorer.py # 分类评分器\n└── [其他评分器实现]\n```\n\n### 设计模式\n\n评分器模块采用面向对象的设计模式，定义了一套标准的评分器接口。所有评分器均继承自基类 `Scorer`，实现统一的评估方法。这种设计模式确保了评分器之间的可互换性和可扩展性。\n\n## 内置评分器\n\n### LLM 即评判评分器 (LLM As A Judge Scorer)\n\n`LLMAsAJudgeScorer` 是 Weave 提供的一种高级评分器，利用大型语言模型作为评判者来评估其他 LLM 输出的质量。这种方法被称为\"LLM 评判\"或\"AI 评估\"，是 AI 系统评估领域的重要技术。\n\n资料来源：[weave/scorers/llm_as_a_judge_scorer.py]()\n\n**核心特性**：\n\n| 特性 | 说明 |\n|------|------|\n| 灵活 prompt 模板 | 支持自定义评估 prompt |\n| 多维度评分 | 可同时评估多个维度 |\n| 可解释性 | 提供评分理由 |\n| 批量评估 | 支持批量处理多个样本 |\n\n### 分类评分器 (Classification Scorer)\n\n`ClassificationScorer` 专门用于评估分类任务的准确性。它通过比较模型预测结果与真实标签来计算各种分类指标。\n\n资料来源：[weave/scorers/classification_scorer.py]()\n\n**支持的评估指标**：\n\n| 指标名称 | 说明 |\n|----------|------|\n| Accuracy | 分类准确率 |\n| Precision | 精确率 |\n| Recall | 召回率 |\n| F1-Score | F1 分数 |\n| Confusion Matrix | 混淆矩阵 |\n\n## 评分器类型系统\n\n评分器模块定义了一套完整的类型系统，用于规范化评分器的输入输出。\n\n资料来源：[weave/scorers/scorer_types.py]()\n\n### 核心类型定义\n\n```python\n# 评分结果类型\nclass ScoreResult:\n name: str # 评分器名称\n value: float # 评分值\n reason: str # 评分理由\n metadata: dict # 附加元数据\n\n# 评分器基类\nclass Scorer(ABC):\n @abstractmethod\n async def score(self, input_data, output_data) -> ScoreResult:\n pass\n```\n\n### 类型层级关系\n\n```mermaid\ngraph TD\n A[Scorer 基类] --> B[LLMAsAJudgeScorer]\n A --> C[ClassificationScorer]\n A --> D[CustomScorer]\n B --> E[单一维度评判]\n B --> F[多维度评判]\n C --> G[二分类]\n C --> H[多分类]\n```\n\n## 评分器工作流程\n\n### 评估流程图\n\n```mermaid\ngraph TD\n A[输入数据] --> B[选择评分器]\n B --> C[LLM 评判]\n B --> D[分类评估]\n B --> E[自定义评估]\n C --> F[生成评估 Prompt]\n D --> G[计算分类指标]\n E --> H[执行业务逻辑]\n F --> I[调用 LLM API]\n G --> J[输出评分结果]\n H --> J\n I --> J\n J --> K[返回 ScoreResult]\n```\n\n### 异步评分流程\n\n评分器采用异步设计，支持高并发评估场景：\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Scorer as 评分器\n participant LLM as LLM API\n participant Weave as Weave 追踪\n \n Client->>Scorer: 提交评分请求\n Scorer->>Scorer: 验证输入\n Scorer->>LLM: 发送评估请求\n LLM-->>Scorer: 返回评估结果\n Scorer->>Weave: 记录评估过程\n Scorer-->>Client: 返回 ScoreResult\n```\n\n## 与追踪系统集成\n\n评分器模块与 Weave 的追踪系统深度集成，提供了完整的可观测性支持。\n\n### 集成方式\n\n1. **自动追踪**：评分器的执行过程自动记录到 Weave 追踪服务器\n2. **上下文传递**：评分器可以访问被评分操作的完整上下文信息\n3. **结果关联**：评分结果与原始调用自动关联\n\n```python\n# 评分器使用示例\nimport weave\n\n@weave.op()\nasync def my_evaluation(input_data):\n # 使用评分器评估\n scorer = LLMAsAJudgeScorer(prompt_template=my_template)\n result = await scorer.score(input_data, model_output)\n return result\n```\n\n资料来源：[sdks/node/src/opType.ts:1-30]()\n\n## 扩展评分器\n\n### 创建自定义评分器\n\n开发者可以通过继承 `Scorer` 基类来创建自定义评分器：\n\n```python\nfrom weave.scorers import Scorer, ScoreResult\n\nclass MyCustomScorer(Scorer):\n def __init__(self, config):\n self.config = config\n \n async def score(self, input_data, output_data) -> ScoreResult:\n # 自定义评分逻辑\n score_value = self.calculate_score(output_data)\n return ScoreResult(\n name=\"my_custom_scorer\",\n value=score_value,\n reason=\"Custom evaluation reason\",\n metadata={\"config\": self.config}\n )\n```\n\n### 评分器配置选项\n\n| 配置项 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `name` | str | 评分器名称 | 类名 |\n| `description` | str | 评分器描述 | 空字符串 |\n| `threshold` | float | 通过阈值 | 0.0 |\n| `aggregation` | str | 聚合方式 | \"mean\" |\n\n## 最佳实践\n\n### 1. 选择合适的评分器\n\n| 场景 | 推荐评分器 |\n|------|------------|\n| LLM 输出质量评估 | LLMAsAJudgeScorer |\n| 分类模型评估 | ClassificationScorer |\n| 自定义业务逻辑 | CustomScorer |\n\n### 2. 性能优化建议\n\n- **批量评分**：使用批量接口减少 API 调用开销\n- **异步执行**：充分利用异步能力提高吞吐量\n- **缓存结果**：对于相同输入，可考虑缓存评分结果\n\n### 3. 评估结果分析\n\n评分结果应包含：\n\n- 原始分数值\n- 详细的评分理由\n- 相关的元数据\n- 与其他评估维度的关联信息\n\n## 总结\n\n评分器模块是 Weave 评估系统的基础组件，提供了标准化、可扩展的评估能力。通过内置的 LLM 评判评分器和分类评分器，开发者可以快速构建 AI 应用的评估流程。同时，该模块支持深度定制，满足各种复杂的业务评估需求。\n\n与 Weave 的追踪系统集成后，评分器不仅能够提供量化评估结果，还能记录完整的评估上下文，为 AI 应用的持续优化提供了数据基础。\n\n---\n\n\n\n## 模型供应商集成\n\n### 相关页面\n\n相关主题：[框架集成](#framework_integrations), [函数追踪机制](#tracing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/integrations/README.md](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n- [weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n- [sdks/node/src/integrations/googleGenAI.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/integrations/googleGenAI.ts)\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [weave/trace_server_mock/README.md](https://github.com/wandb/weave/blob/main/trace_server_mock/README.md)\n \n\n# 模型供应商集成\n\n## 概述\n\n模型供应商集成（Model Vendor Integration）是 Weave 框架中用于自动追踪和监控第三方 AI 模型供应商 SDK 调用的一种机制。通过隐式补丁（Implicit Patching）和显式补丁（Explicit Patching）两种模式，开发者可以在几乎不修改业务代码的情况下，将 OpenAI、Anthropic、Google GenAI、Mistral 等主流 AI 服务商的 API 调用自动记录到 Weave 追踪系统中。\n\n集成架构的核心设计理念是：**零侵入式追踪**。Weave 通过 Python 的 `sys.meta_path` 导入钩子机制，在支持的供应商库被导入时自动应用补丁，使追踪功能对业务代码完全透明。\n\n资料来源：[weave/integrations/README.md:1-30]()\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[用户代码] -->|import weave| B[Weave 初始化]\n B --> C{隐式补丁启用?}\n C -->|是| D[sys.meta_path 导入钩子]\n C -->|否| E[手动调用 patch_xxx]\n D --> F[供应商库导入]\n F --> G[自动调用 patch_xxx]\n G --> H[Monkey Patch 注入]\n H --> I[API 调用拦截]\n I --> J[Weave Client]\n J --> K[Trace Server]\n E --> L[手动 patch 函数]\n L --> H\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| **Patcher 基类** | `weave/integrations/patcher.py` | 定义统一补丁接口 |\n| **Patch 注册器** | `weave/integrations/patch.py` | 统一暴露各供应商 patch 函数 |\n| **Autopatch 机制** | `weave/trace/autopatch.py` | 管理隐式补丁配置 |\n| **供应商 SDK 包装器** | `weave/integrations//_sdk.py` | 具体供应商的追踪实现 |\n\n资料来源：[weave/integrations/patch.py:1-50]()\n\n## 集成注册机制\n\n### 供应商集成结构\n\n每个供应商集成都遵循统一的项目结构：\n\n```\nweave/integrations/\n├── __init__.py\n├── openai/\n│ ├── __init__.py\n│ ├── openai_sdk.py\n│ └── openai_test.py\n├── anthropic/\n│ ├── __init__.py\n│ ├── anthropic_sdk.py\n│ └── anthropic_test.py\n├── google_genai/\n│ ├── __init__.py\n│ ├── google_genai_sdk.py\n│ └── google_genai_test.py\n└── mistral/\n ├── __init__.py\n ├── mistral_sdk.py\n └── mistral_test.py\n```\n\n资料来源：[weave/integrations/README.md:45-60]()\n\n### 注册新供应商集成\n\n开发新的供应商集成需要完成以下步骤：\n\n1. 在 `weave/integrations/` 下创建供应商文件夹\n2. 实现 `_sdk.py` 核心补丁逻辑\n3. 在 `patch.py` 中注册 patch 函数\n4. 在 `AutopatchSettings` 中添加配置字段\n\n#### Step 1: 创建 patch 函数\n\n在 `weave/integrations/patch.py` 中添加：\n\n```python\ndef patch_(settings: IntegrationSettings | None = None) -> None:\n \"\"\"Enable Weave tracing for .\"\"\"\n from weave.integrations.._sdk import get__patcher\n\n if settings is None:\n settings = IntegrationSettings()\n get__patcher(settings).attempt_patch()\n```\n\n资料来源：[weave/integrations/README.md:60-85]()\n\n#### Step 2: 添加配置支持\n\n在 `weave/trace/autopatch.py` 的 `AutopatchSettings` 类中添加：\n\n```python\nclass AutopatchSettings(BaseModel):\n # ... existing fields ...\n : IntegrationSettings = Field(default_factory=IntegrationSettings)\n```\n\n资料来源：[weave/integrations/README.md:100-110]()\n\n## 补丁机制详解\n\n### 隐式补丁（Implicit Patching）\n\n隐式补丁通过 Python 的 `sys.meta_path` 导入钩子实现。当 `weave.init()` 被调用时，Weave 注册一个自定义的导入finder，该 finder 会拦截对支持供应商库的导入请求。\n\n```python\n# 启用隐式补丁（默认行为）\nweave.init(\"my-project\")\nimport openai # 自动被追踪!\n\n# 禁用隐式补丁\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\n```\n\n资料来源：[weave/integrations/README.md:25-40]()\n\n### 显式补丁（Explicit Patching）\n\n显式补丁允许开发者手动控制何时启用追踪：\n\n```python\nimport weave\n\n# 初始化时禁用隐式补丁\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\n\n# 显式启用特定集成\nweave.integrations.patch_openai()\nweave.integrations.patch_anthropic()\nweave.integrations.patch_mistral()\n\n# 使用供应商 SDK\nfrom openai import OpenAI\nclient = OpenAI()\nresponse = client.chat.completions.create(...) # 会被追踪\n```\n\n资料来源：[weave/integrations/README.md:40-55]()\n\n### 补丁执行流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant P as Patcher\n participant V as 供应商 SDK\n participant W as Weave Client\n\n U->>P: attempt_patch()\n P->>V: 获取目标方法\n P->>P: 保存原始方法引用\n P->>V: 注入包装方法\n U->>V: 调用 API\n V->>W: 记录调用信息\n W->>U: 返回结果\n Note over P: undo_patch() 可恢复原始行为\n```\n\n## 供应商 SDK 包装模式\n\n### OpenAI 包装\n\nOpenAI 集成通过 Monkey Patch 方式包装 `openai.OpenAI` 客户端的关键方法：\n\n- `chat.completions.create` → 包装为 Op\n- 流式响应通过 `streamReducer` 处理\n\n```python\ndef wrapOpenAI(openai: OpenAI): T {\n // 包装 chat.completions.create\n return wrappedClient\n}\n```\n\n资料来源：[sdks/node/src/op.ts:1-30]()\n\n### Google GenAI 包装\n\nGoogle GenAI 集成使用 Proxy 模式包装 `models` 对象：\n\n```typescript\nconst wrappedModels = new Proxy(models, {\n get(target, prop, receiver) {\n if (prop === 'generateContent') {\n return wrappedGenerateContent;\n }\n if (prop === 'generateContentStream') {\n return wrappedGenerateContentStream;\n }\n return Reflect.get(target, prop, receiver);\n },\n});\n```\n\n资料来源：[sdks/node/src/integrations/googleGenAI.ts:80-95]()\n\n### Op 包装器设计\n\nWeave 的核心追踪单元是 `Op`（操作）。Op 包装器接口定义如下：\n\n```typescript\nexport interface OpWrapper any> {\n (this: any, ...params: Parameters): AsyncResult;\n}\n\nexport interface CallMethod any> {\n (\n this: any,\n ...params: Parameters\n ): Promise<[Awaited>, Call]>;\n}\n```\n\nOp 包装器支持多种使用模式：\n\n| 模式 | 签名 | 用途 |\n|------|------|------|\n| 函数包装 | `op(fn)` | 装饰器风格 |\n| 选项包装 | `op(fn, options)` | 自定义配置 |\n| 装饰器工厂 | `@op(options)` | Stage 3 装饰器 |\n| 传统装饰器 | `@op` | 兼容旧语法 |\n\n资料来源：[sdks/node/src/opType.ts:40-75]()\n\n## 配置管理\n\n### IntegrationSettings\n\n每个供应商集成都有独立的配置对象：\n\n```python\nclass IntegrationSettings(BaseModel):\n enabled: bool = True\n # 供应商特定配置选项\n```\n\n### AutopatchSettings\n\n```python\nclass AutopatchSettings(BaseModel):\n openai: IntegrationSettings = Field(default_factory=IntegrationSettings)\n anthropic: IntegrationSettings = Field(default_factory=IntegrationSettings)\n mistral: IntegrationSettings = Field(default_factory=IntegrationSettings)\n # 新供应商...\n```\n\n### 环境变量配置\n\n| 变量名 | 值 | 作用 |\n|--------|-----|------|\n| `WEAVE_IMPLICITLY_PATCH_INTEGRATIONS` | `true`/`false` | 全局控制隐式补丁 |\n\n资料来源：[weave/integrations/README.md:28-35]()\n\n## 测试框架\n\n### VCR 测试模式\n\nWeave 使用 `pytest-recording`（基于 vcrpy）进行集成测试：\n\n```python\n@pytest.mark.vcr(\n filter_headers=[\"authorization\"],\n allowed_hosts=[\"api.wandb.ai\", \"localhost\"],\n)\ndef test__quickstart(\n client: weave.weave_client.WeaveClient,\n patch_: None,\n) -> None:\n # 测试代码\n calls = list(client.get_calls())\n assert len(calls) == 1\n```\n\n### 测试夹具\n\n```python\n@pytest.fixture()\ndef patch_() -> Generator[None, None, None]:\n from weave.integrations.._sdk import get__patcher\n\n patcher = get__patcher()\n patcher.attempt_patch()\n yield\n patcher.undo_patch()\n```\n\n资料来源：[weave/integrations/README.md:120-140]()\n\n### 运行测试\n\n```bash\n# 录制模式\nMISTRAL_API_KEY=... pytest --record-mode=rewrite weave/integrations/mistral/mistral_test.py\n\n# 重放模式\npytest weave/integrations/mistral/mistral_test.py\n\n# 生产环境测试\nMISTRAL_API_KEY=... pytest --trace-server=prod weave/integrations/mistral/mistral_test.py\n```\n\n资料来源：[weave/integrations/README.md:145-155]()\n\n## Trace Server 接口\n\n### 核心端点\n\n| 端点 | 方法 | 用途 |\n|------|------|------|\n| `/call/upsert_batch` | POST | 批量记录调用 |\n| `/calls/stream_query` | POST | 查询调用历史 |\n| `/test/health` | GET | 健康检查 |\n\n### Mock Server\n\n测试使用内存中的 mock server，支持：\n\n- 项目隔离（通过 `project_id`）\n- 调用记录查询\n- 状态重置\n\n资料来源：[trace_server_mock/README.md:1-40]()\n\n## Op 选项配置\n\n### 可用选项\n\n```typescript\nexport interface OpOptions any> {\n name?: string; // 自定义操作名称\n streamReducer?: StreamReducer; // 流式响应处理\n originalFunction?: T; // 原始函数引用\n callDisplayName?: Function; // 动态显示名称\n summarize?: Function; // 结果摘要生成\n bindThis?: WeaveObject; // this 绑定\n parameterNames?: ParameterNamesOption; // 参数命名\n opKind?: string; // 操作类型（llm/agent/tool/search）\n opColor?: string; // UI 颜色\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:80-105]()\n\n### 流式响应处理\n\n```typescript\nexport interface StreamReducer {\n initialStateFn: () => R;\n reduceFn: (state: R, chunk: T) => R;\n finalizeFn: (state: R) => void;\n}\n```\n\n## 开发指南\n\n### 添加新供应商的检查清单\n\n1. ✅ 创建 `weave/integrations//` 目录\n2. ✅ 实现 `_sdk.py`（继承 Patcher 基类）\n3. ✅ 在 `patch.py` 中添加 `patch_()` 函数\n4. ✅ 在 `AutopatchSettings` 中注册配置\n5. ✅ 创建 `_test.py` 测试文件\n6. ✅ 运行测试并录制 VCR cassettes\n7. ✅ 验证追踪数据正确性\n\n### 常见问题排查\n\n| 问题 | 解决方案 |\n|------|----------|\n| 补丁未生效 | 检查 `implicitly_patch_integrations` 设置 |\n| API Key 错误 | 使用环境变量或设置 dummy key |\n| 测试失败 | 确认 VCR cassettes 录制完整 |\n| 重复追踪 | 避免多次调用 `attempt_patch()` |\n\n资料来源：[weave/integrations/README.md:140-160]()\n\n## 相关资源\n\n- [OpenAI 集成源码](weave/integrations/openai/openai_sdk.py)\n- [Anthropic 集成源码](weave/integrations/anthropic/anthropic_sdk.py)\n- [Google GenAI 集成源码](weave/integrations/google_genai/google_genai_sdk.py)\n- [Mistral 集成源码](weave/integrations/mistral/mistral_sdk.py)\n- [补丁注册器](weave/integrations/patch.py)\n- [Patcher 基类](weave/integrations/patcher.py)\n\n---\n\n\n\n## 框架集成\n\n### 相关页面\n\n相关主题：[模型供应商集成](#vendor_integrations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/integrations/langchain/langchain.py](https://github.com/wandb/weave/blob/main/weave/integrations/langchain/langchain.py)\n- [weave/integrations/dspy/dspy_callback.py](https://github.com/wandb/weave/blob/main/weave/integrations/dspy/dspy_callback.py)\n- [weave/integrations/llamaindex/llamaindex.py](https://github.com/wandb/weave/blob/main/weave/integrations/llamaindex/llamaindex.py)\n- [weave/integrations/crewai/crewai_sdk.py](https://github.com/wandb/weave/blob/main/weave/integrations/crewai/crewai_sdk.py)\n- [weave/integrations/autogen/autogen_sdk.py](https://github.com/wandb/weave/blob/main/weave/integrations/autogen/autogen_sdk.py)\n- [weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n- [weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n \n\n# 框架集成\n\n## 概述\n\n框架集成（Framework Integration）是 Weave 为第三方 AI 框架和 SDK 提供的自动追踪支持机制。通过在 `weave/integrations/` 目录下实现的集成模块，Weave 能够自动拦截和记录用户使用 LangChain、DSPy、LlamaIndex、CrewAI、AutoGen 等主流 AI 框架时的 API 调用，将这些调用以结构化的方式记录到 Weave Trace Server 中。\n\n集成的核心价值在于**零侵入性**——用户无需修改原有代码，通过隐式补丁（Implicit Patching）或显式调用补丁函数，即可启用追踪功能。这种设计使得追踪能力的添加变得透明且可配置。\n\n## 目录结构\n\n每个框架集成都遵循统一的目录结构规范：\n\n```\nweave/integrations/\n├── __init__.py\n├── patch.py # 所有补丁函数的统一入口\n├── langchain/\n│ ├── __init__.py\n│ ├── langchain.py # LangChain 集成核心实现\n│ └── langchain_test.py # 集成测试\n├── dspy/\n│ ├── __init__.py\n│ ├── dspy_callback.py # DSPy 回调实现\n│ └── dspy_test.py\n├── llamaindex/\n│ ├── __init__.py\n│ ├── llamaindex.py # LlamaIndex 集成核心\n│ └── llamaindex_test.py\n├── crewai/\n│ ├── __init__.py\n│ ├── crewai_sdk.py # CrewAI SDK 集成\n│ └── crewai_test.py\n└── autogen/\n ├── __init__.py\n ├── autogen_sdk.py # AutoGen 集成\n └── autogen_test.py\n```\n\n## 核心架构\n\n### 集成架构图\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Weave 初始化]\n B --> C{隐式补丁启用?}\n C -->|是| D[修改 sys.meta_path]\n C -->|否| E[手动调用 patch_* 函数]\n D --> F[import hook 拦截]\n F --> G[Vendor SDK 导入]\n G --> H[自动调用对应 patcher]\n E --> I[调用 patch_]\n I --> J[attempt_patch 执行]\n H --> J\n J --> K[Monkey Patch SDK]\n K --> L[API 调用拦截]\n L --> M[Call 记录创建]\n M --> N[Trace Server 上报]\n \n O[patch_ 函数] --> P[get__patcher]\n P --> Q[Patcher 实例]\n Q --> R[attempt_patch]\n Q --> S[undo_patch]\n```\n\n### 组件职责\n\n| 组件 | 职责 | 典型实现位置 |\n|------|------|-------------|\n| `patch.py` | 统一导出所有补丁函数 | `weave/integrations/patch.py` |\n| `_sdk.py` | 核心补丁逻辑实现 | 各框架目录下 |\n| `IntegrationSettings` | 集成配置数据模型 | `weave/integrations/` |\n| `AutopatchSettings` | 全局自动补丁配置 | `weave/trace/autopatch.py` |\n| `WeaveCallback` | 框架特定的回调处理器 | 各框架目录 |\n\n## 补丁机制\n\n### 隐式补丁流程\n\n当用户初始化 Weave 并设置 `implicitly_patch_integrations=True`（默认值）时，Weave 会修改 Python 的 `sys.meta_path` 导入钩子链：\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant Hook as MetaPath Finder\n participant Patch as patch_\n participant SDK as Vendor SDK\n participant Weave as Weave Tracing\n \n User->>Weave: weave.init(\"project\")\n Weave->>Hook: 注册 Import Hook\n User->>SDK: import openai\n Hook->>Patch: 拦截导入\n Patch->>Patch: attempt_patch()\n Patch->>SDK: Monkey Patch\n SDK-->>User: 返回 patched 模块\n User->>SDK: client.chat.completions.create()\n SDK->>Weave: 触发 WeaveCallback\n Weave->>Weave: 记录 Call\n```\n\n### 显式补丁接口\n\n用户也可以禁用隐式补丁，手动选择要追踪的框架：\n\n```python\nimport weave\n\n# 禁用隐式补丁\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\n\n# 显式启用特定框架追踪\nweave.integrations.patch_openai()\nweave.integrations.patch_anthropic()\nweave.integrations.patch_langchain()\nweave.integrations.patch_llamaindex()\nweave.integrations.patch_dspy()\nweave.integrations.patch_crewai()\nweave.integrations.patch_autogen()\n```\n\n每个补丁函数的签名遵循统一规范：\n\n```python\ndef patch_(settings: IntegrationSettings | None = None) -> None:\n \"\"\"启用 的 Weave 追踪。\"\"\"\n from weave.integrations.._sdk import get__patcher\n \n if settings is None:\n settings = IntegrationSettings()\n get__patcher(settings).attempt_patch()\n```\n\n## 配置系统\n\n### 集成配置类\n\n每个框架都有对应的配置类，用于控制追踪行为：\n\n```python\nclass IntegrationSettings(BaseModel):\n \"\"\"集成配置基类。\"\"\"\n enabled: bool = True\n capture_input: bool = True\n capture_output: bool = True\n tags: list[str] = []\n```\n\n### 全局自动补丁配置\n\n`AutopatchSettings` 类管理所有集成的全局配置：\n\n```python\nclass AutopatchSettings(BaseModel):\n enabled: bool = True\n openai: IntegrationSettings = Field(default_factory=IntegrationSettings)\n anthropic: IntegrationSettings = Field(default_factory=IntegrationSettings)\n langchain: IntegrationSettings = Field(default_factory=IntegrationSettings)\n llamaindex: IntegrationSettings = Field(default_factory=IntegrationSettings)\n dspy: IntegrationSettings = Field(default_factory=IntegrationSettings)\n crewai: IntegrationSettings = Field(default_factory=IntegrationSettings)\n autogen: IntegrationSettings = Field(default_factory=IntegrationSettings)\n```\n\n### 配置方式\n\n| 方式 | 代码示例 | 优先级 |\n|------|---------|--------|\n| 初始化参数 | `weave.init(project, settings={...})` | 高 |\n| 环境变量 | `WEAVE_IMPLICITLY_PATCH_INTEGRATIONS=false` | 中 |\n| 默认值 | `IntegrationSettings()` 构造 | 低 |\n\n## 框架特定集成\n\n### LangChain 集成\n\nLangChain 集成通过实现自定义 Callback Handler 来拦截 LLM 调用：\n\n```python\n# weave/integrations/langchain/langchain.py\nclass WeaveCallbackHandler(BaseCallbackHandler):\n \"\"\"LangChain 的 Weave 回调处理器。\"\"\"\n \n def __init__(self, settings: IntegrationSettings | None = None):\n self.settings = settings or IntegrationSettings()\n # 初始化追踪上下文...\n \n def on_llm_start(self, serialized, prompts, **kwargs):\n \"\"\"LLM 调用开始时记录。\"\"\"\n # 创建 Call 记录...\n \n def on_llm_end(self, response, **kwargs):\n \"\"\"LLM 调用完成时记录结果。\"\"\"\n # 结束 Call 记录...\n```\n\n### DSPy 集成\n\nDSPy 集成使用回调机制捕获模块执行：\n\n```python\n# weave/integrations/dspy/dspy_callback.py\nclass WeaveCallback:\n \"\"\"DSPy 的 Weave 回调实现。\"\"\"\n \n def __init__(self):\n self._calls = []\n \n def before_forward(self, program, inputs):\n \"\"\"模块前向传播前记录。\"\"\"\n pass\n \n def after_forward(self, program, outputs):\n \"\"\"模块前向传播后记录。\"\"\"\n pass\n```\n\n### LlamaIndex 集成\n\n```python\n# weave/integrations/llamaindex/llamaindex.py\nclass WeaveCallbackHandler(BaseCallbackHandler):\n \"\"\"LlamaIndex 的 Weave 回调处理器。\"\"\"\n \n def on_event_start(self, event_type, payload, **kwargs):\n \"\"\"事件开始时记录。\"\"\"\n pass\n \n def on_event_end(self, event_type, payload, **kwargs):\n \"\"\"事件结束时记录。\"\"\"\n pass\n```\n\n### CrewAI 集成\n\n```python\n# weave/integrations/crewai/crewai_sdk.py\ndef get_crewai_patcher(settings: IntegrationSettings | None = None) -> Patcher:\n \"\"\"获取 CrewAI 的补丁实例。\"\"\"\n return CrewAIHandler(settings)\n```\n\n### AutoGen 集成\n\n```python\n# weave/integrations/autogen/autogen_sdk.py\nclass WeaveAutoGenCallback:\n \"\"\"AutoGen 的 Weave 回调实现。\"\"\"\n \n def __init__(self, settings: IntegrationSettings | None = None):\n self.settings = settings or IntegrationSettings()\n```\n\n## 补丁器模式\n\n每个框架的集成都遵循统一的 Patcher 模式：\n\n```mermaid\nclassDiagram\n class Patcher {\n +settings: IntegrationSettings\n +attempt_patch(): None\n +undo_patch(): None\n #_do_patch(): None\n #_do_unpatch(): None\n }\n \n class LangChainPatcher {\n +attempt_patch(): None\n +undo_patch(): None\n }\n \n class DSPyPatcher {\n +attempt_patch(): None\n +undo_patch(): None\n }\n \n class LlamaIndexPatcher {\n +attempt_patch(): None\n +undo_patch(): None\n }\n \n Patcher <|-- LangChainPatcher\n Patcher <|-- DSPyPatcher\n Patcher <|-- LlamaIndexPatcher\n```\n\n### Patcher 接口规范\n\n| 方法 | 参数 | 返回 | 说明 |\n|------|------|------|------|\n| `get__patcher` | `settings: IntegrationSettings` | `Patcher` | 工厂函数，返回补丁器实例 |\n| `attempt_patch` | 无 | `None` | 执行补丁，拦截 SDK 调用 |\n| `undo_patch` | 无 | `None` | 撤销补丁，恢复原始实现 |\n\n## 测试框架\n\n### 测试工具链\n\n集成测试使用 `pytest-recording` 和 `vcrpy` 来录制和回放网络请求：\n\n```python\n@pytest.mark.vcr(\n filter_headers=[\"authorization\"],\n allowed_hosts=[\"api.wandb.ai\", \"localhost\"],\n)\ndef test__quickstart(\n client: weave.weave_client.WeaveClient,\n patch_: None,\n) -> None:\n \"\"\"框架快速开始测试。\"\"\"\n # 执行框架操作...\n calls = list(client.get_calls())\n assert len(calls) == 1\n```\n\n### 测试 Fixtures\n\n```python\n@pytest.fixture()\ndef patch_() -> Generator[None, None, None]:\n \"\"\"自动应用和清理补丁。\"\"\"\n from weave.integrations.._sdk import get__patcher\n \n patcher = get__patcher()\n patcher.attempt_patch()\n yield\n patcher.undo_patch()\n```\n\n### 运行测试\n\n```bash\n# 录制模式\npytest --record-mode=rewrite weave/integrations//_test.py\n\n# 回放模式（默认）\npytest weave/integrations//_test.py\n\n# 使用生产 Trace Server\npytest --trace-server=prod weave/integrations//_test.py\n```\n\n## 数据流\n\n### Call 记录流程\n\n```mermaid\ngraph LR\n A[Framework API Call] --> B[WeaveCallback]\n B --> C[创建 Call.start]\n C --> D[执行原始调用]\n D --> E[获取响应]\n E --> F[创建 Call.end]\n F --> G[序列化为 JSON]\n G --> H[上传到 Trace Server]\n H --> I[存储到数据库]\n```\n\n### 序列化的数据类型\n\n| 类型 | 存储方式 | 说明 |\n|------|---------|------|\n| 小型对象 | Inline | 直接存储在 Call 记录中 |\n| 大型对象 | 文件 | 存储为 `MemTraceFilesArtifact` |\n| 图像 | 文件 | 使用 PIL 序列化 |\n| 音频 | 文件 | 使用 wave 模块序列化 |\n| Op | 内联 | 存储为 Op 类型引用 |\n\n## 开发新集成\n\n### 开发步骤\n\n1. **创建目录结构**：在 `weave/integrations/` 下创建新框架的目录\n2. **实现 `_sdk.py`**：包含 `get__patcher` 工厂函数\n3. **注册补丁函数**：在 `weave/integrations/patch.py` 中添加导出\n4. **添加配置支持**：在 `AutopatchSettings` 中添加新字段\n5. **编写测试**：使用 pytest-recording 录制网络请求\n6. **运行测试**：验证集成正确工作\n\n### 最小集成模板\n\n```python\n# weave/integrations//_sdk.py\nfrom weave.integrations import IntegrationSettings, Patcher\n\nclass Patcher(Patcher):\n def __init__(self, settings: IntegrationSettings | None = None):\n self.settings = settings or IntegrationSettings()\n self._original = None\n \n def attempt_patch(self) -> None:\n \"\"\"应用补丁。\"\"\"\n # 1. 保存原始实现\n # 2. Monkey Patch 新实现\n pass\n \n def undo_patch(self) -> None:\n \"\"\"撤销补丁。\"\"\"\n # 恢复原始实现\n pass\n\ndef get__patcher(\n settings: IntegrationSettings | None = None\n) -> Patcher:\n return Patcher(settings)\n```\n\n## 环境变量\n\n| 变量名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `WEAVE_IMPLICITLY_PATCH_INTEGRATIONS` | `bool` | `true` | 是否启用隐式补丁 |\n| `WEAVE_DISPLAY_VIEWER` | `string` | `auto` | 显示查看器配置 |\n| `_API_KEY` | `string` | - | 各框架的 API 密钥 |\n\n## 限制与注意事项\n\n1. **线程安全**：部分集成可能存在线程安全问题，高并发场景下需谨慎使用\n2. **版本兼容**：框架更新可能导致集成失效，需保持版本同步\n3. **性能开销**：自动追踪会带来一定的性能开销，生产环境可选择性禁用\n4. **数据脱敏**：敏感信息（如 API Key）需通过 `filter_headers` 配置进行过滤\n\n---\n\n\n\n## 数据序列化\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/trace/serialization/README.md](https://github.com/wandb/weave/blob/main/weave/trace/serialization/README.md)\n- [weave/trace/serialization/serialize.py](https://github.com/wandb/weave/blob/main/weave/trace/serialization/serialize.py)\n- [weave/trace/serialization/mem_artifact.py](https://github.com/wandb/weave/blob/main/weave/trace/serialization/mem_artifact.py)\n- [weave/trace/serialization/op_type.py](https://github.com/wandb/weave/blob/main/weave/trace/serialization/op_type.py)\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [sdks/node/src/fn.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/fn.ts)\n \n\n# 数据序列化\n\n## 概述\n\n数据序列化（Serialization）是 Weave 追踪系统中的核心基础设施，负责将 Python 对象转换为 JSON 可序列化的格式，以便在客户端与服务器之间传输，并在需要时将数据还原为原始 Python 对象。\n\nWeave 的序列化系统支持多种数据类型，包括 Python 原生类型（int、float、str、bool、None）、集合类型（list、tuple、dict）、自定义对象以及\"可字典化\"（dictifiable）的对象。资料来源：[weave/trace/serialization/README.md]()\n\n## 核心组件\n\n### 序列化入口点\n\n序列化系统的主要入口点是 `weave/trace/serialization/serialize.py`，该文件包含两个核心函数：\n\n| 函数 | 功能 | 可逆性 |\n|------|------|--------|\n| `to_json()` | 将 Python 对象转换为 JSON 可序列化格式 | 是 |\n| `from_json()` | 将 JSON 数据还原为 Python 对象 | 是 |\n\n资料来源：[weave/trace/serialization/README.md]()\n\n### 自定义对象序列化模块\n\n`weave/trace/serialization/custom_objs.py` 是处理自定义对象序列化的主要模块，包含以下关键函数：\n\n| 函数 | 功能 |\n|------|------|\n| `encode_custom_obj()` | 使用注册的序列化器编码自定义对象（支持内联和文件两种方式） |\n| `decode_custom_inline_obj()` | 解码内联自定义对象 |\n| `decode_custom_obj()` | 解码基于文件的自定义对象 |\n\n资料来源：[weave/trace/serialization/README.md]()\n\n### 内存追踪文件工件\n\n`MemTraceFilesArtifact` 类负责文件-based 序列化的读写操作。当保存自定义对象时，数据被写入工件文件；当需要还原对象时，数据从工件文件中读取。\n\n```python\ndef _my_type(artifact: MemTraceFilesArtifact, name: str) -> MyCustomType:\n # Load the object's data from the file in the artifact\n with artifact.open(f\"{name}.txt\") as f:\n value = f.read()\n return MyCustomType(value)\n```\n\n资料来源：[weave/trace/serialization/README.md]()\n\n## 序列化类型支持\n\n### Python 原生类型\n\n| 类型 | 可逆性 | 说明 |\n|------|--------|------|\n| int | ✓ | 整数 |\n| float | ✓ | 浮点数 |\n| str | ✓ | 字符串 |\n| bool | ✓ | 布尔值 |\n| None | ✓ | 空值 |\n\n### 集合类型\n\n| 类型 | 可逆性 | 说明 |\n|------|--------|------|\n| list | ✓ | 列表 |\n| tuple | ✓ | 元组 |\n| dict | ✓ | 字典 |\n\n### 注册的自定义对象\n\n通过 `custom_objs` 模块注册的自定义对象具有可逆性，前提是序列化器已正确注册。\n\n### 任意 Python 对象\n\n任意 Python 对象（未注册序列化器）无法被序列化还原。\n\n### 可字典化对象\n\n\"Dictifiable\"对象只能部分还原，最终还原为字典而非原始类型。\n\n资料来源：[weave/trace/serialization/README.md]()\n\n## 序列化流程\n\n### 整体序列化流程\n\nWeave 的序列化采用客户端-服务端架构，数据在用户代码与服务器存储之间流转：\n\n```mermaid\nflowchart LR\n UserCode1[\"用户代码\"] -->|\"Python 对象\"| WeaveClient\n \n subgraph WeaveClient[\"Weave 客户端\"]\n ClientSave[\"client.save()\"] --> ToJson[\"to_json()\"]\n ToJson -->|\"JSON 数据\"| ServerStorage[\"服务器存储\"]\n ServerStorage -->|\"JSON 数据\"| FromJson[\"from_json()\"]\n FromJson --> ClientGet[\"client.get()\"]\n end\n \n WeaveClient -->|\"Python 对象\"| UserCode2[\"用户代码\"]\n```\n\n### 自定义对象序列化流程\n\n对于基于文件的自定义对象，序列化过程涉及注册序列化器、写入工件文件、解码还原等步骤：\n\n```mermaid\nflowchart TD\n CustomObj[\"自定义对象
(PIL.Image.Image, wave.Wave_read 等)\"] --> ToJson[\"to_json()\"]\n ToJson --> EncodeCustomObj[\"encode_custom_obj()\"]\n \n subgraph CustomSerialization[\"自定义对象序列化过程\"]\n EncodeCustomObj --> Serializer[\"已注册的序列化器
(save 方法)\"]\n Serializer -->|\"写入文件\"| MemArtifact[\"MemTraceFilesArtifact\"]\n \n MemArtifact -->|\"读取文件\"| Deserializer[\"已注册的序列化器
(load 方法)\"]\n Deserializer --> DecodeCustomObj[\"decode_custom_obj()\"]\n end\n \n DecodeCustomObj --> FromJson[\"from_json()\"]\n FromJson --> ReconstructedObj[\"还原的自定义对象\"]\n \n RegisterSerializer[\"register_serializer()\"] -.->|\"注册\"| Serializer\n RegisterSerializer -.->|\"注册\"| Deserializer\n```\n\n资料来源：[weave/trace/serialization/README.md]()\n\n## 自定义类型注册机制\n\n### 注册序列化器\n\nWeave 允许用户为自定义类型指定 `save` 和 `load` 方法，实现与追踪系统的集成：\n\n```python\nfrom weave.trace.serialization import serializer\n\n# 为自定义类型注册序列化器\nserializer.register_serializer(MyCustomType, save_my_type, load_my_type)\n```\n\n### 序列化器定义\n\n自定义序列化器需要实现两个核心函数：\n\n**保存函数（save_my_type）**：\n\n```python\ndef save_my_type(obj: MyCustomType, artifact: MemTraceFilesArtifact) -> None:\n # 将对象写入工件文件\n with artifact.open(\"my_type.txt\", \"w\") as f:\n f.write(obj.value)\n```\n\n**加载函数（load_my_type）**：\n\n```python\ndef load_my_type(artifact: MemTraceFilesArtifact) -> MyCustomType:\n # 从工件文件读取数据并还原对象\n with artifact.open(\"my_type.txt\") as f:\n value = f.read()\n return MyCustomType(value)\n```\n\n资料来源：[weave/trace/serialization/README.md]()\n\n## 序列化模式\n\n### 内联序列化\n\n对于序列化表示较小的对象（如 Python datetime 对象），序列化系统会将值直接\"内联\"存储，与其他序列化信息（如类名、反序列化 Op）一起存储。这种方式避免了额外的 API 请求来检索值。\n\n### 基于文件的序列化\n\n较大的值（如图片）通常使用基于文件的序列化方式。技术层面支持每个工件包含多个文件，但目前实践中每个工件只使用一个文件（obj.py）。\n\n资料来源：[weave/trace/serialization/README.md]()\n\n## 第一类序列化类型\n\nWeave 内置了对以下常见类型的序列化支持，这些类型定义在 `weave/type_handlers/` 目录中：\n\n| 类型 | 处理类 | 用途 |\n|------|--------|------|\n| PIL.Image.Image | 图像处理器 | 图片数据序列化 |\n| wave.Wave_read | 音频处理器 | 音频数据序列化 |\n| weave.Op | Op 处理器 | 操作对象序列化 |\n| datetime.datetime | 日期时间处理器 | 日期时间对象序列化 |\n| rich.markdown.Markdown | Markdown 处理器 | Markdown 内容序列化 |\n\n这些 `KNOWN_TYPES` 使用 `register_serializer` 实现。与其他类型不同的是，这些类型始终使用 SDK 当前的 `load` 函数进行加载，而非使用对象包中的加载函数。\n\n资料来源：[weave/trace/serialization/README.md]()\n\n## 跨运行时兼容性\n\n当保存自定义对象时，Weave 还会将 `load` 函数作为 Op 保存到对象中。这使得对象可以在未注册序列化器的 Python 运行时中进行反序列化，只要必要的依赖可用。这是以\"最大努力\"方式实现的，如果任何依赖不可用，对象将无法加载。\n\n目前 Weave 不保存依赖的锁定文件，但未来可能考虑添加此功能以提供更好的可移植性。\n\n资料来源：[weave/trace/serialization/README.md]()\n\n## Op 类型定义\n\n在 TypeScript SDK 中，Op 类型定义如下：\n\n```typescript\nexport type Op any> = {\n __isOp: true;\n __wrappedFunction: T;\n __boundThis?: WeaveObject;\n __name: string;\n __savedRef?: OpRef | Promise;\n __parameterNames?: ParameterNamesOption;\n invoke: CallMethod;\n} & T &\n ((\n ...args: Parameters\n ) => ReturnType extends AsyncIterable\n ? AsyncIterable>\n : Promise>>);\n```\n\n### Op 核心属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `__isOp` | boolean | 标识符，用于 `isOp()` 函数判断 |\n| `__wrappedFunction` | T | 被包装的原始函数 |\n| `__name` | string | 操作名称 |\n| `__savedRef` | OpRef \\| Promise\\ | 保存的引用 |\n| `__parameterNames` | ParameterNamesOption | 参数名称配置 |\n\n### Op 工具函数\n\n```typescript\nexport function isOp(value: any): value is Op {\n return value && value.__isOp === true;\n}\n\nexport function getOpName(opValue: Op): string {\n return opValue.__name;\n}\n\nexport function getOpWrappedFunction any>(\n opValue: Op\n): T {\n return opValue.__wrappedFunction;\n}\n```\n\n资料来源：[sdks/node/src/opType.ts]()\n\n## OpOptions 配置选项\n\n`OpOptions` 接口定义了可用于配置 op 包装器的选项：\n\n```typescript\nexport interface OpOptions any> {\n name?: string;\n streamReducer?: StreamReducer;\n originalFunction?: T;\n callDisplayName?: (...args: Parameters) => string;\n summarize?: (result: Awaited>) => Record;\n bindThis?: WeaveObject;\n isDecorator?: boolean;\n shouldAdoptThis?: boolean;\n parameterNames?: ParameterNamesOption;\n /** 操作类型 (如 'llm', 'agent', 'tool', 'search')，用于 UI 分类 */\n opKind?: string;\n /** 操作在 UI 中的自定义颜色 */\n opColor?: string;\n}\n```\n\n### OpOptions 参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 操作的显示名称 |\n| `streamReducer` | StreamReducer | 流式结果 reducer 配置 |\n| `originalFunction` | T | 原始函数引用 |\n| `callDisplayName` | function | 自定义调用显示名称 |\n| `summarize` | function | 结果摘要生成函数 |\n| `bindThis` | WeaveObject | 绑定的 this 对象 |\n| `isDecorator` | boolean | 是否为装饰器模式 |\n| `shouldAdoptThis` | boolean | 是否采用原始函数的 this 值 |\n| `parameterNames` | ParameterNamesOption | 参数名称配置 |\n| `opKind` | string | 操作类型分类 |\n| `opColor` | string | UI 显示颜色 |\n\n资料来源：[sdks/node/src/opType.ts]()\n\n## Callable 抽象接口\n\nFn 模块定义了 `Callable` 接口用于抽象可调用对象：\n\n```typescript\nexport interface Callable {\n run: (input: I) => Promise;\n}\n\nexport abstract class CallableObject\n extends WeaveObject\n implements Callable\n{\n abstract run(input: I): Promise;\n}\n```\n\n### 类型别名\n\n```typescript\nexport type FnInputs> =\n T extends Callable ? I : never;\nexport type FnOutput> =\n T extends Callable ? O : never;\n```\n\n### 参数映射工具函数\n\n```typescript\nexport function mapArgs<\n T extends Record,\n M extends Record,\n>(input: T, mapping: M): {[K in keyof M]: T[M[K]]} {\n const result: Partial<{[K in keyof M]: T[M[K]]}> = {};\n\n for (const [newKey, oldKey] of Object.entries(mapping)) {\n if (oldKey in input) {\n result[newKey as keyof M] = input[oldKey];\n }\n }\n return result as {[K in keyof M]: T[M[K]]};\n}\n```\n\n资料来源：[sdks/node/src/fn.ts]()\n\n## 当前限制与未来改进\n\n### 已知的限制\n\n1. **文件 I/O 可能阻塞主线程**：对于特别大的文件，文件 I/O 操作可能阻塞主线程。\n\n2. **序列化器信息不透明**：目前没有简单的方法了解已注册的类型及其相对顺序。\n\n3. **序列化和反序列化逻辑分散**：inline 和 file-backed 自定义对象的信息分散在 `serializer.py` 和 `custom_objs.py` 中，增加了复杂性。\n\n### 建议的改进方向\n\n1. 将文件创建逻辑从 `serializer.py` 移至 `custom_objs.py`。\n\n2. 暴露单一的 `decode_custom_obj` 方法，与单一的 `encode` 方法对应。\n\n3. 添加依赖锁定文件以提高跨运行时兼容性。\n\n资料来源：[weave/trace/serialization/README.md]()\n\n## 使用示例\n\n### 基本序列化操作\n\n```python\nimport weave\n\n# 初始化客户端\nclient = weave.init()\n\n# 创建自定义对象\nmy_obj = MyCustomType(\"Hello, Weave!\")\n\n# 保存对象到 Weave\nref = client.save(my_obj, \"my-custom-object\")\n\n# 从 Weave 检索对象\nretrieved_obj = client.get(ref)\n```\n\n### TypeScript 中定义 Op\n\n```typescript\nimport * as weave from \"weave\";\n\nclass TestClass {\n @weave.op\n async logImage(image: WeaveImage) {\n // 处理图片\n }\n}\n```\n\n资料来源：[weave/trace/serialization/README.md]()\n资料来源：[sdks/node/README.md]()\n\n## 总结\n\nWeave 的数据序列化系统提供了灵活而强大的对象序列化能力，支持原类型、自定义对象以及各种复杂数据结构。通过注册自定义序列化器，开发者可以轻松扩展系统以支持任意类型。系统采用内联和文件两种序列化模式，根据对象大小和复杂性自动选择最优方案。同时，通过将反序列化逻辑作为 Op 保存，确保了跨运行时环境的兼容性。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：wandb/weave\n\n摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v0.52.31。\n\n## 1. 安装坑 · 来源证据：v0.52.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.52.31\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5abf422dae9b416fa8f2c65c21c2a4cd | https://github.com/wandb/weave/releases/tag/v0.52.31 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v0.52.40\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.52.40\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac47498581a248b0b6be5e90b060b5ec | https://github.com/wandb/weave/releases/tag/v0.52.40 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：v0.52.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.30\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8279f2b8caaa46f893597430a4238d93 | https://github.com/wandb/weave/releases/tag/v0.52.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 配置坑 · 来源证据：v0.52.35\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.35\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82d6e8a0c7804ed9875e5d4df6cfbf3f | https://github.com/wandb/weave/releases/tag/v0.52.35 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：v0.52.36\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.36\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0347e61db43c4471a16dabca6f9d4b7f | https://github.com/wandb/weave/releases/tag/v0.52.36 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:650377372 | https://github.com/wandb/weave | README/documentation is current enough for a first validation pass.\n\n## 7. 维护坑 · 来源证据：v0.52.38\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.52.38\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6ca52f3493342d3b958dd3159f4f8fe | https://github.com/wandb/weave/releases/tag/v0.52.38 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:650377372 | https://github.com/wandb/weave | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:650377372 | https://github.com/wandb/weave | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:650377372 | https://github.com/wandb/weave | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：v0.52.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.52.33\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4f93114a48d4bee972dce582d09d376 | https://github.com/wandb/weave/releases/tag/v0.52.33 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 安全/权限坑 · 来源证据：v0.52.37\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.52.37\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c68137d6b888458d83ba2b477f463aaa | https://github.com/wandb/weave/releases/tag/v0.52.37 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：v0.52.39\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.52.39\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_de6a7e38f1644ad9ae7b67c43f2baad3 | https://github.com/wandb/weave/releases/tag/v0.52.39 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:650377372 | https://github.com/wandb/weave | issue_or_pr_quality=unknown\n\n## 15. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:650377372 | https://github.com/wandb/weave | release_recency=unknown\n\n\n",
"markdown_key": "weave",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:650377372",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/wandb/weave"
},
{
"evidence_id": "art_689a0a5ca88448e7acd472f68cbb3797",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/wandb/weave#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "weave 说明书",
"toc": [
"https://github.com/wandb/weave 项目说明书",
"目录",
"项目介绍",
"概述",
"核心架构",
"核心概念",
"Op 装饰器",
"集成系统",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "dedbcd89f7ba4f4674125655e091d8dda08e1111",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# cjs-basic-fixture - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 cjs-basic-fixture 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.claude/skills/bump-version/SKILL.md`, `.claude/skills/publish-pypi/SKILL.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.claude/skills/bump-version/SKILL.md`, `.claude/skills/publish-pypi/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install weave` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.claude/skills/bump-version/SKILL.md`, `.claude/skills/publish-pypi/SKILL.md` Claim：`clm_0003` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude/skills/bump-version/SKILL.md`, `.claude/skills/publish-pypi/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude/skills/bump-version/SKILL.md`, `.claude/skills/publish-pypi/SKILL.md`, `AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude/skills/bump-version/SKILL.md`, `.claude/skills/publish-pypi/SKILL.md`, `AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.claude/skills/bump-version/SKILL.md`, `.claude/skills/publish-pypi/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1234\n- 重要文件覆盖：40/1234\n- 证据索引条目：79\n- 角色 / Skill 条目：2\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 cjs-basic-fixture 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 cjs-basic-fixture 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 cjs-basic-fixture 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 2 个角色 / Skill / 项目文档条目。\n\n- **bump-version**（skill）：Bump the Weave Python SDK version for release. Use when preparing a new release. 激活提示：当用户任务与“bump-version”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/bump-version/SKILL.md`\n- **publish-pypi**（skill）：Build and publish the Weave Python SDK to PyPI. Use when releasing a new version. 激活提示：当用户任务与“publish-pypi”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/publish-pypi/SKILL.md`\n\n## 证据索引\n\n- 共索引 79 条证据。\n\n- **Agent instructions for weave repository**（documentation）：Agent instructions for weave repository 证据：`AGENTS.md`\n- **Weave by Weights & Biases**（documentation）：! Open in Colab https://colab.research.google.com/assets/colab-badge.svg http://wandb.me/weave colab ! Stable Version https://img.shields.io/pypi/v/weave?color=green https://pypi.org/project/weave ! Download Stats https://img.shields.io/pypi/dm/weave https://pypistats.org/packages/weave ! Github Checks https://img.shields.io/github/check-runs/wandb/weave/master https://github.com/wandb/weave ! codecov https://codecov.io/gh/wandb/weave/graph/badge.svg?token=YOUR TOKEN https://codecov.io/gh/wandb/weave 证据：`README.md`\n- **Rules**（documentation）：This directory contains rules for the Fixit linter. 证据：`rules/README.md`\n- **Scripts**（documentation）：This directory contains scripts for the weave repo, including: 证据：`scripts/README.md`\n- **trace server mock**（documentation）：Lightweight in-memory mock of the Weave trace server. Standalone Python project, sibling of the weave package — deliberately not part of the shipped SDK distribution . The published weave wheel does not include this code; consumers who don't need the mock don't pay for its dependencies. 证据：`trace_server_mock/README.md`\n- **Weave benchmarks**（documentation）：This directory has self-contained benchmarks for testing Weave performance/overhead. 证据：`scripts/benchmarks/README.md`\n- **Weave**（documentation）：Weave is a library for tracing and monitoring AI applications. 证据：`sdks/node/README.md`\n- **Host-app integration tests pnpm run test:hostApps**（documentation）：Host-app integration tests pnpm run test:hostApps 证据：`sdks/node/src/__tests__/hostApps/README.md`\n- **Claude**（documentation）： 证据：`tests/integrations/claude_agent_sdk/cassettes/CLAUDE.md`\n- **Trace Server Tests**（documentation）：This test directory is intended to contain tests that are isolated from the Weave client itself. They directly test the trace server implementation without going through the client layer. 证据：`tests/trace_server/README.md`\n- **Integrations**（documentation）：This directory contains various integrations for Weave. Weave provides automatic implicit patching for all supported integrations using an import hook mechanism, making integration seamless and effortless. There are 2 styles of libraries we are interested in patching: model vendors and orchestration frameworks. 证据：`weave/integrations/README.md`\n- **Display Module**（documentation）：The display module provides a unified interface for console output with a pluggable viewer system. This allows users to configure their preferred display method rich, print, etc. without changing their code. 证据：`weave/trace/display/README.md`\n- **Serialization Patterns Audit in Weave for Weave devs**（documentation）：Serialization Patterns Audit in Weave for Weave devs 证据：`weave/trace/serialization/README.md`\n- **Trace Server**（documentation）：Example data flow for starting a call 证据：`weave/trace_server/README.md`\n- **Contributing to weave**（documentation）：- Contributing to weave contributing-to-weave - Issues issues - PRs prs - Conventional Commits conventional-commits - Types types - Setting up your environment setting-up-your-environment - Working with the weave package working-with-the-weave-package - Linting linting - Building the weave package building-the-weave-package - Testing testing - Deprecating features deprecating-features 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"weave\", \"version\": \"0.14.0\", \"description\": \"AI development toolkit\", \"types\": \"dist/index.d.ts\", \"main\": \"dist/index.js\", \"type\": \"commonjs\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \"./dist/index.mjs\", \"require\": \"./dist/index.js\" }, \"./instrument\": { \"types\": \"./dist/esm/instrument.d.mts\", \"import\": \"./dist/esm/instrument.mjs\" } }, \"scripts\": { \"build\": \"node scripts/build.mjs\", \"prepare\": \"npm run build\", \"test\": \"jest --silent\", \"test:coverage\": \"jest --coverage\", \"test:watch\": \"jest --watch\", \"test:legacy\": \"jest --selectProjects legacy\", \"test:modern\": \"jest --selectProjects modern\", \"test:hostApps\": \"jest --selectProjects hostApps --runInBand\", \"format\"… 证据：`sdks/node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"cjs-basic-fixture\", \"version\": \"0.0.0\", \"private\": true, \"type\": \"commonjs\", \"scripts\": { \"start\": \"node main.cjs\" }, \"description\": \"CJS smoke host app for the hostApps integration tests. The 'weave' tarball is installed at test time via npm install --no-save .\" } 证据：`sdks/node/src/__tests__/hostApps/fixtures/cjs-basic/package.json`\n- **Package**（package_manifest）：{ \"name\": \"esm-basic-fixture\", \"version\": \"0.0.0\", \"private\": true, \"type\": \"module\", \"scripts\": { \"start\": \"node --import=weave/instrument main.mjs\" }, \"description\": \"ESM smoke host app for the hostApps integration tests. The 'weave' tarball is installed at test time via npm install --no-save .\" } 证据：`sdks/node/src/__tests__/hostApps/fixtures/esm-basic/package.json`\n- **Bump Python SDK Version**（skill_instruction）：This replicates the GitHub Actions bump-python-sdk-version workflow. 证据：`.claude/skills/bump-version/SKILL.md`\n- **Publish to PyPI**（skill_instruction）：This replicates the GitHub Actions publish-pypi-release workflow. 证据：`.claude/skills/publish-pypi/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Description**（documentation）：What does the PR do? Include a concise description of the PR contents. 证据：`.github/pull_request_template.md`\n- **Weave Documentation**（documentation）：For docs, please see the public docs page https://docs.wandb.ai/weave . 证据：`DOCS.md`\n- **Security Policy**（documentation）：Please report all vulnerabilities to security@wandb.com. 证据：`SECURITY.md`\n- **BuiltinObjectClasses**（documentation）：Refresher on Objects and object storage 证据：`dev_docs/BuiltinObjectClasses.md`\n- **Weave Reference Format Specification**（documentation）：Weave Reference Format Specification 证据：`dev_docs/REF_SPEC.md`\n- **Weave Release Process**（documentation）：This document outlines how to publish a new Weave release to our public PyPI package https://pypi.org/project/weave/ . 证据：`dev_docs/RELEASE.md`\n- **Contribution License Agreement**（documentation）：This Contribution License Agreement \"Agreement\" is agreed to by the party signing below \"You\" , and conveys certain license rights to Weights and Biases, Inc. \"W&B\" , for Your contributions to W&B open source projects. This Agreement is effective as of the latest signature date below \"Effective Date\" . 证据：`dev_docs/cla.md`\n- **Working notes**（documentation）：pnpm install pnpm link --global pnpm link --global weave 证据：`sdks/node/README-DEV.md`\n- **Tsconfig.Examples**（structured_config）：{ \"extends\": \"../tsconfig.json\", \"exclude\": , \"compilerOptions\": { \"rootDir\": \".\", \"outDir\": \"../dist/examples\", \"paths\": { \"weave\": \"../dist/src\" } }, \"references\": { \"path\": \"../src/tsconfig.src.json\" } } 证据：`sdks/node/examples/tsconfig.examples.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"../tsconfig.json\", \"compilerOptions\": { \"experimentalDecorators\": true, \"rootDir\": \"../../../src\", \"outDir\": \"../../../dist/ tests /legacy\", \"tsBuildInfoFile\": \"../../../dist/ tests /legacy/.tsbuildinfo\" }, \"include\": \"../../../src/ / \", \"../../../types/ / \" } 证据：`sdks/node/src/__tests__/legacy/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"../tsconfig.json\", \"compilerOptions\": { \"target\": \"es2022\", \"experimentalDecorators\": false, \"rootDir\": \"../../../src\", \"outDir\": \"../../../dist/ tests /modern\", \"tsBuildInfoFile\": \"../../../dist/ tests /modern/.tsbuildinfo\" }, \"include\": \"../../../src/ / \", \"../../../types/ / \" } 证据：`sdks/node/src/__tests__/modern/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"es2018\", \"module\": \"commonjs\", \"moduleResolution\": \"node\", \"strict\": true, \"esModuleInterop\": true, \"types\": \"jest\", \"node\" , \"composite\": true, \"declaration\": true, \"sourceMap\": true, \"baseUrl\": \".\", \"rootDir\": \"../\", \"paths\": { \"weave\": \"../index.ts\" , \"weave/ \": \"../ \" } }, \"include\": \"../ / \", \"../../types/ / \" } 证据：`sdks/node/src/__tests__/tsconfig.json`\n- **Tsconfig.Src**（structured_config）：{ \"extends\": \"../tsconfig.json\", \"exclude\": , \"compilerOptions\": { \"rootDir\": \".\", \"outDir\": \"../dist/src\" } } 证据：`sdks/node/src/tsconfig.src.json`\n- **Tsconfig.Cjs**（structured_config）：// CJS-target tsconfig used by scripts/build.mjs . Extends the project root // tsconfig and pins module: commonjs here so the format is self-evident // without having to chase the extends chain. Also excludes the ESM-only // src/esm/ files which use import.meta.url , a syntax error under // module: commonjs . { \"extends\": \"./tsconfig.json\", \"compilerOptions\": { \"module\": \"commonjs\" }, \"exclude\": \"examples\", \"dist\", \"node modules\", \"src/integrations/checkOpenai.ts\", \"src/ tests / / \", \"src/esm/ \" } 证据：`sdks/node/tsconfig.cjs.json`\n- **Tsconfig.Esm**（structured_config）：// ESM-target tsconfig used by scripts/build.mjs . Extends the project root // tsconfig and pins module: esnext here so the format is self-evident // without having to chase the extends chain. Also excludes the CJS-only // file: src/utils/commonJSLoader.ts exists to patch the require // chain for CJS hosts and has no role under ESM where the loader hook in // src/esm/instrument.mts plays the equivalent role . { \"extends\": \"./tsconfig.json\", \"compilerOptions\": { \"module\": \"esnext\" }, \"exclude\": \"examples\", \"dist\", \"node modules\", \"src/integrations/checkOpenai.ts\", \"src/ tests / / \", \"src/utils/commonJSLoader.ts\" } 证据：`sdks/node/tsconfig.esm.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"composite\": true, // ES2022 matches our minimum supported runtime Node 18+ . \"target\": \"es2022\", \"moduleResolution\": \"node\", \"sourceMap\": true, \"strict\": true, \"esModuleInterop\": true, \"outDir\": \"dist\", \"paths\": { \"weave\": \"./src/index.ts\" }, \"declaration\": true, \"declarationMap\": true, \"rootDir\": \"src\", \"tsBuildInfoFile\": \"dist/.tsbuildinfo\", \"allowJs\": true, \"resolveJsonModule\": true }, \"include\": \"src/ / \", \"types/ / \" , \"exclude\": \"examples\", \"dist\", \"node modules\", \"src/integrations/checkOpenai.ts\", \"src/ tests / / \" } 证据：`sdks/node/tsconfig.json`\n- **Weave.Openapi**（structured_config）：{ \"openapi\": \"3.1.0\", \"info\": {\"title\": \"FastAPI\", \"version\": \"0.1.0\"}, \"servers\": {\"url\": \"https://api.wandb.ai\"} , \"paths\": { \"/health\": { \"get\": { \"tags\": \"Service\" , \"summary\": \"Read Root\", \"operationId\": \"read root health get\", \"responses\": { \"200\": { \"description\": \"Successful Response\", \"content\": {\"application/json\": {\"schema\": {}}} } } } }, \"/server info\": { \"get\": { \"tags\": \"Service\" , \"summary\": \"Server Info\", \"operationId\": \"server info server info get\", \"responses\": { \"200\": { \"description\": \"Successful Response\", \"content\": { \"application/json\": { \"schema\": {\"$ref\": \" /components/schemas/ServerInfoRes\"} } } } } } }, \"/call/start\": { \"post\": { \"tags\": \"Calls\" , \"summary\": \"Call… 证据：`sdks/node/weave.openapi.json`\n- **Error Response**（structured_config）：{ \"type\": \"system\", \"subtype\": \"init\", \"session id\": \"s-err999\" }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"text\", \"text\": \"Something went wrong while processing.\" } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"result\", \"subtype\": \"result\", \"duration ms\": 800, \"duration api ms\": 600, \"is error\": true, \"num turns\": 1, \"session id\": \"s-err999\", \"total cost usd\": 0.001, \"usage\": { \"input tokens\": 20, \"output tokens\": 10 }, \"result\": \"Error: something went wrong\" } 证据：`tests/integrations/claude_agent_sdk/cassettes/error_response.json`\n- **Multi Tool Response**（structured_config）：{ \"type\": \"system\", \"subtype\": \"init\", \"session id\": \"s-multi789\" }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"tool use\", \"id\": \"toolu 01READ\", \"name\": \"Read\", \"input\": { \"path\": \"/tmp/a.py\" } }, { \"type\": \"tool use\", \"id\": \"toolu 02BASH\", \"name\": \"Bash\", \"input\": { \"command\": \"pwd\" } } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"user\", \"message\": { \"content\": { \"type\": \"tool result\", \"tool use id\": \"toolu 01READ\", \"content\": \"print 'hello' \" }, { \"type\": \"tool result\", \"tool use id\": \"toolu 02BASH\", \"content\": \"/tmp\" } } }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"text\", \"text\": \"Done checking both files.\" } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\":… 证据：`tests/integrations/claude_agent_sdk/cassettes/multi_tool_response.json`\n- **Multi Turn Response**（structured_config）：{ \"type\": \"system\", \"subtype\": \"init\", \"session id\": \"s-mt001\" }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"text\", \"text\": \"Hello! How can I help you?\" } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"result\", \"subtype\": \"result\", \"duration ms\": 600, \"duration api ms\": 400, \"is error\": false, \"num turns\": 1, \"session id\": \"s-mt001\", \"total cost usd\": 0.002, \"usage\": { \"input tokens\": 15, \"output tokens\": 8 }, \"result\": \"Hello! How can I help you?\" }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"text\", \"text\": \"The capital of France is Paris.\" } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"result\", \"subtype\": \"result\", \"duration ms\": 700, \"duration api ms\": 500… 证据：`tests/integrations/claude_agent_sdk/cassettes/multi_turn_response.json`\n- **Simple Text Response**（structured_config）：{ \"type\": \"system\", \"subtype\": \"init\", \"session id\": \"s-abc123\" }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"text\", \"text\": \"The answer is 4.\" } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"result\", \"subtype\": \"result\", \"duration ms\": 1200, \"duration api ms\": 900, \"is error\": false, \"num turns\": 1, \"session id\": \"s-abc123\", \"total cost usd\": 0.003, \"usage\": { \"input tokens\": 25, \"output tokens\": 10 }, \"result\": \"The answer is 4.\" } 证据：`tests/integrations/claude_agent_sdk/cassettes/simple_text_response.json`\n- **Thinking Response**（structured_config）：{ \"type\": \"system\", \"subtype\": \"init\", \"session id\": \"s-think789\" }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"thinking\", \"thinking\": \"Let me think about this carefully...\", \"signature\": \"sig abc123\" } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"text\", \"text\": \"After careful consideration, the answer is 42.\" } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"result\", \"subtype\": \"result\", \"duration ms\": 2000, \"duration api ms\": 1500, \"is error\": false, \"num turns\": 1, \"session id\": \"s-think789\", \"total cost usd\": 0.005, \"usage\": { \"input tokens\": 50, \"output tokens\": 30 }, \"result\": \"After careful consideration, the answer is 42… 证据：`tests/integrations/claude_agent_sdk/cassettes/thinking_response.json`\n- **Tool Use Response**（structured_config）：{ \"type\": \"system\", \"subtype\": \"init\", \"session id\": \"s-def456\" }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"text\", \"text\": \"Let me check the files in the directory.\" }, { \"type\": \"tool use\", \"id\": \"toolu 01ABC\", \"name\": \"Bash\", \"input\": { \"command\": \"ls -la\" } } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"user\", \"message\": { \"content\": { \"type\": \"tool result\", \"tool use id\": \"toolu 01ABC\", \"content\": \"file1.py\\nfile2.py\\nREADME.md\" } } }, { \"type\": \"assistant\", \"message\": { \"content\": { \"type\": \"text\", \"text\": \"I found 3 files: file1.py, file2.py, and README.md.\" } , \"model\": \"claude-sonnet-4-6\" } }, { \"type\": \"result\", \"subtype\": \"result\", \"duration ms\": 3500, \"duration… 证据：`tests/integrations/claude_agent_sdk/cassettes/tool_use_response.json`\n- **Default Vector Store**（structured_config）：{\"embedding dict\": {\"6b4e050b-66f5-4c9d-a9b2-8880d39be567\": 0.002446331549435854, -0.013814171776175499, -0.007511758245527744, -0.026190951466560364, 0.003040638053789735, 0.024186894297599792, -0.028042975813150406, -0.011139792390167713, -0.024698274210095406, -0.02609420381486416, 0.020994223654270172, 0.03051695041358471, -0.0012827691389247775, -0.007477205246686935, 0.0030630973633378744, 0.021685278043150902, 0.023468198254704475, 0.011616619303822517, -0.0003077350265812129, -0.017428385093808174, -0.016198309138417244, -0.015479612164199352, 0.011264181695878506, 0.0008569071069359779, -0.0006832797662355006, -0.0035589286126196384, 0.02344055473804474, -0.03590717166662216, -0.00… 证据：`tests/integrations/llamaindex/vector_index/default__vector_store.json`\n- **Docstore**（structured_config）：{\"docstore/data\": {\"6b4e050b-66f5-4c9d-a9b2-8880d39be567\": {\" data \": {\"id \": \"6b4e050b-66f5-4c9d-a9b2-8880d39be567\", \"embedding\": null, \"metadata\": {\"file path\": \"/Users/ayushthakur/integrations/weave-dev/weave/tests/integrations/llamaindex/test data/paul graham essay.txt\", \"file name\": \"paul graham essay.txt\", \"file type\": \"text/plain\", \"file size\": 75042, \"creation date\": \"2024-11-22\", \"last modified date\": \"2024-10-03\"}, \"excluded embed metadata keys\": \"file name\", \"file type\", \"file size\", \"creation date\", \"last modified date\", \"last accessed date\" , \"excluded llm metadata keys\": \"file name\", \"file type\", \"file size\", \"creation date\", \"last modified date\", \"last accessed date\" , \"relat… 证据：`tests/integrations/llamaindex/vector_index/docstore.json`\n- **Graph Store**（structured_config）：{\"graph dict\": {}} 证据：`tests/integrations/llamaindex/vector_index/graph_store.json`\n- **Image Vector Store**（structured_config）：{\"embedding dict\": {}, \"text id to ref doc id\": {}, \"metadata dict\": {}} 证据：`tests/integrations/llamaindex/vector_index/image__vector_store.json`\n- **Index Store**（structured_config）：{\"index store/data\": {\"e081edba-af4c-440a-953f-dfe781117555\": {\" type \": \"vector store\", \" data \": \"{\\\"index id\\\": \\\"e081edba-af4c-440a-953f-dfe781117555\\\", \\\"summary\\\": null, \\\"nodes dict\\\": {\\\"6b4e050b-66f5-4c9d-a9b2-8880d39be567\\\": \\\"6b4e050b-66f5-4c9d-a9b2-8880d39be567\\\", \\\"58299c1a-c1a7-49ce-96d0-a099d21fd16f\\\": \\\"58299c1a-c1a7-49ce-96d0-a099d21fd16f\\\", \\\"37651ba3-3b7b-4d71-b191-7ea8fd334652\\\": \\\"37651ba3-3b7b-4d71-b191-7ea8fd334652\\\", \\\"f0b59cc1-02c7-4730-8151-c7c9aebe657a\\\": \\\"f0b59cc1-02c7-4730-8151-c7c9aebe657a\\\", \\\"34e2d45b-4548-4cb6-a000-4985bde28d22\\\": \\\"34e2d45b-4548-4cb6-a000-4985bde28d22\\\", \\\"8a921837-97a3-44af-adb2-7afc14a48707\\\": \\\"8a921837-97a3-44af-adb2-7afc14a48707\\\", \\\"… 证据：`tests/integrations/llamaindex/vector_index/index_store.json`\n- **Cost Checkpoint**（structured_config）：{ \"gpt-4\": { \"provider\": \"openai\", \"input\": 3e-05, \"output\": 6e-05, \"created at\": \"2024-10-08 08:45:39\" } , \"gpt-4o\": { \"provider\": \"openai\", \"input\": 5e-06, \"output\": 1.5e-05, \"created at\": \"2024-10-08 08:45:39\" }, { \"provider\": \"openai\", \"input\": 2.5e-06, \"output\": 1e-05, \"created at\": \"2024-12-18 09:00:21\" }, { \"provider\": \"openai\", \"input\": 2.5e-06, \"output\": 1e-05, \"cache read input\": 1.25e-06, \"cache creation input\": 0.0, \"created at\": \"2026-04-01 13:02:37\" } , \"gpt-4o-mini\": { \"provider\": \"openai\", \"input\": 1.5e-07, \"output\": 6e-07, \"created at\": \"2024-10-08 08:45:39\" }, { \"provider\": \"openai\", \"input\": 1.5e-07, \"output\": 6e-07, \"cache read input\": 7.5e-08, \"cache creation input\": 0.… 证据：`weave/trace_server/costs/cost_checkpoint.json`\n- **Generated Base Object Class Schemas**（structured_config）：{ \"$defs\": { \"ActionSpec\": { \"properties\": { \"name\": { \"anyOf\": { \"type\": \"string\" }, { \"type\": \"null\" } , \"default\": null, \"title\": \"Name\" }, \"description\": { \"anyOf\": { \"type\": \"string\" }, { \"type\": \"null\" } , \"default\": null, \"title\": \"Description\" }, \"config\": { \"discriminator\": { \"mapping\": { \"contains words\": \" /$defs/ContainsWordsActionConfig\", \"llm judge\": \" /$defs/LlmJudgeActionConfig\" }, \"propertyName\": \"action type\" }, \"oneOf\": { \"$ref\": \" /$defs/LlmJudgeActionConfig\" }, { \"$ref\": \" /$defs/ContainsWordsActionConfig\" } , \"title\": \"Config\" } }, \"required\": \"config\" , \"title\": \"ActionSpec\", \"type\": \"object\" }, \"AnnotationSpec\": { \"properties\": { \"name\": { \"anyOf\": { \"type\": \"string\"… 证据：`weave/trace_server/interface/builtin_object_classes/generated/generated_base_object_class_schemas.json`\n- **Generated Builtin Object Class Schemas**（structured_config）：{ \"$defs\": { \"ActionSpec\": { \"properties\": { \"name\": { \"anyOf\": { \"type\": \"string\" }, { \"type\": \"null\" } , \"default\": null, \"title\": \"Name\" }, \"description\": { \"anyOf\": { \"type\": \"string\" }, { \"type\": \"null\" } , \"default\": null, \"title\": \"Description\" }, \"config\": { \"discriminator\": { \"mapping\": { \"contains words\": \" /$defs/ContainsWordsActionConfig\", \"llm judge\": \" /$defs/LlmJudgeActionConfig\" }, \"propertyName\": \"action type\" }, \"oneOf\": { \"$ref\": \" /$defs/LlmJudgeActionConfig\" }, { \"$ref\": \" /$defs/ContainsWordsActionConfig\" } , \"title\": \"Config\" } }, \"required\": \"config\" , \"title\": \"ActionSpec\", \"type\": \"object\" }, \"AlertSpec\": { \"properties\": { \"name\": { \"anyOf\": { \"type\": \"string\" }, {… 证据：`weave/trace_server/interface/builtin_object_classes/generated/generated_builtin_object_class_schemas.json`\n- **Model Providers**（structured_config）：{ \"openai/gpt-oss-120b\": { \"litellm provider\": \"coreweave\", \"api key name\": \"WANDB API KEY\" }, \"openai/gpt-oss-20b\": { \"litellm provider\": \"coreweave\", \"api key name\": \"WANDB API KEY\" }, \"google/gemma-4-31B-it\": { \"litellm provider\": \"coreweave\", \"api key name\": \"WANDB API KEY\" }, \"ibm-granite/granite-4.1-8b\": { \"litellm provider\": \"coreweave\", \"api key name\": \"WANDB API KEY\" }, \"MiniMaxAI/MiniMax-M2.5\": { \"litellm provider\": \"coreweave\", \"api key name\": \"WANDB API KEY\" }, \"zai-org/GLM-5.1\": { \"litellm provider\": \"coreweave\", \"api key name\": \"WANDB API KEY\" }, \"zai-org/GLM-5-FP8\": { \"litellm provider\": \"coreweave\", \"api key name\": \"WANDB API KEY\" }, \"zai-org/GLM-4.5\": { \"litellm provider\":… 证据：`weave/trace_server/model_providers/model_providers.json`\n- **.gitattributes**（source_file）：.png binary .jpg binary .gif binary 证据：`.gitattributes`\n- **Codeowners**（source_file）：@wandb/weave-team /docs/ @wandb/docs-team @wandb/weave-team /weave/trace server/migrations @tssweeney @gtarpenning 证据：`.github/CODEOWNERS`\n- **Monitor Python dependencies in pyproject.toml**（source_file）：version: 2 updates: Monitor Python dependencies in pyproject.toml - package-ecosystem: \"uv\" directory: \"/\" target-branch: \"master\" schedule: interval: \"weekly\" day: \"monday\" time: \"09:00\" timezone: \"America/New York\" Group minor and patch updates together to reduce PR noise Groups match the optional dependencies structure in pyproject.toml groups: Core dependencies core: patterns: - \"pydantic \" - \"wandb \" - \"packaging \" - \"tenacity \" - \"emoji \" - \"uuid-utils \" - \"numpy \" - \"rich \" - \"click \" - \"gql \" - \"jsonschema \" - \"diskcache-weave \" - \"nest-asyncio \" - \"weave server sdk \" 证据：`.github/dependabot.yml`\n- **.gitignore**（source_file）：.DS Store .python-version .ipynb checkpoints dist/ /wandb/ pycache .idea .egg-info/ build/ gha-creds- .json .vscode .mypy cache .hypothesis .env .ruff cache .pytest cache .coverage .nox .venv .claude/worktrees .weave client dropped items log.jsonl .log /file::memory:?cache=shared tests/weave models/ .cursor/rules/personal.mdc pyrightconfig.json .coverage/ coverage.xml htmlcov/ 证据：`.gitignore`\n- **.graphqlrc**（source_file）：schema: \"./wb schema.gql\" 证据：`.graphqlrc`\n- **Priority 0: Type checkers slowest — start immediately, run in parallel**（source_file）：repos: Priority 0: Type checkers slowest — start immediately, run in parallel - repo: local hooks: - id: ty name: ty type checker entry: uv run ty check language: python always run: true pass filenames: false priority: 0 - repo: https://github.com/RobertCraigie/pyright-python rev: v1.1.387 hooks: - id: pyright additional dependencies: \". tests \" exclude: \".github/scripts/validate docs coverage.py\" always run: true pass filenames: false priority: 0 - repo: https://github.com/pre-commit/mirrors-mypy rev: \"v1.19.1\" hooks: - id: mypy additional dependencies: types-pkg-resources==0.1.3, types-all, wandb =0.15.5, wandb<0.19.0 Note: You have to update pyproject.toml tool.mypy too! args: \"--config-… 证据：`.pre-commit-config.yaml`\n- **Makefile**（source_file）：prerelease-dry-run: uv run ./scripts/prerelease dry run.py 证据：`Makefile`\n- 其余 19 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `README.md`, `rules/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.md`, `README.md`, `rules/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, weave/__init__.py\n- **安装与快速开始**：importance `high`\n - source_paths: pyproject.toml, weave/trace/weave_init.py\n- **系统架构**：importance `high`\n - source_paths: weave/trace/weave_client.py, weave/trace_server/clickhouse_trace_server_batched.py, weave/trace_server_bindings\n- **追踪数据流**：importance `high`\n - source_paths: weave/trace/call.py, weave/trace/log_call.py, weave/trace/op_accumulator.py, weave/trace/context\n- **函数追踪机制**：importance `high`\n - source_paths: weave/trace/op.py, weave/trace/op_caller.py, weave/trace/op_protocol.py, weave/trace/autopatch.py\n- **评估系统**：importance `high`\n - source_paths: weave/flow/scorer.py, weave/evaluation/eval.py, weave/evaluation/eval_imperative.py, weave/flow/leaderboard.py\n- **评分器模块**：importance `medium`\n - source_paths: weave/scorers, weave/scorers/llm_as_a_judge_scorer.py, weave/scorers/classification_scorer.py, weave/scorers/scorer_types.py\n- **模型供应商集成**：importance `high`\n - source_paths: weave/integrations/openai/openai_sdk.py, weave/integrations/anthropic/anthropic_sdk.py, weave/integrations/google_genai/google_genai_sdk.py, weave/integrations/mistral/mistral_sdk.py, weave/integrations/patch.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `dedbcd89f7ba4f4674125655e091d8dda08e1111`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：v0.52.31\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.52.31\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_5abf422dae9b416fa8f2c65c21c2a4cd | https://github.com/wandb/weave/releases/tag/v0.52.31 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：v0.52.40\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.52.40\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ac47498581a248b0b6be5e90b060b5ec | https://github.com/wandb/weave/releases/tag/v0.52.40 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v0.52.30\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.30\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8279f2b8caaa46f893597430a4238d93 | https://github.com/wandb/weave/releases/tag/v0.52.30 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v0.52.35\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.35\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_82d6e8a0c7804ed9875e5d4df6cfbf3f | https://github.com/wandb/weave/releases/tag/v0.52.35 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v0.52.36\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.52.36\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_0347e61db43c4471a16dabca6f9d4b7f | https://github.com/wandb/weave/releases/tag/v0.52.36 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:650377372 | https://github.com/wandb/weave | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.52.38\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v0.52.38\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_e6ca52f3493342d3b958dd3159f4f8fe | https://github.com/wandb/weave/releases/tag/v0.52.38 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:650377372 | https://github.com/wandb/weave | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:650377372 | https://github.com/wandb/weave | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:650377372 | https://github.com/wandb/weave | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：wandb/weave\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：v0.52.31（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.52.40（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.52.30（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.52.35（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.52.36（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/wandb/weave 项目说明书\n\n生成时间：2026-05-16 23:32:03 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [安装与快速开始](#installation)\n- [系统架构](#system_architecture)\n- [追踪数据流](#trace_flow)\n- [函数追踪机制](#tracing)\n- [评估系统](#evaluation)\n- [评分器模块](#scorers)\n- [模型供应商集成](#vendor_integrations)\n- [框架集成](#framework_integrations)\n- [数据序列化](#serialization)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装与快速开始](#installation), [系统架构](#system_architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/wandb/weave/blob/main/README.md)\n- [weave/integrations/README.md](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n- [sdks/node/README.md](https://github.com/wandb/weave/blob/main/sdks/node/README.md)\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [weave/trace/serialization/README.md](https://github.com/wandb/weave/blob/main/weave/trace/serialization/README.md)\n \n\n# 项目介绍\n\n## 概述\n\nWeave 是一个用于追踪和监控 AI 应用程序的库，由 W&B（Weights & Biases）开发维护。它提供了一套完整的工具集，帮助开发者追踪 AI 模型的调用、执行过程，并支持对 AI 应用进行评估和可视化。\n\n资料来源：[README.md:1]()\n\n## 核心架构\n\n### 整体架构\n\nWeave 项目主要由以下几个核心部分组成：\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Weave SDK]\n B --> C[Op 追踪层]\n C --> D[Trace Server]\n D --> E[W&B UI]\n \n F[Python SDK] --> B\n G[Node.js SDK] --> B\n \n H[集成支持] --> B\n H --> I[OpenAI]\n H --> J[Anthropic]\n H --> K[Mistral]\n```\n\n### 主要组件\n\n| 组件 | 位置 | 功能描述 |\n|------|------|----------|\n| trace | `weave/trace/` | Python 追踪核心实现 |\n| trace_server | `weave/trace_server/` | 追踪服务器接口 |\n| integrations | `weave/integrations/` | 第三方库集成支持 |\n| flow | `weave/flow/` | 评估工作流 |\n| Node SDK | `sdks/node/` | JavaScript/TypeScript SDK |\n\n资料来源：[README.md:20-25]()\n\n## 核心概念\n\n### Op（操作）\n\nOp 是 Weave 的核心抽象概念，用于包装和追踪函数调用。它支持：\n\n- **异步函数追踪**：自动处理 async/await 模式\n- **流式响应处理**：支持流式输出的追踪和聚合\n- **调用元数据记录**：记录调用参数、返回值、执行时间等信息\n\n```mermaid\ngraph LR\n A[原始函数] -->|createOpWrapper| B[Op 包装器]\n B --> C{调用执行}\n C -->|追踪| D[Call 对象]\n C -->|返回| E[原始返回值]\n D --> F[Trace Server]\n```\n\n资料来源：[sdks/node/src/opType.ts:1-30]()\n\n### Op 类型定义\n\n```typescript\nexport type Op any> = {\n __isOp: true;\n __wrappedFunction: T;\n __boundThis?: WeaveObject;\n __name: string;\n __savedRef?: OpRef | Promise;\n __parameterNames?: ParameterNamesOption;\n invoke: CallMethod;\n} & T;\n```\n\n资料来源：[sdks/node/src/opType.ts:3-18]()\n\n### 调用方法（CallMethod）\n\nCallMethod 接口定义了 Op 的调用行为，返回一个 Promise，包含原始返回值和 Call 对象：\n\n```typescript\nexport interface CallMethod any> {\n (\n this: any,\n ...params: Parameters\n ): Promise<[Awaited>, Call]>;\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:62-68]()\n\n### 调用对象（Call）\n\nCall 对象用于存储追踪信息，包括：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| callId | string | 唯一调用标识符 |\n| opName | string | 操作名称 |\n| inputs | object | 输入参数 |\n| outputs | object | 输出结果 |\n| summary | object | 调用摘要 |\n| error | Error | 错误信息（如有） |\n\n## Op 装饰器\n\nWeave 支持两种装饰器模式：现代 Stage 3 装饰器和传统装饰器语法。\n\n### 现代装饰器语法（Stage 3）\n\n```javascript\nclass TestClass {\n @weave.op\n async logImage(image: WeaveImage) {\n // 方法实现\n }\n}\n```\n\n### 传统装饰器语法\n\n```javascript\nclass TestClass {\n @weave.op({ name: 'customName' })\n async logImage(image: WeaveImage) {\n // 方法实现\n }\n}\n```\n\n### 装饰器选项\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| name | string | 自定义操作名称 |\n| streamReducer | StreamReducer | 流式响应聚合器 |\n| callDisplayName | function | 动态显示名称生成 |\n| summarize | function | 结果摘要生成函数 |\n| bindThis | WeaveObject | 绑定 this 上下文 |\n| parameterNames | string[] | 参数名称配置 |\n| opKind | string | 操作类型分类 |\n| opColor | string | UI 显示颜色 |\n\n资料来源：[sdks/node/src/opType.ts:71-87]()\n\n## 集成系统\n\n### 隐式集成\n\n当隐式集成启用（默认）时，Weave 会自动检测并追踪支持的第三方库。用户只需初始化 Weave 项目：\n\n```python\nimport weave\nweave.init(\"my-project\")\nimport openai # 自动被追踪！\n```\n\n### 显式集成\n\n通过设置 `implicitly_patch_integrations=False` 禁用隐式集成，然后手动调用 patch 函数：\n\n```python\nimport weave\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\nweave.integrations.patch_openai()\nweave.integrations.patch_anthropic()\n```\n\n资料来源：[weave/integrations/README.md:1-50]()\n\n### 可用集成\n\n| 集成 | Patch 函数 | 说明 |\n|------|------------|------|\n| OpenAI | `patch_openai()` | OpenAI API 调用追踪 |\n| Anthropic | `patch_anthropic()` | Anthropic Claude API 追踪 |\n| Mistral | `patch_mistral()` | Mistral API 追踪 |\n\n### 开发新集成\n\n开发新的供应商集成需要创建以下文件结构：\n\n```\nweave/integrations//\n├── __init__.py\n├── _sdk.py\n└── _test.py\n```\n\n集成开发流程：\n\n1. 创建供应商文件夹\n2. 实现 `get__patcher()` 函数\n3. 返回 `MultiPatcher` 或 `NoOpPatcher` 对象\n4. 在 `AutopatchSettings` 中注册设置\n\n```python\nfrom weave.integrations.patcher import SymbolPatcher, MultiPatcher, NoOpPatcher\nfrom weave.trace.autopatch import IntegrationSettings\n\ndef get__patcher(\n settings: IntegrationSettings | None = None,\n) -> MultiPatcher | NoOpPatcher:\n if settings is None:\n settings = IntegrationSettings()\n if not settings.enabled:\n return NoOpPatcher()\n \n global __patcher\n if __patcher is None:\n # 实现符号替换逻辑\n __patcher = MultiPatcher([...])\n return __patcher\n```\n\n资料来源：[weave/integrations/README.md:100-140]()\n\n## 序列化系统\n\n### 序列化机制\n\nWeave 提供两种序列化方式：\n\n| 方式 | 适用场景 | 说明 |\n|------|----------|------|\n| 文件序列化 | 大型值（图片等） | 通过 `MemTraceFilesArtifact` 存储 |\n| 内联序列化 | 小型值（datetime 等） | 直接嵌入序列化信息 |\n\n资料来源：[weave/trace/serialization/README.md:1-30]()\n\n### 自定义类型支持\n\n用户可以注册自定义的 `save` 和 `load` 方法：\n\n```python\nfrom weave import register_serializer\n\n@register_serializer(MyCustomClass)\nclass MyCustomSerializer:\n def save(self, obj):\n # 自定义序列化逻辑\n return {...}\n \n def load(self, data):\n # 自定义反序列化逻辑\n return MyCustomClass(...)\n```\n\n### 内置类型\n\nWeave 内置以下类型的序列化支持：\n\n| 类型 | 模块 | 说明 |\n|------|------|------|\n| 图像 | PIL.Image.Image | 图片序列化 |\n| 音频 | wave.Wave_read | 音频序列化 |\n| Op | weave.Op | 操作序列化 |\n| 日期时间 | datetime.datetime | 时间戳序列化 |\n| Markdown | rich.markdown.Markdown | Markdown 内容序列化 |\n\n## 评估工作流\n\n### 评估系统架构\n\n```mermaid\ngraph TD\n A[评估数据集] --> B[评估运行器]\n B --> C[并行执行]\n C --> D[结果聚合]\n D --> E[评分计算]\n E --> F[结果展示]\n \n G[预测函数] --> B\n G --> H[Op 追踪]\n H --> I[Trace Server]\n I --> E\n```\n\n### Callable 接口\n\n评估系统基于 `Callable` 接口设计：\n\n```typescript\nexport interface Callable {\n run: (input: I) => Promise;\n}\n```\n\n资料来源：[sdks/node/src/fn.ts:10-13]()\n\n## SDK 使用\n\n### Python SDK\n\n#### 初始化项目\n\n```python\nimport weave\nweave.init(\"my-project\")\n```\n\n#### 追踪函数\n\n```python\nimport weave\n\n@weave.op()\ndef extract_fruit(sentence):\n # 函数实现\n return fruit\n```\n\n### Node.js SDK\n\n#### 安装\n\n```bash\nnpm install weave\n```\n\n#### 初始化和追踪\n\n```javascript\nimport {init, op, wrapOpenAI} from 'weave';\nimport {OpenAI} from 'openai';\n\nconst openai = wrapOpenAI(new OpenAI());\n\nasync function extractDinos(input) {\n const response = await openai.chat.completions.create({\n model: 'gpt-4o',\n messages: [{role: 'user', content: input}],\n });\n return response.choices[0].message.content;\n}\n\nconst extractDinosOp = op(extractDinos);\n\nasync function main() {\n await init('weave-quickstart');\n const result = await extractDinosOp('输入文本');\n console.log(result);\n}\n```\n\n资料来源：[sdks/node/README.md:1-60]()\n\n## 配置选项\n\n### Weave 初始化配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| project_name | string | 必填 | 项目名称 |\n| settings | dict | None | 配置字典 |\n| entity | string | None | 团队/用户名称 |\n| host | string | api.wandb.ai | API 主机地址 |\n\n### 集成设置\n\n| 设置 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| implicitly_patch_integrations | bool | True | 是否启用隐式集成 |\n| enabled | bool | True | 是否启用特定集成 |\n\n## 项目结构\n\n```\nweave/\n├── __init__.py # 主入口\n├── trace/ # 追踪核心\n│ ├── autopatch.py # 自动集成\n│ ├── ops.py # Op 定义\n│ └── serialization/ # 序列化系统\n├── trace_server/ # 服务端接口\n├── integrations/ # 第三方集成\n│ ├── openai/ # OpenAI 集成\n│ ├── anthropic/ # Anthropic 集成\n│ └── mistral/ # Mistral 集成\n└── flow/ # 评估工作流\n\nsdks/\n└── node/ # JavaScript SDK\n ├── src/\n │ ├── op.ts # Op 实现\n │ ├── opType.ts # 类型定义\n │ └── evaluation.ts # 评估功能\n └── README.md # Node SDK 文档\n```\n\n资料来源：[README.md:15-30]()\n\n## 快速开始\n\n### Python 快速开始\n\n1. 安装 Weave：`pip install weave`\n2. 初始化项目并追踪函数\n3. 查看追踪结果在 W&B 仪表板\n\n### Node.js 快速开始\n\n1. 安装：`npm install weave`\n2. 配置 `~/.netrc` 中的 W&B API 密钥\n3. 使用 `op()` 包装函数\n4. 运行并查看结果\n\n## 贡献指南\n\n项目当前处于代码整理阶段。核心代码位置：\n\n- **追踪代码**：`weave/trace` 和 `weave/trace_server`\n- **评估代码**：`weave/flow`\n\n资料来源：[README.md:27-30]()\n\n---\n\n\n\n## 安装与快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction), [函数追踪机制](#tracing)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/wandb/weave/blob/main/pyproject.toml)\n- [weave/trace/weave_init.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_init.py)\n- [weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n- [weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n- [sdks/node/README.md](https://github.com/wandb/weave/blob/main/sdks/node/README.md)\n- [weave/integrations/README.md](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n\n \n\n# 安装与快速开始\n\n## 概述\n\nWeave 是一个用于 AI 应用追踪（Tracing）和监控的库，由 W&B（Weights & Biases）提供。该库支持 Python 和 Node.js 两个主要 SDK，能够自动捕获和记录 AI 应用的执行过程，帮助开发者追踪函数调用、分析性能、调试问题。\n\n安装与快速开始模块是用户接触 Weave 的第一步，涵盖了环境准备、SDK 安装、项目初始化、基础追踪操作等核心流程。资料来源：[README.md:1-5]()\n\n## 环境要求\n\n### Python SDK 系统要求\n\n| 要求类型 | 最低版本 | 说明 |\n|---------|---------|------|\n| Python | 3.8+ | 支持 Python 3.8 及以上版本 |\n| pip | 最新版本 | 推荐使用最新版本的 pip 进行安装 |\n\n### Node.js SDK 系统要求\n\n| 要求类型 | 最低版本 | 说明 |\n|---------|---------|------|\n| Node.js | 18+ | 支持 Node.js 18 及以上版本 |\n| npm | 最新版本 | 用于安装 weave 包 |\n\n### 网络要求\n\n- 需要访问 W&B API 服务（api.wandb.ai）\n- 部分功能需要有效的 W&B API Key\n- 测试环境支持本地 Trace Server（localhost）\n\n资料来源：[sdks/node/README.md:1-20]()\n\n## Python SDK 安装\n\n### 使用 pip 安装\n\n```bash\npip install weave\n```\n\n### 验证安装\n\n安装完成后，可通过以下命令验证：\n\n```python\nimport weave\nprint(weave.__version__)\n```\n\n资料来源：[pyproject.toml](https://github.com/wandb/weave/blob/main/pyproject.toml)\n\n## Node.js SDK 安装\n\n### 使用 npm 安装\n\n```bash\nnpm install weave\n```\n\n### 配置认证\n\n在 `~/.netrc` 文件中添加 W&B API Key：\n\n```\nmachine api.wandb.ai\n login user\n password \n```\n\nAPI Key 可从 [W&B 授权页面](https://wandb.ai/authorize) 获取。\n\n资料来源：[sdks/node/README.md:1-25]()\n\n## 项目初始化\n\n### Python 初始化流程\n\n使用 `weave.init()` 函数初始化项目：\n\n```python\nimport weave\n\n# 初始化项目\nweave.init(\"my-project\")\n```\n\n### Node.js 初始化流程\n\n```javascript\nimport {init} from 'weave';\n\n// 初始化项目\nawait init('my-awesome-ai-project');\n```\n\n### 初始化参数说明\n\n| 参数名 | 类型 | 必需 | 默认值 | 说明 |\n|-------|------|-----|-------|------|\n| project | string | 是 | - | 项目名称 |\n| entity | string | 否 | 当前用户 | W&B 实体/团队名称 |\n| settings | dict/Settings | 否 | None | 高级配置选项 |\n\n### 配置选项（Settings）\n\n初始化时可通过 `settings` 参数进行高级配置：\n\n```python\nimport weave\n\nweave.init(\"my-project\", settings={\n 'implicitly_patch_integrations': True, # 自动注入集成\n 'print_call_link': True, # 打印调用链接\n})\n```\n\n资料来源：[weave/trace/weave_init.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_init.py)\n\n## 追踪操作入门\n\n### 使用 op 装饰器追踪函数\n\n#### Python 示例\n\n```python\nimport weave\n\n@weave.op()\ndef extract_fruit(sentence: str) -> str:\n \"\"\"提取句子中的水果名称\"\"\"\n return \"apple\"\n\n# 调用追踪函数\nresult = extract_fruit(\"I love apples and oranges\")\n```\n\n#### Node.js 示例\n\n```javascript\nimport {op} from 'weave';\n\nconst extractDinosOp = op(async function extractDinos(input) {\n // 你的逻辑\n return result;\n});\n```\n\n资料来源：[sdks/node/README.md:30-55]()\n\n### 类方法追踪\n\n#### Python 类方法\n\n```python\nimport weave\n\nclass MyAgent:\n @weave.op()\n async def analyze(self, text: str) -> dict:\n return {\"sentiment\": \"positive\", \"text\": text}\n\nagent = MyAgent()\nresult = await agent.analyze(\"This is great!\")\n```\n\n#### Node.js 类装饰器\n\n```javascript\nimport * as weave from \"weave\";\n\nclass TestClass {\n @weave.op\n async logImage(image) {\n // 方法逻辑\n }\n}\n```\n\n资料来源：[sdks/node/README.md:55-70]()\n\n## 自动集成与注入\n\n### 隐式注入（默认启用）\n\n当隐式注入启用时，Weave 会在支持的库被导入时自动应用追踪补丁：\n\n```python\nimport weave\nweave.init(\"my-project\")\nimport openai # 自动追踪已启用！\n```\n\n### 显式控制\n\n如需显式控制，可禁用隐式注入：\n\n```python\nimport weave\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\n\n# 显式启用特定集成\nweave.integrations.patch_openai()\nweave.integrations.patch_anthropic()\nweave.integrations.patch_mistral()\n```\n\n### 支持的集成列表\n\n| 集成名称 | 库名称 | patch 函数 |\n|---------|-------|-----------|\n| OpenAI | openai | `weave.integrations.patch_openai()` |\n| Anthropic | anthropic | `weave.integrations.patch_anthropic()` |\n| Mistral | mistral | `weave.integrations.patch_mistral()` |\n| LlamaIndex | llama_index | `weave.integrations.patch_llama_index()` |\n| Langchain | langchain | `weave.integrations.patch_langchain()` |\n\n资料来源：[weave/integrations/README.md:1-50]()\n\n## 快速开始示例\n\n### Python 完整示例\n\n```python\nimport weave\n\n# 1. 初始化项目\nweave.init(\"quickstart-demo\")\n\n# 2. 定义追踪函数\n@weave.op()\ndef extract_fruit(sentence: str) -> str:\n \"\"\"从句子中提取水果名称\"\"\"\n fruits = [\"apple\", \"banana\", \"cherry\", \"date\"]\n for fruit in fruits:\n if fruit in sentence.lower():\n return fruit\n return \"未找到水果\"\n\n# 3. 调用函数\nresult = extract_fruit(\"I love eating apples\")\nprint(f\"结果: {result}\")\n\n# 4. 获取追踪结果\ncalls = list(weave_client.get_calls())\nprint(f\"追踪到的调用数: {len(calls)}\")\n```\n\n### Node.js 完整示例\n\n创建 `predict.mjs` 文件：\n\n```javascript\nimport {OpenAI} from 'openai';\nimport {init, op, wrapOpenAI} from 'weave';\n\nconst openai = wrapOpenAI(new OpenAI());\n\nasync function extractDinos(input) {\n const response = await openai.chat.completions.create({\n model: 'gpt-4o',\n messages: [{role: 'user', content: `提取恐龙信息: ${input}`}],\n });\n return response.choices[0].message.content;\n}\n\nconst extractDinosOp = op(extractDinos);\n\nasync function main() {\n await init('weave-quickstart');\n const result = await extractDinosOp('T. rex 追逐三角龙');\n console.log(result);\n}\n\nmain();\n```\n\n运行：\n\n```bash\nnode predict.mjs\n```\n\n资料来源：[sdks/node/README.md:30-65]()\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 Weave SDK] --> B{选择运行环境}\n B -->|Python| C[使用 pip 安装]\n B -->|Node.js| D[使用 npm 安装]\n C --> E[配置 W&B API Key]\n D --> E\n E --> F[初始化项目 weave.init]\n F --> G{定义追踪操作}\n G -->|函数| H[使用 @weave.op 装饰器]\n G -->|类方法| I[使用 @weave.op 装饰方法]\n H --> J[调用追踪函数]\n I --> J\n J --> K[查看追踪结果]\n K --> L{启用集成追踪?}\n L -->|是| M[隐式/显式注入集成]\n L -->|否| K\n```\n\n## 常见问题与解决方案\n\n### 1. 追踪未生效\n\n**问题**：调用函数后没有追踪记录。\n\n**解决方案**：\n- 确保在调用函数前已调用 `weave.init()`\n- 检查是否禁用了隐式注入\n- 确认使用了正确的装饰器语法\n\n### 2. API Key 配置错误\n\n**问题**：无法连接到 W&B 服务。\n\n**解决方案**：\n- 验证 `~/.netrc` 文件中的 API Key 格式正确\n- 确认 API Key 具有有效权限\n- 检查网络连接和代理设置\n\n### 3. 集成库未被追踪\n\n**问题**：使用第三方库（如 OpenAI）时未记录调用。\n\n**解决方案**：\n- 确认集成库已安装：`pip install openai`\n- 显式调用 patch 函数：`weave.integrations.patch_openai()`\n- 或确保隐式注入已启用\n\n资料来源：[weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n\n## 下一步\n\n完成安装和快速开始后，你可以：\n\n| 进阶主题 | 说明 |\n|---------|------|\n| 高级追踪配置 | 自定义追踪行为、属性和显示方式 |\n| 评估与测试 | 使用 Weave 构建 AI 评估流程 |\n| 自定义序列化 | 添加自定义类型的序列化支持 |\n| 集成开发 | 为新的供应商库开发集成支持 |\n\n资料来源：[weave/trace/serialization/README.md:1-30]()\n\n## 相关文档链接\n\n- [Python SDK 源码](https://github.com/wandb/weave/tree/main/weave/trace)\n- [Node.js SDK 源码](https://github.com/wandb/weave/tree/main/sdks/node/src)\n- [集成开发指南](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n- [W&B 官方文档](https://docs.wandb.ai/)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[追踪数据流](#trace_flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/trace/weave_client.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_client.py)\n- [weave/trace_server/clickhouse_trace_server_batched.py](https://github.com/wandb/weave/blob/main/weave/trace_server/clickhouse_trace_server_batched.py)\n- [weave/trace_server_bindings](https://github.com/wandb/weave/blob/main/weave/trace_server_bindings)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n- [weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n \n\n# 系统架构\n\n## 概述\n\nWeave 是一个用于追踪和监控 AI 应用程序的库，支持 Python 和 Node.js 双端 SDK。其核心设计围绕**追踪（Tracing）**和**评估（Evaluations）**两大功能模块展开，旨在为 AI 应用提供可观测性和性能分析能力。\n\n系统架构采用分层设计，包含以下核心层次：\n\n```graph TD\n A[用户代码] --> B[Weave SDK 层]\n B --> C[追踪客户端层]\n C --> D[Trace Server 接口层]\n D --> E[Trace Server 实现层]\n E --> F[(ClickHouse 数据库)]\n \n G[集成模块] --> B\n H[自动补丁模块] --> G\n```\n\n资料来源：[weave/trace/weave_client.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_client.py)\n\n## 核心组件\n\n### SDK 层架构\n\nWeave SDK 提供 Python 和 Node.js 两种实现，共同遵循相同的架构理念：\n\n| SDK 类型 | 主要语言 | 核心文件 | 功能定位 |\n|---------|---------|---------|---------|\n| Python SDK | Python | `weave/trace/weave_client.py` | 服务端追踪数据处理 |\n| Node.js SDK | TypeScript | `sdks/node/src/op.ts` | 客户端函数包装与追踪 |\n\nPython SDK 侧重于服务端 trace 数据的接收、存储和查询，而 Node.js SDK 则专注于客户端操作的包装和追踪。\n\n资料来源：[sdks/node/src/op.ts:1-50](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n\n### 追踪客户端层\n\n`WeaveClient` 是 Python SDK 的核心类，负责管理追踪会话和调用记录：\n\n```mermaid\nclassDiagram\n class WeaveClient {\n +project_id: str\n +settings: WeaveStorageSettings\n +pushNewCall() CallContext\n +finishCall() None\n +finishCallWithException() None\n +waitForBatchProcessing() None\n }\n \n class CallContext {\n +currentCall: Call\n +parentCall: Call | None\n +newStack: list\n }\n```\n\n客户端通过 `pushNewCall()` 创建新的调用上下文，跟踪操作的执行状态和层级关系。\n\n资料来源：[weave/trace/weave_client.py](https://github.com/wandb/weave/blob/main/weave/trace/weave_client.py)\n\n### Op 包装机制\n\nOp（操作）是 Weave 追踪的基本单元，通过 `op()` 函数包装用户函数：\n\n```graph TD\n A[用户定义函数 fn] --> B[op(fn) 包装]\n B --> C[创建 Op 对象]\n C --> D[注入追踪逻辑]\n D --> E[返回包装后的函数]\n \n E --> F[同步函数处理]\n E --> G[异步函数处理]\n E --> H[流式响应处理]\n \n F --> I[直接返回结果]\n G --> J[Promise 包装]\n H --> K[AsyncIterator 代理]\n```\n\nOp 对象保留原函数的所有特性，同时添加追踪能力：\n\n```typescript\nexport type Op any> = {\n __isOp: true;\n __wrappedFunction: T;\n __boundThis?: WeaveObject;\n __name: string;\n __savedRef?: OpRef | Promise;\n __parameterNames?: ParameterNamesOption;\n invoke: CallMethod;\n} & T;\n```\n\n资料来源：[sdks/node/src/opType.ts:1-30](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n\n### Trace Server 接口层\n\n`trace_server_bindings` 定义了 Weave 与后端服务之间的接口契约：\n\n| 接口方法 | 功能描述 | 数据格式 |\n|---------|---------|---------|\n| `calls/stream_query` | 流式查询调用记录 | NDJSON |\n| `call/upsert_batch` | 批量创建/更新调用 | JSON |\n| `obj/*` | 对象管理 | JSON |\n| `table/*` | 表格数据管理 | JSON |\n| `file/*` | 文件存储管理 | 二进制 |\n\n接口层采用 RESTful 设计，兼容生产环境和测试环境。\n\n资料来源：[weave/trace_server_bindings](https://github.com/wandb/weave/blob/main/weave/trace_server_bindings)\n\n### Trace Server 实现层\n\n`clickhouse_trace_server_batched.py` 实现了基于 ClickHouse 的 trace 服务器：\n\n```mermaid\ngraph LR\n A[批量请求接收] --> B[请求队列管理]\n B --> C[批处理优化]\n C --> D[ClickHouse 写入]\n D --> E[查询接口]\n E --> F[NDJSON 流式响应]\n```\n\n批量处理机制显著提高了数据写入效率，降低了数据库连接开销。\n\n资料来源：[weave/trace_server/clickhouse_trace_server_batched.py](https://github.com/wandb/weave/blob/main/weave/trace_server/clickhouse_trace_server_batched.py)\n\n## 集成模块架构\n\n### 自动补丁系统\n\nWeave 的自动补丁系统通过 `sys.meta_path` 拦截导入，自动应用追踪补丁：\n\n```graph TD\n A[import vendor_lib] --> B[Meta Path 钩子]\n B --> C{patch_ 可用?}\n C -->|是| D[调用 patch_]\n C -->|否| E[跳过补丁]\n D --> F[修改 vendor_lib 函数]\n F --> G[注入追踪调用]\n```\n\n用户可通过配置控制隐式补丁行为：\n\n```python\n# 启用隐式补丁（默认）\nweave.init('my-project')\n\n# 禁用隐式补丁\nweave.init('my-project', settings={'implicitly_patch_integrations': False})\n\n# 或通过环境变量\n# export WEAVE_IMPLICITLY_PATCH_INTEGRATIONS=false\n```\n\n资料来源：[weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n\n### 支持的集成\n\n自动补丁系统支持主流 AI 服务商的 SDK：\n\n| 集成名称 | 补丁函数 | 追踪范围 |\n|---------|---------|---------|\n| OpenAI | `patch_openai()` | Chat completions, Embeddings |\n| Anthropic | `patch_anthropic()` | Messages, Completions |\n| Mistral | `patch_mistral()` | Chat endpoints |\n\n每个集成都有对应的 `get__patcher()` 函数用于获取补丁器实例。\n\n资料来源：[weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n\n## 数据流架构\n\n### 调用追踪数据流\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant SDK as Weave SDK\n participant Client as WeaveClient\n participant Server as Trace Server\n participant DB as ClickHouse\n \n User->>SDK: 调用 op 包装函数\n SDK->>Client: pushNewCall()\n Client->>Client: 创建 CallContext\n User->>SDK: 执行业务逻辑\n SDK->>Client: finishCall(result)\n Client->>Server: upsert_batch(calls)\n Server->>DB: 批量写入\n DB-->>Server: 确认写入\n Server-->>Client: 响应\n```\n\n### 流式响应处理\n\n对于支持流式输出的 AI API，Weave 通过代理模式拦截 `AsyncIterator`：\n\n```typescript\nconst proxy = new Proxy(result, {\n get: (target, prop) => {\n if (prop === Symbol.asyncIterator) {\n return WeaveIterator;\n }\n return Reflect.get(target, prop);\n },\n});\n```\n\n流式处理结合 `StreamReducer` 实现状态聚合和最终结果记录：\n\n```typescript\nexport interface StreamReducer {\n initialStateFn: () => R;\n reduceFn: (state: R, chunk: T) => R;\n finalizeFn: (state: R) => void;\n}\n```\n\n资料来源：[sdks/node/src/op.ts:150-200](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n\n## 配置系统\n\n### 初始化配置\n\nWeave 通过 `init()` 函数初始化追踪环境：\n\n```python\nweave.init(\n project_id: str, # 项目标识符\n settings: dict | None = None # 配置字典\n)\n```\n\n### 自动补丁配置\n\n`AutopatchSettings` 类定义了各集成的独立配置：\n\n```python\nclass AutopatchSettings(BaseModel):\n openai: IntegrationSettings = Field(default_factory=IntegrationSettings)\n anthropic: IntegrationSettings = Field(default_factory=IntegrationSettings)\n mistral: IntegrationSettings = Field(default_factory=IntegrationSettings)\n # ... 其他集成\n```\n\n### 客户端设置\n\n`WeaveStorageSettings` 控制客户端行为：\n\n| 设置项 | 类型 | 默认值 | 说明 |\n|-------|------|-------|------|\n| `implicitly_patch_integrations` | bool | `True` | 是否启用隐式集成补丁 |\n| `should_print_call_link` | bool | `True` | 是否打印调用链接 |\n\n## 测试架构\n\n### Mock Trace Server\n\n`trace_server_mock` 提供轻量级的内存 trace 服务器用于测试：\n\n```graph TD\n A[测试用例] --> B[启动 Mock Server]\n B --> C[设置环境变量]\n C --> D[执行测试逻辑]\n D --> E[查询 /test/getCalls]\n E --> F[断言验证]\n F --> G[清理 Mock Server]\n```\n\nMock 服务器支持以下测试专用端点：\n\n| 端点 | 方法 | 用途 |\n|-----|------|-----|\n| `/test/health` | GET | 健康检查 |\n| `/test/getCalls` | GET | 查询已记录的调用 |\n| `/test/reset` | POST | 重置测试数据 |\n\n资料来源：[trace_server_mock/README.md](https://github.com/wandb/weave/blob/main/trace_server_mock/README.md)\n\n### VCR 录制机制\n\n集成测试使用 `pytest-recording` 和 `vcrpy` 录制网络请求：\n\n```python\n@pytest.mark.vcr(\n filter_headers=[\"authorization\"],\n allowed_hosts=[\"api.wandb.ai\", \"localhost\"],\n)\ndef test__quickstart(\n client: weave.weave_client.WeaveClient,\n patch_: None,\n) -> None:\n # 测试逻辑\n```\n\n录制模式支持 `--record-mode=rewrite` 重新生成录制文件。\n\n## 序列化和反序列化\n\n### 序列化架构\n\nWeave 支持自定义类型的序列化和反序列化：\n\n```mermaid\ngraph LR\n A[Python 对象] -->|save| B[MemTraceFilesArtifact]\n B --> C[序列化数据]\n C --> D[HTTP 上传]\n \n D --> E[Trace Server]\n E --> F[ClickHouse 存储]\n \n F --> G[加载请求]\n G --> H[反序列化函数]\n H --> I[load_my_type]\n I --> J[Python 对象]\n```\n\n自定义类型需通过 `serializer.register_serializer()` 注册保存和加载函数。\n\n资料来源：[weave/trace/serialization/README.md](https://github.com/wandb/weave/blob/main/weave/trace/serialization/README.md)\n\n## 关键设计模式\n\n### 1. 代理模式\n\nOp 包装使用 JavaScript `Proxy` 拦截 `AsyncIterator` 访问，实现流式响应的透明追踪。\n\n### 2. 工厂模式\n\n各集成通过 `get__patcher()` 工厂函数获取统一的 `Patcher` 实例。\n\n### 3. 装饰器模式\n\nNode.js SDK 支持 `@weave.op` 装饰器用于类方法的追踪包装：\n\n```typescript\nclass TestClass {\n @weave.op\n async logImage(image: WeaveImage) {\n // 方法实现\n }\n}\n```\n\n### 4. 批量处理模式\n\nTrace Server 采用批量写入优化，减少数据库 I/O 开销。\n\n## 总结\n\nWeave 系统架构围绕追踪核心，采用分层和模块化设计：\n\n1. **SDK 层**：提供 Python/Node.js 双端 API\n2. **客户端层**：管理调用上下文和追踪状态\n3. **接口层**：定义统一的 trace 数据交换协议\n4. **服务端层**：实现高效的数据存储和查询\n5. **集成层**：支持主流 AI 服务的自动追踪\n\n架构设计强调**透明性**（无需修改业务代码）和**可扩展性**（支持自定义集成和类型），为 AI 应用提供无缝的可观测性能力。\n\n---\n\n\n\n## 追踪数据流\n\n### 相关页面\n\n相关主题：[系统架构](#system_architecture), [数据序列化](#serialization)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [sdks/node/src/evaluation.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/evaluation.ts)\n- [sdks/node/src/fn.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/fn.ts)\n- [weave/integrations/README.md](https://github.com/wandb/weave/blob/main/weave/integrations/README.md)\n- [weave/trace/serialization/README.md](https://github.com/wandb/weave/blob/main/weave/trace/serialization/README.md)\n- [trace_server_mock/README.md](https://github.com/wandb/weave/blob/main/trace_server_mock/README.md)\n- [README.md](https://github.com/wandb/weave/blob/main/README.md)\n \n\n# 追踪数据流\n\n## 概述\n\n追踪数据流（Trace Data Flow）是 Weave 框架中负责捕获、记录和传递 AI 应用执行信息的核心机制。它通过在函数调用前后插入钩子（Hook），将每次操作的输入、输出、执行时间和上下文信息收集起来，形成完整的调用链路追踪。\n\nWeave 的追踪系统主要分为两个层面：\n\n1. **Python SDK 层**：基于 `weave/trace` 目录下的核心组件，负责 Python 环境和第三方库的集成追踪\n2. **Node SDK 层**：基于 `sdks/node/src/` 目录下的 TypeScript 实现，为 JavaScript/TypeScript 环境提供追踪能力\n\n资料来源：[README.md:1-20]()\n\n## 核心数据类型\n\n### Op 类型定义\n\nOp（Operation）是 Weave 追踪的基本单位，表示一个被追踪的函数或方法。其核心类型定义如下：\n\n```typescript\nexport type Op any> = {\n __isOp: true; // 类型标记\n __wrappedFunction: T; // 原始函数引用\n __boundThis?: WeaveObject; // 绑定的 this 对象\n __name: string; // 操作名称\n __savedRef?: OpRef | Promise; // Op 的持久化引用\n __parameterNames?: ParameterNamesOption;// 参数名称配置\n invoke: CallMethod; // 调用方法\n} & T;\n```\n\n资料来源：[sdks/node/src/opType.ts:3-17]()\n\n### Call 类型\n\nCall 表示一次函数调用的完整记录，包含调用 ID、时间戳、输入输出等信息：\n\n```typescript\nexport interface Call {\n id: string;\n traceId?: string;\n parentId?: string;\n startedAt: Date;\n endedAt?: Date;\n inputs?: Record;\n outputs?: Record;\n summary?: CallSummary;\n attributes?: Record;\n opName?: string;\n opRef?: OpRef;\n}\n```\n\n### OpRef 类型\n\nOpRef 是操作的持久化引用，用于在 UI 中定位和分享特定的操作版本：\n\n```typescript\nexport class OpRef {\n constructor(\n public projectId: string,\n public objectId: string,\n public digest: string\n ) {}\n\n public uri() {\n return `weave:///${this.projectId}/op/${this.objectId}:${this.digest}`;\n }\n\n public ui_url() {\n const domain = getGlobalDomain();\n return `https://${domain}/${this.projectId}/weave/ops/${this.objectId}/versions/${this.digest}`;\n }\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:65-85]()\n\n## 追踪流程架构\n\n### 整体数据流图\n\n```mermaid\ngraph TD\n A[用户调用被追踪函数] --> B[Op Wrapper 拦截调用]\n B --> C[创建 InternalCall 对象]\n C --> D[推入新调用栈]\n D --> E[记录开始时间戳]\n E --> F[执行原始函数]\n F --> G[收集返回值]\n G --> H[记录结束时间戳]\n H --> I[构建 Call 对象]\n I --> J[发送到 Trace Server]\n J --> K[返回结果给调用方]\n \n L[异步迭代器场景] --> M[StreamReducer 处理]\n M --> N[增量收集流式输出]\n N --> O[组装完整输出]\n O --> H\n```\n\n### 调用上下文管理\n\nWeave 使用全局客户端和上下文栈来管理调用层级关系：\n\n```typescript\ninterface CallContext {\n currentCall: Call;\n parentCall: Call | null;\n newStack: boolean;\n}\n\nclass WeaveClient {\n // 推送新调用并获取上下文\n pushNewCall(): CallContext {\n // 创建新的 Call 对象\n // 建立父子调用关系\n // 返回上下文信息\n }\n}\n```\n\n资料来源：[sdks/node/src/op.ts:30-80]()\n\n## Op 创建与包装\n\n### 创建流程\n\n当用户使用 `@weave.op` 装饰器或 `op()` 函数包装函数时，Weave 执行以下步骤：\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant O as op() 函数\n participant CP as createOpWrapper\n participant IC as InternalCall\n participant C as WeaveClient\n\n U->>O: op(myFunction, options?)\n O->>CP: createOpWrapper(myFunction, options)\n CP->>IC: new InternalCall()\n IC->>C: pushNewCall()\n C-->>IC: 返回 CallContext\n IC-->>CP: wrapped function\n CP-->>O: Op 对象\n O-->>U: 可追踪的函数\n```\n\n### Op Wrapper 实现\n\n核心的函数包装逻辑位于 `createOpWrapper` 函数中：\n\n```typescript\nconst opWrapper = async function (\n this: any,\n ...params: Parameters\n): Promise>> {\n const client = getGlobalClient();\n \n // 检查客户端是否初始化\n if (!client) {\n warnOnce('weave-not-initialized', 'WARNING: Weave is not initialized...');\n return await fn.apply(thisArg, params);\n }\n\n // 创建调用上下文\n const {currentCall, parentCall, newStack} = client.pushNewCall();\n const startTime = new Date();\n \n // 打印调用链接（可选）\n if (client.settings.shouldPrintCallLink && parentCall == null) {\n console.log(`${TRACE_CALL_EMOJI} https://${domain}/${client.projectId}/r/call/${currentCall.callId}`);\n }\n\n // 执行原始函数\n const result = await fn.apply(thisArg, params);\n \n // 记录完成信息并发送\n // ...\n return result;\n};\n```\n\n资料来源：[sdks/node/src/op.ts:50-100]()\n\n### 装饰器支持\n\nWeave 支持两种装饰器模式：\n\n| 装饰器类型 | 使用方式 | 代码示例 |\n|-----------|---------|---------|\n| Stage 3 装饰器 | `@weave.op` | `@weave.op async method()` |\n| Legacy 装饰器 | `@weave.op()` | `@weave.op() async method()` |\n| 装饰器工厂 | `@weave.op(options)` | `@weave.op({name: 'custom'}) async method()` |\n\n```typescript\n// Stage 3 装饰器处理\nfunction handleModernDecorator any>(\n originalMethod: T,\n context: ClassMethodDecoratorContext,\n factoryOptions?: Partial>\n): T {\n const derivedName = `${String(context.name)}`;\n const options = {\n ...factoryOptions,\n isDecorator: true,\n originalFunction: originalMethod,\n context: context,\n };\n return createOpWrapper(originalMethod, options);\n}\n```\n\n资料来源：[sdks/node/src/op.ts:150-200]()\n\n## 异步迭代器支持\n\n### StreamReducer 接口\n\n对于返回异步迭代器的函数（如流式 LLM 输出），Weave 使用 `StreamReducer` 接口进行处理：\n\n```typescript\nexport interface StreamReducer {\n initialStateFn: () => R; // 初始状态工厂\n reduceFn: (state: R, chunk: T) => R; // 归约函数\n finalizeFn: (state: R) => void; // 最终化函数\n}\n```\n\n资料来源：[sdks/node/src/opType.ts:18-24]()\n\n### 并行流式处理\n\n对于评估场景中的并行流式处理，Weave 提供了以下机制：\n\n```typescript\nasync function* asyncParallelMap(\n asyncIterator: AsyncIterable,\n fn: (item: T, ...args: any[]) => Promise,\n fnParams: (item: T) => any[],\n maxConcurrency: number\n) {\n const itemPromiseMap: Map}>> = new Map();\n \n for await (const item of asyncIterator) {\n // 控制并发数量\n if (itemPromiseMap.size >= maxConcurrency) {\n const done = await Promise.race(itemPromiseMap.values());\n itemPromiseMap.delete(done.item);\n yield { ...done, nRunning: itemPromiseMap.size, nDone: ++nDone };\n }\n const prom = runOne(item);\n itemPromiseMap.set(item, prom);\n }\n // 处理剩余项目...\n}\n```\n\n资料来源：[sdks/node/src/evaluation.ts:40-70]()\n\n## 集成追踪机制\n\n### 隐式补丁模式\n\nWeave 通过 `sys.meta_path` 拦截机制实现隐式补丁：\n\n```mermaid\ngraph LR\n A[import vendor_lib] --> B[meta_path 拦截]\n B --> C[调用 patch_()]\n C --> D[SymbolPatcher 替换符号]\n D --> E[vendor_lib 函数被追踪]\n```\n\n### 显式补丁模式\n\n当隐式补丁被禁用时，用户需要显式调用补丁函数：\n\n```python\nimport weave\n\n# 初始化，禁用隐式补丁\nweave.init(\"my-project\", settings={'implicitly_patch_integrations': False})\n\n# 显式启用追踪\nweave.integrations.patch_openai()\nweave.integrations.patch_anthropic()\nweave.integrations.patch_mistral()\n```\n\n资料来源：[weave/integrations/README.md:30-60]()\n\n### Patch 函数结构\n\n每个集成需要实现 `get__patcher` 函数：\n\n```python\ndef get__patcher(\n settings: IntegrationSettings | None = None,\n) -> MultiPatcher | NoOpPatcher:\n if settings is None:\n settings = IntegrationSettings()\n\n if not settings.enabled:\n return NoOpPatcher()\n\n global __patcher\n if __patcher is None:\n __patcher = MultiPatcher([\n # 添加具体的补丁对象...\n ])\n return __patcher\n```\n\n## 追踪服务端交互\n\n### 批量上传接口\n\n追踪数据通过 HTTP API 批量上传到 Trace Server：\n\n```mermaid\nsequenceDiagram\n participant SDK as Weave SDK\n participant TS as Trace Server\n participant DB as In-Memory Store\n\n SDK->>TS: POST /call/upsert_batch\n TS->>DB: 存储调用记录\n DB-->>TS: 确认存储\n TS-->>SDK: 200 OK\n\n Note over SDK,TS: 支持生产环境 API 格式\n```\n\n### 模拟服务器\n\n测试环境使用轻量级模拟 Trace Server：\n\n```bash\nREADY=http://127.0.0.1:NNNN\n```\n\n**主要端点：**\n\n| 端点 | 方法 | 用途 |\n|-----|------|-----|\n| `/call/upsert_batch` | POST | 批量上传调用记录 |\n| `/calls/stream_query` | POST | 流式查询调用 |\n| `/test/health` | GET | 健康检查 |\n| `/test/getCalls` | GET | 获取调用列表（测试专用） |\n| `/test/reset` | POST | 重置存储（测试专用） |\n\n资料来源：[trace_server_mock/README.md:15-30]()\n\n## Callable 抽象\n\n### CallableObject 基类\n\nWeave 提供了 `CallableObject` 抽象类，用于构建可追踪的自定义类型：\n\n```typescript\nexport interface Callable {\n run: (input: I) => Promise;\n}\n\nexport abstract class CallableObject\n extends WeaveObject\n implements Callable\n{\n abstract run(input: I): Promise;\n}\n```\n\n### 参数映射\n\n提供了 `mapArgs` 工具函数用于参数重映射：\n\n```typescript\nexport function mapArgs<\n T extends Record,\n M extends Record,\n>(input: T, mapping: M): {[K in keyof M]: T[M[K]]} {\n const result: Partial<{[K in keyof M]: T[M[K]]}> = {};\n\n for (const [newKey, oldKey] of Object.entries(mapping)) {\n if (oldKey in input) {\n result[newKey as keyof M] = input[oldKey];\n }\n }\n return result as {[K in keyof M]: T[M[K]]};\n}\n```\n\n资料来源：[sdks/node/src/fn.ts:1-30]()\n\n## 初始化与配置\n\n### 项目初始化\n\n使用 `init` 函数初始化追踪项目：\n\n```typescript\nimport {init} from 'weave';\n\nawait init('my-awesome-ai-project');\n```\n\n### 追踪选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `shouldPrintCallLink` | boolean | - | 是否打印调用链接到控制台 |\n| `implicitly_patch_integrations` | boolean | true | 是否启用隐式集成补丁 |\n| `callDisplayName` | function | undefined | 自定义调用名称生成器 |\n| `opKind` | string | undefined | 操作类型标识 |\n| `opColor` | string | undefined | UI 显示颜色 |\n\n### 操作装饰器选项\n\n```typescript\ninterface OpOptions any> {\n name?: string;\n callDisplayName?: (args: Parameters) => string;\n bindThis?: any;\n isDecorator?: boolean;\n shouldAdoptThis?: boolean;\n originalFunction?: F;\n context?: ClassMethodDecoratorContext;\n opKind?: string;\n opColor?: string;\n}\n```\n\n## 数据序列化\n\n### 序列化策略\n\n追踪数据支持多种序列化策略：\n\n| 策略 | 适用场景 | 说明 |\n|-----|---------|------|\n| 文件序列化 | 大型对象（如图片） | 通过 `MemTraceFilesArtifact` 存储 |\n| 内联序列化 | 小型对象（如 datetime） | 直接存储在 Call 对象中 |\n\n### 内置序列化类型\n\nWeave 内置以下第一类序列化器：\n\n- **图片**: `PIL.Image.Image`\n- **音频**: `wave.Wave_read`\n- **操作**: `weave.Op`\n- **日期时间**: `datetime.datetime`\n- **Markdown**: `rich.markdown.Markdown`\n\n资料来源：[weave/trace/serialization/README.md:20-35]()\n\n## 调用链路追踪\n\n### 父子调用关系\n\n每次函数调用都会建立父子调用关系：\n\n```mermaid\ngraph TD\n A[根调用: extract_dinos] --> B[子调用: openai.chat.completions.create]\n B --> C[子调用: model.invoke]\n A --> D[子调用: post_process]\n C --> D\n```\n\n### 调用链接打印\n\n当 `shouldPrintCallLink` 启用且为根调用时，系统会打印追踪链接：\n\n```typescript\nconst TRACE_CALL_EMOJI = '🔍';\nconsole.log(\n `${TRACE_CALL_EMOJI} https://${domain}/${client.projectId}/r/call/${currentCall.callId}`\n);\n```\n\n## 错误处理\n\n### 未初始化警告\n\n当 Weave 未初始化时，追踪调用会被静默跳过：\n\n```typescript\nif (!client) {\n warnOnce(\n 'weave-not-initialized',\n 'WARNING: Weave is not initialized, so calls wont be tracked. Call `weave.init` to initialize before calling ops.'\n );\n return await fn.apply(thisArg, params);\n}\n```\n\n### 补丁失败处理\n\n对于未成功加载的集成，返回 `NoOpPatcher`：\n\n```python\nif not settings.enabled:\n return NoOpPatcher()\n```\n\n## 总结\n\nWeave 的追踪数据流通过以下关键组件实现：\n\n1. **Op 抽象层**：提供统一的函数包装和追踪接口\n2. **Call 上下文管理**：维护调用栈和父子关系\n3. **集成补丁系统**：支持第三方库的自动和手动追踪\n4. **异步迭代器处理**：支持流式输出的增量追踪\n5. **序列化层**：处理复杂数据类型的持久化\n\n整个系统在 Python SDK 和 Node SDK 之间保持了架构一致性，同时针对各语言特性进行了优化适配。\n\n---\n\n\n\n## 函数追踪机制\n\n### 相关页面\n\n相关主题：[追踪数据流](#trace_flow), [模型供应商集成](#vendor_integrations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [weave/trace/op.py](https://github.com/wandb/weave/blob/main/weave/trace/op.py)\n- [weave/trace/op_caller.py](https://github.com/wandb/weave/blob/main/weave/trace/op_caller.py)\n- [weave/trace/op_protocol.py](https://github.com/wandb/weave/blob/main/weave/trace/op_protocol.py)\n- [weave/trace/autopatch.py](https://github.com/wandb/weave/blob/main/weave/trace/autopatch.py)\n- [sdks/node/src/opType.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/opType.ts)\n- [sdks/node/src/op.ts](https://github.com/wandb/weave/blob/main/sdks/node/src/op.ts)\n- [weave/integrations/patch.py](https://github.com/wandb/weave/blob/main/weave/integrations/patch.py)\n \n\n# 函数追踪机制\n\n## 概述\n\n函数追踪机制（Function Tracing Mechanism）是 Weave 框架的核心能力之一，用于自动捕获、记录和监控 AI 应用程序中函数的执行情况。该机制通过将普通函数包装为可追踪的 Op（操作）对象，实现对函数调用链路、输入输出、执行时间等关键信息的完整记录。\n\nWeave 的函数追踪机制主要包含以下特性：\n\n- **透明包装**：通过装饰器或显式包装，将现有函数转换为可追踪的 Op\n- **调用链路**：自动维护父子调用关系，构建完整的调用树\n- **属性标注**：支持为操作添加分类标签（如 `llm`、`agent`、`tool`）和自定义颜色\n- **流式支持**：兼容异步生成器，可追踪流式输出的中间结果\n- **集成支持**：通过自动补丁机制，无缝集成第三方 SDK（如 OpenAI、Anthropic）\n\n---\n\n## 核心概念\n\n### Op（操作）\n\nOp 是 Weave 追踪系统的基本单位。每个被追踪的函数都会被包装为一个 Op 对象，它包含以下核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `__isOp` | boolean | 标识该对象为 Op |\n| `__wrappedFunction` | Function | 被包装的原始函数 |\n| `__name` | string | 操作名称 |\n| `__boundThis` | WeaveObject | 绑定的 `this` 上下文 |\n| `__parameterNames` | string[] | 参数名称列表 |\n| `invoke` | CallMethod | 异步调用方法 |\n\nOp 的类型定义同时支持同步函数和异步函数：\n\n```typescript\nexport type Op any> = {\n __isOp: true;\n __wrappedFunction: T;\n __boundThis?: WeaveObject;\n __name: string;\n __savedRef?: OpRef | Promise;\n __parameterNames?: ParameterNamesOption;\n invoke: CallMethod;\n} & T &\n ((\n ...args: Parameters