test-msw-vfs-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MSW 에셋 CLI 래퍼 —

@choigawoon/msw-vfs-cli

MSW资产CLI封装工具 —

@choigawoon/msw-vfs-cli

.map

.ui

.gamelogic

.model

world.yaml

에 걸친 읽기·탐색·편집·변환을

@choigawoon/msw-vfs-cli@0.5.3

단일 CLI 로 처리한다.

npx

로 호출하므로 로컬 설치 불필요 — npm 이 첫 호출 시 캐싱.

通过

@choigawoon/msw-vfs-cli@0.5.3

这一单一CLI工具，即可完成对

.map

.ui

.gamelogic

.model

world.yaml

文件的读取、浏览、编辑和转换操作。由于通过

npx

调用，无需本地安装——首次调用时npm会自动缓存该工具。

버전 핀 — 한 곳에서 관리

版本锁定 — 统一管理

Pin:
```
@choigawoon/msw-vfs-cli@0.5.3
```
Sources of truth (셋 다 일치해야 함):
1. 이 파일 상단의 버전 표기
2. ```
scripts/msw-vfs.js
```
  의
```
PKG
```
  상수
3. ```
scripts/msw-vfs-batch.js
```
  의
```
PKG
```
  상수
동일한 CLI 버전이 뷰어(
```
packages/viewer/src/lib/vfs.ts
```
의
```
REQUIRED_CLI_VERSION
```
) 에서도 요구된다. 스킬·CLI·뷰어 셋 모두 같은 마이너(
```
^0.5.0
```
) 안에서 움직여야
```
read-entity
```
/
```
edit-component
```
같은 L2 호출과 데몬 session recorder 가 맞물린다.

锁定版本:
```
@choigawoon/msw-vfs-cli@0.5.3
```
唯一可信来源（三者必须保持一致）:
1. 本文件顶部标注的版本
2. ```
scripts/msw-vfs.js
```
  中的
```
PKG
```
  常量
3. ```
scripts/msw-vfs-batch.js
```
  中的
```
PKG
```
  常量
查看器（
```
packages/viewer/src/lib/vfs.ts
```
中的
```
REQUIRED_CLI_VERSION
```
）也要求使用相同的CLI版本。技能、CLI、查看器三者必须在同一个次要版本（
```
^0.5.0
```
）范围内运行，才能确保
```
read-entity
```
/
```
edit-component
```
等L2调用与守护进程session recorder正常协同工作。

AI 호출 가시성 —

--ai

플래그

AI调用可见性 —

--ai

参数

단발 래퍼

scripts/msw-vfs.js

는 매 호출에 --ai
를 자동으로 붙인다 (CLI 0.5.3+ 의 client-identity 플래그). 의미:

데몬이 살아 있으면 호출이
```
~/.msw-vfs/sessions/s_<ts>_<id>.jsonl
```
에 자동 기록됨.
동일 데몬에 붙은 뷰어 (
```
@choigawoon/msw-vfs-viewer
```
) 의 Activity 패널에 실시간으로 뜸 (client 뱃지 =
```
ai
```
).
데몬이 없으면 로컬 fallback — 동작은 그대로, 기록만 안 됨.

배치 래퍼 (
scripts/msw-vfs-batch.js
) 는 예외:

serve

서브커맨드가 in-process 파이프라 데몬

/rpc

를 거치지 않는다. 따라서 batch 호출은 recorder 가시성이 없다 — 기록이 필요하면 단발 래퍼를 쓴다. (동시에 캐시 효과는 단발도 데몬 위에서 동등하게 누림.)

单次调用封装脚本

scripts/msw-vfs.js

会自动为每次调用添加**

--ai

**参数（CLI 0.5.3+新增的客户端身份标识参数）。其作用如下：

如果守护进程正在运行，调用记录会自动保存到
```
~/.msw-vfs/sessions/s_<ts>_<id>.jsonl
```
中。
连接到同一守护进程的查看器（
```
@choigawoon/msw-vfs-viewer
```
）的Activity面板会实时显示该调用（客户端标识为
```
ai
```
）。
如果守护进程未运行，则会启用本地回退机制——功能正常运行，但不会生成调用记录。

批量调用封装脚本（
scripts/msw-vfs-batch.js
）例外:

serve

子命令通过进程内管道运行，不经过守护进程的

/rpc

接口。因此批量调用不会被记录器追踪——如果需要记录，请使用单次调用封装脚本。（同时，单次调用和批量调用在守护进程上的缓存效果一致。）

실행 방식 — 에이전트 위임

执行方式 — 委托给Agent

이 스킬이 트리거되면 직접 CLI 를 실행하지 말고,

msw-blob-vfs-reader

에이전트에 위임한다.

Agent(
  subagent_type="msw-devtools:msw-blob-vfs-reader",
  description="맵/UI 분석",
  prompt="<사용자 요청 + 대상 파일 경로를 포함한 구체적 지시>"
)

이유:

.map

.ui

출력은 대량이며 메인 컨텍스트를 오염시킨다. 에이전트가 sonnet 모델로 분석 후 요약만 돌려주므로 컨텍스트 효율이 높다.

예외 — 에이전트 위임 없이 직접 실행하는 경우:

사용자가 명시적으로 "여기서 직접 해줘"라고 요청한 경우
분석 결과를 바탕으로 즉시 편집 작업이 이어지는 경우 (편집 컨텍스트가 필요)

当触发本技能时，请勿直接执行CLI，而是委托给

msw-blob-vfs-reader

Agent。

Agent(
  subagent_type="msw-devtools:msw-blob-vfs-reader",
  description="地图/UI分析",
  prompt="<包含用户请求及目标文件路径的具体指令>"
)

原因:

.map

.ui

文件的输出内容量大，会污染主上下文。Agent会通过sonnet模型进行分析后仅返回摘要，从而提升上下文使用效率。

例外情况 — 无需委托Agent直接执行的场景:

用户明确要求“直接在这里处理”时
需要基于分析结果立即执行编辑操作时（需要保留编辑上下文）

기본 호출 — 단발 (1 쿼리)

基础调用 — 单次（1个查询）

bash

node <plugin>/skills/test-msw-vfs-cli/scripts/msw-vfs.js <file> <subcmd> [args...]

래퍼가
```
npx -y @choigawoon/msw-vfs-cli@0.5.3
```
로 실행 — 별도 설치 불필요.
stdio 는 pass-through. 출력은 CLI 가 직접 쓰는 포맷(text + JSON 혼합).
```
<file>
```
은
```
.map
```
/
```
.ui
```
/
```
.gamelogic
```
/
```
.model
```
중 하나. YAML/world 모드는
```
--type
```
선행 필요.

bash

node <plugin>/skills/test-msw-vfs-cli/scripts/msw-vfs.js <file> <subcmd> [args...]

封装脚本会通过
```
npx -y @choigawoon/msw-vfs-cli@0.5.3
```
执行——无需单独安装。
标准输入输出直接传递，输出格式为CLI原生格式（文本+JSON混合）。
```
<file>
```
为
```
.map
```
/
```
.ui
```
/
```
.gamelogic
```
/
```
.model
```
中的一种。若为YAML/world模式，需先添加
```
--type
```
参数。

배치 호출 — N 쿼리 (serve)

批量调用 — N个查询（serve）

동일 파일에 여러 쿼리를 던질 때

serve

파이프를 쓰면 Node 콜드 스타트 + JSON 파싱 비용이 한 번으로 상각된다.

bash

undefined

当对同一文件执行多个查询时，使用

serve

管道可避免多次Node冷启动和JSON解析的开销。

bash

undefined

파일로부터

从文件读取

node <plugin>/skills/test-msw-vfs-cli/scripts/msw-vfs-batch.js queries.jsonl

stdin

从标准输入读取

cat queries.jsonl | node <plugin>/skills/test-msw-vfs-cli/scripts/msw-vfs-batch.js

undefined

cat queries.jsonl | node <plugin>/skills/test-msw-vfs-cli/scripts/msw-vfs-batch.js

undefined

요청 포맷 (newline-JSON, 한 줄 1 쿼리)

请求格式（换行分隔JSON，每行1个查询）

json

{"id":"a","argv":["/abs/map01.map","summary"]}
{"id":"b","argv":["/abs/map01.map","read-entity","/maps/map01/Hero"]}
{"id":"c","argv":["/abs/map01.map","grep-entities","BossRush"]}

argv[0]

은 파일 경로. 나머지는 CLI 서브커맨드 + 플래그. 응답은

{id,stdout,stderr,code}

형태의 newline-JSON.

json

{"id":"a","argv":["/abs/map01.map","summary"]}
{"id":"b","argv":["/abs/map01.map","read-entity","/maps/map01/Hero"]}
{"id":"c","argv":["/abs/map01.map","grep-entities","BossRush"]}

argv[0]

为文件路径，其余为CLI子命令及参数。响应格式为

{id,stdout,stderr,code}

的换行分隔JSON。

⚠️ 명령 선택의 선결 조건 — entry 타입 먼저 확인

⚠️ 命令选择前提 — 先确认文件类型

모든 명령이 모든 파일에 동작하지 않는다. 명령을 고르기 전에 먼저 파일 확장자를 보고 분기한다.

Entry	쓸 수 있는 명령군	트리/엔티티 명령 가능?
`.map` / `.ui` / `.gamelogic`	L1 VFS + L2 Entity + YAML export/import	✅
`.model`	`.model` 전용 서브셋: `info` / `list` / `get` / `set` / `remove` / `summary` / `validate`	❌ — 트리 없음
`world.yaml`	`--type world` + `build-world` 만	❌

.model

은 단일 템플릿 (메타 +

Values[]

행 테이블) — 자식 엔티티 트리가 없고 런타임에 소비되어 엔티티 1 개를 만든다. 그래서 트리 가정 명령 (

ls

tree

read-entity

list-entities

edit-entity

add-component

…) 은 모두 거부된다:

$ msw-vfs DefaultPlayer.model list-entities
msw-vfs: 'list-entities' is not a .model command —
         .model has no children; a .model produces one entity at runtime.

并非所有命令都适用于所有文件。选择命令前，请先根据文件扩展名进行区分。

文件类型	可用命令集	是否支持树形/实体命令?
`.map` / `.ui` / `.gamelogic`	L1 VFS + L2 Entity + YAML导出/导入	✅
`.model`	`.model` 专属子命令集: `info` / `list` / `get` / `set` / `remove` / `summary` / `validate`	❌ — 无树形结构
`world.yaml`	仅支持 `--type world` + `build-world`	❌

.model

是单一模板（元数据+

Values[]

行表）——没有子实体树，在运行时会被消费生成单个实体。因此所有基于树形结构的命令（

ls

tree

read-entity

list-entities

edit-entity

add-component

…）都会被拒绝：

$ msw-vfs DefaultPlayer.model list-entities
msw-vfs: 'list-entities' is not a .model command —
         .model has no children; a .model produces one entity at runtime.

.model

작업 라우팅 치트시트

.model

操作路由速查表

의도	`.map` / `.ui` 에서라면	`.model` 에서는
메타데이터 / 컴포넌트 카운트	`summary` / `read-entity`	`info` 또는 `summary`
들어있는 값들 나열	(개념상 다름)	`list`
값 하나 읽기	`read-entity` 하위	`get <name> [--target-type T]`
값 변경	`edit-component`	`set <name> <json> [--target-type T]`
값 제거	—	`remove <name>`
모델이 만들 엔티티 트리를 펼쳐 보고 싶음	(해당 없음)	`.map` / `.ui` 에 `spawn-model` 으로 펼친 뒤 그 파일에서 트리 명령

操作意图	若为 `.map` / `.ui` 文件时	若为 `.model` 文件时
查看元数据/组件数量	`summary` / `read-entity`	`info` 或 `summary`
列出所有值	（概念不同）	`list`
读取单个值	`read-entity` 子命令	`get <name> [--target-type T]`
修改值	`edit-component`	`set <name> <json> [--target-type T]`
删除值	—	`remove <name>`
查看模型将生成的实体树	（无对应操作）	通过 `.map` / `.ui` 文件的 `spawn-model` 命令展开后，再对该文件使用树形命令

흔한 환각 — 존재하지 않는 명령들

常见误区 — 不存在的命令

다음 이름들은 그럴듯하지만 CLI 에 존재하지 않는다. 호출 전에 의심하라:

❌
```
list-components
```
— 어디에도 없음. "엔티티가 가진 컴포넌트들"을 보려면
```
.map
```
/
```
.ui
```
에서 read-entity <path> --deep
(전체 컴포넌트 묶음 반환).
```
.model
```
에서는 info
의 JSON 안
```
Components
```
배열을 본다.
❌
```
list-entities
```
on
```
.model
```
— 위 규칙대로 거부됨.
❌
```
edit-component
```
on
```
.model
```
—
```
.model
```
의 컴포넌트 값은
```
set <name>
```
으로 편집한다 (
```
--target-type
```
으로 어느 컴포넌트의 값인지 한정).
❌
```
summary
```
가 빠진 명령 —
```
.model
```
에서도
```
summary
```
는 동작한다 (component_counts 포함).

확신이 안 서면 반드시

msw-vfs --help

를 먼저 본다. 도움말이 entity-tree 섹션과

.model

섹션을 분리해 보여준다.

자세한 호환성 표는 docs/vfs-commands.md 최상단 "명령 ↔ entry 타입 호환성" 섹션.

以下命令名称看似合理，但实际上CLI中并不存在。调用前请务必确认：

❌
```
list-components
```
— 不存在任何场景。若要查看「实体包含的组件」，在
```
.map
```
/
```
.ui
```
文件中使用**
```
read-entity <path> --deep
```
（返回完整组件集合）；在
.model
文件中查看
```
info
```
**返回JSON中的
```
Components
```
数组。
❌ 在
```
.model
```
文件中使用
```
list-entities
```
— 按照上述规则会被拒绝。
❌ 在
```
.model
```
文件中使用
```
edit-component
```
—
```
.model
```
的组件值需通过
```
set <name>
```
命令编辑（通过
```
--target-type
```
指定所属组件）。
❌
```
.model
```
文件不支持
```
summary
```
—
```
.model
```
文件同样支持
```
summary
```
命令（包含component_counts）。

若不确定，请务必先执行
msw-vfs --help
。帮助文档会分别展示entity-tree相关命令和

.model

두 레이어 — L1(VFS) vs L2(Entity) — entity-tree entry 전용

两层架构 — L1(VFS) vs L2(Entity) — 仅适用于entity-tree类型文件

위 표대로
.model
/
world.yaml
에는 적용되지 않는다.
.map
/
.ui
/
.gamelogic
안에서 같은 데이터를 두 각도로 노출한다는 의미.

선택 기준:

탐색·검색·grep → L1 (
```
ls
```
/
```
tree
```
/
```
glob
```
/
```
grep
```
/
```
read
```
/
```
stat
```
/
```
summary
```
)

엔티티 단위 읽기·편집·CRUD → L2 (

read-entity

list-entities

find-entities

grep-entities

edit-entity

edit-component

add-entity

remove-entity

/ …)

세부 명령 카탈로그는 upstream

COMMANDS.md

또는

msw-vfs --help

如上述表格所示，不适用于
.model
/
world.yaml
文件。仅针对
.map
/
.ui
/
.gamelogic
文件，从两个维度展示同一数据。

选择标准：

浏览、搜索、grep → L1（
```
ls
```
/
```
tree
```
/
```
glob
```
/
```
grep
```
/
```
read
```
/
```
stat
```
/
```
summary
```
）

实体级读取、编辑、CRUD → L2（

read-entity

list-entities

find-entities

grep-entities

edit-entity

edit-component

add-entity

remove-entity

/…）

详细命令目录请查看上游

COMMANDS.md

或执行

msw-vfs --help

。

원칙

操作原则

.map
/
.ui
를 Read 툴로 직접 열지 않는다. 단일 거대 JSON 이라 컨텍스트 초과. 반드시 CLI 를 경유.
탐색은 lazy 하게 —
```
ls /
```
부터 한 층씩.
```
tree --depth 3
```
부터 치지 않는다.
편집은 L2 기본 — 엔티티 메타는
```
edit-entity
```
, 컴포넌트 값은
```
edit-component
```
. L1
```
edit <path>.json
```
은 같은
```
@type
```
컴포넌트가 한 엔티티에 2 개 이상인 모호성 탈출구일 때만.
편집 전에 반드시
read-entity
로 현재 상태 확인 → 패치 생성 → 편집 →
```
validate
```
또는 재-
```
read-entity
```
로 검증.
대량 엔티티 연속 질의는 batch — 파일마다 매번 단발 호출하면 콜드 스타트 × N.

请勿直接用Read工具打开
.map
/
.ui
文件。这类文件是单一巨型JSON，会导致上下文过载。必须通过CLI工具处理。
浏览操作需循序渐进 — 从
```
ls /
```
开始逐层深入，不要直接使用
```
tree --depth 3
```
。
编辑操作默认使用L2 — 实体元数据使用
```
edit-entity
```
，组件值使用
```
edit-component
```
。仅当同一实体包含多个同
```
@type
```
组件存在歧义时，才使用L1的
```
edit <path>.json
```
作为兜底方案。
编辑前务必通过
read-entity
确认当前状态 → 生成修改补丁 → 执行编辑 → 通过
```
validate
```
或重新执行
```
read-entity
```
验证结果。
大量实体连续查询请使用批量调用 — 若对每个文件都单独调用单次命令，会产生N次冷启动开销。

읽기 전용이 아니다 — 편집도 지원

支持编辑操作 — 并非只读

이전 버전 스킬과 달리 이제 CLI 가 다음을 지원한다:

엔티티 메타 편집:
```
edit-entity <path> --set enable=false
```

컴포넌트 값 편집:

edit-component <entity> <@type> --set Position='[1,0,0]'

엔티티 CRUD:
```
add-entity
```
/
```
remove-entity
```
/
```
rename-entity
```
컴포넌트 CRUD:
```
add-component
```
/
```
remove-component
```
```
.model
```
값 편집:
```
set <name> <json>
```
(타입 추론 +
```
--type
```
강제)
YAML 왕복:
```
export-yaml
```
/
```
import-yaml
```
/
```
build-world
```

편집 전 백업 / 커밋은 호출자 책임 — CLI 는

--output / -o

로 다른 경로에 쓰는 옵션을 제공.

与旧版本技能不同，当前CLI支持以下编辑操作：

实体元数据编辑：
```
edit-entity <path> --set enable=false
```

组件值编辑：

edit-component <entity> <@type> --set Position='[1,0,0]'

实体CRUD：
```
add-entity
```
/
```
remove-entity
```
/
```
rename-entity
```
组件CRUD：
```
add-component
```
/
```
remove-component
```
```
.model
```
值编辑：
```
set <name> <json>
```
（自动类型推断 +
```
--type
```
强制指定）
YAML双向转换：
```
export-yaml
```
/
```
import-yaml
```
/
```
build-world
```

编辑前的备份/提交由调用者负责——CLI提供

--output / -o

选项，可将修改后的内容保存到其他路径。

포맷 참고

格式参考

```
.map
```
/
```
.ui
```
/
```
.gamelogic
```
—
```
Entities[]
```
배열 + entity → component 트리 (format-refs/map-authoring.md, format-refs/ui-authoring.md)
```
.model
```
—
```
Values[]
```
오버라이드 테이블을 갖는 entity 템플릿 (format-refs/model-authoring.md)
수동 편집 가이드: docs/manual-editing.md
VFS ↔ YAML 파이프라인: docs/vfs-yaml-pipeline.md
업스트림: https://github.com/choigawoon/msw-vfs-cli (MIT, v0.5.3)

```
.map
```
/
```
.ui
```
/
```
.gamelogic
```
—
```
Entities[]
```
数组 + entity → component树形结构（format-refs/map-authoring.md, format-refs/ui-authoring.md）
```
.model
```
— 包含
```
Values[]
```
覆盖表的实体模板（format-refs/model-authoring.md）
手动编辑指南：docs/manual-editing.md
VFS ↔ YAML流水线：docs/vfs-yaml-pipeline.md
上游仓库：https://github.com/choigawoon/msw-vfs-cli（MIT协议，v0.5.3）

test-msw-vfs-cli

Original

Translation

MSW 에셋 CLI 래퍼 —
`@choigawoon/msw-vfs-cli`

MSW资产CLI封装工具 —
`@choigawoon/msw-vfs-cli`

버전 핀 — 한 곳에서 관리

版本锁定 — 统一管理

AI 호출 가시성 —
`--ai`
플래그

AI调用可见性 —
`--ai`
参数

실행 방식 — 에이전트 위임

执行方式 — 委托给Agent

기본 호출 — 단발 (1 쿼리)

基础调用 — 单次（1个查询）

배치 호출 — N 쿼리 (serve)

批量调用 — N个查询（serve）

파일로부터

从文件读取

stdin

从标准输入读取

요청 포맷 (newline-JSON, 한 줄 1 쿼리)

请求格式（换行分隔JSON，每行1个查询）

⚠️ 명령 선택의 선결 조건 — entry 타입 먼저 확인

⚠️ 命令选择前提 — 先确认文件类型

`.model`
작업 라우팅 치트시트

`.model`
操作路由速查表

흔한 환각 — 존재하지 않는 명령들

常见误区 — 不存在的命令

두 레이어 — L1(VFS) vs L2(Entity) — entity-tree entry 전용

两层架构 — L1(VFS) vs L2(Entity) — 仅适用于entity-tree类型文件

원칙

操作原则

읽기 전용이 아니다 — 편집도 지원

支持编辑操作 — 并非只读

포맷 참고

格式参考

test-msw-vfs-cli

Original

Translation

MSW 에셋 CLI 래퍼 — @choigawoon/msw-vfs-cli

MSW资产CLI封装工具 — @choigawoon/msw-vfs-cli

버전 핀 — 한 곳에서 관리

版本锁定 — 统一管理

AI 호출 가시성 — --ai 플래그

AI调用可见性 — --ai参数

실행 방식 — 에이전트 위임

执行方式 — 委托给Agent

기본 호출 — 단발 (1 쿼리)

基础调用 — 单次（1个查询）

배치 호출 — N 쿼리 (serve)

批量调用 — N个查询（serve）

파일로부터

从文件读取

stdin

从标准输入读取

요청 포맷 (newline-JSON, 한 줄 1 쿼리)

请求格式（换行分隔JSON，每行1个查询）

⚠️ 명령 선택의 선결 조건 — entry 타입 먼저 확인

⚠️ 命令选择前提 — 先确认文件类型

.model 작업 라우팅 치트시트

.model操作路由速查表

흔한 환각 — 존재하지 않는 명령들

常见误区 — 不存在的命令

두 레이어 — L1(VFS) vs L2(Entity) — entity-tree entry 전용

两层架构 — L1(VFS) vs L2(Entity) — 仅适用于entity-tree类型文件

원칙

操作原则

읽기 전용이 아니다 — 편집도 지원

支持编辑操作 — 并非只读

포맷 참고

格式参考

MSW 에셋 CLI 래퍼 —
`@choigawoon/msw-vfs-cli`

MSW资产CLI封装工具 —
`@choigawoon/msw-vfs-cli`

AI 호출 가시성 —
`--ai`
플래그

AI调用可见性 —
`--ai`
参数

`.model`
작업 라우팅 치트시트

`.model`
操作路由速查表