Agent Server

PocketHook Agent Server là gì?

#

Agent server biến PocketHook thành trợ lý AI đầy đủ. Thay vì tự viết logic phản hồi, bạn kết nối LLM (Claude, GPT, Gemini, v.v.) để xử lý tin nhắn, gọi công cụ và trả về phản hồi PocketHook có cấu trúc — bao gồm kích hoạt Shortcut.

Máy chủ chạy trên máy của riêng bạn. Dữ liệu của bạn ở lại với bạn.

Đây là điểm khởi đầu. Máy chủ đi kèm bộ công cụ cốt lõi và được thiết kế để bạn mở rộng. Thêm các tích hợp của riêng bạn — email, lịch, tài liệu, API — và biến nó thành của bạn.

Tính năng

#

• LLM đa nhà cung cấp — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (cục bộ), LM Studio (cục bộ)
• Xác thực OAuth — GitHub Copilot và OpenAI Codex qua device code / browser flow
• Công cụ agent — Lệnh shell, đọc/ghi tệp, liệt kê thư mục, tìm kiếm web, web scraping, quản lý dev server
• Tách framework / người dùng — Các tệp framework (skills/, custom-tools/, config/) chỉ đọc. Tùy chỉnh của bạn nằm dưới data/user/ (skills, custom tools, instructions, prefs có kiểu). Cập nhật framework được cài đặt gọn gàng mà không ghi đè công việc của bạn
• Prefs người dùng có kiểu — Lưu các giá trị như ứng dụng bản đồ ưa thích hoặc tên miền tunnel trong data/user/prefs.json. Tham chiếu chúng trong kỹ năng dưới dạng {{prefs.key}} và server sẽ thay thế khi nạp
• Tác vụ lập trình trong một lần gọi — Meta-tool run_code_job tạo một tác vụ nền kiểu prompt (chạy bởi LLM bạn đã cấu hình) và gửi xác nhận cho người dùng trong một bước duy nhất, thay thế mẫu “respond + create-job” dễ gây lỗi
• Công cụ giao thức có kiểu — Sáu công cụ respond_* chuyên biệt (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), cùng với các công cụ tác vụ có kiểu (create_once_job, create_cron_job) và các công cụ workspace có kiểu (create_project, list_projects, delete_project). Schema sẽ từ chối URL không hợp lệ, cú pháp nút bấm, và các kết hợp type/schedule trước khi đến thiết bị
• Trình ghi có kiểu cho tùy chỉnh — create_user_skill và create_custom_tool xây dựng markdown lớp người dùng với frontmatter chính xác, để trình nạp luôn phân tích được chúng và agent không bao giờ phải tự viết các tệp này
• Tác vụ nền — Tác vụ một lần hoặc định kỳ với biểu thức cron hoặc khoảng thời gian đơn giản
• Kỹ năng động — Định nghĩa shortcut và quy tắc hành vi dưới dạng tệp .md. Chỉ một chỉ mục nhỏ gọn được nạp vào prompt; nội dung đầy đủ được tải theo yêu cầu qua công cụ load_skill
• Kỹ năng tự quản lý — Agent có thể tạo, chỉnh sửa và xóa định nghĩa kỹ năng (ghi luôn đi vào lớp người dùng)
• Bộ nhớ ngữ nghĩa — Tìm kiếm dựa trên vector với embedding (Ollama, LM Studio hoặc OpenAI). Bộ nhớ được LLM tự động phân loại vào các chiều wing/room/hall/status
• Đồ thị tri thức — Kho lưu trữ bộ ba thời gian cho các sự kiện bền vững với tự động vô hiệu hóa. Quan hệ đa giá trị cùng tồn tại; sự kiện đơn giá trị tự động thay thế
• Phương pháp PARA với cascade khi kết thúc dự án — Mỗi bộ nhớ được gắn thẻ trạng thái (Project, Area, Resource, Archive). Khi một dự án kết thúc, một lệnh gọi complete_project duy nhất lưu trữ các vector của nó, vô hiệu hóa mọi triple lập kế hoạch gắn với slug của nó, và ghi lại sự hoàn thành — một lệnh gọi thay vì ba
• Gợi nhớ lai — Kết hợp tìm kiếm từ khóa FTS5 với tìm kiếm ngữ nghĩa vector sử dụng reciprocal rank fusion
• Bộ nhớ dài hạn — SQLite + tìm kiếm toàn văn FTS5 làm dự phòng khi bộ nhớ ngữ nghĩa bị tắt
• Quản lý dev server với hợp đồng tunnel — Khởi động, dừng và liệt kê dev server. Khi yêu cầu tunnel: true, server thực thi nó trước khi chạy và sau khi spawn — một server localhost không thể tiếp cận sẽ không bao giờ bị để chạy âm thầm
• Làm sạch URL tự động — Nếu agent để lại URL localhost trong phản hồi, các công cụ respond_* sẽ viết lại thành URL tunnel tương ứng để điện thoại của bạn luôn nhận được liên kết có thể truy cập
• Công cụ tùy chỉnh — Agent có thể cài đặt công cụ CLI và đăng ký chúng như khả năng mới
• Quản lý phiên bản — Quản lý phiên bản git tự động cho tệp workspace; sao lưu cấu hình cho kỹ năng và quyền
• Bảng điều khiển web — Tổng quan trực tiếp các tác vụ nền, tùy chỉnh theo từng người dùng. /dashboard và /api/jobs không yêu cầu xác thực theo thiết kế — hãy hạn chế truy cập ở lớp mạng (Tailscale ACL, tường lửa, reverse proxy với basic auth) hoặc đặt DASHBOARD=false nếu bạn không cần nó
• Đường hầm HTTPS — Hỗ trợ tích hợp cho Tailscale, ngrok và Cloudflare Tunnel
• Dịch vụ hệ thống — Cài đặt như dịch vụ liên tục trên macOS, Linux hoặc Windows
• Giới hạn tốc độ — Giới hạn yêu cầu theo token với ngưỡng có thể cấu hình

Yêu cầu

#

• Runtime Bun
• API key hoặc thông tin xác thực OAuth cho nhà cung cấp LLM của bạn
• (Tùy chọn) Tailscale, ngrok hoặc cloudflared cho đường hầm HTTPS

Bắt Đầu Nhanh

#

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

# Thiết lập tương tác — chọn provider, model, token xác thực, port
bun run setup

# Khởi động server + đường hầm HTTPS
bun run dev:tunnel

Trình hướng dẫn thiết lập sẽ dẫn bạn qua việc chọn nhà cung cấp LLM, cấu hình xác thực và thiết lập quyền công cụ.

Sau khi chạy, sao chép các URL hiển thị vào Cài đặt PocketHook:

Cách Hoạt Động

#

1. Bạn gửi tin nhắn trong PocketHook
2. Máy chủ chuyển tiếp đến LLM bạn chọn cùng lịch sử hội thoại, bộ nhớ được gợi lại và các công cụ có sẵn
3. LLM xử lý tin nhắn — có thể chạy lệnh shell, đọc/ghi tệp, tìm kiếm web, lên lịch tác vụ nền, ghi nhớ sự kiện hoặc khởi động dev server
4. Phản hồi được trả về theo định dạng PocketHook (msg + shortcut + data + url)
5. PocketHook hiển thị tin nhắn và thực thi bất kỳ Shortcuts nào trên thiết bị của bạn

Nhà Cung Cấp LLM Được Hỗ Trợ

#

Chuyển đổi nhà cung cấp bất kỳ lúc nào với bun run switch. Ollama và LM Studio chạy hoàn toàn trên máy của bạn — không cần API key, dữ liệu không rời khỏi mạng của bạn.

Bộ Nhớ

#

Hệ thống bộ nhớ có ba lớp, mỗi lớp phục vụ một mục đích khác nhau.

Thiết kế bộ nhớ ngữ nghĩa kết hợp ý tưởng từ MemPalace (kiến trúc cung điện trí nhớ tổ chức bộ nhớ thành wing, hall và room) và phương pháp PARA của Tiago Forte (Projects, Areas, Resources, Archive) cho quản lý vòng đời tri thức.

Bộ nhớ hội thoại

#

SQLite với tìm kiếm toàn văn FTS5. Tất cả tin nhắn được lưu trữ với dấu thời gian và ID phiên.

• Ngắn hạn — MAX_HISTORY tin nhắn gần nhất được giữ trong bộ nhớ mỗi phiên
• Dài hạn — Tất cả tin nhắn được lưu trữ trong SQLite, tìm kiếm được qua so khớp từ khóa FTS5
• Gợi nhớ mỗi lượt — Khi bộ nhớ ngữ nghĩa bật, MAX_RECALL kiểm soát số lượng bộ nhớ liên quan được đưa vào prompt mỗi lượt
• Phiên hết hạn sau SESSION_TTL_MINUTES, nhưng bộ nhớ dài hạn tồn tại mãi mãi

Tinh chỉnh tương tác với bun run memory.

Bộ nhớ ngữ nghĩa

#

Yêu cầu VECTOR_MEMORY=true và nhà cung cấp embedding (Ollama, LM Studio hoặc OpenAI).

Mỗi bộ nhớ được nhúng dưới dạng vector và được LLM tự động phân loại vào bốn chiều:

• Wing — Thực thể: user, person:john, project:blog, place:london
• Room — Loại: facts, preferences, events, decisions, requests
• Hall — Chủ đề: personal, tech, health, travel, food, work
• Status — Phân loại PARA: project, area, resource, archive

Khi bạn đặt câu hỏi, trích xuất thực thể tập trung tìm kiếm vector vào các wing liên quan nhất. Kết quả được hợp nhất với kết quả từ khóa FTS5 sử dụng reciprocal rank fusion — để bạn nhận được tốt nhất từ cả so khớp từ khóa và ngữ nghĩa.

Đồ thị tri thức

#

Kho lưu trữ bộ ba thời gian cho các sự kiện có cấu trúc, bền vững:

• Bộ ba: (subject, predicate, object) với dấu thời gian valid_from / valid_until
• Vị từ đơn giá trị (lives_in, partner) tự động vô hiệu hóa giá trị cũ khi cập nhật
• Vị từ đa giá trị (child, friend, hobby) cùng tồn tại mà không bị vô hiệu hóa
• Sự kiện đồ thị tri thức được đưa vào cùng bộ nhớ được gợi lại trong mỗi cuộc hội thoại

Khi bạn nói với agent “Tôi chuyển đến Berlin”, nó vô hiệu hóa bộ ba lives_in cũ và tạo bộ ba mới — tự động.

Vòng đời PARA

#

Mỗi bộ nhớ được gắn thẻ trạng thái PARA:

• Project — Công việc đang hoạt động, có thời hạn
• Area — Trách nhiệm liên tục
• Resource — Tài liệu tham khảo (danh sách, đề xuất, hướng dẫn)
• Archive — Dự án đã hoàn thành hoặc bị hủy

Khi dự án hoàn thành, agent sử dụng tương đồng ngữ nghĩa để lưu trữ chỉ bộ nhớ của dự án đó trong khi giữ lại tài liệu tham khảo cho sử dụng trong tương lai.

Cascade khi kết thúc dự án

#

Hãy nói “Tôi đang hủy chuyến đi Barcelona” và một lệnh gọi công cụ duy nhất xử lý mọi thứ:

1. Lưu trữ các vector của dự án (events, decisions, requests gắn với Barcelona).
2. Vô hiệu hóa mọi triple đồ thị tri thức đang hoạt động có vị từ trùng với slug dự án (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Ghi lại sự hoàn thành như một triple mới: (user, "cancelled_visit_barcelona", "2026-04-15").

Việc so khớp có nhận biết ranh giới — một dự án khác tên là revisit_barcelona vẫn không bị chạm tới. Agent không còn phải điều phối ba lệnh gọi riêng biệt theo đúng thứ tự nữa, vì vậy các model nhỏ hơn cũng làm đúng.

Nếu VECTOR_MEMORY bị tắt hoặc nhà cung cấp embedding không thể truy cập, hệ thống sẽ dùng FTS5 làm dự phòng mà không có lỗi.

Kỹ Năng

#

Kỹ năng là các tệp .md trong skills/ định nghĩa iOS Shortcuts mà agent có thể kích hoạt và/hoặc quy tắc hành vi. Chúng sử dụng tải động: chỉ một chỉ mục nhỏ gọn (tiêu đề, mô tả, danh sách shortcut) được đưa vào prompt hệ thống. Agent tải nội dung đầy đủ theo yêu cầu qua công cụ load_skill, giữ mức sử dụng token thấp khi bạn thêm nhiều kỹ năng hơn.

Mỗi tệp kỹ năng sử dụng 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

Các trường frontmatter

#

Kỹ năng cũng có thể là quy tắc hành vi không có shortcut (ví dụ: “cách lên kế hoạch chuyến du lịch gia đình”). Sử dụng shortcuts: [] cho những trường hợp này.

Agent có thể tạo và quản lý kỹ năng khi được yêu cầu — hãy yêu cầu nó “tạo một kỹ năng để điều khiển đèn” và nó sẽ viết tệp .md cho bạn. Kỹ năng mới và đã chỉnh sửa luôn đi vào lớp người dùng của bạn (data/user/skills/), vì vậy các bản cập nhật framework sẽ không bao giờ ghi đè chúng. Xem phần Tùy chỉnh agent của bạn bên dưới.

Thực thi shortcut trên máy chủ Mac

#

Khi một kỹ năng có target: mac, shortcut sẽ chạy âm thầm trên máy chủ Mac qua CLI shortcuts run thay vì được gửi đến thiết bị iOS. Điều này lý tưởng cho các hành động tạo nội dung được đồng bộ qua iCloud — ghi chú, nhắc nhở, sự kiện lịch — vì kết quả tự động đồng bộ đến tất cả thiết bị của bạn mà không cần ứng dụng PocketHook làm gì cả.

Cách hoạt động:

1. Agent quyết định một shortcut nên chạy (ví dụ “tạo ghi chú với biên bản cuộc họp hôm nay”)
2. Máy chủ gọi shortcuts run "shortcutName" với dữ liệu được truyền dưới dạng JSON qua stdin, dùng cùng định dạng wrapper mà PocketHook iOS sử dụng
3. Nếu sync_app được thiết lập, máy chủ sẽ mở ứng dụng đó trong nền một lát (open -gj -a Notes) để buộc đồng bộ iCloud, sau đó đóng sau 5 giây
4. Người dùng nhận được tin nhắn xác nhận trong cuộc trò chuyện; bản thân shortcut không được gửi đến thiết bị

Yêu cầu:

• Máy chủ phải chạy trên macOS — shortcuts run chỉ có trên macOS. Trên các nền tảng khác, máy chủ ghi cảnh báo và quay lại thực thi trên thiết bị
• Shortcut phải được cài đặt trong Shortcuts.app trên máy Mac của máy chủ
• Shortcut nên nhận Dictionary làm đầu vào (PocketHook bọc dữ liệu trong { context, timestamp, app, data })

Khi nào nên dùng target: mac:

• Các hành động đồng bộ iCloud (Notes, Reminders, Calendar) — kết quả sẽ đến mọi thiết bị dù sao
• Xử lý chạy lâu mà bạn muốn giữ ngoài thiết bị iOS
• Bất kỳ shortcut nào không cần tương tác với giao diện iPhone

Khi nào nên giữ target: device (mặc định):

• Shortcut cần các tính năng chỉ có trên iPhone (camera, vị trí chính xác, tự động hóa ứng dụng cục bộ)
• Shortcut yêu cầu người dùng nhập liệu tương tác
• Shortcut dùng App Intents từ các ứng dụng chỉ có trên iOS

Tác Vụ Nền

#

Yêu cầu agent lên lịch tác vụ và nó sẽ xử lý phần còn lại:

• “Kiểm tra thời tiết mỗi sáng lúc 8 giờ và tạo ghi chú”
• “Chạy script này mỗi giờ”
• “Nhắc tôi kiểm tra email sau 30 phút”

Tác vụ hỗ trợ biểu thức cron (0 8 * * *) và khoảng thời gian đơn giản (30m, 1h, 2d). Kết quả được gửi đến PocketHook khi nó kiểm tra endpoint /jobs.

Hai loại thực thi:

• Shell — Chạy lệnh bash, thu kết quả. Có thể kích hoạt Shortcut khi hoàn thành
• Prompt — Được xử lý bởi agent AI với quyền truy cập đầy đủ công cụ, lưu trữ phản hồi PocketHook hoàn chỉnh

Dev Server

#

Khi agent tạo dự án web trong workspace (Hugo, Astro, Next.js, Flask, Go, v.v.), nó chủ động đề xuất phục vụ:

• Preview — Khởi động dev server cục bộ trên cổng được gán tự động để xem nhanh
• Public — Khởi động server và phơi bày qua đường hầm HTTPS để truy cập từ bất kỳ đâu

Agent quản lý vòng đời: khởi động, dừng và liệt kê các server đang chạy. Tất cả server được dọn dẹp khi server chính dừng.

Hợp đồng tunnel

#

Khi agent khởi động một server với yêu cầu phơi bày qua tunnel, runtime sẽ thực thi điều đó: nếu không có công cụ tunnel (Tailscale, ngrok, cloudflared) được cài đặt, server sẽ từ chối khởi động. Nếu thiết lập tunnel thất bại sau khi spawn, tiến trình mồ côi sẽ bị dừng và agent được thông báo rõ ràng — để nó có thể chuyển sang chế độ preview hoặc yêu cầu bạn cài đặt tunnel. URL được trả về luôn là URL tunnel khi tunneling bật, kèm theo ghi chú rằng URL cục bộ chỉ dùng trên host.

Làm lưới an toàn, mọi công cụ respond_* xử lý hậu kỳ tin nhắn của nó: bất kỳ URL localhost hoặc 127.0.0.1 nào lọt vào phản hồi đều được viết lại tự động thành URL tunnel tương ứng khi một server được quản lý có URL đó. Khi không thể viết lại, bạn sẽ nhận được cảnh báo trong log thay vì một liên kết hỏng trên điện thoại.

Bảng Điều Khiển

#

Bảng điều khiển web tích hợp tại /dashboard hiển thị tổng quan trực tiếp các tác vụ nền.

Không xác thực theo thiết kế. Cả /dashboard và /api/jobs đều là endpoint GET mở — bất kỳ ai có thể truy cập host đều có thể liệt kê các tác vụ. Hãy hạn chế truy cập ở lớp mạng (Tailscale ACL, tường lửa, reverse proxy với basic auth) hoặc đặt DASHBOARD=false nếu bạn không cần nó. Ứng dụng PocketHook iOS không sử dụng các endpoint này.

Hoàn toàn tùy chỉnh:

• Chỉnh sửa nhanh — Đặt dashboard.html trong workspace/dashboard/ cho tùy chỉnh đơn giản
• Dự án đầy đủ — Tạo dự án framework (Svelte, React, Vue, v.v.) trong workspace/dashboard/ với đầu ra build vào dist/

Yêu cầu agent tùy chỉnh bảng điều khiển của bạn và nó sẽ xử lý phần còn lại — mỗi người dùng nhận được bảng điều khiển duy nhất, được cá nhân hóa.

Công Cụ Tùy Chỉnh

#

Agent có thể cài đặt công cụ CLI và đăng ký chúng như khả năng mới — tự mở rộng mà không cần sửa đổi mã máy chủ.

Ví dụ, hãy nói “cài Playwright và dùng nó để chụp ảnh màn hình”. Agent sẽ:

1. Cài đặt dependency
2. Tạo định nghĩa công cụ (một tệp .md đơn giản)
3. Sử dụng công cụ mới trong các cuộc hội thoại sau

Công cụ tùy chỉnh được tải lại nóng — không cần khởi động lại. Xóa tệp .md để gỡ bỏ công cụ.

Quản Lý Phiên Bản

#

Tất cả dữ liệu người dùng được quản lý phiên bản tự động:

• Tệp workspace — Theo dõi bằng repo git cục bộ bên trong workspace/. Mỗi lần ghi tạo auto-commit. Yêu cầu agent “hoàn tác thay đổi cuối” hoặc dùng git revert HEAD thủ công
• Tệp cấu hình — config/agent-instructions.md, config/personality.md, skills/ và permissions.json được sao lưu trước mỗi lần sửa đổi. Tối đa 20 phiên bản mỗi tệp

Git là tùy chọn — nếu chưa cài đặt, các thay đổi workspace không được quản lý phiên bản. Sao lưu cấu hình luôn hoạt động.

Tùy Chỉnh Agent Của Bạn

#

Agent server đi kèm với một framework base tối giản và mong bạn xếp tùy chỉnh của riêng mình lên trên. Runtime giữ hai phần tách biệt để các bản cập nhật framework không bao giờ phá hỏng công việc của bạn.

Framework so với người dùng

#

pockethook-agent-server/
├── skills/                      # kỹ năng do framework cung cấp (chỉ đọc)
├── custom-tools/                # dành cho các công cụ do framework cung cấp (chỉ đọc)
├── config/
│   ├── agent-instructions.md    # hướng dẫn agent của framework (chỉ đọc)
│   └── personality.md           # tính cách của framework (chỉ đọc)
└── data/user/                   # tùy chỉnh CỦA BẠN nằm ở đây (bị git-ignore)
    ├── skills/                  # kỹ năng riêng của bạn (ghi đè base theo tên tệp)
    ├── custom-tools/            # các công cụ tùy chỉnh bạn đã cài
    ├── instructions.md          # phần bổ sung của bạn cho hướng dẫn agent
    └── prefs.json               # giá trị có kiểu được tham chiếu dưới dạng {{prefs.key}}

Tùy chỉnh người dùng được ghi qua các công cụ có kiểu chuyên biệt (create_user_skill, create_custom_tool) để các tệp kết quả luôn khớp với định dạng của trình nạp. Công cụ write cũng từ chối bất kỳ đường dẫn nào dưới skills/, custom-tools/, hoặc config/ và chuyển hướng agent đến data/user/* — vì vậy ngay cả các chỉnh sửa tệp trực tiếp cũng kết thúc ở lớp người dùng.

Lưu ý về thư mục custom-tools/ của base. Hôm nay nó chỉ chứa một mẫu (_example.md) mà trình nạp bỏ qua — mọi công cụ agent cài cho bạn đều đi vào data/user/custom-tools/. Thư mục này được dành sẵn để các bản phát hành framework tương lai có thể cung cấp các công cụ tích hợp tùy chọn mà không ghi đè các bản cài của bạn. Khi điều đó xảy ra, các tệp lớp người dùng của bạn vẫn thắng khi xảy ra xung đột tên công cụ, nên không có gì cần di chuyển.

Bốn cách để tùy chỉnh

#

Bạn không bao giờ phải tự viết các tệp này bằng tay. Chỉ cần nói với agent bạn muốn gì và nó sẽ tự động chọn lớp phù hợp.

Preferences có kiểu với {{prefs.*}}

#

Giả sử bạn viết một kỹ năng lập kế hoạch tuyến đường cần biết điểm bắt đầu mặc định của bạn. Thay vì hardcode “Madrid” vào kỹ năng, hãy tham chiếu pref:

- **Điểm bắt đầu**: {{prefs.routeOrigin}}, trừ khi người dùng chỉ định một điểm xuất phát khác.

Và lưu giá trị trong data/user/prefs.json:

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

Server thay thế placeholder khi kỹ năng được nạp. Các khóa lồng nhau ({{prefs.tunnel.domain}}) cũng hoạt động. Các khóa không xác định được để nguyên để các lỗi đánh máy vẫn nhìn thấy được.

Chỉnh sửa trực tiếp framework base

#

Nếu bạn tự lưu trữ và muốn tự mình tinh chỉnh framework, bạn có thể chỉnh sửa config/agent-instructions.md, config/personality.md, skills/ hoặc custom-tools/ trực tiếp — server không ngăn bạn khi bạn dùng trình chỉnh sửa tệp. Nhưng agent sẽ không ghi vào các đường dẫn đó từ một cuộc hội thoại. Và các bản cập nhật framework sẽ ghi đè các chỉnh sửa của bạn. Hãy ưu tiên lớp người dùng cho bất cứ điều gì bạn muốn giữ lại.

Mở Rộng Máy Chủ

#

• Công cụ tùy chỉnh — Yêu cầu agent cài đặt công cụ CLI; chúng tự động đi vào data/user/custom-tools/
• Thêm kỹ năng — Yêu cầu agent tạo kỹ năng; tệp đi vào data/user/skills/
• Thay đổi hành vi — Yêu cầu agent áp dụng quy tắc toàn cục; nó được thêm vào data/user/instructions.md
• Cấu hình quyền — Chạy bun run permissions để kiểm soát công cụ nào agent có thể sử dụng
• Thêm công cụ tích hợp — Triển khai hàm công cụ mới trong src/tools.ts cho tích hợp sâu hơn (yêu cầu fork server)

Cấu Hình

#

Tất cả cài đặt được lưu trong .env (tạo bởi bun run setup). Tùy chọn chính:

Xem tham chiếu cấu hình đầy đủ tại kho GitHub.

Chạy Như Dịch Vụ

#

Cài đặt như dịch vụ liên tục khởi động tự động:

bun run service install

INSTANCE_NAME mặc định là basename của thư mục dự án sau khi bỏ tiền tố pockethook- (ví dụ: một checkout trong pockethook-agent-server/ trở thành agent-server). Đặt rõ ràng để chạy nhiều checkout trên cùng một máy mà không bị xung đột — mỗi instance giữ data/ và log riêng của nó.

Quản lý với bun run service status, restart, stop hoặc uninstall.

Bảo Mật

#

• Bắt buộc HTTPS — PocketHook yêu cầu HTTPS cho tất cả URL
• Xác thực bearer token — Khóa bí mật chia sẻ giữa ứng dụng và máy chủ
• Giới hạn tốc độ — Giới hạn theo token ngăn chặn lạm dụng
• Công cụ sandbox — Lệnh shell và truy cập tệp bị giới hạn bởi quyền
• Mẫu bị chặn — Lệnh nguy hiểm (sudo, rm -rf /) bị chặn mặc định
• Ranh giới thư mục làm việc — Agent không thể thoát khỏi thư mục được chỉ định
• Tệp nhạy cảm được bảo vệ — .env, .git, *.key, *.pem bị chặn khỏi quyền truy cập agent
• Quản lý phiên bản tự động — Tất cả thay đổi workspace được theo dõi git để dễ dàng khôi phục