From dffc8b24dd4abb2ac23e77d868dbae05bef2bfd9 Mon Sep 17 00:00:00 2001 From: Hyungi Ahn Date: Sun, 17 May 2026 07:13:53 +0900 Subject: [PATCH] =?UTF-8?q?docs(hermes):=20PR-Hermes-Skill-Polish-1=20clos?= =?UTF-8?q?ure=20=EB=B3=B4=EA=B3=A0=EC=84=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 과 통합 검토) --- reports/pr_hermes_skill_polish_1_closure.md | 137 ++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 reports/pr_hermes_skill_polish_1_closure.md diff --git a/reports/pr_hermes_skill_polish_1_closure.md b/reports/pr_hermes_skill_polish_1_closure.md new file mode 100644 index 0000000..d23110b --- /dev/null +++ b/reports/pr_hermes_skill_polish_1_closure.md @@ -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 ''" + +# 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 시점 재평가 |