better-dsh 0.2.4-a → 0.2.4-b

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/productivity/productivity-shopify.md

@@ -1,377 +0,0 @@
----
-title: "Shopify — 通过 curl 使用 Shopify Admin 与 Storefront GraphQL API"
-sidebar_label: "Shopify"
-description: "通过 curl 使用 Shopify Admin 与 Storefront GraphQL API"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Shopify
-
-通过 curl 使用 Shopify Admin 与 Storefront GraphQL API。涵盖商品、订单、客户、库存、metafield。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 可选 — 通过 `hermes skills install official/productivity/shopify` 安装 |
-| 路径 | `optional-skills/productivity/shopify` |
-| 版本 | `1.0.0` |
-| 作者 | community |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `Shopify`, `E-commerce`, `Commerce`, `API`, `GraphQL` |
-| 相关 skill | [`airtable`](/user-guide/skills/bundled/productivity/productivity-airtable), [`xurl`](/user-guide/skills/bundled/social-media/social-media-xurl) |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
-:::
-
-# Shopify — Admin 与 Storefront GraphQL API
-
-通过 `curl` 直接操作 Shopify 店铺：列出商品、管理库存、拉取订单、更新客户、读取 metafield。无需 SDK，无需应用框架——只需 GraphQL 端点和自定义应用访问令牌。
-
-REST Admin API 自 2024-04 起已进入遗留状态，仅接受安全修复。**所有管理操作请使用 GraphQL Admin**。面向客户的只读查询（商品、集合、购物车）请使用 **Storefront GraphQL**。
-
-## 前置条件
-
-1. 在 Shopify 管理后台：**Settings → Apps and sales channels → Develop apps → Create an app**。
-2. 点击 **Configure Admin API scopes**，选择所需权限（见下方示例），保存。
-3. **Install app** → Admin API 访问令牌仅显示一次。立即复制——Shopify 不会再次展示。令牌以 `shpat_` 开头。
-4. 保存至 `~/.hermes/.env`：
-   ```
-   SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxx
-   SHOPIFY_STORE_DOMAIN=my-store.myshopify.com
-   SHOPIFY_API_VERSION=2026-01
-   ```
-
-> **注意：** 自 2026 年 1 月 1 日起，在 Shopify 管理后台新建"旧版自定义应用"的功能已停用。新配置应使用 **Dev Dashboard**（`shopify.dev/docs/apps/build/dev-dashboard`）。已有的管理后台创建的应用继续有效。如果用户的店铺没有现有自定义应用且时间在 2026-01-01 之后，请引导其使用 Dev Dashboard 而非管理后台流程。
-
-常用权限范围（scope）按任务分类：
-- 商品 / 集合：`read_products`、`write_products`
-- 库存：`read_inventory`、`write_inventory`、`read_locations`
-- 订单：`read_orders`、`write_orders`（不含 `read_all_orders` 时仅返回最近 30 条）
-- 客户：`read_customers`、`write_customers`
-- 草稿订单：`read_draft_orders`、`write_draft_orders`
-- 履约：`read_fulfillments`、`write_fulfillments`
-- Metafield / metaobject：由对应资源的 scope 覆盖
-
-## API 基础
-
-- **端点：** `https://$SHOPIFY_STORE_DOMAIN/admin/api/$SHOPIFY_API_VERSION/graphql.json`
-- **认证头：** `X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN`（**不是** `Authorization: Bearer`）
-- **方法：** 始终为 `POST`，始终使用 `Content-Type: application/json`，请求体为 `{"query": "...", "variables": {...}}`
-- **HTTP 200 不代表成功。** GraphQL 在顶层 `errors` 数组和各字段的 `userErrors` 中返回错误。两者都需检查。
-- **ID 为 GID 字符串：** `gid://shopify/Product/10079467700516`、`gid://shopify/Variant/...`、`gid://shopify/Order/...`。原样传入——不要去掉前缀。
-- **速率限制：** 基于查询消耗（leaky bucket）计算。每个响应的 `extensions.cost` 包含 `requestedQueryCost`、`actualQueryCost`、`throttleStatus.{currentlyAvailable, maximumAvailable, restoreRate}`。当 `currentlyAvailable` 低于下一次查询消耗时退避。标准店铺 = 100 点桶，50/s 恢复；Plus = 1000/100。
-
-基础 curl 模式（可复用）：
-
-```bash
-shop_gql() {
-  local query="$1"
-  local variables="${2:-{}}"
-  curl -sS -X POST \
-    "https://${SHOPIFY_STORE_DOMAIN}/admin/api/${SHOPIFY_API_VERSION:-2026-01}/graphql.json" \
-    -H "Content-Type: application/json" \
-    -H "X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}" \
-    --data "$(jq -nc --arg q "$query" --argjson v "$variables" '{query: $q, variables: $v}')"
-}
-```
-
-通过管道传给 `jq` 以获得可读输出。`-sS` 保留错误可见性同时隐藏进度条。
-
-## 发现
-
-### 店铺信息 + 当前 API 版本
-```bash
-shop_gql '{ shop { name myshopifyDomain primaryDomain { url } currencyCode plan { displayName } } }' | jq
-```
-
-### 列出所有支持的 API 版本
-```bash
-shop_gql '{ publicApiVersions { handle supported } }' | jq '.data.publicApiVersions[] | select(.supported)'
-```
-
-## 商品
-
-### 搜索商品（前 20 条匹配结果）
-```bash
-shop_gql '
-query($q: String!) {
-  products(first: 20, query: $q) {
-    edges { node { id title handle status totalInventory variants(first: 5) { edges { node { id sku price inventoryQuantity } } } } }
-    pageInfo { hasNextPage endCursor }
-  }
-}' '{"q":"hoodie status:active"}' | jq
-```
-
-查询语法支持 `title:`、`sku:`、`vendor:`、`product_type:`、`status:active`、`tag:`、`created_at:>2025-01-01`。完整语法：https://shopify.dev/docs/api/usage/search-syntax
-
-### 分页获取商品（游标）
-```bash
-shop_gql '
-query($cursor: String) {
-  products(first: 100, after: $cursor) {
-    edges { cursor node { id handle } }
-    pageInfo { hasNextPage endCursor }
-  }
-}' '{"cursor":null}'
-# 后续调用：传入上一次的 endCursor
-```
-
-### 获取商品（含变体 + metafield）
-```bash
-shop_gql '
-query($id: ID!) {
-  product(id: $id) {
-    id title handle descriptionHtml tags status
-    variants(first: 20) { edges { node { id sku price compareAtPrice inventoryQuantity selectedOptions { name value } } } }
-    metafields(first: 20) { edges { node { namespace key type value } } }
-  }
-}' '{"id":"gid://shopify/Product/10079467700516"}' | jq
-```
-
-### 创建含一个变体的商品
-```bash
-shop_gql '
-mutation($input: ProductCreateInput!) {
-  productCreate(product: $input) {
-    product { id handle }
-    userErrors { field message }
-  }
-}' '{"input":{"title":"Test Hoodie","status":"DRAFT","vendor":"Hermes","productType":"Apparel","tags":["test"]}}'
-```
-
-新版本中变体有独立的 mutation：
-
-```bash
-# 创建商品后添加变体
-shop_gql '
-mutation($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
-  productVariantsBulkCreate(productId: $productId, variants: $variants) {
-    productVariants { id sku price }
-    userErrors { field message }
-  }
-}' '{"productId":"gid://shopify/Product/...","variants":[{"optionValues":[{"optionName":"Size","name":"M"}],"price":"49.00","inventoryItem":{"sku":"HD-M","tracked":true}}]}'
-```
-
-### 更新价格 / SKU
-```bash
-shop_gql '
-mutation($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
-  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
-    productVariants { id sku price }
-    userErrors { field message }
-  }
-}' '{"productId":"gid://shopify/Product/...","variants":[{"id":"gid://shopify/ProductVariant/...","price":"55.00"}]}'
-```
-
-## 订单
-
-### 列出最近订单（不含 `read_all_orders` 时默认最多 30 条）
-```bash
-shop_gql '
-{
-  orders(first: 20, reverse: true, query: "financial_status:paid") {
-    edges { node {
-      id name createdAt displayFinancialStatus displayFulfillmentStatus
-      totalPriceSet { shopMoney { amount currencyCode } }
-      customer { id displayName email }
-      lineItems(first: 10) { edges { node { title quantity sku } } }
-    } }
-  }
-}' | jq
-```
-
-常用订单查询过滤器：`financial_status:paid|pending|refunded`、`fulfillment_status:unfulfilled|fulfilled`、`created_at:>2025-01-01`、`tag:gift`、`email:foo@example.com`。
-
-### 获取单个订单（含收货地址）
-```bash
-shop_gql '
-query($id: ID!) {
-  order(id: $id) {
-    id name email
-    shippingAddress { name address1 address2 city province country zip phone }
-    lineItems(first: 50) { edges { node { title quantity variant { sku } originalUnitPriceSet { shopMoney { amount currencyCode } } } } }
-    transactions { id kind status amountSet { shopMoney { amount currencyCode } } }
-  }
-}' '{"id":"gid://shopify/Order/...."}' | jq
-```
-
-## 客户
-
-```bash
-# 搜索
-shop_gql '
-{
-  customers(first: 10, query: "email:*@example.com") {
-    edges { node { id email displayName numberOfOrders amountSpent { amount currencyCode } } }
-  }
-}'
-
-# 创建
-shop_gql '
-mutation($input: CustomerInput!) {
-  customerCreate(input: $input) {
-    customer { id email }
-    userErrors { field message }
-  }
-}' '{"input":{"email":"test@example.com","firstName":"Test","lastName":"User","tags":["api-created"]}}'
-```
-
-## 库存
-
-库存挂载在与变体关联的**库存项目**上，数量按**仓库位置**跟踪。
-
-```bash
-# 获取某变体在所有仓库的库存
-shop_gql '
-query($id: ID!) {
-  productVariant(id: $id) {
-    id sku
-    inventoryItem {
-      id tracked
-      inventoryLevels(first: 10) {
-        edges { node { location { id name } quantities(names: ["available","on_hand","committed"]) { name quantity } } }
-      }
-    }
-  }
-}' '{"id":"gid://shopify/ProductVariant/..."}'
-```
-
-调整库存（增量）— 使用 `inventoryAdjustQuantities`：
-
-```bash
-shop_gql '
-mutation($input: InventoryAdjustQuantitiesInput!) {
-  inventoryAdjustQuantities(input: $input) {
-    inventoryAdjustmentGroup { reason changes { name delta } }
-    userErrors { field message }
-  }
-}' '{
-  "input": {
-    "reason": "correction",
-    "name": "available",
-    "changes": [{"delta": 5, "inventoryItemId": "gid://shopify/InventoryItem/...", "locationId": "gid://shopify/Location/..."}]
-  }
-}'
-```
-
-设置绝对库存（非增量）— `inventorySetQuantities`：
-
-```bash
-shop_gql '
-mutation($input: InventorySetQuantitiesInput!) {
-  inventorySetQuantities(input: $input) {
-    inventoryAdjustmentGroup { id }
-    userErrors { field message }
-  }
-}' '{"input":{"reason":"correction","name":"available","ignoreCompareQuantity":true,"quantities":[{"inventoryItemId":"gid://shopify/InventoryItem/...","locationId":"gid://shopify/Location/...","quantity":100}]}}'
-```
-
-## Metafield 与 Metaobject
-
-Metafield 用于为资源（商品、客户、订单、店铺）附加自定义数据。
-
-```bash
-# 读取
-shop_gql '
-query($id: ID!) {
-  product(id: $id) {
-    metafields(first: 10, namespace: "custom") {
-      edges { node { key type value } }
-    }
-  }
-}' '{"id":"gid://shopify/Product/..."}'
-
-# 写入（适用于任意 owner 类型）
-shop_gql '
-mutation($metafields: [MetafieldsSetInput!]!) {
-  metafieldsSet(metafields: $metafields) {
-    metafields { id key namespace }
-    userErrors { field message code }
-  }
-}' '{"metafields":[{"ownerId":"gid://shopify/Product/...","namespace":"custom","key":"care_instructions","type":"multi_line_text_field","value":"Wash cold. Tumble dry low."}]}'
-```
-
-## Storefront API（公开只读）
-
-使用不同的端点和令牌，适用于面向客户的应用或 Hydrogen 风格的 headless 配置。请求头有所不同：
-
-- **端点：** `https://$SHOPIFY_STORE_DOMAIN/api/$SHOPIFY_API_VERSION/graphql.json`
-- **认证头（公开）：** `X-Shopify-Storefront-Access-Token: <public token>` — 可嵌入浏览器
-- **认证头（私有）：** `Shopify-Storefront-Private-Token: <private token>` — 仅限服务端
-
-```bash
-curl -sS -X POST \
-  "https://${SHOPIFY_STORE_DOMAIN}/api/${SHOPIFY_API_VERSION:-2026-01}/graphql.json" \
-  -H "Content-Type: application/json" \
-  -H "X-Shopify-Storefront-Access-Token: ${SHOPIFY_STOREFRONT_TOKEN}" \
-  -d '{"query":"{ shop { name } products(first: 5) { edges { node { id title handle } } } }"}' | jq
-```
-
-## 批量操作
-
-适用于超出速率限制的大批量数据导出（完整商品目录、全年订单）：
-
-```bash
-# 1. 启动批量查询
-shop_gql '
-mutation {
-  bulkOperationRunQuery(query: """
-    { products { edges { node { id title handle variants { edges { node { sku price } } } } } } }
-  """) {
-    bulkOperation { id status }
-    userErrors { field message }
-  }
-}'
-
-# 2. 轮询状态
-shop_gql '{ currentBulkOperation { id status errorCode objectCount fileSize url partialDataUrl } }'
-
-# 3. 状态为 COMPLETED 时下载 JSONL 文件
-curl -sS "$URL" > products.jsonl
-```
-
-每行 JSONL 为一个节点，嵌套连接以独立行输出并附带 `__parentId`。如有需要，在客户端重新组装。
-
-## Webhook
-
-订阅事件以避免轮询：
-
-```bash
-shop_gql '
-mutation($topic: WebhookSubscriptionTopic!, $sub: WebhookSubscriptionInput!) {
-  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $sub) {
-    webhookSubscription { id topic endpoint { __typename ... on WebhookHttpEndpoint { callbackUrl } } }
-    userErrors { field message }
-  }
-}' '{"topic":"ORDERS_CREATE","sub":{"callbackUrl":"https://example.com/webhook","format":"JSON"}}'
-```
-
-使用应用的 client secret（非访问令牌）验证传入 webhook 的 HMAC：
-
-```bash
-echo -n "$REQUEST_BODY" | openssl dgst -sha256 -hmac "$APP_SECRET" -binary | base64
-# 与 X-Shopify-Hmac-Sha256 请求头比对
-```
-
-## 常见陷阱
-
-- **REST 端点仍然存在但已冻结。** 不要针对 `/admin/api/.../products.json` 编写新集成，请使用 GraphQL。
-- **令牌格式检查。** Admin 令牌以 `shpat_` 开头，Storefront 公开令牌以 `shpua_` 开头。若令牌正确但请求头错误，每次请求都会返回 401 且无有效错误信息。
-- **令牌有效但返回 403 = 缺少 scope。** Shopify 返回 `{"errors":[{"message":"Access denied for ..."}]}`。在应用上重新配置 Admin API scope，然后重新安装以重新生成令牌。
-- **`userErrors` 为空 ≠ 成功。** 还需检查 `data.<mutation>.<resource>` 是否非空。某些失败两者均不填充——请检查完整响应。
-- **GID 与数字 ID。** 旧版 REST 返回数字 ID；GraphQL 需要完整 GID 字符串。转换方式：`gid://shopify/Product/<numeric>`。
-- **速率限制意外。** 单次深度嵌套的 `products(first: 250)` 可能消耗 1000+ 点，在标准套餐店铺上立即触发限流。从小范围开始，读取 `extensions.cost`，再做调整。
-- **分页排序。** `products(first: N, reverse: true)` 按 `id DESC` 排序，而非 `created_at`。若需"最新优先"，请使用 `sortKey: CREATED_AT, reverse: true`。
-- **历史数据需要 `read_all_orders`。** 不含此 scope 时，`orders(...)` 会静默限制在 60 天窗口内。不会报错，只是结果比预期少。对于订单量大的 Shopify Plus 商户，请通过应用的受保护数据设置申请此 scope。
-- **货币金额为字符串。** 金额以 `"49.00"` 而非 `49.0` 返回。若关心零填充，不要盲目使用 `jq tonumber`。
-- **多货币 Money 字段** 同时包含 `shopMoney`（店铺货币）和 `presentmentMoney`（客户货币）。请保持一致地选择其中一个。
-
-## 安全须知
-
-Shopify 中的 mutation 操作是真实生效的——它们会创建商品、执行退款、取消订单、发货。在执行 `productDelete`、`orderCancel`、`refundCreate` 或任何批量 mutation 之前：请明确说明变更内容、所在店铺，并与用户确认。除非用户有独立的开发店铺，否则不存在生产数据的暂存副本。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/productivity/productivity-siyuan.md

@@ -1,305 +0,0 @@
----
-title: "Siyuan"
-sidebar_label: "Siyuan"
-description: "通过 curl 调用 SiYuan Note API，在自托管知识库中搜索、读取、创建和管理块与文档"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Siyuan
-
-通过 curl 调用 SiYuan Note API，在自托管知识库中搜索、读取、创建和管理块与文档。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 可选 — 使用 `hermes skills install official/productivity/siyuan` 安装 |
-| 路径 | `optional-skills/productivity/siyuan` |
-| 版本 | `1.0.0` |
-| 作者 | FEUAZUR |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `SiYuan`, `Notes`, `Knowledge Base`, `PKM`, `API` |
-| 相关 skill | [`obsidian`](/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`notion`](/user-guide/skills/bundled/productivity/productivity-notion) |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
-:::
-
-# SiYuan Note API
-
-通过 curl 调用 [SiYuan](https://github.com/siyuan-note/siyuan) 内核 API，在自托管知识库中搜索、读取、创建、更新和删除块与文档。无需额外工具 — 只需 curl 和 API token。
-
-## 前提条件
-
-1. 安装并运行 SiYuan（桌面版或 Docker）
-2. 获取 API token：**设置 > 关于 > API token**
-3. 将其存储在 `~/.hermes/.env` 中：
-   ```
-   SIYUAN_TOKEN=your_token_here
-   SIYUAN_URL=http://127.0.0.1:6806
-   ```
-   若未设置，`SIYUAN_URL` 默认为 `http://127.0.0.1:6806`。
-
-## API 基础
-
-所有 SiYuan API 调用均为 **POST 请求，携带 JSON 请求体**。每个请求遵循以下模式：
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/..." \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"param": "value"}'
-```
-
-响应为 JSON，结构如下：
-```json
-{"code": 0, "msg": "", "data": { ... }}
-```
-`code: 0` 表示成功。其他值均为错误 — 请检查 `msg` 获取详情。
-
-**ID 格式：** SiYuan ID 形如 `20210808180117-6v0mkxr`（14 位时间戳 + 7 位字母数字字符）。
-
-## 快速参考
-
-| 操作 | 端点 |
-|-----------|----------|
-| 全文搜索 | `/api/search/fullTextSearchBlock` |
-| SQL 查询 | `/api/query/sql` |
-| 读取块 | `/api/block/getBlockKramdown` |
-| 读取子块 | `/api/block/getChildBlocks` |
-| 获取路径 | `/api/filetree/getHPathByID` |
-| 获取属性 | `/api/attr/getBlockAttrs` |
-| 列出笔记本 | `/api/notebook/lsNotebooks` |
-| 列出文档 | `/api/filetree/listDocsByPath` |
-| 创建笔记本 | `/api/notebook/createNotebook` |
-| 创建文档 | `/api/filetree/createDocWithMd` |
-| 追加块 | `/api/block/appendBlock` |
-| 更新块 | `/api/block/updateBlock` |
-| 重命名文档 | `/api/filetree/renameDocByID` |
-| 设置属性 | `/api/attr/setBlockAttrs` |
-| 删除块 | `/api/block/deleteBlock` |
-| 删除文档 | `/api/filetree/removeDocByID` |
-| 导出为 Markdown | `/api/export/exportMdContent` |
-
-## 常用操作
-
-### 搜索（全文）
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/search/fullTextSearchBlock" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"query": "meeting notes", "page": 0}' | jq '.data.blocks[:5]'
-```
-
-### 搜索（SQL）
-
-直接查询块数据库。仅 SELECT 语句是安全的。
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/query/sql" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"stmt": "SELECT id, content, type, box FROM blocks WHERE content LIKE '\''%keyword%'\'' AND type='\''p'\'' LIMIT 20"}' | jq '.data'
-```
-
-常用列：`id`、`parent_id`、`root_id`、`box`（笔记本 ID）、`path`、`content`、`type`、`subtype`、`created`、`updated`。
-
-### 读取块内容
-
-以 Kramdown（类 Markdown）格式返回块内容。
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getBlockKramdown" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'
-```
-
-### 读取子块
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getChildBlocks" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
-```
-
-### 获取人类可读路径
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/getHPathByID" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
-```
-
-### 获取块属性
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/getBlockAttrs" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
-```
-
-### 列出笔记本
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/lsNotebooks" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{}' | jq '.data.notebooks[] | {id, name, closed}'
-```
-
-### 列出笔记本中的文档
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/listDocsByPath" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"notebook": "NOTEBOOK_ID", "path": "/"}' | jq '.data.files[] | {id, name}'
-```
-
-### 创建文档
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/createDocWithMd" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "notebook": "NOTEBOOK_ID",
-    "path": "/Meeting Notes/2026-03-22",
-    "markdown": "# Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
-  }' | jq '.data'
-```
-
-### 创建笔记本
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/createNotebook" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "My New Notebook"}' | jq '.data.notebook.id'
-```
-
-### 向文档追加块
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/appendBlock" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "parentID": "DOCUMENT_OR_BLOCK_ID",
-    "data": "New paragraph added at the end.",
-    "dataType": "markdown"
-  }' | jq '.data'
-```
-
-另有：`/api/block/prependBlock`（参数相同，在开头插入）和 `/api/block/insertBlock`（使用 `previousID` 代替 `parentID`，在指定块之后插入）。
-
-### 更新块内容
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/updateBlock" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "id": "BLOCK_ID",
-    "data": "Updated content here.",
-    "dataType": "markdown"
-  }' | jq '.data'
-```
-
-### 重命名文档
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/renameDocByID" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "DOCUMENT_ID", "title": "New Title"}'
-```
-
-### 设置块属性
-
-自定义属性必须以 `custom-` 为前缀：
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/setBlockAttrs" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "id": "BLOCK_ID",
-    "attrs": {
-      "custom-status": "reviewed",
-      "custom-priority": "high"
-    }
-  }'
-```
-
-### 删除块
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/deleteBlock" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "BLOCK_ID"}'
-```
-
-删除整个文档：使用 `/api/filetree/removeDocByID`，参数为 `{"id": "DOC_ID"}`。
-删除笔记本：使用 `/api/notebook/removeNotebook`，参数为 `{"notebook": "NOTEBOOK_ID"}`。
-
-### 将文档导出为 Markdown
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/export/exportMdContent" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "DOCUMENT_ID"}' | jq -r '.data.content'
-```
-
-## 块类型
-
-SQL 查询中常见的 `type` 值：
-
-| 类型 | 描述 |
-|------|-------------|
-| `d` | 文档（根块） |
-| `p` | 段落 |
-| `h` | 标题 |
-| `l` | 列表 |
-| `i` | 列表项 |
-| `c` | 代码块 |
-| `m` | 数学块 |
-| `t` | 表格 |
-| `b` | 引用块 |
-| `s` | 超级块 |
-| `html` | HTML 块 |
-
-## 注意事项
-
-- **所有端点均为 POST** — 即使是只读操作也不例外。不要使用 GET。
-- **SQL 安全性**：仅使用 SELECT 查询。INSERT/UPDATE/DELETE/DROP 有危险，绝不应发送。
-- **ID 校验**：ID 匹配模式 `YYYYMMDDHHmmss-xxxxxxx`。不符合此模式的应予以拒绝。
-- **错误响应**：处理 `data` 之前，始终检查响应中的 `code != 0`。
-- **大型文档**：块内容和导出结果可能非常大。SQL 中使用 `LIMIT`，并通过 `jq` 管道仅提取所需内容。
-- **笔记本 ID**：操作特定笔记本时，先通过 `lsNotebooks` 获取其 ID。
-
-## 替代方案：MCP Server
-
-如果您更倾向于使用原生集成而非 curl，可安装 SiYuan MCP server：
-
-```yaml
-# In ~/.hermes/config.yaml under mcp_servers:
-mcp_servers:
-  siyuan:
-    command: npx
-    args: ["-y", "@porkll/siyuan-mcp"]
-    env:
-      SIYUAN_TOKEN: "your_token"
-      SIYUAN_URL: "http://127.0.0.1:6806"
-```