setup-tool

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": ["用于内部核验的官方来源，不渲染进说明书"]
}

最终说明书只允许出现：

1. 作用；
2. 使用方法；
3. 特殊注意事项——仅当 special_notes 非空时显示，否则整节省略。

usage 必须来自官方资料或实际验证，不能为空；不从工具名派生 slash 命令、口语触发词、CLI 或 MCP 调用。生成后必须回读 Word 文档，确认文件可打开、章节精简、中文正常且没有安装审计内容。

宿主 adapter 约定

新增某一宿主支持前，在 adapters/README.md 记录并验证：识别信号、支持工具形态、作用域和写入位置、配置命令、重启/发现方法、卸载方式、系统/shell 差异及官方来源。未通过这道证据门槛前不得声称支持。

边界

• 不安装身份未确认的项目；不把项目名、示例或安装命令伪装成触发词。
• 不跳过冲突/价值判断或用户的方案选择。
• 不硬编码宿主、路径、操作系统、代理、镜像或工作区。
• 不把“安装成功”误报为“配置完成”或“可用”。