SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场knowledge-base

knowledge-base

通用与其它

查看项目

更新于 10-16 06:02

技能介绍

用途

这是一个面向 AI 智能体的 Markdown 知识库（Knowledge Base）规范。此处的知识库指一个 Markdown 文件夹，设计目标是让任何 AI 智能体无需向量数据库即可浏览：智能体读取一个索引文件，根据描述挑选相关笔记，然后只打开这些笔记。整体知识库保持可读，索引保持精简——因为索引会被载入上下文，必须高信号。

当创建新知识库、增改笔记或做维护巡检时，应用以下规则。当用户请求含义不明（新建知识库、新增笔记还是清理）时，先询问是哪一种再动手。

核心原则

  • 索引优先导航：索引是地图而非容器。智能体读取 INDEX.md，按一行描述选择笔记，然后只打开这些文件。任何笔记只要未在索引中登记，就不算“在”知识库中。
  • 原子化：一条笔记一个主题。若标题需要“和”字，通常应拆成两条笔记。原子化笔记更易查找、链接和复用。
  • 稳定 ID：每条笔记有永久 ID，永不更改、永不重用，使链接能在重命名与移动后存续。
  • 带理由的链接：两条笔记连接时，说明原因（前置、支持、对比、参见）。连接本身与笔记同等有价值。
  • 精简指令：保持 INDEX.md 的说明简短、高信号——它与智能体上下文预算竞争。正文按需加载。
  • 面向检索的结构：清晰的 H1 标题与 H2/H3 小节，便于智能体抓取笔记中相关片段而非整篇。
  • 关联：每个链接目标也应出现在该笔记的 related frontmatter 中。

目录结构（按主题嵌套）

knowledge-base/
  INDEX.md                 # 入口：说明 + 完整笔记注册表
  topics/
    <topic>/
      _topic.md            # 主题地图：该主题覆盖什么 + 其笔记
      <slug>.md            # 一条原子笔记
  assets/                  # 笔记引用的图片 / 附件

主题文件夹为简短小写名词（auth、billing、deploys）。_topic.md 是主题级的内容地图（MOC）：简短引言加上该主题下所有笔记的链接。它是便利视图；INDEX.md 仍是唯一事实来源。

命名规则

  • 小写 kebab-case，可预测、可 grep：topics/auth/session-tokens.md。
  • 不含空格、不含大写、文件名不含日期（日期放在 frontmatter 中）。
  • 文件名 slug 应与笔记 id 的 slug 部分一致。

必填 frontmatter（每条笔记）

---
id: 20260618-session-tokens     # ID 方案：YYYYMMDD-slug。稳定。永不重用或更改。
title: Session tokens           # 人类标题，也是笔记的 H1
tags: [auth, security]          # 仅使用 INDEX.md 受控列表中的标签
created: 2026-06-18
updated: 2026-06-18
related: [20260618-auth-flow]    # 已链接笔记的 ID
summary: One scannable sentence describing what this note covers.
---
  • id：YYYYMMDD-slug。可排序、可读、稳定。同日不同标题的笔记以 slug 区分；若两条同日笔记 slug 相同，追加 -2、-3……（分配前先查 INDEX.md 注册表）。一旦分配，id 即永久。
  • summary：这句确切的话会放进索引注册表——写它以便智能体决定是否打开该笔记。
  • updated：正文变化时即更新。

笔记正文形态

# Session tokens

> Summary: One sentence (mirrors frontmatter summary).

## Context
Why this note exists / when it applies.

## Details
The actual content, in short H2/H3 sections.

## Related
- [Auth flow](auth-flow.md) — prerequisite: tokens are issued during the auth flow.
- [Rate limiting](../api/rate-limiting.md) — see-also: tokens carry the rate-limit key.

笔记之间使用相对链接，并用短语标注关系。

INDEX.md（唯一事实来源）

INDEX.md 有两部分：面向智能体的操作说明，以及注册表。

# Knowledge Base — Index

## How to use this KB (for agents)
1. Read this index first. Pick notes by their descriptions; open only those.
2. To answer a question, prefer opening 1–3 specific notes over scanning everything.
3. Cite the note `id` when you use information from it.

## How to update this KB (for agents)
- New idea → create a new note (atomic). Same idea changed → edit the note in place and bump `updated`.
- Any create / rename / delete MUST update this registry and the topic's `_topic.md` in the same change.
- Use only tags from the controlled vocabulary below; add a new tag here before using it.

## Controlled tags
`auth`, `security`, `billing`, `api`, `ops`   <!-- extend deliberately -->

## Registry
### auth
- `20260618-auth-flow` — **Authentication flow** — `topics/auth/auth-flow.md` — How a user session is established end to end.
- `20260618-session-tokens` — **Session tokens** — `topics/auth/session-tokens.md` — Token format, lifetime, and rotation.

### billing
- `20260618-invoicing` — **Invoicing** — `topics/billing/invoicing.md` — How invoices are generated and sent.

注册表行格式：id — Title — path — 一行描述。

_topic.md（主题地图）

# Auth

Notes covering authentication, sessions, and access control.

- [Authentication flow](auth-flow.md) — how a session is established.
- [Session tokens](session-tokens.md) — token format, lifetime, rotation.

工作流

创建新知识库

  1. 为上述文件夹结构执行 create_directory。
  2. 写入 INDEX.md，包含说明块、空的受控标签列表与空注册表。
  3. 添加第一个主题文件夹 + _topic.md，然后添加第一条笔记（均通过 write_file）。
  4. 在 INDEX.md 中登记该笔记，并从 _topic.md 链接它——两者都用 edit_block，以便只改动变化的行。

新增笔记

  1. 选择或创建主题文件夹（用 list_directory 查看现有内容）。
  2. write_file 写入笔记（kebab-case slug），含完整 frontmatter 与正文形态。
  3. 添加交叉链接（并在 related 中镜像）。
  4. 用 edit_block 在 INDEX.md 中登记，并在 _topic.md 中链接——同一次改动内完成。

更新笔记

  • 同一想法、新信息 → 用 edit_block 原地编辑该笔记，更新 updated；若范围变化，用 edit_block 更新注册表行。
  • 确实是新想法 → write_file 新建一条原子笔记，而非扩展此笔记。

维护巡检（按需运行）

使用 start_search（ripgrep）做文本扫描，用 get_file_info / list_directory 做存在性检查——二者结合可让此任务在规模上可行：

  • 孤儿笔记（无入链——出链不重要）：对笔记的 id 与文件名 slug 在知识库中 start_search，然后扣除始终存在的自匹配——笔记自身文件、INDEX.md 及其 _topic.md。剩余即为真实入链引用；若无剩余即为孤儿，应从相关笔记/MOC 链接它，或归档。
  • 失效链接 / 漂移：不要从文本命中推断其已解析——字符串存在不代表文件存在。用 get_file_info（或按主题 list_directory）确认每个注册表路径与 related 目标确实存在，并确认磁盘上每个文件都已登记。仅对标题/摘要不同步这一半使用文本比对。
  • 非原子笔记：扩展到覆盖多个主题的笔记 → 拆分。
  • 重复：近似相同的笔记 → 合并，保留一个 id，重定向链接。
  • 标签泛滥：从 INDEX.md 读取受控列表，然后 start_search 检索 frontmatter tags: 行，标出不在列表中的标签 → 调和。用 read_multiple_files 批量拉取候选，用 edit_block 应用修复，并报告改动内容。

完成任何知识库编辑前的检查清单

  • 每条新增/变化的笔记都有完整、有效的 frontmatter。
  • id 唯一且未变；文件名 slug 与 id slug 一致。
  • 所有链接可解析，并在 related 中镜像。
  • INDEX.md 注册表与主题 _topic.md 反映了该变化。
  • 标签来自受控词汇表。
  • 每条变化的笔记都更新了 updated。

暂未提供：官方正文内容、具体收费与价格、平台支持范围、实际效果数据、安装命令等信息，资料中均未提及。