guide

package
v2.0.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package guide 是随二进制内嵌的「使用手册」:docs/ 目录里的 Markdown 文档,经 MCP 工具 usage_guide 按需读取。

目的:接入的智能体不会用某个功能时,可以直接查手册(而不是凭记忆回答),用户也可以一句话让会话自己去查。 手册随 Hub 的版本一起发布,所以描述的就是这个 Hub 现在能做的事,不会出现「文档比程序新或旧」。

这个包只负责「有哪些主题、怎么按标题 / 关键词取内容」,不依赖数据库,也不知道 MCP;工具层在 internal/mcp。

Index

Constants

This section is empty.

Variables

View Source
var Default = New(docs.FS, registry)

Default 是随二进制内嵌的手册:docs/ 下的全部 Markdown,主题登记在 topics.go。

Functions

This section is empty.

Types

type Guide

type Guide struct {
	// contains filtered or unexported fields
}

Guide 是一组主题与它们的内容。

func New

func New(fsys fs.FS, topics []Topic) *Guide

New 用给定的文件系统与主题登记表建一个 Guide(测试用合成文档;正式使用见 Default)。

func (*Guide) Body

func (g *Guide) Body(t Topic) (string, error)

Body 返回主题的 Markdown 全文。

func (*Guide) Info

func (g *Guide) Info(t Topic) (Info, error)

Info 返回主题的体量。

func (*Guide) Lookup

func (g *Guide) Lookup(ref string) (Topic, bool)

Lookup 按标识取主题:不区分大小写,也接受文件名(带或不带 .md)。

func (*Guide) Outline

func (g *Guide) Outline(t Topic, maxLevel int) ([]idocs.Heading, error)

Outline 返回主题的标题大纲(一到 maxLevel 级;maxLevel<=0 表示三级)。

func (*Guide) Search

func (g *Guide) Search(query string, limit int) []Hit

Search 在全部主题里按关键词找小节。

规则:查询按空白切成词,每个词都要在这一节(标题或正文)里出现(词多于三个时有三分之二即可); 词没有字面出现在这一节、但是登记表给该篇登记的同义词(Keywords)时算一个较弱的命中, 前提是至少有一个词字面命中,这样「任务 指派」这类同义问法也能落到任务板那一篇。 标题命中比正文命中权重高,主题标题 / 摘要 / 同义词命中再加分。整段中文没有空格时,上面的严格规则可能一个都找不到, 此时退到「二字组」宽松匹配(至少 60% 的二字组命中)。每个主题最多给三条,避免一篇长文把结果占满。 最后,词全是某一篇的主题词、而这一篇没有任何小节字面命中时,补一条指向该篇开头的命中(见 topicHits)。

func (*Guide) Section

func (g *Guide) Section(t Topic, ref string) (string, idocs.Heading, error)

Section 取主题里的一节(连同它下面更深层的小节)。ref 可以是标题文字、锚点,或标题文字的唯一前缀 / 唯一子串 (不区分大小写)——智能体常常只记得「8.12」或「运行预设」;以 # 开头表示明确指定锚点。 找不到、有歧义(含同名标题不止一个)时返回 *SectionError,同名标题的候选带着 #锚点,照着写就能取到指定的那一个。

func (*Guide) Topics

func (g *Guide) Topics() []Topic

Topics 按阅读顺序返回全部主题(副本)。

type Hit

type Hit struct {
	Topic   string  `json:"topic"`
	Title   string  `json:"title"`
	Section string  `json:"section,omitempty"` // 命中的小节标题(文档开头的导语没有)
	Anchor  string  `json:"anchor,omitempty"`
	Snippet string  `json:"snippet"`
	Score   float64 `json:"score"`
}

Hit 是一条搜索命中(落在某个小节上)。

type Info

type Info struct {
	Chars    int // 全文字符数(rune)
	Sections int // 二、三级标题的个数
}

Info 是主题的体量信息,列表里给出,方便智能体决定「整篇读」还是「先看大纲再读一节」。

type SectionError

type SectionError struct {
	Ref        string
	Ambiguous  bool
	Candidates []string // 最多 12 个相近的标题;没有相近的就是文档里靠前的标题
}

SectionError 是按标题取一节失败的原因:没有这个标题,或者有多个同样接近的标题。

func (*SectionError) Error

func (e *SectionError) Error() string

type Topic

type Topic struct {
	// ID 是稳定的短标识,usage_guide 用它取内容;只用小写字母、数字与连字符。
	ID string `json:"id"`
	// File 是 docs/ 下的文件名(扁平,没有子目录)。
	File string `json:"file"`
	// Title 是给人看的标题;不取文件里的 H1,因为 H1 常带「操作手册」「迁移指南」之类的后缀,列表里太长。
	Title string `json:"title"`
	// Summary 一两句话:这个主题回答什么问题。list 与搜索都用它,写成「读者会怎么问」的样子。
	Summary string `json:"summary"`
	// Keywords 是搜索用的同义词 / 英文名 / 常见叫法(不出现在列表里)。
	Keywords []string `json:"-"`
}

Topic 是手册里的一个主题,对应 docs/ 下的一个 Markdown 文件。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL