# KengNote AI Agent Guide
> KengNote is a Markdown note system. This file is the short, AI-readable entry point.

## Start Here
> Follow this path first. It is the shortest route for another AI Agent to connect without guessing the UI.

- Site: https://kengnote.com/keng/
- API base: https://kengnote.com/keng/api
- Auth header: `Authorization: Bearer <personal_api_key>`
- Browser agents can often read the non-HttpOnly `keng_api_key` cookie after the user logs in.
- CLI agents should ask the user to open https://kengnote.com/keng/mykey.html and paste the current API Key.
- Always verify identity first with `GET /me`.
- Folder-path shorthand: `keng>folder>note title` means find the user's folder named `folder`, then the note whose first Markdown heading/title matches `note title`.
- Do not query imaginary tables such as `apiKeyTb`; API keys live on `user_tb.api_key` and should normally be accessed through the web UI/API only.
- `GET /me` includes `balance_cents` for display. Do not modify balances directly; wallet changes go through server payment/ledger APIs.
- `GET /me` returns finite `limitNote`; admin/king accounts use 100000 note slots, not unlimited.

## 3-Step Quick Start
```text
1. Auth: get the browser cookie `keng_api_key` or ask the user for https://kengnote.com/keng/mykey.html.
2. Verify: GET /me and confirm id/username are the user you are helping.
3. Work: GET /folders, GET /notes?q=keyword, then GET /notes/{id} before any PUT update. Note ids are scoped strings such as `personal:123` or `team:456`.
```

Minimal write test:
```bash
curl -H "Authorization: Bearer <personal_api_key>" \
   -H "Content-Type: application/json" \
   -d '{"content":"# Agent 接入测试\n这是一条测试笔记。","tags":["agent"],"folder_id":null}' \
   https://kengnote.com/keng/api/notes
```

## Core API
```text
GET    /me
GET    /notes?q=<keyword>
POST   /notes                       {"content":"# title\nbody","tags":[],"folder_id":null,"comment":""}
GET    /notes/{id}
PUT    /notes/{id}                  {"content":"...","tags":[]}
DELETE /notes/{id}
GET    /folders
POST   /folders                     {"name":"folder name"}
GET    /shared
POST   /notes/{id}/share            {"to_username":"...","permission":"read"}
POST   /notes/{id}/sharelink        {"expires_hours":24}
GET    /sharelinks/{token}/info
GET    /wallet?tab=income|expense|ledger
GET    /wallet/qrcode?url=...
POST   /alipay/order                 {"amount_cents":100}
GET    /alipay/orders/{order_no}
POST   /stripe/order                 {"amount_cents":100}
GET    /stripe/sessions/{session_id}
POST   /wallet/note-slots/purchase  {"slots":10}
GET    /me/ai-provider               read secretary model config (dialogue + vision blocks include provider_group/provider_label/base_url/model; no plaintext key)
POST   /me/ai-provider               {"dialogue":{"provider_group":"official","provider_label":"deepseek",...},"vision":{...}} save own dialogue/vision model (model name is user-entered; own key skips platform billing)
GET    /admin/users                  king only, q/page/page_size; includes ai_provider/ai_vision model summary fields
PUT    /admin/users/{uid}            king only, edit user fields/permissions
```

Use the `id` returned by `/notes` exactly as-is. Do not infer note type from numeric ranges; `raw_id` is only the database-local integer.

## Full
> Use these flows for real work.

1. Get the current user:
   `GET /me`
2. Resolve folders:
   `GET /folders`, match by `name`/`folder`.
3. List or search notes:
   `GET /notes` or `GET /notes?q=<keyword>`.
4. Read the exact note before modifying:
   `GET /notes/{id}`.
5. Update only the intended note:
   `PUT /notes/{id}` with the full new Markdown content.

## Auth Paths
### Browser Agent
```javascript
const apiKey = document.cookie.split(';')
  .map(c => c.trim())
  .find(c => c.startsWith('keng_api_key='))
  ?.split('=')[1];
```

### Session API
```text
GET https://kengnote.com/keng/api/my-key
```

### CLI Agent
Ask the user to open https://kengnote.com/keng/mykey.html, copy the key, then call APIs with:
```text
Authorization: Bearer <personal_api_key>
```

## Common Errors
- `401`: API Key is invalid, expired, or belongs to another user. Ask for the current key again.
- `403` with `code: "NOTE_SLOT_LIMIT"`: the user has no remaining personal note slots. Do not update or overwrite an existing note as a fallback; show `recharge_url` to the user and ask them to buy note slots or recharge first.
- Wallet records from `GET /wallet` include numeric amounts, `direction` (`income`/`expense`/`pending`), `pay_channel` for recharge records (`wechat`/`alipay`/`stripe`), and a `detail` label such as WeChat recharge, Alipay recharge, or note-slot purchase. Use `tab=income|expense|ledger` for income, expense, or combined ledger; old `recharge|consume|all` aliases still work.
- Alipay recharge uses PC web checkout (`alipay.trade.page.pay`): `POST /alipay/order` returns a `pay_url`; redirect the browser to it (`window.location.href`), and after Alipay redirects back to `settings.html?section=account` poll `GET /alipay/orders/{order_no}` to confirm credit. If the server has no app private key configured the API returns `ALIPAY_PAGEPAY_UNAVAILABLE`. Public Alipay notify/return URLs are under `/keng/api/alipay/...`.
- Stripe recharge uses Hosted Checkout: `POST /stripe/order` returns `checkout_url`, `session_id`, and `order_no`; redirect the browser to `checkout_url`, then after Stripe redirects back to `settings.html?section=account&pay=stripe&stripe_session_id=...`, poll `GET /stripe/sessions/{session_id}` to confirm credit. Webhook support is available at `POST /stripe/webhook` when `webhook_secret` is configured; otherwise the return/poll path still performs server-side Stripe session verification and idempotent crediting.
- Lucy attachments use SiliconFlow `PaddlePaddle/PaddleOCR-VL-1.5`. Pasted/uploaded images are queued as attachments and processed only after the user sends instructions. `POST /lucy/chat` accepts `enhanced`; external spider actions require `enhanced=true`, while note searches refresh the side list instead of printing internal result tables in chat.
- Empty list: call `GET /me` and `GET /folders` before assuming notes are missing.
- Wrong folder: resolve by folder id, not by display text guessed from the UI.
- Shared notes: use `GET /shared` for inbox-style shared notes.

Full manual: https://kengnote.com/keng/api/manual
---
**💡 个性化指南**：如果你知道用户的 API Key，在请求本端点时加上 `Authorization: Bearer <api_key>` 即可获取该用户的个性化指南（含用户名、apikey、可直接运行的命令）。

API Key 获取方式：用户登录 https://kengnote.com/keng/settings.html 后在"个人信息"中可查看。