pi-okf-memory 0.1.0

package/src/server/capture.ts

@@ -0,0 +1,52 @@
+/**
+ * capture.ts — 记忆纪律(系统提示片段)与捕获评估。
+ * 神经自我学习驱动:捕获由"预测误差"驱动 —— 用户纠正、首次披露、反直觉结论
+ * 都是模型预测失败的信号,内在动机触发写入;取代固定规则表。
+ */
+
+/** 注入系统提示的"记忆纪律"片段(Agent 自主决定何时调用 okf_remember) */
+export const MEMORY_DISCIPLINE: string = `
+# 记忆纪律(okf-memory)
+
+你有一个 OKF 长期记忆库。记忆不靠自动记录,而靠你判断"本轮是否产生了值得沉淀的新知识"。
+
+## 值得记忆(高价值信号,写!)
+- 用户给出新背景事实 / 偏好 / 习惯(首次披露)
+- 达成的决策及理由(尤其用户明确拍板的事项)
+- 可复用方法论 / 流程 / 经验教训
+- 用户纠正了你的理解(这是最强的"预测误差"信号)
+- 反直觉但被用户确认的结论
+- 技术选型:用户提到前端/后端/语言/方案/配置的选择、切换、配置细节
+
+## 不值得记忆(不写)
+- 寒暄、过程性问答、单轮临时任务
+- 已记忆内容的重复表述(先搜再写,命中则跳过)
+- 未验证的猜测、尚未落地的设想(可归入 Idea 类型等待成熟)
+
+## 写入纪律
+1. 写入前必先 okf_search:命中同标题 → 不新建,更新或跳过;命中相近 → 互补合并或互建交叉链接
+2. 每篇必须:type 非空、title 简洁、description 一句话摘要(检索全靠它)、正文结构化(标题/列表/表格)
+3. type 词表:Fact 背景事实 / Preference 偏好 / Decision 决策 / Method 方法论 / Insight 洞察 / Idea 灵感 / Lesson 教训 / TechChoice 技术选型
+4. 正文模板:Decision/Insight 用 # 数据 → # 分析 → # 结论 三段式;TechChoice 用 # Options 候选表 + # Active 当前使用;其余自由结构化
+5. **交叉链接必须显式传 related 参数**:新建概念时,把 okf_search 命中的相关概念 ID 填进
+   related(如 related: ["fact/门店布局"])。工具会自动双向建立「## 相关」链接。
+   - 正文里手写路径 **不会** 生成图谱边 —— 图谱的边只来自 related 写入的链接。
+   - 一次会话里新建多条互相相关的概念时,后建的必须把先建的 ID 放进 related。
+   - 若 okf_remember 返回 status="linked",说明命中相近概念,用返回的 similarTo 作 related 重新提交(不要重复写正文)。
+
+## 技术选型三档规则(用户既定协议,硬性执行)
+1. 命中 2+ 候选 → 全部展示给用户选择(带说明/配置/状态),绝不擅自决定
+2. 命中 1 个候选 → 直接使用
+3. 用户未指定技术,但消息命中维度关键词(如"前端")→ 按该维度记忆处理
+4. 用户说出新技术/切换/配置 → okf_remember 追加式更新,不覆盖旧候选
+5. 用户拍板后,记录选择反馈(权重自动更新,下次排序靠前)
+
+## 唤起纪律
+- 会话开场先 okf_search 预取相关记忆,再开始干活
+- 检索不到 → 明确告知"记忆库没有",不要编造
+`.trim()
+
+/** 预取提示:会话启动时建议先搜什么(低优先级,供摘要注入用) */
+export const RECALL_GUIDE: string = `
+记忆库概念清单见本片段顶部(okf-memory index)。需要细节时用 okf_read <concept_id>。
+`.trim()

package/src/server/concept.ts

@@ -0,0 +1,302 @@
+/**
+ * concept.ts — OKF v0.1 概念化:frontmatter 组装、正文模板、概念 ID 规范化、frontmatter 解析。
+ * 依据 OKF v0.1:frontmatter 唯一硬要求是 type;title/description 强烈建议;tags/timestamp 可选;扩展字段允许。
+ */
+
+/** 类型词表(起步版) */
+export const TYPE_VOCAB: readonly string[] = [
+  'Fact', 'Preference', 'Decision', 'Method',
+  'Insight', 'Idea', 'Lesson', 'TechChoice',
+]
+
+/** 概念 frontmatter 元数据(OKF v0.1) */
+export interface ConceptMeta {
+  type: string
+  title?: string
+  description?: string
+  resource?: string
+  tags?: string[]
+  timestamp?: string
+  source?: string
+  [key: string]: unknown
+}
+
+/** 解析 frontmatter 的结果 */
+export interface ParsedFrontmatter {
+  meta: ConceptMeta | null
+  body: string
+}
+
+/** 归一化并校验概念类型(大小写不敏感,必须属于 TYPE_VOCAB);非法时抛错 */
+export function normalizeType(type: unknown): string {
+  const t = String(type || '').trim()
+  if (!t) throw new Error('OKF 概念 type 必填')
+  const hit = TYPE_VOCAB.find((v) => v.toLowerCase() === t.toLowerCase())
+  if (!hit) throw new Error(`非法 type:「${type}」;可选:${TYPE_VOCAB.join('/')}`)
+  return hit
+}
+
+/** 规范化概念 ID:保留中文/字母数字,其余转连字符(Windows 安全字符集) */
+export function slugify(input: unknown): string {
+  return String(input ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^\p{L}\p{N}\-]/gu, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+/** YAML 标量转义 */
+function yamlScalar(v: unknown): string {
+  if (typeof v === 'string') {
+    if (/^[\p{L}\p{N}\s.,\-_/:（）()%¥￥+*#@!?'"=<>\[\]{}|&^~`\\;]*$/u.test(v) && !/^[\s\-?:]/.test(v) && !v.includes(': ')) {
+      return v
+    }
+    return JSON.stringify(v)
+  }
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
+  return JSON.stringify(v)
+}
+
+function yamlTags(tags: unknown): string {
+  if (!Array.isArray(tags) || tags.length === 0) return 'tags: []'
+  const items = tags.map((t) => {
+    const s = String(t)
+    // 含逗号/引号/方括号的 tag 必须 JSON 转义,否则 flow 数组解析会被拆坏
+    return /[,()[\]{}"'#:]/.test(s) ? JSON.stringify(s) : yamlScalar(s)
+  }).join(', ')
+  return `tags: [${items}]`
+}
+
+/** 生成 frontmatter(固定顺序,稳定可比较) */
+export function buildFrontmatter(meta: ConceptMeta): string {
+  const lines = ['---']
+  const order = ['type', 'title', 'description', 'resource', 'tags', 'timestamp', 'source']
+  for (const key of order) {
+    const v = meta[key]
+    if (v === undefined || v === null || v === '') continue
+    if (key === 'tags') {
+      lines.push(yamlTags(v))
+    } else {
+      lines.push(`${key}: ${yamlScalar(v)}`)
+    }
+  }
+  // 生产者扩展字段(OKF 允许,消费者须保留)
+  for (const [k, v] of Object.entries(meta)) {
+    if (order.includes(k)) continue
+    lines.push(`${k}: ${yamlScalar(v)}`)
+  }
+  lines.push('---')
+  return lines.join('\n')
+}
+
+/**
+ * 生成概念文档。
+ */
+export function buildConcept(meta: ConceptMeta, body: string): string {
+  const type = String(meta.type || '').trim()
+  if (!type) throw new Error('OKF 概念必须包含非空 type')
+  const fm = buildFrontmatter(meta)
+  const b = String(body || '').trim()
+  return b ? `${fm}\n\n${b}\n` : `${fm}\n`
+}
+
+/**
+ * 决策/结论三段式模板(继承用户约定:数据/分析/结论)。
+ */
+export function buildDecisionBody(parts: { data?: string; analysis?: string; conclusion: string }): string {
+  const { data, analysis, conclusion } = parts || {}
+  const out: string[] = []
+  if (data) out.push(`# 数据\n\n${data.trim()}`)
+  if (analysis) out.push(`# 分析\n\n${analysis.trim()}`)
+  if (conclusion) out.push(`# 结论\n\n${conclusion.trim()}`)
+  if (out.length === 0) throw new Error('Decision/Insight 正文需至少包含 conclusion')
+  return out.join('\n\n')
+}
+
+/**
+ * 技术选型正文模板(TechChoice):Options 候选表 + Active 当前使用。
+ */
+export function buildTechChoiceBody(spec: { title?: string; options: Array<{ name: string; desc?: string; config?: string; status?: string }>; active?: string; notes?: string }): string {
+  const opts = spec.options || []
+  if (opts.length === 0) throw new Error('TechChoice 至少需要一个候选')
+  const rows = opts
+    .map((o) => `| ${yamlScalar(o.name)} | ${yamlScalar(o.desc || '')} | ${yamlScalar(o.config || '')} | ${yamlScalar(o.status || 'candidate')} |`)
+    .join('\n')
+  const out: string[] = []
+  out.push(`## Options\n\n| 候选 | 说明 | 配置要点 | 状态 |\n|---|---|---|---|\n${rows}`)
+  if (spec.active) out.push(`## Active\n\n- 当前使用:${spec.active}`)
+  if (spec.notes) out.push(`## 相关\n\n${spec.notes.trim()}`)
+  return out.join('\n\n')
+}
+
+/** 解析 frontmatter(容错:解析失败返回 {meta:null, body:原文};支持引号/多行块/flow 数组) */
+export function parseFrontmatter(md: unknown): ParsedFrontmatter {
+  const text = String(md || '')
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text)
+  if (!m) return { meta: null, body: text }
+  const [, yaml, body] = m
+  const meta: Record<string, unknown> = {}
+  const lines = yaml.split(/\r?\n/)
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) { i++; continue }
+    const idx = line.indexOf(':')
+    if (idx <= 0) { i++; continue }
+    const key = line.slice(0, idx).trim().replace(/^['"]|['"]$/g, '')
+    let val = line.slice(idx + 1).trim()
+    // 多行块值(| 字面 / > 折叠)
+    if (val === '|' || val === '>' || val === '|-' || val === '>-') {
+      const block: string[] = []
+      i++
+      while (i < lines.length && /^\s+/.test(lines[i])) {
+        block.push(lines[i].replace(/^[ \t]+/, ''))
+        i++
+      }
+      meta[key] = block.join('\n')
+      continue
+    }
+    // flow 数组:尊重引号内逗号
+    if (val.startsWith('[') && val.endsWith(']')) {
+      meta[key] = splitFlowArray(val.slice(1, -1))
+      i++
+      continue
+    }
+    meta[key] = unquoteScalar(val)
+    i++
+  }
+  return { meta: meta as ConceptMeta, body: body || '' }
+}
+
+/** flow 数组拆分:引号内的逗号不拆,去引号/转义(闭合引号消费但不进内容;反斜杠转义下一个字符) */
+function splitFlowArray(s: string): string[] {
+  const out: string[] = []
+  let cur = ''
+  let q: string | null = null
+  let esc = false
+  for (const ch of s) {
+    if (esc) {
+      // 转义:只保留下一字符本身(丢反斜杠),\"→"、\\→\
+      cur += ch
+      esc = false
+    } else if (ch === '\\') {
+      esc = true
+    } else if (q) {
+      if (ch === q) {
+        q = null // 闭合引号:消费,不进内容
+      } else {
+        cur += ch
+      }
+    } else if (ch === '"' || ch === "'") {
+      q = ch
+    } else if (ch === ',') {
+      if (cur.trim()) out.push(unquoteScalar(cur))
+      cur = ''
+    } else {
+      cur += ch
+    }
+  }
+  if (cur.trim()) out.push(unquoteScalar(cur))
+  return out.filter(Boolean)
+}
+
+/** 去掉标量两端匹配的引号并还原常见转义 */
+function unquoteScalar(v: string): string {
+  const s = String(v || '').trim()
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1).replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\\n/g, '\n')
+  }
+  return s
+}
+
+export interface ValidationResult {
+  ok: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+/**
+ * OKF v0.1 符合性校验(三条硬要求 + 建议字段)。
+ */
+export function validateConcept(md: string): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+  const { meta } = parseFrontmatter(md)
+  // 硬要求 1:可解析 YAML 头信息
+  if (!meta) {
+    errors.push('缺少可解析的 YAML frontmatter')
+    return { ok: false, errors, warnings }
+  }
+  // 硬要求 2:type 非空
+  const type = String(meta.type || '').trim()
+  if (!type) errors.push('type 字段为空')
+  // 建议字段
+  if (!meta.title) warnings.push('缺 title(将用文件名推导)')
+  if (!meta.description) warnings.push('缺 description(索引/搜索靠它)')
+  if (!meta.timestamp) warnings.push('缺 timestamp')
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+interface Section {
+  key: string | null
+  content: string
+}
+
+/**
+ * 按顶层小节合并两份概念正文(防止更新时无限追加 "## 补充(日期)"):
+ * - 相同小节标题(如 # 数据 / ## Options)→ 新内容覆盖旧小节,保留原位置
+ * - 新小节 → 追加到末尾
+ * - 无标题引言 → 仅当旧文没有引言时才补入
+ */
+export function mergeConceptBodies(existing: string, incoming: string): string {
+  const ex = splitSections(existing)
+  const inc = splitSections(incoming)
+  const byKey = new Map<string | null, Section>(ex.map((s) => [s.key, s]))
+  for (const s of inc) {
+    if (s.key === null) {
+      if (!byKey.has(null)) byKey.set(null, s)
+    } else {
+      byKey.set(s.key, s)
+    }
+  }
+  const out: Section[] = []
+  const used = new Set<string | null>()
+  for (const s of ex) {
+    const hit = byKey.get(s.key)
+    if (hit) { out.push(hit); used.add(s.key) }
+  }
+  for (const s of inc) {
+    if (!used.has(s.key)) { out.push(s); used.add(s.key) }
+  }
+  return out.map(renderSection).filter(Boolean).join('\n\n')
+}
+
+/** 按 #/##/### 顶层标题切分成小节(含无标题引言小节 key=null) */
+function splitSections(body: unknown): Section[] {
+  const sections: Section[] = []
+  let cur: Section | null = null
+  for (const line of String(body || '').split('\n')) {
+    const m = /^(#{1,3})\s+(.*)$/.exec(line)
+    if (m) {
+      cur = { key: `${m[1]} ${m[2]}`.replace(/\s+/g, ' ').trim(), content: '' }
+      sections.push(cur)
+    } else {
+      if (!cur) {
+        // 无标题引言小节:必须把首行一并收进 content,否则引言内容丢失
+        cur = { key: null, content: '' }
+        sections.push(cur)
+      }
+      cur.content += line + '\n'
+    }
+  }
+  return sections
+}
+
+function renderSection(s: Section): string {
+  if (s.key === null) return s.content.trim()
+  const body = s.content.trim()
+  return body ? `${s.key}\n\n${body}` : s.key
+}

package/src/server/dedupe.ts

@@ -0,0 +1,164 @@
+/**
+ * dedupe.ts — 去重与互补决策(对应"互补而非复制"原则)。
+ * 写前必查:命中且相同 → skip;命中但互补 → merge 建议 + 交叉链接;未命中 → create。
+ */
+import { promises as fs } from 'node:fs'
+import { parseFrontmatter, type ConceptMeta } from './concept.js'
+import { scanBundle, readConcept, type BundleEntry } from './store.js'
+
+/**
+ * 词项化:空白分词 + CJK 二元组。
+ * 纯子串匹配对中文短语(如「查询数据库」)几乎必然落空,而库中概念标题/描述往往写成
+ * 「查询鼎赞…数据…」。补重叠二元组后,「查询」「数据」等子片段也能命中,提升中文召回。
+ * 保留原始整串词项以维持精确短语加分。
+ */
+function tokenizeQuery(q: string): string[] {
+  const terms = new Set<string>()
+  const raw = String(q || '').split(/\s+/).filter(Boolean)
+  for (const token of raw) {
+    terms.add(token)
+    // 含 CJK 且长度>=3 时,补相邻 2 字符二元组
+    if (/[\u4e00-\u9fff]/.test(token) && token.length >= 3) {
+      for (let i = 0; i < token.length - 1; i++) terms.add(token.slice(i, i + 2))
+    }
+  }
+  return [...terms]
+}
+
+export interface SearchOptions {
+  type?: string
+  tags?: string[]
+  limit?: number
+}
+
+export interface SearchHit {
+  conceptId: string
+  title: string
+  description: string
+  type: string
+  tags: string[]
+  score: number
+}
+
+/**
+ * 全库检索:按关键词匹配 title/description/tags/type(正文做二级加分)。
+ */
+export async function search(root: string, query: string, opts: SearchOptions = {}): Promise<SearchHit[]> {
+  const { type, tags, limit = 20 } = opts
+  const q = String(query || '').trim().toLowerCase()
+  const qTerms = tokenizeQuery(q)
+  const concepts = await scanBundle(root)
+  const hits: SearchHit[] = []
+  for (const c of concepts) {
+    let text: string
+    try {
+      text = await fs.readFile(c.filePath, 'utf8')
+    } catch {
+      continue
+    }
+    const { meta } = parseFrontmatter(text)
+    if (!meta || !meta.type) continue
+    if (type && String(meta.type).toLowerCase() !== String(type).toLowerCase()) continue
+    if (tags && tags.length > 0) {
+      const mt = Array.isArray(meta.tags) ? (meta.tags as string[]).map(String) : []
+      if (!tags.every((t) => mt.some((x) => x.toLowerCase().includes(String(t).toLowerCase())))) continue
+    }
+    let score = 0
+    if (qTerms.length > 0) {
+      const hay = [meta.title, meta.description, Array.isArray(meta.tags) ? (meta.tags as string[]).join(' ') : '', meta.type]
+        .filter(Boolean)
+        .join(' ').toLowerCase()
+      let matched = 0
+      for (const t of qTerms) {
+        if (hay.includes(t)) matched++
+        else if (text.toLowerCase().includes(t)) { score += 0.3; matched++ }
+      }
+      if (matched === 0) continue
+      score += (matched / qTerms.length) * 2
+      if (hay.includes(q)) score += 3 // 完整短语命中加分
+    }
+    score += (Array.isArray(meta.tags) ? (meta.tags as string[]).length : 0) * 0.1
+    hits.push({
+      conceptId: c.conceptId,
+      title: meta.title || c.conceptId,
+      description: meta.description || '',
+      type: meta.type,
+      tags: Array.isArray(meta.tags) ? (meta.tags as string[]) : [],
+      score,
+    })
+  }
+  hits.sort((a, b) => b.score - a.score)
+  return hits.slice(0, limit)
+}
+
+export interface SimilarHit {
+  conceptId: string
+  title: string
+  type: string
+  similarity: number
+}
+
+/**
+ * 按标题找相似概念(去重主查:精确相等或互相包含)。
+ * 包含判定要求较短一方 ≥ MIN_CONTAIN_LEN(3 字符),否则「前端」这种短词
+ * 会误伤「前端方案」,挡住正常新建。
+ */
+const MIN_CONTAIN_LEN = 3
+export async function findSimilarByTitle(root: string, title: string, type?: string): Promise<SimilarHit[]> {
+  const t = String(title || '').trim().toLowerCase()
+  if (!t) return []
+  const concepts = await scanBundle(root)
+  const out: SimilarHit[] = []
+  for (const c of concepts) {
+    let text: string
+    try {
+      text = await fs.readFile(c.filePath, 'utf8')
+    } catch {
+      continue
+    }
+    const { meta } = parseFrontmatter(text)
+    if (!meta || !meta.title) continue
+    if (type && String(meta.type).toLowerCase() !== String(type).toLowerCase()) continue
+    const ct = String(meta.title).trim().toLowerCase()
+    if (ct === t) {
+      out.push({ conceptId: c.conceptId, title: meta.title, type: meta.type, similarity: 1 })
+    } else if ((ct.includes(t) || t.includes(ct)) && Math.min(ct.length, t.length) >= MIN_CONTAIN_LEN) {
+      out.push({ conceptId: c.conceptId, title: meta.title, type: meta.type, similarity: 0.6 })
+    }
+  }
+  return out.sort((a, b) => b.similarity - a.similarity)
+}
+
+export interface DecideInput {
+  title: string
+  type?: string
+  body: string
+}
+
+export interface DecideResult {
+  action: 'skip' | 'update' | 'create'
+  conceptId?: string
+  reason: string
+}
+
+/**
+ * 去重决策。
+ */
+export async function decide(root: string, { title, type, body }: DecideInput): Promise<DecideResult> {
+  const similar = await findSimilarByTitle(root, title, type)
+  if (similar.length > 0) {
+    const top = similar[0]
+    if (top.similarity >= 1) {
+      // 标题完全相同:比较正文长度,内容被覆盖 → update,否则 skip 建议
+      const existing = await readConcept(root, top.conceptId)
+      const bodyLen = String(body || '').trim().length
+      const existingLen = String(existing.body || '').trim().length
+      if (bodyLen > existingLen * 0.7) {
+        return { action: 'update', conceptId: top.conceptId, reason: `标题相同且新正文更完整(${bodyLen}字 vs 已有${existingLen}字),更新已有概念` }
+      }
+      return { action: 'skip', conceptId: top.conceptId, reason: '标题相同的概念已存在,内容未明显增加,跳过写入' }
+    }
+    return { action: 'update', conceptId: top.conceptId, reason: `找到相近概念[${top.title}](similarity ${top.similarity}),建议互补合并或互建交叉链接` }
+  }
+  return { action: 'create', reason: '未命中已有概念,新建' }
+}

package/src/server/dsh-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 可选宿主依赖的环境声明。
+ *
+ * `@deepseek-ai/dsh-tools` 只在 dsh 运行时提供,本包不将其列为依赖
+ * (pi 侧根本用不到它)。src/server/index.ts 用动态 import + try/catch
+ * 做降级,因此这里声明一个宽松的模块形状即可,避免 tsc 报「找不到模块」。
+ */
+declare module '@deepseek-ai/dsh-tools' {
+  /** 官方工具定义包装器(缺失时调用方会降级为透传原对象) */
+  export const defineTool: ((def: unknown) => unknown) | undefined
+}

package/src/server/graph.ts

@@ -0,0 +1,135 @@
+/**
+ * graph.ts — 记忆图谱数据提取:把 OKF 记忆库转成图谱 JSON(nodes/edges/timeline)。
+ * 供 okf_graph 工具/服务消费,契约与可视化前端一致,可被 dshfind 等复用。
+ * 纯业务逻辑,不依赖 dsh ctx,便于单测。
+ */
+import { promises as fs } from 'node:fs'
+import { scanBundle, type BundleEntry } from './store.js'
+import { parseFrontmatter } from './concept.js'
+import { loadMeta } from './learning.js'
+
+export interface GraphMeta {
+  generatedAt: string
+  root: string
+  totalConcepts: number
+}
+
+export interface GraphNode {
+  id: string
+  title: string
+  type: string
+  tags: string[]
+  description: string
+  weight: number
+  state: string
+  lastAccessed: string | null
+}
+
+export interface GraphEdge {
+  source: string
+  target: string
+  text: string
+}
+
+export interface GraphTimelineEntry {
+  id: string
+  weight: number
+  state: string
+  lastAccessed: string | null
+  accessCount: number
+}
+
+export interface GraphData {
+  meta: GraphMeta
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+  timeline: GraphTimelineEntry[]
+}
+
+export interface BuildGraphOptions {
+  /** 预留:后续可扩展筛选/上限 */
+  limit?: number
+}
+
+/**
+ * 提取记忆图谱数据。
+ */
+export async function buildGraph(root: string, _opts: BuildGraphOptions = {}): Promise<GraphData> {
+  const concepts: BundleEntry[] = await scanBundle(root)
+  const weights = await loadMeta(root)
+  const meta: GraphMeta = {
+    generatedAt: new Date().toISOString(),
+    root,
+    totalConcepts: concepts.length,
+  }
+
+  const nodes: GraphNode[] = []
+  const byId = new Map<string, string>()
+  for (const c of concepts) {
+    let text: string
+    try {
+      text = await readText(c.filePath)
+    } catch {
+      continue
+    }
+    const { meta: fm } = parseFrontmatter(text)
+    if (!fm) continue
+    const w = weights.entries[c.conceptId]
+    nodes.push({
+      id: c.conceptId,
+      title: fm.title || c.conceptId.replace(/^[^/]+\//, ''),
+      type: fm.type || 'Other',
+      tags: Array.isArray(fm.tags) ? (fm.tags as string[]) : [],
+      description: fm.description || '',
+      weight: w ? +w.weight.toFixed(2) : 1.0,
+      state: w?.state || 'active',
+      lastAccessed: w?.lastAccessed || null,
+    })
+    byId.set(c.conceptId, c.conceptId)
+  }
+
+  // 边:交叉链接(用 recall 同款正则,不触发权重反馈)
+  const edges: GraphEdge[] = []
+  const seen = new Set<string>()
+  for (const c of concepts) {
+    let text: string
+    try {
+      text = await readText(c.filePath)
+    } catch {
+      continue
+    }
+    const { body } = parseFrontmatter(text)
+    const re = /\[([^\]]+)\]\(\/([^)]+\.md)\)/g
+    let m: RegExpExecArray | null
+    while ((m = re.exec(body || '')) !== null) {
+      let targetId = m[2].replace(/^\/+/, '').replace(/\.md$/, '')
+      if (!byId.has(targetId)) {
+        const k = Object.keys(byId).find((x) => x.toLowerCase() === targetId.toLowerCase())
+        if (k) targetId = k
+      }
+      if (targetId && targetId !== c.conceptId) {
+        const k = [c.conceptId, targetId].sort().join('||')
+        if (!seen.has(k)) {
+          seen.add(k)
+          edges.push({ source: c.conceptId, target: targetId, text: m[1] })
+        }
+      }
+    }
+  }
+
+  // 时间线(权重历史,供学习热力)
+  const timeline: GraphTimelineEntry[] = Object.entries(weights.entries || {}).map(([id, e]) => ({
+    id,
+    weight: +e.weight.toFixed(2),
+    state: e.state || 'active',
+    lastAccessed: e.lastAccessed || null,
+    accessCount: e.accessCount || 0,
+  }))
+
+  return { meta, nodes, edges, timeline }
+}
+
+/** 读文件 */
+async function readText(filePath: string): Promise<string> {
+  return fs.readFile(filePath, 'utf8')
+}