Skip to main content
  1. Dokumentasi/

Agent Server

Apa itu PocketHook Agent Server?
#

Pelayan agent mengubah PocketHook menjadi pembantu AI sepenuhnya. Daripada menulis logik respons sendiri, anda menyambungkan LLM (Claude, GPT, Gemini, dll.) yang memproses mesej, memanggil alat, dan mengembalikan respons PocketHook berstruktur — termasuk pencetus Shortcut.

Pelayan berjalan di mesin anda sendiri. Data anda kekal dengan anda.

Ini adalah titik permulaan. Pelayan dihantar dengan set alat teras dan direka untuk diperluas oleh anda. Tambah integrasi anda sendiri — e-mel, kalendar, dokumen, API — dan jadikan milik anda.

Ciri-ciri
#

  • LLM berbilang penyedia — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (tempatan), LM Studio (tempatan)
  • Pengesahan OAuth — GitHub Copilot dan OpenAI Codex melalui device code / browser flow
  • Alat agent — Perintah shell, baca/tulis fail, senarai direktori, carian web, web scraping, pengurusan dev server
  • Pemisahan framework / pengguna — Fail framework (skills/, custom-tools/, config/) adalah baca sahaja. Penyesuaian anda berada di bawah data/user/ (skills, custom tools, instructions, typed prefs). Kemas kini framework dipasang dengan kemas tanpa menulis ganti kerja anda
  • Typed user prefs — Simpan nilai seperti aplikasi peta pilihan atau domain tunnel dalam data/user/prefs.json. Rujuk ia dalam kemahiran sebagai {{prefs.key}} dan pelayan akan menggantikannya semasa dimuatkan
  • Tugas pengaturcaraan dalam satu panggilan — Meta-tool run_code_job mencipta background job jenis prompt (dijalankan oleh LLM yang anda konfigurasikan) dan menghantar pengesahan kepada pengguna dalam satu langkah, menggantikan corak “respond + create-job” yang mudah ralat
  • Alat protokol bertaip — Enam alat respond_* khusus (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), bersama alat tugas bertaip (create_once_job, create_cron_job) dan alat workspace bertaip (create_project, list_projects, delete_project). Skema menolak URL yang tidak sah, sintaks butang, dan kombinasi type/schedule sebelum sampai ke peranti
  • Penulis bertaip untuk penyesuaiancreate_user_skill dan create_custom_tool membina markdown lapisan pengguna dengan frontmatter yang betul, supaya pemuat sentiasa boleh memprosesnya dan agent tidak pernah menulis fail-fail ini secara manual
  • Tugas latar belakang — Tugas sekali atau berulang dengan ungkapan cron atau selang mudah
  • Kemahiran dinamik — Tentukan pintasan dan peraturan tingkah laku sebagai fail .md. Hanya indeks ringkas yang dimuatkan ke dalam prompt; kandungan penuh diambil atas permintaan melalui alat load_skill
  • Kemahiran pengurusan sendiri — Agent boleh mencipta, mengedit, dan memadamkan definisi kemahiran (penulisan sentiasa mendarat pada lapisan pengguna)
  • Memori semantik — Carian berasaskan vektor dengan embedding (Ollama, LM Studio, atau OpenAI). Memori diklasifikasi secara automatik ke dimensi wing/room/hall/status oleh LLM
  • Graf pengetahuan — Stor triple temporal untuk fakta tahan lama dengan pembatalan automatik. Hubungan berbilang nilai wujud bersama; fakta nilai tunggal diganti secara automatik
  • Kaedah PARA dengan cascade akhir projek — Setiap memori ditag dengan status (Project, Area, Resource, Archive). Apabila projek berakhir, satu panggilan complete_project mengarkibkan vektornya, membatalkan setiap triple perancangan yang terikat dengan slug-nya, dan merekodkan penyelesaian — satu panggilan bukan tiga
  • Recall hibrid — Menggabungkan carian kata kunci FTS5 dengan carian semantik vektor menggunakan reciprocal rank fusion
  • Memori jangka panjang — SQLite + carian teks penuh FTS5 sebagai sandaran apabila memori semantik dinyahdayakan
  • Pengurusan dev server dengan tunnel contract — Mula, henti, dan senarai dev server. Apabila tunnel: true diminta, pelayan menguatkuasakannya pre-flight dan post-spawn — pelayan localhost yang tidak dapat dicapai tidak akan dibiarkan berjalan secara senyap
  • Sanitasi URL automatik — Jika agent meninggalkan URL localhost dalam respons, alat respond_* akan menulis semula ia ke URL tunnel yang sepadan supaya telefon anda sentiasa mendapat pautan yang boleh dicapai
  • Alat tersuai — Agent boleh memasang alat CLI dan mendaftarkannya sebagai keupayaan baharu
  • Versi — Versi git automatik untuk fail workspace; sandaran konfigurasi untuk kemahiran dan kebenaran
  • Papan pemuka web — Gambaran langsung tugas latar belakang, boleh disuai setiap pengguna. /dashboard dan /api/jobs tidak disahkan secara reka bentuk — hadkan akses pada lapisan rangkaian (Tailscale ACL, firewall, reverse proxy dengan basic auth) atau tetapkan DASHBOARD=false jika anda tidak memerlukannya
  • Terowong HTTPS — Sokongan terbina dalam untuk Tailscale, ngrok, dan Cloudflare Tunnel
  • Perkhidmatan sistem — Pasang sebagai perkhidmatan berterusan di macOS, Linux, atau Windows
  • Had kadar — Had permintaan per token dengan ambang boleh dikonfigurasi

Keperluan
#

Mula Pantas
#

git clone https://github.com/pockethook-app/pockethook-agent-server.git
cd pockethook-agent-server
bun install

# Persediaan interaktif — pilih penyedia, model, token auth, port
bun run setup

# Mula pelayan + terowong HTTPS
bun run dev:tunnel

Wizard persediaan akan membimbing anda melalui pemilihan penyedia LLM, konfigurasi pengesahan, dan persediaan kebenaran alat.

Setelah berjalan, salin URL yang dipaparkan ke dalam Tetapan PocketHook:

Tetapan PocketHookURL
Server URLhttps://your-host
Health Check URLhttps://your-host/health
Polling URLhttps://your-host/jobs

Cara Ia Berfungsi
#

  1. Anda menghantar mesej dalam PocketHook
  2. Pelayan memajukannya ke LLM pilihan anda dengan sejarah perbualan, memori yang dipanggil semula, dan alat yang tersedia
  3. LLM memproses mesej — ia boleh menjalankan perintah shell, membaca/menulis fail, mencari web, menjadualkan tugas latar belakang, mengingat fakta, atau memulakan dev server
  4. Respons dikembalikan dalam format PocketHook (msg + shortcut + data + url)
  5. PocketHook memaparkan mesej dan menjalankan sebarang Shortcuts pada peranti anda

Penyedia LLM yang Disokong
#

PenyediaAuthModel Lalai
AnthropicAPI keyclaude-sonnet-4-20250514
OpenAIAPI keygpt-4.1-mini
OpenAI CodexOAuthgpt-5.1-codex-mini
GitHub CopilotOAuthclaude-sonnet-4
Google (Gemini)API keygemini-2.5-flash
MistralAPI keymistral-medium-latest
GroqAPI keyllama-3.3-70b-versatile
xAI (Grok)API keygrok-3-mini-fast
OpenRouterAPI keyanthropic/claude-sonnet-4
Ollama (tempatan)Tiadallama3.2
LM Studio (tempatan)Tiadaqwen3.5-4b-mlx

Tukar penyedia bila-bila masa dengan bun run switch. Ollama dan LM Studio berjalan sepenuhnya di mesin anda — tiada API key diperlukan, tiada data meninggalkan rangkaian anda.

Memori
#

Sistem memori mempunyai tiga lapisan, setiap satu melayani tujuan yang berbeza.

Reka bentuk memori semantik menggabungkan idea dari MemPalace (seni bina istana memori yang mengatur memori ke dalam wing, hall, dan room) dan kaedah PARA Tiago Forte (Projects, Areas, Resources, Archive) untuk pengurusan kitaran hayat pengetahuan.

Memori perbualan
#

SQLite dengan carian teks penuh FTS5. Semua mesej disimpan dengan cap masa dan ID sesi.

  • Jangka pendekMAX_HISTORY mesej terakhir disimpan dalam memori setiap sesi
  • Jangka panjang — Semua mesej disimpan dalam SQLite, boleh dicari melalui padanan kata kunci FTS5
  • Recall setiap giliran — Apabila memori semantik aktif, MAX_RECALL mengawal berapa banyak memori berkaitan yang disuntik ke dalam prompt setiap giliran
  • Sesi tamat selepas SESSION_TTL_MINUTES, tetapi memori jangka panjang kekal selama-lamanya

Sesuaikan ini secara interaktif dengan bun run memory.

Memori semantik
#

Memerlukan VECTOR_MEMORY=true dan penyedia embedding (Ollama, LM Studio, atau OpenAI).

Setiap memori dibenamkan sebagai vektor dan diklasifikasi secara automatik oleh LLM ke dalam empat dimensi:

  • Wing — Entiti: user, person:john, project:blog, place:london
  • Room — Jenis: facts, preferences, events, decisions, requests
  • Hall — Topik: personal, tech, health, travel, food, work
  • Status — Klasifikasi PARA: project, area, resource, archive

Apabila anda bertanya soalan, pengekstrakan entiti memfokuskan carian vektor pada wing yang paling relevan. Keputusan digabungkan dengan keputusan kata kunci FTS5 menggunakan reciprocal rank fusion — supaya anda mendapat yang terbaik daripada padanan kata kunci dan semantik.

Graf pengetahuan
#

Stor triple temporal untuk fakta berstruktur dan tahan lama:

  • Triple: (subject, predicate, object) dengan cap masa valid_from / valid_until
  • Predikat nilai tunggal (lives_in, partner) membatalkan nilai lama secara automatik semasa pengemaskinian
  • Predikat berbilang nilai (child, friend, hobby) wujud bersama tanpa pembatalan
  • Fakta graf pengetahuan disuntik bersama memori yang dipanggil semula dalam setiap perbualan

Apabila anda memberitahu agent “Saya berpindah ke Berlin”, ia membatalkan triple lives_in lama dan mencipta yang baharu — secara automatik.

Kitaran hayat PARA
#

Setiap memori ditag dengan status PARA:

  • Project — Kerja aktif yang terikat masa
  • Area — Tanggungjawab berterusan
  • Resource — Bahan rujukan (senarai, cadangan, panduan)
  • Archive — Projek yang selesai atau dibatalkan

Apabila projek selesai, agent menggunakan persamaan semantik untuk mengarkibkan hanya memori projek tersebut sambil mengekalkan bahan rujukan untuk kegunaan masa hadapan.

Cascade akhir projek
#

Sebut “Saya membatalkan perjalanan saya ke Barcelona” dan satu panggilan tool mengendalikan semuanya:

  1. Mengarkibkan vektor projek (events, decisions, requests yang terikat dengan Barcelona).
  2. Membatalkan setiap triple graf pengetahuan yang aktif yang predikatnya sepadan dengan slug projek (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
  3. Merekodkan penyelesaian sebagai triple baharu: (user, "cancelled_visit_barcelona", "2026-04-15").

Padanan menyedari sempadan — projek lain bernama revisit_barcelona kekal tidak disentuh. Agent tidak perlu lagi mengatur tiga panggilan berasingan dalam urutan yang betul, jadi model yang lebih kecil juga melakukannya dengan betul.

Jika VECTOR_MEMORY dinyahdayakan atau penyedia embedding tidak dapat dicapai, sistem kembali kepada FTS5 sahaja tanpa ralat.

Kemahiran
#

Kemahiran ialah fail .md dalam skills/ yang mentakrifkan iOS Shortcuts yang boleh dicetuskan oleh agent dan/atau peraturan tingkah laku. Mereka menggunakan pemuatan dinamik: hanya indeks ringkas (tajuk, penerangan, senarai pintasan) disuntik ke dalam prompt sistem. Agent memuatkan kandungan penuh atas permintaan melalui alat load_skill, mengekalkan penggunaan token yang rendah apabila anda menambah lebih banyak kemahiran.

Setiap fail kemahiran menggunakan frontmatter YAML:

---
title: Notes
description: Create notes on the user's device with a title and body
shortcuts: [newNote]
target: mac
sync_app: Notes
---

### New Note

Shortcut name: `newNote`

Creates a new note on the user's device.

Data fields:
- title (string, required): Note title
- content (string, required): Note body

Medan frontmatter
#

MedanWajibPenerangan
titleYaNama yang mudah dibaca
descriptionYaSatu ayat yang digunakan dalam indeks kemahiran yang dipaparkan kepada agent
shortcutsYaTatasusunan nama pintasan yang ditakrifkan dalam fail. Gunakan [] untuk kemahiran yang hanya mengandungi peraturan tingkah laku
targetTidakTempat pintasan dijalankan: device (lalai, dihantar ke iOS) atau mac (dijalankan pada pelayan)
sync_appTidakApp yang dicetuskan di latar belakang selepas pelaksanaan di pelayan untuk mencetuskan penyegerakan iCloud (contohnya Notes, Calendar, Reminders). Ketinggalan atau gunakan none untuk melangkau

Kemahiran juga boleh menjadi peraturan tingkah laku tanpa pintasan (contohnya, “cara merancang perjalanan keluarga”). Gunakan shortcuts: [] untuk ini.

Agent boleh mencipta dan mengurus kemahiran apabila diminta — minta ia untuk “cipta kemahiran untuk mengawal lampu saya” dan ia akan menulis fail .md untuk anda. Kemahiran baharu dan yang disunting sentiasa mendarat pada lapisan pengguna anda (data/user/skills/), jadi kemas kini framework tidak akan menulis ganti mereka. Lihat bahagian Menyesuaikan agent anda di bawah.

Menjalankan pintasan pada pelayan Mac
#

Apabila kemahiran mempunyai target: mac, pintasan akan dijalankan secara senyap pada pelayan Mac melalui CLI shortcuts run dan bukannya dihantar ke peranti iOS. Ini sesuai untuk tindakan yang mencipta kandungan yang disegerakkan iCloud — nota, peringatan, acara kalendar — kerana hasilnya secara automatik disegerakkan ke semua peranti anda tanpa perlu aplikasi PocketHook melakukan apa-apa.

Cara ia berfungsi:

  1. Agent memutuskan sebuah pintasan patut dijalankan (contohnya “cipta nota dengan nota mesyuarat hari ini”)
  2. Pelayan memanggil shortcuts run "shortcutName" dengan data dihantar sebagai JSON melalui stdin, menggunakan format wrapper yang sama seperti yang digunakan PocketHook iOS
  3. Jika sync_app ditetapkan, pelayan membuka aplikasi tersebut secara ringkas di latar belakang (open -gj -a Notes) untuk memaksa penyegerakan iCloud, kemudian menutupnya selepas 5 saat
  4. Pengguna menerima mesej pengesahan dalam sembang; pintasan itu sendiri tidak dihantar ke peranti

Keperluan:

  • Pelayan mesti berjalan pada macOSshortcuts run hanya tersedia pada macOS. Pada platform lain, pelayan akan merekodkan amaran dan berundur kepada pelaksanaan pada peranti
  • Pintasan mesti dipasang dalam Shortcuts.app pada Mac pelayan
  • Pintasan sepatutnya menerima Dictionary sebagai input (PocketHook membungkus data dalam { context, timestamp, app, data })

Bila menggunakan target: mac:

  • Tindakan yang disegerakkan iCloud (Notes, Reminders, Calendar) — hasilnya tetap sampai ke setiap peranti
  • Pemprosesan berjalan lama yang anda mahu jauhkan daripada peranti iOS
  • Mana-mana pintasan yang tidak perlu berinteraksi dengan UI iPhone

Bila kekal dengan target: device (lalai):

  • Pintasan yang memerlukan ciri khas iPhone (kamera, lokasi tepat, automasi aplikasi tempatan)
  • Pintasan yang meminta input interaktif daripada pengguna
  • Pintasan yang menggunakan App Intents daripada aplikasi khas iOS

Tugas Latar Belakang
#

Minta agent untuk menjadualkan tugas dan ia akan menguruskan selebihnya:

  • “Semak cuaca setiap pagi jam 8 dan cipta nota”
  • “Jalankan skrip ini setiap jam”
  • “Ingatkan saya untuk semak e-mel dalam 30 minit”

Tugas menyokong ungkapan cron (0 8 * * *) dan selang mudah (30m, 1h, 2d). Keputusan dihantar ke PocketHook apabila ia mengundi endpoint /jobs.

Dua jenis pelaksanaan:

  • Shell — Menjalankan perintah bash, menangkap output. Boleh mencetuskan Shortcut apabila selesai
  • Prompt — Diproses oleh agent AI dengan akses alat penuh, menyimpan respons PocketHook lengkap

Dev Server
#

Apabila agent mencipta projek web dalam workspace (Hugo, Astro, Next.js, Flask, Go, dll.), ia secara proaktif menawarkan untuk menyajikannya:

  • Preview — Memulakan dev server tempatan pada port yang ditetapkan secara automatik untuk tontonan pantas
  • Public — Memulakan pelayan dan mendedahkannya melalui terowong HTTPS supaya ia boleh diakses dari mana-mana

Agent menguruskan kitaran hayat: mula, henti, dan senarai pelayan yang berjalan. Semua pelayan dibersihkan apabila pelayan utama berhenti.

Tunnel contract
#

Apabila agent memulakan pelayan dengan permintaan pendedahan tunnel, runtime menguatkuasakannya: jika tiada alat tunnel (Tailscale, ngrok, cloudflared) dipasang, pelayan enggan bermula. Jika persediaan tunnel gagal selepas spawn, proses yatim dihentikan dan agent diberitahu secara eksplisit — supaya ia boleh kembali ke mod preview atau meminta anda memasang tunnel. URL yang dikembalikan sentiasa URL tunnel apabila tunneling aktif, dengan nota bahawa URL tempatan hanya untuk hos.

Sebagai jaring keselamatan, setiap alat respond_* memproses selepas mesejnya: mana-mana URL localhost atau 127.0.0.1 yang menyelinap ke dalam jawapan akan ditulis semula secara automatik ke URL tunnel yang sepadan apabila pelayan yang diuruskan mempunyainya. Apabila tidak boleh menulis semula, anda mendapat amaran dalam log sebaliknya daripada pautan rosak pada telefon anda.

Papan Pemuka
#

Papan pemuka web terbina dalam di /dashboard menunjukkan gambaran langsung tugas latar belakang.

Tidak disahkan secara reka bentuk. Kedua-dua /dashboard dan /api/jobs adalah endpoint GET terbuka — sesiapa yang boleh mencapai hos boleh menyenaraikan tugas. Hadkan akses pada lapisan rangkaian (Tailscale ACL, firewall, reverse proxy dengan basic auth) atau tetapkan DASHBOARD=false jika anda tidak memerlukannya. Aplikasi PocketHook iOS tidak menggunakan endpoint ini.

Ia boleh disuai sepenuhnya:

  • Edit pantas — Letakkan dashboard.html dalam workspace/dashboard/ untuk penyesuaian mudah
  • Projek penuh — Cipta projek kerangka kerja (Svelte, React, Vue, dll.) dalam workspace/dashboard/ dengan output binaan ke dist/

Minta agent untuk menyesuaikan papan pemuka anda dan ia akan menguruskan selebihnya — setiap pengguna mendapat papan pemuka unik dan diperibadikan.

Alat Tersuai
#

Agent boleh memasang alat CLI dan mendaftarkannya sebagai keupayaan baharu — memperluaskan dirinya tanpa mengubah suai kod pelayan.

Contohnya, katakan “pasang Playwright dan gunakan untuk mengambil tangkapan skrin”. Agent akan:

  1. Memasang dependensi
  2. Mencipta definisi alat (fail .md yang mudah)
  3. Menggunakan alat baharu dalam perbualan akan datang

Alat tersuai dimuat semula secara langsung — tiada mula semula diperlukan. Padamkan fail .md untuk membuang alat.

Versi
#

Semua data pengguna diversi secara automatik:

  • Fail workspace — Dijejaki dengan repo git tempatan dalam workspace/. Setiap penulisan mencipta auto-commit. Minta agent untuk “buat asal perubahan terakhir” atau gunakan git revert HEAD secara manual
  • Fail konfigurasiconfig/agent-instructions.md, config/personality.md, skills/, dan permissions.json disandarkan sebelum setiap pengubahsuaian. Sehingga 20 versi setiap fail

Git adalah pilihan — jika tidak dipasang, perubahan workspace tidak diversi. Sandaran konfigurasi sentiasa berfungsi.

Menyesuaikan Agent Anda
#

Agent server dihantar dengan framework base minimum dan mengharapkan anda melapisi penyesuaian anda sendiri di atasnya. Runtime mengekalkan kedua-duanya berasingan supaya kemas kini framework tidak pernah memusnahkan kerja anda.

Framework berbanding pengguna
#

pockethook-agent-server/
├── skills/                      # kemahiran yang dibekalkan framework (baca sahaja)
├── custom-tools/                # disimpan untuk alat yang dibekalkan framework (baca sahaja)
├── config/
│   ├── agent-instructions.md    # arahan agent framework (baca sahaja)
│   └── personality.md           # personaliti framework (baca sahaja)
└── data/user/                   # penyesuaian ANDA ada di sini (git-ignored)
    ├── skills/                  # kemahiran anda sendiri (mengatasi base berdasarkan nama fail)
    ├── custom-tools/            # custom tools yang anda pasang
    ├── instructions.md          # tambahan anda kepada arahan agent
    └── prefs.json               # nilai bertaip yang dirujuk sebagai {{prefs.key}}

Penyesuaian pengguna ditulis melalui alat bertaip khusus (create_user_skill, create_custom_tool) supaya fail yang terhasil sentiasa sepadan dengan format pemuat. Alat write juga menolak sebarang path di bawah skills/, custom-tools/, atau config/ dan mengarahkan agent ke data/user/* — jadi walaupun pengeditan fail langsung berakhir pada lapisan pengguna.

Nota tentang direktori custom-tools/ base. Hari ini ia hanya mengandungi templat (_example.md) yang diabaikan oleh pemuat — setiap alat yang dipasang oleh agent untuk anda masuk ke data/user/custom-tools/. Direktori ini disimpan supaya keluaran framework masa hadapan boleh menghantar alat terbina dalam pilihan tanpa mengatasi pemasangan anda. Apabila itu berlaku, fail lapisan pengguna anda tetap menang pada pertembungan nama alat, jadi tidak ada yang perlu dipindahkan.

Empat cara untuk menyesuaikan
#

Apa yang anda mahu ubahKe mana ia pergiContoh
Kemahiran pintasan atau tingkah lakudata/user/skills/<name>.md“Cipta kemahiran untuk log senaman saya”
Alat CLI yang dibungkus sebagai keupayaan agentdata/user/custom-tools/<name>.md“Pasang ffmpeg dan biar saya menggunakannya untuk penukaran”
Peraturan global (“sentiasa balas dalam bahasa Inggeris”, “jangan gunakan jadual”)data/user/instructions.md“Mulai sekarang, sentiasa ringkaskan artikel dalam 3 bullet”
Nilai lalai bertaip yang dirujuk oleh kemahirandata/user/prefs.json“Titik mula laluan lalai saya ialah Madrid”{"routeOrigin": "Madrid"}

Anda tidak perlu menulis fail-fail ini secara manual. Cukup beritahu agent apa yang anda mahu dan ia akan memilih lapisan yang betul secara automatik.

Typed preferences dengan {{prefs.*}}
#

Katakan anda menulis kemahiran perancang laluan yang perlu mengetahui titik permulaan lalai anda. Daripada hardcode “Madrid” ke dalam kemahiran, rujuk pref:

- **Titik permulaan**: {{prefs.routeOrigin}}, kecuali pengguna menentukan titik mula yang berbeza.

Dan simpan nilainya dalam data/user/prefs.json:

{
  "routeOrigin": "Madrid, Spain",
  "preferredMapsApp": "apple",
  "tunnel": { "domain": "my-host.ts.net" }
}

Pelayan menggantikan placeholder apabila kemahiran dimuatkan. Kunci bersarang ({{prefs.tunnel.domain}}) juga berfungsi. Kunci yang tidak diketahui dibiarkan tidak disentuh supaya salah taip kekal kelihatan.

Mengedit framework base secara langsung
#

Jika anda hos sendiri dan mahu menala framework itu sendiri, anda boleh mengedit config/agent-instructions.md, config/personality.md, skills/, atau custom-tools/ secara langsung — pelayan tidak menghalang anda apabila anda menggunakan editor fail. Tetapi agent tidak akan menulis ke path tersebut dari perbualan. Dan kemas kini framework akan menulis ganti suntingan anda. Utamakan lapisan pengguna untuk apa sahaja yang anda mahu kekalkan.

Memperluaskan Pelayan
#

  • Alat tersuai — Minta agent untuk memasang alat CLI; mereka mendarat di data/user/custom-tools/ secara automatik
  • Tambah kemahiran — Minta agent untuk mencipta kemahiran; fail pergi ke data/user/skills/
  • Ubah tingkah laku — Minta agent untuk menggunakan peraturan global; ia ditambah pada data/user/instructions.md
  • Konfigurasi kebenaran — Jalankan bun run permissions untuk mengawal alat mana yang boleh digunakan oleh agent
  • Tambah alat terbina dalam — Laksanakan fungsi alat baharu dalam src/tools.ts untuk integrasi yang lebih dalam (memerlukan fork pelayan)

Konfigurasi
#

Semua tetapan disimpan dalam .env (dicipta oleh bun run setup). Pilihan utama:

Pemboleh ubahLalaiPenerangan
AUTH_TOKEN(wajib)Rahsia dikongsi dengan PocketHook
LLM_API_KEY(wajib)API key penyedia LLM
LLM_PROVIDERanthropicNama penyedia
LLM_MODELclaude-sonnet-4-20250514ID model
LLM_REASONINGoffTahap penaakulan: off, minimal, low, medium, high, xhigh. Tahap lebih tinggi menambah token pemikiran tersembunyi (lebih lambat + lebih mahal). Diabaikan oleh model yang tidak menyokong
PORT3000Port pelayan
AGENT_NAMEPocketHook AssistantNama paparan agent
MAX_HISTORY50Mesej dalam memori jangka pendek
MAX_RECALL5Memori dikembalikan setiap giliran oleh recall semantik (hanya apabila VECTOR_MEMORY=true)
SESSION_TTL_MINUTES60Tamat tempoh sesi
VECTOR_MEMORYfalseDayakan memori semantik (memerlukan penyedia embedding)
EMBEDDING_PROVIDERollamaPenyedia embedding: ollama, lm-studio, atau openai
EMBEDDING_MODELnomic-embed-textNama model embedding
EMBEDDING_URL(auto)URL API embedding
EMBEDDING_API_KEYAPI key untuk OpenAI embeddings
LOG_LEVELinfoTahap log: debug, info, warn, error
RATE_LIMIT_MAX30Permintaan maksimum setiap tetingkap
DASHBOARDtrueDayakan papan pemuka web (laluan /dashboard)
INSTANCE_NAME(basename direktori projek, dengan awalan pockethook- dibuang)Akhiran yang digunakan untuk label perkhidmatan sistem, direktori log, dan padanan proses. Tetapkan secara eksplisit apabila menjalankan beberapa checkout pada mesin yang sama

Lihat rujukan konfigurasi penuh di repositori GitHub.

Menjalankan sebagai Perkhidmatan
#

Pasang sebagai perkhidmatan berterusan yang bermula secara automatik:

bun run service install
PlatformBackendLokasi perkhidmatan
macOSlaunchd~/Library/LaunchAgents/com.pockethook.${INSTANCE_NAME}.plist
Linuxsystemd (user)~/.config/systemd/user/pockethook-${INSTANCE_NAME}.service
WindowsNSSMPocketHook-${PascalCase(INSTANCE_NAME)} dalam Windows Service Manager

INSTANCE_NAME lalai kepada basename direktori projek dengan awalan pockethook- dibuang (cth., checkout dalam pockethook-agent-server/ menjadi agent-server). Tetapkan secara eksplisit untuk menjalankan beberapa checkout pada mesin yang sama tanpa pertembungan — setiap instance mengekalkan data/ dan log tersendiri.

Urus dengan bun run service status, restart, stop, atau uninstall.

Keselamatan
#

  • HTTPS wajib — PocketHook menguatkuasakan HTTPS untuk semua URL
  • Pengesahan bearer token — Rahsia dikongsi antara aplikasi dan pelayan
  • Had kadar — Had per token mencegah penyalahgunaan
  • Alat kotak pasir — Perintah shell dan akses fail dihadkan oleh kebenaran
  • Corak disekat — Perintah berbahaya (sudo, rm -rf /) disekat secara lalai
  • Sempadan direktori kerja — Agent tidak boleh keluar dari direktori yang ditetapkan
  • Fail sensitif dilindungi.env, .git, *.key, *.pem disekat daripada akses agent
  • Versi automatik — Semua perubahan workspace dijejaki git untuk pengunduran mudah