开发者文档指南

知识库

团队读写皆宜的 Markdown 原生知识库：带类型、链接与引用的 OKF 概念——任何脚本都可检索。

什么是知识库

知识库工作区把项目的活文档存为 OKF（Open Knowledge Format）概念——带 YAML frontmatter 的纯 Markdown 文件，一文件一概念。一份 playbook、一条业务规则、政策 PDF 的一段摘录：团队该记住的一切都成为概念。

概念格式

frontmatter 携带 type、title、description 与 tags。wiki 式链接连接相关概念，可选的 # Citations 章节记录来源：

---
type: Business Rule
title: 退款需要二次审批
description: 什么情况下退款需要第二人签字。
tags: [payments, policy]
---

超过 500 美元的退款停在 pending_approval，
直到第二位评审签字。

相关：[审批关卡](approval-gates.md)

# Citations
- payments-policy.pdf，第 12 页

概念类型

类型	用途
Source Document	作为参考保留的完整外部文档
Source Section	来源的段落或章节
Topic	团队持续维护认知的主题
Playbook	团队反复执行的步骤化流程
Business Rule	决策必须遵守的政策或不变式
Query Analysis	带结论的已分析问题

文档自动转换

向知识库工作区上传 PDF、Word、PowerPoint、Excel、OpenDocument、RTF、ePub 或 CSV 文件会自动转换为 Markdown——加密或损坏的文件会明确报错。Markdown 与纯文本原样保留。

从脚本检索与体检

workflow 模块里的 okf 对象检索项目知识库。传 workspace_id 可指定其他工作区：

from workflow import okf

hits = okf.search("退款政策")   # 概念摘要
for h in hits:
    print(h["title"], "-", h.get("description", ""))

issues = okf.lint()                  # 健康报告
for i in issues:
    print(i["issue_type"], i["concept_id"], i["message"])

健康检查

lint() 报告四类问题：断开的 wiki 链接、无入链的孤儿概念、缺类型或引用的概念、重复标题。批量编辑后跑一遍，保持知识库可信。