{
"canonical_name": "DemonDamon/AgenticX",
"compilation_id": "pack_aabf1d28e5c14b81b0278606e2b19ec7",
"created_at": "2026-05-19T05:52:00.589865+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, 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 agenticx` 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 agenticx",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_c879bd41d9194243941a50afa9b0e769"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_10664917b90daebeb1ac7d56c8cc7065",
"canonical_name": "DemonDamon/AgenticX",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/DemonDamon/AgenticX",
"slug": "agenticx",
"source_packet_id": "phit_ab196eb24d234d88af39725564427ead",
"source_validation_id": "dval_a033e96109b941659a17d833e0697cac"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 16,
"github_stars": 119,
"one_liner_en": "AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).",
"one_liner_zh": "AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "AgenticX",
"title_zh": "AgenticX 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-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_ab196eb24d234d88af39725564427ead",
"page_model": {
"artifacts": {
"artifact_slug": "agenticx",
"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 agenticx",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/DemonDamon/AgenticX#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"多角色协作流程",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat)."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Desktop app fails on startup: agx serve failed to start (local API not available)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_4330954394974f1ab2f82c8645e1dce9 | https://github.com/DemonDamon/AgenticX/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：AgenticX + Machi v0.3.7",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f4983001c0714fbe923df9e3263934b3 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：AgenticX + Machi v0.3.7",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_026abb56e0864ba4b60ba497e1a19084 | https://github.com/DemonDamon/AgenticX/issues/14 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Machi launch failure on mac",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_1f85a307f6b44099b52dfdb50d13f91c | https://github.com/DemonDamon/AgenticX/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Machi launch failure on mac",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_170a543fa1d640b7a6c9c54d5b9ce6c1 | https://github.com/DemonDamon/AgenticX/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_2d8c2ce59a394bd8901a52ddaf36f821 | https://github.com/DemonDamon/AgenticX/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | 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 | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.5",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_c05bccba0b02475cb74b550d42c91222 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：AgenticX v0.3.5",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.6",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_619eaf3ee1334cb6bc5db5adb67b7c8f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：AgenticX v0.3.6",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.8",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_3c0dad4f133a4a199f8b54083f16427f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：AgenticX v0.3.8",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bash_exec fails to run any command on Windows (WinError 2)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_14230559f63c4fd8a7a8d1310b6284d0 | https://github.com/DemonDamon/AgenticX/issues/7 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：bash_exec fails to run any command on Windows (WinError 2)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：添加模型不支持codex 认证方式",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_b24824ec7b6e4e7fa6bc5b7b2874817c | https://github.com/DemonDamon/AgenticX/issues/4 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：添加模型不支持codex 认证方式",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 2,
"forks": 16,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 119
},
"source_url": "https://github.com/DemonDamon/AgenticX",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).",
"title": "AgenticX 能力包",
"trial_prompt": "# AgenticX - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for DemonDamon/AgenticX.\n\nProject:\n- Name: AgenticX\n- Repository: https://github.com/DemonDamon/AgenticX\n- Summary: AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to AgenticX. Produce one small intermediate artifact and wait for confirmation.\n2. page-quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-installation: Installation Guide. Produce one small intermediate artifact and wait for confirmation.\n4. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n5. page-core-abstractions: Core Abstractions. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/DemonDamon/AgenticX\n- https://github.com/DemonDamon/AgenticX#readme\n- agenticx/skills/agenticx-a2a-connector/SKILL.md\n- agenticx/skills/agenticx-agent-builder/SKILL.md\n- agenticx/skills/agenticx-automation-crontask/SKILL.md\n- agenticx/skills/agenticx-deployer/SKILL.md\n- agenticx/skills/agenticx-memory-architect/SKILL.md\n- agenticx/skills/agenticx-quickstart/SKILL.md\n- agenticx/skills/agenticx-skill-manager/SKILL.md\n- agenticx/skills/agenticx-tool-creator/SKILL.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Desktop app fails on startup: agx serve failed to start (local API not a（https://github.com/DemonDamon/AgenticX/issues/2）；github/github_issue: MCP will report an error upon startup: \"[Errno 2] No such file or direct（https://github.com/DemonDamon/AgenticX/issues/14）；github/github_issue: Machi launch failure on mac（https://github.com/DemonDamon/AgenticX/issues/13）；github/github_issue: Windows: Document ingestion fails for PDF files (missing PDF reader libs（https://github.com/DemonDamon/AgenticX/issues/10）；github/github_issue: UX: Cannot queue follow-up messages while `bash_exec` (or tool) is runni（https://github.com/DemonDamon/AgenticX/issues/8）；github/github_issue: bash_exec fails to run any command on Windows (WinError 2)（https://github.com/DemonDamon/AgenticX/issues/7）；github/github_issue: 添加模型不支持codex 认证方式（https://github.com/DemonDamon/AgenticX/issues/4）；github/github_release: AgenticX v0.3.8（https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.8）；github/github_release: AgenticX + Machi v0.3.7（https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7）；github/github_release: AgenticX v0.3.6（https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.6）；github/github_release: AgenticX v0.3.5（https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.5）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Desktop app fails on startup: agx serve failed to start (local API not a",
"url": "https://github.com/DemonDamon/AgenticX/issues/2"
},
{
"kind": "github_issue",
"source": "github",
"title": "MCP will report an error upon startup: \"[Errno 2] No such file or direct",
"url": "https://github.com/DemonDamon/AgenticX/issues/14"
},
{
"kind": "github_issue",
"source": "github",
"title": "Machi launch failure on mac",
"url": "https://github.com/DemonDamon/AgenticX/issues/13"
},
{
"kind": "github_issue",
"source": "github",
"title": "Windows: Document ingestion fails for PDF files (missing PDF reader libs",
"url": "https://github.com/DemonDamon/AgenticX/issues/10"
},
{
"kind": "github_issue",
"source": "github",
"title": "UX: Cannot queue follow-up messages while `bash_exec` (or tool) is runni",
"url": "https://github.com/DemonDamon/AgenticX/issues/8"
},
{
"kind": "github_issue",
"source": "github",
"title": "bash_exec fails to run any command on Windows (WinError 2)",
"url": "https://github.com/DemonDamon/AgenticX/issues/7"
},
{
"kind": "github_issue",
"source": "github",
"title": "添加模型不支持codex 认证方式",
"url": "https://github.com/DemonDamon/AgenticX/issues/4"
},
{
"kind": "github_release",
"source": "github",
"title": "AgenticX v0.3.8",
"url": "https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.8"
},
{
"kind": "github_release",
"source": "github",
"title": "AgenticX + Machi v0.3.7",
"url": "https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7"
},
{
"kind": "github_release",
"source": "github",
"title": "AgenticX v0.3.6",
"url": "https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.6"
},
{
"kind": "github_release",
"source": "github",
"title": "AgenticX v0.3.5",
"url": "https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.5"
}
],
"status": "已收录 11 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).",
"effort": "安装已验证",
"forks": 16,
"icon": "link",
"name": "AgenticX 能力包",
"risk": "可发布",
"slug": "agenticx",
"stars": 119,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"多角色协作流程",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/DemonDamon/AgenticX 项目说明书\n\n生成时间：2026-05-15 23:21:36 UTC\n\n## 目录\n\n- [Introduction to AgenticX](#page-introduction)\n- [Quick Start Guide](#page-quickstart)\n- [Installation Guide](#page-installation)\n- [System Architecture](#page-architecture)\n- [Core Abstractions](#page-core-abstractions)\n- [Agent Core System](#page-agent-core)\n- [Meta-Agent and Team Management](#page-meta-agent)\n- [Tool System and MCP Hub](#page-tool-system)\n- [Memory System](#page-memory-system)\n- [Avatar and Group Chat](#page-avatar-system)\n\n\n\n## Introduction to AgenticX\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Quick Start Guide](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md)\n- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n- [desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n- [enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/departments/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/departments/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)\n- [enterprise/apps/admin-console/src/app/admin/models/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx)\n- [enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n \n\n# Introduction to AgenticX\n\n## Overview\n\nAgenticX is a comprehensive multi-platform AI agent framework designed to enable intelligent autonomous agents (\"分身\", \"avatars\") capable of executing complex tasks across enterprise and desktop environments. The framework provides a unified architecture for building, deploying, and managing AI agents with built-in support for skill management, task automation, knowledge bases, and enterprise identity & access management (IAM).\n\n资料来源：[enterprise/features/agents/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n资料来源：[examples/agenticx-for-agentkit/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n## Platform Architecture\n\nAgenticX consists of three primary deployment surfaces:\n\n| Platform | Purpose | Key Components |\n|----------|---------|----------------|\n| **Enterprise Admin Console** | Centralized administration for organizations | User Management, Role Management, Department Hierarchy, Audit Logs, Model Configuration |\n| **Enterprise Web Portal** | User-facing authentication and portal access | OAuth/Auth integration, Apache 2.0 licensed, ISO27001 & SOC2 compliant |\n| **Desktop Application** | Local agent execution and management | Task Automation, Settings Panel, Skill Management, WeChat Integration |\n\n资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Architecture Diagram\n\n```mermaid\ngraph TD\n subgraph Enterprise[\"Enterprise Layer\"]\n A[Admin Console] --> B[IAM System]\n A --> C[Audit Logs]\n A --> D[Model Management]\n B --> E[Users]\n B --> F[Roles]\n B --> G[Departments]\n end\n \n subgraph Desktop[\"Desktop Layer\"]\n H[Desktop App] --> I[Skill Manager]\n H --> J[Task Automation]\n H --> K[Settings Panel]\n H --> L[WeChat Integration]\n end\n \n subgraph Integration[\"External Integrations\"]\n M[Volcano Engine]\n N[AgentKit]\n O[Knowledge Base]\n end\n \n Desktop --> Integration\n Enterprise --> Desktop\n```\n\n## Core Components\n\n### 1. Agent Feature Module\n\nThe agent feature (`@agenticx/feature-agents`) provides the core agentic capabilities for creating intelligent avatars (\"分身\") that can autonomously execute tasks.\n\n资料来源：[enterprise/features/agents/README.md:5](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n### 2. Knowledge Base Feature\n\nThe knowledge base module (`@agenticx/feature-knowledge-base`) enables agents to access and utilize structured information repositories for enhanced decision-making.\n\n资料来源：[enterprise/features/knowledge-base/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n\n### 3. Task Automation System\n\nThe desktop application supports automated task execution with configurable prompts, workspace assignments, and model selection.\n\n| Property | Description |\n|----------|-------------|\n| `task.enabled` | Boolean flag to enable/disable automation |\n| `task.prompt` | Custom prompt instructions for the agent |\n| `task.workspace` | Designated workspace path for task execution |\n| `task.provider` | AI provider identifier (e.g., openai, volcengine) |\n| `task.model` | Specific model to use for execution |\n| `task.lastRunAt` | Timestamp of last execution |\n| `task.lastRunStatus` | Execution result: `success` or `error` |\n\n资料来源：[desktop/src/components/automation/TaskList.tsx:10](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n\n### 4. Settings Management\n\nThe desktop application provides comprehensive settings management including:\n\n- **Provider Configuration**: API keys and model selection\n- **Environment Dependencies**: External executable management with installation states (installed, installing, manual_required, not_installed)\n- **Global Tool Paths**: Third-party tool scanning configuration\n- **WeChat Integration**: Personal WeChat binding via iLink protocol\n- **GWS Studio Configuration**: Gateway studio base URL settings\n\n资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n资料来源：[desktop/src/store.ts:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n## Enterprise Identity & Access Management (IAM)\n\n### User Management\n\nThe admin console provides comprehensive user management with the following capabilities:\n\n- User search by email, name, or ID\n- Status filtering (active/inactive/all)\n- Department filtering\n- Pagination with configurable page size\n- User detail drawer with edit capabilities\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/users/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)\n\n### Role Management\n\nRole-based access control with scope matrix editor for granular permission configuration:\n\n```mermaid\ngraph LR\n A[Role] --> B[Code]\n A --> C[Display Name]\n A --> D[Permissions/Scopes]\n D --> E[audit:read]\n D --> F[users:manage]\n D --> G[models:configure]\n D --> H[roles:admin]\n```\n\n| Role Operation | Description |\n|----------------|-------------|\n| Create Role | Define new role with code, name, and scope matrix |\n| Edit Role | Modify existing role properties and permissions |\n| Duplicate Role | Copy existing role configuration |\n| Manage Members | View and manage users assigned to specific roles |\n| Role Removal | PATCH update member's role codes when removed |\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n\n### Department Hierarchy\n\nHierarchical organizational structure with the following features:\n\n- Tree-based department navigation\n- Drill-down navigation with breadcrumb trail\n- Export department structure functionality\n- Refresh capabilities for real-time updates\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/departments/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/departments/page.tsx)\n\n### Bulk Import\n\nCSV-based bulk user provisioning with a 5-step workflow:\n\n1. **Upload CSV** - Drag & drop or paste CSV content\n2. **Column Mapping** - Map CSV columns to system fields\n3. **Pre-check** - Validate data integrity and constraints\n4. **Server Write** - Batch write to backend with transaction support\n5. **Results** - Success/failure reporting with downloadable failure CSV\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)\n\n## Audit & Compliance\n\n### Audit Log System\n\nComprehensive audit logging with table chain verification:\n\n- Event type filtering\n- User and model search\n- Full table chain validation status\n- Chain integrity indicators (complete/failed)\n- Scanned row counts\n\n| Verification Status | Badge Color | Description |\n|--------------------|-------------|-------------|\n| Chain Complete | Success (Green) | Full table chain validation passed |\n| Chain Failed | Destructive (Red) | Validation failed with reason |\n| Loading | Warning (Yellow) | Validation in progress |\n\n资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n\n### Security Compliance\n\nThe enterprise portal demonstrates commitment to security standards:\n\n- Apache 2.0 License\n- ISO27001 Certification\n- SOC2 Compliance\n\n资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n\n## Model Management\n\nThe admin console provides centralized model configuration:\n\n- **Provider Management**: Add/remove AI providers\n- **Model Registration**: Add models with custom IDs and display labels\n- **Provider Templates**: Pre-configured provider templates for quick setup\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| Model ID | Provider-specific model identifier | `gpt-4o-mini`, `qwen-plus` |\n| Display Name | Human-readable label | \"GPT-4o Mini (Fast)\" |\n| Provider | Parent provider configuration | volcengine, openai |\n\n资料来源：[enterprise/apps/admin-console/src/app/admin/models/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx)\n\n## External Integrations\n\n### AgentKit Integration\n\nAgenticX supports integration with LangChain's AgentKit framework for Volcano Engine deployment:\n\n```bash\n# Deployment workflow\nagx volcengine deploy --region --app-name \nagx volcengine logs [--follow]\nagx volcengine destroy\n```\n\nThe integration includes:\n\n- Complete agent definition templates\n- Docker deployment configurations\n- Synchronous and asynchronous testing support\n- Tool definition examples\n\n资料来源：[examples/agenticx-for-agentkit/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n### WeChat Integration\n\nDesktop application supports personal WeChat binding via the official iLink protocol:\n\n- QR code scanning for account binding\n- Automatic sidecar service management\n- Message relay to Machi agent for agent execution\n\n资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Skill Management\n\nSkills extend agent capabilities through modular configurations:\n\n| Skill Source | Location | Description |\n|--------------|----------|-------------|\n| Global Skills | System-wide | Shared across all agent instances |\n| Project Skills | `.agents/skills/` | Project-specific skill definitions |\n| Third-party Skills | Custom scan paths | External skill repositories |\n| SKILL.md | Configuration files | Standard skill definition format |\n\n| Installation State | Badge | Description |\n|-------------------|-------|-------------|\n| Installed | Emerald | Green badge, globally available |\n| Installing | Muted | In progress, non-blocking |\n| Manual Required | Warning | User action needed |\n| Not Installed | Default | Available for installation |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n资料来源：[desktop/src/components/automation/TaskList.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n\n## State Management\n\nThe desktop application uses a centralized store architecture:\n\n```mermaid\ngraph TD\n A[Global Store] --> B[Chat Panes]\n A --> C[Agent Management]\n A --> D[Settings State]\n A --> E[Token Dashboard]\n A --> F[Confirmation Dialogs]\n \n B --> B1[Messages]\n B --> B2[Session History]\n B --> B3[Context Inheritance]\n \n C --> C1[Sub Agents]\n C --> C2[Selected Agent]\n \n D --> D1[Provider Config]\n D --> D2[Model Config]\n D --> D3[API Keys]\n```\n\nKey store functions:\n\n- `addSubAgent` / `removeSubAgent` - Agent lifecycle management\n- `setSelectedSubAgent` - Active agent switching\n- `openSettings` / `updateSettings` - Configuration management\n- `openTokenDashboard` - Usage monitoring\n- `openConfirm` / `closeConfirm` - User confirmation workflow\n\n资料来源：[desktop/src/store.ts:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Installation Guide](#page-installation), [Agent Core System](#page-agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n- [examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n- [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md)\n- [enterprise/features/tools-mcp/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/tools-mcp/README.md)\n \n\n# Quick Start Guide\n\nAgenticX is a multi-agent collaboration framework that enables intelligent agents (referred to as \"分神\" or avatars) to work together using various collaboration patterns. This guide provides a streamlined path to getting started with AgenticX for development and deployment.\n\n## Prerequisites\n\nBefore you begin, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details |\n|-------------|-----------------|\n| Python | 3.10+ |\n| Package Manager | pip or uv |\n| API Keys | Provider-specific (OpenAI, Azure, etc.) |\n| Network | Access to model provider endpoints |\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n## Installation\n\n### Core Package\n\nInstall the AgenticX core package using pip:\n\n```bash\npip install agenticx\n```\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n### Example Dependencies\n\nFor specific integrations, install example-specific requirements:\n\n```bash\npip install -r requirements.txt\n```\n\n## Project Structure\n\nA typical AgenticX project follows this structure:\n\n```\nagenticx-for-intent-recognition/\n├── main.py # Main entry point\n├── config.yaml # Configuration file\n├── requirements.txt # Python dependencies\n├── agents/ # Agent definitions\n├── workflows/ # Workflow definitions\n├── tools/ # Tool implementations\n└── tests/ # Test suite\n```\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n## Configuration\n\n### Step 1: Create Configuration File\n\nCopy the `config.yaml` template and configure your API keys:\n\n```yaml\n# Example config.yaml structure\nprovider: openai\nmodel: gpt-4o-mini\napi_key: your-api-key-here\n```\n\n### Step 2: Adjust Settings\n\nModify configuration parameters based on your requirements:\n\n- **Model Selection**: Choose appropriate models for your use case\n- **API Endpoint**: Configure provider-specific endpoints if needed\n- **Timeout Settings**: Adjust request timeouts for long-running tasks\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n## Building Your First Agent\n\n### Basic Agent Creation\n\nCreate a simple agent using the AgenticX core API:\n\n```python\nfrom agenticx import Agent, AgentConfig\n\nconfig = AgentConfig(\n name=\"demo_agent\",\n model=\"gpt-4o-mini\",\n tools=[\"bash_exec\", \"file_read\"]\n)\n\nagent = Agent(config)\n```\n\n### Agent Patterns\n\nAgenticX supports multiple collaboration patterns. Register custom patterns in the manager:\n\n```python\nfrom agenticx.collaboration import CollaborationMode, CustomPattern\n\npattern_classes = {\n CollaborationMode.CUSTOM_PATTERN: CustomPattern,\n}\n```\n\n资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n\n## Collaboration Patterns\n\nAgenticX provides built-in collaboration modes for multi-agent scenarios:\n\n```mermaid\ngraph TD\n A[User Request] --> B[Manager Agent]\n B --> C[Sub-Agent 1]\n B --> D[Sub-Agent 2]\n B --> E[Sub-Agent N]\n C --> F[Result Aggregation]\n D --> F\n E --> F\n F --> G[Final Response]\n \n style B fill:#e1f5fe\n style F fill:#fff3e0\n```\n\n### Available Patterns\n\n| Pattern | Use Case | Complexity |\n|---------|----------|------------|\n| Sequential | Ordered task execution | Low |\n| Parallel | Concurrent independent tasks | Medium |\n| Hierarchical | Manager-subordinate coordination | High |\n| Custom | Domain-specific collaboration logic | Variable |\n\n资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n\n## Enterprise Features\n\nThe enterprise edition extends AgenticX with additional capabilities:\n\n### Available Feature Modules\n\n| Module | Package | Purpose |\n|--------|---------|---------|\n| Agents | `@agenticx/feature-agents` | Avatar management and configuration |\n| Knowledge Base | `@agenticx/feature-knowledge-base` | Document indexing and retrieval |\n| Identity & Access | `@agenticx/feature-iam` | Tenant, department, role, and permission management |\n| MCP Tools | `@agenticx/feature-tools-mcp` | MCP protocol integration for tool access |\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md), [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md), [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md), [enterprise/features/tools-mcp/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/tools-mcp/README.md)\n\n### Feature Module Usage\n\n```tsx\nimport { featureName } from \"@agenticx/feature-agents\";\n```\n\n## CLI Commands\n\nAgenticX provides a command-line interface for common operations:\n\n| Command | Description |\n|---------|-------------|\n| `agx init` | Initialize a new project |\n| `agx serve` | Start the AgenticX server |\n| `agx deploy` | Deploy to cloud providers |\n| `agx logs [--follow]` | View engine logs |\n| `agx destroy` | Clean up deployed resources |\n\n### Deployment Example (Volcengine)\n\n```bash\nagx volcengine deploy # Deploy to Volcengine\nagx logs --follow # Monitor deployment\nagx volcengine destroy # Clean up resources\n```\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n## Running the Project\n\nExecute your AgenticX application:\n\n```bash\npython main.py\n```\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n## Testing\n\n### Running Tests\n\nExecute the test suite to validate your implementation:\n\n```bash\npytest tests/\n```\n\n### Test Structure\n\nOrganize tests following the project structure:\n\n```\ntests/\n├── test_agents.py # Agent behavior tests\n├── test_workflows.py # Workflow execution tests\n└── test_integration.py # End-to-end integration tests\n```\n\n## Deployment\n\n### Docker Deployment\n\nThe project includes Dockerfile support for containerized deployment:\n\n```dockerfile\n# Refer to examples/agenticx-for-agentkit/hi-agent/Dockerfile\n```\n\n### Cloud Deployment\n\n1. Configure cloud provider credentials\n2. Run deployment command:\n ```bash\n agx volcengine deploy\n ```\n3. Monitor logs:\n ```bash\n agx logs --follow\n ```\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n## Next Steps\n\n| Resource | Description |\n|----------|-------------|\n| [Project Homepage](https://github.com/DemonDamon/AgenticX) | Main repository and documentation |\n| [Collaboration Patterns Paper](https://arxiv.org/abs/2501.06322) | Academic paper on multi-agent collaboration |\n| [Volcengine Integration](../agenticx/integrations/agentkit/) | Cloud-specific integration source |\n| [Project Templates](../agenticx/cli/templates/volcengine/) | Deployment configuration templates |\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Import errors | Ensure `agenticx` is installed: `pip install agenticx` |\n| API key errors | Verify credentials in `config.yaml` |\n| Timeout errors | Increase timeout values in configuration |\n| Deployment failures | Check cloud provider credentials and quotas |\n\n### Getting Help\n\nFor additional support:\n- Open an issue on [GitHub](https://github.com/DemonDamon/AgenticX/issues)\n- Consult the project documentation\n- Review the collaboration patterns academic paper\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)\n- [pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml)\n- [desktop/src/global.d.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/global.d.ts)\n- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n \n\n# Installation Guide\n\n## Overview\n\nThe Installation Guide provides comprehensive instructions for setting up the AgenticX environment across different deployment scenarios. AgenticX is a monorepo containing enterprise applications, desktop clients, and backend services that require specific configuration and dependency management.\n\n## System Architecture Overview\n\n```graph TD\n A[AgenticX Monorepo] --> B[Python Backend Core]\n A --> C[Enterprise Applications]\n A --> D[Desktop Client]\n B --> E[API Services]\n B --> F[Agent Engine]\n C --> G[Admin Console]\n C --> H[Web Portal]\n D --> I[Settings Panel]\n D --> J[ChatPane Interface]\n```\n\n## Prerequisites\n\n### System Requirements\n\n| Component | Minimum Version | Recommended |\n|-----------|-----------------|-------------|\n| Python | 3.11+ | 3.12+ |\n| Node.js | 18.0+ | 20.x LTS |\n| npm/yarn | 9.0+ | Latest stable |\n| Git | 2.30+ | Latest |\n\n### External Dependencies\n\nThe desktop application requires several external executable dependencies that can be installed globally once and shared across all instances.\n\n```graph TD\n A[External Tools] --> B[Python Packages]\n A --> C[Node.js Packages]\n A --> D[System Binaries]\n B --> E[adalflow]\n B --> F[agenticx-core]\n D --> G[agx CLI Tool]\n```\n\n资料来源：[pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml)\n\n## Python Package Installation\n\n### Project Structure\n\nThe Python backend uses Poetry for dependency management with the following key packages:\n\n| Package | Purpose | Version Constraint |\n|---------|---------|---------------------|\n| adalflow | Core AI framework | ^0.3.0 |\n| agenticx-core | Main agent engine | Internal |\n| pydantic | Data validation | ^2.0 |\n| fastapi | API framework | ^0.100.0 |\n| uvicorn | ASGI server | ^0.23.0 |\n\n### Installation Commands\n\n```bash\n# Clone the repository\ngit clone https://github.com/DemonDamon/AgenticX.git\ncd AgenticX\n\n# Install backend dependencies using Poetry\npoetry install\n\n# Or using pip with pyproject.toml\npip install -e .\n```\n\n资料来源：[INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)\n\n### Environment Variables\n\nThe application requires specific environment variables for configuration:\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `AGX_API_BASE` | Backend API endpoint | Yes |\n| `AGX_API_TOKEN` | Authentication token | Yes |\n| `OPENAI_API_KEY` | LLM provider key | Conditional |\n| `ANTHROPIC_API_KEY` | Claude API key | Conditional |\n\n## Enterprise Applications\n\n### Admin Console Setup\n\nThe enterprise admin console is a Next.js application located in `enterprise/apps/admin-console/`.\n\n```mermaid\ngraph LR\n A[Admin Console] --> B[IAM Module]\n A --> C[Models Module]\n A --> D[Audit Module]\n B --> E[Roles Management]\n B --> F[User Bulk Import]\n```\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n\n### Installation Steps\n\n```bash\ncd enterprise/apps/admin-console\n\n# Install dependencies\nnpm install\n\n# Configure environment\ncp .env.example .env.local\n\n# Start development server\nnpm run dev\n```\n\n### Web Portal Setup\n\nThe web portal application provides the public-facing interface.\n\n资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n\n## Desktop Application\n\n### Architecture\n\nThe desktop client provides a native interface for the AgenticX system with the following key components:\n\n```graph TD\n A[Desktop Client] --> B[Settings Panel]\n A --> C[ChatPane]\n A --> D[Task Automation]\n A --> E[Skills Manager]\n A --> F[Token Dashboard]\n \n B --> G[Provider Configuration]\n B --> H[API Base Settings]\n B --> I[Theme Settings]\n \n C --> J[Sub Agents]\n C --> K[History Panel]\n C --> L[Spawns Column]\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Desktop-Specific Installation\n\nThe desktop application requires additional native dependencies and configurations:\n\n#### WeChat Integration Setup\n\nThe desktop client supports WeChat integration via the iLink protocol:\n\n```typescript\ninterface WeChatStatus {\n port: number;\n running: boolean;\n}\n\n// Initialize WeChat sidecar\nconst { port, running } = await window.agenticxDesktop.wechatSidecarPort();\nif (!running) {\n const startRes = await window.agenticxDesktop.wechatSidecarStart();\n sidecarPort = startRes.port;\n}\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n#### Skills Management\n\nThe desktop application includes a skills management system that scans multiple locations:\n\n| Location | Description | Priority |\n|----------|-------------|----------|\n| `.agents/skills/` | Project-local skills | High |\n| Global skills | System-wide shared skills | Medium |\n| Third-party scan | External skill directories | Configurable |\n| Custom paths | User-defined locations | Manual |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Desktop IPC API\n\nThe desktop client exposes a comprehensive IPC API for configuration and skill management:\n\n```typescript\ninterface AgenticXDesktopAPI {\n getSkillSettings(): Promise;\n putSkillSettings(payload: SkillSettingsPayload): Promise;\n refreshSkills(): Promise;\n \n installBundle(args: BundleInstallArgs): Promise;\n uninstallBundle(args: { name: string }): Promise;\n \n installFromRegistry(args: RegistryInstallArgs): Promise;\n searchRegistry(args: { q: string }): Promise;\n}\n```\n\n资料来源：[desktop/src/global.d.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/global.d.ts)\n\n## Advanced Configuration\n\n### Token Dashboard\n\nThe desktop client includes a token usage dashboard with configurable date ranges:\n\n```typescript\ntype TokenDashboardRange = '7d' | '30d' | '90d' | 'custom';\n\ninterface TokenDashboardState {\n range: TokenDashboardRange;\n customFrom?: string;\n customTo?: string;\n}\n```\n\n资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n### Model Provider Configuration\n\nSupport for multiple LLM providers with per-provider configuration:\n\n| Provider | Config Key | Required Field |\n|----------|------------|----------------|\n| OpenAI | `provider` | `apiKey` |\n| Anthropic | `provider` | `apiKey` |\n| Custom | `provider` | `apiBase` + `apiKey` |\n\n### Theme and UI Settings\n\n| Setting | Type | Options |\n|---------|------|---------|\n| Theme Mode | `ThemeMode` | `light`, `dark`, `system` |\n| Theme Color | `ThemeColor` | Various accent colors |\n| Chat Style | `ChatStyle` | `pro`, `lite` |\n\n## Verification and Testing\n\n### Post-Installation Checks\n\nAfter installation, verify the setup using these checks:\n\n1. **Backend Connectivity**: Confirm API base URL is accessible\n2. **Authentication**: Verify token is valid and has required permissions\n3. **Skills Scanning**: Check that skill locations are properly configured\n4. **Bundle Installation**: Test bundle install/uninstall operations\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| API connection failed | Verify `AGX_API_BASE` environment variable |\n| Skills not loading | Check SKILL.md placement in `.agents/skills/` |\n| Bundle install blocked | Acknowledge high-risk warning if appropriate |\n\n## Repository Structure Summary\n\n```\nAgenticX/\n├── enterprise/\n│ ├── apps/\n│ │ ├── admin-console/ # IAM, Models, Audit\n│ │ └── web-portal/ # Public portal\n│ └── ...\n├── desktop/\n│ ├── src/\n│ │ ├── components/ # UI components\n│ │ ├── store.ts # State management\n│ │ └── global.d.ts # Type definitions\n│ └── ...\n├── pyproject.toml # Python dependencies\n└── INSTALL.md # Installation instructions\n```\n\n资料来源：[pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml), [INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Core Abstractions](#page-core-abstractions), [Agent Core System](#page-agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n- [enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)\n- [enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n- [enterprise/apps/web-portal/src/components/WorkspaceShell.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/components/WorkspaceShell.tsx)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n \n\n# System Architecture\n\n## Overview\n\nAgenticX is a comprehensive multi-component AI agent platform designed to enable intelligent automation, multi-agent collaboration, and enterprise-grade management. The system architecture follows a modular design pattern with clear separation between core processing engines, enterprise management interfaces, and client applications.\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n## High-Level Architecture\n\nThe AgenticX platform comprises three primary layers:\n\n1. **Core Engine Layer** — Python-based agent runtime with workflow orchestration\n2. **Enterprise Management Layer** — Web-based admin console and web portal\n3. **Client Application Layer** — Desktop client application\n\n```mermaid\ngraph TB\n subgraph Core[\"Core Engine Layer\"]\n WF[\"Workflow Engine\"]\n AG[\"Agent Core\"]\n MEM[\"Memory System\"]\n KNOW[\"Knowledge Base\"]\n end\n \n subgraph Enterprise[\"Enterprise Management Layer\"]\n AC[\"Admin Console\"]\n WP[\"Web Portal\"]\n IAM[\"IAM System\"]\n end\n \n subgraph Client[\"Client Application Layer\"]\n DESK[\"Desktop App\"]\n UI[\"React Components\"]\n end\n \n DESK --> WF\n AC --> IAM\n WP --> IAM\n WF --> AG\n WF --> MEM\n WF --> KNOW\n```\n\n## Component Architecture\n\n### Core Engine Layer\n\nThe core engine provides the foundational AI agent capabilities including tool execution, memory management, and knowledge retrieval.\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n#### Agent Core\n\nThe Agent Core handles fundamental agent operations:\n\n| Component | Function |\n|-----------|----------|\n| Tool Registry | Discovers and manages available tools |\n| Execution Engine | Processes agent tasks and tool invocations |\n| State Management | Maintains agent conversation state |\n\n#### Workflow Engine\n\nThe workflow engine orchestrates multi-step agent tasks with support for both synchronous and asynchronous execution patterns.\n\n资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n### Enterprise Management Layer\n\nThe enterprise layer provides centralized management capabilities for users, roles, and system configuration.\n\n#### Admin Console\n\nThe Admin Console (`enterprise/apps/admin-console/`) is a Next.js application that provides administrative functions:\n\n- **User Management** — Create, edit, and manage user accounts with search and filtering capabilities\n- **Role Management** — Define roles with granular permission scopes\n- **Audit Logs** — Track system events with chain verification for data integrity\n- **Model Management** — Configure AI provider models\n- **Bulk Operations** — CSV-based bulk user import with pre-validation\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)\n\n```mermaid\ngraph LR\n subgraph AdminConsole[\"Admin Console\"]\n US[\"Users Module\"]\n RL[\"Roles Module\"]\n AU[\"Audit Module\"]\n MD[\"Models Module\"]\n BI[\"Bulk Import Module\"]\n end\n \n US --> IAM[\"IAM Backend\"]\n RL --> IAM\n AU --> IAM\n MD --> IAM\n BI --> IAM\n```\n\n#### Web Portal\n\nThe Web Portal (`enterprise/apps/web-portal/`) serves as the main user interface for end users, providing:\n\n- Authentication services\n- Workspace management\n- Theme and preference settings\n- Multi-language support (Chinese and English)\n- Admin console navigation integration\n\n资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n\n#### Identity and Access Management (IAM)\n\nThe IAM system manages authentication and authorization across the platform:\n\n| Feature | Description |\n|---------|-------------|\n| User Management | Full CRUD operations with email/display name tracking |\n| Role-Based Access Control | Roles with scoped permission matrices |\n| Bulk Import | CSV-based batch operations with pre-check validation |\n| Department Hierarchy | Organizational structure support via `dept_path` |\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)\n\nThe bulk import workflow follows a step-based process:\n\n1. **Upload CSV** — File upload or text paste with automatic parsing\n2. **Column Mapping** — Map CSV columns to system fields\n3. **Pre-check** — Validate all rows before submission\n4. **Execute Import** — Server-side batch write with failure tracking\n5. **Results** — Display success/failure counts with downloadable failure report\n\n### Client Application Layer\n\n#### Desktop Application\n\nThe Desktop Application (`desktop/`) is a React-based client with the following key components:\n\n| Component | Purpose |\n|-----------|---------|\n| SettingsPanel | Configure providers, models, environment tools |\n| TaskList | Manage automated tasks with enable/disable controls |\n| ChatPane | Agent conversation interface |\n| Store | Centralized state management using Zustand |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n```mermaid\ngraph TD\n ST[\"Store (Zustand)\"]\n SP[\"SettingsPanel\"]\n TL[\"TaskList\"]\n CP[\"ChatPane\"]\n \n ST --> SP\n ST --> TL\n ST --> CP\n \n SP --> |\"provider/model\"| ST\n TL --> |\"task toggle\"| ST\n CP --> |\"messages\"| ST\n```\n\n#### State Management\n\nThe desktop application uses Zustand for centralized state management with the following store structure:\n\n| State Category | Key Properties |\n|----------------|----------------|\n| Session | `sessionId`, `userMode`, `theme` |\n| Chat | `messages`, `modelProvider`, `modelName` |\n| Settings | `providers`, `apiKey`, `defaultProvider` |\n| UI | `sidebarCollapsed`, `focusMode`, `commandPaletteOpen` |\n| Tasks | `tasks`, `activeTaskspaceId` |\n\n资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n#### Task Automation\n\nTasks support the following configuration options:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `enabled` | boolean | Toggle task execution |\n| `prompt` | string | Task instruction prompt |\n| `workspace` | string | Working directory path |\n| `provider` | string | AI provider identifier |\n| `model` | string | Model name |\n| `lastRunAt` | timestamp | Last execution time |\n| `lastRunStatus` | enum | `success`, `error` |\n| `lastRunError` | string | Error message if failed |\n\n资料来源：[desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n\n### Feature Modules\n\nEnterprise features are implemented as standalone modules under `enterprise/features/`:\n\n| Module | Description |\n|--------|-------------|\n| `@agenticx/feature-agents` | Multi-agent spawning and management |\n| `@agenticx/feature-knowledge-base` | RAG-based knowledge retrieval |\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n## Integration Architecture\n\n### AgentKit Integration\n\nAgenticX integrates with Volcano Engine's AgentKit for enhanced capabilities:\n\n```\n┌────────────────────────────────────────────────────┐\n│ AgenticX 框架 │\n├─────────────┬────────────┬───────────┬─────────────┤\n│ Agent Core │ Tools │ Memory │ Knowledge │\n└─────────────┴────────────┴───────────┴─────────────┘\n │\n ┌──────────┴───────────┐\n │ AgentKit Integration │\n └──────────┬───────────┘\n │\n ┌────────────────┼────────────────┐\n ▼ ▼ ▼\n┌──────────┐ ┌───────────┐ ┌────────────┐\n│ Ark LLM │ │ Runtime │ │ Bridges & │\n│ Provider │ │ Client │ │ Adapters │\n└──────────┘ └───────────┘ └────────────┘\n```\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n### WeChat Integration\n\nThe desktop application supports WeChat integration via the iLink protocol:\n\n```mermaid\ngraph LR\n WC[\"WeChat Client\"]\n SD[\"Desktop Sidecar\"]\n AG[\"AgenticX Desktop\"]\n \n WC --> |\"iLink Protocol\"| SD\n SD --> AG\n AG --> |\"Agent Execution\"| SD\n```\n\nThe sidecar service manages the WeChat connection with states:\n- `idle` — No active binding\n- `binding` — QR code scanning in progress\n- `connected` — Active WeChat session\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Security Architecture\n\n### Audit Chain Verification\n\nThe audit system implements chain verification to ensure log integrity:\n\n| Status | Description |\n|--------|-------------|\n| `full` | Full table chain verification passed |\n| `valid` | Chain verification in progress |\n| `failed` | Chain verification failed with reason |\n\nEach audit log entry includes a chain signature that can be verified against the full table state.\n\n资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n\n### Role-Based Permissions\n\nRoles use a scope matrix for fine-grained permission control:\n\n- Roles can be assigned multiple permission scopes\n- Users can have multiple roles (role code aggregation)\n- Role membership changes use PATCH operations for atomic updates\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n\n## Deployment Architecture\n\n### Project Templates\n\nAgenticX provides deployment templates for different use cases:\n\n| Template | Command | Use Case |\n|----------|---------|----------|\n| `mcp` | `agx volcengine init --template mcp` | Tool auto-discovery and sharing |\n| `a2a` | `agx volcengine init --template a2a` | Multi-agent collaboration |\n| `knowledge` | `agx volcengine init --template knowledge` | Knowledge base RAG |\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `agx volcengine init` | Initialize new project from template |\n| `agx volcengine logs [--follow]` | View deployment logs |\n| `agx volcengine destroy` | Clean up deployed resources |\n\n## Data Flow\n\n### Bulk Import Flow\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant AC as Admin Console\n participant BE as Backend API\n \n U->>AC: Upload CSV\n AC->>AC: Parse & Display Preview\n U->>AC: Map Columns\n AC->>BE: Pre-check Request\n BE-->>AC: Validation Results\n alt Has Failures\n AC->>U: Display Failure Table\n U->>AC: Fix CSV / Remap\n else All Valid\n AC->>BE: Execute Import\n BE-->>AC: Success/Failure Report\n AC->>U: Show Results\n end\n```\n\n### Task Execution Flow\n\n```mermaid\ngraph TD\n START[\"Task Triggered\"]\n CHECK{\"Task Enabled?\"}\n LOAD[\"Load Task Config\"]\n EXEC[\"Execute Agent\"]\n SUCCESS{\"Success?\"}\n LOG[\"Log Result\"]\n ERR[\"Log Error\"]\n END[\"Complete\"]\n \n START --> CHECK\n CHECK --> |\"No\"| END\n CHECK --> |\"Yes\"| LOAD\n LOAD --> EXEC\n EXEC --> SUCCESS\n SUCCESS --> |\"Yes\"| LOG\n SUCCESS --> |\"No\"| ERR\n LOG --> END\n ERR --> END\n```\n\n## Configuration Management\n\n### Environment Tools\n\nThe system supports external executable dependencies:\n\n| State | Badge | Description |\n|-------|-------|-------------|\n| `installed` | Green | Tool globally installed |\n| `installing` | Blue | Installation in progress |\n| `manual_required` | Orange | User must install manually |\n| `not_installed` | Gray | Not yet installed |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Theme and Localization\n\nThe platform supports dynamic theme switching:\n\n| Theme Mode | Description |\n|------------|-------------|\n| `light` | Light color scheme |\n| `dark` | Dark color scheme |\n| `system` | Follow OS preference |\n\nSupported locales: `zh` (Chinese), `en` (English)\n\n资料来源：[enterprise/apps/web-portal/src/components/WorkspaceShell.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/components/WorkspaceShell.tsx)\n\n---\n\n\n\n## Core Abstractions\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Agent Core System](#page-agent-core), [Tool System and MCP Hub](#page-tool-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/core/agent.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent.py) *(未在上下文中找到)*\n- [agenticx/core/task.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task.py) *(未在上下文中找到)*\n- [agenticx/core/tool.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/tool.py) *(未在上下文中找到)*\n- [agenticx/core/component.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/component.py) *(未在上下文中找到)*\n- [agenticx/core/event_bus.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/event_bus.py) *(未在上下文中找到)*\n- [agenticx/core/message.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/message.py) *(未在上下文中找到)*\n\n**注意**：指定的 Core 模块源文件未出现在本次检索的上下文中。页面基于可见的代码结构和命名约定生成，标注为\"基于推断\"的部分需要后续对照源码验证。\n\n \n\n# Core Abstractions\n\nThe **Core Abstractions** layer is the foundational component system underlying AgenticX's agent framework. It provides the essential building blocks—Agent, Task, Tool, Component, EventBus, and Message—that enable developers to construct autonomous AI agents with configurable behaviors, tool integration, and event-driven communication.\n\n---\n\n## Overview\n\nAgenticX follows a modular, composable architecture where every functional unit is modeled as a first-class abstraction. The core layer defines:\n\n- **Agent** — The primary executor that coordinates tasks, tools, and message handling\n- **Task** — A unit of work with prompts, execution constraints, and state tracking\n- **Tool** — Callable functions and external integrations available to agents\n- **Component** — Reusable building blocks that can be mixed into agents\n- **EventBus** — Publish/subscribe infrastructure for inter-component messaging\n- **Message** — Standardized data structures for agent communication\n\n---\n\n## Architecture Diagram\n\n```mermaid\ngraph TD\n A[User Input] --> B[Agent]\n B --> C[Task Executor]\n B --> D[Tool Registry]\n B --> E[Message Bus]\n \n C --> F[Task]\n F --> G[Prompt Engine]\n \n D --> H[Tool 1]\n D --> I[Tool 2]\n D --> J[Tool N]\n \n E --> K[EventBus]\n K --> L[Component 1]\n K --> M[Component 2]\n \n N[Model Provider] --> B\n O[External Services] --> D\n```\n\n---\n\n## Agent Abstraction\n\nThe `Agent` class is the central coordinator that orchestrates all other abstractions. It manages the execution loop, tool invocations, message history, and component lifecycle.\n\n### Key Responsibilities\n\n| Responsibility | Description |\n|----------------|-------------|\n| Execution Control | Runs the agent loop, handling user prompts and model responses |\n| Tool Management | Maintains a registry of available tools and routes tool calls |\n| Message Handling | Processes incoming messages and maintains conversation history |\n| Component Integration | Loads and coordinates components for extended functionality |\n| State Management | Tracks execution state, errors, and result outputs |\n\n### Agent Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Unique identifier for the agent |\n| `model` | `str` | Model provider/model identifier (e.g., `openai/gpt-4o`) |\n| `provider` | `str` | LLM provider backend |\n| `tools` | `List[Tool]` | List of tools the agent can invoke |\n| `system_prompt` | `str` | Base instructions guiding agent behavior |\n| `max_retries` | `int` | Maximum retry attempts for failed operations |\n\n资料来源：[agenticx/core/agent.py]() *(源码待验证)*\n\n---\n\n## Task Abstraction\n\nTasks represent discrete units of work that an agent can execute. They encapsulate the prompt, execution parameters, and runtime state.\n\n### Task State Machine\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending\n Pending --> Running : start()\n Running --> Success : complete()\n Running --> Failed : error\n Running --> Pending : retry\n Success --> [*]\n Failed --> [*]\n```\n\n### Task Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `prompt` | `str` | The task instruction or question |\n| `workspace` | `Optional[str]` | Working directory or context path |\n| `enabled` | `bool` | Whether the task can execute |\n| `lastRunAt` | `Optional[datetime]` | Timestamp of last execution |\n| `lastRunStatus` | `Optional[str]` | Outcome: `success`, `error` |\n| `lastRunError` | `Optional[str]` | Error message if failed |\n\n资料来源：[desktop/src/components/automation/TaskList.tsx](desktop/src/components/automation/TaskList.tsx) *(前端实现参照)*\n\n---\n\n## Tool Abstraction\n\nTools extend agent capabilities by providing callable functions for external operations. Tools can be local Python functions or remote service integrations.\n\n### Tool Registration Flow\n\n```mermaid\nsequenceDiagram\n participant A as Agent\n participant T as Tool Registry\n participant M as Model\n participant E as External Service\n \n A->>T: Register Tool\n M-->>A: Generate Tool Call\n A->>E: Execute via Tool\n E-->>A: Return Result\n A->>M: Pass Result to Model\n```\n\n### Tool Installation States\n\n| State | Badge | Description |\n|-------|-------|-------------|\n| `installed` | 已安装 | Tool binary present and functional |\n| `installing` | 安装中 | Installation in progress |\n| `manual_required` | 需手动安装 | User must install externally |\n| `not_installed` | 未安装 | Tool not found, can be installed |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](desktop/src/components/SettingsPanel.tsx)\n\n### Registry Tool Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `str` | Tool identifier |\n| `description` | `Optional[str]` | Human-readable description |\n| `enabled` | `bool` | Availability status |\n\n---\n\n## Component Abstraction\n\nComponents are reusable functional units that can be mixed into agents to provide specific capabilities. They communicate via the EventBus and expose lifecycle hooks.\n\n### Component Features\n\n| Feature | Description |\n|---------|-------------|\n| Lifecycle Hooks | `on_init`, `on_start`, `on_stop` methods |\n| Event Subscription | Subscribe to specific event types via EventBus |\n| State Sharing | Components can share state through the agent context |\n\n资料来源：[agenticx/core/component.py]() *(源码待验证)*\n\n---\n\n## EventBus Abstraction\n\nThe EventBus provides a publish/subscribe messaging infrastructure for loose coupling between components.\n\n### Event Flow\n\n```mermaid\ngraph LR\n P[Publisher] -->|emit| EB[EventBus]\n EB -->|dispatch| S1[Subscriber 1]\n EB -->|dispatch| S2[Subscriber 2]\n EB -->|dispatch| SN[Subscriber N]\n```\n\n### Supported Event Types\n\n| Event | Trigger |\n|-------|---------|\n| `agent.start` | Agent execution begins |\n| `agent.complete` | Agent finishes execution |\n| `tool.call` | A tool is invoked |\n| `tool.result` | Tool execution returns |\n| `error` | Any error occurs in the pipeline |\n\n资料来源：[agenticx/core/event_bus.py]() *(源码待验证)*\n\n---\n\n## Message Abstraction\n\nMessages are the standard units of communication between agents, components, and external systems.\n\n### Message Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `role` | `str` | Sender role: `user`, `assistant`, `system`, `tool` |\n| `content` | `str` | Message body |\n| `tool_calls` | `Optional[List]` | Tool invocation metadata |\n| `tool_call_id` | `Optional[str]` | Correlation ID for tool responses |\n| `metadata` | `Optional[Dict]` | Additional contextual data |\n\n资料来源：[agenticx/core/message.py]() *(源码待验证)*\n\n---\n\n## Integration with Enterprise Features\n\nThe core abstractions compose with enterprise-level features:\n\n### Skill System\n\nAgents can be configured with skills—specialized capabilities loaded from:\n- Global skill directory (`.agents/skills/`)\n- Third-party scan paths\n- Custom skill paths\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](desktop/src/components/AvatarCreateDialog.tsx)\n\n### Model Management\n\nThe admin console provides UI for managing model providers and configurations:\n\n| Field | Description |\n|-------|-------------|\n| `id` | Unique provider identifier |\n| `displayName` | Human-readable name |\n| `models` | List of available model IDs |\n\n资料来源：[enterprise/apps/admin-console/src/app/admin/models/page.tsx](enterprise/apps/admin-console/src/app/admin/models/page.tsx)\n\n---\n\n## Quick Start Pattern\n\n```python\nfrom agenticx import Agent, Tool, Message\n\n# Define a custom tool\ncalculator = Tool(\n name=\"calculator\",\n description=\"Perform arithmetic operations\",\n func=compute\n)\n\n# Create an agent\nagent = Agent(\n name=\"math-assistant\",\n model=\"openai/gpt-4o\",\n tools=[calculator],\n system_prompt=\"You are a helpful math assistant.\"\n)\n\n# Execute\nresponse = agent.run(Message(role=\"user\", content=\"What is 2 + 2?\"))\nprint(response.content)\n```\n\n---\n\n## See Also\n\n- [Collaboration Patterns](../collaboration/README.md) — Multi-agent coordination using Core Abstractions\n- [Tool Integration](../integrations/) — Built-in tool adapters\n- [Enterprise IAM](../enterprise/features/iam/) — Access control for agents\n\n---\n\n\n\n## Agent Core System\n\n### 相关页面\n\n相关主题：[Meta-Agent and Team Management](#page-meta-agent), [Tool System and MCP Hub](#page-tool-system), [Memory System](#page-memory-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/core/agent_executor.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent_executor.py)\n- [agenticx/core/self_repair.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/self_repair.py)\n- [agenticx/core/overflow_recovery.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/overflow_recovery.py)\n- [agenticx/core/task_validator.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task_validator.py)\n- [agenticx/core/reflector.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/reflector.py)\n- [agenticx/core/guiderails.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/guiderails.py)\n \n\n# Agent Core System\n\nThe Agent Core System is the central orchestration engine of AgenticX, responsible for executing AI agent tasks, managing execution lifecycle, ensuring safety through guardrails, validating task outputs, handling memory overflow scenarios, enabling self-repair capabilities, and providing reflective analysis of agent behavior.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"Agent Core System\"\n A[Agent Executor] --> B[Task Validator]\n A --> C[Guiderails]\n A --> D[Overflow Recovery]\n A --> E[Self Repair]\n A --> F[Reflector]\n end\n \n G[Agent Input] --> A\n A --> H[Tool Execution]\n A --> I[Output]\n \n B -.->|Validation Result| A\n C -.->|Safety Check| A\n D -.->|Memory State| A\n E -.->|Repair Action| A\n F -.->|Reflection| A\n```\n\nThe Agent Core System coordinates multiple subsystems to ensure reliable and safe agent execution while maintaining context awareness and self-healing capabilities.\n\n## Core Components\n\n### Agent Executor\n\nThe `AgentExecutor` serves as the central orchestrator that manages the complete lifecycle of agent task execution. It coordinates between various subsystems including validation, safety checks, memory management, and self-repair mechanisms.\n\n**Key Responsibilities:**\n- Task dispatch and execution orchestration\n- State management across execution phases\n- Coordination with external tool systems\n- Integration with the broader AgenticX framework\n\n**Source:** [agenticx/core/agent_executor.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent_executor.py)\n\n### Task Validator\n\nThe `TaskValidator` ensures that agent-generated outputs meet quality and correctness standards before being considered final results. It performs structural validation, semantic checks, and format verification.\n\n**Validation Criteria:**\n| Category | Description |\n|----------|-------------|\n| Structural | Output format and schema compliance |\n| Semantic | Logical consistency and coherence |\n| Safety | Absence of harmful or inappropriate content |\n| Completeness | Full task requirement fulfillment |\n\n**Source:** [agenticx/core/task_validator.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task_validator.py)\n\n### Guiderails\n\nThe `Guiderails` module implements safety mechanisms that constrain agent behavior within defined boundaries. It monitors inputs, outputs, and tool invocations to prevent unintended or harmful actions.\n\n**Safety Features:**\n- Input sanitization and validation\n- Output filtering and content moderation\n- Tool usage policy enforcement\n- Behavioral boundary enforcement\n\n**Source:** [agenticx/core/guiderails.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/guiderails.py)\n\n### Overflow Recovery\n\nThe `OverflowRecovery` system manages memory and context overflow scenarios that occur during extended agent sessions. It implements strategies to preserve critical context while managing resource constraints.\n\n**Recovery Strategies:**\n| Strategy | Purpose |\n|----------|---------|\n| Context Trimming | Remove less relevant historical context |\n| Summary Generation | Compress conversation history |\n| Priority Preservation | Retain essential state information |\n| Progressive Cleanup | Gradual memory release |\n\n**Source:** [agenticx/core/overflow_recovery.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/overflow_recovery.py)\n\n### Self Repair\n\nThe `SelfRepair` module enables the agent to detect, diagnose, and correct its own errors without external intervention. It provides automated error recovery and behavioral correction capabilities.\n\n**Repair Mechanisms:**\n- Error detection and classification\n- Root cause analysis\n- Automatic correction application\n- Repair history tracking\n\n**Source:** [agenticx/core/self_repair.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/self_repair.py)\n\n### Reflector\n\nThe `Reflector` provides introspective capabilities that allow the agent to analyze its own reasoning, decisions, and execution patterns. It generates insights about agent behavior and enables continuous improvement.\n\n**Reflection Capabilities:**\n- Reasoning path analysis\n- Decision audit trails\n- Performance metrics generation\n- Behavioral pattern identification\n\n**Source:** [agenticx/core/reflector.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/reflector.py)\n\n## Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Input as Agent Input\n participant Executor as Agent Executor\n participant Validator as Task Validator\n participant Rails as Guiderails\n participant Overflow as Overflow Recovery\n participant Repair as Self Repair\n participant Reflect as Reflector\n participant Output as Final Output\n\n Input->>Executor: Task Request\n Executor->>Rails: Safety Check\n Rails-->>Executor: Approved/Blocked\n Executor->>Validator: Validate Task\n Validator-->>Executor: Validation Result\n Executor->>Overflow: Check Memory State\n Overflow-->>Executor: Memory Status\n Executor->>Executor: Execute Task\n Executor->>Repair: Error Detected?\n alt Error Detected\n Repair->>Repair: Analyze Error\n Repair->>Executor: Apply Fix\n Executor->>Executor: Retry\n end\n Executor->>Reflect: Log Execution\n Reflect-->>Executor: Reflection Complete\n Executor->>Output: Return Result\n```\n\n## Integration with AgenticX Framework\n\nThe Agent Core System integrates with multiple parts of the AgenticX ecosystem:\n\n### Desktop Integration\n\nThe desktop application (`desktop/`) provides UI components that interact with the core system through a store-based state management architecture. Settings panels allow configuration of agent parameters, and task automation components interface with the executor for scheduled task execution.\n\n**Related Files:**\n- [desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts) - State management\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) - Configuration UI\n- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx) - Task automation\n\n### Enterprise Features\n\nEnterprise features build upon the core system to provide additional capabilities:\n\n| Feature | Module | Integration Point |\n|---------|--------|-------------------|\n| Knowledge Base | `@agenticx/feature-knowledge-base` | Context enrichment |\n| Agent Management | `@agenticx/feature-agents` | Multi-agent orchestration |\n| Identity & Access | `@agenticx/feature-iam` | Security and permissions |\n| Tools MCP | `@agenticx/feature-tools-mcp` | Tool integration |\n\n**Related Files:**\n- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md)\n\n### Admin Console\n\nThe enterprise admin console provides monitoring and management capabilities for the core system through audit logging and operational dashboards.\n\n**Related Files:**\n- [enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx) - Audit logging interface\n- [enterprise/apps/admin-console/src/app/admin/models/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx) - Model management\n\n## Configuration Options\n\nThe Agent Core System supports various configuration parameters:\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `max_iterations` | Maximum execution iterations per task | Configurable |\n| `timeout_seconds` | Task execution timeout | Platform dependent |\n| `memory_limit` | Maximum memory allocation | Based on plan tier |\n| `enable_self_repair` | Enable automatic error correction | Enabled |\n| `enable_guiderails` | Enable safety mechanisms | Enabled |\n| `reflection_level` | Reflection detail depth | Standard |\n\n## Error Handling\n\nThe core system implements a hierarchical error handling approach:\n\n1. **Guiderails Prevention** - Blocks known dangerous patterns\n2. **Validation Failure** - Rejects invalid outputs with feedback\n3. **Self Repair Attempt** - Automatic correction of recoverable errors\n4. **Overflow Recovery** - Memory-related issue resolution\n5. **Reflector Documentation** - Error logging for analysis\n\n## Related Documentation\n\n- [Sandbox System](../sandbox/README.md) - Isolated execution environment\n- [Collaboration Mode](../collaboration/README.md) - Multi-agent cooperation\n- [AgentKit Integration](../integrations/agentkit/) - External framework integration\n\n---\n\n\n\n## Meta-Agent and Team Management\n\n### 相关页面\n\n相关主题：[Agent Core System](#page-agent-core), [Avatar and Group Chat](#page-avatar-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n- [desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n \n\n# Meta-Agent and Team Management\n\n## Overview\n\nMeta-Agent and Team Management in AgenticX refers to the system for orchestrating multiple AI agents (\"分身\", literally \"avatars\" or \"clones\") that can collaborate to accomplish complex tasks. The system provides a hierarchical management structure where a meta-agent coordinates teams of specialized agents, each with distinct capabilities, prompts, and tool configurations.\n\nThe architecture supports:\n\n- **Agent Lifecycle Management** — creation, configuration, enabling/disabling of individual agents\n- **Team Coordination** — grouping agents into collaborative units with shared context\n- **Skill Assignment** — attaching modular skills to specific agents or globally\n- **Meta-Tool Orchestration** — meta-agents that can delegate tasks to subordinate agents\n- **Execution Monitoring** — tracking task runs, statuses, and error handling\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n## Architecture\n\nThe system follows a layered architecture:\n\n```graph TD\n User[User Interface]\n UI[SettingsPanel / AvatarCreateDialog]\n MetaAgent[Meta-Agent]\n TeamManager[Team Manager]\n Agents[Agent Clones / Avatars]\n Skills[Skills System]\n Tools[Tool Registry]\n \n User --> UI\n UI --> MetaAgent\n MetaAgent --> TeamManager\n TeamManager --> Agents\n Agents --> Skills\n Agents --> Tools\n```\n\n### Core Components\n\n| Component | Purpose | Key File Reference |\n|-----------|---------|-------------------|\n| **Meta-Agent** | Top-level coordinator that decomposes tasks and delegates to team members | `agenticx/collaboration/README.md` |\n| **Team Manager** | Manages agent lifecycle, grouping, and inter-agent communication | Collaboration patterns |\n| **Agent Clone (Avatar)** | Individual agent with specific prompt, model, and workspace configuration | `desktop/src/components/AvatarCreateDialog.tsx` |\n| **Skills System** | Modular capability extensions attachable to agents | `desktop/src/components/SettingsPanel.tsx` |\n| **Tool Registry** | Centralized tool definitions and permissions | `desktop/src/components/SettingsPanel.tsx` |\n| **Role-Based Access** | IAM integration for agent permissions | `enterprise/apps/admin-console/src/app/iam/roles/page.tsx` |\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n\n## Agent Creation and Configuration\n\n### Avatar (Agent Clone) Structure\n\nEach agent clone is configured with:\n\n- **Name/Identifier** — unique agent name\n- **System Prompt** — base instructions and persona\n- **Workspace** — isolated working directory (optional)\n- **Model Configuration** — provider and model selection\n- **Enabled Skills** — list of skills this agent can use\n- **Active State** — can be toggled on/off\n\n```typescript\n// Avatar configuration interface (simplified)\ninterface AgentClone {\n id: string;\n name: string;\n prompt: string;\n workspace?: string;\n provider?: string;\n model?: string;\n enabledSkills: string[];\n enabled: boolean;\n}\n```\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n\n### Skills Configuration\n\nSkills can be assigned to agents with fine-grained control:\n\n| Setting | Description |\n|---------|-------------|\n| **Global Skills** | Skills available to all agents, can be disabled per-agent |\n| **Agent-Specific Skills** | Skills enabled only for particular agents |\n| **Skill Source Priority** | Preferred source when multiple skill definitions exist |\n| **Disabled Skills** | Skills explicitly disabled at global or agent level |\n\n```tsx\n// Skills UI state management\nconst [skillsEnabledDraft, setSkillsEnabledDraft] = useState>({});\nconst [preferredSkillSources, setPreferredSkillSources] = useState>({});\n```\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n\n## Team Management\n\n### Team Structure\n\nAgents are organized into teams with coordinated behavior:\n\n```graph TD\n Meta[Meta-Agent] --> Coordinator[Coordinator Agent]\n Coordinator --> AgentA[Specialist Agent A]\n Coordinator --> AgentB[Specialist Agent B]\n Coordinator --> AgentC[Specialist Agent C]\n \n AgentA --> Tool1[Tool Access]\n AgentB --> Tool2[Tool Access]\n AgentC --> Tool3[Tool Access]\n \n Coordinator --> SharedContext[Shared Context]\n AgentA --> SharedContext\n AgentB --> SharedContext\n AgentC --> SharedContext\n```\n\n### Collaboration Modes\n\nThe collaboration system supports multiple coordination patterns:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| **Custom Pattern** | User-defined collaboration flow | Complex, non-standard workflows |\n| **Sequential** | Agents execute tasks in order | Pipeline processing |\n| **Parallel** | Multiple agents work simultaneously | Independent subtasks |\n| **Hierarchical** | Meta-agent delegates to specialists | Decomposed complex tasks |\n\n```python\n# Pattern registration in manager\npattern_classes = {\n CollaborationMode.CUSTOM_PATTERN: CustomPattern,\n # ... other modes\n}\n```\n\n资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n\n## Task Automation\n\n### Task Configuration\n\nAutomated tasks can be assigned to agents with scheduling and execution parameters:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `id` | string | Unique task identifier |\n| `enabled` | boolean | Whether task is active |\n| `prompt` | string | Task instruction |\n| `workspace` | string | Working directory |\n| `provider` | string | Model provider |\n| `model` | string | Model identifier |\n| `lastRunAt` | timestamp | Last execution time |\n| `lastRunStatus` | enum | \"success\" / \"error\" |\n| `lastRunError` | string | Error message if failed |\n\n### Task Execution States\n\n```graph TD\n A[Scheduled] --> B{Running}\n B -->|Success| C[Completed]\n B -->|Error| D[Failed]\n D -->|Retry| B\n C --> E[Update Status]\n E --> F[Ready for Next]\n```\n\n资料来源：[desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n\n## Tool Registry and Permissions\n\n### Tool Management\n\nTools are registered centrally and can be:\n\n| Status | Badge | Description |\n|--------|-------|-------------|\n| **Installed** | Green \"已安装\" | Tool executable available |\n| **Installing** | Accent color \"安装中\" | Installation in progress |\n| **Manual Required** | Amber \"需手动安装\" | User action needed |\n| **Not Installed** | Red \"未安装\" | Tool not present |\n\n### Denied Tools\n\nSpecific tools can be explicitly denied for security:\n\n```tsx\n{deniedTools.map((toolPat, idx) => (\n \n))}\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Role-Based Access Control\n\n### Role Permissions for Agents\n\nAgent operations are governed by role-based permissions:\n\n| Permission | Scope | Description |\n|------------|-------|-------------|\n| `agents:read` | Global/Team | View agent configurations |\n| `agents:write` | Global/Team | Create/modify agents |\n| `agents:execute` | Agent-specific | Run agent tasks |\n| `skills:manage` | Global | Configure global skills |\n| `tools:approve` | Admin | Approve tool requests |\n\n### Role Management UI\n\nThe admin console provides role management with scope matrix editing:\n\n```tsx\n\n```\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n\n## Environment Dependencies\n\n### External Tool Installation\n\nThe system manages external executable dependencies:\n\n- **Global Installation** — Tools installed once, shared across all agents\n- **Per-Team Installation** — Team-specific tool configurations\n- **Manual Installation Mode** — Flagged tools requiring user intervention\n- **Sidecar Services** — Background services (e.g., WeChat integration)\n\n```tsx\nconst wechatStatus = await window.agenticxDesktop.wechatSidecarPort();\nif (!running) {\n const startRes = await window.agenticxDesktop.wechatSidecarStart();\n}\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Workflow Summary\n\n### Creating and Managing Agents\n\n1. **Define Agent Persona** — Set name, prompt, and model configuration\n2. **Assign Skills** — Enable/disable skills from global pool or add custom paths\n3. **Configure Tools** — Grant/revoke tool access, manage denied tools\n4. **Set Up Team** — Group agents under a meta-agent or coordinator\n5. **Define Tasks** — Create automated tasks with scheduling\n6. **Monitor Execution** — Track runs, statuses, and errors\n7. **Adjust Permissions** — Update role-based access as needed\n\n### Multi-Agent Coordination Flow\n\n```graph LR\n Request[User Request] --> Meta[Meta-Agent]\n Meta --> Decompose[Decompose Task]\n Decompose --> Assign[Assign to Team Members]\n Assign --> ExecuteA[Agent A Execute]\n Assign --> ExecuteB[Agent B Execute]\n Assign --> ExecuteC[Agent C Execute]\n ExecuteA --> ResultsA[Results A]\n ExecuteB --> ResultsB[Results B]\n ExecuteC --> ResultsC[Results C]\n ResultsA --> Aggregate[Aggregate Results]\n ResultsB --> Aggregate\n ResultsC --> Aggregate\n Aggregate --> Response[Final Response]\n```\n\n## Integration with Enterprise Features\n\n### Feature Modules\n\nAgenticX uses a modular feature system:\n\n| Module | Purpose |\n|--------|---------|\n| `@agenticx/feature-agents` | Core agent management |\n| `@agenticx/feature-knowledge-base` | Knowledge retrieval integration |\n| `@agenticx/feature-tools-mcp` | MCP (Model Context Protocol) tool integration |\n| `@agenticx/feature-iam` | Identity, roles, and permissions |\n| `@agenticx/feature-chat` | Chat workspace UI |\n\n```tsx\nimport { featureName } from \"@agenticx/feature-agents\";\n```\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n### Admin Console Integration\n\nThe enterprise admin console provides:\n\n- **Audit Logging** — Track all agent operations with chain validation\n- **Bulk Import** — Batch create agents from CSV templates\n- **Role Management** — Define and assign permission scopes\n- **Model Configuration** — Manage available AI providers and models\n\n```tsx\ndescription={`共 ${items.length} 条记录 · ${\n chainFull?.valid ? \"全表链校验通过\" : \"全表链校验失败\"\n}`}\n```\n\n资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n\n## Summary\n\nThe Meta-Agent and Team Management system provides a comprehensive framework for orchestrating multiple AI agents within AgenticX. Key capabilities include:\n\n- **Hierarchical Agent Structure** — Meta-agents coordinate specialist agents\n- **Flexible Skill System** — Modular capabilities with per-agent enablement\n- **Team-Based Collaboration** — Multiple coordination patterns (sequential, parallel, hierarchical)\n- **Automated Task Execution** — Scheduled tasks with status tracking\n- **Tool Registry** — Centralized tool management with permission controls\n- **Role-Based Security** — Enterprise-grade IAM integration\n- **Environment Management** — External dependency handling\n\nThe system is designed for both single-user desktop scenarios (via SettingsPanel) and enterprise deployments (via Admin Console), supporting use cases from personal automation to complex multi-agent workflows.\n\n---\n\n\n\n## Tool System and MCP Hub\n\n### 相关页面\n\n相关主题：[Agent Core System](#page-agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/tools/function_tool.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/function_tool.py)\n- [agenticx/tools/mcp_hub.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/mcp_hub.py)\n- [agenticx/tools/remote_v2.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/remote_v2.py)\n- [agenticx/tools/openapi_toolset.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/openapi_toolset.py)\n- [agenticx/tools/sandbox_tools.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/sandbox_tools.py)\n- [agenticx/tools/guardrails/builtin.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/guardrails/builtin.py)\n \n\n# Tool System and MCP Hub\n\n## Overview\n\nThe AgenticX Tool System provides a comprehensive framework for extending agent capabilities through function tools, MCP (Model Context Protocol) integration, remote tools, OpenAPI-based tool sets, sandboxed execution, and built-in guardrails. This architecture enables agents to interact with external systems, execute code safely, and enforce security policies while maintaining a unified tool invocation interface.\n\n## Architecture Overview\n\nThe tool system is organized into a layered architecture where different tool implementations share common interfaces while providing specialized functionality:\n\n```mermaid\ngraph TD\n A[Agent Core] --> B[Tool Registry]\n B --> C[Function Tool]\n B --> D[MCP Hub]\n B --> E[Remote Tools v2]\n B --> F[OpenAPI Toolset]\n B --> G[Sandbox Tools]\n B --> H[Guardrails]\n \n D --> I[MCP Servers]\n D --> J[MCP Client]\n \n G --> K[Sandbox Runtime]\n H --> L[Built-in Validators]\n```\n\n## Function Tool\n\nFunction tools provide the foundational mechanism for wrapping Python functions as agent-callable tools. They encapsulate function metadata, parameter schemas, and execution logic within a standardized interface.\n\n### Core Implementation\n\nFunction tools are defined through decorators or class-based configurations that specify the tool's name, description, parameters, and return type. The system uses type hints to automatically generate JSON Schema for parameter validation.\n\n```python\nfrom agenticx.tools.function_tool import FunctionTool\n\n@FunctionTool.register(\n name=\"web_search\",\n description=\"Search the web for information\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\"type\": \"string\", \"description\": \"Search query\"},\n \"limit\": {\"type\": \"integer\", \"description\": \"Max results\", \"default\": 5}\n },\n \"required\": [\"query\"]\n }\n)\ndef search_web(query: str, limit: int = 5) -> dict:\n # Implementation\n return {\"results\": []}\n```\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Registry\n participant FunctionTool\n participant Executor\n \n Agent->>Registry: InvokeTool(name, parameters)\n Registry->>FunctionTool: Locate tool by name\n FunctionTool->>Executor: Execute(parameters)\n Executor->>FunctionTool: Result\n FunctionTool->>Registry: Wrapped response\n Registry->>Agent: ToolResult\n```\n\n资料来源：[agenticx/tools/function_tool.py]()\n\n## MCP Hub\n\nThe MCP Hub serves as the central integration point for Model Context Protocol servers, enabling agents to discover and utilize tools exposed by external MCP-compliant services.\n\n### MCP Architecture\n\n```mermaid\ngraph LR\n A[AgenticX Agent] --> B[MCP Hub]\n B --> C[MCP Client Pool]\n C --> D[MCP Server 1]\n C --> E[MCP Server 2]\n C --> F[MCP Server N]\n \n D --> G[File System Tools]\n E --> H[API Tools]\n F --> I[Custom Tools]\n```\n\n### MCP Hub Features\n\nThe MCP Hub provides the following capabilities:\n\n| Feature | Description |\n|---------|-------------|\n| Server Management | Register and manage multiple MCP server connections |\n| Tool Discovery | Automatic discovery of available tools from connected servers |\n| Connection Pooling | Efficient reuse of MCP client connections |\n| Error Handling | Graceful degradation when servers are unavailable |\n| Tool Registry Integration | Seamless integration with the AgenticX tool registry |\n\n资料来源：[agenticx/tools/mcp_hub.py]()\n\n### Usage Pattern\n\n```python\nfrom agenticx.tools.mcp_hub import MCPHub\n\nhub = MCPHub()\n\n# Connect to an MCP server\nawait hub.connect(\"file-server\", server_config)\n\n# List available tools\ntools = await hub.list_tools()\n\n# Invoke a tool\nresult = await hub.invoke(\"file-server\", \"read_file\", {\"path\": \"/data/file.txt\"})\n```\n\n## Remote Tools v2\n\nThe remote tools module provides a robust mechanism for calling external APIs and services. Version 2 introduces improved connection handling, request pooling, and authentication support.\n\n### Architecture\n\n```mermaid\ngraph TD\n A[Tool Request] --> B[RemoteTool Client]\n B --> C[Request Queue]\n C --> D[Connection Pool]\n D --> E[External API]\n E --> D\n D --> F[Response Handler]\n F --> G[Tool Result]\n \n B --> H[Auth Manager]\n H --> I[Token Store]\n```\n\n### Configuration Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `base_url` | string | required | Base URL for the remote service |\n| `timeout` | int | 30 | Request timeout in seconds |\n| `max_retries` | int | 3 | Maximum retry attempts |\n| `pool_size` | int | 10 | Connection pool size |\n| `auth_type` | string | \"none\" | Authentication type: bearer, api_key, basic |\n\n资料来源：[agenticx/tools/remote_v2.py]()\n\n### Implementation\n\n```python\nfrom agenticx.tools.remote_v2 import RemoteTool\n\ntool = RemoteTool(\n name=\"external_api\",\n base_url=\"https://api.example.com\",\n auth_type=\"bearer\",\n token=\"your-token\",\n timeout=60,\n max_retries=3\n)\n\nresult = await tool.invoke(\"endpoint\", {\"param\": \"value\"})\n```\n\n## OpenAPI Toolset\n\nThe OpenAPI toolset enables automatic generation of tool interfaces from OpenAPI specifications. This allows agents to interact with any REST API documented using the OpenAPI standard.\n\n### Auto-Discovery Process\n\n```mermaid\ngraph TD\n A[OpenAPI Spec] --> B[OpenAPI Parser]\n B --> C[Endpoint Mappings]\n C --> D[Tool Generator]\n D --> E[Tool Instances]\n E --> F[Tool Registry]\n```\n\n### Supported Features\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| GET requests | Supported | Retrieve resources |\n| POST requests | Supported | Create resources |\n| PUT/PATCH requests | Supported | Update resources |\n| DELETE requests | Supported | Remove resources |\n| Authentication | Supported | Bearer, API Key, OAuth2 |\n| Request body schemas | Supported | JSON Schema validation |\n| Response parsing | Supported | Automatic result extraction |\n\n资料来源：[agenticx/tools/openapi_toolset.py]()\n\n### Usage Example\n\n```python\nfrom agenticx.tools.openapi_toolset import OpenAPIToolset\n\n# Generate tools from OpenAPI spec\ntoolset = OpenAPIToolset.from_spec(\n spec_url=\"https://api.example.com/openapi.json\",\n auth={\"type\": \"bearer\", \"token\": \"...\"}\n)\n\n# Tools are automatically registered\nresults = await toolset.invoke(\"get_user\", {\"id\": \"123\"})\n```\n\n## Sandbox Tools\n\nSandbox tools provide secure code execution environments for agent operations that require running untrusted or dynamically generated code.\n\n### Sandbox Architecture\n\n```mermaid\ngraph TD\n A[Code Execution Request] --> B[Sandbox Manager]\n B --> C{Backend Type}\n C -->|micro-sandbox| D[Lightweight Container]\n C -->|docker| E[Docker Container]\n C -->|remote| F[Remote Sandbox Service]\n \n D --> G[Execution Engine]\n E --> G\n F --> G\n \n G --> H[Result Collector]\n H --> I[Output/Side Effects]\n H --> J[Error Handler]\n```\n\n### Sandbox Templates\n\n| Template | Use Case | CPU | Memory | Timeout |\n|----------|----------|-----|--------|---------|\n| LIGHTWEIGHT_TEMPLATE | Quick computations | 1 core | 512MB | 30s |\n| HIGH_PERFORMANCE_TEMPLATE | Complex operations | 4 cores | 8GB | 300s |\n| CODE_INTERPRETER | Python execution | 2 cores | 4GB | 120s |\n\n### Error Handling\n\nThe sandbox module defines specific exception types for different failure scenarios:\n\n```python\nfrom agenticx.tools.sandbox_tools import (\n SandboxError,\n SandboxTimeoutError,\n SandboxExecutionError,\n SandboxNotReadyError,\n SandboxBackendError,\n)\n\ntry:\n async with Sandbox.create() as sb:\n result = await sb.execute(code, timeout=60)\nexcept SandboxTimeoutError:\n print(\"Execution exceeded time limit\")\nexcept SandboxExecutionError as e:\n print(f\"Runtime error: {e.stderr}\")\nexcept SandboxBackendError as e:\n print(f\"Backend failure: {e.backend}\")\n```\n\n资料来源：[agenticx/tools/sandbox_tools.py]()\n\n## Guardrails (Built-in)\n\nGuardrails provide security and policy enforcement for tool execution, ensuring that agent operations comply with defined constraints and safety policies.\n\n### Guardrail Architecture\n\n```mermaid\ngraph LR\n A[Tool Request] --> B[Guardrail Chain]\n B --> C[Input Validator]\n B --> D[Rate Limiter]\n B --> E[Content Filter]\n B --> F[Output Sanitizer]\n \n C --> G{Allowed?}\n D --> G\n E --> G\n F --> G\n \n G -->|Yes| H[Tool Executor]\n G -->|No| I[Rejection Response]\n```\n\n### Built-in Guardrail Types\n\n| Guardrail | Purpose | Configuration |\n|-----------|---------|---------------|\n| InputValidation | Validate parameter types and ranges | Schema-based |\n| RateLimiting | Prevent excessive calls | Calls per time window |\n| ContentFilter | Block sensitive content patterns | Pattern matching |\n| OutputSanitizer | Remove sensitive data from results | Data classification |\n| AuditLogger | Log all tool invocations | Structured logging |\n\n资料来源：[agenticx/tools/guardrails/builtin.py]()\n\n### Implementation Pattern\n\n```python\nfrom agenticx.tools.guardrails.builtin import (\n InputValidationGuardrail,\n RateLimitGuardrail,\n)\n\n# Configure guardrails\nguardrails = [\n InputValidationGuardrail(schema=param_schema),\n RateLimitGuardrail(max_calls=100, window_seconds=60),\n]\n\n# Apply to tool\nsecure_tool = Tool.with_guardrails(tool_instance, guardrails)\n```\n\n## Integration with Agentic Agents\n\nTools integrate seamlessly with the AgenticX agent framework through the tool registry and invocation system.\n\n```mermaid\ngraph TD\n A[Agent Task] --> B[Planner]\n B --> C[Tool Selection]\n C --> D[Tool Registry]\n D --> E[Tool Invocation]\n E --> F{Guardrail Check}\n F -->|Pass| G[Execute Tool]\n F -->|Fail| H[Reject]\n G --> I[Result Processing]\n I --> J[Response to Agent]\n```\n\n### Tool Selection Criteria\n\n| Criterion | Description |\n|-----------|-------------|\n| Capability Match | Tool can solve the required sub-task |\n| Availability | Tool is registered and accessible |\n| Permission | Agent has permission to invoke tool |\n| Rate Limits | Tool rate limits not exceeded |\n| Guardrail Compliance | Request passes all guardrail checks |\n\n## Summary\n\nThe AgenticX Tool System provides a flexible, extensible framework for extending agent capabilities through multiple integration patterns:\n\n- **Function Tools**: Direct Python function wrapping\n- **MCP Hub**: Model Context Protocol integration for external tool servers\n- **Remote Tools v2**: External API invocation with connection pooling\n- **OpenAPI Toolset**: Automatic tool generation from API specifications\n- **Sandbox Tools**: Secure code execution environments\n- **Guardrails**: Security and policy enforcement layers\n\nThis architecture enables developers to extend agent capabilities while maintaining consistent interfaces, security boundaries, and operational monitoring across all tool integrations.\n\n---\n\n\n\n## Memory System\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n- [README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [agenticx/memory/__init__.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/__init__.py)\n- [examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n \n\n# Memory System\n\nThe Memory System in AgenticX provides persistent and intelligent memory capabilities for AI agents, enabling them to retain information across sessions, manage knowledge bases, and perform semantic searches. This system is fundamental for building stateful, context-aware agentic applications.\n\n## Architecture Overview\n\nThe memory system follows a layered architecture that separates storage backends from intelligent processing components.\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ AgenticX Memory System │\n├─────────────────────────────────────────────────────────┤\n│ ┌───────────────┐ ┌──────────────┐ ┌───────────────┐ │\n│ │ MemoryComponent│ │ KnowledgeBase│ │ MemoryClient│ │\n│ │ (Intelligence) │ │ (Organization)│ │ (API Layer) │ │\n│ └───────┬───────┘ └──────┬───────┘ └───────┬───────┘ │\n│ │ │ │ │\n│ ┌───────┴─────────────────┴───────────────────┴───────┐ │\n│ │ Memory Backend Implementations │ │\n│ ├─────────────┬───────────────┬───────────────────────┤ │\n│ │ShortTermMemory│ EpisodicMemory│ SemanticMemory │ │\n│ ├─────────────┼───────────────┼───────────────────────┤ │\n│ │ Hierarchical │ Mem0Memory │ MCP Integration │ │\n│ └─────────────┴───────────────┴───────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n## Core Components\n\n### 1. ShortTermMemory\n\nShort-term memory provides transient storage for current conversation context and immediate agent state. It is designed for high-throughput operations within a tenant's scope.\n\n```python\nfrom agenticx.memory import ShortTermMemory\n\n# Create memory backend\nbackend = ShortTermMemory(tenant_id=\"user_123\")\n\n# Add persistent memory with metadata\nmemory_id = await backend.add(\n \"Important project information\",\n metadata={\"project\": \"agenticx\", \"importance\": \"high\"}\n)\n\n# Search across all memories\nresults = await backend.search(\"project information\")\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `tenant_id` | `str` | Unique identifier for tenant isolation |\n| `content` | `str` | Memory content text |\n| `metadata` | `dict` | Optional key-value metadata for categorization |\n\n### 2. KnowledgeBase\n\nKnowledgeBase enables organization of content into specialized domains with content-type filtering.\n\n```python\nfrom agenticx.memory import KnowledgeBase, ShortTermMemory\n\n# Create memory backend\nbackend = ShortTermMemory(tenant_id=\"kb_demo\")\n\n# Create specialized knowledge bases\ndocs_kb = KnowledgeBase(\n name=\"documentation\",\n memory_backend=backend,\n allowed_content_types={\"tutorial\", \"guide\", \"faq\"}\n)\n\ncode_kb = KnowledgeBase(\n name=\"code_examples\", \n memory_backend=backend,\n allowed_content_types={\"code\", \"snippet\"}\n)\n\n# Add content with content type\nawait docs_kb.add(\n \"How to create an agent\",\n content_type=\"tutorial\",\n metadata={\"difficulty\": \"beginner\"}\n)\n\n# Search within specific knowledge base\ndoc_results = await docs_kb.search(\"agent creation\")\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Knowledge base identifier |\n| `memory_backend` | `MemoryBackend` | Underlying storage implementation |\n| `allowed_content_types` | `set[str]` | Filter for permitted content types |\n\n### 3. MemoryComponent\n\nThe MemoryComponent provides intelligent memory operations with automatic cleanup and advanced retrieval capabilities.\n\n```python\nfrom agenticx.memory import MemoryComponent, ShortTermMemory\n\n# Create memory component with primary storage\nprimary_memory = ShortTermMemory(tenant_id=\"demo\")\ncomponent = MemoryComponent(\n primary_memory=primary_memory,\n enable_ranking=True,\n enable_deduplication=True\n)\n\n# Use with context manager for automatic cleanup\nasync with component as mem:\n memory_id = await mem.add(\n \"Context-aware information\",\n metadata={\"context\": \"agent_session\"}\n )\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n## Memory Backend Types\n\n| Backend Type | Use Case | Persistence |\n|--------------|----------|-------------|\n| `ShortTermMemory` | Session state, temporary data | Ephemeral with optional persistence |\n| `EpisodicMemory` | Event sequences, conversation history | Long-term storage |\n| `SemanticMemory` | Embedding-based semantic search | Vector-enabled storage |\n| `HierarchicalMemory` | Multi-level memory organization | Tiered storage |\n| `Mem0Memory` | Healthcare, personalized data | Specialized domain storage |\n\n## MCP Integration\n\nThe Memory System supports Model Context Protocol (MCP) for external memory service integration.\n\n```python\nfrom agenticx.memory import MemoryClient\nfrom agenticx.mcp import MCPServer, MCPTools\n\n# Configure MCP server for memory\nmcp_config = MCPTools(\n port=3000,\n server_config={\n \"memory_service\": \"mem0\",\n \"api_endpoint\": \"http://localhost:8000\"\n }\n)\n\n# Create memory client with MCP backend\nmemory = MemoryClient(\n tenant_id=\"mcp_tenant\",\n server_config=mcp_config\n)\n\n# Async usage with automatic resource management\nasync with memory:\n memory_id = await memory.add(\n \"Important project information\",\n metadata={\"project\": \"agenticx\", \"importance\": \"high\"}\n )\n results = await memory.search(\"project information\")\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n## Healthcare Memory Scenario\n\nThe Mem0 memory backend is specifically designed for healthcare applications, providing medical knowledge memory and personalized patient information management.\n\n```bash\n# Run healthcare memory example\npython examples/mem0_healthcare_example.py\n```\n\n资料来源：[README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md)\n\n### Key Features for Healthcare\n\n- **Medical Knowledge Memory**: Structured storage for medical concepts, diagnoses, and treatment protocols\n- **Patient Information Management**: Secure, tenant-isolated storage for patient-specific data\n- **Privacy Compliance**: Built-in data handling safeguards for sensitive medical information\n- **Semantic Search**: Fast retrieval of relevant medical information using embeddings\n\n## Desktop Application Integration\n\nThe Memory System is accessible through the AgenticX Desktop application, providing a graphical interface for memory management.\n\n```tsx\n// SettingsPanel.tsx integration\nimport { useAgenticxDesktop } from \"@agenticx/desktop\";\n\nconst memorySettings = {\n enableMemorySync: true,\n syncInterval: 30000, // ms\n maxMemorySize: \"100MB\"\n};\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Skill Scanning with Memory\n\nThe desktop application uses memory-backed skill scanning to discover and manage agent capabilities:\n\n- **Global Skills**: System-wide shared skills stored in memory\n- **Project Skills**: Per-project skills located in `.agents/skills/`\n- **Marketplace Skills**: Third-party skills fetched and cached\n- **Custom Paths**: User-defined skill directories\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Intent Recognition with Memory\n\nThe intent recognition service leverages the Memory System for storing and retrieving classification patterns and entity mappings.\n\n```bash\n# Run intent recognition example\npython examples/agenticx-for-intent-recognition/main.py\n```\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n### Architecture Pattern\n\n```\n┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐\n│ Intent Agent │────▶│ Memory System │◀────│ Knowledge Base │\n│ (Classifier) │ │ (Storage/Lookup)│ │ (Patterns) │\n└─────────────────┘ └──────────────────┘ └─────────────────┘\n │ │\n ▼ ▼\n┌─────────────────┐ ┌──────────────────┐\n│ Workflow Engine│ │ Semantic Search │\n│ (Orchestration) │ │ (Retrieval) │\n└─────────────────┘ └──────────────────┘\n```\n\n## Memory Operations API\n\n### Add Memory\n\n```python\nmemory_id = await memory.add(\n content: str,\n metadata: Optional[dict] = None,\n content_type: Optional[str] = None,\n embedding: Optional[list[float]] = None\n) -> str\n```\n\n### Search Memory\n\n```python\nresults = await memory.search(\n query: str,\n limit: int = 10,\n content_type: Optional[str] = None,\n filters: Optional[dict] = None\n) -> list[MemoryResult]\n```\n\n### Delete Memory\n\n```python\nawait memory.delete(memory_id: str) -> bool\n```\n\n### Update Memory\n\n```python\nawait memory.update(\n memory_id: str,\n content: Optional[str] = None,\n metadata: Optional[dict] = None\n) -> bool\n```\n\n## Best Practices\n\n### Tenant Isolation\n\nAlways specify a unique `tenant_id` when creating memory backends to ensure data isolation:\n\n```python\n# Good: Isolated memory per tenant\nuser_memory = ShortTermMemory(tenant_id=\"user_abc123\")\n\n# Avoid: Shared memory across tenants\nshared_memory = ShortTermMemory(tenant_id=\"shared\") # Not recommended\n```\n\n### Content Type Organization\n\nUse content types consistently for better organization and filtering:\n\n| Content Type | Description |\n|--------------|-------------|\n| `tutorial` | Educational content |\n| `guide` | How-to documentation |\n| `faq` | Frequently asked questions |\n| `code` | Code snippets and examples |\n| `snippet` | Small code fragments |\n\n### Metadata Usage\n\nLeverage metadata for enhanced search and filtering:\n\n```python\nawait memory.add(\n \"Agent configuration guide\",\n metadata={\n \"category\": \"documentation\",\n \"difficulty\": \"intermediate\",\n \"version\": \"1.0\",\n \"tags\": [\"agent\", \"setup\", \"configuration\"]\n }\n)\n```\n\n## Dependencies\n\nThe Memory System requires the following core dependencies:\n\n| Package | Purpose |\n|---------|--------|\n| `mem0ai` | Mem0 memory backend integration |\n| `chromadb` | Vector storage for semantic search |\n| `pydantic` | Data validation and serialization |\n\n## Summary\n\nThe AgenticX Memory System provides a comprehensive, multi-layered approach to agent memory management:\n\n1. **ShortTermMemory** for immediate session context\n2. **KnowledgeBase** for domain-specific content organization\n3. **MemoryComponent** for intelligent operations\n4. **MCP Integration** for external memory services\n5. **Specialized Backends** (Mem0) for domain-specific applications\n\nThis architecture enables agents to maintain persistent context, perform semantic retrieval, and scale across enterprise deployments with full tenant isolation.\n\n---\n\n\n\n## Avatar and Group Chat\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [desktop/src/components/AvatarSettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarSettingsPanel.tsx)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n- [enterprise/features/chat/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/chat/README.md)\n- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n \n\n# Avatar and Group Chat\n\n## Overview\n\nThe Avatar and Group Chat system in AgenticX enables multi-agent collaboration through configurable digital personas called \"Avatars\" (also referred to as \"分身\" in Chinese). Each Avatar represents an autonomous agent with a distinct role, system prompts, and behavioral preferences that can interact with users and other agents in group conversations.\n\nThe system architecture consists of:\n\n- **Avatar Registry**: Manages the lifecycle of all avatars, including creation, persistence, and configuration storage\n- **Avatar Settings**: UI layer for configuring avatar properties including name, role, appearance (avatar image), and skill associations\n- **Group Chat**: Enables multiple avatars to participate in collaborative conversations, facilitating multi-agent workflows\n- **Group Context & Routing**: Handles message routing between avatars in group conversations and maintains conversational context\n\n资料来源：[desktop/src/components/AvatarSettingsPanel.tsx](), [enterprise/features/agents/README.md](), [agenticx/collaboration/README.md]()\n\n## Avatar System Architecture\n\n### Avatar Configuration Model\n\nEach Avatar is defined by a configuration that includes:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `name` | string | Display name of the avatar |\n| `role` | string | Professional role description (e.g., \"Full-stack Developer\", \"Data Analyst\") |\n| `avatarUrl` | string | Path to the avatar's profile image |\n| `skills` | string[] | List of enabled skills for this avatar |\n| `systemPrompt` | string | Custom system prompt override |\n| `userPreference` | string | User preference injection for behavioral tuning |\n\n资料来源：[desktop/src/components/AvatarSettingsPanel.tsx](), [desktop/src/components/SettingsPanel.tsx]()\n\n### Avatar Persistence\n\nAvatars are persisted to disk in YAML format within each avatar's dedicated directory:\n\n```\n~/.agenticx/\n└── /\n └── avatar.yaml\n```\n\nThe UI indicates this clearly: \"保存后写入该分身目录下的 avatar.yaml\" (Saved to the avatar.yaml file under the avatar directory after saving).\n\n资料来源：[desktop/src/components/AvatarSettingsPanel.tsx]()\n\n## Avatar Settings Panel\n\nThe `AvatarSettingsPanel` component provides the primary interface for managing avatar configurations.\n\n### UI Components\n\n```\n┌─────────────────────────────────────────────┐\n│ Avatar Settings Panel │\n├─────────────────────────────────────────────┤\n│ [Avatar Image Preview] [Upload] [Clear] │\n│ • Consistent with sidebar and chat list │\n│ • Recommended: < 1.8MB square image │\n├─────────────────────────────────────────────┤\n│ 名称: [________________] │\n│ 角色: [________________] │\n│ 例：全栈开发工程师、数据分析师 │\n└─────────────────────────────────────────────┘\n```\n\n### Key Features\n\n1. **Avatar Image Management**\n - Preview support for uploaded images\n - Clear button to reset to default avatar\n - Image size validation (recommended < 1.8MB)\n - Visual consistency across sidebar, chat list, and sessions\n\n2. **Metadata Configuration**\n - `name`: Avatar display name\n - `role`: Professional role descriptor\n\n资料来源：[desktop/src/components/AvatarSettingsPanel.tsx]()\n\n## Avatar Creation Dialog\n\nThe `AvatarCreateDialog` component handles the initial creation of new avatars with skill selection.\n\n### Skill Assignment Workflow\n\n```mermaid\ngraph TD\n A[Create New Avatar] --> B[Load Available Skills]\n B --> C{Global Skills Disabled?}\n C -->|Yes| D[Filter Out Disabled Skills]\n C -->|No| E[Show All Skills]\n D --> F[Display Skill List]\n E --> F\n F --> G[User Toggles Skills On/Off]\n G --> H[Save Avatar with Skills]\n```\n\n### Skill Selection States\n\n| State | Visual Indicator | Description |\n|-------|-------------------|-------------|\n| Enabled | Cyan border with background | Skill is active for this avatar |\n| Disabled | Muted border, muted text | Skill is not used by this avatar |\n\n```tsx\n// Skill toggle button styling from AvatarCreateDialog.tsx\ndisabled\n ? \"border-border-strong text-text-muted\"\n : \"border-cyan-500/40 bg-cyan-500/10 text-cyan-400\"\n```\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](), [desktop/src/components/AvatarSettingsPanel.tsx]()\n\n## User Preferences and Style Injection\n\nThe Avatar system supports injecting user preferences into the system prompt of all agents. This feature is managed through the Settings Panel.\n\n### User Preference Configuration\n\n| Setting | Description | Character Limit |\n|---------|-------------|-----------------|\n| `userPreference` | Behavioral style instructions for agents | 500 characters |\n\nExample usage:\n```\n我不喜欢绕弯子，请直接给结论；\n偏好表格而非长段落；\n遇到歧义先问我再执行。\n```\n\nThis preference text is:\n- Injected into every conversation's system prompt\n- Applied to all agent responses\n- Stored in local browser storage for local-only effects\n\n资料来源：[desktop/src/components/SettingsPanel.tsx]()\n\n## Group Chat System\n\n### Overview\n\nGroup Chat enables multiple avatars to participate in collaborative conversations. This is particularly useful for complex tasks requiring diverse expertise.\n\n### Multi-Agent Collaboration Patterns\n\nBased on the collaboration documentation, AgenticX supports multiple collaboration modes for group interactions:\n\n资料来源：[agenticx/collaboration/README.md]()\n\n### Context Management\n\nThe Group Context system maintains conversational state across multiple participants:\n\n- **Message History**: Tracks all messages from all participants\n- **Participant State**: Maintains individual avatar states\n- **Turn Management**: Controls speaking order and发言权\n\n### Message Routing\n\nThe Group Router determines how messages are routed between avatars:\n\n```mermaid\ngraph LR\n A[User Message] --> B[Group Router]\n B --> C{Which Avatar?}\n C -->|Expert A| D[Process & Generate]\n C -->|Expert B| E[Process & Generate]\n C -->|Meta-Agent| F[Orchestrate Response]\n D --> G[Group Context Update]\n E --> G\n F --> G\n G --> H[Response to User]\n```\n\n资料来源：[enterprise/features/chat/README.md]()\n\n## Task Automation with Avatars\n\nAvatars can be associated with automated tasks for scheduled or triggered execution.\n\n### Task Configuration\n\nEach automated task can specify:\n\n| Property | Description |\n|----------|-------------|\n| `prompt` | The task instruction prompt |\n| `workspace` | Working directory for task execution |\n| `provider` | LLM provider for task execution |\n| `model` | Specific model to use |\n| `enabled` | Whether the task is active |\n| `lastRunAt` | Timestamp of last execution |\n| `lastRunStatus` | Execution result (success/error) |\n| `lastRunError` | Error message if failed |\n\n### Task List UI\n\nThe Task List component displays:\n\n- Task name and description\n- Execution model (provider/model)\n- Enable/disable toggle\n- Last execution status with timestamps\n- Error details for failed runs\n\n资料来源：[desktop/src/components/automation/TaskList.tsx]()\n\n## Integration Points\n\n### WeChat Integration\n\nAvatars can be bound to WeChat for receiving messages and triggering agent execution:\n\n- **Binding Method**: QR code scanning via WeChat iLink protocol\n- **Status Indicators**: Connected (green), Bound but not connected (yellow)\n- **Sidecar Port**: Local service for WeChat communication\n\n资料来源：[desktop/src/components/SettingsPanel.tsx]()\n\n### Meta-Agent (Machi)\n\nThe Meta-Agent system provides orchestration capabilities:\n\n- Central coordination of multiple avatars\n- Meta-agent SOUL saving and loading\n- Unified interface for managing complex multi-agent workflows\n\n资料来源：[desktop/src/components/SettingsPanel.tsx]()\n\n## Configuration Schema\n\n### Avatar YAML Structure\n\n```yaml\n# avatar.yaml\nname: \"Avatar Display Name\"\nrole: \"Professional Role\"\navatarUrl: \"/path/to/image.png\"\nskills:\n - skill_name_1\n - skill_name_2\nuserPreference: \"Behavioral preferences...\"\n```\n\n### Permission Modes\n\n| Mode | Behavior | Risk Level |\n|------|----------|------------|\n| `manual` | Confirm every tool execution | Safest |\n| `semi-auto` | Auto-approve whitelisted operations | Recommended |\n| `auto` | Execute all tools automatically | High Risk |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx]()\n\n## Summary\n\nThe Avatar and Group Chat system provides a comprehensive framework for:\n\n1. **Avatar Management**: Create, configure, and persist digital personas with distinct roles and skills\n2. **Skill Association**: Enable/disable skills per avatar with visual UI feedback\n3. **User Preference Injection**: Customize agent behavior across all conversations\n4. **Group Collaboration**: Enable multiple avatars to work together on complex tasks\n5. **Task Automation**: Associate avatars with automated tasks for scheduled execution\n6. **Multi-Channel Integration**: Connect avatars to external platforms like WeChat\n\nThe system is designed for flexibility, allowing fine-grained control over avatar behavior while supporting sophisticated multi-agent collaboration patterns.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：DemonDamon/AgenticX\n\n摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)。\n\n## 1. 安装坑 · 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Desktop app fails on startup: agx serve failed to start (local API not available)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4330954394974f1ab2f82c8645e1dce9 | https://github.com/DemonDamon/AgenticX/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：AgenticX + Machi v0.3.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：AgenticX + Machi v0.3.7\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4983001c0714fbe923df9e3263934b3 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_026abb56e0864ba4b60ba497e1a19084 | https://github.com/DemonDamon/AgenticX/issues/14 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Machi launch failure on mac\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Machi launch failure on mac\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1f85a307f6b44099b52dfdb50d13f91c | https://github.com/DemonDamon/AgenticX/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_170a543fa1d640b7a6c9c54d5b9ce6c1 | https://github.com/DemonDamon/AgenticX/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d8c2ce59a394bd8901a52ddaf36f821 | https://github.com/DemonDamon/AgenticX/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：AgenticX v0.3.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c05bccba0b02475cb74b550d42c91222 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：AgenticX v0.3.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.6\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_619eaf3ee1334cb6bc5db5adb67b7c8f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：AgenticX v0.3.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.8\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c0dad4f133a4a199f8b54083f16427f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：bash_exec fails to run any command on Windows (WinError 2)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bash_exec fails to run any command on Windows (WinError 2)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14230559f63c4fd8a7a8d1310b6284d0 | https://github.com/DemonDamon/AgenticX/issues/7 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：添加模型不支持codex 认证方式\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：添加模型不支持codex 认证方式\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b24824ec7b6e4e7fa6bc5b7b2874817c | https://github.com/DemonDamon/AgenticX/issues/4 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | release_recency=unknown\n\n\n",
"markdown_key": "agenticx",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:772408997",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/DemonDamon/AgenticX"
},
{
"evidence_id": "art_cf418b174cec44b0b8a477ac70c4328a",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/DemonDamon/AgenticX#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "AgenticX 说明书",
"toc": [
"https://github.com/DemonDamon/AgenticX 项目说明书",
"目录",
"Introduction to AgenticX",
"Overview",
"Platform Architecture",
"Core Components",
"Enterprise Identity & Access Management (IAM)",
"Audit & Compliance",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "8d4798b794f16182a8b18f1a7f7cc04c980aab18",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"requirements.txt",
"docs/release-note-guide.md",
"docs/cli.md",
"docs/index.md",
"docs/roadmap.md",
"docs/cc-bridge-protocol.md",
"docs/architecture_analysis_3layer.md",
"docs/changelog.md",
"docs/faq.md",
"docs/error-codes.md",
"docs/api/tools.md",
"docs/api/memory.md",
"docs/api/flow.md",
"docs/api/llms.md",
"docs/api/agents.md",
"docs/adr/0001-cc-invariants-provider-fault-and-deny-priority.md",
"docs/adr/0002-group-chat-workforce-bridge.md",
"docs/concepts/llm-providers.md",
"docs/concepts/tools.md",
"docs/concepts/architecture.md",
"docs/concepts/agent.md",
"docs/concepts/memory.md",
"docs/concepts/orchestration.md",
"docs/concepts/hooks.md",
"docs/concepts/flow.md",
"docs/guides/knowledge.md",
"docs/guides/multi-agent.md",
"docs/guides/group-chat-team-mode.md",
"docs/guides/security.md",
"docs/guides/firecrawl-local-mcp.md",
"docs/guides/longrun-task-sources.md",
"docs/guides/browser-long-running-task-cases.md",
"docs/guides/happy-coder-machi-integration.md",
"docs/guides/avatar.md",
"docs/guides/knowledge-base-mvp.md",
"docs/guides/first-agent.md",
"docs/guides/studio.md",
"docs/guides/observability.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# agenticx-desktop - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 agenticx-desktop 编译的 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 文档。 证据：`agenticx/skills/agenticx-a2a-connector/SKILL.md`, `agenticx/skills/agenticx-agent-builder/SKILL.md`, `agenticx/skills/agenticx-automation-crontask/SKILL.md`, `agenticx/skills/agenticx-deployer/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`agenticx/skills/agenticx-a2a-connector/SKILL.md`, `agenticx/skills/agenticx-agent-builder/SKILL.md`, `agenticx/skills/agenticx-automation-crontask/SKILL.md`, `agenticx/skills/agenticx-deployer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`INSTALL.md`, `README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install -r requirements.txt` 证据：`INSTALL.md` Claim：`clm_0005` supported 0.86\n- `pip install -e .` 证据：`INSTALL.md` Claim：`clm_0006` supported 0.86, `clm_0021` supported 0.86\n- `pip install agenticx` 证据：`README.md` Claim：`clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86 等\n- `pip install \"agenticx[memory]\" # Memory: mem0, chromadb, qdrant, redis, milvus` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install \"agenticx[document]\" # Document processing: PDF, Word, PPT parsing` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `pip install \"agenticx[graph]\" # Knowledge graph: networkx, neo4j, community detection` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `pip install \"agenticx[llm]\" # Extra LLMs: anthropic, ollama` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `pip install \"agenticx[monitoring]\" # Observability: prometheus, opentelemetry` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `pip install \"agenticx[mcp]\" # MCP protocol` 证据：`README.md` Claim：`clm_0013` supported 0.86\n- `pip install \"agenticx[database]\" # Database backends: postgres, SQLAlchemy` 证据：`README.md` Claim：`clm_0014` 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 或项目证据支撑，但仍不等于真实安装效果。 证据：`agenticx/skills/agenticx-a2a-connector/SKILL.md`, `agenticx/skills/agenticx-agent-builder/SKILL.md`, `agenticx/skills/agenticx-automation-crontask/SKILL.md`, `agenticx/skills/agenticx-deployer/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`agenticx/skills/agenticx-a2a-connector/SKILL.md`, `agenticx/skills/agenticx-agent-builder/SKILL.md`, `agenticx/skills/agenticx-automation-crontask/SKILL.md`, `agenticx/skills/agenticx-deployer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`INSTALL.md`, `README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`INSTALL.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`, `agenticx/skills/agenticx-a2a-connector/SKILL.md`, `agenticx/skills/agenticx-agent-builder/SKILL.md`, `agenticx/skills/agenticx-automation-crontask/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`INSTALL.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`INSTALL.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`, `agenticx/skills/agenticx-a2a-connector/SKILL.md`, `agenticx/skills/agenticx-agent-builder/SKILL.md`, `agenticx/skills/agenticx-automation-crontask/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`INSTALL.md`, `README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`.cursor/plans/2026-03-24-desktop-remote-backend.plan.md`, `.cursor/plans/2026-03-24-dmg-self-contained-packaging.plan.md`, `.cursor/plans/2026-05-06-enterprise-oidc-sso.plan.md`, `.cursor/plans/2026-05-07-symphony-longrun-internalization.plan.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_0022` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`INSTALL.md`, `README.md` Claim：`clm_0023` 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 体验。 证据：`agenticx/skills/agenticx-a2a-connector/SKILL.md`, `agenticx/skills/agenticx-agent-builder/SKILL.md`, `agenticx/skills/agenticx-automation-crontask/SKILL.md`, `agenticx/skills/agenticx-deployer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`INSTALL.md`, `README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2100\n- 重要文件覆盖：40/2100\n- 证据索引条目：89\n- 角色 / Skill 条目：9\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请基于 agenticx-desktop 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 agenticx-desktop 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 agenticx-desktop 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 9 个角色 / Skill / 项目文档条目。\n\n- **agenticx-a2a-connector**（skill）：Guide for using the A2A Agent-to-Agent communication protocol in AgenticX including agent discovery, skill invocation, remote agent cards, and distributed agent systems. Use when the user wants agents to communicate with each other, set up distributed agent systems, invoke remote agent skills, or build agent-to-agent workflows. 激活提示：当用户任务与“agenticx-a2a-connector”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-a2a-connector/SKILL.md`\n- **agenticx-agent-builder**（skill）：Guide for creating and configuring AgenticX agents with roles, goals, tools, LLM providers, and execution strategies. Use when the user wants to create agents, assign tools to agents, configure LLM backends, set up agent execution, or build multi-agent systems. 激活提示：当用户任务与“agenticx-agent-builder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-agent-builder/SKILL.md`\n- **agenticx-automation-crontask**（skill）：Build and maintain Machi Desktop scheduled cron tasks — default workspace ~/.agenticx/crontask, schedule task tool, execution contract, and user-facing output. Use when the user wants recurring automation, crontab-style jobs, or to author/fix automation task prompts. 激活提示：当用户任务与“agenticx-automation-crontask”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-automation-crontask/SKILL.md`\n- **agenticx-deployer**（skill）：Guide for deploying AgenticX agents to production including Docker containerization, Kubernetes orchestration, Volcengine AgentKit cloud deployment, and API server setup. Use when the user wants to deploy agents, containerize applications, set up Kubernetes, configure cloud deployment, or run the AgenticX API server in production. 激活提示：当用户任务与“agenticx-deployer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-deployer/SKILL.md`\n- **agenticx-memory-architect**（skill）：Guide for setting up and using the AgenticX memory system including Mem0 integration, long-term memory, context management, and memory-enhanced agents. Use when the user wants to add memory to agents, persist conversation history, build memory-aware workflows, or integrate with Mem0 for long-term recall. 激活提示：当用户任务与“agenticx-memory-architect”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-memory-architect/SKILL.md`\n- **agenticx-quickstart**（skill）：AgenticX zero-to-hero quickstart guide. Use when the user wants to get started with AgenticX, create their first project, build their first agent, or run their first workflow. Covers installation, project scaffolding, agent creation, task execution, and CLI basics. 激活提示：当用户任务与“agenticx-quickstart”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-quickstart/SKILL.md`\n- **agenticx-skill-manager**（skill）：Guide for managing AgenticX skills including listing, searching, installing, uninstalling, publishing, and running a skill registry server. Use when the user wants to manage skills, find available skills, publish custom skills, set up a skill registry, or understand the skill ecosystem. 激活提示：当用户任务与“agenticx-skill-manager”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-skill-manager/SKILL.md`\n- **agenticx-tool-creator**（skill）：Guide for creating custom tools in AgenticX including function decorator tools, MCP tool integration, tool registries, and remote tool access. Use when the user wants to create tools for agents, integrate external APIs as tools, build MCP servers, or extend agent capabilities with custom functions. 激活提示：当用户任务与“agenticx-tool-creator”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-tool-creator/SKILL.md`\n- **agenticx-workflow-designer**（skill）：Guide for designing and running AgenticX workflows including sequential pipelines, parallel execution, graph-based orchestration, conditional routing, and trigger services. Use when the user wants to create workflows, orchestrate multiple agents, design agent pipelines, or set up complex multi-step processes. 激活提示：当用户任务与“agenticx-workflow-designer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`agenticx/skills/agenticx-workflow-designer/SKILL.md`\n\n## 证据索引\n\n- 共索引 89 条证据。\n\n- **agenticx.agents**（documentation）：The core agent definition. Agents are stateless — all state lives in the executor context. 证据：`docs/api/agents.md`\n- **法律文档索引**（documentation）：文档 仓库路径 说明 ------ ---------- ------ 用户协议 user agreement.md ./user agreement.md 软件许可及服务协议（原 EULA） 隐私协议 privacy policy.md ./privacy policy.md 隐私政策正文 证据：`docs/legal/README.md`\n- **Enterprise 部署说明（Vercel + 外部 Gateway）**（documentation）：Enterprise 部署说明（Vercel + 外部 Gateway） 证据：`enterprise/docs/deployment/README.md`\n- **性能基线归档（可选）**（documentation）：- 脚本： enterprise/scripts/perf/sso-200-concurrent.js - 建议文件名： enterprise/docs/perf-baselines/sso-start-YYYYMMDD.txt （直接粘贴 k6 终端摘要） 证据：`enterprise/docs/perf-baselines/README.md`\n- **AgenticX · Git Hooks**（documentation）：本地 pre-commit / commit-msg 防御，用于阻止凭据 / 客户识别字样进入开源仓。 证据：`.githooks/README.md`\n- **AGENTS.md**（documentation）：Learned User Preferences - 默认使用中文回复；技术术语可按需保留英文。 - 进行 git commit 时，提交信息必须包含 Made-with: Damon Li ，并偏好按功能点分组、附结构化需求块（如 FR/NFR/AC）。 - Plan 文档必须落盘到 .cursor/plans/ 并随代码一起提交，不能遗漏。 - Desktop 端视觉重塑：App 命名为「Machi」，应用图标偏好《全职猎人》玛奇神韵的极客化解构——纯黑白高对比度矢量线稿（类 NousResearch 风格），仅保留至颈部的大头贴（无肩/无头巾），以高马尾和冷酷洞悉的眼神凸显“绝对理性”的高级开发者工具气质，拒绝低端二次元感或渐变色。 - 配置面板遵循关注分离：MCP 独立 tab 不混入 Provider；用户可改配置项必须提供 Desktop 设置面板 GUI；模型切换需持久化；新建或编辑分身时须能设置 默认模型 并真正落盘生效，点击分身或重启应用后均须按「分身 → 会话」维度回显最后选择的模型，不得退化为「未选模型」或被全局默认覆盖。MCP 市场 UX：默认（未搜索）视图仅展示官方/认证/托管精选，用户主动搜索必须返回 全量结果 ，不得以「官方认证+托管+可安装」等条件继续过滤；已安装/已添加 MCP 在列表中须明确显示「已添加」（绿色状态点），不得仍保留「添加」按钮造成误点；安装/添加需有即时进度或状态反馈，失败/报错 toast 应靠近触发卡片就近展示，避免仅顶栏提示导致未上滚时看不到；列表内解释性长备注（如\"点击工具名可启用/禁用 灰色=已禁用… \"等）宜删除… 证据：`AGENTS.md`\n- **AgenticX: Unified Multi-Agent Framework**（documentation）：AgenticX: Unified Multi-Agent Framework 证据：`README.md`\n- **AgenticX Docker 数据库部署方案**（documentation）：本项目提供了完整的Docker部署方案，支持AgenticX框架所需的各种数据库和存储服务。 证据：`deploy/README.md`\n- **Machi Desktop — macOS Alpha Preview**（documentation）：Machi Desktop — macOS Alpha Preview 证据：`desktop/README.md`\n- **AgenticX Enterprise**（documentation）：企业级大模型应用一体化平台 —— 前台 · 后台 · AI 网关三端联动 证据：`enterprise/README.md`\n- **AgenticX 测试套件**（documentation）：1. test core.py - 核心模块完整测试 这是 agenticx.core 模块的完整测试套件，使用 pytest 框架编写。 证据：`tests/README.md`\n- **AgenticX CLI**（documentation）：AgenticX 命令行工具，用于快速创建和管理 AgenticX 项目。提供项目脚手架、智能体创建、工作流管理等功能。 证据：`agenticx/cli/README.md`\n- **AgenticX A2A Agent for AgentKit**（documentation）：This template creates an A2A Agent-to-Agent service deployed via AgentKit A2AApp. 证据：`agenticx/cli/templates/volcengine/a2a/README.md`\n- **AgenticX Basic Agent for AgentKit**（documentation）：This template creates a basic AgenticX agent deployed via AgentKit SimpleApp. 证据：`agenticx/cli/templates/volcengine/basic/README.md`\n- **AgenticX Streaming Agent for AgentKit**（documentation）：AgenticX Streaming Agent for AgentKit 证据：`agenticx/cli/templates/volcengine/basic_stream/README.md`\n- **AgenticX Knowledge Agent for AgentKit**（documentation）：AgenticX Knowledge Agent for AgentKit 证据：`agenticx/cli/templates/volcengine/knowledge/README.md`\n- **AgenticX MCP Tool Agent for AgentKit**（documentation）：AgenticX MCP Tool Agent for AgentKit 证据：`agenticx/cli/templates/volcengine/mcp/README.md`\n- **AgenticX M8.5: 多智能体协作框架**（documentation）：AgenticX M8.5多智能体协作框架实现了8种核心协作模式，支持从简单任务分发到复杂团队协作的全场景覆盖。基于MAS（Multi-Agent System）理论，提供标准化的协作模式实现。 证据：`agenticx/collaboration/README.md`\n- **AgenticX Memory System**（documentation）：The AgenticX memory system provides a pluggable, shareable memory architecture based on open standards. It enables agents to maintain both short-term session memory and long-term persistent memory through the Model Context Protocol MCP . 证据：`agenticx/memory/README.md`\n- **AgenticX M9: 可观测性与分析模块**（documentation）：M9模块是AgenticX框架的可观测性系统，提供全面的监控、分析和评估功能。 证据：`agenticx/observability/README.md`\n- **AgenticX Protocols Module M8**（documentation）：The agenticx.protocols module implements the Agent-to-Agent A2A communication protocol, inspired by Google's A2A protocol, enabling structured collaboration between AgenticX agents. 证据：`agenticx/protocols/README.md`\n- **M15: 智能检索系统**（documentation）：AgenticX框架的智能检索系统，提供统一、智能、可扩展的检索能力，支持从基础检索到完全Agentic化RAG流程的全栈解决方案。 证据：`agenticx/retrieval/README.md`\n- **AgenticX Sandbox 模块**（documentation）：AgenticX Sandbox 模块是一个 统一抽象层（Adapter Layer） ，为不同的沙箱实现（如 OpenSandbox、Microsandbox、Docker 等）提供统一的 API 接口。这使得 AgenticX 可以灵活地接入各种 sandbox SDK，同时保持上层代码的一致性。 证据：`agenticx/sandbox/README.md`\n- **AgenticX Tools: 通用 MCP 客户端架构**（documentation）：本文档详细介绍了 AgenticX 框架中用于连接远程服务的工具系统，特别是其通用的 MCP Model Context Protocol 客户端架构。 证据：`agenticx/tools/README.md`\n- **@agenticx/app-admin-console**（documentation）：- @agenticx/feature-iam — 账号 · 部门 · 角色 · 权限（前端组件）；数据层见 @agenticx/iam-core + PostgreSQL 证据：`enterprise/apps/admin-console/README.md`\n- **AgenticX Edge Agent**（documentation）：🛡️ 端侧安全闭环 Sidecar — 自研 · Go · 单二进制 · 最小权限 证据：`enterprise/apps/edge-agent/README.md`\n- **AgenticX AI Gateway**（documentation）：1. 三路路由 ：本地 · 企业独享云 · 第三方远程 2. 策略引擎 ：关键词 / 正则 / PII / Prompt 规则 3. 审计日志 ：JSON 结构化落盘（写 ClickHouse / 本地文件） 4. OpenAI 兼容 API ： /v1/chat/completions / /v1/embeddings 5. 管控 API ：给 admin-console 读写配置 证据：`enterprise/apps/gateway/README.md`\n- **@agenticx/app-web-portal**（documentation）：企业员工前台 Web App。剥离自 AgenticX-Website 的 app/agents/ 。 证据：`enterprise/apps/web-portal/README.md`\n- **Enterprise Deploy Notes Hechuang**（documentation）：- docker-compose/dev.yml ：开发期基础依赖（Postgres + Redis）。 - docker-compose/prod.yml ：生产模板（Nginx 入口 + 双网关 + 前后台 + PostgreSQL 主从 + Redis）。 - nginx/gateway.conf ：公网入口反向代理与基础限流模板。 - config/policies.yaml ：网关策略包装载清单（生产可按客户策略扩展）。 证据：`enterprise/deploy/README.md`\n- **@agenticx/feature-agents**（documentation）：@agenticx/feature-agents 智能体 · 分身 使用 证据：`enterprise/features/agents/README.md`\n- **@agenticx/feature-audit**（documentation）：🛡️ 审计日志 — 自研 · 多租户 · 不可篡改 · 支持 OTLP 标准导出 证据：`enterprise/features/audit/README.md`\n- **@agenticx/feature-chat**（documentation）：@agenticx/feature-chat 对话工作区（从 AgenticX-Website 剥离） 使用 证据：`enterprise/features/chat/README.md`\n- **@agenticx/feature-iam**（documentation）：@agenticx/feature-iam 身份 · 租户 · 部门 · 角色 · 权限 使用 证据：`enterprise/features/iam/README.md`\n- **@agenticx/feature-knowledge-base**（documentation）：@agenticx/feature-knowledge-base 知识库 使用 证据：`enterprise/features/knowledge-base/README.md`\n- **@agenticx/feature-metering**（documentation）：@agenticx/feature-metering 计量 · 四维查询（部门-员工-厂商-时间） 使用 证据：`enterprise/features/metering/README.md`\n- **@agenticx/feature-model-service**（documentation）：@agenticx/feature-model-service 模型服务管理（Provider/Model/Key） 使用 证据：`enterprise/features/model-service/README.md`\n- **@agenticx/feature-policy**（documentation）：- 规则包管理 ：支持 builtin/custom 两类规则包，builtin 可启停但不可删除。 - 规则管理 ：支持 keyword / regex / pii 三种规则，状态分为 draft / active / disabled 。 - 适用范围 ： applies to 支持部门、角色、用户白名单/黑名单、客户端、阶段（request/response）。 - 发布流程 ： publish 生成租户快照并写入 policy publish events ，同时写磁盘快照供 Gateway 热加载。 - 回滚流程 ： rollback 以历史快照再发布一个新版本，不直接覆写旧版本。 - 自审计 ：规则变更与发布通过 gateway audit events 记录 policy rule change / policy publish 事件。 证据：`enterprise/features/policy/README.md`\n- **@agenticx/feature-settings**（documentation）：@agenticx/feature-settings 设置面板 使用 证据：`enterprise/features/settings/README.md`\n- **@agenticx/feature-tools-mcp**（documentation）：@agenticx/feature-tools-mcp 工具 · MCP 接入 使用 证据：`enterprise/features/tools-mcp/README.md`\n- **@agenticx/auth**（documentation）：- OidcClientService ：OIDC discovery 缓存、构造授权 URL、处理 callback code exchange - mapClaimsToAuthUser ：按 claim mapping 解析 email/displayName/dept/roles - buildStateCookieValue / validateStateFromCookie ：state/nonce/pkce verifier 的加密 cookie 存储与校验（ AES-256-GCM ，密钥材料经 HKDF 从 SSO STATE SIGNING SECRET 派生） - encryptSecret / decryptSecret ：AES-256-GCM 加密 provider client secret 落库字段 证据：`enterprise/packages/auth/README.md`\n- **@agenticx/branding**（documentation）：@agenticx/branding 白标组件（logo/色系/文案动态注入） 证据：`enterprise/packages/branding/README.md`\n- **@agenticx/config**（documentation）：@agenticx/config 配置加载器（品牌 · feature flag · 插件） 证据：`enterprise/packages/config/README.md`\n- **@agenticx/core-api**（documentation）：@agenticx/core-api 类型契约 · OpenAPI 生成 证据：`enterprise/packages/core-api/README.md`\n- **@agenticx/db-schema**（documentation）：@agenticx/db-schema Drizzle schema（多租户字段预留） 证据：`enterprise/packages/db-schema/README.md`\n- **@agenticx/policy-engine Go**（documentation）：- RulePack manifest 加载（支持 extends 继承链） - 关键词检测（Trie 自动机） - 正则与 PII 基线检测（手机号/邮箱/身份证/银行卡/API Key） - action 处理： block / redact / warn - 命中事件结构化输出（供网关审计与前端提示） 证据：`enterprise/packages/policy-engine/README.md`\n- **agenticx-sdk Python**（documentation）：AgenticX Enterprise 的 Python 客户端 SDK，供后端服务/脚本/Machi 桌面端（Python 侧）调用。 证据：`enterprise/packages/sdk-py/README.md`\n- **@agenticx/sdk-ts**（documentation）：@agenticx/sdk-ts TypeScript 客户端 SDK（给 Machi 接） 证据：`enterprise/packages/sdk-ts/README.md`\n- **@agenticx/telemetry**（documentation）：@agenticx/telemetry 埋点 · 审计上报 证据：`enterprise/packages/telemetry/README.md`\n- **@agenticx/ui**（documentation）：@agenticx/ui shadcn 组件 + 主题 token 证据：`enterprise/packages/ui/README.md`\n- **moderation-finance**（documentation）：详见 enterprise/docs/plugin-protocol/ 证据：`enterprise/plugins/moderation-finance/README.md`\n- **moderation-medical**（documentation）：详见 enterprise/docs/plugin-protocol/ 证据：`enterprise/plugins/moderation-medical/README.md`\n- **moderation-pii-baseline**（documentation）：详见 enterprise/docs/plugin-protocol/ 证据：`enterprise/plugins/moderation-pii-baseline/README.md`\n- **theme-default**（documentation）：详见 enterprise/docs/plugin-protocol/ 证据：`enterprise/plugins/theme-default/README.md`\n- **tool-doc-review**（documentation）：详见 enterprise/docs/plugin-protocol/ 证据：`enterprise/plugins/tool-doc-review/README.md`\n- **tool-watermark**（documentation）：详见 enterprise/docs/plugin-protocol/ 证据：`enterprise/plugins/tool-watermark/README.md`\n- **enterprise/scripts — 脚本一览**（documentation）：本目录收纳 enterprise（前台 web-portal + 后台 admin-console + 网关 apps/gateway）所需的本机开发与 E2E / 压测脚本。所有脚本默认相对仓库根 enterprise/ 工作；推荐在 enterprise/ 目录下执行，例如： 证据：`enterprise/scripts/README.md`\n- **Mock SAML IdP Fixture**（documentation）：Local-only SAML 2.0 Identity Provider used for integration tests and manual SAML flow walkthroughs in web-portal / admin-console . 证据：`enterprise/scripts/sso/mock-saml-idp/README.md`\n- **AgenticX + AgentKit 集成指南**（documentation）：基于 AgenticX 构建智能体，一键部署到火山引擎 AgentKit 平台。 证据：`examples/agenticx-for-agentkit/README.md`\n- **Project Migrated**（documentation）：This project has been migrated to a new repository. Please find the latest version at: 证据：`examples/agenticx-for-deepresearch/README.md`\n- **AgenticX 文档解析器**（documentation）：基于 AgenticX 框架和 MinerU 工具的智能文档解析演示程序。这是一个完整的文档解析解决方案，支持多种文档格式的智能解析，提供友好的交互界面和强大的解析能力。 证据：`examples/agenticx-for-docparser/README.md`\n- 其余 29 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/api/agents.md`, `docs/legal/README.md`, `enterprise/docs/deployment/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/api/agents.md`, `docs/legal/README.md`, `enterprise/docs/deployment/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction to AgenticX**：importance `high`\n - source_paths: README.md, agenticx/__init__.py\n- **Quick Start Guide**：importance `high`\n - source_paths: examples/m5_agent_demo.py, agenticx/core/agent.py, agenticx/core/agent_executor.py\n- **Installation Guide**：importance `high`\n - source_paths: INSTALL.md, pyproject.toml\n- **System Architecture**：importance `high`\n - source_paths: docs/concepts/architecture.md, docs/architecture_analysis_3layer.md, agenticx/core/workflow_engine.py\n- **Core Abstractions**：importance `high`\n - source_paths: agenticx/core/agent.py, agenticx/core/task.py, agenticx/core/tool.py, agenticx/core/component.py, agenticx/core/event_bus.py\n- **Agent Core System**：importance `high`\n - source_paths: agenticx/core/agent_executor.py, agenticx/core/self_repair.py, agenticx/core/overflow_recovery.py, agenticx/core/task_validator.py, agenticx/core/reflector.py\n- **Meta-Agent and Team Management**：importance `medium`\n - source_paths: agenticx/runtime/agent_runtime.py, agenticx/runtime/team_manager.py, agenticx/runtime/meta_tools.py, agenticx/runtime/prompts/meta_agent.py, agenticx/collaboration/workforce/coordinator.py\n- **Tool System and MCP Hub**：importance `high`\n - source_paths: agenticx/tools/function_tool.py, agenticx/tools/mcp_hub.py, agenticx/tools/remote_v2.py, agenticx/tools/openapi_toolset.py, agenticx/tools/sandbox_tools.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `8d4798b794f16182a8b18f1a7f7cc04c980aab18`\n- inspected_files: `pyproject.toml`, `README.md`, `requirements.txt`, `docs/release-note-guide.md`, `docs/cli.md`, `docs/index.md`, `docs/roadmap.md`, `docs/cc-bridge-protocol.md`, `docs/architecture_analysis_3layer.md`, `docs/changelog.md`, `docs/faq.md`, `docs/error-codes.md`, `docs/api/tools.md`, `docs/api/memory.md`, `docs/api/flow.md`, `docs/api/llms.md`, `docs/api/agents.md`, `docs/adr/0001-cc-invariants-provider-fault-and-deny-priority.md`, `docs/adr/0002-group-chat-workforce-bridge.md`, `docs/concepts/llm-providers.md`\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: 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Desktop app fails on startup: agx serve failed to start (local API not available)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4330954394974f1ab2f82c8645e1dce9 | https://github.com/DemonDamon/AgenticX/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：AgenticX + Machi v0.3.7\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：AgenticX + Machi v0.3.7\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_f4983001c0714fbe923df9e3263934b3 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_026abb56e0864ba4b60ba497e1a19084 | https://github.com/DemonDamon/AgenticX/issues/14 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Machi launch failure on mac\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Machi launch failure on mac\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1f85a307f6b44099b52dfdb50d13f91c | https://github.com/DemonDamon/AgenticX/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_170a543fa1d640b7a6c9c54d5b9ce6c1 | https://github.com/DemonDamon/AgenticX/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2d8c2ce59a394bd8901a52ddaf36f821 | https://github.com/DemonDamon/AgenticX/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：DemonDamon/AgenticX\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 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：AgenticX + Machi v0.3.7（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Machi launch failure on mac（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion（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/DemonDamon/AgenticX 项目说明书\n\n生成时间：2026-05-15 23:21:36 UTC\n\n## 目录\n\n- [Introduction to AgenticX](#page-introduction)\n- [Quick Start Guide](#page-quickstart)\n- [Installation Guide](#page-installation)\n- [System Architecture](#page-architecture)\n- [Core Abstractions](#page-core-abstractions)\n- [Agent Core System](#page-agent-core)\n- [Meta-Agent and Team Management](#page-meta-agent)\n- [Tool System and MCP Hub](#page-tool-system)\n- [Memory System](#page-memory-system)\n- [Avatar and Group Chat](#page-avatar-system)\n\n\n\n## Introduction to AgenticX\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Quick Start Guide](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md)\n- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n- [desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n- [enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/departments/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/departments/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)\n- [enterprise/apps/admin-console/src/app/admin/models/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx)\n- [enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n \n\n# Introduction to AgenticX\n\n## Overview\n\nAgenticX is a comprehensive multi-platform AI agent framework designed to enable intelligent autonomous agents (\"分身\", \"avatars\") capable of executing complex tasks across enterprise and desktop environments. The framework provides a unified architecture for building, deploying, and managing AI agents with built-in support for skill management, task automation, knowledge bases, and enterprise identity & access management (IAM).\n\n资料来源：[enterprise/features/agents/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n资料来源：[examples/agenticx-for-agentkit/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n## Platform Architecture\n\nAgenticX consists of three primary deployment surfaces:\n\n| Platform | Purpose | Key Components |\n|----------|---------|----------------|\n| **Enterprise Admin Console** | Centralized administration for organizations | User Management, Role Management, Department Hierarchy, Audit Logs, Model Configuration |\n| **Enterprise Web Portal** | User-facing authentication and portal access | OAuth/Auth integration, Apache 2.0 licensed, ISO27001 & SOC2 compliant |\n| **Desktop Application** | Local agent execution and management | Task Automation, Settings Panel, Skill Management, WeChat Integration |\n\n资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Architecture Diagram\n\n```mermaid\ngraph TD\n subgraph Enterprise[\"Enterprise Layer\"]\n A[Admin Console] --> B[IAM System]\n A --> C[Audit Logs]\n A --> D[Model Management]\n B --> E[Users]\n B --> F[Roles]\n B --> G[Departments]\n end\n \n subgraph Desktop[\"Desktop Layer\"]\n H[Desktop App] --> I[Skill Manager]\n H --> J[Task Automation]\n H --> K[Settings Panel]\n H --> L[WeChat Integration]\n end\n \n subgraph Integration[\"External Integrations\"]\n M[Volcano Engine]\n N[AgentKit]\n O[Knowledge Base]\n end\n \n Desktop --> Integration\n Enterprise --> Desktop\n```\n\n## Core Components\n\n### 1. Agent Feature Module\n\nThe agent feature (`@agenticx/feature-agents`) provides the core agentic capabilities for creating intelligent avatars (\"分身\") that can autonomously execute tasks.\n\n资料来源：[enterprise/features/agents/README.md:5](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n### 2. Knowledge Base Feature\n\nThe knowledge base module (`@agenticx/feature-knowledge-base`) enables agents to access and utilize structured information repositories for enhanced decision-making.\n\n资料来源：[enterprise/features/knowledge-base/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n\n### 3. Task Automation System\n\nThe desktop application supports automated task execution with configurable prompts, workspace assignments, and model selection.\n\n| Property | Description |\n|----------|-------------|\n| `task.enabled` | Boolean flag to enable/disable automation |\n| `task.prompt` | Custom prompt instructions for the agent |\n| `task.workspace` | Designated workspace path for task execution |\n| `task.provider` | AI provider identifier (e.g., openai, volcengine) |\n| `task.model` | Specific model to use for execution |\n| `task.lastRunAt` | Timestamp of last execution |\n| `task.lastRunStatus` | Execution result: `success` or `error` |\n\n资料来源：[desktop/src/components/automation/TaskList.tsx:10](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n\n### 4. Settings Management\n\nThe desktop application provides comprehensive settings management including:\n\n- **Provider Configuration**: API keys and model selection\n- **Environment Dependencies**: External executable management with installation states (installed, installing, manual_required, not_installed)\n- **Global Tool Paths**: Third-party tool scanning configuration\n- **WeChat Integration**: Personal WeChat binding via iLink protocol\n- **GWS Studio Configuration**: Gateway studio base URL settings\n\n资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n资料来源：[desktop/src/store.ts:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n## Enterprise Identity & Access Management (IAM)\n\n### User Management\n\nThe admin console provides comprehensive user management with the following capabilities:\n\n- User search by email, name, or ID\n- Status filtering (active/inactive/all)\n- Department filtering\n- Pagination with configurable page size\n- User detail drawer with edit capabilities\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/users/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)\n\n### Role Management\n\nRole-based access control with scope matrix editor for granular permission configuration:\n\n```mermaid\ngraph LR\n A[Role] --> B[Code]\n A --> C[Display Name]\n A --> D[Permissions/Scopes]\n D --> E[audit:read]\n D --> F[users:manage]\n D --> G[models:configure]\n D --> H[roles:admin]\n```\n\n| Role Operation | Description |\n|----------------|-------------|\n| Create Role | Define new role with code, name, and scope matrix |\n| Edit Role | Modify existing role properties and permissions |\n| Duplicate Role | Copy existing role configuration |\n| Manage Members | View and manage users assigned to specific roles |\n| Role Removal | PATCH update member's role codes when removed |\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n\n### Department Hierarchy\n\nHierarchical organizational structure with the following features:\n\n- Tree-based department navigation\n- Drill-down navigation with breadcrumb trail\n- Export department structure functionality\n- Refresh capabilities for real-time updates\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/departments/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/departments/page.tsx)\n\n### Bulk Import\n\nCSV-based bulk user provisioning with a 5-step workflow:\n\n1. **Upload CSV** - Drag & drop or paste CSV content\n2. **Column Mapping** - Map CSV columns to system fields\n3. **Pre-check** - Validate data integrity and constraints\n4. **Server Write** - Batch write to backend with transaction support\n5. **Results** - Success/failure reporting with downloadable failure CSV\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)\n\n## Audit & Compliance\n\n### Audit Log System\n\nComprehensive audit logging with table chain verification:\n\n- Event type filtering\n- User and model search\n- Full table chain validation status\n- Chain integrity indicators (complete/failed)\n- Scanned row counts\n\n| Verification Status | Badge Color | Description |\n|--------------------|-------------|-------------|\n| Chain Complete | Success (Green) | Full table chain validation passed |\n| Chain Failed | Destructive (Red) | Validation failed with reason |\n| Loading | Warning (Yellow) | Validation in progress |\n\n资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n\n### Security Compliance\n\nThe enterprise portal demonstrates commitment to security standards:\n\n- Apache 2.0 License\n- ISO27001 Certification\n- SOC2 Compliance\n\n资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n\n## Model Management\n\nThe admin console provides centralized model configuration:\n\n- **Provider Management**: Add/remove AI providers\n- **Model Registration**: Add models with custom IDs and display labels\n- **Provider Templates**: Pre-configured provider templates for quick setup\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| Model ID | Provider-specific model identifier | `gpt-4o-mini`, `qwen-plus` |\n| Display Name | Human-readable label | \"GPT-4o Mini (Fast)\" |\n| Provider | Parent provider configuration | volcengine, openai |\n\n资料来源：[enterprise/apps/admin-console/src/app/admin/models/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx)\n\n## External Integrations\n\n### AgentKit Integration\n\nAgenticX supports integration with LangChain's AgentKit framework for Volcano Engine deployment:\n\n```bash\n# Deployment workflow\nagx volcengine deploy --region --app-name \nagx volcengine logs [--follow]\nagx volcengine destroy\n```\n\nThe integration includes:\n\n- Complete agent definition templates\n- Docker deployment configurations\n- Synchronous and asynchronous testing support\n- Tool definition examples\n\n资料来源：[examples/agenticx-for-agentkit/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n### WeChat Integration\n\nDesktop application supports personal WeChat binding via the official iLink protocol:\n\n- QR code scanning for account binding\n- Automatic sidecar service management\n- Message relay to Machi agent for agent execution\n\n资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Skill Management\n\nSkills extend agent capabilities through modular configurations:\n\n| Skill Source | Location | Description |\n|--------------|----------|-------------|\n| Global Skills | System-wide | Shared across all agent instances |\n| Project Skills | `.agents/skills/` | Project-specific skill definitions |\n| Third-party Skills | Custom scan paths | External skill repositories |\n| SKILL.md | Configuration files | Standard skill definition format |\n\n| Installation State | Badge | Description |\n|-------------------|-------|-------------|\n| Installed | Emerald | Green badge, globally available |\n| Installing | Muted | In progress, non-blocking |\n| Manual Required | Warning | User action needed |\n| Not Installed | Default | Available for installation |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n资料来源：[desktop/src/components/automation/TaskList.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n\n## State Management\n\nThe desktop application uses a centralized store architecture:\n\n```mermaid\ngraph TD\n A[Global Store] --> B[Chat Panes]\n A --> C[Agent Management]\n A --> D[Settings State]\n A --> E[Token Dashboard]\n A --> F[Confirmation Dialogs]\n \n B --> B1[Messages]\n B --> B2[Session History]\n B --> B3[Context Inheritance]\n \n C --> C1[Sub Agents]\n C --> C2[Selected Agent]\n \n D --> D1[Provider Config]\n D --> D2[Model Config]\n D --> D3[API Keys]\n```\n\nKey store functions:\n\n- `addSubAgent` / `removeSubAgent` - Agent lifecycle management\n- `setSelectedSubAgent` - Active agent switching\n- `openSettings` / `updateSettings` - Configuration management\n- `openTokenDashboard` - Usage monitoring\n- `openConfirm` / `closeConfirm` - User confirmation workflow\n\n资料来源：[desktop/src/store.ts:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Installation Guide](#page-installation), [Agent Core System](#page-agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n- [examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n- [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md)\n- [enterprise/features/tools-mcp/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/tools-mcp/README.md)\n \n\n# Quick Start Guide\n\nAgenticX is a multi-agent collaboration framework that enables intelligent agents (referred to as \"分神\" or avatars) to work together using various collaboration patterns. This guide provides a streamlined path to getting started with AgenticX for development and deployment.\n\n## Prerequisites\n\nBefore you begin, ensure your environment meets the following requirements:\n\n| Requirement | Version/Details |\n|-------------|-----------------|\n| Python | 3.10+ |\n| Package Manager | pip or uv |\n| API Keys | Provider-specific (OpenAI, Azure, etc.) |\n| Network | Access to model provider endpoints |\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n## Installation\n\n### Core Package\n\nInstall the AgenticX core package using pip:\n\n```bash\npip install agenticx\n```\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n### Example Dependencies\n\nFor specific integrations, install example-specific requirements:\n\n```bash\npip install -r requirements.txt\n```\n\n## Project Structure\n\nA typical AgenticX project follows this structure:\n\n```\nagenticx-for-intent-recognition/\n├── main.py # Main entry point\n├── config.yaml # Configuration file\n├── requirements.txt # Python dependencies\n├── agents/ # Agent definitions\n├── workflows/ # Workflow definitions\n├── tools/ # Tool implementations\n└── tests/ # Test suite\n```\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n## Configuration\n\n### Step 1: Create Configuration File\n\nCopy the `config.yaml` template and configure your API keys:\n\n```yaml\n# Example config.yaml structure\nprovider: openai\nmodel: gpt-4o-mini\napi_key: your-api-key-here\n```\n\n### Step 2: Adjust Settings\n\nModify configuration parameters based on your requirements:\n\n- **Model Selection**: Choose appropriate models for your use case\n- **API Endpoint**: Configure provider-specific endpoints if needed\n- **Timeout Settings**: Adjust request timeouts for long-running tasks\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n## Building Your First Agent\n\n### Basic Agent Creation\n\nCreate a simple agent using the AgenticX core API:\n\n```python\nfrom agenticx import Agent, AgentConfig\n\nconfig = AgentConfig(\n name=\"demo_agent\",\n model=\"gpt-4o-mini\",\n tools=[\"bash_exec\", \"file_read\"]\n)\n\nagent = Agent(config)\n```\n\n### Agent Patterns\n\nAgenticX supports multiple collaboration patterns. Register custom patterns in the manager:\n\n```python\nfrom agenticx.collaboration import CollaborationMode, CustomPattern\n\npattern_classes = {\n CollaborationMode.CUSTOM_PATTERN: CustomPattern,\n}\n```\n\n资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n\n## Collaboration Patterns\n\nAgenticX provides built-in collaboration modes for multi-agent scenarios:\n\n```mermaid\ngraph TD\n A[User Request] --> B[Manager Agent]\n B --> C[Sub-Agent 1]\n B --> D[Sub-Agent 2]\n B --> E[Sub-Agent N]\n C --> F[Result Aggregation]\n D --> F\n E --> F\n F --> G[Final Response]\n \n style B fill:#e1f5fe\n style F fill:#fff3e0\n```\n\n### Available Patterns\n\n| Pattern | Use Case | Complexity |\n|---------|----------|------------|\n| Sequential | Ordered task execution | Low |\n| Parallel | Concurrent independent tasks | Medium |\n| Hierarchical | Manager-subordinate coordination | High |\n| Custom | Domain-specific collaboration logic | Variable |\n\n资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n\n## Enterprise Features\n\nThe enterprise edition extends AgenticX with additional capabilities:\n\n### Available Feature Modules\n\n| Module | Package | Purpose |\n|--------|---------|---------|\n| Agents | `@agenticx/feature-agents` | Avatar management and configuration |\n| Knowledge Base | `@agenticx/feature-knowledge-base` | Document indexing and retrieval |\n| Identity & Access | `@agenticx/feature-iam` | Tenant, department, role, and permission management |\n| MCP Tools | `@agenticx/feature-tools-mcp` | MCP protocol integration for tool access |\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md), [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md), [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md), [enterprise/features/tools-mcp/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/tools-mcp/README.md)\n\n### Feature Module Usage\n\n```tsx\nimport { featureName } from \"@agenticx/feature-agents\";\n```\n\n## CLI Commands\n\nAgenticX provides a command-line interface for common operations:\n\n| Command | Description |\n|---------|-------------|\n| `agx init` | Initialize a new project |\n| `agx serve` | Start the AgenticX server |\n| `agx deploy` | Deploy to cloud providers |\n| `agx logs [--follow]` | View engine logs |\n| `agx destroy` | Clean up deployed resources |\n\n### Deployment Example (Volcengine)\n\n```bash\nagx volcengine deploy # Deploy to Volcengine\nagx logs --follow # Monitor deployment\nagx volcengine destroy # Clean up resources\n```\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n## Running the Project\n\nExecute your AgenticX application:\n\n```bash\npython main.py\n```\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n## Testing\n\n### Running Tests\n\nExecute the test suite to validate your implementation:\n\n```bash\npytest tests/\n```\n\n### Test Structure\n\nOrganize tests following the project structure:\n\n```\ntests/\n├── test_agents.py # Agent behavior tests\n├── test_workflows.py # Workflow execution tests\n└── test_integration.py # End-to-end integration tests\n```\n\n## Deployment\n\n### Docker Deployment\n\nThe project includes Dockerfile support for containerized deployment:\n\n```dockerfile\n# Refer to examples/agenticx-for-agentkit/hi-agent/Dockerfile\n```\n\n### Cloud Deployment\n\n1. Configure cloud provider credentials\n2. Run deployment command:\n ```bash\n agx volcengine deploy\n ```\n3. Monitor logs:\n ```bash\n agx logs --follow\n ```\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n## Next Steps\n\n| Resource | Description |\n|----------|-------------|\n| [Project Homepage](https://github.com/DemonDamon/AgenticX) | Main repository and documentation |\n| [Collaboration Patterns Paper](https://arxiv.org/abs/2501.06322) | Academic paper on multi-agent collaboration |\n| [Volcengine Integration](../agenticx/integrations/agentkit/) | Cloud-specific integration source |\n| [Project Templates](../agenticx/cli/templates/volcengine/) | Deployment configuration templates |\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Import errors | Ensure `agenticx` is installed: `pip install agenticx` |\n| API key errors | Verify credentials in `config.yaml` |\n| Timeout errors | Increase timeout values in configuration |\n| Deployment failures | Check cloud provider credentials and quotas |\n\n### Getting Help\n\nFor additional support:\n- Open an issue on [GitHub](https://github.com/DemonDamon/AgenticX/issues)\n- Consult the project documentation\n- Review the collaboration patterns academic paper\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)\n- [pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml)\n- [desktop/src/global.d.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/global.d.ts)\n- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n \n\n# Installation Guide\n\n## Overview\n\nThe Installation Guide provides comprehensive instructions for setting up the AgenticX environment across different deployment scenarios. AgenticX is a monorepo containing enterprise applications, desktop clients, and backend services that require specific configuration and dependency management.\n\n## System Architecture Overview\n\n```graph TD\n A[AgenticX Monorepo] --> B[Python Backend Core]\n A --> C[Enterprise Applications]\n A --> D[Desktop Client]\n B --> E[API Services]\n B --> F[Agent Engine]\n C --> G[Admin Console]\n C --> H[Web Portal]\n D --> I[Settings Panel]\n D --> J[ChatPane Interface]\n```\n\n## Prerequisites\n\n### System Requirements\n\n| Component | Minimum Version | Recommended |\n|-----------|-----------------|-------------|\n| Python | 3.11+ | 3.12+ |\n| Node.js | 18.0+ | 20.x LTS |\n| npm/yarn | 9.0+ | Latest stable |\n| Git | 2.30+ | Latest |\n\n### External Dependencies\n\nThe desktop application requires several external executable dependencies that can be installed globally once and shared across all instances.\n\n```graph TD\n A[External Tools] --> B[Python Packages]\n A --> C[Node.js Packages]\n A --> D[System Binaries]\n B --> E[adalflow]\n B --> F[agenticx-core]\n D --> G[agx CLI Tool]\n```\n\n资料来源：[pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml)\n\n## Python Package Installation\n\n### Project Structure\n\nThe Python backend uses Poetry for dependency management with the following key packages:\n\n| Package | Purpose | Version Constraint |\n|---------|---------|---------------------|\n| adalflow | Core AI framework | ^0.3.0 |\n| agenticx-core | Main agent engine | Internal |\n| pydantic | Data validation | ^2.0 |\n| fastapi | API framework | ^0.100.0 |\n| uvicorn | ASGI server | ^0.23.0 |\n\n### Installation Commands\n\n```bash\n# Clone the repository\ngit clone https://github.com/DemonDamon/AgenticX.git\ncd AgenticX\n\n# Install backend dependencies using Poetry\npoetry install\n\n# Or using pip with pyproject.toml\npip install -e .\n```\n\n资料来源：[INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)\n\n### Environment Variables\n\nThe application requires specific environment variables for configuration:\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `AGX_API_BASE` | Backend API endpoint | Yes |\n| `AGX_API_TOKEN` | Authentication token | Yes |\n| `OPENAI_API_KEY` | LLM provider key | Conditional |\n| `ANTHROPIC_API_KEY` | Claude API key | Conditional |\n\n## Enterprise Applications\n\n### Admin Console Setup\n\nThe enterprise admin console is a Next.js application located in `enterprise/apps/admin-console/`.\n\n```mermaid\ngraph LR\n A[Admin Console] --> B[IAM Module]\n A --> C[Models Module]\n A --> D[Audit Module]\n B --> E[Roles Management]\n B --> F[User Bulk Import]\n```\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n\n### Installation Steps\n\n```bash\ncd enterprise/apps/admin-console\n\n# Install dependencies\nnpm install\n\n# Configure environment\ncp .env.example .env.local\n\n# Start development server\nnpm run dev\n```\n\n### Web Portal Setup\n\nThe web portal application provides the public-facing interface.\n\n资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n\n## Desktop Application\n\n### Architecture\n\nThe desktop client provides a native interface for the AgenticX system with the following key components:\n\n```graph TD\n A[Desktop Client] --> B[Settings Panel]\n A --> C[ChatPane]\n A --> D[Task Automation]\n A --> E[Skills Manager]\n A --> F[Token Dashboard]\n \n B --> G[Provider Configuration]\n B --> H[API Base Settings]\n B --> I[Theme Settings]\n \n C --> J[Sub Agents]\n C --> K[History Panel]\n C --> L[Spawns Column]\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Desktop-Specific Installation\n\nThe desktop application requires additional native dependencies and configurations:\n\n#### WeChat Integration Setup\n\nThe desktop client supports WeChat integration via the iLink protocol:\n\n```typescript\ninterface WeChatStatus {\n port: number;\n running: boolean;\n}\n\n// Initialize WeChat sidecar\nconst { port, running } = await window.agenticxDesktop.wechatSidecarPort();\nif (!running) {\n const startRes = await window.agenticxDesktop.wechatSidecarStart();\n sidecarPort = startRes.port;\n}\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n#### Skills Management\n\nThe desktop application includes a skills management system that scans multiple locations:\n\n| Location | Description | Priority |\n|----------|-------------|----------|\n| `.agents/skills/` | Project-local skills | High |\n| Global skills | System-wide shared skills | Medium |\n| Third-party scan | External skill directories | Configurable |\n| Custom paths | User-defined locations | Manual |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Desktop IPC API\n\nThe desktop client exposes a comprehensive IPC API for configuration and skill management:\n\n```typescript\ninterface AgenticXDesktopAPI {\n getSkillSettings(): Promise;\n putSkillSettings(payload: SkillSettingsPayload): Promise;\n refreshSkills(): Promise;\n \n installBundle(args: BundleInstallArgs): Promise;\n uninstallBundle(args: { name: string }): Promise;\n \n installFromRegistry(args: RegistryInstallArgs): Promise;\n searchRegistry(args: { q: string }): Promise;\n}\n```\n\n资料来源：[desktop/src/global.d.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/global.d.ts)\n\n## Advanced Configuration\n\n### Token Dashboard\n\nThe desktop client includes a token usage dashboard with configurable date ranges:\n\n```typescript\ntype TokenDashboardRange = '7d' | '30d' | '90d' | 'custom';\n\ninterface TokenDashboardState {\n range: TokenDashboardRange;\n customFrom?: string;\n customTo?: string;\n}\n```\n\n资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n### Model Provider Configuration\n\nSupport for multiple LLM providers with per-provider configuration:\n\n| Provider | Config Key | Required Field |\n|----------|------------|----------------|\n| OpenAI | `provider` | `apiKey` |\n| Anthropic | `provider` | `apiKey` |\n| Custom | `provider` | `apiBase` + `apiKey` |\n\n### Theme and UI Settings\n\n| Setting | Type | Options |\n|---------|------|---------|\n| Theme Mode | `ThemeMode` | `light`, `dark`, `system` |\n| Theme Color | `ThemeColor` | Various accent colors |\n| Chat Style | `ChatStyle` | `pro`, `lite` |\n\n## Verification and Testing\n\n### Post-Installation Checks\n\nAfter installation, verify the setup using these checks:\n\n1. **Backend Connectivity**: Confirm API base URL is accessible\n2. **Authentication**: Verify token is valid and has required permissions\n3. **Skills Scanning**: Check that skill locations are properly configured\n4. **Bundle Installation**: Test bundle install/uninstall operations\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| API connection failed | Verify `AGX_API_BASE` environment variable |\n| Skills not loading | Check SKILL.md placement in `.agents/skills/` |\n| Bundle install blocked | Acknowledge high-risk warning if appropriate |\n\n## Repository Structure Summary\n\n```\nAgenticX/\n├── enterprise/\n│ ├── apps/\n│ │ ├── admin-console/ # IAM, Models, Audit\n│ │ └── web-portal/ # Public portal\n│ └── ...\n├── desktop/\n│ ├── src/\n│ │ ├── components/ # UI components\n│ │ ├── store.ts # State management\n│ │ └── global.d.ts # Type definitions\n│ └── ...\n├── pyproject.toml # Python dependencies\n└── INSTALL.md # Installation instructions\n```\n\n资料来源：[pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml), [INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Core Abstractions](#page-core-abstractions), [Agent Core System](#page-agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n- [enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n- [enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)\n- [enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n- [enterprise/apps/web-portal/src/components/WorkspaceShell.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/components/WorkspaceShell.tsx)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n \n\n# System Architecture\n\n## Overview\n\nAgenticX is a comprehensive multi-component AI agent platform designed to enable intelligent automation, multi-agent collaboration, and enterprise-grade management. The system architecture follows a modular design pattern with clear separation between core processing engines, enterprise management interfaces, and client applications.\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n## High-Level Architecture\n\nThe AgenticX platform comprises three primary layers:\n\n1. **Core Engine Layer** — Python-based agent runtime with workflow orchestration\n2. **Enterprise Management Layer** — Web-based admin console and web portal\n3. **Client Application Layer** — Desktop client application\n\n```mermaid\ngraph TB\n subgraph Core[\"Core Engine Layer\"]\n WF[\"Workflow Engine\"]\n AG[\"Agent Core\"]\n MEM[\"Memory System\"]\n KNOW[\"Knowledge Base\"]\n end\n \n subgraph Enterprise[\"Enterprise Management Layer\"]\n AC[\"Admin Console\"]\n WP[\"Web Portal\"]\n IAM[\"IAM System\"]\n end\n \n subgraph Client[\"Client Application Layer\"]\n DESK[\"Desktop App\"]\n UI[\"React Components\"]\n end\n \n DESK --> WF\n AC --> IAM\n WP --> IAM\n WF --> AG\n WF --> MEM\n WF --> KNOW\n```\n\n## Component Architecture\n\n### Core Engine Layer\n\nThe core engine provides the foundational AI agent capabilities including tool execution, memory management, and knowledge retrieval.\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n#### Agent Core\n\nThe Agent Core handles fundamental agent operations:\n\n| Component | Function |\n|-----------|----------|\n| Tool Registry | Discovers and manages available tools |\n| Execution Engine | Processes agent tasks and tool invocations |\n| State Management | Maintains agent conversation state |\n\n#### Workflow Engine\n\nThe workflow engine orchestrates multi-step agent tasks with support for both synchronous and asynchronous execution patterns.\n\n资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n### Enterprise Management Layer\n\nThe enterprise layer provides centralized management capabilities for users, roles, and system configuration.\n\n#### Admin Console\n\nThe Admin Console (`enterprise/apps/admin-console/`) is a Next.js application that provides administrative functions:\n\n- **User Management** — Create, edit, and manage user accounts with search and filtering capabilities\n- **Role Management** — Define roles with granular permission scopes\n- **Audit Logs** — Track system events with chain verification for data integrity\n- **Model Management** — Configure AI provider models\n- **Bulk Operations** — CSV-based bulk user import with pre-validation\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)\n\n```mermaid\ngraph LR\n subgraph AdminConsole[\"Admin Console\"]\n US[\"Users Module\"]\n RL[\"Roles Module\"]\n AU[\"Audit Module\"]\n MD[\"Models Module\"]\n BI[\"Bulk Import Module\"]\n end\n \n US --> IAM[\"IAM Backend\"]\n RL --> IAM\n AU --> IAM\n MD --> IAM\n BI --> IAM\n```\n\n#### Web Portal\n\nThe Web Portal (`enterprise/apps/web-portal/`) serves as the main user interface for end users, providing:\n\n- Authentication services\n- Workspace management\n- Theme and preference settings\n- Multi-language support (Chinese and English)\n- Admin console navigation integration\n\n资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)\n\n#### Identity and Access Management (IAM)\n\nThe IAM system manages authentication and authorization across the platform:\n\n| Feature | Description |\n|---------|-------------|\n| User Management | Full CRUD operations with email/display name tracking |\n| Role-Based Access Control | Roles with scoped permission matrices |\n| Bulk Import | CSV-based batch operations with pre-check validation |\n| Department Hierarchy | Organizational structure support via `dept_path` |\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)\n\nThe bulk import workflow follows a step-based process:\n\n1. **Upload CSV** — File upload or text paste with automatic parsing\n2. **Column Mapping** — Map CSV columns to system fields\n3. **Pre-check** — Validate all rows before submission\n4. **Execute Import** — Server-side batch write with failure tracking\n5. **Results** — Display success/failure counts with downloadable failure report\n\n### Client Application Layer\n\n#### Desktop Application\n\nThe Desktop Application (`desktop/`) is a React-based client with the following key components:\n\n| Component | Purpose |\n|-----------|---------|\n| SettingsPanel | Configure providers, models, environment tools |\n| TaskList | Manage automated tasks with enable/disable controls |\n| ChatPane | Agent conversation interface |\n| Store | Centralized state management using Zustand |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n```mermaid\ngraph TD\n ST[\"Store (Zustand)\"]\n SP[\"SettingsPanel\"]\n TL[\"TaskList\"]\n CP[\"ChatPane\"]\n \n ST --> SP\n ST --> TL\n ST --> CP\n \n SP --> |\"provider/model\"| ST\n TL --> |\"task toggle\"| ST\n CP --> |\"messages\"| ST\n```\n\n#### State Management\n\nThe desktop application uses Zustand for centralized state management with the following store structure:\n\n| State Category | Key Properties |\n|----------------|----------------|\n| Session | `sessionId`, `userMode`, `theme` |\n| Chat | `messages`, `modelProvider`, `modelName` |\n| Settings | `providers`, `apiKey`, `defaultProvider` |\n| UI | `sidebarCollapsed`, `focusMode`, `commandPaletteOpen` |\n| Tasks | `tasks`, `activeTaskspaceId` |\n\n资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)\n\n#### Task Automation\n\nTasks support the following configuration options:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `enabled` | boolean | Toggle task execution |\n| `prompt` | string | Task instruction prompt |\n| `workspace` | string | Working directory path |\n| `provider` | string | AI provider identifier |\n| `model` | string | Model name |\n| `lastRunAt` | timestamp | Last execution time |\n| `lastRunStatus` | enum | `success`, `error` |\n| `lastRunError` | string | Error message if failed |\n\n资料来源：[desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n\n### Feature Modules\n\nEnterprise features are implemented as standalone modules under `enterprise/features/`:\n\n| Module | Description |\n|--------|-------------|\n| `@agenticx/feature-agents` | Multi-agent spawning and management |\n| `@agenticx/feature-knowledge-base` | RAG-based knowledge retrieval |\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n## Integration Architecture\n\n### AgentKit Integration\n\nAgenticX integrates with Volcano Engine's AgentKit for enhanced capabilities:\n\n```\n┌────────────────────────────────────────────────────┐\n│ AgenticX 框架 │\n├─────────────┬────────────┬───────────┬─────────────┤\n│ Agent Core │ Tools │ Memory │ Knowledge │\n└─────────────┴────────────┴───────────┴─────────────┘\n │\n ┌──────────┴───────────┐\n │ AgentKit Integration │\n └──────────┬───────────┘\n │\n ┌────────────────┼────────────────┐\n ▼ ▼ ▼\n┌──────────┐ ┌───────────┐ ┌────────────┐\n│ Ark LLM │ │ Runtime │ │ Bridges & │\n│ Provider │ │ Client │ │ Adapters │\n└──────────┘ └───────────┘ └────────────┘\n```\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n### WeChat Integration\n\nThe desktop application supports WeChat integration via the iLink protocol:\n\n```mermaid\ngraph LR\n WC[\"WeChat Client\"]\n SD[\"Desktop Sidecar\"]\n AG[\"AgenticX Desktop\"]\n \n WC --> |\"iLink Protocol\"| SD\n SD --> AG\n AG --> |\"Agent Execution\"| SD\n```\n\nThe sidecar service manages the WeChat connection with states:\n- `idle` — No active binding\n- `binding` — QR code scanning in progress\n- `connected` — Active WeChat session\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Security Architecture\n\n### Audit Chain Verification\n\nThe audit system implements chain verification to ensure log integrity:\n\n| Status | Description |\n|--------|-------------|\n| `full` | Full table chain verification passed |\n| `valid` | Chain verification in progress |\n| `failed` | Chain verification failed with reason |\n\nEach audit log entry includes a chain signature that can be verified against the full table state.\n\n资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n\n### Role-Based Permissions\n\nRoles use a scope matrix for fine-grained permission control:\n\n- Roles can be assigned multiple permission scopes\n- Users can have multiple roles (role code aggregation)\n- Role membership changes use PATCH operations for atomic updates\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n\n## Deployment Architecture\n\n### Project Templates\n\nAgenticX provides deployment templates for different use cases:\n\n| Template | Command | Use Case |\n|----------|---------|----------|\n| `mcp` | `agx volcengine init --template mcp` | Tool auto-discovery and sharing |\n| `a2a` | `agx volcengine init --template a2a` | Multi-agent collaboration |\n| `knowledge` | `agx volcengine init --template knowledge` | Knowledge base RAG |\n\n资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `agx volcengine init` | Initialize new project from template |\n| `agx volcengine logs [--follow]` | View deployment logs |\n| `agx volcengine destroy` | Clean up deployed resources |\n\n## Data Flow\n\n### Bulk Import Flow\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant AC as Admin Console\n participant BE as Backend API\n \n U->>AC: Upload CSV\n AC->>AC: Parse & Display Preview\n U->>AC: Map Columns\n AC->>BE: Pre-check Request\n BE-->>AC: Validation Results\n alt Has Failures\n AC->>U: Display Failure Table\n U->>AC: Fix CSV / Remap\n else All Valid\n AC->>BE: Execute Import\n BE-->>AC: Success/Failure Report\n AC->>U: Show Results\n end\n```\n\n### Task Execution Flow\n\n```mermaid\ngraph TD\n START[\"Task Triggered\"]\n CHECK{\"Task Enabled?\"}\n LOAD[\"Load Task Config\"]\n EXEC[\"Execute Agent\"]\n SUCCESS{\"Success?\"}\n LOG[\"Log Result\"]\n ERR[\"Log Error\"]\n END[\"Complete\"]\n \n START --> CHECK\n CHECK --> |\"No\"| END\n CHECK --> |\"Yes\"| LOAD\n LOAD --> EXEC\n EXEC --> SUCCESS\n SUCCESS --> |\"Yes\"| LOG\n SUCCESS --> |\"No\"| ERR\n LOG --> END\n ERR --> END\n```\n\n## Configuration Management\n\n### Environment Tools\n\nThe system supports external executable dependencies:\n\n| State | Badge | Description |\n|-------|-------|-------------|\n| `installed` | Green | Tool globally installed |\n| `installing` | Blue | Installation in progress |\n| `manual_required` | Orange | User must install manually |\n| `not_installed` | Gray | Not yet installed |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Theme and Localization\n\nThe platform supports dynamic theme switching:\n\n| Theme Mode | Description |\n|------------|-------------|\n| `light` | Light color scheme |\n| `dark` | Dark color scheme |\n| `system` | Follow OS preference |\n\nSupported locales: `zh` (Chinese), `en` (English)\n\n资料来源：[enterprise/apps/web-portal/src/components/WorkspaceShell.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/components/WorkspaceShell.tsx)\n\n---\n\n\n\n## Core Abstractions\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Agent Core System](#page-agent-core), [Tool System and MCP Hub](#page-tool-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/core/agent.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent.py) *(未在上下文中找到)*\n- [agenticx/core/task.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task.py) *(未在上下文中找到)*\n- [agenticx/core/tool.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/tool.py) *(未在上下文中找到)*\n- [agenticx/core/component.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/component.py) *(未在上下文中找到)*\n- [agenticx/core/event_bus.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/event_bus.py) *(未在上下文中找到)*\n- [agenticx/core/message.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/message.py) *(未在上下文中找到)*\n\n**注意**：指定的 Core 模块源文件未出现在本次检索的上下文中。页面基于可见的代码结构和命名约定生成，标注为\"基于推断\"的部分需要后续对照源码验证。\n\n \n\n# Core Abstractions\n\nThe **Core Abstractions** layer is the foundational component system underlying AgenticX's agent framework. It provides the essential building blocks—Agent, Task, Tool, Component, EventBus, and Message—that enable developers to construct autonomous AI agents with configurable behaviors, tool integration, and event-driven communication.\n\n---\n\n## Overview\n\nAgenticX follows a modular, composable architecture where every functional unit is modeled as a first-class abstraction. The core layer defines:\n\n- **Agent** — The primary executor that coordinates tasks, tools, and message handling\n- **Task** — A unit of work with prompts, execution constraints, and state tracking\n- **Tool** — Callable functions and external integrations available to agents\n- **Component** — Reusable building blocks that can be mixed into agents\n- **EventBus** — Publish/subscribe infrastructure for inter-component messaging\n- **Message** — Standardized data structures for agent communication\n\n---\n\n## Architecture Diagram\n\n```mermaid\ngraph TD\n A[User Input] --> B[Agent]\n B --> C[Task Executor]\n B --> D[Tool Registry]\n B --> E[Message Bus]\n \n C --> F[Task]\n F --> G[Prompt Engine]\n \n D --> H[Tool 1]\n D --> I[Tool 2]\n D --> J[Tool N]\n \n E --> K[EventBus]\n K --> L[Component 1]\n K --> M[Component 2]\n \n N[Model Provider] --> B\n O[External Services] --> D\n```\n\n---\n\n## Agent Abstraction\n\nThe `Agent` class is the central coordinator that orchestrates all other abstractions. It manages the execution loop, tool invocations, message history, and component lifecycle.\n\n### Key Responsibilities\n\n| Responsibility | Description |\n|----------------|-------------|\n| Execution Control | Runs the agent loop, handling user prompts and model responses |\n| Tool Management | Maintains a registry of available tools and routes tool calls |\n| Message Handling | Processes incoming messages and maintains conversation history |\n| Component Integration | Loads and coordinates components for extended functionality |\n| State Management | Tracks execution state, errors, and result outputs |\n\n### Agent Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Unique identifier for the agent |\n| `model` | `str` | Model provider/model identifier (e.g., `openai/gpt-4o`) |\n| `provider` | `str` | LLM provider backend |\n| `tools` | `List[Tool]` | List of tools the agent can invoke |\n| `system_prompt` | `str` | Base instructions guiding agent behavior |\n| `max_retries` | `int` | Maximum retry attempts for failed operations |\n\n资料来源：[agenticx/core/agent.py]() *(源码待验证)*\n\n---\n\n## Task Abstraction\n\nTasks represent discrete units of work that an agent can execute. They encapsulate the prompt, execution parameters, and runtime state.\n\n### Task State Machine\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending\n Pending --> Running : start()\n Running --> Success : complete()\n Running --> Failed : error\n Running --> Pending : retry\n Success --> [*]\n Failed --> [*]\n```\n\n### Task Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `prompt` | `str` | The task instruction or question |\n| `workspace` | `Optional[str]` | Working directory or context path |\n| `enabled` | `bool` | Whether the task can execute |\n| `lastRunAt` | `Optional[datetime]` | Timestamp of last execution |\n| `lastRunStatus` | `Optional[str]` | Outcome: `success`, `error` |\n| `lastRunError` | `Optional[str]` | Error message if failed |\n\n资料来源：[desktop/src/components/automation/TaskList.tsx](desktop/src/components/automation/TaskList.tsx) *(前端实现参照)*\n\n---\n\n## Tool Abstraction\n\nTools extend agent capabilities by providing callable functions for external operations. Tools can be local Python functions or remote service integrations.\n\n### Tool Registration Flow\n\n```mermaid\nsequenceDiagram\n participant A as Agent\n participant T as Tool Registry\n participant M as Model\n participant E as External Service\n \n A->>T: Register Tool\n M-->>A: Generate Tool Call\n A->>E: Execute via Tool\n E-->>A: Return Result\n A->>M: Pass Result to Model\n```\n\n### Tool Installation States\n\n| State | Badge | Description |\n|-------|-------|-------------|\n| `installed` | 已安装 | Tool binary present and functional |\n| `installing` | 安装中 | Installation in progress |\n| `manual_required` | 需手动安装 | User must install externally |\n| `not_installed` | 未安装 | Tool not found, can be installed |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](desktop/src/components/SettingsPanel.tsx)\n\n### Registry Tool Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `str` | Tool identifier |\n| `description` | `Optional[str]` | Human-readable description |\n| `enabled` | `bool` | Availability status |\n\n---\n\n## Component Abstraction\n\nComponents are reusable functional units that can be mixed into agents to provide specific capabilities. They communicate via the EventBus and expose lifecycle hooks.\n\n### Component Features\n\n| Feature | Description |\n|---------|-------------|\n| Lifecycle Hooks | `on_init`, `on_start`, `on_stop` methods |\n| Event Subscription | Subscribe to specific event types via EventBus |\n| State Sharing | Components can share state through the agent context |\n\n资料来源：[agenticx/core/component.py]() *(源码待验证)*\n\n---\n\n## EventBus Abstraction\n\nThe EventBus provides a publish/subscribe messaging infrastructure for loose coupling between components.\n\n### Event Flow\n\n```mermaid\ngraph LR\n P[Publisher] -->|emit| EB[EventBus]\n EB -->|dispatch| S1[Subscriber 1]\n EB -->|dispatch| S2[Subscriber 2]\n EB -->|dispatch| SN[Subscriber N]\n```\n\n### Supported Event Types\n\n| Event | Trigger |\n|-------|---------|\n| `agent.start` | Agent execution begins |\n| `agent.complete` | Agent finishes execution |\n| `tool.call` | A tool is invoked |\n| `tool.result` | Tool execution returns |\n| `error` | Any error occurs in the pipeline |\n\n资料来源：[agenticx/core/event_bus.py]() *(源码待验证)*\n\n---\n\n## Message Abstraction\n\nMessages are the standard units of communication between agents, components, and external systems.\n\n### Message Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `role` | `str` | Sender role: `user`, `assistant`, `system`, `tool` |\n| `content` | `str` | Message body |\n| `tool_calls` | `Optional[List]` | Tool invocation metadata |\n| `tool_call_id` | `Optional[str]` | Correlation ID for tool responses |\n| `metadata` | `Optional[Dict]` | Additional contextual data |\n\n资料来源：[agenticx/core/message.py]() *(源码待验证)*\n\n---\n\n## Integration with Enterprise Features\n\nThe core abstractions compose with enterprise-level features:\n\n### Skill System\n\nAgents can be configured with skills—specialized capabilities loaded from:\n- Global skill directory (`.agents/skills/`)\n- Third-party scan paths\n- Custom skill paths\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](desktop/src/components/AvatarCreateDialog.tsx)\n\n### Model Management\n\nThe admin console provides UI for managing model providers and configurations:\n\n| Field | Description |\n|-------|-------------|\n| `id` | Unique provider identifier |\n| `displayName` | Human-readable name |\n| `models` | List of available model IDs |\n\n资料来源：[enterprise/apps/admin-console/src/app/admin/models/page.tsx](enterprise/apps/admin-console/src/app/admin/models/page.tsx)\n\n---\n\n## Quick Start Pattern\n\n```python\nfrom agenticx import Agent, Tool, Message\n\n# Define a custom tool\ncalculator = Tool(\n name=\"calculator\",\n description=\"Perform arithmetic operations\",\n func=compute\n)\n\n# Create an agent\nagent = Agent(\n name=\"math-assistant\",\n model=\"openai/gpt-4o\",\n tools=[calculator],\n system_prompt=\"You are a helpful math assistant.\"\n)\n\n# Execute\nresponse = agent.run(Message(role=\"user\", content=\"What is 2 + 2?\"))\nprint(response.content)\n```\n\n---\n\n## See Also\n\n- [Collaboration Patterns](../collaboration/README.md) — Multi-agent coordination using Core Abstractions\n- [Tool Integration](../integrations/) — Built-in tool adapters\n- [Enterprise IAM](../enterprise/features/iam/) — Access control for agents\n\n---\n\n\n\n## Agent Core System\n\n### 相关页面\n\n相关主题：[Meta-Agent and Team Management](#page-meta-agent), [Tool System and MCP Hub](#page-tool-system), [Memory System](#page-memory-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/core/agent_executor.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent_executor.py)\n- [agenticx/core/self_repair.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/self_repair.py)\n- [agenticx/core/overflow_recovery.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/overflow_recovery.py)\n- [agenticx/core/task_validator.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task_validator.py)\n- [agenticx/core/reflector.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/reflector.py)\n- [agenticx/core/guiderails.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/guiderails.py)\n \n\n# Agent Core System\n\nThe Agent Core System is the central orchestration engine of AgenticX, responsible for executing AI agent tasks, managing execution lifecycle, ensuring safety through guardrails, validating task outputs, handling memory overflow scenarios, enabling self-repair capabilities, and providing reflective analysis of agent behavior.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"Agent Core System\"\n A[Agent Executor] --> B[Task Validator]\n A --> C[Guiderails]\n A --> D[Overflow Recovery]\n A --> E[Self Repair]\n A --> F[Reflector]\n end\n \n G[Agent Input] --> A\n A --> H[Tool Execution]\n A --> I[Output]\n \n B -.->|Validation Result| A\n C -.->|Safety Check| A\n D -.->|Memory State| A\n E -.->|Repair Action| A\n F -.->|Reflection| A\n```\n\nThe Agent Core System coordinates multiple subsystems to ensure reliable and safe agent execution while maintaining context awareness and self-healing capabilities.\n\n## Core Components\n\n### Agent Executor\n\nThe `AgentExecutor` serves as the central orchestrator that manages the complete lifecycle of agent task execution. It coordinates between various subsystems including validation, safety checks, memory management, and self-repair mechanisms.\n\n**Key Responsibilities:**\n- Task dispatch and execution orchestration\n- State management across execution phases\n- Coordination with external tool systems\n- Integration with the broader AgenticX framework\n\n**Source:** [agenticx/core/agent_executor.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent_executor.py)\n\n### Task Validator\n\nThe `TaskValidator` ensures that agent-generated outputs meet quality and correctness standards before being considered final results. It performs structural validation, semantic checks, and format verification.\n\n**Validation Criteria:**\n| Category | Description |\n|----------|-------------|\n| Structural | Output format and schema compliance |\n| Semantic | Logical consistency and coherence |\n| Safety | Absence of harmful or inappropriate content |\n| Completeness | Full task requirement fulfillment |\n\n**Source:** [agenticx/core/task_validator.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task_validator.py)\n\n### Guiderails\n\nThe `Guiderails` module implements safety mechanisms that constrain agent behavior within defined boundaries. It monitors inputs, outputs, and tool invocations to prevent unintended or harmful actions.\n\n**Safety Features:**\n- Input sanitization and validation\n- Output filtering and content moderation\n- Tool usage policy enforcement\n- Behavioral boundary enforcement\n\n**Source:** [agenticx/core/guiderails.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/guiderails.py)\n\n### Overflow Recovery\n\nThe `OverflowRecovery` system manages memory and context overflow scenarios that occur during extended agent sessions. It implements strategies to preserve critical context while managing resource constraints.\n\n**Recovery Strategies:**\n| Strategy | Purpose |\n|----------|---------|\n| Context Trimming | Remove less relevant historical context |\n| Summary Generation | Compress conversation history |\n| Priority Preservation | Retain essential state information |\n| Progressive Cleanup | Gradual memory release |\n\n**Source:** [agenticx/core/overflow_recovery.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/overflow_recovery.py)\n\n### Self Repair\n\nThe `SelfRepair` module enables the agent to detect, diagnose, and correct its own errors without external intervention. It provides automated error recovery and behavioral correction capabilities.\n\n**Repair Mechanisms:**\n- Error detection and classification\n- Root cause analysis\n- Automatic correction application\n- Repair history tracking\n\n**Source:** [agenticx/core/self_repair.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/self_repair.py)\n\n### Reflector\n\nThe `Reflector` provides introspective capabilities that allow the agent to analyze its own reasoning, decisions, and execution patterns. It generates insights about agent behavior and enables continuous improvement.\n\n**Reflection Capabilities:**\n- Reasoning path analysis\n- Decision audit trails\n- Performance metrics generation\n- Behavioral pattern identification\n\n**Source:** [agenticx/core/reflector.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/reflector.py)\n\n## Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Input as Agent Input\n participant Executor as Agent Executor\n participant Validator as Task Validator\n participant Rails as Guiderails\n participant Overflow as Overflow Recovery\n participant Repair as Self Repair\n participant Reflect as Reflector\n participant Output as Final Output\n\n Input->>Executor: Task Request\n Executor->>Rails: Safety Check\n Rails-->>Executor: Approved/Blocked\n Executor->>Validator: Validate Task\n Validator-->>Executor: Validation Result\n Executor->>Overflow: Check Memory State\n Overflow-->>Executor: Memory Status\n Executor->>Executor: Execute Task\n Executor->>Repair: Error Detected?\n alt Error Detected\n Repair->>Repair: Analyze Error\n Repair->>Executor: Apply Fix\n Executor->>Executor: Retry\n end\n Executor->>Reflect: Log Execution\n Reflect-->>Executor: Reflection Complete\n Executor->>Output: Return Result\n```\n\n## Integration with AgenticX Framework\n\nThe Agent Core System integrates with multiple parts of the AgenticX ecosystem:\n\n### Desktop Integration\n\nThe desktop application (`desktop/`) provides UI components that interact with the core system through a store-based state management architecture. Settings panels allow configuration of agent parameters, and task automation components interface with the executor for scheduled task execution.\n\n**Related Files:**\n- [desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts) - State management\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) - Configuration UI\n- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx) - Task automation\n\n### Enterprise Features\n\nEnterprise features build upon the core system to provide additional capabilities:\n\n| Feature | Module | Integration Point |\n|---------|--------|-------------------|\n| Knowledge Base | `@agenticx/feature-knowledge-base` | Context enrichment |\n| Agent Management | `@agenticx/feature-agents` | Multi-agent orchestration |\n| Identity & Access | `@agenticx/feature-iam` | Security and permissions |\n| Tools MCP | `@agenticx/feature-tools-mcp` | Tool integration |\n\n**Related Files:**\n- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md)\n\n### Admin Console\n\nThe enterprise admin console provides monitoring and management capabilities for the core system through audit logging and operational dashboards.\n\n**Related Files:**\n- [enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx) - Audit logging interface\n- [enterprise/apps/admin-console/src/app/admin/models/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx) - Model management\n\n## Configuration Options\n\nThe Agent Core System supports various configuration parameters:\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `max_iterations` | Maximum execution iterations per task | Configurable |\n| `timeout_seconds` | Task execution timeout | Platform dependent |\n| `memory_limit` | Maximum memory allocation | Based on plan tier |\n| `enable_self_repair` | Enable automatic error correction | Enabled |\n| `enable_guiderails` | Enable safety mechanisms | Enabled |\n| `reflection_level` | Reflection detail depth | Standard |\n\n## Error Handling\n\nThe core system implements a hierarchical error handling approach:\n\n1. **Guiderails Prevention** - Blocks known dangerous patterns\n2. **Validation Failure** - Rejects invalid outputs with feedback\n3. **Self Repair Attempt** - Automatic correction of recoverable errors\n4. **Overflow Recovery** - Memory-related issue resolution\n5. **Reflector Documentation** - Error logging for analysis\n\n## Related Documentation\n\n- [Sandbox System](../sandbox/README.md) - Isolated execution environment\n- [Collaboration Mode](../collaboration/README.md) - Multi-agent cooperation\n- [AgentKit Integration](../integrations/agentkit/) - External framework integration\n\n---\n\n\n\n## Meta-Agent and Team Management\n\n### 相关页面\n\n相关主题：[Agent Core System](#page-agent-core), [Avatar and Group Chat](#page-avatar-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n- [desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n \n\n# Meta-Agent and Team Management\n\n## Overview\n\nMeta-Agent and Team Management in AgenticX refers to the system for orchestrating multiple AI agents (\"分身\", literally \"avatars\" or \"clones\") that can collaborate to accomplish complex tasks. The system provides a hierarchical management structure where a meta-agent coordinates teams of specialized agents, each with distinct capabilities, prompts, and tool configurations.\n\nThe architecture supports:\n\n- **Agent Lifecycle Management** — creation, configuration, enabling/disabling of individual agents\n- **Team Coordination** — grouping agents into collaborative units with shared context\n- **Skill Assignment** — attaching modular skills to specific agents or globally\n- **Meta-Tool Orchestration** — meta-agents that can delegate tasks to subordinate agents\n- **Execution Monitoring** — tracking task runs, statuses, and error handling\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n## Architecture\n\nThe system follows a layered architecture:\n\n```graph TD\n User[User Interface]\n UI[SettingsPanel / AvatarCreateDialog]\n MetaAgent[Meta-Agent]\n TeamManager[Team Manager]\n Agents[Agent Clones / Avatars]\n Skills[Skills System]\n Tools[Tool Registry]\n \n User --> UI\n UI --> MetaAgent\n MetaAgent --> TeamManager\n TeamManager --> Agents\n Agents --> Skills\n Agents --> Tools\n```\n\n### Core Components\n\n| Component | Purpose | Key File Reference |\n|-----------|---------|-------------------|\n| **Meta-Agent** | Top-level coordinator that decomposes tasks and delegates to team members | `agenticx/collaboration/README.md` |\n| **Team Manager** | Manages agent lifecycle, grouping, and inter-agent communication | Collaboration patterns |\n| **Agent Clone (Avatar)** | Individual agent with specific prompt, model, and workspace configuration | `desktop/src/components/AvatarCreateDialog.tsx` |\n| **Skills System** | Modular capability extensions attachable to agents | `desktop/src/components/SettingsPanel.tsx` |\n| **Tool Registry** | Centralized tool definitions and permissions | `desktop/src/components/SettingsPanel.tsx` |\n| **Role-Based Access** | IAM integration for agent permissions | `enterprise/apps/admin-console/src/app/iam/roles/page.tsx` |\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n\n## Agent Creation and Configuration\n\n### Avatar (Agent Clone) Structure\n\nEach agent clone is configured with:\n\n- **Name/Identifier** — unique agent name\n- **System Prompt** — base instructions and persona\n- **Workspace** — isolated working directory (optional)\n- **Model Configuration** — provider and model selection\n- **Enabled Skills** — list of skills this agent can use\n- **Active State** — can be toggled on/off\n\n```typescript\n// Avatar configuration interface (simplified)\ninterface AgentClone {\n id: string;\n name: string;\n prompt: string;\n workspace?: string;\n provider?: string;\n model?: string;\n enabledSkills: string[];\n enabled: boolean;\n}\n```\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n\n### Skills Configuration\n\nSkills can be assigned to agents with fine-grained control:\n\n| Setting | Description |\n|---------|-------------|\n| **Global Skills** | Skills available to all agents, can be disabled per-agent |\n| **Agent-Specific Skills** | Skills enabled only for particular agents |\n| **Skill Source Priority** | Preferred source when multiple skill definitions exist |\n| **Disabled Skills** | Skills explicitly disabled at global or agent level |\n\n```tsx\n// Skills UI state management\nconst [skillsEnabledDraft, setSkillsEnabledDraft] = useState>({});\nconst [preferredSkillSources, setPreferredSkillSources] = useState>({});\n```\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n\n## Team Management\n\n### Team Structure\n\nAgents are organized into teams with coordinated behavior:\n\n```graph TD\n Meta[Meta-Agent] --> Coordinator[Coordinator Agent]\n Coordinator --> AgentA[Specialist Agent A]\n Coordinator --> AgentB[Specialist Agent B]\n Coordinator --> AgentC[Specialist Agent C]\n \n AgentA --> Tool1[Tool Access]\n AgentB --> Tool2[Tool Access]\n AgentC --> Tool3[Tool Access]\n \n Coordinator --> SharedContext[Shared Context]\n AgentA --> SharedContext\n AgentB --> SharedContext\n AgentC --> SharedContext\n```\n\n### Collaboration Modes\n\nThe collaboration system supports multiple coordination patterns:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| **Custom Pattern** | User-defined collaboration flow | Complex, non-standard workflows |\n| **Sequential** | Agents execute tasks in order | Pipeline processing |\n| **Parallel** | Multiple agents work simultaneously | Independent subtasks |\n| **Hierarchical** | Meta-agent delegates to specialists | Decomposed complex tasks |\n\n```python\n# Pattern registration in manager\npattern_classes = {\n CollaborationMode.CUSTOM_PATTERN: CustomPattern,\n # ... other modes\n}\n```\n\n资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n\n## Task Automation\n\n### Task Configuration\n\nAutomated tasks can be assigned to agents with scheduling and execution parameters:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `id` | string | Unique task identifier |\n| `enabled` | boolean | Whether task is active |\n| `prompt` | string | Task instruction |\n| `workspace` | string | Working directory |\n| `provider` | string | Model provider |\n| `model` | string | Model identifier |\n| `lastRunAt` | timestamp | Last execution time |\n| `lastRunStatus` | enum | \"success\" / \"error\" |\n| `lastRunError` | string | Error message if failed |\n\n### Task Execution States\n\n```graph TD\n A[Scheduled] --> B{Running}\n B -->|Success| C[Completed]\n B -->|Error| D[Failed]\n D -->|Retry| B\n C --> E[Update Status]\n E --> F[Ready for Next]\n```\n\n资料来源：[desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n\n## Tool Registry and Permissions\n\n### Tool Management\n\nTools are registered centrally and can be:\n\n| Status | Badge | Description |\n|--------|-------|-------------|\n| **Installed** | Green \"已安装\" | Tool executable available |\n| **Installing** | Accent color \"安装中\" | Installation in progress |\n| **Manual Required** | Amber \"需手动安装\" | User action needed |\n| **Not Installed** | Red \"未安装\" | Tool not present |\n\n### Denied Tools\n\nSpecific tools can be explicitly denied for security:\n\n```tsx\n{deniedTools.map((toolPat, idx) => (\n \n))}\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Role-Based Access Control\n\n### Role Permissions for Agents\n\nAgent operations are governed by role-based permissions:\n\n| Permission | Scope | Description |\n|------------|-------|-------------|\n| `agents:read` | Global/Team | View agent configurations |\n| `agents:write` | Global/Team | Create/modify agents |\n| `agents:execute` | Agent-specific | Run agent tasks |\n| `skills:manage` | Global | Configure global skills |\n| `tools:approve` | Admin | Approve tool requests |\n\n### Role Management UI\n\nThe admin console provides role management with scope matrix editing:\n\n```tsx\n\n```\n\n资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)\n\n## Environment Dependencies\n\n### External Tool Installation\n\nThe system manages external executable dependencies:\n\n- **Global Installation** — Tools installed once, shared across all agents\n- **Per-Team Installation** — Team-specific tool configurations\n- **Manual Installation Mode** — Flagged tools requiring user intervention\n- **Sidecar Services** — Background services (e.g., WeChat integration)\n\n```tsx\nconst wechatStatus = await window.agenticxDesktop.wechatSidecarPort();\nif (!running) {\n const startRes = await window.agenticxDesktop.wechatSidecarStart();\n}\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Workflow Summary\n\n### Creating and Managing Agents\n\n1. **Define Agent Persona** — Set name, prompt, and model configuration\n2. **Assign Skills** — Enable/disable skills from global pool or add custom paths\n3. **Configure Tools** — Grant/revoke tool access, manage denied tools\n4. **Set Up Team** — Group agents under a meta-agent or coordinator\n5. **Define Tasks** — Create automated tasks with scheduling\n6. **Monitor Execution** — Track runs, statuses, and errors\n7. **Adjust Permissions** — Update role-based access as needed\n\n### Multi-Agent Coordination Flow\n\n```graph LR\n Request[User Request] --> Meta[Meta-Agent]\n Meta --> Decompose[Decompose Task]\n Decompose --> Assign[Assign to Team Members]\n Assign --> ExecuteA[Agent A Execute]\n Assign --> ExecuteB[Agent B Execute]\n Assign --> ExecuteC[Agent C Execute]\n ExecuteA --> ResultsA[Results A]\n ExecuteB --> ResultsB[Results B]\n ExecuteC --> ResultsC[Results C]\n ResultsA --> Aggregate[Aggregate Results]\n ResultsB --> Aggregate\n ResultsC --> Aggregate\n Aggregate --> Response[Final Response]\n```\n\n## Integration with Enterprise Features\n\n### Feature Modules\n\nAgenticX uses a modular feature system:\n\n| Module | Purpose |\n|--------|---------|\n| `@agenticx/feature-agents` | Core agent management |\n| `@agenticx/feature-knowledge-base` | Knowledge retrieval integration |\n| `@agenticx/feature-tools-mcp` | MCP (Model Context Protocol) tool integration |\n| `@agenticx/feature-iam` | Identity, roles, and permissions |\n| `@agenticx/feature-chat` | Chat workspace UI |\n\n```tsx\nimport { featureName } from \"@agenticx/feature-agents\";\n```\n\n资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n\n### Admin Console Integration\n\nThe enterprise admin console provides:\n\n- **Audit Logging** — Track all agent operations with chain validation\n- **Bulk Import** — Batch create agents from CSV templates\n- **Role Management** — Define and assign permission scopes\n- **Model Configuration** — Manage available AI providers and models\n\n```tsx\ndescription={`共 ${items.length} 条记录 · ${\n chainFull?.valid ? \"全表链校验通过\" : \"全表链校验失败\"\n}`}\n```\n\n资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)\n\n## Summary\n\nThe Meta-Agent and Team Management system provides a comprehensive framework for orchestrating multiple AI agents within AgenticX. Key capabilities include:\n\n- **Hierarchical Agent Structure** — Meta-agents coordinate specialist agents\n- **Flexible Skill System** — Modular capabilities with per-agent enablement\n- **Team-Based Collaboration** — Multiple coordination patterns (sequential, parallel, hierarchical)\n- **Automated Task Execution** — Scheduled tasks with status tracking\n- **Tool Registry** — Centralized tool management with permission controls\n- **Role-Based Security** — Enterprise-grade IAM integration\n- **Environment Management** — External dependency handling\n\nThe system is designed for both single-user desktop scenarios (via SettingsPanel) and enterprise deployments (via Admin Console), supporting use cases from personal automation to complex multi-agent workflows.\n\n---\n\n\n\n## Tool System and MCP Hub\n\n### 相关页面\n\n相关主题：[Agent Core System](#page-agent-core)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/tools/function_tool.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/function_tool.py)\n- [agenticx/tools/mcp_hub.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/mcp_hub.py)\n- [agenticx/tools/remote_v2.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/remote_v2.py)\n- [agenticx/tools/openapi_toolset.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/openapi_toolset.py)\n- [agenticx/tools/sandbox_tools.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/sandbox_tools.py)\n- [agenticx/tools/guardrails/builtin.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/guardrails/builtin.py)\n \n\n# Tool System and MCP Hub\n\n## Overview\n\nThe AgenticX Tool System provides a comprehensive framework for extending agent capabilities through function tools, MCP (Model Context Protocol) integration, remote tools, OpenAPI-based tool sets, sandboxed execution, and built-in guardrails. This architecture enables agents to interact with external systems, execute code safely, and enforce security policies while maintaining a unified tool invocation interface.\n\n## Architecture Overview\n\nThe tool system is organized into a layered architecture where different tool implementations share common interfaces while providing specialized functionality:\n\n```mermaid\ngraph TD\n A[Agent Core] --> B[Tool Registry]\n B --> C[Function Tool]\n B --> D[MCP Hub]\n B --> E[Remote Tools v2]\n B --> F[OpenAPI Toolset]\n B --> G[Sandbox Tools]\n B --> H[Guardrails]\n \n D --> I[MCP Servers]\n D --> J[MCP Client]\n \n G --> K[Sandbox Runtime]\n H --> L[Built-in Validators]\n```\n\n## Function Tool\n\nFunction tools provide the foundational mechanism for wrapping Python functions as agent-callable tools. They encapsulate function metadata, parameter schemas, and execution logic within a standardized interface.\n\n### Core Implementation\n\nFunction tools are defined through decorators or class-based configurations that specify the tool's name, description, parameters, and return type. The system uses type hints to automatically generate JSON Schema for parameter validation.\n\n```python\nfrom agenticx.tools.function_tool import FunctionTool\n\n@FunctionTool.register(\n name=\"web_search\",\n description=\"Search the web for information\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\"type\": \"string\", \"description\": \"Search query\"},\n \"limit\": {\"type\": \"integer\", \"description\": \"Max results\", \"default\": 5}\n },\n \"required\": [\"query\"]\n }\n)\ndef search_web(query: str, limit: int = 5) -> dict:\n # Implementation\n return {\"results\": []}\n```\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Registry\n participant FunctionTool\n participant Executor\n \n Agent->>Registry: InvokeTool(name, parameters)\n Registry->>FunctionTool: Locate tool by name\n FunctionTool->>Executor: Execute(parameters)\n Executor->>FunctionTool: Result\n FunctionTool->>Registry: Wrapped response\n Registry->>Agent: ToolResult\n```\n\n资料来源：[agenticx/tools/function_tool.py]()\n\n## MCP Hub\n\nThe MCP Hub serves as the central integration point for Model Context Protocol servers, enabling agents to discover and utilize tools exposed by external MCP-compliant services.\n\n### MCP Architecture\n\n```mermaid\ngraph LR\n A[AgenticX Agent] --> B[MCP Hub]\n B --> C[MCP Client Pool]\n C --> D[MCP Server 1]\n C --> E[MCP Server 2]\n C --> F[MCP Server N]\n \n D --> G[File System Tools]\n E --> H[API Tools]\n F --> I[Custom Tools]\n```\n\n### MCP Hub Features\n\nThe MCP Hub provides the following capabilities:\n\n| Feature | Description |\n|---------|-------------|\n| Server Management | Register and manage multiple MCP server connections |\n| Tool Discovery | Automatic discovery of available tools from connected servers |\n| Connection Pooling | Efficient reuse of MCP client connections |\n| Error Handling | Graceful degradation when servers are unavailable |\n| Tool Registry Integration | Seamless integration with the AgenticX tool registry |\n\n资料来源：[agenticx/tools/mcp_hub.py]()\n\n### Usage Pattern\n\n```python\nfrom agenticx.tools.mcp_hub import MCPHub\n\nhub = MCPHub()\n\n# Connect to an MCP server\nawait hub.connect(\"file-server\", server_config)\n\n# List available tools\ntools = await hub.list_tools()\n\n# Invoke a tool\nresult = await hub.invoke(\"file-server\", \"read_file\", {\"path\": \"/data/file.txt\"})\n```\n\n## Remote Tools v2\n\nThe remote tools module provides a robust mechanism for calling external APIs and services. Version 2 introduces improved connection handling, request pooling, and authentication support.\n\n### Architecture\n\n```mermaid\ngraph TD\n A[Tool Request] --> B[RemoteTool Client]\n B --> C[Request Queue]\n C --> D[Connection Pool]\n D --> E[External API]\n E --> D\n D --> F[Response Handler]\n F --> G[Tool Result]\n \n B --> H[Auth Manager]\n H --> I[Token Store]\n```\n\n### Configuration Options\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `base_url` | string | required | Base URL for the remote service |\n| `timeout` | int | 30 | Request timeout in seconds |\n| `max_retries` | int | 3 | Maximum retry attempts |\n| `pool_size` | int | 10 | Connection pool size |\n| `auth_type` | string | \"none\" | Authentication type: bearer, api_key, basic |\n\n资料来源：[agenticx/tools/remote_v2.py]()\n\n### Implementation\n\n```python\nfrom agenticx.tools.remote_v2 import RemoteTool\n\ntool = RemoteTool(\n name=\"external_api\",\n base_url=\"https://api.example.com\",\n auth_type=\"bearer\",\n token=\"your-token\",\n timeout=60,\n max_retries=3\n)\n\nresult = await tool.invoke(\"endpoint\", {\"param\": \"value\"})\n```\n\n## OpenAPI Toolset\n\nThe OpenAPI toolset enables automatic generation of tool interfaces from OpenAPI specifications. This allows agents to interact with any REST API documented using the OpenAPI standard.\n\n### Auto-Discovery Process\n\n```mermaid\ngraph TD\n A[OpenAPI Spec] --> B[OpenAPI Parser]\n B --> C[Endpoint Mappings]\n C --> D[Tool Generator]\n D --> E[Tool Instances]\n E --> F[Tool Registry]\n```\n\n### Supported Features\n\n| Feature | Status | Description |\n|---------|--------|-------------|\n| GET requests | Supported | Retrieve resources |\n| POST requests | Supported | Create resources |\n| PUT/PATCH requests | Supported | Update resources |\n| DELETE requests | Supported | Remove resources |\n| Authentication | Supported | Bearer, API Key, OAuth2 |\n| Request body schemas | Supported | JSON Schema validation |\n| Response parsing | Supported | Automatic result extraction |\n\n资料来源：[agenticx/tools/openapi_toolset.py]()\n\n### Usage Example\n\n```python\nfrom agenticx.tools.openapi_toolset import OpenAPIToolset\n\n# Generate tools from OpenAPI spec\ntoolset = OpenAPIToolset.from_spec(\n spec_url=\"https://api.example.com/openapi.json\",\n auth={\"type\": \"bearer\", \"token\": \"...\"}\n)\n\n# Tools are automatically registered\nresults = await toolset.invoke(\"get_user\", {\"id\": \"123\"})\n```\n\n## Sandbox Tools\n\nSandbox tools provide secure code execution environments for agent operations that require running untrusted or dynamically generated code.\n\n### Sandbox Architecture\n\n```mermaid\ngraph TD\n A[Code Execution Request] --> B[Sandbox Manager]\n B --> C{Backend Type}\n C -->|micro-sandbox| D[Lightweight Container]\n C -->|docker| E[Docker Container]\n C -->|remote| F[Remote Sandbox Service]\n \n D --> G[Execution Engine]\n E --> G\n F --> G\n \n G --> H[Result Collector]\n H --> I[Output/Side Effects]\n H --> J[Error Handler]\n```\n\n### Sandbox Templates\n\n| Template | Use Case | CPU | Memory | Timeout |\n|----------|----------|-----|--------|---------|\n| LIGHTWEIGHT_TEMPLATE | Quick computations | 1 core | 512MB | 30s |\n| HIGH_PERFORMANCE_TEMPLATE | Complex operations | 4 cores | 8GB | 300s |\n| CODE_INTERPRETER | Python execution | 2 cores | 4GB | 120s |\n\n### Error Handling\n\nThe sandbox module defines specific exception types for different failure scenarios:\n\n```python\nfrom agenticx.tools.sandbox_tools import (\n SandboxError,\n SandboxTimeoutError,\n SandboxExecutionError,\n SandboxNotReadyError,\n SandboxBackendError,\n)\n\ntry:\n async with Sandbox.create() as sb:\n result = await sb.execute(code, timeout=60)\nexcept SandboxTimeoutError:\n print(\"Execution exceeded time limit\")\nexcept SandboxExecutionError as e:\n print(f\"Runtime error: {e.stderr}\")\nexcept SandboxBackendError as e:\n print(f\"Backend failure: {e.backend}\")\n```\n\n资料来源：[agenticx/tools/sandbox_tools.py]()\n\n## Guardrails (Built-in)\n\nGuardrails provide security and policy enforcement for tool execution, ensuring that agent operations comply with defined constraints and safety policies.\n\n### Guardrail Architecture\n\n```mermaid\ngraph LR\n A[Tool Request] --> B[Guardrail Chain]\n B --> C[Input Validator]\n B --> D[Rate Limiter]\n B --> E[Content Filter]\n B --> F[Output Sanitizer]\n \n C --> G{Allowed?}\n D --> G\n E --> G\n F --> G\n \n G -->|Yes| H[Tool Executor]\n G -->|No| I[Rejection Response]\n```\n\n### Built-in Guardrail Types\n\n| Guardrail | Purpose | Configuration |\n|-----------|---------|---------------|\n| InputValidation | Validate parameter types and ranges | Schema-based |\n| RateLimiting | Prevent excessive calls | Calls per time window |\n| ContentFilter | Block sensitive content patterns | Pattern matching |\n| OutputSanitizer | Remove sensitive data from results | Data classification |\n| AuditLogger | Log all tool invocations | Structured logging |\n\n资料来源：[agenticx/tools/guardrails/builtin.py]()\n\n### Implementation Pattern\n\n```python\nfrom agenticx.tools.guardrails.builtin import (\n InputValidationGuardrail,\n RateLimitGuardrail,\n)\n\n# Configure guardrails\nguardrails = [\n InputValidationGuardrail(schema=param_schema),\n RateLimitGuardrail(max_calls=100, window_seconds=60),\n]\n\n# Apply to tool\nsecure_tool = Tool.with_guardrails(tool_instance, guardrails)\n```\n\n## Integration with Agentic Agents\n\nTools integrate seamlessly with the AgenticX agent framework through the tool registry and invocation system.\n\n```mermaid\ngraph TD\n A[Agent Task] --> B[Planner]\n B --> C[Tool Selection]\n C --> D[Tool Registry]\n D --> E[Tool Invocation]\n E --> F{Guardrail Check}\n F -->|Pass| G[Execute Tool]\n F -->|Fail| H[Reject]\n G --> I[Result Processing]\n I --> J[Response to Agent]\n```\n\n### Tool Selection Criteria\n\n| Criterion | Description |\n|-----------|-------------|\n| Capability Match | Tool can solve the required sub-task |\n| Availability | Tool is registered and accessible |\n| Permission | Agent has permission to invoke tool |\n| Rate Limits | Tool rate limits not exceeded |\n| Guardrail Compliance | Request passes all guardrail checks |\n\n## Summary\n\nThe AgenticX Tool System provides a flexible, extensible framework for extending agent capabilities through multiple integration patterns:\n\n- **Function Tools**: Direct Python function wrapping\n- **MCP Hub**: Model Context Protocol integration for external tool servers\n- **Remote Tools v2**: External API invocation with connection pooling\n- **OpenAPI Toolset**: Automatic tool generation from API specifications\n- **Sandbox Tools**: Secure code execution environments\n- **Guardrails**: Security and policy enforcement layers\n\nThis architecture enables developers to extend agent capabilities while maintaining consistent interfaces, security boundaries, and operational monitoring across all tool integrations.\n\n---\n\n\n\n## Memory System\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n- [README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [agenticx/memory/__init__.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/__init__.py)\n- [examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n \n\n# Memory System\n\nThe Memory System in AgenticX provides persistent and intelligent memory capabilities for AI agents, enabling them to retain information across sessions, manage knowledge bases, and perform semantic searches. This system is fundamental for building stateful, context-aware agentic applications.\n\n## Architecture Overview\n\nThe memory system follows a layered architecture that separates storage backends from intelligent processing components.\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ AgenticX Memory System │\n├─────────────────────────────────────────────────────────┤\n│ ┌───────────────┐ ┌──────────────┐ ┌───────────────┐ │\n│ │ MemoryComponent│ │ KnowledgeBase│ │ MemoryClient│ │\n│ │ (Intelligence) │ │ (Organization)│ │ (API Layer) │ │\n│ └───────┬───────┘ └──────┬───────┘ └───────┬───────┘ │\n│ │ │ │ │\n│ ┌───────┴─────────────────┴───────────────────┴───────┐ │\n│ │ Memory Backend Implementations │ │\n│ ├─────────────┬───────────────┬───────────────────────┤ │\n│ │ShortTermMemory│ EpisodicMemory│ SemanticMemory │ │\n│ ├─────────────┼───────────────┼───────────────────────┤ │\n│ │ Hierarchical │ Mem0Memory │ MCP Integration │ │\n│ └─────────────┴───────────────┴───────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n## Core Components\n\n### 1. ShortTermMemory\n\nShort-term memory provides transient storage for current conversation context and immediate agent state. It is designed for high-throughput operations within a tenant's scope.\n\n```python\nfrom agenticx.memory import ShortTermMemory\n\n# Create memory backend\nbackend = ShortTermMemory(tenant_id=\"user_123\")\n\n# Add persistent memory with metadata\nmemory_id = await backend.add(\n \"Important project information\",\n metadata={\"project\": \"agenticx\", \"importance\": \"high\"}\n)\n\n# Search across all memories\nresults = await backend.search(\"project information\")\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `tenant_id` | `str` | Unique identifier for tenant isolation |\n| `content` | `str` | Memory content text |\n| `metadata` | `dict` | Optional key-value metadata for categorization |\n\n### 2. KnowledgeBase\n\nKnowledgeBase enables organization of content into specialized domains with content-type filtering.\n\n```python\nfrom agenticx.memory import KnowledgeBase, ShortTermMemory\n\n# Create memory backend\nbackend = ShortTermMemory(tenant_id=\"kb_demo\")\n\n# Create specialized knowledge bases\ndocs_kb = KnowledgeBase(\n name=\"documentation\",\n memory_backend=backend,\n allowed_content_types={\"tutorial\", \"guide\", \"faq\"}\n)\n\ncode_kb = KnowledgeBase(\n name=\"code_examples\", \n memory_backend=backend,\n allowed_content_types={\"code\", \"snippet\"}\n)\n\n# Add content with content type\nawait docs_kb.add(\n \"How to create an agent\",\n content_type=\"tutorial\",\n metadata={\"difficulty\": \"beginner\"}\n)\n\n# Search within specific knowledge base\ndoc_results = await docs_kb.search(\"agent creation\")\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `str` | Knowledge base identifier |\n| `memory_backend` | `MemoryBackend` | Underlying storage implementation |\n| `allowed_content_types` | `set[str]` | Filter for permitted content types |\n\n### 3. MemoryComponent\n\nThe MemoryComponent provides intelligent memory operations with automatic cleanup and advanced retrieval capabilities.\n\n```python\nfrom agenticx.memory import MemoryComponent, ShortTermMemory\n\n# Create memory component with primary storage\nprimary_memory = ShortTermMemory(tenant_id=\"demo\")\ncomponent = MemoryComponent(\n primary_memory=primary_memory,\n enable_ranking=True,\n enable_deduplication=True\n)\n\n# Use with context manager for automatic cleanup\nasync with component as mem:\n memory_id = await mem.add(\n \"Context-aware information\",\n metadata={\"context\": \"agent_session\"}\n )\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n## Memory Backend Types\n\n| Backend Type | Use Case | Persistence |\n|--------------|----------|-------------|\n| `ShortTermMemory` | Session state, temporary data | Ephemeral with optional persistence |\n| `EpisodicMemory` | Event sequences, conversation history | Long-term storage |\n| `SemanticMemory` | Embedding-based semantic search | Vector-enabled storage |\n| `HierarchicalMemory` | Multi-level memory organization | Tiered storage |\n| `Mem0Memory` | Healthcare, personalized data | Specialized domain storage |\n\n## MCP Integration\n\nThe Memory System supports Model Context Protocol (MCP) for external memory service integration.\n\n```python\nfrom agenticx.memory import MemoryClient\nfrom agenticx.mcp import MCPServer, MCPTools\n\n# Configure MCP server for memory\nmcp_config = MCPTools(\n port=3000,\n server_config={\n \"memory_service\": \"mem0\",\n \"api_endpoint\": \"http://localhost:8000\"\n }\n)\n\n# Create memory client with MCP backend\nmemory = MemoryClient(\n tenant_id=\"mcp_tenant\",\n server_config=mcp_config\n)\n\n# Async usage with automatic resource management\nasync with memory:\n memory_id = await memory.add(\n \"Important project information\",\n metadata={\"project\": \"agenticx\", \"importance\": \"high\"}\n )\n results = await memory.search(\"project information\")\n```\n\n资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)\n\n## Healthcare Memory Scenario\n\nThe Mem0 memory backend is specifically designed for healthcare applications, providing medical knowledge memory and personalized patient information management.\n\n```bash\n# Run healthcare memory example\npython examples/mem0_healthcare_example.py\n```\n\n资料来源：[README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md)\n\n### Key Features for Healthcare\n\n- **Medical Knowledge Memory**: Structured storage for medical concepts, diagnoses, and treatment protocols\n- **Patient Information Management**: Secure, tenant-isolated storage for patient-specific data\n- **Privacy Compliance**: Built-in data handling safeguards for sensitive medical information\n- **Semantic Search**: Fast retrieval of relevant medical information using embeddings\n\n## Desktop Application Integration\n\nThe Memory System is accessible through the AgenticX Desktop application, providing a graphical interface for memory management.\n\n```tsx\n// SettingsPanel.tsx integration\nimport { useAgenticxDesktop } from \"@agenticx/desktop\";\n\nconst memorySettings = {\n enableMemorySync: true,\n syncInterval: 30000, // ms\n maxMemorySize: \"100MB\"\n};\n```\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n### Skill Scanning with Memory\n\nThe desktop application uses memory-backed skill scanning to discover and manage agent capabilities:\n\n- **Global Skills**: System-wide shared skills stored in memory\n- **Project Skills**: Per-project skills located in `.agents/skills/`\n- **Marketplace Skills**: Third-party skills fetched and cached\n- **Custom Paths**: User-defined skill directories\n\n资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n\n## Intent Recognition with Memory\n\nThe intent recognition service leverages the Memory System for storing and retrieving classification patterns and entity mappings.\n\n```bash\n# Run intent recognition example\npython examples/agenticx-for-intent-recognition/main.py\n```\n\n资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)\n\n### Architecture Pattern\n\n```\n┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐\n│ Intent Agent │────▶│ Memory System │◀────│ Knowledge Base │\n│ (Classifier) │ │ (Storage/Lookup)│ │ (Patterns) │\n└─────────────────┘ └──────────────────┘ └─────────────────┘\n │ │\n ▼ ▼\n┌─────────────────┐ ┌──────────────────┐\n│ Workflow Engine│ │ Semantic Search │\n│ (Orchestration) │ │ (Retrieval) │\n└─────────────────┘ └──────────────────┘\n```\n\n## Memory Operations API\n\n### Add Memory\n\n```python\nmemory_id = await memory.add(\n content: str,\n metadata: Optional[dict] = None,\n content_type: Optional[str] = None,\n embedding: Optional[list[float]] = None\n) -> str\n```\n\n### Search Memory\n\n```python\nresults = await memory.search(\n query: str,\n limit: int = 10,\n content_type: Optional[str] = None,\n filters: Optional[dict] = None\n) -> list[MemoryResult]\n```\n\n### Delete Memory\n\n```python\nawait memory.delete(memory_id: str) -> bool\n```\n\n### Update Memory\n\n```python\nawait memory.update(\n memory_id: str,\n content: Optional[str] = None,\n metadata: Optional[dict] = None\n) -> bool\n```\n\n## Best Practices\n\n### Tenant Isolation\n\nAlways specify a unique `tenant_id` when creating memory backends to ensure data isolation:\n\n```python\n# Good: Isolated memory per tenant\nuser_memory = ShortTermMemory(tenant_id=\"user_abc123\")\n\n# Avoid: Shared memory across tenants\nshared_memory = ShortTermMemory(tenant_id=\"shared\") # Not recommended\n```\n\n### Content Type Organization\n\nUse content types consistently for better organization and filtering:\n\n| Content Type | Description |\n|--------------|-------------|\n| `tutorial` | Educational content |\n| `guide` | How-to documentation |\n| `faq` | Frequently asked questions |\n| `code` | Code snippets and examples |\n| `snippet` | Small code fragments |\n\n### Metadata Usage\n\nLeverage metadata for enhanced search and filtering:\n\n```python\nawait memory.add(\n \"Agent configuration guide\",\n metadata={\n \"category\": \"documentation\",\n \"difficulty\": \"intermediate\",\n \"version\": \"1.0\",\n \"tags\": [\"agent\", \"setup\", \"configuration\"]\n }\n)\n```\n\n## Dependencies\n\nThe Memory System requires the following core dependencies:\n\n| Package | Purpose |\n|---------|--------|\n| `mem0ai` | Mem0 memory backend integration |\n| `chromadb` | Vector storage for semantic search |\n| `pydantic` | Data validation and serialization |\n\n## Summary\n\nThe AgenticX Memory System provides a comprehensive, multi-layered approach to agent memory management:\n\n1. **ShortTermMemory** for immediate session context\n2. **KnowledgeBase** for domain-specific content organization\n3. **MemoryComponent** for intelligent operations\n4. **MCP Integration** for external memory services\n5. **Specialized Backends** (Mem0) for domain-specific applications\n\nThis architecture enables agents to maintain persistent context, perform semantic retrieval, and scale across enterprise deployments with full tenant isolation.\n\n---\n\n\n\n## Avatar and Group Chat\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [desktop/src/components/AvatarSettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarSettingsPanel.tsx)\n- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)\n- [desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)\n- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)\n- [enterprise/features/chat/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/chat/README.md)\n- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)\n- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)\n \n\n# Avatar and Group Chat\n\n## Overview\n\nThe Avatar and Group Chat system in AgenticX enables multi-agent collaboration through configurable digital personas called \"Avatars\" (also referred to as \"分身\" in Chinese). Each Avatar represents an autonomous agent with a distinct role, system prompts, and behavioral preferences that can interact with users and other agents in group conversations.\n\nThe system architecture consists of:\n\n- **Avatar Registry**: Manages the lifecycle of all avatars, including creation, persistence, and configuration storage\n- **Avatar Settings**: UI layer for configuring avatar properties including name, role, appearance (avatar image), and skill associations\n- **Group Chat**: Enables multiple avatars to participate in collaborative conversations, facilitating multi-agent workflows\n- **Group Context & Routing**: Handles message routing between avatars in group conversations and maintains conversational context\n\n资料来源：[desktop/src/components/AvatarSettingsPanel.tsx](), [enterprise/features/agents/README.md](), [agenticx/collaboration/README.md]()\n\n## Avatar System Architecture\n\n### Avatar Configuration Model\n\nEach Avatar is defined by a configuration that includes:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `name` | string | Display name of the avatar |\n| `role` | string | Professional role description (e.g., \"Full-stack Developer\", \"Data Analyst\") |\n| `avatarUrl` | string | Path to the avatar's profile image |\n| `skills` | string[] | List of enabled skills for this avatar |\n| `systemPrompt` | string | Custom system prompt override |\n| `userPreference` | string | User preference injection for behavioral tuning |\n\n资料来源：[desktop/src/components/AvatarSettingsPanel.tsx](), [desktop/src/components/SettingsPanel.tsx]()\n\n### Avatar Persistence\n\nAvatars are persisted to disk in YAML format within each avatar's dedicated directory:\n\n```\n~/.agenticx/\n└── /\n └── avatar.yaml\n```\n\nThe UI indicates this clearly: \"保存后写入该分身目录下的 avatar.yaml\" (Saved to the avatar.yaml file under the avatar directory after saving).\n\n资料来源：[desktop/src/components/AvatarSettingsPanel.tsx]()\n\n## Avatar Settings Panel\n\nThe `AvatarSettingsPanel` component provides the primary interface for managing avatar configurations.\n\n### UI Components\n\n```\n┌─────────────────────────────────────────────┐\n│ Avatar Settings Panel │\n├─────────────────────────────────────────────┤\n│ [Avatar Image Preview] [Upload] [Clear] │\n│ • Consistent with sidebar and chat list │\n│ • Recommended: < 1.8MB square image │\n├─────────────────────────────────────────────┤\n│ 名称: [________________] │\n│ 角色: [________________] │\n│ 例：全栈开发工程师、数据分析师 │\n└─────────────────────────────────────────────┘\n```\n\n### Key Features\n\n1. **Avatar Image Management**\n - Preview support for uploaded images\n - Clear button to reset to default avatar\n - Image size validation (recommended < 1.8MB)\n - Visual consistency across sidebar, chat list, and sessions\n\n2. **Metadata Configuration**\n - `name`: Avatar display name\n - `role`: Professional role descriptor\n\n资料来源：[desktop/src/components/AvatarSettingsPanel.tsx]()\n\n## Avatar Creation Dialog\n\nThe `AvatarCreateDialog` component handles the initial creation of new avatars with skill selection.\n\n### Skill Assignment Workflow\n\n```mermaid\ngraph TD\n A[Create New Avatar] --> B[Load Available Skills]\n B --> C{Global Skills Disabled?}\n C -->|Yes| D[Filter Out Disabled Skills]\n C -->|No| E[Show All Skills]\n D --> F[Display Skill List]\n E --> F\n F --> G[User Toggles Skills On/Off]\n G --> H[Save Avatar with Skills]\n```\n\n### Skill Selection States\n\n| State | Visual Indicator | Description |\n|-------|-------------------|-------------|\n| Enabled | Cyan border with background | Skill is active for this avatar |\n| Disabled | Muted border, muted text | Skill is not used by this avatar |\n\n```tsx\n// Skill toggle button styling from AvatarCreateDialog.tsx\ndisabled\n ? \"border-border-strong text-text-muted\"\n : \"border-cyan-500/40 bg-cyan-500/10 text-cyan-400\"\n```\n\n资料来源：[desktop/src/components/AvatarCreateDialog.tsx](), [desktop/src/components/AvatarSettingsPanel.tsx]()\n\n## User Preferences and Style Injection\n\nThe Avatar system supports injecting user preferences into the system prompt of all agents. This feature is managed through the Settings Panel.\n\n### User Preference Configuration\n\n| Setting | Description | Character Limit |\n|---------|-------------|-----------------|\n| `userPreference` | Behavioral style instructions for agents | 500 characters |\n\nExample usage:\n```\n我不喜欢绕弯子，请直接给结论；\n偏好表格而非长段落；\n遇到歧义先问我再执行。\n```\n\nThis preference text is:\n- Injected into every conversation's system prompt\n- Applied to all agent responses\n- Stored in local browser storage for local-only effects\n\n资料来源：[desktop/src/components/SettingsPanel.tsx]()\n\n## Group Chat System\n\n### Overview\n\nGroup Chat enables multiple avatars to participate in collaborative conversations. This is particularly useful for complex tasks requiring diverse expertise.\n\n### Multi-Agent Collaboration Patterns\n\nBased on the collaboration documentation, AgenticX supports multiple collaboration modes for group interactions:\n\n资料来源：[agenticx/collaboration/README.md]()\n\n### Context Management\n\nThe Group Context system maintains conversational state across multiple participants:\n\n- **Message History**: Tracks all messages from all participants\n- **Participant State**: Maintains individual avatar states\n- **Turn Management**: Controls speaking order and发言权\n\n### Message Routing\n\nThe Group Router determines how messages are routed between avatars:\n\n```mermaid\ngraph LR\n A[User Message] --> B[Group Router]\n B --> C{Which Avatar?}\n C -->|Expert A| D[Process & Generate]\n C -->|Expert B| E[Process & Generate]\n C -->|Meta-Agent| F[Orchestrate Response]\n D --> G[Group Context Update]\n E --> G\n F --> G\n G --> H[Response to User]\n```\n\n资料来源：[enterprise/features/chat/README.md]()\n\n## Task Automation with Avatars\n\nAvatars can be associated with automated tasks for scheduled or triggered execution.\n\n### Task Configuration\n\nEach automated task can specify:\n\n| Property | Description |\n|----------|-------------|\n| `prompt` | The task instruction prompt |\n| `workspace` | Working directory for task execution |\n| `provider` | LLM provider for task execution |\n| `model` | Specific model to use |\n| `enabled` | Whether the task is active |\n| `lastRunAt` | Timestamp of last execution |\n| `lastRunStatus` | Execution result (success/error) |\n| `lastRunError` | Error message if failed |\n\n### Task List UI\n\nThe Task List component displays:\n\n- Task name and description\n- Execution model (provider/model)\n- Enable/disable toggle\n- Last execution status with timestamps\n- Error details for failed runs\n\n资料来源：[desktop/src/components/automation/TaskList.tsx]()\n\n## Integration Points\n\n### WeChat Integration\n\nAvatars can be bound to WeChat for receiving messages and triggering agent execution:\n\n- **Binding Method**: QR code scanning via WeChat iLink protocol\n- **Status Indicators**: Connected (green), Bound but not connected (yellow)\n- **Sidecar Port**: Local service for WeChat communication\n\n资料来源：[desktop/src/components/SettingsPanel.tsx]()\n\n### Meta-Agent (Machi)\n\nThe Meta-Agent system provides orchestration capabilities:\n\n- Central coordination of multiple avatars\n- Meta-agent SOUL saving and loading\n- Unified interface for managing complex multi-agent workflows\n\n资料来源：[desktop/src/components/SettingsPanel.tsx]()\n\n## Configuration Schema\n\n### Avatar YAML Structure\n\n```yaml\n# avatar.yaml\nname: \"Avatar Display Name\"\nrole: \"Professional Role\"\navatarUrl: \"/path/to/image.png\"\nskills:\n - skill_name_1\n - skill_name_2\nuserPreference: \"Behavioral preferences...\"\n```\n\n### Permission Modes\n\n| Mode | Behavior | Risk Level |\n|------|----------|------------|\n| `manual` | Confirm every tool execution | Safest |\n| `semi-auto` | Auto-approve whitelisted operations | Recommended |\n| `auto` | Execute all tools automatically | High Risk |\n\n资料来源：[desktop/src/components/SettingsPanel.tsx]()\n\n## Summary\n\nThe Avatar and Group Chat system provides a comprehensive framework for:\n\n1. **Avatar Management**: Create, configure, and persist digital personas with distinct roles and skills\n2. **Skill Association**: Enable/disable skills per avatar with visual UI feedback\n3. **User Preference Injection**: Customize agent behavior across all conversations\n4. **Group Collaboration**: Enable multiple avatars to work together on complex tasks\n5. **Task Automation**: Associate avatars with automated tasks for scheduled execution\n6. **Multi-Channel Integration**: Connect avatars to external platforms like WeChat\n\nThe system is designed for flexibility, allowing fine-grained control over avatar behavior while supporting sophisticated multi-agent collaboration patterns.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：DemonDamon/AgenticX\n\n摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)。\n\n## 1. 安装坑 · 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Desktop app fails on startup: agx serve failed to start (local API not available)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4330954394974f1ab2f82c8645e1dce9 | https://github.com/DemonDamon/AgenticX/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：AgenticX + Machi v0.3.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：AgenticX + Machi v0.3.7\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4983001c0714fbe923df9e3263934b3 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_026abb56e0864ba4b60ba497e1a19084 | https://github.com/DemonDamon/AgenticX/issues/14 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Machi launch failure on mac\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Machi launch failure on mac\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1f85a307f6b44099b52dfdb50d13f91c | https://github.com/DemonDamon/AgenticX/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_170a543fa1d640b7a6c9c54d5b9ce6c1 | https://github.com/DemonDamon/AgenticX/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d8c2ce59a394bd8901a52ddaf36f821 | https://github.com/DemonDamon/AgenticX/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：AgenticX v0.3.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c05bccba0b02475cb74b550d42c91222 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：AgenticX v0.3.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.6\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_619eaf3ee1334cb6bc5db5adb67b7c8f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：AgenticX v0.3.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.8\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c0dad4f133a4a199f8b54083f16427f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：bash_exec fails to run any command on Windows (WinError 2)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bash_exec fails to run any command on Windows (WinError 2)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14230559f63c4fd8a7a8d1310b6284d0 | https://github.com/DemonDamon/AgenticX/issues/7 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：添加模型不支持codex 认证方式\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：添加模型不支持codex 认证方式\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b24824ec7b6e4e7fa6bc5b7b2874817c | https://github.com/DemonDamon/AgenticX/issues/4 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | 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项目：DemonDamon/AgenticX\n\n摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)。\n\n## 1. 安装坑 · 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Desktop app fails on startup: agx serve failed to start (local API not available)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4330954394974f1ab2f82c8645e1dce9 | https://github.com/DemonDamon/AgenticX/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：AgenticX + Machi v0.3.7\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：AgenticX + Machi v0.3.7\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4983001c0714fbe923df9e3263934b3 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP will report an error upon startup: \"[Errno 2] No such file or directory\".\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_026abb56e0864ba4b60ba497e1a19084 | https://github.com/DemonDamon/AgenticX/issues/14 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Machi launch failure on mac\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Machi launch failure on mac\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1f85a307f6b44099b52dfdb50d13f91c | https://github.com/DemonDamon/AgenticX/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_170a543fa1d640b7a6c9c54d5b9ce6c1 | https://github.com/DemonDamon/AgenticX/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2d8c2ce59a394bd8901a52ddaf36f821 | https://github.com/DemonDamon/AgenticX/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：AgenticX v0.3.5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.5\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c05bccba0b02475cb74b550d42c91222 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：AgenticX v0.3.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.6\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_619eaf3ee1334cb6bc5db5adb67b7c8f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 安全/权限坑 · 来源证据：AgenticX v0.3.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.8\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c0dad4f133a4a199f8b54083f16427f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：bash_exec fails to run any command on Windows (WinError 2)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bash_exec fails to run any command on Windows (WinError 2)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_14230559f63c4fd8a7a8d1310b6284d0 | https://github.com/DemonDamon/AgenticX/issues/7 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：添加模型不支持codex 认证方式\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：添加模型不支持codex 认证方式\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b24824ec7b6e4e7fa6bc5b7b2874817c | https://github.com/DemonDamon/AgenticX/issues/4 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# AgenticX - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for DemonDamon/AgenticX.\n\nProject:\n- Name: AgenticX\n- Repository: https://github.com/DemonDamon/AgenticX\n- Summary: AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to AgenticX. Produce one small intermediate artifact and wait for confirmation.\n2. page-quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-installation: Installation Guide. Produce one small intermediate artifact and wait for confirmation.\n4. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n5. page-core-abstractions: Core Abstractions. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/DemonDamon/AgenticX\n- https://github.com/DemonDamon/AgenticX#readme\n- agenticx/skills/agenticx-a2a-connector/SKILL.md\n- agenticx/skills/agenticx-agent-builder/SKILL.md\n- agenticx/skills/agenticx-automation-crontask/SKILL.md\n- agenticx/skills/agenticx-deployer/SKILL.md\n- agenticx/skills/agenticx-memory-architect/SKILL.md\n- agenticx/skills/agenticx-quickstart/SKILL.md\n- agenticx/skills/agenticx-skill-manager/SKILL.md\n- agenticx/skills/agenticx-tool-creator/SKILL.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：DemonDamon/AgenticX\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install agenticx\n```\n\n来源：https://github.com/DemonDamon/AgenticX#readme\n\n## 来源\n\n- repo: https://github.com/DemonDamon/AgenticX\n- docs: https://github.com/DemonDamon/AgenticX#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_a033e96109b941659a17d833e0697cac"
}