Skip to content

Commit fc01b9b

Browse files
thrcleclaude
thrcle
and
claude
committed
feat: /help 슬래시 커맨드 추가 및 사용자 가이드 작성
- /help: 커맨드 목록과 사용 플로우를 Discord에서 바로 확인 가능 - docs/USAGE.md: 처음 사용하는 유저를 위한 단계별 가이드 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent b4ba91b commit fc01b9b

3 files changed

Lines changed: 163 additions & 0 deletions

File tree

‎docs/USAGE.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Lang2SQL 사용 가이드
2+
3+
Discord에서 자연어로 질문하면 SQL을 생성하고 결과를 돌려주는 분석 에이전트입니다.
4+
5+
---
6+
7+
## 빠른 시작
8+
9+
봇이 서버에 있다면 바로 질문할 수 있습니다.
10+
11+
```
12+
@Lang2SQL 이번 달 매출 상위 고객 10명 알려줘
13+
```
14+
15+
처음 사용한다면 아래 순서대로 세팅합니다.
16+
17+
---
18+
19+
## 1단계: DB 연결
20+
21+
DB가 연결되지 않으면 SQL을 실행할 수 없습니다.
22+
23+
```
24+
/setup
25+
```
26+
27+
DB 종류(PostgreSQL, MySQL, SQLite 등)를 선택하는 안내가 나타납니다. 접속 정보를 입력하면 연결됩니다. DSN을 직접 알고 있다면 `/connect dsn:...`으로 바로 입력할 수도 있습니다.
28+
29+
> 관리자 권한이 필요합니다.
30+
31+
---
32+
33+
## 2단계: 비즈니스 용어 등록
34+
35+
"월매출", "활성고객"처럼 회사 내부 용어를 등록해두면 LLM이 SQL을 훨씬 정확하게 만듭니다.
36+
37+
### 방법 A — 텍스트에서 자동 추출
38+
39+
문서나 정의집 내용을 붙여넣으면 후보를 자동으로 뽑아줍니다.
40+
41+
```
42+
/ingest content:월매출은 SUM(orders.amount)이고, 활성고객은 30일 내 로그인한 users, 환불제외는 status != 'cancelled'
43+
```
44+
45+
후보 목록이 표시되면 확인 후 등록합니다.
46+
47+
```
48+
/confirm_ingest ref:inline:xxxx accept:all layer:channel
49+
```
50+
51+
- `accept`: `all`이면 전체, `1,3`처럼 번호를 지정하면 선택 등록
52+
- `layer`: `channel`(이 채널 전용), `guild`(전사 공통, 관리자 전용), `member`(개인)
53+
54+
### 방법 B — 직접 등록
55+
56+
```
57+
/term_custom
58+
```
59+
60+
안내에 따라 용어명, 정의, 종류(metric/rule/dimension/table)를 입력합니다.
61+
62+
### 방법 C — DB 스캔으로 자동 추출
63+
64+
```
65+
/org_setup org:회사명
66+
```
67+
68+
DB 스키마를 분석해 비즈니스 용어 후보를 자동으로 뽑습니다.
69+
70+
---
71+
72+
## 3단계: 질문하기
73+
74+
용어를 등록한 뒤 자연어로 질문합니다.
75+
76+
```
77+
@Lang2SQL 월매출 기준 이번 달 상위 고객 10명 보여줘
78+
@Lang2SQL 환불제외 기준으로 채널별 주문 수 알려줘
79+
```
80+
81+
봇이 SQL을 생성해 실행하고 결과를 표시합니다.
82+
83+
---
84+
85+
## 용어 우선순위 (Federation)
86+
87+
같은 용어가 여러 레이어에 등록된 경우 **좁은 범위가 우선** 적용됩니다.
88+
89+
```
90+
개인(member) > 채널(channel) > 전사(guild)
91+
```
92+
93+
예를 들어 "활성고객"을 전사에서는 "30일 내 로그인"으로 정의했더라도, 마케팅 채널에서 "14일 내 로그인"으로 따로 등록하면 마케팅 채널 안에서만 그 정의가 우선 적용됩니다. 다른 채널에는 영향이 없습니다.
94+
95+
---
96+
97+
## 전체 커맨드 목록
98+
99+
| 커맨드 | 설명 |
100+
|---|---|
101+
| `/setup` | DB 연결 마법사 (관리자) |
102+
| `/connect dsn:...` | DSN으로 직접 DB 연결 |
103+
| `/ingest content:...` | 텍스트에서 용어 후보 추출 |
104+
| `/ingest ref:파일명` | 서버 파일에서 용어 후보 추출 |
105+
| `/confirm_ingest ref:... accept:... layer:...` | 추출된 후보 검토 후 등록 |
106+
| `/term_custom` | 용어 직접 등록 (위저드) |
107+
| `/term_custom action:show` | 등록된 용어 전체 조회 |
108+
| `/term_custom action:remove term:용어명` | 용어 삭제 |
109+
| `/org_setup org:...` | 전사 조직 등록 + DB 스캔 |
110+
| `/org_setup team:...` | 팀(채널) 등록 |
111+
| `/enrich` | DB 컬럼 메타데이터 자동 보강 |
112+
| `/remember text:...` | 사실 기억 저장 |
113+
| `/audit_me` | 내 활동 이력 조회 |
114+
115+
---
116+
117+
## 자주 묻는 질문
118+
119+
**Q. 질문했는데 엉뚱한 SQL이 나와요.**
120+
등록된 용어가 없거나 DB 메타데이터가 부족한 경우입니다. `/enrich`로 컬럼 설명을 보강하거나 `/term_custom`으로 관련 용어를 등록해보세요.
121+
122+
**Q. "guild 용어는 관리자만 등록 가능" 오류가 나요.**
123+
`layer:guild`는 관리자 권한이 필요합니다. `layer:channel`로 채널 범위로 등록하거나 관리자에게 요청하세요.
124+
125+
**Q. 이전 대화 내용을 기억하나요?**
126+
같은 채널(또는 DM 스레드)에서 이어지는 대화는 맥락이 유지됩니다. `/remember`로 중요한 사실을 명시적으로 저장할 수도 있습니다.

‎src/lang2sql/frontends/discord/bot.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,10 @@ async def audit_me(interaction: discord.Interaction) -> None:
261261
handlers.audit_me(to_identity(_interaction_context(interaction))),
262262
)
263263

264+
@tree.command(name="help", description="Lang2SQL 사용 방법 안내")
265+
async def help(interaction: discord.Interaction) -> None:
266+
await self._run(interaction, handlers.help())
267+
264268
async def _run(self, interaction: discord.Interaction, coro) -> None:
265269
"""Await a handler coroutine and reply with its OutboundMessage."""
266270
await interaction.response.defer(thinking=True)

‎src/lang2sql/frontends/discord/commands.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -264,6 +264,39 @@ async def confirm_ingest(
264264
)
265265
return OutboundMessage(text=result.content)
266266

267+
async def help(self) -> OutboundMessage:
268+
"""사용 방법 안내."""
269+
text = """\
270+
**Lang2SQL 사용 가이드**
271+
272+
**📊 질문하기**
273+
봇을 멘션하거나 채널에서 자연어로 질문하세요.
274+
> @Lang2SQL 이번 달 매출 상위 고객 10명 알려줘
275+
276+
**🗄️ DB 연결** (관리자)
277+
`/setup` — 안내에 따라 DB 접속 정보 입력
278+
`/connect dsn:...` — DSN 직접 입력
279+
280+
**📖 비즈니스 용어 등록**
281+
`/ingest content:월매출은 SUM(orders.amount), 활성고객은 30일 내 로그인`
282+
→ 후보 추출 후 아래 커맨드로 확정
283+
`/confirm_ingest ref:inline:xxxx accept:all layer:channel`
284+
285+
`/term_custom` — 용어 직접 등록 (위저드)
286+
`/term_custom action:show` — 등록된 용어 조회
287+
`/org_setup org:회사명` — DB 스캔으로 용어 자동 추출
288+
289+
**🏷️ 용어 우선순위**
290+
개인(member) > 채널(channel) > 전사(guild)
291+
같은 채널 안에서 등록한 정의가 전사 정의보다 우선 적용됩니다.
292+
293+
**🔧 기타**
294+
`/enrich` — DB 컬럼 설명 자동 보강
295+
`/remember text:...` — 사실 저장
296+
`/audit_me` — 내 활동 이력 조회
297+
`/help` — 이 도움말"""
298+
return OutboundMessage(text=text)
299+
267300

268301
def _fmt_ts(ts: float) -> str:
269302
"""Format an epoch timestamp as a short UTC string for audit listings."""

0 commit comments

Comments
 (0)