harness-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/references/code-verification.md 整理面向在 harness-sdk 文档站点site/下编写、审计或评审文档的开发者与 AI 技能skill作者。文档中凡涉及 SDK 代码示例都必须与实际源码逐一核对——看似合理但实际错误的代码比缺失文档更快摧毁开发者信任。读完本文你将掌握本地克隆优先、GitHub API 兜底、安装包内省抽查、无法验证即上报的四层校验梯队以及如何在docs-audit、docs-writer等技能流程中正确上报无法验证的代码块。背景为什么文档代码需要一道独立验证规程harness-sdk 是一个同时提供 Pythonstrands-py/与 TypeScriptstrands-ts/双语言 SDK 的开源仓库其文档站点位于 site/基于 Astro Starlight 构建详见 site/SITE-ARCHITECTURE.md。站点中既有手工编写的 MDX 指南也有从 SDK 源码自动生成的 API 参考页src/content/docs/api/python/_generated与src/content/docs/api/typescript/_generated均为指向.build/api-docs/的符号链接。这种手写 生成混合的内容结构意味着任何一处手写代码示例都必须与真实 SDK 源码保持一致否则生成页与手写页之间就会出现口径冲突。为此仓库在 .agents/references/code-verification.md 中沉淀了一套四层验证梯队Tier 1–4优先使用最快的本地克隆Tier 1依次降级到 GitHub APITier 2、已安装包内省Tier 3最后是停止并上报Tier 4。原则是能用的最高层优先绝不跳过验证步骤直接发布未经验证的代码。需要特别说明的是本规程中所有路径包括引用本规程的技能流程均以仓库根目录为基准规程提到的npm run sdk:clone需要在site/目录下执行package.json所在位置。在当前的仓库布局中SDK 源码已就地存在Python 位于 strands-py/src/strands/TypeScript 位于 strands-ts/src/因此下文会同时给出克隆布局与当前仓库实际路径两套定位方式。Tier 1本地 SDK 克隆首选克隆目录与数据来源当环境中存在npm run sdk:clone填充的本地克隆时直接从磁盘读取源码这比网络请求更快也完全避开 GitHub API 的速率限制site/.build/sdk-python/src/strands/[path] site/.build/sdk-typescript/strands-ts/src/[path]如果克隆尚不存在就在site/下执行npm run sdk:clone生成或直接降级到 Tier 2。需要留意的是当前仓库中site/package.json的 scripts 实际提供的是sdk:generate:py、sdk:generate:ts、sdk:generate、sdk:sync等对应 site/SITE-ARCHITECTURE.md 中描述的 API 文档生成流程说明克隆与生成步骤随仓库演进会有调整引用时应以当前package.json为准。而在本仓库中验证源码的等价位置是Python SDKstrands-py/src/strands/即克隆布局中site/.build/sdk-python/src/strands/的本地真身TypeScript SDKstrands-ts/src/即克隆布局中site/.build/sdk-typescript/strands-ts/src/的本地真身Python 关键模块速查表规程给出了 Python 侧需要反复核对的模块清单均对应 strands-py/src/strands/ 下的真实路径关注点模块路径核对内容Agent 主类agent/agent.pyAgent类、构造函数签名、__call__/stream_async结果形状agent/agent_result.pyAgentResult最终响应、指标、停止原因会话管理agent/conversation_manager/ConversationManager、SlidingWindowConversationManager、SummarizingConversationManager状态存储agent/state.pyAgentState每个 Agent 的键值存储工具装饰器tools/decorator.pytool装饰器与签名推断工具分组tools/tool_provider.py分组工具的ToolProvider基类MCP 集成tools/mcp/MCP 客户端 / 服务端工具集成结构化输出tools/structured_output/结构化输出工具辅助Hook 注册hooks/registry.pyHookRegistry、Hook 回调注册Hook 事件hooks/events.py事件类型BeforeInvocationEvent、AfterInvocationEvent等模型提供商models/Bedrock、Anthropic、OpenAI 等实现多智能体multiagent/graph.py、multiagent/swarm.py、multiagent/a2a/图、群、智能体间编排会话持久化session/SessionManager、FileSessionManager、S3SessionManager、RepositorySessionManager事件循环event_loop/核心事件循环与流式输出遥测telemetry/追踪、指标、OTEL 集成中断/恢复interrupt.py、types/interrupt.py中断/恢复原语异常types/exceptions.py错误类公共类型types/content.py、types/tools.py、types/streaming.py消息/工具/流式公共形状以tool装饰器为例tools/decorator.py 的模块 docstring 明确说明了它的职责从 docstring 与类型注解提取函数元数据名称、描述、参数、生成用于输入校验的 JSON schema、同时支持普通函数调用func(arg1, arg2)与工具调用agent.my_tool(param1hello, param2123)两种模式、提供错误处理与结果格式化并且同时适用于独立函数和类方法。文中示例from strands import Agent, tool正是文档写作时需要逐项核对的签名形态。TypeScript 关键模块速查表TypeScript 侧对应的模块清单均在 strands-ts/src/ 下关注点模块路径Agent 核心agent/Agent类、agent result、配置工具tools/tool()工厂、工具注册、MCP 工具支持会话管理conversation-manager/ConversationManager实现Hookhooks/Hook 注册表与事件类型模型models/模型提供商实现多智能体multiagent/图、群、agent 间编排会话持久化session/会话管理器与持久化插件plugins/、vended-plugins/插件系统与内置插件干预interventions/、vended-interventions/干预 Hook重试retry/重试策略遥测telemetry/追踪与指标错误errors.ts错误类公共类型types/content、tools、streaming 等导出入口index.ts公共导出的权威入口TypeScript 侧还提供了两个非常有用的用法模式来源strands-ts/test/与strands-ts/src/__tests__/——单元测试天然展示正确调用方式strands-ts/examples/——可运行的示例如first-agent、agents-as-tools、mcp、graph、swarm等子目录见 examples/。Tier 1 需要验证的四个要点无论 Python 还是 TypeScriptTier 1 阶段至少要核对导入路径确实指向真实模块——不能凭记忆写from strands import ...要确认模块文件存在参数名、类型与默认值匹配类定义——对照构造函数/函数签名逐一核对引用的方法确实存在于所示类上——避免看起来应该有的方法双语言页面各自独立验证——同一功能在 Python 与 TypeScript 的 API 形态不同必须分别核对不能由一个语言的结果推断另一个语言。Tier 2GitHub API 兜底当本地克隆不可用时通过 GitHub API 抓取源码下述命令中的[path]需替换为实际模块相对路径# Python SDK当前仓库中位于 strands-py/src/strands/ gh api repos/strands-agents/harness-sdk/contents/strands-py/src/strands/[path] # TypeScript SDK当前仓库中位于 strands-ts/src/ gh api repos/strands-agents/harness-sdk/contents/strands-ts/src/[path]该层适合只差一个文件、临时确认签名的场景但要意识到它受 GitHub API 速率限制约束这也是 Tier 1 优先于它的原因之一。Tier 3已安装包内省抽查当无法访问源码仓库时可以利用本机已安装的 SDK 包进行抽查式验证。该方式适合快速核对参数名与类型但看不到内部模块结构# Python python -c from strands.agent.agent import Agent; help(Agent.__init__) # TypeScript检查导出 node -e const sdk require(strands-agents/sdk); console.log(Object.keys(sdk))其中 Python 侧from strands.agent.agent import Agent的模块路径在 strands-py/src/strands/agent/agent.py 中确有对应实现该模块同时支持自然语言对话agent(Analyze this data)与工具直调agent.tool.tool_name(param1value)两种交互模式node -e console.log(Object.keys(sdk))则与 Tier 1 中index.ts是公共导出权威入口的判断形成呼应——导出的顶层键名就定义在 strands-ts/src/index.ts。Tier 4停止并上报不可验证时的红线如果上述三个层级全部不可用严禁带着未验证的代码继续发布。这里有三条纪律审阅者不是验证步骤——不要指望 PR 审阅环节替代码示例补课未验证的代码块不允许出现在 PR 描述里当作留给别人的 TODO 清单正确的做法是把缺口上报到调用技能skill的输出中交由下一轮技能迭代去解决而不是转嫁给审阅者。具体到两个调用方来自docs-audit把每个无法验证的条目列在### Accuracy Issues下例如Agent.stream_asyncsignature — no SDK source available to verify并在### Recommended Actions中补充一条获取验证来源后再重新审计的对应行动项来自docs-writer从草稿中删掉受影响代码块并在交付成品页时上报该不可验证条目——明确指出涉及的类/方法以及失败在哪一层绝不输出猜测出来的示例。将规程落到仓库实际布局中结合当前仓库可以给出一条开箱即用的验证路径建议供文档编写与审计时参考优先在仓库内直接读源码Python 看 strands-py/src/strands/TypeScript 看 strands-ts/src/这等价于规程 Tier 1 的本地克隆且永远是最新真身需要用法模式时翻测试与示例Python 侧测试在 strands-py/tests/ 与 strands-py/tests_integ/TypeScript 侧在 strands-ts/test/ 与 strands-ts/examples/用真实调用验证文档示例核对 API 参考页与手写页的一致性站点自动生成的 API 页来自 site/scripts/api-generation-python.py 与 site/scripts/api-generation-typescript.ts详见 site/SITE-ARCHITECTURE.md手写 MDX 中的代码示例应与其口径一致四个核对点逐项过导入路径真实、参数名/类型/默认值匹配、方法存在于所展示类上、双语言各自验证验证不了就上报按 Tier 4 的规则在docs-audit/docs-writer输出中明确标注### Accuracy Issues、### Recommended Actions或随页交付说明而不是发布猜测代码。小结代码验证规程的本质是把文档示例与 SDK 源码一致变成一条可执行的工程纪律Tier 1 本地克隆/仓库源码最快最全Tier 2 GitHub API 兜底网络抓取Tier 3 安装包内省适合抽查Tier 4 是任何情况下都不允许发布未验证代码的兜底红线。对文档作者而言这意味着每一次写出Agent、tool、ConversationManager、SessionManager等 API 示例时都要能指出对应的源码文件与签名对技能skill作者而言这意味着把验证缺口的上报作为流程的一等公民而不是留给审阅者的遗留 TODO。将这一规程固化进文档写作流水线才能让 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点击查看免费下载相关推荐InsForge 文档工程规范四层文档体系、防漂移工作流与验证机制InsForge 文档工程规范四层文档体系、防漂移工作流与验证机制 本文面向 InsForge 仓库的维护者与贡献者系统讲解 InsForge 产品文档的工后端前端AI 应用Yuxi 面向读者的文档体系Diátaxis 四类分层、事实 Owner 与可验证证据Yuxi 面向读者的文档体系Diátaxis 四类分层、事实 Owner 与可验证证据 本文是 Yuxi 开源仓库内文档治理决策与写作规范的实践指南。它回答两人工智能大模型AI AgentRAG多智能体知识图谱后端前端AutoRAG Datasource Skills 手动 QA 指南从 Harness 到源码级验证体系AutoRAG Datasource Skills 手动 QA 指南从 Harness 到源码级验证体系 本文围绕仓库中的 docs/manual qa da人工智能AI AgentRAG本地部署CLI上一篇CANN Runtime 托管内存UVM 统一虚拟内存编程实践基于 0_uvm_allocate 样例的深度解析下一篇3分钟快速上手Nucleus Co-op让你在单台电脑上享受本地分屏游戏乐趣创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考