#故障排查

先确定失败的边界：编写的源码、编译产物、已安装包，还是正在运行的宿主。 不要手工修复生成文件；修改拥有该行为的源声明，再重新构建。 能力地图区分受支持输出与受支持的客户端行为。

#确认版本和正在检查的对象

在项目中安装正确的框架包后：

npx --no-install agent-bundle --version
npx --no-install agent-bundle validate
npx --no-install agent-bundle inspect --json

对于复制来的产物，应检查该产物，而不是无关的源码工作区：

npx --no-install agent-bundle inspect --artifact artifact --json
npx --no-install agent-bundle validate --artifact artifact

inspect --artifact 不与源码 --root 或 --config 组合。 validate --artifact 接收纯组合产物；清单感知的安装路径也能理解 npm 根目录。 这些根目录的 inventory 职责不同，参见交付。

报告问题时记录 compiler/runtime 包选择器，以及 artifact/application 版本。 预览包应来自同一个不可变构建。正式 compiler/runtime 版本号可以不同； 使用匹配脚手架记录的配对，不要假定数字版本号必须相同。

#找到最小修正

#全新工作区中的生成类型

生成声明不是手写源码。在独立 typecheck 前运行当前受支持的生成路径，失败时停止：

npx --no-install agent-bundle validate
npm run typecheck

项目需要自己的 typecheck 脚本和正确的 tsconfig inclusion。 准备失败后可能保留旧生成文件，不要把它描述为最新。 当前 inclusion 警告并非所有 project references 的完整审计。 对于 solution-style 配置，验证每个实际消费程序；不要只把文件加进无关根程序以消除警告。 不要为获取类型而把服务器实现导入浏览器运行时代码。

starter 的普通测试命令会运行它附带的每个池；完整检查在其前面加上构建与类型检查：

npm test
npm run check

按需测试池见测试，规范契约见复用框架。 纯静态插件不应只为模仿 MCP starter 就增加 React/MCP 测试依赖。

#安装与替换

使用交付的 INSTALL.md 或受支持的包绑定安装器。 原生注册、文件放置、启用和实时会话是不同状态。 解释 receipt 或重新加载步骤前，请阅读安装指南。

使用 doctor 做只读安装状态检查。 不同版本或外来目录可能要求明确的 operator 决定；不要从 rm -rf、全局 cache 编辑或校验前权限修复开始。 keep-data 与 purge 的所有权要求不同。 缺少历史所有权，不代表可以删除推导出来的目录。

打包测试使用临时数据和隔离宿主根目录。 不要把真实密码、tracker session、私钥或正在使用的 operator 数据放进可复现 fixture。

#有用的问题报告证据

记录包选择器、Node 版本、最小相关配置与路由、精确命令、结构化诊断，以及运行来自源码、artifact、 已安装包还是原生宿主。写清预期行为与实际终态。

App/session 问题中，分别记录服务器、工具、启动投影和浏览器 profile。 重建问题标明新旧 revision，不必附上无关原始日志。 隐藏凭据、authorization header、session cookie 和私有命令数据，不要上传整个环境变量转储。

适用时链接诊断参考或对应能力记录。 测试失败、文档中的限制与未执行的验收用例，需要不同的后续工作；写明证据实际确立的是哪一种。