feat(product-source): 光湖知识库模块 v0.1.0 — Git 驱动的完整知识库系统

铸渊 2026-08-08 开发，冰朔架构决策：
- Git 是底层引擎，不依赖任何数据库（PostgreSQL/Redis/ORM）
- Agent 直达底层，中间不隔第三方服务
- 拆解 Outline v0.80.2 为参考样本，光湖自己实现全部能力

技术栈：
- 后端：Express v5 + simple-git + gray-matter（Git 操作层）
- 前端：Vite + React 19 + TypeScript + marked
- 存储：Markdown 文件 + Git 仓库（commit=版本历史，diff=对比）

功能清单（全部可用）：
- 文档 CRUD（创建/读取/更新/删除/移动）
- 文档树导航（文件夹层级）
- Markdown 编辑器（编辑/预览双栏）
- 全文搜索（防抖 + 下拉结果）
- 版本历史（git log）
- 版本 diff 对比（选择两个 commit 对比）

API 端点（Agent 和 UI 共用）：
- GET/POST/PUT/DELETE /api/docs/{*path}
- GET /api/tree
- GET /api/history/{*path}
- GET /api/version/:hash/{*path}
- GET /api/diff/{*path}?from=&to=
- GET /api/search?q=
- POST /api/move
- GET /api/health

product-source/guanghu-knowledge-base/src/api.ts

@@ -0,0 +1,116 @@
+/**
+ * 光湖知识库 · API 客户端
+ * Agent 和前端 UI 共用同一套接口。
+ */
+
+const BASE = '/api';
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE}${path}`, {
+    headers: { 'Content-Type': 'application/json' },
+    ...options,
+  });
+  const data = await res.json();
+  if (!data.ok) throw new Error(data.error || '请求失败');
+  return data as T;
+}
+
+// ─── 类型（与 server 保持一致） ───
+
+export interface DocMeta {
+  id: string;
+  title: string;
+  slug: string;
+  parentPath: string;
+  createdAt: string;
+  updatedAt: string;
+  author: string;
+  tags: string[];
+}
+
+export interface DocContent {
+  meta: DocMeta;
+  body: string;
+}
+
+export interface DocTreeNode {
+  name: string;
+  path: string;
+  type: 'folder' | 'document';
+  children?: DocTreeNode[];
+}
+
+export interface VersionEntry {
+  hash: string;
+  shortHash: string;
+  author: string;
+  date: string;
+  message: string;
+}
+
+export interface SearchResult {
+  path: string;
+  title: string;
+  snippet: string;
+  line: number;
+}
+
+export interface DiffResult {
+  additions: number;
+  deletions: number;
+  hunks: { oldStart: number; newStart: number; lines: string[] }[];
+}
+
+// ─── API 方法 ───
+
+export const api = {
+  /** 获取文档树 */
+  getTree: () =>
+    request<{ ok: true; tree: DocTreeNode[] }>('/tree').then(d => d.tree),
+
+  /** 读取文档 */
+  getDoc: (path: string) =>
+    request<{ ok: true; doc: DocContent }>(`/docs/${path}`).then(d => d.doc),
+
+  /** 创建文档 */
+  createDoc: (path: string, title: string, body: string, author = 'anonymous') =>
+    request<{ ok: true; doc: DocContent }>(`/docs/${path}`, {
+      method: 'POST',
+      body: JSON.stringify({ title, body, author }),
+    }).then(d => d.doc),
+
+  /** 更新文档 */
+  updateDoc: (path: string, title: string, body: string, author = 'anonymous') =>
+    request<{ ok: true; doc: DocContent }>(`/docs/${path}`, {
+      method: 'PUT',
+      body: JSON.stringify({ title, body, author }),
+    }).then(d => d.doc),
+
+  /** 删除文档 */
+  deleteDoc: (path: string) =>
+    request<{ ok: true }>(`/docs/${path}`, { method: 'DELETE' }),
+
+  /** 移动文档 */
+  moveDoc: (oldPath: string, newPath: string) =>
+    request<{ ok: true }>('/move', {
+      method: 'POST',
+      body: JSON.stringify({ oldPath, newPath }),
+    }),
+
+  /** 获取版本历史 */
+  getHistory: (path: string, max = 50) =>
+    request<{ ok: true; history: VersionEntry[] }>(`/history/${path}?max=${max}`).then(d => d.history),
+
+  /** 获取某版本内容 */
+  getDocAtVersion: (path: string, hash: string) =>
+    request<{ ok: true; content: string }>(`/version/${hash}/${path}`).then(d => d.content),
+
+  /** 版本对比 */
+  diffVersions: (path: string, from: string, to: string) =>
+    request<{ ok: true; diff: DiffResult }>(`/diff/${path}?from=${from}&to=${to}`).then(d => d.diff),
+
+  /** 搜索 */
+  search: (query: string) =>
+    request<{ ok: true; results: SearchResult[]; count: number }>(`/search?q=${encodeURIComponent(query)}`)
+      .then(d => d.results),
+};