SPFx Dev Skills 背后：测试代理所知，修复其遗漏
内容提要
AI编码代理可升级SharePoint Framework项目，但需引导。测试显示，代理能识别SPFx并找文档，但常漏依赖和配置。反幻觉技能提升有限，而CLI for Microsoft 365工具效果最佳，使依赖和配置正确率大幅提高。文档警告和重写指南促使代理采用CLI。SPFx Dev Skills预览版整合决策规则，指导代理正确升级，并强调审查输出。
延伸解读
为何代理会“知其然不知其所以然”
测试显示，AI代理能识别SPFx项目并直接构造文档URL，但常忽略中间版本（如1.22.0和1.22.1）的增量变更，导致升级不完整。代理倾向于先制定计划再用文档确认，而非先阅读文档。这解释了为何仅提供文档链接或反幻觉技能效果有限——代理需要明确的决策规则来纠正其固有行为模式。
CLI工具为何比通用技能更有效
当明确指示代理使用CLI for Microsoft 365时，依赖正确率从34/50升至50/50，配置正确率从38/85升至83/85。原因在于CLI已编码了版本间升级逻辑，而通用技能或文档仅提供指导，无法保证代理执行所有必要步骤。这表明，对于规则明确的升级任务，专用工具比通用AI技能更可靠。
文档措辞如何影响代理决策
实验发现，仅添加CLI提示无法改变代理行为，因为代理倾向于选择详细的逐步指南。但在移除详细指南并添加警告（说明手动更新package.json会导致构建失败）后，CLI采用率从0/5升至5/5。重写指南为概念性说明并指向CLI后，效果同样显著。这说明文档设计需同时考虑人类读者和AI代理的决策逻辑。
技能之外的修复：平台与文档协作
研究不仅改进了SPFx Dev Skills，还发现Microsoft Learn返回HTML页面不利于代理解析，因此推动GitHub Copilot支持Markdown格式。这表明，AI代理体验问题可能源于技能之外的文档格式或平台限制。开发者应审查代理输出，并反馈问题以帮助改进技能和底层工具。
Q&A
SPFx Dev Skills 是什么？它主要解决什么问题？
SPFx Dev Skills 是微软 SharePoint Framework 团队和开发者关系团队合作开发的预览版技能包，用于指导 AI 编码代理正确执行 SPFx 相关任务，尤其是项目升级。它基于测试结果，将 SPFx 特定的决策规则打包成一个技能，引导代理使用正确的工具（如 CLI for Microsoft 365）和遵循正确的步骤，避免遗漏依赖和配置错误。
在测试中，AI 编码代理升级 SPFx 项目时主要存在哪些问题？
测试发现，AI 编码代理能识别 SPFx 项目并找到文档，但常遗漏依赖和配置细节。例如，代理只更新了主要版本号，却忽略了中间版本的增量变化，导致依赖未更新、配置不正确。代理倾向于先制定计划再用文档确认，而不是完全依赖文档，且不会主动使用 CLI for Microsoft 365 等工具。
反幻觉技能和 context7 MCP 服务器对提升 AI 代理升级 SPFx 项目的效果如何？
反幻觉技能能提升部分指标（如惯用法使用从 7/10 提升到 10/10，依赖更新从 34/50 提升到 40/50），并减少约 9% 的 token 使用，但配置正确率仍只有 46/85，项目仍只是部分升级。添加 context7 MCP 服务器没有带来显著提升，因为代理在 5 次运行中有 3 次未调用其工具。
CLI for Microsoft 365 在 SPFx 升级中起到什么作用？为什么它效果最好？
CLI for Microsoft 365 的 spfx project upgrade 命令能分析源和目标版本，生成版本特定的增量升级所需更改。在测试中，当明确指示代理使用 CLI 时，依赖更新从 34/50 提升到 50/50，配置正确率从 38/85 提升到 83/85。效果最好是因为该工具已经编码了升级逻辑，能提供确定性指导，而代理自身无法发现它。
文档中的警告和重写迁移指南如何影响 AI 代理的行为？
在文档中添加警告（指出手动更新 package.json 会导致构建失败）并移除详细迁移步骤后，CLI 采用率从 0/5 提升到 5/5。但恢复详细迁移指南后，CLI 采用率又降回 0/5。因此，团队重写了迁移指南，改为解释 gulp 到 Heft 迁移的概念，并引导读者使用 CLI 应用更改，这样代理在 5/5 次运行中都使用了 CLI，配置正确率达到 85/85。
SPFx Dev Skills 目前包含哪些指导内容？
SPFx Dev Skills 预览版目前涵盖：创建 SPFx web parts、扩展、库和自适应卡片扩展；使用 CLI for Microsoft 365 升级项目；为 SPFx 1.22.0 及以上版本选择 Heft，更早版本选择 gulp；使用 Fluent UI v9 构建 React 界面；以及使用 PnPjs 访问 SharePoint 和 Microsoft Graph 数据。升级指导要求代理先检测已安装版本并检查 Node 和 TypeScript 兼容性，然后使用 CLI 按顺序应用更改，最后确保构建干净。
除了 SPFx Dev Skills，这次调查还带来了哪些其他改进？
调查发现 Microsoft Learn 支持直接返回 Markdown 格式的页面，这比转换完整 HTML 页面更干净。这一发现被分享给 GitHub Copilot 团队，他们为 GitHub Copilot Chat 和 CLI 添加了 Accept: text/markdown 支持。此外，文档改进（如警告和重写迁移指南）已提交到 SPFx 文档，使所有开发者和代理受益。
