打破第四面墙 — VS Code 扩展
让 Minecraft 女仆 AI 跨次元操作你的 VS Code 工作区
English | 简体中文
🎯 这是什么？
打破第四面墙 (TLM: Breaking the Fourth Wall) 是一个 VS Code 扩展插件，作为 WebSocket Server 运行在本地，
接收来自 Minecraft 模组中 车万女仆 (Touhou Little Maid) AI 的请求，
让游戏内的女仆能够：
- 📖 读取你当前工作区的文件和代码
- ✍️ 在你编辑器中插入或替换文本
- 🔍 查看你选中的代码片段并分析
- 📂 列出目录结构和文件信息
- 💬 跨次元与你进行编程协作
┌─────────────────────────┐ WebSocket (JSON) ┌─────────────────────────┐
│ Minecraft Mod (Client) │ ◄──────────────────────► │ VS Code 插件 (Server) │
│ Java / NeoForge │ ws://127.0.0.1:21420 │ TypeScript │
│ │ │ │
│ 女仆 AI 发起请求 │ {type, taskId, │ 操作你的工作区文件 │
│ │ operation, payload} │ 受严格安全沙盒限制 │
└─────────────────────────┘ └─────────────────────────┘
🛡️ 安全模型
你的代码安全是我们最优先的考量：
| 防护层 |
说明 |
| 仅 localhost |
WebSocket 服务器只绑定 127.0.0.1，外部网络无法访问 |
| 工作区沙盒 |
所有文件操作被严格限制在当前 vscode.workspace 范围内 |
| 路径穿越防护 |
拒绝 ..、~、绝对路径等 5 层安全校验 |
| 手动开关 |
可通过状态栏一键关闭服务器，保护敏感工作区 |
| 单客户端 |
最多允许 1 个 Minecraft 客户端连接 |
| 开源可审计 |
全部代码在 GitHub 开源 |
📋 前置条件
- VS Code
^1.125.0
- Minecraft
1.21.1 + NeoForge 21.1.235+
- 车万女仆 (Touhou Little Maid)
v1.5.2+
- TLM: Breaking the Fourth Wall Mod（配套 Minecraft 模组，必需）
⚠️ 本插件是配套组件，单独安装无法工作。请确保 Minecraft 端模组已正确安装。
🚀 快速开始
- 在 VS Code 扩展商店搜索 "打破第四面墙" 或 "TLM_BreakTheFourthWall" 安装
- 安装后，状态栏右侧会出现
📡 女仆桥接: 等待连接... 图标
- 启动 Minecraft 并进入世界，模组会自动连接到
ws://127.0.0.1:21420
- 连接成功后状态栏显示
🔌 女仆桥接: 已连接
- 与女仆对话，她就能操作你的工作区了！
⚙️ 扩展配置
| 配置项 |
类型 |
默认值 |
说明 |
tlmBreakingTheFourthWall.port |
number |
21420 |
WebSocket 服务器端口，需与模组端一致 |
tlmBreakingTheFourthWall.autoStart |
boolean |
true |
是否随 VS Code 自动启动。设为 false 可保护敏感工作区 |
tlmBreakingTheFourthWall.maxFileSizeKb |
number |
1024 |
文件读/写操作的最大大小 (KB) |
tlmBreakingTheFourthWall.commandTimeoutSeconds |
number |
30 |
命令执行的超时时间 (秒) |
⌨️ 命令
在命令面板 (Ctrl+Shift+P) 中可用：
| 命令 |
说明 |
| 切换女仆桥接服务器 (开启/关闭) |
💡 最常用 — 一键开关服务器，也可直接点击状态栏 |
| 显示女仆桥接状态 |
查看服务器运行信息和端口 |
| 启动女仆桥接服务器 |
手动启动 WebSocket 服务器 |
| 停止女仆桥接服务器 |
手动停止 WebSocket 服务器 |
| 诊断女仆桥接连接 |
输出完整诊断信息到输出通道 |
🔧 支持的操作
插件为女仆 AI 提供以下工作区操作：
| 操作 |
类别 |
说明 |
system.ping |
系统 |
健康检查 |
system.getStatus |
系统 |
获取工作区/编辑器状态 |
file.read |
文件 |
读取工作区文件 |
file.write |
文件 |
创建/覆盖文件 |
file.list |
文件 |
列出目录 |
file.delete |
文件 |
删除文件/空目录 |
file.exists |
文件 |
检查文件存在 |
editor.getActive |
编辑器 |
获取活动编辑器内容 |
editor.getSelection |
编辑器 |
获取选中文本 |
editor.insert |
编辑器 |
光标处插入 |
editor.replaceSelection |
编辑器 |
替换选中文本 |
🐛 已知问题
- 中文 Windows 系统上 Python 子进程可能出现编码问题（已通过
PYTHONIOENCODING=utf-8 修复于模组端）
- 状态栏在部分自定义主题中
warningBackground 颜色可能不明显
📦 开发
git clone https://github.com/134zhou/tlm-breakingthefourthwall-vscodeplugin.git
cd tlm-breakingthefourthwall-vscodeplugin
npm install
npm run compile # 编译 TypeScript
npm run watch # 监听模式
# 按 F5 启动 Extension Development Host 调试
📄 许可证
本项目为开源项目，完整源代码可在 GitHub 获取。
English
🎯 What is this?
Breaking the Fourth Wall (TLM: BreakTheFourthWall) is a VS Code extension that acts as a local WebSocket Server.
It receives requests from the Touhou Little Maid Minecraft mod's AI system,
enabling in-game maids to interact with your real VS Code workspace.
🛡️ Security
- localhost only — Server binds exclusively to
127.0.0.1
- Workspace sandbox — All file operations confined to
vscode.workspace
- Path traversal protection — 5-layer security validation
- Manual toggle — One-click server stop via status bar
- Single client — Max 1 Minecraft connection
- Open source — Full source code available for audit
🚀 Quick Start
- Install from VS Code Marketplace
- Status bar shows
📡 女仆桥接: 等待连接...
- Launch Minecraft with the companion mod — auto-connects to
ws://127.0.0.1:21420
- Start collaborating with your maid across dimensions!
⚙️ Settings
See the 中文配置表 above. Key settings:
tlmBreakingTheFourthWall.port — WebSocket port (default: 21420)tlmBreakingTheFourthWall.autoStart — Auto-start on VS Code launch (default: true, set false to protect sensitive workspaces)
⌨️ Commands
| Command |
Description |
| 切换女仆桥接服务器 (开启/关闭) |
Toggle server on/off (also available via status bar click) |
| 显示女仆桥接状态 |
Show server status info |
| 诊断女仆桥接连接 |
Output full diagnostic information |
Enjoy coding with your cross-dimensional maid assistant! 🦊✨
