技能介绍

文档和代码各说一套话

很多团队的 wiki、ADR、参考页会越写越长：字段表从 Pydantic 模型里抄一遍，接口改了文档却没人改。OKF（Open Knowledge Format） 的思路是：每篇 Markdown 顶部的 YAML frontmatter 是这篇文档的结构化事实；正文只解释「为什么、怎么串起来」，凡是 schema、端点契约、配置键等权威定义在代码里，文档用 schema_source（如 connectors/web_api/models.py:PortfolioResponse）和 documents 指向它们，而不是在 prose 里重复维护。

技能在做什么

围绕 Job 1 — 按 OKF 维护文档 与 Job 2 — 快速找到该看的文档，技能指导你与仓库内 tooling 协作：

Frontmatter 约定：通用字段含 type（wiki-chapter / adr / index 等）、title、tags、intent（供检索排序的短句）、schema_source、documents；ADR 另有 status、date、supersedes / superseded_by。文档之间的关系仍用正文里的普通 Markdown 链接构成知识图。
新建与校验：用 run.sh new 打出 frontmatter 骨架；改文档前从代码里填好指针；提交前跑 run.sh lint（--ci 仅在 error 时非零退出），处理断链、悬空指针、缺失 type 等。
查找策略：先 grep，再脚本。字面量命中时 grep 已足够；run.sh find / find_docs.py 的价值在于按 intent 和 frontmatter「归属」排序——例如 symbol、endpoint、config key 或关键词，即使字面串埋在正文深处，仍优先返回「拥有」该条目的文档。run.sh schema 可解析某文档的 schema_source 并打印真实代码定义；run.sh index [--cache] 导出全库 frontmatter 索引。

适用边界

脚本对带 OKF frontmatter 的仓库是只读的（除非你主动改文件）；需存在 docs/wiki/ 等约定布局，或在仓库根用 --repo 指定。未迁移的旧文档在 lint 里多为 info，不应单独当作 CI 失败原因。更完整的 schema 与「不要写成上千行 prose」规则见技能资料中的 references/conventions.md、references/okf-spec.md、references/lookup-strategy.md。