Skip to content

SCHEMA.md

Latest commit

 

History

History
353 lines (246 loc) · 14.6 KB

SCHEMA.md

File metadata and controls

353 lines (246 loc) · 14.6 KB
Raw

Wiki 结构约定

这个文件定义了知识库页面的最小结构。目标是让 agent 的输出足够稳定，但不要把写作流程变成负担。

全局规则

  1. 新增文件使用英文小写的 kebab-case，具体规则见「文件命名」；页面标题与正文可以使用中文。
  2. 新的知识页面只能放在 wiki/topics/、wiki/syntheses/ 或 wiki/comparisons/ 下。
  3. 每个页面都应当在 Obsidian 中单独打开时仍然容易理解。
  4. 优先通过页面链接建立关系，而不是在不同页面中重复解释同一件事。
  5. 任何包含结论、建议或判断的页面，都应附带来源指针。
  6. 新页面应带一个英文 category 字段，并按分类子目录存放。
  7. tags 用来表达细粒度主题，不用来替代一级分类。

用词检查

使用具体的动作和对象解释行为，保留更清晰的英文技术术语。描述字段与请求响应时使用“接口定义”，描述双方交互要求时使用“调用约定”；“契约测试”等正式术语保留。

不要为了显得专业而自造抽象概念或套用比喻。例如把“新模型不再需要 TodoWrite”写成「补偿型脚手架退役」，把“多 agent 共享任务列表的功能变多”写成「协作原语增厚」，把“分步传递数据”写成「上下文接力」。描述机制时写清它是什么工具或代码、解决什么问题、有哪些限制和代价；能用具体工具名（如 TodoWrite、Tasks）说清的，不要改成泛称。

bin/wiki check-jargon 按 bin/jargon-rules.json 报告需修改的词项、位置和建议，不自动替换。原始引用和技术标识按 bin/README.md 的规则保留；需要上下文判断的表达仍由人工审阅。

文件命名

  • 新增文件的名称主体使用英文小写、数字和连字符，使用小写扩展名。例如 dual-token-server-api.md、2026-09-27-dual-token-lifecycle.png；不使用空格、下划线或中文文件名。
  • 语义后缀按工具约定保留，例如 check-jargon.test.ts。点分隔的是后缀，名称主体仍用 kebab-case。
  • AGENTS.md、SCHEMA.md、README.md、SKILL.md、LICENSE 等约定文件，以及工具要求的 .gitignore、.github/pull_request_template.md 等固定名称保留原样；不要借例外命名普通知识页面。
  • 已在目标分支存在的文件不批量改名，修改正文也不要求改名；尚未合入的 PR 新增文件遵守新规则。
  • 文件名与展示标题分开：frontmatter 的 title 和正文标题可以使用中文。链接使用实际路径，必要时用显示文本，例如 [[wiki/topics/architecture/jwt|JWT]]。
  • wikilink 别名：[[实际路径|显示文本]] 中竖线左侧是链接目标、右侧是渲染文本；指向页内小节用 [[路径#小节]]。Markdown 表格内竖线与列分隔冲突，别名需转义写成 \|（如 [[wiki/topics/ai/prompt\|Prompt]]）。批量改文件名时只替换目标路径，显示文本保持原样。
  • 重命名新增文件时，同步修改导航、页面链接、来源指针及 PR 中的路径说明；原始素材正文不因命名规则改写。

原始素材命名

  • 新增素材使用稳定的对象或主题名，例如 raw/sources/gbrain.md、raw/sources/letta-context-repositories.md，不自动加发布日期或抓取日期前缀。发布日期、抓取日期和源码提交版本写在文件头。
  • 同一对象的多份来源合并到同一份素材；同名但不同对象加作者、组织或具体主题区分。文件已存在时先阅读，再按任务授权追加或修订，不直接覆盖。
  • 已合入的日期命名文件保留原名；明确要求改名时同步更新所有引用。尚未合入的新增文件采用上述规则。

建议使用的 frontmatter

新页面建议带上这组最小 frontmatter：

---
title: 页面标题
description: 一句话说明这页解决什么问题，便于 agent 先扫 frontmatter
type: topic
category: frontend
created: 2026-04-12
updated: 2026-04-12
tags: []
source_refs: []
resource: []
timestamp: 2026-04-12
---

字段约定：

  • type：topic、synthesis 或 comparison
  • description：面向人和 agent 的一句话摘要。新页面应优先补上，避免 agent 必须打开正文才能判断页面是否相关
  • category：英文一级分类，例如 frontend、ai、systems
  • tags：细粒度英文主题，推荐 1 到 5 个
  • source_refs：支持本页内容的相对路径、页面名或 URL
  • resource：OKF-compatible 字段，导出时默认镜像 source_refs
  • resource_type：可选字段。只有当页面描述真实外部资源时才填写，例如 API Endpoint、Automation Job、Metric、BigQuery Table
  • timestamp：OKF-compatible 字段，导出时默认使用 updated

OKF 兼容约定

这个 wiki 的主格式仍然是 Obsidian-compatible Markdown，但新页面应逐步兼容 Open Knowledge Format。

兼容目标：

  1. 保留现有 category、source_refs 等治理字段，不为了兼容 OKF 丢掉本仓库的审阅和来源约束。
  2. 在 frontmatter 中补充 description，让 agent 可以在不读取全文的情况下初筛页面。
  3. 内部 type 始终表示页面职责，只允许 topic、synthesis、comparison。不要把外部资源类型直接塞进内部 type。
  4. 使用 resource 作为 OKF-compatible 来源字段。手写页面时可以让它与 source_refs 相同；未来导出工具可以自动从 source_refs 生成。
  5. 如果页面描述真实外部资源，使用可选 resource_type 表达资源对象类型，例如 API Endpoint、Automation Job、Metric、BigQuery Table。
  6. 使用 timestamp 作为 OKF-compatible 更新时间字段。手写页面时可以与 updated 相同；未来导出工具可以自动生成。
  7. 仓库内部可以继续使用 [[wikilink]]，但 OKF 导出时应转换为标准 Markdown 链接。
  8. raw/sources/ 继续作为事实层，不因 OKF 兼容而把未成熟资料直接提升到 wiki/。

字段映射：

Wiki 字段 OKF-compatible 字段 说明
title title 保持一致
description description 新增，一句话摘要
type type 保持一致，取值仍受本仓库页面类型约束
tags tags 保持一致
source_refs resource source_refs 是内部来源字段，resource 是导出友好字段
updated timestamp updated 是内部字段，timestamp 是导出友好字段
resource_type type 或扩展字段 仅在 resource mode 导出时映射为 OKF type；knowledge mode 下保留为扩展字段
category 扩展字段 OKF 不强制，本仓库继续保留

导出模式：

  • knowledge mode：面向普通知识库 Agent 和 RAG。导出时 type 保持为 topic、synthesis、comparison，resource_type 作为扩展字段保留。
  • resource mode：面向资源目录或工具目录。若页面存在 resource_type，导出时可以令 OKF type = resource_type，并把内部页面职责保留为 page_type。

最小样板：

---
title: 页面标题
description: 一句话说明这页解决什么问题
type: synthesis
category: ai
created: 2026-06-15
updated: 2026-06-15
timestamp: 2026-06-15
tags:
  - agent
source_refs:
  - raw/sources/example.md
resource:
  - raw/sources/example.md
---

资源页样板：

---
title: Search API
description: 搜索服务的 HTTP API 入口与调用边界
type: topic
category: tooling
created: 2026-06-15
updated: 2026-06-15
timestamp: 2026-06-15
tags:
  - api
  - search
resource_type: API Endpoint
resource:
  - https://example.com/api/search
source_refs:
  - raw/sources/search-api.md
---

分类与 tag 的分工：

  • category 解决“这页放哪儿”
  • tags 解决“这页还和哪些主题相关”
  • 目录只保留一个主分类，交叉语义通过 tags 和页面链接表达

分类治理：

  1. 当前一级分类默认冻结，不随迁移过程随意扩张。
  2. 更细粒度主题优先放进 tags，例如 react、rsc、mcp、typescript。
  3. 只有当一个主题持续形成稳定页面簇，并且放进现有分类明显别扭时，才考虑升级为新的一级分类。

页面类型

1. 主题页面

路径：wiki/topics/<category>/

用于稳定主题页，既包括概念，也包括具体对象。主题页回答“这是什么？”，并且应该可以长期持续演化。

建议结构：

# 页面标题

## 摘要

用一小段话定义这个主题。

## 关键点

- 要点 1
- 要点 2

## 相关页面

- [[相关页面]]

## 来源指针

- 来源 1

示例：

  • React
  • MCP
  • Rolldown
  • Software Design

2. 综合页面

路径：wiki/syntheses/<category>/

用于把多份笔记或多份资料整合为更高层次的理解。综合页面回答“目前综合后的理解是什么？”

建议结构：

# 页面标题

## 问题

这页在回答什么问题？

## 简答

一句话回答。

## 综合结论

展开说明综合后的理解。

## 使用限制

哪些场景不适用，有什么已知限制？

## 还需要确认什么

写出尚未验证的具体行为，或谁需要决定哪项选择；没有此类内容时省略。

## 来源指针

- 来源 1

示例：

  • RSC 的序列化心智模型
  • Agent 驱动 Wiki 的维护流程

3. 对比页面

路径：wiki/comparisons/<category>/

用于记录选择、取舍和决策。对比页面回答“应该怎么选？”

建议结构：

# 页面标题

## 当前结论

目前的推荐结论是什么？

## 备选项

- 方案 A
- 方案 B

## 取舍分析

| 方案 | 优势 | 风险 | 适用场景 |
| --- | --- | --- | --- |
| A | ... | ... | ... |

## 推荐理由

写清楚当前选择及原因。

## 来源指针

- 来源 1

示例：

  • Obsidian vs Logseq
  • RSC vs SSR

收录页约定（curated list / awesome 类）

用于把一批同类外部对象（skill、组件库、参考站、工具……）收进 wiki，形成可召回、可维护的索引。收录页回答「我们收录了哪些 X、各是什么水平」，不回答「X 是什么」（那是对象 topic 页或清单行的职责），也不回答「该怎么选」（那是 comparison 的职责）。type 仍是 topic，按领域分类目录存放（如 wiki/topics/frontend/、wiki/topics/ai/）。

判断是否该用收录页：

  • 有一批同领域对象需要持续维护，用一页做「索引 + 分级」比每个对象单独开页更划算；
  • 单个对象不值得开 topic 页，但合起来值得一页（例如「动画组件库收藏」）；
  • 已有多个 topic / comparison / 清单行分散引用同一批对象，需要一个聚合召回入口。

定位纪律

  1. 收录页是 curated list，不是 star 排行榜，也不是全网镜像；只收「过线或有教学价值」的条目。
  2. 筛选操作规则放在对应 skill 或其参考文件中，通用标准共用，每个 awesome 索引另有一份专属标准；能独立解释领域问题的知识才放进 Wiki，不为维护索引另建 synthesis。收录页保留「一句话价值 + 分级 + 指针」，可链接相关领域知识页。
  3. 一两句话能说明用途、分级和主要限制的条目，直接附来源链接收录，不要求 raw。证据不足的候选不收录；只有资料本身值得保存时才放 raw/sources/，不自动创建候选名单。
  4. 对象若另开 topic / product 页，收录页条目与对象页解耦：收录页只留指针。
  5. 需要保留原文摘录、较长分析或验证记录时，同一对象（一个库 / 站）在 raw/sources/ 只保留一份合并素材，命名遵循「原始素材命名」；不按 URL / 页面拆多个文件，收录时剔除导航、广告等噪音，不整站搬运。

Frontmatter 约定

type: topic
description: <领域> 资源索引：推荐 / 可参考 / 偏薄，附用途与来源
tags:
  - catalog          # 必含：recall 时先查 catalog + 领域 tag
  - <领域 tag>        # 如 skills / component-library / tooling
source_refs:          # 对象来源 URL、相关领域知识，以及实际保留的 raw（如有）
resource:             # 镜像 source_refs
  • 页面标题统一为 Awesome <领域>（沿用 awesome 的 curated list 语义）或 <领域> 收录索引，方便按标题召回；新增文件名仍遵守「文件命名」。
  • 分级语义统一三档：推荐 / 可参考 / 偏薄；分级操作依据放在相关 skill 中；收录页简要说明三档含义，并按档列出条目。

结构模板（必要小节）

# 标题

## 摘要        # 说明收录哪些资源
## 分级        # 简要解释三档含义
## 索引        # 按档分组表格：| 对象 | 一句话价值 | 指针 |；指针必须可点，可直接链来源；有独立素材时再链 raw
## 相关页面
## 来源指针

召回与更新约定

  • 找「收录了哪些 X」：先查 tags: catalog + 领域 tag 的页面，不要逐个 topic 页翻。
  • 收录页加条目、改分级 = 知识变更，走 branch + PR；PR body 说明该条目的判据与分级理由。
  • 收录页新增对象若本身值得开页（topic / product），导航同步更新 index.md；纯索引行变更不需要。

样板页：wiki/topics/ai/awesome-agent-skills.md（本约定的首个实例，2026-08 建立并沿用至今）。

提示词（prompts/）

提示词不进 wiki/ 页面，而是单独的 prompts/ 目录：一条一个 <id>.md，正文原样复制原文（不翻译、不精简），场景、分级、来源和使用限制写在 frontmatter。

bin/wiki prompts list [--tag <tag>] [--level <档>] [--json]   列出
bin/wiki prompts search <关键词>                              搜索（含正文）
bin/wiki prompts show <id>                                    打印原文
bin/wiki prompts check                                        校验所有提示词文件

正文是 frontmatter 之后的原文副本，保留原有格式，不额外包代码块。元数据的语言、字段、新增流程和存档使用限制见 prompts/README.md。

原始材料规则

  • raw/sources/ 存放原始资料和迁移后的残留材料。
  • raw/assets/ 存放被页面引用的附件。
  • 不要强行把 raw 材料改写成 wiki 页面，除非它已经达到可以被提升的程度。

迁移判断规则

  • 成熟的概念页或对象页，提升到 wiki/topics/
  • 多来源整合出的结论，提升到 wiki/syntheses/
  • 选型、对比、决策类内容，提升到 wiki/comparisons/
  • 暂时不成形的残留内容，留在 raw/sources/
  • 页面落库时必须选择一个英文一级分类，并进入对应的分类子目录