autosnippet 2.8.3 → 2.10.0

package/lib/http/routes/knowledge.js

@@ -0,0 +1,246 @@
+/**
+ * Knowledge API 路由 (V3)
+ * 统一知识条目的 CRUD + 生命周期操作
+ * 替代 recipes.js + candidates.js （旧路由继续保留用于向后兼容）
+ */
+
+import express from 'express';
+import { asyncHandler } from '../middleware/errorHandler.js';
+import { getServiceContainer } from '../../injection/ServiceContainer.js';
+import { ValidationError } from '../../shared/errors/index.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+import { getContext, safeInt } from '../utils/routeHelpers.js';
+
+const logger = Logger.getInstance();
+const router = express.Router();
+
+const MAX_BATCH_SIZE = 100;
+
+/* ═══ 查询 ═══════════════════════════════════════════════ */
+
+/**
+ * GET /api/v1/knowledge
+ * 获取知识条目列表（支持筛选和分页）
+ */
+router.get('/', asyncHandler(async (req, res) => {
+  const { lifecycle, kind, category, language, knowledgeType, scope, keyword, tag, source } = req.query;
+  const page = safeInt(req.query.page, 1);
+  const pageSize = safeInt(req.query.limit, 20, 1, 1000);
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+
+  if (keyword) {
+    const result = await knowledgeService.search(keyword, { page, pageSize });
+    return res.json({ success: true, data: result });
+  }
+
+  const filters = {};
+  if (lifecycle)     filters.lifecycle = lifecycle;
+  if (kind)          filters.kind = kind;
+  if (category)      filters.category = category;
+  if (language)      filters.language = language;
+  if (knowledgeType) filters.knowledgeType = knowledgeType;
+  if (scope)         filters.scope = scope;
+  if (tag)           filters.tag = tag;
+  if (source)        filters.source = source;
+
+  const result = await knowledgeService.list(filters, { page, pageSize });
+  res.json({ success: true, data: result });
+}));
+
+/**
+ * GET /api/v1/knowledge/stats
+ * 获取统计信息
+ */
+router.get('/stats', asyncHandler(async (req, res) => {
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const stats = await knowledgeService.getStats();
+  res.json({ success: true, data: stats });
+}));
+
+/**
+ * GET /api/v1/knowledge/:id
+ * 获取知识条目详情
+ */
+router.get('/:id', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const entry = await knowledgeService.get(id);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/* ═══ CRUD ═══════════════════════════════════════════════ */
+
+/**
+ * POST /api/v1/knowledge
+ * 创建知识条目（wire format 直通）
+ */
+router.post('/', asyncHandler(async (req, res) => {
+  const data = req.body;
+
+  if (!data.title || !data.content) {
+    throw new ValidationError('title and content are required');
+  }
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.create(data, context);
+  res.status(201).json({
+    success: true,
+    data: entry.toJSON(),
+  });
+}));
+
+/**
+ * PATCH /api/v1/knowledge/:id
+ * 更新知识条目（白名单字段）
+ */
+router.patch('/:id', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.update(id, req.body, context);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/**
+ * DELETE /api/v1/knowledge/:id
+ * 删除知识条目
+ */
+router.delete('/:id', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const result = await knowledgeService.delete(id, context);
+  res.json({ success: true, data: result });
+}));
+
+/* ═══ 生命周期操作（3 状态: pending / active / deprecated）═══ */
+
+/**
+ * PATCH /api/v1/knowledge/:id/publish
+ * 发布 (pending → active) — 仅开发者
+ */
+router.patch('/:id/publish', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.publish(id, context);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/**
+ * PATCH /api/v1/knowledge/:id/deprecate
+ * 废弃 (pending|active → deprecated)
+ */
+router.patch('/:id/deprecate', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const { reason } = req.body;
+
+  if (!reason) {
+    throw new ValidationError('reason is required for deprecation');
+  }
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.deprecate(id, reason, context);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/**
+ * PATCH /api/v1/knowledge/:id/reactivate
+ * 重新激活 (deprecated → pending)
+ */
+router.patch('/:id/reactivate', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const entry = await knowledgeService.reactivate(id, context);
+  res.json({ success: true, data: entry.toJSON() });
+}));
+
+/* ═══ 批量操作 ═══════════════════════════════════════════ */
+
+/**
+ * POST /api/v1/knowledge/batch-publish
+ * 批量发布 (pending → active)
+ * 支持 autoApprovableOnly=true 参数，只发布 auto_approvable 的条目
+ */
+router.post('/batch-publish', asyncHandler(async (req, res) => {
+  const { ids } = req.body;
+
+  if (!Array.isArray(ids) || ids.length === 0) {
+    throw new ValidationError('ids array is required and must not be empty');
+  }
+  if (ids.length > MAX_BATCH_SIZE) {
+    throw new ValidationError(`Batch size exceeds limit of ${MAX_BATCH_SIZE}`);
+  }
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+  const context = getContext(req);
+
+  const results = await Promise.allSettled(
+    ids.map(id => knowledgeService.publish(id, context)),
+  );
+
+  const published = results.filter(r => r.status === 'fulfilled').map(r => r.value.toJSON());
+  const failed = results
+    .map((r, i) => r.status === 'rejected' ? { id: ids[i], error: r.reason?.message } : null)
+    .filter(Boolean);
+
+  res.json({
+    success: true,
+    data: { published, failed, total: ids.length, successCount: published.length, failureCount: failed.length },
+  });
+}));
+
+/* ═══ 使用 / 质量 ═══════════════════════════════════════ */
+
+/**
+ * POST /api/v1/knowledge/:id/usage
+ * 记录使用（adoption / application / guard_hit / view / success）
+ */
+router.post('/:id/usage', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const { type = 'adoption', feedback } = req.body;
+  const context = getContext(req);
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+
+  await knowledgeService.incrementUsage(id, type, { actor: context.userId, feedback });
+  res.json({ success: true, message: `${type} recorded` });
+}));
+
+/**
+ * PATCH /api/v1/knowledge/:id/quality
+ * 重新计算质量评分
+ */
+router.patch('/:id/quality', asyncHandler(async (req, res) => {
+  const { id } = req.params;
+  const context = getContext(req);
+
+  const container = getServiceContainer();
+  const knowledgeService = container.get('knowledgeService');
+
+  const result = await knowledgeService.updateQuality(id, context);
+  res.json({ success: true, data: result });
+}));
+
+export default router;

package/lib/http/routes/search.js

@@ -44,13 +44,13 @@ router.get('/', asyncHandler(async (req, res) => {
   const results = {};
   const pagination = { page, pageSize: limit };
 
-  // 搜索 Recipe（统一模型，包含所有知识类型）
+  // 搜索知识条目（V3 统一模型）
   if (type === 'all' || type === 'recipe' || type === 'solution') {
     try {
-      const recipeService = container.get('recipeService');
-      results.recipes = await recipeService.searchRecipes(q, pagination);
+      const knowledgeService = container.get('knowledgeService');
+      results.recipes = await knowledgeService.search(q, pagination);
     } catch (err) {
-      logger.warn('Recipe 搜索失败', { query: q, error: err.message });
+      logger.warn('Knowledge 搜索失败', { query: q, error: err.message });
       results.recipes = { items: [], total: 0 };
     }
   }
@@ -66,11 +66,11 @@ router.get('/', asyncHandler(async (req, res) => {
     }
   }
 
-  // 搜索 Candidate
+  // 搜索候选知识条目 (V3: lifecycle=draft/pending)
   if (type === 'all' || type === 'candidate') {
     try {
-      const candidateService = container.get('candidateService');
-      results.candidates = await candidateService.searchCandidates(q, pagination);
+      const knowledgeService = container.get('knowledgeService');
+      results.candidates = await knowledgeService.search(q, pagination);
     } catch (err) {
       logger.warn('Candidate 搜索失败', { query: q, error: err.message });
       results.candidates = { items: [], total: 0 };
@@ -172,18 +172,14 @@ router.get('/graph/all', asyncHandler(async (req, res) => {
   const nodeTypes = {};   // id → 主要类型（供前端区分渲染）
   const nodeCategories = {};  // id → category/target 名（供前端分组布局）
   if (nodeMap.size > 0) {
-    const recipeService = container.get('recipeService');
-    // 使用 repository.findById 避免 RecipeService.getRecipe 在找不到时记录 error 日志
-    const recipeRepo = recipeService?.recipeRepository ?? null;
+    const knowledgeRepo = container.get('knowledgeRepository');
     for (const [id, types] of nodeMap) {
-      // 记录节点主要类型
       const primaryType = types.has('recipe') ? 'recipe' : [...types][0];
       nodeTypes[id] = primaryType;
 
-      if (primaryType === 'recipe' && recipeRepo) {
-        // 仅 recipe 类型才查 DB；直接用 repo 避免 NotFoundError 日志噪音
+      if ((primaryType === 'recipe' || primaryType === 'knowledge') && knowledgeRepo) {
         try {
-          const r = await recipeRepo.findById(id);
+          const r = await knowledgeRepo.findById(id);
           if (r) {
             nodeLabels[id] = r.title || r.name || id;
             nodeCategories[id] = r.category || '';
@@ -191,7 +187,6 @@ router.get('/graph/all', asyncHandler(async (req, res) => {
           }
         } catch { /* not found – fall through */ }
       }
-      // module / candidate 或查不到的 recipe → 直接用 ID
       nodeLabels[id] = id;
     }
   }
@@ -226,9 +221,9 @@ router.post('/context-aware', asyncHandler(async (req, res) => {
     throw new ValidationError('keyword is required');
   }
   const container = getServiceContainer();
-  const recipeService = container.get('recipeService');
+  const knowledgeService = container.get('knowledgeService');
   const pageSize = Math.min(limit || 10, 100);
-  const list = await recipeService.searchRecipes(keyword, { page: 1, pageSize });
+  const list = await knowledgeService.search(keyword, { page: 1, pageSize });
   const items = list.data || list.items || [];
   const results = items.map(r => ({
     name: (r.title || r.id) + '.md',

package/lib/http/routes/skills.js

@@ -5,7 +5,7 @@
 
 import express from 'express';
 import { asyncHandler } from '../middleware/errorHandler.js';
-import { listSkills, loadSkill, createSkill, suggestSkills } from '../../external/mcp/handlers/skill.js';
+import { listSkills, loadSkill, createSkill, deleteSkill, updateSkill, suggestSkills } from '../../external/mcp/handlers/skill.js';
 import { ValidationError } from '../../shared/errors/index.js';
 
 const router = express.Router();
@@ -107,4 +107,47 @@ router.post('/', asyncHandler(async (req, res) => {
   res.status(201).json({ success: true, data: parsed.data });
 }));
 
+/**
+ * PUT /api/v1/skills/:name
+ * 更新项目级 Skill（description / content）
+ */
+router.put('/:name', asyncHandler(async (req, res) => {
+  const { name } = req.params;
+  const { description, content } = req.body;
+
+  if (!description && !content) {
+    throw new ValidationError('At least one of description or content must be provided');
+  }
+
+  const raw = updateSkill(null, { name, description, content });
+  const parsed = JSON.parse(raw);
+
+  if (!parsed.success) {
+    const status = parsed.error?.code === 'SKILL_NOT_FOUND' ? 404
+      : parsed.error?.code === 'BUILTIN_PROTECTED' ? 403 : 500;
+    return res.status(status).json(parsed);
+  }
+
+  res.json({ success: true, data: parsed.data });
+}));
+
+/**
+ * DELETE /api/v1/skills/:name
+ * 删除项目级 Skill
+ */
+router.delete('/:name', asyncHandler(async (req, res) => {
+  const { name } = req.params;
+
+  const raw = deleteSkill(null, { name });
+  const parsed = JSON.parse(raw);
+
+  if (!parsed.success) {
+    const status = parsed.error?.code === 'SKILL_NOT_FOUND' ? 404
+      : parsed.error?.code === 'BUILTIN_PROTECTED' ? 403 : 500;
+    return res.status(status).json(parsed);
+  }
+
+  res.json({ success: true, data: parsed.data });
+}));
+
 export default router;

package/lib/infrastructure/cache/GraphCache.js

@@ -0,0 +1,143 @@
+/**
+ * GraphCache — 基于文件的图数据持久化缓存
+ *
+ * 功能:
+ * 1. 将图数据序列化为 JSON 写入磁盘
+ * 2. 基于 contentHash 判断缓存是否有效（Package.swift / 源文件）
+ * 3. 支持 SPM 依赖图和 AST ProjectGraph 两种场景
+ *
+ * 缓存位置: {projectRoot}/.autosnippet/cache/
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import Logger from '../logging/Logger.js';
+
+export class GraphCache {
+  #cacheDir;
+  #logger;
+
+  /**
+   * @param {string} projectRoot 项目根目录
+   */
+  constructor(projectRoot) {
+    this.#cacheDir = join(projectRoot, '.autosnippet', 'cache');
+    this.#logger = Logger.getInstance();
+  }
+
+  /**
+   * 保存缓存
+   * @param {string} key 缓存键名（生成 {key}.json）
+   * @param {object} data 要缓存的数据
+   * @param {object} meta 元信息（含 hash、timestamp 等）
+   */
+  save(key, data, meta = {}) {
+    try {
+      if (!existsSync(this.#cacheDir)) {
+        mkdirSync(this.#cacheDir, { recursive: true });
+      }
+      const payload = {
+        version: 1,
+        savedAt: new Date().toISOString(),
+        ...meta,
+        data,
+      };
+      const filePath = join(this.#cacheDir, `${key}.json`);
+      writeFileSync(filePath, JSON.stringify(payload), 'utf-8');
+      this.#logger.debug(`[GraphCache] saved: ${key} (${JSON.stringify(payload).length} bytes)`);
+    } catch (err) {
+      this.#logger.warn(`[GraphCache] save failed for ${key}: ${err.message}`);
+    }
+  }
+
+  /**
+   * 加载缓存
+   * @param {string} key 缓存键名
+   * @returns {{ data: object, [key: string]: any } | null}
+   */
+  load(key) {
+    try {
+      const filePath = join(this.#cacheDir, `${key}.json`);
+      if (!existsSync(filePath)) return null;
+      const raw = readFileSync(filePath, 'utf-8');
+      return JSON.parse(raw);
+    } catch (err) {
+      this.#logger.warn(`[GraphCache] load failed for ${key}: ${err.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * 检查缓存是否有效（hash 匹配）
+   * @param {string} key 缓存键
+   * @param {string} currentHash 当前内容的 hash
+   * @returns {boolean}
+   */
+  isValid(key, currentHash) {
+    const cached = this.load(key);
+    if (!cached) return false;
+    return cached.contentHash === currentHash;
+  }
+
+  /**
+   * 删除缓存
+   * @param {string} key
+   */
+  invalidate(key) {
+    try {
+      const filePath = join(this.#cacheDir, `${key}.json`);
+      if (existsSync(filePath)) {
+        unlinkSync(filePath);
+        this.#logger.debug(`[GraphCache] invalidated: ${key}`);
+      }
+    } catch (err) {
+      this.#logger.warn(`[GraphCache] invalidate failed for ${key}: ${err.message}`);
+    }
+  }
+
+  /**
+   * 计算文件内容 hash
+   * @param {string} filePath 文件绝对路径
+   * @returns {string} sha256 hex (前 16 字符)
+   */
+  computeFileHash(filePath) {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      return this.computeContentHash(content);
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * 计算字符串内容 hash
+   * @param {string} content
+   * @returns {string} sha256 hex (前 16 字符)
+   */
+  computeContentHash(content) {
+    return createHash('sha256').update(content).digest('hex').substring(0, 16);
+  }
+
+  /**
+   * 批量计算文件 hash 映射
+   * @param {string[]} filePaths 文件绝对路径数组
+   * @param {string} projectRoot 项目根目录
+   * @returns {Object<string, string>} { relativePath: hash }
+   */
+  computeFileHashes(filePaths, projectRoot) {
+    const hashes = {};
+    for (const fp of filePaths) {
+      const rel = relative(projectRoot, fp);
+      hashes[rel] = this.computeFileHash(fp);
+    }
+    return hashes;
+  }
+
+  /**
+   * 获取缓存目录路径
+   */
+  getCacheDir() {
+    return this.#cacheDir;
+  }
+}

package/lib/infrastructure/database/migrations/015_create_token_usage.js

@@ -0,0 +1,27 @@
+/**
+ * Migration 015: Create token_usage table
+ *
+ * 持久化 AI 调用的 Token 消耗记录，支持近 7 日消耗趋势查询。
+ * 每次 ChatAgent.execute() 完成后写入一条记录。
+ */
+export default function migrate(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS token_usage (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      timestamp   INTEGER NOT NULL,
+      source      TEXT NOT NULL DEFAULT 'unknown',
+      dimension   TEXT,
+      provider    TEXT,
+      model       TEXT,
+      input_tokens  INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      total_tokens  INTEGER NOT NULL DEFAULT 0,
+      duration_ms   INTEGER,
+      tool_calls    INTEGER DEFAULT 0,
+      session_id    TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_token_usage_timestamp ON token_usage(timestamp);
+    CREATE INDEX IF NOT EXISTS idx_token_usage_source    ON token_usage(source);
+  `);
+}