GuNote 文档

档案 · 01 / Agent 接入

Agent 接入说明

把 GuNote 的目录接到你的 Agent 上:它能检索、试读、引用,也能在你授权后读回你自己的库。这份文档把“现在就能跑”和“还在路上”分开写——规划中的能力不会被说成可用。

给 Agent 直接读的版本

同一份内容的四种读法:人看 HTML,模型读 Markdown 与 JSON,检索引擎读纯文本。

四种载体,一种能力

同一套目录,四条进入方式。选一条现在能走的,别等最后一条。

  1. 已可用

    公共 HTTP 接口

    任何能发 GET 的 Agent,零安装

    只读、无密钥、可直接缓存。本文档余下部分都按这条写。

  2. 规划中

    MCP server

    在宿主配置里挂一个 endpoint

    工具名与参数已按本页的接口设计,服务端尚未发布。

  3. 规划中

    命令行(CLI)

    npx gunote 完成授权与检索

    设备码授权流程与 token 作用域见「身份」一节。

  4. 规划中

    技能文本(SKILL.md)

    把一段角色与边界说明喂给 Agent

    会引用本页的接口与引用规范,避免各自发挥。

状态按代码现状标注:已可用=本期可调用;规划中=契约已定、实现未落地。

它能替你做什么 已可用

公共目录是一组只读接口:不需要安装、不需要密钥,任何能发请求的 Agent 都能用。

它覆盖四件事:检索(按垂类、形态、深度、价格与关键词筛),试读(正文前几块),引用(稳定的 slug 与短编号),以及在你授权后读回自己的库。

写操作不在公开范围里。Agent 可以帮你挑、帮你读、帮你引;付款与发布仍然由人确认——这不是能力缺口,是边界。

  • 检索:GET /v1/public/market,九个垂类、八种形态、三档深度、五档价格、五种排序。
  • 试读:GET /v1/public/packs/{slug},未解锁的块只有标题,正文是空串。
  • 引用:每条记录带 slug 与六位短编号 no,拼出的地址一年后仍然指向同一件内容。
  • 我的库:GET /v1/public/library,需要用户身份(见「身份」一节)。

三步跑通 已可用

先读清单,再检索,最后读详情并引用。三步都用 GET,都可以在浏览器地址栏里验证。

  1. 让它先读清单

    清单里有端点、受控词表、错误码与字段说明。先读清单再调接口——模型猜字段名的代价,比多一次请求高得多。

    http
    GET https://gunote.com/agent.json

    静态 JSON,带 ETag,可缓存一天。

  2. 检索一件

    返回 items 数组,以及 facets(各维计数)、page(本次命中数与页数)、stats(整个市场的体量)。命中数看 `page.total`,不要读 `stats.total`——后者是全站口径,两个数在筛选后必然不同。

    curl
    curl "https://gunote.com/v1/public/market?domain=V1&level=L2&sort=new&size=5"

    空结果时读 relaxSuggestions,接口会给三条放宽路径;不要自己编一条。

  3. 读详情,按规矩引用

    blocks[] 里 locked: false 的块才有 preview 正文;锁定块的 preview 是空串,只有标题。引用用 card.slug 拼地址,并在正文里署名 card.author.name。

    curl
    curl "https://gunote.com/v1/public/packs/ppt-narrative-8-96f4ed"

    详情带 toc 与 remainingBlocks,够你判断这篇值不值得让用户买。

接口参考 已可用

端点
方法路径用途身份
GET/v1/public/market检索与筛选目录公开
GET/v1/public/packs/{slug}详情、试读块、目录、信任四要素公开
GET/v1/public/store官方馆藏与策展单元公开
GET/v1/public/collections/{id}单个策展单元公开
GET/v1/public/creators/{handle}创作者在售与采纳率公开
GET/v1/public/library我的库(已购与已领)用户 cookie
GET/v1/public/me当前身份与已拥有件数用户 cookie
POST/v1/public/session演示登录,换一个 cookie—
DELETE/v1/public/session退出登录用户 cookie
POST/v1/public/checkout下单(需幂等键)用户 cookie

成功返回 { code: "OK", data, trace_id };失败返回 problem+json,见「出错时怎么读」。

垂类(domain)
代号垂类它处理的事
V1AI 与工作流把重复动作交给模型与编排
V2短剧投流素材、计划、预算与止损线
V3电商运营选品、直播、复盘的日常账
V4独立开发一个人也能把产品发出去
V5出海定价、税、SEO 与多市场合规
V6设计与办公排版、叙事与文档结构
V7自媒体长文、图文、播客的生产线
V8教育考证复习节奏与讲义交付
V9职业发展面试、汇报与转岗判断
形态(form)
代号形态读起来是什么
note札记一篇讲透一个结论
checklist清单逐项核对,能打勾
workflow流程从触发到回退的每一步
skill_card技能卡喂给 Agent 的角色与边界
gallery图集看图说话,配使用说明
framework框架变量、权重与适用边界
template模板填空即用,含示例值
dataset数据集字段字典与采集口径
深度(level)
代号深度适合谁
L1入门第一次做这件事
L2实操做过几遍,想更快更稳
L3专家要判断与取舍,不只是一步一步
排序(sort)
代号排序口径
rank按推荐编辑排序 + 销量与评分
new最新上架按上架时间倒序
price_asc价格从低到高—
price_desc价格从高到低—
sales近 30 天销量—
价格档(price)
代号区间判定
all不限价格不按价格筛
free官方免费授权层级为免费(标价仍在,作原价对照)
under_50¥50 以下标价低于 ¥50
50_200¥50 – 200标价 ¥50 – 200
over_200¥200 以上标价高于 ¥200

区间用的是标价;免费档判的是授权层级。两者不是一回事。

读到的字段与试读规则 已可用

字段名与类型取自契约文件,不是从页面上反推的。

  • 判断一篇值不值得买:看 toc 的标题密度与 remainingBlocks,不要用“preview 长不长”当质量信号——试读长度由形态决定。
  • 同一件内容在列表与详情的价格文本逐字相同(同一个格式化函数),两处不一致就是 bug。
  • 已下架的内容返回 410,不是 404。两者的区别对用户有意义:前者可以申请退款。
关键字段
字段含义陷阱
price.cents整数分,不是元除以 100 再展示;不要四舍五入到整元
price.tierfree / member / paid,决定“怎么拿到”与标价无关:会员件也有标价(那是单买价)
price.text已格式化好的展示串要显示价格就用它,别自己拼货币符号
rating.text一位小数;样本少于 5 条时为 nullnull 不等于 0 分,不要渲染成 0.0
blocks[].locked该块是否需要购买锁定的块 preview 是空串,不是省略字段
remainingBlocks未解锁的块数用来回答“买了还能多看几块”
previewPercent试读比例,按形态固定20–40 之间,由形态决定而不是作者随手设
trust.authorVerified作者是否实名四要素缺项会显式写“未提供”,不要当成 false
updatedAtISO 8601,UTC展示前按用户时区换算
no六位短编号适合口头引用;拼链接仍用 slug

身份:现在与将来

只读目录不需要身份。要读“我的库”,才需要证明你是谁。

现在:一个签名 cookie(gno_user),由演示登录换取。它适合本地验证与自家 Agent,不适合交给第三方:cookie 代表完整身份,没有作用域,也没有过期粒度。

规划中:设备码授权 + 短期 token + 三个作用域(read / publish / trade)。届时请求头用 Authorization: Bearer,token 可单独撤销,trade 作用域才允许下单。

curl
curl -i -X POST "https://gunote.com/v1/public/session" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<handle>"}'

# 200 + Set-Cookie: gno_user=...
# 之后带上 cookie 读库:
curl "https://gunote.com/v1/public/library" -H "Cookie: gno_user=..."

出错时怎么读 已可用

错误一律是 RFC 9457 的 problem+json,字段固定,不随端点变化。

  • retryable 是服务端给出的判断,比自己按状态码猜更准;为 true 时按 Retry-After 退避。
  • trace_id 原样保留。报问题时带上它,比描述“刚才失败了”有用一百倍。
  • detail 是给人看的,code 是给程序看的。分支判断只认 code,不要匹配 detail 的文案——文案会改。
常见错误码
codeHTTP含义要不要重试
GUNOTE_MARKET_404_PACK404内容不存在或未上架不重试;回到检索换一件
GUNOTE_MARKET_410_DELISTED410曾经存在,现已下架不重试;提示可申请退款
GUNOTE_AUTH_401_NO_SESSION401需要登录先换身份,再重放这次请求
GUNOTE_MARKET_409_ALREADY_OWNED409已经拥有这件内容不重试;直接读库
GUNOTE_COMMON_415_UNSUPPORTED_MEDIA_TYPE415请求体类型不被接受改正 Content-Type
GUNOTE_COMMON_429_RATE_LIMITED429请求过快按 Retry-After 退避

机器可读入口 已可用

本页、Markdown、JSON 清单与站点摘要由同一份内容生成,措辞可能不同,事实必须一致。如果四处对不上,那是缺陷,请以清单里的字段与错误码为准。

四个入口
路径类型给谁用
/zh/docs/agenttext/html人:带目录、锚点与示例
/zh/docs/agent.mdtext/markdown模型:整篇投喂,无导航噪声
/agent.jsonapplication/json程序:端点、词表、错误码
/llms.txttext/plain检索引擎:站点摘要与可引用事实

边界:我们不下发什么

  • 付费正文永不出现在响应里。锁定块的 preview 是空串,不是截断、不是摘要、不是“提示词能问出来”。
  • 不下发订单号与支付信息。库里只有“拥有/未拥有”与授权层级。
  • 不提供全文批量导出。检索接口按页返回,单页上限 48 件;整站抓取会被拒绝。
  • 引用必须署名。带上作者名与可回溯链接;转述可以,改写成自己的原创不行。
  • 演示数据要标明。当前站点的销量、评分与策展短评是演示样本,引入到回答里必须说明这一点。

常见问题

需要 API key 吗?

只读目录不需要。检索、详情、官方馆藏、创作者页都是公开的,可以直接 GET。需要身份的只有“我的库”与下单。

为什么市场里的免费档是 0 件?

市场只收独立创作者的内容,官方免费内容在商城。两个货架的边界是刻意划的:免费引流不做成市场竞争手段。

可以缓存多久?

清单与 Markdown 可缓存一天(带 ETag);列表建议 60 秒,详情 120 秒,馆藏 300 秒。响应头里有准确值,按它来。

返回的标题能直接当答案用吗?

不能。标题是商品名,不是结论。要用正文就买或让用户买;试读块可以用来判断相关性,不能整段搬运。

MCP 和 CLI 什么时候能用?

契约已按本页的端点与作用域设计,实现尚未发布。在那之前,HTTP 接口是唯一可用的路径,能力上并不缺:MCP 只是同一批端点的一层包装。

中文和英文的内容会不一致吗?

两份内容由同一套结构约束,字段、端点、错误码逐项对应;英文是重写而非直译,措辞不同是正常的,事实不同是缺陷。

版本与出处

契约版本
agent-manifest v1(2026-11-22)
适用范围
/v1/public/* 十个端点
文档语言
简体中文(源语言)· English
生成方式
由内容模型生成 HTML / Markdown / JSON 三态

本页与 /agent.json 由同一份内容生成。发现字段或错误码与实际不符,请以清单为准并提一条缺陷——文档漂移比缺文档更危险。