OKF 知识格式集成

完整规格见 00-product-spec.md

定位

OKF v0.1 是 Memory 与 Knowledge 的存储真源。PostgreSQL 是从 OKF 文件建立的检索索引。

上层 AI 可以：

通过 MCP 走 PostgreSQL 快速检索（推荐，速度更快），或
直接读取 OKF 文件（例如 ${paths.contexts}/shared/knowledge/projects/my-project.md）

目录约定

OKF 文件存放在 paths.contexts 下（默认 ~/.yzos/contexts/）。单机可用 default/；多设备用 work/、personal/、shared/（见 12-multi-device.md）。

路径可在 config.yaml 中配置。PostgreSQL 中 okf_files.path 存储相对 paths.contexts 的路径或绝对路径。

${paths.home}/
  contexts/                     # paths.contexts
    default/                    # 单机默认（多设备时为 work/personal/shared）
      knowledge/                 # Knowledge Bundle
        index.md
        projects/
        ai-work/                # AI 工具工作结晶
        ...
      memory/
        index.md
        user_insight/
        ...
      entities/                 # 人物 / 项目 / 任务的 OKF 档案
        person/
        project/
        task/
    shared/                     # 可选的多设备同步区
      ...
  exports/                      # cron rollup 产出
    daily/2026-06-27.md
    weekly/2026-W26.md
  observations/                 # L4 原始观察数据（非 OKF，默认不同步）
  entity_overrides/             # 人工覆盖（L2，可同步）
  sync.toml

YZOS 概念类型

Knowledge

type	说明
`Project`	项目总览
`Technical Insight`	技术见解
`AI Work Summary`	AI 工具工作摘要
`Playbook`	操作手册
`Reference`	外部文档归档
`Infrastructure`	基础设施知识
`Voice Summary`	语音交流摘要
`Entity Person`	人物档案（`entities/person/`）
`Entity Project`	项目档案（`entities/project/`）
`Entity Task`	任务档案（`entities/task/`）

AI Work Summary 示例

---
type: AI Work Summary
title: Claude Code 修复 SAML 回调地址
description: 在示例项目中修复了 SAML 认证回调地址配置。
tool: claude-code
project: example-project
resource: ai-session:ai-claude-20260627-143022
tags: [saml, auth, example-project]
timestamp: 2026-06-27T15:45:00Z
---

# 做了什么

修复了 SAML 回调地址缺少 base_url 前缀的问题，并在前端暴露了 use_absolute_acs_url 标志位。

# Tool Use 摘要

- Edit `src/auth/saml.py`，添加 base_url 前缀逻辑
- Bash `pytest tests/auth/`，全部通过

# 关联

- 属于 [示例项目](/projects/example-project.md)

Memory

维度不变：user_insight | topic_highlight | deep_user_model | custom。

不存在 agentic_memory 维度：AI 行为偏好由各个上层 AI 工具自行管理，YZOS 只负责观察并结晶其工作产出。

Cron 维护与 OKF

维护任务直接操作 OKF 文件：

任务	OKF 操作
`kb_reorganize`	合并相似 Knowledge 条目、修复断链、更新 index.md
`rollup_daily`	写入 `exports/daily/YYYY-MM-DD.md`
`rollup_weekly`	写入 `exports/weekly/YYYY-Www.md`
`reconcile`	扫描 OKF 哈希，与 PostgreSQL 对账

Rollup 文件同样遵循 OKF 格式，可被上层 AI 直接读取。

与 PostgreSQL 同步

写入路径：Triage -> OKF .md 文件 -> Indexer -> PostgreSQL chunks。

维护路径：cron reconcile 扫描 OKF，补建缺失的 PostgreSQL 索引条目。

外部编辑：文件监听器检测到 mtime 变化后触发重新索引。

导入来源

来源	映射到
Claude Code 项目中的 `CLAUDE.md`	Knowledge Reference
AI 工具会话日志	Knowledge `ai-work/`
手工 Markdown	`knowledge/` 或 `memory/custom/`

知识图谱

OKF 交叉链接存储在 okf_links 表中，在审查 UI 中用 Cytoscape.js 渲染。上层 AI 通过 MCP yzos_knowledge_graph 工具获取子图。