@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/core/init.js

@@ -287,14 +287,8 @@ export class InitCommand {
             await this.createDirectoryStructure(zhuanspecPath);
             await this.ensureTemplateFiles(zhuanspecPath, config);
         }
-        // Step 2: Configure AI tools
-        const toolSpinner = this.startSpinner('正在配置 AI 工具...');
-        const rootStubStatus = await this.configureAITools(projectPath, zhuanspecDir, config.aiTools);
-        toolSpinner.stopAndPersist({
-            symbol: PALETTE.white('▌'),
-            text: PALETTE.white('AI 工具已配置'),
-        });
-        // Step 3: Select business direction and apply architecture file
+        // Step 2: Select business direction and sync Claude assets BEFORE configureAITools
+        // This ensures .claude directory is not deleted after slash commands are generated
         await this.promptForBusinessDirection();
         if (this.businessDirection) {
             const directionMetaPath = path.join(zhuanspecPath, '.business-direction');
@@ -339,6 +333,7 @@ export class InitCommand {
                     text: PALETTE.midGray(`未找到 ${this.businessDirection} 业务规范模板目录，保留默认模板`),
                 });
             }
+            // Sync Claude assets BEFORE configureAITools to avoid deletion
             const claudeAssetSpinner = this.startSpinner(`正在同步 ${this.businessDirection} 业务 Claude 规范资产...`);
             const claudeAssetResult = this.syncBusinessClaudeAssets(projectPath);
             const claudeMdText = this.describeClaudeAssetResult('CLAUDE.md', claudeAssetResult.claudeMd);
@@ -348,8 +343,15 @@ export class InitCommand {
                 text: PALETTE.white(`Claude 规范资产同步完成：${claudeMdText}；${dotClaudeText}`),
             });
         }
+        // Step 3: Configure AI tools (after Claude assets sync to preserve generated files)
+        const toolSpinner = this.startSpinner('正在配置 AI 工具...');
+        const toolConfigResult = await this.configureAITools(projectPath, zhuanspecDir, config.aiTools);
+        toolSpinner.stopAndPersist({
+            symbol: PALETTE.white('▌'),
+            text: PALETTE.white('AI 工具已配置'),
+        });
         // Success message
-        this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode, rootStubStatus);
+        this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode, toolConfigResult.rootStubStatus, toolConfigResult.claudeHookSummary);
     }
     async validate(projectPath, _zhuanspecPath) {
         const extendMode = await FileSystemUtils.directoryExists(_zhuanspecPath);
@@ -543,10 +545,34 @@ export class InitCommand {
             path.join(zhuanspecPath, 'specs'),
             path.join(zhuanspecPath, 'changes'),
             path.join(zhuanspecPath, 'changes', 'archive'),
+            // NEW: Project-level knowledge directory
+            path.join(zhuanspecPath, 'knowledge'),
+            path.join(zhuanspecPath, 'knowledge', 'troubleshooting'),
+            path.join(zhuanspecPath, 'knowledge', 'best-practices'),
+            path.join(zhuanspecPath, 'knowledge', 'implicit-conventions'),
         ];
         for (const dir of directories) {
             await FileSystemUtils.createDirectory(dir);
         }
+        // NEW: Create initial knowledge index file if not exists
+        const indexPath = path.join(zhuanspecPath, 'knowledge', 'index.md');
+        if (!(await FileSystemUtils.fileExists(indexPath))) {
+            const knowledgeIndexContent = `# Knowledge Index
+
+## Troubleshooting
+
+<!-- Entries will be added by collect-knowledge hook -->
+
+## Best Practices
+
+<!-- Project-specific best practices -->
+
+## Implicit Conventions
+
+<!-- Conventions discovered during implementation -->
+`;
+            await FileSystemUtils.writeFile(indexPath, knowledgeIndexContent);
+        }
     }
     async generateFiles(zhuanspecPath, config) {
         await this.writeTemplateFiles(zhuanspecPath, config, false);
@@ -635,6 +661,11 @@ export class InitCommand {
         return ['oms', 'ass'];
     }
     async promptForBusinessDirection() {
+        // 处理显式的跳过标记（从命令行参数或交互式选择传入）
+        if (this.businessDirection === '__skip__') {
+            this.businessDirection = undefined;
+            return;
+        }
         if (this.businessDirection) {
             return;
         }
@@ -1098,7 +1129,9 @@ export class InitCommand {
                 await slashConfigurator.generateAll(projectPath, zhuanspecDir);
             }
         }
-        return rootStubStatus;
+        // Generate Claude Code hooks configuration
+        const claudeHookSummary = await this.generateClaudeSettings(projectPath);
+        return { rootStubStatus, claudeHookSummary };
     }
     async configureRootAgentsStub(projectPath, zhuanspecDir) {
         const configurator = ToolRegistry.get('agents');
@@ -1110,7 +1143,178 @@ export class InitCommand {
         await configurator.configure(projectPath, zhuanspecDir);
         return existed ? 'updated' : 'created';
     }
-    displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode, rootStubStatus) {
+    /**
+     * Generate Claude Code hooks configuration for ZhuanSpec workflow.
+     * Creates .claude/settings.json with hooks for SessionStart, PreToolUse, PostToolUse, and Stop.
+     */
+    async generateClaudeSettings(projectPath) {
+        const claudeDir = path.join(projectPath, '.claude');
+        const settingsPath = path.join(claudeDir, 'settings.json');
+        // Ensure .claude directory exists
+        await FileSystemUtils.createDirectory(claudeDir);
+        // Check if settings.json already exists
+        const existingSettings = await this.readExistingSettings(settingsPath);
+        // Define ZhuanSpec hooks configuration
+        const zhuanspecHooksConfig = {
+            hooks: {
+                SessionStart: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook init',
+                                statusMessage: 'Initializing ZhuanSpec...',
+                            },
+                        ],
+                    },
+                ],
+                PreToolUse: [
+                    {
+                        matcher: 'Write|Edit',
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook deviation-check',
+                                statusMessage: 'Checking proposal compliance...',
+                            },
+                        ],
+                    },
+                ],
+                PostToolUse: [
+                    {
+                        matcher: 'Write|Edit|Read|Grep|Glob|Bash|Skill|Agent|mcp__.*',
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook record-progress',
+                                statusMessage: '📝 Recording progress...',
+                                async: false,
+                            },
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook collect-knowledge',
+                                statusMessage: '📚 Collecting knowledge...',
+                                async: false,
+                            },
+                        ],
+                    },
+                ],
+                Stop: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook summarize',
+                                statusMessage: 'Summarizing progress...',
+                            },
+                        ],
+                    },
+                ],
+                Notification: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook notify-milestone',
+                                statusMessage: 'Checking milestones...',
+                            },
+                        ],
+                    },
+                ],
+            },
+            env: {
+                ZHUANSPEC_PHASE: 'idle',
+                ZHUANSPEC_CHANGE_ID: '',
+                ZHUANSPEC_CURRENT_TASK: '',
+                ZHUANSPEC_HOOKS_VERSION: '1.0.0',
+            },
+        };
+        // Merge with existing settings if present
+        const mergeResult = this.mergeSettings(existingSettings, zhuanspecHooksConfig);
+        // Write the settings file
+        await FileSystemUtils.writeFile(settingsPath, JSON.stringify(mergeResult.settings, null, 2));
+        return mergeResult.summary;
+    }
+    async readExistingSettings(settingsPath) {
+        try {
+            if (await FileSystemUtils.fileExists(settingsPath)) {
+                const content = await FileSystemUtils.readFile(settingsPath);
+                return JSON.parse(content);
+            }
+        }
+        catch {
+            // Ignore parse errors, will create new file
+        }
+        return null;
+    }
+    mergeSettings(existing, zhuanspecConfig) {
+        const summary = {
+            totalAddedHooks: 0,
+            duplicateHooksSkipped: 0,
+        };
+        if (!existing) {
+            const zhuanspecHooks = zhuanspecConfig.hooks;
+            for (const hookConfigs of Object.values(zhuanspecHooks)) {
+                summary.totalAddedHooks += Array.isArray(hookConfigs) ? hookConfigs.length : 0;
+            }
+            return { settings: zhuanspecConfig, summary };
+        }
+        // Deep merge: preserve existing settings while adding ZhuanSpec hooks
+        const merged = { ...existing };
+        // Merge hooks
+        if (merged.hooks && typeof merged.hooks === 'object') {
+            const existingHooks = merged.hooks;
+            const zhuanspecHooks = zhuanspecConfig.hooks;
+            // For each hook type, append ZhuanSpec hooks to existing array
+            for (const [hookType, zhuanspecHookConfig] of Object.entries(zhuanspecHooks)) {
+                if (existingHooks[hookType] && Array.isArray(existingHooks[hookType])) {
+                    // Append ZhuanSpec hooks to existing hooks array while de-duplicating.
+                    const existingArray = existingHooks[hookType];
+                    const zhuanspecArray = zhuanspecHookConfig;
+                    const existingSignatures = new Set(existingArray.map((item) => JSON.stringify(item)));
+                    const uniqueToAppend = [];
+                    for (const item of zhuanspecArray) {
+                        const signature = JSON.stringify(item);
+                        if (existingSignatures.has(signature)) {
+                            summary.duplicateHooksSkipped += 1;
+                            continue;
+                        }
+                        existingSignatures.add(signature);
+                        uniqueToAppend.push(item);
+                    }
+                    summary.totalAddedHooks += uniqueToAppend.length;
+                    existingHooks[hookType] = [...existingArray, ...uniqueToAppend];
+                }
+                else {
+                    // Create new hook type with ZhuanSpec config
+                    const zhuanspecArray = zhuanspecHookConfig;
+                    summary.totalAddedHooks += Array.isArray(zhuanspecArray)
+                        ? zhuanspecArray.length
+                        : 0;
+                    existingHooks[hookType] = zhuanspecHookConfig;
+                }
+            }
+        }
+        else {
+            // No existing hooks, add all ZhuanSpec hooks
+            const zhuanspecHooks = zhuanspecConfig.hooks;
+            for (const hookConfigs of Object.values(zhuanspecHooks)) {
+                summary.totalAddedHooks += Array.isArray(hookConfigs) ? hookConfigs.length : 0;
+            }
+            merged.hooks = zhuanspecConfig.hooks;
+        }
+        // Merge env variables
+        if (merged.env && typeof merged.env === 'object') {
+            const existingEnv = merged.env;
+            const zhuanspecEnv = zhuanspecConfig.env;
+            merged.env = { ...existingEnv, ...zhuanspecEnv };
+        }
+        else {
+            merged.env = zhuanspecConfig.env;
+        }
+        return { settings: merged, summary };
+    }
+    displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode, rootStubStatus, claudeHookSummary) {
         console.log(); // Empty line for spacing
         const successHeadline = extendMode
             ? 'ZhuanSpec 工具配置已更新！'
@@ -1150,21 +1354,27 @@ export class InitCommand {
             console.log(PALETTE.midGray('斜杠命令在启动时加载。请重启您的编程助手'));
             console.log(PALETTE.midGray('以确保新的 /zhuanspec 命令出现在命令面板中。'));
         }
+        console.log();
+        console.log(PALETTE.white('Claude Hook 注册说明'));
+        console.log(PALETTE.lightGray(`- 直接注册（Claude 生命周期）: SessionStart(init), PreToolUse(deviation-check), PostToolUse(record-progress/collect-knowledge), Stop(summarize)`));
+        console.log(PALETTE.lightGray('- 间接触发（阶段门禁）: pre-apply/post-apply/review-* 通过上述主链路与 zhuanspec review 执行'));
+        console.log(PALETTE.midGray(`- 本次 hooks 变更: 新增 ${claudeHookSummary.totalAddedHooks}，跳过重复 ${claudeHookSummary.duplicateHooksSkipped}`));
         // Get the selected tool name(s) for display
         const toolName = this.formatToolNames(selectedTools);
+        // Display workflow diagram
+        console.log();
+        console.log(PALETTE.white('ZhuanSpec 工作流程'));
+        console.log(PALETTE.darkGray('─'.repeat(60)));
+        console.log();
+        this.displayWorkflowDiagram();
+        console.log();
+        console.log(PALETTE.darkGray('─'.repeat(60)));
+        console.log();
+        // Quick start guide
+        console.log(PALETTE.white(`快速开始 - 在 ${toolName} 中执行：`));
+        console.log(PALETTE.lightGray('  /zhuanspec:proposal "我想添加 [您的功能]"'));
+        console.log(PALETTE.midGray('  → 自动创建变更提案，开始规范化开发流程'));
         console.log();
-        console.log(`下一步 - 将这些提示复制到 ${toolName}：`);
-        console.log(chalk.gray('────────────────────────────────────────────────────────────'));
-        console.log(PALETTE.white('1. 填充您的项目上下文：'));
-        console.log(PALETTE.lightGray('   "请阅读 zhuanspec/project.md 并帮助我填写'));
-        console.log(PALETTE.lightGray('    有关我的项目、技术栈和约定的详细信息"\n'));
-        console.log(PALETTE.white('2. 创建您的第一个变更提案：'));
-        console.log(PALETTE.lightGray('   "我想添加 [您的功能]。请为此功能'));
-        console.log(PALETTE.lightGray('    创建一个 ZhuanSpec 变更提案"\n'));
-        console.log(PALETTE.white('3. 了解 ZhuanSpec 工作流：'));
-        console.log(PALETTE.lightGray('   "请解释 zhuanspec/AGENTS.md 中的 ZhuanSpec 工作流'));
-        console.log(PALETTE.lightGray('    以及我应该如何在这个项目上与您合作"'));
-        console.log(PALETTE.darkGray('────────────────────────────────────────────────────────────\n'));
         // Codex heads-up: prompts installed globally
         const selectedToolIds = new Set(selectedTools.map((t) => t.value));
         if (selectedToolIds.has('codex')) {
@@ -1173,6 +1383,24 @@ export class InitCommand {
             console.log();
         }
     }
+    displayWorkflowDiagram() {
+        const gray = '\x1b[90m';
+        const green = '\x1b[32m';
+        const cyan = '\x1b[36m';
+        const yellow = '\x1b[33m';
+        const magenta = '\x1b[35m';
+        const reset = '\x1b[0m';
+        console.log();
+        console.log(`    ${gray}[技术设计]${reset}  →  ${green}[创建提案]${reset}  →  ${cyan}[实施变更]${reset}  →  ${yellow}[审查门禁]${reset}  →  ${magenta}[归档完成]${reset}`);
+        console.log();
+        console.log(`     ${gray}/techDesign${reset}      ${gray}/proposal${reset}        ${cyan}/apply${reset}         ${yellow}/review${reset}         ${magenta}/archive${reset}`);
+        console.log();
+        console.log(`    ${gray}techDesign${reset} : 可选阶段，生成技术设计文档`);
+        console.log(`    ${green}propose${reset}    : 创建变更提案，等待审批，可集成测试 case`);
+        console.log(`    ${cyan}apply${reset}     : 实施变更，执行 tasks 追踪进度`);
+        console.log(`    ${yellow}review${reset}    : 审查门禁，代码审查 + 单测 + spec-code 一致性验证`);
+        console.log(`    ${magenta}archive${reset}   : 归档完成，更新 specs 记录变更和知识沉淀`);
+    }
     formatToolNames(tools) {
         const names = tools
             .map((tool) => tool.successLabel ?? tool.name)

package/dist/core/parsers/requirement-blocks.js

@@ -1,7 +1,10 @@
 export function normalizeRequirementName(name) {
     return name.trim();
 }
-const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/;
+const REQUIREMENT_HEADER_REGEX = /^###\s*(?:Requirement|需求)[：:]\s*(.+)\s*$/i;
+function isRequirementHeader(line) {
+    return /^###\s*(?:Requirement|需求)[：:]/i.test(line);
+}
 /**
  * Extracts the Requirements section from a spec file and parses requirement blocks.
  */
@@ -80,10 +83,10 @@ function normalizeLineEndings(content) {
 export function parseDeltaSpec(content) {
     const normalized = normalizeLineEndings(content);
     const sections = splitTopLevelSections(normalized);
-    const addedLookup = getSectionCaseInsensitive(sections, 'ADDED Requirements');
-    const modifiedLookup = getSectionCaseInsensitive(sections, 'MODIFIED Requirements');
-    const removedLookup = getSectionCaseInsensitive(sections, 'REMOVED Requirements');
-    const renamedLookup = getSectionCaseInsensitive(sections, 'RENAMED Requirements');
+    const addedLookup = getSectionByAliases(sections, ['ADDED Requirements', '新增要求']);
+    const modifiedLookup = getSectionByAliases(sections, ['MODIFIED Requirements', '修改要求']);
+    const removedLookup = getSectionByAliases(sections, ['REMOVED Requirements', '移除要求', '删除要求']);
+    const renamedLookup = getSectionByAliases(sections, ['RENAMED Requirements', '重命名要求']);
     const added = parseRequirementBlocksFromSection(addedLookup.body);
     const modified = parseRequirementBlocksFromSection(modifiedLookup.body);
     const removedNames = parseRemovedNames(removedLookup.body);
@@ -120,10 +123,10 @@ function splitTopLevelSections(content) {
     }
     return result;
 }
-function getSectionCaseInsensitive(sections, desired) {
-    const target = desired.toLowerCase();
+function getSectionByAliases(sections, aliases) {
+    const targets = new Set(aliases.map((alias) => alias.toLowerCase()));
     for (const [title, body] of Object.entries(sections)) {
-        if (title.toLowerCase() === target)
+        if (targets.has(title.toLowerCase()))
             return { body, found: true };
     }
     return { body: '', found: false };
@@ -136,7 +139,7 @@ function parseRequirementBlocksFromSection(sectionBody) {
     let i = 0;
     while (i < lines.length) {
         // Seek next requirement header
-        while (i < lines.length && !/^###\s+Requirement:/.test(lines[i]))
+        while (i < lines.length && !isRequirementHeader(lines[i]))
             i++;
         if (i >= lines.length)
             break;
@@ -149,7 +152,7 @@ function parseRequirementBlocksFromSection(sectionBody) {
         const name = normalizeRequirementName(m[1]);
         const buf = [headerLine];
         i++;
-        while (i < lines.length && !/^###\s+Requirement:/.test(lines[i]) && !/^##\s+/.test(lines[i])) {
+        while (i < lines.length && !isRequirementHeader(lines[i]) && !/^##\s+/.test(lines[i])) {
             buf.push(lines[i]);
             i++;
         }