hololake-system-architecture/product-source/guanghu-knowledge-base/server/index.ts

/**
 * 光湖知识库 · API 服务器
 *
 * Express + Git 引擎，提供知识库全部 REST API。
 * Agent 直接调用这些接口，不经过任何第三方服务。
 */

import express from 'express';
import cors from 'cors';
import { GitEngine } from './git-engine.js';
import { PersonaAgent, createDefaultPersona } from './persona-agent.js';
import { projectHumanKnowledgeTree } from './language-protocol-kernel.js';
import path from 'path';

// __dirname 兼容 CJS 和 ESM
const _dirname = typeof __dirname !== 'undefined' ? __dirname : process.cwd();

// ─── 配置 ───

const PORT = parseInt(process.env.KB_PORT || '3890', 10);
const REPO_PATH = process.env.KB_REPO_PATH || path.resolve(_dirname, '../kb-data');

// ─── 初始化 ───

const app = express();
const engine = new GitEngine(REPO_PATH);

app.use(cors({
  origin(origin, callback) {
    const allowed = !origin || origin === 'null' || /^https?:\/\/(127\.0\.0\.1|localhost)(:\d+)?$/.test(origin);
    callback(allowed ? null : new Error('仅允许 HoloLake 本机界面访问'), allowed);
  },
}));
app.use(express.json({ limit: '10mb' }));

// Express v5 的 {*param} 返回数组，工具函数统一转字符串
const p = (v: unknown): string => Array.isArray(v) ? v.join('/') : String(v);

// ─── 健康检查 ───

app.get('/api/health', (_req, res) => {
  res.json({
    module: 'guanghu-knowledge-base',
    version: '0.1.0',
    engine: 'git',
    repo: REPO_PATH,
    status: 'online',
    time: new Date().toISOString(),
  });
});

// ─── 文档树 ───

app.get('/api/tree', async (_req, res) => {
  try {
    const tree = await engine.getTree();
    res.json({ ok: true, tree: projectHumanKnowledgeTree(tree) });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// ─── 文档 CRUD ───

// 读取文档
app.get('/api/docs/{*docPath}', async (req, res) => {
  try {
    const docPath = p(req.params.docPath);
    const doc = await engine.getDoc(docPath);
    res.json({ ok: true, doc });
  } catch (err: any) {
    res.status(404).json({ ok: false, error: `文档不存在: ${p(req.params.docPath)}` });
  }
});

// 创建文档
app.post('/api/docs/{*docPath}', async (req, res) => {
  try {
    const docPath = p(req.params.docPath);
    const { title, body, author } = req.body;
    if (!title || !body) {
      return res.status(400).json({ ok: false, error: 'title 和 body 必填' });
    }
    const doc = await engine.createDoc(docPath, title, body, author);
    res.status(201).json({ ok: true, doc });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// 更新文档
app.put('/api/docs/{*docPath}', async (req, res) => {
  try {
    const docPath = p(req.params.docPath);
    const { title, body, author } = req.body;
    if (!title || !body) {
      return res.status(400).json({ ok: false, error: 'title 和 body 必填' });
    }
    const doc = await engine.updateDoc(docPath, title, body, author);
    res.json({ ok: true, doc });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// 删除文档
app.delete('/api/docs/{*docPath}', async (req, res) => {
  try {
    const docPath = p(req.params.docPath);
    await engine.deleteDoc(docPath);
    res.json({ ok: true, message: `已删除: ${docPath}` });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// 重命名/移动文档
app.post('/api/move', async (req, res) => {
  try {
    const { oldPath, newPath } = req.body;
    if (!oldPath || !newPath) {
      return res.status(400).json({ ok: false, error: 'oldPath 和 newPath 必填' });
    }
    await engine.moveDoc(oldPath, newPath);
    res.json({ ok: true, message: `${oldPath} → ${newPath}` });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// ─── 版本历史 ───

app.get('/api/history/{*docPath}', async (req, res) => {
  try {
    const docPath = p(req.params.docPath);
    const maxCount = parseInt(req.query.max?.toString() || '50', 10);
    const history = await engine.getHistory(docPath, maxCount);
    res.json({ ok: true, history });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// 获取某版本内容
app.get('/api/version/:hash/{*docPath}', async (req, res) => {
  try {
    const { hash } = req.params;
    const docPath = p(req.params.docPath);
    const content = await engine.getDocAtVersion(docPath, hash);
    res.json({ ok: true, content });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// 版本对比
app.get('/api/diff/{*docPath}', async (req, res) => {
  try {
    const docPath = p(req.params.docPath);
    const { from, to } = req.query;
    if (!from || !to) {
      return res.status(400).json({ ok: false, error: 'from 和 to (commit hash) 必填' });
    }
    const diff = await engine.diffVersions(docPath, from.toString(), to.toString());
    res.json({ ok: true, diff });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// ─── 搜索 ───

app.get('/api/search', async (req, res) => {
  try {
    const query = req.query.q?.toString();
    if (!query) {
      return res.status(400).json({ ok: false, error: 'q 参数必填' });
    }
    const results = await engine.search(query);
    res.json({ ok: true, results, count: results.length });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

// ─── Forgejo（Git 远端引擎） ───

app.get('/api/forgejo/status', async (_req, res) => {
  try {
    res.json({ ok: true, status: await engine.getRepositoryStatus() });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

app.put('/api/forgejo/remote', async (req, res) => {
  try {
    const { url } = req.body;
    if (!url || typeof url !== 'string') {
      return res.status(400).json({ ok: false, error: 'url 必填且为字符串' });
    }
    res.json({ ok: true, status: await engine.configureRemote(url) });
  } catch (err: any) {
    res.status(400).json({ ok: false, error: err.message });
  }
});

app.delete('/api/forgejo/remote', async (_req, res) => {
  try {
    res.json({ ok: true, status: await engine.removeRemote() });
  } catch (err: any) {
    res.status(400).json({ ok: false, error: err.message });
  }
});

app.post('/api/forgejo/fetch', async (_req, res) => {
  try {
    res.json({ ok: true, status: await engine.fetchRemote() });
  } catch (err: any) {
    res.status(502).json({ ok: false, error: err.message });
  }
});

app.post('/api/forgejo/pull', async (_req, res) => {
  try {
    res.json({ ok: true, status: await engine.pullRemote() });
  } catch (err: any) {
    res.status(409).json({ ok: false, error: err.message });
  }
});

app.post('/api/forgejo/push', async (req, res) => {
  try {
    if (req.body?.confirm !== true) {
      return res.status(428).json({ ok: false, error: '推送需要用户明确确认' });
    }
    res.json({ ok: true, status: await engine.pushRemote() });
  } catch (err: any) {
    res.status(409).json({ ok: false, error: err.message });
  }
});

// ─── Agent（人格体） ───

let personaAgent: PersonaAgent | null = null;

function getAgent(): PersonaAgent {
  if (!personaAgent) {
    personaAgent = createDefaultPersona(engine);
    console.log('人格体已创建:', personaAgent.getDefinition().name);
  }
  return personaAgent;
}

// Agent 状态
app.get('/api/agent/status', (_req, res) => {
  const agent = getAgent();
  const def = agent.getDefinition();
  const runtime = agent.getRuntimeStatus();
  res.json({
    ok: true,
    persona: {
      id: def.id,
      name: def.name,
      role: def.role,
      model: def.model,
      permissionMode: def.permissionMode,
    },
    conversationLength: agent.getConversation().length,
    configured: runtime.configured,
    operational: runtime.operational,
    tools: runtime.toolNames,
    engine: 'git',
    repo: REPO_PATH,
  });
});

// Agent 对话
app.post('/api/agent/chat', async (req, res) => {
  try {
    const { message } = req.body;
    if (!message || typeof message !== 'string') {
      return res.status(400).json({ ok: false, error: 'message 必填且为字符串' });
    }
    const agent = getAgent();
    const reply = await agent.chat(message);
    res.json({
      ok: true,
      reply,
      conversationLength: agent.getConversation().length,
      pendingActions: agent.getPendingActions(),
    });
  } catch (err: any) {
    res.status(500).json({ ok: false, error: err.message });
  }
});

app.get('/api/agent/actions', (_req, res) => {
  res.json({ ok: true, actions: getAgent().getPendingActions() });
});

app.post('/api/agent/actions/:actionId/confirm', async (req, res) => {
  try {
    const result = await getAgent().confirmAction(req.params.actionId);
    res.json({ ok: true, result, actions: getAgent().getPendingActions() });
  } catch (err: any) {
    res.status(409).json({ ok: false, error: err.message });
  }
});

app.post('/api/agent/actions/:actionId/reject', (req, res) => {
  try {
    getAgent().rejectAction(req.params.actionId);
    res.json({ ok: true, actions: getAgent().getPendingActions() });
  } catch (err: any) {
    res.status(409).json({ ok: false, error: err.message });
  }
});

// Agent 对话历史
app.get('/api/agent/conversation', (_req, res) => {
  const agent = getAgent();
  res.json({ ok: true, messages: agent.getConversation() });
});

// 清空对话
app.post('/api/agent/clear', (_req, res) => {
  const agent = getAgent();
  agent.clearConversation();
  res.json({ ok: true, message: '对话已清空' });
});

// ─── 启动 ───

async function start() {
  await engine.init();
  // 初始化人格体
  getAgent();
  app.listen(PORT, '127.0.0.1', () => {
    console.log(`光湖知识库 API 已启动: http://localhost:${PORT}`);
    const runtime = personaAgent?.getRuntimeStatus();
    console.log(`人格体运行状态: ${runtime?.operational ? '已接入模型' : '等待模型配置'}`);
    console.log(`仓库路径: ${REPO_PATH}`);
  });
}

start().catch(err => {
  console.error('启动失败:', err);
  process.exit(1);
});

export default app;