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 bawahdata/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_jobmencipta 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 kombinasitype/schedulesebelum sampai ke peranti - Penulis bertaip untuk penyesuaian —
create_user_skilldancreate_custom_toolmembina 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 alatload_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_projectmengarkibkan 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: truediminta, 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
localhostdalam respons, alatrespond_*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.
/dashboarddan/api/jobstidak disahkan secara reka bentuk — hadkan akses pada lapisan rangkaian (Tailscale ACL, firewall, reverse proxy dengan basic auth) atau tetapkanDASHBOARD=falsejika 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#
- Runtime Bun
- API key atau kelayakan OAuth untuk penyedia LLM anda
- (Pilihan) Tailscale, ngrok, atau cloudflared untuk terowong HTTPS
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 PocketHook | URL |
|---|---|
| Server URL | https://your-host |
| Health Check URL | https://your-host/health |
| Polling URL | https://your-host/jobs |
Cara Ia Berfungsi#
- Anda menghantar mesej dalam PocketHook
- Pelayan memajukannya ke LLM pilihan anda dengan sejarah perbualan, memori yang dipanggil semula, dan alat yang tersedia
- LLM memproses mesej — ia boleh menjalankan perintah shell, membaca/menulis fail, mencari web, menjadualkan tugas latar belakang, mengingat fakta, atau memulakan dev server
- Respons dikembalikan dalam format PocketHook (
msg+shortcut+data+url) - PocketHook memaparkan mesej dan menjalankan sebarang Shortcuts pada peranti anda
Penyedia LLM yang Disokong#
| Penyedia | Auth | Model Lalai |
|---|---|---|
| Anthropic | API key | claude-sonnet-4-20250514 |
| OpenAI | API key | gpt-4.1-mini |
| OpenAI Codex | OAuth | gpt-5.1-codex-mini |
| GitHub Copilot | OAuth | claude-sonnet-4 |
| Google (Gemini) | API key | gemini-2.5-flash |
| Mistral | API key | mistral-medium-latest |
| Groq | API key | llama-3.3-70b-versatile |
| xAI (Grok) | API key | grok-3-mini-fast |
| OpenRouter | API key | anthropic/claude-sonnet-4 |
| Ollama (tempatan) | Tiada | llama3.2 |
| LM Studio (tempatan) | Tiada | qwen3.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 pendek —
MAX_HISTORYmesej 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_RECALLmengawal 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 masavalid_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:
- Mengarkibkan vektor projek (events, decisions, requests yang terikat dengan Barcelona).
- Membatalkan setiap triple graf pengetahuan yang aktif yang predikatnya sepadan dengan slug projek (
scheduled_visit_barcelona,planning_visit_barcelona,confirmed_visit_barcelona). - 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#
| Medan | Wajib | Penerangan |
|---|---|---|
title | Ya | Nama yang mudah dibaca |
description | Ya | Satu ayat yang digunakan dalam indeks kemahiran yang dipaparkan kepada agent |
shortcuts | Ya | Tatasusunan nama pintasan yang ditakrifkan dalam fail. Gunakan [] untuk kemahiran yang hanya mengandungi peraturan tingkah laku |
target | Tidak | Tempat pintasan dijalankan: device (lalai, dihantar ke iOS) atau mac (dijalankan pada pelayan) |
sync_app | Tidak | App 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:
- Agent memutuskan sebuah pintasan patut dijalankan (contohnya “cipta nota dengan nota mesyuarat hari ini”)
- Pelayan memanggil
shortcuts run "shortcutName"dengan data dihantar sebagai JSON melalui stdin, menggunakan format wrapper yang sama seperti yang digunakan PocketHook iOS - Jika
sync_appditetapkan, pelayan membuka aplikasi tersebut secara ringkas di latar belakang (open -gj -a Notes) untuk memaksa penyegerakan iCloud, kemudian menutupnya selepas 5 saat - Pengguna menerima mesej pengesahan dalam sembang; pintasan itu sendiri tidak dihantar ke peranti
Keperluan:
- Pelayan mesti berjalan pada macOS —
shortcuts runhanya 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
/dashboarddan/api/jobsadalah endpointGETterbuka — sesiapa yang boleh mencapai hos boleh menyenaraikan tugas. Hadkan akses pada lapisan rangkaian (Tailscale ACL, firewall, reverse proxy dengan basic auth) atau tetapkanDASHBOARD=falsejika anda tidak memerlukannya. Aplikasi PocketHook iOS tidak menggunakan endpoint ini.
Ia boleh disuai sepenuhnya:
- Edit pantas — Letakkan
dashboard.htmldalamworkspace/dashboard/untuk penyesuaian mudah - Projek penuh — Cipta projek kerangka kerja (Svelte, React, Vue, dll.) dalam
workspace/dashboard/dengan output binaan kedist/
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:
- Memasang dependensi
- Mencipta definisi alat (fail
.mdyang mudah) - 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 gunakangit revert HEADsecara manual - Fail konfigurasi —
config/agent-instructions.md,config/personality.md,skills/, danpermissions.jsondisandarkan 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 kedata/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 ubah | Ke mana ia pergi | Contoh |
|---|---|---|
| Kemahiran pintasan atau tingkah laku | data/user/skills/<name>.md | “Cipta kemahiran untuk log senaman saya” |
| Alat CLI yang dibungkus sebagai keupayaan agent | data/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 kemahiran | data/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 permissionsuntuk mengawal alat mana yang boleh digunakan oleh agent - Tambah alat terbina dalam — Laksanakan fungsi alat baharu dalam
src/tools.tsuntuk integrasi yang lebih dalam (memerlukan fork pelayan)
Konfigurasi#
Semua tetapan disimpan dalam .env (dicipta oleh bun run setup). Pilihan utama:
| Pemboleh ubah | Lalai | Penerangan |
|---|---|---|
AUTH_TOKEN | (wajib) | Rahsia dikongsi dengan PocketHook |
LLM_API_KEY | (wajib) | API key penyedia LLM |
LLM_PROVIDER | anthropic | Nama penyedia |
LLM_MODEL | claude-sonnet-4-20250514 | ID model |
LLM_REASONING | off | Tahap penaakulan: off, minimal, low, medium, high, xhigh. Tahap lebih tinggi menambah token pemikiran tersembunyi (lebih lambat + lebih mahal). Diabaikan oleh model yang tidak menyokong |
PORT | 3000 | Port pelayan |
AGENT_NAME | PocketHook Assistant | Nama paparan agent |
MAX_HISTORY | 50 | Mesej dalam memori jangka pendek |
MAX_RECALL | 5 | Memori dikembalikan setiap giliran oleh recall semantik (hanya apabila VECTOR_MEMORY=true) |
SESSION_TTL_MINUTES | 60 | Tamat tempoh sesi |
VECTOR_MEMORY | false | Dayakan memori semantik (memerlukan penyedia embedding) |
EMBEDDING_PROVIDER | ollama | Penyedia embedding: ollama, lm-studio, atau openai |
EMBEDDING_MODEL | nomic-embed-text | Nama model embedding |
EMBEDDING_URL | (auto) | URL API embedding |
EMBEDDING_API_KEY | — | API key untuk OpenAI embeddings |
LOG_LEVEL | info | Tahap log: debug, info, warn, error |
RATE_LIMIT_MAX | 30 | Permintaan maksimum setiap tetingkap |
DASHBOARD | true | Dayakan 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
| Platform | Backend | Lokasi perkhidmatan |
|---|---|---|
| macOS | launchd | ~/Library/LaunchAgents/com.pockethook.${INSTANCE_NAME}.plist |
| Linux | systemd (user) | ~/.config/systemd/user/pockethook-${INSTANCE_NAME}.service |
| Windows | NSSM | PocketHook-${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,*.pemdisekat daripada akses agent - Versi automatik — Semua perubahan workspace dijejaki git untuk pengunduran mudah