cdsa-harness 0.1.1 → 0.4.0

package/README.md

@@ -1,81 +1,146 @@
-# CDSA Harness (Node.js CLI) ⌨️
+# CDSA Harness (Node.js CLI) 🎓⌨️
 
-> Claude Code / Codex CLI / OpenCode 와 **똑같은 방식(npm/npx)** 으로 설치하는,
-> 좁은 의미의 AI 에이전트 하네스 교육용 터미널 앱.
-
-시작하면 ASCII 배너가 뜨고, **Agent Loop** 의 모든 단계가 색으로 흐릅니다.
+> **AI 에이전트가 내부에서 실제로 뭘 하는지** 단계별로 드러내는 교육용 터미널 하네스.
+> Claude Code·Codex 는 과정을 숨기지만, CDSA Harness 는 **컨텍스트 구성 → API 요청 → 모델의 판단 → 토큰/응답시간 → 도구 실행 → 결과 되먹임**을 전부 펼쳐 보여줍니다.
 
 ```
-입력 → 컨텍스트 구성 → LLM 호출 → 도구 판단 → 승인 → 실행 → 결과 반영 → 반복
+① 입력 → ② LLM 호출(보낼 컨텍스트·도구) → ③ 모델 응답(토큰·지연·tool_call)
+      → ④ 도구 판단 → ⑤ 실행/승인 → ⑥ 결과 되먹임 → (반복)
 ```
 
-- **의존성 0개** — Node 18+ 내장 기능만 사용(`fetch`/`readline`/`node:test`). `npx` 가 빠르고 설치 실패가 없습니다.
-- 같은 저장소의 Python 버전(Mini Harness GUI / CDSA Harness TUI)과 **동일한 하네스 구조**를 그대로 옮긴 것입니다.
+- **의존성 0개** — Node 18+ 내장 기능만(`fetch`/`readline`/`node:test`)
+- **실제 LLM 연결** — OpenAI · Anthropic(Claude) · OpenRouter, 또는 키 없이 `mock`
+- **교육 모드** — 매 반복마다 모델에 보내는 메시지 구성·추정 토큰·시스템 프롬프트, 실제 토큰 사용량/응답시간까지 그대로 표시
+- **플러그인** — `.cdsa/plugins/` 에 JS 파일을 두면 **새 도구가 자동 등록**되어 모델이 사용
+- **스킬** — `.cdsa/skills/` 에 마크다운을 두면 `/이름` 으로 부르는 **프롬프트 템플릿**
 
 ---
 
 ## 설치 / 실행
 
-### npx (설치 없이 즉시)
-
 ```bash
-# 로컬 체크아웃에서
-cd node-cli
-npx .                       # API Key 없으면 자동 mock 모드
+npx cdsa-harness                 # 설치 없이 즉시 (키 없으면 mock)
+npm install -g cdsa-harness      # 전역 설치 → 'cdsa-harness' / 'cdsa'
 ```
 
-### 전역 설치
+## 실제 AI 연결하기
 
+가장 쉬운 길 — 실행 후 `/setup` 입력(대화형으로 제공자·키·모델 선택):
 ```bash
-cd node-cli
-npm install -g .            # 또는: npm link
-cdsa-harness                # 어디서나 실행 (별칭: cdsa)
+cdsa-harness
+› /setup
 ```
 
-### 그냥 node 로
-
+또는 플래그/환경변수로:
 ```bash
-cd node-cli
-node bin/cdsa-harness.js
+cdsa-harness --provider openai --model gpt-4o-mini
+cdsa-harness --provider anthropic --model claude-3-5-haiku-latest
+
+# 키는 환경변수로도 자동 인식(파일에 저장 안 함)
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENROUTER_API_KEY=sk-or-...
 ```
 
-> npm 레지스트리에 publish 하면 `npm install -g cdsa-harness` / `npx cdsa-harness` 로 바로 설치됩니다.
+---
+
+## 슬래시 명령
+
+| 명령 | 설명 |
+|------|------|
+| `/setup` | 제공자·API 키·모델 대화형 연결 |
+| `/provider <이름>` | openai · anthropic · openrouter · mock 전환 |
+| `/model <이름>` | 모델 변경 |
+| `/teach` | 교육 모드 켜기/끄기 |
+| `/context` | 지금 모델에 보내는 컨텍스트 들여다보기 |
+| `/reset` | 대화/컨텍스트 초기화 |
+| `/config` | 현재 설정값 |
+| `/quit` | 종료 (Ctrl+D) |
+
+## 플래그
+
+```
+--provider <openai|anthropic|openrouter|mock>
+--model <모델명>
+--workspace <폴더경로>
+--setup        대화형 연결 설정
+--no-teach     교육 모드 끄고 간결 출력
+--auto         승인 자동
+```
 
 ---
 
-## 옵션 / 명령
+## 🔌 플러그인 (추가 도구)
+
+### 방법 A — npm 으로 설치 (권장)
+
+`cdsa-harness-plugin-*` 이름의 패키지를 설치하면 **자동으로 발견·로드**됩니다.
 
 ```bash
-cdsa-harness --provider openai --model gpt-4.1-mini   # 실제 LLM
-cdsa-harness --provider openrouter --model anthropic/claude-3.5-sonnet
-cdsa-harness --workspace ./my-project                 # 작업 폴더 지정
-cdsa-harness --auto                                   # 승인 자동
+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}`;
+  },
+};
 ```
 
-터미널 슬래시 명령: `/help` · `/reset` · `/config` · `/sessions` · `/quit` (Ctrl+D 로도 종료)
+## 🎯 스킬 (프롬프트 템플릿)
 
+`.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` 이 있으면 우선).
+`~/.cdsa_harness/config.json` (실행 폴더에 `config.json` 있으면 우선).
 
 ```json
 {
   "provider": "openai",
   "api_key": "",
-  "model": "gpt-4.1-mini",
+  "model": "gpt-4o-mini",
   "workspace": "./workspace",
   "approval_mode": "manual",
   "allow_shell": false,
   "max_steps": 8,
-  "temperature": 0.2
+  "temperature": 0.2,
+  "max_tokens": 1024,
+  "teach_mode": true
 }
 ```
 
-작업 폴더 상대경로는 **현재 폴더(cwd)** 기준으로 해석합니다(CLI 답게).
-
----
+> `api_key` 가 비어 있으면 해당 provider 의 환경변수를 자동으로 찾습니다.
 
 ## 도구 & 안전장치
 
@@ -94,23 +159,20 @@ cdsa-harness --auto                                   # 승인 자동
 
 ```
 node-cli/
-├── bin/cdsa-harness.js   # npm/npx 진입점 (#!/usr/bin/env node)
+├── bin/cdsa-harness.js   # npm/npx 진입점
 ├── src/
-│   ├── config.js         # 설정 로드/저장
-│   ├── llm.js            # OpenAI/OpenRouter(fetch) + mock
-│   ├── tools.js          # 도구 + sandbox + diff + 스키마
-│   ├── loop.js           # ⭐ Agent Loop
+│   ├── config.js         # 설정 + 환경변수 키 감지
+│   ├── llm.js            # OpenAI/Anthropic/OpenRouter + mock, 응답 정규화(토큰·지연)
+│   ├── tools.js          # 도구 + sandbox + diff
+│   ├── loop.js           # ⭐ Agent Loop + 교육용 이벤트(컨텍스트/되먹임)
 │   ├── session.js        # 세션 로그(JSONL)
-│   ├── banner.js         # CDSA HARNESS ASCII 배너
-│   ├── ui.js             # ANSI 색/박스/diff 렌더
-│   └── cli.js            # 터미널 REPL
-├── workspace/            # 샘플 작업 폴더
+│   ├── banner.js / ui.js # 배너 · ANSI/박스/diff 렌더
+│   └── cli.js            # REPL + 교육 모드 렌더 + /setup
 └── test/core.test.js     # node --test
 ```
 
 ## 테스트
 
 ```bash
-cd node-cli
 npm test        # node --test
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdsa-harness",
-  "version": "0.1.1",
-  "description": "좁은 의미의 AI 에이전트 하네스를 터미널에서 체험하는 교육용 CLI (Claude Code / Codex / OpenCode 구조의 미니 런타임)",
+  "version": "0.4.0",
+  "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. OpenAI/Claude/OpenRouter + npm 으로 설치하는 플러그인(추가 도구)·스킬 확장.",
   "type": "module",
   "bin": {
     "cdsa-harness": "bin/cdsa-harness.js",