Chaim
ebfe7f6a1d
תוספתי בלבד, אפס שבירת-תאימות. שני invariants מחוזה-כלי-ה-MCP (X9): GAP-44 (INV-TOOL4, סימטריית extract/get): נוסף get_appraiser_facts — ה-get המקביל ל-extract_appraiser_facts. קורא list_appraiser_facts + detect_appraiser_conflicts מה-DB ללא חילוץ-LLM יקר ולא-דטרמיניסטי. מחזיר count=0 (לא שגיאה) אם טרם חולץ. GAP-53 (INV-TOOL5, limit-caps / OWASP API4:2023): נוסף _clamp_limit (תקרה 200, non-positive→max) על ~13 כלי list/search ב-server.py (case_list, search_*, precedent_library_list, halachot_pending, missing_precedent_list, list_*_citations…). list_chair_feedback קיבל param limit חדש (server→workflow→db עם LIMIT) — היה ללא תקרה כלל. לא הוסף get_appraiser_facts ל-frontmatter של סוכנים (INV-AG3 "לא עודף" — ההוראות עוד לא מפנות אליו; חיווט = follow-up). נותר ב-FU-14: GAP-45/48/49/50/51/52. עודכנו docs/spec/X9 (INV-TOOL4/5) ו-gap-audit (סטטוס פרוסה 1). אומת: py_compile על 4 קבצי הקוד. אימות runtime (restart MCP server) נדחה עד שהחילוץ הפעיל של היו"ר יסתיים. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
9.9 KiB
X9 — חוזה כלי-ה-MCP (Agent MCP Tool Contract)
קובץ-תחום זה כפוף ל-חוקת המערכת והוא ה-deep-dive על משטח כלי-ה-MCP — 71 הכלים ש-mcp-server חושף לסוכני Paperclip (CEO/analyst/researcher/writer/qa/…). עד כה הספ תיאר מה הסוכנים עושים (X4-agents.md) אך לא חוזה-הכלים עצמו: envelope, שמות, idempotency, סימטריית extract/get, ומפת-הרשאות. הקובץ מגדיר את הכללים; הממצאים → gap-audit.md.
מודלי-סמכות מעורבים. TOOL1/TOOL2/TOOL3/TOOL5 הם הנדסיים (עיצוב-API/כלים — ≥3 מקורות). TOOL4 ו-TOOL6 הם פרויקטלי-תפעוליים, הנקשרים ל-G2 ו-G10.
1. אינוונטר (71 כלים, server.py)
| דומיין | כלים (מייצג) |
|---|---|
| ניהול-תיק | case_create/list/get/update/delete, case_get_final_text |
| מסמכים | document_upload, document_upload_training, document_list/get_text/update, extract_references |
| טענות+טיעונים | extract_claims, get_claims, aggregate_claims_to_arguments, get_legal_arguments |
| חיפוש (6 — חופפים) | search_decisions, search_case_documents, find_similar_cases, search_internal_decisions, search_precedent_library, precedent_search_library |
| כתיבת-בלוק (6 — חופפים) | draft_section, get_block_context, write_block, write_all_blocks, write_interim_draft, save_block_content |
| ייצוא/QA | export_docx, export_interim_draft, validate_decision, revise_draft, list_bookmarks, apply_user_edit |
| פסיקה (3 תת-מערכות) | case-attached (precedent_attach/list/remove/search_library) · library (precedent_library_) · internal (internal_decision_) |
| הלכות | halacha_review, halachot_pending, precedent_extract_halachot/metadata, precedent_process_pending |
| ציטוטים | extract_internal_citations, list_internal_citations, list_incoming_citations |
| missing-precedents | missing_precedent_create/list/close |
| workflow/feedback | workflow_status, get_metrics, processing_status, set_outcome, brainstorm_directions, approve_direction, ingest_final_version, record/list_chair_feedback |
| appraiser/style | extract_appraiser_facts, style_corpus_enrich, style_corpus_pending_enrichment |
2. Invariants של התחום
INV-TOOL1: envelope-תשובה עקבי לכל הכלים
כלל: כל כלי מחזיר מבנה אחיד (למשל {status, data, message}) — לא string-לפעמים-JSON-לפעמים-{error}.
שגיאה מובחנת ממצב-ריק ממצב-הצלחה באופן עקבי. מופע של G2;
מקביל ל-X6 INV-UI3. הנדסי.
מקורות: Anthropic — MCP / tool result conventions (https://modelcontextprotocol.io/) ·
JSON-RPC 2.0 (result/error envelope) (https://www.jsonrpc.org/specification) · RFC 9457 (Problem Details) | סטטוס: verified
אכיפה: wrapper-תשובה משותף בכל הכלים. כיום אין — מעורב.
הפרה ידועה: search_* מחזיר "לא נמצאו תוצאות." או JSON; חלק {error}, חלק raise (gap-audit GAP-48).
INV-TOOL2: שמות עקביים + חיפוש לפי-קורפוס
כלל: שמות-הכלים עוקבים אחר convention אחיד, ושם משקף התנהגות. כלי-חיפוש מובחנים לפי הקורפוס
(style / internal / external / case-attached), לא ב-6 שמות חופפים; כלי-כתיבת-בלוק אינם חופפים (context מול write).
מופע של G2 ("סימטריה", §6). הנדסי.
מקורות: Anthropic — Writing effective tools / clear names (https://www.anthropic.com/engineering/writing-tools-for-agents) ·
Google API Design Guide (naming) (https://cloud.google.com/apis/design/naming_convention) ·
Zalando RESTful API Guidelines | סטטוס: verified
אכיפה: איחוד/מיזוג כלי-חיפוש + כלי-בלוק; rename של שמות-מטעים. כיום אין.
הפרה ידועה: precedent_search_library מחפש למעשה quotes מצורפים-לתיק (שם מטעה); 6 כלי-חיפוש + 6 כלי-בלוק חופפים (gap-audit GAP-49/50).
INV-TOOL3: idempotency בכל כלי-מוטציה
כלל: כלי שמשנה-מצב הוא idempotent על מפתח דטרמיניסטי — קריאה חוזרת אינה יוצרת כפילות. מופע של
G3. הנדסי.
מקורות: Stripe — Idempotent requests (https://docs.stripe.com/api/idempotent_requests) ·
Kleppmann DDIA (idempotence) · IETF — Idempotency-Key header draft (https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) | סטטוס: verified
אכיפה: upsert/ON CONFLICT בכלי-מוטציה. כיום חלקי — missing_precedent_create/precedent_link_cases/extract_internal_citations idempotent; case_create/document_upload/precedent_attach לא.
הפרה ידועה: gap-audit GAP-52.
INV-TOOL4: סימטריית extract/get + persistence
כלל: לכל כלי-חילוץ שכותב ל-DB יש כלי-קריאה (get) מקביל, והפלט נשמר durably (לא מוחזר-ונאבד).
מופע של G2 (מקור-אמת נגיש). פרויקטלי-תפעולי.
מקור-סמכות: דפוס extract_claims↔get_claims, aggregate↔get_legal_arguments ב-server.py.
אכיפה: לכל extract — get מקביל. GAP-44 ✅ נסגר (2026-06-06): נוסף get_appraiser_facts (קורא list_appraiser_facts+detect_appraiser_conflicts, ללא חילוץ-מחדש). נותר: תור-חילוץ סמוי (GAP-45).
הפרה ידועה: תור-חילוץ סמוי (gap-audit GAP-45).
INV-TOOL5: limit-caps על כל כלי-רשימה/חיפוש
כלל: לכל כלי שמחזיר רשימה יש תקרת-limit נאכפת (הגנה מפני עומס/DoS); pagination היכן שרלוונטי. הנדסי.
מקורות: OWASP API Security Top 10 — API4:2023 Unrestricted Resource Consumption (https://owasp.org/API-Security/editions/2023/en/0xa4-unrestricted-resource-consumption/) ·
Microsoft REST API Guidelines (pagination) · Stripe API (limit caps) | סטטוס: verified
אכיפה: clamp ל-max בכל כלי-רשימה. GAP-53 ✅ נסגר (2026-06-06): _clamp_limit (תקרה 200) על ~13 כלי list/search ב-server.py; list_chair_feedback קיבל param limit (server→workflow→db עם LIMIT).
הפרה ידועה: —
INV-TOOL6: שלמות-הרשאות — כל כלי שהוראות-הסוכן דורשות מוענק
כלל: מפת-ההרשאות (אילו כלים מוענקים לכל סוכן) תואמת את מה שהוראות-הסוכן מצריכות — לא חסר ולא עודף.
מופע של G10 (שערים מוגדרים); מפורט ב-X4-agents.md. פרויקטלי-תפעולי.
מקור-סמכות: frontmatter tools: ב-.claude/agents/ מול הוראות-הסוכן.
אכיפה: בדיקת-עקביות tools↔instructions (יעד FU-13).
הפרה ידועה: legal-analyst חסר aggregate_claims_to_arguments/extract_references/extract_internal_citations; researcher חסר טריגרי-חילוץ (gap-audit GAP-46).
3. הערות-עיצוב
- set_outcome — אי-התאמת enum:
block_writer.py:442משתמש ב-rejected/accepted/partial, בעודlessons.py:11מגדירrejection/partial_acceptance/full_acceptance/betterment_levy. שתי אוצרות-מילים → SSoT יחיד נדרש (gap-audit GAP-51; תואם X6 INV-UI1 על enum-סטטוס). - 3 מסלולי-קליטת-פסיקה (library / internal / training) עם ולידציה א-סימטרית — נקשר ל-01-ingest.md / GAP-01/05.
הממצאים המלאים + התיקון → FU-14 (gap-audit.md).
4. הפניות-אחיות
- X4-agents.md — מפת-הסוכנים + ההרשאות (INV-TOOL6).
- X8-field-provenance.md — כלי-החילוץ ומה שהם שומרים.
- X6-ui-api-contract.md — envelope מקביל בצד-ה-API.
- 01-ingest.md, 03-retrieval.md — מסלולי-קליטה/חיפוש שהכלים עוטפים.
- 00-constitution.md — G2, G3, G10.
- mcp-server/src/legal_mcp/server.py, tools/.