superdevlisted

# SuperDev MCP 使用指南 ## 核心理念 ### 工具给证据，AI 下根因 `diagnose_service`、`analyze_trace_logs`、`summarize_error_window` 只收集确定性证据。不要把工具输出当成根因照搬；先采集运行状态、日志、trace、错误聚合，再由 AI 明确写出推理链和置信度。 ### 读写分离 + 双层安全门 只读工具可放心使用。配置写入必须走 `preview_config_change → apply_config_change`。**所有写工具采用统一审批模型**：直接调用（不传 `approval_token`），需要审批时 MCP 默认在 SuperDev 桌面端等待用户批准并自动带 token 续跑，对你无感。是否真正审批由用户配置的开关决定，用户也可在批准时开启「项目级免审窗口」让后续同项目操作自动通过。详见 `references/safe-operations.md`。 ## 第一步：永远先建立全局视野 开始任何 SuperDev MCP 任务前，先用 `get_runtime_snapshot` 或 `list_services` 摸清项目、服务、deployment、环境和状态。用户已经指定项目时用 `list_services`，用户只说“看看 SuperDev 怎么了”时用 `get_runtime_snapshot`。 不要一上来就调用具体写操作，也不要在没有证据时猜测根因。 配置远程主机前必须先调用 `list_hosts`。`host_ids` 只能填写 `list_hosts` 返回的非本机主机 `hosts[].id`（`is_self=false`），不能填写 `hosts[].name`、SSH Host、机器名或用户口头描述。 ## 总决策树 | 用户意图 | 先做什么 | 继续阅读 | | --- | --- | --- | | 把服务跑起来 / 重启 / 停掉（哪怕没提 SuperDev） | 先 `list_services` 看该项目是否已被 SuperDev 接管；已接管则走 `start_service`/`restart_service`/`stop_service`，不要 shell 自己起 | 本页「第零纪律」 | | 我（AI）刚改了被接管服务的代码，且改的是不热更新的部分 | 改动落盘后主动 `restart_service`（编译型先确认 deployment 会重新编译），再让用户验证 | 本页「第零·五纪律」 | | 服务挂了、报错、为什么慢 | `list_services` 定位 deployment，然后 `diagnose_service` 采证 | `references/debugging-workflow.md` | | 看日志、查某个错误 | 按已知信息选择 `tail_logs` / `follow_logs` / `search_logs` / `get_log_context` | `references/log-tools.md` | | AI 调试遇到登录/鉴权墙 | 先 `get_debug_credentials` 取项目/服务授信的测试账号或 api-key，再正常填登录框或带请求头 | 本页「AI 调试凭据纪律」 | | 调试本机前端页面（点击/输入/截图/读 console，哪怕没提 SuperDev） | `list_browser_targets`