monitor-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Monitor Configuration Assistant

显示器配置助手

Optimize multi-monitor setups on macOS through an interactive interview process. Discover connected displays, understand the user's physical arrangement and workflow, then configure optimal resolutions, refresh rates, and orientations.

通过交互式引导流程优化macOS上的多显示器设置。识别已连接的显示器，了解用户的物理布局和工作流程，然后配置最佳的分辨率、刷新率和显示方向。

Requirements

要求

macOS
```
displayplacer
```
CLI tool (will prompt to install if missing)

macOS
```
displayplacer
```
CLI工具（若缺失将提示安装）

Workflow

工作流程

Step 1: Ensure displayplacer is Installed

步骤1：确保已安装displayplacer

Check if displayplacer is available:

bash

command -v displayplacer || echo "NOT_INSTALLED"

If not installed, offer to install:

bash

brew install displayplacer

检查displayplacer是否可用：

bash

command -v displayplacer || echo "NOT_INSTALLED"

若未安装，提供安装选项：

bash

brew install displayplacer

Step 2: Discover Connected Displays

步骤2：识别已连接的显示器

Run displayplacer to get full display information:

bash

displayplacer list

Parse and present the displays in a clear format:

I found these displays:

1. [Type] - [Size] inch
   - Current: [resolution] @ [hz]Hz
   - Rotation: [degrees]
   - Position: [origin]

2. ...

Identify each display by:

Serial screen ID (persistent across reboots)
Type (MacBook built-in, external)
Size (27 inch, 32 inch, etc.)

运行displayplacer获取完整的显示器信息：

bash

displayplacer list

解析并以清晰格式展示显示器信息：

我检测到以下显示器：

1. [类型] - [尺寸]英寸
   - 当前设置：[分辨率] @ [hz]Hz
   - 旋转角度：[度数]
   - 位置：[原点坐标]

2. ...

通过以下信息识别每个显示器：

屏幕序列号（重启后仍保持一致）
类型（MacBook内置显示器、外接显示器）
尺寸（27英寸、32英寸等）

Step 3: Interview About Physical Setup

步骤3：询问物理布局信息

Ask about the physical arrangement:

"Which monitor is in front of you (center)?"
"What's to your left? Right?"
"Are any monitors rotated vertically (portrait mode)?"
"Roughly how far do you sit from your displays? (helps determine optimal resolution)"

询问显示器的物理排列情况：

“哪台显示器在你的正前方（中间位置）？”
“左侧和右侧分别是哪台显示器？”
“是否有显示器垂直旋转（竖屏模式）？”
“你通常坐在离显示器多远的位置？（有助于确定最佳分辨率）”

Step 4: Interview About Use Case

步骤4：询问使用场景

Ask about primary use:

"What do you primarily use this setup for?"
- Programming/code reading
- Video editing/media production
- General productivity
- Gaming
- Mixed use
"Do you prefer maximum sharpness (smaller text) or comfortable readability (larger text)?"
"Is smooth scrolling important to you? (120Hz vs 60Hz)"

询问主要使用场景：

“你主要用这套显示器设置做什么？”
- 编程/代码阅读
- 视频编辑/媒体制作
- 日常办公
- 游戏
- 混合使用
“你更倾向于最高清晰度（文字更小）还是舒适可读性（文字更大）？”
“流畅滚动对你来说重要吗？（120Hz vs 60Hz）”

Step 5: Analyze and Recommend

步骤5：分析并给出推荐

Based on the interview, reference

references/resolution_guidelines.md

for optimal settings.

Consider:

4K displays: Can run at native 4K, scaled 1440p, or scaled 1080p
Portrait orientation: Use
```
degree:90
```
or
```
degree:270
```
depending on cable exit preference
Refresh rates: Prioritize 120Hz for programming/gaming if available
Main display: Set the center/primary monitor as main with
```
origin:(0,0)
```

Present the recommendation:

Based on your setup, I recommend:

Center (32" Dell): 3840x2160 @ 120Hz - Main display
  → Maximum 4K sharpness, smooth scrolling

Left (27" Dell): 1800x3200 @ 60Hz portrait
  → Vertical for code reading, high resolution

Right (MacBook): 1512x982 @ 120Hz
  → Native Retina scaling

Want me to apply this configuration?

基于用户的回答，参考

references/resolution_guidelines.md

配置最佳设置。

考虑因素：

4K显示器：可运行原生4K、缩放1440p或缩放1080p模式
竖屏模式：根据线缆接口方向选择
```
degree:90
```
或
```
degree:270
```
刷新率：若支持，编程/游戏场景优先选择120Hz
主显示器：将中间/主要显示器设为主屏幕，设置
```
origin:(0,0)
```

展示推荐配置：

根据你的设置，我给出以下推荐：

中间（32英寸Dell）：3840x2160 @ 120Hz - 主显示器
  → 4K最高清晰度，流畅滚动

左侧（27英寸Dell）：1800x3200 @ 60Hz 竖屏
  → 竖屏适合代码阅读，高分辨率

右侧（MacBook）：1512x982 @ 120Hz
  → 原生Retina缩放

需要我应用此配置吗？

Step 6: Apply Configuration

步骤6：应用配置

Construct and execute the displayplacer command:

bash

displayplacer \
  "id:[DISPLAY_ID] res:[WIDTH]x[HEIGHT] hz:[REFRESH] color_depth:8 enabled:true [scaling:on] origin:([X],[Y]) degree:[ROTATION]" \
  "id:[DISPLAY_ID] ..." \
  "id:[DISPLAY_ID] ..."

Key parameters:

```
id:
```
- Use persistent screen ID for reliability
```
res:
```
- Resolution (check available modes in displayplacer list)
```
hz:
```
- Refresh rate
```
scaling:on
```
- Enable HiDPI scaling (omit for native resolution)
```
origin:
```
- Position relative to other displays
```
degree:
```
- Rotation (0, 90, 180, 270)

构建并执行displayplacer命令：

bash

displayplacer \
  "id:[DISPLAY_ID] res:[WIDTH]x[HEIGHT] hz:[REFRESH] color_depth:8 enabled:true [scaling:on] origin:([X],[Y]) degree:[ROTATION]" \
  "id:[DISPLAY_ID] ..." \
  "id:[DISPLAY_ID] ..."

关键参数：

```
id:
```
- 使用屏幕序列号以保证可靠性
```
res:
```
- 分辨率（在displayplacer list输出中查看可用模式）
```
hz:
```
- 刷新率
```
scaling:on
```
- 启用HiDPI缩放（原生分辨率模式下省略此参数）
```
origin:
```
- 相对于其他显示器的位置
```
degree:
```
- 旋转角度（0、90、180、270）

Step 7: Verify and Save Profile

步骤7：验证并保存配置文件

After applying, verify the configuration:

bash

displayplacer list | grep -E "(Serial screen id|Resolution:|Origin:|Rotation:)"

Offer to save as a reusable profile:

bash

mkdir -p ~/.config/display-profiles

Create a shell script for the profile:

bash

#!/bin/bash

应用配置后，验证设置是否生效：

bash

displayplacer list | grep -E "(Serial screen id|Resolution:|Origin:|Rotation:)"

提供保存为可复用配置文件的选项：

bash

mkdir -p ~/.config/display-profiles

创建配置文件的Shell脚本：

bash

#!/bin/bash

Profile: [name]

配置文件：[名称]

[description]

[描述]

displayplacer
"id:... res:... hz:... ..."

echo "Profile [name] applied"


Optionally add shell aliases for quick switching.

displayplacer
"id:... res:... hz:... ..."

echo "已应用配置文件[名称]"


可选择性添加Shell别名以快速切换配置。

Troubleshooting

故障排查

Monitor Shows Upside Down

显示器显示倒置

Change rotation from

degree:90

degree:270

or vice versa.

将旋转参数从

degree:90

改为

degree:270

，或反之。

Resolution Mode Not Found

找不到分辨率模式

Some resolutions require

scaling:on

, others don't. Check the available modes in

displayplacer list

output and match exactly.

部分分辨率需要启用

scaling:on

，部分不需要。查看

displayplacer list

输出中的可用模式并完全匹配。

Display IDs Changed

显示器ID变更

Use serial screen IDs (start with 's') instead of persistent IDs for more reliability, or use contextual IDs with the

--contextual

flag.

使用屏幕序列号（以's'开头）替代持久ID以提升可靠性，或使用

--contextual

标志使用上下文ID。

Portrait Resolution Format

竖屏分辨率格式

When rotated, specify resolution in portrait format:

1080x1920

instead of

1920x1080

旋转后，需以竖屏格式指定分辨率：

1080x1920

而非

1920x1080

。

Example Session

示例会话

User: optimize my monitors

Claude: Let me check your connected displays...
[runs displayplacer list]

I found 3 displays:
1. MacBook Pro 16" - Built-in Liquid Retina XDR
2. Dell S3225QS - 32" 4K @ 120Hz capable
3. Dell U2720Q - 27" 4K @ 60Hz capable

How are these physically arranged?

User: The 32" is center, 27" is on my left rotated vertical, MacBook on right

Claude: Great setup for coding! How far do you sit from the displays?

User: About 2.5 feet

Claude: At 2.5 feet from 4K displays, here's what I recommend:
- 32" center: 3840x2160 @ 120Hz (full 4K, maximum sharpness)
- 27" left: 1800x3200 portrait @ 60Hz (tons of code lines visible)
- MacBook right: Native Retina @ 120Hz

Want me to apply this?

User: Yes

Claude: [applies configuration]

Done! Your displays are now configured:
- 32" Dell: Main display, 4K @ 120Hz
- 27" Dell: Portrait left, 1800x3200
- MacBook: Right side, native resolution

I've also saved this as a profile at ~/.config/display-profiles/coding.sh
Run `display-coding` to restore this configuration anytime.

用户：优化我的显示器

Claude：让我检查一下已连接的显示器...
[运行displayplacer list]

我检测到3台显示器：
1. MacBook Pro 16" - 内置Liquid Retina XDR显示器
2. Dell S3225QS - 32英寸4K，支持120Hz
3. Dell U2720Q - 27英寸4K，支持60Hz

这些显示器的物理布局是怎样的？

用户：32英寸的在中间，27英寸的在左侧竖屏放置，MacBook在右侧

Claude：非常适合编程的布局！你通常坐在离显示器多远的位置？

用户：大约2.5英尺

Claude：在距离4K显示器2.5英尺的位置，推荐如下配置：
- 中间32英寸：3840x2160 @ 120Hz（完整4K，最高清晰度）
- 左侧27英寸：1800x3200竖屏 @ 60Hz（可显示大量代码行）
- 右侧MacBook：原生Retina分辨率 @ 120Hz

需要我应用此配置吗？

用户：是的

Claude：[应用配置]

完成！你的显示器已配置完成：
- 32英寸Dell：主显示器，4K @ 120Hz
- 27英寸Dell：左侧竖屏，1800x3200
- MacBook：右侧，原生分辨率

我还将此配置保存为配置文件，路径为~/.config/display-profiles/coding.sh
随时运行`display-coding`即可恢复此配置。