플러그인 만들기
플러그인은 .js 파일 하나입니다. 맨 위 주석(헤더 주석)에 이름과 권한을 적고, sc.operation 으로 실행할 동작을 등록합니다. 이 쪽은 만드는 방법과 sc API 참조입니다. 쓰는 방법은 플러그인 사용하기를 참고합니다.
새 플러그인 만들기
- 매니저 위 도구 줄의 더하기(+) 버튼을 클릭하거나 명령 팔레트(Ctrl+K)에서 「새 플러그인...」을 실행합니다. 「새 플러그인」 창이 뜹니다.
- 아래 표의 값을 정합니다. 창의 「미리보기」 칸에 만들어질 헤더 주석이 보입니다.
- [만들기] 버튼을 클릭합니다. 파일을 만들고, 매니저에서 그 플러그인을 선택하고, 코드를 탭으로 엽니다.
| 칸 | 내용 |
|---|---|
| 이름 | 목록에 보일 이름입니다. 필수입니다 |
| ID | 영문 소문자·숫자·- 로 64자까지이고 - 로 시작하거나 끝날 수 없습니다. 이름에서 제안하며 한글 이름이면 직접 적습니다. 파일 이름(<ID>.js)이 됩니다. 이미 있는 ID(기본 플러그인 포함), 같은 이름의 파일, Windows 예약 이름(con, nul, com1 등)은 쓸 수 없고 아래에 까닭이 나옵니다 |
| 한 줄 설명 | 비우면 시작 템플릿의 기본 설명이 들어갑니다. 설명은 한 줄과 사용법, 한계 양식으로 만들어집니다 |
| 그룹 | 「내 플러그인」, 있는 그룹, 「새 그룹...」 중에서 선택합니다 |
| 버전·만든 사람 | 버전은 1.0.0 처럼 숫자와 점으로 적습니다. 만든 사람은 마지막에 적은 값을 기억합니다 |
| 시작 템플릿 | 본문의 출발점입니다(아래 표). 선택하면 권한 기본값이 바뀝니다 |
| 할 수 있는 일 | 권한 체크 상자 10개와 접속할 곳입니다. 경고 색 권한을 체크하거나 템플릿이 쓰는 권한을 빼면 경고 줄이 나옵니다 |
| 자동 실행 | 문서를 저장한 뒤, 파일을 연 뒤, 파일 탭을 닫은 뒤 중에서 체크합니다. 체크하면 「이벤트로 돌면 묻지 않고 실행됩니다.」가 나옵니다 |
| 저장 위치 | 내 플러그인 폴더의 <ID>.js 입니다 |
| 시작 템플릿 | 본문 | 기본 권한 |
|---|---|---|
| 「선택한 텍스트 바꾸기」 | 선택한 텍스트를 읽어 바꾼 뒤 그 자리에 넣습니다(예제: 영문 대문자로) | text.read text.write |
| 「문서 전체 바꾸기」 | 코드 블록 밖을 정리합니다(예제: 겹친 빈 줄 줄이기) | text.read text.write |
| 「보고서 만들기(새 문서로)」 | 현재 문서를 읽어 보고서를 새 문서로 만듭니다(예제: 줄·글자 수와 제목 목록) | text.read document.write |
| 「작업 폴더 점검」 | 작업 폴더의 마크다운 파일을 탭 없이 읽어 점검하고 결과를 새 문서로 만듭니다 | workspace.read document.write |
| 「빈 템플릿」 | 자주 쓰는 기능을 주석으로 적어 둔 빈 본문입니다 | 없음 |
시작 템플릿은 실제로 동작하는 짧은 코드입니다. 만든 파일의 헤더 주석 뒤에는 선언 파일 참조 줄(/// <reference path="./_types/sc.d.ts" />)이 들어갑니다. 이 앱에서 만든 플러그인은 처음 실행할 때 실행 확인을 묻지 않습니다.
AI로 만들기
- 매니저 위 도구 줄의 AI로 만들기 버튼을 클릭하거나 AI 채팅 입력란에
/플러그인을 입력합니다. 「새 플러그인」 창의 [AI로 만들기] 버튼은 입력한 값을 채팅 입력란에 채워 줍니다. - 하고 싶은 일을 써서 보냅니다. 「문서 내용은 보내지 않습니다」. 요청 내용만 보냅니다.
- AI 가 코드를 만들면 앱이 형식과 구문을 검사합니다. 걸리면 AI 에게 한 번 다시 요청합니다.
- 답 아래의 [미리보기·저장] 버튼을 클릭하면 코드 전체와 요청한 권한이 보입니다. 문서 읽기·쓰기 밖의 권한은 경고 색으로 따로 나옵니다.
- [저장] 버튼을 클릭하면 내 플러그인 폴더에 저장합니다. 저장만 하고 실행하지 않으며, 처음 실행할 때 실행 확인을 받습니다.
AI 설정이 없으면 AI 설정 창이 열립니다. 자세한 설정은 AI를 참고합니다.
코드 편집과 시험
매니저의 「코드 편집...」은 플러그인을 문서 탭으로 엽니다. 편집기 위 도구 줄에 버튼이 있습니다.
- 저장(Ctrl+S): 이미 허용한 플러그인이면 저장한 내용에도 허용이 이어집니다.
- 실행(F5): 저장한 뒤 마지막으로 보던 문서에 실행합니다. 결과가 그 문서에 바로 들어가므로 버려도 되는 문서에서 연습합니다. 열린 문서가 없으면 「플러그인을 실행해 볼 문서를 먼저 여세요.」가 나옵니다.
- 플러그인 정보: 이름, 그룹, 버전, 만든 사람, 설명, 권한, 접속할 곳, 비밀값, 입력값, AI 에이전트 호출, 저장 뒤 자동 실행을 양식으로 고칩니다. 양식에 없는 태그와 권한은 그대로 남습니다.
입력하면 자동 완성이 뜹니다. sc. 뒤에는 쓸 수 있는 함수가, sc.invoke(' 안에서는 앱 기능 이름과 필요한 권한이 나옵니다. 이름에 마우스를 올리면 설명이 보이고 구문 오류는 밑줄로 표시됩니다.
파일과 폴더
plugins/
tidy-lines.js ← 플러그인 하나 = 파일 하나(헤더 주석 + sc.operation)
my-tool.js
_types/
sc.d.ts ← 바깥 편집기용 선언 파일(목록에는 나오지 않음)
- 내 플러그인 폴더는 기본으로 설정 폴더 안의
plugins입니다. 파일을 넣거나 지우면 몇 초 안에 목록이 바뀝니다. _나.으로 시작하는 파일과 폴더는 목록에 들지 않습니다.main.js가 든 폴더도 플러그인으로 읽습니다(예전 형식).- 같은 ID 의 플러그인이 둘이면 내 플러그인 쪽은 실행하지 않습니다. 한쪽의
@id나 파일 이름을 바꿉니다. - 플러그인은 앱 설정 폴더나 다른 프로그램의 설정 폴더에 있는 파일을 열거나 저장할 수 없습니다.
헤더 주석
이름, 그룹, 권한 같은 정보는 따로 파일 없이 스크립트 맨 위 주석에 적습니다.
/**
* @name 선택한 줄 번호 붙이기
* @group 내 플러그인
* @permissions text.read text.write
* @description
* 선택한 줄 앞에 번호를 붙입니다.
*/
sc.operation('run', async ({ doc }) => {
const sel = await sc.invoke('text.selection', { doc });
if (sel.start === sel.end) throw new sc.UsageError('줄을 먼저 선택하세요.');
const out = sel.text.split('\n').map((line, i) => `${i + 1}. ${line}`).join('\n');
await sc.invoke('text.replace', { doc, edits: [{ range: sel.range, text: out }] });
return { changed: 1 };
});
| 태그 | 뜻 |
|---|---|
@name |
목록에 보일 이름입니다. 없으면 파일 이름입니다 |
@id |
플러그인 ID 입니다. 없으면 파일 이름에서 만듭니다 |
@group |
매니저에서 묶일 그룹입니다. 없으면 그룹 없이 목록 맨 위에 놓입니다 |
@version · @author |
버전과 만든 사람입니다 |
@description |
설명입니다. 다음 줄부터 여러 줄 마크다운으로 적고 다음 @ 줄에서 끝납니다. 설명 줄이 @ 로 시작하면 \@ 로 적습니다 |
@permissions |
쓸 권한을 공백으로 나눠 적습니다. 없으면 text.read text.write 입니다 |
@network |
접속할 사이트를 공백이나 쉼표로 나눠 적습니다. 없으면 접속하지 않습니다 |
@secret 이름 제목 |
토큰 같은 비밀값입니다. 한 줄에 하나씩 적습니다 |
@param {형} 이름 제목 — 설명 |
실행 전에 받을 입력값입니다 |
@event 이벤트 |
이벤트가 일어나면 자동으로 실행합니다. 이벤트마다 한 줄씩 적습니다 |
@mcp on · @agent 설명 |
AI 에이전트가 부를 수 있게 하고 에이전트에게 보일 설명을 적습니다 |
@title |
동작 제목입니다. 없으면 이름을 씁니다 |
@name:en 등 |
@name:en, @title:en, @description:en, @param:en 이름 제목 — 설명 으로 화면 언어가 en 일 때 보일 글을 적습니다. 없으면 바탕 글을 보입니다 |
@param 은 다음 꼴입니다.
- 형은
string,integer(integer:1..6은 범위),number,boolean,uri,enum:a|b|c(목록에서 선택),string[](쉼표로 나눠 입력),string:/정규식/입니다. 형을 생략하면string입니다. - 이름이
이름이면 필수,[이름]이면 선택,[이름=기본값]이면 선택이며 기본값이 들어갑니다. - 입력 창은 필수 입력값이 있을 때만 뜹니다.
doc(문서 번호)은 묻지 않고 지금 문서를 씁니다.
권한은 다음 열 가지입니다. 옛 이름 text 와 document 는 .read 와 .write 를 모두 뜻합니다.
| 권한 | 쓸 수 있는 일 |
|---|---|
text.read |
문서 텍스트와 구조를 읽습니다 |
text.write |
문서 텍스트를 고칩니다 |
document.read |
열린 문서 목록을 보고 문서 파일을 읽어 엽니다 |
document.write |
새 문서를 만들고 문서를 저장합니다 |
app.read |
앱 구성을 읽습니다 |
app.commands |
앱 명령을 실행합니다 |
ui.status |
상태 표시줄에 칸을 겁니다 |
storage |
설정을 기억합니다. 적지 않아도 쓸 수 있고, 코드에 sc.storage 가 있으면 배지가 붙습니다 |
workspace.read |
탭을 열지 않고 작업 폴더의 파일을 읽습니다 |
workspace.write |
작업 폴더의 파일을 고쳐 씁니다 |
동작 작성하기
sc.operation(이름, 함수) 로 동작을 등록합니다. 헤더 주석 하나는 동작 run 하나에 대응합니다.
- 함수의 첫째 인자는 입력값(기본값이 채워진 객체), 둘째 인자
ctx의ctx.signal.aborted와ctx.signal.throwIfAborted()로 [중지] 버튼을 확인합니다.ctx.progress(퍼센트, 텍스트)는 있지만 지금은 화면에 보이지 않습니다. - 문서는 실행 전에 뜬 사본을 읽고 고칩니다. 끝나면 앱이 바뀐 텍스트를 문서마다 편집 한 번으로 넣습니다. 실패하거나 중지하면 문서는 그대로이고, 실행하는 동안 직접 고친 문서에는 결과를 넣지 않습니다.
- 명령 실행, 상태 칸, 알림은 요청으로 적어 두었다가 편집과 저장이 끝난 뒤 차례로 일어납니다. 실패하거나 중지한 실행의 요청은 버립니다.
- 한 번에 하나만 실행합니다. 자바스크립트 실행 시간은 60초, 접속 대기를 포함한 전체는 10분, 자바스크립트 메모리는 256MB 까지입니다.
- 한 실행이 새로 만들 수 있는 문서는 32개이고, 써 넣을 수 있는 텍스트는 합계 256MB 까지입니다.
console.log텍스트와 오류는 「메시지」 탭에 쌓입니다. 돌려준 값은 메시지에 찍지 않습니다.- 단축키 칸 명령 ID 는
script.run_0부터script.run_63까지이고, 칸 번호는 플러그인마다 기억합니다.
결과를 보이는 방법은 세 가지입니다.
- 고치는 플러그인은 문서를 고치고
{ changed: 3 }처럼 고친 곳 수를 돌려줍니다. 알림에 그 수가 나옵니다. - 점검 플러그인은
sc.findings.add로 찾은 문제를 냅니다. 「점검 결과」 탭에 플러그인 이름으로 묶여 모입니다. - 보고서 플러그인은
document.new로 새 문서를 만듭니다. 실행이 끝나면 새 탭으로 열립니다.
커서가 표 밖인 것처럼 지금은 쓸 수 없는 상황은 throw new sc.UsageError('안내 텍스트') 로 알립니다. 오류가 아니라 안내 알림이 한 번 나오고 문서는 그대로입니다.
점검 플러그인의 예입니다.
/**
* @name 할 일 표시 점검
* @permissions text.read
*/
sc.operation('run', async ({ doc }) => {
const { text } = await sc.invoke('text.get', { doc });
const findings = [];
text.split('\n').forEach((line, i) => {
const at = line.indexOf('TODO');
if (at >= 0) findings.push({ line: i + 1, col: at + 1, message: '할 일 표시가 남아 있습니다.', severity: 'info' });
});
await sc.findings.add(findings);
});
sc API: 문서와 텍스트
sc.invoke(이름, 인자) 로 앱 기능을 부릅니다. 권한이 모자라면 오류로 멈추고 「메시지」 탭에 이유가 나옵니다. 인자의 doc 은 문서 번호이고 생략하면 지금 문서입니다. 위치는 줄과 칸이 1부터이고 칸은 코드 포인트입니다.
| 이름 | 권한 | 인자 → 결과 |
|---|---|---|
text.get |
text.read |
{doc?} → {text} |
text.selection |
text.read |
{doc?} → {text, range, start, end}. start·end 는 UTF-16 위치이고 range 는 text.replace 에 그대로 넘깁니다 |
text.insert |
text.write |
{doc?, text, at?: {line, column}} → {range}. at 이 없으면 커서 자리에 넣습니다 |
text.replace |
text.write |
{doc?, edits: [{range, text}]} → {changed, count}. range 는 {start: {line, column}, end: {line, column}} 입니다 |
document.list |
document.read |
→ {documents: [{doc, title, path, active}]} |
document.get |
document.read |
{doc?} → {doc, title, path, active, length} |
document.open |
document.read |
{path} → {doc}. 파일을 읽어 사본에 더하고 실행이 끝나면 탭으로 엽니다 |
document.new |
document.write |
{title?, text} → {doc}. 실행이 끝나면 새 탭으로 엽니다 |
document.save |
document.write |
{doc?, path?} → {doc, path}. 저장을 요청하고 앱이 글을 넣은 뒤 저장합니다 |
lumimd.outline.get |
text.read |
{doc?} → {headings: [{level, title, line}]} |
lumimd.ast.get |
text.read |
{doc?, types?} → {nodes}. 마크다운 구문 노드이고 types 로 거릅니다. position.offset 은 UTF-16 입니다 |
lumimd.stats.get |
text.read |
{doc?} → {chars, words, lines} |
lumimd.lint.list |
text.read |
{doc?} → {problems: [{rule, message, line, column, end_line, end_column, fixable}], count} |
lumimd.autofix.run |
text.write |
{doc?} → {fixed, uncertain, unfixable, total}. 문제 자동 수정을 합니다 |
lumimd.numbering.run |
text.write |
{doc?, style?} → {headings, links}. style 은 decimal, decimal_bare, official, chapter, outline, report, word_list, none 입니다 |
lumimd.markdown.import |
없음 | {html} → {markdown}. HTML 을 마크다운으로 바꿉니다 |
lumimd.corrections.get |
없음 | → {tables: [{name, pairs: [[틀린, 바른], …]}]}. 설정 폴더의 corrections 폴더에 있는 .csv 교정표를 읽습니다 |
document.open과document.save의 파일은.md,.markdown,.mdown,.mkd,.txt의 로컬 절대 경로만 됩니다. 열려 있지 않은 파일은 작업 폴더나 열린 문서의 폴더 안만 열고, 다른 이름으로 저장도 그 안에서만 하며 이미 있는 다른 파일은 덮어쓰지 않습니다. 파일 크기는 32MB 까지입니다.- 교정표는 한 줄에
틀린,바른(쉼표나 탭)을 적고#줄과 빈 줄은 건너뜁니다. 파일 하나는 512KB, 2,000쌍, 표는 32개까지 읽고 형식이 틀린 파일은 뺍니다. sc.util.range(텍스트, 시작, 끝)은 UTF-16 위치를{start: {line, column}, end: {line, column}}범위로 바꿉니다.
sc API: 앱과 연결하기
아래 기능도 sc.invoke 로 부르며 짧게 쓰는 함수가 함께 있습니다.
| 이름 | 권한 | 짧은 꼴 | 하는 일 |
|---|---|---|---|
app.describe |
app.read |
sc.app.describe(부분?) |
앱 구성을 돌려줍니다. app(이름·버전·언어·테마), commands(ID·이름·켜짐·체크·단축키·메뉴), menus, workspace(작업 폴더), events 중 하나를 고를 수 있습니다 |
app.command.run |
app.commands |
sc.app.run(명령 ID) |
앱 명령 실행을 요청합니다. 한 실행에 16개까지입니다 |
app.locale |
없음 | sc.app.locale() |
화면 언어 코드(ko, en 등)입니다 |
ui.status.set |
ui.status |
sc.status.set(텍스트, 툴팁?) · sc.status.clear() |
상태 표시줄에 이 플러그인의 칸을 겁니다. 플러그인마다 하나, 60자까지입니다 |
ui.notify |
없음 | sc.notify(텍스트, 수준?) |
알림을 띄웁니다. 수준은 info, success, warning, error 이고 한 실행에 5개, 300자까지입니다 |
ui.findings.add |
없음 | sc.findings.add(항목 또는 항목 배열) |
점검 결과를 냅니다 |
ui.findings.add의 항목은{ message, severity?, file?, doc?, line?, col? }입니다. 심각도는error,warning(기본),info입니다.file은 절대 경로이고 비우면 지금 문서입니다. 한 실행에 1,000개까지입니다.- 같은 플러그인을 다시 실행하면 그 플러그인 묶음만 바뀝니다. 문제가 없을 때도
sc.findings.add([])를 부르면 지난 결과가 지워지고 「문제가 없습니다」가 나옵니다. - 실행할 수 있는 명령은
app.describe의commands에 있는 것뿐입니다. 종료, 설정, 탐색기 파일 작업, 플러그인, 단축키·MCP·외부 도구 설정 같은 명령은 목록에 없고 실행할 수 없습니다. 실행 시점에 꺼져 있는 명령은 건너뛰고 「메시지」 탭에 적습니다.
sc API: 템플릿과 스니펫
「템플릿으로 새 문서...」 창에 있는 템플릿과 스니펫을 플러그인이 씁니다. 토큰 규칙은 템플릿과 스니펫과 같습니다.
| 이름 | 권한 | 인자 → 결과 |
|---|---|---|
template.list |
app.read |
{kind?, query?} → {items: [{name, kind, category, summary, user, tokens, blocks}]}. kind 는 template 또는 snippet 이고 생략하면 둘 다입니다. tokens 는 사용자 정의 토큰 이름, blocks 는 반복·조건 블록({name, kind: "each", fields}·{name, kind: "if"})입니다 |
template.new |
document.write |
{name, values?, title?} → {doc, title, caret, tokens}. 템플릿으로 새 문서를 만들고 실행이 끝나면 새 탭으로 엽니다 |
snippet.insert |
text.write |
{doc?, name, values?} → {doc, range, caret, tokens}. 커서 자리에 스니펫을 넣습니다. 선택한 텍스트가 있으면 바꿉니다 |
template.expand |
app.read |
{text, values?} → {text, caret, tokens}. 받은 텍스트의 토큰만 채워 돌려주고 문서는 그대로 둡니다 |
values는{ "고객": "ACME" }처럼 사용자 정의 토큰 이름과 텍스트입니다. 100개, 값 하나 10,000자까지이고 값 안의{{…}}는 다시 채우지 않습니다. 값을 주지 않은 토큰은 그대로 남고 결과의tokens에filled,unfilled,unknown으로 나옵니다.- 반복 블록(
{{#each 품목}})에는 텍스트 배열이나{ "이름": "키보드" }같은 객체 배열을 넣습니다. 500개까지이고 배열 안에 배열은 넣을 수 없습니다. 결과의tokens.repeats에 반복 횟수가 나옵니다. 짝이 맞지 않는 블록 태그가 있거나 결과가 1MB를 넘으면 오류가 납니다. - 날짜, 시각, 작성자, 소속, 이메일, 커서 같은 기본 토큰은 앱이 채우며
values에 넣으면 오류가 납니다. - 작성자, 소속, 이메일은 설정 > MCP 의 「AI 앱에 사용자 정보(이름·소속·이메일) 제공」이 켜져 있을 때만 채우고 꺼져 있으면 빈 값입니다. 플러그인도 인터넷으로 텍스트를 보낼 수 있어 AI 앱과 같은 규칙을 따릅니다.
- 새 문서와 넣은 스니펫은
{{커서}}자리에 커서를 둡니다.caret은 그 자리의{line, column, offset}이고offset은 UTF-16 위치입니다.template.expand는{{커서}}를 지우고 자리만 돌려주며 없으면null입니다. - 「템플릿 값 입력」 창은 띄우지 않습니다. 사용자에게 값을 물으려면
@param을 쓰거나sc.app.run('file.new_from_template')로 템플릿 창을 엽니다.
회의록 템플릿으로 새 문서를 만드는 예입니다. 사용자 정의 토큰이 있는 템플릿이면 values 에 값을 넣습니다.
/**
* @name 주간 회의록
* @permissions app.read document.write
*/
sc.operation('run', async () => {
const { items } = await sc.invoke('template.list', { kind: 'template', query: '회의록' });
if (items.length === 0) throw new sc.UsageError('회의록 템플릿이 없습니다.');
const made = await sc.invoke('template.new', { name: items[0].name, title: '주간 회의' });
return { doc: made.doc, unfilled: made.tokens.unfilled };
});
선택한 목록 줄로 기본 템플릿 체크리스트 를 채우는 예입니다. 반복 블록 {{#each 항목}} 에는 텍스트 배열을 넘깁니다. 줄 앞의 -, 1., [x] 는 떼어 냅니다.
/**
* @name 선택한 목록으로 체크리스트
* @permissions text.read document.write
*/
sc.operation('run', async () => {
const sel = await sc.invoke('text.selection', {});
const items = sel.text
.split(/\r?\n/)
.map((line) => line.replace(/^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?/, '').trim())
.filter((line) => line !== '');
if (items.length === 0) throw new sc.UsageError('목록 줄을 먼저 선택하세요.');
const made = await sc.invoke('template.new', {
name: '체크리스트',
title: '준비물',
values: { 제목: '준비물', 항목: items },
});
return { doc: made.doc, repeats: made.tokens.repeats };
});
필드가 여러 개인 반복 블록에는 { 이름: '키보드', 수량: '2' } 같은 객체 배열을 넘깁니다. 합계 같은 계산은 템플릿이 하지 않으므로 플러그인에서 계산해 values 에 넣습니다.
sc API: 설정 기억
플러그인마다 실행 사이에 남는 작은 저장소가 있습니다. 다른 플러그인의 값은 읽을 수 없습니다.
| 이름 | 짧은 꼴 | 하는 일 |
|---|---|---|
storage.get |
await sc.storage.get(키, 기본값?) |
값을 읽습니다. 없으면 기본값입니다 |
storage.set |
await sc.storage.set(키, 값) |
값을 적습니다. JSON 으로 바꿀 수 있는 값이어야 합니다 |
storage.delete |
await sc.storage.delete(키) |
키를 지웁니다 |
storage.keys |
await sc.storage.keys() |
적어 둔 키 목록입니다 |
storage.clear |
await sc.storage.clear() |
저장소를 비웁니다 |
- 실행 전에 저장된 값을 사본으로 읽고, 성공으로 끝난 실행만 바뀐 값을 씁니다.
- 합계 64KB, 키 256개, 키 이름 128자까지입니다.
- 값은 설정 폴더의
plugin-data폴더에 평문 파일로 남습니다. 토큰 같은 비밀값은 넣지 않고@secret을 씁니다. - 플러그인을 지우면 그 값도 지웁니다.
sc API: 작업 폴더 파일
탭을 열지 않고 파일을 읽고 고칩니다. 닿는 곳은 탐색기의 작업 폴더와 열린 문서의 폴더뿐이고, 작업 폴더 밖 문서의 폴더는 그 폴더의 파일만 닿습니다. 심볼릭 링크, .., 네트워크 경로는 거절하고 문서 확장자 파일만 다룹니다.
| 이름 | 권한 | 짧은 꼴 | 하는 일 |
|---|---|---|---|
workspace.files |
workspace.read |
sc.workspace.files({folder?, exts?, max?}) |
파일 목록 {roots, files: [{path, rel, root, name, size}], truncated} 를 돌려줍니다. 기본은 마크다운 2,000개이고 max 로 5,000개까지 늘립니다. .git, node_modules 같은 폴더는 건너뜁니다 |
workspace.read |
workspace.read |
sc.workspace.read(경로) |
파일 텍스트를 돌려줍니다. 파일 하나 4MB, 한 실행 합계 64MB 까지입니다 |
workspace.exists |
workspace.read |
sc.workspace.exists(경로 배열) |
있는지를 배열로 돌려줍니다. 닿을 수 없는 곳은 null 입니다 |
workspace.write |
workspace.write |
sc.workspace.write(경로, 텍스트) |
이 실행에서 읽은 파일만 고쳐 씁니다. 한 실행에 500개까지입니다 |
workspace.write 는 요청으로 적어 두었다가 실행이 끝난 뒤 앱이 씁니다. 쓸 수 있는 파일은 .md, .markdown, .mdown, .mkd, .txt 입니다. 탭으로 열린 파일은 편집기에 편집 한 번으로 넣고 저장하며 고치는 중인 탭은 건너뜁니다. 열리지 않은 파일은 디스크에 쓰되 읽은 뒤 바뀐 파일은 건너뛰고 BOM 과 줄 끝(CRLF)은 그대로 둡니다.
인터넷 접속과 비밀값
@network 에 적은 사이트로만 fetch 로 접속합니다.
/**
* @name 주소 확인
* @permissions text.read
* @network example.com
*/
sc.operation('run', async () => {
const res = await fetch('https://example.com/');
await sc.notify(`상태 ${res.status}`, res.ok ? 'success' : 'warning');
});
@network항목은example.com,*.example.com,example.com:8443꼴입니다. 기본은 https 이고http://를 붙여 적은 항목만 평문 접속을 허락합니다.*는 모든 공개 사이트입니다.- 루프백과 사설 주소로는 접속하지 않고, 리다이렉트마다 다시 검사합니다.
fetch(주소, {method, headers, body, timeout})의body는 텍스트이고timeout은 밀리초입니다. 응답은status,ok,headers,text(),json(),arrayBuffer()로 읽습니다.URL,URLSearchParams,Headers도 쓸 수 있습니다.- 응답 본문은 20MB 까지이고 기본 제한 시간은 30초(최대 300초), 동시 요청은 16개, 한 실행의 요청은 1,000개까지입니다.
@secret 이름 제목으로 선언한 비밀값은 매니저의 「비밀값...」 버튼으로 넣고 OS 키 저장소에 보관합니다. 코드에서는sc.secrets.get('이름')으로 읽습니다.await없이 바로 값을 돌려주고, 값이 없으면 오류입니다. 출력과 오류에서는[secret:이름]으로 가립니다.@network *와@secret은 함께 쓸 수 없습니다. 함께 적으면 플러그인을 읽지 못합니다.- 설치 확인과 실행 확인 창에 접속할 곳과 비밀값이 나옵니다.
이벤트로 자동 실행하기
헤더 주석에 @event 이벤트 를 적으면 그 일이 일어난 뒤 플러그인이 실행됩니다. 동작은 인자로 { event, doc, path, title } 를 받습니다.
| 이벤트 | 언제 |
|---|---|
document.saved |
사용자가 문서를 저장했을 때입니다. 자동 저장과 플러그인·AI 에이전트가 한 저장은 뺍니다 |
document.opened |
사용자가 파일을 열었을 때입니다. 지난 세션 복원, 새 문서, 플러그인 코드 탭, 플러그인이나 AI 에이전트가 연 파일은 뺍니다 |
document.closed |
파일이 있는 문서 탭을 닫았을 때입니다. 인자에 doc 이 없고 플러그인·AI 에이전트가 닫은 것은 뺍니다 |
/**
* @name 저장 알림
* @permissions text.read
* @event document.saved
*/
sc.operation('run', async ({ title }) => {
await sc.notify(`${title} 을(를) 저장했습니다.`, 'success');
});
- 실행을 허락한 플러그인만 자동으로 돕니다. 실행 확인 창에 「다음 일이 일어나면 묻지 않고 실행합니다」가 따로 나옵니다.
- 시작과 끝 알림 없이 돌고 「메시지」 탭에 기록합니다. 비밀값이 비어 있으면 건너뜁니다.
- 이벤트가 부른 실행이 파일·탭 명령(열기·닫기·저장)을 요청하면 건너뜁니다. 서로 끝없이 부르지 않게 하기 위해서입니다. 밀린 자동 실행이 32개를 넘으면 뒤의 것을 건너뜁니다.
- 멈추려면
@event줄을 지우고 저장하거나 플러그인을 삭제합니다. 앱 밖에서 파일이 바뀌면 지문이 달라져 다시 허락하기 전까지 돌지 않습니다.
AI 에이전트가 부르게 하기
헤더 주석에 @mcp on 을 적으면 AI 에이전트가 이 플러그인을 부를 수 있고, @agent 에 에이전트에게 보일 설명을 적습니다. 접속할 곳과 비밀값이 모두 없는 플러그인은 @mcp on 이 없어도 부를 수 있습니다. 직접 만든 플러그인은 한 번 실행해 허락한 뒤에야 에이전트가 부를 수 있습니다. 연결 방법은 AI 에이전트 연결(MCP)를 참고합니다.
선언 파일
매니저를 열면 내 플러그인 폴더의 _types/sc.d.ts 에 TypeScript 선언 파일을 씁니다. 새 플러그인에는 /// <reference path="./_types/sc.d.ts" /> 가 들어 있어 VS Code 같은 바깥 편집기에서도 sc 의 자동 완성과 검사를 받습니다. 선언 파일의 ScOp, ScPermission, ScEvent 는 이 쪽의 표와 같습니다.