soloforge 1.2.17 → 1.2.19

package/dist/bin/soloforge.js

@@ -16,6 +16,7 @@ import { cmdConfigResolve, cmdConfigExplain, cmdConfigConfirm, cmdConfigUnset, l
 import { resolveCurrentProjectConfigReports, validateConfigPrecedence, } from "../engine/config_precedence_contract.js";
 import { isReadForbidden } from "../engine/privacy_secret_contract.js";
 import { routeIntent } from "../engine/intent_router.js";
+import { debugLog } from "../engine/debug_log.js";
 const command = process.argv[2];
 const args = process.argv.slice(3);
 async function main() {
@@ -115,7 +116,7 @@ async function main() {
   generate-claude-md  生成包含工作流规则的 CLAUDE.md
   generate-trae       生成 .trae/mcp.json 和 .trae/rules/project_rules.md
   generate-codex      生成 .codex/ 配置和 AGENTS.md
-  check-write         PreToolUse hook，用于范围检查（读取 TOOL_INPUT 环境变量）
+  check-write         PreToolUse hook，用于范围检查（读取 stdin JSON）
   post-bash           PostToolUse hook，用于跟踪 Bash 执行结果
   validate            验证项目配置和知识文件（config.yaml 可选，缺失时自动推断）
   validate-mechanisms 验证双层机制承载模型完整性（模板层 + 机制层）
@@ -147,12 +148,12 @@ async function cmdInitAuto() {
         const icon = field.confidence === "high" ? "✅" : field.confidence === "medium" ? "⚠️" : "❓";
         const valStr = typeof field.value === "object" ? JSON.stringify(field.value) : String(field.value);
         console.log(`  ${icon} ${key}: ${valStr} (${field.confidence}, ${field.confidence_source})`);
-        console.log(`     evidence: ${field.evidence.join(", ")}`);
+        console.log(`     证据: ${field.evidence.join(", ")}`);
     }
     console.log("=".repeat(50));
     console.log(`综合置信度: ${draft.confidence}`);
     if (draft.advisory_notes.length > 0) {
-        console.log("advisory:");
+        console.log("建议:");
         for (const note of draft.advisory_notes) {
             console.log(`  - ${note}`);
         }
@@ -160,13 +161,13 @@ async function cmdInitAuto() {
     // Schema 校验 (advisory)
     const validation = validateConfigDraft(draft);
     if (validation.warnings.length > 0) {
-        console.log("\nschema advisory:");
+        console.log("\nschema 建议:");
         for (const w of validation.warnings) {
             console.log(`  ⚠️ ${w}`);
         }
     }
     if (!validation.valid) {
-        console.log("\nschema errors:");
+        console.log("\nschema 错误:");
         for (const e of validation.errors) {
             console.log(`  ❌ ${e}`);
         }
@@ -224,9 +225,9 @@ function writeConfigWithEvidence(projectPath, draft, evidence) {
         scope: draft.scope,
     };
     fss.writeFileSync(configPath, YAML.stringify(yamlConfig), "utf-8");
-    // Write legacy evidence format (backward compat) + schema v2 entries
+    // 写入旧版 evidence 格式（向后兼容）+ schema v2 条目
     fss.writeFileSync(evidencePath, JSON.stringify(evidence, null, 2), "utf-8");
-    // Also write schema v2 entries
+    // 同时写入 schema v2 条目
     const v2Entries = Object.entries(evidence.fields).map(([key, field]) => ({
         field_path: key,
         value_hash: hashConfigValue(JSON.stringify(field.value)),
@@ -236,7 +237,7 @@ function writeConfigWithEvidence(projectPath, draft, evidence) {
         lifetime: "project_persistent",
         collected_at: evidence.generated_at || new Date().toISOString(),
     }));
-    // Merge v2 entries into the evidence file
+    // 合并 v2 条目到 evidence 文件
     try {
         const existing = JSON.parse(fss.readFileSync(evidencePath, "utf-8"));
         existing.entries = v2Entries;
@@ -274,7 +275,7 @@ async function cmdInitBlueprint() {
         console.log("支持的框架关键词: Spring Boot, Go, Rust, Gradle, React, Vue, Angular, Next.js, Nuxt");
         return;
     }
-    // Build draft from parsed blueprint
+    // 从解析的蓝图构建草稿
     const draft = {
         name: path.basename(projectPath),
         tech_stack: {
@@ -294,7 +295,7 @@ async function cmdInitBlueprint() {
         confidence: "high",
     };
     const evidence = generateBlueprintEvidence(blueprintText, draft, projectPath);
-    // Create dirs + write config + evidence
+    // 创建目录 + 写入配置 + evidence
     const dirs = [
         ".soloforge/state", ".soloforge/state/debt",
         ".soloforge/knowledge/patterns", ".soloforge/knowledge/patterns/core",
@@ -363,7 +364,7 @@ async function cmdInit() {
     if (interactive) {
         const config = await interactiveConfig(projectPath);
         if (config) {
-            // config is { draft, evidence }
+            // config 结构为 { draft, evidence }
             writeConfigWithEvidence(projectPath, config.draft, config.evidence);
         }
         else if (!process.stdin.isTTY) {
@@ -388,7 +389,7 @@ async function cmdInit() {
                 },
             };
             fss.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2), "utf-8");
-            console.log("✅ .mcp.json created (soloforge + playwright)");
+            console.log("✅ .mcp.json 已创建（soloforge + playwright）");
         }
         // 生成 hooks
         await cmdGenerateHooks(projectPath);
@@ -427,7 +428,7 @@ async function copyGlobalPatterns(projectPath) {
                 fss.copyFileSync(src, dest);
             }
         }
-        console.log(`✅ ${files.length} default patterns copied to ~/.soloforge/patterns/`);
+        console.log(`✅ ${files.length} 个默认模板已复制到 ~/.soloforge/patterns/`);
     }
 }
 async function copyKnowledgeTemplates(projectPath) {
@@ -452,7 +453,7 @@ async function copyKnowledgeTemplates(projectPath) {
             }
         }
         if (copiedCount > 0) {
-            console.log(`✅ ${copiedCount} knowledge templates copied to .soloforge/knowledge/`);
+            console.log(`✅ ${copiedCount} 个知识模板已复制到 .soloforge/knowledge/`);
         }
     }
 }
@@ -467,7 +468,7 @@ async function generateAdapterConfigs(projectPath, adapter) {
                 },
             };
             fss.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2), "utf-8");
-            console.log("✅ .mcp.json created (soloforge + playwright)");
+            console.log("✅ .mcp.json 已创建（soloforge + playwright）");
         }
         await cmdGenerateHooks(projectPath);
         await cmdGenerateClaudeMdInner(projectPath);
@@ -485,7 +486,7 @@ function ensureGitignore(projectPath) {
     if (missing.length > 0) {
         const addition = (content.endsWith("\n") ? "" : "\n") + missing.join("\n") + "\n";
         fss.appendFileSync(gitignorePath, addition, "utf-8");
-        console.log(`✅ .gitignore updated with: ${missing.join(", ")}`);
+        console.log(`✅ .gitignore 已更新: ${missing.join(", ")}`);
     }
 }
 async function cmdGenerateHooks(projectPath) {
@@ -506,7 +507,7 @@ async function cmdGenerateHooks(projectPath) {
     // 仅 merge hooks 字段，保留用户的 permissions/env 等设置
     existing.hooks = hooksConfig.hooks;
     fss.writeFileSync(settingsPath, JSON.stringify(existing, null, 2), "utf-8");
-    console.log("✅ .claude/settings.json updated with hooks");
+    console.log("✅ .claude/settings.json 已更新 hooks 配置");
 }
 async function cmdGenerateClaudeMd() {
     await cmdGenerateClaudeMdInner(process.cwd());
@@ -523,23 +524,23 @@ async function cmdGenerateCodexInner(projectPath) {
     fss.mkdirSync(codexDir, { recursive: true });
     const tomlContent = generateCodexMcpConfig(projectPath);
     fss.writeFileSync(path.join(codexDir, "config.toml"), tomlContent, "utf-8");
-    console.log("✅ .codex/config.toml created");
+    console.log("✅ .codex/config.toml 已创建");
     // 生成 .codex/hooks.json
     const hooksContent = generateCodexHooksConfig();
     fss.writeFileSync(path.join(codexDir, "hooks.json"), hooksContent, "utf-8");
-    console.log("✅ .codex/hooks.json created");
+    console.log("✅ .codex/hooks.json 已创建");
     // 生成 AGENTS.md
     const { config } = await resolveProjectConfig(projectPath);
     const agentsContent = generateCodexAgentsMd(config);
     fss.writeFileSync(path.join(projectPath, "AGENTS.md"), agentsContent, "utf-8");
-    console.log("✅ AGENTS.md created");
+    console.log("✅ AGENTS.md 已创建");
 }
 async function cmdGenerateTraeInner(projectPath) {
     // 生成 .trae/mcp.json
     const traeDir = path.join(projectPath, ".trae");
     fss.mkdirSync(traeDir, { recursive: true });
     const traeMcpPath = path.join(traeDir, "mcp.json");
-    const traeMcpConfig = generateTraeMcpConfig();
+    const traeMcpConfig = generateTraeMcpConfig(projectPath);
     fss.writeFileSync(traeMcpPath, JSON.stringify(traeMcpConfig, null, 2), "utf-8");
     console.log("✅ .trae/mcp.json created");
     // 生成 .trae/rules/project_rules.md
@@ -557,16 +558,11 @@ async function cmdGenerateClaudeMdInner(projectPath) {
     console.log("✅ CLAUDE.md created");
 }
 async function cmdCheckWrite() {
-    console.error("[soloForge] CLI: 执行 cmdCheckWrite");
+    debugLog("CLI: 执行 cmdCheckWrite");
     try {
-        // 检测运行环境: Claude Code 通过 TOOL_INPUT 环境变量，Codex 通过 stdin JSON
-        const isClaudeCode = !!process.env.TOOL_INPUT;
+        // 所有适配器均通过 stdin 读取 JSON（Claude Code / Codex 统一）
         let toolInput;
-        if (isClaudeCode) {
-            toolInput = process.env.TOOL_INPUT;
-        }
-        else {
-            // Codex: 从 stdin 读取 JSON
+        {
             const chunks = [];
             for await (const chunk of process.stdin) {
                 chunks.push(chunk);
@@ -585,13 +581,11 @@ async function cmdCheckWrite() {
         const parsed = JSON.parse(toolInput);
         let filePath;
         let content;
-        if (isClaudeCode) {
-            filePath = parsed.file_path || parsed.path || "";
-            content = parsed.content || parsed.new_string || "";
-        }
-        else {
-            // Codex stdin JSON 使用不同的字段名
-            const input = parsed.input || parsed;
+        {
+            // Claude Code: { tool_input: { file_path, content/new_string } } 格式
+            // Codex: { input: { file_path, content/new_string } } 格式
+            // 回退: 顶层 { file_path, content/new_string }
+            const input = parsed.tool_input || parsed.input || parsed;
             filePath = input.file_path || input.path || "";
             content = input.content || input.new_string || "";
         }
@@ -607,57 +601,36 @@ async function cmdCheckWrite() {
         // 使用 scope_controller 统一检查
         const { checkScope } = await import("../engine/scope_controller.js");
         const result = checkScope(filePath, allowedPaths, content || undefined);
-        // Privacy / Secret Contract: forbidden read patterns 
+        // 隐私/秘密契约：禁止读取的模式 
         if (isReadForbidden(filePath)) {
-            if (isClaudeCode) {
-                console.error(JSON.stringify({
-                    allowed: false,
-                    reason: `隐私策略: ${filePath} 匹配禁止读取模式`,
-                    has_secrets: true,
-                    severity: "blocked",
-                }));
-                process.exit(1);
-            }
-            else {
-                process.stdout.write(JSON.stringify({
-                    hookSpecificOutput: {
-                        hookEventName: "PreToolUse",
-                        permissionDecision: "deny",
-                        permissionDecisionReason: `隐私策略: ${filePath} 匹配禁止读取模式`,
-                    },
-                }));
-                process.exit(0);
-            }
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: `隐私策略: ${filePath} 匹配禁止读取模式`,
+                },
+            }));
+            process.exit(0);
         }
         if (result.severity === "blocked") {
-            if (isClaudeCode) {
-                console.error(JSON.stringify(result));
-                process.exit(1);
-            }
-            else {
-                // Codex: stdout 输出特定 JSON 拒绝格式
-                const denyOutput = {
-                    hookSpecificOutput: {
-                        hookEventName: "PreToolUse",
-                        permissionDecision: "deny",
-                        permissionDecisionReason: result.reason || "Write blocked by scope check",
-                    },
-                };
-                process.stdout.write(JSON.stringify(denyOutput));
-                process.exit(0);
-            }
+            const denyOutput = {
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: result.reason || "范围检查阻止了写入",
+                },
+            };
+            process.stdout.write(JSON.stringify(denyOutput));
+            process.exit(0);
         }
         if (result.severity === "warning") {
-            if (isClaudeCode) {
-                console.error(JSON.stringify(result));
-            }
-            // 警告不阻止操作
+            console.error(JSON.stringify(result));
         }
         process.exit(0); // 允许
     }
     catch (e) {
-        console.error(`SoloForge check-write error: ${e instanceof Error ? e.message : String(e)}`);
-        process.exit(1); // 出错时拦截（fail-closed 策略：安全钩子宁可误拦也不放行）
+        console.error(`SoloForge 写入检查错误: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
     }
 }
 function resolveProjectPath() {
@@ -679,16 +652,16 @@ function resolveProjectPath() {
     return process.cwd();
 }
 async function cmdPostBash() {
-    console.error("[soloForge] CLI: 执行 cmdPostBash");
+    debugLog("CLI: 执行 cmdPostBash");
     // Bash 的 PostToolUse hook — 目前为空操作占位符
     // 未来: 跟踪命令结果，检测构建/测试失败
     process.exit(0);
 }
 export { buildHookAdditionalContext } from "../adapters/claude_code/pre_prompt_contract.js";
 async function cmdPrePrompt() {
-    console.error("[soloForge] CLI: 执行 cmdPrePrompt");
+    debugLog("CLI: 执行 cmdPrePrompt");
     try {
-        // UserPromptSubmit hook receives JSON on stdin with { prompt: "..." }
+        // UserPromptSubmit hook 从 stdin 接收 JSON { prompt: "..." }
         const chunks = [];
         for await (const chunk of process.stdin) {
             chunks.push(chunk);
@@ -710,21 +683,23 @@ async function cmdPrePrompt() {
             process.exit(0);
             return;
         }
-        // Use intent router to classify — if route is SoloForge-worthy, inject structured context
+        // 使用意图路由器分类 — 如果路由属于 SoloForge 范畴，注入结构化上下文
         const decision = routeIntent({ intent: userMessage });
         const additionalContext = buildHookAdditionalContext(decision);
         if (additionalContext) {
             const output = {
                 hookSpecificOutput: {
                     hookEventName: "UserPromptSubmit",
-                    additionalContext,
+                    additionalContext: typeof additionalContext === "string"
+                        ? additionalContext
+                        : JSON.stringify(additionalContext),
                 },
             };
             process.stdout.write(JSON.stringify(output));
         }
     }
     catch (e) {
-        console.error("[soloForge] pre-prompt hook error:", e);
+        console.error("[soloForge] pre-prompt hook 错误:", e);
     }
     process.exit(0);
 }
@@ -736,19 +711,19 @@ async function checkEvidenceWarnings(projectPath) {
     if (!fss.existsSync(configPath))
         return warnings;
     if (!fss.existsSync(evidencePath)) {
-        warnings.push("config.yaml exists but config.evidence.json is missing — source traceability lost");
+        warnings.push("config.yaml 存在但 config.evidence.json 缺失 — 来源追溯性丢失");
         return warnings;
     }
-    // Check mtime staleness
+    // 检查 mtime 过期
     try {
         const configStat = fss.statSync(configPath);
         const evidenceStat = fss.statSync(evidencePath);
         if (configStat.mtimeMs > evidenceStat.mtimeMs) {
-            warnings.push("config.evidence.json is stale (config.yaml was modified after evidence was generated)");
+            warnings.push("config.evidence.json 已过期（config.yaml 在 evidence 生成后被修改）");
         }
     }
     catch { }
-    // Legacy field consistency check (schema v1 evidence)
+    // 旧版字段一致性检查（schema v1 evidence）
     try {
         const evidenceRaw = JSON.parse(fss.readFileSync(evidencePath, "utf-8"));
         const configContent = fss.readFileSync(configPath, "utf-8");
@@ -756,23 +731,23 @@ async function checkEvidenceWarnings(projectPath) {
         for (const [key, field] of Object.entries(evidenceRaw.fields)) {
             const actualValue = getConfigFieldValue(config, key);
             if (actualValue !== undefined && JSON.stringify(field.value) !== JSON.stringify(actualValue)) {
-                warnings.push(`evidence field '${key}' value does not match config.yaml`);
+                warnings.push(`evidence 字段 '${key}' 的值与 config.yaml 不匹配`);
             }
         }
     }
     catch { }
-    // Config precedence validation using schema v2 entries
+    // 使用 schema v2 条目验证配置优先级
     try {
         const entries = loadConfigEvidenceEntries(projectPath);
-        // Check C-class auto-write violations
+        // 检查 C 类字段自动写入违规
         for (const e of entries) {
             if (e.source === "cli_flag" || e.source === "mcp_param") {
                 if (e.lifetime === "project_persistent") {
-                    warnings.push(`CLI/MCP parameter (${e.source}) persisted to config — field: ${e.field_path}`);
+                    warnings.push(`CLI/MCP 参数（${e.source}）已持久化到 config — 字段: ${e.field_path}`);
                 }
             }
         }
-        // Run config precedence validation with live resolution
+        // 运行实时解析的配置优先级验证
         try {
             const { reports } = await resolveCurrentProjectConfigReports(projectPath);
             const findings = validateConfigPrecedence(reports, entries);
@@ -803,13 +778,13 @@ async function cmdValidate() {
     try {
         const { config, source } = await resolveProjectConfig(projectPath);
         if (source === "inferred") {
-            console.log("ℹ️  No .soloforge/config.yaml found — using auto-inferred configuration.");
-            console.log("   Run 'soloforge init --auto' to persist.");
+            console.log("ℹ️  未找到 .soloforge/config.yaml — 使用自动推断的配置。");
+            console.log("   运行 'soloforge init --auto' 可持久化。");
         }
         else {
-            console.log("✅ config.yaml is valid");
+            console.log("✅ config.yaml 有效");
         }
-        // Config precedence validation using shared function
+        // 使用共享函数验证配置优先级
         let hasHardFail = false;
         try {
             const { reports, entries } = await resolveCurrentProjectConfigReports(projectPath);
@@ -834,7 +809,7 @@ async function cmdValidate() {
             }
         }
         catch { }
-        // Evidence checks
+        // Evidence 检查
         const evidenceWarnings = await checkEvidenceWarnings(projectPath);
         for (const w of evidenceWarnings) {
             console.log(`⚠️  evidence: ${w}`);
@@ -846,10 +821,10 @@ async function cmdValidate() {
             const index = new KnowledgeIndexManager(config);
             await index.build();
             const entries = index.getAllEntries();
-            console.log(`✅ ${entries.project.length} project knowledge entries indexed`);
+            console.log(`✅ ${entries.project.length} 条项目知识已索引`);
             const issues = await index.checkHealth();
             if (issues.length > 0) {
-                console.log(`⚠️  ${issues.length} health issues found:`);
+                console.log(`⚠️  ${issues.length} 个健康问题:`);
                 for (const { entry, issue } of issues) {
                     console.log(`  - ${entry.name}: ${issue}`);
                 }
@@ -872,7 +847,7 @@ async function cmdValidate() {
             else {
                 console.log(`✅ 双层机制验证: ${dlAdvisory.length} advisory, 0 hard_fail`);
             }
-        } // end dual-layer check
+        } // 双层机制检查结束
         if (hasHardFail) {
             console.error("❌ validate 失败: 配置优先级存在 hard_fail");
             process.exit(1);
@@ -885,7 +860,7 @@ async function cmdValidate() {
 }
 async function cmdValidateMechanisms() {
     console.error("[soloForge] CLI: 执行 cmdValidateMechanisms");
-    // Resolve root from compiled binary location: dist/bin/soloforge.js -> project root
+    // 从编译后的二进制位置推导根目录: dist/bin/soloforge.js -> 项目根
     const soloforgeRoot = path.resolve(import.meta.dirname, "..", "..");
     const projectPath = fss.existsSync(path.join(soloforgeRoot, "src", "engine"))
         ? soloforgeRoot
@@ -915,7 +890,7 @@ async function cmdValidateMechanisms() {
             process.exit(1);
         }
         console.log(`\n✅ 双层机制验证通过，${advisory.length} advisory findings`);
-        // Audit summary
+        // 审计摘要
         try {
             const { auditTemplateMechanisms } = await import("../engine/template_mechanism_auditor.js");
             const audit = auditTemplateMechanisms(projectPath);
@@ -927,7 +902,7 @@ async function cmdValidateMechanisms() {
             }
         }
         catch {
-            // audit is advisory, not blocking
+            // 审计仅为建议，不阻断
         }
     }
     catch (e) {
@@ -939,7 +914,7 @@ async function cmdAuditTemplateMechanisms() {
     console.error("[soloForge] CLI: 执行 cmdAuditTemplateMechanisms");
     const asJson = args.includes("--json");
     const changedOnly = args.includes("--changed-only");
-    // Resolve root from compiled binary location
+    // 从编译后的二进制位置推导根目录
     const soloforgeRoot = path.resolve(import.meta.dirname, "..", "..");
     const projectPath = fss.existsSync(path.join(soloforgeRoot, "src", "engine"))
         ? soloforgeRoot
@@ -954,7 +929,7 @@ async function cmdAuditTemplateMechanisms() {
             }
             return;
         }
-        // Human-readable output
+        // 人类可读输出
         console.log(`模板-机制审计报告 (${report.generated_at})`);
         console.log(`  模板文件: ${report.total_template_files}`);
         console.log(`  注册资产: ${report.total_registered_assets}`);
@@ -1067,7 +1042,7 @@ async function cmdValidateBatch1() {
                 console.log(`${ri} ${r.rule}: ${r.evidence}`);
             }
         }
-        console.log(allPass ? "\nAll scenarios PASS" : "\nSome scenarios FAIL");
+        console.log(allPass ? "\n所有场景通过" : "\n部分场景失败");
     }
     process.exit(allPass ? 0 : 1);
 }
@@ -1080,7 +1055,7 @@ async function cmdStatus() {
     console.log(`  产品: ${config.product_profile}`);
     console.log(`  后端: ${config.tech_stack.backend.framework || "未配置"}`);
     console.log(`  前端: ${config.tech_stack.frontend.framework || "未配置"}`);
-    // Per-field config precedence status
+    // 逐字段配置优先级状态
     try {
         const { resolutions, entries } = await resolveCurrentProjectConfigReports(projectPath);
         if (resolutions.length > 0) {
@@ -1096,7 +1071,7 @@ async function cmdStatus() {
         if (fss.existsSync(schemaPath)) {
             try {
                 const raw = JSON.parse(fss.readFileSync(schemaPath, "utf-8"));
-                console.log(`  evidence: schema_version=${raw.schema_version ?? 1}, ${entries.length} entries`);
+                console.log(`  evidence: schema_version=${raw.schema_version ?? 1}, ${entries.length} 条`);
             }
             catch {
                 console.log("  evidence: 无法解析");
@@ -1107,7 +1082,7 @@ async function cmdStatus() {
         }
     }
     catch { }
-    // Evidence warnings
+    // Evidence 警告
     const evidenceWarnings = await checkEvidenceWarnings(projectPath);
     for (const w of evidenceWarnings) {
         console.log(`  ⚠️  evidence: ${w}`);