---
name: host-tool-setup
description: Use when 需要检查、规划、审批、验证或回滚 GitNexus、Serena、Context7、MCP 等宿主工具能力。
---

# Host Tool Setup

用于宿主工具初始化。它独立于 `target-repo-setup`：目标仓库初始化成功不代表宿主工具已安装或可用；计划已生成，不代表工具已安装。

## 使用原则

- `SKILL.md` 负责路由、边界和人读口径；详细安装依据放在 `references/tool-installation.md`。
- 确定性 runtime 只负责 `inspect`、`plan`、确认校验、本机状态报告、`verify` 和 `result.json`。
- `install`、`configure-mcp`、`activate`、`index`、`rollback` 只写 guidance-only 报告，指向安装 reference；它们不是自动安装器，不写用户级配置。
- 工具缺失时进入安装引导，不把 setup 判成失败。
- 计划已生成不代表工具已安装；确认继续也不代表工具可用。
- guidance-only 报告是中间证据，不是终点；如果宿主工具仍缺失或未验证，当前 agent 不得结束本轮 setup 回复。
- 真实安装、MCP 配置、Serena 初始化 / 激活和 GitNexus 索引由当前 agent 按 `references/host-tool-install-session.md` 与 `references/tool-installation.md` 先完成 `host-tool-plan-review.subagentPreReview` 并确认材料可提交人工审查，再向用户确认后执行。
- 到达 `host-tool-plan-review` 前，必须按 workflow 的 `subagentPreReview` 调度独立 reviewer 子代理；未取得“材料可提交人工审查”预审结论时，不得请求人工确认安装计划。

## 最短操作顺序

1. 运行 `inspect`，只读检查 PATH、Codex / Claude Code 配置标记和目标仓库证据目录。
2. 运行 `plan`，生成 `.nucleus/runs/<workflowRunId>/host-tool-setup/host-tool-plan.json` 和 `host-tool-plan.md`。
3. 读取 `references/host-tool-install-session.md` 和 `references/tool-installation.md`，根据 inspect 结果判断 GitNexus、Serena、Context7 需要哪种安装或配置引导。
4. 如需执行审批后动作，先运行 `approval --approval <approval.json>`。审批事实必须包含匹配的 `planHash` 和精确 `approvedScopes`。
5. `install`、`configure-mcp`、`activate`、`index`、`rollback` 会写引导报告；AI 按 reference 引导用户选择安装方式、配置位置和验证步骤。
6. 如果 `summary.md` 或 `result.json` 仍显示缺工具，当前 agent 必须先完成 `host-tool-plan-review.subagentPreReview` 并确认材料可提交人工审查，再继续安装确认和执行；不能把报告路径交给用户后结束。
7. 用户确认后，由当前 agent 执行安装、用户级配置、Serena 初始化 / 激活、GitNexus 索引等动作；该确认前必须已完成 `host-tool-plan-review.subagentPreReview` 并确认材料可提交人工审查。
8. 运行 `verify` 获取真实只读验证结果；缺工具或缺配置证据时返回 blocked。
9. 运行 `build-result`，先读 `summary.md`，机器事实源是 `result.json`；未通过时继续安装会话，直到 verify 通过或用户明确拒绝。

## 子命令

运行 `python3 scripts/host_tool_setup.py list-subcommands` 查看完整能力。

- 真实只读能力：`inspect`、`plan`、`verify`、`build-result`。
- 确认门控引导能力：`approval`、`install`、`configure-mcp`、`activate`、`index`、`rollback`。

## 审批范围

稳定 scope：

- `host-tool-install:gitnexus`
- `host-tool-install:serena`
- `host-tool-install:context7`
- `host-mcp-config:codex:gitnexus`
- `host-mcp-config:claude:gitnexus`
- `host-mcp-config:codex:serena`
- `host-mcp-config:claude:serena`
- `host-mcp-config:codex:context7`
- `host-mcp-config:claude:context7`
- `host-tool-activate:serena`
- `host-tool-index:gitnexus`
- `host-tool-verify`

不要新增泛化的 `install-plan` 或 `tool-readiness` scope。每个 scope 必须有 executor、report、verify 和 rollback 语义。

## 边界

- 证据只写 `.nucleus/runs/<workflowRunId>/host-tool-setup/**`。
- 不写 `docs/requirement/**`。
- 不把 `.autocode/**`、`.claude/notepads/**`、`docs/bugfix/**` 当事实源。
- 脚本不写用户级 `~/.codex`、`~/.claude`、MCP 配置或系统工具目录。
- 写用户级配置、安装 npm/uv 工具、激活 Serena 或建立 GitNexus 索引前，AI 必须按 reference 向用户说明将做什么并等待确认。
- `SUCCEEDED` 只能由真实 `verify` 通过产生；确认通过、计划生成或 guidance report 都不等于成功。
- 缺工具时不能停在 `NEEDS_HUMAN_REVIEW`、summary 或 guidance report；当前 agent 必须按安装会话 reference 先完成 `host-tool-plan-review.subagentPreReview` 并确认材料可提交人工审查，再继续安装确认和执行，然后重新运行 verify。

## 何时读取资源

- workflow step、artifact 和 result 语义：读 `references/workflow-contract.md`。
- scope、approval 和 planHash：读 `references/approval-scopes.md`。
- 缺工具后的 subagentPreReview、安装确认、执行和 verify 闭环：读 `references/host-tool-install-session.md`。
- GitNexus、Serena、Context7 安装和配置依据：读 `references/tool-installation.md`。
- 人读摘要和交付口径：读 `references/human-result.md`。
- 计划摘要模板来自 `assets/host-tool-plan-template.md`。
- Codex 入口纪律硬前置（可选）：读 `references/codex-entry-hook.md`，模板见 `assets/codex-session-start-hook.py` 与 `assets/codex-hooks.json`。Claude Code 由插件自带 SessionStart hook 自动注入，无需本引导；Codex 需用户开启 `[features] hooks = true` 并 `/hooks` 审批后才生效，属审批式可选增强，非 setup 默认动作。