docs(hermes): PR-Hermes-Skill-Polish-1 closure 보고서
3 SKILL.md (docsrv_memo/search/ask) frontmatter 표준화 — prerequisites.env → required_environment_variables (agentskills.io 표준). skill_view 시 자동 register_env_passthrough 발화 + config-level terminal.env_passthrough 와 이중 안전망. docsrv_ask 본문: Multi-Turn 차단 정책 + Response Format verbatim 강화. 검증: - Layer 1 fixture 회귀 0 (5/5 raw_leak, 3/3 finish_reason 동일) - E2E: pre-polish 4 turn → post-polish 3 turn (25% 감소, but 목표 1 turn 도달 X) — prompt-only enforcement 한계 명확화 결정: - Skill-Curl-Refine-1 (frontmatter) = SHIPPED - Multi-Turn-Refinement-1 (prompt) = PARTIAL — plugin-level escalate - 신규 트랙 PR-Hermes-MultiTurn-Hard-Enforcement-1 (P2) 박힘 (Answer-Policy-1 과 통합 검토)
This commit is contained in:
Hyungi Ahn
@@ -0,0 +1,137 @@
|
||||
# PR-Hermes-Skill-Polish-1 Closure Report
|
||||
|
||||
**Date**: 2026-05-17
|
||||
**선행 PR**: PR-Hermes-Docsrv-Search-1 + ToolCall-Adapter-1 + Sandbox-Env-Propagation-1
|
||||
**범위**: 3 SKILL.md frontmatter 표준화 + docsrv_ask 본문 refinement 차단 강화
|
||||
**파일**: `~/.hermes/skills/personal/{docsrv_memo,docsrv_search,docsrv_ask}/SKILL.md`
|
||||
|
||||
## Summary
|
||||
|
||||
PR-Hermes-Sandbox-Env-Propagation-1 closure 시 발견된 2건 후속:
|
||||
1. **frontmatter legacy `prerequisites.env`** — 표준 `required_environment_variables` (agentskills.io schema) 로 마이그레이션. `skill_view` tool_call 시 자동 `register_env_passthrough` 발화 ⇒ config-level `terminal.env_passthrough` 와 이중 안전망.
|
||||
2. **Hermes chat multi-turn refinement 루프** — Gemma 가 첫 docsrv_ask 결과 만족 못 하면 query 변형 후 재호출. SKILL.md 본문에 "1회 호출 후 verbatim, refinement 재호출 금지" 정책 강조.
|
||||
|
||||
## Skill-Curl-Refine-1 변경 (frontmatter 표준화)
|
||||
|
||||
3 SKILL 모두 동일 패턴:
|
||||
|
||||
```diff
|
||||
prerequisites:
|
||||
commands: [curl, jq]
|
||||
- env: [HERMES_DOCSRV_TOKEN]
|
||||
+required_environment_variables:
|
||||
+ - name: HERMES_DOCSRV_TOKEN
|
||||
+ prompt: Document Server JWT (voice-memo-bot 365d access token)
|
||||
+ help: "voice-memo-bot user (id=4) 가 발급한 long-lived JWT. LaunchAgent ai.hermes.gateway 의 EnvironmentVariables 에 이미 주입됨."
|
||||
```
|
||||
|
||||
**`prerequisites.commands`** 는 유지 (advisory only, Hermes 의 `_collect_prerequisite_values` 가 legacy_env_vars 로 그대로 변환).
|
||||
|
||||
**효과**:
|
||||
- `skill_view` tool_call 호출 시 자동 `register_env_passthrough(["HERMES_DOCSRV_TOKEN"])` (`tools/skills_tool.py:1336`)
|
||||
- agentskills.io 표준 (Shopify / Notion skill 등 동일 패턴) — Hermes 공식 marketplace 호환
|
||||
|
||||
## Multi-Turn-Refinement-1 변경 (본문 강화, docsrv_ask)
|
||||
|
||||
신규 섹션 추가 (`docsrv_ask/SKILL.md`):
|
||||
|
||||
```markdown
|
||||
## Multi-Turn / Refinement 차단 정책
|
||||
|
||||
- 같은 query 또는 의미적 동일 query 를 본 skill 로 재호출 금지. 한 사용자 turn 당 docsrv_ask 1회만.
|
||||
- confidence=medium 또는 completeness=partial 도 만족 — refinement 욕구로 query 변형 후 재호출 X.
|
||||
- 사용자가 명시적으로 "더 자세히" / "다른 측면" 요청 시에만 다른 query 로 재호출 (그것도 1회).
|
||||
- 본 정책 위반 시 Mac mini 26B 가 동일 corpus 에 동일 LLM 추론 반복 → 가치 ↓ + 부하 ↑ + Hermes 응답 시간 ↑↑.
|
||||
```
|
||||
|
||||
기존 "Response Format — 재합성 최소화 정책" 도 강화:
|
||||
- "ai_answer 그대로 사용" → "**verbatim** (한 글자도 재작성 X — paraphrase 금지, summarization 금지)"
|
||||
|
||||
docsrv_search 도 동일 1회 호출 정책 1단락 추가.
|
||||
|
||||
## 검증
|
||||
|
||||
### Regression: Layer 1 fixture (Adapter A)
|
||||
|
||||
```
|
||||
memo-search | 1.06s | raw_leak=0 | tool_calls=1(docsrv_ask) | finish=[stop,tool_calls] ✅
|
||||
asme-search | 11.33s| raw_leak=0 | tool_calls=0 | finish=[stop] (Gemma 직접 답변)
|
||||
today-tasks | n/a | raw_leak=0 | tool_calls=0 | finish=[stop] (Gemma 직접 답변)
|
||||
multi-tool | n/a | raw_leak=0 | tool_calls=1(docsrv_ask) | finish=[stop,tool_calls] ✅
|
||||
explicit-call | 0.74s | raw_leak=0 | tool_calls=1(docsrv_ask) | finish=[stop,tool_calls] ✅
|
||||
|
||||
raw_token leak suppressed: 5/5
|
||||
finish_reason override: 3/3 (tool 사용한 case)
|
||||
```
|
||||
|
||||
**SKILL.md polish 가 Adapter A 회귀 0** — pre-polish 와 동일 결과 (1.06s / 11.33s / 0.74s 동일).
|
||||
|
||||
### E2E (Hermes chat — multi-turn 차단 검증)
|
||||
|
||||
`hermes chat -s docsrv_ask -q 'docsrv_ask 으로 내 자료에서 voice memo 관련 자료 찾아줘'`
|
||||
|
||||
**측정 결과 (kill 시점)**:
|
||||
- DS API 호출 횟수: pre-polish 4회 → **post-polish 3회** (1회 감소, but **목표 1회 도달 X**)
|
||||
- Hermes turn count: 3 turn 진행 중 kill (max-turns=4)
|
||||
- 매 turn 마다 같은 `voice memo` exact query 로 docsrv_ask 재호출 (refinement variation 도 없음 — 그냥 동일 query 반복)
|
||||
- DS 응답: 매번 동일 `conf=medium completeness=full refused=False` → 그래도 Gemma 가 만족 못 함
|
||||
|
||||
**해석 — prompt-only enforcement 의 한계**:
|
||||
- SKILL.md 본문에 "1회 호출 후 verbatim 사용, refinement 재호출 금지" 명시했으나 Gemma 4 26B 가 follow 안 함
|
||||
- 원인 후보: (a) 23000+ input tokens 의 페르소나/skills/tools prompt 사이에 SKILL.md instruction 이 묻혀 weight 낮음 (b) Gemma 4 의 agentic loop training 이 "fixed point 후 stop" 보다 "더 정보 fetch" 쪽 bias (c) Hermes agent loop 자체가 verdict=partial 같은 부분 만족 신호 보면 자동 retry
|
||||
- 결론: **prompt-only multi-turn 차단은 약한 enforcement**. 진짜 1회 호출 보장은 plugin-level (Phase 2 Answer-Policy-1) 또는 Hermes agent loop config (max_tool_calls_per_skill) 필요
|
||||
|
||||
**부분 효과는 있음**: pre-polish 4 turn → post-polish 3 turn (25% 감소). SKILL.md 강조가 weight 0 은 아니지만 hard guarantee 못 됨.
|
||||
|
||||
## 결정 사항
|
||||
|
||||
1. **Skill-Curl-Refine-1 (frontmatter 마이그레이션) = SHIPPED**:
|
||||
- Layer 1 fixture 회귀 0 (5/5 raw_leak suppressed, 3/3 finish_reason override 유지)
|
||||
- 3 SKILL 모두 agentskills.io 표준 호환
|
||||
- `terminal.env_passthrough` config-level fix 와 이중 안전망 확보
|
||||
2. **Multi-Turn-Refinement-1 (SKILL.md 본문 정책) = PARTIAL** (정직히 보고):
|
||||
- prompt-only enforcement 가 약함 — Gemma 4 26B 가 SKILL.md 의 "1회 호출 후 verbatim, 재호출 금지" instruction 무시
|
||||
- 효과: 4 turn → 3 turn (25% 감소), but 목표 1 turn 도달 못 함
|
||||
- **결론**: hard guarantee 는 plugin-level enforcement 필요. PR-Hermes-Answer-Policy-1 (Phase 2) 또는 Hermes agent loop config (`max_tool_calls_per_skill: 1`) 별 트랙으로 escalate
|
||||
3. **묶음 closure 보다 분리**: Skill-Curl-Refine-1 만 SHIPPED, Multi-Turn-Refinement-1 은 "prompt-only attempt 실패 기록" 으로 closure + 별 PR (plugin-level) 진입 조건 박힘
|
||||
|
||||
## File changes
|
||||
|
||||
### Mac mini
|
||||
- `~/.hermes/skills/personal/docsrv_ask/SKILL.md` — frontmatter 표준화 + Multi-Turn 차단 섹션 추가 + Response Format verbatim 강화 (v0.1.0 → v0.2.0)
|
||||
- `~/.hermes/skills/personal/docsrv_search/SKILL.md` — frontmatter 표준화 + 1회 호출 정책 1단락 (v0.1.0 → v0.2.0)
|
||||
- `~/.hermes/skills/personal/docsrv_memo/SKILL.md` — frontmatter 표준화 (v0.1.0 그대로, 본문 변경 0)
|
||||
- `*.SKILL.md.pre-polish.20260517` 3개 (7일 안전망)
|
||||
|
||||
### 변경 없음
|
||||
- `~/.hermes/config.yaml` (env_passthrough 와 channel_prompts 그대로)
|
||||
- `~/scripts/mlx-proxy.py` (Adapter A 그대로)
|
||||
- DS code
|
||||
|
||||
## 7일 안전망 (2026-05-24)
|
||||
|
||||
- Mac mini `~/.hermes/skills/personal/docsrv_{memo,search,ask}/SKILL.md.pre-polish.20260517` 3개
|
||||
- 복귀 시: `ssh macmini "for s in docsrv_memo docsrv_search docsrv_ask; do cp ~/.hermes/skills/personal/$s/SKILL.md.pre-polish.20260517 ~/.hermes/skills/personal/$s/SKILL.md; done && launchctl bootout/bootstrap"`
|
||||
|
||||
## 검증 commands (재실행)
|
||||
|
||||
```bash
|
||||
# Layer 1 fixture regression
|
||||
ssh macmini "python3 ~/.hermes/fixtures/pr_adapter_a_fixture.py"
|
||||
|
||||
# Hermes E2E (multi-turn 차단 검증)
|
||||
ssh macmini "HERMES_DOCSRV_TOKEN=... && ~/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main chat -Q -s docsrv_ask -q '<query>'"
|
||||
|
||||
# DS API 호출 횟수 측정 (1회 기대)
|
||||
ssh gpu "cd ~/Documents/code/hyungi_Document_Server && docker compose logs --since=5m fastapi | grep -c 'ask query'"
|
||||
```
|
||||
|
||||
## 후속 트랙
|
||||
|
||||
| 우선 | 트랙 | 비고 |
|
||||
|---|---|---|
|
||||
| **P2 (escalated)** | **PR-Hermes-MultiTurn-Hard-Enforcement-1** | 본 PR 의 Multi-Turn-Refinement-1 prompt-only attempt 실패 → plugin-level 강제. 후보: (a) Hermes agent loop config `max_tool_calls_per_skill: 1` (b) `tools/skills_tool.py` 의 tool dispatcher 에 per-skill 호출 카운터 (c) PR-Hermes-Answer-Policy-1 (Phase 2) 의 일부로 통합 |
|
||||
| **P3** | PR-Hermes-MaxTokens-Followup | 23320 input tokens 대응 — Hermes tools/skills 선택 로딩 mechanism 조사 (별 PR) |
|
||||
| 별 트랙 | PR-Hermes-Answer-Policy-1 (Phase 2) | 출처 라벨 plugin-level 강제. MultiTurn-Hard-Enforcement 와 통합 검토 |
|
||||
| 별 트랙 | PR-Hermes-WebSearch-2B-SearXNG | ddgs 1주 baseline 후 |
|
||||
| 별 트랙 | PR-D (P2 강등) | Adapter A 1주 측정 + 가족 onboarding 시점 재평가 |
|
||||
Reference in New Issue
Block a user