人工智能大模型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点击查看免费下载导读本文围绕 Strands Agents 开源仓库team/designs/目录下的设计文档体系展开系统讲解设计文档Design Document的定义、触发时机、提交流程、标准模板与写作规范并逐一拆解仓库中已沉淀的 0001–0017 号设计文档及其与 DECISIONS.md 轻量决策记录的配合关系。读完本文你将掌握如何在 Strands AgentsPython/TypeScript 双语言 SDK仓库中提交一份高质量、可评审、可追溯的架构设计提案并理解插件Plugin、干预Intervention、上下文管理Context Management、长时记忆Memory Manager等核心机制背后的设计决策脉络。设计文档是什么把为什么写进项目历史team/designs/README.md开宗明义设计文档Design Document用于记录对 Strands Agents 有重大意义的功能与变更捕获问题problem、提案proposal、被权衡过的备选方案alternatives以及架构选择带来的后果consequences。一旦设计获批并合入它就成为项目的正式设计与决策历史的一部分。与设计文档互补的是 DECISIONS.md——一份轻量级架构决策记录ADR按时间线记录我们做了什么决定、为什么。两者分工明确设计文档面向重大功能篇幅长包含完整的问题陈述、方案对比与后果分析决策记录面向轻量决策通常是一段Decision Rationale如仓库中记录的Hooks as Low-Level Primitives、Pay for Play: Opt-In Breaking Changes Are Acceptable、Null Means Explicit Removal; Undefined Means Apply the Default等。从仓库实际内容看这一分工运转良好重大功能走设计文档如 0001-plugins.md 的插件机制、0007-intervention-primitive.md 的干预原语而 API 命名、单元选择这类粒度适中的决策直接沉淀进 DECISIONS.md。何时需要写设计文档触发条件与边界README 给出了明确的判定标准。满足以下任一条件就应当走设计文档流程影响 SDK 多个部分的新主要功能如插件体系、干预原语、上下文管理大项现有 API 的破坏性变更breaking changes需要设计讨论的架构级变更工作量超过一周的大型贡献引入全新概念的功能。反过来以下场景跳过设计流程bug 修复、小改进、文档更新以及在自己仓库中的新增扩展。这一边界的本质是设计文档的成本编写 评审 迭代应当花在影响面大、不可轻易回退的决策上。仓库实例哪些功能走了设计文档对照team/designs/目录可以清楚看到这套判定标准在实践中的落地设计文档对应主题触发的判定理由0001-plugins.mdPlugin 插件原语替代 HookProvider 抽象引入全新概念、影响 SDK 多个部分0003-context-management.md上下文管理战略路线图架构级变更跨多个 track 的重大功能0007-intervention-primitive.mdIntervention 干预原语Proceed/Deny/Guide/Interrupt/Transform新主要功能 新概念0008-proactive-context-compression.md主动上下文压缩threshold 触发新功能影响 ConversationManager 基类0011-memory-manager.md跨会话长时记忆 MemoryManager新主要功能 新概念0015-bidi-webrtc-design.md双向 WebRTC 设计架构级变更这些文档全部遵循 README 中的统一模板形成了一致的决策历史档案。如何提交功能提案从分支到合入的七步流程README 给出了标准提交流程结合仓库协作惯例可细化为对照路线图先在项目路线图中确认想法与方向一致创建分支在本仓库中基于主干创建独立分支编写设计文档按模板新建文件命名遵循designs/NNNN-feature-name.md四位序号 功能名如0001-plugins.md提交 Pull Request发起 PR 进入评审讨论根据反馈迭代回应评审意见修改设计获得批准获批并合入后设计即成为项目决策历史的一部分实现时引用设计在实现 PR 中链接对应的设计文档保证设计 → 实现全程可追溯。值得注意的细节模板中**Status**: Proposed | Accepted | Deprecated | Superseded这一状态字段贯穿文档生命周期。仓库中 0008-proactive-context-compression.md 和 0011-memory-manager.md 均标注Proposed并附Date与关联Issue编号而 README 末尾的Accepted Designs一节目前仍标注暂无已接受设计——说明这批设计文档正处于提案待实现或实现中的状态读者在引用时应以其状态字段为准。设计文档标准模板逐节拆解README 提供的模板是仓库所有设计文档的统一骨架共十个部分。逐节拆解如下并给出对应仓库实例的写法示范。头部元信息Status / Date / Issue模板要求文档开头标注状态、日期与关联 Issue。仓库实例的写法**Status**: Proposed **Date**: 2026-04-08 **Issue**: #555: Proactive Context Compression0008-proactive-context-compression.md 还在头部补充了Dependencies如 #1295 Context Limit Property on Model与Related关联项帮助评审者快速理解提案在 issue 网络中的位置。Problem为什么需要这个变更模板要求用几句话说明动机并给出三个标准问题要完成什么任务今天为什么困难或不可能谁在承受这个问题0007-intervention-primitive.md 是优秀的示范——它列举了四个具体痛点无短路no short-circuiting、碎片化的动作模型、缺乏统一审计、排序与冲突解决未定义并用代码对比展示了插件直接改写事件与干预处理器返回类型化决策的本质差异// Plugin: mutates the event directly beforeToolCall(event: BeforeToolCallEvent): void { if (!this.isAuthorized(event)) { event.cancelTool Access denied // deny? guide? interrupt? framework cant tell } } // Intervention handler: returns a typed decision, framework applies it async beforeToolCall(event: BeforeToolCallEvent): PromiseInterventionAction { if (!this.isAuthorized(event)) { return new Deny(User not authorized for this tool) } }Current State先让读者理解现状有多痛模板要求展示现在到底难在哪里用现有 API、流程或 workaround 说明问题尽量给出具体例子、报错信息或数字。这一点在 0003-context-management.md 中体现得淋漓尽致文档详细分析了会话上下文的三大挑战无智能填充与移除、滑动窗口丢消息、摘要逐轮丢失细节和工具上下文的两个挑战全量工具定义常驻、超大工具结果导致不可恢复的溢出循环并指出Strands 目前对动态过滤工具或管理结果大小没有一等支持用户必须自行解决。Goals好的方案必须做到什么Goals 一节定义用户成果、未来机会、方案约束。0003-context-management.md 进一步将设计原则提炼为四条值得所有设计文档借鉴Paved paths over escape hatches铺好主路而非只留逃生舱用户频繁用插件实现同一目标说明该抽象应升级为一等接口Autonomy over configuration代理应在运行中动态自适应而非仅启动时配置固定Research-backed基于数据而非猜测Provider Agnostic核心策略跨模型提供商通用。Key Decisions历史决策、假设与备选模板要求列出四类关键问题过去有哪些相关决策提案包含哪些假设/不变量/风险哪些备选被放弃及原因哪些需要评审会对齐仓库中 0001-plugins.md 完美示范了这一节——它在为什么不是 HookProviders附录中给出明确定义Plugin 是 SDK 的高层抽象通过修改代理核心属性来改变行为Hooks 是 SDK 的低层原语在特定生命周期事件执行代码。两者职责重叠导致用户困惑因此提案将HookProvider弃用并重命名为Plugin同时明确不弃用 hooks 这一低层原语。这一决策后来在 DECISIONS.md 的Hooks as Low-Level Primitives, Not High-Level Abstractions条目中得到呼应——高层构造应建立在 hooks 之上而不是把HookProvider作为唯一开发者界面。Proposal把备选方案摆上桌面模板的核心要求是把各选项放在同等地位上列出利弊推荐项排第一让读者看到选择是靠权衡做出的而不是靠断言。每个选项标注 Pros/Cons若确实没有真正的备选设计空间狭窄或一种方案明显占优用一句话说明而不是编造稻草人但仍要讲清推荐项自身的取舍。0008-proactive-context-compression.md 示范了 Alternatives Considered 的写法它对比了做成独立 Plugin与放进 ConversationManager 基类两个方案最终选择后者理由是 ConversationManager 已是上下文管理的既定原语、用户会去那里找解决方案且插件方案需要暴露额外的公共 API 面。同时给出了备选方案仅用 tokenizer 做估算被否决的原因网络依赖在隔离 VPC 环境会挂起且估算只作用于增量消息。Developer Experience开发者的第一视角模板要求展示推荐方案下开发者体验典型用法代码、所需配置、报错与边界情况。0011-memory-manager.md 给出从原型到生产的完整 DX 梯度// 最小原型零基础设施 const agent new Agent({ model, memoryManager: new MemoryManager({ stores: [new InMemoryMemoryStore({ name: notes })], storeToolConfig: true, }), }) // Agent 现在拥有 search_memory 和 store_memory 工具 // 生产Bedrock Knowledge Bases const agent new Agent({ model, memoryManager: new MemoryManager({ stores: [new BedrockKnowledgeBaseStore({ name: personal, knowledgeBaseId: KB123, dataSourceId: DS456 })], storeToolConfig: true, }), })这种从原型到生产只改一个 import的渐进式复杂度设计正是 README 模板中 DX 一节的精髓。Consequences变更的后果与迁移模板要求说明变更后什么变得更容易 / 更困难。仓库设计文档普遍包含三个子节What Becomes Easier、What Becomes Harder or Requires Attention、Migration。0008-proactive-context-compression.md 的 Consequences 写得极具实操价值更容易的包括长会话不再意外溢出、工具密集型工作流自动获得 loop 内压缩需要留意的包括用户需在模型配置中显式设置contextWindowLimit在按提供商默认表上线之前、自定义 ConversationManager 必须实现reduceOnThreshold()才能启用主动压缩迁移结论为无破坏性变更。Willingness to Implement是否愿意亲自实现模板的最后一项是Yes / No / Maybe with guidance用于评审时确认提案人是否有意愿与资源落地。仓库中 0008-proactive-context-compression.md 与 0011-memory-manager.md 均明确标注Yes为评审决策提供了关键信号。写作规范三条让评审更顺畅的习惯README 的Writing the document一节给出三条核心写作纪律这也是评审体验的关键Earn the code先挣得展示代码的权利在读者理解问题之前不要展示 API、片段或接口。必须按 Problem → Current State → Goals 的顺序推进让第一个代码片段出现在 Proposal 时读者已经知道它为什么必须存在。否则代码读起来像对未陈述问题的解决方案评审者只能从语法反推你的意图。Lead with the rubric, not the verdict先给标准再给结论在提案之前先陈述目标与约束让选择读起来是推理得出的而非断言得出的。Weigh options honestly诚实权衡选项把备选方案放在同等地位上列出真实利弊推荐项排第一让推荐靠权衡赢得而不是靠稻草人撑腰。没有真正的备选时直说不要发明一个。这三条纪律在仓库设计文档中一以贯之。例如 0007-intervention-primitive.md 在提出干预原语前先用整整一节Problem建立多个独立控制层没有共享接口的痛点再在附录 CWhy Not Just Hooks?中诚实承认vanilla hooks 今天就能实现这一切但论证了短路由、区分 deny/guide、有序求值、统一审计这四段样板代码值得框架吸收——这正是先给标准再给结论与诚实权衡的教科书式示范。从设计到代码设计文档如何在仓库中落地设计文档不是纸上谈兵team/designs/中的核心概念在strands-py/、strands-ts/等 SDK 源码中均有对应实现。以下通过源码路径验证几个关键设计Plugin从协议到实现0001-plugins.md 提议的Plugin概念已在 Python SDK 中落地为抽象基类 plugin.py每个插件必须提供稳定的name标识abstractmethod def name__init__中自动发现hook与tool装饰的方法discover_hooks/discover_tools分别存入_hooks与_tools通过init_agent(agent)钩子完成代理实例的自定义初始化。0001-plugins.md 中预言的hook装饰器简化写法也已落地为 decorator.py——装饰器从回调的类型注解中推断事件类型infer_event_types支持联合类型绑定多个事件且可写作hook或hook()两种形式from strands.plugins import Plugin, hook from strands.hooks import BeforeModelCallEvent class MyPlugin(Plugin): name my-plugin hook def on_model_call(self, event: BeforeModelCallEvent): print(fModel called: {event})这正是设计文档Simple hook callback authoring一节所追求的 DX——用装饰器包裹一个函数即可作为插件传入Agent(plugins[...])。Intervention从提案到双语言原语0007-intervention-primitive.md 提议的干预原语已在 Python SDK 落地为 handler.py 与registry.pyInterventionHandler基类为每个生命周期事件提供默认 no-op 实现before_invocation、before_tool_call、after_tool_call、before_model_call、after_model_call默认返回Proceed()——与设计文档框架检测哪些方法被覆写、只调用这些方法的决策完全一致生命周期方法支持同步或async两种写法_MaybeAwaitable类型别名异步处理器可以在决定前等待 I/O数据库查询、HTTP 授权调用、人工审批提示on_error属性提供throw | proceed | deny三档异常策略其中proceed为 fail-open、deny为 fail-closed文档注释明确警告了各自的安全含义。设计文档中的动作模型Proceed / Deny / Guide / Interrupt / Transform对应实现为actions.py中的Proceed、Deny、Guide、Confirm、Transform等类型化动作且 handler.py 中before_tool_call的返回签名还包含了设计文档未显式列出的Confirm——说明实现相对设计在评审后进一步演化。高层特性插件体系的真实用户设计文档中的概念被 SDK 高层特性直接消费。Python SDK 的 memory.py 中class MemoryManager(Plugin)——长时记忆管理器本身就是 0011-memory-manager.md 所设计的插件通过注册工具、注入上下文、提取事实融入代理生命周期。代理初始化参数plugins[...]、interventions[...]与memoryManager也都在 agent.py 的导入与类型声明中可见from ..plugins import Plugin、from ..interventions.handler import InterventionHandler、from ..memory import MemoryManager。这一设计文档 → 抽象基类 → 高层特性复用的链条完整展示了设计文档体系如何在仓库中从提案演变为可运行代码。设计文档与团队规范的衔接设计文档体系并非孤立存在它与team/目录下的其他治理文档共同构成完整决策框架TENETS.md 定义了六条开发信条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。设计文档中的许多取舍都以这些信条为论证依据——例如 0001-plugins.md 引用 The obvious path is the happy path 论证为何弃用命名模糊的HookProvider。DECISIONS.md 记录轻量决策与设计文档互为补充。例如Provide Both Low-Level and High-Level APIs决策直接指导了 0011-memory-manager.md 中一等memoryManager参数 底层可编程search/store方法的双层 API 设计When Internal Interfaces Should Extend HookProvider决策则给出了单职责接口用简单接口、多生命周期事件用 HookProvider的选择标准。AGENTS.md、AGENT_GUIDELINES.md 与 PR.md 则从协作流程层面保障设计评审的质量——AGENT_GUIDELINES 中Approvals Need Reasoning要求不批准时必须明确理由这与设计文档备选方案诚实权衡的写作纪律一脉相承。结语Strands Agents 的设计文档体系是一个问题驱动、模板约束、源码闭环的完整决策机制README 定义了何时写、怎么写、如何提交模板保证了每个提案都覆盖问题、现状、目标、关键决策、方案权衡、DX、后果与实现意愿team/designs/下 17 份真实文档展示了该机制在插件、干预、上下文管理、长时记忆等核心机制上的实际产出而strands-py/与strands-ts/的源码则证明这些设计最终都沉淀为了可运行的 SDK 能力。对希望为 Strands Agents 贡献架构级功能的开发者而言从designs/NNNN-feature-name.md命名一份提案开始遵循本文梳理的流程与规范即是最贴近项目治理惯例的参与路径。赞分享人工智能大模型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点击查看免费下载相关推荐Podman 设计文档体系从提案到落地的功能变更管理指南Podman 设计文档体系从提案到落地的功能变更管理指南 设计文档Design Document是 Podman 社区用于规划重大功能、在动手实现前达成维容器运行时云原生CLIbravado单元测试指南用BravadoResponseMock模拟响应让测试告别真实网络请求bravado单元测试指南用BravadoResponseMock模拟响应让测试告别真实网络请求 Bravado 是一个用于 Swagger / OpenA人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务Neon 技术设计 RFC 体系从提议模板到源码落地全指南Neon 技术设计 RFC 体系从提议模板到源码落地全指南 Neon 是一个 Serverless Postgres 实现其核心架构计算与存储分离、pag数据库后端分布式数据库云原生上一篇KeyDB中的流数据结构stream.h实现分析下一篇React Native Firebase 静默推送终极指南如何在后台智能更新应用数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考