cdsa-harness 0.5.1 → 0.11.0

package/README.md

@@ -9,6 +9,7 @@
 ```
 
 - **의존성 0개** — Node 18+ 내장 기능만(`fetch`/`readline`/`node:test`)
+- **실시간 스트리밍** — 모델 응답이 토큰 단위로 흐름(`/stream` 토글, OpenAI·Claude·mock)
 - **실제 LLM 연결** — OpenAI · Anthropic(Claude) · OpenRouter, 또는 키 없이 `mock`
 - **교육 모드** — 매 반복마다 모델에 보내는 메시지 구성·추정 토큰·시스템 프롬프트, 실제 토큰 사용량/응답시간까지 그대로 표시
 - **MCP 클라이언트** — Claude Code·Cursor 등과 **공용 표준**. MCP 서버를 그대로 붙여 도구로 사용
@@ -17,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` 입력(대화형으로 제공자·키·모델 선택):
@@ -53,6 +72,7 @@ export OPENROUTER_API_KEY=sk-or-...
 | `/provider <이름>` | openai · anthropic · openrouter · mock 전환 |
 | `/model <이름>` | 모델 변경 |
 | `/teach` | 교육 모드 켜기/끄기 |
+| `/stream` | 실시간 스트리밍 출력 켜기/끄기 |
 | `/context` | 지금 모델에 보내는 컨텍스트 들여다보기 |
 | `/reset` | 대화/컨텍스트 초기화 |
 | `/config` | 현재 설정값 |
@@ -129,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
 ---
@@ -139,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,7 +1,7 @@
 {
   "name": "cdsa-harness",
-  "version": "0.5.1",
-  "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. OpenAI/Claude/OpenRouter + MCP(다른 에이전트와 공용) + npm 플러그인·크로스포맷 스킬.",
+  "version": "0.11.0",
+  "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. 실시간 스트리밍 + OpenAI/Claude/OpenRouter + MCP + npm 플러그인·크로스포맷 스킬.",
   "type": "module",
   "bin": {
     "cdsa-harness": "bin/cdsa-harness.js",
@@ -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.0";
+
+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"],
@@ -46,15 +48,24 @@ function clip(s, n) {
 }
 
 // cfg.teach_mode 를 실행 중 토글할 수 있으므로 closure 로 cfg 를 잡아둔다.
-function makePrinter(cfg) {
+// stream.active 는 onToken 과 공유하는 스트리밍 상태.
+function makePrinter(cfg, stream) {
   return (ev) => {
-    if (cfg.teach_mode) return printTeach(ev);
-    return printCompact(ev);
+    if (cfg.teach_mode) return printTeach(ev, stream);
+    return printCompact(ev, stream);
   };
 }
 
+function replyMetaLine(d) {
+  const meta = [];
+  if (d.latencyMs != null) meta.push(`응답 ${d.latencyMs}ms`);
+  if (d.usage) meta.push(`토큰 입력 ${d.usage.input ?? "?"}/출력 ${d.usage.output ?? "?"}/합계 ${d.usage.total ?? "?"}`);
+  if (d.request?.bodyBytes) meta.push(`요청 ${d.request.bodyBytes}B`);
+  return meta.length ? meta.join(" · ") : "";
+}
+
 // ---- 교육(teach) 렌더: 내부 과정을 패널로 펼쳐 보여준다 ----
-function printTeach(ev) {
+function printTeach(ev, stream) {
   const d = ev.data || {};
   switch (ev.step) {
     case Step.USER_INPUT:
@@ -85,16 +96,26 @@ function printTeach(ev) {
     }
 
     case Step.MODEL_REPLY: {
+      // 스트리밍으로 이미 본문이 출력된 경우: 줄바꿈 후 메타/도구호출만 덧붙인다.
+      if (d.streamed) {
+        if (stream && stream.active) {
+          process.stdout.write("\n");
+          stream.active = false;
+        }
+        for (const tc of d.toolCalls || []) {
+          console.log(c.yellow(`  ↳ 도구 호출 요청: ${c.bold(tc.name)}(${clip(JSON.stringify(tc.args), 200)})`));
+        }
+        const meta = replyMetaLine(d);
+        if (meta) console.log(c.grey("  ─ " + meta));
+        return;
+      }
       const lines = [];
       if (ev.detail && ev.detail !== "(텍스트 없음)") lines.push(...clip(ev.detail, 1200).split("\n"));
       for (const tc of d.toolCalls || []) {
         lines.push(c.yellow(`↳ 도구 호출 요청: ${c.bold(tc.name)}(${clip(JSON.stringify(tc.args), 200)})`));
       }
-      const meta = [];
-      if (d.latencyMs != null) meta.push(`응답 ${d.latencyMs}ms`);
-      if (d.usage) meta.push(`토큰 입력 ${d.usage.input ?? "?"}/출력 ${d.usage.output ?? "?"}/합계 ${d.usage.total ?? "?"}`);
-      if (d.request?.bodyBytes) meta.push(`요청 ${d.request.bodyBytes}B`);
-      if (meta.length) lines.push(c.grey("─ " + meta.join(" · ")));
+      const meta = replyMetaLine(d);
+      if (meta) lines.push(c.grey("─ " + meta));
       else lines.push(c.dim("(mock: 토큰/지연 측정 없음)"));
       console.log(panel(lines.length ? lines : ["(빈 응답)"], { title: "🤖 ③ 모델 응답 (원본 판단)", color: "green" }));
       return;
@@ -132,11 +153,17 @@ function printTeach(ev) {
 }
 
 // ---- 간결(compact) 렌더: 한 줄 위주 ----
-function printCompact(ev) {
+function printCompact(ev, stream) {
   const [icon, color] = STEP_STYLE[ev.step] || ["•", "cyan"];
   const paint = c[color] || ((x) => x);
   if (ev.step === Step.APPROVAL && !ev.title.includes("자동 승인")) return;
   if (ev.step === Step.MODEL_REPLY) {
+    const d = ev.data || {};
+    if (d.streamed) {
+      if (stream && stream.active) { process.stdout.write("\n"); stream.active = false; }
+      for (const tc of d.toolCalls || []) console.log(c.yellow(`  ↳ ${tc.name}(${clip(JSON.stringify(tc.args), 120)})`));
+      return;
+    }
     if (ev.detail && ev.detail !== "(텍스트 없음)") console.log(panel(ev.detail.split("\n"), { title: "🤖 모델", color: "green" }));
     return;
   }
@@ -175,20 +202,23 @@ 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"],
     ["작업 폴더", cfg.workspacePath()],
     ["승인 모드", cfg.approval_mode],
     ["셸 실행", cfg.allow_shell ? "허용" : "차단"],
@@ -209,10 +239,12 @@ 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")} <이름>   모델 변경`,
         `  ${c.cyan("/teach")}    교육 모드 켜기/끄기(내부 과정 펼쳐보기)`,
+        `  ${c.cyan("/stream")}   실시간 스트리밍 출력 켜기/끄기`,
         `  ${c.cyan("/context")}  지금 모델에 보내는 컨텍스트 들여다보기`,
         `  ${c.cyan("/skills")}   스킬 목록(.cdsa/skills 의 /명령들)`,
         `  ${c.cyan("/plugins")}  플러그인 목록(파일·npm 추가 도구)`,
@@ -304,6 +336,7 @@ function parseArgs(argv) {
     else if (a === "--help" || a === "-h") out.help = true;
     else if (a === "--setup") out.setup = true;
     else if (a === "--no-teach") out.noTeach = true;
+    else if (a === "--no-stream") out.noStream = true;
     else if (a === "--provider") out.provider = argv[++i];
     else if (a === "--model") out.model = argv[++i];
     else if (a === "--workspace") out.workspace = argv[++i];
@@ -324,6 +357,7 @@ export async function main(argv = []) {
         "  --workspace <폴더경로>\n" +
         "  --setup                대화형 연결 설정 실행\n" +
         "  --no-teach             교육 모드 끄고 간결하게\n" +
+        "  --no-stream            실시간 스트리밍 끄기\n" +
         "  --auto                 승인 자동(approval_mode=auto)\n" +
         "  -h, --help             도움말\n\n" +
         "API 키는 환경변수로도 인식됩니다: OPENAI_API_KEY / ANTHROPIC_API_KEY / OPENROUTER_API_KEY\n"
@@ -355,6 +389,7 @@ export async function main(argv = []) {
   if (args.workspace) cfg.workspace = args.workspace;
   if (args.auto) cfg.approval_mode = "auto";
   if (args.noTeach) cfg.teach_mode = false;
+  if (args.noStream) cfg.stream = false;
 
   const rl = readline.createInterface({ input: stdin, output: stdout });
   let session = null;
@@ -406,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 = [];
@@ -418,13 +456,23 @@ export async function main(argv = []) {
   }
 
   session = SessionLog.create();
+  // 스트리밍: 토큰이 도착하는 대로 실시간 출력(첫 토큰에 헤더 1회).
+  const stream = { active: false };
+  const onToken = (chunk) => {
+    if (!stream.active) {
+      process.stdout.write("\n" + c.green("🤖 ③ 모델 응답 (스트리밍)") + "\n");
+      stream.active = true;
+    }
+    process.stdout.write(c.green(chunk));
+  };
   const loop = new AgentLoop({
     config: cfg,
     client: makeClient(cfg),
     toolbox,
-    onEvent: makePrinter(cfg),
+    onEvent: makePrinter(cfg, stream),
     approvalCallback: makeApproval(ask),
     session,
+    onToken,
   });
   loop.reset();
 
@@ -439,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; }
@@ -447,6 +507,11 @@ export async function main(argv = []) {
       console.log(c.green(`교육 모드 ${cfg.teach_mode ? "ON" : "OFF"}.`));
       continue;
     }
+    if (low === "/stream") {
+      cfg.stream = !cfg.stream;
+      console.log(c.green(`스트리밍 ${cfg.stream ? "ON (실시간 출력)" : "OFF"}.`));
+      continue;
+    }
     if (low === "/setup" || low === "/login") {
       await runSetup(ask, cfg);
       loop.client = makeClient(cfg);
@@ -503,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",
@@ -38,6 +39,9 @@ const DEFAULTS = {
   temperature: 0.2,
   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,22 +14,57 @@ 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)
   }
 
-  async chat(messages, tools) {
-    if (this.provider === "mock") return mockChat(messages);
-    if (this.provider === "anthropic") return this._anthropicChat(messages, tools);
-    if (ENDPOINTS[this.provider]) return this._openaiChat(messages, tools);
+  _endpoint(provider) {
+    return this.baseUrl || ENDPOINTS[provider] || ENDPOINTS.anthropic;
+  }
+
+  // onToken(chunk) 를 주면 텍스트가 도착하는 대로 콜백한다(스트리밍).
+  async chat(messages, tools, onToken = null) {
+    if (this.provider === "mock") {
+      const r = mockChat(messages);
+      if (onToken && r.content) await streamText(r.content, onToken);
+      return r;
+    }
+    if (this.provider === "anthropic") {
+      return onToken ? this._anthropicStream(messages, tools, onToken) : this._anthropicChat(messages, tools);
+    }
+    if (ENDPOINTS[this.provider]) {
+      return onToken ? this._openaiStream(messages, tools, onToken) : this._openaiChat(messages, tools);
+    }
     throw new LLMError(`지원하지 않는 provider 입니다: ${this.provider}`);
   }
 
+  // 스트리밍용: 응답 객체(본문 스트림)를 그대로 받는다.
+  async _openStream(url, headers, body) {
+    const json = JSON.stringify(body);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeout);
+    const started = Date.now();
+    let res;
+    try {
+      res = await fetch(url, { method: "POST", headers, body: json, signal: ctrl.signal });
+    } catch (e) {
+      clearTimeout(timer);
+      throw new LLMError(`네트워크 오류: ${e.message}`);
+    }
+    if (!res.ok) {
+      clearTimeout(timer);
+      const text = await res.text().catch(() => "");
+      throw new LLMError(httpErrorMessage(res.status, text || res.statusText));
+    }
+    return { res, started, timer, bodyBytes: Buffer.byteLength(json, "utf8") };
+  }
+
   async _post(url, headers, body) {
     const json = JSON.stringify(body);
     const ctrl = new AbortController();
@@ -46,23 +81,14 @@ export class LLMClient {
     const latencyMs = Date.now() - started;
     if (!res.ok) {
       const text = await res.text().catch(() => "");
-      let msg = `API 오류 ${res.status}: ${trim(text) || res.statusText}`;
-      if (res.status === 404) {
-        msg += "\n  ↳ 모델 이름을 확인하세요. /model 로 변경 가능. " +
-          "OpenRouter 는 'provider/model' 형식이어야 합니다 (예: openai/gpt-4o-mini, anthropic/claude-3.7-sonnet).";
-      } else if (res.status === 401 || res.status === 403) {
-        msg += "\n  ↳ API 키가 잘못되었거나 권한이 없어요. /setup 으로 다시 연결하세요.";
-      } else if (res.status === 429) {
-        msg += "\n  ↳ 요청이 너무 많거나 크레딧이 부족할 수 있어요(잠시 후 재시도).";
-      }
-      throw new LLMError(msg);
+      throw new LLMError(httpErrorMessage(res.status, text || res.statusText));
     }
     return { payload: await res.json(), latencyMs, bodyBytes: Buffer.byteLength(json, "utf8") };
   }
 
   // --- 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;
@@ -87,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,
@@ -103,6 +129,87 @@ export class LLMClient {
     };
   }
 
+  // --- OpenAI/OpenRouter 스트리밍 ---
+  async _openaiStream(messages, tools, onToken) {
+    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;
+      body.tool_choice = "auto";
+    }
+    const headers = { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" };
+    if (this.provider === "openrouter") {
+      headers["HTTP-Referer"] = "https://github.com/cdsassj00/miniharness";
+      headers["X-Title"] = "CDSA Harness";
+    }
+    const { res, started, timer, bodyBytes } = await this._openStream(url, headers, body);
+    let content = "";
+    const tcMap = new Map(); // index -> {id,name,args}
+    let usage = null;
+    try {
+      await readSSE(res, (data) => {
+        if (data === "[DONE]") return;
+        let json;
+        try { json = JSON.parse(data); } catch { return; }
+        if (json.usage) usage = { input: json.usage.prompt_tokens ?? null, output: json.usage.completion_tokens ?? null, total: json.usage.total_tokens ?? null };
+        const delta = json.choices?.[0]?.delta;
+        if (!delta) return;
+        if (delta.content) { content += delta.content; onToken(delta.content); }
+        for (const tc of delta.tool_calls || []) {
+          const i = tc.index ?? 0;
+          const cur = tcMap.get(i) || { id: tc.id || `call_${i}`, name: "", args: "" };
+          if (tc.id) cur.id = tc.id;
+          if (tc.function?.name) cur.name += tc.function.name;
+          if (tc.function?.arguments) cur.args += tc.function.arguments;
+          tcMap.set(i, cur);
+        }
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const toolCalls = [...tcMap.values()].map((t) => ({ id: t.id, name: t.name, args: safeParse(t.args) }));
+    return { content: content || null, toolCalls, usage, latencyMs: Date.now() - started, request: this._meta(url, tools, bodyBytes) };
+  }
+
+  // --- Anthropic 스트리밍 ---
+  async _anthropicStream(messages, tools, onToken) {
+    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" };
+    const { res, started, timer, bodyBytes } = await this._openStream(url, headers, body);
+    let content = "";
+    const blocks = new Map(); // index -> {type,name,id,json}
+    let usage = { input: null, output: null, total: 0 };
+    try {
+      await readSSE(res, (data) => {
+        let ev;
+        try { ev = JSON.parse(data); } catch { return; }
+        if (ev.type === "message_start" && ev.message?.usage) usage.input = ev.message.usage.input_tokens ?? null;
+        else if (ev.type === "content_block_start") {
+          const b = ev.content_block || {};
+          blocks.set(ev.index, { type: b.type, name: b.name, id: b.id, json: "" });
+        } else if (ev.type === "content_block_delta") {
+          const d = ev.delta || {};
+          if (d.type === "text_delta") { content += d.text; onToken(d.text); }
+          else if (d.type === "input_json_delta") {
+            const cur = blocks.get(ev.index);
+            if (cur) cur.json += d.partial_json || "";
+          }
+        } else if (ev.type === "message_delta" && ev.usage) {
+          usage.output = ev.usage.output_tokens ?? usage.output;
+        }
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    usage.total = (usage.input || 0) + (usage.output || 0);
+    const toolCalls = [...blocks.values()]
+      .filter((b) => b.type === "tool_use")
+      .map((b) => ({ id: b.id, name: b.name, args: safeParse(b.json) }));
+    return { content: content || null, toolCalls, usage, latencyMs: Date.now() - started, request: this._meta(url, tools, bodyBytes) };
+  }
+
   _meta(endpoint, tools, bodyBytes) {
     return {
       provider: this.provider,
@@ -120,6 +227,51 @@ function trim(s) {
   return s.length > 400 ? s.slice(0, 400) + " …" : s;
 }
 
+function safeParse(jsonStr) {
+  try {
+    return JSON.parse(jsonStr || "{}");
+  } catch {
+    return { _raw: jsonStr };
+  }
+}
+
+function httpErrorMessage(status, text) {
+  let msg = `API 오류 ${status}: ${trim(text)}`;
+  if (status === 404) {
+    msg += "\n  ↳ 모델 이름을 확인하세요. /model 로 변경 가능. " +
+      "OpenRouter 는 'provider/model' 형식이어야 합니다 (예: openai/gpt-4o-mini, anthropic/claude-3.7-sonnet).";
+  } else if (status === 401 || status === 403) {
+    msg += "\n  ↳ API 키가 잘못되었거나 권한이 없어요. /setup 으로 다시 연결하세요.";
+  } else if (status === 429) {
+    msg += "\n  ↳ 요청이 너무 많거나 크레딧이 부족할 수 있어요(잠시 후 재시도).";
+  }
+  return msg;
+}
+
+// SSE(data: ...) 본문 스트림을 줄 단위로 콜백. onEvent(dataString) 호출(‘[DONE]’ 포함).
+async function readSSE(res, onEvent) {
+  let buf = "";
+  for await (const chunk of res.body) {
+    buf += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    let nl;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (line.startsWith("data:")) onEvent(line.slice(5).trim());
+    }
+  }
+  if (buf.trim().startsWith("data:")) onEvent(buf.trim().slice(5).trim());
+}
+
+// mock/공통: 텍스트를 토큰처럼 쪼개 콜백(TTY 면 살짝 지연해 흐르는 효과).
+async function streamText(text, onToken) {
+  const parts = String(text).match(/\S+\s*|\s+/g) || [String(text)];
+  for (const p of parts) {
+    onToken(p);
+    if (process.stdout.isTTY) await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
 function parseOpenAiReply(payload) {
   const msg = payload?.choices?.[0]?.message;
   if (!msg) {

package/src/loop.js

@@ -79,13 +79,14 @@ function findRules(workspace) {
 }
 
 export class AgentLoop {
-  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null }) {
+  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null, onToken = null }) {
     this.config = config;
     this.client = client;
     this.toolbox = toolbox;
     this.onEvent = onEvent;
     this.approvalCallback = approvalCallback;
     this.session = session;
+    this.onToken = onToken; // 스트리밍 토큰 콜백(있으면 실시간 출력)
     this.messages = [];
   }
 
@@ -168,9 +169,10 @@ export class AgentLoop {
         }
       );
 
+      const streaming = Boolean(this.onToken && this.config.stream);
       let reply;
       try {
-        reply = await this.client.chat(this.messages, tools);
+        reply = await this.client.chat(this.messages, tools, streaming ? this.onToken : null);
       } catch (e) {
         if (e instanceof LLMError) {
           this._emit(Step.ERROR, "LLM 오류", e.message);
@@ -180,11 +182,13 @@ export class AgentLoop {
       }
 
       // ③ 모델의 원본 판단 + 실측 메타(응답시간/토큰/요청크기)를 드러낸다.
+      // streamed=true 면 텍스트는 이미 실시간 출력됨 → UI 는 메타만 덧붙인다.
       this._emit(Step.MODEL_REPLY, "모델 응답", reply.content || "(텍스트 없음)", {
         toolCalls: reply.toolCalls.map((tc) => ({ name: tc.name, args: tc.args })),
         usage: reply.usage || null,
         latencyMs: reply.latencyMs ?? null,
         request: reply.request || null,
+        streamed: streaming && Boolean(reply.content),
       });
       if (reply.content) finalText = reply.content;
 

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) + "╯");