플러그인 만들기·고치기

결과물은 플러그인 폴더 하나(또는 그 패키지)다. 설치·켜기·배치·공유는 이 스킬이 저절로 하지 않는다.

0. 무엇을 요청받았나 — 그 단계만

• 위젯은 사용자가 위젯으로 만들어 달라고 했을 때만 만든다. 도구나 데이터만으로 되는 기능에 위젯을 덧붙이지 않는다.
• 플러그인이 맞는지 먼저 본다 — 절차만 담으면 되는 일은 스킬(skill-creator), 이미 있는 MCP 서버는 add_mcp_server. 플러그인은 데몬 안에서 코드가 돈다는 대가가 있다.
• 다음 단계(설치·배치·패키징)가 필요해 보이면 제안만 한다.

1. 계약의 정본은 플러그인 가이드다

docs/plugins.ko.md(영문 docs/plugins.en.md). 이 스킬 폴더에서 위로 올라가며 설치 폴더의 docs/ 를 찾는다(앱 폴더가 dist 면 그 위). 못 찾으면 공개 레포의 같은 문서(https://github.com/tigu77/tiguclaw/blob/main/docs/plugins.ko.md).

매니페스트 키·needs·settings·widgets·host·배포 규칙은 거기서 읽고, 여기서 기억으로 쓰지 않는다. 가이드에 없는 것(코어 내부 파일 import 등)은 계약 밖이라 다음 버전에 깨질 수 있다 — 쓰지 않는다.

2. 쓰기 전에 — 위험 평가를 보인다

플러그인은 격리 없이 데몬과 같은 프로세스에서 돈다. 파일·네트워크·코어에 닿을 수 있고 needs 는 선언이지 강제가 아니다. 그래서 새로 만들 때도, 고쳐서 하는 일이 늘 때도 코드를 쓰기 전에 짧게 알린다:

• 무엇을 하나 · 언제 실행되나 — 모델이 도구를 부를 때 / 위젯이 값을 받을 때(데이터 라우트) / 데몬 시작 때(start()) / 주기 타이머.
• 데이터 — 무엇을 읽고 쓰나, 자기 자리(host.dataDir) 밖을 건드리나, 개인 자료·자격이 지나가나.
• 네트워크 — 나가는 호스트(needs.network)와 밖으로 보내는 내용.
• 모델 호출(needs.llm, 비용) · 스스로 말하기(needs.outbound, 폰에 메시지가 간다).
• 위젯이면: 읽기만 하는 위젯도 비격리 코드다. «안전하다» 고 말하지 않는다.

사용자가 만들어 달라고 한 것은 쓰기에 대한 동의다. 설치·켜기 동의는 아니다. 평가에서 사용자가 예상하지 못했을 대가(외부 전송·개인 자료·start() 상시 실행)가 나오면 쓰기 전에 확인받는다.

3. 어디에 쓰나 — 쓰기와 켜기의 경계

• 기본은 작업 폴더 <홈>/workspace/<플러그인 이름>/. 로더가 읽지 않는 자리다.
• <홈>/plugins/<이름>/ 에 두는 것은 설치다. ★그 폴더에 있으면 다음 데몬 시작 때 자동으로 로드돼 실행될 수 있다(사용자가 끄지 않은 한). 그래서 그 폴더에 쓰거나 복사하는 것은 사용자가 그 자리(설치)를 명시했을 때만 한다 — «설치해 줘»·«홈 플러그인 폴더에 바로 만들어» 같은 요청이 곧 그 동의이고, 쓰기 전에 위 사실을 알린다.
• 지금 켜는 것은 별개다. 폴더에 있는 플러그인은 대시보드 플러그인 화면에 나타나고, 사용자가 거기서 설치(켜기)하면 재시작 없이 바로 켜진다. 비서가 대신 켜는 도구는 없다 — «지금 바로 쓰게» 를 받으면 그 화면에서 켜도록 안내한다. 반영하려고 데몬을 재시작하지 않는다(진행 중인 대화가 끊긴다).
• 이미 설치된 플러그인을 «고쳐 줘» 는 그 자리 수정의 동의다(§5).

4. 만들기

1. 이름 — 소문자·숫자·하이픈, 앱과 함께 오는 플러그인 이름은 예약돼 있다(가이드 §2·§11). 폴더 이름 = 매니페스트 name.
2. 최소 구성 — package.json(tiguclaw 블록) + 진입점(기본 내보내기 클래스). 필요한 것만 구현한다: 도구 getTools() / 위젯 값 getDataRoutes() / 상시 동작 start() 와 stop().
3. needs 는 실제로 쓰는 것만. 모르는 키는 거부된다. 밖에 나가면 host.fetch 로만(전역 fetch 를 쓰면 선언이 거짓이 된다).
4. 값과 비밀을 코드에서 뺀다 — 사람에게 물을 값은 settings, 열쇠·토큰은 secret(플러그인 설정 파일엔 저장되지 않고 홈 .env 파일에 저장된다). 개인 자료·자격·사용자 경로를 코드·매니페스트·예시에 박지 않는다.
5. AI 판단이 필요한 기능(전처리 → 모델 → 후처리)이면 needs.llm 과 host.ask 를 쓴다. 계약(받는 이름·반환·reason·한계)은 가이드 §7 이 정본이다. 만들 때 지킬 것만:
   • 모델을 고르게 하려면 settings 에 프로필 칸({ "key": "profile", "type": "string" })을 두고 그 값을 넘긴다. 칸이 비면 기본 모델로 돈다. 사용자가 «싼 모델로» 처럼 원하는 모델을 말했으면 어느 프로필인지 확인하고, 설치 뒤 그 플러그인 설정에서 그 이름을 고르도록 안내한다 — 모델·프로필 이름을 코드에 박지 않는다.

   • import { randomUUID } from "node:crypto"; // 진입점 파일 맨 위
     // 서로 독립인 호출이면 scope 를 호출마다 다르게 — 같은 scope 는 앞 호출의 이력을 이어 본다
     const a = await host.ask({ prompt, scope: `note-${randomUUID()}`, profile: host.settings.profile });
     if (!a.ok) return { text: `실패(${a.reason})`, isError: true }; // 문구가 아니라 reason 으로 분기

   • 그 모델은 도구를 쓰지 않는다. 가져오기·읽기는 플러그인 코드가 하고(host.fetch), 모델엔 판단·종합만 맡긴다. 웹·API 내용은 프롬프트에 «믿을 수 없는 데이터» 로 표시한다. 출처가 있으면 실제로 읽은 것과 목록에서만 본 것을 가른다.
   • 도구 호출 하나에서 ask 를 여러 번 부르거나 오래 걸리는 작업 뒤에 두지 않는다 — 호출 수·총비용 상한이 없다(가이드 §7 «한계»). 이 한계는 사용자에게도 말한다.
6. 끌 때 정리 — stop()/dispose() 에서 타이머·구독을 푼다.

5. 고치기

• 먼저 읽는다 — 매니페스트·진입점·그 폴더의 관례(언어·빌드 산출물·구조). 그 관례를 따른다.
• 앱과 함께 오는(번들) 플러그인은 앱 소스다. 기본은 고치지 않는다. 먼저 대안을 낸다 — 그 플러그인 설정에 해당 값이 있으면 설정으로, 없으면 다른 이름의 홈 플러그인으로 만들기(번들 이름은 예약이라 같은 이름은 못 쓴다). 사용자가 그래도 앱 소스 수정을 원하면 «업데이트에 덮이고 되돌리기 전까지 /update 가 막힌다» 를 알리고 확인받은 뒤에만 한다.
• 홈에 설치된 플러그인을 고칠 때 반영 시점이 둘이다: 데몬 쪽 코드(진입점과 그것이 부르는 파일)는 지금 도는 것이 안 바뀌고 다음 시작 때 바뀐 코드가 실행된다. 브라우저 쪽 파일(web/ 아래 위젯 코드·문구)은 요청마다 새로 읽혀, 재시작 없이 다음 화면 로드부터 바뀐 코드가 돈다. 고치기 전에 원본을 <홈>/workspace/.trash/ 에 백업한다.
• needs 가 늘거나 하는 일이 넓어지면 §2 를 다시 하고 무엇이 늘었는지 말한다.
• 플러그인 설정값 파일(<홈>/plugins/<이름>/settings.json)과 홈 .env 는 사용자 데이터다 — 코드 수정에 섞어 바꾸지 않는다.

6. 위젯 — 명시 요청 시만

• 브라우저 쪽 web/widget.js 에서 window.tiguWidgets.register("<이름>/<id>", …), 매니페스트 widgets 에 같은 id 를 선언한다. 값은 getDataRoutes() 로 받는다. 정리는 ctx.onDispose, 문구는 web/locales/, 색은 테마 토큰(가이드 §5-1·§6·§8).
• 대화 중 답에 붙는 카드(host.postCard)를 쓸 때만 needs.ui: ["chat-widget"].
• 위젯 설정에 열쇠·토큰을 넣지 않는다(브라우저로 나가고 백업에 든다).
• 사용자가 설치한 플러그인의 default: true 는 자동 배치되지 않는다. 위젯 패널에 놓는 것은 사용자가 요청할 때 configure_home 으로 한다.
• 작업 폴더의 위젯은 화면에 안 보인다 — 위젯 제작의 완료 확인은 §7 의 정적 확인까지이고, 화면 확인은 설치 뒤다(설치는 §3).

7. 확인 — 실행하지 않는 것부터

1. 정적 확인(코드를 실행하지 않는다): package.json 이 JSON 으로 읽히고 name·entry·needs 키·settings 타입·widgets id 가 가이드 규칙에 맞는지, node --check <진입점>·node --check web/widget.js.
2. 돌려 보는 확인(핸들러 호출 등)은 코드를 실행하는 일이다. 밖으로 나가거나(네트워크) 파일을 쓰거나 모델을 부르는 코드면 그 내용을 보여 주고 확인받은 뒤에만 한다.
3. 실제 로드 확인은 설치 뒤 로그의 [plugin-loader] 줄로 한다(가이드 §12) — 설치는 §3 대로 따로 확인받는다.

보고: 만든·고친 파일 · needs 와 위험 평가 요약 · 확인한 것과 확인하지 않은 것 · 다음 단계 제안(설치·배치·패키징).

8. 패키징 — 요청 시만

• 세 형태(가이드 §10): 소스 폴더 / 번들 .js / npm pack. ★npm pack 결과는 루트가 package/ 다 — 풀 때 폴더 이름을 플러그인 이름으로 바꿔야 한다(안 바꾸면 위젯 자산·host.dataDir 이 반쪽만 된다).
• 묶기 전에 빠질 것을 확인한다: 플러그인 설정값 파일·.env·dataDir 의 데이터·토큰·개인 경로. package.json 의 files 로 포함 목록을 정한다.
• ★npm pack 은 --dry-run 이어도 package.json 의 prepack·postpack 같은 스크립트를 실행한다. 그래서 목록 확인은 npm pack --dry-run --ignore-scripts 로 하고, 실제로 묶을 때 스크립트가 필요하면 그 내용을 먼저 보여 주고 실행 확인을 받는다(묶어 달라는 요청은 스크립트 실행의 동의가 아니다).
• 공유·출판(npm publish·업로드·전송)은 출판을 명시적으로 요청받았을 때만 한다(«npm 에 올려 줘» 같은). 그때도 나갈 파일 목록·이름·버전을 보여 주고 한 번 확인받은 뒤에 한다. 로그인·토큰은 사용자가 직접 넣는다 — 받거나 대신 입력하지 않는다. 출판 요청이 없으면 산출물 경로만 알려 준다.