PraisonAI 工程规范与实践指南Agent-Centric 开发工作流、TDD 执行流程与发布机制【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAIPraisonAI是一个以Agent-Centric为核心的多 Agent 框架生态本文基于仓库中src/praisonai-agents/.agent/workflows/instruction.md这份面向 Agent 开发者的工作指令文档完整解析其核心哲学、三层架构Core SDK / Wrapper / Tools、强制执行的三大开发阶段Analysis → Execute → Post-analysis、真实 Agent 测试要求以及 PyPI 发布工作流并结合仓库源码给出可验证的实现证据。读完本文你将掌握在 PraisonAI 生态中从需求分析、TDD 开发、CLI 对齐、文档撰写到最终发布的一整套可复制工程方法论以及这套规范在praisonaiagents与praisonai两个包中的落地方式。文档定位一份Agent 工作流指令而非普通文档src/praisonai-agents/.agent/workflows/instruction.md位于仓库的.agent/workflows/目录下带description: instruction的 front-matter其定位是在 AI 工程师或 Agent接手 PraisonAI 代码任务时强制执行的工作手册。它明确要求Create multiple TODOs and sub-TODOs, get all things done. First: detailed analysis, plan, and gap analysis... Then: implement, fix, test (TDD, Agent-Centric, no perf impact, DRY)... After: re-do detailed analysis/plan to find remaining gaps and propose fixes.即遵循先分析规划 → 再实现测试 → 最后复盘补缺的闭环同时给出三个硬性边界TDD 强制先写测试再写实现Agent-Centric所有设计围绕 Agents、workflows、sessions、tools、memory 展开零性能回退不允许出现性能回归。文档同时强调AGENTS.md 不是用来写文档的AGENTS.md is not for documentation它只承载开发约束而真正的用户文档交给 Mintlify 页面SDK 模块页与 API 接口页承载并且要求文档面向非开发者、多用 Mermaid 图配色约定Agent/输入/输出用 Dark Red#8B0000工具用 Teal#189AB4正文用白色#fff。核心哲学与工程原则核心哲学Simpler • More extensible • Faster • Agent-centric这一哲学贯穿整个 SDK 设计功能要强大但保持轻量可靠让非开发者也能上手SDK 与文档必须给人几行代码就能完成任务的体验Few lines of code to do the task!。五大设计原则原则规则Agent-Centric设计以 Agents、workflows、sessions、tools、memory 为中心Protocol-Driven核心 SDK 只放 protocols/hooks/adapters重逻辑放在 wrapper/toolsMinimal API参数少而精、默认值合理、覆盖需显式声明Performance-First懒加载、可选依赖、热路径零回归Production-Ready默认安全、多 Agent 安全、异步安全工程原则MUSTDRY复用抽象禁止重复代码Protocol-Driven Core核心只含协议/钩子重实现下沉到 wrapper/toolsNo perf impact懒导入、可选依赖、无全局单例、无重量级模块级工作TDD mandatory测试先行Multi-agent async safe by default默认多 Agent 与异步安全。这些原则在源码中有直接体现。src/praisonai-agents/praisonaiagents/__init__.py顶部就声明tools, config, memory, workflows, db, obs, knowledge 和 mcp 通过__getattr__懒加载以规避重量级依赖并给出了完整命名约定表add_X注册、get_X获取、enable_X开关、XConfig配置类等这正是Minimal API / 命名即文档的落地。src/praisonai-agents/praisonaiagents/agent/agent.py#L41-L45的注释进一步给出量化证据Rich、LLM 与显示工具只在outputverbose时导入将静默模式的导入耗时从约 420ms 降到约 20ms。关键硬性要求CRITICAL REQUIREMENTSEXECUTE VERIFY 模式不猜、不假设完成必须有证据仅用可选依赖所有重量级模块一律懒导入每个功能/修复都必须三线齐发Python CLI 文档/示例任何核心改动必须论证更简单的客户端 API、可衡量的收益、无性能回归如需 TypeScript 对齐则更新praisonai-ts但绝不能牺牲 Python 核心性能。三层架构Core / Wrapper / Tools文档用三个分区清晰定义了职责边界仓库目录结构与之一一对应层职责仓库位置Corepraisonaiagents协议驱动、轻量只含 protocols/hooks/adapters无重量级导入src/praisonai-agents/praisonaiagentsWrapperpraisonai真实集成数据库、可观测性、CLI懒导入 可选依赖src/praisonai/praisonaiToolspraisonai-tools可插拔工具绝不反向加重 core/wrapper 负担src/praisonai-agents/praisonaiagents/tools协议驱动的证据src/praisonai-agents/praisonaiagents/agent/protocols.py定义了AgentProtocol要求name属性、chat/achat方法与RunnableAgentProtocol扩展run/start/arun/astart注释明确说明其价值是在测试中无需真实 LLM 调用即可 mock Agent、支持自定义 Agent 实现、支持静态类型检查且这些协议零性能开销。这正是文档所说核心只含协议的落点。src/praisonai-agents/praisonaiagents/cli/protocols.py则是 wrapper ↔ code 边界上的 CLI 扩展协议TemplateStoreProtocol、SessionStoreProtocol、ServeHandlerProtocol等保证 CLI 功能在核心包中只依赖协议接口。工具的扩展点文档指明扩展点是tools/base.py、tools/decorator.py与db/*。仓库中src/praisonai-agents/praisonaiagents/tools/base.py提供BaseTool基类与ToolResult支持多模态 content 通道与model_output上下文压缩src/praisonai-agents/praisonaiagents/tools/decorator.py提供tool装饰器支持显式name/description、Injected状态注入、approvalTrue人工审批以及input_guardrails工具级守卫。强制执行流程三大阶段文档定义了不可跳过的 MANDATORY EXECUTION FLOW任何任务都必须走完三个阶段且以最终证据显示 missing 0作为收尾判据。PHASE 1 — 分析写代码之前步骤内容1.1 Acceptance Criteria针对 API、CLI、docs、tests、perf 写出可测试的验收标准1.2 Repo Inventory端到端扫描相关文件模块/类/API/导出、CLI 命令、测试、文档与示例给出路径 符号 grep 计数证据识别 DRY 机会1.3 Gap Analysis现有 vs 所需缺失项core SDK、wrapper、tools、CLI、docs、tests、exports与风险perf、API 破坏、可选依赖、异步、多 Agent1.4 Report当前行为、痛点、根因附文件引用、约束、风险登记表、决策日志1.5 Plan分步计划tests → impl → CLI → docs → verify列出待改文件与兼容/回滚/性能策略1.6 Proposal最小化的 Agent-Centric 设计协议进核心、实现进 wrapper给出升级路径说明1.7 TODO Tree细粒度可执行的任务树覆盖 Python CLI TDD docs perf倒数第二项必须是端到端验证所有改动最后一项必须是补齐剩余缺口missing0并复验或最终扫描确认 missing0PHASE 2 — 执行2.1 TDD先写会失败的测试要求确定性强、运行快2.2 实现DRY、Agent-Centric、协议驱动重逻辑放 wrapper/tools多 Agent 与异步安全2.3 CLI 对齐每个功能都必须有 CLI 命令要求可脚本化、帮助信息清晰、退出码正确2.4 文档Mintlify 页面SDK 用 Module、API 用 API提供可复制粘贴运行的示例2.5 验证运行单元/集成测试并展示结果冒烟验证python3 -c ...与 CLI help/run可选依赖缺失时优雅降级性能检查核心无重量级导入、导入耗时合理每个声明都给出证据终止进程时禁止发送 termination request 终止命令应 kill 端口。REAL AGENTIC TEST强制不可用冒烟测试替代文档特别强调仅构造对象断言属于 SMOKE TEST必须额外跑至少一次真实 Agent 执行——创建一个带被测特性的 Agent、调用agent.start(真实任务提示)而非仅构造对象、确认 Agent 调用了 LLM 并产生文本响应、打印完整输出。最小示例from praisonaiagents import Agent agent Agent(nametest, instructionsYou are a helpful assistant) result agent.start(Say hello in one sentence) print(result)冒烟测试与真实 Agent 测试两者都必须具备。这与src/praisonai-agents/praisonaiagents/agent/protocols.py中RunnableAgentProtocol.start的定义相呼应——start是真实执行入口而非单纯构造。PHASE 3 — 实现后分析3.1重新扫描文件总结最终行为与架构3.2确认剩余缺口API、CLI、docs、tests、exports、perf、multi-agent、async有缺口就继续当作必做工作直到 missing03.3报告改了什么、为什么、验证证据、权衡取舍3.4计划关闭剩余缺口或制定维护计划3.5提案对 UX、安全、性能、可扩展性的改进建议并标注 implemented 或 out-of-scope。功能交付的三通道CLI、YAML、Python文档要求每个功能都能以 3 种方式运行CLI、YAML、Python并强调所有功能必须有 CLI 集成、Agent 优先的命名与人体工学。仓库为此提供了丰富佐证Pythonpraisonaiagents的Agent类即文档中的最小示例形态YAML仓库examples/yaml/下存放大量可运行配置如agent-with-mcp.yaml、nested_workflow.yaml、agents_workflow.yaml等src/praisonai-agents/praisonaiagents/config/与src/praisonai-agents/praisonaiagents/task/负责将 YAML 描述解析为可执行对象CLIpraisonaiagents包内提供cli/目录与praisonaiwrapper 的cli/子模块src/praisonai-agents/praisonaiagents/cli/protocols.py中的协议正是为了CLI 功能可在 wrapper ↔ code 边界稳定复用而设计。发布工作流PUBLISH WORKFLOW文档给出完整的双包发布顺序先 Core SDK 后 Wrapper仓库中的 bump_and_release.py 脚本与之一致。触发方式GitHub Actions推荐手动发布Actions → PyPI Release → 在 main 分支运行 workflowbump 默认 patch夜间发布.github/workflows/nightly-release-gate.yml于每日 00:00 UTC 运行条件为src/praisonai或src/praisonai-agents自上一个v*tag 以来有变更、且当前 main HEAD 上 Core Tests 通过随后派发pypi-release.ymlbumppatch, sourcenightly发布前仍需 pypi 环境审批临时 minor/major仅手动 PyPI Release显式选择 bump 级别。Step 1 — 发布 praisonaiagentsCore SDKcd src/praisonai-agents praisonai publish pypi内部使用 uvuv lock→uv build→uv publish自动 bump patch 版本需要PYPI_TOKEN环境变量。Step 2 — 发布 praisonaiWrappercd src/praisonai python scripts/bump_and_release.py WRAPPER_VERSION --agents AGENTS_VERSION --wait # 示例 python scripts/bump_and_release.py 4.5.90 --agents 1.5.91 --wait脚本会等待 agents 在 PyPI 上可用然后 bump 所有版本文件、执行uv lock、构建、提交、打 tag、推送并创建 GitHub Release随后在src/praisonai清理dist/后执行uv publish。若bump_and_release已完成发布仅需验证pip index versions praisonai | head -1若uv publish报 File already exists说明该版本已存在于 PyPI——即发布成功。bump_and_release.py 的文档字符串给出了更完整的参数形态--agents指定 agents 版本、--wait等待 PyPI 传播、--auto自动探测 PyPI 上最新 agents 版本、--code/--bot/--train及对应--wait-code/--wait-bot/--wait-train管理附属包发布顺序为 praisonaiagents → praisonai-code → praisonai-bot → praisonai-train → praisonai-browser → praisonai另有 publish_all.py 支持一键全量发布默认 patch支持--dry-run。Step 3 — 发布 praisonai-tools外部包按需# 在 pyproject.toml 中 bump 版本后 python3.13 -m build uv run twine upload dist/*PR 合入门控PraisonAI 的 PR 默认通过Claude PR merge gate.github/workflows/claude-merge-gate.yml在验证通过后合并如需退出自动合并给 PR 加no-auto-merge标签门控无法运行时才退化为手动gh pr merge。实践要点与自检清单综合文档要求在 PraisonAI 生态中完成任何功能开发时可对照以下检查清单验收先行为 API、CLI、docs、tests、perf 各写一条可测试的验收标准协议驱动核心新增能力优先以 Protocol 表达参考agent/protocols.py实现放在 wrapper/tools性能红线新代码不得引入模块级重量级导入或全局单例静默模式导入耗时是硬指标三通道交付同一功能同时给出 Python 示例、YAML 配置与 CLI 命令测试分级单元测试TDD 先行 集成测试 冒烟测试python3 -c与 CLI help/run真实 Agent 测试agent.start(真实任务)且打印输出证据闭环实现后重新扫描确认 API、CLI、docs、tests、exports、perf、multi-agent、async 各项缺口为 0再宣告完成文档面向非开发者Mintlify 组件 Mermaid 图Agent 用 Dark Red、工具用 Teal示例必须可复制运行发布顺序先praisonai publish pypi发布 agents再用bump_and_release.py --wait发布 wrapper最后按需发布 tools。这套工作流既是开发规范也是让Agent 自主完成 PraisonAI 功能开发可被验证、可被审计的工程保障从分析到实现到发布每一步都要求可测试、可复现、有证据最终落实为missing 0的确定性交付。【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考