@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/core/configurators/slash/windsurf.js

@@ -1,8 +1,11 @@
 import { SlashCommandConfigurator } from './base.js';
 const FILE_PATHS = {
     proposal: '.windsurf/workflows/zhuanspec-proposal.md',
+    design: '.windsurf/workflows/zhuanspec-design.md',
     apply: '.windsurf/workflows/zhuanspec-apply.md',
-    archive: '.windsurf/workflows/zhuanspec-archive.md'
+    review: '.windsurf/workflows/zhuanspec-review.md',
+    archive: '.windsurf/workflows/zhuanspec-archive.md',
+    knowledge: '.windsurf/workflows/zhuanspec-knowledge.md'
 };
 export class WindsurfSlashCommandConfigurator extends SlashCommandConfigurator {
     toolId = 'windsurf';
@@ -13,8 +16,11 @@ export class WindsurfSlashCommandConfigurator extends SlashCommandConfigurator {
     getFrontmatter(id) {
         const descriptions = {
             proposal: '搭建新的 ZhuanSpec 变更并严格验证。',
+            design: '在 proposal 之前独立生成技术设计请求文档。',
             apply: '实施已批准的 ZhuanSpec 变更并保持任务同步。',
-            archive: '归档已部署的 ZhuanSpec 变更并更新规范。'
+            review: '在归档前执行代码审查和单元测试验证。',
+            archive: '归档已部署的 ZhuanSpec 变更并更新规范。',
+            knowledge: '管理项目知识库（最佳实践、陷阱、隐式约定）。'
         };
         const description = descriptions[id];
         return `---\ndescription: ${description}\nauto_execution_mode: 3\n---`;

package/dist/core/dashboard/metrics.d.ts

@@ -0,0 +1,33 @@
+export interface ChangeMetricsSummary {
+    changeId: string;
+    phase: string;
+    currentNode: string;
+    currentTask: string;
+    totalTasks: number;
+    completedTasks: number;
+    currentWave: number;
+    nextTask: string;
+    toolCalls: number;
+    skillCalls: Record<string, number>;
+    review: {
+        critical: number;
+        important: number;
+        minor: number;
+        passed: boolean;
+    };
+    tests: {
+        passed: number;
+        failed: number;
+        coverage: number | null;
+    };
+    tokenUsage: number;
+    contextLoad: number;
+    durations: {
+        proposeMs: number;
+        applyMs: number;
+        reviewMs: number;
+        archiveMs: number;
+    };
+}
+export declare function loadChangeMetrics(zhuanspecDir: string, changeId: string): Promise<ChangeMetricsSummary>;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/core/dashboard/metrics.js

@@ -0,0 +1,114 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { countTasksFromContent } from '../../utils/task-progress.js';
+async function readJsonIfExists(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+function parseWaveFromTaskId(taskId) {
+    if (!taskId)
+        return 0;
+    const id = taskId.split('.')[0];
+    const num = Number(id);
+    return Number.isFinite(num) ? num : 0;
+}
+function findNextTask(tasksContent) {
+    const lines = tasksContent.split('\n');
+    for (const line of lines) {
+        const match = line.match(/^-\s*\[\s\]\s*(\d+\.\d+)/);
+        if (match)
+            return match[1];
+    }
+    return '';
+}
+function countSkillCalls(toolCalls) {
+    const result = {};
+    for (const call of toolCalls ?? []) {
+        const inputContent = (call?.input?.content ?? '');
+        const matches = inputContent.match(/@skill:([^\s@]+)/g) ?? [];
+        for (const raw of matches) {
+            const names = raw.replace('@skill:', '').split(',');
+            for (const name of names) {
+                const key = name.trim();
+                if (!key || key === 'none')
+                    continue;
+                result[key] = (result[key] ?? 0) + 1;
+            }
+        }
+    }
+    return result;
+}
+export async function loadChangeMetrics(zhuanspecDir, changeId) {
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const metricsDir = path.join(changeDir, 'metrics');
+    const progress = await readJsonIfExists(path.join(metricsDir, 'progress.json'));
+    const events = await readJsonIfExists(path.join(metricsDir, 'events.json'));
+    const review = await readJsonIfExists(path.join(metricsDir, 'review.json'));
+    const tests = await readJsonIfExists(path.join(metricsDir, 'tests.json'));
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    let totalTasks = 0;
+    let completedTasks = 0;
+    let nextTask = '';
+    try {
+        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+        const taskProgress = countTasksFromContent(tasksContent);
+        totalTasks = taskProgress.total;
+        completedTasks = taskProgress.completed;
+        nextTask = findNextTask(tasksContent);
+    }
+    catch {
+        // ignore
+    }
+    const phase = progress?.phase ?? 'idle';
+    const currentTask = progress?.currentTask ?? '';
+    const currentNode = progress?.currentNode ?? phase;
+    const currentWave = parseWaveFromTaskId(currentTask || nextTask);
+    const toolCalls = (progress?.toolCalls ?? []);
+    const skillCalls = countSkillCalls(toolCalls);
+    const tokenUsage = Number(progress?.stats?.tokenUsageTotal ?? 0) +
+        Number(progress?.stats?.tokenUsage?.propose ?? 0) +
+        Number(progress?.stats?.tokenUsage?.apply ?? 0) +
+        Number(progress?.stats?.tokenUsage?.review ?? 0) +
+        Number(progress?.stats?.tokenUsage?.archive ?? 0);
+    const contextLoad = Number(progress?.stats?.contextLoad ?? 0);
+    const phaseDurations = (progress?.stats?.durationMs ?? {});
+    return {
+        changeId,
+        phase,
+        currentNode,
+        currentTask,
+        totalTasks,
+        completedTasks,
+        currentWave,
+        nextTask,
+        toolCalls: toolCalls.length,
+        skillCalls,
+        review: {
+            critical: Number(review?.summary?.critical ?? 0),
+            important: Number(review?.summary?.important ?? 0),
+            minor: Number(review?.summary?.minor ?? 0),
+            passed: Boolean(review?.passed ?? false),
+        },
+        tests: {
+            passed: Number(tests?.passed ?? 0),
+            failed: Number(tests?.failed ?? 0),
+            coverage: typeof tests?.coverage === 'number'
+                ? Number(tests.coverage)
+                : null,
+        },
+        tokenUsage,
+        contextLoad,
+        durations: {
+            proposeMs: Number(phaseDurations.propose ?? 0),
+            applyMs: Number(phaseDurations.apply ?? 0),
+            reviewMs: Number(phaseDurations.review ?? 0),
+            archiveMs: Number(phaseDurations.archive ?? 0),
+        },
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/core/hooks/collect-knowledge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PostToolUse Hook - Collect Knowledge
+ *
+ * This hook runs after Write/Edit operations to:
+ * 1. Detect pitfall keywords in content or conversation
+ * 2. Extract and save troubleshooting knowledge
+ * 3. Record implicit conventions discovered
+ */
+interface CollectKnowledgeOptions {
+    json?: boolean;
+    file?: string;
+    content?: string;
+}
+export declare function collectKnowledgeHook(options: CollectKnowledgeOptions): Promise<void>;
+export {};
+//# sourceMappingURL=collect-knowledge.d.ts.map

package/dist/core/hooks/collect-knowledge.js

@@ -0,0 +1,203 @@
+/**
+ * PostToolUse Hook - Collect Knowledge
+ *
+ * This hook runs after Write/Edit operations to:
+ * 1. Detect pitfall keywords in content or conversation
+ * 2. Extract and save troubleshooting knowledge
+ * 3. Record implicit conventions discovered
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { PITFALL_KEYWORDS, BEST_PRACTICE_KEYWORDS, IMPLICIT_CONVENTION_KEYWORDS } from './deviation-check.js';
+import { getBeijingTime, getBeijingTimeForFilename } from './record-progress.js';
+export async function collectKnowledgeHook(options) {
+    // Read stdin for Claude Code hook input
+    let stdinData = {};
+    try {
+        const stdinContent = await readStdin();
+        if (stdinContent) {
+            stdinData = JSON.parse(stdinContent);
+        }
+    }
+    catch {
+        // Ignore parse errors
+    }
+    // Get content from stdin or options
+    const content = stdinData.tool_input?.content
+        || options.content
+        || '';
+    const filePath = stdinData.tool_input?.file_path
+        || options.file
+        || '';
+    const output = await runCollectKnowledge(content, filePath);
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else {
+        if (output.systemMessage) {
+            console.log(output.systemMessage);
+        }
+    }
+}
+async function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => data += chunk);
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(null));
+    });
+}
+async function runCollectKnowledge(content, filePath) {
+    const phase = process.env.ZHUANSPEC_PHASE || 'idle';
+    const changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
+    // No active change → nothing to collect
+    if (!changeId || phase === 'idle') {
+        return {
+            continue: true,
+        };
+    }
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const knowledgeDir = path.join(changeDir, 'knowledge');
+    const troubleshootingDir = path.join(knowledgeDir, 'troubleshooting');
+    const bestPracticesDir = path.join(knowledgeDir, 'best-practices');
+    const implicitConventionsDir = path.join(knowledgeDir, 'implicit-conventions');
+    // Check for all keyword types
+    const contentLower = content.toLowerCase();
+    const detectedPitfalls = PITFALL_KEYWORDS.filter(kw => contentLower.includes(kw.toLowerCase()));
+    const detectedBestPractices = BEST_PRACTICE_KEYWORDS.filter(kw => contentLower.includes(kw.toLowerCase()));
+    const detectedImplicitConventions = IMPLICIT_CONVENTION_KEYWORDS.filter(kw => contentLower.includes(kw.toLowerCase()));
+    // If no keywords detected, return early
+    if (detectedPitfalls.length === 0 && detectedBestPractices.length === 0 && detectedImplicitConventions.length === 0) {
+        return {
+            continue: true,
+        };
+    }
+    // Create directories as needed
+    await FileSystemUtils.createDirectory(knowledgeDir);
+    const collectedTypes = [];
+    let totalEntries = 0;
+    // Process pitfalls
+    if (detectedPitfalls.length > 0) {
+        await FileSystemUtils.createDirectory(troubleshootingDir);
+        const pitfall = extractKnowledgeContext(content, filePath, detectedPitfalls, 'troubleshooting');
+        const timestamp = getBeijingTimeForFilename();
+        const filename = `pitfall-${timestamp}.md`;
+        const pitfallPath = path.join(troubleshootingDir, filename);
+        await FileSystemUtils.writeFile(pitfallPath, formatKnowledgeRecord(pitfall));
+        updateKnowledgeIndex(knowledgeDir, 'troubleshooting', pitfall.title, filename);
+        collectedTypes.push('pitfall');
+        totalEntries++;
+    }
+    // Process best practices
+    if (detectedBestPractices.length > 0) {
+        await FileSystemUtils.createDirectory(bestPracticesDir);
+        const bestPractice = extractKnowledgeContext(content, filePath, detectedBestPractices, 'best_practice');
+        const timestamp = getBeijingTimeForFilename();
+        const filename = `best-practice-${timestamp}.md`;
+        const bpPath = path.join(bestPracticesDir, filename);
+        await FileSystemUtils.writeFile(bpPath, formatKnowledgeRecord(bestPractice));
+        updateKnowledgeIndex(knowledgeDir, 'best-practices', bestPractice.title, filename);
+        collectedTypes.push('best practice');
+        totalEntries++;
+    }
+    // Process implicit conventions
+    if (detectedImplicitConventions.length > 0) {
+        await FileSystemUtils.createDirectory(implicitConventionsDir);
+        const implicitConvention = extractKnowledgeContext(content, filePath, detectedImplicitConventions, 'implicit_contract');
+        const timestamp = getBeijingTimeForFilename();
+        const filename = `implicit-convention-${timestamp}.md`;
+        const icPath = path.join(implicitConventionsDir, filename);
+        await FileSystemUtils.writeFile(icPath, formatKnowledgeRecord(implicitConvention));
+        updateKnowledgeIndex(knowledgeDir, 'implicit-conventions', implicitConvention.title, filename);
+        collectedTypes.push('implicit convention');
+        totalEntries++;
+    }
+    return {
+        continue: true,
+        systemMessage: `📝 Knowledge detected and recorded: ${collectedTypes.join(', ')}`,
+        hookSpecificOutput: {
+            knowledgeCollected: `${totalEntries} entries`,
+            pitfallDetected: detectedPitfalls.length > 0,
+        },
+    };
+}
+async function updateKnowledgeIndex(knowledgeDir, section, title, filename) {
+    const indexPath = path.join(knowledgeDir, 'index.md');
+    const subdir = section === 'troubleshooting' ? 'troubleshooting' :
+        section === 'best-practices' ? 'best-practices' :
+            'implicit-conventions';
+    const indexEntry = `\n- [${title}](${subdir}/${filename}) - ${getBeijingTime()}\n`;
+    if (await FileSystemUtils.fileExists(indexPath)) {
+        const existingIndex = await FileSystemUtils.readFile(indexPath);
+        // Find section or create it
+        const sectionHeader = `## ${section}`;
+        if (existingIndex.includes(sectionHeader)) {
+            // Append to existing section
+            const updated = existingIndex.replace(sectionHeader, `${sectionHeader}${indexEntry}`);
+            await FileSystemUtils.writeFile(indexPath, updated);
+        }
+        else {
+            // Add new section
+            await FileSystemUtils.writeFile(indexPath, `${existingIndex}\n\n${sectionHeader}${indexEntry}`);
+        }
+    }
+    else {
+        await FileSystemUtils.writeFile(indexPath, `# Knowledge Index\n\n## troubleshooting\n\n## best-practices\n\n## implicit-conventions\n${indexEntry}`);
+    }
+}
+function extractKnowledgeContext(content, filePath, keywords, type) {
+    // Extract relevant context around keywords
+    const lines = content.split('\n');
+    const relevantLines = [];
+    for (let i = 0; i < lines.length; i++) {
+        const lineLower = lines[i].toLowerCase();
+        if (keywords.some(kw => lineLower.includes(kw.toLowerCase()))) {
+            // Include surrounding context (3 lines before and after)
+            const start = Math.max(0, i - 3);
+            const end = Math.min(lines.length, i + 4);
+            for (let j = start; j < end; j++) {
+                relevantLines.push(lines[j]);
+            }
+            relevantLines.push('---');
+        }
+    }
+    // Generate title from first keyword found
+    const firstKeyword = keywords[0];
+    const typeLabel = type === 'troubleshooting' ? 'Issue' :
+        type === 'best_practice' ? 'Best Practice' :
+            'Convention';
+    const title = `${typeLabel}: ${firstKeyword} in ${filePath}`;
+    return {
+        type,
+        title,
+        content: relevantLines.join('\n'),
+        source: filePath,
+        timestamp: getBeijingTime(),
+        tags: keywords,
+    };
+}
+function formatKnowledgeRecord(entry) {
+    return `# ${entry.title}
+
+**Type**: ${entry.type}
+**Source**: ${entry.source}
+**Timestamp**: ${entry.timestamp}
+**Tags**: ${entry.tags.join(', ')}
+
+## Context
+
+${entry.content}
+
+## Resolution
+
+[To be filled when resolved]
+
+## Lessons Learned
+
+[To be extracted after resolution]
+`;
+}
+//# sourceMappingURL=collect-knowledge.js.map

package/dist/core/hooks/context-load-hook.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Context Load Hook
+ *
+ * Records context resource loading (project.md, rules, specs, knowledge, skills).
+ * This hook tracks what resources are loaded during each phase.
+ */
+interface ContextLoadOutput {
+    continue: boolean;
+    systemMessage?: string;
+    hookSpecificOutput?: {
+        resourceRecorded: boolean;
+        resourceType: string;
+        resourcePath: string;
+    };
+}
+/**
+ * Main hook function - records context resource loading
+ */
+export declare function contextLoadHook(filePath: string, triggerContext?: string): Promise<ContextLoadOutput>;
+/**
+ * CLI entry point
+ */
+export declare function runContextLoadHook(): Promise<void>;
+export {};
+//# sourceMappingURL=context-load-hook.d.ts.map

package/dist/core/hooks/context-load-hook.js

@@ -0,0 +1,159 @@
+/**
+ * Context Load Hook
+ *
+ * Records context resource loading (project.md, rules, specs, knowledge, skills).
+ * This hook tracks what resources are loaded during each phase.
+ */
+import path from 'path';
+import fs from 'fs';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { getBeijingTime } from './record-progress.js';
+/**
+ * Determine resource type from file path
+ */
+function determineResourceType(filePath) {
+    if (filePath.includes('project.md'))
+        return 'project.md';
+    if (filePath.includes('.claude/rules/'))
+        return 'rule';
+    if (filePath.includes('zhuanspec/specs/'))
+        return 'spec';
+    if (filePath.includes('zhuanspec/knowledge/'))
+        return 'knowledge';
+    if (filePath.includes('AGENTS.md'))
+        return 'AGENTS.md';
+    if (filePath.includes('CLAUDE.md'))
+        return 'CLAUDE.md';
+    if (filePath.includes('skills/') && filePath.includes('SKILL.md'))
+        return 'skill';
+    return 'other';
+}
+/**
+ * Determine load source based on trigger
+ */
+function determineLoadSource(triggerContext) {
+    if (triggerContext.includes('SessionStart'))
+        return 'init-hook';
+    if (triggerContext.includes('Skill'))
+        return 'skill-request';
+    if (triggerContext.includes('AskUser'))
+        return 'user-request';
+    return 'auto-load';
+}
+/**
+ * Get file size in characters
+ */
+async function getFileSizeChars(filePath) {
+    try {
+        const absolutePath = path.resolve(process.cwd(), filePath);
+        const content = await fs.promises.readFile(absolutePath, 'utf-8');
+        return content.length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Main hook function - records context resource loading
+ */
+export async function contextLoadHook(filePath, triggerContext = 'auto-load') {
+    const phase = process.env.ZHUANSPEC_PHASE || 'idle';
+    const changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
+    // Skip if not in active phase
+    if (!changeId || phase === 'idle') {
+        return { continue: true };
+    }
+    // Determine resource type
+    const resourceType = determineResourceType(filePath);
+    // Skip 'other' type resources
+    if (resourceType === 'other') {
+        return { continue: true };
+    }
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const metricsDir = path.join(zhuanspecDir, 'changes', changeId, 'metrics');
+    // Ensure metrics directory exists
+    await FileSystemUtils.createDirectory(metricsDir);
+    const contextPath = path.join(metricsDir, 'context_resources.json');
+    // Create resource record
+    const resourceRecord = {
+        resourceId: `ctx-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        type: resourceType,
+        path: filePath,
+        loadedAt: getBeijingTime(),
+        phase,
+        sizeChars: await getFileSizeChars(filePath),
+        source: determineLoadSource(triggerContext)
+    };
+    // Load existing context records or create new
+    let contextResources;
+    if (await FileSystemUtils.fileExists(contextPath)) {
+        try {
+            contextResources = JSON.parse(await FileSystemUtils.readFile(contextPath));
+            contextResources.resources.push(resourceRecord);
+        }
+        catch {
+            contextResources = {
+                changeId,
+                sessionId: `sess-${Date.now()}`,
+                resources: [resourceRecord]
+            };
+        }
+    }
+    else {
+        contextResources = {
+            changeId,
+            sessionId: `sess-${Date.now()}`,
+            resources: [resourceRecord]
+        };
+    }
+    // Write context resources file
+    await FileSystemUtils.writeFile(contextPath, JSON.stringify(contextResources, null, 2));
+    return {
+        continue: true,
+        systemMessage: `📚 Context loaded: ${resourceType} (${filePath}) | Size: ${resourceRecord.sizeChars} chars`,
+        hookSpecificOutput: {
+            resourceRecorded: true,
+            resourceType,
+            resourcePath: filePath
+        }
+    };
+}
+/**
+ * CLI entry point
+ */
+export async function runContextLoadHook() {
+    // Read stdin for tool input
+    let stdinData = {};
+    try {
+        const stdinContent = await readStdin();
+        if (stdinContent) {
+            stdinData = JSON.parse(stdinContent);
+        }
+    }
+    catch {
+        // Ignore parse errors
+    }
+    const filePath = stdinData.tool_input?.file_path || '';
+    const triggerContext = stdinData.trigger_context || 'read-tool';
+    if (!filePath) {
+        console.log(JSON.stringify({ continue: true }));
+        return;
+    }
+    const output = await contextLoadHook(filePath, triggerContext);
+    console.log(JSON.stringify(output));
+}
+async function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => data += chunk);
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(null));
+    });
+}
+// CLI execution
+if (require.main === module) {
+    runContextLoadHook();
+}
+//# sourceMappingURL=context-load-hook.js.map

package/dist/core/hooks/deviation-check.d.ts

@@ -0,0 +1,27 @@
+/**
+ * PreToolUse Hook - Deviation Check
+ *
+ * This hook runs before Write/Edit operations to check if the modification
+ * is within the approved proposal scope. It implements the "Reverse Sync" iron law.
+ *
+ * Logic:
+ * 1. If ZHUANSPEC_PHASE is 'idle' or no change bound → allow (normal workflow)
+ * 2. If ZHUANSPEC_PHASE is 'propose' → block (no code changes in propose phase)
+ * 3. If ZHUANSPEC_PHASE is 'apply' → check if file is in proposal scope:
+ *    - In scope → allow
+ *    - Out of scope → block with deviation handling options
+ */
+interface DeviationCheckOptions {
+    json?: boolean;
+    file?: string;
+    tool?: string;
+    trigger?: 'pre-tool' | 'post-prompt' | 'resume';
+    prompt?: string;
+}
+declare const PITFALL_KEYWORDS: string[];
+declare const BEST_PRACTICE_KEYWORDS: string[];
+declare const IMPLICIT_CONVENTION_KEYWORDS: string[];
+declare const USER_CORRECTION_KEYWORDS: string[];
+export declare function deviationCheckHook(options: DeviationCheckOptions): Promise<void>;
+export { PITFALL_KEYWORDS, USER_CORRECTION_KEYWORDS, BEST_PRACTICE_KEYWORDS, IMPLICIT_CONVENTION_KEYWORDS };
+//# sourceMappingURL=deviation-check.d.ts.map