故障排查

症状：我本来想打开一个页面，却看到了 404

文档已经从旧的混合分组迁移到七个顶层分区。请从 /docs 或 快速指南 开始，而不是继续沿用旧路径。

症状：Rules、Prompts 或 MCP 相关内容被写到了错误的位置

先检查以下几点：

1. plugin.config.ts 里实际装配了哪些输出插件。
2. 你写的是 global prompt 还是 workspace prompt。
3. 目标插件是否对该类内容有自己的路由行为。

症状：clean 看起来不安全，或者删掉了太多内容

先查看 dry-run 与 clean。如果你的目录同时混有手写文件和生成文件，请在真正执行清理前把手写文件移出 tnmsc 管理的输出路径。

Warning 如果 tnmsc 需要的是 .codex/ 这类目录，但在那里发现了一个同名文件，这会被视为路径类型冲突。恢复行为的目的，就是避免这种冲突阻塞整个同步过程。

当前运行时的处理方式是发出警告、删除阻塞文件，然后继续执行。之所以把该文件视为可丢弃，是因为它占据了一个对生成输出而言必须是目录的路径。

症状：运行因为不受支持的 plugins 键错误而停止

先检查 ~/.aindex/.tnmsc.json。

现在只要 plugins 配置块里包含未知键，tnmsc 就会快速失败。日志会告诉你哪个键不受支持，并打印受支持键列表。

可以这样修复：

1. 删除不受支持的键。
2. 把它改成 JSON Schema 或 aindex 与 .tnmsc.json 中列出的受支持键之一。
3. 重新运行命令。

症状：某个文档页面构建失败

先运行：

pnpm -C doc run validate:content

这一步校验会检查：

• 每个 MDX 文件是否都有 title 和 description
• 每个内容目录是否都有 _meta.ts
• _meta.ts 是否覆盖了当前文件和子目录
• 站内文档链接是否指向真实页面