@newest-ai/notes-pipeline 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @newest-ai/notes-pipeline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把笔记仓库编译成静态笔记站点：**Markdown → 预构建 Vue SPA**。
+主站、子站共用同一套界面与编译逻辑，站点差异只体现在 `blog.config.mjs`。
+
+## 安装
+
+```bash
+npm i -D @newest-ai/notes-pipeline
+```
+
+## 命令
+
+```bash
+npx notes-pipeline build     # 同步（如配置了 source）+ 编译到 dist/
+npx notes-pipeline sync      # 只同步笔记源到 workspace/
+npx notes-pipeline dev       # 编译后启动本地预览
+```
+
+选项：
+
+| 参数 | 说明 |
+|---|---|
+| `--config <file>` | 配置文件，默认 `blog.config.mjs` |
+| `--base <path>` | 站点部署路径，覆盖 `site.base`，如 `/agent/` |
+| `--source <mode>` | 强制笔记源模式：`local` / `git` |
+| `--port <number>` | dev 端口，默认 `devPort`（4321） |
+
+## 笔记目录约定
+
+- 顶层目录 = 分类，子目录任意深度；`NN-` 编号前缀只影响排序，展示标题会自动去掉。
+- 根目录散落的 `.md` 归入「概览」（`content.rootSkip` 中的文件除外）。
+- 文章标题取文件名；`[[wikilink]]`、`[文本](相对.md)` 自动解析为站内文章。
+- 图片支持相对路径、`./images/…`、`![[image.png]]`，按 basename 全局匹配（大小写不敏感）。
+
+## 配置
+
+```js
+export default {
+  site: {
+    title: '智能体笔记',
+    brand: '智能体笔记',        // 顶部品牌文字
+    brandAccent: '',            // brand 尾部高亮片段（如 'AI'）
+    description: '…',
+    lang: 'zh-CN',
+    base: '/agent/',            // 部署路径，必须以 / 开头、/ 结尾
+    url: 'https://newest-ai.com/agent/',
+    heroText: '个人网站 · 无商业目的 · 不接广告 · 合规守法',
+    footer: {
+      siteName: '智能体笔记',    // 可选
+      domain: 'newest-ai.com',   // 可选
+      icp: { text: '…', href: '…' },
+      gongan: { text: '…', href: '…' },
+      bio: '作者简介…',           // 可选
+      mainSite: 'https://newest-ai.com', // 子站可选：回链主站
+      text: '个人笔记 · 无商业目的 · 不接广告 · 合规守法',
+    },
+  },
+
+  content: {
+    dir: 'notes',               // 笔记目录（未配置 source 时生效）
+    exclude: ['.obsidian', '.git', 'node_modules'],
+    rootSkip: ['readme.md', 'idea.md'],
+    rootSectionTitle: '概览',
+  },
+
+  // 笔记源可选：笔记在别的仓库时先同步到 workspace/，再编译
+  source: {
+    mode: 'git',                // 'git' | 'local'
+    dir: 'D:/Notes/ai-notes',   // local 模式源目录
+    workspace: 'workspace',
+    git: { url: 'git@…', branch: 'master', depth: 1 },
+  },
+
+  // 菜单分级：main = 目录之上再抽一层类别；sub = 顶层目录直接当菜单
+  menu: {
+    type: 'main',
+    groups: [
+      { title: '基本功', dirs: ['01-语言基础', '02-操作系统'] },
+    ],
+  },
+
+  output: 'dist',
+  devPort: 4321,
+}
+```
+
+### 菜单类型
+
+| 类型 | 说明 | 树结构 |
+|---|---|---|
+| `main` | 主站：在目录之上抽一层类别 | `group → category → subcategory → article` |
+| `sub`  | 子站：顶层目录直接作为菜单 | `category → subcategory → article` |
+
+`menu.groups` 中未出现的目录会平铺在类别之后；「概览」始终置顶。
+
+## 产物
+
+```
+dist/
+├── index.html              # 注入站点配置与页面标题
+├── assets/                 # 预构建 UI（js/css/字体）
+├── favicon.svg
+├── gongan.png
+└── content/
+    ├── tree.json           # 导航树 + 扁平索引
+    ├── site.json           # 站点配置快照
+    ├── articles/<id>.json  # 每篇文章 HTML、标题、大纲、上/下一篇
+    └── images/             # 笔记引用的图片
+```
+
+部署时把 `dist/` 托管到 `site.base` 对应的路径即可。资源与数据请求均使用以 `base` 开头的绝对路径。

package/bin/cli.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * notes-pipeline CLI
+ *
+ *   notes-pipeline build [--config blog.config.mjs] [--base /agent/] [--source local|git]
+ *   notes-pipeline sync  [--config blog.config.mjs] [--source local|git]
+ *   notes-pipeline dev   [--port 4321] [...同 build]
+ */
+import path from 'node:path'
+import { buildSite } from '../src/build.mjs'
+import { loadConfig } from '../src/config.mjs'
+import { syncSource } from '../src/sync.mjs'
+import { startServer } from '../src/server.mjs'
+
+const HELP = `
+notes-pipeline — 笔记仓库编译为静态站点
+
+用法：
+  notes-pipeline build [选项]     同步（如配置了 source）+ 编译到 dist/
+  notes-pipeline sync  [选项]     只同步笔记源到 workspace/
+  notes-pipeline dev   [选项]     编译后启动本地静态服务器
+
+选项：
+  --config <file>    配置文件，默认 blog.config.mjs
+  --base <path>      站点部署路径，覆盖配置里的 site.base，如 /agent/
+  --source <mode>    强制笔记源模式：local | git
+  --port <number>    dev 端口，默认取配置 devPort（4321）
+  -h, --help         显示帮助
+`.trim()
+
+const COMMANDS = new Set(['build', 'sync', 'dev'])
+
+function parseArgs(argv) {
+  const opts = {}
+  let command = 'build'
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '-h' || arg === '--help') {
+      opts.help = true
+    } else if (arg === '--config') {
+      opts.configPath = argv[++i]
+    } else if (arg === '--base') {
+      opts.base = argv[++i]
+    } else if (arg === '--source') {
+      opts.sourceMode = argv[++i]
+    } else if (arg === '--port') {
+      opts.port = Number(argv[++i])
+    } else if (COMMANDS.has(arg)) {
+      command = arg
+    } else {
+      throw new Error(`未知参数：${arg}`)
+    }
+  }
+  return { command, opts }
+}
+
+async function main() {
+  const { command, opts } = parseArgs(process.argv.slice(2))
+  if (opts.help) {
+    console.log(HELP)
+    return
+  }
+
+  const root = process.cwd()
+
+  if (command === 'sync') {
+    const config = await loadConfig(root, { configPath: opts.configPath, sourceMode: opts.sourceMode })
+    if (!config.source) {
+      console.log('ℹ️  当前配置未设置 source，笔记直接在 content.dir 中，无需同步。')
+      return
+    }
+    const result = syncSource(config)
+    console.log(`✅ 同步完成（${result.mode}）→ ${path.relative(root, config.contentDir)}`)
+    return
+  }
+
+  if (command === 'dev') {
+    const { config, outDir } = await buildSite({ ...opts, root })
+    startServer({ dir: outDir, port: opts.port || config.devPort })
+    return
+  }
+
+  await buildSite({ ...opts, root })
+}
+
+main().catch((err) => {
+  console.error(`❌ ${err?.message || err}`)
+  process.exit(1)
+})

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@newest-ai/notes-pipeline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "笔记仓库 → 静态笔记站点的编译流水线（Markdown → Vue SPA），支持主站分组菜单与子站平铺菜单",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "notes-pipeline": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "ui-dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build:ui": "vite build",
+    "pack:check": "npm run build:ui && npm pack --dry-run",
+    "prepack": "npm run build:ui"
+  },
+  "keywords": [
+    "notes",
+    "static-site",
+    "markdown",
+    "vue",
+    "vite"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/code-beast/notes-pipeline.git"
+  },
+  "dependencies": {
+    "highlight.js": "^11.11.1",
+    "katex": "^0.16.21",
+    "markdown-it": "^14.1.0",
+    "markdown-it-anchor": "^9.2.0",
+    "markdown-it-task-lists": "^2.1.1",
+    "markdown-it-texmath": "^1.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "mermaid": "^11.4.1",
+    "vite": "^6.0.7",
+    "vue": "^3.5.13"
+  }
+}

package/src/build.mjs

@@ -0,0 +1,147 @@
+/**
+ * 编译入口：笔记目录 → 静态站点产物。
+ *
+ * 流程：同步（可选）→ 清理产物 → 拷贝预构建 UI → 扫描笔记 → 渲染 Markdown
+ *       → 写文章 JSON / 导航树 / 站点配置 → 生成 index.html
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { loadConfig } from './config.mjs'
+import { syncSource } from './sync.mjs'
+import { scanNotes, flattenRoots, applyMenuGroups } from './scan.mjs'
+import { createImages } from './images.mjs'
+import { createMarkdown, extractHeadings } from './markdown.mjs'
+import { buildSitePayload, renderIndexHtml } from './page.mjs'
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const UI_DIST = path.join(PKG_ROOT, 'ui-dist')
+
+const readText = (abs) =>
+  fs.readFileSync(abs, 'utf8').replace(/^\uFEFF/, '').replace(/\r\n/g, '\n')
+
+function ensureUiBuilt() {
+  if (!fs.existsSync(path.join(UI_DIST, 'index.html'))) {
+    throw new Error(`UI 产物缺失：${UI_DIST}（请在包内执行 npm run build:ui）`)
+  }
+}
+
+function copyUi(outDir) {
+  for (const e of fs.readdirSync(UI_DIST, { withFileTypes: true })) {
+    if (e.name === 'index.html') continue
+    fs.cpSync(path.join(UI_DIST, e.name), path.join(outDir, e.name), { recursive: true })
+  }
+}
+
+function writeFile(outDir, rel, content) {
+  const dest = path.join(outDir, rel)
+  fs.mkdirSync(path.dirname(dest), { recursive: true })
+  fs.writeFileSync(dest, content, 'utf8')
+}
+
+/**
+ * @param {{ root?: string, configPath?: string, base?: string, sourceMode?: 'local'|'git',
+ *           skipSync?: boolean, log?: (msg: string) => void }} options
+ */
+export async function buildSite(options = {}) {
+  const root = options.root || process.cwd()
+  const log = options.log || console.log
+
+  log('\n🔨 编译笔记 → 静态站点\n')
+
+  const config = await loadConfig(root, {
+    configPath: options.configPath || 'blog.config.mjs',
+    base: options.base,
+    sourceMode: options.sourceMode,
+  })
+
+  if (config.source && !options.skipSync) {
+    const r = syncSource(config)
+    log(`   已同步（${r.mode}）→ ${path.relative(root, config.contentDir)}`)
+  }
+
+  const contentDir = config.contentDir
+  if (!fs.existsSync(contentDir)) throw new Error(`笔记目录不存在：${contentDir}`)
+
+  ensureUiBuilt()
+
+  const outDir = path.resolve(root, config.output)
+  fs.rmSync(outDir, { recursive: true, force: true })
+  fs.mkdirSync(outDir, { recursive: true })
+  copyUi(outDir)
+
+  const scan = scanNotes(contentDir, config.content)
+  const roots = config.menu.type === 'main' ? applyMenuGroups(scan.roots, config.menu.groups) : scan.roots
+  const flat = flattenRoots(roots)
+
+  log(`   扫描：Markdown ${scan.mdFiles.length} 篇（收录 ${flat.length} 篇），图片 ${scan.imageFiles.length} 张`)
+
+  // 文章查找表（wikilink / .md 链接解析用）
+  const byId = new Map()
+  const byBasename = new Map()
+  for (const a of flat) {
+    byId.set(a.id.toLowerCase(), a.id)
+    const name = path.posix.basename(a.id).toLowerCase()
+    if (!byBasename.has(name)) byBasename.set(name, a.id)
+  }
+
+  const images = createImages({ imageFiles: scan.imageFiles, outDir })
+  const md = createMarkdown({ images, articles: { byId, byBasename }, base: config.site.base })
+
+  const nodeTitle = new Map()
+  const collectTitle = (node) => {
+    if (node.type === 'article') nodeTitle.set(node.id, node.title)
+    else (node.children || []).forEach(collectTitle)
+  }
+  roots.forEach(collectTitle)
+
+  const mdByRel = new Map(scan.mdFiles.map((f) => [f.rel, f.abs]))
+  const rendered = new Map()
+
+  flat.forEach((item, i) => {
+    const rel = `${item.id}.md`
+    const abs = mdByRel.get(rel)
+    if (!abs) return
+    const source = readText(abs)
+    const html = md.render(source, { dir: path.posix.dirname(rel) })
+    const prev = i > 0 ? flat[i - 1] : null
+    const next = i < flat.length - 1 ? flat[i + 1] : null
+    const payload = {
+      id: item.id,
+      title: nodeTitle.get(item.id) || item.title,
+      html,
+      headings: extractHeadings(html),
+      prev: prev ? { id: prev.id, title: prev.title } : null,
+      next: next ? { id: next.id, title: next.title } : null,
+      source: rel,
+    }
+    rendered.set(item.id, payload)
+    writeFile(outDir, item.file, JSON.stringify(payload))
+  })
+
+  const tree = {
+    meta: {
+      generatedAt: new Date().toISOString(),
+      total: flat.length,
+      menuType: config.menu.type,
+      source: config.source
+        ? (config.source.mode === 'git' ? config.source.git.url : config.source.dir)
+        : config.content.dir,
+    },
+    roots,
+    flat,
+  }
+  writeFile(outDir, 'content/tree.json', JSON.stringify(tree))
+
+  const sitePayload = buildSitePayload({ config, total: flat.length })
+  writeFile(outDir, 'content/site.json', JSON.stringify(sitePayload))
+
+  const template = fs.readFileSync(path.join(UI_DIST, 'index.html'), 'utf8')
+  writeFile(outDir, 'index.html', renderIndexHtml(template, { payload: sitePayload, base: config.site.base }))
+
+  log(`   渲染：文章 ${rendered.size} 篇，引用图片 ${images.copied.size} 张`)
+  log(`✅ 完成：${path.relative(root, outDir) || config.output}/\n`)
+
+  return { config, outDir, total: flat.length, images: images.copied.size }
+}

package/src/config.mjs

@@ -0,0 +1,101 @@
+/**
+ * 站点配置加载与规范化。
+ *
+ * 配置文件（默认 blog.config.mjs）默认导出一个对象，字段见 README。
+ * 这里补齐默认值并把 base 规范为以 / 开头、以 / 结尾的形式。
+ */
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const DEFAULT_EXCLUDE = ['.git', '.obsidian', '.idea', '.hermes', 'node_modules']
+
+export function normalizeBase(base) {
+  let b = String(base || '/').trim()
+  if (!b.startsWith('/')) b = `/${b}`
+  if (!b.endsWith('/')) b += '/'
+  return b.replace(/\/{2,}/g, '/')
+}
+
+function normalizeSource(source, root) {
+  const mode = source.mode === 'local' ? 'local' : 'git'
+  const workspace = source.workspace || 'workspace'
+  const dir = source.dir ? path.resolve(root, source.dir) : null
+  if (mode === 'local' && !dir) throw new Error('source.mode=local 时必须提供 source.dir')
+  if (mode === 'git' && !(source.git && source.git.url)) throw new Error('source.mode=git 时必须提供 source.git.url')
+  return {
+    mode,
+    dir,
+    workspace,
+    git: {
+      url: source.git?.url || '',
+      branch: source.git?.branch || 'master',
+      depth: source.git?.depth ?? 1,
+    },
+  }
+}
+
+function normalizeMenu(menu) {
+  if (!menu) return { type: 'sub', groups: [] }
+  const type = menu.type === 'main' ? 'main' : 'sub'
+  const groups = Array.isArray(menu.groups) ? menu.groups : []
+  if (type === 'main' && groups.length === 0) {
+    throw new Error('menu.type=main 时必须提供 menu.groups（顶层类别 → 目录名列表）')
+  }
+  for (const g of groups) {
+    if (!g.title || !Array.isArray(g.dirs)) throw new Error('menu.groups 每项必须是 { title, dirs: [] }')
+  }
+  return { type, groups }
+}
+
+/**
+ * @param {string} root 站点项目根目录
+ * @param {{ configPath?: string, base?: string, sourceMode?: string }} options
+ */
+export async function loadConfig(root, options = {}) {
+  const abs = path.resolve(root, options.configPath || 'blog.config.mjs')
+  let raw
+  try {
+    raw = (await import(pathToFileURL(abs).href)).default
+  } catch (e) {
+    throw new Error(`无法加载配置文件 ${abs}：${e.message}`)
+  }
+  if (!raw || typeof raw !== 'object') throw new Error(`配置文件 ${abs} 必须默认导出对象`)
+
+  const site = { ...(raw.site || {}) }
+  site.base = normalizeBase(options.base || site.base)
+  site.title = site.title || 'Notes'
+  site.brand = site.brand || site.title
+  site.brandAccent = site.brandAccent || ''
+  site.description = site.description || ''
+  site.lang = site.lang || 'zh-CN'
+  site.url = site.url || ''
+  site.heroText = site.heroText || ''
+  site.footer = { ...(site.footer || {}) }
+
+  const content = {
+    dir: raw.content?.dir || 'notes',
+    exclude: raw.content?.exclude || DEFAULT_EXCLUDE,
+    rootSkip: raw.content?.rootSkip ?? ['readme.md', 'idea.md'],
+    rootSectionTitle: raw.content?.rootSectionTitle || '概览',
+  }
+
+  let source = raw.source ? normalizeSource(raw.source, root) : null
+  if (source && options.sourceMode) {
+    const mode = options.sourceMode === 'local' ? 'local' : 'git'
+    source = normalizeSource({ ...source, mode }, root)
+  }
+
+  const menu = normalizeMenu(raw.menu)
+
+  return {
+    root,
+    site,
+    content,
+    source,
+    menu,
+    output: raw.output || 'dist',
+    devPort: raw.devPort || 4321,
+    // 有 source 时正文来自 workspace；否则来自 content.dir
+    contentDir: path.resolve(root, source ? source.workspace : content.dir),
+  }
+}

package/src/images.mjs

@@ -0,0 +1,77 @@
+/**
+ * 图片解析与拷贝。
+ *
+ * 解析顺序：相对当前 md 所在目录 → 去掉 ./ 再试 → 按 basename 全局匹配（大小写不敏感）。
+ * 输出名做 ASCII 净化并去重，写入 dist/content/images/。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+export function sanitizeName(base) {
+  return base.replace(/\s+/g, '_').replace(/[^\w.-]+/g, '_')
+}
+
+export function createImages({ imageFiles, outDir }) {
+  const byPath = new Map() // 小写 rel -> rel
+  const byBasename = new Map() // 小写 basename -> rel
+  for (const img of imageFiles) {
+    const rel = img.rel
+    byPath.set(rel.toLowerCase(), rel)
+    const key = img.base.toLowerCase()
+    if (!byBasename.has(key)) byBasename.set(key, rel)
+  }
+
+  const copied = new Map() // rel -> 输出文件名
+  const usedNames = new Set()
+
+  function resolve(ref, fromDir = '') {
+    let clean = String(ref || '').trim()
+    // 去掉 Obsidian 图片后缀： #pic_center、|623、#right 等
+    clean = clean.replace(/[#|].*$/, '').trim()
+    if (!clean) return null
+    // 绝对 URL / data:
+    if (/^[a-z][a-z0-9+.-]*:/i.test(clean)) return null
+
+    let rel = path.posix.normalize(path.posix.join(fromDir || '.', clean))
+    if (byPath.has(rel.toLowerCase())) return byPath.get(rel.toLowerCase())
+
+    if (clean.startsWith('./')) {
+      rel = path.posix.normalize(path.posix.join(fromDir || '.', clean.slice(2)))
+      if (byPath.has(rel.toLowerCase())) return byPath.get(rel.toLowerCase())
+    }
+
+    const base = path.posix.basename(clean).toLowerCase()
+    if (byBasename.has(base)) return byBasename.get(base)
+    return null
+  }
+
+  function copy(rel) {
+    if (!rel) return null
+    if (copied.has(rel)) return copied.get(rel)
+    const src = imageFiles.find((i) => i.rel === rel)
+    if (!src) return null
+
+    const base = sanitizeName(path.posix.basename(rel))
+    let finalName = base
+    let n = 1
+    while (usedNames.has(finalName)) {
+      const ext = path.extname(base)
+      finalName = `${path.basename(base, ext)}_${n++}${ext}`
+    }
+    usedNames.add(finalName)
+
+    const dest = path.join(outDir, 'content', 'images', finalName)
+    fs.mkdirSync(path.dirname(dest), { recursive: true })
+    fs.copyFileSync(src.abs, dest)
+    copied.set(rel, finalName)
+    return finalName
+  }
+
+  return {
+    resolve,
+    copy,
+    get copied() {
+      return copied
+    },
+  }
+}