mastraudit

Mastraudit

在 Mastra 工作中，将此指南作为构建指南。趁实现正在引入昂贵错误时，及时防止这些错误。现有名称也适用于明确要求的审计。

修改代码之前

1. 找出运行时的负责人和实际版本。 从调用它们的包中解析依赖，包括 CLI、存储和引擎适配器。清单中的版本范围、目录项或目录列表都不代表已安装的版本。阅读该版本内嵌的文档和类型，以及已配置的本地供应商镜像中对应的页面。较新的镜像仍可能描述较新的发行版。本地证据缺失时，使用已发布的文档；并说明这一缺口。
2. 阅读现有的可行先例。 遵循现有的公共桥接层、存储提供程序、模型策略和领域操作。确定执行路径：普通 Agent、持久化工作流、Studio 聊天、HTTP 或 stdio MCP。追踪由什么构建它，以及通过什么注册使其公开。阅读 结构，了解所有权和导入变更。
3. 选择契约和边界。 明确有用的输出、失败和完成状态，以及各步骤之间传递的引用，并限制输出、步骤、耗时和重试次数。为 Agent 提供其做出决策所需的操作；将整个确定性工作流包装起来，可能导致 Agent 比较陷入循环。工具或结构化输出请阅读 契约，有状态工作请阅读 执行。
4. 运行前选择验收路径。 明确本次变更涉及的一个流程及其可观察结果。先检查测试和导入的副作用。仅审计的范围允许检查源代码和执行安全的本地检查，不允许调用模型、提交工作流、写入存储或部署。运行测试、评估或声称已完成之前，请阅读 证据。

这是一项简短的实现决策，不是新的规划文档。如果项目使用跟踪器，请将证据保留在负责该项的跟踪器条目中。

对于相同的来源、已安装版本和运行时，复用已确立的预检。依赖、导入、设置或执行路径发生变化时，再检查相关契约；无需重读已确认的文档，也无需每次保存后都重新运行已通过的检查。

构建过程中

• 将领域行为和规范架构保留在其源头；Mastra 负责将它们连接起来。检查类型检查无法验证的胶合代码：注册键、生成的架构、输出投影、回调传递、存储注入、恢复转发和模型设置。
• 复用适用的已安装扫描器。调用前先阅读其签名和覆盖范围。扫描器输出只是线索，须对照实际调用方和受支持的契约进行核实。没有可用的扫描器时，应说明覆盖范围的缺口，而不是臆造包导出项。
• 在修改依赖、添加回退方案或归咎于提供程序之前，先建立最小复现。从请求大小、有效设置、身份、来源版本和持久化状态着手。每次只改变一个原因。
• 对于 Studio，在限时运行前与其负责人协调稳定的运行时窗口。有关来源地址、热重载、过期的捆绑包、本地 stdio 和内嵌应用，请阅读 Studio 和 MCP。
• 对已证实的静默失败，在共享边界上添加最小且实用的防护。在信任防护之前，先确认它能在原始不利案例中触发。不要仅仅因为一项聚焦检查通过，就运行庞大的测试套件。

出现故障时

症状	首要排查项
空对象、工具被忽略、架构遭拒	查看 contracts 中的原生结果、生成的提供方架构，以及工具／结构化输出的兼容性。
步骤缓慢、重复搜索、较早的信息缺失	查看 execution 中测得的提示词／结果／快照大小，以及处理器保留情况。
进度丢失、重复写入、恢复卡住	查看 execution 中的检查点、身份、幂等性和持久状态。
单元测试意外连接或写入	查看 evidence 中的导入时初始化、环境变量优先级和驱动保护。
Studio 无法加载、打包卡住或运行记录丢失	查看 Studio and MCP 中的进程、来源、依赖关系图和重新加载时段。
修复在 HTTP 中有效，但在现有 MCP 会话中失败	查看 Studio and MCP 中的传输身份和进程启动时间。
内嵌 HTML 可用，但 Agent UI 不可用	查看 Studio and MCP 中的工具元数据、资源、结果封装和访客端与宿主端握手。
分数达标，但答案不符合要求	查看 evidence 中的独立预期、硬性要求和已持久化的实验依据。

完成前

使用最接近且获准的依据测试变更路径。可见功能需要在预期宿主环境中进行交互；持久化功能需要检查其存储输出和恢复边界。如果未获准执行这些操作，请说明缺少哪些验收依据。

给出简短结论、变更内容、已安装的版本和实际测试的确切源代码／运行时、重点依据，以及尚存的差距。将源码检查、运行时执行、持久化、宿主交互、发布和部署分别作为独立声明。明确的审计应按故障代价对已确认的问题排序：阻塞、应修复、已记录；每项都应包含 file:line、后果和修复方法。对于跳过的检查，请附上覆盖情况说明。

达到所述验收条件后即停止。新发现的无关问题应记入跟踪器，而不是作为理由继续进行无休止的额外检查。