人工智能大模型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 仓库内置的docs-writer 技能位于 .agents/skills/docs-writer/SKILL.md如何在编写、重写文档页面、草拟章节、撰写博客与发布说明时严格遵循五层语音栈five-layer voice stack产出事实准确、可运行、可被搜索引擎与 AI 检索引用的 Strands 文档。读完本文你将掌握 docs-writer 的完整输入约定、七步写作流程、MDX 双语言Python/TypeScript排版规范、代码验证程序与术语锁定机制并了解它与 docs-reviewer、docs-audit、docs-planner 三个配套技能的协作边界。一、技能定位docs-writer 是什么、何时触发docs-writer 是 harness-sdk 仓库.agents/skills/体系下的文档写作技能用于起草或重写 Strands Agents 文档页面。它的 frontmatterdescription定义了明确的触发条件编写新的文档页面重写未通过 audit审计的页面为现有页面草拟新章节撰写关于 Strands 的博客文章与发布说明release notes自然语言触发词包括 write a doc、draft a page、rewrite the quickstart、add a tutorial for X、document this feature技能的总目标是按照五层语音栈起草或重写 Strands Agents 文档。语音栈的完整定义位于 .agents/references/voice-guide.md技能执行的第一步就是加载它配合 .agents/references/terminology.md术语锁定文件一起作为写作基准。在文档技能体系中docs-writer 与另外三个技能形成完整闭环参见 .agents/skills/README.md 中的文档技能表技能定位docs-planner盘点文档缺口、按 P0-P3 优先级排定待办积压SKILL.mddocs-writer按语音栈起草或重写页面本文主角docs-reviewer对草稿做语音、结构、术语审查是 docs-writer 的最后一关SKILL.mddocs-audit对已发布页面做质量与准确性评估产出结构化改进建议SKILL.md一个典型的循环是docs-planner 发现缺口 → docs-writer 起草 → docs-reviewer 把关 → 合并发布 → 定期用 docs-audit 复查。docs-writer 明确不做三件事不经人工审查自动提交、不从代码自动生成参考文档、不发布或部署文档。二、输入约定写之前先明确五类输入docs-writer 需要五类输入其中前三项为必填Content type内容类型必填tutorial、howto、reference、explanation、blog 五选一。内容类型直接决定语气register、结构与约束放宽项见第四节。Topic主题必填本页覆盖的主题。Target file目标文件在 docs 仓库中的落地路径如已知。Existing content现有内容若为重写提供当前页面作为基线。Context上下文可选社区信号、GitHub issues、驱动本次写作的定位主题。从源码结构看这份输入清单与.agents/skills/README.md中技能命名{domain}-{action}、说明针对本仓库、引用真实文件路径的编写指南一致说明 docs-writer 是高度仓库化的技能它的一切规则都绑定到本仓库的语音栈与术语锁定文件而非通用写作模板。三、写作流程七步走从加载语音上下文到 reviewer 放行docs-writer 定义了从 Step 1 到 Step 7 的线性流程外加两个带后缀的中间步骤3b、4b。整体流程如下Step 1加载语音上下文动笔前必须先读两个文件../../references/voice-guide.md完整的五层语音栈→ 即 .agents/references/voice-guide.md../../references/terminology.md规范术语→ 即 .agents/references/terminology.md若是重写场景还需先读当前已发布页面作为基线。注意原文中的../../相对路径是以 SKILL.md 所在目录.agents/skills/docs-writer/为起点的在仓库根目录视角下对应.agents/references/。Step 2大纲每个条目是一个问题大纲的每个条目必须是该章节回答的那个问题结构随内容类型变化Tutorial通往一个可用结果的逐步旅程How-to前置条件、步骤、预期结果ReferenceAPI 表面类、方法、参数Explanation问题、设计取舍、权衡、影响硬性要求是一章节一问题一个章节尝试回答两个问题就拆分回答不清问题就不该存在。混合类型章节本身就是结构缺陷docs-audit 会把 mixed 直接记为 finding。大纲完成后要主动检查 scope creep范围蔓延。Step 3草稿首句写开发者目标撰写每个章节时遵循以下规则每个章节的第一句话描述开发者的目标framing layer即More You Than I原则写你通过向构造函数传参来创建带自定义工具的 Agent而不是Agent 类在其构造函数中接受 tools 参数。后者是 reference 式的描述适合参数表不适合教程。语气与该内容类型匹配register layertutorial 耐心、鼓励how-to 高效、命令式reference 正式、穷尽explanation 思辨、展现取舍。代码示例必须可运行使用真实的 Strands 导入与贴近现实的取值。非确定性输出要显式标注Agent 行为是非确定性的同一提示可能产生不同模型响应、工具选择与推理路径文档必须按 voice-guide 的Documenting non-deterministic behavior模式处理——确定性代码精确展示非确定性部分显式标注模式一模型输出把预期响应作为代码下方的注释如# Typical output:。模式二工具选择使用可以/可能使用can use / may use的能力性语言不用将会调用will call这种确定性语言。模式三多步推理在注释中展示一条代表性调用链的次序步骤。模式四结构化输出schema 是确定性的如 Pydantic 模型精确展示取值示例放相邻独立代码块。注释解释意图而非机制写# 最多重试 3 次指数退避不写# 调用重试函数。一个代码块只讲一个概念片段长度匹配所演示内容的复杂度偏向精简若搭建代码喧宾夺主说明片段过重。片段必须可直接复制运行导入齐全、变量已定义、无缺失上下文。琐碎 API 表面优先用散文单个属性、单个方法调用、一行配置变更用行内反引号代码比独立代码块更清晰当调用之间的形状、次序或交互承载知识点时才用代码块。**图示用 yamltitle: [title] description: [140-160 char description for SEO]可选字段仅在适用时添加languages、community、experimental、integrationType、category、redirectFrom、tags、sourceLinks。该 schema 在 [site/src/content.config.ts](https://link.gitcode.com/i/cdfb3b6d2dfebeca9fa8abeac98a4458) 中由 Zod 定义并校验docs collection 的 extend 对象**schema 未验证的字段会在构建时被 Zod 静默剥离**如自造的 contentType、lastReviewed 会被无声丢弃因此不要发明字段。另外languages 不应列出全部支持语言pythontypescript 同时列出是冗余特性在所有语言可用时应省略该字段。 ### Step 7运行 docs-reviewer 对完成的草稿运行 docs-reviewer 技能[.agents/skills/docs-reviewer/SKILL.md](https://link.gitcode.com/i/e88dce01bf195c3a2d445849f3ff0554)处理其所有发现后再交付。docs-reviewer 审查六个维度语音栈合规、双语言正确性、术语一致性、代码示例质量、人AI 可读性、内容类型对齐并输出三档裁决 - **Ship it**全维度良好至多一个措辞级 warning零术语违规代码示例结构完整。 - **Tighten**两个及以上 warning或一个可原地修复的 failing 分数给出行级修复建议后由作者修订重交。 - **Rethink**两个及以上 failing 分数或任何结构性失败内容类型错误、混合目的章节需重列大纲、框架根本性反转、前置条件缺失需要作者重新列大纲再重写。 注意 docs-reviewer 与 docs-audit 的分工边界reviewer 检查代码示例**结构完整**Stripe 完整性原则导入齐全、变量已定义、真实取值但不验证导入路径是否解析到真实 SDK 模块、方法签名是否匹配当前 SDK 版本——那属于 docs-audit 的职责docs-audit 以 SDK 源码为唯一事实源文档与源码冲突时文档按定义出错。 ## 四、输出约定与 Git 工作流 docs-writer 的最终交付物为三部分 1. **完整页面内容**全文 2. **语音选择简述**所用 register、关键编辑决策 3. **留给 PM 评审的开放问题**术语、范围、准确性顾虑 Git 工作流遵循仓库 [AGENTS.md](https://link.gitcode.com/i/15b786da7d81175cacfaf5a0e96dac45) 与 [CONTRIBUTING.md](https://link.gitcode.com/i/8dbd1069fd2d9051cc1759cdc0a481ed) 中的约定技能本身不自动提交auto-commit 需要人工审查。 ## 五、边界这个技能明确不做的事 - **不自动提交**必须有人工审查。 - **不从代码自动生成参考文档**那是独立的自动生成关注点site 侧有 api-generation 脚本与 api/... 速记链接体系见 [mdx-authoring.md](https://link.gitcode.com/i/09854e476ac67263a8e6981ee9dde7fd) 的 API Reference Shorthand。 - **不发布或部署文档**。 ## 六、常见坑Gotchas docs-writer 的六条实战提醒是最容易翻车的地方 1. **TypeScript 绝不内联在 MDX 中**。TypeScript 示例必须放在兄弟 .ts 片段文件中经 --8-- 指令包含内联 TypeScript 会直接导致 review 失败。 2. **代码必须对照 SDK 源码验证**。最常见的失败模式是看似合理的导入其实不存在或参数名写错——这正是 Step 4b 存在的意义。 3. **术语锁定是严格的**。Hook 不是 callbackPlugin 不是 middlewareTool 不是 function详见 [terminology.md](https://link.gitcode.com/i/3c9607cfc5c2a7059a784992196e3ec8) 的锁定表SDK 语境下 skills 也是被禁的同义词。动笔前先查表。 4. **覆盖表按内容类型放宽不同规则**。不要把 tutorial 的约束套用到 reference 页面reference 允许被动语态、豁免 More You Than I 框架。 5. **MDX 的 Tabs 语法很挑剔**。必须严格匹配 [mdx-authoring.md](https://link.gitcode.com/i/09854e476ac67263a8e6981ee9dde7fd) 中的模式否则构建会失败组件名是 Tab 而非 TabItemTab 内内容不能以空行开头。 6. **激进删减**。初稿总是长 30-50%真实性审查Step 5是质量主要来源。 ## 七、双语言与 AI 可读性docs-writer 的隐藏设计 docs-writer 背后的 voice-guide 还有两套贯穿性原则值得单独说明 **多语言文档原则**Strands 同时发布 Python 与 TypeScript SDK仓库中分别位于 [strands-py](https://link.gitcode.com/i/60e8a9c5dfdaeb0e8212ac3f23110540) 与 [strands-ts](https://link.gitcode.com/i/5119600c59cbe77e7a81f588c3df80a2)。概念类页面tutorial、how-to、explanation在特性两个 SDK 都有时用 Tabs 双语言呈现参考文档按语言分开。特性只在单语言存在时只写该语言并注明可用性。**API 对等是目标不是保证**两 SDK 的参数名、导入路径、API 表面可能不同必须各自独立对照源码验证。页面标题结构在两个语言下应一致TOC 相同分歧是内容不是结构——放进已有 Tab 内部绝不允许只在一种语言存在的标题会在另一语言的 TOC 中产生空 stub也不允许带语言后缀的标题如 Tool Caching: Python。 **人AI 双受众原则**开发者现在以两种方式消费文档——直接阅读以及通过 AI 中介Cursor docs、GitHub Copilot、Claude Code MCP 等。每页必须自包含self-contained因为 AI 助手可能只抓取单页而无导航上下文。自包含检查清单五项顶部有上下文首段说明覆盖内容与受众、前置条件显式声明、无承重性的前后交叉引用、关键术语首次出现即定义或链接、代码示例自包含含导入与设置。术语一致性对 AI 尤其关键同一文档集中混用 API key、access token、auth credential 会在 AI 生成的代码建议中产生幻觉式混淆——一个概念一个术语处处如此。 ## 八、实战建议如何在自己的页面中运用这套流程 结合 docs-writer 的流程与语音栈落地一套可复用的写作自检序列 1. 动笔前先读 [voice-guide.md](https://link.gitcode.com/i/9fcc2f279c7800766fc21030ce501785) 与 [terminology.md](https://link.gitcode.com/i/3c9607cfc5c2a7059a784992196e3ec8)明确内容类型与对应 register。 2. 列大纲每项写成该节回答的问题检查无混合类型章节。 3. 每节首句写开发者目标代码示例对照 SDK 源码验证Tier 1 本地克隆优先非确定性输出按四种模式标注。 4. TypeScript 代码走 .ts 片段文件 --8-- 包含Python 可内联共享散文用 Syntax 组件保持语言中立。 5. 按覆盖表与硬约束自检禁用词、无 em-dash、无 emoji、主动语态、术语一致。 6. 审查机器感打破结构同质、加入编辑判断、激进删减。 7. 补 frontmattertitle 140-160 字符 description可选字段见 Zod schema最后过一遍 docs-reviewer。 这套流程的价值在于把写文档从自由发挥变成可检查、可评审的工程活动语音栈是可执行的分层规范术语锁是构建期强制的统一性代码验证四层兜底保证示例真实可运行而 AI 可读性检查让每一页既能被人类直接读懂也能被检索工具与 LLM 准确引用。赞分享人工智能大模型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 文档语音体系指南五层 Voice Stack 与面向人类与 AI 的文档写作规范harness sdk 文档语音体系指南五层 Voice Stack 与面向人类与 AI 的文档写作规范 本篇技术指南基于 harness sdk 仓库中维护人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务Wasp 文档写作指南如何为全栈框架 Wasp 编写高质量技术文档Wasp 文档写作指南如何为全栈框架 Wasp 编写高质量技术文档 Wasp 是一个以“全栈框架”为核心的 JavaScript/TypeScript 开发框Web框架后端前端CLI开发工具OpenShell 架构文档编写规范arch-doc-writer 技术写作工作流与质量体系OpenShell 架构文档编写规范arch doc writer 技术写作工作流与质量体系 本篇指南完整解读 OpenShell 仓库中 .claude/a上一篇NeoformatNeovim/Vim代码格式化插件详解下一篇WSL基础命令完全指南从安装到高级管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考