ln-010-dev-environment-setup

**路径：**文件路径（references/、../ln-*）均相对于此技能目录。

开发环境设置

**类型：**L2 领域协调器
**类别：**0XX 共享

用于环境设置的运行时支持协调器。运行时是执行的唯一事实来源。工作器输出是独立摘要，而非聊天文本。

必须阅读

执行前请加载以下文件：

• references/coordinator_runtime_contract.md
• references/environment_setup_runtime_contract.md
• references/environment_worker_runtime_contract.md
• references/coordinator_summary_contract.md
• references/agent_skill_roots_contract.md
• references/environment_state_contract.md
• references/environment_state_schema.json

MCP 服务是此工作流的目标，而非启动前提。如果某个服务已断开连接或不可用，请继续检查文件和命令行，并将相应界面报告为 disconnected 或 skipped，而不是让协调器失败。

适用场景

• 首次设置环境
• 安装或更新后 Agent/MCP 出现偏差
• Claude 和 Codex 之间的市场、插件、MCP 或 Codex 执行默认设置出现偏差
• 审核或修复指令文件

输入

参数	必填	默认值	说明
targets	否	both	claude、codex 或 both
dry_run	否	false	仅制定计划，不进行更改
plugins	否	agile-workflow	传递给 ln-013。使用明确的插件列表，或使用 all 请求所有市场插件。不会静默安装可选插件。
auto_install_providers	否	false	传递给 ln-013 MCP 提供方检查。为 false 时，仅检测提供方。
apply_ide_override	否	false	传递给 ln-012 第 6b 阶段。为 true 时，经用户明确同意后，ln-012 可能会将 claudeCode.initialPermissionMode 和 claudeCode.allowDangerouslySkipPermissions 写入 Cursor / VSCode 用户设置。为 false（默认值）时，第 6b 阶段仅进行检测，并报告偏差，不会更改 IDE 设置。

运行时

运行时系列：environment-setup-runtime

标识符：

• targets-{normalizedTargets}

阶段：

1. PHASE_0_CONFIG
2. PHASE_1_ASSESS
3. PHASE_1B_PROVIDER_SELECTION
4. PHASE_2_DISPATCH_PLAN
5. PHASE_3_WORKER_EXECUTION
6. PHASE_4_VERIFY
7. PHASE_5_WRITE_ENV_STATE
8. PHASE_6_SELF_CHECK

终止阶段：

• DONE
• PAUSED

阶段图

阶段 1：评估

收集一份环境快照：

• Agent 的可用性和版本
• MCP 注册/连接状态
• Hook 状态
• 市场/插件对齐状态
• Codex 技能根目录发现健康状况：活动根目录、缓存根目录、重复的技能名称、known_marketplaces.json 安装位置偏移、~/.codex/skills 下是否可见缓存、~/.codex/skills 是否是指向 ~/.claude/plugins 的整个根目录联接点，以及 approval_policy=never 和 sandbox_mode=danger-full-access 是否已对齐
• 图谱提供程序依赖状态：针对检测到的每种项目语言，检查是否已安装对应的图谱提供程序二进制文件（例如 Python 对应 basedpyright，C# 对应 csharp-ls）。如果已连接 hex-graph MCP，则使用 mcp__hex-graph__install_graph_providers，并设置 mode: "check"
• 图谱索引新鲜度：hex-graph 是否已连接，以及本会话中是否已为项目建立索引（仅检测，此处不建立索引）
• 指令文件状态
• .hex-skills/environment_state.json 中的禁用标志（如果存在）
• 任务管理提供程序可用性检测（Linear MCP、gh CLI / Projects v2 就绪状态、文件始终可用）；明确选择在阶段 1b 进行
• 研究工具检测（Ref → Context7 → websearch）
• git worktree 可用性
• Claude Code IDE 扩展状态：使用 glob 匹配 ~/.cursor/extensions/anthropic.claude-code-* 和 ~/.vscode/extensions/anthropic.claude-code-*。对于每个找到的扩展，从对应 IDE 的用户 settings.json 中读取 claudeCode.initialPermissionMode 和 claudeCode.allowDangerouslySkipPermissions。仅检测——此处不进行写入。

检查点负载：

• assess_summary

阶段 1b：跟踪器提供程序选择

用户选择任务跟踪器提供程序（linear、github、file）。选择会保存到 .hex-skills/environment_state.json -> task_management.provider，并由每个任务相关技能（ln-200、ln-220、ln-300、ln-401、ln-130 等）复用。

必须读取： 在此阶段前加载 references/tracker_provider_contract.md。

Codex exec --full-auto 无法在运行期间提示用户。选择必须通过运行时 pause + pending_decision + record-decision 进行（不得使用 AskUserQuestion）。

决策树：

1. 加载阶段 1 的可用性数据和环境状态中现有的 task_management。
2. 计算 available = filter([linear, github, file], byAvailability)：
   • 仅当 Linear MCP 服务已连接时，linear 才可用。
   • 仅当 gh auth status 正常、已检测到仓库，并且（尚无 project_number，或现有项目具有 Status 字段且包含全部 7 个规范选项：Backlog、Todo、In Progress、To Review、To Rework、Done、Canceled）时，github 才可用。
   • file 始终可用。
3. 如果已设置 task_management.provider 且 task_management.status == "active"：

node references/scripts/environment-setup-runtime/cli.mjs pause \
  --identifier {identifier} \
  --reason "Confirm tracker provider" \
  --payload '{"kind":"tracker_provider_confirmation","question":"Keep current tracker {provider}?","choices":["keep","switch"],"resume_to_phase":"PHASE_1B_PROVIDER_SELECTION"}'

通过 set-decision 恢复。选择 keep 时，复用现有提供程序。选择 switch 时，继续执行第 4 步。

4. 如果当前没有提供程序，或者用户选择了 switch，且 available.length > 1：

node references/scripts/environment-setup-runtime/cli.mjs pause \
  --identifier {identifier} \
  --reason "Select tracker provider" \
  --payload '{"kind":"tracker_provider_selection","choices":<available>,"resume_to_phase":"PHASE_1B_PROVIDER_SELECTION"}'

5. 如果 available.length == 1，不要暂停。使用 selected_by: "single_option" 自动选择，并写入原因（例如："Only file mode available because: Linear MCP disconnected, gh CLI not authenticated"）。
6. 阶段 1b 检查点：

node references/scripts/environment-setup-runtime/cli.mjs checkpoint \
  --identifier {identifier} \
  --phase PHASE_1B_PROVIDER_SELECTION \
  --payload '{"provider_selection":{"chosen":"<provider>","available":<available>,"reason":"<text>","selected_by":"user|single_option"}}'

检查点负载：

• provider_selection.chosen
• provider_selection.available
• provider_selection.reason
• provider_selection.selected_by

阶段 2：调度计划

构建选择性调度计划。只调用有任务的工作器。

调度优先级：

• 如果存在市场/插件偏差、Codex 发现违规（包括整个根目录联接点），或 Codex 执行默认值偏差，则 ln-013-config-syncer 必须先运行，之后才能报告 Codex 状态正常。
• 如果已注册 hex-graph MCP，且满足以下任一条件：(a) 检测到的项目语言缺少图提供程序依赖项；或 (b) 项目尚未建立索引，则 ln-012-mcp-configurator 必须运行，即使 MCP 注册已完成也不例外。ln-012 负责安装图提供程序依赖项（PHASE_3）和建立图索引（PHASE_5）。

工作器：

• ln-011-agent-installer
• ln-012-mcp-configurator
• ln-013-config-syncer
• ln-014-agent-instructions-manager

setup-environment 中打包但不会由 ln-010 调度的独立技能：

• ln-015-hex-line-uninstaller 仅可直接调用，因为它会移除现有的 Claude 侧集成界面。

检查点载荷：

• dispatch_plan

阶段 3：工作器执行

只调用选中的工作器。不要在工作器调用之间重新探测整个环境。

阶段 1 的评估是共享的发现快照。根据该快照生成子清单，并将其传入受管理的工作器运行。

对于每个选中的工作器：

• 计算确定性的 child_run_id
• 计算确切的 child_summary_artifact_path
• 委派前保存 child_run 元数据检查点
• 启动受管理的 environment-worker-runtime 子运行
• 使用 runId 和 summaryArtifactPath 调用工作器
• 读取工作器写入的产物
• 通过 environment-setup-runtime 记录结构化的工作器摘要

每个工作器都可独立运行，但阶段 3 始终使用受管理的传输方式。

预期摘要类型：

• env-agent-install
• env-mcp-config
• env-marketplace-align
• env-instructions

使用运行时的 record-worker 记录摘要。

阶段 4：验证

针对工作器运行后的状态执行定向验证：

• 健康检查
• Hook 状态
• 市场/插件和配置对齐状态
• Codex 技能发现和执行默认值状态（包括整个根目录联接点检测）
• 指令文件质量
• 运行时依赖项状态（ripgrep、可选语言服务器）
• 图提供程序依赖项健康状态（根据项目语言检查 basedpyright、scip-python 等）
• 图索引状态（已建立索引、已跳过或已过期）

检查点载荷：

• verification_summary

阶段 5：写入环境状态

将最终持久状态写入：

• .hex-skills/environment_state.json

包括所有已检测的部分：agents（包括对齐状态、市场插件、Codex 技能根目录健康状态和 Codex 执行默认值状态）、task_management、research、claude_md、assessment、hooks、ide_extension（阶段 1 中 Cursor / VSCode Claude Code 扩展状态，以及 ln-012 在阶段 6b 中进行的任何更改）。

规则：

• 运行时状态不是环境状态
• 工作器绝不写入 .hex-skills/environment_state.json
• 持久化前，依据共享架构验证输出

检查点载荷：

• env_state_written
• final_result

阶段 6：自检

确认：

• 所有必需的阶段检查点都存在
• 已记录已调度工作器的摘要
• 已写入最终状态文件，除非设置了 dry_run

检查点载荷：

• pass
• final_result

输出策略

运行时产物：

• .hex-skills/runtime-artifacts/runs/{run_id}/{summary_kind}/{identifier}.json

持久环境输出：

• .hex-skills/environment_state.json

不要混淆这两个层级。

Worker 调用（强制）

调用宿主技能： 必须委派 Skill(skill: "...", args: "...")。

• Claude：严格按所示方式调用 Skill 工具。
• Codex：如果没有 Skill 工具，则在可用技能中找到指定技能，读取其 SKILL.md，将 args 视为 $ARGUMENTS，执行该技能工作流，然后携带其结果／产物返回此处。
• 不要内联工作器逻辑，也不要在未执行目标技能的情况下标记工作器已完成。

阶段	工作器	上下文
3	ln-011-agent-installer	安装或更新 CLI Agent
3	ln-012-mcp-configurator	配置 MCP 服务、钩子、权限和 IDE 扩展权限模式（阶段 6b）
3	ln-013-config-syncer	安装／验证 Claude 和 Codex marketplace 插件、对齐 MCP 状态并对齐 Codex 默认设置
3	ln-014-agent-instructions-manager	创建并审查指令文件

node references/scripts/environment-worker-runtime/cli.mjs start --skill {worker} --identifier {childIdentifier} --manifest-file {childManifestPath} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}
node references/scripts/environment-setup-runtime/cli.mjs checkpoint --identifier {identifier} --phase PHASE_3_WORKER_EXECUTION --payload '{"child_run":{"worker":"{worker}","run_id":"{childRunId}","summary_artifact_path":"{childSummaryArtifactPath}"}}'
Skill(skill: "{worker}", args: "{workerArgs} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
Read {childSummaryArtifactPath}
node references/scripts/environment-setup-runtime/cli.mjs record-worker --identifier {identifier} --payload '{...environment worker summary...}'

apply_ide_override 仅将 ln-010 的输入传递给 ln-012。默认值 false 会让阶段 6b 保持在检测模式，并在评估摘要中将 IDE 偏差报告为 WARN；传入 true 后，ln-012 会提示用户并写入 Cursor／VSCode 设置。

plugins 和 auto_install_providers 仅将 ln-010 的输入传递给 ln-013。默认选择的插件为 agile-workflow；可选插件需要提供明确列表或使用 all。auto_install_providers=false 会让 MCP 提供方处理仅处于检测模式。

TodoWrite 格式（强制）

- Phase 1: Assess (pending)
- Phase 1b: Tracker provider selection (pending)
- Phase 2: Build dispatch plan (pending)
- Phase 3: Start child runtime, checkpoint child metadata, and run selected workers (pending)
- Phase 4: Verify final state (pending)
- Phase 5: Write environment_state.json (pending)
- Phase 6: Self-check (pending)

关键规则

• 运行时状态是执行的 SSOT。
• 恢复或续跑时不要依赖聊天记忆。
• 不要运行未选中的工作器。
• 不要在常规设置流程中分派 ln-015-hex-line-uninstaller；它是独立的清理工具。
• 不要在每个工作器运行后重复完整环境发现。
• 仅在阶段 5 写入 .hex-skills/environment_state.json。
• dry_run 可以以 final_result=DRY_RUN_PLAN 结束，并跳过最终状态写入。

完成标准

• 已通过带标识符的清单和状态启动运行时
• 已记录评估快照
• 已由用户明确选择跟踪器提供方，或确认仅有的一个选项
• 已记录分派计划检查点
• 每次委派前均已记录子工作器运行元数据检查点
• 已通过机器可读合约记录工作器摘要
• 已记录验证摘要检查点
• 已验证并写入 .hex-skills/environment_state.json，或明确标记为 DRY_RUN_PLAN
• 已通过自检

元分析

可选参考：仅当用户要求运行后元分析或按协议格式反思运行时，才加载 references/meta_analysis_protocol.md。

技能类型：domain-coordinator。收到请求时，在所有阶段完成后运行。使用协议格式在聊天中输出。

---

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