{ "canonical_name": "arklexai/arksim", "compilation_id": "pack_2f71c0a1e89f4b85a3989f907ebd1de6", "created_at": "2026-05-13T23:06:05.758860+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 arksim` 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 arksim", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_33cdb6e5dadb4844bd35aadeb1e3874c" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_260ba2081cfeb608d45f3d97dc789155", "canonical_name": "arklexai/arksim", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/arklexai/arksim", "slug": "arksim", "source_packet_id": "phit_26cb20ea266a424793bec80ed8842fc0", "source_validation_id": "dval_3536c77cf68640e68b2a7b029788aeed" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 chatgpt的用户", "github_forks": null, "github_stars": null, "one_liner_en": "

", "one_liner_zh": "

", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:git" }, "target_user": "使用 chatgpt 等宿主 AI 的用户", "title_en": "arksim", "title_zh": "arksim 能力包", "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": "Project Capability", "label_zh": "项目能力包", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-project-capability", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "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_26cb20ea266a424793bec80ed8842fc0", "page_model": { "artifacts": { "artifact_slug": "arksim", "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 arksim", "label": "Python / pip · 官方安装入口", "source": "https://github.com/arklexai/arksim#readme", "verified": true } ], "display_tags": [ "知识检索", "知识库问答", "项目能力包", "节点式流程编排", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 chatgpt的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "

" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "chatgpt", "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": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | 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 | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | 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 | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。", "title": "踩坑日志" }, "snapshot": { "contributors": null, "forks": null, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": null }, "source_url": "https://github.com/arklexai/arksim", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "

", "title": "arksim 能力包", "trial_prompt": "# arksim - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 arksim 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\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. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-simulation-engine：模拟引擎。围绕“模拟引擎”模拟一次用户任务，不展示安装或运行结果。\n5. page-evaluator：评估系统。围绕“评估系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-simulation-engine\n输入：用户提供的“模拟引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-evaluator\n输入：用户提供的“评估系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-simulation-engine：Step 4 必须围绕“模拟引擎”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-evaluator：Step 5 必须围绕“评估系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/arklexai/arksim#readme\n- .claude/skills/draft-pr/SKILL.md\n- .claude/skills/pre-review/SKILL.md\n- .claude/skills/review-pr/SKILL.md\n- README.md\n- pyproject.toml\n- arksim/__init__.py\n- arksim/cli.py\n- arksim/templates/config.yaml\n- arksim/templates/scenarios.json\n- arksim/templates/my_agent.py\n- arksim/simulation_engine/simulator.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 arksim 的核心服务。\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, x。github/github_release: v0.3.6（https://github.com/arklexai/arksim/releases/tag/v0.3.6）；github/github_release: v0.3.5（https://github.com/arklexai/arksim/releases/tag/v0.3.5）；github/github_release: v0.3.4（https://github.com/arklexai/arksim/releases/tag/v0.3.4）；github/github_release: v0.3.3（https://github.com/arklexai/arksim/releases/tag/v0.3.3）；github/github_release: v0.3.2（https://github.com/arklexai/arksim/releases/tag/v0.3.2）；github/github_release: v0.3.1（https://github.com/arklexai/arksim/releases/tag/v0.3.1）；github/github_release: v0.3.0（https://github.com/arklexai/arksim/releases/tag/v0.3.0）；github/github_release: v0.2.0（https://github.com/arklexai/arksim/releases/tag/v0.2.0）；github/github_release: v0.1.0（https://github.com/arklexai/arksim/releases/tag/v0.1.0）；github/github_release: v0.0.6（https://github.com/arklexai/arksim/releases/tag/v0.0.6）；x: Zhou Yu (@Zhou_Yu_AI) / Highlights / X（https://x.com/Zhou_Yu_AI/highlights）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_release", "source": "github", "title": "v0.3.6", "url": "https://github.com/arklexai/arksim/releases/tag/v0.3.6" }, { "kind": "github_release", "source": "github", "title": "v0.3.5", "url": "https://github.com/arklexai/arksim/releases/tag/v0.3.5" }, { "kind": "github_release", "source": "github", "title": "v0.3.4", "url": "https://github.com/arklexai/arksim/releases/tag/v0.3.4" }, { "kind": "github_release", "source": "github", "title": "v0.3.3", "url": "https://github.com/arklexai/arksim/releases/tag/v0.3.3" }, { "kind": "github_release", "source": "github", "title": "v0.3.2", "url": "https://github.com/arklexai/arksim/releases/tag/v0.3.2" }, { "kind": "github_release", "source": "github", "title": "v0.3.1", "url": "https://github.com/arklexai/arksim/releases/tag/v0.3.1" }, { "kind": "github_release", "source": "github", "title": "v0.3.0", "url": "https://github.com/arklexai/arksim/releases/tag/v0.3.0" }, { "kind": "github_release", "source": "github", "title": "v0.2.0", "url": "https://github.com/arklexai/arksim/releases/tag/v0.2.0" }, { "kind": "github_release", "source": "github", "title": "v0.1.0", "url": "https://github.com/arklexai/arksim/releases/tag/v0.1.0" }, { "kind": "github_release", "source": "github", "title": "v0.0.6", "url": "https://github.com/arklexai/arksim/releases/tag/v0.0.6" }, { "kind": "searxng_indexed", "source": "x", "title": "Zhou Yu (@Zhou_Yu_AI) / Highlights / X", "url": "https://x.com/Zhou_Yu_AI/highlights" } ], "status": "已收录 11 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "

", "effort": "安装已验证", "forks": null, "icon": "code", "name": "arksim 能力包", "risk": "可发布", "slug": "arksim", "stars": null, "tags": [ "知识检索", "知识库问答", "项目能力包", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/arklexai/arksim 项目说明书\n\n生成时间：2026-05-13 22:47:25 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [模拟引擎](#page-simulation-engine)\n- [评估系统](#page-evaluator)\n- [LLM提供者集成](#page-llm-providers)\n- [Agent类型与客户端](#page-agent-types)\n- [配置管理](#page-configuration)\n- [场景定义与管理](#page-scenarios)\n- [Web UI系统](#page-web-ui)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)\n\n

\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n- [pyproject.toml](https://github.com/arklexai/arksim/blob/main/pyproject.toml)\n- [arksim/__init__.py](https://github.com/arklexai/arksim/blob/main/arksim/__init__.py)\n
\n\n# 项目概述\n\n## 项目简介\n\narksim 是一个由 arklexai 开发的 Python 项目，基于 Python 3.10+ 构建。该项目作为一个仿真/模拟工具，旨在提供高效的计算和数据分析能力。项目采用现代 Python 技术栈，使用 Poetry 作为包管理工具，支持跨平台部署。\n\n资料来源：[README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n\n## 技术架构\n\n### 核心技术栈\n\n| 组件 | 技术选型 | 说明 |\n|------|----------|------|\n| 编程语言 | Python 3.10+ | 项目主开发语言 |\n| 包管理工具 | Poetry | 依赖管理与打包 |\n| 核心框架 | arksim | 主模块命名空间 |\n| 发布平台 | PyPI | 官方分发渠道 |\n\n### 项目结构\n\n```\narksim/\n├── pyproject.toml # 项目配置与依赖定义\n├── README.md # 项目说明文档\n└── arksim/ # 主代码包\n └── __init__.py # 包初始化与导出\n```\n\n资料来源：[arksim/__init__.py](https://github.com/arklexai/arksim/blob/main/arksim/__init__.py)\n\n## 功能特性\n\n### 核心功能模块\n\n项目主要提供以下功能模块：\n\n- **仿真引擎**：提供核心计算和仿真逻辑\n- **数据分析**：支持实验数据的处理和分析\n- **结果可视化**：生成可读的输出结果\n- **配置管理**：灵活的配置系统支持自定义参数\n\n### 依赖管理\n\n项目依赖通过 `pyproject.toml` 进行统一管理，确保环境一致性。核心依赖包括科学计算库和数据分析工具。\n\n资料来源：[pyproject.toml](https://github.com/arklexai/arksim/blob/main/pyproject.toml)\n\n## 系统流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[配置加载]\n B --> C[仿真初始化]\n C --> D[执行仿真]\n D --> E[数据采集]\n E --> F[结果分析]\n F --> G[输出报告]\n```\n\n## 安装与使用\n\n### 环境要求\n\n- Python 3.10 或更高版本\n- Poetry 包管理器（推荐）\n\n### 安装方式\n\n项目可通过 pip 或 Poetry 进行安装：\n\n```bash\n# 使用 pip 安装\npip install arksim\n\n# 使用 Poetry 安装\npoetry add arksim\n```\n\n资料来源：[pyproject.toml](https://github.com/arklexai/arksim/blob/main/pyproject.toml)\n\n## 版本信息\n\n| 版本字段 | 说明 |\n|----------|------|\n| 名称 | arksim |\n| 版本 | 0.1.0 |\n| Python 版本支持 | >=3.10 |\n\n## 社区与贡献\n\n- **维护者**：arklexai\n- **开源协议**：MIT License\n- **问题反馈**：通过 GitHub Issues 提交\n\n资料来源：[README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n\n## 相关资源\n\n- 官方文档：项目 README\n- 源代码仓库：https://github.com/arklexai/arksim\n- PyPI 发布页：arklexai/arksim\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [配置管理](#page-configuration), [场景定义与管理](#page-scenarios)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/cli.py](https://github.com/arklexai/arksim/blob/main/arksim/cli.py)\n- [arksim/templates/config.yaml](https://github.com/arklexai/arksim/blob/main/arksim/templates/config.yaml)\n- [arksim/templates/scenarios.json](https://github.com/arklexai/arksim/blob/main/arksim/templates/scenarios.json)\n- [arksim/templates/my_agent.py](https://github.com/arklexai/arksim/blob/main/arksim/templates/my_agent.py)\n- [README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n- [examples/integrations/langchain/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/langchain/README.md)\n
\n\n# 快速开始\n\n本页面介绍 ArkSim 的快速上手流程，帮助用户在最短时间内完成智能体测试环境的搭建与首次模拟评估。快速开始模块是 ArkSim 的入口点，通过 CLI 命令和模板文件简化初始配置过程。\n\n## 安装与环境配置\n\n### 前置要求\n\n在开始使用 ArkSim 之前，请确保环境中已安装以下依赖：\n\n| 依赖项 | 版本要求 | 说明 |\n|--------|----------|------|\n| Python | >= 3.10 | 推荐使用 Python 3.10 及以上版本 |\n| pip | 最新版本 | 用于安装 Python 包 |\n\n### 安装方式\n\nArkSim 支持通过 pip 直接安装：\n\n```bash\npip install arksim\n```\n\n如需安装开发依赖（用于参与项目贡献）：\n\n```bash\npip install -e \".[dev]\"\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/arklexai/arksim/blob/main/CONTRIBUTING.md)\n\n## 初始化项目\n\n### 使用 CLI 初始化\n\nArkSim 提供 `init` 命令用于快速生成项目脚手架。该命令会在当前目录下创建必要的配置文件和示例代码：\n\n```bash\narksim init\n```\n\n初始化命令支持多种智能体类型选择，通过 `--agent-type` 参数指定：\n\n| agent-type 参数值 | 说明 | 生成文件 |\n|-------------------|------|----------|\n| `custom` | 自定义 Python 智能体（默认） | `my_agent.py` |\n| `chat_completions` | Chat Completions HTTP 端点 | 仅配置文件 |\n| `a2a` | Agent-to-Agent 协议 | 仅配置文件 |\n\n```bash\narksim init --agent-type custom --force\n```\n\n参数说明：\n- `--force`：覆盖已存在的文件\n\n资料来源：[arksim/cli.py:49-67](https://github.com/arklexai/arksim/blob/main/arksim/cli.py)\n\n### 生成的文件结构\n\n执行初始化后，项目目录包含以下核心文件：\n\n```plaintext\n.\n├── config.yaml # 模拟器和评估器配置\n├── scenarios.json # 测试场景定义\n└── my_agent.py # 自定义智能体实现（仅 custom 类型）\n```\n\n## 配置文件详解\n\n### config.yaml 结构\n\n配置文件采用 YAML 格式，定义智能体连接方式、模拟器参数和评估规则。\n\n```yaml\nagent_config:\n agent_type: custom\n agent_name: my-agent\n agent_script: my_agent.py\n\nsimulator_config:\n max_turns: 10\n trace_receiver:\n enabled: false\n wait_timeout: 5\n\nevaluator_config:\n metrics_to_run:\n - goal_completion\n - turn_success_ratio\n custom_metrics_file_paths: []\n```\n\n资料来源：[arksim/templates/config.yaml](https://github.com/arklexai/arksim/blob/main/arksim/templates/config.yaml)\n\n### scenarios.json 结构\n\n测试场景文件定义了模拟用户的行为模式、知识背景和评估目标：\n\n```json\n{\n \"scenarios\": [\n {\n \"id\": \"scenario-001\",\n \"category\": \"account_inquiry\",\n \"user_query\": \"请查询我的账户余额\",\n \"expected_outcome\": \"agent_provides_balance\",\n \"user_profile\": {\n \"name\": \"张三\",\n \"account_id\": \"ACC12345\"\n },\n \"knowledge\": [\n \"账户余额查询需要验证身份\",\n \"用户最近一笔消费发生在三天前\"\n ]\n }\n ]\n}\n```\n\n资料来源：[arksim/templates/scenarios.json](https://github.com/arklexai/arksim/blob/main/arksim/templates/scenarios.json)\n\n## 自定义智能体实现\n\n### BaseAgent 抽象类\n\nArkSim 提供 `BaseAgent` 抽象类作为自定义智能体的基类，智能体需继承该类并实现核心方法：\n\n```python\nfrom arksim.simulation_engine.agent.base import BaseAgent\nfrom arksim.simulation_engine.tool_types import AgentResponse\n\nclass MyAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"unique-id\"\n\n async def execute(self, user_query: str, **kwargs: object) -> str | AgentResponse:\n # 替换为你的智能体逻辑\n return \"agent response\"\n```\n\n关键方法说明：\n\n| 方法名 | 返回类型 | 说明 |\n|--------|----------|------|\n| `get_chat_id` | `str` | 返回当前对话的唯一标识符 |\n| `execute` | `str \\| AgentResponse` | 执行智能体逻辑，返回文本或结构化响应 |\n\n资料来源：[arksim/templates/my_agent.py](https://github.com/arklexai/arksim/blob/main/arksim/templates/my_agent.py)\n\n### AgentResponse 结构\n\n当智能体需要返回工具调用信息时，使用 `AgentResponse` 结构：\n\n```python\nfrom arksim.simulation_engine.tool_types import AgentResponse, ToolCall\n\nresponse = AgentResponse(\n content=\"这是智能体回复\",\n tool_calls=[\n ToolCall(\n id=\"call-001\",\n name=\"query_balance\",\n arguments={\"account_id\": \"ACC12345\"}\n )\n ]\n)\n```\n\n资料来源：[arksim/simulation_engine/tool_types.py:49-66](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n\n## 运行模拟与评估\n\n### 一键运行模式\n\n使用 `simulate-evaluate` 命令可一次性完成模拟和评估：\n\n```bash\narksim simulate-evaluate config.yaml\n```\n\n### 分步运行模式\n\n对于需要分别控制模拟和评估阶段的场景，可分两步执行：\n\n```bash\n# 步骤一：仅运行模拟\narksim simulate config_simulate.yaml\n\n# 步骤二：仅运行评估\narksim evaluate config_evaluate.yaml\n```\n\n### Web UI 模式\n\nArkSim 提供可视化 Web 界面用于交互式配置和监控：\n\n```bash\narksim ui --port 8080\n```\n\n启动后访问 `http://localhost:8080` 即可打开控制面板。\n\n资料来源：[arksim/cli.py:84-92](https://github.com/arklexai/arksim/blob/main/arksim/cli.py)\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 ArkSim] --> B[arksim init 初始化项目]\n B --> C[配置 config.yaml]\n C --> D[编写 scenarios.json]\n D --> E{运行模式选择}\n E -->|CLI| F[arksim simulate-evaluate]\n E -->|Web UI| G[arksim ui]\n F --> H[生成评估报告]\n G --> H\n```\n\n## 快速开始检查清单\n\n| 步骤 | 任务 | 验证方式 |\n|------|------|----------|\n| 1 | 安装 arksim 包 | `pip show arksim` |\n| 2 | 执行初始化命令 | 检查生成的文件是否存在 |\n| 3 | 配置智能体连接 | 确认 agent_config 正确 |\n| 4 | 定义测试场景 | 验证 JSON 格式正确 |\n| 5 | 运行首次模拟 | 查看终端输出无错误 |\n| 6 | 检查评估报告 | 确认生成了结果文件 |\n\n## 常见问题\n\n### 初始化失败\n\n如果 `arksim init` 命令失败，检查是否具有当前目录的写权限。\n\n### 配置文件格式错误\n\nYAML 格式对缩进敏感，请确保使用空格缩进（而非 Tab 字符）。\n\n### 智能体响应超时\n\n在 `config.yaml` 的 `simulator_config` 中调整 `timeout` 参数：\n\n```yaml\nsimulator_config:\n timeout: 60\n```\n\n## 下一步\n\n- 了解[自定义评估指标](./custom-metrics.md)的实现方法\n- 查看[集成示例](./integrations/)了解与 LangChain、LangGraph 等框架的连接方式\n- 参考[贡献指南](./contributing.md)参与项目开发\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [模拟引擎](#page-simulation-engine), [评估系统](#page-evaluator)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/simulation_engine/simulator.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/simulator.py)\n- [arksim/evaluator/evaluator.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/evaluator.py)\n- [arksim/simulation_engine/entities.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/entities.py)\n- [arksim/evaluator/entities.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/entities.py)\n- [arksim/simulation_engine/tool_types.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n
\n\n# 系统架构\n\n## 概述\n\nArkSim 是一个基于 LLM 的多轮对话代理仿真与评估框架，旨在通过模拟真实用户与 Agent 之间的交互，自动评估 Agent 在各类场景下的表现。系统通过 YAML 配置文件定义测试场景和评估指标，支持自定义指标扩展和多种 Agent 接入方式。\n\n资料来源：[README.md]()\n\n## 核心架构组件\n\nArkSim 系统由三大核心模块组成：**仿真引擎（Simulation Engine）**、**评估器（Evaluator）** 和 **CLI 接口（Command Line Interface）**。这三个模块相互协作，共同完成从场景模拟到结果评估的完整流程。\n\n### 仿真引擎\n\n仿真引擎负责管理用户模拟、对话历史和与 Agent 的交互。核心组件包括：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| `Simulator` | 主控制器，协调模拟流程 | `arksim/simulation_engine/simulator.py` |\n| `ScenarioRunner` | 场景执行器 | `arksim/simulation_engine/simulator.py` |\n| `BaseAgent` | Agent 抽象基类 | `arksim/simulation_engine/agent/base.py` |\n| `UserSimulator` | 用户模拟器 | `arksim/simulation_engine/entities.py` |\n\n资料来源：[arksim/simulation_engine/simulator.py:1-100]()\n\n### 评估器\n\n评估器负责根据预定义指标对模拟结果进行评分，支持定量指标和定性指标两种评估方式：\n\n| 指标类型 | 描述 | 评分范围 |\n|----------|------|----------|\n| `QuantitativeMetric` | 定量指标，返回 0.0-1.0 分数 | 数值型 |\n| `QualitativeMetric` | 定性指标，提供详细文本分析 | 文本型 |\n\n资料来源：[arksim/evaluator/evaluator.py:1-80]()\n\n## 系统架构图\n\n```mermaid\ngraph TD\n A[配置文件 config.yaml] --> B[CLI 入口]\n B --> C[仿真引擎 Simulator]\n C --> D[场景加载器]\n C --> E[用户模拟器 UserSimulator]\n C --> F[Agent 连接器]\n \n E --> G[对话历史 ChatHistory]\n F --> G\n G --> H[对话记录数据]\n \n H --> I[评估器 Evaluator]\n I --> J[定量指标计算]\n I --> K[定性指标计算]\n \n J --> L[量化结果 QuantResult]\n K --> M[定性结果 QualResult]\n \n L --> N[HTML 报告生成]\n M --> N\n \n F --> O[Chat Completions API]\n F --> P[A2A 协议]\n F --> Q[自定义 Agent 类]\n```\n\n## 数据流与实体模型\n\n### 核心实体\n\n```mermaid\nclassDiagram\n class Scenario {\n +str id\n +str description\n +UserProfile user_profile\n +list~Turn~ turns\n +list~str~ knowledge_base\n }\n \n class UserProfile {\n +str id\n +dict attributes\n +str language\n }\n \n class Turn {\n +str user_query\n +str expected_behavior\n +str evaluation_criteria\n }\n \n class AgentResponse {\n +str content\n +list~ToolCall~ tool_calls\n }\n \n class ToolCall {\n +str id\n +str name\n +dict arguments\n +str result\n }\n \n Scenario --> UserProfile\n Scenario --> Turn\n Turn --> AgentResponse\n AgentResponse --> ToolCall\n```\n\n资料来源：[arksim/simulation_engine/entities.py:1-50]()\n\n### 评估结果实体\n\n| 实体 | 字段 | 说明 |\n|------|------|------|\n| `QuantResult` | score, reason, metadata | 定量评估结果，包含分数和理由 |\n| `QualResult` | assessment, recommendations | 定性评估结果，包含建议 |\n| `ScoreInput` | scenario, chat_history, metadata | 评分输入数据 |\n\n资料来源：[arksim/evaluator/entities.py:1-60]()\n\n## Agent 连接类型\n\nArkSim 支持多种 Agent 接入方式，便于与不同类型的 Agent 系统集成：\n\n| 类型 | 配置键 | 适用场景 | 源码位置 |\n|------|--------|----------|----------|\n| `custom` | `agent_type: custom` | 自定义 Python 类 | `arksim/simulation_engine/agent/base.py` |\n| `chat_completions` | `agent_type: chat_completions` | HTTP API 端点 | `arksim/cli.py` |\n| `a2a` | `agent_type: a2a` | Agent-to-Agent 协议 | `arksim/cli.py` |\n\n```python\n# 自定义 Agent 示例\nclass MyAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"unique-id\"\n \n async def execute(self, user_query: str, **kwargs) -> str | AgentResponse:\n return AgentResponse(content=\"response\", tool_calls=[])\n```\n\n资料来源：[arksim/simulation_engine/agent/base.py:1-30]()\n\n## 工具调用捕获机制\n\nArkSim 支持从 Agent 响应中捕获工具调用，以便评估工具使用的准确性：\n\n```python\nclass ToolCall(BaseModel):\n model_config = ConfigDict(extra=\"ignore\")\n \n id: str\n name: str\n arguments: dict[str, Any] = Field(default_factory=dict)\n result: str | None = None\n error: str | None = None\n source: ToolCallSource | None = None\n```\n\n工具调用来源包括：\n- `AgentResponse` 返回的显式工具调用\n- 通过 TracingProcessor 自动捕获的工具调用\n\n资料来源：[arksim/simulation_engine/tool_types.py:1-40]()\n\n## 配置系统\n\n### 配置文件结构\n\n```yaml\nagent_config:\n agent_type: custom # custom | chat_completions | a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n\nscenario_file: scenarios.json\n\nevaluator:\n metrics_to_run:\n - goal_completion\n - custom_metric_name\n custom_metrics_file_paths:\n - custom_metrics.py\n\ntrace_receiver:\n enabled: true\n wait_timeout: 5\n```\n\n### 自定义指标注册\n\n用户可通过以下步骤添加自定义指标：\n\n1. 创建指标类，继承 `QuantitativeMetric` 或 `QualitativeMetric`\n2. 实现 `evaluate()` 方法\n3. 在 `config.yaml` 中添加文件路径到 `custom_metrics_file_paths`\n\n```python\nfrom arksim.evaluator import QuantitativeMetric, ScoreInput\n\nclass MyMetric(QuantitativeMetric):\n name = \"my_custom_metric\"\n \n async def evaluate(self, input: ScoreInput) -> QuantResult:\n score = 1.0\n reason = \"评估理由\"\n return QuantResult(score=score, reason=reason, metadata={})\n```\n\n资料来源：[examples/customer-service/custom_metrics.py:1-40]()\n\n## 评估报告\n\n评估完成后，系统生成交互式 HTML 报告，包含以下内容：\n\n| 报告部分 | 内容 |\n|----------|------|\n| 摘要统计 | 平均分数、成功率、失败模式分布 |\n| 场景详情 | 每个场景的对话历史和评分详情 |\n| 工具调用 | Agent 调用的工具及结果 |\n| 失败分析 | 按类别归类的失败原因 |\n\n```html\n\n
\n
\n \n Goal Completion\n ${score}\n \n
${reason}
\n
\n
\n```\n\n资料来源：[arksim/utils/html_report/report_template.html:1-50]()\n\n## 工作流程\n\n```mermaid\ngraph LR\n A[加载配置] --> B[解析场景]\n B --> C[初始化 Agent]\n C --> D[逐轮模拟]\n D --> E{还有未完成轮次?}\n E -->|是| F[用户模拟器生成输入]\n F --> G[Agent 执行]\n G --> H[记录对话历史]\n H --> I[捕获工具调用]\n I --> D\n E -->|否| J[评估所有场景]\n J --> K[计算指标分数]\n K --> L[生成 HTML 报告]\n```\n\n### 分步执行模式\n\n系统支持将模拟和评估拆分为独立步骤执行：\n\n```bash\n# 步骤 1: 模拟\narksim simulate config_simulate.yaml\n\n# 步骤 2: 评估\narksim evaluate config_evaluate.yaml\n```\n\n这种模式允许：\n- 复用模拟结果进行多次评估\n- 独立调试模拟或评估阶段\n- 并行执行多个评估配置\n\n资料来源：[examples/customer-service/README.md]()\n\n## 扩展机制\n\n### 指标扩展\n\nArkSim 通过抽象基类提供指标扩展能力：\n\n```python\n# 定量指标\nclass QuantitativeMetric(ABC):\n name: str\n \n @abstractmethod\n async def evaluate(self, input: ScoreInput) -> QuantResult:\n pass\n\n# 定性指标\nclass QualitativeMetric(ABC):\n name: str\n \n @abstractmethod\n async def evaluate(self, input: ScoreInput) -> QualResult:\n pass\n```\n\n### Agent 扩展\n\n通过继承 `BaseAgent` 类并实现 `execute()` 方法，可以接入任何类型的 Agent 系统：\n\n```python\nclass CustomAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"custom-agent-id\"\n \n async def execute(self, user_query: str, **kwargs) -> str | AgentResponse:\n # 自定义 Agent 逻辑\n pass\n```\n\n## 技术栈\n\n| 层级 | 技术/库 | 用途 |\n|------|---------|------|\n| Web UI | Alpine.js, Tailwind CSS | 前端交互界面 |\n| 数据验证 | Pydantic | 数据模型定义 |\n| HTTP 客户端 | httpx | Agent API 调用 |\n| 命令行 | argparse | CLI 接口 |\n| 测试 | pytest | 单元测试 |\n\n资料来源：[arksim/ui/frontend/index.html:1-30](), [arksim/simulation_engine/tool_types.py:1-20]()\n\n## 相关文档\n\n- [快速开始指南](../getting-started)\n- [Agent 集成示例](../examples/integrations)\n- [自定义指标教程](../guides/custom-metrics)\n- [CLI 命令参考](../reference/cli)\n\n---\n\n\n\n## 模拟引擎\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [评估系统](#page-evaluator), [Agent类型与客户端](#page-agent-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/simulation_engine/simulator.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/simulator.py)\n- [arksim/simulation_engine/agent/base.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/base.py)\n- [arksim/simulation_engine/agent/factory.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/factory.py)\n- [arksim/simulation_engine/agent/response_parsers.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/response_parsers.py)\n- [arksim/simulation_engine/tool_types.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n
\n\n# 模拟引擎\n\n## 概述\n\n模拟引擎（Simulation Engine）是 ArkSim 的核心组件，负责在受控环境中自动执行 AI 代理的测试场景。引擎通过模拟真实用户对话流程，驱动代理执行并捕获其响应和工具调用，从而实现自动化质量评估。\n\n**核心功能：**\n- 多轮对话模拟\n- 工具调用捕获与记录\n- 路由上下文注入\n- 结构化响应解析\n- 评估指标计算\n\n**资料来源：** [README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n\n---\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph 模拟引擎核心\n SIM[模拟引擎 Simulator]\n AGENT[代理连接器 Agent Connectors]\n TOOL[工具类型系统]\n end\n \n subgraph 代理类型\n BASE[BaseAgent 自定义代理]\n CHAT[Chat Completions 端点]\n A2A[A2A 协议代理]\n end\n \n subgraph 数据模型\n TC[ToolCall 工具调用]\n AR[AgentResponse 代理响应]\n end\n \n SIM --> AGENT\n AGENT --> BASE\n AGENT --> CHAT\n AGENT --> A2A\n SIM --> TOOL\n TOOL --> TC\n BASE --> AR\n CHAT --> AR\n A2A --> AR\n```\n\n**资料来源：** [arksim/simulation_engine/agent/factory.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/factory.py)\n\n---\n\n## 代理连接器体系\n\n### BaseAgent 抽象基类\n\n所有自定义代理必须继承 `BaseAgent`，实现以下核心方法：\n\n| 方法 | 返回类型 | 说明 |\n|------|---------|------|\n| `get_chat_id()` | `str` | 返回会话唯一标识符 |\n| `execute(user_query, **kwargs)` | `str \\| AgentResponse` | 执行用户查询并返回响应 |\n\n```python\nfrom arksim.simulation_engine.agent.base import BaseAgent\nfrom arksim.simulation_engine.tool_types import AgentResponse\n\nclass MyAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"unique-id\"\n\n async def execute(self, user_query: str, **kwargs: object) -> str | AgentResponse:\n # 替换为您的代理逻辑\n return \"agent response\"\n```\n\n**资料来源：** [README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n\n### AgentResponse 数据结构\n\n`AgentResponse` 是代理执行后返回的结构化响应对象：\n\n```python\nclass AgentResponse(BaseModel):\n model_config = ConfigDict(extra=\"ignore\")\n \n content: str # 文本响应内容\n tool_calls: list[ToolCall] = Field(default_factory=list) # 工具调用列表\n```\n\n该模型使用 Pydantic 的 `extra=\"ignore\"` 配置，确保与未来版本的前向兼容性。\n\n**资料来源：** [arksim/simulation_engine/tool_types.py:32-41](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n\n---\n\n## 工具调用系统\n\n### ToolCall 模型\n\n`ToolCall` 记录单轮对话中观察到的工具/函数调用：\n\n```python\nclass ToolCall(BaseModel):\n model_config = ConfigDict(extra=\"ignore\")\n \n id: str # 调用唯一标识符\n name: str # 工具名称\n arguments: dict[str, Any] = Field(default_factory=dict) # 调用参数\n result: str | None = None # 调用结果\n error: str | None = None # 错误信息\n source: ToolCallSource | None = None # 调用来源\n```\n\n### ToolCallSource 枚举\n\n定义工具调用的来源类型：\n\n| 值 | 说明 |\n|---|------|\n| `AgentResponse` | 从标准响应中显式返回 |\n| `TracingProcessor` | 通过追踪处理器自动捕获 |\n\n**资料来源：** [arksim/simulation_engine/tool_types.py:15-30](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n\n---\n\n## 代理类型支持\n\n### 1. 自定义 Python 代理\n\n通过继承 `BaseAgent` 实现：\n\n```python\nclass MyAgent(BaseAgent):\n async def execute(self, user_query: str, **kwargs: object) -> str | AgentResponse:\n # 业务逻辑\n return AgentResponse(content=\"响应\", tool_calls=[...])\n```\n\n**资料来源：** [examples/customer-service/README.md](https://github.com/arklexai/arksim/blob/main/examples/customer-service/README.md)\n\n### 2. Chat Completions 端点\n\n通过 HTTP 调用外部服务：\n\n```yaml\nagent_config:\n agent_type: chat_completions\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n```\n\n### 3. A2A 协议代理\n\n支持 Agent-to-Agent 协议通信：\n\n```yaml\nagent_config:\n agent_type: a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:9999/agent\n```\n\n### 4. 追踪代理 (Traced Agent)\n\n通过 `ArksimTracingProcessor` 自动捕获工具调用，无需在 `AgentResponse` 中显式返回：\n\n```\n模拟器设置路由上下文 → agent.execute() 正常执行\n→ SDK 触发 TracingProcessor.on_span_end → arksim 捕获 → 评估器评分\n```\n\n**资料来源：** [examples/customer-service/README.md](https://github.com/arklexai/arksim/blob/main/examples/customer-service/README.md)\n\n---\n\n## 工作流程\n\n### 模拟执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户配置\n participant SIM as Simulator\n participant AGENT as Agent\n participant TRACE as Trace Receiver\n \n User->>SIM: 加载 config.yaml 和 scenarios.json\n SIM->>SIM: 解析测试场景\n loop 每轮对话\n SIM->>AGENT: 发送 user_query + 路由上下文\n AGENT->>AGENT: 执行代理逻辑\n AGENT-->>SIM: AgentResponse\n SIM->>TRACE: 捕获追踪数据\n TRACE-->>SIM: 工具调用列表\n SIM->>SIM: 记录对话历史\n end\n SIM-->>User: 生成 simulation.json\n```\n\n### 集成框架支持\n\nArkSim 提供与多种主流 AI 框架的集成示例：\n\n| 框架 | 示例路径 | 说明 |\n|-----|---------|------|\n| LangChain/LangGraph | `examples/integrations/langchain/` | 使用自定义代理连接器 |\n| Claude Agent SDK | `examples/integrations/claude-agent-sdk/` | Anthropic SDK 集成 |\n| AutoGen | `examples/integrations/autogen/` | Microsoft AutoGen 集成 |\n| CrewAI | `examples/integrations/crewai/` | CrewAI 框架集成 |\n| Pydantic AI | `examples/integrations/pydantic-ai/` | Pydantic AI 集成 |\n| Dify | `examples/integrations/dify/` | Dify 平台集成 |\n\n**资料来源：** [examples/integrations/langchain/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/langchain/README.md), [examples/integrations/claude-agent-sdk/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/claude-agent-sdk/README.md)\n\n---\n\n## 配置文件结构\n\n### 模拟配置 (config.yaml)\n\n```yaml\n# 模拟器设置\nsimulator:\n max_turns: 10\n timeout: 60\n\n# 代理配置\nagent_config:\n agent_type: custom # custom | chat_completions | a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000\n\n# 追踪接收器\ntrace_receiver:\n enabled: true\n wait_timeout: 5\n```\n\n### 场景文件 (scenarios.json)\n\n定义测试用例和预期行为：\n\n```json\n{\n \"scenarios\": [\n {\n \"id\": \"scenario-001\",\n \"name\": \"客户身份验证\",\n \"initial_context\": {...},\n \"expected_outcome\": {...}\n }\n ]\n}\n```\n\n**资料来源：** [examples/integrations/dify/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/dify/README.md)\n\n---\n\n## CLI 命令\n\n模拟引擎通过命令行接口操作：\n\n| 命令 | 说明 |\n|-----|------|\n| `arksim simulate-evaluate config.yaml` | 模拟和评估（一步完成） |\n| `arksim simulate config_simulate.yaml` | 仅运行模拟 |\n| `arksim evaluate config_evaluate.yaml` | 仅运行评估 |\n\n**资料来源：** [examples/customer-service/README.md](https://github.com/arklexai/arksim/blob/main/examples/customer-service/README.md)\n\n---\n\n## 模块加载机制\n\n模拟引擎使用专用模块加载器处理自定义代理：\n\n```python\n# arksim/utils/module_loader.py\n# 使用 UUID 生成唯一模块名避免冲突\nmodule_name = f\"_arksim_{uuid.uuid4().hex[:8]}_{path.stem}\"\nspec = importlib.util.spec_from_file_location(module_name, str(path))\n```\n\n**关键特性：**\n- 缓存机制避免重复加载\n- 唯一模块名支持多实例并发\n- 自动添加父目录到 `sys.path`\n\n**资料来源：** [arksim/utils/module_loader.py](https://github.com/arklexai/arksim/blob/main/arksim/utils/module_loader.py)\n\n---\n\n## 执行输出\n\n模拟完成后生成以下产物：\n\n| 文件 | 位置 | 说明 |\n|-----|------|------|\n| `simulation.json` | `./results/simulation/` | 完整对话历史和工具调用记录 |\n| 评估报告 | stdout | 每场景指标分数和失败分析 |\n\n**资料来源：** [examples/integrations/dify/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/dify/README.md)\n\n---\n\n## 前向兼容性\n\n模拟引擎的数据模型采用以下策略确保版本兼容性：\n\n```python\nmodel_config = ConfigDict(extra=\"ignore\")\n```\n\n此配置允许：\n- 旧版本代码加载新版本快照时不抛出 `ValidationError`\n- 新版本添加字段不会破坏旧版本解析\n\n**资料来源：** [arksim/simulation_engine/tool_types.py:19-21](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n\n---\n\n\n\n## 评估系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [模拟引擎](#page-simulation-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/evaluator/evaluator.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/evaluator.py)\n- [arksim/evaluator/evaluate.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/evaluate.py)\n- [arksim/evaluator/base_metric.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/base_metric.py)\n- [arksim/evaluator/builtin_metrics.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/builtin_metrics.py)\n- [arksim/evaluator/thresholds.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/thresholds.py)\n- [arksim/evaluator/error_detection.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/error_detection.py)\n- [arksim/evaluator/trajectory_matching.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/trajectory_matching.py)\n
\n\n# 评估系统\n\n## 概述\n\n评估系统（Evaluation System）是 ArkSim 的核心组件之一，负责对模拟对话进行质量评分和结果分析。该系统通过预定义的指标体系，从多个维度评估智能体（Agent）的表现，包括目标完成度、响应有效性、对话连贯性等。\n\n评估系统支持内置指标和自定义指标扩展，评估结果可生成详细的 HTML 报告，帮助开发者识别智能体的优势与不足。资料来源：[arksim/evaluator/evaluator.py:1-50]()\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[模拟对话数据] --> B[评估引擎]\n B --> C[内置指标]\n B --> D[自定义指标]\n C --> E[评分计算]\n D --> E\n E --> F[错误检测]\n E --> G[轨迹匹配]\n F --> H[最终报告]\n G --> H\n H --> I[HTML报告]\n H --> J[JSON结果]\n```\n\n### 核心模块\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| 评估引擎 | `evaluator.py` | 协调评估流程，汇总各指标结果 |\n| 评估执行 | `evaluate.py` | 处理单个对话的评分逻辑 |\n| 基础指标 | `base_metric.py` | 定义指标基类和通用接口 |\n| 内置指标 | `builtin_metrics.py` | 提供开箱即用的评估指标 |\n| 阈值管理 | `thresholds.py` | 管理评分阈值和判断标准 |\n| 错误检测 | `error_detection.py` | 识别对话中的错误模式 |\n| 轨迹匹配 | `trajectory_matching.py` | 对比预期与实际对话轨迹 |\n\n资料来源：[arksim/evaluator/base_metric.py:1-30]()\n\n## 指标体系\n\n### 指标类型\n\n评估系统采用双轨指标架构：\n\n#### 定量指标（QuantitativeMetric）\n\n定量指标返回数值型评分，范围通常为 0.0 到 1.0：\n\n```python\nclass QuantitativeMetric(Protocol):\n async def score(self, input: ScoreInput) -> QuantResult: ...\n```\n\n资料来源：[arksim/evaluator/base_metric.py:20-25]()\n\n#### 定性指标（QualitativeMetric）\n\n定性指标提供更详细的文本反馈和子项评分：\n\n```python\nclass QualitativeMetric(Protocol):\n async def score(self, input: ScoreInput) -> QualResult: ...\n```\n\n资料来源：[arksim/evaluator/base_metric.py:30-35]()\n\n### 评分输入\n\n所有指标共享统一的输入结构 `ScoreInput`，包含：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `scenario` | Scenario | 测试场景定义 |\n| `chat_history` | list[Turn] | 完整对话历史 |\n| `agent_response` | str | 智能体最终响应 |\n| `metadata` | dict | 额外元数据 |\n\n资料来源：[arksim/evaluator/base_metric.py:40-60]()\n\n## 内置指标\n\n### 目标完成度（Goal Completion）\n\n评估智能体是否完成了用户场景中设定的核心目标。系统根据场景定义的成功条件进行判断。\n\n### 最终分数（Final Score）\n\n综合评分，计算公式为：\n\n```\n最终分数 = 回合成功率 × 40% + 目标完成度 × 60%\n```\n\n资料来源：[arksim/utils/html_report/report_template.html:1-50]()\n\n### 其他内置指标\n\n内置指标还包括：\n\n- **Helpfulness**：响应有帮助程度\n- **Coherence**：对话连贯性\n- **Relevance**：响应相关性\n- **Safety**：安全性检查\n- **Turn Success Ratio**：单回合成功比例\n\n资料来源：[arksim/evaluator/builtin_metrics.py:1-100]()\n\n## 自定义指标\n\n### 实现自定义指标\n\n用户可以通过继承 `QuantitativeMetric` 或 `QualitativeMetric` 来创建自定义指标：\n\n```python\nfrom arksim.evaluator import (\n QualitativeMetric,\n QualResult,\n format_chat_history,\n)\n\nclass VerificationComplianceMetric(QualitativeMetric):\n async def score(self, input: ScoreInput) -> QualResult:\n # 实现评分逻辑\n return QualResult(\n score=score,\n reason=\"评估理由\"\n )\n```\n\n资料来源：[examples/customer-service/custom_metrics.py:1-50]()\n\n### 自定义指标配置\n\n1. 在 `custom_metrics/` 目录下创建指标文件\n2. 实现 `QuantitativeMetric` 或 `QualitativeMetric` 接口\n3. 返回 `QuantResult` 或 `QualResult`，包含 `score` 和 `reason`\n4. 在 `config.yaml` 的 `custom_metrics_file_paths` 中添加文件路径\n5. （可选）在 `metrics_to_run` 中指定要运行的指标\n\n资料来源：[examples/e-commerce/custom_metrics.py:1-80]()\n\n## 阈值管理\n\n### 阈值配置\n\n阈值系统根据评分结果判断对话状态：\n\n| 状态 | 条件 | 说明 |\n|------|------|------|\n| 成功（Done） | 最终分数 = 1.0 | 完全达标 |\n| 部分失败（Partial Failure） | 0 < 分数 < 1.0 | 部分达标 |\n| 完全失败（Failure） | 分数 = 0 | 完全未达标 |\n\n资料来源：[arksim/evaluator/thresholds.py:1-50]()\n\n### 阈值判断逻辑\n\n```mermaid\ngraph TD\n A[开始评估] --> B{分数 == 1.0?}\n B -->|是| C[状态: Done]\n B -->|否| D{分数 > 0?}\n D -->|是| E[状态: Partial Failure]\n D -->|否| F[状态: Failure]\n```\n\n## 错误检测\n\n### 错误模式识别\n\n错误检测模块分析对话历史，识别常见的失败模式：\n\n- **重复响应**：智能体重复相同或相似的回复\n- **信息缺失**：未提供必要的信息或答案\n- **行为错误**：执行了不正确的操作或判断\n- **上下文丢失**：未能保持对话上下文连贯性\n\n资料来源：[arksim/evaluator/error_detection.py:1-80]()\n\n### 错误分类\n\n评估报告会对检测到的错误进行分类，便于问题定位：\n\n| 错误类型 | 检测依据 |\n|----------|----------|\n| 重复响应 | 检测连续或间隔出现的相似回复 |\n| 缺少信息 | 关键场景信息未被提取或使用 |\n| 工具调用错误 | 工具参数或调用时机不当 |\n\n## 轨迹匹配\n\n### 功能概述\n\n轨迹匹配模块将实际对话轨迹与预期轨迹进行对比，评估智能体是否按照预期的路径执行。\n\n资料来源：[arksim/evaluator/trajectory_matching.py:1-60]()\n\n### 匹配算法\n\n```mermaid\ngraph LR\n A[预期轨迹] --> C[轨迹对比器]\n B[实际轨迹] --> C\n C --> D{匹配度计算}\n D -->|高| E[轨迹匹配成功]\n D -->|低| F[轨迹偏离]\n```\n\n## 报告生成\n\n### HTML 报告\n\n评估完成后，系统生成详细的 HTML 报告，包含：\n\n- **概览统计**：整体分数分布、通过率\n- **场景详情**：每个测试场景的详细评分\n- **对话回放**：完整的对话转录及评分标注\n- **错误分析**：失败模式汇总及建议\n\n资料来源：[arksim/utils/html_report/report_template.html:1-100]()\n\n### 报告数据结构\n\n```json\n{\n \"scenario_id\": \"scenario_001\",\n \"goal_completion_score\": 0.85,\n \"final_score\": 0.82,\n \"status\": \"partial_failure\",\n \"chat_history\": [...],\n \"metrics\": {\n \"goal_completion\": { \"score\": 0.85, \"reason\": \"...\" },\n \"turn_success_ratio\": { \"score\": 0.78, \"reason\": \"...\" }\n }\n}\n```\n\n## 配置使用\n\n### 命令行使用\n\n```bash\n# 模拟和评估一体化\narksim simulate-evaluate config.yaml\n\n# 分步执行\narksim simulate config_simulate.yaml\narksim evaluate config_evaluate.yaml\n```\n\n### YAML 配置\n\n```yaml\nevaluation:\n provider: openai\n model: gpt-4o-mini\n metrics_to_run:\n - goal_completion\n - turn_success_ratio\n - final_score\n custom_metrics_file_paths:\n - ./custom_metrics/metrics.py\n num_workers: auto\n report_html: true\n```\n\n资料来源：[examples/integrations/dify/README.md:1-30]()\n\n## 评估流程\n\n```mermaid\nsequenceDiagram\n participant S as 模拟器\n participant E as 评估引擎\n participant M as 指标计算\n participant R as 报告生成\n \n S->>E: 提交对话数据\n E->>M: 分发指标任务\n M-->>E: 逐项评分\n E->>E: 计算综合分数\n E->>E: 错误检测\n E->>E: 轨迹匹配\n E->>R: 生成报告\n R-->>用户: HTML报告 + 控制台输出\n```\n\n## 最佳实践\n\n### 指标设计建议\n\n1. **明确评分标准**：每个指标应有清晰的评分依据\n2. **合理分数区间**：定量指标建议使用 0.0-1.0 或 0-100\n3. **提供失败理由**：便于问题诊断和修复\n4. **避免指标耦合**：各指标应独立评估\n\n### 测试场景设计\n\n1. 覆盖正向和负向场景\n2. 包含边界条件和异常情况\n3. 设置明确的成功/失败标准\n4. 提供足够的上下文信息\n\n## 扩展指南\n\n### 添加新指标类型\n\n1. 在 `base_metric.py` 中定义指标接口\n2. 在 `builtin_metrics.py` 中实现默认逻辑\n3. 在 `evaluate.py` 中注册指标处理器\n\n### 集成外部评估服务\n\n```python\nclass ExternalEvaluator:\n async def score(self, input: ScoreInput) -> QuantResult:\n # 调用外部 API\n response = await external_api.evaluate(input)\n return QuantResult(score=response.score, reason=response.reason)\n```\n\n## 总结\n\n评估系统是 ArkSim 实现智能体质量验证的核心基础设施，通过模块化的指标体系、灵活的扩展机制和详细的报告输出，帮助开发者全面了解智能体的表现并进行针对性优化。系统设计遵循可扩展性和易用性原则，既支持开箱即用的内置功能，也支持用户根据业务需求定制专属评估指标。\n\n---\n\n\n\n## LLM提供者集成\n\n### 相关页面\n\n相关主题：[Agent类型与客户端](#page-agent-types), [配置管理](#page-configuration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/llms/chat/providers/openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/openai.py)\n- [arksim/llms/chat/providers/anthropic.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/anthropic.py)\n- [arksim/llms/chat/providers/google.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/google.py)\n- [arksim/llms/chat/providers/azure_openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/azure_openai.py)\n- [arksim/llms/chat/llm.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/llm.py)\n
\n\n# LLM提供者集成\n\n## 概述\n\nArkSim的LLM提供者集成模块为模拟器提供了连接各种大语言模型服务的能力。该模块采用统一抽象的架构设计，将不同LLM提供商的API差异封装在独立的提供者实现中，使上层业务逻辑无需关心底层具体使用的是哪家服务商。\n\nLLM提供者在ArkSim中扮演核心角色，主要用于：\n\n- **用户模拟器（User Simulator）**：基于真实用户行为生成自然对话\n- **评估器（Evaluator）**：分析对话质量并给出评分\n- **自定义代理连接**：支持通过LLM驱动自定义代理行为\n\n资料来源：[arksim/llms/chat/llm.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/llm.py)\n\n## 架构设计\n\n### 整体架构\n\nArkSim的LLM集成采用工厂模式与策略模式相结合的架构：\n\n```mermaid\ngraph TD\n A[调用方] --> B[LLM 抽象层]\n B --> C{Provider Factory}\n C --> D[OpenAI Provider]\n C --> E[Anthropic Provider]\n C --> F[Google Provider]\n C --> G[Azure OpenAI Provider]\n \n H[配置层] --> C\n H --> B\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| LLM 抽象类 | `arksim/llms/chat/llm.py` | 定义通用接口，封装请求/响应处理 |\n| OpenAI Provider | `arksim/llms/chat/providers/openai.py` | OpenAI API及兼容API实现 |\n| Anthropic Provider | `arksim/llms/chat/providers/anthropic.py` | Anthropic Claude API实现 |\n| Google Provider | `arksim/llms/chat/providers/google.py` | Google Gemini API实现 |\n| Azure OpenAI Provider | `arksim/llms/chat/providers/azure_openai.py` | Azure OpenAI服务实现 |\n\n资料来源：[arksim/llms/chat/providers/openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/openai.py)\n\n## 支持的LLM提供者\n\n### OpenAI\n\nOpenAI提供者是最常用的实现，支持标准的Chat Completions API格式。\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | string | 是 | OpenAI API密钥 |\n| `model` | string | 是 | 模型名称（如`gpt-4o`、`gpt-4o-mini`） |\n| `base_url` | string | 否 | API基础URL，支持自定义端点 |\n| `timeout` | int | 否 | 请求超时时间（秒） |\n| `max_retries` | int | 否 | 最大重试次数 |\n\n**使用示例：**\n\n```yaml\nllm:\n provider: openai\n api_key: ${OPENAI_API_KEY}\n model: gpt-4o\n base_url: https://api.openai.com/v1\n```\n\n资料来源：[arksim/llms/chat/providers/openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/openai.py)\n\n### Anthropic\n\nAnthropic提供者用于连接Claude系列模型，支持其特有的消息格式和工具调用能力。\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | string | 是 | Anthropic API密钥 |\n| `model` | string | 是 | 模型名称（如`claude-sonnet-4-20250514`） |\n| `base_url` | string | 否 | API基础URL |\n| `max_tokens` | int | 否 | 最大输出token数 |\n\n**使用示例：**\n\n```yaml\nllm:\n provider: anthropic\n api_key: ${ANTHROPIC_API_KEY}\n model: claude-sonnet-4-20250514\n```\n\n资料来源：[arksim/llms/chat/providers/anthropic.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/anthropic.py)\n\n### Google\n\nGoogle提供者支持Gemini系列模型，适用于需要多模态能力的场景。\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | string | 是 | Google API密钥 |\n| `model` | string | 是 | 模型名称（如`gemini-2.0-flash`） |\n| `base_url` | string | 否 | API基础URL |\n\n资料来源：[arksim/llms/chat/providers/google.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/google.py)\n\n### Azure OpenAI\n\nAzure OpenAI提供者支持企业级部署场景，兼容OpenAI API格式的同时提供Azure特有的安全和管理功能。\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | string | 是 | Azure API密钥 |\n| `endpoint` | string | 是 | Azure端点URL |\n| `api_version` | string | 是 | API版本（如`2024-02-01`） |\n| `azure_deployment` | string | 是 | 部署名称 |\n\n**使用示例：**\n\n```yaml\nllm:\n provider: azure_openai\n api_key: ${AZURE_OPENAI_API_KEY}\n endpoint: https://your-resource.openai.azure.com\n api_version: \"2024-02-01\"\n azure_deployment: gpt-4o\n```\n\n资料来源：[arksim/llms/chat/providers/azure_openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/azure_openai.py)\n\n## 配置管理\n\n### 环境变量注入\n\nArkSim支持通过环境变量安全地配置敏感信息，避免在配置文件中明文存储密钥。\n\n```yaml\nllm:\n provider: openai\n api_key: ${OPENAI_API_KEY} # 从环境变量读取\n```\n\n### 配置文件结构\n\n完整的模拟器配置通常包含LLM配置和应用配置：\n\n```yaml\nagent_config:\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n\nuser_simulator:\n llm:\n provider: openai\n api_key: ${OPENAI_API_KEY}\n model: gpt-4o\n\nevaluator:\n llm:\n provider: anthropic\n api_key: ${ANTHROPIC_API_KEY}\n model: claude-sonnet-4-20250514\n```\n\n资料来源：[arksim/llms/chat/llm.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/llm.py)\n\n## 请求处理流程\n\n### 统一请求接口\n\n```mermaid\nsequenceDiagram\n participant 调用方\n participant LLM抽象层\n participant Provider\n participant 外部API\n \n 调用方->>LLM抽象层: send_messages(messages, options)\n LLM抽象层->>Provider: send(messages, config)\n Provider->>外部API: HTTP POST\n 外部API-->>Provider: Response\n Provider-->>LLM抽象层: 标准化响应\n LLM抽象层-->>调用方: 返回结果\n```\n\n### 错误处理策略\n\nLLM提供者实现了统一的错误处理机制：\n\n1. **网络错误**：自动重试（可配置重试次数）\n2. **速率限制**：指数退避策略\n3. **认证错误**：抛出明确的认证异常\n4. **模型不可用**：返回友好的错误提示\n\n资料来源：[arksim/llms/chat/providers/openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/openai.py)\n\n## 在模拟器中的使用\n\n### 用户模拟器集成\n\n用户模拟器是LLM提供者的主要消费者之一，它使用LLM来生成符合用户画像的对话行为：\n\n```python\nclass UserSimulator:\n def __init__(self, llm_config: dict):\n self.llm = create_llm(llm_config)\n \n async def generate_response(\n self, \n context: dict,\n user_profile: dict\n ) -> str:\n prompt = self._build_prompt(context, user_profile)\n response = await self.llm.chat([{\"role\": \"user\", \"content\": prompt}])\n return response.content\n```\n\n### 评估器集成\n\n评估器使用独立的LLM实例来分析对话质量：\n\n```python\nclass Evaluator:\n def __init__(self, llm_config: dict):\n self.llm = create_llm(llm_config)\n \n async def evaluate(self, conversation: list) -> dict:\n analysis_prompt = self._build_analysis_prompt(conversation)\n result = await self.llm.chat([{\"role\": \"user\", \"content\": analysis_prompt}])\n return self._parse_result(result)\n```\n\n资料来源：[arksim/llms/chat/llm.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/llm.py)\n\n## 扩展自定义提供者\n\n如需集成其他LLM提供者，可以继承基础Provider类：\n\n```python\nfrom arksim.llms.chat.providers.base import BaseProvider\n\nclass CustomProvider(BaseProvider):\n async def chat(self, messages: list, **kwargs) -> ChatResponse:\n # 实现自定义逻辑\n pass\n \n async def completion(self, prompt: str, **kwargs) -> str:\n # 实现自定义逻辑\n pass\n```\n\n注册新提供者只需在Provider工厂中添加对应的创建逻辑即可。\n\n## 最佳实践\n\n### 密钥管理\n\n- 始终使用环境变量存储API密钥\n- 不要将包含密钥的配置文件提交到版本控制系统\n- 使用`.env`文件配合`.gitignore`排除\n\n### 成本控制\n\n- 选择合适的模型大小，避免过度使用高端模型\n- 配置适当的`max_tokens`限制\n- 使用流式响应处理长对话\n\n### 性能优化\n\n- 为长期运行的模拟任务复用LLM实例\n- 合理设置超时时间和重试策略\n- 考虑使用异步调用提高并发能力\n\n## 相关文档\n\n- [CLI命令行工具](../cli.md)\n- [模拟器配置指南](../configuration.md)\n- [自定义代理连接](../custom-agent.md)\n- [评估指标说明](../evaluation-metrics.md)\n\n---\n\n\n\n## Agent类型与客户端\n\n### 相关页面\n\n相关主题：[LLM提供者集成](#page-llm-providers), [配置管理](#page-configuration), [模拟引擎](#page-simulation-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/simulation_engine/agent/clients/chat_completions.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/clients/chat_completions.py)\n- [arksim/simulation_engine/agent/clients/a2a.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/clients/a2a.py)\n- [arksim/simulation_engine/agent/clients/custom.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/clients/custom.py)\n- [arksim/simulation_engine/agent/base.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/base.py)\n
\n\n# Agent类型与客户端\n\n## 概述\n\nArkSim 支持多种 Agent 连接方式，允许用户将不同类型的 AI Agent 接入仿真评估框架。系统通过统一的抽象层，支持自定义 Python 类、Chat Completions API、A2A 协议等多种接入方式。\n\n核心抽象由 `BaseAgent` 基类定义，所有 Agent 实现必须继承该类并实现核心接口方法。\n\n## Agent 类型架构\n\n```mermaid\ngraph TD\n subgraph Agent类型\n Custom[自定义Python类
custom]\n ChatCompletions[Chat Completions API
chat_completions]\n A2A[A2A协议
a2a]\n end\n \n subgraph 核心抽象\n Base[BaseAgent]\n Response[AgentResponse]\n end\n \n Custom --> Base\n ChatCompletions --> Base\n A2A --> Base\n \n Base --> Response\n```\n\n## BaseAgent 抽象基类\n\n`BaseAgent` 是所有 Agent 实现的基础抽象类，定义了 Agent 必须实现的接口规范。\n\n### 核心方法\n\n| 方法名 | 返回类型 | 说明 |\n|--------|----------|------|\n| `get_chat_id()` | `str` | 获取会话唯一标识符 |\n| `execute()` | `str \\| AgentResponse` | 执行用户查询，返回响应内容 |\n\n### AgentResponse 数据结构\n\n用于封装包含工具调用的复杂响应：\n\n```python\nclass AgentResponse(NamedTuple):\n message: str # 助手回复文本\n tool_calls: list[ToolCall] | None # 工具调用列表（可选）\n error: str | None = None # 错误信息（可选）\n```\n\n资料来源：[arksim/simulation_engine/agent/base.py:1-50]()\n\n### 自定义 Agent 实现示例\n\n```python\nfrom arksim.simulation_engine.agent.base import BaseAgent\nfrom arksim.simulation_engine.tool_types import AgentResponse\n\nclass MyAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"unique-id\"\n\n async def execute(self, user_query: str, **kwargs: object) -> str | AgentResponse:\n # 替换为你的 Agent 逻辑\n return \"agent response\"\n```\n\n资料来源：[README.md:1-100]()\n\n## Chat Completions 客户端\n\n`ChatCompletionsAgent` 用于连接支持 OpenAI 兼容 Chat Completions API 的 HTTP 端点。\n\n### 配置参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `endpoint` | `str` | 是 | API 端点 URL，如 `http://localhost:8000/v1/chat/completions` |\n| `api_key` | `str` | 否 | API 密钥认证 |\n| `model` | `str` | 否 | 模型名称 |\n| `timeout` | `int` | 否 | 请求超时时间（秒） |\n| `extra_headers` | `dict` | 否 | 额外 HTTP 请求头 |\n| `extra_body` | `dict` | 否 | 额外请求体参数 |\n\n### YAML 配置示例\n\n```yaml\nagent_config:\n agent_type: chat_completions\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n timeout: 60\n```\n\n### 工作流程\n\n```mermaid\nsequenceDiagram\n participant Simulator\n participant ChatCompletionsClient\n participant HTTPEndpoint\n \n Simulator->>ChatCompletionsClient: execute(user_query)\n ChatCompletionsClient->>HTTPEndpoint: POST /v1/chat/completions\n HTTPEndpoint-->>ChatCompletionsClient: Chat Completion Response\n ChatCompletionsClient-->>Simulator: str | AgentResponse\n```\n\n资料来源：[arksim/simulation_engine/agent/clients/chat_completions.py:1-100]()\n\n## A2A 协议客户端\n\n`A2AAgent` 实现 Agent-to-Agent 协议客户端，用于与支持 A2A 规范的远程 Agent 通信。\n\n### 协议特性\n\n- 支持标准 A2A 协议端点\n- 自动处理 JSON-RPC 格式消息\n- 会话状态管理\n\n### 配置参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `endpoint` | `str` | 是 | A2A Agent 端点 URL，如 `http://localhost:9999/agent` |\n| `agent_id` | `str` | 否 | Agent 标识符 |\n| `timeout` | `int` | 否 | 请求超时时间（秒） |\n\n### YAML 配置示例\n\n```yaml\nagent_config:\n agent_type: a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:9999/agent\n```\n\n资料来源：[arksim/simulation_engine/agent/clients/a2a.py:1-100]()\n\n## 自定义 Agent 客户端\n\n`CustomAgent` 允许用户通过继承 `BaseAgent` 实现自定义逻辑，适用于本地运行的 Agent 或需要深度定制的场景。\n\n### 初始化选项\n\n通过 `arksim init` 命令可自动生成模板：\n\n```bash\narksim init --agent-type custom --force\n```\n\n### 工具调用支持\n\n自定义 Agent 可返回 `AgentResponse` 包含工具调用信息：\n\n```python\nfrom arksim.simulation_engine.tool_types import ToolCall, AgentResponse\n\nasync def execute(self, user_query: str, **kwargs) -> AgentResponse:\n tool_calls = [\n ToolCall(\n id=\"call_1\",\n name=\"get_weather\",\n arguments={\"location\": \"北京\"}\n )\n ]\n return AgentResponse(\n message=\"正在查询天气...\",\n tool_calls=tool_calls\n )\n```\n\n### 追踪集成\n\n支持通过 `ArksimTracingProcessor` 自动捕获工具调用：\n\n> Simulator 设置路由上下文 -> agent.execute() 正常运行 -> SDK 触发 TracingProcessor.on_span_end -> arksim 捕获 -> 评估器评分\n\n资料来源：[arksim/simulation_engine/agent/clients/custom.py:1-100]()\n\n## Agent 类型对比\n\n| 特性 | custom | chat_completions | a2a |\n|------|--------|------------------|-----|\n| 实现方式 | Python 类继承 | HTTP API 调用 | HTTP 协议 |\n| 本地/远程 | 均可 | 远程 | 远程 |\n| 工具调用捕获 | AgentResponse / TracingProcessor | 自动解析 | 自动解析 |\n| 配置复杂度 | 中 | 低 | 低 |\n| 适用场景 | 深度定制、本地 Agent | 标准 API 服务 | A2A 协议 Agent |\n\n## 命令行工具支持\n\n### 初始化命令\n\n```bash\narksim init --agent-type [--force]\n```\n\n支持的 `--agent-type` 选项：\n- `custom`：生成 Python 代理文件（无需服务器）\n- `chat_completions`：HTTP 端点\n- `a2a`：Agent-to-Agent 协议\n\n### CLI 参数说明\n\n| 参数 | 说明 |\n|------|------|\n| `--agent-type` | Agent 连接类型，默认 `custom` |\n| `--force` | 覆盖已存在的文件 |\n\n资料来源：[arksim/cli.py:1-100]()\n\n## 集成示例\n\nArkSim 提供了多种集成示例，演示如何连接不同类型的 Agent：\n\n| 集成项目 | Agent 类型 | 说明 |\n|----------|------------|------|\n| `langchain` | Custom | LangChain/LangGraph 集成 |\n| `langgraph` | Custom | LangGraph 专用集成 |\n| `claude-agent-sdk` | Custom | Claude Agent SDK 集成 |\n| `autogen` | Custom | Microsoft AutoGen 集成 |\n| `rasa` | Chat Completions | Rasa Pro 集成 |\n| `dify` | Custom | Dify 平台集成 |\n| `openclaw` | Chat Completions | OpenClaw 网关集成 |\n\n运行任意集成示例：\n\n```bash\ncd examples/integrations/\narksim simulate-evaluate config.yaml\n```\n\n资料来源：[examples/integrations/langchain/README.md:1-50]()\n资料来源：[examples/integrations/rasa/README.md:1-80]()\n\n## 最佳实践\n\n1. **选择合适的 Agent 类型**：优先使用 `chat_completions` 或 `a2a`，仅在需要深度定制时使用 `custom`\n2. **工具调用返回规范**：自定义 Agent 应返回 `AgentResponse` 包含 `tool_calls` 以支持完整评估\n3. **错误处理**：确保 `execute()` 方法妥善处理异常，返回有意义的错误信息\n4. **会话标识**：实现正确的 `get_chat_id()` 确保多会话场景正确追踪\n\n---\n\n\n\n## 配置管理\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [场景定义与管理](#page-scenarios), [Agent类型与客户端](#page-agent-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/config.yaml](https://github.com/arklexai/arksim/blob/main/arksim/config.yaml)\n- [arksim/config_evaluate.yaml](https://github.com/arklexai/arksim/blob/main/arksim/config_evaluate.yaml)\n- [arksim/config_simulate.yaml](https://github.com/arklexai/arksim/blob/main/arksim/config_simulate.yaml)\n- [arksim/config/types.py](https://github.com/arklexai/arksim/blob/main/arksim/config/types.py)\n- [arksim/config/core/agent.py](https://github.com/arklexai/arksim/blob/main/arksim/config/core/agent.py)\n- [arksim/config/utils.py](https://github.com/arklexai/arksim/blob/main/arksim/config/utils.py)\n
\n\n# 配置管理\n\n## 概述\n\nArkSim 的配置管理系统负责定义仿真和评估流程的所有参数，包括代理连接方式、场景文件路径、指标配置、API 端点设置等。该系统采用 YAML 格式的配置文件，支持三种主要运行模式：联合仿真评估、单独仿真和单独评估。配置系统通过 Pydantic 模型实现类型安全的数据验证，确保配置文件的正确性和一致性。\n\nArkSim 的配置架构设计遵循模块化原则，将不同功能领域的配置参数分离到独立的核心模块中。这种设计使得配置管理更加清晰，便于维护和扩展。配置系统支持多种代理类型，包括自定义 Python 类、Chat Completions 接口、A2A 协议等，每种代理类型都有其专属的配置结构。\n\n## 配置架构\n\n### 模块结构\n\nArkSim 的配置系统位于 `arksim/config/` 目录下，采用分层架构设计。核心类型定义集中在 `types.py` 中，提供基础数据模型；代理相关配置在 `core/agent.py` 中定义；通用工具函数位于 `utils.py`。\n\n```mermaid\ngraph TD\n A[config.yaml] --> B[config/types.py - 基础类型]\n A --> C[config/core/agent.py - 代理配置]\n A --> D[config/utils.py - 工具函数]\n B --> E[ConfigLoader]\n C --> F[AgentConfig]\n D --> G[YAML加载和验证]\n```\n\n### 配置加载流程\n\n配置系统通过统一的加载器处理 YAML 配置文件，加载过程包括文件解析、类型验证和默认值填充三个阶段。系统首先读取 YAML 文件内容，然后根据配置类型选择对应的 Pydantic 模型进行数据验证，最后将验证通过的配置对象传递给相应的组件使用。\n\n## 配置文件类型\n\nArkSim 支持三种主要的配置文件类型，分别用于不同的运行场景：\n\n| 配置文件 | 用途 | 关键参数 |\n|---------|------|---------|\n| `config.yaml` | 联合仿真评估 | agent_config、scenarios、metrics |\n| `config_simulate.yaml` | 独立仿真 | agent_config、scenarios |\n| `config_evaluate.yaml` | 独立评估 | agent_config、scenarios_results |\n\n### 联合配置文件 (config.yaml)\n\n完整的仿真评估配置包含所有必要的参数，适用于一次性执行仿真和评估流程。配置文件中需要指定代理设置、场景定义、评估指标和可选的自定义指标。\n\n### 仿真配置文件 (config_simulate.yaml)\n\n仅包含仿真所需的参数，用于生成对话数据而不执行评估。该配置文件适用于调试仿真逻辑或生成特定格式的对话记录。\n\n### 评估配置文件 (config_evaluate.yaml)\n\n仅包含评估所需的参数，用于对已存在的仿真结果进行评分分析。当需要使用不同的评估指标重新分析历史仿真数据时，此配置非常有用。\n\n## 代理配置\n\n代理配置是 ArkSim 配置系统的核心部分，定义了如何连接和交互目标 AI 代理。系统支持多种代理类型，每种类型具有不同的配置结构。\n\n### 代理类型\n\nArkSim 支持以下代理类型：\n\n| 代理类型 | 标识符 | 说明 |\n|---------|--------|------|\n| 自定义 Python 类 | `custom` | 用户实现的 BaseAgent 子类 |\n| Chat Completions | `chat_completions` | OpenAI 风格的 HTTP 接口 |\n| A2A 协议 | `a2a` | Agent-to-Agent 通信协议 |\n\n### 自定义代理配置\n\n自定义代理需要通过 `agent_type: custom` 指定类型，并提供 Python 模块路径和类名：\n\n```yaml\nagent_config:\n agent_type: custom\n agent_name: my-agent\n module: my_agent\n class_name: MyAgent\n```\n\n### Chat Completions 配置\n\nChat Completions 类型代理通过 HTTP 接口调用，需要配置服务端点：\n\n```yaml\nagent_config:\n agent_type: chat_completions\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n```\n\n资料来源：[README.md]()\n\n### A2A 协议配置\n\nA2A 协议代理同样使用 HTTP 接口，但使用不同的端点路径：\n\n```yaml\nagent_config:\n agent_type: a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:9999/agent\n```\n\n资料来源：[README.md]()\n\n## 场景配置\n\n场景配置定义仿真测试的具体案例，包括用户画像、初始知识状态和预期目标。场景以 JSON 格式存储，通过配置文件中的 `scenarios` 参数引用。\n\n### 场景文件结构\n\n场景文件通常命名为 `scenarios.json`，包含多个测试场景的数组，每个场景定义一个完整的用户交互测试用例。\n\n### 场景加载\n\nArkSim 支持从指定路径加载场景文件：\n\n```yaml\nscenarios: /path/to/scenarios.json\n```\n\nUI 界面提供了场景文件路径输入和浏览功能，支持即时验证文件有效性。\n\n## 指标配置\n\n### 定量指标\n\n定量指标返回 0.0 到 1.0 之间的数值评分，用于衡量代理行为的可量化方面。系统内置多种定量指标，也可通过自定义指标扩展。\n\n### 定性指标\n\n定性指标返回分类标签，如 \"compliant\"、\"flagged\"、\"pass\"、\"fail\" 等。系统根据预设的标签集合判断指标情感方向（正面/负面/中性），用于生成可视化展示。\n\n### 自定义指标\n\n用户可以在 `tests/arksim/custom_metrics/` 目录下创建自定义指标文件，并在配置中引用：\n\n```yaml\ncustom_metrics_file_paths:\n - tests/arksim/custom_metrics/my_metric.py\n\nmetrics_to_run:\n - verification_compliance\n - my_custom_metric\n```\n\n资料来源：[examples/customer-service/custom_metrics.py]()\n\n## 追踪配置\n\nArkSim 支持通过追踪机制自动捕获代理的工具调用，这对于无法直接获取工具调用数据的代理特别有用。\n\n### 追踪接收器配置\n\n```yaml\ntrace_receiver:\n enabled: true\n wait_timeout: 5\n```\n\n当 `trace_receiver.enabled` 设为 `true` 时，系统启用追踪接收器等待模式；`wait_timeout` 定义最大等待时间（秒）。\n\n### 追踪工作流程\n\n```mermaid\ngraph LR\n A[Simulator设置路由上下文] --> B[Agent执行]\n B --> C[SDK触发TracingProcessor]\n C --> D[on_span_end回调]\n D --> E[ArkSim捕获工具调用]\n E --> F[Evaluator评分]\n```\n\n资料来源：[examples/customer-service/README.md]()\n\n## 配置工具函数\n\nArkSim 提供了配置相关的工具函数用于处理 YAML 文件加载、配置合并和参数验证。这些函数位于 `arksim/config/utils.py`，被配置加载器和各组件广泛使用。\n\n### 配置验证\n\n系统通过 Pydantic 模型自动验证配置参数的类型和取值范围，确保配置文件符合预期格式。验证失败时返回详细的错误信息，指出具体的配置项和问题原因。\n\n## 使用示例\n\n### 命令行使用\n\n```bash\n# 联合仿真评估\narksim simulate-evaluate config.yaml\n\n# 单独仿真\narksim simulate config_simulate.yaml\n\n# 单独评估\narksim evaluate config_evaluate.yaml\n```\n\n### Python 脚本使用\n\n```python\nfrom arksim.config.types import Config\nfrom arksim.config.utils import load_config\n\n# 加载配置文件\nconfig = load_config(\"config.yaml\")\n\n# 使用配置执行仿真\nsimulator = Simulator(config)\nresults = await simulator.run()\n```\n\n## 最佳实践\n\n1. **分离配置策略**：对于频繁修改的参数（如 API 端点），建议使用环境变量引用而非硬编码\n2. **场景复用**：将通用场景定义提取为模板，减少重复配置\n3. **自定义指标模块化**：将自定义指标组织在独立目录，便于版本管理和共享\n4. **配置版本控制**：在配置文件中添加注释说明版本和变更历史\n5. **测试配置隔离**：为测试环境创建独立的配置文件，避免影响生产配置\n\n## 相关文件索引\n\n| 文件路径 | 功能描述 |\n|---------|---------|\n| `arksim/config/types.py` | 配置数据模型和类型定义 |\n| `arksim/config/core/agent.py` | 代理配置核心逻辑 |\n| `arksim/config/utils.py` | 配置加载和验证工具 |\n| `examples/customer-service/config.yaml` | 完整配置示例 |\n| `examples/integrations/*/config.yaml` | 各集成场景配置参考 |\n\n---\n\n\n\n## 场景定义与管理\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [配置管理](#page-configuration), [模拟引擎](#page-simulation-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/scenario/entities.py](https://github.com/arklexai/arksim/blob/main/arksim/scenario/entities.py)\n- [arksim/templates/scenarios.json](https://github.com/arklexai/arksim/blob/main/arksim/templates/scenarios.json)\n- [examples/e-commerce/scenarios.json](https://github.com/arklexai/arksim/blob/main/examples/e-commerce/scenarios.json)\n- [examples/customer-service/scenarios.json](https://github.com/arklexai/arksim/blob/main/examples/customer-service/scenarios.json)\n- [arksim/simulation_engine/entities.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/entities.py)\n
\n\n# 场景定义与管理\n\n## 概述\n\n场景（Scenario）是 ArkSim 仿真评估系统的核心抽象单元，用于定义模拟用户与智能体之间的交互测试用例。每个场景包含用户画像、背景知识、对话目标等关键信息，模拟器基于这些场景生成多轮对话，评估器则根据对话结果计算各项质量指标。\n\n场景定义采用 JSON 格式存储在 `scenarios.json` 文件中，支持批量定义多个测试场景。系统默认每个场景生成 5 次独立对话（可配置），以统计学方式验证智能体行为的一致性和可靠性。\n\n资料来源：[arksim/simulation_engine/entities.py:1-50]()\n\n## 场景数据模型\n\n### 核心场景实体\n\n场景实体定义了测试用例的完整结构，包含用户模拟所需的所有信息：\n\n```json\n{\n \"scenario_id\": \"unique-scenario-identifier\",\n \"user_profile\": {\n \"name\": \"张三\",\n \"age\": 35,\n \"occupation\": \"工程师\",\n \"personality\": \"direct_and_patient\"\n },\n \"knowledge\": {\n \"account_type\": \"高级会员\",\n \"subscription_date\": \"2023-01-15\"\n },\n \"goal\": \"取消当前的订阅服务\",\n \"expected_actions\": [\"verify_identity\", \"confirm_cancellation\", \"offer_alternative\"],\n \"success_criteria\": {\n \"min_score\": 0.8,\n \"required_steps\": [\"身份验证\", \"确认取消\"]\n }\n}\n```\n\n资料来源：[arksim/templates/scenarios.json]()\n\n### 场景属性说明\n\n| 属性 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| `scenario_id` | string | 是 | 场景唯一标识符，用于结果关联 |\n| `user_profile` | object | 是 | 模拟用户的人口统计特征和性格属性 |\n| `knowledge` | object | 是 | 用户知道的背景信息，用于生成自然对话 |\n| `goal` | string | 是 | 用户想要达成的核心目标 |\n| `expected_actions` | array | 否 | 期望智能体执行的关键动作序列 |\n| `success_criteria` | object | 否 | 成功评判的详细标准 |\n\n资料来源：[arksim/scenario/entities.py]()\n\n## 场景结构详解\n\n### 用户画像（User Profile）\n\n用户画像定义了模拟用户的身份特征，影响对话生成的自然度和多样性：\n\n```json\n{\n \"user_profile\": {\n \"name\": \"李明\",\n \"age\": 28,\n \"occupation\": \"软件工程师\",\n \"personality\": \"technical_and_direct\",\n \"communication_style\": \"concise\",\n \"language\": \"中文\"\n }\n}\n```\n\n用户画像支持的性格类型包括：`direct_and_patient`（直接且有耐心）、`technical_and_direct`（技术型直接）、`emotional`（情绪化）、`friendly_chatty`（友好健谈）等。不同性格会影响模拟用户的措辞风格和对话策略。\n\n资料来源：[examples/customer-service/scenarios.json]()\n\n### 背景知识（Knowledge）\n\n背景知识定义用户角色已知的信息，这些信息在对话开始时存在于用户脑海中，但不会主动透露给智能体：\n\n```json\n{\n \"knowledge\": {\n \"account_id\": \"ACC-2024-001\",\n \"account_type\": \"企业版\",\n \"subscription_plan\": \"年付\",\n \"billing_cycle\": \"monthly\",\n \"payment_method\": \"信用卡\",\n \"registered_email\": \"li@example.com\"\n }\n}\n```\n\n知识库中的信息可被智能体通过询问获取，用于验证对话上下文的一致性。\n\n资料来源：[arksim/templates/scenarios.json]()\n\n### 对话目标（Goal）\n\n目标定义模拟用户希望达成的最终结果，是评估目标完成度的主要依据：\n\n```json\n{\n \"goal\": \"将当前套餐从企业版降级为标准版\",\n \"goal_type\": \"service_change\",\n \"constraints\": [\n \"希望在月底前生效\",\n \"不接受销售推销\"\n ]\n}\n```\n\n资料来源：[examples/e-commerce/scenarios.json]()\n\n## 场景管理工作流\n\n### 场景生命周期\n\n```mermaid\ngraph TD\n A[创建 scenarios.json] --> B[场景加载与解析]\n B --> C{语法验证}\n C -->|通过| D[场景预处理]\n C -->|失败| E[返回错误信息]\n D --> F[模拟用户生成]\n F --> G[多轮对话执行]\n G --> H[结果存储]\n H --> I[评估计分]\n I --> J[生成报告]\n```\n\n场景管理遵循标准的三阶段流程：加载验证阶段、模拟执行阶段、评估报告阶段。每个阶段都有明确的输入输出和错误处理机制。\n\n资料来源：[arksim/simulation_engine/entities.py:50-100]()\n\n### 场景配置参数\n\n模拟器通过 `SimulationConfig` 类管理场景执行的全局参数：\n\n| 参数 | 默认值 | 描述 |\n|------|--------|------|\n| `scenarios_file` | - | 场景文件路径（必需） |\n| `num_conversations_per_scenario` | 5 | 每个场景的对话轮次 |\n| `max_turns` | 5 | 单次对话的最大轮数 |\n| `num_workers` | 50 | 并行工作线程数 |\n| `model` | gpt-4o | 用于用户模拟的LLM模型 |\n| `provider` | openai | LLM提供商 |\n\n资料来源：[arksim/simulation_engine/entities.py:20-45]()\n\n### 场景文件验证\n\n系统对场景文件进行多层次验证：\n\n1. **语法验证**：JSON 格式正确性检查\n2. **必填字段验证**：确认 `scenario_id`、`user_profile`、`goal` 等必填字段存在\n3. **类型验证**：各字段类型符合数据模型定义\n4. **一致性验证**：检查 `expected_actions` 中引用的动作是否在知识库中有对应定义\n\n资料来源：[arksim/scenario/entities.py]()\n\n## 场景与评估集成\n\n### 评估指标计算\n\n场景执行完成后，系统根据对话内容计算多维度评估指标：\n\n```json\n{\n \"goal_completion_score\": 0.85,\n \"goal_completion_reason\": \"用户成功取消订阅，但未提供取消确认邮件\",\n \"turn_success_ratio\": 0.92,\n \"final_score\": 0.88,\n \"status\": \"done\",\n \"scores\": [\n {\n \"name\": \"identity_verification\",\n \"value\": 1.0,\n \"reason\": \"正确执行了身份验证流程\"\n }\n ]\n}\n```\n\n评分规则：\n- `final_score = turn_success_ratio × 0.4 + goal_completion_score × 0.6`\n- 状态判定：`done`（1.0）、`partial_failure`（≥0.6）、`failed`（<0.6）\n\n资料来源：[arksim/utils/html_report/report_template.html:80-120]()\n\n### 自定义指标扩展\n\nArkSim 支持通过 `custom_metrics.py` 添加领域特定评估指标：\n\n```python\nclass VerificationComplianceSchema(BaseModel):\n identity_verification: float # 0.0-1.0\n action_gating: float # 0.0-1.0\n reason: str\n```\n\n自定义指标需要实现 `QuantitativeMetric` 或 `QualitativeMetric` 接口，并在 `config.yaml` 中引用。\n\n资料来源：[examples/customer-service/custom_metrics.py]()\n\n## 场景文件最佳实践\n\n### 目录组织结构\n\n建议的场景文件组织方式：\n\n```\nproject/\n├── config.yaml # 仿真评估配置\n├── scenarios.json # 场景定义文件\n├── custom_metrics/ # 自定义指标目录\n│ └── quality_metrics.py\n└── results/ # 输出结果目录\n └── simulation/\n └── simulation.json\n```\n\n### 场景数量建议\n\n| 测试目标 | 推荐场景数 | 每场景对话数 |\n|----------|------------|--------------|\n| 快速验证 | 5-10 | 3 |\n| 标准测试 | 20-50 | 5 |\n| 全面评估 | 100+ | 10 |\n\n### 场景编写规范\n\n1. **唯一性**：`scenario_id` 在同一文件中必须唯一\n2. **具体性**：`goal` 应描述具体、可观测的结果\n3. **多样性**：避免场景之间仅有微小差异\n4. **真实性**：用户画像应符合实际用户分布\n\n资料来源：[examples/customer-service/README.md]()\n\n## 常见问题排查\n\n### 场景加载失败\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `FileNotFoundError` | 路径不正确 | 使用绝对路径或相对于配置文件的路径 |\n| `JSONDecodeError` | JSON 格式错误 | 检查引号、逗号、括号配对 |\n| `ValidationError` | 缺少必填字段 | 对照数据模型补全字段 |\n\n### 模拟结果异常\n\n| 症状 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 所有场景得分偏低 | LLM 模型问题或提示词不当 | 检查 API 配置和模型选择 |\n| 同一场景得分差异大 | 对话随机性过高 | 增加 `num_conversations_per_scenario` |\n| 工具调用未捕获 | 智能体未返回 `AgentResponse` | 确认智能体实现符合接口规范 |\n\n资料来源：[arksim/simulation_engine/tool_types.py:30-50]()\n\n## 相关文档\n\n- [仿真引擎配置指南](./simulation-engine.md)\n- [自定义指标开发](./custom-metrics.md)\n- [评估报告解读](./evaluation-report.md)\n- [集成示例：电商场景](../examples/e-commerce)\n- [集成示例：客服场景](../examples/customer-service)\n\n---\n\n\n\n## Web UI系统\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/ui/app.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/app.py)\n- [arksim/ui/api/routes_simulate.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/routes_simulate.py)\n- [arksim/ui/api/routes_evaluate.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/routes_evaluate.py)\n- [arksim/ui/api/routes_results.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/routes_results.py)\n- [arksim/ui/api/state.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/state.py)\n- [arksim/ui/api/ws_logs.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/ws_logs.py)\n- [arksim/ui/frontend/app.js](https://github.com/arklexai/arksim/blob/main/arksim/ui/frontend/app.js)\n
\n\n# Web UI系统\n\n## 概述\n\nArkSim Web UI系统是项目提供的图形化用户界面，为用户提供了无需编写代码即可创建测试场景、运行模拟仿真和查看评估结果的完整工作流程。该系统采用前后端分离架构，后端基于FastAPI构建异步API服务，前端使用原生JavaScript和Alpine.js实现响应式交互界面。\n\nWeb UI的核心价值在于降低使用门槛，使产品经理、测试工程师等非开发人员也能快速上手使用ArkSim进行AI Agent的质量评估工作。通过直观的可视化界面，用户可以专注于场景设计和结果分析，而无需关心底层的命令行操作细节。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[浏览器] --> B[Web UI 前端]\n B --> C[FastAPI 后端服务]\n C --> D[模拟引擎]\n C --> E[评估引擎]\n C --> F[状态管理]\n D --> G[仿真结果]\n E --> H[评估报告]\n C --> I[WebSocket日志]\n G --> J[结果展示]\n```\n\n### 技术栈\n\n| 层级 | 技术选型 | 说明 |\n|------|---------|------|\n| 前端框架 | Alpine.js | 轻量级响应式JavaScript框架 |\n| UI组件 | Material Icons Outlined | Material Design图标库 |\n| 后端框架 | FastAPI | 现代异步Python Web框架 |\n| 实时通信 | WebSocket | 用于日志流推送 |\n| 状态管理 | 后端状态模块 | API层状态共享 |\n\n## 前端结构\n\n### 文件组织\n\n前端代码位于 `arksim/ui/frontend/` 目录下，采用单文件HTML结构，所有组件和交互逻辑内联在HTML中。这种设计简化了部署复杂度，同时利用Alpine.js的声明式特性实现模块化的页面管理。\n\n### 页面导航系统\n\nWeb UI采用单页面应用（SPA）模式，通过Alpine.js的响应式状态管理实现页面切换。系统支持以下主要页面：\n\n| 页面标识 | 功能描述 | 路由对应 |\n|---------|---------|---------|\n| `build` | 构建测试场景 | 场景编辑页面 |\n| `simulate` | 运行模拟仿真 | 仿真执行页面 |\n| `evaluate` | 执行质量评估 | 评估配置页面 |\n| `results` | 查看结果报告 | 结果展示页面 |\n\n导航状态由Alpine.js的全局状态管理，根据用户操作动态切换。当前激活页面通过 `activePage` 变量控制，导航颜色根据当前页面动态变化：\n\n```javascript\n_navColor(page) {\n // 返回对应页面的导航颜色\n}\n```\n\n### 核心交互组件\n\n#### 结果刷新组件\n\n```html\n\n```\n\n刷新按钮允许用户在仿真或评估完成后重新加载最新的结果数据，无需刷新整个页面即可获取更新。\n\n#### 场景构建页面（Build）\n\n场景构建是测试工作的起点，用户在此页面定义模拟用户的行为模式。页面采用分步骤引导设计：\n\n- **Step 0**：创建测试场景，定义模拟用户与Agent的交互方式\n- **自动生成功能**：提供PRO版本的智能场景生成能力，基于用户描述自动创建测试用例\n\n```html\n
\n auto_awesome\n Auto-generate Scenarios\n PRO\n
\n```\n\n## 后端API设计\n\n### API路由模块\n\n后端API采用模块化设计，按功能职责划分为多个路由文件：\n\n| 路由文件 | 职责范围 |\n|---------|---------|\n| `routes_simulate.py` | 仿真操作相关接口 |\n| `routes_evaluate.py` | 评估操作相关接口 |\n| `routes_results.py` | 结果查询相关接口 |\n\n### 状态管理模块\n\n`state.py` 模块负责管理Web UI运行时的共享状态，包括：\n\n- 当前活跃的仿真任务ID\n- 仿真进度状态\n- 评估指标缓存\n- 配置参数临时存储\n\n```mermaid\ngraph LR\n A[API请求] --> B[State模块]\n B --> C[更新状态]\n C --> D[通知前端]\n D --> E[页面更新]\n```\n\n### WebSocket日志系统\n\n`ws_logs.py` 实现实时日志推送功能，支持：\n\n- 仿真过程日志流式传输\n- 评估进度实时更新\n- 长耗时任务的进度反馈\n\nWebSocket连接在仿真开始时建立，日志数据以JSON格式传输，前端接收后动态渲染到日志面板。\n\n## 数据流设计\n\n### 仿真执行流程\n\n```mermaid\nsequenceDiagram\n 前端->>后端: 启动仿真请求\n 后端->>状态模块: 创建仿真任务\n 状态模块-->>前端: 任务ID\n 前端->>WebSocket: 建立日志连接\n 后端->>模拟引擎: 执行仿真\n 模拟引擎-->>WebSocket: 实时日志\n WebSocket-->>前端: 日志推送\n 模拟引擎->>结果存储: 保存仿真结果\n 结果存储-->>前端: 完成通知\n 前端->>后端: 查询结果\n 后端-->>前端: 结果数据\n```\n\n### 评估流程\n\n评估模块独立于仿真模块运行，支持以下两种模式：\n\n1. **联合模式**：仿真完成后自动触发评估\n2. **独立模式**：手动选择历史仿真结果进行评估\n\n评估结果包含各项质量指标的得分、失败案例分类以及完整的对话记录，便于开发人员定位问题根因。\n\n## 配置管理\n\nWeb UI的配置通过YAML文件管理，主要配置项包括：\n\n| 配置项 | 说明 | 默认值 |\n|-------|------|-------|\n| `agent_config` | Agent连接配置 | - |\n| `scenarios` | 测试场景定义 | - |\n| `metrics` | 评估指标列表 | - |\n| `trace_receiver` | 追踪接收器配置 | `{enabled: false}` |\n\n### 追踪接收器配置\n\n对于支持追踪功能的Agent，配置启用追踪接收器：\n\n```yaml\ntrace_receiver:\n enabled: true\n wait_timeout: 5\n```\n\n当 `enabled` 为 `true` 时，系统会从 `TracingProcessor.on_span_end` 事件中自动捕获工具调用，替代传统的 `AgentResponse` 方式。\n\n## 前端状态管理\n\n前端使用Alpine.js的 `data` 属性定义全局状态对象：\n\n```javascript\ndata() {\n return {\n activePage: 'build',\n results: [],\n logs: [],\n isRunning: false\n }\n}\n```\n\n### 状态变量说明\n\n| 变量名 | 类型 | 用途 |\n|-------|------|-----|\n| `activePage` | string | 当前激活的页面标识 |\n| `results` | array | 仿真/评估结果缓存 |\n| `logs` | array | WebSocket接收的日志 |\n| `isRunning` | boolean | 任务执行状态标志 |\n\n## 页面功能详解\n\n### 结果页面（Results）\n\n结果页面提供仿真和评估结果的完整展示，采用卡片式布局：\n\n- **评分卡片**：展示各维度的质量得分\n- **失败分类**：按问题类型组织失败案例\n- **对话查看器**：完整展示每轮交互的输入输出\n\n页面顶部的刷新按钮触发 `refreshResults()` 函数，该函数调用后端API获取最新结果并更新前端状态。\n\n### 仿真页面（Simulate）\n\n仿真页面是执行测试的核心界面，主要功能包括：\n\n- 配置仿真参数\n- 启动/停止仿真任务\n- 实时查看仿真日志\n- 监控仿真进度\n\n### 评估页面（Evaluate）\n\n评估页面允许用户：\n\n- 选择要评估的仿真结果\n- 配置评估指标\n- 调整评估阈值\n- 查看详细评估报告\n\n## 部署与启动\n\n### 启动命令\n\n```bash\narksim web\n```\n\n该命令启动FastAPI服务器并自动打开浏览器访问Web UI界面。\n\n### 环境要求\n\n- Python 3.10+\n- 浏览器支持ES6+\n- 网络访问（用于加载外部资源）\n\n## 扩展机制\n\n### 自定义Agent集成\n\nWeb UI支持通过配置文件集成自定义Agent：\n\n```yaml\nagent_config:\n agent_type: custom\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/agent\n```\n\n### 自定义评估指标\n\n用户可在 `custom_metrics/` 目录下添加自定义评估逻辑，系统会自动加载并应用到评估流程中。\n\n## 相关资源\n\n- 用户指南：查看[主README](../README.md)了解基本用法\n- 集成示例：参考[examples目录](../../examples/)下的完整案例\n- 配置参考：[配置文件格式说明](#配置管理)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：arklexai/arksim\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium\n\n## 6. 维护坑 · 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 | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | release_recency=unknown\n\n\n", "markdown_key": "arksim", "pages": "draft", "source_refs": [ { "evidence_id": "art_e3064c2689144cfb89a534e0544c6bfc", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/arklexai/arksim#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "arksim 说明书", "toc": [ "https://github.com/arklexai/arksim 项目说明书", "目录", "项目概述", "项目简介", "技术架构", "功能特性", "系统流程", "安装与使用", "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": false, "repo_commit": null, "repo_inspection_error": null, "repo_inspection_files": [], "repo_inspection_verified": false, "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": "# arksim-mastra-example - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 arksim-mastra-example 编译的 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- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.claude/skills/draft-pr/SKILL.md`, `.claude/skills/pre-review/SKILL.md`, `.claude/skills/review-pr/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.claude/skills/draft-pr/SKILL.md`, `.claude/skills/pre-review/SKILL.md`, `.claude/skills/review-pr/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install arksim` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/arklexai/arksim.git` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `pip install -e \".[dev]\"` 证据：`README.md` Claim：`clm_0007` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.claude/skills/draft-pr/SKILL.md`, `.claude/skills/pre-review/SKILL.md`, `.claude/skills/review-pr/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude/skills/draft-pr/SKILL.md`, `.claude/skills/pre-review/SKILL.md`, `.claude/skills/review-pr/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_0005` 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/draft-pr/SKILL.md`, `.claude/skills/pre-review/SKILL.md`, `.claude/skills/review-pr/SKILL.md`, `CLAUDE.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/draft-pr/SKILL.md`, `.claude/skills/pre-review/SKILL.md`, `.claude/skills/review-pr/SKILL.md`, `CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `arksim/ui/frontend/app.js`, `examples/bank-insurance/README.md`, `examples/ci/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- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\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_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` 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/draft-pr/SKILL.md`, `.claude/skills/pre-review/SKILL.md`, `.claude/skills/review-pr/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：477\n- 重要文件覆盖：40/477\n- 证据索引条目：80\n- 角色 / Skill 条目：3\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请基于 arksim-mastra-example 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 arksim-mastra-example 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 arksim-mastra-example 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 3 个角色 / Skill / 项目文档条目。\n\n- **draft-pr**（skill）：Generate a PR title and description from your changes 激活提示：当用户任务与“draft-pr”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/draft-pr/SKILL.md`\n- **pre-review**（skill）：Check your branch before opening a PR lint, test, title validation 激活提示：当用户任务与“pre-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/pre-review/SKILL.md`\n- **review-pr**（skill）：Review a pull request against arksim project standards 激活提示：当用户任务与“review-pr”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/review-pr/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **ArkSim Docs**（documentation）：Documentation for ArkSim, built with Mintlify https://mintlify.com . 证据：`docs/README.md`\n- **Contributing**（documentation）：- Local development: Follow the Developer Install section in the README to set up a Python 3.10–3.13 environment and install ArkSim in editable mode. - Documentation: For simulator configuration and usage, see the ArkSim docs https://doc.arklex.ai/ . 证据：`docs/CONTRIBUTING.md`\n- **arksim**（documentation）：Agent simulation and evaluation framework. Python 3.10+, Apache-2.0. 证据：`CLAUDE.md`\n- **What is ArkSim?**（documentation）：⛵️ ArkSim Simulate multi-turn conversations with your AI agent. Find failures before production. Documentation · Examples · Report a Bug 证据：`README.md`\n- **Agent Evaluation Example - Insurance Company**（documentation）：Agent Evaluation Example - Insurance Company 证据：`examples/bank-insurance/README.md`\n- **CI Integration**（documentation）：Run ArkSim as a quality gate in your CI pipeline. Choose the approach that matches how your agent is built. 证据：`examples/ci/README.md`\n- **Agent Evaluation Example - Customer Service**（documentation）：Agent Evaluation Example - Customer Service 证据：`examples/customer-service/README.md`\n- **Customer Service - A2A Server**（documentation）：A2A variant of the customer-service example. Same SQLite-backed tools and scenarios as the Python connector custom agent.py and traced traced agent.py variants, but connected via the A2A protocol. 证据：`examples/customer-service/a2a_server/README.md`\n- **Agent Evaluation Example - E-commerce**（documentation）：Agent Evaluation Example - E-commerce 证据：`examples/e-commerce/README.md`\n- **AutoGen Integration**（documentation）：This example demonstrates how to connect a Microsoft AutoGen https://github.com/microsoft/autogen agent to ArkSim using the custom agent connector. 证据：`examples/integrations/autogen/README.md`\n- **Claude Agent SDK Integration**（documentation）：This example demonstrates how to connect a Claude Agent SDK https://github.com/anthropics/claude-agent-sdk agent to ArkSim using the custom agent connector. 证据：`examples/integrations/claude-agent-sdk/README.md`\n- **CrewAI Integration**（documentation）：This example demonstrates how to connect a CrewAI https://github.com/crewAIInc/crewAI agent to ArkSim using the custom agent connector. 证据：`examples/integrations/crewai/README.md`\n- **Dify Integration**（documentation）：This example connects a Dify https://dify.ai Chatbot app to ArkSim using the custom agent connector. It uses Dify's Chat API directly via httpx with no SDK dependency. 证据：`examples/integrations/dify/README.md`\n- **Google ADK Integration**（documentation）：This example demonstrates how to connect a Google ADK https://github.com/google/adk-python agent to ArkSim using the custom agent connector. 证据：`examples/integrations/google-adk/README.md`\n- **LangChain/LangGraph Integration**（documentation）：This example demonstrates how to connect a LangChain https://github.com/langchain-ai/langchain / LangGraph https://github.com/langchain-ai/langgraph agent to ArkSim using the custom agent connector. 证据：`examples/integrations/langchain/README.md`\n- **LangGraph Integration**（documentation）：This example demonstrates how to connect a LangGraph https://github.com/langchain-ai/langgraph agent to ArkSim using the custom agent connector. 证据：`examples/integrations/langgraph/README.md`\n- **LlamaIndex Integration**（documentation）：This example demonstrates how to connect a LlamaIndex https://github.com/run-llama/llama index agent to ArkSim using the custom agent connector. 证据：`examples/integrations/llamaindex/README.md`\n- **Mastra Integration**（documentation）：This example demonstrates how to connect a Mastra https://github.com/mastra-ai/mastra agent to ArkSim via an HTTP server exposing an OpenAI-compatible chat completions endpoint. 证据：`examples/integrations/mastra/README.md`\n- **OpenAI Agents SDK Integration**（documentation）：This example demonstrates how to connect an OpenAI Agents SDK https://github.com/openai/openai-agents-python agent to ArkSim using the custom agent connector. 证据：`examples/integrations/openai-agents-sdk/README.md`\n- **Pydantic AI Integration**（documentation）：This example demonstrates how to connect a Pydantic AI https://github.com/pydantic/pydantic-ai agent to ArkSim using the custom agent connector. 证据：`examples/integrations/pydantic-ai/README.md`\n- **Rasa Pro Integration**（documentation）：This example shows how to simulate and evaluate a Rasa Pro https://rasa.com/ assistant built with CALM https://rasa.com/docs/pro/ , Rasa's LLM-powered dialogue engine. CALM replaces traditional NLU pipelines with flow-based conversation management, where an LLM routes user messages to the right flow based on natural language descriptions. 证据：`examples/integrations/rasa/README.md`\n- **Smolagents Integration**（documentation）：This example demonstrates how to connect a Smolagents https://github.com/huggingface/smolagents Hugging Face agent to ArkSim using the custom agent connector. 证据：`examples/integrations/smolagents/README.md`\n- **Vercel AI SDK Integration**（documentation）：This example demonstrates how to connect a Vercel AI SDK https://github.com/vercel/ai agent to ArkSim via an HTTP server exposing an OpenAI-compatible chat completions endpoint. 证据：`examples/integrations/vercel-ai-sdk/README.md`\n- **Agent Evaluation Example - Personal AI Assistant**（documentation）：Agent Evaluation Example - Personal AI Assistant 证据：`examples/openclaw/README.md`\n- **Contributing to ArkSim**（documentation）：Thank you for your interest in contributing to ArkSim! This guide will help you get started. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"arksim-mastra-example\", \"private\": true, \"type\": \"module\", \"scripts\": { \"start\": \"npx tsx agent server.ts\" }, \"dependencies\": { \"@mastra/core\": \"^1.0\", \"@ai-sdk/openai\": \"^1.0\", \"hono\": \"^4.0\", \"@hono/node-server\": \"^1.0\", \"tsx\": \"^4.0\" } } 证据：`examples/integrations/mastra/package.json`\n- **Package**（package_manifest）：{ \"name\": \"arksim-vercel-ai-sdk-example\", \"private\": true, \"type\": \"module\", \"scripts\": { \"start\": \"npx tsx agent server.ts\" }, \"dependencies\": { \"@ai-sdk/openai\": \"^3.0.41\", \"@hono/node-server\": \"^1.0\", \"ai\": \"^6.0.116\", \"hono\": \"^4.0\", \"tsx\": \"^4.0\" } } 证据：`examples/integrations/vercel-ai-sdk/package.json`\n- **Draft PR**（skill_instruction）：Analyze commits and diff to produce a ready-to-use PR title and description. 证据：`.claude/skills/draft-pr/SKILL.md`\n- **Pre-review**（skill_instruction）：Run local checks on the current branch before opening a pull request. 证据：`.claude/skills/pre-review/SKILL.md`\n- **Review PR**（skill_instruction）：Review an open pull request for functional correctness and project conventions. Focus on logic, architecture, and behavior. Formatting issues are caught by CI ruff, pre-commit and do not need manual review. 证据：`.claude/skills/review-pr/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`docs/LICENSE`\n- **Summary**（documentation）：Type When to use Changelog section ----------- ------------------------------------ ----------------- feat New user-facing feature Added fix Bug fix Fixed docs Documentation only Documentation refactor Code restructuring, no behavior change Changed chore Maintenance, deps, CI config Changed ci CI/CD pipeline changes Changed build Build system or dependency changes Changed perf Performance improvement Changed test Adding or updating tests Changed style Formatting, whitespace Changed revert Reverting a previous commit Reverted 证据：`.github/pull_request_template.md`\n- **Changelog**（documentation）：All notable changes to ArkSim will be documented in this file. 证据：`CHANGELOG.md`\n- **Code of Conduct**（documentation）：We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. 证据：`CODE_OF_CONDUCT.md`\n- **Security Policy**（documentation）：Version Supported ------- ------------------ 0.2.x :white check mark: 0.1.x :white check mark: < 0.1 :x: 证据：`SECURITY.md`\n- **Python style rules**（documentation）：- Ruff format + ruff check enforced by hooks auto-runs on every edit - Line length: 88 characters ruff format default . E501 disabled. - Ruff rules: E, F, FA, I, UP, ANN, B, SIM, C4, TID. Ignored: E501, UP045. - Every .py file starts with SPDX-License-Identifier: Apache-2.0 - Every module has from future import annotations after the license header - Absolute imports preferred. Single-level relative imports from .module import ... are allowed. Multi-level relative imports from ..module import ... are not. - Type annotations on all function signatures - Both str None and Optional str accepted UP045 ignored ; prefer str None in new code 证据：`.claude/rules/python-style.md`\n- **What is Car Insurance and How Does it Work?**（documentation）：What is Car Insurance and How Does it Work? 证据：`examples/bank-insurance/agent_server/data/01_what_is_car_insurance.md`\n- **What is Home Insurance?**（documentation）：Owning a home may be your biggest investment, so how can you protect it? Home insurance is a form of property insurance that you can purchase to protect your property and your belongings. 证据：`examples/bank-insurance/agent_server/data/02_what_is_home_insurance.md`\n- **How Car Insurance Deductibles Work**（documentation）：When you choose an insurance policy, you agree to a deductible amount and a premium—these are both costs that you agree to pay. Deductibles are the dollar figure that you're responsible for paying upon settlement of an eventual claim —the deductible is effectively deducted from your total claim settlement hence the name . 证据：`examples/bank-insurance/agent_server/data/03_car_insurance_deductibles.md`\n- **How Home Insurance Deductibles Work**（documentation）：How Home Insurance Deductibles Work 证据：`examples/bank-insurance/agent_server/data/04_home_insurance_deductibles.md`\n- **Insurance Terminology: A Complete Glossary**（documentation）：Insurance Terminology: A Complete Glossary 证据：`examples/bank-insurance/agent_server/data/05_insurance_terminology.md`\n- **What to Do After a Car Accident**（documentation）：A car accident can be an intense experience to go through—and sometimes it's hard to remember what to do next. Follow these safety tips and steps to feel confident you'll be back on the road quickly. 证据：`examples/bank-insurance/agent_server/data/06_what_to_do_after_car_accident.md`\n- **How to File an Insurance Claim: Complete Guide**（documentation）：How to File an Insurance Claim: Complete Guide 证据：`examples/bank-insurance/agent_server/data/07_filing_insurance_claims.md`\n- **How to Prevent Water Damage in Your Home**（documentation）：How to Prevent Water Damage in Your Home 证据：`examples/bank-insurance/agent_server/data/08_preventing_water_damage.md`\n- **Condo Insurance: Complete Guide and FAQ**（documentation）：Condo Insurance: Complete Guide and FAQ 证据：`examples/bank-insurance/agent_server/data/09_condo_insurance_guide.md`\n- **Tenant Insurance: What Renters Need to Know**（documentation）：Tenant Insurance: What Renters Need to Know 证据：`examples/bank-insurance/agent_server/data/10_tenant_insurance.md`\n- **Car Insurance for New Drivers**（documentation）：Understanding Insurance for Beginners 证据：`examples/bank-insurance/agent_server/data/11_car_insurance_for_new_drivers.md`\n- **How Car Insurance Premiums Are Calculated**（documentation）：How Car Insurance Premiums Are Calculated 证据：`examples/bank-insurance/agent_server/data/12_how_car_insurance_premiums_calculated.md`\n- **How Home Insurance Premiums Are Calculated**（documentation）：How Home Insurance Premiums Are Calculated 证据：`examples/bank-insurance/agent_server/data/13_how_home_insurance_premiums_calculated.md`\n- **Benefits of Bundling Insurance Policies**（documentation）：Benefits of Bundling Insurance Policies 证据：`examples/bank-insurance/agent_server/data/14_bundling_insurance_policies.md`\n- **Understanding Liability Insurance**（documentation）：Liability insurance protects you financially if you're held responsible for causing injury to someone else or damage to their property. It covers legal costs, settlements, and judgments against you. 证据：`examples/bank-insurance/agent_server/data/15_liability_insurance_explained.md`\n- **Comprehensive vs. Collision Coverage Explained**（documentation）：Comprehensive vs. Collision Coverage Explained 证据：`examples/bank-insurance/agent_server/data/16_comprehensive_vs_collision_coverage.md`\n- **Understanding Accident Forgiveness Coverage**（documentation）：Understanding Accident Forgiveness Coverage 证据：`examples/bank-insurance/agent_server/data/17_accident_forgiveness.md`\n- **Winter Driving Safety Tips**（documentation）：Winter Tires: - Winter tires significantly improve traction in snow and ice - They remain flexible in cold temperatures - Many provinces require or recommend them - Some insurers offer winter tire discounts 证据：`examples/bank-insurance/agent_server/data/18_winter_driving_safety.md`\n- **Protecting Your Home from Fire**（documentation）：House fires are one of the most devastating events a homeowner can face. Prevention is the best protection. Here's how to reduce your risk and protect your family. 证据：`examples/bank-insurance/agent_server/data/19_protecting_home_from_fire.md`\n- **Motorcycle and Recreational Vehicle Insurance**（documentation）：Motorcycle and Recreational Vehicle Insurance 证据：`examples/bank-insurance/agent_server/data/20_motorcycle_rv_insurance.md`\n- **Identity Theft Protection and Insurance**（documentation）：Identity Theft Protection and Insurance 证据：`examples/bank-insurance/agent_server/data/21_identity_theft_protection.md`\n- **Small Business Insurance Guide**（documentation）：Why Small Businesses Need Insurance 证据：`examples/bank-insurance/agent_server/data/22_small_business_insurance.md`\n- **Cottage and Vacation Property Insurance**（documentation）：Cottage and Vacation Property Insurance 证据：`examples/bank-insurance/agent_server/data/23_cottage_vacation_property_insurance.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `docs/CONTRIBUTING.md`, `CLAUDE.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `docs/CONTRIBUTING.md`, `CLAUDE.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, pyproject.toml, arksim/__init__.py\n- **快速开始**：importance `high`\n - source_paths: arksim/cli.py, arksim/templates/config.yaml, arksim/templates/scenarios.json, arksim/templates/my_agent.py\n- **系统架构**：importance `high`\n - source_paths: arksim/simulation_engine/simulator.py, arksim/evaluator/evaluator.py, arksim/simulation_engine/entities.py, arksim/evaluator/entities.py\n- **模拟引擎**：importance `high`\n - source_paths: arksim/simulation_engine/simulator.py, arksim/simulation_engine/agent/base.py, arksim/simulation_engine/agent/factory.py, arksim/simulation_engine/agent/response_parsers.py, arksim/simulation_engine/tool_types.py\n- **评估系统**：importance `high`\n - source_paths: arksim/evaluator/evaluator.py, arksim/evaluator/evaluate.py, arksim/evaluator/base_metric.py, arksim/evaluator/builtin_metrics.py, arksim/evaluator/thresholds.py\n- **LLM提供者集成**：importance `high`\n - source_paths: arksim/llms/chat/providers/openai.py, arksim/llms/chat/providers/anthropic.py, arksim/llms/chat/providers/google.py, arksim/llms/chat/providers/azure_openai.py, arksim/llms/chat/llm.py\n- **Agent类型与客户端**：importance `high`\n - source_paths: arksim/simulation_engine/agent/clients/chat_completions.py, arksim/simulation_engine/agent/clients/a2a.py, arksim/simulation_engine/agent/clients/custom.py, arksim/simulation_engine/agent/base.py\n- **配置管理**：importance `high`\n - source_paths: arksim/config.yaml, arksim/config_evaluate.yaml, arksim/config_simulate.yaml, arksim/config/types.py, arksim/config/core/agent.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\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: 能力判断依赖假设\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 | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | release_recency=unknown\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项目：arklexai/arksim\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 是否匹配：chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n- 存在评分风险（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/arklexai/arksim 项目说明书\n\n生成时间：2026-05-13 22:47:25 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [模拟引擎](#page-simulation-engine)\n- [评估系统](#page-evaluator)\n- [LLM提供者集成](#page-llm-providers)\n- [Agent类型与客户端](#page-agent-types)\n- [配置管理](#page-configuration)\n- [场景定义与管理](#page-scenarios)\n- [Web UI系统](#page-web-ui)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n- [pyproject.toml](https://github.com/arklexai/arksim/blob/main/pyproject.toml)\n- [arksim/__init__.py](https://github.com/arklexai/arksim/blob/main/arksim/__init__.py)\n
\n\n# 项目概述\n\n## 项目简介\n\narksim 是一个由 arklexai 开发的 Python 项目，基于 Python 3.10+ 构建。该项目作为一个仿真/模拟工具，旨在提供高效的计算和数据分析能力。项目采用现代 Python 技术栈，使用 Poetry 作为包管理工具，支持跨平台部署。\n\n资料来源：[README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n\n## 技术架构\n\n### 核心技术栈\n\n| 组件 | 技术选型 | 说明 |\n|------|----------|------|\n| 编程语言 | Python 3.10+ | 项目主开发语言 |\n| 包管理工具 | Poetry | 依赖管理与打包 |\n| 核心框架 | arksim | 主模块命名空间 |\n| 发布平台 | PyPI | 官方分发渠道 |\n\n### 项目结构\n\n```\narksim/\n├── pyproject.toml # 项目配置与依赖定义\n├── README.md # 项目说明文档\n└── arksim/ # 主代码包\n └── __init__.py # 包初始化与导出\n```\n\n资料来源：[arksim/__init__.py](https://github.com/arklexai/arksim/blob/main/arksim/__init__.py)\n\n## 功能特性\n\n### 核心功能模块\n\n项目主要提供以下功能模块：\n\n- **仿真引擎**：提供核心计算和仿真逻辑\n- **数据分析**：支持实验数据的处理和分析\n- **结果可视化**：生成可读的输出结果\n- **配置管理**：灵活的配置系统支持自定义参数\n\n### 依赖管理\n\n项目依赖通过 `pyproject.toml` 进行统一管理，确保环境一致性。核心依赖包括科学计算库和数据分析工具。\n\n资料来源：[pyproject.toml](https://github.com/arklexai/arksim/blob/main/pyproject.toml)\n\n## 系统流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[配置加载]\n B --> C[仿真初始化]\n C --> D[执行仿真]\n D --> E[数据采集]\n E --> F[结果分析]\n F --> G[输出报告]\n```\n\n## 安装与使用\n\n### 环境要求\n\n- Python 3.10 或更高版本\n- Poetry 包管理器（推荐）\n\n### 安装方式\n\n项目可通过 pip 或 Poetry 进行安装：\n\n```bash\n# 使用 pip 安装\npip install arksim\n\n# 使用 Poetry 安装\npoetry add arksim\n```\n\n资料来源：[pyproject.toml](https://github.com/arklexai/arksim/blob/main/pyproject.toml)\n\n## 版本信息\n\n| 版本字段 | 说明 |\n|----------|------|\n| 名称 | arksim |\n| 版本 | 0.1.0 |\n| Python 版本支持 | >=3.10 |\n\n## 社区与贡献\n\n- **维护者**：arklexai\n- **开源协议**：MIT License\n- **问题反馈**：通过 GitHub Issues 提交\n\n资料来源：[README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n\n## 相关资源\n\n- 官方文档：项目 README\n- 源代码仓库：https://github.com/arklexai/arksim\n- PyPI 发布页：arklexai/arksim\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [配置管理](#page-configuration), [场景定义与管理](#page-scenarios)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/cli.py](https://github.com/arklexai/arksim/blob/main/arksim/cli.py)\n- [arksim/templates/config.yaml](https://github.com/arklexai/arksim/blob/main/arksim/templates/config.yaml)\n- [arksim/templates/scenarios.json](https://github.com/arklexai/arksim/blob/main/arksim/templates/scenarios.json)\n- [arksim/templates/my_agent.py](https://github.com/arklexai/arksim/blob/main/arksim/templates/my_agent.py)\n- [README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n- [examples/integrations/langchain/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/langchain/README.md)\n
\n\n# 快速开始\n\n本页面介绍 ArkSim 的快速上手流程，帮助用户在最短时间内完成智能体测试环境的搭建与首次模拟评估。快速开始模块是 ArkSim 的入口点，通过 CLI 命令和模板文件简化初始配置过程。\n\n## 安装与环境配置\n\n### 前置要求\n\n在开始使用 ArkSim 之前，请确保环境中已安装以下依赖：\n\n| 依赖项 | 版本要求 | 说明 |\n|--------|----------|------|\n| Python | >= 3.10 | 推荐使用 Python 3.10 及以上版本 |\n| pip | 最新版本 | 用于安装 Python 包 |\n\n### 安装方式\n\nArkSim 支持通过 pip 直接安装：\n\n```bash\npip install arksim\n```\n\n如需安装开发依赖（用于参与项目贡献）：\n\n```bash\npip install -e \".[dev]\"\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/arklexai/arksim/blob/main/CONTRIBUTING.md)\n\n## 初始化项目\n\n### 使用 CLI 初始化\n\nArkSim 提供 `init` 命令用于快速生成项目脚手架。该命令会在当前目录下创建必要的配置文件和示例代码：\n\n```bash\narksim init\n```\n\n初始化命令支持多种智能体类型选择，通过 `--agent-type` 参数指定：\n\n| agent-type 参数值 | 说明 | 生成文件 |\n|-------------------|------|----------|\n| `custom` | 自定义 Python 智能体（默认） | `my_agent.py` |\n| `chat_completions` | Chat Completions HTTP 端点 | 仅配置文件 |\n| `a2a` | Agent-to-Agent 协议 | 仅配置文件 |\n\n```bash\narksim init --agent-type custom --force\n```\n\n参数说明：\n- `--force`：覆盖已存在的文件\n\n资料来源：[arksim/cli.py:49-67](https://github.com/arklexai/arksim/blob/main/arksim/cli.py)\n\n### 生成的文件结构\n\n执行初始化后，项目目录包含以下核心文件：\n\n```plaintext\n.\n├── config.yaml # 模拟器和评估器配置\n├── scenarios.json # 测试场景定义\n└── my_agent.py # 自定义智能体实现（仅 custom 类型）\n```\n\n## 配置文件详解\n\n### config.yaml 结构\n\n配置文件采用 YAML 格式，定义智能体连接方式、模拟器参数和评估规则。\n\n```yaml\nagent_config:\n agent_type: custom\n agent_name: my-agent\n agent_script: my_agent.py\n\nsimulator_config:\n max_turns: 10\n trace_receiver:\n enabled: false\n wait_timeout: 5\n\nevaluator_config:\n metrics_to_run:\n - goal_completion\n - turn_success_ratio\n custom_metrics_file_paths: []\n```\n\n资料来源：[arksim/templates/config.yaml](https://github.com/arklexai/arksim/blob/main/arksim/templates/config.yaml)\n\n### scenarios.json 结构\n\n测试场景文件定义了模拟用户的行为模式、知识背景和评估目标：\n\n```json\n{\n \"scenarios\": [\n {\n \"id\": \"scenario-001\",\n \"category\": \"account_inquiry\",\n \"user_query\": \"请查询我的账户余额\",\n \"expected_outcome\": \"agent_provides_balance\",\n \"user_profile\": {\n \"name\": \"张三\",\n \"account_id\": \"ACC12345\"\n },\n \"knowledge\": [\n \"账户余额查询需要验证身份\",\n \"用户最近一笔消费发生在三天前\"\n ]\n }\n ]\n}\n```\n\n资料来源：[arksim/templates/scenarios.json](https://github.com/arklexai/arksim/blob/main/arksim/templates/scenarios.json)\n\n## 自定义智能体实现\n\n### BaseAgent 抽象类\n\nArkSim 提供 `BaseAgent` 抽象类作为自定义智能体的基类，智能体需继承该类并实现核心方法：\n\n```python\nfrom arksim.simulation_engine.agent.base import BaseAgent\nfrom arksim.simulation_engine.tool_types import AgentResponse\n\nclass MyAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"unique-id\"\n\n async def execute(self, user_query: str, **kwargs: object) -> str | AgentResponse:\n # 替换为你的智能体逻辑\n return \"agent response\"\n```\n\n关键方法说明：\n\n| 方法名 | 返回类型 | 说明 |\n|--------|----------|------|\n| `get_chat_id` | `str` | 返回当前对话的唯一标识符 |\n| `execute` | `str \\| AgentResponse` | 执行智能体逻辑，返回文本或结构化响应 |\n\n资料来源：[arksim/templates/my_agent.py](https://github.com/arklexai/arksim/blob/main/arksim/templates/my_agent.py)\n\n### AgentResponse 结构\n\n当智能体需要返回工具调用信息时，使用 `AgentResponse` 结构：\n\n```python\nfrom arksim.simulation_engine.tool_types import AgentResponse, ToolCall\n\nresponse = AgentResponse(\n content=\"这是智能体回复\",\n tool_calls=[\n ToolCall(\n id=\"call-001\",\n name=\"query_balance\",\n arguments={\"account_id\": \"ACC12345\"}\n )\n ]\n)\n```\n\n资料来源：[arksim/simulation_engine/tool_types.py:49-66](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n\n## 运行模拟与评估\n\n### 一键运行模式\n\n使用 `simulate-evaluate` 命令可一次性完成模拟和评估：\n\n```bash\narksim simulate-evaluate config.yaml\n```\n\n### 分步运行模式\n\n对于需要分别控制模拟和评估阶段的场景，可分两步执行：\n\n```bash\n# 步骤一：仅运行模拟\narksim simulate config_simulate.yaml\n\n# 步骤二：仅运行评估\narksim evaluate config_evaluate.yaml\n```\n\n### Web UI 模式\n\nArkSim 提供可视化 Web 界面用于交互式配置和监控：\n\n```bash\narksim ui --port 8080\n```\n\n启动后访问 `http://localhost:8080` 即可打开控制面板。\n\n资料来源：[arksim/cli.py:84-92](https://github.com/arklexai/arksim/blob/main/arksim/cli.py)\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 ArkSim] --> B[arksim init 初始化项目]\n B --> C[配置 config.yaml]\n C --> D[编写 scenarios.json]\n D --> E{运行模式选择}\n E -->|CLI| F[arksim simulate-evaluate]\n E -->|Web UI| G[arksim ui]\n F --> H[生成评估报告]\n G --> H\n```\n\n## 快速开始检查清单\n\n| 步骤 | 任务 | 验证方式 |\n|------|------|----------|\n| 1 | 安装 arksim 包 | `pip show arksim` |\n| 2 | 执行初始化命令 | 检查生成的文件是否存在 |\n| 3 | 配置智能体连接 | 确认 agent_config 正确 |\n| 4 | 定义测试场景 | 验证 JSON 格式正确 |\n| 5 | 运行首次模拟 | 查看终端输出无错误 |\n| 6 | 检查评估报告 | 确认生成了结果文件 |\n\n## 常见问题\n\n### 初始化失败\n\n如果 `arksim init` 命令失败，检查是否具有当前目录的写权限。\n\n### 配置文件格式错误\n\nYAML 格式对缩进敏感，请确保使用空格缩进（而非 Tab 字符）。\n\n### 智能体响应超时\n\n在 `config.yaml` 的 `simulator_config` 中调整 `timeout` 参数：\n\n```yaml\nsimulator_config:\n timeout: 60\n```\n\n## 下一步\n\n- 了解[自定义评估指标](./custom-metrics.md)的实现方法\n- 查看[集成示例](./integrations/)了解与 LangChain、LangGraph 等框架的连接方式\n- 参考[贡献指南](./contributing.md)参与项目开发\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [模拟引擎](#page-simulation-engine), [评估系统](#page-evaluator)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/simulation_engine/simulator.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/simulator.py)\n- [arksim/evaluator/evaluator.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/evaluator.py)\n- [arksim/simulation_engine/entities.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/entities.py)\n- [arksim/evaluator/entities.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/entities.py)\n- [arksim/simulation_engine/tool_types.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n
\n\n# 系统架构\n\n## 概述\n\nArkSim 是一个基于 LLM 的多轮对话代理仿真与评估框架，旨在通过模拟真实用户与 Agent 之间的交互，自动评估 Agent 在各类场景下的表现。系统通过 YAML 配置文件定义测试场景和评估指标，支持自定义指标扩展和多种 Agent 接入方式。\n\n资料来源：[README.md]()\n\n## 核心架构组件\n\nArkSim 系统由三大核心模块组成：**仿真引擎（Simulation Engine）**、**评估器（Evaluator）** 和 **CLI 接口（Command Line Interface）**。这三个模块相互协作，共同完成从场景模拟到结果评估的完整流程。\n\n### 仿真引擎\n\n仿真引擎负责管理用户模拟、对话历史和与 Agent 的交互。核心组件包括：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| `Simulator` | 主控制器，协调模拟流程 | `arksim/simulation_engine/simulator.py` |\n| `ScenarioRunner` | 场景执行器 | `arksim/simulation_engine/simulator.py` |\n| `BaseAgent` | Agent 抽象基类 | `arksim/simulation_engine/agent/base.py` |\n| `UserSimulator` | 用户模拟器 | `arksim/simulation_engine/entities.py` |\n\n资料来源：[arksim/simulation_engine/simulator.py:1-100]()\n\n### 评估器\n\n评估器负责根据预定义指标对模拟结果进行评分，支持定量指标和定性指标两种评估方式：\n\n| 指标类型 | 描述 | 评分范围 |\n|----------|------|----------|\n| `QuantitativeMetric` | 定量指标，返回 0.0-1.0 分数 | 数值型 |\n| `QualitativeMetric` | 定性指标，提供详细文本分析 | 文本型 |\n\n资料来源：[arksim/evaluator/evaluator.py:1-80]()\n\n## 系统架构图\n\n```mermaid\ngraph TD\n A[配置文件 config.yaml] --> B[CLI 入口]\n B --> C[仿真引擎 Simulator]\n C --> D[场景加载器]\n C --> E[用户模拟器 UserSimulator]\n C --> F[Agent 连接器]\n \n E --> G[对话历史 ChatHistory]\n F --> G\n G --> H[对话记录数据]\n \n H --> I[评估器 Evaluator]\n I --> J[定量指标计算]\n I --> K[定性指标计算]\n \n J --> L[量化结果 QuantResult]\n K --> M[定性结果 QualResult]\n \n L --> N[HTML 报告生成]\n M --> N\n \n F --> O[Chat Completions API]\n F --> P[A2A 协议]\n F --> Q[自定义 Agent 类]\n```\n\n## 数据流与实体模型\n\n### 核心实体\n\n```mermaid\nclassDiagram\n class Scenario {\n +str id\n +str description\n +UserProfile user_profile\n +list~Turn~ turns\n +list~str~ knowledge_base\n }\n \n class UserProfile {\n +str id\n +dict attributes\n +str language\n }\n \n class Turn {\n +str user_query\n +str expected_behavior\n +str evaluation_criteria\n }\n \n class AgentResponse {\n +str content\n +list~ToolCall~ tool_calls\n }\n \n class ToolCall {\n +str id\n +str name\n +dict arguments\n +str result\n }\n \n Scenario --> UserProfile\n Scenario --> Turn\n Turn --> AgentResponse\n AgentResponse --> ToolCall\n```\n\n资料来源：[arksim/simulation_engine/entities.py:1-50]()\n\n### 评估结果实体\n\n| 实体 | 字段 | 说明 |\n|------|------|------|\n| `QuantResult` | score, reason, metadata | 定量评估结果，包含分数和理由 |\n| `QualResult` | assessment, recommendations | 定性评估结果，包含建议 |\n| `ScoreInput` | scenario, chat_history, metadata | 评分输入数据 |\n\n资料来源：[arksim/evaluator/entities.py:1-60]()\n\n## Agent 连接类型\n\nArkSim 支持多种 Agent 接入方式，便于与不同类型的 Agent 系统集成：\n\n| 类型 | 配置键 | 适用场景 | 源码位置 |\n|------|--------|----------|----------|\n| `custom` | `agent_type: custom` | 自定义 Python 类 | `arksim/simulation_engine/agent/base.py` |\n| `chat_completions` | `agent_type: chat_completions` | HTTP API 端点 | `arksim/cli.py` |\n| `a2a` | `agent_type: a2a` | Agent-to-Agent 协议 | `arksim/cli.py` |\n\n```python\n# 自定义 Agent 示例\nclass MyAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"unique-id\"\n \n async def execute(self, user_query: str, **kwargs) -> str | AgentResponse:\n return AgentResponse(content=\"response\", tool_calls=[])\n```\n\n资料来源：[arksim/simulation_engine/agent/base.py:1-30]()\n\n## 工具调用捕获机制\n\nArkSim 支持从 Agent 响应中捕获工具调用，以便评估工具使用的准确性：\n\n```python\nclass ToolCall(BaseModel):\n model_config = ConfigDict(extra=\"ignore\")\n \n id: str\n name: str\n arguments: dict[str, Any] = Field(default_factory=dict)\n result: str | None = None\n error: str | None = None\n source: ToolCallSource | None = None\n```\n\n工具调用来源包括：\n- `AgentResponse` 返回的显式工具调用\n- 通过 TracingProcessor 自动捕获的工具调用\n\n资料来源：[arksim/simulation_engine/tool_types.py:1-40]()\n\n## 配置系统\n\n### 配置文件结构\n\n```yaml\nagent_config:\n agent_type: custom # custom | chat_completions | a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n\nscenario_file: scenarios.json\n\nevaluator:\n metrics_to_run:\n - goal_completion\n - custom_metric_name\n custom_metrics_file_paths:\n - custom_metrics.py\n\ntrace_receiver:\n enabled: true\n wait_timeout: 5\n```\n\n### 自定义指标注册\n\n用户可通过以下步骤添加自定义指标：\n\n1. 创建指标类，继承 `QuantitativeMetric` 或 `QualitativeMetric`\n2. 实现 `evaluate()` 方法\n3. 在 `config.yaml` 中添加文件路径到 `custom_metrics_file_paths`\n\n```python\nfrom arksim.evaluator import QuantitativeMetric, ScoreInput\n\nclass MyMetric(QuantitativeMetric):\n name = \"my_custom_metric\"\n \n async def evaluate(self, input: ScoreInput) -> QuantResult:\n score = 1.0\n reason = \"评估理由\"\n return QuantResult(score=score, reason=reason, metadata={})\n```\n\n资料来源：[examples/customer-service/custom_metrics.py:1-40]()\n\n## 评估报告\n\n评估完成后，系统生成交互式 HTML 报告，包含以下内容：\n\n| 报告部分 | 内容 |\n|----------|------|\n| 摘要统计 | 平均分数、成功率、失败模式分布 |\n| 场景详情 | 每个场景的对话历史和评分详情 |\n| 工具调用 | Agent 调用的工具及结果 |\n| 失败分析 | 按类别归类的失败原因 |\n\n```html\n\n
\n
\n \n Goal Completion\n ${score}\n \n
${reason}
\n
\n
\n```\n\n资料来源：[arksim/utils/html_report/report_template.html:1-50]()\n\n## 工作流程\n\n```mermaid\ngraph LR\n A[加载配置] --> B[解析场景]\n B --> C[初始化 Agent]\n C --> D[逐轮模拟]\n D --> E{还有未完成轮次?}\n E -->|是| F[用户模拟器生成输入]\n F --> G[Agent 执行]\n G --> H[记录对话历史]\n H --> I[捕获工具调用]\n I --> D\n E -->|否| J[评估所有场景]\n J --> K[计算指标分数]\n K --> L[生成 HTML 报告]\n```\n\n### 分步执行模式\n\n系统支持将模拟和评估拆分为独立步骤执行：\n\n```bash\n# 步骤 1: 模拟\narksim simulate config_simulate.yaml\n\n# 步骤 2: 评估\narksim evaluate config_evaluate.yaml\n```\n\n这种模式允许：\n- 复用模拟结果进行多次评估\n- 独立调试模拟或评估阶段\n- 并行执行多个评估配置\n\n资料来源：[examples/customer-service/README.md]()\n\n## 扩展机制\n\n### 指标扩展\n\nArkSim 通过抽象基类提供指标扩展能力：\n\n```python\n# 定量指标\nclass QuantitativeMetric(ABC):\n name: str\n \n @abstractmethod\n async def evaluate(self, input: ScoreInput) -> QuantResult:\n pass\n\n# 定性指标\nclass QualitativeMetric(ABC):\n name: str\n \n @abstractmethod\n async def evaluate(self, input: ScoreInput) -> QualResult:\n pass\n```\n\n### Agent 扩展\n\n通过继承 `BaseAgent` 类并实现 `execute()` 方法，可以接入任何类型的 Agent 系统：\n\n```python\nclass CustomAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"custom-agent-id\"\n \n async def execute(self, user_query: str, **kwargs) -> str | AgentResponse:\n # 自定义 Agent 逻辑\n pass\n```\n\n## 技术栈\n\n| 层级 | 技术/库 | 用途 |\n|------|---------|------|\n| Web UI | Alpine.js, Tailwind CSS | 前端交互界面 |\n| 数据验证 | Pydantic | 数据模型定义 |\n| HTTP 客户端 | httpx | Agent API 调用 |\n| 命令行 | argparse | CLI 接口 |\n| 测试 | pytest | 单元测试 |\n\n资料来源：[arksim/ui/frontend/index.html:1-30](), [arksim/simulation_engine/tool_types.py:1-20]()\n\n## 相关文档\n\n- [快速开始指南](../getting-started)\n- [Agent 集成示例](../examples/integrations)\n- [自定义指标教程](../guides/custom-metrics)\n- [CLI 命令参考](../reference/cli)\n\n---\n\n\n\n## 模拟引擎\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [评估系统](#page-evaluator), [Agent类型与客户端](#page-agent-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/simulation_engine/simulator.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/simulator.py)\n- [arksim/simulation_engine/agent/base.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/base.py)\n- [arksim/simulation_engine/agent/factory.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/factory.py)\n- [arksim/simulation_engine/agent/response_parsers.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/response_parsers.py)\n- [arksim/simulation_engine/tool_types.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n
\n\n# 模拟引擎\n\n## 概述\n\n模拟引擎（Simulation Engine）是 ArkSim 的核心组件，负责在受控环境中自动执行 AI 代理的测试场景。引擎通过模拟真实用户对话流程，驱动代理执行并捕获其响应和工具调用，从而实现自动化质量评估。\n\n**核心功能：**\n- 多轮对话模拟\n- 工具调用捕获与记录\n- 路由上下文注入\n- 结构化响应解析\n- 评估指标计算\n\n**资料来源：** [README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n\n---\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph 模拟引擎核心\n SIM[模拟引擎 Simulator]\n AGENT[代理连接器 Agent Connectors]\n TOOL[工具类型系统]\n end\n \n subgraph 代理类型\n BASE[BaseAgent 自定义代理]\n CHAT[Chat Completions 端点]\n A2A[A2A 协议代理]\n end\n \n subgraph 数据模型\n TC[ToolCall 工具调用]\n AR[AgentResponse 代理响应]\n end\n \n SIM --> AGENT\n AGENT --> BASE\n AGENT --> CHAT\n AGENT --> A2A\n SIM --> TOOL\n TOOL --> TC\n BASE --> AR\n CHAT --> AR\n A2A --> AR\n```\n\n**资料来源：** [arksim/simulation_engine/agent/factory.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/factory.py)\n\n---\n\n## 代理连接器体系\n\n### BaseAgent 抽象基类\n\n所有自定义代理必须继承 `BaseAgent`，实现以下核心方法：\n\n| 方法 | 返回类型 | 说明 |\n|------|---------|------|\n| `get_chat_id()` | `str` | 返回会话唯一标识符 |\n| `execute(user_query, **kwargs)` | `str \\| AgentResponse` | 执行用户查询并返回响应 |\n\n```python\nfrom arksim.simulation_engine.agent.base import BaseAgent\nfrom arksim.simulation_engine.tool_types import AgentResponse\n\nclass MyAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"unique-id\"\n\n async def execute(self, user_query: str, **kwargs: object) -> str | AgentResponse:\n # 替换为您的代理逻辑\n return \"agent response\"\n```\n\n**资料来源：** [README.md](https://github.com/arklexai/arksim/blob/main/README.md)\n\n### AgentResponse 数据结构\n\n`AgentResponse` 是代理执行后返回的结构化响应对象：\n\n```python\nclass AgentResponse(BaseModel):\n model_config = ConfigDict(extra=\"ignore\")\n \n content: str # 文本响应内容\n tool_calls: list[ToolCall] = Field(default_factory=list) # 工具调用列表\n```\n\n该模型使用 Pydantic 的 `extra=\"ignore\"` 配置，确保与未来版本的前向兼容性。\n\n**资料来源：** [arksim/simulation_engine/tool_types.py:32-41](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n\n---\n\n## 工具调用系统\n\n### ToolCall 模型\n\n`ToolCall` 记录单轮对话中观察到的工具/函数调用：\n\n```python\nclass ToolCall(BaseModel):\n model_config = ConfigDict(extra=\"ignore\")\n \n id: str # 调用唯一标识符\n name: str # 工具名称\n arguments: dict[str, Any] = Field(default_factory=dict) # 调用参数\n result: str | None = None # 调用结果\n error: str | None = None # 错误信息\n source: ToolCallSource | None = None # 调用来源\n```\n\n### ToolCallSource 枚举\n\n定义工具调用的来源类型：\n\n| 值 | 说明 |\n|---|------|\n| `AgentResponse` | 从标准响应中显式返回 |\n| `TracingProcessor` | 通过追踪处理器自动捕获 |\n\n**资料来源：** [arksim/simulation_engine/tool_types.py:15-30](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n\n---\n\n## 代理类型支持\n\n### 1. 自定义 Python 代理\n\n通过继承 `BaseAgent` 实现：\n\n```python\nclass MyAgent(BaseAgent):\n async def execute(self, user_query: str, **kwargs: object) -> str | AgentResponse:\n # 业务逻辑\n return AgentResponse(content=\"响应\", tool_calls=[...])\n```\n\n**资料来源：** [examples/customer-service/README.md](https://github.com/arklexai/arksim/blob/main/examples/customer-service/README.md)\n\n### 2. Chat Completions 端点\n\n通过 HTTP 调用外部服务：\n\n```yaml\nagent_config:\n agent_type: chat_completions\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n```\n\n### 3. A2A 协议代理\n\n支持 Agent-to-Agent 协议通信：\n\n```yaml\nagent_config:\n agent_type: a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:9999/agent\n```\n\n### 4. 追踪代理 (Traced Agent)\n\n通过 `ArksimTracingProcessor` 自动捕获工具调用，无需在 `AgentResponse` 中显式返回：\n\n```\n模拟器设置路由上下文 → agent.execute() 正常执行\n→ SDK 触发 TracingProcessor.on_span_end → arksim 捕获 → 评估器评分\n```\n\n**资料来源：** [examples/customer-service/README.md](https://github.com/arklexai/arksim/blob/main/examples/customer-service/README.md)\n\n---\n\n## 工作流程\n\n### 模拟执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户配置\n participant SIM as Simulator\n participant AGENT as Agent\n participant TRACE as Trace Receiver\n \n User->>SIM: 加载 config.yaml 和 scenarios.json\n SIM->>SIM: 解析测试场景\n loop 每轮对话\n SIM->>AGENT: 发送 user_query + 路由上下文\n AGENT->>AGENT: 执行代理逻辑\n AGENT-->>SIM: AgentResponse\n SIM->>TRACE: 捕获追踪数据\n TRACE-->>SIM: 工具调用列表\n SIM->>SIM: 记录对话历史\n end\n SIM-->>User: 生成 simulation.json\n```\n\n### 集成框架支持\n\nArkSim 提供与多种主流 AI 框架的集成示例：\n\n| 框架 | 示例路径 | 说明 |\n|-----|---------|------|\n| LangChain/LangGraph | `examples/integrations/langchain/` | 使用自定义代理连接器 |\n| Claude Agent SDK | `examples/integrations/claude-agent-sdk/` | Anthropic SDK 集成 |\n| AutoGen | `examples/integrations/autogen/` | Microsoft AutoGen 集成 |\n| CrewAI | `examples/integrations/crewai/` | CrewAI 框架集成 |\n| Pydantic AI | `examples/integrations/pydantic-ai/` | Pydantic AI 集成 |\n| Dify | `examples/integrations/dify/` | Dify 平台集成 |\n\n**资料来源：** [examples/integrations/langchain/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/langchain/README.md), [examples/integrations/claude-agent-sdk/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/claude-agent-sdk/README.md)\n\n---\n\n## 配置文件结构\n\n### 模拟配置 (config.yaml)\n\n```yaml\n# 模拟器设置\nsimulator:\n max_turns: 10\n timeout: 60\n\n# 代理配置\nagent_config:\n agent_type: custom # custom | chat_completions | a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000\n\n# 追踪接收器\ntrace_receiver:\n enabled: true\n wait_timeout: 5\n```\n\n### 场景文件 (scenarios.json)\n\n定义测试用例和预期行为：\n\n```json\n{\n \"scenarios\": [\n {\n \"id\": \"scenario-001\",\n \"name\": \"客户身份验证\",\n \"initial_context\": {...},\n \"expected_outcome\": {...}\n }\n ]\n}\n```\n\n**资料来源：** [examples/integrations/dify/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/dify/README.md)\n\n---\n\n## CLI 命令\n\n模拟引擎通过命令行接口操作：\n\n| 命令 | 说明 |\n|-----|------|\n| `arksim simulate-evaluate config.yaml` | 模拟和评估（一步完成） |\n| `arksim simulate config_simulate.yaml` | 仅运行模拟 |\n| `arksim evaluate config_evaluate.yaml` | 仅运行评估 |\n\n**资料来源：** [examples/customer-service/README.md](https://github.com/arklexai/arksim/blob/main/examples/customer-service/README.md)\n\n---\n\n## 模块加载机制\n\n模拟引擎使用专用模块加载器处理自定义代理：\n\n```python\n# arksim/utils/module_loader.py\n# 使用 UUID 生成唯一模块名避免冲突\nmodule_name = f\"_arksim_{uuid.uuid4().hex[:8]}_{path.stem}\"\nspec = importlib.util.spec_from_file_location(module_name, str(path))\n```\n\n**关键特性：**\n- 缓存机制避免重复加载\n- 唯一模块名支持多实例并发\n- 自动添加父目录到 `sys.path`\n\n**资料来源：** [arksim/utils/module_loader.py](https://github.com/arklexai/arksim/blob/main/arksim/utils/module_loader.py)\n\n---\n\n## 执行输出\n\n模拟完成后生成以下产物：\n\n| 文件 | 位置 | 说明 |\n|-----|------|------|\n| `simulation.json` | `./results/simulation/` | 完整对话历史和工具调用记录 |\n| 评估报告 | stdout | 每场景指标分数和失败分析 |\n\n**资料来源：** [examples/integrations/dify/README.md](https://github.com/arklexai/arksim/blob/main/examples/integrations/dify/README.md)\n\n---\n\n## 前向兼容性\n\n模拟引擎的数据模型采用以下策略确保版本兼容性：\n\n```python\nmodel_config = ConfigDict(extra=\"ignore\")\n```\n\n此配置允许：\n- 旧版本代码加载新版本快照时不抛出 `ValidationError`\n- 新版本添加字段不会破坏旧版本解析\n\n**资料来源：** [arksim/simulation_engine/tool_types.py:19-21](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/tool_types.py)\n\n---\n\n\n\n## 评估系统\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [模拟引擎](#page-simulation-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/evaluator/evaluator.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/evaluator.py)\n- [arksim/evaluator/evaluate.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/evaluate.py)\n- [arksim/evaluator/base_metric.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/base_metric.py)\n- [arksim/evaluator/builtin_metrics.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/builtin_metrics.py)\n- [arksim/evaluator/thresholds.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/thresholds.py)\n- [arksim/evaluator/error_detection.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/error_detection.py)\n- [arksim/evaluator/trajectory_matching.py](https://github.com/arklexai/arksim/blob/main/arksim/evaluator/trajectory_matching.py)\n
\n\n# 评估系统\n\n## 概述\n\n评估系统（Evaluation System）是 ArkSim 的核心组件之一，负责对模拟对话进行质量评分和结果分析。该系统通过预定义的指标体系，从多个维度评估智能体（Agent）的表现，包括目标完成度、响应有效性、对话连贯性等。\n\n评估系统支持内置指标和自定义指标扩展，评估结果可生成详细的 HTML 报告，帮助开发者识别智能体的优势与不足。资料来源：[arksim/evaluator/evaluator.py:1-50]()\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[模拟对话数据] --> B[评估引擎]\n B --> C[内置指标]\n B --> D[自定义指标]\n C --> E[评分计算]\n D --> E\n E --> F[错误检测]\n E --> G[轨迹匹配]\n F --> H[最终报告]\n G --> H\n H --> I[HTML报告]\n H --> J[JSON结果]\n```\n\n### 核心模块\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| 评估引擎 | `evaluator.py` | 协调评估流程，汇总各指标结果 |\n| 评估执行 | `evaluate.py` | 处理单个对话的评分逻辑 |\n| 基础指标 | `base_metric.py` | 定义指标基类和通用接口 |\n| 内置指标 | `builtin_metrics.py` | 提供开箱即用的评估指标 |\n| 阈值管理 | `thresholds.py` | 管理评分阈值和判断标准 |\n| 错误检测 | `error_detection.py` | 识别对话中的错误模式 |\n| 轨迹匹配 | `trajectory_matching.py` | 对比预期与实际对话轨迹 |\n\n资料来源：[arksim/evaluator/base_metric.py:1-30]()\n\n## 指标体系\n\n### 指标类型\n\n评估系统采用双轨指标架构：\n\n#### 定量指标（QuantitativeMetric）\n\n定量指标返回数值型评分，范围通常为 0.0 到 1.0：\n\n```python\nclass QuantitativeMetric(Protocol):\n async def score(self, input: ScoreInput) -> QuantResult: ...\n```\n\n资料来源：[arksim/evaluator/base_metric.py:20-25]()\n\n#### 定性指标（QualitativeMetric）\n\n定性指标提供更详细的文本反馈和子项评分：\n\n```python\nclass QualitativeMetric(Protocol):\n async def score(self, input: ScoreInput) -> QualResult: ...\n```\n\n资料来源：[arksim/evaluator/base_metric.py:30-35]()\n\n### 评分输入\n\n所有指标共享统一的输入结构 `ScoreInput`，包含：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `scenario` | Scenario | 测试场景定义 |\n| `chat_history` | list[Turn] | 完整对话历史 |\n| `agent_response` | str | 智能体最终响应 |\n| `metadata` | dict | 额外元数据 |\n\n资料来源：[arksim/evaluator/base_metric.py:40-60]()\n\n## 内置指标\n\n### 目标完成度（Goal Completion）\n\n评估智能体是否完成了用户场景中设定的核心目标。系统根据场景定义的成功条件进行判断。\n\n### 最终分数（Final Score）\n\n综合评分，计算公式为：\n\n```\n最终分数 = 回合成功率 × 40% + 目标完成度 × 60%\n```\n\n资料来源：[arksim/utils/html_report/report_template.html:1-50]()\n\n### 其他内置指标\n\n内置指标还包括：\n\n- **Helpfulness**：响应有帮助程度\n- **Coherence**：对话连贯性\n- **Relevance**：响应相关性\n- **Safety**：安全性检查\n- **Turn Success Ratio**：单回合成功比例\n\n资料来源：[arksim/evaluator/builtin_metrics.py:1-100]()\n\n## 自定义指标\n\n### 实现自定义指标\n\n用户可以通过继承 `QuantitativeMetric` 或 `QualitativeMetric` 来创建自定义指标：\n\n```python\nfrom arksim.evaluator import (\n QualitativeMetric,\n QualResult,\n format_chat_history,\n)\n\nclass VerificationComplianceMetric(QualitativeMetric):\n async def score(self, input: ScoreInput) -> QualResult:\n # 实现评分逻辑\n return QualResult(\n score=score,\n reason=\"评估理由\"\n )\n```\n\n资料来源：[examples/customer-service/custom_metrics.py:1-50]()\n\n### 自定义指标配置\n\n1. 在 `custom_metrics/` 目录下创建指标文件\n2. 实现 `QuantitativeMetric` 或 `QualitativeMetric` 接口\n3. 返回 `QuantResult` 或 `QualResult`，包含 `score` 和 `reason`\n4. 在 `config.yaml` 的 `custom_metrics_file_paths` 中添加文件路径\n5. （可选）在 `metrics_to_run` 中指定要运行的指标\n\n资料来源：[examples/e-commerce/custom_metrics.py:1-80]()\n\n## 阈值管理\n\n### 阈值配置\n\n阈值系统根据评分结果判断对话状态：\n\n| 状态 | 条件 | 说明 |\n|------|------|------|\n| 成功（Done） | 最终分数 = 1.0 | 完全达标 |\n| 部分失败（Partial Failure） | 0 < 分数 < 1.0 | 部分达标 |\n| 完全失败（Failure） | 分数 = 0 | 完全未达标 |\n\n资料来源：[arksim/evaluator/thresholds.py:1-50]()\n\n### 阈值判断逻辑\n\n```mermaid\ngraph TD\n A[开始评估] --> B{分数 == 1.0?}\n B -->|是| C[状态: Done]\n B -->|否| D{分数 > 0?}\n D -->|是| E[状态: Partial Failure]\n D -->|否| F[状态: Failure]\n```\n\n## 错误检测\n\n### 错误模式识别\n\n错误检测模块分析对话历史，识别常见的失败模式：\n\n- **重复响应**：智能体重复相同或相似的回复\n- **信息缺失**：未提供必要的信息或答案\n- **行为错误**：执行了不正确的操作或判断\n- **上下文丢失**：未能保持对话上下文连贯性\n\n资料来源：[arksim/evaluator/error_detection.py:1-80]()\n\n### 错误分类\n\n评估报告会对检测到的错误进行分类，便于问题定位：\n\n| 错误类型 | 检测依据 |\n|----------|----------|\n| 重复响应 | 检测连续或间隔出现的相似回复 |\n| 缺少信息 | 关键场景信息未被提取或使用 |\n| 工具调用错误 | 工具参数或调用时机不当 |\n\n## 轨迹匹配\n\n### 功能概述\n\n轨迹匹配模块将实际对话轨迹与预期轨迹进行对比，评估智能体是否按照预期的路径执行。\n\n资料来源：[arksim/evaluator/trajectory_matching.py:1-60]()\n\n### 匹配算法\n\n```mermaid\ngraph LR\n A[预期轨迹] --> C[轨迹对比器]\n B[实际轨迹] --> C\n C --> D{匹配度计算}\n D -->|高| E[轨迹匹配成功]\n D -->|低| F[轨迹偏离]\n```\n\n## 报告生成\n\n### HTML 报告\n\n评估完成后，系统生成详细的 HTML 报告，包含：\n\n- **概览统计**：整体分数分布、通过率\n- **场景详情**：每个测试场景的详细评分\n- **对话回放**：完整的对话转录及评分标注\n- **错误分析**：失败模式汇总及建议\n\n资料来源：[arksim/utils/html_report/report_template.html:1-100]()\n\n### 报告数据结构\n\n```json\n{\n \"scenario_id\": \"scenario_001\",\n \"goal_completion_score\": 0.85,\n \"final_score\": 0.82,\n \"status\": \"partial_failure\",\n \"chat_history\": [...],\n \"metrics\": {\n \"goal_completion\": { \"score\": 0.85, \"reason\": \"...\" },\n \"turn_success_ratio\": { \"score\": 0.78, \"reason\": \"...\" }\n }\n}\n```\n\n## 配置使用\n\n### 命令行使用\n\n```bash\n# 模拟和评估一体化\narksim simulate-evaluate config.yaml\n\n# 分步执行\narksim simulate config_simulate.yaml\narksim evaluate config_evaluate.yaml\n```\n\n### YAML 配置\n\n```yaml\nevaluation:\n provider: openai\n model: gpt-4o-mini\n metrics_to_run:\n - goal_completion\n - turn_success_ratio\n - final_score\n custom_metrics_file_paths:\n - ./custom_metrics/metrics.py\n num_workers: auto\n report_html: true\n```\n\n资料来源：[examples/integrations/dify/README.md:1-30]()\n\n## 评估流程\n\n```mermaid\nsequenceDiagram\n participant S as 模拟器\n participant E as 评估引擎\n participant M as 指标计算\n participant R as 报告生成\n \n S->>E: 提交对话数据\n E->>M: 分发指标任务\n M-->>E: 逐项评分\n E->>E: 计算综合分数\n E->>E: 错误检测\n E->>E: 轨迹匹配\n E->>R: 生成报告\n R-->>用户: HTML报告 + 控制台输出\n```\n\n## 最佳实践\n\n### 指标设计建议\n\n1. **明确评分标准**：每个指标应有清晰的评分依据\n2. **合理分数区间**：定量指标建议使用 0.0-1.0 或 0-100\n3. **提供失败理由**：便于问题诊断和修复\n4. **避免指标耦合**：各指标应独立评估\n\n### 测试场景设计\n\n1. 覆盖正向和负向场景\n2. 包含边界条件和异常情况\n3. 设置明确的成功/失败标准\n4. 提供足够的上下文信息\n\n## 扩展指南\n\n### 添加新指标类型\n\n1. 在 `base_metric.py` 中定义指标接口\n2. 在 `builtin_metrics.py` 中实现默认逻辑\n3. 在 `evaluate.py` 中注册指标处理器\n\n### 集成外部评估服务\n\n```python\nclass ExternalEvaluator:\n async def score(self, input: ScoreInput) -> QuantResult:\n # 调用外部 API\n response = await external_api.evaluate(input)\n return QuantResult(score=response.score, reason=response.reason)\n```\n\n## 总结\n\n评估系统是 ArkSim 实现智能体质量验证的核心基础设施，通过模块化的指标体系、灵活的扩展机制和详细的报告输出，帮助开发者全面了解智能体的表现并进行针对性优化。系统设计遵循可扩展性和易用性原则，既支持开箱即用的内置功能，也支持用户根据业务需求定制专属评估指标。\n\n---\n\n\n\n## LLM提供者集成\n\n### 相关页面\n\n相关主题：[Agent类型与客户端](#page-agent-types), [配置管理](#page-configuration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/llms/chat/providers/openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/openai.py)\n- [arksim/llms/chat/providers/anthropic.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/anthropic.py)\n- [arksim/llms/chat/providers/google.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/google.py)\n- [arksim/llms/chat/providers/azure_openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/azure_openai.py)\n- [arksim/llms/chat/llm.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/llm.py)\n
\n\n# LLM提供者集成\n\n## 概述\n\nArkSim的LLM提供者集成模块为模拟器提供了连接各种大语言模型服务的能力。该模块采用统一抽象的架构设计，将不同LLM提供商的API差异封装在独立的提供者实现中，使上层业务逻辑无需关心底层具体使用的是哪家服务商。\n\nLLM提供者在ArkSim中扮演核心角色，主要用于：\n\n- **用户模拟器（User Simulator）**：基于真实用户行为生成自然对话\n- **评估器（Evaluator）**：分析对话质量并给出评分\n- **自定义代理连接**：支持通过LLM驱动自定义代理行为\n\n资料来源：[arksim/llms/chat/llm.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/llm.py)\n\n## 架构设计\n\n### 整体架构\n\nArkSim的LLM集成采用工厂模式与策略模式相结合的架构：\n\n```mermaid\ngraph TD\n A[调用方] --> B[LLM 抽象层]\n B --> C{Provider Factory}\n C --> D[OpenAI Provider]\n C --> E[Anthropic Provider]\n C --> F[Google Provider]\n C --> G[Azure OpenAI Provider]\n \n H[配置层] --> C\n H --> B\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| LLM 抽象类 | `arksim/llms/chat/llm.py` | 定义通用接口，封装请求/响应处理 |\n| OpenAI Provider | `arksim/llms/chat/providers/openai.py` | OpenAI API及兼容API实现 |\n| Anthropic Provider | `arksim/llms/chat/providers/anthropic.py` | Anthropic Claude API实现 |\n| Google Provider | `arksim/llms/chat/providers/google.py` | Google Gemini API实现 |\n| Azure OpenAI Provider | `arksim/llms/chat/providers/azure_openai.py` | Azure OpenAI服务实现 |\n\n资料来源：[arksim/llms/chat/providers/openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/openai.py)\n\n## 支持的LLM提供者\n\n### OpenAI\n\nOpenAI提供者是最常用的实现，支持标准的Chat Completions API格式。\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | string | 是 | OpenAI API密钥 |\n| `model` | string | 是 | 模型名称（如`gpt-4o`、`gpt-4o-mini`） |\n| `base_url` | string | 否 | API基础URL，支持自定义端点 |\n| `timeout` | int | 否 | 请求超时时间（秒） |\n| `max_retries` | int | 否 | 最大重试次数 |\n\n**使用示例：**\n\n```yaml\nllm:\n provider: openai\n api_key: ${OPENAI_API_KEY}\n model: gpt-4o\n base_url: https://api.openai.com/v1\n```\n\n资料来源：[arksim/llms/chat/providers/openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/openai.py)\n\n### Anthropic\n\nAnthropic提供者用于连接Claude系列模型，支持其特有的消息格式和工具调用能力。\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | string | 是 | Anthropic API密钥 |\n| `model` | string | 是 | 模型名称（如`claude-sonnet-4-20250514`） |\n| `base_url` | string | 否 | API基础URL |\n| `max_tokens` | int | 否 | 最大输出token数 |\n\n**使用示例：**\n\n```yaml\nllm:\n provider: anthropic\n api_key: ${ANTHROPIC_API_KEY}\n model: claude-sonnet-4-20250514\n```\n\n资料来源：[arksim/llms/chat/providers/anthropic.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/anthropic.py)\n\n### Google\n\nGoogle提供者支持Gemini系列模型，适用于需要多模态能力的场景。\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | string | 是 | Google API密钥 |\n| `model` | string | 是 | 模型名称（如`gemini-2.0-flash`） |\n| `base_url` | string | 否 | API基础URL |\n\n资料来源：[arksim/llms/chat/providers/google.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/google.py)\n\n### Azure OpenAI\n\nAzure OpenAI提供者支持企业级部署场景，兼容OpenAI API格式的同时提供Azure特有的安全和管理功能。\n\n**配置参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | string | 是 | Azure API密钥 |\n| `endpoint` | string | 是 | Azure端点URL |\n| `api_version` | string | 是 | API版本（如`2024-02-01`） |\n| `azure_deployment` | string | 是 | 部署名称 |\n\n**使用示例：**\n\n```yaml\nllm:\n provider: azure_openai\n api_key: ${AZURE_OPENAI_API_KEY}\n endpoint: https://your-resource.openai.azure.com\n api_version: \"2024-02-01\"\n azure_deployment: gpt-4o\n```\n\n资料来源：[arksim/llms/chat/providers/azure_openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/azure_openai.py)\n\n## 配置管理\n\n### 环境变量注入\n\nArkSim支持通过环境变量安全地配置敏感信息，避免在配置文件中明文存储密钥。\n\n```yaml\nllm:\n provider: openai\n api_key: ${OPENAI_API_KEY} # 从环境变量读取\n```\n\n### 配置文件结构\n\n完整的模拟器配置通常包含LLM配置和应用配置：\n\n```yaml\nagent_config:\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n\nuser_simulator:\n llm:\n provider: openai\n api_key: ${OPENAI_API_KEY}\n model: gpt-4o\n\nevaluator:\n llm:\n provider: anthropic\n api_key: ${ANTHROPIC_API_KEY}\n model: claude-sonnet-4-20250514\n```\n\n资料来源：[arksim/llms/chat/llm.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/llm.py)\n\n## 请求处理流程\n\n### 统一请求接口\n\n```mermaid\nsequenceDiagram\n participant 调用方\n participant LLM抽象层\n participant Provider\n participant 外部API\n \n 调用方->>LLM抽象层: send_messages(messages, options)\n LLM抽象层->>Provider: send(messages, config)\n Provider->>外部API: HTTP POST\n 外部API-->>Provider: Response\n Provider-->>LLM抽象层: 标准化响应\n LLM抽象层-->>调用方: 返回结果\n```\n\n### 错误处理策略\n\nLLM提供者实现了统一的错误处理机制：\n\n1. **网络错误**：自动重试（可配置重试次数）\n2. **速率限制**：指数退避策略\n3. **认证错误**：抛出明确的认证异常\n4. **模型不可用**：返回友好的错误提示\n\n资料来源：[arksim/llms/chat/providers/openai.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/providers/openai.py)\n\n## 在模拟器中的使用\n\n### 用户模拟器集成\n\n用户模拟器是LLM提供者的主要消费者之一，它使用LLM来生成符合用户画像的对话行为：\n\n```python\nclass UserSimulator:\n def __init__(self, llm_config: dict):\n self.llm = create_llm(llm_config)\n \n async def generate_response(\n self, \n context: dict,\n user_profile: dict\n ) -> str:\n prompt = self._build_prompt(context, user_profile)\n response = await self.llm.chat([{\"role\": \"user\", \"content\": prompt}])\n return response.content\n```\n\n### 评估器集成\n\n评估器使用独立的LLM实例来分析对话质量：\n\n```python\nclass Evaluator:\n def __init__(self, llm_config: dict):\n self.llm = create_llm(llm_config)\n \n async def evaluate(self, conversation: list) -> dict:\n analysis_prompt = self._build_analysis_prompt(conversation)\n result = await self.llm.chat([{\"role\": \"user\", \"content\": analysis_prompt}])\n return self._parse_result(result)\n```\n\n资料来源：[arksim/llms/chat/llm.py](https://github.com/arklexai/arksim/blob/main/arksim/llms/chat/llm.py)\n\n## 扩展自定义提供者\n\n如需集成其他LLM提供者，可以继承基础Provider类：\n\n```python\nfrom arksim.llms.chat.providers.base import BaseProvider\n\nclass CustomProvider(BaseProvider):\n async def chat(self, messages: list, **kwargs) -> ChatResponse:\n # 实现自定义逻辑\n pass\n \n async def completion(self, prompt: str, **kwargs) -> str:\n # 实现自定义逻辑\n pass\n```\n\n注册新提供者只需在Provider工厂中添加对应的创建逻辑即可。\n\n## 最佳实践\n\n### 密钥管理\n\n- 始终使用环境变量存储API密钥\n- 不要将包含密钥的配置文件提交到版本控制系统\n- 使用`.env`文件配合`.gitignore`排除\n\n### 成本控制\n\n- 选择合适的模型大小，避免过度使用高端模型\n- 配置适当的`max_tokens`限制\n- 使用流式响应处理长对话\n\n### 性能优化\n\n- 为长期运行的模拟任务复用LLM实例\n- 合理设置超时时间和重试策略\n- 考虑使用异步调用提高并发能力\n\n## 相关文档\n\n- [CLI命令行工具](../cli.md)\n- [模拟器配置指南](../configuration.md)\n- [自定义代理连接](../custom-agent.md)\n- [评估指标说明](../evaluation-metrics.md)\n\n---\n\n\n\n## Agent类型与客户端\n\n### 相关页面\n\n相关主题：[LLM提供者集成](#page-llm-providers), [配置管理](#page-configuration), [模拟引擎](#page-simulation-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/simulation_engine/agent/clients/chat_completions.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/clients/chat_completions.py)\n- [arksim/simulation_engine/agent/clients/a2a.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/clients/a2a.py)\n- [arksim/simulation_engine/agent/clients/custom.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/clients/custom.py)\n- [arksim/simulation_engine/agent/base.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/agent/base.py)\n
\n\n# Agent类型与客户端\n\n## 概述\n\nArkSim 支持多种 Agent 连接方式，允许用户将不同类型的 AI Agent 接入仿真评估框架。系统通过统一的抽象层，支持自定义 Python 类、Chat Completions API、A2A 协议等多种接入方式。\n\n核心抽象由 `BaseAgent` 基类定义，所有 Agent 实现必须继承该类并实现核心接口方法。\n\n## Agent 类型架构\n\n```mermaid\ngraph TD\n subgraph Agent类型\n Custom[自定义Python类
custom]\n ChatCompletions[Chat Completions API
chat_completions]\n A2A[A2A协议
a2a]\n end\n \n subgraph 核心抽象\n Base[BaseAgent]\n Response[AgentResponse]\n end\n \n Custom --> Base\n ChatCompletions --> Base\n A2A --> Base\n \n Base --> Response\n```\n\n## BaseAgent 抽象基类\n\n`BaseAgent` 是所有 Agent 实现的基础抽象类，定义了 Agent 必须实现的接口规范。\n\n### 核心方法\n\n| 方法名 | 返回类型 | 说明 |\n|--------|----------|------|\n| `get_chat_id()` | `str` | 获取会话唯一标识符 |\n| `execute()` | `str \\| AgentResponse` | 执行用户查询，返回响应内容 |\n\n### AgentResponse 数据结构\n\n用于封装包含工具调用的复杂响应：\n\n```python\nclass AgentResponse(NamedTuple):\n message: str # 助手回复文本\n tool_calls: list[ToolCall] | None # 工具调用列表（可选）\n error: str | None = None # 错误信息（可选）\n```\n\n资料来源：[arksim/simulation_engine/agent/base.py:1-50]()\n\n### 自定义 Agent 实现示例\n\n```python\nfrom arksim.simulation_engine.agent.base import BaseAgent\nfrom arksim.simulation_engine.tool_types import AgentResponse\n\nclass MyAgent(BaseAgent):\n async def get_chat_id(self) -> str:\n return \"unique-id\"\n\n async def execute(self, user_query: str, **kwargs: object) -> str | AgentResponse:\n # 替换为你的 Agent 逻辑\n return \"agent response\"\n```\n\n资料来源：[README.md:1-100]()\n\n## Chat Completions 客户端\n\n`ChatCompletionsAgent` 用于连接支持 OpenAI 兼容 Chat Completions API 的 HTTP 端点。\n\n### 配置参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `endpoint` | `str` | 是 | API 端点 URL，如 `http://localhost:8000/v1/chat/completions` |\n| `api_key` | `str` | 否 | API 密钥认证 |\n| `model` | `str` | 否 | 模型名称 |\n| `timeout` | `int` | 否 | 请求超时时间（秒） |\n| `extra_headers` | `dict` | 否 | 额外 HTTP 请求头 |\n| `extra_body` | `dict` | 否 | 额外请求体参数 |\n\n### YAML 配置示例\n\n```yaml\nagent_config:\n agent_type: chat_completions\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n timeout: 60\n```\n\n### 工作流程\n\n```mermaid\nsequenceDiagram\n participant Simulator\n participant ChatCompletionsClient\n participant HTTPEndpoint\n \n Simulator->>ChatCompletionsClient: execute(user_query)\n ChatCompletionsClient->>HTTPEndpoint: POST /v1/chat/completions\n HTTPEndpoint-->>ChatCompletionsClient: Chat Completion Response\n ChatCompletionsClient-->>Simulator: str | AgentResponse\n```\n\n资料来源：[arksim/simulation_engine/agent/clients/chat_completions.py:1-100]()\n\n## A2A 协议客户端\n\n`A2AAgent` 实现 Agent-to-Agent 协议客户端，用于与支持 A2A 规范的远程 Agent 通信。\n\n### 协议特性\n\n- 支持标准 A2A 协议端点\n- 自动处理 JSON-RPC 格式消息\n- 会话状态管理\n\n### 配置参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `endpoint` | `str` | 是 | A2A Agent 端点 URL，如 `http://localhost:9999/agent` |\n| `agent_id` | `str` | 否 | Agent 标识符 |\n| `timeout` | `int` | 否 | 请求超时时间（秒） |\n\n### YAML 配置示例\n\n```yaml\nagent_config:\n agent_type: a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:9999/agent\n```\n\n资料来源：[arksim/simulation_engine/agent/clients/a2a.py:1-100]()\n\n## 自定义 Agent 客户端\n\n`CustomAgent` 允许用户通过继承 `BaseAgent` 实现自定义逻辑，适用于本地运行的 Agent 或需要深度定制的场景。\n\n### 初始化选项\n\n通过 `arksim init` 命令可自动生成模板：\n\n```bash\narksim init --agent-type custom --force\n```\n\n### 工具调用支持\n\n自定义 Agent 可返回 `AgentResponse` 包含工具调用信息：\n\n```python\nfrom arksim.simulation_engine.tool_types import ToolCall, AgentResponse\n\nasync def execute(self, user_query: str, **kwargs) -> AgentResponse:\n tool_calls = [\n ToolCall(\n id=\"call_1\",\n name=\"get_weather\",\n arguments={\"location\": \"北京\"}\n )\n ]\n return AgentResponse(\n message=\"正在查询天气...\",\n tool_calls=tool_calls\n )\n```\n\n### 追踪集成\n\n支持通过 `ArksimTracingProcessor` 自动捕获工具调用：\n\n> Simulator 设置路由上下文 -> agent.execute() 正常运行 -> SDK 触发 TracingProcessor.on_span_end -> arksim 捕获 -> 评估器评分\n\n资料来源：[arksim/simulation_engine/agent/clients/custom.py:1-100]()\n\n## Agent 类型对比\n\n| 特性 | custom | chat_completions | a2a |\n|------|--------|------------------|-----|\n| 实现方式 | Python 类继承 | HTTP API 调用 | HTTP 协议 |\n| 本地/远程 | 均可 | 远程 | 远程 |\n| 工具调用捕获 | AgentResponse / TracingProcessor | 自动解析 | 自动解析 |\n| 配置复杂度 | 中 | 低 | 低 |\n| 适用场景 | 深度定制、本地 Agent | 标准 API 服务 | A2A 协议 Agent |\n\n## 命令行工具支持\n\n### 初始化命令\n\n```bash\narksim init --agent-type [--force]\n```\n\n支持的 `--agent-type` 选项：\n- `custom`：生成 Python 代理文件（无需服务器）\n- `chat_completions`：HTTP 端点\n- `a2a`：Agent-to-Agent 协议\n\n### CLI 参数说明\n\n| 参数 | 说明 |\n|------|------|\n| `--agent-type` | Agent 连接类型，默认 `custom` |\n| `--force` | 覆盖已存在的文件 |\n\n资料来源：[arksim/cli.py:1-100]()\n\n## 集成示例\n\nArkSim 提供了多种集成示例，演示如何连接不同类型的 Agent：\n\n| 集成项目 | Agent 类型 | 说明 |\n|----------|------------|------|\n| `langchain` | Custom | LangChain/LangGraph 集成 |\n| `langgraph` | Custom | LangGraph 专用集成 |\n| `claude-agent-sdk` | Custom | Claude Agent SDK 集成 |\n| `autogen` | Custom | Microsoft AutoGen 集成 |\n| `rasa` | Chat Completions | Rasa Pro 集成 |\n| `dify` | Custom | Dify 平台集成 |\n| `openclaw` | Chat Completions | OpenClaw 网关集成 |\n\n运行任意集成示例：\n\n```bash\ncd examples/integrations/\narksim simulate-evaluate config.yaml\n```\n\n资料来源：[examples/integrations/langchain/README.md:1-50]()\n资料来源：[examples/integrations/rasa/README.md:1-80]()\n\n## 最佳实践\n\n1. **选择合适的 Agent 类型**：优先使用 `chat_completions` 或 `a2a`，仅在需要深度定制时使用 `custom`\n2. **工具调用返回规范**：自定义 Agent 应返回 `AgentResponse` 包含 `tool_calls` 以支持完整评估\n3. **错误处理**：确保 `execute()` 方法妥善处理异常，返回有意义的错误信息\n4. **会话标识**：实现正确的 `get_chat_id()` 确保多会话场景正确追踪\n\n---\n\n\n\n## 配置管理\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [场景定义与管理](#page-scenarios), [Agent类型与客户端](#page-agent-types)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/config.yaml](https://github.com/arklexai/arksim/blob/main/arksim/config.yaml)\n- [arksim/config_evaluate.yaml](https://github.com/arklexai/arksim/blob/main/arksim/config_evaluate.yaml)\n- [arksim/config_simulate.yaml](https://github.com/arklexai/arksim/blob/main/arksim/config_simulate.yaml)\n- [arksim/config/types.py](https://github.com/arklexai/arksim/blob/main/arksim/config/types.py)\n- [arksim/config/core/agent.py](https://github.com/arklexai/arksim/blob/main/arksim/config/core/agent.py)\n- [arksim/config/utils.py](https://github.com/arklexai/arksim/blob/main/arksim/config/utils.py)\n
\n\n# 配置管理\n\n## 概述\n\nArkSim 的配置管理系统负责定义仿真和评估流程的所有参数，包括代理连接方式、场景文件路径、指标配置、API 端点设置等。该系统采用 YAML 格式的配置文件，支持三种主要运行模式：联合仿真评估、单独仿真和单独评估。配置系统通过 Pydantic 模型实现类型安全的数据验证，确保配置文件的正确性和一致性。\n\nArkSim 的配置架构设计遵循模块化原则，将不同功能领域的配置参数分离到独立的核心模块中。这种设计使得配置管理更加清晰，便于维护和扩展。配置系统支持多种代理类型，包括自定义 Python 类、Chat Completions 接口、A2A 协议等，每种代理类型都有其专属的配置结构。\n\n## 配置架构\n\n### 模块结构\n\nArkSim 的配置系统位于 `arksim/config/` 目录下，采用分层架构设计。核心类型定义集中在 `types.py` 中，提供基础数据模型；代理相关配置在 `core/agent.py` 中定义；通用工具函数位于 `utils.py`。\n\n```mermaid\ngraph TD\n A[config.yaml] --> B[config/types.py - 基础类型]\n A --> C[config/core/agent.py - 代理配置]\n A --> D[config/utils.py - 工具函数]\n B --> E[ConfigLoader]\n C --> F[AgentConfig]\n D --> G[YAML加载和验证]\n```\n\n### 配置加载流程\n\n配置系统通过统一的加载器处理 YAML 配置文件，加载过程包括文件解析、类型验证和默认值填充三个阶段。系统首先读取 YAML 文件内容，然后根据配置类型选择对应的 Pydantic 模型进行数据验证，最后将验证通过的配置对象传递给相应的组件使用。\n\n## 配置文件类型\n\nArkSim 支持三种主要的配置文件类型，分别用于不同的运行场景：\n\n| 配置文件 | 用途 | 关键参数 |\n|---------|------|---------|\n| `config.yaml` | 联合仿真评估 | agent_config、scenarios、metrics |\n| `config_simulate.yaml` | 独立仿真 | agent_config、scenarios |\n| `config_evaluate.yaml` | 独立评估 | agent_config、scenarios_results |\n\n### 联合配置文件 (config.yaml)\n\n完整的仿真评估配置包含所有必要的参数，适用于一次性执行仿真和评估流程。配置文件中需要指定代理设置、场景定义、评估指标和可选的自定义指标。\n\n### 仿真配置文件 (config_simulate.yaml)\n\n仅包含仿真所需的参数，用于生成对话数据而不执行评估。该配置文件适用于调试仿真逻辑或生成特定格式的对话记录。\n\n### 评估配置文件 (config_evaluate.yaml)\n\n仅包含评估所需的参数，用于对已存在的仿真结果进行评分分析。当需要使用不同的评估指标重新分析历史仿真数据时，此配置非常有用。\n\n## 代理配置\n\n代理配置是 ArkSim 配置系统的核心部分，定义了如何连接和交互目标 AI 代理。系统支持多种代理类型，每种类型具有不同的配置结构。\n\n### 代理类型\n\nArkSim 支持以下代理类型：\n\n| 代理类型 | 标识符 | 说明 |\n|---------|--------|------|\n| 自定义 Python 类 | `custom` | 用户实现的 BaseAgent 子类 |\n| Chat Completions | `chat_completions` | OpenAI 风格的 HTTP 接口 |\n| A2A 协议 | `a2a` | Agent-to-Agent 通信协议 |\n\n### 自定义代理配置\n\n自定义代理需要通过 `agent_type: custom` 指定类型，并提供 Python 模块路径和类名：\n\n```yaml\nagent_config:\n agent_type: custom\n agent_name: my-agent\n module: my_agent\n class_name: MyAgent\n```\n\n### Chat Completions 配置\n\nChat Completions 类型代理通过 HTTP 接口调用，需要配置服务端点：\n\n```yaml\nagent_config:\n agent_type: chat_completions\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/v1/chat/completions\n```\n\n资料来源：[README.md]()\n\n### A2A 协议配置\n\nA2A 协议代理同样使用 HTTP 接口，但使用不同的端点路径：\n\n```yaml\nagent_config:\n agent_type: a2a\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:9999/agent\n```\n\n资料来源：[README.md]()\n\n## 场景配置\n\n场景配置定义仿真测试的具体案例，包括用户画像、初始知识状态和预期目标。场景以 JSON 格式存储，通过配置文件中的 `scenarios` 参数引用。\n\n### 场景文件结构\n\n场景文件通常命名为 `scenarios.json`，包含多个测试场景的数组，每个场景定义一个完整的用户交互测试用例。\n\n### 场景加载\n\nArkSim 支持从指定路径加载场景文件：\n\n```yaml\nscenarios: /path/to/scenarios.json\n```\n\nUI 界面提供了场景文件路径输入和浏览功能，支持即时验证文件有效性。\n\n## 指标配置\n\n### 定量指标\n\n定量指标返回 0.0 到 1.0 之间的数值评分，用于衡量代理行为的可量化方面。系统内置多种定量指标，也可通过自定义指标扩展。\n\n### 定性指标\n\n定性指标返回分类标签，如 \"compliant\"、\"flagged\"、\"pass\"、\"fail\" 等。系统根据预设的标签集合判断指标情感方向（正面/负面/中性），用于生成可视化展示。\n\n### 自定义指标\n\n用户可以在 `tests/arksim/custom_metrics/` 目录下创建自定义指标文件，并在配置中引用：\n\n```yaml\ncustom_metrics_file_paths:\n - tests/arksim/custom_metrics/my_metric.py\n\nmetrics_to_run:\n - verification_compliance\n - my_custom_metric\n```\n\n资料来源：[examples/customer-service/custom_metrics.py]()\n\n## 追踪配置\n\nArkSim 支持通过追踪机制自动捕获代理的工具调用，这对于无法直接获取工具调用数据的代理特别有用。\n\n### 追踪接收器配置\n\n```yaml\ntrace_receiver:\n enabled: true\n wait_timeout: 5\n```\n\n当 `trace_receiver.enabled` 设为 `true` 时，系统启用追踪接收器等待模式；`wait_timeout` 定义最大等待时间（秒）。\n\n### 追踪工作流程\n\n```mermaid\ngraph LR\n A[Simulator设置路由上下文] --> B[Agent执行]\n B --> C[SDK触发TracingProcessor]\n C --> D[on_span_end回调]\n D --> E[ArkSim捕获工具调用]\n E --> F[Evaluator评分]\n```\n\n资料来源：[examples/customer-service/README.md]()\n\n## 配置工具函数\n\nArkSim 提供了配置相关的工具函数用于处理 YAML 文件加载、配置合并和参数验证。这些函数位于 `arksim/config/utils.py`，被配置加载器和各组件广泛使用。\n\n### 配置验证\n\n系统通过 Pydantic 模型自动验证配置参数的类型和取值范围，确保配置文件符合预期格式。验证失败时返回详细的错误信息，指出具体的配置项和问题原因。\n\n## 使用示例\n\n### 命令行使用\n\n```bash\n# 联合仿真评估\narksim simulate-evaluate config.yaml\n\n# 单独仿真\narksim simulate config_simulate.yaml\n\n# 单独评估\narksim evaluate config_evaluate.yaml\n```\n\n### Python 脚本使用\n\n```python\nfrom arksim.config.types import Config\nfrom arksim.config.utils import load_config\n\n# 加载配置文件\nconfig = load_config(\"config.yaml\")\n\n# 使用配置执行仿真\nsimulator = Simulator(config)\nresults = await simulator.run()\n```\n\n## 最佳实践\n\n1. **分离配置策略**：对于频繁修改的参数（如 API 端点），建议使用环境变量引用而非硬编码\n2. **场景复用**：将通用场景定义提取为模板，减少重复配置\n3. **自定义指标模块化**：将自定义指标组织在独立目录，便于版本管理和共享\n4. **配置版本控制**：在配置文件中添加注释说明版本和变更历史\n5. **测试配置隔离**：为测试环境创建独立的配置文件，避免影响生产配置\n\n## 相关文件索引\n\n| 文件路径 | 功能描述 |\n|---------|---------|\n| `arksim/config/types.py` | 配置数据模型和类型定义 |\n| `arksim/config/core/agent.py` | 代理配置核心逻辑 |\n| `arksim/config/utils.py` | 配置加载和验证工具 |\n| `examples/customer-service/config.yaml` | 完整配置示例 |\n| `examples/integrations/*/config.yaml` | 各集成场景配置参考 |\n\n---\n\n\n\n## 场景定义与管理\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [配置管理](#page-configuration), [模拟引擎](#page-simulation-engine)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/scenario/entities.py](https://github.com/arklexai/arksim/blob/main/arksim/scenario/entities.py)\n- [arksim/templates/scenarios.json](https://github.com/arklexai/arksim/blob/main/arksim/templates/scenarios.json)\n- [examples/e-commerce/scenarios.json](https://github.com/arklexai/arksim/blob/main/examples/e-commerce/scenarios.json)\n- [examples/customer-service/scenarios.json](https://github.com/arklexai/arksim/blob/main/examples/customer-service/scenarios.json)\n- [arksim/simulation_engine/entities.py](https://github.com/arklexai/arksim/blob/main/arksim/simulation_engine/entities.py)\n
\n\n# 场景定义与管理\n\n## 概述\n\n场景（Scenario）是 ArkSim 仿真评估系统的核心抽象单元，用于定义模拟用户与智能体之间的交互测试用例。每个场景包含用户画像、背景知识、对话目标等关键信息，模拟器基于这些场景生成多轮对话，评估器则根据对话结果计算各项质量指标。\n\n场景定义采用 JSON 格式存储在 `scenarios.json` 文件中，支持批量定义多个测试场景。系统默认每个场景生成 5 次独立对话（可配置），以统计学方式验证智能体行为的一致性和可靠性。\n\n资料来源：[arksim/simulation_engine/entities.py:1-50]()\n\n## 场景数据模型\n\n### 核心场景实体\n\n场景实体定义了测试用例的完整结构，包含用户模拟所需的所有信息：\n\n```json\n{\n \"scenario_id\": \"unique-scenario-identifier\",\n \"user_profile\": {\n \"name\": \"张三\",\n \"age\": 35,\n \"occupation\": \"工程师\",\n \"personality\": \"direct_and_patient\"\n },\n \"knowledge\": {\n \"account_type\": \"高级会员\",\n \"subscription_date\": \"2023-01-15\"\n },\n \"goal\": \"取消当前的订阅服务\",\n \"expected_actions\": [\"verify_identity\", \"confirm_cancellation\", \"offer_alternative\"],\n \"success_criteria\": {\n \"min_score\": 0.8,\n \"required_steps\": [\"身份验证\", \"确认取消\"]\n }\n}\n```\n\n资料来源：[arksim/templates/scenarios.json]()\n\n### 场景属性说明\n\n| 属性 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| `scenario_id` | string | 是 | 场景唯一标识符，用于结果关联 |\n| `user_profile` | object | 是 | 模拟用户的人口统计特征和性格属性 |\n| `knowledge` | object | 是 | 用户知道的背景信息，用于生成自然对话 |\n| `goal` | string | 是 | 用户想要达成的核心目标 |\n| `expected_actions` | array | 否 | 期望智能体执行的关键动作序列 |\n| `success_criteria` | object | 否 | 成功评判的详细标准 |\n\n资料来源：[arksim/scenario/entities.py]()\n\n## 场景结构详解\n\n### 用户画像（User Profile）\n\n用户画像定义了模拟用户的身份特征，影响对话生成的自然度和多样性：\n\n```json\n{\n \"user_profile\": {\n \"name\": \"李明\",\n \"age\": 28,\n \"occupation\": \"软件工程师\",\n \"personality\": \"technical_and_direct\",\n \"communication_style\": \"concise\",\n \"language\": \"中文\"\n }\n}\n```\n\n用户画像支持的性格类型包括：`direct_and_patient`（直接且有耐心）、`technical_and_direct`（技术型直接）、`emotional`（情绪化）、`friendly_chatty`（友好健谈）等。不同性格会影响模拟用户的措辞风格和对话策略。\n\n资料来源：[examples/customer-service/scenarios.json]()\n\n### 背景知识（Knowledge）\n\n背景知识定义用户角色已知的信息，这些信息在对话开始时存在于用户脑海中，但不会主动透露给智能体：\n\n```json\n{\n \"knowledge\": {\n \"account_id\": \"ACC-2024-001\",\n \"account_type\": \"企业版\",\n \"subscription_plan\": \"年付\",\n \"billing_cycle\": \"monthly\",\n \"payment_method\": \"信用卡\",\n \"registered_email\": \"li@example.com\"\n }\n}\n```\n\n知识库中的信息可被智能体通过询问获取，用于验证对话上下文的一致性。\n\n资料来源：[arksim/templates/scenarios.json]()\n\n### 对话目标（Goal）\n\n目标定义模拟用户希望达成的最终结果，是评估目标完成度的主要依据：\n\n```json\n{\n \"goal\": \"将当前套餐从企业版降级为标准版\",\n \"goal_type\": \"service_change\",\n \"constraints\": [\n \"希望在月底前生效\",\n \"不接受销售推销\"\n ]\n}\n```\n\n资料来源：[examples/e-commerce/scenarios.json]()\n\n## 场景管理工作流\n\n### 场景生命周期\n\n```mermaid\ngraph TD\n A[创建 scenarios.json] --> B[场景加载与解析]\n B --> C{语法验证}\n C -->|通过| D[场景预处理]\n C -->|失败| E[返回错误信息]\n D --> F[模拟用户生成]\n F --> G[多轮对话执行]\n G --> H[结果存储]\n H --> I[评估计分]\n I --> J[生成报告]\n```\n\n场景管理遵循标准的三阶段流程：加载验证阶段、模拟执行阶段、评估报告阶段。每个阶段都有明确的输入输出和错误处理机制。\n\n资料来源：[arksim/simulation_engine/entities.py:50-100]()\n\n### 场景配置参数\n\n模拟器通过 `SimulationConfig` 类管理场景执行的全局参数：\n\n| 参数 | 默认值 | 描述 |\n|------|--------|------|\n| `scenarios_file` | - | 场景文件路径（必需） |\n| `num_conversations_per_scenario` | 5 | 每个场景的对话轮次 |\n| `max_turns` | 5 | 单次对话的最大轮数 |\n| `num_workers` | 50 | 并行工作线程数 |\n| `model` | gpt-4o | 用于用户模拟的LLM模型 |\n| `provider` | openai | LLM提供商 |\n\n资料来源：[arksim/simulation_engine/entities.py:20-45]()\n\n### 场景文件验证\n\n系统对场景文件进行多层次验证：\n\n1. **语法验证**：JSON 格式正确性检查\n2. **必填字段验证**：确认 `scenario_id`、`user_profile`、`goal` 等必填字段存在\n3. **类型验证**：各字段类型符合数据模型定义\n4. **一致性验证**：检查 `expected_actions` 中引用的动作是否在知识库中有对应定义\n\n资料来源：[arksim/scenario/entities.py]()\n\n## 场景与评估集成\n\n### 评估指标计算\n\n场景执行完成后，系统根据对话内容计算多维度评估指标：\n\n```json\n{\n \"goal_completion_score\": 0.85,\n \"goal_completion_reason\": \"用户成功取消订阅，但未提供取消确认邮件\",\n \"turn_success_ratio\": 0.92,\n \"final_score\": 0.88,\n \"status\": \"done\",\n \"scores\": [\n {\n \"name\": \"identity_verification\",\n \"value\": 1.0,\n \"reason\": \"正确执行了身份验证流程\"\n }\n ]\n}\n```\n\n评分规则：\n- `final_score = turn_success_ratio × 0.4 + goal_completion_score × 0.6`\n- 状态判定：`done`（1.0）、`partial_failure`（≥0.6）、`failed`（<0.6）\n\n资料来源：[arksim/utils/html_report/report_template.html:80-120]()\n\n### 自定义指标扩展\n\nArkSim 支持通过 `custom_metrics.py` 添加领域特定评估指标：\n\n```python\nclass VerificationComplianceSchema(BaseModel):\n identity_verification: float # 0.0-1.0\n action_gating: float # 0.0-1.0\n reason: str\n```\n\n自定义指标需要实现 `QuantitativeMetric` 或 `QualitativeMetric` 接口，并在 `config.yaml` 中引用。\n\n资料来源：[examples/customer-service/custom_metrics.py]()\n\n## 场景文件最佳实践\n\n### 目录组织结构\n\n建议的场景文件组织方式：\n\n```\nproject/\n├── config.yaml # 仿真评估配置\n├── scenarios.json # 场景定义文件\n├── custom_metrics/ # 自定义指标目录\n│ └── quality_metrics.py\n└── results/ # 输出结果目录\n └── simulation/\n └── simulation.json\n```\n\n### 场景数量建议\n\n| 测试目标 | 推荐场景数 | 每场景对话数 |\n|----------|------------|--------------|\n| 快速验证 | 5-10 | 3 |\n| 标准测试 | 20-50 | 5 |\n| 全面评估 | 100+ | 10 |\n\n### 场景编写规范\n\n1. **唯一性**：`scenario_id` 在同一文件中必须唯一\n2. **具体性**：`goal` 应描述具体、可观测的结果\n3. **多样性**：避免场景之间仅有微小差异\n4. **真实性**：用户画像应符合实际用户分布\n\n资料来源：[examples/customer-service/README.md]()\n\n## 常见问题排查\n\n### 场景加载失败\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `FileNotFoundError` | 路径不正确 | 使用绝对路径或相对于配置文件的路径 |\n| `JSONDecodeError` | JSON 格式错误 | 检查引号、逗号、括号配对 |\n| `ValidationError` | 缺少必填字段 | 对照数据模型补全字段 |\n\n### 模拟结果异常\n\n| 症状 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 所有场景得分偏低 | LLM 模型问题或提示词不当 | 检查 API 配置和模型选择 |\n| 同一场景得分差异大 | 对话随机性过高 | 增加 `num_conversations_per_scenario` |\n| 工具调用未捕获 | 智能体未返回 `AgentResponse` | 确认智能体实现符合接口规范 |\n\n资料来源：[arksim/simulation_engine/tool_types.py:30-50]()\n\n## 相关文档\n\n- [仿真引擎配置指南](./simulation-engine.md)\n- [自定义指标开发](./custom-metrics.md)\n- [评估报告解读](./evaluation-report.md)\n- [集成示例：电商场景](../examples/e-commerce)\n- [集成示例：客服场景](../examples/customer-service)\n\n---\n\n\n\n## Web UI系统\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [arksim/ui/app.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/app.py)\n- [arksim/ui/api/routes_simulate.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/routes_simulate.py)\n- [arksim/ui/api/routes_evaluate.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/routes_evaluate.py)\n- [arksim/ui/api/routes_results.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/routes_results.py)\n- [arksim/ui/api/state.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/state.py)\n- [arksim/ui/api/ws_logs.py](https://github.com/arklexai/arksim/blob/main/arksim/ui/api/ws_logs.py)\n- [arksim/ui/frontend/app.js](https://github.com/arklexai/arksim/blob/main/arksim/ui/frontend/app.js)\n
\n\n# Web UI系统\n\n## 概述\n\nArkSim Web UI系统是项目提供的图形化用户界面，为用户提供了无需编写代码即可创建测试场景、运行模拟仿真和查看评估结果的完整工作流程。该系统采用前后端分离架构，后端基于FastAPI构建异步API服务，前端使用原生JavaScript和Alpine.js实现响应式交互界面。\n\nWeb UI的核心价值在于降低使用门槛，使产品经理、测试工程师等非开发人员也能快速上手使用ArkSim进行AI Agent的质量评估工作。通过直观的可视化界面，用户可以专注于场景设计和结果分析，而无需关心底层的命令行操作细节。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[浏览器] --> B[Web UI 前端]\n B --> C[FastAPI 后端服务]\n C --> D[模拟引擎]\n C --> E[评估引擎]\n C --> F[状态管理]\n D --> G[仿真结果]\n E --> H[评估报告]\n C --> I[WebSocket日志]\n G --> J[结果展示]\n```\n\n### 技术栈\n\n| 层级 | 技术选型 | 说明 |\n|------|---------|------|\n| 前端框架 | Alpine.js | 轻量级响应式JavaScript框架 |\n| UI组件 | Material Icons Outlined | Material Design图标库 |\n| 后端框架 | FastAPI | 现代异步Python Web框架 |\n| 实时通信 | WebSocket | 用于日志流推送 |\n| 状态管理 | 后端状态模块 | API层状态共享 |\n\n## 前端结构\n\n### 文件组织\n\n前端代码位于 `arksim/ui/frontend/` 目录下，采用单文件HTML结构，所有组件和交互逻辑内联在HTML中。这种设计简化了部署复杂度，同时利用Alpine.js的声明式特性实现模块化的页面管理。\n\n### 页面导航系统\n\nWeb UI采用单页面应用（SPA）模式，通过Alpine.js的响应式状态管理实现页面切换。系统支持以下主要页面：\n\n| 页面标识 | 功能描述 | 路由对应 |\n|---------|---------|---------|\n| `build` | 构建测试场景 | 场景编辑页面 |\n| `simulate` | 运行模拟仿真 | 仿真执行页面 |\n| `evaluate` | 执行质量评估 | 评估配置页面 |\n| `results` | 查看结果报告 | 结果展示页面 |\n\n导航状态由Alpine.js的全局状态管理，根据用户操作动态切换。当前激活页面通过 `activePage` 变量控制，导航颜色根据当前页面动态变化：\n\n```javascript\n_navColor(page) {\n // 返回对应页面的导航颜色\n}\n```\n\n### 核心交互组件\n\n#### 结果刷新组件\n\n```html\n\n```\n\n刷新按钮允许用户在仿真或评估完成后重新加载最新的结果数据，无需刷新整个页面即可获取更新。\n\n#### 场景构建页面（Build）\n\n场景构建是测试工作的起点，用户在此页面定义模拟用户的行为模式。页面采用分步骤引导设计：\n\n- **Step 0**：创建测试场景，定义模拟用户与Agent的交互方式\n- **自动生成功能**：提供PRO版本的智能场景生成能力，基于用户描述自动创建测试用例\n\n```html\n
\n auto_awesome\n Auto-generate Scenarios\n PRO\n
\n```\n\n## 后端API设计\n\n### API路由模块\n\n后端API采用模块化设计，按功能职责划分为多个路由文件：\n\n| 路由文件 | 职责范围 |\n|---------|---------|\n| `routes_simulate.py` | 仿真操作相关接口 |\n| `routes_evaluate.py` | 评估操作相关接口 |\n| `routes_results.py` | 结果查询相关接口 |\n\n### 状态管理模块\n\n`state.py` 模块负责管理Web UI运行时的共享状态，包括：\n\n- 当前活跃的仿真任务ID\n- 仿真进度状态\n- 评估指标缓存\n- 配置参数临时存储\n\n```mermaid\ngraph LR\n A[API请求] --> B[State模块]\n B --> C[更新状态]\n C --> D[通知前端]\n D --> E[页面更新]\n```\n\n### WebSocket日志系统\n\n`ws_logs.py` 实现实时日志推送功能，支持：\n\n- 仿真过程日志流式传输\n- 评估进度实时更新\n- 长耗时任务的进度反馈\n\nWebSocket连接在仿真开始时建立，日志数据以JSON格式传输，前端接收后动态渲染到日志面板。\n\n## 数据流设计\n\n### 仿真执行流程\n\n```mermaid\nsequenceDiagram\n 前端->>后端: 启动仿真请求\n 后端->>状态模块: 创建仿真任务\n 状态模块-->>前端: 任务ID\n 前端->>WebSocket: 建立日志连接\n 后端->>模拟引擎: 执行仿真\n 模拟引擎-->>WebSocket: 实时日志\n WebSocket-->>前端: 日志推送\n 模拟引擎->>结果存储: 保存仿真结果\n 结果存储-->>前端: 完成通知\n 前端->>后端: 查询结果\n 后端-->>前端: 结果数据\n```\n\n### 评估流程\n\n评估模块独立于仿真模块运行，支持以下两种模式：\n\n1. **联合模式**：仿真完成后自动触发评估\n2. **独立模式**：手动选择历史仿真结果进行评估\n\n评估结果包含各项质量指标的得分、失败案例分类以及完整的对话记录，便于开发人员定位问题根因。\n\n## 配置管理\n\nWeb UI的配置通过YAML文件管理，主要配置项包括：\n\n| 配置项 | 说明 | 默认值 |\n|-------|------|-------|\n| `agent_config` | Agent连接配置 | - |\n| `scenarios` | 测试场景定义 | - |\n| `metrics` | 评估指标列表 | - |\n| `trace_receiver` | 追踪接收器配置 | `{enabled: false}` |\n\n### 追踪接收器配置\n\n对于支持追踪功能的Agent，配置启用追踪接收器：\n\n```yaml\ntrace_receiver:\n enabled: true\n wait_timeout: 5\n```\n\n当 `enabled` 为 `true` 时，系统会从 `TracingProcessor.on_span_end` 事件中自动捕获工具调用，替代传统的 `AgentResponse` 方式。\n\n## 前端状态管理\n\n前端使用Alpine.js的 `data` 属性定义全局状态对象：\n\n```javascript\ndata() {\n return {\n activePage: 'build',\n results: [],\n logs: [],\n isRunning: false\n }\n}\n```\n\n### 状态变量说明\n\n| 变量名 | 类型 | 用途 |\n|-------|------|-----|\n| `activePage` | string | 当前激活的页面标识 |\n| `results` | array | 仿真/评估结果缓存 |\n| `logs` | array | WebSocket接收的日志 |\n| `isRunning` | boolean | 任务执行状态标志 |\n\n## 页面功能详解\n\n### 结果页面（Results）\n\n结果页面提供仿真和评估结果的完整展示，采用卡片式布局：\n\n- **评分卡片**：展示各维度的质量得分\n- **失败分类**：按问题类型组织失败案例\n- **对话查看器**：完整展示每轮交互的输入输出\n\n页面顶部的刷新按钮触发 `refreshResults()` 函数，该函数调用后端API获取最新结果并更新前端状态。\n\n### 仿真页面（Simulate）\n\n仿真页面是执行测试的核心界面，主要功能包括：\n\n- 配置仿真参数\n- 启动/停止仿真任务\n- 实时查看仿真日志\n- 监控仿真进度\n\n### 评估页面（Evaluate）\n\n评估页面允许用户：\n\n- 选择要评估的仿真结果\n- 配置评估指标\n- 调整评估阈值\n- 查看详细评估报告\n\n## 部署与启动\n\n### 启动命令\n\n```bash\narksim web\n```\n\n该命令启动FastAPI服务器并自动打开浏览器访问Web UI界面。\n\n### 环境要求\n\n- Python 3.10+\n- 浏览器支持ES6+\n- 网络访问（用于加载外部资源）\n\n## 扩展机制\n\n### 自定义Agent集成\n\nWeb UI支持通过配置文件集成自定义Agent：\n\n```yaml\nagent_config:\n agent_type: custom\n agent_name: my-agent\n api_config:\n endpoint: http://localhost:8000/agent\n```\n\n### 自定义评估指标\n\n用户可在 `custom_metrics/` 目录下添加自定义评估逻辑，系统会自动加载并应用到评估流程中。\n\n## 相关资源\n\n- 用户指南：查看[主README](../README.md)了解基本用法\n- 集成示例：参考[examples目录](../../examples/)下的完整案例\n- 配置参考：[配置文件格式说明](#配置管理)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：arklexai/arksim\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium\n\n## 6. 维护坑 · 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 | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：arklexai/arksim\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | no_demo; severity=medium\n\n## 6. 维护坑 · 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 | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_e3064c2689144cfb89a534e0544c6bfc | https://github.com/arklexai/arksim#readme | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# arksim - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 arksim 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：chatgpt\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. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-simulation-engine：模拟引擎。围绕“模拟引擎”模拟一次用户任务，不展示安装或运行结果。\n5. page-evaluator：评估系统。围绕“评估系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-simulation-engine\n输入：用户提供的“模拟引擎”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-evaluator\n输入：用户提供的“评估系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-simulation-engine：Step 4 必须围绕“模拟引擎”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-evaluator：Step 5 必须围绕“评估系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/arklexai/arksim#readme\n- .claude/skills/draft-pr/SKILL.md\n- .claude/skills/pre-review/SKILL.md\n- .claude/skills/review-pr/SKILL.md\n- README.md\n- pyproject.toml\n- arksim/__init__.py\n- arksim/cli.py\n- arksim/templates/config.yaml\n- arksim/templates/scenarios.json\n- arksim/templates/my_agent.py\n- arksim/simulation_engine/simulator.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 arksim 的核心服务。\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", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：arklexai/arksim\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install arksim\n```\n\n来源：https://github.com/arklexai/arksim#readme\n\n## 来源\n\n- docs: https://github.com/arklexai/arksim#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_3536c77cf68640e68b2a7b029788aeed" }