| name | setup-tool |
| description | 调研、评估、安装和配置已有工具，并生成有来源的使用说明。适用于“装个工具”“安装/配置 X 工具”“setup X”或“下载安装 X 并写说明书”。可用于 Claude Code、Codex、Hermes、OpenClaw 或普通项目环境；不会编造未声明的触发词或宿主命令。 |
setup-tool
这是跨宿主的工具接入顾问。按以下五个阶段工作，任何阶段信息不足时明确说明缺口，而不是猜测。
0. 确定宿主与边界
确认用户希望工具服务于 Claude Code、Codex、Hermes、OpenClaw、普通终端/项目，还是多个宿主。仅当当前上下文不能确定时询问。
读取 references/install-routes.md。只有官方资料已核验的平台 adapter 才能提供该宿主的目录、配置命令与重启方式。未适配的平台走 generic 路线：安装可移植的 CLI、MCP 或项目依赖，并明确“宿主接入方式尚未核验”。不要猜测目录、配置键或 slash 命令。
1. 查询并核验具体项目
按证据优先级识别：用户给出的精确 URL/包名/本地路径 → 官方仓库或包注册表 → 模糊名称搜索。模糊时只展示最相关候选（精确名、维护状态、描述、官方链接）；仍不能唯一确认才请用户选择。
核验官方来源、发布状态、许可证/维护状态、支持系统和安装形态。不要因为名称相似就安装，也不要把搜索摘要当成事实来源。
2. 解释用途并评估适配性
在安装前给出简洁表格：
| 项目是什么 | 常见存在形态 | 与现有体系的关系 | 对用户的实际价值 |
|---|
| 官方功能与边界 | skill / MCP / CLI / 库 / 二进制 / 桌面 app，或其组合 | 重名、端口、配置、依赖、权限、功能重叠与兼容性 | 能解决的具体任务、局限与替代方案 |
检查已有同名命令、MCP、skill、配置和依赖，给出“无冲突 / 可共存 / 需迁移 / 不建议安装”的结论和证据。无法确认时标记“待验证”，不能保证兼容。
如需扫描已知的 skill 目录，只能在 adapter 或用户已核验目录后运行：
python scripts/scan_existing_tools.py --root "<已核验的 skill 根目录>" --query "<工具名>"
该扫描器要求显式目录和查询词，默认最多返回 20 条 JSON 结果；目录不可访问会作为 JSON 中的 errors 返回，而不是把所有本机 skill 原样打印或让 shell 失败。
3. 给出选择与推荐
基于上一步给出至少两个真实可行选项；若确实只有一种安装形式，另一个选项必须是“不安装/继续使用现有方案”。每个选项说明安装形态与作用域、写入目录/配置、权限和维护成本、对现有体系的影响、配置/卸载难度和适用场景。
必须有一个 推荐选项 并说明理由，也必须提供 不安装 选项。推荐不等于替用户决定：全局安装、配置写入、二进制执行、密钥/网络访问或桌面安装在执行前仍需用户选择。
4. 安装、验证与配置
执行用户选择的官方方案。预检版本、目标目录、系统/CPU 架构、已存在安装、认证和网络要求。用官方支持的最小真实操作验证，不以退出码为唯一依据。
能够安全、可逆且不需要用户秘密的信息配置，直接完成并报告改动；涉及授权、API Key、付费、不可逆覆盖或用户偏好的设置，给出逐步操作并停在需要用户输入的位置。
5. 生成说明书
安装评估、方案选择、冲突分析、安装日志和验证证据只用于当前安装流程，不写进给用户日常查阅的说明书。
默认生成 Word（.docx）。只有用户明确要求 Markdown，或明确选择同时保留两种格式时，才生成 .md。不得在 Word 依赖缺失时静默降级为 Markdown；应明确说明缺少的依赖并处理后再生成。调用 scripts/gen_tool_manual.py 时只提供：
{
"name": "工具名",
"function_desc": "这个工具具体能做什么",
"usage": ["经过官方资料或实测确认的使用步骤"],
"special_notes": ["确实影响使用的特殊限制或注意事项"],
"sources": ["用于内部核验的官方来源，不渲染进说明书"]
}
最终说明书只允许出现：
- 作用；
- 使用方法；
- 特殊注意事项——仅当
special_notes 非空时显示，否则整节省略。
usage 必须来自官方资料或实际验证，不能为空；不从工具名派生 slash 命令、口语触发词、CLI 或 MCP 调用。生成后必须回读 Word 文档，确认文件可打开、章节精简、中文正常且没有安装审计内容。
宿主 adapter 约定
新增某一宿主支持前，在 adapters/README.md 记录并验证：识别信号、支持工具形态、作用域和写入位置、配置命令、重启/发现方法、卸载方式、系统/shell 差异及官方来源。未通过这道证据门槛前不得声称支持。
边界
- 不安装身份未确认的项目；不把项目名、示例或安装命令伪装成触发词。
- 不跳过冲突/价值判断或用户的方案选择。
- 不硬编码宿主、路径、操作系统、代理、镜像或工作区。
- 不把“安装成功”误报为“配置完成”或“可用”。
