Composio 技术文档写作规范以 Modal 式写作风格打造清晰、可执行、便于 Agent 检索的开发者文档【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文是 Composio 仓库内置的文档写作技能good-docs-writing核心规范解读其规则体系取自 style-guide.md。这份指南定义了 Composio 官方文档的声音直接、自信、低术语门槛、示例优先。读完本文你将掌握一套可复用的技术写作规则包括语气、结构、术语、标点、代码示例与排版六大部分并能用 audit-process.md 中的审计清单反向检查已有文档。这份规范同时服务于人类读者与检索式 Agent清晰的结构、精确的反引号标识符、可复制的代码让文档既好读也好被索引与引用。这份风格指南是什么为什么它存在Composio 在仓库中维护了一套面向文档写作的 Agent 技能目录位于.agents/skills/下。其中 good-docs-writing/SKILL.md 是技能入口references/style-guide.md 是完整规则集而 good-docs-audit/SKILL.md 是配套的审计流程用于对照规则检查已有文档并输出违规报告。这套规范的来源是 Modal 的文档风格style guide 开篇即注明 this guide is derived from Modals documentation voice。它被抽象为一条条祈使句规则每条规则后附一个真实示例作为证据。它的目标读者不是理论家而是想交付的开发者Treat the reader as a capable developer who wants to ship, not a student who needs a lecture。这套规范并不是空谈。Composio 自身的核心文档就是它的活样本例如 quickstart.mdx 开篇第一句直接给能力Build an agent that chooses Composio tools at runtime.没有铺垫how-composio-works.mdx 第一句直接定义概念Asessionis the runtime context for an agentic run。这就是规范里第一句定义概念或陈述收益的实践。声音与语气用你直接对话先讲为什么再讲怎么做风格指南的 Voice Tone 部分定义了整份文档的说话方式共六条以你称呼读者直接对话。不要躲在the user或one后面。示例Modals goal is to make running code in the cloud feel like youre running code locally.自信而平实不模糊、不推销。陈述事实先讲收益再讲限制。示例Modal makes it trivially easy to scale compute across thousands of containers.当某事是自动发生时让读者安心。明确告诉读者这些你不用担心。示例For the most part, scaling out will happen automatically, and you wont need to think about it.先解释为什么再给怎么做。先给出动机再给方案。自然使用缩写形式you dont、wont、its让语气更有人味。允许偶尔的温度与个性Thats it!、Take a breath of fresh air但要克制绝不滑稽。在 good-docs-writing/SKILL.md 中这条被压缩成最优先的规则Address the reader as you, never the user or one以及Open with the concept or benefit in the first sentence. No throat-clearing.第一句就给出概念或收益不要清嗓子式的铺垫。观察 Composio 文档的实际落点。how-composio-works.mdx 的userID best practices小节用了一个手风琴组件直接以祈使句给建议Use a stable identifier like your database ID, never one that can change.configuring-sessions.mdx 在讲connectedAccounts时也用Arrays are the preferred format这种直接断言。这就是陈述事实、先讲收益。结构概念先行渐进式披露示例尽早出现结构规则决定了读者以及解析文档的 Agent的阅读路径开篇第一句定义概念或陈述收益然后展开不做无意义的开场白。示例AnApprepresents an application running on Modal. It groups one or more Functions for atomic deployment and acts as a shared namespace.内容顺序概念 → 简单示例 → 进阶场景 → 坑。这是渐进式披露progressive disclosure。尽早给出最小可运行示例然后再解释刚才发生了什么explain what just happened。段落保持短小把密集信息拆成项目符号列表和编号步骤。使用过渡性路标句子标记解释转向例如What just happened?、But why does this matter?、Now, as before, …。混搭句子长度。短陈述句承担主体长句补充必要细节。示例The timeout duration is a measure of a Functionsexecutiontime. It does not include scheduling time or any other period besides the time your code is executing in Modal.最小可运行示例早出现 解释刚才发生了什么正是 quickstart.mdx 的结构先给完整可运行的 Python/TypeScript Agent 代码随后专门用一个名为 What just happened? 的章节逐条解释composio.sessions.create()做了什么、session.tools()为什么只返回少量 meta tools。这种示例 → 复盘的节奏正是规范要求的。术语核心名词大写为专有概念精确术语替代含糊表述术语规则保证全文概念一致这对搜索引擎与 LLM 的语义检索尤其重要将产品的核心名词作为专有概念大写如同 Modal 把App、Function、Image、Volume、Secret、Sandbox、Cls大写。规则是当名词指代产品本身时大写指代泛化概念时小写。产品名称保持一致不要出现 the Modal platform 这类填充式叫法。对应到 Composio就是统一写 Composio、Session、Toolkit、Tool、Meta tools、Connect Link、Auth Config、Connected Account而不是一会儿一个叫法。优先使用精确技术术语而非含糊表达例如 cold start、autoscaler、ephemeral、atomic deployment、warm pool、scaledown window。术语第一次出现时在上下文中解释之后直接使用。示例This is known as acold start, and it is often associated with higher latency.避免营销浮夸词与模糊强调词seamlessly、powerful、robust、cutting-edge。如果一件事很容易就展示它很容易。用类比锚定陌生概念然后立刻收住。示例Containers are like light-weight virtual machines.在 Composio 的文档体系里这套术语被固化成了概念地图。查看 docs/agent/instructions/context.md这是文档 Agent 的常驻概念地图Session、Toolkit、Meta tools、Auth Configs、Connected Accounts、Triggers 等都有规范定义和唯一权威页面。它把一个概念对应一个规范叫法、一个权威链接的意图做到了系统层面例如 Meta tools 是固定集合COMPOSIO_SEARCH_TOOLS、COMPOSIO_GET_TOOL_SCHEMAS、COMPOSIO_MANAGE_CONNECTIONS等Toolkit 与 Tool 的命名模式是{TOOLKIT}_{ACTION}如GITHUB_CREATE_ISSUE。写文档时沿用这套词汇就是执行术语规范。标点硬规则禁用 em-dash、使用牛津逗号、标识符一律反引号标点部分是硬性规定尤其是第一条不使用 em-dash长破折号。用句号、逗号、冒号或括号改写句子。这是硬规则This is a hard rule发布前必须清除每一处 em-dash。注意这一点比 Modal 原版更严格Modal 允许仅用于真正插入语的 em-dash但本规范直接禁用。使用牛津逗号列举最后一项前的逗号。所有代码标识符、命令、参数、路径、文件名一律使用反引号app.function()、modal deploy、scaledown_window、/gpu-glossary/。斜体用于细微区分与否定强调不用于一般性强调。示例This automatic upgrade doesnotchange the cost of the GPU.缩写与硬件名按惯例大写GPU、ASGI、A100、H100。对应中文写作时这条规则的移植方式是中文正文中不出现——式破折号改用冒号、逗号或括号所有代码标识符session.tools()、COMPOSIO_SEARCH_TOOLS、session_preset保持反引号包裹即使它们混在中文句子里。代码示例给完整可运行的片段标注脚枪footgun代码示例是这份指南最强调实战可用性的部分共六条先给完整可运行的片段导入、装饰器、函数一应俱全不给读者贴了也跑不起来的碎片。保持示例最小化用简单的名字f、app用...省略无关的函数体。展示框架惯用模式例如 Modal 的装饰器模式app.function()、app.cls()和 Image 的方法链写法。只在行为不明显处加注释干净的代码本身会说话在能教学的地方内联展示期望输出# 42。展示真实的 CLI 调用形式与真实提示符shell 用$或%Python REPL 用。示例modal run script.py::app.f。当某个 flag 是脚枪footgun时紧跟在示例之后说明。示例Remember to removeforce_buildTrueafter youve rebuilt the Image, or it will rebuild every time you run your code.Composio 文档是这条规则的完整执行者。在 configuring-sessions.mdx 的 direct tools preset 示例中代码块尾部直接打印期望输出# GMAIL_FETCH_EMAILS、# GMAIL_CREATE_EMAIL_DRAFT在connectedAccounts小节文档用 Callout 明示数组是首选格式单个字符串仅为向后兼容被自动强转为单元素数组这就是footgun 紧随示例之后。再比如 preload 小节文档明确给出版本门槛Requirescomposio/core≥0.9.0(TypeScript) orcomposio≥0.13.0(Python)把兼容性限制讲在前面。同页的 sandbox 禁用小节还列出了禁用后的三个具体行为meta tools 被排除、系统提示行被剥离、直接调用返回 400让读者对后果有精确预期。排版与格式标题大小写一致、具体化标题、Callout 与温和纠正格式规则决定文档的可扫读性单篇文档内标题大小写风格保持一致。Modal 倾向概念指南用句首大写sentence case如 How do Web Functions run in the cloud?参考类标题用标题大写title case如 Volume commits and reloads。每页选定一种不要漂移。标题要具体、有描述性避免泛化标题Entrypoints for ephemeral Apps 好于 Entrypoints。用 Callout 承载警告、提示、受限功能与 Beta 状态不要把它们埋在正文里。示例Deployment rollbacks are available on the Team and Enterprise plans.用Note that …或Gotchas旁注温和纠正不要用严厉警告的口吻。链接使用描述性锚文本自然地嵌进句子里绝不用裸 URL 或 click here。关键概念首次定义时加粗之后不再加粗。Composio 的文档组件体系为此提供了基础设施Callout、Accordions、Tabs、Steps等 MDX 组件在 quickstart.mdx 和 configuring-sessions.mdx 中被大量使用。例如 quickstart 用Callout typewarn提示 Do not install composio-core用Callout typeinfo说明 TypeScript SDK 是 ESM-only 且需要 Node.js 22.22.3how-composio-works 用Accordion收纳 userID 最佳实践。这些排版元素就是规范里 Callout 规则的产品化实现。审计流程把规范变成可执行的检查清单规范不能只靠自觉配套的 audit-process.md 提供了正式审计流程先读good-docs-writing技能拿到评判标准再完整读取目标文件逐条规则类别核对最后按格式输出报告。报告以file:line引用每一处违规给出原文引用与具体改写Give a real rewrite, not consider revising。审计清单按破坏力排序前几项对声音损害最大含糊与填充词it might be the case that、in order to、basically、simply、just删掉或下定决心。被动语态能用主动就主动。the function is invoked by the client 改为 the client invokes the function。营销浮夸词seamlessly、powerful、robust、blazing-fast、cutting-edge、world-class换成具体陈述或删除。em-dash逐处标记改为句号、逗号、冒号或括号。第三人称距离the user、one、developers can 处若本意是你就改回 you。无上下文术语首次出现时未解释的缩写或行话。术语不一致同一概念两种叫法或核心名词App、Function、Image、Volume、Secret大小写不统一。标题大小写漂移单篇文档内 sentence case 与 title case 混用。缺失反引号代码标识符、命令、参数、路径、文件名裸奔在正文中。被埋没的警告本应放进 Callout 的坑、版本说明、功能限制被埋在正文。虚弱的开头页面或小节没有以概念或收益开头先做无意义铺垫。碎片化/不可运行代码无法直接粘贴运行的片段或缺少期望输出 / footgun 说明。报告按 High / Medium / Low 三级组织每条违规用统一形状输出- file.md:42 · [Punctuation] Em-dash banned Offending: Modal is fast — really fast — and it scales automatically. Rewrite: Modal is fast, really fast, and it scales automatically.审计的默认行为是只报告不改文件Report, then offer to apply. Only write to files when explicitly asked.这与仓库只读的约束一致审计技能用于检查修改需显式授权。快速自检清单动笔前的六问style-guide.md 最后给出了一个写作时的快速自检这是整份规范的可执行浓缩我是否在第一句就给出了概念或收益开头附近是否有可运行示例我是否在用你而不是the user是否删除了每一处 em-dash是否删掉了所有 seamlessly、powerful 之类的模糊强调词所有代码标识符是否都用反引号包裹核心名词App、Function、Volume是否大写good-docs-writing/SKILL.md 进一步把最重要的规则压缩为六条以你称呼读者第一句给概念或收益近顶部放最小可运行示例删除每一处 em-dash砍掉模糊强调词为每个代码标识符加反引号。动笔前对照这份最短清单就足以覆盖大部分常见漂移。规范如何服务搜索引擎、Agent 与 LLM这套风格指南之所以值得被当作写作基准是因为它与机器可读性高度兼容反引号标识符与统一术语让代码实体session.tools()、COMPOSIO_SEARCH_TOOLS、sandbox_size在索引中保持精确可检索LLM 引用时不易产生别名歧义。概念 → 示例 → 进阶 → 坑的固定结构让文档形成稳定的信息模式Agent 可以在预期位置找到定义、代码与警告。概念地图与权威页面见 docs/agent/instructions/context.md把一个概念对应一个权威链接制度化文档 Agent 在回答时可以优先链接规范页面而不是临时搜索。可运行的代码示例与期望输出让文档既是阅读材料又是测试用例quickstart.mdx 里的# GMAIL_FETCH_EMAILS这类输出注释本质上就是把这段代码会产出什么写进了文档。**先讲为什么再讲怎么做**恰好也是知识图谱的构建方式动机陈述让概念之间的关系显式化而非只罗列操作步骤。对于要在 Composio 仓库中新增或修订文档的场景推荐的落地路径是先读 good-docs-writing/SKILL.md 与 style-guide.md 掌握规则参照现有文档如 configuring-sessions.mdx 的 Callout、Tabs、期望输出写法保持体例一致定稿前用 audit-process.md 的十二项清单做一次自审最后用文末的六问快速自检收尾。这样产出的文档既符合开发者阅读习惯也经得起搜索引擎与 Agent 的检索与引用。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
