Documentation
¶
Overview ¶
Package guide 是随二进制内嵌的「使用手册」:docs/ 目录里的 Markdown 文档,经 MCP 工具 usage_guide 按需读取。
目的:接入的智能体不会用某个功能时,可以直接查手册(而不是凭记忆回答),用户也可以一句话让会话自己去查。 手册随 Hub 的版本一起发布,所以描述的就是这个 Hub 现在能做的事,不会出现「文档比程序新或旧」。
这个包只负责「有哪些主题、怎么按标题 / 关键词取内容」,不依赖数据库,也不知道 MCP;工具层在 internal/mcp。
Index ¶
- Variables
- type Guide
- func (g *Guide) Body(t Topic) (string, error)
- func (g *Guide) Info(t Topic) (Info, error)
- func (g *Guide) Lookup(ref string) (Topic, bool)
- func (g *Guide) Outline(t Topic, maxLevel int) ([]idocs.Heading, error)
- func (g *Guide) Search(query string, limit int) []Hit
- func (g *Guide) Section(t Topic, ref string) (string, idocs.Heading, error)
- func (g *Guide) Topics() []Topic
- type Hit
- type Info
- type SectionError
- type Topic
Constants ¶
This section is empty.
Variables ¶
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 (*Guide) Search ¶
Search 在全部主题里按关键词找小节。
规则:查询按空白切成词,每个词都要在这一节(标题或正文)里出现(词多于三个时有三分之二即可); 词没有字面出现在这一节、但是登记表给该篇登记的同义词(Keywords)时算一个较弱的命中, 前提是至少有一个词字面命中,这样「任务 指派」这类同义问法也能落到任务板那一篇。 标题命中比正文命中权重高,主题标题 / 摘要 / 同义词命中再加分。整段中文没有空格时,上面的严格规则可能一个都找不到, 此时退到「二字组」宽松匹配(至少 60% 的二字组命中)。每个主题最多给三条,避免一篇长文把结果占满。 最后,词全是某一篇的主题词、而这一篇没有任何小节字面命中时,补一条指向该篇开头的命中(见 topicHits)。
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 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 文件。