622 lines
22 KiB
Markdown
622 lines
22 KiB
Markdown
# Refactor: agent / skills / tools DX 개선 plan
|
|
|
|
> 한 번의 작업 세션으로 codex가 처음부터 끝까지 수행할 수 있도록 작성된 단일 PR plan.
|
|
|
|
---
|
|
|
|
## 목표
|
|
|
|
지금 구조는 컨셉상 "agent ⊃ skills ⊃ tools"인데 실제 코드가 다음과 같이 어긋나 있다.
|
|
|
|
1. `src/tools/builtins/`의 5개 tool은 전부 onboarding 전용인데도 글로벌 폴더에 위치
|
|
2. tool 파일이 `@skills/onboarding/*`을 import (의존 방향이 거꾸로)
|
|
3. `OnboardingSkill`이 모든 tool을 `createBuiltInToolRegistry().list()`로 받아 `selectToolsForDerived()`에서 **이름 문자열로** 필터 → 오타에 무방비
|
|
4. `runtime/tool-loop.ts`는 generic LLM↔tool loop인데 onboarding 폴더 안에 갇혀 있음
|
|
5. `Skill` 인터페이스가 `name/canHandle/handle` 3줄뿐 — 새 skill이 어떻게 자기 tool을 선언할지 가이드 없음
|
|
6. skill의 의존성 조립이 `main.ts`에 노출 — skill 폴더에 entry factory가 없음
|
|
|
|
이 plan을 끝내면:
|
|
|
|
- onboarding-tool은 onboarding 폴더 안에서 self-contained
|
|
- tool→skill의 역방향 import 0건
|
|
- `selectToolsForDerived`가 tool 객체 직접 참조 (컴파일 타임 안전)
|
|
- generic runtime은 `src/agent/runtime/`로 hoist
|
|
- `Skill` 인터페이스에 `tools` 필드 추가
|
|
- `createOnboardingSkill(deps)` factory 도입
|
|
- `docs/skill-authoring.md`로 신규 skill/tool 추가 절차 문서화
|
|
|
|
---
|
|
|
|
## 최종 구조
|
|
|
|
```
|
|
src/
|
|
agent/
|
|
agent.ts
|
|
types.ts
|
|
index.ts
|
|
runtime/
|
|
tool-loop.ts ← hoisted from skills/onboarding/runtime
|
|
tool-loop.test.ts ← hoisted
|
|
tools/
|
|
tool.ts ← ToolContext에서 OnboardingSession 제거, generic param 추가
|
|
registry.ts
|
|
parser.ts
|
|
parser.test.ts
|
|
serializer.ts
|
|
index.ts
|
|
(builtins/ 폴더 삭제)
|
|
skills/
|
|
skill.ts ← tools: readonly Tool[] 추가
|
|
onboarding/
|
|
index.ts ← createOnboardingSkill(deps) factory export
|
|
skill.ts ← tool을 직접 import, selectToolsForDerived 객체 참조
|
|
session.ts
|
|
types.ts
|
|
constants.ts
|
|
message-filter.ts
|
|
onboarding-templates.ts
|
|
tools/ ← NEW: onboarding 전용 tool 모음
|
|
index.ts ← createOnboardingToolRegistry, ALL_TOOLS export
|
|
context.ts ← OnboardingToolContext
|
|
validate-nickname.ts
|
|
check-onboarding-progress.ts
|
|
check-onboarding-progress.test.ts
|
|
lookup-community-rule.ts
|
|
get-room-context.ts
|
|
verify-discord-nickname.ts
|
|
verify-discord-nickname.test.ts
|
|
prompts/ ← 변경 없음
|
|
runtime/ ← tool-loop만 빠짐
|
|
orchestrator.ts ← import 경로 갱신
|
|
orchestrator.test.ts
|
|
critic.ts
|
|
validator.ts
|
|
validator.test.ts
|
|
planner-schema.ts
|
|
trace.ts
|
|
state/ ← 변경 없음
|
|
docs/
|
|
skill-authoring.md ← NEW
|
|
```
|
|
|
|
---
|
|
|
|
## 변경 사항 상세
|
|
|
|
### 1. `src/tools/tool.ts` — ToolContext에서 onboarding 의존성 제거 + Tool generic화
|
|
|
|
**before**
|
|
|
|
```ts
|
|
import type { GarnetClient } from "@common/garnet";
|
|
import type { NatsClient } from "@common/nats";
|
|
import type { RoomContextService } from "@room/room-context-service";
|
|
import type { ZodType } from "zod";
|
|
import type { OnboardingSession } from "@skills/onboarding/types";
|
|
|
|
export interface ToolContext {
|
|
chatroomId?: string | undefined;
|
|
natsClient?: Pick<NatsClient, "request"> | undefined;
|
|
userId?: string | undefined;
|
|
session?: OnboardingSession | null | undefined;
|
|
garnetClient?: GarnetClient | undefined;
|
|
roomContextService?: RoomContextService | undefined;
|
|
}
|
|
|
|
export interface Tool<A, R> {
|
|
name: string;
|
|
description: string;
|
|
argsSchema: ZodType<A>;
|
|
resultSchema: ZodType<R>;
|
|
execute(args: A, ctx: ToolContext): Promise<R>;
|
|
}
|
|
```
|
|
|
|
**after**
|
|
|
|
```ts
|
|
import type { GarnetClient } from "@common/garnet";
|
|
import type { NatsClient } from "@common/nats";
|
|
import type { RoomContextService } from "@room/room-context-service";
|
|
import type { ZodType } from "zod";
|
|
|
|
export interface ToolContext {
|
|
chatroomId?: string | undefined;
|
|
natsClient?: Pick<NatsClient, "request"> | undefined;
|
|
userId?: string | undefined;
|
|
garnetClient?: GarnetClient | undefined;
|
|
roomContextService?: RoomContextService | undefined;
|
|
}
|
|
|
|
export interface Tool<A, R, C extends ToolContext = ToolContext> {
|
|
name: string;
|
|
description: string;
|
|
argsSchema: ZodType<A>;
|
|
resultSchema: ZodType<R>;
|
|
execute(args: A, ctx: C): Promise<R>;
|
|
}
|
|
```
|
|
|
|
`@skills/onboarding/types` import 한 줄과 `session` 필드 한 줄을 삭제, `Tool`에 generic `C` 추가. default를 `ToolContext`로 두면 기존 `Tool<A, R>` 호출도 그대로 유효.
|
|
|
|
### 2. `src/skills/onboarding/tools/context.ts` — 신규 파일
|
|
|
|
```ts
|
|
import type { ToolContext } from "@tools/tool";
|
|
import type { OnboardingSession } from "../types.js";
|
|
|
|
export interface OnboardingToolContext extends ToolContext {
|
|
session?: OnboardingSession | null | undefined;
|
|
}
|
|
```
|
|
|
|
### 3. tool 5개 + test 2개 이동
|
|
|
|
git mv로 파일을 옮기고, 옮긴 파일의 내부 import 경로만 수정.
|
|
|
|
| from | to |
|
|
|---|---|
|
|
| `src/tools/builtins/validate-nickname.ts` | `src/skills/onboarding/tools/validate-nickname.ts` |
|
|
| `src/tools/builtins/check-onboarding-progress.ts` | `src/skills/onboarding/tools/check-onboarding-progress.ts` |
|
|
| `src/tools/builtins/check-onboarding-progress.test.ts` | `src/skills/onboarding/tools/check-onboarding-progress.test.ts` |
|
|
| `src/tools/builtins/lookup-community-rule.ts` | `src/skills/onboarding/tools/lookup-community-rule.ts` |
|
|
| `src/tools/builtins/get-room-context.ts` | `src/skills/onboarding/tools/get-room-context.ts` |
|
|
| `src/tools/builtins/verify-discord-nickname.ts` | `src/skills/onboarding/tools/verify-discord-nickname.ts` |
|
|
| `src/tools/builtins/verify-discord-nickname.test.ts` | `src/skills/onboarding/tools/verify-discord-nickname.test.ts` |
|
|
| `src/tools/builtins/index.ts` | (덮어쓰기, 아래 #4 참고) |
|
|
|
|
각 파일에서 import 경로를 다음 규칙으로 갱신:
|
|
|
|
- `import type { Tool, ToolContext } from "../tool.js";`
|
|
→ `import type { Tool } from "@tools/tool";`
|
|
→ `import type { OnboardingToolContext } from "./context.js";`
|
|
- `from "@skills/onboarding/onboarding-templates"` → `from "../onboarding-templates.js"`
|
|
- `from "@skills/onboarding/constants"` → `from "../constants.js"`
|
|
- `from "@skills/onboarding/types"` → `from "../types.js"`
|
|
- `from "@skills/onboarding/session"` → `from "../session.js"`
|
|
- `from "@skills/onboarding/state/progress"` → `from "../state/progress.js"`
|
|
- `from "../../config.js"` → `from "../../../config.js"` (한 단계 깊어짐)
|
|
- 테스트 파일도 동일한 규칙 + 새 위치 기준으로 sibling import 경로 사용
|
|
|
|
각 tool의 export 시그니처를 `Tool<Args, Result>` → `Tool<Args, Result, OnboardingToolContext>`로 변경. `ctx` 파라미터를 사용하는 함수(`persistDiscordMemberId(memberId, ctx)` 등) 내부 타입도 맞춰서 `OnboardingToolContext`로 갱신.
|
|
|
|
### 4. `src/skills/onboarding/tools/index.ts` — 신규 (구 `tools/builtins/index.ts` 대체)
|
|
|
|
```ts
|
|
import type { Tool } from "@tools/tool";
|
|
import { ToolRegistry } from "@tools/registry";
|
|
import type { OnboardingToolContext } from "./context.js";
|
|
import { checkOnboardingProgressTool } from "./check-onboarding-progress.js";
|
|
import { getRoomContextTool } from "./get-room-context.js";
|
|
import { lookupCommunityRuleTool } from "./lookup-community-rule.js";
|
|
import { validateNicknameTool } from "./validate-nickname.js";
|
|
import { verifyDiscordNicknameTool } from "./verify-discord-nickname.js";
|
|
|
|
export const onboardingTools = {
|
|
validateNickname: validateNicknameTool,
|
|
checkOnboardingProgress: checkOnboardingProgressTool,
|
|
lookupCommunityRule: lookupCommunityRuleTool,
|
|
getRoomContext: getRoomContextTool,
|
|
verifyDiscordNickname: verifyDiscordNicknameTool,
|
|
} as const;
|
|
|
|
export const onboardingToolList: readonly Tool<unknown, unknown, OnboardingToolContext>[] = [
|
|
validateNicknameTool,
|
|
checkOnboardingProgressTool,
|
|
lookupCommunityRuleTool,
|
|
getRoomContextTool,
|
|
verifyDiscordNicknameTool,
|
|
];
|
|
|
|
export function createOnboardingToolRegistry(): ToolRegistry {
|
|
return new ToolRegistry()
|
|
.register(validateNicknameTool)
|
|
.register(checkOnboardingProgressTool)
|
|
.register(lookupCommunityRuleTool)
|
|
.register(getRoomContextTool)
|
|
.register(verifyDiscordNicknameTool);
|
|
}
|
|
|
|
export {
|
|
checkOnboardingProgressTool,
|
|
getRoomContextTool,
|
|
lookupCommunityRuleTool,
|
|
validateNicknameTool,
|
|
verifyDiscordNicknameTool,
|
|
};
|
|
export type { OnboardingToolContext } from "./context.js";
|
|
```
|
|
|
|
### 5. 빈 `src/tools/builtins/` 폴더 삭제
|
|
|
|
```bash
|
|
rm -rf src/tools/builtins
|
|
```
|
|
|
|
### 6. `src/skills/onboarding/skill.ts` — tool 객체 직접 참조
|
|
|
|
다음 import를 추가:
|
|
|
|
```ts
|
|
import {
|
|
checkOnboardingProgressTool,
|
|
lookupCommunityRuleTool,
|
|
onboardingToolList,
|
|
validateNicknameTool,
|
|
verifyDiscordNicknameTool,
|
|
type OnboardingToolContext,
|
|
} from './tools/index.js';
|
|
```
|
|
|
|
기존:
|
|
|
|
```ts
|
|
import { createBuiltInToolRegistry } from '@tools/builtins/index';
|
|
import type { Tool, ToolContext } from '@tools/tool';
|
|
```
|
|
|
|
→ 다음으로 변경:
|
|
|
|
```ts
|
|
import type { Tool } from '@tools/tool';
|
|
```
|
|
|
|
(`ToolContext` 사용처는 모두 `OnboardingToolContext`로 교체)
|
|
|
|
생성자 내부:
|
|
|
|
```ts
|
|
this.tools = createBuiltInToolRegistry().list();
|
|
```
|
|
|
|
→
|
|
|
|
```ts
|
|
this.tools = onboardingToolList;
|
|
```
|
|
|
|
`tools` 필드 타입을 `readonly Tool<unknown, unknown, OnboardingToolContext>[]`로 변경.
|
|
|
|
`buildToolContext(...)` 반환 타입을 `ToolContext` → `OnboardingToolContext`.
|
|
|
|
`generateLlmText` 시그니처 옵션의 `toolContext?: ToolContext | undefined` → `OnboardingToolContext | undefined`. `tools?: readonly Tool<unknown, unknown>[] | undefined` → `readonly Tool<unknown, unknown, OnboardingToolContext>[] | undefined`.
|
|
|
|
핵심: `selectToolsForDerived`를 객체 참조로 다시 작성:
|
|
|
|
```ts
|
|
private selectToolsForDerived(
|
|
derived: DerivedState,
|
|
): readonly Tool<unknown, unknown, OnboardingToolContext>[] {
|
|
if (derived.intent.kind === 'discord-verify-question') {
|
|
return [verifyDiscordNicknameTool];
|
|
}
|
|
|
|
if (derived.phase.kind === 'nickname-rejected') {
|
|
return [
|
|
validateNicknameTool,
|
|
lookupCommunityRuleTool,
|
|
checkOnboardingProgressTool,
|
|
];
|
|
}
|
|
|
|
if (derived.intent.kind === 'status-question') {
|
|
return [checkOnboardingProgressTool];
|
|
}
|
|
|
|
if (derived.intent.kind === 'discord-question') {
|
|
return [lookupCommunityRuleTool, verifyDiscordNicknameTool];
|
|
}
|
|
|
|
return this.tools;
|
|
}
|
|
```
|
|
|
|
문자열 매칭(`tool.name === '...'`) 전부 제거. tool 이름 변경/삭제 시 컴파일 에러로 잡힌다.
|
|
|
|
마지막으로 클래스 상단에 `Skill` 인터페이스의 `tools` 필드를 노출:
|
|
|
|
```ts
|
|
get tools(): readonly Tool<unknown, unknown>[] {
|
|
return onboardingToolList as readonly Tool<unknown, unknown>[];
|
|
}
|
|
```
|
|
|
|
(또는 그냥 public 필드로 두어도 됨. 테스트 깨지지 않게 getter 권장.)
|
|
|
|
### 7. `src/skills/skill.ts` — 인터페이스에 tools 추가
|
|
|
|
```ts
|
|
import type { AgentRequest, AgentResponse, ConversationMessage } from "@agent/types";
|
|
import type { Tool } from "@tools/tool";
|
|
|
|
export interface Skill {
|
|
readonly name: string;
|
|
readonly tools: readonly Tool<unknown, unknown>[];
|
|
canHandle(request: AgentRequest): boolean;
|
|
handle(
|
|
request: AgentRequest,
|
|
conversationHistory: ConversationMessage[],
|
|
): Promise<AgentResponse>;
|
|
}
|
|
```
|
|
|
|
### 8. `src/agent/runtime/tool-loop.ts` — hoist
|
|
|
|
`src/skills/onboarding/runtime/tool-loop.ts` → `src/agent/runtime/tool-loop.ts`로 이동.
|
|
`src/skills/onboarding/runtime/tool-loop.test.ts` → `src/agent/runtime/tool-loop.test.ts`로 이동.
|
|
|
|
이동 후 import 경로 점검:
|
|
- `import { parseToolCalls } from "@tools/parser";` 그대로 유효
|
|
- `import type { Tool, ToolContext } from "@tools/tool";` 그대로 유효
|
|
- `import { getActiveProcessTrace } from "./trace.js";` →
|
|
- 결정 사항: `trace.ts`는 onboarding 전용이므로 hoist하지 않는다.
|
|
- tool-loop가 trace 의존성을 가지면 안 됨. 따라서 **trace 호출을 옵션 콜백으로 일반화**:
|
|
|
|
`tool-loop.ts` 변경:
|
|
|
|
```ts
|
|
export interface ToolLoopOptions {
|
|
// ...기존...
|
|
onToolCallStart?: (call: { name: string; args: unknown }) => {
|
|
finish: (result: { ok: boolean; resultSummary: string }) => void;
|
|
};
|
|
}
|
|
```
|
|
|
|
내부에서 `getActiveProcessTrace()?.startStep('tool-call')` 호출하던 자리를 `options.onToolCallStart?.(...)` 호출로 대체.
|
|
|
|
orchestrator(onboarding 전용)에서 `runWithTools` 호출 시 `onToolCallStart` 콜백을 주입:
|
|
|
|
```ts
|
|
import { runWithTools } from "@agent/runtime/tool-loop";
|
|
// ...
|
|
return runWithTools({
|
|
// ...기존 옵션...
|
|
onToolCallStart: ({ name, args }) => {
|
|
const step = getActiveProcessTrace()?.startStep('tool-call');
|
|
return {
|
|
finish: ({ ok, resultSummary }) => {
|
|
step?.finish({ args, name, ok, resultSummary });
|
|
},
|
|
};
|
|
},
|
|
});
|
|
```
|
|
|
|
orchestrator.ts에서:
|
|
|
|
```ts
|
|
import { runWithTools } from "./tool-loop.js";
|
|
```
|
|
|
|
→
|
|
|
|
```ts
|
|
import { runWithTools } from "@agent/runtime/tool-loop";
|
|
```
|
|
|
|
`ToolContext` import도 마찬가지로 그대로.
|
|
|
|
`tool-loop.test.ts`도 mock 시나리오 점검 — trace 의존성 사라졌으므로 테스트는 단순화 가능하지만, 기능 회귀가 없다면 **테스트는 import 경로만 바꾸고 기존 시나리오 유지**.
|
|
|
|
### 9. `src/skills/onboarding/index.ts` — factory export
|
|
|
|
기존 (3줄짜리 re-export):
|
|
|
|
```ts
|
|
export { OnboardingSkill } from './skill.js';
|
|
export type { OnboardingSession } from './types.js';
|
|
```
|
|
|
|
추가:
|
|
|
|
```ts
|
|
import type { GarnetClient } from '@common/garnet';
|
|
import type { NatsClient } from '@common/nats';
|
|
import type { LlmClient } from '@llm/llm-client';
|
|
import type { RoomContextService } from '@room/room-context-service';
|
|
import type { ShadowEvalPublisher } from '@eval/shadow-bus';
|
|
import { OnboardingSkill } from './skill.js';
|
|
|
|
export interface CreateOnboardingSkillOptions {
|
|
garnetClient: GarnetClient;
|
|
llmClient: LlmClient;
|
|
roomContextService?: RoomContextService;
|
|
shadowEvalPublisher?: ShadowEvalPublisher;
|
|
natsClient?: Pick<NatsClient, 'request'>;
|
|
}
|
|
|
|
export function createOnboardingSkill(opts: CreateOnboardingSkillOptions): OnboardingSkill {
|
|
return new OnboardingSkill(
|
|
opts.garnetClient,
|
|
opts.llmClient,
|
|
opts.roomContextService,
|
|
opts.shadowEvalPublisher,
|
|
opts.natsClient,
|
|
);
|
|
}
|
|
|
|
export { OnboardingSkill } from './skill.js';
|
|
export type { OnboardingSession } from './types.js';
|
|
```
|
|
|
|
`OnboardingSkill` 클래스의 생성자 시그니처는 건드리지 않는다 (eval/runner.ts가 직접 생성하는 곳이 있어 호환 유지).
|
|
|
|
### 10. `src/main.ts` — factory 사용
|
|
|
|
기존 `src/main.ts:218-229`:
|
|
|
|
```ts
|
|
const agent = new Agent(natsClient, conversationStore);
|
|
const shadowEvalBus = new ShadowEvalBus(garnetClient);
|
|
const onboardingSkill = new OnboardingSkill(
|
|
garnetClient,
|
|
llmClient,
|
|
roomContextService,
|
|
shadowEvalBus,
|
|
natsClient,
|
|
);
|
|
agent.registerSkill(onboardingSkill);
|
|
```
|
|
|
|
→
|
|
|
|
```ts
|
|
const agent = new Agent(natsClient, conversationStore);
|
|
const shadowEvalBus = new ShadowEvalBus(garnetClient);
|
|
const onboardingSkill = createOnboardingSkill({
|
|
garnetClient,
|
|
llmClient,
|
|
roomContextService,
|
|
shadowEvalPublisher: shadowEvalBus,
|
|
natsClient,
|
|
});
|
|
agent.registerSkill(onboardingSkill);
|
|
```
|
|
|
|
import 변경:
|
|
|
|
```ts
|
|
import { OnboardingSkill } from '@skills/onboarding/index';
|
|
```
|
|
→
|
|
```ts
|
|
import { createOnboardingSkill } from '@skills/onboarding/index';
|
|
```
|
|
|
|
### 11. `src/eval/judges/process-judge.ts` — registry import 경로 갱신
|
|
|
|
```ts
|
|
import { createBuiltInToolRegistry } from "@tools/builtins/index";
|
|
```
|
|
→
|
|
```ts
|
|
import { createOnboardingToolRegistry } from "@skills/onboarding/tools/index";
|
|
```
|
|
|
|
호출부 `createBuiltInToolRegistry()` → `createOnboardingToolRegistry()`로 일괄 변경.
|
|
|
|
### 12. `src/eval/runner.ts` — 변경 없음 권장
|
|
|
|
`new OnboardingSkill(...)` 직접 호출 부분은 그대로 둔다 (factory만 main.ts에서 사용). 호환성 유지를 위해 클래스도 계속 export.
|
|
|
|
### 13. 그 외 영향받는 import 점검 (grep으로 확인)
|
|
|
|
다음 패턴이 남아 있으면 안 됨:
|
|
- `@tools/builtins` (모두 `@skills/onboarding/tools` 또는 직접 import로 교체)
|
|
- tool 파일 안의 `@skills/onboarding/*` (모두 relative `../...`로 교체)
|
|
- `tool.name === '...'` 형태의 문자열 매칭 (객체 참조로 교체)
|
|
|
|
검증 명령:
|
|
```bash
|
|
grep -rn "@tools/builtins" src
|
|
# → 결과 0건이어야 함
|
|
|
|
grep -n "from \"@skills/onboarding" src/skills/onboarding/tools
|
|
# → 결과 0건 (tool 파일이 자기 skill을 alias로 import 금지)
|
|
|
|
grep -n "tool.name ===" src/skills
|
|
# → 결과 0건
|
|
```
|
|
|
|
### 14. `docs/skill-authoring.md` — 신규 가이드
|
|
|
|
```markdown
|
|
# Skill / Tool 추가 가이드
|
|
|
|
## 새 tool 추가
|
|
1. `src/skills/<your-skill>/tools/<tool-name>.ts` 생성.
|
|
2. `Tool<Args, Result, YourSkillToolContext>` 형태로 export.
|
|
3. `src/skills/<your-skill>/tools/index.ts`의 `onboardingToolList` 같은 배열에 등록.
|
|
4. skill 파일에서 직접 import해 `selectToolsForDerived`(또는 동등한 메서드)에 객체로 추가.
|
|
5. tool은 절대 `@skills/...` alias로 다른 skill을 import하지 않는다 (relative import만 허용).
|
|
|
|
## 새 skill 추가
|
|
1. `src/skills/<your-skill>/` 폴더 생성.
|
|
2. `Skill` 인터페이스(`src/skills/skill.ts`) 구현 — 최소한 `name`, `tools`, `canHandle`, `handle`.
|
|
3. `tools/` 서브폴더에 자기 tool 모음과 `<YourSkill>ToolContext extends ToolContext`.
|
|
4. `index.ts`에 `create<YourSkill>Skill(opts)` factory 추가.
|
|
5. `src/main.ts`의 bootstrap에서 factory 호출 후 `agent.registerSkill(...)`.
|
|
6. LLM↔tool 루프가 필요하면 `@agent/runtime/tool-loop`의 `runWithTools` 재사용.
|
|
|
|
## 어디를 보면 되나
|
|
- agent 디스패처: `src/agent/agent.ts`
|
|
- skill 인터페이스: `src/skills/skill.ts`
|
|
- generic tool 인터페이스: `src/tools/tool.ts`
|
|
- generic LLM↔tool 루프: `src/agent/runtime/tool-loop.ts`
|
|
- onboarding skill 구현: `src/skills/onboarding/`
|
|
- onboarding tool 모음: `src/skills/onboarding/tools/`
|
|
```
|
|
|
|
---
|
|
|
|
## 실행 순서 (codex가 그대로 따라가도록)
|
|
|
|
각 단계는 끝나면 다음 단계로 넘어가기 전에 typecheck를 돌릴 수 있다 (선택).
|
|
|
|
1. **`src/tools/tool.ts` 수정**: `OnboardingSession` import 제거, `session` 필드 제거, `Tool`에 generic `C extends ToolContext = ToolContext` 추가.
|
|
2. **새 폴더 생성**: `src/skills/onboarding/tools/`, `src/agent/runtime/`.
|
|
3. **`src/skills/onboarding/tools/context.ts` 작성** (위 #2 내용).
|
|
4. **tool 5개 + test 2개 이동** (`git mv`로). 각 파일 import 경로 갱신 + 시그니처 `Tool<A, R, OnboardingToolContext>`로 변경.
|
|
5. **`src/skills/onboarding/tools/index.ts` 작성** (위 #4 내용).
|
|
6. **`src/tools/builtins/` 삭제**: `rm -rf src/tools/builtins` (이미 모두 옮겼는지 ls로 확인).
|
|
7. **tool-loop hoist**: `git mv src/skills/onboarding/runtime/tool-loop.ts src/agent/runtime/tool-loop.ts` (test도). trace 의존성을 `onToolCallStart` 콜백으로 일반화.
|
|
8. **`src/skills/onboarding/runtime/orchestrator.ts` 갱신**: `runWithTools` import 경로를 `@agent/runtime/tool-loop`로 변경, `onToolCallStart` 콜백으로 trace 주입.
|
|
9. **`src/skills/skill.ts` 인터페이스 확장**: `tools: readonly Tool[]` 추가.
|
|
10. **`src/skills/onboarding/skill.ts` 갱신**:
|
|
- `@tools/builtins/index` import 제거.
|
|
- 개별 tool import 추가.
|
|
- `this.tools = onboardingToolList`.
|
|
- `selectToolsForDerived`를 객체 참조로 재작성.
|
|
- `ToolContext` 사용처를 `OnboardingToolContext`로 교체.
|
|
- `tools` getter 노출.
|
|
11. **`src/skills/onboarding/index.ts`에 factory 추가** (위 #9 내용).
|
|
12. **`src/main.ts` 갱신** (위 #10 내용).
|
|
13. **`src/eval/judges/process-judge.ts` import 경로 갱신** (위 #11 내용).
|
|
14. **`docs/skill-authoring.md` 작성** (위 #14 내용).
|
|
15. **검증**:
|
|
```bash
|
|
grep -rn "@tools/builtins" src # 0건
|
|
grep -rn "tool.name ===" src/skills # 0건
|
|
npm run typecheck
|
|
npm run lint
|
|
npm run test
|
|
```
|
|
셋 다 통과하면 완료.
|
|
|
|
---
|
|
|
|
## 위험 요소 및 대응
|
|
|
|
| 위험 | 대응 |
|
|
|---|---|
|
|
| `Tool<A, R>`의 default generic이 `ToolContext`라서 기존 호출부가 `OnboardingToolContext` 필드(`session`)를 못 읽을 수 있음 | onboarding 안의 모든 사용처를 `Tool<..., OnboardingToolContext>`로 명시적 선언. tool-loop는 generic하게 받으므로 무관. |
|
|
| `selectToolsForDerived`가 `readonly Tool<unknown, unknown, OnboardingToolContext>[]`를 반환하는데 `generateLlmText` 옵션이 `Tool<unknown, unknown>[]`를 받으면 covariance 문제 발생 가능 | `generateLlmText`/`orchestrator.run`/`runWithTools`까지 일관되게 `OnboardingToolContext`로 흘려준다. tool-loop는 `Tool<unknown, unknown, C>` generic으로 받도록 수정. |
|
|
| trace 호출을 콜백으로 빼면서 누락이 생길 수 있음 | `tool-loop.test.ts`에 "콜백이 ok=true/false 둘 다에서 호출되는지" 테스트 한두 개 추가. |
|
|
| `eval/runner.ts`의 `new OnboardingSkill(...)`가 ctor 시그니처 의존 | ctor는 건드리지 않으므로 회귀 없음. |
|
|
| import 깊이가 한 단계 늘어나는 케이스 (`../../../config.js`) | 그대로 두거나, 필요하면 `@config` alias 신설. 본 plan에선 alias 추가 안 함. |
|
|
| pre-commit hook이 lint/format을 강제할 수 있음 | 마지막에 `npm run lint:fix && npm run format` 한 번 실행. |
|
|
|
|
---
|
|
|
|
## 비목표 (이번 PR에서 안 함)
|
|
|
|
- `src/skills/onboarding/runtime/orchestrator.ts`의 onboarding-specific planner를 generic화하는 작업 (별도 작업)
|
|
- `prompts/tool-policy.ts`의 자연어 정책을 코드 정책으로 통합 (별도)
|
|
- 두 번째 skill 추가
|
|
- `ToolRegistry` API 단순화 (`pick(names)` 제거 등)
|
|
|
|
---
|
|
|
|
## 검증 체크리스트
|
|
|
|
- [ ] `grep -rn "@tools/builtins" src` → 0건
|
|
- [ ] `grep -rn "from \"@skills/onboarding" src/skills/onboarding/tools` → 0건 (relative만)
|
|
- [ ] `grep -n "tool.name ===" src/skills/onboarding/skill.ts` → 0건
|
|
- [ ] `npm run typecheck` 통과
|
|
- [ ] `npm run lint` 통과
|
|
- [ ] `npm run test` 통과 (특히 `tool-loop.test.ts`, `check-onboarding-progress.test.ts`, `verify-discord-nickname.test.ts`)
|
|
- [ ] `npm run build` 통과
|
|
- [ ] `docs/skill-authoring.md` 존재
|