cdsa-harness 0.6.0 → 0.11.1

package/README.md

@@ -18,13 +18,31 @@
 
 ---
 
-## 설치 / 실행
+## 설치 / 실행 — 둘 중 하나 선택
 
+### 방법 1) Node.js + npm (개발자·일반)
+Node 18+ 가 있으면:
 ```bash
 npx cdsa-harness                 # 설치 없이 즉시 (키 없으면 mock)
 npm install -g cdsa-harness      # 전역 설치 → 'cdsa-harness' / 'cdsa'
 ```
 
+### 방법 2) 단일 실행파일 다운로드 (Node 불필요 · 폐쇄망)
+**Node 설치 없이** 파일 하나만 받아 실행합니다. 공공/폐쇄망에 적합.
+1. [Releases](https://github.com/cdsassj00/miniharness/releases) 에서 OS 에 맞는 파일 다운로드
+   - Windows: `cdsa-harness-win.exe`
+   - macOS: `cdsa-harness-macos`
+   - Linux: `cdsa-harness-linux`
+2. 실행:
+   ```bash
+   # Windows (PowerShell)
+   .\cdsa-harness-win.exe
+   # macOS / Linux (실행권한 부여 후)
+   chmod +x ./cdsa-harness-linux && ./cdsa-harness-linux
+   ```
+> 이 바이너리는 Node 런타임을 포함(약 100MB+)하므로 Node 설치가 필요 없습니다.
+> 내장 스킬·플러그인(HWPX 포함)도 모두 들어있어 단독 실행됩니다.
+
 ## 실제 AI 연결하기
 
 가장 쉬운 길 — 실행 후 `/setup` 입력(대화형으로 제공자·키·모델 선택):
@@ -131,7 +149,19 @@ export default {
 ## 🎯 스킬 (프롬프트 템플릿)
 
 `.cdsa/skills/` 에 마크다운을 두면 `/파일명` 으로 실행됩니다. 본문의 `$ARGUMENTS`(또는 `{{args}}`)가 치환됩니다.
-**다른 에이전트의 스킬도 인식** — `.claude/commands/`, `.claude/skills/<이름>/SKILL.md`, `.opencode/command/` 등을 함께 읽습니다. `/skills` 로 목록 확인.
+
+- **기본 내장 스킬**(설치하면 누구에게나 제공):
+  - 실용: `/explain` 쉽게 설명 · `/review` 코드 리뷰 · `/summarize` 3줄 요약 · `/tour` 프로젝트 브리핑 · `/todo` 미완성(TODO) 수집 · `/plan` 실행 전 계획만
+  - 교육/재미: `/eli5` 5살도 알게 · `/rubberduck` 질문으로 디버깅 · `/quiz` 학습 퀴즈 · `/haiku` 하이쿠 · `/loop` 이 요청을 에이전트 루프로 어떻게 처리할지 해설
+  - **🇰🇷 공공(대한민국)**: `/minwon` 민원분류 · `/gongmun` 공문 기안 · `/privacy` 개인정보 점검 · `/press` 보도자료 · `/report` 개조식 보고 · `/minutes` 회의록 · `/policyqa` 정책 Q&A · `/hwpx` 한컴 문서 요약
+
+## 🇰🇷 공공 특화 + HWPX
+
+- **공공 스킬** — 위 `/minwon` `/gongmun` `/privacy` 등으로 민원·공문·개인정보·보도자료 등 행정 업무를 바로 시도.
+- **HWPX 내장 도구(`hwpx_read`)** — 한컴 `.hwpx` 문서(zip+xml)에서 본문 텍스트를 **의존성 없이** 추출. `/hwpx 파일.hwpx` 로 읽어 요약.
+  - 구버전 `.hwp`(바이너리)는 한컴오피스에서 `.hwpx` 로 저장 후 사용.
+- **다른 에이전트의 스킬도 인식** — `.claude/commands/`, `.claude/skills/<이름>/SKILL.md`, `.opencode/command/` 등을 함께 읽습니다.
+- **남과 공유**하려면: 로컬 스킬 파일은 본인만 쓰지만, 플러그인 패키지(`{ skills: [...] }`)로 npm 배포하면 `cdsa-harness add` 한 모두가 사용. `/skills` 로 목록 확인.
 
 ```markdown
 ---
@@ -141,6 +171,31 @@ $ARGUMENTS 파일을 read_file 로 읽고 핵심을 한국어 3줄로 요약해
 ```
 실행: `/summarize notes.txt`
 
+## 🏢 폐쇄망 / 오프라인 설치
+
+의존성이 **0개**라 폐쇄망 배포가 쉽습니다(추가 다운로드 없음).
+
+**Node 가 이미 있는 경우 — tgz 반입 후 오프라인 설치:**
+```bash
+# (외부망) 패키지 묶기
+npm pack cdsa-harness          # → cdsa-harness-x.y.z.tgz 생성
+# (폐쇄망으로 파일 반입 후)
+npm install -g ./cdsa-harness-x.y.z.tgz   # 인터넷 불필요
+```
+
+**사내/폐쇄망 LLM (OpenAI 호환 서버 — vLLM, 내부 게이트웨이 등):**
+`config.json` 의 `base_url` 에 **전체 엔드포인트**를 적으면 그쪽으로 호출합니다.
+```json
+{
+  "provider": "openai",
+  "base_url": "https://llm.내부망.local/v1/chat/completions",
+  "api_key": "사내토큰",
+  "model": "사내모델명"
+}
+```
+
+> Node 자체를 못 까는 환경은 **단일 실행파일(.exe)** 빌드가 답입니다(로드맵).
+
 ## 설정 (config.json)
 
 `~/.cdsa_harness/config.json` (실행 폴더에 `config.json` 있으면 우선).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdsa-harness",
-  "version": "0.6.0",
+  "version": "0.11.1",
   "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. 실시간 스트리밍 + OpenAI/Claude/OpenRouter + MCP + npm 플러그인·크로스포맷 스킬.",
   "type": "module",
   "bin": {
@@ -12,11 +12,16 @@
   },
   "scripts": {
     "start": "node bin/cdsa-harness.js",
-    "test": "node --test"
+    "test": "node --test",
+    "gen": "node scripts/gen-builtins.mjs",
+    "build:exe": "node scripts/build-exe.mjs",
+    "prepack": "node scripts/gen-builtins.mjs"
   },
   "files": [
     "bin",
     "src",
+    "skills",
+    "plugins",
     "workspace",
     "README.md"
   ],
@@ -30,7 +35,7 @@
     "llm",
     "education"
   ],
-  "author": "cdsassj00",
+  "author": "CDSA",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,5 +45,9 @@
   "homepage": "https://github.com/cdsassj00/miniharness/tree/main/node-cli#readme",
   "bugs": {
     "url": "https://github.com/cdsassj00/miniharness/issues"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1",
+    "postject": "^1.0.0-alpha.6"
   }
 }

package/plugins/hwpx_read.mjs

@@ -0,0 +1,95 @@
+// 내장 플러그인: 한컴 HWPX 문서에서 본문 텍스트를 추출한다.
+// HWPX 는 ZIP 컨테이너(안에 Contents/section*.xml). 의존성 없이 zlib 로 직접 푼다.
+// (구버전 .hwp 는 바이너리 OLE 포맷이라 여기서는 안내만 한다 — .hwpx 로 저장 권장)
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+
+// --- 아주 작은 ZIP 리더 (method 0=저장, 8=deflate 지원) ---
+function readZipEntries(buf) {
+  // End of Central Directory 찾기(뒤에서부터 시그니처 0x06054b50)
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= 0 && i > buf.length - 22 - 65536; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error("ZIP(EOCD)을 찾을 수 없습니다 — HWPX 가 아닐 수 있어요");
+  const count = buf.readUInt16LE(eocd + 10);
+  let off = buf.readUInt32LE(eocd + 16); // central directory 시작
+  const entries = [];
+  for (let n = 0; n < count; n++) {
+    if (buf.readUInt32LE(off) !== 0x02014b50) break;
+    const method = buf.readUInt16LE(off + 10);
+    const compSize = buf.readUInt32LE(off + 20);
+    const nameLen = buf.readUInt16LE(off + 28);
+    const extraLen = buf.readUInt16LE(off + 30);
+    const commentLen = buf.readUInt16LE(off + 32);
+    const localOff = buf.readUInt32LE(off + 42);
+    const name = buf.toString("utf8", off + 46, off + 46 + nameLen);
+    entries.push({ name, method, compSize, localOff });
+    off += 46 + nameLen + extraLen + commentLen;
+  }
+  return entries;
+}
+
+function extractEntry(buf, entry) {
+  // local file header 에서 실제 데이터 시작 계산
+  const lo = entry.localOff;
+  if (buf.readUInt32LE(lo) !== 0x04034b50) throw new Error("로컬 헤더 손상");
+  const nameLen = buf.readUInt16LE(lo + 26);
+  const extraLen = buf.readUInt16LE(lo + 28);
+  const start = lo + 30 + nameLen + extraLen;
+  const data = buf.subarray(start, start + entry.compSize);
+  if (entry.method === 0) return data; // 저장(무압축)
+  if (entry.method === 8) return zlib.inflateRawSync(data); // deflate
+  throw new Error(`지원하지 않는 압축 방식(${entry.method})`);
+}
+
+// HWPX section XML 의 <hp:t>...</hp:t> 텍스트 런을 모아 평문으로.
+function xmlToText(xml) {
+  const runs = [];
+  const re = /<hp:t[^>]*>([\s\S]*?)<\/hp:t>/g;
+  let m;
+  while ((m = re.exec(xml)) !== null) runs.push(m[1]);
+  let text = runs.join("");
+  if (!text) text = xml.replace(/<[^>]+>/g, ""); // 폴백: 모든 태그 제거
+  return text
+    .replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&")
+    .replace(/&quot;/g, '"').replace(/&#13;/g, "").replace(/&#10;/g, "\n")
+    .replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+export default {
+  name: "hwpx_read",
+  description: "한컴 HWPX(.hwpx) 문서에서 본문 텍스트를 추출한다. 구버전 .hwp 는 .hwpx 로 저장 후 사용.",
+  parameters: {
+    type: "object",
+    properties: { path: { type: "string", description: "작업 폴더 기준 .hwpx 상대 경로" } },
+    required: ["path"],
+  },
+  mutating: false,
+  async handler(args, ctx) {
+    const rel = (args.path || "").trim();
+    const target = path.resolve(ctx.workspace, rel);
+    if (target !== ctx.workspace && !target.startsWith(ctx.workspace + path.sep)) {
+      return "작업 폴더 밖 경로에는 접근할 수 없습니다.";
+    }
+    if (/\.hwp$/i.test(rel)) {
+      return "구버전 .hwp(바이너리)는 직접 지원하지 않습니다. 한컴오피스에서 '다른 이름으로 저장 → .hwpx' 후 다시 시도하세요.";
+    }
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) return `파일이 없습니다: ${rel}`;
+    try {
+      const buf = fs.readFileSync(target);
+      const entries = readZipEntries(buf);
+      const sections = entries
+        .filter((e) => /Contents\/section\d+\.xml$/i.test(e.name))
+        .sort((a, b) => a.name.localeCompare(b.name));
+      if (!sections.length) return "HWPX 본문(Contents/section*.xml)을 찾지 못했습니다.";
+      const parts = sections.map((e) => xmlToText(extractEntry(buf, e).toString("utf8")));
+      const text = parts.join("\n\n").trim();
+      const clipped = text.length > 12000 ? text.slice(0, 12000) + "\n... (이후 생략)" : text;
+      return `[HWPX 본문 추출: ${rel}]\n\n${clipped || "(본문 텍스트 없음)"}`;
+    } catch (e) {
+      return `HWPX 파싱 실패: ${e.message}`;
+    }
+  },
+};

package/skills/eli5.md

@@ -0,0 +1,6 @@
+---
+description: 지정한 파일/개념을 5살도 알게 아주 쉽게 설명
+---
+$ARGUMENTS 을(를) 다섯 살 아이도 이해할 수 있게 아주 쉬운 비유로 설명해줘.
+파일 이름이면 read_file 로 읽고 설명해. 전문용어는 풀어서 쓰고, 그림 그리듯 비유를 들어줘.
+파일은 수정하지 마.

package/skills/explain.md

@@ -0,0 +1,5 @@
+---
+description: 파일/코드를 읽고 비개발자도 알게 쉽게 설명
+---
+$ARGUMENTS 을(를) read_file 도구로 읽고, 무엇을 하는 코드/문서인지
+비개발자도 이해할 수 있게 한국어로 차근차근 설명해줘. 실제 수정은 하지 마.

package/skills/gongmun.md

@@ -0,0 +1,6 @@
+---
+description: 공문서(기안문) 초안 작성 — 제목/수신/본문/붙임 [공공]
+---
+"$ARGUMENTS" 내용을 바탕으로 대한민국 행정 공문서(기안문) 초안을 작성해줘.
+형식: 제목 / 수신 / (경유) / 본문(개조식, 'ㅇ' 글머리) / 붙임.
+정중한 공공 문체로. 사실이 불확실한 부분은 [   ] 로 비워 '채울 항목'임을 표시해줘.

package/skills/haiku.md

@@ -0,0 +1,6 @@
+---
+description: 파일이나 주제로 하이쿠(짧은 3줄 시) 짓기 — 재미용
+---
+$ARGUMENTS (파일명이면 read_file 로 그 내용을 읽어)를 주제로,
+5-7-5 운율을 살린 한국어 하이쿠를 한 편 지어줘. 짧고 운치 있게.
+파일은 절대 건드리지 말고 시만 보여줘.

package/skills/hwpx.md

@@ -0,0 +1,6 @@
+---
+description: 한컴 HWPX(.hwpx) 문서를 읽어 핵심을 개조식으로 요약 [공공]
+---
+$ARGUMENTS 파일을 hwpx_read 도구로 읽어 본문 텍스트를 추출한 뒤,
+핵심 내용을 한국어 개조식('ㅇ' 글머리)으로 요약해줘. 파일은 수정하지 마.
+(.hwp 구버전이면 .hwpx 로 저장 후 다시 시도하라고 안내해줘.)

package/skills/loop.md

@@ -0,0 +1,7 @@
+---
+description: 이 요청을 '에이전트 루프' 관점에서 어떻게 처리할지 메타 해설 (CDSA 특별)
+---
+다음 요청을 실제로 수행하기 전에, CDSA Harness 의 에이전트 루프
+(컨텍스트 구성 → LLM 호출 → 도구 판단 → 실행 → 결과 되먹임) 관점에서
+어떤 도구를 어떤 순서로 부를 계획인지 단계별로 한국어로 먼저 설명해줘: $ARGUMENTS
+설명만 하고, 이번에는 실제 도구 호출(특히 write_file)은 하지 마.

package/skills/minutes.md

@@ -0,0 +1,7 @@
+---
+description: 회의 내용을 표준 회의록으로 정리(안건/논의/결정/조치) [공공]
+---
+$ARGUMENTS (파일명이면 read_file 로 읽어)를 회의록으로 정리해줘.
+머리말: 일시[   ] / 장소[   ] / 참석[   ].
+본문: 안건별로 [논의내용] · [결정사항] · [조치사항(담당/기한)] 을 개조식으로.
+한국어로 깔끔하게. 파일은 수정하지 마.

package/skills/minwon.md

@@ -0,0 +1,7 @@
+---
+description: 민원 내용을 분류(분야·담당부서·긴급도)하고 처리 방향 제안 [공공]
+---
+다음 민원을 분석해줘($ARGUMENTS 가 파일명이면 read_file 로 읽어).
+표 형태로 한국어로 깔끔하게 정리해줘:
+1) 분야 분류  2) 담당 부서(추정)  3) 긴급도(상/중/하)  4) 핵심 요지 1줄  5) 처리 방향 제안
+개인정보(연락처·주민번호 등)가 보이면 마스킹해서 표시해줘. 파일은 수정하지 마.

package/skills/plan.md

@@ -0,0 +1,6 @@
+---
+description: 시킨 작업을 '실행하지 말고' 단계별 계획만 세우기
+---
+다음 작업을 실제로 수행하지 말고, 어떻게 처리할지 단계별 계획만 세워줘: $ARGUMENTS
+필요하면 read_file / list_dir 로 사실만 확인하되, write_file 은 절대 호출하지 마.
+각 단계마다 '왜 그 단계가 필요한지'도 한 줄씩 덧붙여줘.

package/skills/policyqa.md

@@ -0,0 +1,6 @@
+---
+description: 정책·제도 질문에 근거를 들어 설명(모르면 모른다고) [공공]
+---
+다음 질문에 공공 정책·행정 관점에서 한국어로 답해줘: $ARGUMENTS
+필요하면 작업 폴더의 관련 문서를 read_file 로 확인해 근거로 삼아.
+확실하지 않은 부분은 추측하지 말고 '확인 필요'로 표시하고, 어디서/누구에게 확인하면 되는지 안내해줘.

package/skills/press.md

@@ -0,0 +1,6 @@
+---
+description: 보도자료 초안 작성(제목/부제/리드/본문/문의처) [공공]
+---
+"$ARGUMENTS" 를 주제로 공공기관 보도자료 초안을 작성해줘.
+구성: 제목 / 부제 / 리드(핵심 1문단) / 본문(육하원칙) / 기대효과 / 문의처[   ].
+객관적이고 간결한 보도 문체로 한국어로 작성해줘.

package/skills/privacy.md

@@ -0,0 +1,7 @@
+---
+description: 개인정보(주민번호·연락처·이메일·계좌 등) 점검 및 마스킹 제안 [공공]
+---
+$ARGUMENTS (파일명이면 read_file 로 읽어)에서 개인정보로 보이는 항목
+(주민등록번호, 휴대전화, 이메일, 주소, 계좌·카드번호, 여권번호 등)을 찾아
+'유형 — 발견 위치 — 마스킹 예시(예: 010-****-1234)' 표로 정리해줘.
+하나도 없으면 없다고 명확히 말해줘. 파일은 절대 수정하지 말고 점검 보고만 해줘.

package/skills/quiz.md

@@ -0,0 +1,6 @@
+---
+description: 작업 폴더 코드/문서로 학습 퀴즈 만들기
+---
+작업 폴더를 list_dir / read_file 로 살펴보고, 이 코드·문서를 공부할 수 있는
+객관식 퀴즈 3문제를 한국어로 만들어줘($ARGUMENTS 주제가 있으면 그쪽으로).
+각 문제에 보기 4개와 정답, 그리고 한 줄 해설을 달아줘. 파일은 수정하지 마.

package/skills/report.md

@@ -0,0 +1,6 @@
+---
+description: 개조식 1쪽 보고서로 요약(추진배경/현황/문제점/개선방안) [공공]
+---
+$ARGUMENTS (파일명이면 read_file 로 읽어)를 대한민국 공공 보고서 양식의 개조식으로
+1쪽 분량으로 요약해줘. 항목: □ 추진배경 / □ 현황 / □ 문제점 / □ 개선방안 / □ 기대효과.
+각 항목은 'ㅇ' 글머리로 간결하게. 파일은 수정하지 마.

package/skills/review.md

@@ -0,0 +1,5 @@
+---
+description: 파일을 읽고 버그 위험·개선점을 리뷰
+---
+$ARGUMENTS 파일을 read_file 도구로 읽고, 버그 위험·가독성·개선점을 한국어로 짚어줘.
+실제 수정은 하지 말고, 무엇을 어떻게 고치면 좋을지 제안만 해줘.

package/skills/rubberduck.md

@@ -0,0 +1,7 @@
+---
+description: 러버덕 디버깅 — 답 대신 질문으로 스스로 찾게 돕기
+---
+당신은 '러버덕(고무오리)' 디버깅 파트너입니다. 사용자의 고민: $ARGUMENTS
+바로 정답을 주지 말고, 문제를 좁히는 좋은 질문 3~5개를 한국어로 던져줘.
+필요하면 read_file 로 관련 파일을 살펴봐도 되지만, 절대 수정하지 마.
+마지막에 "이 중 어디부터 확인해볼까요?" 라고 물어줘.

package/skills/summarize.md

@@ -0,0 +1,5 @@
+---
+description: 지정한 파일을 읽고 한국어 3줄로 요약
+---
+$ARGUMENTS 파일을 read_file 도구로 읽은 다음, 핵심 내용을 한국어 3줄로 요약해줘.
+파일을 수정하지는 말고, 요약만 보여줘.

package/skills/todo.md

@@ -0,0 +1,6 @@
+---
+description: 작업 폴더에서 TODO/FIXME 주석을 모아 목록화
+---
+작업 폴더의 파일들을 list_dir / read_file 로 훑어 TODO, FIXME, XXX, HACK 같은
+미완성 표시가 있는 곳을 찾아 '파일 — 해당 줄 내용' 형태의 한국어 목록으로 정리해줘.
+하나도 없으면 없다고 분명히 말해줘. 파일은 수정하지 마.

package/skills/tour.md

@@ -0,0 +1,6 @@
+---
+description: 작업 폴더를 둘러보고 이 프로젝트가 무엇인지 브리핑
+---
+작업 폴더를 list_dir 로 살펴보고, 핵심으로 보이는 파일 2~4개를 read_file 로 읽어
+이 프로젝트가 무엇이고 어떤 구조인지 한국어로 친절하게 브리핑해줘.
+$ARGUMENTS 가 있으면 그 주제에 초점을 맞춰. 파일은 절대 수정하지 마.

package/src/builtins.js

@@ -0,0 +1,105 @@
+// AUTO-GENERATED by scripts/gen-builtins.mjs — 직접 수정하지 마세요.
+// 스킬/플러그인/버전을 바꾼 뒤 `node scripts/gen-builtins.mjs` 로 재생성하세요.
+import p0 from "../plugins/hwpx_read.mjs";
+
+export const VERSION = "0.11.1";
+
+export const BUILTIN_PLUGINS = [p0];
+
+export const BUILTIN_SKILLS = [
+  {
+    "name": "eli5",
+    "description": "지정한 파일/개념을 5살도 알게 아주 쉽게 설명",
+    "body": "$ARGUMENTS 을(를) 다섯 살 아이도 이해할 수 있게 아주 쉬운 비유로 설명해줘.\n파일 이름이면 read_file 로 읽고 설명해. 전문용어는 풀어서 쓰고, 그림 그리듯 비유를 들어줘.\n파일은 수정하지 마."
+  },
+  {
+    "name": "explain",
+    "description": "파일/코드를 읽고 비개발자도 알게 쉽게 설명",
+    "body": "$ARGUMENTS 을(를) read_file 도구로 읽고, 무엇을 하는 코드/문서인지\n비개발자도 이해할 수 있게 한국어로 차근차근 설명해줘. 실제 수정은 하지 마."
+  },
+  {
+    "name": "gongmun",
+    "description": "공문서(기안문) 초안 작성 — 제목/수신/본문/붙임 [공공]",
+    "body": "\"$ARGUMENTS\" 내용을 바탕으로 대한민국 행정 공문서(기안문) 초안을 작성해줘.\n형식: 제목 / 수신 / (경유) / 본문(개조식, 'ㅇ' 글머리) / 붙임.\n정중한 공공 문체로. 사실이 불확실한 부분은 [   ] 로 비워 '채울 항목'임을 표시해줘."
+  },
+  {
+    "name": "haiku",
+    "description": "파일이나 주제로 하이쿠(짧은 3줄 시) 짓기 — 재미용",
+    "body": "$ARGUMENTS (파일명이면 read_file 로 그 내용을 읽어)를 주제로,\n5-7-5 운율을 살린 한국어 하이쿠를 한 편 지어줘. 짧고 운치 있게.\n파일은 절대 건드리지 말고 시만 보여줘."
+  },
+  {
+    "name": "hwpx",
+    "description": "한컴 HWPX(.hwpx) 문서를 읽어 핵심을 개조식으로 요약 [공공]",
+    "body": "$ARGUMENTS 파일을 hwpx_read 도구로 읽어 본문 텍스트를 추출한 뒤,\n핵심 내용을 한국어 개조식('ㅇ' 글머리)으로 요약해줘. 파일은 수정하지 마.\n(.hwp 구버전이면 .hwpx 로 저장 후 다시 시도하라고 안내해줘.)"
+  },
+  {
+    "name": "loop",
+    "description": "이 요청을 '에이전트 루프' 관점에서 어떻게 처리할지 메타 해설 (CDSA 특별)",
+    "body": "다음 요청을 실제로 수행하기 전에, CDSA Harness 의 에이전트 루프\n(컨텍스트 구성 → LLM 호출 → 도구 판단 → 실행 → 결과 되먹임) 관점에서\n어떤 도구를 어떤 순서로 부를 계획인지 단계별로 한국어로 먼저 설명해줘: $ARGUMENTS\n설명만 하고, 이번에는 실제 도구 호출(특히 write_file)은 하지 마."
+  },
+  {
+    "name": "minutes",
+    "description": "회의 내용을 표준 회의록으로 정리(안건/논의/결정/조치) [공공]",
+    "body": "$ARGUMENTS (파일명이면 read_file 로 읽어)를 회의록으로 정리해줘.\n머리말: 일시[   ] / 장소[   ] / 참석[   ].\n본문: 안건별로 [논의내용] · [결정사항] · [조치사항(담당/기한)] 을 개조식으로.\n한국어로 깔끔하게. 파일은 수정하지 마."
+  },
+  {
+    "name": "minwon",
+    "description": "민원 내용을 분류(분야·담당부서·긴급도)하고 처리 방향 제안 [공공]",
+    "body": "다음 민원을 분석해줘($ARGUMENTS 가 파일명이면 read_file 로 읽어).\n표 형태로 한국어로 깔끔하게 정리해줘:\n1) 분야 분류  2) 담당 부서(추정)  3) 긴급도(상/중/하)  4) 핵심 요지 1줄  5) 처리 방향 제안\n개인정보(연락처·주민번호 등)가 보이면 마스킹해서 표시해줘. 파일은 수정하지 마."
+  },
+  {
+    "name": "plan",
+    "description": "시킨 작업을 '실행하지 말고' 단계별 계획만 세우기",
+    "body": "다음 작업을 실제로 수행하지 말고, 어떻게 처리할지 단계별 계획만 세워줘: $ARGUMENTS\n필요하면 read_file / list_dir 로 사실만 확인하되, write_file 은 절대 호출하지 마.\n각 단계마다 '왜 그 단계가 필요한지'도 한 줄씩 덧붙여줘."
+  },
+  {
+    "name": "policyqa",
+    "description": "정책·제도 질문에 근거를 들어 설명(모르면 모른다고) [공공]",
+    "body": "다음 질문에 공공 정책·행정 관점에서 한국어로 답해줘: $ARGUMENTS\n필요하면 작업 폴더의 관련 문서를 read_file 로 확인해 근거로 삼아.\n확실하지 않은 부분은 추측하지 말고 '확인 필요'로 표시하고, 어디서/누구에게 확인하면 되는지 안내해줘."
+  },
+  {
+    "name": "press",
+    "description": "보도자료 초안 작성(제목/부제/리드/본문/문의처) [공공]",
+    "body": "\"$ARGUMENTS\" 를 주제로 공공기관 보도자료 초안을 작성해줘.\n구성: 제목 / 부제 / 리드(핵심 1문단) / 본문(육하원칙) / 기대효과 / 문의처[   ].\n객관적이고 간결한 보도 문체로 한국어로 작성해줘."
+  },
+  {
+    "name": "privacy",
+    "description": "개인정보(주민번호·연락처·이메일·계좌 등) 점검 및 마스킹 제안 [공공]",
+    "body": "$ARGUMENTS (파일명이면 read_file 로 읽어)에서 개인정보로 보이는 항목\n(주민등록번호, 휴대전화, 이메일, 주소, 계좌·카드번호, 여권번호 등)을 찾아\n'유형 — 발견 위치 — 마스킹 예시(예: 010-****-1234)' 표로 정리해줘.\n하나도 없으면 없다고 명확히 말해줘. 파일은 절대 수정하지 말고 점검 보고만 해줘."
+  },
+  {
+    "name": "quiz",
+    "description": "작업 폴더 코드/문서로 학습 퀴즈 만들기",
+    "body": "작업 폴더를 list_dir / read_file 로 살펴보고, 이 코드·문서를 공부할 수 있는\n객관식 퀴즈 3문제를 한국어로 만들어줘($ARGUMENTS 주제가 있으면 그쪽으로).\n각 문제에 보기 4개와 정답, 그리고 한 줄 해설을 달아줘. 파일은 수정하지 마."
+  },
+  {
+    "name": "report",
+    "description": "개조식 1쪽 보고서로 요약(추진배경/현황/문제점/개선방안) [공공]",
+    "body": "$ARGUMENTS (파일명이면 read_file 로 읽어)를 대한민국 공공 보고서 양식의 개조식으로\n1쪽 분량으로 요약해줘. 항목: □ 추진배경 / □ 현황 / □ 문제점 / □ 개선방안 / □ 기대효과.\n각 항목은 'ㅇ' 글머리로 간결하게. 파일은 수정하지 마."
+  },
+  {
+    "name": "review",
+    "description": "파일을 읽고 버그 위험·개선점을 리뷰",
+    "body": "$ARGUMENTS 파일을 read_file 도구로 읽고, 버그 위험·가독성·개선점을 한국어로 짚어줘.\n실제 수정은 하지 말고, 무엇을 어떻게 고치면 좋을지 제안만 해줘."
+  },
+  {
+    "name": "rubberduck",
+    "description": "러버덕 디버깅 — 답 대신 질문으로 스스로 찾게 돕기",
+    "body": "당신은 '러버덕(고무오리)' 디버깅 파트너입니다. 사용자의 고민: $ARGUMENTS\n바로 정답을 주지 말고, 문제를 좁히는 좋은 질문 3~5개를 한국어로 던져줘.\n필요하면 read_file 로 관련 파일을 살펴봐도 되지만, 절대 수정하지 마.\n마지막에 \"이 중 어디부터 확인해볼까요?\" 라고 물어줘."
+  },
+  {
+    "name": "summarize",
+    "description": "지정한 파일을 읽고 한국어 3줄로 요약",
+    "body": "$ARGUMENTS 파일을 read_file 도구로 읽은 다음, 핵심 내용을 한국어 3줄로 요약해줘.\n파일을 수정하지는 말고, 요약만 보여줘."
+  },
+  {
+    "name": "todo",
+    "description": "작업 폴더에서 TODO/FIXME 주석을 모아 목록화",
+    "body": "작업 폴더의 파일들을 list_dir / read_file 로 훑어 TODO, FIXME, XXX, HACK 같은\n미완성 표시가 있는 곳을 찾아 '파일 — 해당 줄 내용' 형태의 한국어 목록으로 정리해줘.\n하나도 없으면 없다고 분명히 말해줘. 파일은 수정하지 마."
+  },
+  {
+    "name": "tour",
+    "description": "작업 폴더를 둘러보고 이 프로젝트가 무엇인지 브리핑",
+    "body": "작업 폴더를 list_dir 로 살펴보고, 핵심으로 보이는 파일 2~4개를 read_file 로 읽어\n이 프로젝트가 무엇이고 어떤 구조인지 한국어로 친절하게 브리핑해줘.\n$ARGUMENTS 가 있으면 그 주제에 초점을 맞춰. 파일은 절대 수정하지 마."
+  }
+];

package/src/cli.js

@@ -2,9 +2,11 @@
 // 핵심 차별점: '교육 모드' — 실제 API 를 붙여도 에이전트 내부에서 벌어지는 일
 // (컨텍스트 구성 → API 요청 → 모델 판단 → 토큰/지연 → 도구 실행 → 결과 되먹임)을 단계별로 드러낸다.
 import readline from "node:readline/promises";
+import path from "node:path";
 import { stdin, stdout } from "node:process";
 
 import { renderBanner } from "./banner.js";
+import { VERSION } from "./builtins.js";
 import {
   ENV_KEYS,
   PROVIDERS,
@@ -24,7 +26,7 @@ import { loadSkills, renderSkill } from "./skills.js";
 import { Toolbox } from "./tools.js";
 import { c, panel, renderDiff } from "./ui.js";
 
-const VERSION = "0.2.0";
+// VERSION 은 src/builtins.js(생성물)에서 가져온다 — npm/exe 양쪽에서 동일.
 
 const STEP_STYLE = {
   [Step.USER_INPUT]: ["🧑", "cyan"],
@@ -200,18 +202,20 @@ function makeClient(cfg) {
     model: cfg.model,
     temperature: cfg.temperature,
     maxTokens: cfg.max_tokens,
+    baseUrl: cfg.base_url,
   });
 }
 
 function printIntro(cfg) {
   console.log(renderBanner());
-  console.log(c.dim("AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 하네스"));
+  console.log(c.dim("AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 하네스") + "  " + c.cyan("· made by CDSA"));
   console.log();
   const keySource = cfg.provider === "mock" ? "-" : cfg.api_key ? "config.json" : ENV_KEYS[cfg.provider] && process.env[ENV_KEYS[cfg.provider]] ? `환경변수 ${ENV_KEYS[cfg.provider]}` : c.red("없음");
   const rows = [
     ["버전", `v${VERSION}`],
     ["provider", cfg.provider],
     ["model", cfg.model],
+    ...(cfg.base_url ? [["엔드포인트", cfg.base_url]] : []),
     ["API 키", keySource],
     ["교육 모드", cfg.teach_mode ? c.green("ON (과정 펼쳐보기)") : "OFF"],
     ["스트리밍", cfg.stream ? c.green("ON (실시간)") : "OFF"],
@@ -235,6 +239,7 @@ function printHelp() {
         `시키고 싶은 일을 한국어로 입력하세요. 예) ${c.cyan("notes.txt 맨 아래에 할 일 3개 추가해줘")}`,
         "",
         c.bold("슬래시 명령"),
+        `  ${c.cyan("/about")}    이 도구 정보(made by CDSA)`,
         `  ${c.cyan("/setup")}    제공자·API 키·모델 연결(대화형)`,
         `  ${c.cyan("/provider")} <openai|anthropic|openrouter|mock> 제공자 변경`,
         `  ${c.cyan("/model")} <이름>   모델 변경`,
@@ -436,7 +441,10 @@ export async function main(argv = []) {
   ];
   const skills = {};
   for (const s of npm.skills) skills[s.name] = { name: s.name, description: s.description || "", body: s.body, source: "(npm)" };
-  Object.assign(skills, loadSkills(cfg.workspacePath())); // 로컬 파일 스킬이 우선
+  Object.assign(
+    skills,
+    loadSkills(cfg.workspacePath(), { importForeign: cfg.import_foreign_skills, extraDirs: cfg.skill_dirs || [] })
+  ); // 로컬 파일 스킬이 우선
   const toolbox = new Toolbox(cfg.workspacePath(), cfg.allow_shell, plugins);
   if (toolbox.plugins.length || Object.keys(skills).length || toolbox.pluginErrors.length || mcp.servers.length) {
     const bits = [];
@@ -479,6 +487,18 @@ export async function main(argv = []) {
 
     if (["/quit", "/exit", "quit", "exit", ":q"].includes(low)) break;
     if (low === "/help") { printHelp(); continue; }
+    if (low === "/about") {
+      console.log(panel([
+        c.bold("CDSA Harness") + c.grey(`  v${VERSION}`),
+        c.dim("AI 에이전트가 내부에서 무슨 일을 하는지 단계별로 드러내는 공개 교육용 하네스."),
+        "",
+        `${c.grey("made by")}  ${c.cyan(c.bold("CDSA"))}`,
+        `${c.grey("npm")}      npm i -g cdsa-harness`,
+        `${c.grey("repo")}     github.com/cdsassj00/miniharness`,
+        `${c.grey("license")}  MIT · 의존성 0개(Node 18+)`,
+      ], { title: "ℹ️  about", color: "cyan" }));
+      continue;
+    }
     if (low === "/reset") { loop.reset(); console.log(c.green("컨텍스트를 초기화했습니다.")); continue; }
     if (low === "/config") { printIntro(cfg); console.log(c.dim(`config.json: ${configPath()}`)); continue; }
     if (low === "/sessions") { console.log(c.dim(`세션 로그: ${sessionsDir()}`)); continue; }
@@ -548,9 +568,23 @@ export async function main(argv = []) {
       continue;
     }
     if (low === "/skills") {
-      const names = Object.keys(skills);
-      const lines = names.length ? names.map((n) => `${c.cyan("/" + n)}  ${c.grey(skills[n].description || "")}`) : [c.dim("등록된 스킬이 없습니다.")];
-      lines.push(c.dim("위치: <작업폴더>/.cdsa/skills/ 또는 ~/.cdsa_harness/skills/ (.md). 본문의 $ARGUMENTS 치환."));
+      const names = Object.keys(skills).sort();
+      const srcTag = (s) => {
+        const src = s.source || "";
+        if (src === "(내장)") return c.dim("⭐ 내장");
+        if (src === "(npm)") return c.dim("📦 npm");
+        if (src.includes(`${path.sep}.claude${path.sep}`)) return c.dim("🟣 claude");
+        if (src.includes(`${path.sep}.opencode${path.sep}`)) return c.dim("🟠 opencode");
+        if (src.includes(`${path.sep}node-cli${path.sep}skills`) || src.includes(`cdsa-harness${path.sep}skills`)) return c.dim("⭐ 내장");
+        if (src.includes(`.cdsa_harness${path.sep}skills`)) return c.dim("🏠 전역");
+        if (src.includes(`.cdsa${path.sep}skills`)) return c.dim("📂 프로젝트");
+        return c.dim("📄 파일");
+      };
+      const lines = names.length
+        ? names.map((n) => `${c.cyan("/" + n)}  ${c.grey(skills[n].description || "")}  ${srcTag(skills[n])}`)
+        : [c.dim("등록된 스킬이 없습니다.")];
+      lines.push(c.dim("추가: <작업폴더>/.cdsa/skills/*.md · ~/.cdsa_harness/skills/ · config.json 의 skill_dirs"));
+      lines.push(c.dim("외부(.claude/commands 등)는 import_foreign_skills 로 끌 수 있음"));
       console.log(panel(lines, { title: "🎯 스킬 (프롬프트 템플릿, /이름 으로 실행)", color: "cyan" }));
       continue;
     }

package/src/config.js

@@ -30,6 +30,7 @@ export const APPROVAL_MODES = ["manual", "auto"];
 const DEFAULTS = {
   provider: "mock",
   api_key: "",
+  base_url: "", // OpenAI 호환 사내/폐쇄망 LLM 의 전체 엔드포인트 직접 지정(있으면 우선)
   model: "mock-agent",
   workspace: "./workspace",
   approval_mode: "manual",
@@ -39,6 +40,8 @@ const DEFAULTS = {
   max_tokens: 1024,
   teach_mode: true,
   stream: true, // 모델 응답을 실시간(토큰 단위)으로 출력
+  import_foreign_skills: true, // .claude/commands 등 외부 포맷 스킬도 읽기(프로젝트+전역)
+  skill_dirs: [], // 스킬을 추가로 읽어올 폴더(절대/상대 경로)
   plugins: [], // 추가로 불러올 npm 플러그인 패키지 이름(이름 규칙과 무관하게 강제 로드)
   mcpServers: {}, // MCP 서버 설정 (Claude Code/Cursor 와 동일한 형식)
 };

package/src/llm.js

@@ -14,13 +14,18 @@ const ENDPOINTS = {
 };
 
 export class LLMClient {
-  constructor({ provider, apiKey, model, temperature = 0.2, maxTokens = 1024, timeout = 60000 }) {
+  constructor({ provider, apiKey, model, temperature = 0.2, maxTokens = 1024, timeout = 60000, baseUrl = "" }) {
     this.provider = provider;
     this.apiKey = apiKey;
     this.model = model;
     this.temperature = temperature;
     this.maxTokens = maxTokens;
     this.timeout = timeout;
+    this.baseUrl = (baseUrl || "").trim(); // 있으면 ENDPOINTS 대신 이 엔드포인트 사용(폐쇄망 사내 LLM)
+  }
+
+  _endpoint(provider) {
+    return this.baseUrl || ENDPOINTS[provider] || ENDPOINTS.anthropic;
   }
 
   // onToken(chunk) 를 주면 텍스트가 도착하는 대로 콜백한다(스트리밍).
@@ -83,7 +88,7 @@ export class LLMClient {
 
   // --- OpenAI / OpenRouter (chat/completions 형식) ---
   async _openaiChat(messages, tools) {
-    const url = ENDPOINTS[this.provider];
+    const url = this._endpoint(this.provider);
     const body = { model: this.model, messages, temperature: this.temperature };
     if (tools && tools.length) {
       body.tools = tools;
@@ -108,7 +113,7 @@ export class LLMClient {
 
   // --- Anthropic (messages 형식) ---
   async _anthropicChat(messages, tools) {
-    const url = ENDPOINTS.anthropic;
+    const url = this._endpoint("anthropic");
     const body = toAnthropicBody(messages, tools, this.model, this.temperature, this.maxTokens);
     const headers = {
       "x-api-key": this.apiKey,
@@ -126,7 +131,7 @@ export class LLMClient {
 
   // --- OpenAI/OpenRouter 스트리밍 ---
   async _openaiStream(messages, tools, onToken) {
-    const url = ENDPOINTS[this.provider];
+    const url = this._endpoint(this.provider);
     const body = { model: this.model, messages, temperature: this.temperature, stream: true, stream_options: { include_usage: true } };
     if (tools && tools.length) {
       body.tools = tools;
@@ -168,7 +173,7 @@ export class LLMClient {
 
   // --- Anthropic 스트리밍 ---
   async _anthropicStream(messages, tools, onToken) {
-    const url = ENDPOINTS.anthropic;
+    const url = this._endpoint("anthropic");
     const body = toAnthropicBody(messages, tools, this.model, this.temperature, this.maxTokens);
     body.stream = true;
     const headers = { "x-api-key": this.apiKey, "anthropic-version": "2023-06-01", "Content-Type": "application/json" };

package/src/plugins.js

@@ -15,6 +15,8 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { BUILTIN_PLUGINS } from "./builtins.js";
+
 export function pluginDirs(workspace) {
   return [
     path.join(os.homedir(), ".cdsa_harness", "plugins"),
@@ -23,7 +25,8 @@ export function pluginDirs(workspace) {
 }
 
 export async function loadPlugins(workspace) {
-  const plugins = [];
+  // 패키지 내장 기본 플러그인(임베드) 먼저, 그다음 디스크의 사용자 플러그인.
+  const plugins = [...BUILTIN_PLUGINS.map((p) => ({ ...p, source: "(내장)" }))];
   for (const dir of pluginDirs(workspace)) {
     let files = [];
     try {
@@ -149,7 +152,12 @@ export async function scanNodeModules(nmDir) {
 // cwd 의 node_modules + cdsa-harness 자신의 node_modules(전역 설치 시 형제 패키지) 를 훑고,
 // config.plugins 에 적힌 패키지는 이름 규칙과 무관하게 강제로 불러온다.
 export async function discoverNpmExtensions(cwd, explicitNames = []) {
-  const here = path.dirname(fileURLToPath(import.meta.url));
+  let here = cwd;
+  try {
+    here = path.dirname(fileURLToPath(import.meta.url));
+  } catch {
+    /* 번들/SEA 환경 등 import.meta.url 사용 불가 시 무시 */
+  }
   const nmDirs = [];
   const add = (d) => {
     const r = path.resolve(d);

package/src/skills.js

@@ -11,22 +11,31 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-// 우리 폴더 + 다른 코딩 에이전트들의 커맨드/스킬 폴더도 함께 읽어 상호운용한다.
-// (Claude Code, OpenCode 등은 스킬이 결국 frontmatter 달린 마크다운이라 그대로 호환)
-export function skillDirs(workspace) {
+import { BUILTIN_SKILLS } from "./builtins.js";
+
+// 스킬 폴더 목록. 순서 = 우선순위(먼저 발견된 것이 이김).
+//  - importForeign: 다른 코딩 에이전트(Claude Code/OpenCode 등)의 커맨드 폴더도 읽기
+//  - extraDirs: 사용자가 config.skill_dirs 로 직접 지정한 폴더(상대경로는 cwd 기준)
+export function skillDirs(workspace, importForeign = true, extraDirs = []) {
   const home = os.homedir();
-  return [
-    // 전역
-    path.join(home, ".cdsa_harness", "skills"),
-    path.join(home, ".claude", "commands"),
-    path.join(home, ".config", "opencode", "command"),
-    // 작업 폴더
-    path.join(workspace, ".cdsa", "skills"),
+  const projectForeign = [
     path.join(workspace, ".claude", "commands"),
     path.join(workspace, ".claude", "skills"),
     path.join(workspace, ".opencode", "command"),
     path.join(workspace, ".github", "prompts"),
   ];
+  const globalForeign = [
+    path.join(home, ".claude", "commands"),
+    path.join(home, ".config", "opencode", "command"),
+  ];
+  const extras = extraDirs.map((d) => (path.isAbsolute(d) ? d : path.resolve(process.cwd(), d)));
+  return [
+    path.join(workspace, ".cdsa", "skills"), // 프로젝트(가장 우선)
+    ...extras, // 사용자가 명시한 폴더
+    ...(importForeign ? projectForeign : []), // 프로젝트의 외부 포맷
+    path.join(home, ".cdsa_harness", "skills"), // 우리 전역
+    ...(importForeign ? globalForeign : []), // 전역 외부 포맷(개인 커맨드 라이브러리)
+  ];
 }
 
 function parseFrontmatter(text) {
@@ -51,9 +60,9 @@ function addSkill(skills, name, file) {
   }
 }
 
-export function loadSkills(workspace) {
+export function loadSkills(workspace, { importForeign = true, extraDirs = [] } = {}) {
   const skills = {};
-  for (const dir of skillDirs(workspace)) {
+  for (const dir of skillDirs(workspace, importForeign, extraDirs)) {
     let entries = [];
     try {
       if (!fs.existsSync(dir)) continue;
@@ -78,6 +87,10 @@ export function loadSkills(workspace) {
       }
     }
   }
+  // 패키지 내장 기본 스킬(임베드) — 가장 낮은 우선순위(사용자 파일이 덮어씀)
+  for (const s of BUILTIN_SKILLS) {
+    if (!skills[s.name]) skills[s.name] = { name: s.name, description: s.description || "", body: s.body, source: "(내장)" };
+  }
   return skills;
 }
 

package/src/tools.js

@@ -55,8 +55,11 @@ export class Toolbox {
     this.workspace = path.resolve(workspace);
     fs.mkdirSync(this.workspace, { recursive: true });
     this.allowShell = allowShell;
-    // 정상 로드된 플러그인만 도구로 사용(로드 에러는 따로 보관해 표시).
-    this.plugins = plugins.filter((p) => p && p.name && typeof p.handler === "function");
+    // 정상 로드된 플러그인만 도구로 사용(로드 에러는 따로 보관해 표시). 이름 중복은 먼저 것 우선.
+    const seen = new Set();
+    this.plugins = plugins.filter(
+      (p) => p && p.name && typeof p.handler === "function" && !seen.has(p.name) && seen.add(p.name)
+    );
     this.pluginErrors = plugins.filter((p) => p && p.error).map((p) => p.error);
     this._pluginMap = new Map(this.plugins.map((p) => [p.name, p]));
   }

package/src/ui.js

@@ -54,14 +54,44 @@ function isWide(code) {
   );
 }
 
-// 둥근 박스 패널. lines: 문자열 배열(ANSI 포함 가능)
+// 문자열을 표시폭 기준으로 줄바꿈(한글=2칸). ANSI 없는 평문 전용.
+export function wrapToWidth(s, width) {
+  if (width < 4) width = 4;
+  const out = [];
+  for (const rawLine of String(s).split("\n")) {
+    let cur = "";
+    let w = 0;
+    for (const ch of rawLine) {
+      const cw = ch.codePointAt(0) > 0x1100 && isWide(ch.codePointAt(0)) ? 2 : 1;
+      if (w + cw > width) {
+        out.push(cur);
+        cur = "";
+        w = 0;
+      }
+      cur += ch;
+      w += cw;
+    }
+    out.push(cur);
+  }
+  return out;
+}
+
+// 둥근 박스 패널. lines: 문자열 배열(ANSI 포함 가능).
+// 터미널 폭을 넘는 '평문' 줄은 자동 줄바꿈해 박스 밖으로 삐져나가지 않게 한다.
 export function panel(lines, { title = "", color = "cyan" } = {}) {
   const paint = c[color] || ((x) => x);
-  const body = Array.isArray(lines) ? lines : String(lines).split("\n");
-  const contentWidth = Math.max(
-    visibleWidth(title) + 2,
-    ...body.map((l) => visibleWidth(l)),
-    10
+  const raw = Array.isArray(lines) ? lines : String(lines).split("\n");
+  const maxInner = Math.max(20, (process.stdout.columns || 80) - 4);
+  // ANSI 가 없는 긴 줄만 줄바꿈(색칠된 줄은 그대로 둠)
+  const body = [];
+  for (const l of raw) {
+    if (!ANSI_RE.test(l) && visibleWidth(l) > maxInner) body.push(...wrapToWidth(l, maxInner));
+    else body.push(l);
+    ANSI_RE.lastIndex = 0;
+  }
+  const contentWidth = Math.min(
+    maxInner,
+    Math.max(visibleWidth(title) + 2, ...body.map((l) => visibleWidth(l)), 10)
   );
   const top = paint("╭─ ") + paint(c.bold(title)) + paint(" " + "─".repeat(Math.max(0, contentWidth - visibleWidth(title) - 2)) + "╮");
   const bottom = paint("╰" + "─".repeat(contentWidth + 2) + "╯");