PraisonAI 项目说明书

Doramagic 项目包 · 项目说明书

PraisonAI 项目

PraisonAI 🦞 — 雇佣一支 24/7 在线 AI 团队。无需编写样板代码，即可创建能够自主研究、规划、编码并执行任务且持续自优化的智能体，五行代码即可部署，内置 memory、RAG，并支持 100+ LLM。

Overview & System Architecture

PraisonAI 是一个面向多智能体（multi-agent）协作与自动化工作流构建的综合性 AI 框架，提供 Python、TypeScript 与 Rust 三种语言实现。其核心目标是把大语言模型（LLM）驱动的单个 Agent 扩展为可编排、可观测、可工具化扩展的智能体团队，并支持检索增强生成（RAG）、MCP 协议、CI 集成与产业模板等高级特性。最新发布版本为 ...

章节 相关页面

继续阅读本节完整说明和来源证据。

1. 框架定位与多语言生态

PraisonAI 的设计遵循"多语言 SDK + 统一概念"的原则。Python 端以 praisonaiagents 为核心包，封装 Agent、Task、Tool、Memory、Workflow 等抽象；TypeScript 端通过 praisonai 包提供 Agent、Task、AgentTeam 等类（资料来源：src/praisonai-ts/README.md），可直接复用 ArxivSearchTool、ArxivDownloadTool 等工具（资料来源：src/praisonai-ts/examples/tools/README.md）；Rust 端则基于 rig-core 构建，提供 #[tool] 过程宏、AgentTeam、AgentFlow 等模式，强调 Tokio 异步性能（资料来源：src/praisonai-rust/README.md）。

社区对工具生态的关注度很高。Issue #6 明确请求"添加对 langchain、crewai 工具的支持"，并建议优先从 Google 系列工具开始接入。PraisonAI 通过 BaseTool 基类与 @tool 装饰器暴露统一的工具注册接口（资料来源：src/praisonai-agents/praisonaiagents/tools/README.md），同时支持外部 pip 可安装插件包，使第三方开发者能够以独立分发形式扩展工具能力。

2. 核心运行时与可插拔协议

Agent 运行时通过 AgentRuntimeProtocol、RuntimeRegistry、resolve_runtime() 等组件实现可插拔抽象。内置 praisonai 运行时包装了既有 Agent 逻辑，register_runtime() 允许用户注册自定义运行时；run_turn() 与 stream_turn() 分别支持一次性调用与流式 delta 输出（资料来源：src/praisonai-agents/praisonaiagents/runtime/README.md）。这种协议优先（protocol-driven）的设计使得 Agent 可以在不同底层执行环境间无缝切换。

flowchart LR
    A[用户配置 / YAML] --> B[Agent 构造]
    B --> C{Runtime 解析}
    C -->|resolve_runtime| D[内置 PraisonAI Runtime]
    C -->|register_runtime| E[自定义 Runtime 插件]
    D --> F[LLM 调用]
    E --> F
    F --> G[Tool 调用 / RAG 检索]
    G --> H[结果返回]

3. 功能模块与典型应用

PraisonAI 在仓库中提供了覆盖不同场景的示例集合：

RAG 与知识库：提供基础检索、AutoRagAgent、混合检索、重排序、引用标注等模式（资料来源：examples/rag/README.md），并通过 praisonai rag index/query/chat/eval 子命令管理向量集合。
MCP 协议：实现 MCP 2025-11-25 规范的 v2 服务端，支持 tools/list 游标分页、readOnlyHint / destructiveHint 等注解（资料来源：src/praisonai/examples/mcp/README.md 与 examples/mcp/README.md）。
行业模板（SRAO 框架）：制造、能源、医疗等行业的预构建工作流实现约 70% 代码复用（资料来源：examples/cookbooks/Industry_Templates/README.md）。
安全特性：SBOM（CycloneDX/SPDX）生成、依赖审计、PII 脱敏（资料来源：examples/security/README.md）。
CI 集成：通过 GitHub Actions 触发 @praisonai 调用，输出多 Agent 评审报告（资料来源：examples/yaml/pr-reviewer/README.md）。
Creator Suite：面向 AI 内容创作者的一体化工具链（资料来源：examples/recipes/creator_suite/README.md）。
Recipe Serve：通过 praisonai recipe serve 暴露 OpenAPI 端点，支持 API Key 鉴权、限流、指标采集与热重载（资料来源：examples/serve/README.md）。
统一参数层：memory、output、guardrails、hooks 等参数支持多种输入形式（布尔、字典、"prompt" 字符串等），简化配置（资料来源：examples/consolidated_params/README.md）。

4. 常见问题与扩展建议

当工具能力不足时，开发者可以基于 BaseTool 类或 @tool 装饰器编写自定义工具，并将其打包为 pip 插件独立分发（资料来源：src/praisonai-agents/praisonaiagents/tools/README.md）。对于 LangChain / CrewAI 工具的兼容需求，社区已多次提出（Issue #6），目前的推荐做法是通过自定义 Tool 适配器包装外部工具后注入 Agent(tools=[...])。在运行时层面，若需替换底层执行引擎，可通过 register_runtime() 注入兼容 AgentRuntimeProtocol 的实现。在部署层面，recipe serve 提供生产级 HTTP 服务能力，但务必启用 --auth api-key 并结合反向代理使用 HTTPS（资料来源：examples/serve/README.md）。

Agents, Tools, MCP & Framework Integrations

PraisonAI 是一个以 Agent 为核心的多智能体开发框架，提供了从基础 Agent 定义、Tools 工具系统、MCP（Model Context Protocol）服务器到跨语言 SDK（Python、TypeScript、Rust）的完整工具链。本页面将系统介绍这些组件的作用、架构与使用方法，并结合社区反馈说明当前的演进方向。

章节 相关页面

继续阅读本节完整说明和来源证据。

Agents、Tools、MCP 与框架集成

1. 框架定位与 Agent 核心抽象

PraisonAI 的核心抽象是 Agent 类，开发者通过 Agent 实例来定义具备特定角色（role）、目标（goal）和背景故事（backstory）的智能体，并由 AgentTeam 协调多个 Agent 协同完成任务。Agent 既可独立运行，也可作为工作流（Workflow）中的节点，通过共享内存（memory）和规划（planning）能力实现复杂任务分解。资料来源：src/praisonai-ts/README.md:1-30

Agent 的配置支持"统一参数解析"模式，优先级依次为：实例属性 > Config > Array > Dict > String > Bool > 默认值。这种优先级模型允许开发者通过同一组参数（memory、output、execution、guardrails、reflection、web、planning、autonomy、caching、knowledge、context、hooks）灵活控制 Agent 行为。资料来源：examples/consolidated_params/README.md:10-30

2. Tools 工具系统

Tools 是赋予 Agent 实际执行能力的模块，PraisonAI 提供三种工具创建方式：

类继承方式：继承 BaseTool 并实现 run 方法，适合复杂、多方法或需要内部状态管理的工具。资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:10-25
装饰器方式：通过 @tool 装饰器将普通函数转换为工具，适合轻量、单一职责的函数。资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:13-22
插件包方式：外部开发者可创建 pip 可安装的 praisonai-* 工具包，通过插件机制被框架自动发现与加载。资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:30-50

下表总结了核心工具类型及其适用场景：

工具类型	适用场景	来源
ArXiv（学术搜索/下载）	论文检索、PDF 下载	资料来源：src/praisonai-ts/examples/tools/README.md:1-30
Exa 搜索	隐私友好的网页搜索	资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:70-90
Spider	通用网页抓取、CSS 选择器抽取	资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:75-90
Newspaper	新闻文章抽取与 NLP 处理	资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:90-100
Stock Market	多接口股票信息（含缓存）	资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:95-100

社区反馈显示，LangChain 与 CrewAI 的工具生态成熟度高，社区议题 #6 曾呼吁增加对这两类工具的支持，以便复用其 Google、Bing、SQL 等扩展能力。资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:5-10

3. MCP 服务器与协议集成

PraisonAI 内置 MCP 服务器，遵循 MCP Protocol Version 2025-11-25 规范，提供 tools、resources、prompts 三类端点。资料来源：examples/mcp/README.md:1-15

MCP v2 关键特性包括：

分页（Pagination）：使用 base64url 编码的不透明游标（cursor），默认每页 50 条，最多 100 条；tools/list、resources/list、prompts/list 均支持游标分页。资料来源：examples/mcp/README.md:5-15、资料来源：src/praisonai/examples/mcp/README.md:10-25
工具注解（Tool Annotations）：readOnlyHint、destructiveHint、idempotentHint、openWorldHint 四个语义提示，帮助客户端理解工具副作用。资料来源：examples/mcp/README.md:15-25
CLI 入口：praisonai mcp list-tools、praisonai mcp tools search "query"、praisonai mcp tools info <name>、praisonai mcp tools schema <name> 等命令用于浏览与查询。资料来源：src/praisonai/examples/mcp/README.md:25-45

服务器还暴露了 praisonai://agents、praisonai://knowledge/sources、praisonai://config、praisonai://mcp/status 等资源 URI，以及 deep-research、code-review、workflow-auto、guardrail-check、context-engineering、eval-criteria、agent-instructions 等预置 prompt 模板。资料来源：examples/mcp_server/README.md:1-25

4. 跨语言 SDK 与行业模板

PraisonAI 提供三套官方 SDK，API 高度对齐：

Python（praisonaiagents）：完整功能集，含 RAG、Tools、MCP、Memory、Workflows。资料来源：examples/README.md:10-40
TypeScript（praisonai-ts）：支持 Agent、Task、AgentTeam，提供 ArXiv 等开箱即用工具。资料来源：src/praisonai-ts/README.md:1-30、资料来源：src/praisonai-ts/examples/tools/README.md:1-30
Rust（praisonai-rust）：基于 Tokio 异步运行时，通过 #[tool] 过程宏简化工具定义，支持 OpenAI、Anthropic、Ollama（通过 rig-core）。资料来源：src/praisonai-rust/README.md:1-30

行业模板基于 SRAO 框架实现约 70% 的代码复用，目前已覆盖制造业（订单解析、库存检查、调度优化、缺陷检测）、能源（SCADA 读取、振动分析、功率预测、维护调度）、医疗（生命体征采集、EMR 检索、分诊建议）等领域。资料来源：examples/cookbooks/Industry_Templates/README.md:1-30

RAG 与知识集成方面，PraisonAI Agents 内置 ChromaDB 向量库，可通过 Agent(knowledge=[...]) 直接挂载文档或 URL 作为检索源，并支持 PDF 问答、多 Agent 共享知识库、评估（praisonai rag eval）等高级模式。资料来源：examples/rag/README.md:1-30

5. 典型应用与社区关注

以 PR Reviewer 为例，开发者可通过 GitHub Actions 在 CI/CD 流水线中触发 PraisonAI 多 Agent 团队（安全、性能、可维护性、主管）协同审查 Pull Request，仅需暴露 OPENAI_API_KEY 与 GitHub App 凭证即可零代码部署。资料来源：examples/yaml/pr-reviewer/README.md:1-30

社区目前最关注的扩展方向是 LangChain/CrewAI 工具兼容性，这将进一步丰富 PraisonAI 的工具生态。资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:5-10

Memory, Knowledge, RAG & Persistence

PraisonAI 提供了一套多层次的状态与上下文管理机制，覆盖了从会话级记忆（Memory）、外部知识库（Knowledge）接入、检索增强生成（RAG）工作流，到状态/会话持久化（State Persistence）的完整能力链。该能力体系既服务于单智能体（Agent）的长期上下文需求，也支撑多智能体协作团队（AgentTeam / AgentFlow）之间共享知...

章节 相关页面

继续阅读本节完整说明和来源证据。

概览

PraisonAI 提供了一套多层次的状态与上下文管理机制，覆盖了从会话级记忆（Memory）、外部知识库（Knowledge） 接入、检索增强生成（RAG） 工作流，到状态/会话持久化（State Persistence） 的完整能力链。该能力体系既服务于单智能体（Agent）的长期上下文需求，也支撑多智能体协作团队（AgentTeam / AgentFlow）之间共享知识、共享记忆以及跨工作流的状态恢复资料来源：examples/python/stateful/README.md。

社区中也曾有用户提出希望增强工具与上下文链路（参见 issue #6 “Please add support for tools of langchain,crewai”），而 praisonaiagents/tools 模块中已包含 Spider、Newspaper、Stock Market 等多种工具，并建议与记忆/知识系统配合使用资料来源：src/praisonai-agents/praisonaiagents/tools/README.md。

记忆系统（Memory）

PraisonAI 提供了统一参数（Consolidated Params） 形式的记忆入口，开发者在创建 Agent 时可直接使用 memory=True 启用默认记忆，或通过 basic_memory.py 切换 SQLite 等预设后端资料来源：examples/consolidated_params/README.md。

在更细粒度上，stateful 示例目录展示了记忆与状态系统的典型用法，包括：

会话设计：使用有意义的 session_id 以便调试与状态恢复资料来源：examples/python/stateful/README.md。
记忆策略：支持短期与长期记忆，并可设置质量阈值（quality thresholds）以决定是否将内容写入长期记忆资料来源：examples/python/stateful/README.md。
生命周期回调（Hooks）：通过 basic_hooks.py 注册 lifecycle 回调，将记忆操作与 Agent 生命周期绑定资料来源：examples/consolidated_params/README.md。
记忆提供者（Memory Provider）：示例中演示了 RAG Provider（ChromaDB + Embeddings）、Mem0 Provider（含图谱支持）以及 Local Provider（SQLite）等可插拔后端资料来源：examples/python/stateful/README.md。

知识库与 RAG

RAG（Retrieval-Augmented Generation）是 PraisonAI 中“知识”的核心使用方式。examples/rag 目录提供了从基础到高级的完整示例矩阵资料来源：examples/rag/README.md：

类别	示例	关键能力
核心概念	`basic_retrieval.py`、`chunking_strategies.py`	检索-生成模式、分段策略
高级模式	`multi_document.py`、`knowledge_graph.py`	多文档合成、图谱关系检索
增强来源	`external_sources.py`、`citations.py`	Web/API 扩展、内联引用
应用	`rag_pdf_qa.py`、`rag_multi_agent.py`、`rag_evaluation.py`	PDF 问答、多智能体协作、评估指标

开发者也可以使用 CLI 完成常见 RAG 任务资料来源：examples/rag/README.md：

praisonai rag index ./documents --collection my_docs
praisonai rag query "What is the main finding?" --collection my_docs
praisonai rag chat --collection my_docs
praisonai rag eval golden_queries.json --collection my_docs

其中“Agentic RAG”通过 AutoRagAgent 引入条件检索策略，由智能体本身决定何时、从哪个集合、以何种 top-k 进行检索资料来源：examples/rag/README.md。结合 GPT-5 与内置向量数据库（如 ChromaDB）后，可构建带 Markdown 渲染、动态 URL 增量的应用资料来源：examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md。

rag_config.yaml 提供了声明式配置入口，支持自定义 chunking.strategy、chunk_size、rag.top_k、min_score 与 include_citations 等参数资料来源：examples/rag/README.md。

flowchart LR
  U[用户查询] --> A[Agent / AutoRagAgent]
  A -- 检索决策 --> R[Vector Store<br/>ChromaDB / SQLite]
  R -- Top-K 文档 --> A
  A -- Prompt + 上下文 --> L[LLM<br/>OpenAI GPT-5 等]
  L -- 答案 + 引用 --> U

持久化与状态管理

持久化机制与记忆系统紧密耦合，但侧重点不同：记忆关注“写入什么”，持久化关注“保存在哪里、跨进程如何恢复”。stateful 示例明确给出了几类典型模式资料来源：examples/python/stateful/README.md：

Session-Based：状态绑定到用户会话。
Workflow-Based：状态绑定到具体工作流。
User-Based：状态绑定到单个用户。
Global：跨用户/跨工作流的全局状态。

最佳实践建议包括：使用有意义的 session_id、在关键工作流里程碑处保存状态、为缺失状态提供合理默认、为长期运行的应用实现记忆清理资料来源：examples/python/stateful/README.md。同时，记忆与知识系统均可与外部系统（Web 应用、数据库、监控与 UI 组件）集成，从而把“智能体状态”延伸到生产环境的可观测性与可恢复性层面资料来源：examples/python/stateful/README.md。

常见失败模式

知识库未加载：检查 OPENAI_API_KEY、目标 URL 可达性以及网络连接资料来源：examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md。
检索效果差：调整 chunking.chunk_size 与 rag.top_k，或启用 reranking.py 演示的两阶段重排资料来源：examples/rag/README.md。
状态无法恢复：确认 session_id 命名一致、检查所选记忆提供者（RAG / Mem0 / Local）的连接配置资料来源：examples/python/stateful/README.md。
工具缺失：社区反馈希望补齐 LangChain / CrewAI 工具，在当前版本可通过 praisonaiagents/tools 中的 Spider、Newspaper、Stock Market 等替代实现类似能力资料来源：src/praisonai-agents/praisonaiagents/tools/README.md。

参见

Tools Module: src/praisonai-agents/praisonaiagents/tools/README.md
RAG Examples: examples/rag/README.md
Stateful Agents: examples/python/stateful/README.md
Consolidated Params: examples/consolidated_params/README.md

来源：https://github.com/MervinPraison/PraisonAI / 项目说明书

Deployment, CLI, Bots, Workflows & Advanced Capabilities

PraisonAI 提供一整套从本地开发到生产部署的运行表面：通过 praisonai CLI 暴露服务化与运维能力，借助 GitHub Action 实现 PR 自动审查，并通过 MCP Server v2、Agentic RAG、SBOM/PII 等高级能力扩展智能体边界。本页梳理这些能力的关系、用法与适用场景。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 2.1 GitHub Action 自动 PR 审查

继续阅读本节完整说明和来源证据。

章节 2.2 Recipe 生产服务

继续阅读本节完整说明和来源证据。

部署、CLI、Bots、Workflows 与高级能力

PraisonAI 提供一整套从本地开发到生产部署的运行表面：通过 praisonai CLI 暴露服务化与运维能力，借助 GitHub Action 实现 PR 自动审查，并通过 MCP Server v2、Agentic RAG、SBOM/PII 等高级能力扩展智能体边界。本页梳理这些能力的关系、用法与适用场景。

一、CLI 命令体系

PraisonAI 通过统一命令行 praisonai 暴露核心能力，主要命令分组如下：

命令	用途	关键参数 / 端点
`praisonai recipe serve`	启动 Recipe HTTP 服务	`--host --port --auth --workers --rate_limit --enable_metrics --enable_admin`
`praisonai endpoints health`	健康检查	无
`praisonai endpoints invoke`	调用 Recipe	`--input-json --api-key --json`
`praisonai mcp list-tools`	列举 MCP 工具	`--limit --cursor --json`
`praisonai rag query`	检索增强问答	`--collection`
`praisonai recipe sbom \	audit \	validate`	SBOM、依赖审计、锁文件校验	`--format cyclonedx/spdx --strict`

其中 recipe serve 在生产模式下可同时暴露 /metrics Prometheus 端点、/openapi.json 规范以及 /admin/reload 热加载入口资料来源：examples/serve/README.md:13-20；暴露公网时必须启用 --auth api-key 并通过环境变量注入密钥资料来源：examples/serve/README.md:74-78。

二、部署形态

2.1 GitHub Action 自动 PR 审查

examples/yaml/pr-reviewer 演示了零代码、多 Agent 的 PR 审查 Action：当用户在评论中以 @praisonai 触发时，Action 安装 PraisonAI 并加载 YAML 定义的团队（Security、Performance、Maintainability、Lead Reviewer），最终以结构化评论回写 PR 资料来源：examples/yaml/pr-reviewer/README.md:8-21。该流程与 Gemini 并行执行互不干扰，并被 Claude 纳入终评资料来源：examples/yaml/pr-reviewer/README.md:30-35。常见排障点包括 OPENAI_API_KEY、PRAISONAI_APP_ID、PRAISONAI_APP_PRIVATE_KEY 三个密钥以及 GitHub App 权限配置资料来源：examples/yaml/pr-reviewer/README.md:38-66。

2.2 Recipe 生产服务

examples/serve 中的 recipe_serve_features.py 与 recipe serve 共同覆盖生产级要素：API Key 鉴权、多 Worker 进程、速率限制、Prometheus 指标、管理员热加载以及 OpenAPI 规范资料来源：examples/serve/README.md:13-20。

三、Bots、Workflows 与多语言运行时

PraisonAI 的 Bot 与 Workflow 由 Agent、Task、AgentTeam 抽象驱动。TypeScript 与 Rust 端均提供与 Python 同名的 Agent/AgentTeam API，Rust 端额外提供 #[tool] 过程宏用于工具声明资料来源：src/praisonai-ts/README.md:55-90, src/praisonai-rust/README.md:23-32。examples/recipes/creator_suite 给出一组面向内容创作的 Recipe 模板（新闻抓取、脚本撰写、Hook 生成、B-roll 合成、发布），可直接作为 Bot 工作流复用资料来源：examples/recipes/creator_suite/README.md:11-25。

四、高级能力

MCP Server v2：遵循 MCP 协议 2025-11-25，支持工具/资源/提示分页（base64url 不透明游标，默认 50/页、上限 100）以及 readOnlyHint/destructiveHint/idempotentHint/openWorldHint 标注资料来源：src/praisonai/examples/mcp/README.md:11-25;CLI 提供 praisonai mcp list-tools|tools search|tools info|tools schema 等子命令资料来源：examples/mcp/README.md:42-58。
RAG 与 Agentic RAG：examples/rag 覆盖基础检索、混合检索（密集+稀疏）、自动决策检索与引用溯源；exa-tool 子目录演示基于 Exa 的 GPT-5 Agentic RAG Streamlit 应用资料来源：examples/rag/README.md:8-24。
安全与合规：security_example.py 与 recipe sbom/audit/validate 支持 CycloneDX/SPDX SBOM、依赖漏洞审计与 PII 字段（email/phone/ssn/credit_card）按 allow|deny|redact 模式脱敏资料来源：examples/security/README.md:5-31。
Consolidated Params：统一参数解析优先级为 Instance > Config > Array > Dict > String > Bool > Default，同一参数既可传 memory=True，也可传 memory="sqlite" 或 MemoryConfig(...) 资料来源：examples/consolidated_params/README.md:42-58。
工具插件系统：BaseTool 类与 @tool 装饰器双形态允许类或函数定义工具，并可打包为 pip 可安装的外部插件包资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:13-30。

社区关注

社区高频请求 Issue #6 希望 PraisonAI 引入 LangChain/CrewAI 生态工具资料来源：Issue #6。当前 praisonaiagents.tools 已通过 BaseTool 与装饰器插件机制开放外部扩展，并支持打包为独立 pip 包，与该诉求方向一致资料来源：src/praisonai-agents/praisonaiagents/tools/README.md:13-30。

参见

核心 Agent 与 Workflow 概念
MCP Server 协议参考
RAG 与知识库
安全与合规（SBOM、PII）

来源：https://github.com/MervinPraison/PraisonAI / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 来源证据：Wrapper layer: stub framework adapters, orchestrator-side version dispatch, and unconditional autogen-tool registration

可能增加新用户试用和生产接入成本。

medium 来源证据：DoctorContractProtocol for runtime config migration

可能影响升级、迁移或版本选择。

medium 来源证据：Runtime capability matrix and hook compatibility

可能增加新用户试用和生产接入成本。

medium 来源证据：YAML: fail-fast schema validation for agents/tasks config with actionable errors (+ `praisonai validate`)

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：MervinPraison/PraisonAI

摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Wrapper layer: stub framework adapters, orchestrator-side version dispatch, and unconditional autogen-tool registration。

1. 安装坑 · 来源证据：Wrapper layer: stub framework adapters, orchestrator-side version dispatch, and unconditional autogen-tool registration

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Wrapper layer: stub framework adapters, orchestrator-side version dispatch, and unconditional autogen-tool registration
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/1590 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 配置坑 · 来源证据：DoctorContractProtocol for runtime config migration

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：DoctorContractProtocol for runtime config migration
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/1941 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Runtime capability matrix and hook compatibility

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Runtime capability matrix and hook compatibility
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/1936 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：YAML: fail-fast schema validation for agents/tasks config with actionable errors (+ `praisonai validate`)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：YAML: fail-fast schema validation for agents/tasks config with actionable errors (+ praisonai validate)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/2125 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：src/praisonai/praisonai: three concrete gaps in framework dispatch, async lifecycle, and tool resolution

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：src/praisonai/praisonai: three concrete gaps in framework dispatch, async lifecycle, and tool resolution
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/1654 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/MervinPraison/PraisonAI | README/documentation is current enough for a first validation pass.

7. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/MervinPraison/PraisonAI | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/MervinPraison/PraisonAI | no_demo; severity=medium

9. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/MervinPraison/PraisonAI | no_demo; severity=medium

10. 安全/权限坑 · 来源证据：Gateway resume can silently lose events: no per-event sequence floor or gap/resync signal on reconnect

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gateway resume can silently lose events: no per-event sequence floor or gap/resync signal on reconnect
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/2153 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 安全/权限坑 · 来源证据：Retrievable tool-output overflow: implement and wire an ArtifactStore so large tool outputs are preserved, not discarded

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Retrievable tool-output overflow: implement and wire an ArtifactStore so large tool outputs are preserved, not discarded
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/2148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/MervinPraison/PraisonAI | issue_or_pr_quality=unknown

13. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/MervinPraison/PraisonAI | release_recency=unknown

来源：Doramagic 发现、验证与编译记录