Ниет құралдары
MCP шлюзі агентке жалпы CRUD емес, ниетке бағытталған 21 құрал ұсынады — олардың әрқайсысы кестедегі операцияны емес, ниетті білдіреді («жазба құру», «контекстті еске түсіру», «жобаның атын өзгерту»). Мұндай жиынтық шектеулерді өз құрылымымен қояды: агент кеңістікті де, жазбаның класын да таңдамайды — оларды құралдың өзі белгілейді, ал токен рұқсаттары қандай құралдар жалпы көрінетінін шешеді.
Агент tools/list ішінде көретін атаулар мен сипаттамалар статикалық — оларға жазбалардың мазмұны ешқашан араласпайды (tool-poisoning-тен қорғаныс).
Токен рұқсаттары — көріну шегі
read-токен тек оқу құралдарын көреді; жазу құралдары tools/list ішінде мүлдем пайда болмайды. Оның үстіне әр шақыру нақты кеңістікке қол жеткізуді бөлек тексереді. Сондықтан төмендегі кестелер — мүмкін болатын ең толық жиынтық; шын мәнінде не көретініңіз токеніңізге байланысты.
Bootstrap
Сессия басындағы құралдар: мен кіммін, маған не қолжетімді, не өзгерді.
| Құрал | Мақсаты |
|---|---|
start_session | Жаңа сессияда бірінші шақырылады. Бір сұрауда: пайдаланушы профилі (әрқашан жүктеледі), қолжетімді жобалар, ал project көрсетілсе — жобаның ықшам индексі (жазба саны + жоғарғы деңгейдегі қалталар), өткен визиттен бергі өзгерістердің дельтасы және knownValues (қолданыстағы категориялар мен тегтердің сөздігі). Идемпотентті; шақыру міндетті емес — тек контекст азырақ болады. |
whoami | Мен кіммін (principal-id), шегім қандай (read/write), қай жобаларда мүшемін және қозғалтқыштың capabilities жиынтығы (vector/trash/revisions) — соқыр күйде байқап көрмеу үшін. |
get_my_projects | Дайын хэндлдері бар қолжетімді жобалардың жалпақ тізімі — project аргументіне арналған. Хэндл әдетте space/slug түрінде болады, бірақ кеңістіктің түбірлік жобасында бір ғана сегментке жиырылады, сондықтан оны ережемен шығармай, жауаптан сол қалпында алады. Жеке домен тізімге кірмейді (ол токеннен айқын). |
start_session → (жоба керек пе?) get_my_projects → құрылымды шолу: list_notes/recent_activity → жазар алдында search/recall → create_note/remember_*/edit_note/link.
Бұл рет — ұсыныс қана, механизм емес: қай құралды шақыруды модель шешеді. Ол өздігінен сақталуы үшін ретті агенттің тұрақты нұсқауына бекітіңіз — Агент ережелері.
Discover — навигация
| Құрал | Мақсаты |
|---|---|
list_notes | Білім қорының ls-і: қалтаның тікелей жазбалары мен ішкі қалталары (детерминистік, беттеуге келеді). project кеңістікті таңдайды, path — қалта (жауаптан сол қалпында алынады), tag сүзеді. Агенттің жадын емес, көрінетін жазбаларды тізеді. |
recent_activity | Ең соңғы өзгертілген жазбалар («жақында нені қозғады, ревью керек»). Әр жазба бойынша: кім (адам/агент), қалай, қайда, қашан. Бұл start_session-дегі дельта емес. |
Read — оқу және recall
| Құрал | Мақсаты |
|---|---|
search | Гибридті іздеу (семантика + лексика, RRF арқылы); вектор қолжетімсіз болғанда іздеу толық мәтін (FTS) бойынша жұмысын жалғастырады — қатесіз. Агенттің өз жадын да қамтиды: «жазар алдында іздеу» ондағы қосарлануларды да жояды. Толық жазбаларды емес, score мен path қоса берілген, рейтингі бойынша реттелген сниппеттерді қайтарады. |
get_note | Ref бойынша (note-id немесе wiki-ref) толық жазба: мазмұны, frontmatter, path, class, versionToken (қауіпсіз жазу үшін) және шығу тегі. detailed режимінде — қосымша outline (тақырыптар) мен links (граф қырлары). |
recall | Тақырып төңірегіндегі контекст-бандлды токен-бюджет шегінде жинау: релевантты жазбалар және олардың граф-көршілері. search-тен бай: білімнен де, жеке жадтан да тартады. budgetTokens көлемін шектейді. |
search пен recall айырмашылығы туралы толығырақ — Агент жады.
Write — жазу және ниет
| Құрал | Мақсаты |
|---|---|
create_note | Жобада жаңа ортақ (KB) жазба құру, класы — user-doc. Жазбаның тақырыбын body (Markdown) ішіндегі бастапқы # H1 белгілейді; path? — баратын қалта; type?/tags? — міндетті емес оверрайд-параметрлер; links? типтелген қырларды бірден қосады. Класты да, кеңістікті де агент таңдамайды. |
remember_about_user | Пайдаланушы туралы ұзақ өмір сүретін фактіні (қалаулары, контексті) оның жеке жадына жазу. category астына observation үстеп жазылады. |
remember_about_project | Жоба туралы фактіні агенттің жеке жадына жазу (класы agent-memory, remember_about_user-ге симметриялы). Ортақ білім емес — ол үшін create_note бар. |
edit_note | Жазбаны позиция бойынша емес, сөз бойынша инкрементті түзету: append/prepend, replace (дене түгелдей), replaceSection (тақырып бойынша), findReplace (бірегей сниппет; бос content = жою). versionToken талап етеді (CAS). |
delete_note | Жазбаны себетке жылжыту — агенттің жалғыз деструктивті әрекеті әрі құрылымы бойынша қайтарымды. Қалпына келтіруді де, себетті тазартуды да тек адам жасайды. |
link | from→нысана түріндегі типтелген байланыс. Нысана — to (note-id) немесе toTitle (әлі құрылмаған жазбаның тақырыбы бойынша forward-ref). Екі жазба да бір кеңістікте болуға тиіс. |
edit_note жаңа ғана алынған get_note-тың versionToken-ін талап етеді. Қатарлас түзету versionConflict қатесін қайтарады — құрал бөгде өзгерістерді үнсіз баспайды, агент қайта оқып, әрекетті қайталайды.
Reorganize — қайта ұйымдастыру
Қайта ұйымдастыру құралдарының грамматикасы — verb_entity. Жазба id-і арқылы, қалта path-ы арқылы, жоба хэндлі арқылы адрестеледі.
| Құрал | Мақсаты |
|---|---|
move_note | Жазбаны атын сақтай отырып басқа қалтаға жылжыту. id мен URL тұрақты қалады, кіріс сілтемелер үзілмейді. |
rename_note | Жазбаның тақырыбын өзгерту. Link-safe: ескі тақырып alias-тарихқа өтеді, кіріс [[сілтемелер]] резолвтеле береді. |
move_folder | Қалтаны ішіндегісімен түгел басқа аталық қалтаға жылжыту. Ішіндегі барлық жазбалардың id-і тұрақты. |
rename_folder | Қалтаның атын орнында өзгерту. Егер қалта — жоба болса, оның хэндлі өзгермейді (хэндл үшін — rename_project). |
rename_project | Жобаның хэндлін және/немесе адам оқитын атауын өзгерту. Link-safe: ескі хэндл alias-қа өтеді. |
Scale — миграция ауқымы
| Құрал | Мақсаты |
|---|---|
create_notes | Бір жобада бір шақырумен бірнеше KB-жазба құру. Best-effort, транзакциялық емес: results[] әрқайсысын ok/error деп белгілейді — тек сәтсіз болғандарын қайталау керек. |
link_many | Бір шақырумен бірнеше типтелген байланыс құру. Best-effort, идемпотентті. |
Әрі қарай
- Агент жады — remember мен recall егжей-тегжейлі.
- Контекст жиынтықтары мен бекітулер —
start_session-ге не түседі. - Қауіпсіздік және көріну — бұл жиынтық «lethal trifecta»-ны қалай үзеді.