kc-beta 0.6.0 → 0.6.2

package/src/agent/tools/workflow-run.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { BaseTool, ToolResult } from "./base.js";
+import { normalizeWorkflowResult } from "./_workflow-result-schema.js";
 
 /**
  * Execute a distilled workflow script against a document.
@@ -9,12 +10,33 @@ import { BaseTool, ToolResult } from "./base.js";
  * result and trace ID automatically. Saves structured result to output/results/.
  */
 export class WorkflowRunTool extends BaseTool {
-  constructor(workspace, versionManager, confidenceScorer, { timeout = 120 } = {}) {
+  /**
+   * @param {Workspace} workspace
+   * @param {VersionManager} versionManager
+   * @param {ConfidenceScorer} confidenceScorer
+   * @param {object} [opts]
+   * @param {number} [opts.timeout=120]
+   * @param {(phase: string, key: string, value: any) => boolean} [opts.recordMilestone]
+   *   v0.6.1 A6: callback for engine-emitted milestone updates. Called on
+   *   successful workflow execution so the distillation/production_qc gates
+   *   see real telemetry, not just filesystem scans of canonical paths.
+   * @param {() => string} [opts.getCurrentPhase]
+   *   v0.6.1 A6: returns the engine's current phase. Used to gate
+   *   production_qc-specific milestone bumps (documentsReviewed) so
+   *   distillation-phase calls don't accidentally credit QC.
+   */
+  constructor(workspace, versionManager, confidenceScorer, {
+    timeout = 120,
+    recordMilestone = null,
+    getCurrentPhase = null,
+  } = {}) {
     super();
     this._workspace = workspace;
     this._versionMgr = versionManager;
     this._confidence = confidenceScorer;
     this._timeout = timeout;
+    this._recordMilestone = recordMilestone;
+    this._getCurrentPhase = getCurrentPhase;
   }
 
   get name() { return "workflow_run"; }
@@ -68,14 +90,18 @@ export class WorkflowRunTool extends BaseTool {
       return new ToolResult(e.message, true);
     }
 
-    // Parse output
-    let resultData;
+    // Parse output (last stdout line as JSON)
+    let parsed;
     try {
       const lines = output.trim().split("\n");
-      resultData = JSON.parse(lines[lines.length - 1]);
+      parsed = JSON.parse(lines[lines.length - 1]);
     } catch {
-      resultData = { raw_output: output.slice(0, 5000) };
+      parsed = { raw_output: output.slice(0, 5000) };
     }
+    // v0.6.2 I1: normalize to canonical dict shape — strips Python
+    // dataclass repr() keys, classifies ERROR results, ensures rule_id
+    // and verdict are present.
+    const resultData = normalizeWorkflowResult(parsed, ruleId, output);
 
     // Attach confidence score
     const extractedValue = String(resultData.extracted_value || resultData.value || "");
@@ -97,6 +123,18 @@ export class WorkflowRunTool extends BaseTool {
     const resultFile = path.join(resultsDir, `${ruleId}_${path.parse(docResolved).name}.json`);
     fs.writeFileSync(resultFile, JSON.stringify(resultData, null, 2), "utf-8");
 
+    // v0.6.1 A6: emit milestone signals so phase gates see this run.
+    // Wrapped in try/catch so milestone emission can never break a workflow.
+    try {
+      this._recordMilestone?.("distillation", "workflowsTested",
+        { id: ruleId, value: { confidence, traceId: resultData.trace_id } });
+      this._recordMilestone?.("distillation", "workflowsPassing", ruleId);
+      const phase = this._getCurrentPhase?.();
+      if (phase === "production_qc") {
+        this._recordMilestone?.("production_qc", "documentsReviewed", 1);
+      }
+    } catch { /* never let milestone emission break workflow execution */ }
+
     return new ToolResult(JSON.stringify(resultData, null, 2));
   }
 

package/src/agent/workspace.js

@@ -240,6 +240,19 @@ export class Workspace {
     return traceId;
   }
 
+  /**
+   * v0.6.2 J3: Synchronous lock mirror of `withFileLock`, for callers
+   * that can't go async (SessionState.save). Locks a sibling
+   * `<relPath>.lock` file via O_CREAT|O_EXCL, with 5s timeout and 30s
+   * stale-takeover. On failure to acquire, runs fn anyway — better to
+   * lose serialization than deadlock a save call. Use sparingly; prefer
+   * `withFileLock` (async) for all paths that allow it.
+   */
+  withSyncFileLock(relPath, fn, { timeoutMs = 5_000, staleMs = 30_000 } = {}) {
+    const lockPath = path.join(this.path, `${relPath}.lock`);
+    return this._withSyncLockAtPath(lockPath, fn, { timeoutMs, staleMs });
+  }
+
   /**
    * B5: Synchronous gitops lock. Mirror of withFileLock but sync to fit
    * autoCommit's existing call signature. Times out and proceeds anyway
@@ -247,6 +260,16 @@ export class Workspace {
    */
   _withGitSyncLock(fn, { timeoutMs = 5_000, staleMs = 30_000 } = {}) {
     const lockPath = path.join(this.path, ".git", "kc-commit.lock");
+    return this._withSyncLockAtPath(lockPath, fn, { timeoutMs, staleMs });
+  }
+
+  /**
+   * Shared sync-lock implementation. Used by `_withGitSyncLock` (B5) and
+   * `withSyncFileLock` (J3 / v0.6.2). Same semantics: O_CREAT|O_EXCL on
+   * a sibling `.lock` file, busy-spin retry with stale takeover, run fn
+   * anyway on timeout.
+   */
+  _withSyncLockAtPath(lockPath, fn, { timeoutMs = 5_000, staleMs = 30_000 } = {}) {
     const start = Date.now();
     let acquired = false;
     while (Date.now() - start < timeoutMs) {

package/src/model-tiers.json

@@ -123,6 +123,38 @@
     }
   },
 
+  "deepseek": {
+    "_comment": "DeepSeek v4 family — flagship pro + cheap flash. Native 1M context but KC caps to 200K.",
+    "conductor": "deepseek-v4-pro",
+    "llm": {
+      "tier1": "deepseek-v4-pro",
+      "tier2": "deepseek-v4-pro",
+      "tier3": "deepseek-v4-flash",
+      "tier4": "deepseek-v4-flash"
+    },
+    "vlm": {
+      "tier1": "",
+      "tier2": "",
+      "tier3": ""
+    }
+  },
+
+  "xiaomi": {
+    "_comment": "Xiaomi MiMo coding plan — flagship Pro + standard + multimodal Omni. Native 1M context but KC caps to 200K. TTS variants excluded (no KC use case).",
+    "conductor": "MiMo-V2.5-Pro",
+    "llm": {
+      "tier1": "MiMo-V2.5-Pro",
+      "tier2": "MiMo-V2.5",
+      "tier3": "MiMo-V2-Pro",
+      "tier4": "MiMo-V2-Pro"
+    },
+    "vlm": {
+      "tier1": "MiMo-V2-Omni",
+      "tier2": "MiMo-V2-Omni",
+      "tier3": ""
+    }
+  },
+
   "openrouter": {
     "conductor": "anthropic/claude-sonnet-4-20250514",
     "llm": {

package/src/providers.js

@@ -211,6 +211,51 @@ const PROVIDERS = [
       zh: "MiniMax",
     },
   },
+  {
+    id: "deepseek",
+    name: "DeepSeek",
+    baseUrl: "https://api.deepseek.com",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: "/models",
+    contextLimit: 200000, // KC cap — DeepSeek v4 is native 1M; we cap to 200K
+    defaultModel: getTierConfig("deepseek").conductor || "deepseek-v4-pro",
+    defaultTiers: getTierConfig("deepseek").llm,
+    defaultVlm: getTierConfig("deepseek").vlm,
+    curatedModels: [
+      { id: "deepseek-v4-pro", ownedBy: "deepseek" },
+      { id: "deepseek-v4-flash", ownedBy: "deepseek" },
+    ],
+    labels: {
+      en: "DeepSeek (v4 family)",
+      zh: "DeepSeek（v4 系列）",
+    },
+  },
+  {
+    id: "xiaomi",
+    name: "Xiaomi MiMo",
+    baseUrl: "https://token-plan-cn.xiaomimimo.com/v1",
+    authType: "bearer",
+    apiFormat: "openai",
+    modelsEndpoint: null, // Xiaomi coding-plan endpoint, no /models — use curated list
+    supportsCodingPlanKey: true,
+    contextLimit: 200000, // KC cap — MiMo V2.5 is native 1M
+    defaultModel: getTierConfig("xiaomi").conductor || "MiMo-V2.5-Pro",
+    defaultTiers: getTierConfig("xiaomi").llm,
+    defaultVlm: getTierConfig("xiaomi").vlm,
+    curatedModels: [
+      { id: "MiMo-V2.5-Pro", ownedBy: "xiaomi" },
+      { id: "MiMo-V2.5", ownedBy: "xiaomi" },
+      { id: "MiMo-V2-Pro", ownedBy: "xiaomi" },
+      { id: "MiMo-V2-Omni", ownedBy: "xiaomi" }, // multimodal
+      // TTS variants (MiMo-V2.5-TTS, *-VoiceClone, *-VoiceDesign, MiMo-V2-TTS)
+      // intentionally excluded — KC has no TTS use case.
+    ],
+    labels: {
+      en: "Xiaomi MiMo (V2.5 family, coding plan)",
+      zh: "小米 MiMo（V2.5 系列，编程计划）",
+    },
+  },
   {
     id: "openrouter",
     name: "OpenRouter",

package/template/skills/en/meta-meta/skill-authoring/SKILL.md

@@ -27,6 +27,25 @@ rule-skills/
 
 Not every rule needs all of these. A simple threshold check might only need SKILL.md and a script. A complex semantic rule might need detailed references and many samples. Start minimal, add as needed during testing.
 
+## Granularity: 1 rule = 1 skill directory (default)
+
+Default to **one rule per skill directory**. Group rules into the same file ONLY when they meet BOTH:
+
+1. They share the same evidence (same section / same table / same field) — so locating one locates all.
+2. They fail together — when one fails, the others almost always fail too (e.g., siblings in a required-fields list where the table itself is missing).
+
+When grouping, name the file with the explicit range so downstream consumers (workflow-run, dashboards, finalization) can parse rule coverage by filename:
+- ✅ `check_r013_r017.py` (R013, R014, R015, R016, R017 — same disclosure table, fail together)
+- ❌ `check_r001_r050_r078.py` (different chapters, even if topically related — keep separate)
+
+### Anti-pattern: the unified runner
+
+If you find yourself writing a single `unified_qc.py` (or `batch_runner.py`, or `master_check.py`) that handles all 110 rules in one Python file, **stop**. That means your per-rule skills are wrong, not that the architecture is wrong. Fix the skills.
+
+E2E #4 demonstrated the cost: an agent wrote `unified_qc.py` to bypass 110 individual skills it didn't trust. Result was 1,150 errors out of 6,930 production checks (16.6%) and a phase counter stuck in `production_qc` while real work happened in skill_authoring. The unified runner felt productive locally and was a global mistake.
+
+If individual skills aren't running cleanly, the right response is to identify which ones break and fix them, not consolidate. The whole pipeline (extraction → skill_testing → distillation → production_qc) assumes one rule = one verifiable artifact.
+
 ## Writing SKILL.md
 
 ### Frontmatter

package/template/skills/zh/meta-meta/skill-authoring/SKILL.md

@@ -27,6 +27,25 @@ rule-skills/
 
 Not every rule needs all of these. A simple threshold check might only need SKILL.md and a script. A complex semantic rule might need detailed references and many samples. Start minimal, add as needed during testing.
 
+## 颗粒度：默认 1 条规则 = 1 个技能目录
+
+默认**每条规则一个独立技能目录**。仅当同时满足以下两个条件时，才能把多条规则合并到同一个文件：
+
+1. 共享同一证据（同一章节 / 同一表格 / 同一字段）——找到一条就找到了全部。
+2. 一同成败——一条失败，其他几乎必然失败（例如必填字段表中的同辈规则，表本身缺失则全部失败）。
+
+合并时，用显式范围命名文件，让下游消费者（workflow-run、dashboards、finalization）可以从文件名解析规则覆盖范围：
+- ✅ `check_r013_r017.py`（R013、R014、R015、R016、R017——同一披露表格，一同失败）
+- ❌ `check_r001_r050_r078.py`（不同章节，即使主题相关，也应分开）
+
+### 反模式：统一运行器（unified runner）
+
+如果你发现自己在写一个 `unified_qc.py`（或 `batch_runner.py`、`master_check.py`）把全部 110 条规则塞进一个 Python 文件里，**停下来**。这说明你的单条规则技能写错了，不是架构错了。请修复单条技能。
+
+E2E #4 给出了代价：智能体写了一个 `unified_qc.py` 绕过它不信任的 110 个独立技能。结果是 6,930 条生产检查里出了 1,150 个错误（16.6%），相位计数器卡在 `production_qc`，而真实工作还在 skill_authoring 里进行。统一运行器在局部看起来很高效，全局上是个错误。
+
+如果某些独立技能跑不通，正确的应对是定位并修复出问题的那几条，而不是合并所有技能。整个流水线（extraction → skill_testing → distillation → production_qc）的前提就是「一条规则 = 一个可独立验证的产物」。
+
 ## Writing SKILL.md
 
 ### Frontmatter