它能替你做什么 已可用
公共目录是一组只读接口:不需要安装、不需要密钥,任何能发请求的 Agent 都能用。
它覆盖四件事:检索(按垂类、形态、深度、价格与关键词筛),试读(正文前几块),引用(稳定的 slug 与短编号),以及在你授权后读回自己的库。
写操作不在公开范围里。Agent 可以帮你挑、帮你读、帮你引;付款与发布仍然由人确认——这不是能力缺口,是边界。
- 检索:
GET /v1/public/market,九个垂类、八种形态、三档深度、五档价格、五种排序。 - 试读:
GET /v1/public/packs/{slug},未解锁的块只有标题,正文是空串。 - 引用:每条记录带
slug与六位短编号no,拼出的地址一年后仍然指向同一件内容。 - 我的库:
GET /v1/public/library,需要用户身份(见「身份」一节)。
三步跑通 已可用
先读清单,再检索,最后读详情并引用。三步都用 GET,都可以在浏览器地址栏里验证。
-
让它先读清单
清单里有端点、受控词表、错误码与字段说明。先读清单再调接口——模型猜字段名的代价,比多一次请求高得多。
http GET https://gunote.com/agent.json静态 JSON,带 ETag,可缓存一天。
-
检索一件
返回
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,接口会给三条放宽路径;不要自己编一条。 -
读详情,按规矩引用
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,见「出错时怎么读」。
| 代号 | 垂类 | 它处理的事 |
|---|---|---|
| V1 | AI 与工作流 | 把重复动作交给模型与编排 |
| V2 | 短剧投流 | 素材、计划、预算与止损线 |
| V3 | 电商运营 | 选品、直播、复盘的日常账 |
| V4 | 独立开发 | 一个人也能把产品发出去 |
| V5 | 出海 | 定价、税、SEO 与多市场合规 |
| V6 | 设计与办公 | 排版、叙事与文档结构 |
| V7 | 自媒体 | 长文、图文、播客的生产线 |
| V8 | 教育考证 | 复习节奏与讲义交付 |
| V9 | 职业发展 | 面试、汇报与转岗判断 |
| 代号 | 形态 | 读起来是什么 |
|---|---|---|
| note | 札记 | 一篇讲透一个结论 |
| checklist | 清单 | 逐项核对,能打勾 |
| workflow | 流程 | 从触发到回退的每一步 |
| skill_card | 技能卡 | 喂给 Agent 的角色与边界 |
| gallery | 图集 | 看图说话,配使用说明 |
| framework | 框架 | 变量、权重与适用边界 |
| template | 模板 | 填空即用,含示例值 |
| dataset | 数据集 | 字段字典与采集口径 |
| 代号 | 深度 | 适合谁 |
|---|---|---|
| L1 | 入门 | 第一次做这件事 |
| L2 | 实操 | 做过几遍,想更快更稳 |
| L3 | 专家 | 要判断与取舍,不只是一步一步 |
| 代号 | 排序 | 口径 |
|---|---|---|
| rank | 按推荐 | 编辑排序 + 销量与评分 |
| new | 最新上架 | 按上架时间倒序 |
| price_asc | 价格从低到高 | — |
| price_desc | 价格从高到低 | — |
| sales | 近 30 天销量 | — |
| 代号 | 区间 | 判定 |
|---|---|---|
| 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.tier | free / member / paid,决定“怎么拿到” | 与标价无关:会员件也有标价(那是单买价) |
| price.text | 已格式化好的展示串 | 要显示价格就用它,别自己拼货币符号 |
| rating.text | 一位小数;样本少于 5 条时为 null | null 不等于 0 分,不要渲染成 0.0 |
| blocks[].locked | 该块是否需要购买 | 锁定的块 preview 是空串,不是省略字段 |
| remainingBlocks | 未解锁的块数 | 用来回答“买了还能多看几块” |
| previewPercent | 试读比例,按形态固定 | 20–40 之间,由形态决定而不是作者随手设 |
| trust.authorVerified | 作者是否实名 | 四要素缺项会显式写“未提供”,不要当成 false |
| updatedAt | ISO 8601,UTC | 展示前按用户时区换算 |
| no | 六位短编号 | 适合口头引用;拼链接仍用 slug |
身份:现在与将来
只读目录不需要身份。要读“我的库”,才需要证明你是谁。
现在:一个签名 cookie(gno_user),由演示登录换取。它适合本地验证与自家 Agent,不适合交给第三方:cookie 代表完整身份,没有作用域,也没有过期粒度。
规划中:设备码授权 + 短期 token + 三个作用域(read / publish / trade)。届时请求头用 Authorization: Bearer,token 可单独撤销,trade 作用域才允许下单。
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的文案——文案会改。
| code | HTTP | 含义 | 要不要重试 |
|---|---|---|---|
| GUNOTE_MARKET_404_PACK | 404 | 内容不存在或未上架 | 不重试;回到检索换一件 |
| GUNOTE_MARKET_410_DELISTED | 410 | 曾经存在,现已下架 | 不重试;提示可申请退款 |
| GUNOTE_AUTH_401_NO_SESSION | 401 | 需要登录 | 先换身份,再重放这次请求 |
| GUNOTE_MARKET_409_ALREADY_OWNED | 409 | 已经拥有这件内容 | 不重试;直接读库 |
| GUNOTE_COMMON_415_UNSUPPORTED_MEDIA_TYPE | 415 | 请求体类型不被接受 | 改正 Content-Type |
| GUNOTE_COMMON_429_RATE_LIMITED | 429 | 请求过快 | 按 Retry-After 退避 |
机器可读入口 已可用
本页、Markdown、JSON 清单与站点摘要由同一份内容生成,措辞可能不同,事实必须一致。如果四处对不上,那是缺陷,请以清单里的字段与错误码为准。
| 路径 | 类型 | 给谁用 |
|---|---|---|
| /zh/docs/agent | text/html | 人:带目录、锚点与示例 |
| /zh/docs/agent.md | text/markdown | 模型:整篇投喂,无导航噪声 |
| /agent.json | application/json | 程序:端点、词表、错误码 |
| /llms.txt | text/plain | 检索引擎:站点摘要与可引用事实 |
边界:我们不下发什么
- 付费正文永不出现在响应里。锁定块的
preview是空串,不是截断、不是摘要、不是“提示词能问出来”。 - 不下发订单号与支付信息。库里只有“拥有/未拥有”与授权层级。
- 不提供全文批量导出。检索接口按页返回,单页上限 48 件;整站抓取会被拒绝。
- 引用必须署名。带上作者名与可回溯链接;转述可以,改写成自己的原创不行。
- 演示数据要标明。当前站点的销量、评分与策展短评是演示样本,引入到回答里必须说明这一点。
常见问题
需要 API key 吗?
只读目录不需要。检索、详情、官方馆藏、创作者页都是公开的,可以直接 GET。需要身份的只有“我的库”与下单。
为什么市场里的免费档是 0 件?
市场只收独立创作者的内容,官方免费内容在商城。两个货架的边界是刻意划的:免费引流不做成市场竞争手段。
可以缓存多久?
清单与 Markdown 可缓存一天(带 ETag);列表建议 60 秒,详情 120 秒,馆藏 300 秒。响应头里有准确值,按它来。
返回的标题能直接当答案用吗?
不能。标题是商品名,不是结论。要用正文就买或让用户买;试读块可以用来判断相关性,不能整段搬运。
MCP 和 CLI 什么时候能用?
契约已按本页的端点与作用域设计,实现尚未发布。在那之前,HTTP 接口是唯一可用的路径,能力上并不缺:MCP 只是同一批端点的一层包装。
中文和英文的内容会不一致吗?
两份内容由同一套结构约束,字段、端点、错误码逐项对应;英文是重写而非直译,措辞不同是正常的,事实不同是缺陷。