Strands Agents 仓库级 Agent 协作开发指南：从 Monorepo 布局到跨 SDK 工程规范

人工智能大模型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点击查看免费下载导读本篇技术指南以仓库根目录的 AGENTS.md 为主体系统讲解 Strands Agents 单仓库monorepo为 AI 编程助手Agent设计的一整套协作开发规范从仓库布局与为什么文档体系到认知复杂度度量、跨 SDKPython 与 TypeScript一致性约定、测试红线、PR 全流程与社区协作姿态。读完本文你将理解这个双语言 Agent SDK 仓库如何让编写代码、开 PR、协助贡献者三类不同目标的 Agent 在同一个仓库内高效、低冲突地并行工作并能直接照着这些规范在仓库内定位源码、运行检查命令与参与贡献。一、Monorepo 布局进入仓库先定位自己AGENTS.md 开篇即给出明确的定位策略这是一份按任务组织的共享指南同一文件被不同目标的 Agent写代码、开 PR、协助贡献者共用因此第一步永远是确定你所在的子项目并遵循该子项目自己的AGENTS.md。仓库顶层结构如下strands-agents/ ├── strands-py/ # Python SDKhatch 管理— 见 strands-py/AGENTS.md ├── strands-ts/ # TypeScript SDKnpm workspace— 见 strands-ts/AGENTS.md ├── site/ # 文档站点Astro— 见 site/AGENTS.md ├── team/ # 治理 跨 SDK 流程tenets、decisions、API bar、PR 与兼容性指南、designs/ 提案 ├── test-infra/ # 需要预置 AWS 基础设施的集成测试 CDK 栈 ├── .agents/ # Agent 技能skills与参考资料references ├── package.json # npm workspace 根 └── .github/workflows/ # CIci.yml 是合并门禁对应的生产代码分布可以从根 README.md 一览strands-py/是 Python SDKagent loop、模型提供商、工具strands-ts/是 TypeScript SDKharness-py/与harness-ts/是通过create_harness()/createHarness()一行组装出完整 Agent 的 harness 包strands-cli/是终端里的strandsCLIsite/是文档站点源码。子项目的代码结构在各自的AGENTS.md中另有详解例如 strands-py/AGENTS.md 给出src/strands/下agent/、models/、tools/、multiagent/、session/、telemetry/等子系统目录strands-ts/AGENTS.md 则对应src/下的agent/、models/、conversation-manager/、hooks/等目录。两个 SDK 的单元测试布局也遵循各自惯例Python 在tests/下严格镜像src/strands/结构TypeScript 则将测试与源码同目录放置于src/**/__tests__/。二、为什么沉淀在 team/动手设计前先读决策文档AGENTS.md 强调在设计新功能或改动 API 之前应先阅读team/下的相关上下文。代码本身不记录为什么team/才是推理过程的载体team/designs/—— RFC 风格的重要功能提案编号为NNNN-*.md是架构上下文最丰富的来源包含问题框定、方案选择、备选方案与后果分析。要动某个大型子系统先找它的设计文档team/DECISIONS.md—— 较轻量的架构决策记录ADR用于小规模决策team/TENETS.md—— 贡献应遵循的原则team/API_BAR_RAISING.md与team/FEATURE_LIFECYCLE.md—— API 变更的准入门槛与功能弃用的流程。这一设计与仓库实际的团队目录一一对应team/下确实存放着从 0001-plugins.md、0005-state-machine.md 到 0018-shared-agent-model-types.md 等 18 份编号提案以及 DECISIONS.md、TENETS.md、API_BAR_RAISING.md、FEATURE_LIFECYCLE.md 等流程文档。从源码结构看这套先读决策文档再动手的约定是仓库维持双语言一致演进的关键治理机制。三、写代码复杂度标签、分支与提交规范3.1 认知复杂度每个 PR 都要贴标签AGENTS.md 规定每个 PR 都必须以其触及的最复杂函数的认知复杂度cognitive complexity打上标签并且嵌套nesting是驱动分数的关键因素。具体要求写平的控制流——守卫子句guard clauses、提取辅助函数、用查找表替代分支阶梯——并把重构单独放进自己的 PR。分数的分级与本地检查命令在根 package.json 与 team/COMPLEXITY.md 中均有落地分级阈值complexity/low≤ 10、complexity/medium11–25、complexity/high 25。两个 SDK 的函数复杂度中位数在 1–2 分low覆盖约九成现有函数计分规则线性流程的每次打断记 1 分if、else、循环、catch/except、三元表达式、switch/match、递归、混用布尔运算符的每一段嵌套会放大代价——每层嵌套再各记 1 分函数顶层的一个if是 1 分三层嵌套就是 4 分贴标签的公平性标签基于你的 diff只针对实际触动的函数计算相对于合并基线merge base分数没有增加的函数不计入所以给一个本就复杂的函数穿线式地加小改动会落在complexity/low而加深该函数则按全额计分——这再次鼓励提取而非加深本地预检命令npm run complexity仓库根或hatch run complexitystrands-py/内。从 .github/scripts/pr-metrics/run-analysis.mjs 的实现看它由 CI 调用同一个入口因此本地看到的标签与 CI 打出的完全一致脚本通过git diff --numstat -z计算改动文件、用merge-base取基线、Python 侧用 complexipy 输出 SARIF、TypeScript 侧加载专用分析引擎且全程只解析不执行源码对不受信任的 PR 也安全。标签是建议性的从不阻塞合并——协议事件转换器、状态机等领域本身就有这么多分支的代码落在high是诚实的在 PR 描述里说明一句即可。3.2 分支、提交与合并门禁分支命名git checkout -b agent-tasks/{ISSUE_NUMBER}提交规范使用 conventional commits ——feat:、fix:、refactor:、docs:等CIci.yml合并门禁会检测改动了哪些路径只运行相关的检查这与.agents/skills/pre-push技能的按区域运行检查逻辑一致Skills仓库级可复用工作流.agents/skills/下按域组织——PR 流程pr-create、pr-writer、pr-feedback、文档docs-writer、docs-reviewer、docs-audit、docs-planner、代码评审strands-review与本地预检pre-push各技能用途详见 .agents/skills/README.md。新增技能时在.agents/skills/skill-name/下建目录至少包含带 frontmatter 与指令的SKILL.md技能命名遵循{domain}-{action}且涉及不可靠 CLI 的工作流应打包已测试过的脚本而非内联命令sourceLinks追踪源文件site/下的文档页面通过 frontmatter 中的sourceLinks指向其实现源码仓库相对路径指向strands-py/与strands-ts/。重命名或移动源文件时必须在同一改动里更新所有引用旧路径的sourceLinks——站点构建只会在路径格式错误或扩展名无法映射时失败不会因路径指向已不存在的文件而失败过时引用会静默腐烂可用grep -rn old/path site/src/content/docs查找受影响页面。四、跨 SDK 约定让两套实现永不漂移AGENTS.md 明确这些规则同时适用于 Python 与 TypeScript 两个 SDK各子指南strands-py/AGENTS.md、strands-ts/AGENTS.md只展示语言惯用形态共享意图集中在根文档避免两者漂移。两个 SDK 追求的是概念与名称的对等parity而非逐行相同的代码。4.1 命名按做什么命名构造而不是按接口命名构造construct按功能命名AgentSkills、ContextOffloader、GoalLoop——绝不用…Plugin后缀。Python 的vended_plugins/与 TS 的vended-plugins/目录已经遵循此规则目录命名用语言惯用分隔符但词干逐词对应、可机械互转vended_plugins/↔vended-plugins/、conversation_manager/↔conversation-manager/。4.2 奇偶性parity标识符、字面量与 wire 字段标识符逐一对应按语言惯用重新转大小写snake_case↔camelCase单词型字符串字面量值字节级一致user、success多词字符串字面量值Python 用snake_case、TypeScript 用camelCasetool_use↔toolUse必须通过显式映射转换绝不直接输出另一种语言的写法TS 侧由STOP_REASON_MAP/snakeToCamel承载见 strands-ts/AGENTS.mdwire 字段名与模型提供商 API 交换的键在两个 SDK 中保持 wire 格式即使违反语言的大小写惯例如inputSchema、tool_use_id钩子hook事件名跨 SDK 共享除后缀约定外在一个 SDK 新增 hook 事件时另一个也要加上同名事件。Python 侧的事件命名规则Event后缀、Before{Action}Event/After{Action}Event配对、每个Before都有逆注册顺序调用的After见 strands-py/AGENTS.md 与 strands-py/docs/HOOKS.md。4.3 公共 API 与内部 API 的标记Python内部符号不进__all__且模块应以_前缀命名公共包在__init__.py中声明显式__all__可选或重量级模型提供商通过模块级__getattr__懒加载避免导入包时拉入每个提供商的第三方依赖见 strands-py/AGENTS.mdTypeScript内部符号不放进index.ts桶文件barrel并打internalTSDoc 标签——TS 没有_前缀文件名的惯例CancelledError在index.ts中的有意省略注释即是范例仅使用命名导出仓库内零个export default见 strands-ts/AGENTS.md。4.4 结构化日志格式统一格式为fieldvalue, fieldvalue | 小写人类可读消息不加标点多条语句用管道符分隔Python用%s插值禁用 f-string由 ruffG规则强制这样在日志级别关闭时跳过插值开销logger.debug(user_id%s, action%s | user performed action, user_id, action)TypeScript用模板字符串禁用 printf 风格%s/%dlogger.warn(\stop_reason${stopReason}, fallback${fallback} | unknown stop reason, converting to camelCase)。此外 Python 侧还区分warnings.warn与logger.warning的受众按受众而非严重级别选择warnings.warn(...)面向开发者——配置字段被忽略/无效、参数被弃用等SDK 被如何使用的提示需显式传stacklevel指向调用方参考 models/_validation.py 中validate_config_keys的stacklevel4logger.warning(...)面向运维诊断——运行期出错MCP 服务器启动失败、工具加载失败、存储写入失败供日志聚合使用。4.5 常青注释evergreen comments注释只陈述无法从代码推断的内容约束、不变量、非显而易见的为什么并保持简短向评审者解释或辩护改动的推理属于 PR 描述不属于源码。禁止叙述代码如何变化或过去是什么样improved、previously、used to、which would previously have crashed。这条同样适用于测试为已发现 bug 写的回归测试要链接其防护的问题并说明保证的行为作为功能开发一部分写的测试不携带 issue 引用。deprecated/legacy 在描述稳定的 API 表面或运行期状态时是允许的仅在叙述代码自身如何变化时被禁止。4.6 语言惯用的其他关键规范两个子指南还给出了各自语言内 lint 无法覆盖的约定可作为写代码时的检查清单Pythonstrands-py/AGENTS.md可选类型一律写 PEP 604 联合X | None禁用Optional[X]类型抑制必须带代码# type: ignore[code]裸 ignore 在warn_unused_ignores下会自我清理数据结构按角色选型——wire/消息/配置形状用TypedDicttotalFalseRequired/NotRequired拥有行为/默认值/序列化助手的运行时对象用dataclass只有模型读写的 schema 才用 pydanticBaseModel公共函数抛错作为契约的一部分时必须写Raises:段错误处理抛具体类型并用from链上原因模型提供商要把厂商错误翻译成 SDK 类型化异常如ContextWindowOverflowException、ModelThrottledException可扩展接口用带**kwargs的Protocol而非Callable工具引用用tool.tool_name属性而非硬编码字符串。TypeScriptstrands-ts/AGENTS.md对象形状用interface组合用extendstype别名只用于联合/交叉/函数/映射类型exactOptionalPropertyTypes下优先写裸prop?: T函数签名必须有显式返回类型但局部变量交由推断供应商错误翻译成类型化错误并保留{ cause }导出的可抛错函数/方法用throws标注example只保留给入口类如BedrockModel、Agent不给类型定义依赖若跨 API 边界则必须是peerDependencies。五、测试子项目指引 test-infra 红线写测试时遵循各子项目的测试文档——Python SDK 看 strands-py/docs/TESTING.mdTypeScript SDK 看 strands-ts/docs/TESTING.md。两个子指南进一步细化Python 单元测试在tests/严格镜像src/strands/结构、用tests/fixtures/的共享夹具、每个 async 测试标注pytest.mark.asyncioTS 测试与源码同目录src/**/__tests__/、遵循嵌套describe模式与批量策略。test-infra/的红线必须牢记。test-infra/的 CDK 栈会部署真实的 AWS 资源Bedrock 知识库、EC2 实例只有一小部分集成测试依赖它绝大多数测试不需要预置基础设施即可运行除非你在专门维护测试基础设施本身或迭代从该栈解析 SSM 参数的测试否则不要部署这个栈绝不在非内部账号设置STRANDS_TEST_INFRA_INTERNALtrue——它附加了宽泛的内部策略与 GitHub OIDC 信任在内部账号之外毫无意义且浪费资源要运行依赖基础设施的集成测试而无需部署任何东西直接开 PRCI 会自动对预置资源运行它们。六、创建 PR小而聚焦作者全程负责开 PR 时遵循 team/PR.md并可用.agents/skills/下的pr-create与pr-writer技能起草与提交。若你代表贡献者开 PR人是作者对提交的一切负责——小而聚焦、作者完全理解的改动是快速评审与被接受的最大预测因子。AGENTS.md 列出的关键纪律提交前先理解贡献者必须能解释每一行为何工作、能捍卫设计写不出就能解释的代码先简化再提交保持小而聚焦一个 PR 一个逻辑变更同时触碰多个子项目strands-py/、strands-ts/、site/的分支几乎总是应该拆成多个 PR重要改动先开 issue让维护者在投入时间前对齐方案不灌水不要顺手的重新格式化、无关重构或投机性抽象它们让 diff 难评审、让改动难信任提交前验证运行相关子项目的检查见 CONTRIBUTING.md 的 Development Environment 或子项目自己的AGENTS.md确保改动在本地能通过ci.yml合并门禁绝不在已知 lint/类型/测试失败的情况下开 PR真正演练改动而不只依赖门禁自动化检查确认代码有效不代表功能可用。端到端跑一遍行为手写脚本、REPL 片段、CLI 或示例确认它做到了 PR 声称的事含边界情况若无法演练如需要预置基础设施就在 PR 里明说而不是暗示已测试对评审有帮助时附上你运行的脚本或命令以评审者视角通读 diff 做自审并诚实勾选 PR 模板中的每一项——包括已评审并理解 PR 中每一行代码含 AI 生成的代码那一项然后用pr-writer技能让描述讲清为什么。从 .agents/skills/README.md 看这套流程已被技能化pr-writer按 Conventional Commits、PR 模板与team/PR.md生成标题与描述并从对话中捕获设计决策pr-create编排完整流程描述生成、CONTRIBUTING.md 预检、条件式 push、gh pr create --draft预防非 draft PR不兼容 flag等 Agent 常见错误pr-feedback通过打包脚本用 GitHub GraphQL 拉取所有未解决评论用反应数据与作者回复区分同意修复与开放讨论。七、评审文档改动需要专用技能当改动涉及site/下的文档时除标准代码评审外还要应用.agents/skills/中的文档技能.agents/skills/docs-reviewer/SKILL.md—— 检查语气一致性、结构、术语与代码示例质量.agents/skills/docs-audit/SKILL.md—— 对照实时 SDK 源码核对技术准确性导入路径、方法签名、API 正确性。评审前必须对照 .agents/references/terminology.md 核对术语、对照 .agents/references/mdx-authoring.md 核对 MDX 写作模式。AGENTS.md 特别强调必须真正阅读这些被引用的源文件再评审——只浏览摘要它们的标准就不适用。八、与社区协作是向导不是守门人协助他人贡献时你是向导——不是守门人也不是代笔人。贡献属于贡献者本人帮助它变好、让贡献者学到东西才是目标。好贡献的标准见 CONTRIBUTING.md而这一节是关于人的把真实问题引向社区真正的疑问与设计讨论属于人——Discord 与 GitHub Discussions假定善意大多数贡献者都在学习要接住他们当前的水平good first issues 是带新人进来的入口不只是要关闭的工单与贡献者对话而非说教温暖、平实、简洁一次只问一个问题不长篇大论绝不居高临下解释为什么让解释成为教学而非命令。总结从根 AGENTS.md 出发的协作闭环纵观全文根 AGENTS.md 构建了一个完整闭环进入仓库先按子项目定位 → 动手前先读team/决策文档 → 写代码时以认知复杂度标签为量化纪律、以跨 SDK 奇偶性约定防止双语言漂移 → 测试时严守test-infra/红线 → 开 PR 时坚持小而聚焦、以pr-create/pr-writer等技能辅助 → 评审文档改动时调用专用技能 → 面向社区时保持向导姿态。这套规范不只是给人看的更是为 AI Agent 设计的可执行契约——配合.agents/skills/下的技能化工作流与npm run complexity、hatch run complexity等可本地复现的检查命令任何 Agent 都能在进入仓库后快速对齐预期、产出高质量且可被快速评审的改动。对希望深入参与 Strands Agents 双语言 SDK 开发的工程师与 Agent 而言AGENTS.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点击查看免费下载相关推荐VoltAgent 仓库开发指南从 AI Agent 协作规范到 Monorepo 验证工作流VoltAgent 仓库开发指南从 AI Agent 协作规范到 Monorepo 验证工作流 VoltAgent 是一个开源的 TypeScript AI人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Composio 仓库导航指南SDK Monorepo 布局、分支工作流与 Agent Skills 维护规范Composio 仓库导航指南SDK Monorepo 布局、分支工作流与 Agent Skills 维护规范 本指南围绕 Composio SDK 仓库内的人工智能AI Agent工具调用MCP 服务MCP Clientsdoocs/md 仓库开发指南从 Monorepo 结构到 Agent 协作规范的完整解读doocs/md 仓库开发指南从 Monorepo 结构到 Agent 协作规范的完整解读 导读 本文以 doocs/md微信 Markdown 编辑器仓前端AI 应用上一篇garak 接入 AWS BedrockBedrockGenerator 使用指南与 Converse API 实现解析下一篇3大核心技术突破深度解析Wand-Enhancer的逆向工程与本地化增强架构创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考