autosnippet 2.13.0 → 2.15.0

package/lib/http/routes/recipes.js

@@ -0,0 +1,163 @@
+/**
+ * Recipes API 路由
+ * 提供 Recipe 知识图谱关系发现等操作
+ *
+ * 说明: Recipe 的 CRUD 已由 knowledge.js 统一提供，
+ * 此路由仅处理 Recipe 特有的批量 AI 操作。
+ */
+
+import express from 'express';
+import { asyncHandler } from '../middleware/errorHandler.js';
+import { getServiceContainer } from '../../injection/ServiceContainer.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+
+const router = express.Router();
+const logger = Logger.getInstance();
+
+/* ═══ 进程内任务状态（单实例足够） ═══════════════════════ */
+
+let discoverTask = {
+  status: 'idle',       // idle | running | done | error
+  startedAt: null,
+  finishedAt: null,
+  discovered: 0,
+  totalPairs: 0,
+  batchErrors: 0,
+  error: null,
+  elapsed: 0,
+  message: null,
+};
+
+function resetTask() {
+  discoverTask = {
+    status: 'idle',
+    startedAt: null,
+    finishedAt: null,
+    discovered: 0,
+    totalPairs: 0,
+    batchErrors: 0,
+    error: null,
+    elapsed: 0,
+    message: null,
+  };
+}
+
+/* ═══ POST /api/v1/recipes/discover-relations ═══════════ */
+
+/**
+ * 异步启动 AI 批量发现 Recipe 知识图谱关系
+ * Body: { batchSize?: number }
+ *
+ * 立即返回 { status: 'started' }，后台执行。
+ * Dashboard 通过 GET /discover-relations/status 轮询进度。
+ */
+router.post('/discover-relations', asyncHandler(async (req, res) => {
+  const { batchSize = 20 } = req.body;
+
+  // 如果已有任务在运行，返回当前状态
+  if (discoverTask.status === 'running') {
+    const elapsed = Math.round((Date.now() - new Date(discoverTask.startedAt).getTime()) / 1000);
+    return res.json({
+      success: true,
+      data: {
+        status: 'running',
+        startedAt: discoverTask.startedAt,
+        elapsed,
+        message: 'AI 分析仍在进行中',
+      },
+    });
+  }
+
+  // 检查 ChatAgent 是否可用
+  const container = getServiceContainer();
+  let chatAgent;
+  try {
+    chatAgent = container.get('chatAgent');
+  } catch {
+    return res.json({
+      success: true,
+      data: { status: 'error', error: 'ChatAgent 不可用，请检查 AI Provider 配置' },
+    });
+  }
+
+  // 快速检查：至少需要 2 条活跃 Recipe
+  try {
+    const knowledgeService = container.get('knowledgeService');
+    const { items = [], data = [] } = await knowledgeService.list(
+      { lifecycle: 'active' }, { page: 1, pageSize: 5 },
+    );
+    const count = items.length || data.length;
+    if (count < 2) {
+      return res.json({
+        success: true,
+        data: {
+          status: 'empty',
+          message: `只有 ${count} 条活跃 Recipe，至少需要 2 条才能分析关系`,
+        },
+      });
+    }
+  } catch {
+    // 如果 list 失败，继续尝试（让 runTask 给出具体错误）
+  }
+
+  // 重置并启动后台任务
+  resetTask();
+  discoverTask.status = 'running';
+  discoverTask.startedAt = new Date().toISOString();
+
+  // 异步执行，不 await
+  (async () => {
+    try {
+      const result = await chatAgent.runTask('discover_all_relations', { batchSize });
+      discoverTask.status = 'done';
+      discoverTask.finishedAt = new Date().toISOString();
+      discoverTask.discovered = result.discovered || 0;
+      discoverTask.totalPairs = result.totalPairs || 0;
+      discoverTask.batchErrors = result.batchErrors || 0;
+      discoverTask.elapsed = Math.round(
+        (new Date(discoverTask.finishedAt).getTime() - new Date(discoverTask.startedAt).getTime()) / 1000,
+      );
+      logger.info('Discover relations completed', {
+        discovered: discoverTask.discovered,
+        totalPairs: discoverTask.totalPairs,
+        batchErrors: discoverTask.batchErrors,
+        elapsed: discoverTask.elapsed,
+      });
+    } catch (err) {
+      discoverTask.status = 'error';
+      discoverTask.finishedAt = new Date().toISOString();
+      discoverTask.error = err.message;
+      discoverTask.elapsed = Math.round(
+        (new Date(discoverTask.finishedAt).getTime() - new Date(discoverTask.startedAt).getTime()) / 1000,
+      );
+      logger.error('Discover relations failed', { error: err.message });
+    }
+  })();
+
+  res.json({
+    success: true,
+    data: {
+      status: 'started',
+      startedAt: discoverTask.startedAt,
+      message: 'AI 分析已启动，正在后台运行',
+    },
+  });
+}));
+
+/* ═══ GET /api/v1/recipes/discover-relations/status ═════ */
+
+/**
+ * 查询关系发现任务状态
+ */
+router.get('/discover-relations/status', asyncHandler(async (req, res) => {
+  const data = { ...discoverTask };
+
+  // 计算实时 elapsed
+  if (data.status === 'running' && data.startedAt) {
+    data.elapsed = Math.round((Date.now() - new Date(data.startedAt).getTime()) / 1000);
+  }
+
+  res.json({ success: true, data });
+}));
+
+export default router;

package/lib/repository/base/BaseRepository.js

@@ -1,4 +1,5 @@
 import Logger from '../../infrastructure/logging/Logger.js';
+import { unixNow } from '../../shared/utils/common.js';
 
 /** Only allow safe SQL identifier characters: letters, digits, underscore */
 const SAFE_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
@@ -180,7 +181,7 @@ export class BaseRepository {
       `;
 
       const stmt = this.db.prepare(query);
-      stmt.run(...updateValues, Math.floor(Date.now() / 1000), id);
+      stmt.run(...updateValues, unixNow(), id);
 
       return this.findById(id);
     } catch (error) {

package/lib/repository/knowledge/KnowledgeRepository.impl.js

@@ -1,6 +1,7 @@
 import { BaseRepository } from '../base/BaseRepository.js';
 import { KnowledgeEntry, Lifecycle, inferKind } from '../../domain/knowledge/index.js';
 import Logger from '../../infrastructure/logging/Logger.js';
+import { safeJsonParse, safeJsonStringify, unixNow } from '../../shared/utils/common.js';
 
 /**
  * KnowledgeRepositoryImpl — 统一知识实体仓储实现
@@ -57,7 +58,7 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
         const row = this._entityToRow(updates);
         delete row.id;
         delete row.createdAt;
-        row.updatedAt = Math.floor(Date.now() / 1000);
+        row.updatedAt = unixNow();
 
         const setClauses = Object.keys(row).map(k => `${k} = ?`).join(', ');
         this.db.prepare(`UPDATE knowledge_entries SET ${setClauses} WHERE id = ?`)
@@ -69,7 +70,7 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
       const merged = KnowledgeEntry.fromJSON({
         ...existing.toJSON(),
         ...updates,
-        updatedAt: Math.floor(Date.now() / 1000),
+        updatedAt: unixNow(),
       });
       const row = this._entityToRow(merged);
       delete row.id;
@@ -248,17 +249,17 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
     return new KnowledgeEntry({
       ...row,
       // JSON 列需要 parse
-      lifecycleHistory: this._parseJson(row.lifecycleHistory, []),
-      tags:             this._parseJson(row.tags, []),
-      content:          this._parseJson(row.content, {}),
-      relations:        this._parseJson(row.relations, {}),
-      constraints:      this._parseJson(row.constraints, {}),
-      reasoning:        this._parseJson(row.reasoning, {}),
-      quality:          this._parseJson(row.quality, {}),
-      stats:            this._parseJson(row.stats, {}),
-      headers:          this._parseJson(row.headers, []),
-      headerPaths:      this._parseJson(row.headerPaths, []),
-      agentNotes:       this._parseJson(row.agentNotes, null),
+      lifecycleHistory: safeJsonParse(row.lifecycleHistory, []),
+      tags:             safeJsonParse(row.tags, []),
+      content:          safeJsonParse(row.content, {}),
+      relations:        safeJsonParse(row.relations, {}),
+      constraints:      safeJsonParse(row.constraints, {}),
+      reasoning:        safeJsonParse(row.reasoning, {}),
+      quality:          safeJsonParse(row.quality, {}),
+      stats:            safeJsonParse(row.stats, {}),
+      headers:          safeJsonParse(row.headers, []),
+      headerPaths:      safeJsonParse(row.headerPaths, []),
+      agentNotes:       safeJsonParse(row.agentNotes, null),
       // SQLite INTEGER → boolean
       autoApprovable:   !!row.autoApprovable,
       includeHeaders:   !!row.includeHeaders,
@@ -271,13 +272,13 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
    * @returns {Object}
    */
   _entityToRow(e) {
-    const now = Math.floor(Date.now() / 1000);
+    const now = unixNow();
     return {
       id:                e.id,
       title:             e.title,
       description:       e.description || '',
       lifecycle:         e.lifecycle,
-      lifecycleHistory:  JSON.stringify(e.lifecycleHistory || []),
+      lifecycleHistory:  safeJsonStringify(e.lifecycleHistory || [], '[]'),
       autoApprovable:    e.autoApprovable ? 1 : 0,
       language:          e.language,
       category:          e.category,
@@ -286,24 +287,24 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
       complexity:        e.complexity || 'intermediate',
       scope:             e.scope || null,
       difficulty:        e.difficulty || null,
-      tags:              JSON.stringify(e.tags || []),
+      tags:              safeJsonStringify(e.tags || [], '[]'),
       trigger:           e.trigger || '',
       topicHint:         e.topicHint || '',
       whenClause:        e.whenClause || '',
       doClause:          e.doClause || '',
       dontClause:        e.dontClause || '',
       coreCode:          e.coreCode || '',
-      content:           JSON.stringify(typeof e.content?.toJSON === 'function' ? e.content.toJSON() : (e.content || {})),
-      relations:         JSON.stringify(typeof e.relations?.toJSON === 'function' ? e.relations.toJSON() : (e.relations || {})),
-      constraints:       JSON.stringify(typeof e.constraints?.toJSON === 'function' ? e.constraints.toJSON() : (e.constraints || {})),
-      reasoning:         JSON.stringify(typeof e.reasoning?.toJSON === 'function' ? e.reasoning.toJSON() : (e.reasoning || {})),
-      quality:           JSON.stringify(typeof e.quality?.toJSON === 'function' ? e.quality.toJSON() : (e.quality || {})),
-      stats:             JSON.stringify(typeof e.stats?.toJSON === 'function' ? e.stats.toJSON() : (e.stats || {})),
-      headers:           JSON.stringify(e.headers || []),
-      headerPaths:       JSON.stringify(e.headerPaths || []),
+      content:           safeJsonStringify(e.content || {}),
+      relations:         safeJsonStringify(e.relations || {}),
+      constraints:       safeJsonStringify(e.constraints || {}),
+      reasoning:         safeJsonStringify(e.reasoning || {}),
+      quality:           safeJsonStringify(e.quality || {}),
+      stats:             safeJsonStringify(e.stats || {}),
+      headers:           safeJsonStringify(e.headers || [], '[]'),
+      headerPaths:       safeJsonStringify(e.headerPaths || [], '[]'),
       moduleName:        e.moduleName || null,
       includeHeaders:    e.includeHeaders ? 1 : 0,
-      agentNotes:        e.agentNotes ? JSON.stringify(e.agentNotes) : null,
+      agentNotes:        e.agentNotes ? safeJsonStringify(e.agentNotes) : null,
       aiInsight:         e.aiInsight || null,
       reviewedBy:        e.reviewedBy || null,
       reviewedAt:        e.reviewedAt || null,
@@ -326,13 +327,6 @@ export class KnowledgeRepositoryImpl extends BaseRepository {
   _mapRowToEntity(row) {
     return this._rowToEntity(row);
   }
-
-  /** @private 安全解析 JSON */
-  _parseJson(value, fallback) {
-    if (!value || value === 'null') return fallback;
-    if (typeof value === 'object') return value;
-    try { return JSON.parse(value); } catch { return fallback; }
-  }
 }
 
 export default KnowledgeRepositoryImpl;

package/lib/service/automation/FileWatcher.js

@@ -14,6 +14,7 @@ import { readFileSync, accessSync, statSync } from 'node:fs';
 import { basename, join, normalize } from 'node:path';
 import { detectTriggers, REGEX } from './DirectiveDetector.js';
 import { saveEventFilter } from './SaveEventFilter.js';
+import { FILE_WATCHER } from '../../shared/constants.js';
 
 /* ── Handler imports ── */
 import { handleCreate } from './handlers/CreateHandler.js';
@@ -31,7 +32,7 @@ const IGNORED = [
   '**/xcuserdata/**', '**/.build/**', '**/*.swp', '**/*.tmp', '**/*~.m', '**/*~.h',
   '**/DerivedData/**', '**/Pods/**', '**/Carthage/**',
 ];
-const DEBOUNCE_DELAY = 300;
+const DEBOUNCE_DELAY = FILE_WATCHER.DEBOUNCE_DELAY_MS;
 
 /* ────────── FileWatcher ────────── */
 
@@ -76,10 +77,10 @@ export class FileWatcher {
       ignored: IGNORED,
       ignoreInitial: true,
       persistent: true,
-      awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 },
+      awaitWriteFinish: { stabilityThreshold: FILE_WATCHER.STABILITY_THRESHOLD_MS, pollInterval: FILE_WATCHER.POLL_INTERVAL_MS },
       usePolling: process.env.ASD_WATCH_POLLING === 'true',
-      interval: 100,
-      binaryInterval: 300,
+      interval: FILE_WATCHER.POLL_INTERVAL_MS,
+      binaryInterval: FILE_WATCHER.BINARY_INTERVAL_MS,
     });
 
     const handleEvent = (relativePath) => {
@@ -115,17 +116,29 @@ export class FileWatcher {
   }
 
   /**
-   * 停止监听
+   * 停止监听，释放所有资源
    */
   async stop() {
     if (this._watcher) {
+      // 移除所有事件监听器，避免泄漏
+      this._watcher.removeAllListeners();
       await this._watcher.close();
       this._watcher = null;
     }
+    // 清理所有防抖定时器
     for (const timer of this._debounceTimers.values()) {
       clearTimeout(timer);
     }
     this._debounceTimers.clear();
+    // 清理 handler 级别的延时定时器
+    if (this._timeoutLink) {
+      clearTimeout(this._timeoutLink);
+      this._timeoutLink = null;
+    }
+    if (this._timeoutHead) {
+      clearTimeout(this._timeoutHead);
+      this._timeoutHead = null;
+    }
   }
 
   /* ────────── 内部：文件处理（分派到 handlers） ────────── */
@@ -134,7 +147,7 @@ export class FileWatcher {
     try {
       accessSync(fullPath);
       const stat = statSync(fullPath);
-      if (stat.isDirectory() || stat.size > 1024 * 1024) return;
+      if (stat.isDirectory() || stat.size > FILE_WATCHER.MAX_FILE_SIZE_BYTES) return;
     } catch {
       return;
     }

package/lib/service/chat/WorkingMemory.js

@@ -284,6 +284,17 @@ export class WorkingMemory {
       .sort((a, b) => b.importance - a.importance);
   }
 
+  /**
+   * 清空 WorkingMemory — 释放内存
+   * 在 Agent execute 结束后调用，避免残留引用导致内存泄漏
+   */
+  clear() {
+    this.#recentObservations.length = 0;
+    this.#compressedObservations.length = 0;
+    this.#scratchpad.length = 0;
+    this.#totalObservations = 0;
+  }
+
   // ─── 内部 ─────────────────────────────────────────────
 
   /**

package/lib/service/chat/tools.js

@@ -1844,6 +1844,68 @@ const submitCandidate = {
   },
 };
 
+// ────────────────────────────────────────────────────────────
+// 16b. save_document — 保存开发文档到知识库
+// ────────────────────────────────────────────────────────────
+const saveDocument = {
+  name: 'save_document',
+  description: '保存开发文档到知识库（架构设计、排查报告、决策记录、调研笔记等）。仅需 title + markdown，无需 Cursor Delivery 字段。文档自动发布，可通过 autosnippet_search 检索。',
+  parameters: {
+    type: 'object',
+    properties: {
+      title:       { type: 'string', description: '文档标题' },
+      markdown:    { type: 'string', description: '文档 Markdown 全文' },
+      description: { type: 'string', description: '一句话摘要（可选）' },
+      tags:        { type: 'array', items: { type: 'string' }, description: '标签: adr, debug-report, design-doc, research, performance 等' },
+      scope:       { type: 'string', enum: ['universal', 'project-specific'], description: '适用范围（默认 project-specific）' },
+    },
+    required: ['title', 'markdown'],
+  },
+  handler: async (params, ctx) => {
+    const knowledgeService = ctx.container.get('knowledgeService');
+
+    const data = {
+      title:         params.title.trim(),
+      description:   params.description || '',
+      knowledgeType: 'dev-document',
+      kind:          'fact',
+      source:        'agent',
+      scope:         params.scope || 'project-specific',
+      tags:          params.tags || [],
+      content: {
+        markdown: params.markdown,
+        pattern:  '',
+      },
+      trigger:    '',
+      doClause:   '',
+      dontClause: '',
+      whenClause: '',
+      topicHint:  '',
+      coreCode:   '',
+      reasoning: {
+        whyStandard: 'Agent development document',
+        sources:     ['agent'],
+        confidence:  0.8,
+      },
+    };
+
+    const saved = await knowledgeService.create(data, { userId: 'agent' });
+
+    // 自动发布（文档不需要人工审核）
+    try {
+      await knowledgeService.publish(saved.id, { userId: 'agent' });
+    } catch { /* best effort */ }
+
+    return {
+      id:            saved.id,
+      title:         saved.title,
+      lifecycle:     'active',
+      knowledgeType: 'dev-document',
+      message:       `文档「${saved.title}」已保存到知识库`,
+    };
+  },
+};
+
 // ────────────────────────────────────────────────────────────
 // 17. approve_candidate
 // ────────────────────────────────────────────────────────────
@@ -3273,6 +3335,7 @@ export const ALL_TOOLS = [
   generateGuardRule,
   // 生命周期操作类 (7)
   submitCandidate,
+  saveDocument,
   approveCandidate,
   rejectCandidate,
   publishRecipe,

package/lib/service/cursor/CursorDeliveryPipeline.js

@@ -15,7 +15,9 @@ import { TopicClassifier } from './TopicClassifier.js';
 import { RulesGenerator } from './RulesGenerator.js';
 import { SkillsSyncer } from './SkillsSyncer.js';
 import { estimateTokens, BUDGET } from './TokenBudget.js';
+import { KNOWLEDGE_CONFIDENCE, DELIVERY_RANK } from '../../shared/constants.js';
 import path from 'node:path';
+import fs from 'node:fs';
 
 export class CursorDeliveryPipeline {
   /**
@@ -48,6 +50,7 @@ export class CursorDeliveryPipeline {
       channelA: { rulesCount: 0, tokensUsed: 0 },
       channelB: { topicCount: 0, patternsCount: 0, totalTokens: 0 },
       channelC: { synced: 0, skipped: 0, errors: 0 },
+      channelD: { documentsCount: 0, filesWritten: 0 },
       totalTokensUsed: 0,
       duration: 0,
     };
@@ -57,9 +60,9 @@ export class CursorDeliveryPipeline {
       const entries = await this._loadEntries();
       this.logger.info?.(`[CursorDelivery] Loaded ${entries.length} knowledge entries`);
 
-      // 2. 分类：rules vs patterns vs facts
-      const { rules, patterns } = this._classify(entries);
-      this.logger.info?.(`[CursorDelivery] Classified: ${rules.length} rules, ${patterns.length} patterns`);
+      // 2. 分类：rules vs patterns vs facts vs documents
+      const { rules, patterns, documents } = this._classify(entries);
+      this.logger.info?.(`[CursorDelivery] Classified: ${rules.length} rules, ${patterns.length} patterns, ${documents.length} documents`);
 
       // 3. 清理旧的动态生成文件
       this.rulesGenerator.cleanDynamicFiles();
@@ -76,6 +79,10 @@ export class CursorDeliveryPipeline {
       const channelC = await this._generateChannelC();
       stats.channelC = channelC;
 
+      // ── Channel D: Dev Documents → references ──
+      const channelD = this._generateChannelD(documents);
+      stats.channelD = channelD;
+
       // 统计
       stats.totalTokensUsed = channelA.tokensUsed + channelB.totalTokens;
       stats.duration = Date.now() - startTime;
@@ -83,9 +90,10 @@ export class CursorDeliveryPipeline {
       this.logger.info?.(`[CursorDelivery] Done in ${stats.duration}ms — ` +
         `A: ${channelA.rulesCount} rules (${channelA.tokensUsed} tokens), ` +
         `B: ${channelB.topicCount} topics (${channelB.totalTokens} tokens), ` +
-        `C: ${channelC.synced} skills synced`);
+        `C: ${channelC.synced} skills synced, ` +
+        `D: ${channelD.documentsCount} documents`);
 
-      return { channelA, channelB, channelC, stats };
+      return { channelA, channelB, channelC, channelD, stats };
     } catch (error) {
       this.logger.error?.(`[CursorDelivery] Error: ${error.message}`);
       throw error;
@@ -120,10 +128,10 @@ export class CursorDeliveryPipeline {
         { page: 1, pageSize: 200 }
       );
       const pendingItems = this._extractItems(pending);
-      // 过滤高置信度 pending（quality.confidence >= 0.7 或无 quality 字段）
+      // 过滤高置信度 pending（quality.confidence >= PENDING_MIN 或无 quality 字段）
       const highConfPending = pendingItems.filter(e => {
         const conf = e.quality?.confidence;
-        return conf === undefined || conf === null || conf >= 0.7;
+        return conf === undefined || conf === null || conf >= KNOWLEDGE_CONFIDENCE.PENDING_MIN;
       });
       allEntries.push(...highConfPending);
     } catch (e) {
@@ -146,16 +154,23 @@ export class CursorDeliveryPipeline {
 
   /**
    * 按 kind 分类知识条目
+   * dev-document 类型单独分流，不进入 Channel A/B 压缩
    * @private
    */
   _classify(entries) {
-    const rules = [], patterns = [], facts = [];
+    const rules = [], patterns = [], facts = [], documents = [];
     for (const entry of entries) {
-      if (entry.kind === 'rule') rules.push(entry);
-      else if (entry.kind === 'fact') facts.push(entry);
-      else patterns.push(entry);  // 无 kind 或 kind='pattern' → pattern
+      if (entry.knowledgeType === 'dev-document') {
+        documents.push(entry);
+      } else if (entry.kind === 'rule') {
+        rules.push(entry);
+      } else if (entry.kind === 'fact') {
+        facts.push(entry);
+      } else {
+        patterns.push(entry);  // 无 kind 或 kind='pattern' → pattern
+      }
     }
-    return { rules, patterns, facts };
+    return { rules, patterns, facts, documents };
   }
 
   /**
@@ -176,10 +191,10 @@ export class CursorDeliveryPipeline {
    */
   _rankScore(entry) {
     let score = 0;
-    score += (entry.quality?.confidence || 0.5) * 50;
-    score += (entry.quality?.authorityScore || 0) * 30;
-    score += Math.min(entry.stats?.useCount || 0, 10) * 2;
-    if (entry.lifecycle === 'active') score += 10;
+    score += (entry.quality?.confidence || KNOWLEDGE_CONFIDENCE.RANK_DEFAULT) * DELIVERY_RANK.CONFIDENCE_WEIGHT;
+    score += (entry.quality?.authorityScore || 0) * DELIVERY_RANK.AUTHORITY_WEIGHT;
+    score += Math.min(entry.stats?.useCount || 0, DELIVERY_RANK.USE_COUNT_MAX) * DELIVERY_RANK.USE_COUNT_WEIGHT;
+    if (entry.lifecycle === 'active') score += DELIVERY_RANK.ACTIVE_BONUS;
     return score;
   }
 
@@ -267,6 +282,98 @@ export class CursorDeliveryPipeline {
     }
   }
 
+  /**
+   * Channel D — Dev Documents 生成
+   * 将 knowledgeType='dev-document' 的条目以原始 MD 写入
+   * .cursor/skills/autosnippet-devdocs/references/ 目录
+   * @private
+   */
+  _generateChannelD(documents) {
+    const result = { documentsCount: 0, filesWritten: 0, filePaths: [] };
+    if (!documents || documents.length === 0) {
+      return result;
+    }
+
+    const devdocsDir = path.join(this.projectRoot, '.cursor', 'skills', 'autosnippet-devdocs');
+    const refsDir = path.join(devdocsDir, 'references');
+    fs.mkdirSync(refsDir, { recursive: true });
+
+    // 生成 SKILL.md（索引页）
+    const skillLines = [
+      '---',
+      'name: autosnippet-devdocs',
+      `description: "Development documents and knowledge artifacts for ${this.projectName}. Use when looking up architecture decisions, debug reports, design docs, or analysis notes."`,
+      '---',
+      '',
+      `# Dev Documents — ${this.projectName}`,
+      '',
+      'Use this skill when:',
+      '- Looking up architecture decisions or design rationale',
+      '- Reviewing debug reports or performance analysis',
+      '- Finding previous research or investigation notes',
+      '- Understanding project-specific decisions and trade-offs',
+      '',
+      '## Document Index',
+      '',
+      '| Title | Tags | Updated |',
+      '|-------|------|---------|',
+    ];
+
+    for (const doc of documents) {
+      const tags = (doc.tags || []).join(', ') || '-';
+      const updated = doc.updatedAt
+        ? new Date(doc.updatedAt * 1000).toISOString().split('T')[0]
+        : '-';
+      const slug = this._slugify(doc.title || doc.id);
+      skillLines.push(`| [${doc.title}](references/${slug}.md) | ${tags} | ${updated} |`);
+
+      // 写入单个文档 MD
+      const markdown = doc.content?.markdown || doc.description || '';
+      const docContent = [
+        `# ${doc.title || 'Untitled'}`,
+        '',
+        doc.description ? `> ${doc.description}` : '',
+        '',
+        `**Tags:** ${tags}  `,
+        `**Scope:** ${doc.scope || 'universal'}  `,
+        `**Created:** ${doc.createdAt ? new Date(doc.createdAt * 1000).toISOString().split('T')[0] : '-'}`,
+        '',
+        '---',
+        '',
+        markdown,
+      ].filter(Boolean).join('\n');
+
+      const docPath = path.join(refsDir, `${slug}.md`);
+      fs.writeFileSync(docPath, docContent, 'utf8');
+      result.filePaths.push(docPath);
+      result.filesWritten++;
+    }
+
+    skillLines.push('');
+    skillLines.push('## Deeper Knowledge');
+    skillLines.push('');
+    skillLines.push('For full-text search across all documents:');
+    skillLines.push('- `autosnippet_search("your query")`');
+
+    fs.writeFileSync(path.join(devdocsDir, 'SKILL.md'), skillLines.join('\n') + '\n', 'utf8');
+    result.documentsCount = documents.length;
+
+    this.logger.info?.(`[CursorDelivery] Channel D: ${result.documentsCount} documents → ${refsDir}`);
+    return result;
+  }
+
+  /**
+   * 文件名安全 slug 化
+   * @private
+   */
+  _slugify(text) {
+    return text
+      .toLowerCase()
+      .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .substring(0, 80) || 'untitled';
+  }
+
   /**
    * 从项目路径推断项目名称
    * @private