mcp-probe-kit 3.2.0 → 3.3.0

package/README.md

@@ -67,6 +67,16 @@ A powerful MCP (Model Context Protocol) server providing **27 tools** covering t
 - **🧠 Memory** (4 tools) - Reusable asset memory
   - `search_memory`, `read_memory_asset`, `memorize_asset`, `scan_and_extract_patterns`
 
+### 🛡️ Quality Constraints (single source of truth)
+
+All hard quality rules live in one module (`src/lib/quality-constraints.ts`) and are injected into `code_review`, the `add_feature` task templates, and the UI tools. Change once, apply everywhere — inspired by [taste-skill](https://github.com/Leonxlnx/taste-skill) and [impeccable](https://github.com/pbakaus/impeccable).
+
+- **Code limits**: single file ≤ 500 lines (split into modules/components when exceeded), function ≤ 50 lines, nesting ≤ 4, parameters ≤ 3.
+- **Completeness blacklist**: `code_review` flags placeholder/elision patterns (`// ...`, `// TODO`, `// rest of code`, bare `...`) as CRITICAL — "a partial output is a broken output".
+- **Anti-laziness task templates**: `add_feature` tasks now carry a Scope-lock deliverable count, a mandatory evidence block (read code before writing), a per-file line budget, and a binary zero-tolerance rule for placeholders. `check_spec` validates these (missing Scope-lock = error, thin task without evidence = warning).
+- **UI hard red lines**: numeric, machine-checkable rules — 4pt spacing scale, WCAG contrast (4.5/3/3), type scale ≥ 1.25, hero font ≤ 6rem, OKLCH, eight interaction states, cognitive load ≤ 4, motion 150-300ms.
+- **UI banned list + Pre-Flight checklist**: match-and-refuse blacklist for AI slop (default Inter/Roboto, AI purple-blue gradients, gradient text, cookie-cutter card grids, em-dash, cream/beige body backgrounds, nested cards) plus a delivery-gate self-check matrix.
+
 ### 🧠 Code Graph Bridge (GitNexus)
 
 - `code_insight` bridges GitNexus by default for query/context/impact analysis

package/build/lib/__tests__/memory-orchestration.unit.test.js

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { renderMemoryGuideSection, shouldShowSourceInSearch, } from '../memory-orchestration.js';
+afterEach(() => {
+    vi.unstubAllEnvs();
+});
+describe('memory-orchestration', () => {
+    test('does not show source path by default', () => {
+        vi.stubEnv('MEMORY_SEARCH_SHOW_SOURCE', '');
+        vi.stubEnv('MEMORY_REPO_ID', '');
+        const section = renderMemoryGuideSection({
+            enabled: true,
+            available: true,
+            degraded: false,
+            query: '404 submit',
+            results: [
+                {
+                    id: '1',
+                    score: 0.91,
+                    name: 'purchase-create-submit-404',
+                    type: 'bugfix',
+                    description: 'desc',
+                    summary: 'summary',
+                    content: '',
+                    tags: ['bugfix'],
+                    sourceProject: 'zhixing/gongyingshang',
+                    sourcePath: 'admin-api/app.js',
+                },
+            ],
+            assetsById: {},
+        });
+        expect(section).toContain('purchase-create-submit-404');
+        expect(section).not.toContain('admin-api/app.js');
+        expect(section).not.toContain('来源:');
+    });
+    test('shows source path when MEMORY_REPO_ID matches', () => {
+        vi.stubEnv('MEMORY_SEARCH_SHOW_SOURCE', '');
+        vi.stubEnv('MEMORY_REPO_ID', 'zhixing/gongyingshang');
+        expect(shouldShowSourceInSearch({
+            id: '1',
+            score: 0.9,
+            name: 'x',
+            type: 'bugfix',
+            description: '',
+            summary: '',
+            content: '',
+            tags: [],
+            sourceProject: 'zhixing/gongyingshang',
+            sourcePath: 'admin-api/app.js',
+        })).toBe(true);
+        expect(shouldShowSourceInSearch({
+            id: '2',
+            score: 0.9,
+            name: 'y',
+            type: 'bugfix',
+            description: '',
+            summary: '',
+            content: '',
+            tags: [],
+            sourceProject: 'other/repo',
+            sourcePath: 'src/index.ts',
+        })).toBe(false);
+    });
+    test('MEMORY_SEARCH_SHOW_SOURCE=true always shows source', () => {
+        vi.stubEnv('MEMORY_SEARCH_SHOW_SOURCE', 'true');
+        vi.stubEnv('MEMORY_REPO_ID', '');
+        const section = renderMemoryGuideSection({
+            enabled: true,
+            available: true,
+            degraded: false,
+            query: 'q',
+            results: [
+                {
+                    id: '1',
+                    score: 0.8,
+                    name: 'n',
+                    type: 'bugfix',
+                    description: '',
+                    summary: 's',
+                    content: '',
+                    tags: [],
+                    sourcePath: 'admin-api/app.js',
+                },
+            ],
+            assetsById: {},
+        });
+        expect(section).toContain('来源: admin-api/app.js');
+    });
+});

package/build/lib/__tests__/memory-payload.unit.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'vitest';
+import { normalizeMemoryPayload, payloadToMemoryFields } from '../memory-payload.js';
+describe('memory-payload', () => {
+    test('maps legacy kind/title/source fields to current schema', () => {
+        const normalized = normalizeMemoryPayload({
+            kind: 'extracted_pattern',
+            title: 'Feishu submit success but sync_failed',
+            source: 'scan_and_extract_patterns-fallback',
+            content: 'Pattern: proxy mismatch',
+            tags: ['feishu', 'pattern'],
+            created_at: '2026-05-25T11:20:06.705Z',
+        });
+        expect(normalized.name).toBe('Feishu submit success but sync_failed');
+        expect(normalized.type).toBe('pattern');
+        expect(normalized.summary).toContain('Pattern');
+        expect(normalized.createdAt).toBe('2026-05-25T11:20:06.705Z');
+    });
+    test('payloadToMemoryFields preserves standard asset fields', () => {
+        const fields = payloadToMemoryFields({
+            id: 'asset-1',
+            name: 'purchase-create-submit-404',
+            type: 'bugfix',
+            description: '送审 404',
+            summary: 'res.data.purchase.id',
+            content: '【现象】404',
+            tags: ['bugfix'],
+            confidence: 0.95,
+            createdAt: '2026-05-27T04:28:04.684Z',
+            updatedAt: '2026-05-27T04:28:04.684Z',
+        });
+        expect(fields.name).toBe('purchase-create-submit-404');
+        expect(fields.type).toBe('bugfix');
+        expect(fields.tags).toEqual(['bugfix']);
+    });
+});

package/build/lib/__tests__/quality-constraints.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/quality-constraints.unit.test.js

@@ -0,0 +1,54 @@
+import { describe, test, expect } from 'vitest';
+import { CODE_LIMITS, BANNED_CODE_PATTERNS, UI_HARD_RULES, UI_BANNED_LIST, renderCodeLimits, renderBannedPatterns, renderUiHardRules, renderUiBannedList, renderPreFlightChecklist, } from '../quality-constraints.js';
+describe('quality-constraints（质量约束单一真相源）', () => {
+    test('CODE_LIMITS 数值符合预期（单文件 500 / 函数 50）', () => {
+        expect(CODE_LIMITS.maxFileLines).toBe(500);
+        expect(CODE_LIMITS.maxFunctionLines).toBe(50);
+        expect(CODE_LIMITS.maxNestingDepth).toBe(4);
+        expect(CODE_LIMITS.maxParameters).toBe(3);
+    });
+    test('黑名单与硬约束清单非空', () => {
+        expect(BANNED_CODE_PATTERNS.length).toBeGreaterThan(0);
+        expect(UI_HARD_RULES.length).toBeGreaterThan(0);
+        expect(UI_BANNED_LIST.length).toBeGreaterThan(0);
+    });
+    test('代码完整性黑名单含关键占位模式', () => {
+        expect(BANNED_CODE_PATTERNS).toContain('// TODO');
+        expect(BANNED_CODE_PATTERNS).toContain('// ...');
+    });
+    test('UI 黑名单含 em-dash 零容忍与 AI 紫蓝渐变', () => {
+        expect(UI_BANNED_LIST.some((b) => b.includes('em-dash'))).toBe(true);
+        expect(UI_BANNED_LIST.some((b) => b.includes('紫蓝渐变'))).toBe(true);
+    });
+    test('renderCodeLimits 输出含 500 行红线', () => {
+        const out = renderCodeLimits();
+        expect(out).toContain('500');
+        expect(out).toContain('HIGH');
+    });
+    test('renderBannedPatterns 输出含 CRITICAL 与二元规则', () => {
+        const out = renderBannedPatterns();
+        expect(out).toContain('CRITICAL');
+        expect(out).toContain('二元');
+    });
+    test('renderUiHardRules 含 4pt 间距阶梯与对比度阈值', () => {
+        const out = renderUiHardRules();
+        expect(out).toContain('4, 8, 12, 16, 24, 32, 48, 64, 96');
+        expect(out).toContain('4.5:1');
+    });
+    test('renderUiBannedList 输出每条以 ❌ 标记', () => {
+        const out = renderUiBannedList();
+        expect(out).toContain('❌');
+    });
+    test('renderPreFlightChecklist 含 Scope-lock 与完整性勾选项', () => {
+        const out = renderPreFlightChecklist();
+        expect(out).toContain('Pre-Flight');
+        expect(out).toContain('Scope-lock');
+        expect(out).toContain('占位符');
+    });
+    // 防回归：注入下游 prompt 的渲染输出自身不得含 em-dash，否则与「em-dash 零容忍」自相矛盾
+    test('代码类渲染输出不含 em-dash（避免规则自相矛盾）', () => {
+        expect(renderCodeLimits()).not.toContain('—');
+        expect(renderBannedPatterns()).not.toContain('—');
+        expect(renderPreFlightChecklist()).not.toContain('—');
+    });
+});

package/build/lib/__tests__/spec-validator.unit.test.js

@@ -1,75 +1,81 @@
 import { describe, test, expect } from 'vitest';
 import { validateSpecDocuments, extractFrIds } from '../spec-validator.js';
-const goodReq = `# 需求文档：demo
-
-## 功能概述
-做一个登录功能。
-
-## 历史经验与坑（来自记忆库）
-- 可复用经验: 无
-- 必须规避的坑: 无
-
-## 范围边界
-In Scope: 登录
-Out of Scope: 注册
-
-## 需求列表
-### FR-1: 登录
-**优先级:** Must
-**用户故事:** 作为用户，我想登录，以便访问系统。
-#### 验收标准（EARS）
-1. WHEN 提交正确凭证 THEN 系统 SHALL 登录成功
-
-## 非功能需求
-- NFR-1: 登录响应 < 1s
-
-## 依赖关系
-- 无
+const goodReq = `# 需求文档：demo
+
+## 功能概述
+做一个登录功能。
+
+## 历史经验与坑（来自记忆库）
+- 可复用经验: 无
+- 必须规避的坑: 无
+
+## 范围边界
+In Scope: 登录
+Out of Scope: 注册
+
+## 需求列表
+### FR-1: 登录
+**优先级:** Must
+**用户故事:** 作为用户，我想登录，以便访问系统。
+#### 验收标准（EARS）
+1. WHEN 提交正确凭证 THEN 系统 SHALL 登录成功
+
+## 非功能需求
+- NFR-1: 登录响应 < 1s
+
+## 依赖关系
+- 无
 `;
-const goodDesign = `# 设计文档：demo
-
-## 概述
-登录设计。
-**对应需求:** FR-1
-
-## 技术方案
-### 技术选型
-使用 JWT。
-
-## 数据模型
-不涉及。
-
-## API 设计
-POST /api/login
-
-## 文件结构
-src/login.ts
-
-## 设计决策
-决策 1：用 JWT。
-
-## 风险评估
-无。
+const goodDesign = `# 设计文档：demo
+
+## 概述
+登录设计。
+**对应需求:** FR-1
+
+## 技术方案
+### 技术选型
+使用 JWT。
+
+## 数据模型
+不涉及。
+
+## API 设计
+POST /api/login
+
+## 文件结构
+src/login.ts
+
+## 设计决策
+决策 1：用 JWT。
+
+## 风险评估
+无。
 `;
-const goodTasks = `# 任务清单：demo
-
-## 概述
-任务分解。
-
-## 任务列表
-### 阶段 2: 核心实现
-- [ ] 2.1 实现登录接口 — _需求: FR-1_ ｜ _设计: API 设计_
-
-## 检查点
-- [ ] 阶段 2 完成后：登录可用
-
-## 需求覆盖矩阵
-| 需求 ID | 设计章节 | 任务编号 | 状态 |
-| FR-1 | API 设计 | 2.1 | 未开始 |
-
-## 文件变更清单
-| 文件 | 操作 | 说明 |
-| src/login.ts | 新建 | 登录接口 |
+const goodTasks = `# 任务清单：demo
+
+## 概述
+任务分解。
+
+## 交付物清单（Scope-lock）
+- 预计新建文件数: 1 个
+- 预计修改文件数: 0 个
+
+## 任务列表
+### 阶段 2: 核心实现
+- [ ] 2.1 实现登录接口 POST /api/login，校验邮箱并返回 JWT
+  - 证据块: 先读 src/router.ts:1，确认路由注册方式
+  - _需求: FR-1_ ｜ _设计: API 设计_
+
+## 检查点
+- [ ] 阶段 2 完成后：登录可用
+
+## 需求覆盖矩阵
+| 需求 ID | 设计章节 | 任务编号 | 状态 |
+| FR-1 | API 设计 | 2.1 | 未开始 |
+
+## 文件变更清单
+| 文件 | 操作 | 说明 |
+| src/login.ts | 新建 | 登录接口 |
 `;
 describe('spec-validator（P1 填写后校验）', () => {
     test('完整规格通过校验', () => {
@@ -98,12 +104,12 @@ describe('spec-validator（P1 填写后校验）', () => {
         expect(r.issues.some((i) => i.code === 'no_acceptance')).toBe(true);
     });
     test('FR 未进 tasks 覆盖矩阵 → 跨文档未覆盖', () => {
-        const reqTwoFr = goodReq.replace('## 非功能需求', `### FR-2: 登出
-**优先级:** Should
-**用户故事:** 作为用户，我想登出。
-#### 验收标准（EARS）
-1. WHEN 点击登出 THEN 系统 SHALL 退出登录
-
+        const reqTwoFr = goodReq.replace('## 非功能需求', `### FR-2: 登出
+**优先级:** Should
+**用户故事:** 作为用户，我想登出。
+#### 验收标准（EARS）
+1. WHEN 点击登出 THEN 系统 SHALL 退出登录
+
 ## 非功能需求`);
         const r = validateSpecDocuments({ requirements: reqTwoFr, design: goodDesign, tasks: goodTasks });
         expect(r.passed).toBe(false);
@@ -112,4 +118,30 @@ describe('spec-validator（P1 填写后校验）', () => {
     test('extractFrIds 去重并保序', () => {
         expect(extractFrIds('FR-1 写了 FR-1 又写 FR-2')).toEqual(['FR-1', 'FR-2']);
     });
+    test('tasks 缺少「交付物清单」章节 → 未通过', () => {
+        const tasksNoScope = goodTasks.replace(/## 交付物清单（Scope-lock）[\s\S]*?\n\n/, '');
+        // 防 fixture 漂移导致替换失效造成假通过
+        expect(tasksNoScope).not.toContain('交付物清单');
+        const r = validateSpecDocuments({ requirements: goodReq, design: goodDesign, tasks: tasksNoScope });
+        expect(r.passed).toBe(false);
+        expect(r.issues.some((i) => i.file === 'tasks' && i.code === 'missing_section')).toBe(true);
+    });
+    test('任务无「证据块」→ thin_task 提醒（warning，不阻断）', () => {
+        const tasksThin = goodTasks.replace('  - 证据块: 先读 src/router.ts:1，确认路由注册方式\n', '');
+        expect(tasksThin).not.toBe(goodTasks);
+        const r = validateSpecDocuments({ requirements: goodReq, design: goodDesign, tasks: tasksThin });
+        expect(r.issues.some((i) => i.code === 'thin_task')).toBe(true);
+        expect(r.warningCount).toBeGreaterThan(0);
+        // 核心语义：thin_task 是 warning，不应阻断 passed
+        expect(r.passed).toBe(true);
+    });
+    test('裸 [填写] 占位（无冒号）也应被检出', () => {
+        const r = validateSpecDocuments({
+            requirements: goodReq + '\n- 备注: [填写]',
+            design: goodDesign,
+            tasks: goodTasks,
+        });
+        expect(r.passed).toBe(false);
+        expect(r.issues.some((i) => i.file === 'requirements' && i.code === 'placeholder')).toBe(true);
+    });
 });

package/build/lib/agents-md-template.js

@@ -4,18 +4,18 @@ function link(layout, targetRel) {
 }
 function memorySection(locale) {
     if (locale === "zh-CN") {
-        return `
-记忆（需 MEMORY_QDRANT_URL 等已配置）：
-- 检索：\`start_*\` 命中后**自动注入**历史经验全文；中途补查可用 \`search_memory\`；单条精读仍可用 \`read_memory_asset\`
-- 沉淀：跨仓库共享**勿填** source_project/source_path；路径写进 content；summary 写检索关键词
-- Bug 修完验证通过 → **必须** \`memorize_asset\` type=\`bugfix\` tags=\`bugfix,root-cause\`（content 含【现象】【根因】【修复】【验证】）
+        return `
+记忆（需 MEMORY_QDRANT_URL 等已配置）：
+- 检索：\`start_*\` 命中后**自动注入**历史经验全文；中途补查可用 \`search_memory\`；单条精读仍可用 \`read_memory_asset\`
+- 沉淀：跨仓库共享**勿填** source_project/source_path；路径写进 content；summary 写检索关键词
+- Bug 修完验证通过 → **必须** \`memorize_asset\` type=\`bugfix\` tags=\`bugfix,root-cause\`（content 含【现象】【根因】【修复】【验证】）
 - 功能/UI 可复用产出 → \`memorize_asset\` type=\`pattern\`/\`component\``;
     }
-    return `
-Memory (requires MEMORY_* env):
-- Search: \`start_*\` auto-injects full memory hits; use \`search_memory\` mid-task; \`read_memory_asset\` for a specific id
-- Store: do NOT use source_project/source_path for cross-repo pools; put paths in content; write keyword-rich summary
-- After verified bugfix → MUST \`memorize_asset\` type=\`bugfix\` (sections: symptom, root cause, fix, verification)
+    return `
+Memory (requires MEMORY_* env):
+- Search: \`start_*\` auto-injects full memory hits; use \`search_memory\` mid-task; \`read_memory_asset\` for a specific id
+- Store: do NOT use source_project/source_path for cross-repo pools; put paths in content; write keyword-rich summary
+- After verified bugfix → MUST \`memorize_asset\` type=\`bugfix\` (sections: symptom, root cause, fix, verification)
 - Reusable feature/UI → \`memorize_asset\` type=\`pattern\`/\`component\``;
 }
 /**
@@ -26,30 +26,30 @@ export function generateAgentsMdInner(input) {
     const graph = link(layout, layout.latestMarkdownPath);
     const ctxIndex = link(layout, layout.legacyIndexPath);
     if (locale === "zh-CN") {
-        return `## MCP（必须先调）
-需已配置 mcp-probe-kit。\`start_*\` 若返回 delegated plan，逐步执行完再结束。
-
-- 新功能 → \`start_feature\`（会先搜记忆）
-- Bug → \`start_bugfix\`（会先搜记忆）
-- UI → \`start_ui\`（会先搜记忆）
-- 不熟代码 / 影响面 → \`code_insight\`（context / impact / auto）
-- 缺上下文 → \`init_project_context\`
-- 提交 → \`gencommit\`
-
-上下文：写代码前先读 [project-context](${ctxIndex})（链到 \`${layout.modularDir}/\` 各文档）
+        return `## MCP（必须先调）
+需已配置 mcp-probe-kit。\`start_*\` 若返回 delegated plan，逐步执行完再结束。
+
+- 新功能 → \`start_feature\`（会先搜记忆）
+- Bug → \`start_bugfix\`（会先搜记忆）
+- UI → \`start_ui\`（会先搜记忆）
+- 不熟代码 / 影响面 → \`code_insight\`（context / impact / auto）
+- 缺上下文 → \`init_project_context\`
+- 提交 → \`gencommit\`
+
+上下文：写代码前先读 [project-context](${ctxIndex})（链到 \`${layout.modularDir}/\` 各文档）
 图谱：大改前读 [latest](${graph})；过期 \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
     }
-    return `## MCP (call first)
-Requires mcp-probe-kit. Complete every \`start_*\` delegated plan step before done.
-
-- Feature → \`start_feature\` (searches memory first)
-- Bug → \`start_bugfix\` (searches memory first)
-- UI → \`start_ui\` (searches memory first)
-- Unfamiliar code / impact → \`code_insight\` (context / impact / auto)
-- Missing context → \`init_project_context\`
-- Commit → \`gencommit\`
-
-Context: before coding read [project-context](${ctxIndex}) (links to \`${layout.modularDir}/\`)
+    return `## MCP (call first)
+Requires mcp-probe-kit. Complete every \`start_*\` delegated plan step before done.
+
+- Feature → \`start_feature\` (searches memory first)
+- Bug → \`start_bugfix\` (searches memory first)
+- UI → \`start_ui\` (searches memory first)
+- Unfamiliar code / impact → \`code_insight\` (context / impact / auto)
+- Missing context → \`init_project_context\`
+- Commit → \`gencommit\`
+
+Context: before coding read [project-context](${ctxIndex}) (links to \`${layout.modularDir}/\`)
 Graph: read [latest](${graph}) before large changes; refresh \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
 }
 export function generateAgentsMdTemplate(input) {

package/build/lib/cursor-history-client.d.ts

@@ -0,0 +1,54 @@
+export interface CursorConversationSummary {
+    composerId: string;
+    name: string;
+    createdAt?: number;
+    lastUpdatedAt?: number;
+    workspaceId?: string;
+    workspacePath?: string;
+    mode?: string;
+    contextUsagePercent?: number;
+    subtitle?: string;
+    isArchived?: boolean;
+    source: 'composerHeaders';
+}
+export interface CursorConversationMessage {
+    bubbleId: string;
+    type: number;
+    text: string;
+    createdAt?: string;
+    requestId?: string;
+}
+export interface CursorConversationDetail {
+    composerId: string;
+    messages: CursorConversationMessage[];
+}
+export interface CursorHistorySearchResult {
+    composerId: string;
+    conversationName: string;
+    bubbleId: string;
+    type: number;
+    text: string;
+    createdAt?: string;
+    requestId?: string;
+}
+export declare class CursorHistoryClient {
+    private withDatabase;
+    private loadConversationIndex;
+    listConversations(params?: {
+        titleQuery?: string;
+        workspaceQuery?: string;
+        includeArchived?: boolean;
+        limit?: number;
+    }): Promise<CursorConversationSummary[]>;
+    searchHistory(params: {
+        query: string;
+        composerId?: string;
+        limit?: number;
+    }): Promise<CursorHistorySearchResult[]>;
+    readConversation(params: {
+        composerId: string;
+        limit?: number;
+        includeEmpty?: boolean;
+    }): Promise<CursorConversationDetail>;
+}
+export declare function createCursorHistoryClient(): CursorHistoryClient;