본문으로 건너뛰기
목차 · AI와 확장

플러그인 만들기

플러그인은 .js 파일 하나입니다. 맨 위 주석(헤더 주석)에 이름과 권한을 적고, sc.operation 으로 실행할 동작을 등록합니다. 이 쪽은 만드는 방법과 sc API 참조입니다. 쓰는 방법은 플러그인 사용하기를 참고합니다.

새 플러그인 만들기

  1. 매니저 위 도구 줄의 더하기(+) 버튼을 클릭하거나 명령 팔레트(Ctrl+K)에서 「새 플러그인...」을 실행합니다. 「새 플러그인」 창이 뜹니다.
  2. 아래 표의 값을 정합니다. 창의 「미리보기」 칸에 만들어질 헤더 주석이 보입니다.
  3. [만들기] 버튼을 클릭합니다. 파일을 만들고, 매니저에서 그 플러그인을 선택하고, 코드를 탭으로 엽니다.
칸 내용
이름 목록에 보일 이름입니다. 필수입니다
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로 만들기

  1. 매니저 위 도구 줄의 AI로 만들기 버튼을 클릭하거나 AI 채팅 입력란에 /플러그인 을 입력합니다. 「새 플러그인」 창의 [AI로 만들기] 버튼은 입력한 값을 채팅 입력란에 채워 줍니다.
  2. 하고 싶은 일을 써서 보냅니다. 「문서 내용은 보내지 않습니다」. 요청 내용만 보냅니다.
  3. AI 가 코드를 만들면 앱이 형식과 구문을 검사합니다. 걸리면 AI 에게 한 번 다시 요청합니다.
  4. 답 아래의 [미리보기·저장] 버튼을 클릭하면 코드 전체와 요청한 권한이 보입니다. 문서 읽기·쓰기 밖의 권한은 경고 색으로 따로 나옵니다.
  5. [저장] 버튼을 클릭하면 내 플러그인 폴더에 저장합니다. 저장만 하고 실행하지 않으며, 처음 실행할 때 실행 확인을 받습니다.

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 는 이 쪽의 표와 같습니다.

관련 페이지