autosnippet 3.2.2 → 3.2.3

package/lib/http/routes/knowledge.js

@@ -9,7 +9,7 @@ import Logger from '../../infrastructure/logging/Logger.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { ValidationError } from '../../shared/errors/index.js';
 import { asyncHandler } from '../middleware/errorHandler.js';
-import { getContext, safeInt } from '../utils/routeHelpers.js';
+import { getContext, safeInt, sanitizeForAPI, sanitizePaginatedForAPI } from '../utils/routeHelpers.js';
 
 const _logger = Logger.getInstance();
 const router = express.Router();
@@ -35,7 +35,7 @@ router.get(
 
     if (keyword) {
       const result = await knowledgeService.search(keyword, { page, pageSize });
-      return res.json({ success: true, data: result });
+      return res.json({ success: true, data: sanitizePaginatedForAPI(result) });
     }
 
     const filters = {};
@@ -65,7 +65,7 @@ router.get(
     }
 
     const result = await knowledgeService.list(filters, { page, pageSize });
-    res.json({ success: true, data: result });
+    res.json({ success: true, data: sanitizePaginatedForAPI(result) });
   })
 );
 
@@ -94,7 +94,7 @@ router.get(
     const container = getServiceContainer();
     const knowledgeService = container.get('knowledgeService');
     const entry = await knowledgeService.get(id);
-    res.json({ success: true, data: entry.toJSON() });
+    res.json({ success: true, data: sanitizeForAPI(entry) });
   })
 );
 
@@ -120,7 +120,7 @@ router.post(
     const entry = await knowledgeService.create(data, context);
     res.status(201).json({
       success: true,
-      data: entry.toJSON(),
+      data: sanitizeForAPI(entry),
     });
   })
 );
@@ -138,7 +138,7 @@ router.patch(
     const context = getContext(req);
 
     const entry = await knowledgeService.update(id, req.body, context);
-    res.json({ success: true, data: entry.toJSON() });
+    res.json({ success: true, data: sanitizeForAPI(entry) });
   })
 );
 
@@ -174,7 +174,7 @@ router.patch(
     const context = getContext(req);
 
     const entry = await knowledgeService.publish(id, context);
-    res.json({ success: true, data: entry.toJSON() });
+    res.json({ success: true, data: sanitizeForAPI(entry) });
   })
 );
 
@@ -197,7 +197,7 @@ router.patch(
     const context = getContext(req);
 
     const entry = await knowledgeService.deprecate(id, reason, context);
-    res.json({ success: true, data: entry.toJSON() });
+    res.json({ success: true, data: sanitizeForAPI(entry) });
   })
 );
 
@@ -214,7 +214,7 @@ router.patch(
     const context = getContext(req);
 
     const entry = await knowledgeService.reactivate(id, context);
-    res.json({ success: true, data: entry.toJSON() });
+    res.json({ success: true, data: sanitizeForAPI(entry) });
   })
 );
 
@@ -245,7 +245,7 @@ router.post(
       ids.map((id) => knowledgeService.publish(id, context))
     );
 
-    const published = results.filter((r) => r.status === 'fulfilled').map((r) => r.value.toJSON());
+    const published = results.filter((r) => r.status === 'fulfilled').map((r) => sanitizeForAPI(r.value));
     const failed = results
       .map((r, i) => (r.status === 'rejected' ? { id: ids[i], error: r.reason?.message } : null))
       .filter(Boolean);

package/lib/http/routes/task.js

@@ -105,6 +105,12 @@ async function _dispatch(svc, operation, params) {
       return _depTree(svc, params);
     case 'stats':
       return _stats(svc);
+    case 'record_decision':
+      return _recordDecision(svc, params);
+    case 'revise_decision':
+      return _reviseDecision(svc, params);
+    case 'unpin_decision':
+      return _unpinDecision(svc, params);
     default:
       return { success: false, message: `Unknown operation: ${operation}` };
   }
@@ -197,7 +203,24 @@ async function _progress(svc, args) {
 
 async function _prime(svc) {
   const result = await svc.prime({ withKnowledge: true });
-  return { success: true, data: result };
+  const decisionCount = (result.decisions || []).length;
+  const staleCount = (result.staleDecisions || []).length;
+  const decisionTitles = (result.decisions || []).map((d) => d.title).join('; ');
+  const statsLine = `${result.inProgress.length} in-progress, ${result.ready.length} ready, ${result.stats.total} total`;
+
+  let message;
+  if (decisionCount > 0) {
+    const stalePart = staleCount > 0 ? ` ${staleCount} stale.` : '';
+    message = `⚠️ ${decisionCount} ACTIVE DECISION(S): [${decisionTitles}].${stalePart} ${statsLine}.`;
+  } else {
+    message = `${statsLine}.`;
+  }
+
+  return {
+    success: true,
+    data: result,
+    message,
+  };
 }
 
 // ── decompose ──
@@ -279,4 +302,61 @@ async function _stats(svc) {
   return { success: true, data: stats };
 }
 
+// ── record_decision ──
+
+async function _recordDecision(svc, args) {
+  if (!args.title) return { success: false, message: 'title is required' };
+  if (!args.description) return { success: false, message: 'description is required' };
+  const { task, isDuplicate } = await svc.recordDecision({
+    title: args.title,
+    description: args.description,
+    rationale: args.rationale || '',
+    tags: args.tags || [],
+    relatedTaskId: args.relatedTaskId || null,
+  });
+  return {
+    success: true,
+    data: task.toJSON(),
+    message: isDuplicate
+      ? `Decision already recorded: ${task.id}`
+      : `Decision pinned: ${task.id} — "${args.title}"`,
+  };
+}
+
+// ── revise_decision ──
+
+async function _reviseDecision(svc, args) {
+  if (!args.id) return { success: false, message: 'id of old decision is required' };
+  if (!args.title) return { success: false, message: 'title of new decision is required' };
+  if (!args.description)
+    return { success: false, message: 'description of new decision is required' };
+  const result = await svc.reviseDecision({
+    oldDecisionId: args.id,
+    title: args.title,
+    description: args.description,
+    rationale: args.rationale || '',
+    reason: args.reason || '',
+  });
+  return {
+    success: true,
+    data: {
+      newDecision: result.newDecision.toJSON(),
+      superseded: result.oldDecisionId,
+    },
+    message: `Decision revised: ${result.oldDecisionId} → ${result.newDecision.id}`,
+  };
+}
+
+// ── unpin_decision ──
+
+async function _unpinDecision(svc, args) {
+  if (!args.id) return { success: false, message: 'id is required' };
+  const task = await svc.unpinDecision(args.id, args.reason || '');
+  return {
+    success: true,
+    data: task.toJSON(),
+    message: `Decision ${args.id} unpinned and closed`,
+  };
+}
+
 export default router;

package/lib/http/utils/routeHelpers.js

@@ -3,6 +3,8 @@
  * 提取自各路由文件中的重复实现
  */
 
+import { KnowledgeEntry } from '../../domain/knowledge/KnowledgeEntry.js';
+
 /**
  * 从请求中提取操作上下文（用户身份、IP、UA）
  * @param {import('express').Request} req
@@ -31,3 +33,31 @@ export function safeInt(value, defaultValue, min = 1, max = 1000) {
   }
   return Math.max(min, Math.min(max, parsed));
 }
+
+/**
+ * 将 KnowledgeEntry（或其 toJSON 输出）转换为对外 API 安全的格式
+ * - 过滤系统内部标签（dimension:* / bootstrap:* 等）
+ *
+ * @param {KnowledgeEntry|Object} entryOrJson  实体或 toJSON 输出
+ * @returns {Object} 过滤后的 JSON
+ */
+export function sanitizeForAPI(entryOrJson) {
+  const json = typeof entryOrJson?.toJSON === 'function' ? entryOrJson.toJSON() : { ...entryOrJson };
+  if (Array.isArray(json.tags)) {
+    json.tags = json.tags.filter((t) => !KnowledgeEntry.isSystemTag(t));
+  }
+  return json;
+}
+
+/**
+ * 将分页结果中的 data 数组批量过滤系统标签
+ * @param {{ data: Array, pagination: Object }} result
+ * @returns {{ data: Array, pagination: Object }}
+ */
+export function sanitizePaginatedForAPI(result) {
+  if (!result?.data) return result;
+  return {
+    ...result,
+    data: result.data.map(sanitizeForAPI),
+  };
+}

package/lib/repository/task/TaskRepository.impl.js

@@ -108,7 +108,8 @@ export class TaskRepositoryImpl {
         SUM(CASE WHEN status = 'open'        THEN 1 ELSE 0 END) as open,
         SUM(CASE WHEN status = 'in_progress' THEN 1 ELSE 0 END) as in_progress,
         SUM(CASE WHEN status = 'closed'      THEN 1 ELSE 0 END) as closed,
-        SUM(CASE WHEN status = 'deferred'    THEN 1 ELSE 0 END) as deferred
+        SUM(CASE WHEN status = 'deferred'    THEN 1 ELSE 0 END) as deferred,
+        SUM(CASE WHEN status = 'pinned'      THEN 1 ELSE 0 END) as pinned
       FROM tasks
     `);
   }
@@ -318,6 +319,7 @@ export class TaskRepositoryImpl {
       in_progress: row.in_progress || 0,
       closed: row.closed || 0,
       deferred: row.deferred || 0,
+      pinned: row.pinned || 0,
     };
   }
 

package/lib/service/cursor/AgentInstructionsGenerator.js

@@ -55,7 +55,9 @@ const MCP_TOOLS_SUMMARY = [
   { name: 'autosnippet_skill', desc: 'Skill management (list/load/create/update/delete/suggest)' },
   { name: 'autosnippet_save_document', desc: 'Save development document (auto-publish)' },
   { name: 'autosnippet_bootstrap', desc: 'Project cold-start & scan (knowledge/refine/scan)' },
-  { name: 'autosnippet_task', desc: 'TaskGraph lifecycle (prime/claim/close/ready/create/fail/defer)' },
+  { name: 'autosnippet_ready', desc: 'Session entry point — loads decisions + ready tasks (call FIRST)' },
+  { name: 'autosnippet_decide', desc: 'Decision management (record/revise/unpin/list)' },
+  { name: 'autosnippet_task', desc: 'Task CRUD (create/claim/close/fail/defer/progress/decompose)' },
   { name: 'autosnippet_health', desc: 'Service health & KB statistics' },
   { name: 'autosnippet_capabilities', desc: 'List all available MCP tools (self-discovery)' },
 ];
@@ -279,7 +281,7 @@ export class AgentInstructionsGenerator {
     // Key tools highlight for Claude
     lines.push('### Recommended Workflow', '');
     lines.push(
-      '1. **Session start**: `autosnippet_task({ operation: "prime" })` — Restore task context'
+      '1. **Session start**: `autosnippet_ready()` — Restore task context and decisions'
     );
     lines.push(
       '2. **Before writing code**: `autosnippet_search({ query: "<topic>" })` to find relevant patterns'
@@ -405,7 +407,7 @@ export class AgentInstructionsGenerator {
       '## Recommended Workflow',
       '',
       '### Session Start (ALWAYS)',
-      '1. `autosnippet_task({ operation: "prime" })` — Restore task context',
+      '1. `autosnippet_ready()` — Restore task context and decisions',
       '',
       '### Task Lifecycle',
       '2. `autosnippet_task({ operation: "claim", id: "asd-xxx" })` — Start working',
@@ -423,7 +425,7 @@ export class AgentInstructionsGenerator {
       '',
       '### Context Pressure',
       '- `_contextHint: CONTEXT_PRESSURE:WARNING` → Summarize completed work, then continue',
-      '- `_contextHint: CONTEXT_PRESSURE:CRITICAL` → Call `autosnippet_task({ operation: "prime" })` immediately',
+      '- `_contextHint: CONTEXT_PRESSURE:CRITICAL` → Call `autosnippet_ready()` immediately',
       '',
     ];
   }

package/lib/service/knowledge/KnowledgeService.js

@@ -225,11 +225,22 @@ export class KnowledgeService {
           case 'relations':
           case 'constraints':
           case 'reasoning':
-          case 'tags':
           case 'headers':
           case 'headerPaths':
             dbUpdates[key] = data[key];
             break;
+
+          // tags 需要特殊处理：API 返回时已过滤系统标签，保存时需要合并回来
+          case 'tags': {
+            const existingSystemTags = (_entry.tags || []).filter((t) =>
+              KnowledgeEntry.isSystemTag(t)
+            );
+            const incomingUserTags = (data.tags || []).filter(
+              (t) => !KnowledgeEntry.isSystemTag(t)
+            );
+            dbUpdates.tags = [...incomingUserTags, ...existingSystemTags];
+            break;
+          }
         }
       }
 

package/lib/service/task/TaskGraphService.js

@@ -1,5 +1,5 @@
 import { Task } from '../../domain/task/Task.js';
-import { DepType, affectsReadyWork, isValidDepType } from '../../domain/task/TaskDependency.js';
+import { affectsReadyWork, DepType, isValidDepType } from '../../domain/task/TaskDependency.js';
 import Logger from '../../infrastructure/logging/Logger.js';
 
 /**
@@ -88,6 +88,13 @@ export class TaskGraphService {
   async decompose(epicId, subtasks) {
     const epic = this.repo.findById(epicId);
     if (!epic) throw new Error(`Epic not found: ${epicId}`);
+    // 决策不可拆解（C6）
+    if (epic.taskType === 'decision') {
+      throw new Error('Cannot decompose a decision. Decisions are atomic records.');
+    }
+    if (epic.status === 'pinned') {
+      throw new Error('Cannot decompose a pinned task.');
+    }
 
     const results = this.repo.inTransaction(() => {
       const created = [];
@@ -359,16 +366,249 @@ export class TaskGraphService {
       withKnowledge: options.withKnowledge !== false,
     });
     const statistics = await this.stats();
-
-    return {
+    // 按创建时间降序，确保超出 limit 时保留最新决策（C5）
+    // 双重过滤 status+taskType，避免 pinned 语义过载（D1）
+    const pinnedDecisions = this.repo.findAll(
+      { status: 'pinned', taskType: 'decision' },
+      { limit: 50, orderBy: 'created_at DESC' }
+    );
+
+    const result = {
       inProgress: inProgress.map((t) => t.toJSON()),
       ready: readyTasks.map((t) => (t.toJSON ? t.toJSON() : t)),
       stats: statistics,
     };
+
+    if (pinnedDecisions.length > 0) {
+      // P2: Stale detection — 超过阈值的决策标记为 stale
+      const staleThresholdSec = this._getDecisionStaleThreshold();
+      const nowSec = Math.floor(Date.now() / 1000);
+      const activeDecisions = [];
+      const staleDecisions = [];
+
+      for (const t of pinnedDecisions) {
+        const isStale =
+          t.metadata?.staleSince ||
+          (staleThresholdSec > 0 && t.createdAt && nowSec - t.createdAt > staleThresholdSec);
+        if (isStale) {
+          staleDecisions.push(t);
+        } else {
+          activeDecisions.push(t);
+        }
+      }
+
+      // P1 Result Compaction: compact 模式 — description 截断到 120 chars
+      // Agent 需要完整内容时调用 autosnippet_decide({ operation: 'list' })
+      result.decisions = activeDecisions.map((t) => ({
+        id: t.id,
+        title: t.title,
+        summary:
+          typeof t.description === 'string'
+            ? t.description
+                .replace(/^## Decision\n/, '')
+                .split(/\n\n## /)[0]
+                .slice(0, 120)
+            : '',
+        createdAt: t.createdAt,
+      }));
+
+      // P2: stale decisions 单独返回（轻量格式，仅供提示）
+      if (staleDecisions.length > 0) {
+        result.staleDecisions = staleDecisions.map((t) => ({
+          id: t.id,
+          title: t.title,
+          createdAt: t.createdAt,
+          ageDays: Math.floor((nowSec - (t.createdAt || nowSec)) / 86400),
+        }));
+      }
+
+      result._decisionHint =
+        'These are team-agreed decisions (compact view). Respect them in your response. ' +
+        'Call autosnippet_decide({ operation: "list" }) for full details. ' +
+        "If the user's request conflicts with a decision, point out the conflict and ask whether to revise_decision.";
+
+      if (staleDecisions.length > 0) {
+        result._staleHint =
+          `${staleDecisions.length} decision(s) are stale (>${Math.floor(staleThresholdSec / 86400)} days). ` +
+          'Consider reviewing with autosnippet_decide({ operation: "list" }) and unpin outdated ones.';
+      }
+    }
+
+    // ── 完整协议指令（从 copilot-instructions.md 移到 prime 返回值）──
+    result._protocol = [
+      'Respect decisions above. Record new decisions when user agrees/disagrees on something.',
+      'Use create/close to track multi-step work.',
+    ].join('\n');
+
+    return result;
+  }
+
+  // ═══ 决策管理 ═══════════════════════════════════════
+
+  /**
+   * 记录决策 — 直接以 pinned 状态创建，避免 open→pinned 的幽灵窗口（C1）
+   * @param {object} params — { title, description, rationale, tags, relatedTaskId }
+   * @returns {{ task: Task, isDuplicate: boolean }}
+   */
+  async recordDecision({ title, description, rationale, tags, relatedTaskId }) {
+    if (!title) throw new Error('Decision title is required');
+    if (!description) throw new Error('Decision description is required');
+
+    let formattedDesc = `## Decision\n${description}`;
+    if (rationale) {
+      formattedDesc += `\n\n## Rationale\n${rationale}`;
+    }
+
+    // 直接以 pinned 状态构建 Task，避免 open→pinned 的幽灵窗口
+    const task = new Task({
+      title,
+      description: formattedDesc,
+      taskType: 'decision',
+      status: 'pinned',
+      priority: 0,
+      // C8: 传递普通对象，_entityToRow() 负责 JSON.stringify
+      metadata: {
+        tags: tags || [],
+        source: 'agent-user-agreement',
+        rationale: rationale || '',
+        recordedAt: new Date().toISOString(),
+      },
+    });
+    task.computeContentHash();
+    task.validate();
+
+    // 去重检测（复用 create 的逻辑）
+    const duplicate = this.repo.findByContentHash(task.contentHash);
+    if (duplicate) {
+      return { task: duplicate, isDuplicate: true };
+    }
+
+    task.id = this.idGen.generate();
+
+    // 单事务：创建 + 关联依赖
+    const saved = this.repo.inTransaction(() => {
+      const created = this.repo.create(task);
+      if (relatedTaskId) {
+        try {
+          this.repo.addDependency(created.id, relatedTaskId, 'related');
+        } catch (err) {
+          this.logger.debug('recordDecision: dependency add failed', { error: err.message });
+        }
+      }
+      return created;
+    });
+
+    this._logEvent(saved.id, 'decision_recorded', null, title);
+    return { task: saved, isDuplicate: false };
+  }
+
+  /**
+   * 修订决策 — 原子事务：创建新决策 + 关闭旧决策 + 建立 supersedes 链（C2+C7）
+   * @param {object} params — { oldDecisionId, title, description, rationale, reason }
+   * @returns {{ newDecision: Task, oldDecisionId: string }}
+   */
+  async reviseDecision({ oldDecisionId, title, description, rationale, reason }) {
+    // 事务前验证
+    const oldDecision = this.repo.findById(oldDecisionId);
+    if (!oldDecision) throw new Error(`Decision not found: ${oldDecisionId}`);
+    if (oldDecision.status !== 'pinned') {
+      throw new Error(`Can only revise pinned decisions (current: ${oldDecision.status})`);
+    }
+
+    let formattedDesc = `## Decision\n${description}`;
+    if (rationale) {
+      formattedDesc += `\n\n## Rationale\n${rationale}`;
+    }
+
+    // 构建新决策 Task
+    const newTask = new Task({
+      title,
+      description: formattedDesc,
+      taskType: 'decision',
+      status: 'pinned',
+      priority: 0,
+      metadata: {
+        tags: [],
+        source: 'agent-user-agreement',
+        rationale: rationale || '',
+        recordedAt: new Date().toISOString(),
+        supersedes: oldDecisionId,
+      },
+    });
+    newTask.computeContentHash();
+    newTask.validate();
+    newTask.id = this.idGen.generate();
+
+    // 原子事务：创建新决策 + 关闭旧决策 + 建立 supersedes 链
+    const newDecision = this.repo.inTransaction(() => {
+      const created = this.repo.create(newTask);
+
+      this.repo.update(oldDecisionId, {
+        status: 'closed',
+        closeReason: `Superseded by ${created.id}: ${reason || 'Revised'}`,
+        closedAt: Math.floor(Date.now() / 1000),
+        updatedAt: Math.floor(Date.now() / 1000),
+      });
+
+      this.repo.addDependency(created.id, oldDecisionId, 'supersedes');
+      return created;
+    });
+
+    this._logEvent(oldDecisionId, 'superseded', 'pinned', `by ${newDecision.id}`);
+    this._logEvent(newDecision.id, 'supersedes', null, oldDecisionId);
+
+    return { newDecision, oldDecisionId };
+  }
+
+  /**
+   * 取消固定决策
+   * @param {string} id
+   * @param {string} [reason='']
+   * @returns {Task}
+   */
+  async unpinDecision(id, reason = '') {
+    const task = this.repo.findById(id);
+    if (!task) throw new Error(`Decision not found: ${id}`);
+    if (task.status !== 'pinned') {
+      throw new Error(`Can only unpin pinned decisions (current: ${task.status})`);
+    }
+
+    const saved = this.repo.update(id, {
+      status: 'closed',
+      closeReason: reason || 'Unpinned',
+      closedAt: Math.floor(Date.now() / 1000),
+      updatedAt: Math.floor(Date.now() / 1000),
+    });
+
+    this._logEvent(id, 'unpinned', 'pinned', reason);
+    return saved;
   }
 
   // ═══ 私有方法 ═══════════════════════════════════════
 
+  /**
+   * P2: 获取决策过期阈值（秒）
+   * 默认 30 天 = 2592000 秒。可通过容器内 'config' 服务配置。
+   * 返回 0 表示禁用过期检测。
+   * @private
+   */
+  _getDecisionStaleThreshold() {
+    try {
+      const config = this.repo?.db
+        ? null // 通过构造函数传入的 config 优先
+        : null;
+      // 暂无 config 注入路径，使用环境变量或硬编码默认值
+      const envDays = process.env.ASD_DECISION_STALE_DAYS;
+      if (envDays !== undefined) {
+        const days = Number.parseInt(envDays, 10);
+        if (Number.isFinite(days) && days >= 0) return days * 86400;
+      }
+      return 30 * 86400; // 默认 30 天
+    } catch {
+      return 30 * 86400;
+    }
+  }
+
   /**
    * 查找因 closedTaskId 完成而新解除阻塞的任务
    * @private

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosnippet",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "description": "Extract code patterns into a knowledge base for AI coding assistants",
   "type": "module",
   "main": "lib/bootstrap.js",

package/skills/autosnippet-intent/SKILL.md

@@ -46,7 +46,9 @@ Use this skill when the user's intent is unclear or overlaps multiple capabiliti
 - Guard: `autosnippet_guard` (code 单文件 / files[] 批量)
 - Bootstrap: `autosnippet_bootstrap` (no params — Mission Briefing) + `autosnippet_dimension_complete`
 - Wiki: `autosnippet_wiki_plan` (topic planning) + `autosnippet_wiki_finalize` (meta.json + dedup)
-- Task: `autosnippet_task` (operation: create / ready / claim / close / fail / defer / progress / prime / stats / decompose)
+- Ready: `autosnippet_ready` (session entry — loads decisions + tasks)
+- Decide: `autosnippet_decide` (operation: record / revise / unpin / list)
+- Task: `autosnippet_task` (operation: create / ready / claim / close / fail / defer / progress / stats / decompose)
 - Skills: `autosnippet_skill` (operation: list / load / create / update / delete / suggest)
 - Admin: `autosnippet_enrich_candidates`, `autosnippet_knowledge_lifecycle`, `autosnippet_validate_candidate`, `autosnippet_check_duplicate`
 

package/skills/autosnippet-recipes/SKILL.md

@@ -118,7 +118,9 @@ Recipe is the core knowledge unit. V3 uses a unified structured model:
 
 | Tool | Description |
 |------|-------------|
-| `autosnippet_task` | TaskGraph lifecycle (`operation`: create/ready/claim/close/fail/defer/progress/prime/stats/decompose) |
+| `autosnippet_ready` | Session entry point — loads decisions + ready tasks (call FIRST) |
+| `autosnippet_decide` | Decision management (`operation`: record/revise/unpin/list) |
+| `autosnippet_task` | Task CRUD (`operation`: create/ready/claim/close/fail/defer/progress/stats/decompose) |
 
 ### Skills Management