ln-012-mcp-configurator

路径： 文件路径（references/）相对于此技能目录。

MCP 配置器

类型： L3 Worker 类别： 0XX 共享

调用方式与 Agent 无关。目标界面特定于 Claude：此技能用于配置 Claude Code MCP 设置、钩子／样式同步、权限，以及 Claude Code IDE 扩展的权限模式。

---

必须阅读

必须阅读： 加载 references/coordinator_summary_contract.md、references/environment_worker_runtime_contract.md 和 references/worker_runtime_contract.md

目标 MCP 是否可用并非此 Worker 的前提条件。如果某个服务尚未连接，请使用配置文件、软件包元数据和 CLI 状态继续完成注册和清理工作；如果无法在没有 MCP 的情况下运行，则将提供方检查或实时验证报告为 skipped。

输入／输出

方向	内容
输入	操作系统信息、dry_run 标志、可选的 apply_ide_override 标志（默认为 false — 若未提供，则 Phase 6b 仅检测）、可选的 runId、可选的 summaryArtifactPath
输出	结构化摘要信封，其中 payload.status = completed / skipped / error，并在 changes / detail 中提供各服务的结果，在 payload.ide_extension 中提供 IDE 扩展状态

如果提供了 summaryArtifactPath，请将相同的摘要 JSON 写入该路径。若未提供，则以内联方式返回摘要，并保持完全独立运行。如果未提供 runId，则在输出摘要信封前生成一个独立的 run_id。

运行时

运行时系列：environment-worker-runtime

阶段配置：

1. PHASE_0_CONFIG
2. PHASE_1_CHECK_STATUS_AND_VERSION
3. PHASE_2_REGISTER_AND_CONFIGURE
4. PHASE_3_VERIFY_GRAPH_PROVIDER_DEPS
5. PHASE_4_HOOKS_AND_OUTPUT_STYLE
6. PHASE_5_GRAPH_INDEXING
7. PHASE_6_MIGRATE_ALLOWED_TOOLS
8. PHASE_7_PERMISSION_SURFACES
9. PHASE_8_WRITE_SUMMARY
10. PHASE_9_SELF_CHECK

运行时规则：

• 输出 summary_kind=env-mcp-config
• 独立运行时生成自己的 run_id，并写入默认的 Worker 系列产物路径
• 托管运行时必须同时提供 runId 和 summaryArtifactPath，并且必须将摘要写入所提供的确切路径
• 在终止运行前，始终先写入经过验证的摘要产物

输出契约

始终根据以下内容构建结构化的 env-mcp-config 摘要信封：

• references/coordinator_summary_contract.md
• references/environment_worker_runtime_contract.md

载荷字段：

• servers
• permissions
• ide_extension
• hooks_synced
• output_style_synced
• allowed_tools_migrated
• graph_provider_status
• status

---

服务注册表

两种传输类型：stdio（本地进程）和 HTTP（云端端点）。

服务	传输	安装	必需	API 密钥
hex-line	stdio	npx -y @levnikolaevich/hex-line-mcp	是	否
hex-ssh	stdio	npx -y @levnikolaevich/hex-ssh-mcp	否	否
hex-graph	stdio	npx -y @levnikolaevich/hex-graph-mcp	否	否
hex-research	stdio	npx -y @levnikolaevich/hex-research-mcp	否	否
context7	HTTP	https://mcp.context7.com/mcp	是	可选
Ref	HTTP	https://api.ref.tools/mcp	是	是（提示用户）
linear	HTTP	https://mcp.linear.app/mcp	询问用户	否（OAuth）

---

工作流

Check Status & Version → Register & Configure → Verify Graph Provider Deps → Hooks → Permissions → IDE Extension Mode → Migrate → Report

阶段 1：检查状态和版本

智能安装：检查 MCP 状态和软件包是否有差异。npx -y 会积极缓存——已连接的服务仍可能由较旧的缓存软件包提供支持。

步骤 1a：检查 MCP 服务状态

运行 claude mcp list -> 解析每个 hex 服务：

服务	状态	操作
已注册 + 已连接	正常工作	检查版本（步骤 1b）
已注册 + 已断开连接	异常	重新注册（阶段 2）
未注册	缺失	在阶段 2 注册

步骤 1b：检查已连接的 hex- 服务版本*

对每个已连接的已发布 hex 服务，并行运行：

npm view @levnikolaevich/${PKG} version 2>/dev/null

然后比较 npm 最新版本与正在运行的本地版本：

1. npx 缓存探测： npm config get cache -> 扫描 {cacheRoot}/_npx/**/node_modules/@levnikolaevich/${PKG}/package.json -> 按 semver/mtime 选择最新版本

使用 npx 缓存版本。如果探测没有返回结果，则报告 running=unknown，并将该服务视为建议刷新，而不是声称它是最新版本。

注意：已发布的 hex 软件包通过 npx -y 运行，而不是全局安装。绝不要探测全局 npm 路径。

npm 最新版本	本地缓存版本	操作
相同	相同	跳过
较新	较旧	标记为“需要更新” -> 阶段 2 重新注册
未知	任意	警告，继续

跳过条件：

条件	操作
disabled: true	跳过
dry_run: true	显示计划执行的命令
已连接 + 本地缓存版本与 npm 最新版本相同	跳过，报告版本

第 2 阶段：注册和配置

一次完成：使用第 1 阶段的状态（不要重新运行 claude mcp list）-> 移除不受支持的服务 -> 注册/更新 -> 验证。

1. 复用第 1 阶段的状态 — 第 1a 步中的服务映射已包含注册状态和连接状态
   • 后备方案（仅限独立运行）：读取 ~/.claude.json + ~/.claude/settings.json
2. 移除不受支持的服务：

不受支持的服务	操作
hashline-edit	如果发现则移除
pencil	如果发现则移除
lighthouse	如果发现则移除
playwright	如果发现则移除
browsermcp	如果发现则移除

3. 注册缺失的服务或更新过时的服务：
   • 如果已配置、已连接且缓存的本地版本匹配 -> 跳过
   • 如果已连接但版本过时 -> 移除并重新添加（强制 npx 获取最新版本）
   • 如果 dry_run: true -> 显示计划执行的命令
   • 如果是 linear -> 询问用户：“你使用 Linear 吗？” -> 如果回答否 -> 跳过

注册命令（依赖操作系统的前缀）：

操作系统	前缀	原因
Windows（bash/MSYS2）	MSYS_NO_PATHCONV=1 claude mcp add ... -- cmd /c npx	MSYS2/Git Bash 会将参数中的 /c 转换为 C:/。MSYS_NO_PATHCONV=1 可阻止此转换
Windows（PowerShell/cmd）	cmd /c npx	原生 Shell 中不存在路径转换问题
macOS / Linux	npx	直接执行

服务	命令（Windows bash — 始终添加 MSYS_NO_PATHCONV=1 前缀）
hex-line	MSYS_NO_PATHCONV=1 claude mcp add -s user hex-line -- cmd /c npx -y @levnikolaevich/hex-line-mcp
hex-ssh	MSYS_NO_PATHCONV=1 claude mcp add -s user hex-ssh -- cmd /c npx -y @levnikolaevich/hex-ssh-mcp
hex-graph	MSYS_NO_PATHCONV=1 claude mcp add -s user hex-graph -- cmd /c npx -y @levnikolaevich/hex-graph-mcp
hex-research	MSYS_NO_PATHCONV=1 claude mcp add -s user hex-research -- cmd /c npx -y @levnikolaevich/hex-research-mcp
context7	claude mcp add -s user --transport http context7 https://mcp.context7.com/mcp
Ref	claude mcp add -s user --transport http Ref https://api.ref.tools/mcp
linear	claude mcp add -s user --transport http linear-server https://mcp.linear.app/mcp

4. 验证：claude mcp list -> 检查所有已注册的服务是否显示为 Connected。这是第二次也是唯一一次 claude mcp list 调用（变更后的验证）。重试并报告失败情况。

Windows MSYS2 路径验证（win32 上必须执行）： 注册后，读取 ~/.claude.json -> 验证每个 hex 服务的 args[0] 是 "/c"，而不是 "C:/"。 如果路径有误：通过 mcp__hex-line__edit_file 修复（使用 set_line 将参数设为 "/c"）。

错误处理：

错误	响应
未找到 claude CLI	失败，报告“Claude CLI 不在 PATH 中”
服务已存在	跳过，报告“已配置”
添加后连接失败	警告，报告 claude mcp list 中的详细信息
缺少 API 密钥（Ref）	提示用户提供密钥；如果用户拒绝则跳过

第 2b 阶段：验证图提供程序依赖项

必须读取： 加载 references/hex_graph_provider_matrix.md 和 references/stack_detection.md。

注册并连接后，仅验证提供更完整 MCP 功能所需的额外系统二进制文件或软件包。假设项目已有自己的运行时和应用依赖项。本阶段不安装项目依赖项、框架软件包或运行时。

第 1 步：确定哪些服务已连接 复用第 2 阶段的验证状态。仅检查已连接的 hex-* 服务的依赖项。

第 2 步：验证 hex-line-mcp 依赖项

依赖项	检查	必需	自动修复	后备方案
ripgrep	rg --version	是	参阅安装表	grep_search 失败
git	git --version	否	仅告知	changes 工具已禁用

按平台安装 ripgrep：

平台	命令
Linux（apt）	sudo apt-get install -y ripgrep
Linux（yum）	sudo yum install -y ripgrep
macOS	brew install ripgrep
Windows（winget）	winget install BurntSushi.ripgrep.MSVC
Windows（scoop）	scoop install ripgrep
备用方案（npm）	npm exec --yes -- @vscode/ripgrep-postinstall

如果 rg --version 失败：询问用户是否要自动安装（建议使用适合其平台的命令）。如果用户拒绝，发出 WARN，但继续操作——hex-line 将退化为使用 grep。

步骤 2a：hex-line 的行尾风险提示

检查仓库和用户的行尾策略，但不要在此处重写：

• .gitattributes 中的 eol= / text=auto
• .editorconfig 中的 end_of_line
• git config --get core.autocrlf
• git config --get core.eol
• git config --get core.safecrlf

当仓库策略和用户工作树策略可能会在常规编辑期间导致行尾变动时，报告 WARN。这仅为提示——不要在 ln-012 中自动编辑仓库策略文件。

步骤 3：检测 hex-graph 当前项目使用的语言

仅从当前项目根目录检测：

1. 如果存在，检查 docs/project/tech_stack.md
2. 检查项目根目录中的标记文件
3. 扫描源文件扩展名作为后备方案

仅使用框架标记来确认语言：

框架提示	语言
FastAPI、Django、Flask	Python
ASP.NET Core	C#
Laravel	PHP
React、Next.js、Express、NestJS	JavaScript / TypeScript

如果未检测到与 hex-graph 相关的语言，则跳过可选的提供程序检查并报告 SKIP。

步骤 4：验证 hex-graph-mcp 的图专用提供程序和 SCIP 导出器

使用 hex-graph-mcp 中的 MCP 工具 install_graph_providers 作为事实来源：

• 首先使用 mode: "check" 调用它
• 将其输出的 instructions_for_agent 用作修复说明
• 只有在用户同意后，才使用 mode: "install" 再次调用
• 将下表视为参考策略，而非第二个实现来源

检测到的项目语言	工具	检查	必需	自动修复	后备方案
JavaScript / TypeScript	无	无	否	无	已提供内嵌 TypeScript 精确覆盖和 SCIP 导出
Python	basedpyright	basedpyright-langserver --version	否	pip install basedpyright	跳过 Python 精确分析
Python	scip-python	scip-python index --help	否	Windows：npm install -g github:levnikolaevich/scip-python#fix/windows-path-sep-regex；macOS/Linux：npm install -g @sourcegraph/scip-python	跳过 Python export_scip
C#	csharp-ls	csharp-ls --version	否	dotnet tool install -g csharp-ls	跳过 C# 精确分析
C#	scip-dotnet	scip-dotnet --help	否	dotnet tool install -g scip-dotnet	跳过 C# export_scip
PHP	phpactor	phpactor --version	否	针对项目的 PHP 安装路径	跳过 PHP 精确分析
PHP	scip-php	scip-php --help 或 php vendor/bin/scip-php --help	否	composer global config repositories.levnikolaevich-scip-php vcs https://github.com/levnikolaevich/scip-php，然后执行 composer global require davidrjenni/scip-php:dev-fix/windows-runtime-fixes --prefer-source	跳过 PHP export_scip

对于 hex-graph，仅考虑图专用提供程序和可选的 SCIP 导出器：

• 检测到相应语言时，务必安装或推荐 basedpyright、csharp-ls、phpactor、scip-python、scip-dotnet 和 scip-php
• 在上游 Windows 修复发布前，务必优先使用打过补丁的 scip-python 安装包
• 打过补丁的 Python SCIP 二进制文件位于默认 PATH 之外时，务必提及 HEX_GRAPH_SCIP_PYTHON_BINARY
• 项目本地 Composer 安装受阻，或上游二进制文件生成空产物时，务必优先使用隔离的、打过补丁的 scip-php 分支导出 PHP SCIP
• 不要安装 python、.NET、php、fastapi、django、laravel、nestjs 或任何项目依赖
• 不要仅为框架叠加层安装任何内容；第 4 阶段的框架支持基于解析器和约定
• 执行任何提供方安装命令前，先征求用户同意

第 5 步：验证 hex-ssh-mcp 依赖

无需系统依赖（纯 JS ssh2）。跳过。

第 6 步：报告依赖表

打印包含以下列的表格：服务器 | 依赖项 | 状态 | 操作。

状态	含义
OK	可用且正常运行
INSTALLED	原先缺失，已自动安装
WARN	缺失，用户拒绝安装
SKIP	对检测到的项目语言而言不需要
FAIL	必需，但无法安装

错误处理：

错误	响应
必需依赖缺失 + 用户拒绝	WARN，继续运行，但功能降级
自动安装失败	WARN，显示手动安装说明
可选依赖缺失	INFO，在报告中注明

对于 hex-graph，还要报告用于提供方/导出器检查的检测到的语言。

第 3 阶段：钩子和输出样式 [CRITICAL]

不要调用 setup_hooks。hex-line 现在会在 MCP 服务启动时自动同步钩子和输出样式。

完成所有第 2 阶段注册后：

1. 触发一次无害的 hex-line 调用以启动服务，例如 mcp__hex-line__inspect_path({ path: "{project_path}" })
2. 验证下方的启动同步结果

钩子（位于 ~/.claude/settings.json）：

1. PreToolUse 钩子 — 将内置的 Read/Edit/Write/Grep/Glob 重定向到对应的 hex-line 工具（Glob -> inspect_path(pattern=...)）
2. PostToolUse 钩子 — 压缩冗长的工具输出（RTK 筛选器）
3. SessionStart 钩子 — 注入 MCP 工具偏好提醒
4. disableAllHooks： 验证钩子同步完成后，读取 ~/.claude/settings.json，设置 disableAllHooks: false（合并写入，保留所有其他字段），然后写回。这里这样做是合适的，因为用户明确调用了设置流程，并希望启用钩子。autoSync 不会管理此标志——它只同步钩子文件内容和条目。

输出样式： 5. 将 output-style.md 复制到 ~/.claude/output-styles/hex-line.md 6. 如果当前未启用任何样式，则设置 outputStyle: "hex-line"（保留现有样式）

**验证：**首次调用 hex-line 工具后，确认以下所有事项：

• ~/.claude/settings.json 包含 3 个 hex-line 钩子条目，且使用当前命令路径
• disableAllHooks: false（由此技能显式设置，而非由 autoSync 设置）
• ~/.claude/output-styles/hex-line.md 存在且与软件包内容一致
• 仅当此前未启用其他样式时，才设置 outputStyle: "hex-line"

**Hex-line 工作流提醒：**同步的输出样式必须说明以下所有事项：

• 在同一文件的后续编辑中，将 revision 作为 base_revision 传递
• 对同一文件进行延迟或混合工具的后续编辑前，运行 verify
• 直接复用 retry_edit、retry_edits、retry_checksum 和 retry_plan
• 将行尾策略视为保留的文件状态，不要让 edit_file 悄悄对其进行规范化

**注意：**autosync 具备幂等性。之后每次启动 hex-line 时，都会重新检查已安装的钩子和样式内容，并且仅在内容发生偏差时更新。

阶段 4：图索引

注册 hex-graph 并确认其已连接后：

1. mcp__hex-graph__index_project({ path: "{project_path}" }) — 构建初始代码知识图谱
2. 如果后续基于图谱的读取或编辑看起来已过时，请重新运行 mcp__hex-graph__index_project({ path: "{project_path}" }) — 此索引流程具有幂等性，且只会刷新已更改的文件

如果 hex-graph 未注册或未连接，则跳过。

阶段 5：迁移 allowed-tools [CRITICAL]

扫描项目命令和技能，在 allowed-tools frontmatter 中用 hex-line 对应工具替换内置工具。

工具映射：

内置工具	Hex 对应工具
Read	mcp__hex-line__read_file
Edit	mcp__hex-line__edit_file
Write	mcp__hex-line__write_file
Grep	mcp__hex-line__grep_search
Glob	mcp__hex-line__inspect_path

步骤：

1. 使用 mcp__hex-line__inspect_path(path=".claude/commands", pattern="*.md", max_entries=0) 查找 .claude/commands/*.md，并使用 mcp__hex-line__inspect_path(path=".claude/skills", pattern="SKILL.md", max_entries=0) 查找 .claude/skills/*/SKILL.md
2. 对每个文件：解析 YAML frontmatter，提取 allowed-tools
3. 对每个映射项： a. 如果存在内置工具且不存在对应的 hex 工具 -> 添加对应的 hex 工具，并移除内置工具（Read 和 Bash 除外） b. 如果存在内置工具且已存在对应的 hex 工具 -> 移除内置工具（Read 和 Bash 除外） c. 保留所有不在替换表中的现有 mcp__* 工具
4. 写回更新后的 frontmatter（保留原有引号样式）

跳过条件：

条件	操作
没有 .claude/ 目录	跳过整个阶段
文件没有 allowed-tools	跳过该文件
已存在所有对应的 hex 工具	跳过该文件，并报告“已迁移”
dry_run: true	显示计划进行的更改

阶段 6：授予权限

指令文件和 MCP Tool Preferences 内容由 ln-014-agent-instructions-manager 管理。此技能不得创建或重写 CLAUDE.md 或 AGENTS.md。

确保内置工具和 MCP 服务前缀已添加到 ~/.claude/settings.json -> permissions.allow[]。

内置工具（确保存在）：

工具	权限条目
Bash	Bash
Read	Read
Write	Write
Edit	Edit
Grep	Grep
WebSearch	WebSearch
WebFetch	WebFetch

MCP 服务（按配置情况）：

服务	权限条目
hex-line	mcp__hex-line
hex-ssh	mcp__hex-ssh
hex-graph	mcp__hex-graph
hex-research	mcp__hex-research
context7	mcp__context7
Ref	mcp__Ref
linear	mcp__linear-server

1. 读取 ~/.claude/settings.json（如果不存在则创建：{"permissions":{"allow":[]}}）
2. 合并现有条目： 对于每个通用工具（Bash、Read、Write、Edit、Grep、WebSearch、WebFetch 以及每个 mcp__{name}）：
   • 如果存在具体变体（例如 Bash(gh repo:*)、Bash(node ...)、WebFetch(domain:docs.github.com)），则移除这些变体 — 通用条目涵盖所有情况
   • 模式：entry.startsWith("Tool(") → 如果将添加通用的 Tool，则移除该条目
3. 添加尚未存在的通用条目
4. 写回（JSON 缩进 2 个空格）

**幂等性：**跳过现有通用条目。仅将具体子条目合并为通用条目。

阶段 6b：验证 IDE 扩展权限模式

Claude Code IDE 扩展（Cursor / VSCode）有自己的 claudeCode.initialPermissionMode 设置。当 Claude 通过 IDE 运行时，该设置会覆盖 ~/.claude/settings.json 中的 permissions.defaultMode。默认值为 "default" — 这会在不提示的情况下忽略 .claude/settings.local.json 中任何项目级别的 bypassPermissions。若要在 IDE 中运行时实际启用绕过权限模式，必须同时设置两个扩展设置。 此阶段以检测为先。 未经用户明确同意，不会修改 IDE 设置，因为权限模式属于安全决策，且各 IDE 的设置因厂商而异。

步骤 1：检测已安装的 Claude Code IDE 扩展

IDE	扩展目录	用户设置路径（Windows）	用户设置路径（macOS）	用户设置路径（Linux）
Cursor	~/.cursor/extensions/anthropic.claude-code-*	%APPDATA%/Cursor/User/settings.json	~/Library/Application Support/Cursor/User/settings.json	~/.config/Cursor/User/settings.json
VSCode	~/.vscode/extensions/anthropic.claude-code-*	%APPDATA%/Code/User/settings.json	~/Library/Application Support/Code/User/settings.json	~/.config/Code/User/settings.json

对每个 IDE：在扩展目录中使用 glob 匹配 anthropic.claude-code-*。如果至少匹配到一项，则表示已安装该扩展。

步骤 2：读取扩展中的 package.json，枚举 claudeCode.* 设置

相关键（已根据扩展 package.json 中的 contributes.configuration.properties 核实）：

设置键	类型	默认值	效果
claudeCode.initialPermissionMode	字符串枚举	"default"	在会话开始时设置 --permission-mode 标志。枚举值：default、acceptEdits、plan、bypassPermissions
claudeCode.allowDangerouslySkipPermissions	布尔值	false	硬性门槛——必须为 true，bypassPermissions 才会实际生效。这是 Anthropic 为 IDE 环境设置的明确保护措施

步骤 3：读取每个已检测到的 IDE 的用户设置 JSON，并报告当前状态

检测到的状态	实际行为	报告为
initialPermissionMode 缺失或为 "default"，且 allowDangerouslySkipPermissions 缺失或为 false	使用标准的基于提示的权限机制，忽略项目的 defaultMode	default-prompt
initialPermissionMode = "acceptEdits"	文件操作自动批准，Bash 操作仍会提示	accept-edits
initialPermissionMode = "plan"	强制进入计划模式（不执行操作）	plan-only
initialPermissionMode = "bypassPermissions"，且 allowDangerouslySkipPermissions = true	绕过权限机制已启用	bypass-active
initialPermissionMode = "bypassPermissions"，且 allowDangerouslySkipPermissions = false	配置错误——用户希望绕过权限，但门槛未开启；将回退为默认设置	bypass-blocked

报告中始终要包含一行说明：通过 IDE 扩展运行时，.claude/settings.local.json 中的 defaultMode 为何会被静默忽略。

步骤 4：与 .claude/settings.json 和 .claude/settings.local.json defaultMode 交叉核对

如果用户的项目设置声明 permissions.defaultMode = "bypassPermissions"，但 IDE 扩展处于 default-prompt 或 bypass-blocked 状态，则在摘要中发出 WARN，说明设置被覆盖：

WARN: 项目 .claude/settings.local.json 声明了 defaultMode: bypassPermissions，但 {IDE} 的 Claude Code IDE 扩展会在会话开始时强制设置 --permission-mode {detected}。通过 IDE 运行时，项目设置会被忽略。若要使两者一致，请以 apply_ide_override=true 运行此技能并在提示时确认，或手动在 {settings_path} 中设置 claudeCode.initialPermissionMode 和 claudeCode.allowDangerouslySkipPermissions。

步骤 5：可选的修复措施（仅在用户明确同意后执行）

只有调用方传入 apply_ide_override=true 时（这是一个与主 dry_run 不同的独立标志），此阶段才会写入 IDE 设置。即使传入了该标志，技能也必须向用户提出一个确认问题，并准确列出将在哪个文件中更改哪些键。

应用更改时：

1. **先备份：**在写入前将 settings.json 复制为 settings.json.bak.{timestamp}
2. **读取 → 深度合并 → 写入：**保留所有其他 claudeCode.* 键（preferredLocation、useTerminal、respectGitIgnore 等）以及所有非 claudeCode.* 键
3. 仅写入由目标模式决定的两个键：
   • 对于 bypassPermissions：设置 claudeCode.allowDangerouslySkipPermissions: true 和 claudeCode.initialPermissionMode: "bypassPermissions"
   • 对于 acceptEdits：设置 claudeCode.initialPermissionMode: "acceptEdits"（无需设置 gate）
   • 对于 default：移除这两个键（或分别设为 false / "default"）
4. **提示完整重启：**打印 "需要重启 IDE（完全退出后重新打开，而非重新加载窗口）——扩展只会在激活时读取设置"
5. **在摘要中记录：**包括修改前后的值、备份路径以及明确的用户同意时间戳

跳过条件：

条件	操作
未找到 Claude Code IDE 扩展	跳过整个阶段，并报告 no-ide
dry_run: true	仅检测并报告，不写入（与默认行为相同）
未提供 apply_ide_override 标志	仅检测并报告，不提示用户
用户拒绝修复提示	跳过写入，并在摘要中记录该决定
项目 .claude/settings*.json 未声明 defaultMode	信息：报告扩展状态，但不发出警告（无需解决冲突）

此阶段默认优先检测的原因：

• IDE 设置因 IDE 厂商和用户而异——在多台机器上自动修改设置会造成侵扰
• bypassPermissions 是一项与安全相关的选择；Anthropic 明确要求在 IDE 环境中启用 allowDangerouslySkipPermissions 才能使用此模式（该模式面向没有互联网连接的沙盒）
• 用户可能确实希望在不同 IDE 中使用不同模式（例如，日常工作时在 Cursor 中使用 acceptEdits，在单独的 VSCode 配置文件中使用 bypassPermissions 进行沙盒自动化）
• 符合宿主项目记忆中禁止修改 Agent 配置的规则：始终检测，仅在明确同意后写入

阶段 7：报告

状态表：

MCP Configuration:
| Server    | Transport | Version | Status        | Permission | Detail                  |
|-----------|-----------|---------|---------------|------------|-------------------------|
| hex-line  | stdio     | 1.5.0   | configured    | granted    | npx package (hex-line-mcp) |
| hex-ssh   | stdio     | 1.2.0   | updated       | granted    | was 1.1.6, now 1.2.0     |
| hex-research | stdio  | 0.1.0   | configured    | granted    | npx package (hex-research-mcp) |
| context7  | HTTP      | —       | configured    | granted    | mcp.context7.com        |
| Ref       | HTTP      | —       | configured    | granted    | api.ref.tools (key set) |
| linear    | HTTP      | —       | skipped       | skipped    | user declined           |

IDE Extension Permission Mode:
| IDE     | Extension Version | initialPermissionMode | allowDangerouslySkipPermissions | Effective State | Conflict with project defaultMode |
|---------|-------------------|-----------------------|---------------------------------|-----------------|-----------------------------------|
| Cursor  | 2.1.92            | bypassPermissions     | true                            | bypass-active   | aligned                           |
| VSCode  | (not installed)   | —                     | —                               | no-ide          | n/a                               |

---

关键规则

1. 只能通过批准的路径写入。 使用 claude mcp add 注册服务。仅在设置权限（permissions.allow[]），或自动同步失败后需要根据明确要求修正钩子／样式时，才写入 ~/.claude/settings.json
2. 添加后进行验证。 注册后始终运行 claude mcp list，确认连接正常
3. 添加可选服务前先征求同意。 使用 Linear 需要获得用户明确同意
4. 所有 hex MCP 均使用 npx -y。 绝不使用 npm i -g——npx 可隔离进程，并避免 Windows 上出现 EBUSY。在 Windows 上，使用 cmd /c npx 包装软件包（参见第 2 阶段的操作系统前缀表）。
5. 移除不受支持的服务。 清理注册表中已不再列出的服务
6. 授予权限。 注册后，将 mcp__{server} 添加到用户设置中
7. 尽量减少调用 claude mcp list 的次数。 第 1 阶段运行一次（发现服务）。第 2 阶段复用这些数据。只有第 2 阶段的步骤 4 会再次运行（变更后验证）。总计最多调用 2 次
8. 始终检查 npm 版本漂移。 已连接不等于已更新。跳过更新前，请比较 npm 上的最新版本与本地缓存的最新 npx 软件包版本
9. 确保 MSYS2 路径安全。 在使用 Git Bash/MSYS2 的 Windows 上，始终在 claude mcp add 前加上 MSYS_NO_PATHCONV=1。注册后，确认 .claude.json 中的 args[0] 是 "/c"，而不是 "C:/"。如果路径已损坏，请直接修复
10. 安装后验证图谱专用依赖。 第 2 阶段注册后，检查系统二进制文件、hex-line 的图谱专用可选提供程序，以及检测到的项目语言对应的可选 SCIP 导出器。仅在用户同意后自动安装。切勿在此处安装项目运行时或框架软件包。
11. 报告行尾（EOL）变更风险，不要隐瞒。 如果 .gitattributes、.editorconfig 或 Git 配置表明工作树的行尾可能被重写，请明确警告，不要在此处悄悄更改仓库策略。
12. 以非破坏方式写入配置。 始终先读取，再合并，然后编辑。绝不从头覆盖配置文件。保留不属于此技能管理的所有键和部分。
13. 先检测 IDE 扩展设置。 第 6b 阶段读取 Cursor / VSCode 用户设置中的 claudeCode.* 键，并报告实际生效的权限模式，但除非 apply_ide_override=true 且用户明确提示确认，否则绝不写入 IDE 设置。IDE 设置因厂商而异，修改 bypassPermissions 属于安全决策，必须由用户本人决定。

反模式

不要	应该
将任意字段写入 ~/.claude.json	对服务使用 claude mcp add；依靠 hex-line 启动时自动同步钩子和样式
添加后跳过验证	每次修改后都检查 claude mcp list
自动添加可选服务	就 Linear 和其他可选服务询问用户
保留不受支持的服务	移除 hashline-edit、pencil 等
计算令牌预算	这不属于此工作线程的职责
在每个阶段都运行 claude mcp list	在阶段 1 运行一次，在阶段 2 复用，修改后再验证一次
认为已连接就表示已是最新版本	检查 npm view 版本与最新缓存的 npx 包版本
认为注册后钩子和样式立即就绪	触发一次无害的 hex-line 工具调用，然后验证自动同步结果
在 Windows bash 中运行 claude mcp add 时未设置 MSYS_NO_PATHCONV	始终使用 MSYS_NO_PATHCONV=1 claude mcp add ...，或之后验证并修正参数
跳过 hex-graph 的提供方验证	先检测项目语言，再验证相关的图专用提供方和 SCIP 导出器
自动安装项目、框架或运行时包	将此阶段限制为 MCP 相关的图提供方和 SCIP 导出器，并在安装前询问用户
仅用已知字段覆盖整个配置文件	读取现有配置 → 仅深度合并自有字段 → 写回修改
因项目提出要求，就悄悄将 claudeCode.initialPermissionMode 切换为 bypassPermissions	检测并警告此覆盖；写入 IDE 设置前，必须同时满足 apply_ide_override=true 并获得用户明确确认
设置 initialPermissionMode = "bypassPermissions"，却不同时设置 allowDangerouslySkipPermissions = true	两个键必须同时设置——缺少这个门控条件时，该模式会悄悄降级为默认值
将 IDE 的 bypassPermissions 当作 Codex CLI 默认设置的替代方案	将 Codex 执行默认设置的管理工作交由 ln-013-config-syncer 处理
因为权限相关，就由此工作线程修改 ~/.codex/config.toml	将实际的 Codex CLI 对齐工作交由 ln-013-config-syncer 处理
更改 IDE 设置后告诉用户使用 Reload Window	始终告诉用户完全退出并重新打开——扩展程序只会在激活时读取设置，不会在 Reload Window 时读取

---

完成定义

• 已安装 MCP 包，并根据 npm 注册表验证版本（阶段 1）
• 已注册缺失的服务，并确认连接成功（阶段 2）
• 已使用最新版本重新注册过时的服务（阶段 2）
• 已验证图专用依赖：ripgrep 可用，已报告检测到的 hex-graph 提供方和 SCIP 导出器（阶段 2b）
• 首次启动 hex-line 后钩子已自动同步（PreToolUse、PostToolUse、SessionStart、ConfigChange、PermissionDenied），且 disableAllHooks: false（阶段 3）。MCP 配置说明：大型工具结果可将 _meta["anthropic/maxResultSizeChars"] 设为最高 500K（Claude Code 2.1.91）；-p 模式可使用 MCP_CONNECTION_NONBLOCKING 环境变量（2.1.89）；disableSkillShellExecution 设置可阻止技能执行 shell 命令（2.1.91）
• 已安装输出样式（阶段 3）
• 已为所有已配置的服务授予权限（阶段 6）
• 已检测已安装的 Cursor / VSCode 的 IDE 扩展权限模式；若其覆盖项目的 defaultMode，则已通过 WARN 报告（阶段 6b）。仅在 apply_ide_override=true 且用户同意时写入。
• 已迁移项目的 allowed-tools（阶段 5）
• 已显示带有版本列的状态表（阶段 7），其中包含 IDE 扩展权限模式行
• 已返回结构化摘要
• 已将摘要产物写入受管理或独立运行时路径

---

版本： 1.7.0 最后更新： 2026-04-07