Jihostishe Skillbox: Unda Maktaba ya Ujuzi yenye Matoleo kwa Mawakala wa AI

Skillbox ni nini?

Skillbox ni maktaba ya ujuzi yenye leseni ya MIT na inayopangishwa na mtumiaji mwenyewe kwa mawakala wa AI. Inakupa mahali pa kati pa kuunda, kuleta, kuweka matoleo, kusambaza na kukagua vifurushi vya ujuzi vinavyoweza kutumika tena. Programu imejengwa kwa React, Bun, Hono na PostgreSQL.

Usakinishaji mpya huwa tupu kwa makusudi. Hauna ujuzi wa kibinafsi, akaunti za watumiaji, funguo za wateja, vituo vya huduma za nje au vitambulisho vya watoa huduma za AI wanaolipiwa. Skillbox husambaza maudhui ya ujuzi lakini haitekelezi kamwe msimbo wa ujuzi uliopakiwa.

Vipengele muhimu

• Uhariri wenye matoleo: Hariri Markdown na faili zinazounga mkono kwa marekebisho yasiyobadilika, utambuzi wa migongano na urejeshaji.
• Ufikiaji wenye mipaka: Unda wasifu wenye ruhusa za ujuzi au vifurushi, pamoja na ruhusa tofauti za kuunda, kusasisha, kuweka kwenye kumbukumbu na kupendekeza.
• Wateja wanaoweza kufutiwa ruhusa: Toa funguo binafsi za wateja, kagua matumizi na zuia ufikiaji wa baadaye inapohitajika.
• Ufikiaji kupitia MCP na CLI: Tumia MCP ya HTTP moja kwa moja, unganisha kupitia daraja la stdio la Node au Bun, au pakua vifurushi kwa uthibitishaji wa checksum.
• Rasilimali za MCP: Onyesha ujuzi ulioidhinishwa na unaolingana kupitia uorodheshaji na usomaji msingi wa rasilimali za MCP.
• Mapendekezo ya hiari: Tumia Jev pamoja na ufunguo wako mwenyewe wa Vercel AI Gateway au TypeSafe AI.
• Uhamishaji wa data: Leta na toa folda asilia, unda nakala rudufu zilizolindwa na urejeshe data kwa uwazi.
• Usambazaji wa kujipangisha: Endesha kwa Docker Compose, weka Caddy mbele kwa HTTPS kwa hiari, au andaa kifurushi cha Umbrel.

Skillbox imeundwa kama programu ya kujipangisha ya mmiliki mmoja yenye wateja walio na mipaka. Si jukwaa la SaaS la umma lenye wapangaji wengi.

Mahitaji ya awali

Usakinishaji unaopendekezwa unahitaji Docker Engine au Docker Desktop yenye Compose v2, pamoja na Bash kwenye Linux, macOS au WSL. Huhitaji kusakinisha Bun au Node.js kwenye mwenyeji kwa usanidi unaotumia Docker.

Sakinisha na uanzishe Skillbox

1. Clone hazina na uingie kwenye saraka yake:

   git clone https://github.com/kitze/skillbox.git
   cd skillbox

2. Tengeneza faili la mazingira la ndani:

   bash scripts/skillbox.sh setup

   Hii huunda .env yenye vitambulisho vya kipekee vya nasibu, huweka hali yake kuwa 0600, na hukataa kubadilisha faili lililopo.

3. Anzisha huduma za Docker:

   bash scripts/skillbox.sh start

4. Fungua http://127.0.0.1:4791 kwenye kivinjari chako.

5. Soma SKILLBOX_ADMIN_TOKEN kutoka kwenye faili lako la ndani la .env na uitumie kuingia. Skripti ya usanidi haichapishi tokeni hii kwa makusudi.

Hifadhi .env kwa usiri. Tokeni ya mmiliki hudhibiti ufikiaji wa kiutawala na pia huhusika katika kulinda vitambulisho vya miunganisho vilivyohifadhiwa.

Usambazaji wa mbali

Kwa usakinishaji wa mbali, weka SKILLBOX_ORIGIN kuwa chanzo cha HTTPS cha usambazaji na usanidi proksi ya nyuma ya TLS. Usifichue mfano wa uzalishaji kupitia HTTP isiyosimbwa. Tazama maelezo ya usambazaji ya hazina kwa maelezo yanayoungwa mkono ya usambazaji.

Maendeleo ya ndani bila usanidi wa programu unaotegemea Docker pekee

Ikiwa tayari una Bun na hifadhidata ya PostgreSQL 16 au mpya zaidi, sakinisha vitegemezi na uanzishe programu moja kwa moja:

bun install --frozen-lockfile
# Set DATABASE_URL
# Set SKILLBOX_ADMIN_TOKEN to at least 32 random characters
# Set SKILLBOX_ORIGIN=http://127.0.0.1:4791
bun run build
bun run start

Hifadhi thamani zote tatu zinazohitajika katika mazingira yaliyolindwa badala ya kuziwasilisha kwenye udhibiti wa msimbo.

Unda ujuzi na wateja walio na mipaka

Baada ya kuingia, unda ujuzi katika kihariri au leta kifurushi cha ujuzi kilichopo. Marekebisho ya ujuzi hayabadiliki, kwa hiyo wateja wanaweza kupakia au kuleta marekebisho mahususi badala ya kutegemea maudhui yanayobadilika.

Kisha, unda wasifu na upe ufikiaji wa ujuzi au vifurushi vinavyohitajika. Weka ruhusa za kuunda, kusasisha, kuweka kwenye kumbukumbu na kupendekeza kwa kujitegemea kulingana na madhumuni ya mteja. Hatimaye, unda muunganisho wa mteja kwa kutumia wasifu huo.

Funguo za wateja huonyeshwa mara moja tu, na Skillbox huhifadhi heshi zake pekee. Hifadhi kila ufunguo mara moja katika usanidi wa mteja uliolindwa. Tumia ufunguo tofauti kwa kila mteja badala ya kusambaza tokeni ya mmiliki.

Sanidi CLI

CLI husoma usanidi wa JSON ulio na URL ya Skillbox na ufunguo wa mteja. Njia yake chaguomsingi ni ~/.config/skillbox/config.json.

{
  "url": "https://skills.example.com",
  "token": "YOUR_CLIENT_KEY"
}

Weka hali ya faili kuwa 0600. Vigeu vya mazingira SKILLBOX_URL na SKILLBOX_TOKEN hubatilisha thamani kutoka kwenye faili la usanidi. Ikiwa hakuna URL iliyosanidiwa, CLI hulenga localhost kwa usalama badala ya huduma ya mtu mwingine.

Weka cli/skillbox.mjs na cli/package.mjs pamoja. Kisha unaweza kuchunguza na kupata ujuzi ulioidhinishwa:

node cli/skillbox.mjs list
node cli/skillbox.mjs search "database migration"
node cli/skillbox.mjs load my-skill
node cli/skillbox.mjs manifest my-skill
node cli/skillbox.mjs fetch my-skill@REVISION

Operesheni ya fetch huthibitisha njia, heshi za faili, ukubwa, alama za kutekelezeka na checksum ya kifurushi kabla ya kuandika faili kwa njia ya atomiki. Hait execute msimbo wala kusakinisha vitegemezi.

Chapisha ujuzi uliosasishwa

Chapisha folda ya ndani kwa kutoa kitambulisho cha ujuzi na marekebisho unayotarajia kusasisha:

node cli/skillbox.mjs publish ./my-skill my-skill EXPECTED_REVISION

Marekebisho yanayotarajiwa yanaunga mkono ugunduzi wa migongano. Uchapishaji pia unategemea ruhusa alizopewa wasifu wa mteja.

Upatanifu wa ukaguzi

Mmiliki anaweza kuendesha ukaguzi wa upatanifu usiobadilisha data:

node cli/skillbox.mjs audit

Amri hii hutoka kwa hali 1 inapopata vifurushi visivyopatana. Inakuandaa kutathmini upatanifu wa MCP Skills bila kuandika upya vifurushi vilivyopo.

Unganisha wakala wa AI kupitia MCP

Sakinisha bootstrap/SKILL.md kama uanzishaji wa skills-library wa wakala. Wateja wanaounga mkono HTTP MCP wanaweza kuunganisha kwenye mwisho wa /mcp wa mfano wako na kutuma ufunguo wa mteja kama tokeni ya bearer:

Authorization: Bearer YOUR_CLIENT_KEY

Kwa mteja wa MCP anayehitaji stdio, sanidi daraja lililojumuishwa:

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": [
        "/absolute/path/to/skillbox/cli/skillbox.mjs",
        "mcp"
      ],
      "env": {
        "SKILLBOX_URL": "https://skills.example.com",
        "SKILLBOX_CONFIG": "/absolute/path/to/protected-client-config.json"
      }
    }
  }
}

Zana za msingi za MCP zinajumuisha search_skills, recommend_skills, load_skill, read_skill_file, na report_skill_use. Zana za kuandika na kupendekeza zinaonyeshwa tu wakati wasifu wa mteja unatoa ruhusa zinazohusika.

Skillbox pia hutoa stadi zinazopatana na zilizoidhinishwa kupitia MCP ya msingi resources/list na resources/read. Faili za mfumo jozi na kubwa zinazotumika zinaweza kufikiwa kama rasilimali, lakini kusoma rasilimali hakuwashi wala kutekeleza stadi.

Usaidizi kamili wa io.modelcontextprotocol/skills bado hautangazwi. Utekelezaji wa sasa hutoa vipengele vya utayari kupitia itifaki ya msingi ya MCP, huku ugunduzi na maafikiano asilia bado yakitegemea SDK na uboreshaji wa itifaki.

Tumia utafutaji na mapendekezo kwa usahihi

Mwanzoni mwa kazi, mawakala bado wanapaswa kuita search_skills ili kuorodhesha stadi zilizoidhinishwa zinazohusika. Mapendekezo huongezea utafutaji na hayauchukui nafasi yake. Kabla ya kutumia stadi iliyochaguliwa, ipakie kwa kutumia marekebisho yasiyobadilika yaliyorejeshwa na Skillbox.

Bila mtoa mapendekezo wa nje, unaweza kutafuta kutoka CLI:

node cli/skillbox.mjs search "database migration"

Kuomba mapendekezo yanayozingatia kazi:

node cli/skillbox.mjs recommend "Fix choppy scrolling in an Expo app"

Operesheni sawa ya MCP ni recommend_skills({task, limit?, offset?}). Wateja wa HTTP wanaweza kutuma mwili uleule wa JSON uliothibitishwa kwa POST /api/skill-recommendations.

Sanidi mapendekezo ya hiari ya Jev

1. Fungua Settings → Jev recommendations.

2. Chagua Vercel AI Gateway, ambayo ndiyo chaguo-msingi, au TypeSafe AI.

3. Weka na uhifadhi ufunguo wako wa API kwa mtoa huduma aliyechaguliwa.

Funguo za watoa huduma huhifadhiwa kando. Kuchagua TypeSafe hakutumi ufunguo wa Gateway uliohifadhiwa kwa TypeSafe, na kubadilisha watoa huduma huhifadhi ufunguo uliokuwa umehifadhiwa awali. Kuondoa ufunguo wa mtoa huduma aliyechaguliwa huzima simu za miundo kwa mtoa huduma huyo.

Ufunguo husimbwa kwa AES-256-GCM katika PostgreSQL kwa kutumia nyenzo ya ufunguo inayotokana na SKILLBOX_ADMIN_TOKEN. Haurejeshwi na API ya mipangilio wala kujumuishwa katika vifurushi vya kivinjari. Kubadilisha tokeni ya mmiliki bila kufuata mchakato uliowekwa wa mzunguko hufanya vitambulisho vilivyohifadhiwa vya miunganisho visitasomeke.

Kuhifadhi ufunguo hakuthibitishi ufikiaji wa mtoa huduma wala hakununui salio. Jev hutuma maandishi ya kazi na maelezo ya stadi zilizoidhinishwa na zinazotumika kwa mtoa huduma aliyechaguliwa, kwa hivyo masharti ya utozaji na utunzaji wa data ya mtoa huduma huyo yanatumika.

Elewa matokeo ya mapendekezo na njia mbadala

Jev hutathmini katalogi nzima ya majani iliyoidhinishwa, iliyowezeshwa na isiyohifadhiwa, hadi majani 200 au herufi 120,000 zilizofanywa mfululizo. Katalogi kubwa hurudi kwenye njia mbadala moja kwa moja badala ya kupanga sehemu isiyotangazwa.

• Umuhimu ni alama isiyokalibishwa kutoka 0 hadi 4, si uwezekano.
• Matokeo yenye alama ya angalau 3 hurejeshwa kwa mpangilio wa alama unaoshuka, kisha kwa ID.
• noMatch=true inamaanisha hakuna mgombea aliyetathminiwa aliyefikia kizingiti.
• Ufunguo unaokosekana, hitilafu ya mtoa huduma, jibu lisilo sahihi, kikomo cha maombi, kikomo cha uwezo, au muda wa mwisho wa sekunde nane huanzisha njia mbadala ya utafutaji wa PostgreSQL.
• Matokeo ya njia mbadala hutumia method=search, relevance=null, na fallbackReason.

Akiba ya ndani ya mchakato huhifadhi hadi maingizo 128 kwa dakika tano. Skillbox huruhusu tathmini mbili kwa wakati mmoja na maombi kumi yasiyohifadhiwa kwenye akiba kwa kila eneo kwa dakika, bila majaribio ya kiotomatiki. Ruzuku za ruhusa, hali ya mzunguko wa maisha na marekebisho hukaguliwa kabla na baada ya simu za modeli, ikijumuisha mipigo ya akiba.

Ingiza, hamisha na hifadhi nakala ya data

Bun ikipatikana, ingiza folda ya stadi kwa:

bun scripts/import.ts /path/to/skills

Uagizaji huhifadhi baiti za faili na frontmatter isiyojulikana, huruka viungo vya mfano na vizalia vya wakati wa utekelezaji, na kuweka karantini ruwaza za siri zinazotambulika. Ugunduzi huu ni wa kimakadirio, kwa hivyo si mbadala wa ukaguzi kamili wa siri. Usiweke kamwe nywila au tokeni katika vifurushi vya stadi.

Hamisha maudhui ya stadi kwenye eneo tupu:

SKILLBOX_EXPORT_DIR=/path/to/empty-export bun scripts/export.ts

Hifadhidata ya PostgreSQL inaendelea kuwa chanzo cha ukweli. Kuhariri folda iliyohamishwa hakubadilishi hifadhidata hadi maudhui yachapishwe tena.

Unda nakala rudufu iliyolindwa kwa:

bash scripts/backup.sh

Uhamishaji na nakala rudufu zinaweza kuwa na maudhui ya faragha ya skill. Ziweke tofauti na msimbo wa programu unaoonekana hadharani. Skripti ya hiari ya uhamishaji kwenda GitHub inahitaji checkout maalum ya uhamishaji wa faragha iliyosanidiwa wazi, na haiwezeshwi kiotomatiki.

Vidokezo vya kina vya uendeshaji

Tumia ufunguo mmoja wa mteja kwa kila muunganisho

Ufunguo tofauti hufanya ubatilishaji na ripoti za matumizi kuwa na manufaa zaidi. Kubatilisha ufunguo huzuia maombi ya baadaye, lakini hakuwezi kuondoa faili ambazo mteja tayari amepakua.

Pendelea profaili zenye upeo finyu

Mpe kila wakala skills na vitendo anavyohitaji pekee. Vifurushi hupanuka kuwa skills za sasa za mwisho zisizojirudia, ilhali marejeo pekee hayatoi ruhusa ya ufikiaji.

Linda tokeni ya mmiliki na nakala rudufu

Tokeni ya mmiliki hutoa ufikiaji wa kiutawala na hutengeneza nyenzo za usimbaji kwa vidhibiti vilivyohifadhiwa vya miunganisho. Ilinde pamoja na hifadhidata na nakala rudufu za usanidi, na fuata utaratibu uliowekwa wa kuibadilisha kabla ya kuibadilisha.

Chukulia skills kama maudhui, si programu zinazoaminika

Skillbox huthibitisha na kusambaza faili za vifurushi bila kuzitekeleza. Endelea kukagua maagizo na msimbo uliopakuliwa kabla ya kuutumia katika mtiririko wa kazi wa wakala.

Tumia mapendekezo ya ulinganishaji kwa tahadhari

Waendelezaji wanaweza kuendesha ulinganishaji wa hiari unaotozwa kwa kutumia ufunguo wao wenyewe wa mtoa huduma:

bun scripts/benchmark-recommendations.ts --live --provider vercel
bun scripts/benchmark-recommendations.ts --live --provider typesafe

Tumia AI_GATEWAY_API_KEY kwa Vercel au TYPESAFE_API_KEY au JEV_KEY kwa TypeSafe. Skripti hii haisanidi programu wala kuhifadhi vidhibiti. Sampuli yake ya sintetiki si dhamana ya muda wa kusubiri wa uzalishaji wala urekebishaji wa uwezekano.

Thibitisha uwekaji au mchango

Endesha ukaguzi wa aina na seti ya majaribio iliyotengwa kabla ya kuweka mabadiliko:

bun run typecheck
bash scripts/test-isolated.sh

Seti ya majaribio iliyotengwa huunda na kuondoa mfano wake wa PostgreSQL wa Docker Compose bila kuchapisha milango ya hifadhidata. Inashughulikia uidhinishaji, marekebisho, tabia ya API na MCP, CLI, mipangilio iliyosimbwa, na mapendekezo. Usielekeze kamwe majaribio ya hifadhidata kwenye uzalishaji.

Hitimisho

Skillbox hutoa mtiririko wa kazi unaodhibitiwa na unaojihifadhi mwenyewe wa kusimamia skills za AI-agent zinazoweza kutumika tena. Anza na usanidi wa Docker, unda skills zenye matoleo, gawa profaili zenye upeo finyu, na uunganishe kila wakala kwa ufunguo wake wa mteja. Kisha unaweza kuongeza ufikiaji wa MCP, mapendekezo ya hiari ya Jev, mtiririko wa kazi wa kubebeka, na nakala rudufu huku ukibaki na umiliki wa katalogi na vidhibiti vyako.