人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载导读本文聚焦 harness-sdk 团队协作规范中的核心机制——API Bar-RaisingAPI 提标评审它是一套在功能合并进 SDK 之前对公开 API 设计与客户侧契约进行系统性把关的质量门禁流程。在本仓库中该机制被用来保证 strands-py 与 strands-ts 两套 SDK 的 API 表面长期保持高质量、一致性与可演进性。读完本文你将掌握API Proposer 与 API Reviewer 两个角色的职责边界、按变更规模分级的评审时间线、api/needs-review与api/review-complete标签驱动的 CI 门禁工作流以及如何产出符合仓库规范的 PR 描述与决策记录。一、什么是 API Bar-RaisingAPI Bar-Raising 是 harness-sdk 引入的一种机制目的是在开发新功能时确保 SDK 的公开 API 表面保持高质量、一致且面向未来同时符合团队对 SDK 的预期以及 团队发展信条Simple at any scale、Extensible by design、Composability、The obvious path is the happy path、We are accessible to humans and agents、Embrace common standards。它的定位非常明确它是一个质量门禁quality gate新功能必须在合并前通过评审它同时尽量降低新功能接入 SDK 的摩擦避免流程过重拖慢迭代它只关注公开 API 设计与客户可见契约不涉及实现细节也不评审内部/私有 API。也就是说评审的衡量对象是客户如何使用这个 API而不是这个 API 内部是怎么实现的。这一原则与 PR 编写规范 中聚焦 WHY 而非 HOW的指导思想一脉相承实现细节交给 diff 与 commit message评审者关心的是更广的上下文与用户影响。二、两个核心角色API Proposer 与 API ReviewerAPI Bar-Raising 涉及两个角色职责互补角色承担者核心职责API Proposer正在开发或提出新功能/新 API 的工程师记录使用场景use cases、提供示例代码、为评审准备完整材料API Reviewer从客户视角批判性评审公开 API 的工程师评估公开 API 是否符合 SDK 信条、决策记录与客户使用习惯并非正式团队岗位任何有多年 API 开发经验的工程师都可担任API Reviewer 的关键提问清单API Reviewer 的评审立场是略带对抗性的主动挑战假设、识别用例覆盖的缺口、确保 API 与 SDK 信条一致。评审时应围绕以下问题展开是否符合 SDK 信条是否符合 决策记录如果可扩展性是目标哪些部分可自定义、哪些不可抽象层级是否恰当哪些使用场景未被覆盖为什么默认参数/默认行为是否是最常见的如果不是为什么这样选择如果一次 API 评审会话产生了能够指导未来 API 设计的结论就应将其记录为一条决策记录Decision Record——这正是 bar-raising 成功的标志。仓库中 team/DECISIONS.md 已经沉淀了多条这类结论例如Hooks 作为低层原语而非高层抽象优先扁平命名空间而非嵌套模块Provide Both Low-Level and High-Level APIs避免在 API 命名中重载领域术语等它们反过来又成为后续评审时的对照依据。API Proposer 的准备清单API Proposer 的目标是让 API Reviewer无需深入理解实现即可从客户视角完整评估 API。为此需要准备记录新功能的预期使用场景提供满足这些使用场景的示例代码片段。为了让评审讨论更顺畅还可额外准备完整的 API 签名包括默认参数值从客户视角出发的端到端示例用法包含模块导入语句如果相关包含与既有功能的集成场景模块导出清单每个模块导出了什么。并且任何涉及该功能的 PR都应把上述信息写进 PR 描述作为日后参考存档。三、评审时间线按变更规模分级API Bar-Raising 必须在新功能或既有功能更新合并进 SDK 之前完成。具体评审强度取决于变更规模变更规模评审方式典型示例最小变更Minimal常规 PR review 即可无需专门指定 API Reviewer给不常用的方法新增一个参数新增一个重载来微调既有行为中等变更Moderate先与 API Reviewer 进行非正式讨论再做常规 PR review新增一个客户用来达成新行为的类重大变更Substantial在设计阶段或之后召开专门的 API Reviewer 会议期望至少 2 位 reviewer 参与新增一个客户预期会频繁使用的原语或抽象补充说明对于较大的功能应在设计流程早期就引入 bar-raising但合并前仍需进行最终评审。也就是说早期评审用于尽早发现潜在问题最终评审是合并前的质量闸门两者不可互相替代。四、流程实操指定 API Reviewer 与 CI 标签门禁标准 PR 评审路径对于标准 PR只需找一位有 API 开发经验的工程师担任 API Reviewer并要求其从 API Reviewer 视角评审提案——聚焦客户使用与公开 API 设计而非深挖实现细节。只要 API Proposer 准备充分API Reviewer 应能仅凭 PR 描述就完整理解并评估提案从而让评审高效且聚焦。用标签跟踪评审状态CI 强制门禁为了让哪些 PR 在等待评审、哪些已通过 API 视角审批一目了然仓库定义了两个 PR 标签api/needs-review标记该 PR 需要 API 评审api/review-completeAPI Reviewer 完成评估、且必要的修改已落实后打上此标签。关键机制CI 会强制检查——带有api/needs-review标签的 PR如果没有api/review-complete标签不能被合并参见 team/API_BAR_RAISING.md 的说明。这意味着评审状态不是靠口头约定而是由 CI 硬性执行杜绝了忘记评审就合入的漏洞。大型功能的会议评审路径对于需要更深入讨论的大型功能应安排与指定 API Reviewer 的会议逐条过使用场景与 API 设计决策。会议形式可正式也可非正式视功能复杂度而定中小型功能30–60 分钟的单次讨论即可大型功能可在设计与实现阶段安排多轮会议。目标是在早期捕获问题同时保持功能开发的快速迭代节奏。备选方案团队共识Team Consensus除指定 API Reviewer 外还可以用团队共识替代当需要广泛对齐、或 API 引入了整个团队都会基于其构建的模式时例如双向智能体 API即 strands-py 中的 BidiAgent团队级讨论收益明显。但团队共识要谨慎使用——一次 30 分钟、10 人参与的会议等于 5 小时的集体投入只有当投入产出比合理时才值得动用。五、评审结论的沉淀从 API 评审到决策记录API Bar-Raising 的长期价值在于每一次成功的评审都应让未来的 API 设计站在前人的肩膀上。仓库 team/DECISIONS.md 就是这一机制的产物其中多条决策可以直接追溯到评审中提出的问题Hooks 作为低层原语而非高层抽象不要让retry_strategy: HookProvider直接暴露给用户而应在 hooks 之上构建RetryStrategy(HookProvider)这类带领域方法与类型签名的高层接口——对应抽象层级是否恰当的评审提问。仓库中 HookProvider 协议 正是这一决策的落地载体优先扁平命名空间from strands.hooks import MultiAgentInitializedEvent优于from strands.hooks.multiagent import MultiAgentInitializedEvent——对应可发现性评审关注点strands-py/src/strands/hooks/init.py 中的 re-export 即为佐证同时提供低层与高层 APIBidiAgent暴露send/receive低层 API同时提供run高层封装——对应默认行为是否最常见的评审提问Pay for Play可选破坏性变更可接受破坏性变更必须被新功能门控——用户不采用新功能就永远不会遇到破坏对应评审中哪些用例未被覆盖的追问公开 API 使用 LLM 原生单位参数以 token 而非字符计数如max_tokens而非max_charsnull表示显式移除undefined表示应用默认值仅适用于 SDK 透传字段如 provider 的params不适用于功能开关false仍是显式关闭避免在 API 命名中重载领域术语Python 用structured_output_model、TypeScript 用structuredOutputSchema各取各自语言生态的惯用语。这些决策记录在后续所有 API 评审中都会被引用形成评审 → 决策 → 再评审的正向循环。六、配套规范PR 描述如何支撑 Bar-RaisingAPI Bar-Raising 要求 PR 描述承载评审所需材料因此与 PR 编写规范 深度绑定。规范要点如下每份 PR 描述应包含Motivation——为什么需要这个变更Public API Changes——公开 API 的变更含代码片段仅在引入或修改公开 API 表面时填写Use Cases可选——开发者何时会使用该功能仅对不显而易见的功能填写Breaking Changes如适用——破坏了什么、如何迁移。写作原则聚焦 WHY 而非 HOW例如写Hook providers need access to the agents result to perform post-invocation actions like logging or analytics而不是Added result field to AfterInvocationEvent dataclass用 before/after 代码片段展示 API 变更而非罗列每个改动的文件保持简洁能用散文就不用冗长列表强调用户影响而非实现细节。明确不写的内容实现细节、测试覆盖说明、逐行变更清单、构建/lint/覆盖率状态、commit 哈希——这些分别由代码注释、CI 和 diff 承担。仓库 .github/PULL_REQUEST_TEMPLATE.md 提供了结构化的模板Description、Related Issues、Documentation PR、Type of Change、Testing、Checklist而 strands-ts/AGENTS.md 明确要求创建 PR 时必须遵循 team/PR.md 的指导并使用该模板。七、与仓库其他协作规范的衔接API Bar-Raising 并不是孤立的它与仓库中其他团队规范共同构成完整的开发流程team/TENETS.md评审判定的价值基准六个信条简单可扩展、可扩展设计、可组合性、显而易见即正确路径、对人与 Agent 都可访问、拥抱通用标准是 API 决策的最终仲裁依据team/DECISIONS.md历史决策的沉淀库评审结论以决策记录形式归档并回灌未来评审team/PR.mdPR 描述的写作标准为 bar-raising 提供评审所需的上下文材料.github/PULL_REQUEST_TEMPLATE.mdPR 的结构化起点。总结API Bar-Raising 把高质量 API 设计从口号变成了可执行、可跟踪、可由 CI 强制执行的工程流程按变更规模分级投入评审资源、用标签驱动合并门禁、把评审结论沉淀为决策记录并以 PR 规范保证评审材料的高质量供给。对于正在为 harness-sdk 贡献新功能的开发者遵循这套流程既能提升 API 的客户体验也能显著降低后续演进与破坏性变更的成本。赞分享人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载相关推荐NSwag代码生成质量门禁5个关键设置确保API客户端质量NSwag代码生成质量门禁5个关键设置确保API客户端质量 NSwag是一个强大的.NET平台OpenAPI工具链能够从ASP.NET Web API控制器开发工具代码生成API设计GetQzonehistoryQQ空间说说导出把历史动态存成本地档案GetQzonehistoryQQ空间说说导出把历史动态存成本地档案 上周帮朋友翻 QQ 空间发现大三那条说说的图片链接已经全 404 了文字还在图没网页爬虫数据分析5分钟搭建LightX2V视频生成环境告别复杂配置的终极指南5分钟搭建LightX2V视频生成环境告别复杂配置的终极指南 还在为视频生成框架的环境配置而头疼吗面对繁杂的依赖项和版本冲突很多开发者和AI爱好者望而却步人工智能大模型媒体生成推理引擎模型推理服务计算机视觉上一篇【亲测免费】 PHP 人脸检测项目教程下一篇Hyperfox 项目教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考