cdsa-harness 0.2.0 → 0.4.0

package/README.md

@@ -11,6 +11,8 @@
 - **의존성 0개** — Node 18+ 내장 기능만(`fetch`/`readline`/`node:test`)
 - **실제 LLM 연결** — OpenAI · Anthropic(Claude) · OpenRouter, 또는 키 없이 `mock`
 - **교육 모드** — 매 반복마다 모델에 보내는 메시지 구성·추정 토큰·시스템 프롬프트, 실제 토큰 사용량/응답시간까지 그대로 표시
+- **플러그인** — `.cdsa/plugins/` 에 JS 파일을 두면 **새 도구가 자동 등록**되어 모델이 사용
+- **스킬** — `.cdsa/skills/` 에 마크다운을 두면 `/이름` 으로 부르는 **프롬프트 템플릿**
 
 ---
 
@@ -68,6 +70,57 @@ export OPENROUTER_API_KEY=sk-or-...
 
 ---
 
+## 🔌 플러그인 (추가 도구)
+
+### 방법 A — npm 으로 설치 (권장)
+
+`cdsa-harness-plugin-*` 이름의 패키지를 설치하면 **자동으로 발견·로드**됩니다.
+
+```bash
+cdsa-harness add cdsa-harness-plugin-git   # = npm install 후 자동 로드
+# 또는 직접:  npm install cdsa-harness-plugin-git
+cdsa-harness                               # 실행 → /plugins 에 자동 등록됨
+```
+
+- cwd 의 `node_modules` 와 전역 설치 위치를 모두 탐색합니다.
+- 이름 규칙과 무관하게 강제 로드하려면 `config.json` 의 `"plugins": ["패키지명"]` 에 추가.
+- 플러그인 패키지는 default export 로 `플러그인 def` · `def 배열` · `{ tools:[...], skills:[...] }` 중 하나를 제공.
+
+> **npm vs npx**: `npm install`(=설치, 보관) 으로 플러그인을 **추가**하고, `npx`(=설치 없이 실행) 또는 설치된 `cdsa-harness` 로 **실행**합니다.
+
+### 방법 B — 로컬 파일 (실험용)
+
+`.cdsa/plugins/` (작업 폴더) 또는 `~/.cdsa_harness/plugins/` 에 `.js`/`.mjs` 파일을 두면 자동 등록.
+
+```js
+// .cdsa/plugins/word_count.mjs
+import fs from "node:fs";
+import path from "node:path";
+export default {
+  name: "word_count",
+  description: "텍스트 파일의 글자/줄/단어 수를 센다",
+  parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+  mutating: false,                 // true 면 실행 전 승인
+  async handler(args, ctx) {       // ctx.workspace = 작업 폴더 절대경로
+    const text = fs.readFileSync(path.resolve(ctx.workspace, args.path), "utf8");
+    return `글자 ${text.length}, 줄 ${text.split("\n").length}`;
+  },
+};
+```
+
+## 🎯 스킬 (프롬프트 템플릿)
+
+`.cdsa/skills/` 또는 `~/.cdsa_harness/skills/` 에 마크다운을 두면 `/파일명` 으로 실행됩니다.
+본문의 `$ARGUMENTS` 는 명령 뒤 텍스트로 치환됩니다. `/skills` 로 목록 확인.
+
+```markdown
+---
+description: 파일을 읽고 3줄로 요약
+---
+$ARGUMENTS 파일을 read_file 로 읽고 핵심을 한국어 3줄로 요약해줘.
+```
+실행: `/summarize notes.txt`
+
 ## 설정 (config.json)
 
 `~/.cdsa_harness/config.json` (실행 폴더에 `config.json` 있으면 우선).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdsa-harness",
-  "version": "0.2.0",
-  "description": "AI 에이전트의 내부 동작(컨텍스트·API요청·토큰·도구·되먹임)을 단계별로 드러내는 교육용 터미널 하네스. OpenAI/Claude/OpenRouter 지원.",
+  "version": "0.4.0",
+  "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. OpenAI/Claude/OpenRouter + npm 으로 설치하는 플러그인(추가 도구)·스킬 확장.",
   "type": "module",
   "bin": {
     "cdsa-harness": "bin/cdsa-harness.js",

package/src/cli.js

@@ -13,9 +13,13 @@ import {
   loadConfig,
   saveConfig,
 } from "./config.js";
+import { execFileSync } from "node:child_process";
+
 import { AgentLoop, Step } from "./loop.js";
 import { LLMClient } from "./llm.js";
+import { discoverNpmExtensions, loadPlugins } from "./plugins.js";
 import { SessionLog, sessionsDir } from "./session.js";
+import { loadSkills, renderSkill } from "./skills.js";
 import { Toolbox } from "./tools.js";
 import { c, panel, renderDiff } from "./ui.js";
 
@@ -213,6 +217,8 @@ function printHelp() {
         `  ${c.cyan("/model")} <이름>   모델 변경`,
         `  ${c.cyan("/teach")}    교육 모드 켜기/끄기(내부 과정 펼쳐보기)`,
         `  ${c.cyan("/context")}  지금 모델에 보내는 컨텍스트 들여다보기`,
+        `  ${c.cyan("/skills")}   스킬 목록(.cdsa/skills 의 /명령들)`,
+        `  ${c.cyan("/plugins")}  플러그인 목록(.cdsa/plugins 의 추가 도구)`,
         `  ${c.cyan("/reset")}    대화/컨텍스트 초기화`,
         `  ${c.cyan("/config")}   현재 설정값`,
         `  ${c.cyan("/quit")}     종료 (Ctrl+D)`,
@@ -298,6 +304,7 @@ export async function main(argv = []) {
     console.log(
       "CDSA Harness — AI 에이전트 내부를 드러내는 교육용 하네스 (터미널)\n\n" +
         "사용법: cdsa-harness [옵션]\n" +
+        "       cdsa-harness add <npm-패키지>   플러그인 설치(이후 자동 로드)\n" +
         "  --provider <openai|anthropic|openrouter|mock>\n" +
         "  --model <모델명>\n" +
         "  --workspace <폴더경로>\n" +
@@ -310,6 +317,24 @@ export async function main(argv = []) {
     return 0;
   }
 
+  // `cdsa-harness add <패키지>` — 플러그인을 npm 으로 설치(이후 자동 로드).
+  if (args._[0] === "add" || args._[0] === "install") {
+    const pkgs = args._.slice(1);
+    if (!pkgs.length) {
+      console.log("사용법: cdsa-harness add <npm-패키지...>   예) cdsa-harness add cdsa-harness-plugin-git");
+      return 1;
+    }
+    console.log(c.cyan(`npm install ${pkgs.join(" ")} ...`));
+    try {
+      execFileSync("npm", ["install", ...pkgs], { stdio: "inherit", cwd: process.cwd() });
+      console.log(c.green("설치 완료. 다음 실행부터 플러그인이 자동으로 로드됩니다 (/plugins 로 확인)."));
+      return 0;
+    } catch (e) {
+      console.log(c.red(`설치 실패: ${e.message}`));
+      return 1;
+    }
+  }
+
   const cfg = loadConfig();
   if (args.provider) cfg.provider = args.provider;
   if (args.model) cfg.model = args.model;
@@ -328,7 +353,24 @@ export async function main(argv = []) {
 
   printIntro(cfg);
 
-  const toolbox = new Toolbox(cfg.workspacePath(), cfg.allow_shell);
+  // 플러그인(추가 도구)·스킬(프롬프트 템플릿)을 불러온다:
+  //   ① 파일: .cdsa/plugins · .cdsa/skills (작업폴더/홈)
+  //   ② npm 패키지: cdsa-harness-plugin-* 자동 발견 + config.plugins 강제 로드
+  const filePlugins = await loadPlugins(cfg.workspacePath());
+  const npm = await discoverNpmExtensions(process.cwd(), cfg.plugins || []);
+  const plugins = [...filePlugins, ...npm.plugins, ...npm.errors.map((e) => ({ error: e }))];
+  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())); // 로컬 파일 스킬이 우선
+  const toolbox = new Toolbox(cfg.workspacePath(), cfg.allow_shell, plugins);
+  if (toolbox.plugins.length || Object.keys(skills).length || toolbox.pluginErrors.length) {
+    const bits = [];
+    if (toolbox.plugins.length) bits.push(c.green(`플러그인 ${toolbox.plugins.length}개`) + c.grey(` (${toolbox.plugins.map((p) => p.name).join(", ")})`));
+    if (Object.keys(skills).length) bits.push(c.green(`스킬 ${Object.keys(skills).length}개`) + c.grey(` (${Object.keys(skills).map((s) => "/" + s).join(", ")})`));
+    if (toolbox.pluginErrors.length) bits.push(c.red(`플러그인 오류 ${toolbox.pluginErrors.length}개`));
+    console.log("🔌 " + bits.join(" · ") + "\n");
+  }
+
   const session = SessionLog.create();
   const loop = new AgentLoop({
     config: cfg,
@@ -394,6 +436,45 @@ export async function main(argv = []) {
       console.log(panel(clip(ctx.systemPrompt, 800).split("\n"), { title: "📜 시스템 프롬프트", color: "grey" }));
       continue;
     }
+    if (low === "/plugins") {
+      const lines = [];
+      if (!toolbox.plugins.length) lines.push(c.dim("등록된 플러그인이 없습니다."));
+      for (const p of toolbox.plugins) {
+        const src = p.source && p.source.includes("/") ? "📄 " + p.source.split("/").slice(-1)[0] : "📦 " + (p.source || "npm");
+        lines.push(`${c.bold(p.name)}${p.mutating ? c.yellow(" (승인필요)") : ""}  ${c.grey(p.description || "")} ${c.dim(src)}`);
+      }
+      for (const e of toolbox.pluginErrors) lines.push(c.red("✖ " + e));
+      lines.push(c.dim("추가: npm 패키지 'cdsa-harness-plugin-*' 설치 → 자동 로드 (cdsa-harness add <pkg>)"));
+      lines.push(c.dim("또는: <작업폴더>/.cdsa/plugins/ 에 .js/.mjs 파일"));
+      console.log(panel(lines, { title: "🔌 플러그인 (모델이 쓸 수 있는 추가 도구)", color: "blue" }));
+      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 치환."));
+      console.log(panel(lines, { title: "🎯 스킬 (프롬프트 템플릿, /이름 으로 실행)", color: "cyan" }));
+      continue;
+    }
+
+    // 위 내장 명령에 안 걸린 '/...' → 스킬이면 실행, 아니면 안내.
+    if (user.startsWith("/")) {
+      const name = low.slice(1).split(/\s+/)[0];
+      if (skills[name]) {
+        const argStr = user.split(/\s+/).slice(1).join(" ");
+        console.log(c.dim(`(스킬 '/${name}' 실행)`));
+        rule();
+        try {
+          await loop.run(renderSkill(skills[name], argStr));
+        } catch (e) {
+          console.log(c.red(`실행 오류: ${e?.message || e}`));
+        }
+        rule();
+      } else {
+        console.log(c.yellow(`알 수 없는 명령/스킬: /${name} — ${c.cyan("/help")}, ${c.cyan("/skills")} 참고`));
+      }
+      continue;
+    }
 
     rule();
     try {

package/src/config.js

@@ -37,6 +37,7 @@ const DEFAULTS = {
   temperature: 0.2,
   max_tokens: 1024,
   teach_mode: true,
+  plugins: [], // 추가로 불러올 npm 플러그인 패키지 이름(이름 규칙과 무관하게 강제 로드)
 };
 
 export function configDir() {

package/src/loop.js

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { LLMError } from "./llm.js";
-import { MUTATING_TOOLS, TOOL_LABELS, ToolError, toolSchemas } from "./tools.js";
+import { TOOL_LABELS, ToolError, toolSchemas } from "./tools.js";
 
 // 단계(Step) 상수
 export const Step = {
@@ -145,7 +145,7 @@ export class AgentLoop {
       "규칙 파일 + 작업 폴더 내용을 시스템 프롬프트로 묶어 모델에 전달합니다."
     );
 
-    const tools = toolSchemas(this.config.allow_shell);
+    const tools = toolSchemas(this.config.allow_shell, this.toolbox.plugins);
     const toolNames = tools.map((t) => t.function.name);
     let finalText = "";
 
@@ -227,8 +227,8 @@ export class AgentLoop {
   }
 
   async _handleToolCall(tc) {
-    const label = TOOL_LABELS[tc.name] || tc.name;
-    const needsApproval = MUTATING_TOOLS.has(tc.name);
+    const label = this.toolbox.label ? this.toolbox.label(tc.name) : TOOL_LABELS[tc.name] || tc.name;
+    const needsApproval = this.toolbox.isMutating(tc.name);
 
     if (needsApproval && this.config.approval_mode === "manual") {
       const req = this._buildApprovalRequest(tc);
@@ -250,7 +250,7 @@ export class AgentLoop {
 
     this._emit(Step.TOOL_RUN, `도구 실행: ${label}`, JSON.stringify(tc.args).slice(0, 2000));
     try {
-      const result = this.toolbox.execute(tc.name, tc.args);
+      const result = await this.toolbox.execute(tc.name, tc.args);
       this._emit(Step.TOOL_RESULT, `결과 반영: ${label}`, (result.output || "").slice(0, 4000));
       return result.output;
     } catch (e) {

package/src/plugins.js

@@ -0,0 +1,191 @@
+// 플러그인 시스템 — OpenCode 스타일 확장성.
+// `.cdsa/plugins/` (작업 폴더) 와 `~/.cdsa_harness/plugins/` (전역) 의 .js/.mjs 파일을
+// 불러와 '새 도구'로 등록한다. 각 파일은 아래 형태의 객체를 default export 한다:
+//
+//   export default {
+//     name: "word_count",
+//     description: "텍스트 파일의 글자/줄 수를 센다",
+//     parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+//     mutating: false,                  // true 면 실행 전 사용자 승인 필요
+//     async handler(args, ctx) { ... }  // ctx = { workspace }
+//   }
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export function pluginDirs(workspace) {
+  return [
+    path.join(os.homedir(), ".cdsa_harness", "plugins"),
+    path.join(workspace, ".cdsa", "plugins"),
+  ];
+}
+
+export async function loadPlugins(workspace) {
+  const plugins = [];
+  for (const dir of pluginDirs(workspace)) {
+    let files = [];
+    try {
+      if (!fs.existsSync(dir)) continue;
+      files = fs.readdirSync(dir).filter((f) => /\.(mjs|js)$/.test(f)).sort();
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      const full = path.join(dir, f);
+      try {
+        const mod = await import(pathToFileURL(full).href);
+        const def = mod.default || mod.plugin || mod;
+        if (!def || !def.name || typeof def.handler !== "function") {
+          plugins.push({ error: `${f}: name/handler 가 없습니다` });
+          continue;
+        }
+        plugins.push({
+          name: def.name,
+          description: def.description || "",
+          parameters: def.parameters || { type: "object", properties: {} },
+          mutating: Boolean(def.mutating),
+          handler: def.handler,
+          source: full,
+        });
+      } catch (e) {
+        plugins.push({ error: `${f}: ${e.message}` });
+      }
+    }
+  }
+  return plugins;
+}
+
+// ---------------------------------------------------------------------------
+// npm 패키지로 설치한 플러그인 자동 발견.
+//   - 이름이 `cdsa-harness-plugin-*` (또는 `@scope/cdsa-harness-plugin-*`)
+//   - 또는 package.json 에 keywords: ["cdsa-harness-plugin"] / "cdsaHarness" 필드
+//   인 패키지를 node_modules 에서 찾아 불러온다.
+// 패키지는 다음 중 하나를 default export:
+//   · 플러그인 def 객체  · def 배열  · { tools:[...], skills:[{name,description,body}] }
+// ---------------------------------------------------------------------------
+function isPluginPackage(pkgJson, name) {
+  if (/^(@[^/]+\/)?cdsa-harness-plugin-/.test(name)) return true;
+  if (pkgJson && pkgJson.cdsaHarness) return true;
+  const kw = (pkgJson && pkgJson.keywords) || [];
+  return Array.isArray(kw) && kw.includes("cdsa-harness-plugin");
+}
+
+async function importPackage(nmDir, name) {
+  const req = createRequire(path.join(nmDir, "__cdsa_resolve__.js"));
+  const entry = req.resolve(name);
+  return import(pathToFileURL(entry).href);
+}
+
+function normalizeModule(mod, source) {
+  const out = { plugins: [], skills: [] };
+  const def = (mod && (mod.default ?? mod)) || null;
+  if (!def) return out;
+  let tools = [];
+  let skills = [];
+  if (Array.isArray(def)) tools = def;
+  else if (def.tools || def.skills) {
+    tools = def.tools || [];
+    skills = def.skills || [];
+  } else if (def.name && typeof def.handler === "function") tools = [def];
+  for (const t of tools) {
+    if (t && t.name && typeof t.handler === "function") {
+      out.plugins.push({
+        name: t.name,
+        description: t.description || "",
+        parameters: t.parameters || { type: "object", properties: {} },
+        mutating: Boolean(t.mutating),
+        handler: t.handler,
+        source,
+      });
+    }
+  }
+  for (const s of skills) if (s && s.name && s.body) out.skills.push(s);
+  return out;
+}
+
+// 한 node_modules 디렉터리를 훑어 플러그인 패키지를 모은다.
+export async function scanNodeModules(nmDir) {
+  const result = { plugins: [], skills: [], errors: [] };
+  let entries = [];
+  try {
+    if (!fs.existsSync(nmDir)) return result;
+    entries = fs.readdirSync(nmDir);
+  } catch {
+    return result;
+  }
+  const names = [];
+  for (const e of entries) {
+    if (e.startsWith(".")) continue;
+    if (e.startsWith("@")) {
+      try {
+        for (const sub of fs.readdirSync(path.join(nmDir, e))) names.push(`${e}/${sub}`);
+      } catch {
+        /* ignore */
+      }
+    } else names.push(e);
+  }
+  for (const name of names) {
+    let pkgJson = {};
+    try {
+      pkgJson = JSON.parse(fs.readFileSync(path.join(nmDir, name, "package.json"), "utf8"));
+    } catch {
+      continue;
+    }
+    if (!isPluginPackage(pkgJson, name)) continue;
+    try {
+      const mod = await importPackage(nmDir, name);
+      const norm = normalizeModule(mod, name);
+      result.plugins.push(...norm.plugins);
+      result.skills.push(...norm.skills);
+    } catch (e) {
+      result.errors.push(`${name}: ${e.message}`);
+    }
+  }
+  return result;
+}
+
+// cwd 의 node_modules + cdsa-harness 자신의 node_modules(전역 설치 시 형제 패키지) 를 훑고,
+// config.plugins 에 적힌 패키지는 이름 규칙과 무관하게 강제로 불러온다.
+export async function discoverNpmExtensions(cwd, explicitNames = []) {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const nmDirs = [];
+  const add = (d) => {
+    const r = path.resolve(d);
+    if (!nmDirs.includes(r)) nmDirs.push(r);
+  };
+  add(path.join(cwd, "node_modules"));
+  add(path.resolve(here, "..", "..")); // .../node_modules/cdsa-harness/src → .../node_modules
+
+  const merged = { plugins: [], skills: [], errors: [] };
+  for (const nm of nmDirs) {
+    const r = await scanNodeModules(nm);
+    merged.plugins.push(...r.plugins);
+    merged.skills.push(...r.skills);
+    merged.errors.push(...r.errors);
+  }
+  for (const name of explicitNames) {
+    if (merged.plugins.some((p) => p.source === name)) continue;
+    let loaded = false;
+    for (const nm of nmDirs) {
+      try {
+        const norm = normalizeModule(await importPackage(nm, name), name);
+        if (norm.plugins.length || norm.skills.length) {
+          merged.plugins.push(...norm.plugins);
+          merged.skills.push(...norm.skills);
+          loaded = true;
+          break;
+        }
+      } catch {
+        /* try next dir */
+      }
+    }
+    if (!loaded) merged.errors.push(`${name}: 불러올 수 없음(설치되어 있나요? npm i ${name})`);
+  }
+  // 이름 중복 제거(먼저 발견된 것 우선)
+  const byName = new Map();
+  for (const p of merged.plugins) if (!byName.has(p.name)) byName.set(p.name, p);
+  merged.plugins = [...byName.values()];
+  return merged;
+}

package/src/skills.js

@@ -0,0 +1,61 @@
+// 스킬 시스템 — OpenCode 의 커스텀 커맨드와 같은 개념.
+// `.cdsa/skills/` (작업 폴더) 와 `~/.cdsa_harness/skills/` (전역) 의 .md 파일을 불러온다.
+// 파일명이 곧 스킬 이름이고(`/이름` 으로 실행), 본문은 모델에 전달할 프롬프트 템플릿이다.
+// 본문 안의 `$ARGUMENTS` 는 `/이름 뒤에 붙인 텍스트` 로 치환된다.
+//
+//   ---
+//   description: 파일을 읽고 3줄로 요약
+//   ---
+//   $ARGUMENTS 파일을 read_file 로 읽고 핵심을 한국어 3줄로 요약해줘.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function skillDirs(workspace) {
+  return [
+    path.join(os.homedir(), ".cdsa_harness", "skills"),
+    path.join(workspace, ".cdsa", "skills"),
+  ];
+}
+
+function parseFrontmatter(text) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  if (!m) return { meta: {}, body: text.trim() };
+  const meta = {};
+  for (const line of m[1].split("\n")) {
+    const i = line.indexOf(":");
+    if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return { meta, body: text.slice(m[0].length).trim() };
+}
+
+export function loadSkills(workspace) {
+  const skills = {};
+  for (const dir of skillDirs(workspace)) {
+    let files = [];
+    try {
+      if (!fs.existsSync(dir)) continue;
+      files = fs.readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      const name = f.replace(/\.md$/, "");
+      try {
+        const raw = fs.readFileSync(path.join(dir, f), "utf8");
+        const { meta, body } = parseFrontmatter(raw);
+        skills[name] = { name, description: meta.description || "", body, source: path.join(dir, f) };
+      } catch {
+        /* ignore unreadable skill */
+      }
+    }
+  }
+  return skills;
+}
+
+// 스킬 본문에 인자를 채워 최종 프롬프트를 만든다.
+export function renderSkill(skill, args) {
+  const argStr = (args || "").trim();
+  if (skill.body.includes("$ARGUMENTS")) return skill.body.replace(/\$ARGUMENTS/g, argStr);
+  return argStr ? `${skill.body}\n\n[추가 입력]\n${argStr}` : skill.body;
+}

package/src/tools.js

@@ -51,10 +51,27 @@ export function diffLines(oldText, newText) {
 }
 
 export class Toolbox {
-  constructor(workspace, allowShell = false) {
+  constructor(workspace, allowShell = false, plugins = []) {
     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");
+    this.pluginErrors = plugins.filter((p) => p && p.error).map((p) => p.error);
+    this._pluginMap = new Map(this.plugins.map((p) => [p.name, p]));
+  }
+
+  // 실행 전 사용자 승인이 필요한 도구인가? (환경을 바꾸는 내장 도구 + mutating 플러그인)
+  isMutating(name) {
+    if (MUTATING_TOOLS.has(name)) return true;
+    const p = this._pluginMap.get(name);
+    return Boolean(p && p.mutating);
+  }
+
+  label(name) {
+    if (TOOL_LABELS[name]) return TOOL_LABELS[name];
+    const p = this._pluginMap.get(name);
+    return p ? `플러그인:${name}` : name;
   }
 
   _resolve(rel) {
@@ -148,16 +165,27 @@ export class Toolbox {
     return { ok: code === 0, output: `$ ${command}\n(exit=${code})\n${out}` };
   }
 
-  execute(name, args = {}) {
+  async execute(name, args = {}) {
     if (name === "list_dir") return this.listDir(args.path || ".");
     if (name === "read_file") return this.readFile(args.path || "");
     if (name === "write_file") return this.writeFile(args.path || "", args.content || "");
     if (name === "run_shell") return this.runShell(args.command || "");
+    const plugin = this._pluginMap.get(name);
+    if (plugin) {
+      let result;
+      try {
+        result = await plugin.handler(args, { workspace: this.workspace });
+      } catch (e) {
+        throw new ToolError(`플러그인 '${name}' 실행 오류: ${e.message}`);
+      }
+      const output = typeof result === "string" ? result : result?.output ?? JSON.stringify(result);
+      return { ok: true, output: String(output) };
+    }
     throw new ToolError(`알 수 없는 도구입니다: ${name}`);
   }
 }
 
-export function toolSchemas(allowShell = false) {
+export function toolSchemas(allowShell = false, plugins = []) {
   const schemas = [
     {
       type: "function",
@@ -216,5 +244,17 @@ export function toolSchemas(allowShell = false) {
       },
     });
   }
+  // 플러그인이 제공하는 도구를 모델에게도 노출한다.
+  for (const p of plugins) {
+    if (!p || !p.name || typeof p.handler !== "function") continue;
+    schemas.push({
+      type: "function",
+      function: {
+        name: p.name,
+        description: (p.description || `플러그인 도구 ${p.name}`) + (p.mutating ? " (승인 필요)" : ""),
+        parameters: p.parameters || { type: "object", properties: {} },
+      },
+    });
+  }
   return schemas;
 }

package/workspace/.cdsa/plugins/word_count.mjs

@@ -0,0 +1,31 @@
+// 예시 플러그인: 작업 폴더 안 텍스트 파일의 글자/줄/단어 수를 센다.
+// 이 파일을 .cdsa/plugins/ 에 두면 자동으로 'word_count' 도구가 등록되어
+// 모델이 호출할 수 있게 된다. (읽기 전용이라 mutating: false → 승인 불필요)
+import fs from "node:fs";
+import path from "node:path";
+
+export default {
+  name: "word_count",
+  description: "작업 폴더 안 텍스트 파일의 글자수/줄수/단어수를 센다.",
+  parameters: {
+    type: "object",
+    properties: { path: { type: "string", description: "작업 폴더 기준 상대 경로" } },
+    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 (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+      return `파일이 없습니다: ${rel}`;
+    }
+    const text = fs.readFileSync(target, "utf8");
+    const chars = text.length;
+    const lines = text.split("\n").length;
+    const words = (text.trim().match(/\S+/g) || []).length;
+    return `${rel} → 글자 ${chars}, 줄 ${lines}, 단어 ${words}`;
+  },
+};

package/workspace/.cdsa/skills/summarize.md

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