PraisonAI 签名一致性Signature ParityPython praisonaiagents 与 TypeScript praisonai-ts 逐参数对齐的工程化实践【免费下载链接】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 采用 Pythonpraisonaiagents与 TypeScriptpraisonai-ts双语言 SDK 实现同一套 Agent 能力本文围绕仓库中的签名一致性报告 SIGNATURE_PARITY.md 展开讲解该报告衡量什么、如何自动生成、如何解读 17 个公开 API 面的 224 个参数的匹配结果以及 30 条豁免waiver背后的设计决策。读完你将掌握签名一致性检查器的运行机制、匹配层级与门禁策略并能读懂这张表去评估双端 SDK 的参数级对齐程度。一、什么是签名一致性与 PARITY.md 的互补关系PraisonAI 仓库中的双端 SDK 长期存在导出符号相同、参数行为不同的风险。仓库里已有 PARITY.mdFeature Parity Tracker它只回答TypeScript 是否导出了与 Python 同名的符号通过解析src/praisonai-ts/src/index.ts的export * from重导出检查名称是否存在。但正如该文件开头的警告所说一个✅ exported单元格只意味着名字被导出并不验证该能力是否真正接线、是否像 Python 端一样工作。签名一致性报告Signature Parity正是为了补上这一层它不再看符号是否存在而是逐参数比对Python 构造器/方法的每个参数与TypeScript 接口成员/方法参数的对应关系、必填性required-ness与有效默认值effective default。以两个具体数字说明分工PARITY.md 显示 TypeScript 侧导出 2058 个特性、与 Python 的缺口为 6P2 中等 1、P3 低 5SIGNATURE_PARITY.md 则在 17 个精挑细选的 surface 上、对 224 个 Python 参数做逐一比对发现 28 处 mismatch 全部被 30 条 waiver 覆盖同时识别出 86 个 TS-only 成员。前者管名字齐不齐后者管参数签名叫不叫得齐两者一起构成双端一致性的两层防线。二、测量机制surface 定义、匹配层级与默认值判定2.1 surface.yaml谁来定义值得比对的表面报告是自动生成的文件头注明由python -m praisonai._dev.parity.signatures --write生成所有被比对的 API 面由 surface.yaml 这份白名单决定。该文件的注释明确了它的设计哲学python.file相对python_rootsrc/praisonai-agents/praisonaiagentstypescript.file相对typescript_rootsrc/praisonai-ts/srcdiscover.init_first_param通过__init__的首参来解析类例如AgentTeam.__init__用init_first_param: agents定位因为agents.py把团队类以PraisonAIAgents、Agents等多个别名导出文件还支持两种签名决策字段export_identity与method_waivers均要求reason与owner缺一不可否则加载失败退出码 2它们不是让检查静音的手段——分歧依旧会被检测并打印为携带原因的警告。surface.yaml 共登记 17 个 surface覆盖 Agent 生命周期Agent.__init__、Agent.start、Agent.chat、团队编排AgentTeam.__init__、AgentTeam.start、任务Task.__init__、交接Handoff.__init__、模型LLM.__init__、会话Session.__init__、工具tool()、ToolsetRegistry.register_toolset、错误PraisonAIError.__init__、知识Knowledge.__init__、FileTracker.__init__以及升级与目标工程GoalEngineer.__init__、DoomLoopDetector.__init__、EscalationPipeline.__init__其中最后一批是 2026-09-03 随功能移植新增的 surface。2.2 匹配顺序exact → camelCase → flattened → alias → missing对 Python 的每个参数位置参数与仅关键字参数*args/**kwargs排除检查器按以下顺序在 TypeScript 侧查找对应成员exact同名精确匹配camelCasePython 的snake_case转成camelCasesnake_to_camel例如api_key→apiKey、max_retries→maxRetriesflattenedPython 端的一个嵌套配置参数在 TS 端展开为多个顶层字段例如Agent.__init__.output展开为verbose、markdown、stream三个字段alias语义别名由 rules.yaml 定义例如base_url→baseURL、interrupt_controller→signal、cancel_token→signal、tool_name_override→name、input_filter→transformContext否则标记为missing。对于匹配成功的参数对检查器还会比较必填性与有效默认值。值得注意的判定细节来自报告原文TS 构造器中的回退表达式如config.x ?? v会被视为有默认值一个被展开flattened的参数会逐一对照它命名到的每个 TS 字段并在 rules.yaml 指明python_config时与 Python 嵌套配置类的字段默认值而非参数自身的None比较TS 端无法静态求值的默认值记为unknown必须走 waiver不能当作undefined放行必需的 TS-only 成员会让检查失败可选的 TS-only 成员仅作提示类型类的差异只作为 warning 输出。2.3 rules.yaml把命名约定与默认值等价规则集中管理rules.yaml 把所有规范化规则集中在一处避免提取器与比较器各自硬编码约定case: snake_to_camel对每个 Python 参数自动应用aliases各 surface 的非纯大小写转换的语义别名见上节flattenedAgent.__init__的output、execution、caching三个参数被展平——其中caching展平为cache对应CachingConfig.enabled与cacheTTLTS 独有仅检查必填性文件注释特别强调正因为 flattened 先于 alias 解析才避免了caching - cache这条别名规则抢跑导致双字段规则永不生效default_equivalences含义相同的默认值配对例如{python: null, typescript: undefined}、{python: null, typescript: []}、{python: false, typescript: undefined}TS 中未设置的布尔值即为 falsy、{python: 0.0, typescript: 0}Python 浮点零与 TS 单一 number 类型、{python_expr: _UNSET, typescript: undefined}Python 模块级未传参哨兵等价于 TS 的undefined。该文件还内置自检机制compare.validate_rules在每次真实提取时运行若某个 alias 或 flattening 指向不存在的 Python 参数、被更早的匹配层级遮蔽、或只是纯粹的大小写变化工具会以退出码 2失败对应测试见tests/unit/_dev/test_signature_parity.py::TestRulesSelfTest。三、检查器工具链与 CLI签名一致性检查器位于 signatures 模块compare.py、py_extract.py、schema.py、export_identity.py、method_inventory.py等报告由 compare.py 中的纯函数compare_all、evaluate、render_markdown、render_json渲染这些函数直接操作预提取的SurfaceSignature对象因此无需 Node 或 TypeScript 编译器即可用 JSON fixture 做单测。运行方式与退出码来自 compare.py 的模块 docstring 与 surface.yaml 注释# 生成/更新报告写入 src/praisonai-ts/SIGNATURE_PARITY.md 与 signature-parity.json python -m praisonai._dev.parity.signatures --write # 仅做检查CI 门禁 python -m praisonai._dev.parity.signatures --check退出码约定退出码含义0全部通过1parity 失败缺口、漂移、waiver 问题或什么都没检查到2工具链失败node/typescript 缺失、surface 未找到输出物包括 Markdown 报告即本文主体 SIGNATURE_PARITY.md与机器可读的 signature-parity.json。底层 TS 侧提取通过ts_extract.mjs调用真实编译器完成Python 侧则由py_extract.py基于 AST 解析。四、总体汇总17 个 surface、224 个参数的对齐全貌报告汇总表截至生成时如下可直接作为双端签名健康度的总览SurfaceParamsExactcamelCaseAliasFlattenedMissingMismatchesWaivedTS-only / TS totalAgent.__init__422982308813 / 59AgentTeam.__init__23203000113 / 26Task.__init__603129000773 / 64Agent.start1100000020 / 21Agent.chat1779100002 / 19AgentTeam.start321000001 / 4Handoff.__init__7223002213 / 21LLM.__init__25816100001 / 26Session.__init__716000115 / 12tool()1355102353 / 14GoalEngineer.__init__642000552 / 8DoomLoopDetector.__init__1100000015 / 16EscalationPipeline.__init__532000004 / 9ToolsetRegistry.register_toolset550000000 / 5PraisonAIError.__init__624000111 / 7FileTracker.__init__101000000 / 1Knowledge.__init__220000000 / 2Total (17 surfaces)22412388832283086 / 314几个值得注意的整体特征223/224 个参数都能找到对应仅tool().input_guardrails与tool().output_guardrails两个参数缺失且已豁免见第七章123 个 exact 88 个 camelCase 合计 211 个即超过 94% 的参数通过同名词根 大小写转换就能对上说明双端 API 命名在刻意保持同构86 个 TS-only 成员表明 TS 端在参数上并非 Python 的镜像而是叠加了相当多自身的能力如AbortSignal、流式回调、持久化等所有 28 处 mismatch 都有对应 waiver当前没有任何未豁免的不一致——这是门禁策略的结果而非巧合。五、核心 Surface 逐面解读5.1Agent.__init__42 参数对齐最复杂的表面Python 侧位于 agent.pyTS 侧接口与构造器在 simple.tsctor 位于 L1008。42 个参数中 29 个 exact、8 个 camelCase、2 个 aliasbase_url → baseURL、interrupt_controller → signal、3 个 flattenedoutput、execution、caching0 缺失8 处 mismatch 全部豁免。该表直观展示了参数命名的三种典型形态exactname、role、goal、backstory、llm、tools、memory、knowledge、planning、reflection、guardrails、web、context、autonomy、output、hooks、skills、approval、learn、backend、runtime、sandbox、retry、templates等camelCaseapi_key → apiKey、self_improve → selfImprove、tool_config → toolConfig、run_on → runOn、tools_run_on → toolsRunOn、tool_search → toolSearch、message_steering → messageSteering、reasoning_effort → reasoningEffortaliasbase_url → baseURL、interrupt_controller → signalTS 用AbortSignal表达中断Python 用InterruptController协议对象。3 个 flattened 参数尤其能说明嵌套配置如何映射到 TS 顶层字段Python 参数Python 配置类TS 展开字段TS 默认值状态outputOutputConfigverbose, markdown, streamverbosegetEnv(PRAISON_VERBOSE) ! false、markdowntrue、streamtruedefault mismatch已豁免executionExecutionConfigmaxIterations, maxToolCallsPerTurnmaxIterations20、maxToolCallsPerTurn10okcachingCachingConfigcache, cacheTTLcachefalse、cacheTTL3600default mismatch已豁免其中output的豁免说明了一个真实的产品分歧Python 端outputNone解析为静默预设verbose、markdown、stream 全为 false而 TS 端默认 markdown/stream 为 true、verbose 取环境变量PRAISON_VERBOSE。报告明确指出对齐字面默认值会改变所有现有调用方的默认行为需要产品决策而非悄悄修改并且展开行的比较是修复比较器之后才暴露出来的这正是它此前被忽视的原因——这是整个文件中最具方法论价值的一条注释。Agent.__init__的 13 个 TS-only 成员为config、pretty?、fetch?、outputSchema?、outputSchemaName?、toolFunctions?、db?、sessionId?、runId?、historyLimit?、autoRestore?、autoPersist?、telemetry?涵盖 TS 端特有的 Schema 输出、会话持久化与遥测注入。5.2Task.__init__60 参数最大的 surfacePython 侧位于 task.pyTS 侧接口在 types.ts。60 个参数中 31 个 exact、29 个 camelCase、0 缺失7 处 mismatch 全部豁免3 个 TS-onlydependencies?、humanInput?、humanReviewPrompt?。任务参数高度强调流程控制其 camelCase 形态非常密集async_execution → asyncExecution、output_file → outputFile、output_json → outputJson、create_directory → createDirectory、task_type → taskType、is_start → isStart、loop_state → loopState、quality_check → qualityCheck、retain_full_context → retainFullContext、max_retries → maxRetries、retry_delay → retryDelay、skip_on_failure → skipOnFailure、on_error → onError、should_run → shouldRun、loop_over → loopOver、loop_var → loopVar、then_task → thenTask、else_task → elseTask、output_variable → outputVariable、fail_on_callback_error → failOnCallbackError、fail_on_memory_error → failOnMemoryError等。注意depends_on → dependsOn的默认值处理TS 端dependsOn回退到config.context ?? []Python 端if depends_on is not None给出相同优先级含显式空列表豁免理由指出TS 端没有暴露dependsOn读回属性Python 端返回的是context。5.3Agent.start与Agent.chat方法与参数的镜像程度差异Agent.startPython execution_mixin.pyTS simple.ts只有 1 个 Python 参数prompt却对应 20 个 TS-only 成员——previousResult?、onToken?、signal?、onEvent?、options?、temperature?、tools?、outputJson?、outputPydantic?、reasoningSteps?、stream?、taskName?、taskDescription?、taskId?、config?、forceRetrieval?、skipRetrieval?、attachments?、toolChoice?、seed?。这反映了 TS 端把单次执行的诸多运行时控制项都收敛到了start方法参数上。Agent.chatPython chat_mixin.pyTS simple.ts则是另一个极端17 个 Python 参数全部命中7 exact、9 camelCase、1 alias0 mismatch、0 waived只有 2 个 TS-onlypreviousResult?、options?。tool_choice → toolChoice的类型为auto | none | required | stringcancel_token别名到signal: AbortSignal。可以说Agent.chat是当前签名对齐最干净的方法之一。5.4Handoff.__init__、LLM.__init__、Session.__init__别名与 camelCase 的密集区Handoff.__init__Python handoff.pyTS handoff.ts7 个参数中 3 个走 alias——tool_name_override → name、tool_description_override → description、input_filter → transformContext。13 个 TS-only 成员condition?、contextPolicy?、maxContextTokens?、maxContextMessages?、preserveSystem?、toolPolicy?、timeoutSeconds?、maxConcurrent?、detectCycles?、maxDepth?、allowParallel?、onComplete?、onError?展示了 TS 端更精细的交接上下文策略LLM.__init__Python llm.pyTS llm/index.ts25 个参数中 16 个 camelCasetop_p → topP、max_tokens → maxTokens、presence_penalty → presencePenalty、frequency_penalty → frequencyPenalty、logit_bias → logitBias、response_format → responseFormat、stop_phrases → stopPhrases、web_search → webSearch、web_fetch → webFetch、prompt_caching → promptCaching、claude_memory → claudeMemory、failover_manager → failoverManager、max_iter → maxIter等1 个 aliasbase_url → baseURL仅 1 个 TS-onlyconfig0 mismatch——是大型 surface 中对齐最完整的代表Session.__init__Python session/api.pyTS session/session.ts7 个参数中 6 个 camelCasesession_id → sessionId、user_id → userId、agent_url → agentUrl、memory_config → memoryConfig、knowledge_config → knowledgeConfig、session_ttl → sessionTtl5 个 TS-onlyconfig?、id?、parent?、db?、ttl?。5.5tool()装饰器唯一存在缺失参数的 surfacePython 侧 decorator.pyTS 侧 tools/decorator.ts。13 个参数中 2 个 missinginput_guardrails、output_guardrails、3 处 mismatch、5 条 waiver——这是整个报告中真实差距密度最高的表面funcalias 到 TS 的必填executePython 端func可选只是为了支持tool裸装饰用法FunctionTool.__init__内部仍要求它属 required mismatch 豁免nameTS 无法从匿名函数推断名称Python 可从__name__推断input_guardrails/output_guardrails豁免条目明确写着NOT an equivalence——与文件中其它 waiver 不同这两条记录的是真实缺口Python 端每工具输入/输出护栏实现在 tool_guardrails.pyTS 端尚无对应实现且设置了过期时间2026-12-07这样如果移植被遗忘门禁会失败而不是让豁免永久化。5.6 升级管线与目标工程DoomLoopDetector、EscalationPipeline、GoalEngineerDoomLoopDetector.__init__Python doom_loop.pyTS doom-loop.ts仅 1 个config参数 exact 匹配15 个 TS-only 成员maxIdenticalActions?、maxSimilarActions?、maxConsecutiveFailures?、maxNoProgressSteps?、similarityThreshold?、maxTimePerAction?、maxTotalTime?、enableAutoRecovery?、maxRecoveryAttempts?、escalateOnLoop?、initialBackoff?、backoffMultiplier?、maxBackoff?、maxRepeatedChunks?、contentChunkSize?——TS 端把全部循环检测配置直接暴露为顶层字段EscalationPipeline.__init__Python pipeline.pyTS pipeline.ts5 参数全部命中checkpoint_service → checkpointService、on_stage_change → onStageChange4 个 TS-onlyoptions?、autonomousRunner?、observability?、doomLoopConfig?GoalEngineer.__init__Python engineer.pyTS goal/engineer.ts6 参数 5 处 mismatch 全部豁免——豁免理由一致地解释构造器只在显式传入时才覆盖maxCriteria/threshold/autoDecompose/verbose默认值活在GoalConfig上提取器报告无默认值而非编造一个这才是正确读法而model则与Agent.__init__.model同型——TS 端急切调用resolveDefaultModel()Python 端先留None再延迟解析。报告同时核对了另外四项maxCriteria 5、threshold 8.0、autoDecompose true、verbose false在双端真实一致只是提取器不跨文件做常量折叠才显示为unknown。5.7 基础构件ToolsetRegistry、PraisonAIError、FileTracker、KnowledgeToolsetRegistry.register_toolsetPython toolsets.pyTS toolsets.ts5/5 全部 exact0 mismatch、0 TS-only——完美的镜像对齐样本PraisonAIError.__init__Python errors.pyTS errors-base.tsagent_id → agentId、run_id → runId、error_category → errorCategory、is_retryable → isRetryableFileTracker.__init__Python knowledge/indexing.pyTS knowledge/indexing.ts与Knowledge.__init__Python knowledge.pyTS knowledge.ts全部命中、0 豁免、0 TS-only同样是干净对齐。六、TS-only 成员双端能力差异的显式清单86 个 TS-only 成员中绝大多数是可选的表中以?标注唯一一个必填的 TS-only 成员是Agent.start场景之外的特例吗不——汇总表里并未出现必填 TS-only 导致的失败因为报告只把必需的 TS-only 当作检查失败可选的一律记作 informational。这些成员本质上是 TypeScript SDK 相对 Python 的能力增量清单按主题可归为几类会话与持久化Agent的db?、sessionId?、runId?、historyLimit?、autoRestore?、autoPersist?Session的id?、parent?、db?、ttl?执行控制Agent.start/Agent.chat的signal?AbortSignal、onToken?、onEvent?、stream?、toolChoice?、seed?、reasoningSteps?结构化输出outputSchema?、outputSchemaName?、outputJson?、outputPydantic?交接与升级Handoff的contextPolicy?、timeoutSeconds?、detectCycles?、maxDepth?、allowParallel?EscalationPipeline的observability?、doomLoopConfig?DoomLoopDetector的全部 15 个字段遥测telemetry?。读懂这一列的实际价值在于Python 开发者对照 TS 文档时这些成员就是TS 有、Python 没有的边界反过来维护者新增 Python 参数时它提醒需要同步评估 TS 端是否存在等价入口。七、豁免机制30 条 waiver 的三类本质报告要求每个缺口必须在 waivers.yaml 中豁免否则检查失败。30 条活动豁免按实质可分为三类第一类同值不同时点Same value, resolved at a different moment——约占一半是假的 mismatch。典型如Agent.__init__.roleTS 构造器存config.role || AssistantPython 的self.role role or Assistant在方法体内产生相同字符串goal、backstory同理分别回退到instructions或内置句子Agent.__init__.modelTS 急切调用resolveDefaultModel()即 default-model.ts 对 PythonAgent._PROVIDER_DEFAULT_MODELS/_resolve_default_model的逐字节移植——相同环境在双端得到相同模型只是解析时机不同且 TS 额外支持PRAISONAI_MODEL别名Task.__init__.description/actiondescription回退到action、action回退到description双端在构造器与方法体内各自解析出相同字符串Handoff的两个 overridedefaultHandoffToolName现在精确产出 Python 的transfer_to_小写、空格转下划线defaultHandoffToolDescription精确产出Transfer task to name (role) - goal此前两者分别输出会含空格而被 provider 拒绝、或措辞不一致的旧版本均已修正PraisonAIError.__init__.run_id、Session.__init__.user_id双端都在构造时急切赋值run_id or str(uuid.uuid4())、user_id or default_user只是声明默认值不同run_id的边界情况被明确指出runId: 在 TS 的??下能存活却被 Python 的or替换。第二类刻意保留的行为分歧deliberate divergenceAgent.__init__.caching双端默认都不缓存但路径不同——Python 的cachingNone解析为CachingConfig(enabledTrue)并置self.cache True但Agent.cache在 praisonaiagents 中只写不读TS 端cache默认 false 且被响应缓存真正采用。对齐字面值反而会在 TS 打开缓存、与 Python 的可观察行为分道扬镳并已被 parity-waiver-gaps.test.ts 的 caching default 用例钉住Agent.__init__.output见 5.1 节静默预设 vs TS 默认 markdown/stream 为 true需要产品决策AgentTeam.__init__.processTS 把未定义 process 当作 sequentialPython 默认值但报告以已核实、超出本 key 范围的口吻记录了一个更深的领域差异——TS 用Promise.all实现process: parallel而 Python 对parallel抛ValueErrorTS 端不校验任何值拼写错误会静默按 sequential 运行Task.__init__.id显式id在 Python 被强制转成strTask(id5).id为5TS 保持 number5Task.__init__.routingTS 把routing列入ENGINE_LEVEL_OPTIONS任何值都会触发notYetHonoured提示且永不进入执行而 Python 的 workflow 执行器会读取它——这是TS 承认尚未实现的诚实记录Agent.__init__.nameTS 生成Agent_randomPython 对仅指令型 agent 留None否则用Agent——双方都不是稳定契约Python 端所有无名 agent 都撞名Agent且Handoff对无名 agent 会抛AttributeErrorTS 端也没有像AgentTeam.get_agent_details那样的按名查找。第三类真实缺口NOT an equivalence——tool().input_guardrails与tool().output_guardrails已在 5.5 节详述是唯一明确标注不是等价、是真实差距的两条且带过期时间 2026-12-07 作为移植提醒。每一条 waiver 都带Owner统一为 praisonai-ts部分带Issue关联说明这套门禁背后是人可以决策、机器执行门禁的治理模型。八、门禁、测试与工程化闭环签名一致性不是一个一次性报告而是一条可持续运行的工程化流水线生成即检查报告由python -m praisonai._dev.parity.signatures --write生成文件头注明请勿手工编辑避免报告与代码脱节CI 门禁--check模式以退出码 1 阻断任何未豁免的 gap/drift/waiver 问题以退出码 2 阻断工具链故障rules.yaml的别名/展平规则还带有自检命名不存在的参数即失败测试钉住行为TS 侧有一整组 parity 测试保障关键行为不被悄悄改变例如 parity-waiver-gaps.test.ts 专门验证caching 默认值等豁免点另有 parity-agent.test.ts、parity-task.test.ts、llm-config-parity.test.ts、session-config-parity.test.ts、tool-config-parity.test.ts 等覆盖各模块的配置级一致性双产物输出人类读 SIGNATURE_PARITY.md机器读 signature-parity.json后者可被 CI 脚本或代码生成工具消费。九、总结从这份报告能学到什么签名一致性报告是 PraisonAI 双语言 SDK 治理的核心证据文件。对使用者而言它是一张双端 API 对照表223/224 个参数成功映射命名规则高度同构exact camelCase 占 94% 以上86 个 TS-only 成员标明了 TS 的能力增量30 条豁免逐条解释了 28 处 mismatch 的来龙去脉——其中绝大多数是解析时机不同而非行为不同真正诚实的缺口只有tool()的输入/输出护栏且带过期提醒。对维护者而言它是一套可复制的工程范式以surface.yaml声明比对面、以rules.yaml集中命名与默认值约定、以waivers.yaml让每次分歧都有签名与理由、以退出码让 CI 阻断任何未经豁免的漂移。任何追求 Python/TypeScript 双端 API 长期同构的项目都可以直接借鉴这套表面声明—规则归一—豁免治理—门禁闭环的签名一致性机制用同样的方式守住跨语言 SDK 的最后一公里。【免费下载链接】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），仅供参考