autosnippet 3.1.15 → 3.2.2

package/lib/service/task/TaskKnowledgeBridge.js

@@ -0,0 +1,86 @@
+import Logger from '../../infrastructure/logging/Logger.js';
+
+/**
+ * TaskKnowledgeBridge — 任务 ↔ 知识桥接服务
+ *
+ * AutoSnippet 独有能力：返回「带知识上下文的任务」，而非裸任务。
+ *
+ * 桥接策略：
+ *   1. 任务标题/描述 → 搜索知识库 → 关联 pattern/rule/fact
+ *   2. 关联的 Guard 规则 → 嵌入任务上下文
+ */
+export class TaskKnowledgeBridge {
+  /**
+   * @param {import('../../service/search/SearchEngine.js').SearchEngine} searchEngine
+   */
+  constructor(searchEngine) {
+    this._search = searchEngine;
+    this.logger = Logger.getInstance();
+  }
+
+  /**
+   * 为就绪任务附加知识上下文
+   * 并行搜索，不阻塞主流程
+   *
+   * @param {import('../../domain/task/Task.js').Task[]} tasks
+   * @returns {Promise<import('../../domain/task/Task.js').Task[]>}
+   */
+  async enrichWithKnowledge(tasks) {
+    if (!tasks || tasks.length === 0) return tasks;
+    if (!this._search) return tasks;
+
+    const results = await Promise.allSettled(tasks.map((task) => this._buildContext(task)));
+
+    return tasks.map((task, i) => {
+      if (results[i].status === 'fulfilled' && results[i].value) {
+        task.knowledgeContext = results[i].value;
+      }
+      return task;
+    });
+  }
+
+  /**
+   * 为单个任务构建知识上下文
+   * @private
+   */
+  async _buildContext(task) {
+    const query = `${task.title} ${task.description}`.trim();
+    if (!query) return null;
+
+    try {
+      const searchResult = await this._search.search(query, {
+        mode: 'auto',
+        limit: 5,
+      });
+
+      const allResults = searchResult?.items || searchResult?.results || [];
+      const knowledge = allResults.filter((r) => r.kind !== 'rule').slice(0, 3);
+      const guardRules = allResults.filter((r) => r.kind === 'rule').slice(0, 5);
+
+      return {
+        relatedKnowledge: knowledge.map((k) => ({
+          id: k.id,
+          title: k.title,
+          kind: k.kind,
+          trigger: k.trigger,
+          actionHint: k.actionHint || k.doClause || '',
+        })),
+        guardRules: guardRules.map((r) => ({
+          id: r.id,
+          title: r.title,
+          trigger: r.trigger,
+          actionHint: r.actionHint || r.doClause || '',
+        })),
+        searchQuery: query,
+      };
+    } catch (err) {
+      this.logger.debug('TaskKnowledgeBridge._buildContext error', {
+        taskId: task.id,
+        error: err.message,
+      });
+      return null;
+    }
+  }
+}
+
+export default TaskKnowledgeBridge;

package/lib/service/task/TaskReadyEngine.js

@@ -0,0 +1,127 @@
+import { Task } from '../../domain/task/Task.js';
+
+/**
+ * TaskReadyEngine — 就绪检测引擎
+ *
+ * 核心能力：通过递归 CTE 计算传递性阻塞，返回所有无阻塞依赖的就绪任务。
+ *
+ * 排序策略 (默认 hybrid):
+ *   priority ASC → 高优先级优先
+ *   created_at ASC → 同优先级先创建优先（防止 starvation）
+ */
+export class TaskReadyEngine {
+  /**
+   * @param {import('better-sqlite3').Database} db — raw SQLite handle
+   */
+  constructor(db) {
+    this._db = db;
+    this._prepareStatements();
+  }
+
+  /** @private */
+  _prepareStatements() {
+    // ── 核心: 递归 CTE 计算传递性阻塞 ──
+    this._readyStmt = this._db.prepare(`
+      WITH RECURSIVE blocked_tasks(id, depth) AS (
+        -- Base case: 直接被阻塞的任务
+        SELECT td.task_id, 1
+        FROM task_dependencies td
+        JOIN tasks blocker ON td.depends_on_id = blocker.id
+        WHERE td.dep_type IN ('blocks', 'waits-for')
+          AND blocker.status != 'closed'
+
+        UNION
+
+        -- Recursive case: 传递性阻塞（深度保护 ≤ 50 层）
+        SELECT td.task_id, bt.depth + 1
+        FROM task_dependencies td
+        JOIN blocked_tasks bt ON td.depends_on_id = bt.id
+        WHERE td.dep_type IN ('blocks', 'waits-for')
+          AND bt.depth < 50
+      )
+      SELECT t.*
+      FROM tasks t
+      WHERE t.status = 'open'
+        AND t.id NOT IN (SELECT id FROM blocked_tasks)
+      ORDER BY t.priority ASC, t.created_at ASC
+      LIMIT ?
+    `);
+
+    // ── 查询被阻塞的任务 ──
+    this._blockedStmt = this._db.prepare(`
+      SELECT t.*, GROUP_CONCAT(td.depends_on_id) as blocked_by
+      FROM tasks t
+      JOIN task_dependencies td ON t.id = td.task_id
+      JOIN tasks blocker ON td.depends_on_id = blocker.id
+      WHERE t.status IN ('open', 'in_progress')
+        AND td.dep_type IN ('blocks', 'waits-for')
+        AND blocker.status != 'closed'
+      GROUP BY t.id
+      ORDER BY t.priority ASC
+    `);
+
+    // ── 依赖树查询 ──
+    this._depTreeStmt = this._db.prepare(`
+      WITH RECURSIVE dep_tree(id, depth, path) AS (
+        SELECT depends_on_id, 1, depends_on_id
+        FROM task_dependencies
+        WHERE task_id = ?
+          AND dep_type IN ('blocks', 'waits-for')
+
+        UNION ALL
+
+        SELECT td.depends_on_id, dt.depth + 1, dt.path || '>' || td.depends_on_id
+        FROM task_dependencies td
+        JOIN dep_tree dt ON td.task_id = dt.id
+        WHERE td.dep_type IN ('blocks', 'waits-for')
+          AND dt.depth < 10
+      )
+      SELECT t.*, dt.depth
+      FROM dep_tree dt
+      JOIN tasks t ON t.id = dt.id
+      ORDER BY dt.depth ASC
+    `);
+  }
+
+  /**
+   * 获取就绪任务（核心方法）
+   *
+   * 就绪 = status='open' 且无未完成的阻塞型依赖（传递性检测）
+   *
+   * @param {object} [options]
+   * @param {number} [options.limit=10]
+   * @returns {Task[]}
+   */
+  getReadyWork(options = {}) {
+    const limit = Math.max(1, Math.min(options.limit || 10, 200));
+    const rows = this._readyStmt.all(limit);
+    return rows.map((r) => Task.fromRow(r));
+  }
+
+  /**
+   * 获取被阻塞的任务列表
+   * @returns {Array<Object>} 带 blocked_by 字段的任务列表
+   */
+  getBlockedWork() {
+    const rows = this._blockedStmt.all();
+    return rows.map((r) => ({
+      ...Task.fromRow(r).toJSON(),
+      blockedBy: r.blocked_by ? r.blocked_by.split(',') : [],
+    }));
+  }
+
+  /**
+   * 获取依赖树
+   * @param {string} taskId
+   * @returns {Array<Object>} 带 depth 的任务列表
+   */
+  getDependencyTree(taskId) {
+    const rows = this._depTreeStmt.all(taskId);
+    return rows.map((r) => ({
+      ...Task.fromRow(r).toJSON(),
+      depth: r.depth,
+    }));
+  }
+}
+
+export default TaskReadyEngine;

package/lib/shared/constants.js

@@ -10,11 +10,11 @@
 
 /** QualityScorer 维度权重 */
 export const QUALITY_WEIGHTS = Object.freeze({
-  completeness: 0.35,
+  completeness: 0.30,
   format: 0.25,
   codeQuality: 0.25,
-  metadata: 0.15,
-  engagement: 0.0,
+  metadata: 0.10,
+  engagement: 0.10,
 });
 
 /** QualityScorer 等级分界线 */

package/package.json

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

package/skills/autosnippet-intent/SKILL.md

@@ -34,7 +34,7 @@ Use this skill when the user's intent is unclear or overlaps multiple capabiliti
 - `autosnippet-batch-scan` / `autosnippet-recipe-candidates` → merged into autosnippet-candidates
 - `autosnippet-dep-graph` → merged into autosnippet-structure
 
-## MCP tools (reference only — 12 个整合工具)
+## MCP tools (reference only — 20 个整合工具)
 
 - System: `autosnippet_health`, `autosnippet_capabilities`
 - Search: `autosnippet_search` (mode: auto / context / keyword / semantic)
@@ -45,7 +45,10 @@ Use this skill when the user's intent is unclear or overlaps multiple capabiliti
 - Document: `autosnippet_save_document`
 - 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)
 - Skills: `autosnippet_skill` (operation: list / load / create / update / delete / suggest)
+- Admin: `autosnippet_enrich_candidates`, `autosnippet_knowledge_lifecycle`, `autosnippet_validate_candidate`, `autosnippet_check_duplicate`
 
 This skill is a router only; it does not perform actions itself.
 

package/skills/autosnippet-recipes/SKILL.md

@@ -78,7 +78,7 @@ Recipe is the core knowledge unit. V3 uses a unified structured model:
 
 ---
 
-## MCP Tools Reference (12 个整合工具)
+## MCP Tools Reference (20 个整合工具)
 
 ### Query (Agent can freely use)
 
@@ -89,6 +89,7 @@ Recipe is the core knowledge unit. V3 uses a unified structured model:
 | `autosnippet_knowledge` | Knowledge browse (`operation`: list/get/insights/confirm_usage) |
 | `autosnippet_graph` | Knowledge graph (`operation`: query/impact/path/stats) |
 | `autosnippet_structure` | Project structure (`operation`: targets/files/metadata) |
+| `autosnippet_capabilities` | Service capability discovery |
 
 ### Candidate Submit (Agent core capability)
 
@@ -103,7 +104,21 @@ Recipe is the core knowledge unit. V3 uses a unified structured model:
 | Tool | Description |
 |------|-------------|
 | `autosnippet_guard` | Code Guard check (`code` single / `files[]` batch — auto-routed) |
-| `autosnippet_bootstrap` | Cold-start + scan (`operation`: knowledge/refine/scan) |
+| `autosnippet_bootstrap` | Cold-start Mission Briefing (no params — returns project analysis + dimension tasks) |
+| `autosnippet_dimension_complete` | Dimension analysis completion (dimensionId + analysisText required) |
+
+### Wiki
+
+| Tool | Description |
+|------|-------------|
+| `autosnippet_wiki_plan` | Plan Wiki doc generation (scan project → topic data packages) |
+| `autosnippet_wiki_finalize` | Finalize Wiki (meta.json + dedup + validation) |
+
+### Task Management
+
+| Tool | Description |
+|------|-------------|
+| `autosnippet_task` | TaskGraph lifecycle (`operation`: create/ready/claim/close/fail/defer/progress/prime/stats/decompose) |
 
 ### Skills Management
 

package/templates/claude-hooks.yaml

@@ -0,0 +1,19 @@
+# AutoSnippet Claude Code Hooks
+# Auto-generated by AutoSnippet. Do not edit manually.
+#
+# 用法：将此文件放到项目 .claude/ 目录下
+# Claude Code 在会话开始时会自动执行 SessionStart hook
+#
+# SessionStart hook 自动调用 prime，恢复任务上下文
+# 无需手动调用 autosnippet_task(operation: "prime")
+
+hooks:
+  SessionStart:
+    # 会话开始时自动 prime TaskGraph 上下文
+    - command: |
+        curl -s -X POST http://localhost:3000/api/v1/task \
+          -H "Content-Type: application/json" \
+          -d '{"operation": "prime"}' \
+          2>/dev/null || echo '{"success": false, "message": "AutoSnippet server not running"}'
+      description: "AutoSnippet TaskGraph auto-prime"
+      timeout: 5000

package/templates/copilot-instructions.md

@@ -1,5 +1,7 @@
 # AutoSnippet Copilot Instructions
 
+> Auto-generated by AutoSnippet. Do not edit manually — regenerated on `asd setup` / `asd bootstrap`.
+
 ## 项目概览
 - 项目名称：AutoSnippet
 - 版本：V3（ESM, SQLite, MCP 11 工具 — 整合版）
@@ -29,7 +31,7 @@
 5. MCP 调用失败时，**不要在同一轮重复重试**，回退到已读文档或静态上下文。
 6. Skills 负责语义与流程，MCP 负责能力与调用；不要在 Skill 内硬编码 URL/HTTP。
 
-## MCP 工具速查（12 个整合工具）
+## MCP 工具速查（20 个整合工具）
 
 ### 检索
 - `autosnippet_search` — 统合搜索入口（通过 `mode` 参数切换）
@@ -68,10 +70,23 @@
 - `autosnippet_bootstrap` — 冷启动 Mission Briefing（无参数，返回项目分析 + 维度任务清单）
 - `autosnippet_dimension_complete` — 维度分析完成通知（dimensionId + analysisText 必填）
 
+### Wiki 文档
+- `autosnippet_wiki_plan` — Wiki 文档规划（扫描项目生成主题数据包）
+- `autosnippet_wiki_finalize` — Wiki 完成（meta.json + 去重 + 验证）
+
+### 任务管理
+- `autosnippet_task` — TaskGraph 任务图管理（`operation`: create / ready / claim / close / fail / defer / progress / prime / stats / decompose / dep_add / dep_tree 等）
+
 ### 系统
 - `autosnippet_health` — 服务健康状态与知识库统计（可检测空 KB 触发冷启动）
 - `autosnippet_capabilities` — 服务能力清单（列出所有可用 MCP 工具，供 Agent 自发现）
 
+### 管理员工具（Admin Tier）
+- `autosnippet_enrich_candidates` — 候选字段完整性诊断（不使用 AI）
+- `autosnippet_knowledge_lifecycle` — 知识条目生命周期操作（publish/deprecate/reactivate 等）
+- `autosnippet_validate_candidate` — 候选结构化预校验（调试用）
+- `autosnippet_check_duplicate` — 相似度检测（调试用）
+
 ## Recipe 结构要点
 - 必须包含：Frontmatter（`title`、`trigger` 必填）+ `## Snippet / Code Reference` + `## AI Context / Usage Guide`。
 - Frontmatter 必填字段（7）：`title`、`trigger`（@开头）、`category`（8 选 1）、`language`、`summary_cn`、`summary_en`、`headers`。
@@ -94,6 +109,23 @@ autosnippet_skill({ operation: "load", name: "autosnippet-coldstart" })
 Skill 包含：完整的 V3 字段格式、JSON 示例模板、维度分析策略。
 **不加载 Skill 直接提交知识会因字段格式问题被反复拒绝。**
 
+## Guard 诊断响应
+
+当编辑器出现来自 "AutoSnippet Guard" 的诊断（黄色/红色波浪线）时：
+1. 读取诊断消息中的 `ruleId`
+2. 调用 `autosnippet_search(query: ruleId)` 查找对应 Recipe
+3. 按 Recipe 的 `doClause` + `coreCode` 修复代码
+4. 保存文件并确认诊断消失
+
+灯泡菜单中可快捷搜索知识库或禁用该行检查。
+
+## 上下文压力应对
+
+- 如果任何工具返回 `_contextHint` 包含 `CONTEXT_PRESSURE:WARNING`：
+  → 简要总结已完成工作，然后继续。
+- 如果任何工具返回 `_contextHint` 包含 `CONTEXT_PRESSURE:CRITICAL`：
+  → 立即调用 `autosnippet_task(operation: "prime")` 恢复会话上下文。
+
 ### V3 字段格式关键提醒
 - `content` **必须是 JSON 对象**（不是字符串）：`{ "pattern": "代码...", "markdown": "## 标题\n正文...", "rationale": "设计原理" }`
 - `reasoning` **必须是 JSON 对象**：`{ "whyStandard": "原因", "sources": ["file.ts"], "confidence": 0.85 }`

package/templates/cursor-rules/autosnippet-conventions.mdc

@@ -98,3 +98,15 @@ Recipes are classified into three kinds:
 ## Recipe over code
 
 When both a Recipe and the codebase have relevant implementations, prefer the Recipe. Recipes are the project's agreed standard; source code may be legacy or non-standard.
+
+## Guard 诊断响应
+
+当编辑器出现 "AutoSnippet Guard" 诊断时：
+1. 读取 ruleId → `autosnippet_search(query: ruleId)`
+2. 按 Recipe 的 doClause + coreCode 修改代码
+3. 保存并确认诊断消失
+
+## 上下文压力应对
+
+- `_contextHint` 包含 `CONTEXT_PRESSURE:WARNING` → 总结已完成工作，继续。
+- `_contextHint` 包含 `CONTEXT_PRESSURE:CRITICAL` → 立即 prime 恢复上下文。

package/templates/cursor-rules/autosnippet-workflow.mdc

@@ -0,0 +1,43 @@
+---
+description: AutoSnippet TaskGraph & Guard 工作流 — 任务管理 + 诊断闭环
+alwaysApply: true
+---
+
+# AutoSnippet TaskGraph Workflow
+
+## 任务管理
+
+1. 新会话开始 → `autosnippet_task(operation: "prime")`
+2. 编码前 → `claim`，完成后 → `close`
+3. 遇到错误 → `fail`（不要跳过）
+4. 发现新工作 → `create` + `dep_add(depType: "discovered-from")`
+5. MCP 调用失败 → 不要在同一轮重复重试
+
+## Guard 诊断响应
+
+当编辑器出现 "AutoSnippet Guard" 诊断时：
+1. 读取 ruleId → `autosnippet_search(query: ruleId)`
+2. 按 Recipe 的 doClause + coreCode 修改代码
+3. 保存并确认诊断消失
+
+## 知识搜索
+
+编码前搜索相关知识：`autosnippet_search(query: "相关关键词")`
+
+## 上下文压力
+
+- `_contextHint` 包含 `CONTEXT_PRESSURE:WARNING` → 总结已完成工作，继续
+- `_contextHint` 包含 `CONTEXT_PRESSURE:CRITICAL` → 立即 prime 恢复上下文
+
+## 任务操作速查
+
+| 操作 | 用途 |
+|------|------|
+| `prime` | 恢复会话上下文（新会话必做） |
+| `claim(id)` | 开始处理任务 |
+| `close(id)` | 完成任务 → 返回 newlyReady |
+| `fail(id, reason)` | 标记失败 |
+| `defer(id, reason)` | 延后处理 |
+| `progress(id, desc)` | 更新进度 |
+| `create(title)` | 创建新任务 |
+| `ready` | 获取就绪任务（带知识上下文） |

package/templates/guard-ci.yml

@@ -1,4 +1,5 @@
 # AutoSnippet Guard CI/CD Check
+# Auto-generated by AutoSnippet. Do not edit manually.
 # 在 push 和 PR 时自动运行 Guard 合规检查
 #
 # 使用方法：将此文件复制到项目的 .github/workflows/ 目录

package/templates/pre-commit-guard.sh

@@ -1,6 +1,7 @@
 #!/bin/sh
 # AutoSnippet Guard pre-commit hook
-# 
+# Auto-generated by AutoSnippet. Do not edit manually.
+#
 # 安装方法：
 #   cp templates/pre-commit-guard.sh .git/hooks/pre-commit
 #   chmod +x .git/hooks/pre-commit