软件开发不仅仅是编写代码,更关乎把可用且可理解的产品交付给用户。代码合并固然重要,但高质量的文档同样决定了软件能否被其他人有效采用。对许多工程师而言,写文档常常被视为一项"繁琐的杂务",容易被推迟或敷衍完成。我们在 Mintlify 团队内部也深有体会,因此打造了 Mintlify Agent,希望彻底改变文档编写的体验。与多数聚焦终端或 IDE 的编码代理不同,我们选择把代理放在 Slack 中。下面详细阐述这个决策的缘由、实现细节、应用场景以及对团队与组织的实际价值。
从终端到 Slack:界面的心理差异 开发者习惯把终端和 IDE 作为生产力的中心。打开终端意味着进入高强度的编码状态,关闭它则通常代表任务完成或需要休息。正因为如此,让工程师再次打开终端去完成文档更新,会产生"重新进入工作模式"的心理阻力。文档写作变成了必须把袜子重新穿上的家务活,令人厌烦。 相比之下,Slack 是一个全天候常开、用于沟通和协调的工具。它不像终端那样暗示高强度思考,而更像一双舒适的室内拖鞋,随时可用、轻松自然。
将文档代理放在 Slack 中,用户可以在收到 PR 合并通知的线程中直接 @mintlify 并下达更新文档的指令,这个过程更符合人们的沟通习惯,消除心理门槛,从而提高文档更新的频率与质量。 为什么不是终端?一方面并非否定终端代理的能力,许多工具在技术层面可以完成文档更新并创建 PR。但我们从客户反馈中发现,终端代理的复杂性常常超过任务本身的价值。终端代理往往像多功能瑞士军刀,既可以写代码、运行测试也能部署,但当目标是"只更新一篇文档"时,过多的配置、上下文工程与指令调试会耗费用户耐心,让他们选择放弃。 以提示词对比说明差异。给终端代理的指令需要明确、详尽并包含大量上下文才能得到稳定结果,而在 Slack 中,用户可以用自然语言描述变更要点,让代理理解意图并完成剩余工作。
更简单、更直观的交互意味着更高的使用率和更快速的价值兑现。 最小化上下文:上下文工程的实践 任何一种代理的核心问题在于上下文。优秀的代理应当在给定任务上只拥有完成任务所需的最小上下文。这个原则既保护敏感信息,又能提高推理效率与准确率。基于这一思路,我们为 Mintlify Agent 设计了精简而强大的工具集,支持代理在受控范围内执行读写操作、跨仓库读取、网站结构检查、网络检索与与用户沟通等功能。 为了保证代理在多轮操作中不丢失意图,我们引入了 todowrite 与 todoread 等机制,允许代理记录并恢复多步骤任务状态。
例如代理在编辑某篇文档时发现需要调整导航或补充图片,它可以将这些后续任务写入 todowrite,然后在完成一个文件后回到先前上下文继续处理。这样的设计避免了频繁的人机交互,提升了自动化完成复杂文档变更的能力。 端到端工作流和信任闭环 我们把代理的工作流抽象为一个"看 - 复核 - 合并 - 重复"的信任闭环。代理读取 PR 和相关文件,做出变更并在平台上生成预览部署,随后在 Slack 中发出可检视的预览链接供用户复核。用户只需在熟悉的沟通界面中查看变更、发表评论或一键合并。借助预览部署,用户能在真实上下文中验证文档与网站的呈现效果,而不需要本地检出或复杂的构建流程。
这种闭环不仅降低了误改风险,还增强了对代理输出的可解释性。用户在 Slack 中与代理互动的历史记录也成为审计与溯源的一部分,使团队对变更过程有更清晰的追踪。 实现细节:工具组合与能力边界 为了让代理既能胜任文档写作又保持简洁,我们明确了其工具边界。核心工具包括文档文件操作的 CRUD 能力、跨仓库访问工具、网站结构读取、网络检索与内部沟通工具等。这样的组合让代理可以在多个仓库中查找相关上下文、更新导航结构、插入迁移说明、并根据外部权威资料补充引用。 跨仓库访问应对了文档往往与产品代码分布在不同仓库的现实。
代理凭借 fetch_pull_request、list_repositories 等能力可以自动定位相关 PR 和文件,从而在正确位置提交更新。read_navigation 工具确保新页面或编辑能融入现有信息架构,避免破坏网站导航。 我们也深刻考虑了权限与安全。代理在执行写入或创建 PR 的操作前,会在 Slack 中向用户明确展示变更摘要和预览链接,并等待用户确认或直接在指定的工作流程中被授权自动合并。审计日志、最小权限策略和预览部署共同构成了安全与可控的保障。 Agentic Automation:从手动到自动的跃迁 我们相信"agentic automation"将成为软件工程的新范式。
这一模式将大型语言模型与外部工具按步骤组合,使复杂目标通过序列化的工具调用得以自动完成。在文档场景下,典型流程可能包括收到代码合并事件、由代理检索变更上下文、生成或更新文档、创建 PR 并在 Slack 中通知相关人员。若满足条件,代理甚至可以自动合并并发布文档,从而实现从代码提交到文档发布的闭环自动化。 为了支撑这种可能性,我们在平台中新增了专门的 Agent API 端点,允许基于触发器(如 commit 推送、feature 发布或 webhook)启动文档工作流。用户可以将文档更新逻辑作为独立的自动化管道配置,当某类事件发生时,代理会按设定的步骤执行研究、写作、校对、预览与沟通。这样的能力让团队能够在保证质量的前提下,把重复性任务交给代理处理,从而把人力解放出来做更高价值的工作。
真实使用场景与用户体验 在 Mintlify 内部我们已经把代理用于一系列日常任务,其中一个最典型的例子是周报与变更日志的维护。以往每周需要人工总结变更、撰写条目并发布到网站。现在只需在 Slack 中 @mintlify 指示代理"基于本周合并的 PR 更新变更日志",代理就会自动收集相关信息、生成条目、提交 PR 并提供预览链接。最后由人工进行快速复核并合并。这个流程将原本令人厌烦的工作转化为一次轻松的沟通交互,极大提升了执行率。 另一个场景是客户支持团队与工程团队的沟通。
当支持人员在 Slack 中分享解决方案细节时,他们可以让代理把关键文本转成文档更新并生成 PR。代理会自动整理信息、检查文档结构并建议合适的位置,使知识库及时同步真实世界的解决方案。 设计哲学:把复杂性留给工程,把简单留给用户 我们的设计哲学很明确:把尽可能多的复杂度封装在平台一侧,让最终用户享受最简单自然的交互。用户不需要学习复杂的上下文工程或编写冗长的提示语,只需在熟悉的 Slack 对话中表达意图。与此同时,平台负责将用户指令转化为精确的工具调用、管理状态、执行变更并提供可验证的预览。 这种理念也影响了我们对代理能力的边界设定。
我们并不追求万能的代理,而是把代理专注在"文档写作与维护"这一垂直领域。通过聚焦,代理能以更高的可靠性与可预测性完成任务,而不会因为泛化能力而引入不必要的错误或风险。 面向企业的考量:合规、审计与权限模型 企业用户对安全与合规的要求通常高于个人团队。为此我们在实现中采用了成熟的审计与权限机制,记录代理的每一次文件访问、变更与 PR 操作,并提供可导出的审计日志。管理员可以控制代理对仓库的访问范围、是否允许自动合并以及在什么条件下需要人工审批。 此外,预览部署不仅提升了用户体验,也成为安全筛查的一道防线。
团队可以在合并前在真实站点上下文中检查文档渲染情况,确保没有敏感信息泄露或渲染异常。在行业合规性方面,我们支持企业级加密与 SOC 类审计能力,为将代理用于生产环境提供保障。 未来方向与持续演进 将代理放在 Slack 并不是终点,而是一个关于如何把 AI 更自然地融入日常工作流程的实验。未来我们计划扩展代理的能力边界,支持更多类型的文档(如 API 参考、迁移指南与架构说明)以及更复杂的自动化触发器。同时会继续优化代理的长期记忆与上下文保持能力,使其在跨会话、跨仓库的多步骤任务中表现更稳健。 我们也在观察社区对功能的需求,优先级将由用户反馈驱动。
无论是增强对多语言文档的支持,还是集成更多审查流程与合规检查,最终目标都是帮助团队把知识沉淀成可发现、可维护的文档资产,而不是让文档变成被遗忘的负担。 结语:让文档更新像发一条消息那么自然 把编程代理放在 Slack 的核心价值在于降低心理与操作门槛,让文档写作回归到团队沟通的自然流程中。通过精简的工具集、可控的权限和预览部署,我们建立了一个看 - 复核 - 合并的信任闭环,把复杂的工程与安全问题留给平台去处理,把简单的指令留给用户去下达。对于希望提高文档质量、缩短知识传播路径并解放工程师时间的团队而言,这样的设计不仅是技术上的优化,更是工作方式的革新。 如果你在寻找一种更顺手、更可持续的文档维护方式,试着在日常沟通中与代理交互,可能会发现写文档再也不是一件让人畏惧的事情。未来的文档工作将不再是孤立的任务,而是嵌入在团队协作流中的自然环节。
。
