mingdao-harness 0.4.6 → 0.5.0

package/src/agent.js

@@ -14,8 +14,11 @@ import { subagentModel } from './routing.js';
 import { writeAudit } from './audit.js';
 import { redactSecrets } from './redact.js';
 import { checkCostGuard, costGuardConfig, todayCost } from './cost-guard.js';
+import { recordCacheStats, packDailyCost } from './cachestats.js';
 import { estimateCost } from './pricing.js';
-import { resolveProviderConfig } from './providers/index.js';
+import { resolveProviderConfig, createProvider } from './providers/index.js';
+import { compileConstraints, checkPreTool, checkPostTool, checkOutput, blockedOutputText } from './constraints.js';
+import { getActivePackContext } from './packs.js';
 
 const MAX_STEPS = 24;
 // 子代理步数上限：审计/精读类只读子任务需要读多个文件 + 交叉引用，12 步易在「读不全」时被截断
@@ -32,9 +35,10 @@ export const READONLY_TIER_SET = new Set(['read', 'ls', 'glob', 'grep', 'skill',
  * 创建 Agent 循环（调用方只需传 provider/permission/io/modelName/workingDir，其余可选）
  * @param {{ provider: any, permission: any, io: any, modelName: any, workingDir: any,
  *   cfg?: any, undoStore?: any, maxSteps?: number, mcp?: any, onCompact?: any, sessionRef?: any,
- *   onUsage?: (modelName: string, usage: any) => void }} params
+ *   onUsage?: (modelName: string, usage: any) => void,
+ *   constraints?: any[] }} params
  */
-export function createAgent({ provider, permission, io, modelName, workingDir, cfg = {}, undoStore, maxSteps, mcp, onCompact, sessionRef, onUsage }) {
+export function createAgent({ provider, permission, io, modelName, workingDir, cfg = {}, undoStore, maxSteps, mcp, onCompact, sessionRef, onUsage, constraints: rawConstraints }) {
   const preset = modelPreset(modelName) || {};
   // v0.3.2 模型自适应：预算按模型上下文窗口推导（留输出余量 + 75% 舒适区），
   // 自定义/本地小模型不再套 128000 默认撑爆窗口；prompt 永不逼近窗口边缘（prefill 不爆炸）。
@@ -58,12 +62,30 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   const temperature = cfg.temperature ?? preset.temperature ?? 0.6;
   const reasoningEffort = cfg.reasoningByModel?.[modelName] ?? cfg.reasoningEffort ?? preset.reasoningEffort?.default ?? undefined;
   const hooks = createHooks(cfg.hooks, workingDir, cfg);
+  // v0.5.0 阶段 A3：领域约束（Pack API v1 的「领域红线」）——在三个时机强制：
+  // PreToolUse（工具/参数）、PostToolUse（工具结果缺项）、输出前（正文禁用措辞）。
+  // 约束**只收紧不放松**权限；未传约束时 compiled.active=false，所有检查点完全惰性，
+  // 对既有行为零影响（这是接入主循环时最重要的不变量）。
+  // 显式传入优先；否则取进程级已挂载的 Pack 约束；都没有 → 空集合（惰性）
+  const constraints = compileConstraints(
+    Array.isArray(rawConstraints) ? rawConstraints : cfg?.constraints ?? getActivePackContext()?.constraints
+  );
+  /** 约束事件写审计（pack/constraint/kind/stage/action）——受监管场景要能回答「红线何时被触发」 */
+  const auditConstraint = (/** @type {any} */ ev) => {
+    if (cfg.audit === false || !ev) return;
+    try {
+      writeAudit({ at: Date.now(), session: sessionRef?.name ?? null, model: modelName, tool: null, constraint: ev });
+    } catch {}
+  };
   const todos = /** @type {any[]} */ ([]);
   // v0.4.6 修复：当前 runTurn 的 usage 累加器引用——spawnTask 定义在 runTurn 之外，
   // 此前子代理的 token 消耗只用于生成汇报文本、从不并入父回合 usage，导致「今日费用」系统性少计
   // （CLI/REPL 每次派子代理都漏计；README 主推的「多方向并行调研」场景漏计最重）。
   // runTurn 开始时指向本轮 usage，finally 清空；runTurn 之外调用 spawnTask 时为 null（安全跳过）。
   let currentUsage = /** @type {any} */ (null);
+  // v0.5.0 A4：当前正在执行的 Pack 工具所属 Pack（由 runTool 按 `pack__<pack>__` 前缀设置），
+  // 供 ctx.llm 写归因记录时标注来源。
+  let currentPack = /** @type {any} */ (null);
   // 会话级共享：调用方传入则复用（/model 切换、子代理均共享，undo 不丢失）
   const undo = undoStore || { backups: new Map() };
   const stepLimit = maxSteps || MAX_STEPS;
@@ -168,6 +190,101 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     return text;
   }
 
+  /**
+   * v0.5.0 A4：Pack 统一模型出口 `ctx.llm()`（Pack API §5）。
+   *
+   * 为什么必须有它：垂域层此前把模型调用写在 Provider 的 chat() 里（Deyi 的 dify.mjs 就是如此），
+   * usage 硬编码为 0 —— 域内调用**完全不计费、不触发日费用护栏、无法归因**。
+   * 走这里则：复用内核的 Provider 解析/重试/超时/能力表；usage 并入当前回合累加器 →
+   * 今日费用、缓存命中率、峰谷判断、日费用护栏在途估算**同时生效**。
+   * @param {any} opts
+   */
+  async function packLlm(/** @type {any} */ opts = {}) {
+    const usedModel = String(opts.model || modelName);
+    const system = String(opts.system || '');
+    const user = String(opts.user ?? opts.prompt ?? '');
+    if (!user) throw new Error('ctx.llm 需要 user（或 prompt）参数');
+    // v0.5.0 A4.5：Pack 级预算前置检查（与日费用护栏同语义，粒度到 Pack）。
+    // 预算在 pack.json 的 budget 声明；超限按 action 处理（block 抛错 / warn 放行并提示）。
+    const packBudget = getActivePackContext()?.mounted?.find((/** @type {any} */ x) => x.name === currentPack)?.budget;
+    if (packBudget && Number(packBudget.dailyYuan) > 0) {
+      const spent = packDailyCost(currentPack);
+      if (spent >= Number(packBudget.dailyYuan)) {
+        const msg = `垂域 Pack「${currentPack}」今日费用 ≈¥${spent.toFixed(5)} 已达上限 ¥${Number(packBudget.dailyYuan).toFixed(2)}`;
+        if (String(packBudget.action || 'block') === 'block') throw new Error(`${msg}（budget.action=block，已阻止本次模型调用）`);
+        try { io.print(style(`⚠ ${msg}（budget.action=warn，本次放行）`, C.yellow)); } catch {}
+      }
+    }
+    const messages = [...(system ? [{ role: 'system', content: system }] : []), { role: 'user', content: user }];
+    let prov = provider;
+    if (usedModel !== modelName) {
+      const pc = resolveProviderConfig(cfg, usedModel);
+      if (!pc || !pc.apiKey) throw new Error(`ctx.llm：模型 ${usedModel} 未配置 API Key`);
+      prov = await createProvider(cfg, usedModel);
+    }
+    const subCaps = resolveModelCaps(cfg, usedModel);
+    const maxTokens = Math.min(
+      Number(opts.maxTokens) > 0 ? Number(opts.maxTokens) : 2048,
+      subCaps.maxOutputCeiling || subCaps.maxOutputTokens
+    );
+    const t0 = Date.now();
+    const res = await prov.chat({
+      model: usedModel,
+      messages,
+      tools: [],
+      temperature: opts.temperature ?? temperature,
+      maxTokens,
+      ...(opts.reasoningEffort ? { reasoningEffort: opts.reasoningEffort } : {}),
+      ...(opts.json ? { responseFormat: { type: 'json_object' } } : {}),
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    // 并入当前回合 usage（与子代理同一机制）：CLI 直接按 res.usage 入账，
+    // WebUI 的 remaining 补记与护栏在途估算随之变准。
+    if (currentUsage && res?.usage) {
+      const u = res.usage;
+      currentUsage.prompt_tokens += u.prompt_tokens || 0;
+      currentUsage.completion_tokens += u.completion_tokens || 0;
+      if (Number.isFinite(u.prompt_cache_hit_tokens)) {
+        currentUsage.prompt_cache_hit_tokens = (currentUsage.prompt_cache_hit_tokens || 0) + u.prompt_cache_hit_tokens;
+      }
+      if (Number.isFinite(u.prompt_cache_miss_tokens)) {
+        currentUsage.prompt_cache_miss_tokens = (currentUsage.prompt_cache_miss_tokens || 0) + u.prompt_cache_miss_tokens;
+      }
+    }
+    // v0.5.0 A4：写一条 **Pack 归因标记记录**（cost=null，不计入 todayCost → 与回合级记录不重复计费；
+    // packCost 仅供 `mingdao cost report --by pack` 展示）。这样垂域团队能看到「自己的红线/工具花了多少」。
+    try {
+      const u = res?.usage || {};
+      const pack = currentPack || opts.pack || null;
+      const pCost = estimateCost(usedModel, u.prompt_tokens || 0, u.completion_tokens || 0, null);
+      recordCacheStats({
+        model: usedModel,
+        prompt: u.prompt_tokens || 0,
+        completion: u.completion_tokens || 0,
+        hit: null,
+        miss: null,
+        cost: null,
+        saved: null,
+        pack,
+        purpose: opts.purpose || null,
+        packCost: pCost,
+      });
+    } catch {}
+
+    const text = String(res?.text || '');
+    let data = null;
+    if (opts.json) {
+      const a = text.indexOf('{');
+      const b = text.lastIndexOf('}');
+      if (a >= 0 && b > a) {
+        try {
+          data = JSON.parse(text.slice(a, b + 1));
+        } catch {}
+      }
+    }
+    return { text, data, usage: res?.usage || null, model: usedModel, purpose: opts.purpose || null, durationMs: Date.now() - t0 };
+  }
+
   function makeCtx() {
     return {
       cwd: workingDir,
@@ -181,6 +298,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       todos,
       undoStore: undo,
       spawnTask: (/** @type {any} */ prompt, /** @type {any} */ opts) => spawnTask(prompt, opts),
+      // v0.5.0 A4：Pack 内所有模型调用必须走这里（禁止自己 fetch 模型接口）——
+      // 否则费用隐身、护栏失效、无法归因。详见 PACK-API §5。
+      llm: (/** @type {any} */ opts) => packLlm(opts),
     };
   }
 
@@ -251,7 +371,69 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     // 整个回合注册一次 SIGINT：思考、工具执行、权限询问期间都能中断
     const offSigint = io.onSigint ? io.onSigint(() => { aborted = true; currentAc?.abort(); }) : () => {};
     const ctx = makeCtx();
-    const stripOrphanCalls = () => {
+    /**
+   * v0.5.0 A3 ③：输出前领域约束（正文禁用措辞）。
+   * 无约束时零开销（constraints.active=false 直接返回原文）；有约束时按 action 处理：
+   *   warn → 放行并附提示；block → 替换为合规说明；block-and-rewrite → 请求一次改写，仍命中则拦截。
+   * 改写请求计入本回合 usage（费用归属当前模型），并写约束审计事件。
+   */
+  const applyOutputConstraints = async (/** @type {any} */ text, /** @type {any} */ ctxRun) => {
+    if (!constraints.active || !text) return { text, note: null };
+    const hit = checkOutput(constraints, text);
+    if (!hit) return { text, note: null };
+    auditConstraint(hit.event);
+    const cid = hit.constraint?.id || '领域红线';
+    if (hit.action === 'warn') {
+      try { io.print(style(`⚠ 领域约束「${cid}」提示：${hit.reason}`, C.yellow)); } catch {}
+      return { text, note: `⚠ 领域约束「${cid}」：${hit.reason}（已放行，请自行复核）` };
+    }
+    if (hit.action === 'block-and-rewrite') {
+      try {
+        io.print(style(`⛔ 领域约束「${cid}」命中，正在自动改写…`, C.yellow));
+        const sys = ctxRun.messages.find((/** @type {any} */ m) => m.role === 'system');
+        const fix = await ctxRun.provider.chat({
+          model: ctxRun.activeModel,
+          messages: [
+            ...(sys ? [sys] : []),
+            {
+              role: 'user',
+              content: `下面这段回复命中了领域红线（${hit.reason}）。请在不改变事实内容的前提下改写成**不含该措辞**的表述，只输出改写后的正文：\n\n${text}`,
+            },
+          ],
+          tools: [],
+          temperature: ctxRun.temperature,
+          maxTokens: Math.min(ctxRun.maxOutput, 2048),
+          signal: ctxRun.signal,
+        });
+        if (fix?.usage) {
+          ctxRun.usage.prompt_tokens += fix.usage.prompt_tokens || 0;
+          ctxRun.usage.completion_tokens += fix.usage.completion_tokens || 0;
+        }
+        const fixed = String(fix?.text || '').trim();
+        if (fixed) {
+          const re = checkOutput(constraints, fixed);
+          if (!re) return { text: fixed, note: `⛔ 领域约束「${cid}」命中，已自动改写` };
+          auditConstraint(re.event);
+          return { text: blockedOutputText(re), note: `⛔ 领域约束「${re.constraint?.id || cid}」改写后仍命中，已拦截` };
+        }
+      } catch {
+        // 改写失败：回落到拦截（fail-closed）
+      }
+      return { text: blockedOutputText(hit), note: `⛔ 领域约束「${cid}」命中，已拦截` };
+    }
+    return { text: blockedOutputText(hit), note: `⛔ 领域约束「${cid}」命中，已拦截` };
+  };
+
+  /** 安全解析工具结果字符串（约束引擎需要结构化对象） */
+  const safeParse = (/** @type {any} */ v) => {
+    if (typeof v !== 'string') return v;
+    try {
+      return JSON.parse(v);
+    } catch {
+      return null;
+    }
+  };
+  const stripOrphanCalls = () => {
       const last = messages[messages.length - 1];
       if (last?.role === 'assistant' && Array.isArray(last.tool_calls) && last.tool_calls.length) {
         messages[messages.length - 1] = { ...last, tool_calls: undefined };
@@ -515,8 +697,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         if (steps === stepLimit) {
           io.endTurn();
           if (res.text) {
-            messages.push({ role: 'assistant', content: res.text });
-            return { text: res.text, reasoning: res.reasoning || '', usage, steps, finish, truncated: false, aborted: false, durationMs: Date.now() - startedAt, perf: perf() };
+            const ap = await applyOutputConstraints(res.text, { messages, provider, activeModel, temperature, maxOutput, usage, signal: currentAc?.signal });
+            messages.push({ role: 'assistant', content: ap.text });
+            return { text: ap.text, reasoning: res.reasoning || '', usage, steps, finish, truncated: false, aborted: false, note: ap.note || undefined, durationMs: Date.now() - startedAt, perf: perf() };
           }
           break;
         }
@@ -610,6 +793,16 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             messages.push({ role: 'tool', tool_call_id: tc.id, content: '用户拒绝了该工具的执行权限。' });
             return null;
           }
+          // v0.5.0 A3 ①：领域约束（PreToolUse）——权限放行之后、执行之前强制。
+          // 与权限引擎的分工：权限回答「用户是否允许」，约束回答「领域是否允许」；两者都通过才执行。
+          const cv = checkPreTool(constraints, name, args);
+          if (cv?.blocked) {
+            io.renderToolDenied(name, args, cv.reason);
+            if (auditOn) auditEntry({ denied: true, reason: cv.reason });
+            auditConstraint(cv.event);
+            messages.push({ role: 'tool', tool_call_id: tc.id, content: `【领域约束】${cv.reason}` });
+            return null;
+          }
           return { tc, name, args, isMcp };
         }
 
@@ -618,6 +811,10 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         // 后续相同调用直接复用结果（仍逐个回填 tool 消息以保持 tool_call_id 配对）
         async function runTool(/** @type {any} */ prep) {
           io.renderToolStart?.(prep.name, prep.args);
+          // Pack 工具名形如 pack__<pack>__<tool>；执行期间标注来源，供 ctx.llm 归因
+          const pkMatch = /^pack__([a-z0-9-]+)__/.exec(String(prep.name || ''));
+          const prevPack = currentPack;
+          currentPack = pkMatch ? pkMatch[1] : null;
           usedToolNames.add(prep.name); // 省钱 B1：执行过即标记，后续轮次省略其 description
           const dedupKey = !prep.isMcp && READONLY_TOOLS_SET.has(prep.name) ? prep.name + ':' + JSON.stringify(prep.args || {}) : null;
           if (dedupKey && turnToolCache.has(dedupKey)) {
@@ -639,6 +836,8 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             // 失败也可能已产生副作用（半写入/部分执行）→ 同样作废缓存
             invalidateReadCache(prep);
             return JSON.stringify({ ok: false, error: String(err?.message || err) });
+          } finally {
+            currentPack = prevPack; // 还原（并行只读批次下 finally 保证不乱序）
           }
         }
 
@@ -683,8 +882,15 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
               outputBytes: Buffer.byteLength(typeof result === 'string' ? result : JSON.stringify(result ?? {}), 'utf8'),
             });
           }
-          const text = typeof result === 'string' ? result : JSON.stringify(result); // 紧凑 JSON（评估 B3）：嵌套结果省 10-20% 回填 token，且下轮按 prompt 重复计费
+          let text = typeof result === 'string' ? result : JSON.stringify(result); // 紧凑 JSON（评估 B3）：嵌套结果省 10-20% 回填 token，且下轮按 prompt 重复计费
           const prefix = prep.cached ? '（与同回合相同调用结果一致，已复用）\n' : '';
+          // v0.5.0 A3 ②：领域约束（PostToolUse）——completeness 缺项时**拒绝该工具结果**，
+          // 让模型必须继续采集而不是把「未提及」当作已完成（「缺项绝不编造」从提示词升级为内核强制）。
+          const pv = checkPostTool(constraints, prep.name, typeof result === 'string' ? safeParse(result) : result);
+          if (pv?.rejected) {
+            auditConstraint(pv.event);
+            text = `【领域约束】${pv.reason}`;
+          }
           messages.push({ role: 'tool', tool_call_id: prep.tc.id, content: prefix + clampText(text, toolResultCap) });
         }
 
@@ -749,8 +955,15 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         io.endTurn();
         // 最终纯文本回复回填消息历史（会话持久化与多轮上下文依赖它）；
         // 空文本不回填，避免个别 API 对 assistant 空 content 报错
+        let outputNote = /** @type {any} */ (null);
+        let finalText = res.text || '';
         if (res.text) {
-          messages.push({ role: 'assistant', content: res.text });
+          // v0.5.0 A3 ③：输出前领域约束必须在**回填历史之前**应用——
+          // 否则被拦下的违规措辞会留在会话里，下一轮又被当作既成事实喂回模型。
+          const ap = await applyOutputConstraints(res.text, { messages, provider, activeModel, temperature, maxOutput, usage, signal: currentAc?.signal });
+          finalText = ap.text;
+          outputNote = ap.note;
+          messages.push({ role: 'assistant', content: finalText });
         }
         // 输出被长度上限截断（DeepSeek 推理吃满 maxOutput 时正文为空）：让模型从断点续写，绝不静默结束。
         // 空轮护栏（评估 4.2-2）：每轮空输出都是全额 completion 计费（pro 32k 闲时 ≈ ¥0.43/轮），
@@ -803,13 +1016,14 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           continue;
         }
         return {
-          text: res.text || '',
+          text: finalText,
           reasoning: res.reasoning || '',
           usage,
           steps,
           finish,
           truncated: false,
           aborted: false,
+          note: outputNote || undefined,
           durationMs: Date.now() - startedAt,
           perf: perf(),
         };
@@ -877,9 +1091,13 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           usage.prompt_tokens += wrapRes.usage.prompt_tokens || 0;
           usage.completion_tokens += wrapRes.usage.completion_tokens || 0;
         }
-        if (wrapRes.text) messages.push({ role: 'assistant', content: wrapRes.text });
+        // v0.5.0 A3 ③：兜底总结同样过一遍输出约束
+        const wrapApplied = wrapRes.text
+          ? await applyOutputConstraints(wrapRes.text, { messages, provider, activeModel, temperature, maxOutput, usage, signal: currentAc?.signal })
+          : { text: null, note: null };
+        if (wrapApplied.text) messages.push({ role: 'assistant', content: wrapApplied.text });
         // capHit：本轮因步数上限被迫收尾（任务可能未真正完成）→ 供上层落检查点续跑
-        return { text: wrapRes.text || null, reasoning: wrapRes.reasoning || '', usage, steps, finish, truncated: false, aborted: false, capHit: true, durationMs: Date.now() - startedAt, perf: perf() };
+        return { text: wrapApplied.text || null, reasoning: wrapRes.reasoning || '', usage, steps, finish, truncated: false, aborted: false, capHit: true, note: wrapApplied.note || undefined, durationMs: Date.now() - startedAt, perf: perf() };
       } catch (/** @type {any} */ err) {
         // v0.4.1：不再静默吞异常——总结失败原因透出，便于定位（此前用户只见「输出截断/无反馈」）
         try { io.print(style(`⚠ 兜底总结失败：${String(err?.message || err)}`, C.yellow)); } catch {}

package/src/cachestats.js

@@ -35,6 +35,11 @@ export function recordCacheStats(/** @type {any} */ entry) {
       firstTokenMs: entry.firstTokenMs ?? undefined, // 首 token 延迟（状态栏平均首 token）
       reasoning: entry.reasoning ?? undefined, // 省钱 B3：推理 token 估算（费用二级分账维度）
       byTool: Array.isArray(entry.byTool) ? entry.byTool : undefined, // 省钱 B3：逐工具 {tool,calls,ms}
+      // v0.5.0 A4：垂域 Pack 归因（**标记记录**：cost 记 null 不计入 todayCost，
+      // 真实费用仍在回合级记录里 —— 两者相加不会重复计费；packCost 仅供 --by pack 展示）
+      pack: entry.pack ? String(entry.pack) : undefined,
+      purpose: entry.purpose ? String(entry.purpose) : undefined,
+      packCost: Number.isFinite(Number(entry.packCost)) ? Number(entry.packCost) : undefined,
     });
     fs.appendFileSync(cacheStatsFile(), line + '\n');
     cacheStatsCount += 1;
@@ -172,12 +177,33 @@ export function formatCacheSummary(/** @type {any} */ sum) {
 }
 
 // 分账统计（评估 /cost 升级）：按模型分账、今日费用、batch 半价任务、节省归因
+/**
+ * v0.5.0 A4.5：某垂域 Pack 的「今日」费用（北京自然日）。
+ * 来源是 ctx.llm 写的归因标记记录（packCost 字段）——标记记录本身 cost=null 不计入总额，
+ * 因此这里不会与回合级总账重复。
+ * @param {any} pack
+ */
+export function packDailyCost(pack) {
+  const want = String(pack || '');
+  if (!want) return 0;
+  const start = beijingDayStart().getTime();
+  let sum = 0;
+  for (const e of listCacheStats(100000)) {
+    if (e.pack !== want) continue;
+    if (!(e.at >= start)) continue;
+    sum += Number(e.packCost) || 0;
+  }
+  return sum;
+}
+
 // 省钱 B3：新增 reasoning 维度、byTool 逐工具累加、byDay 近 14 天按日折线数据
 export function costBreakdown() {
   const entries = listCacheStats(100000);
   const byModel = new Map();
   const byTool = /** @type {Map<string, {calls: number, ms: number}>} */ (new Map());
   const byDay = /** @type {Map<string, number>} */ (new Map()); // 'MM-DD' → cost（近 14 个北京日，含 0 值日）
+  // v0.5.0 A4：垂域 Pack 分账（来自 ctx.llm 的标记记录；cost 为 null 不入总额，取 packCost 展示）
+  const byPack = /** @type {Map<string, {prompt: number, completion: number, cost: number, calls: number}>} */ (new Map());
   const start = beijingDayStart().getTime();
   let totalCost = 0;
   let totalSaved = 0;
@@ -194,6 +220,14 @@ export function costBreakdown() {
     reasoning += e.reasoning || 0;
     if (e.batch) batchCost += e.cost || 0;
     if (e.at >= start) today += e.cost || 0;
+    if (e.pack) {
+      const pk = byPack.get(e.pack) || { prompt: 0, completion: 0, cost: 0, calls: 0 };
+      pk.prompt += e.prompt || 0;
+      pk.completion += e.completion || 0;
+      pk.cost += Number(e.packCost) || 0;
+      pk.calls += 1;
+      byPack.set(e.pack, pk);
+    }
     const m = byModel.get(e.model) || { prompt: 0, completion: 0, cost: 0, saved: 0, turns: 0, batchTurns: 0, reasoning: 0 };
     m.prompt += e.prompt || 0;
     m.completion += e.completion || 0;
@@ -237,6 +271,8 @@ export function costBreakdown() {
     byModel: [...byModel.entries()].map(([model, m]) => ({ model, ...m })).sort((a, b) => b.cost - a.cost),
     byTool: [...byTool.entries()].map(([tool, t]) => ({ tool, ...t })).sort((a, b) => b.ms - a.ms),
     byDay: days,
+    // v0.5.0 A4：垂域 Pack 分账（ctx.llm 归因；cost 为 null 的标记记录不计入 totalCost，故不重复计费）
+    byPack: [...byPack.entries()].map(([pack, v]) => ({ pack, ...v })).sort((a, b) => b.cost - a.cost),
   };
 }
 

package/src/cli.js

@@ -205,6 +205,7 @@ async function main() {
       key: { module: 'key', handler: 'handleKey' },
       desktop: { module: 'desktop', handler: 'handleDesktop' },
       diagnose: { module: 'diagnose', handler: 'handleDiagnose' },
+      pack: { module: 'pack', handler: 'handlePack' }, // v0.5.0：垂域 Pack 查看/校验/脚手架
     });
     const hit = dispatchTable[opts.prompt[0]];
     if (hit) {
@@ -426,6 +427,16 @@ async function main() {
     const mounted = mountConfigTools(cfg);
     if (mounted.length && !jsonMode) io.print(style(`🔧 已挂载声明式工具（config.tools）：${mounted.join(', ')}`, C.dim));
   }
+  // v0.5.0 阶段 A：挂载垂域 Pack（工具进注册表；约束与提示词段进进程级上下文）。
+  // 坏 Pack 只告警不阻塞启动；未装 Pack 时全部惰性。
+  {
+    const { mountPacks } = await import('./packs.js');
+    const packCtx = await mountPacks(cfg, { cwd: workingDir });
+    for (const w of packCtx.warnings) console.error(`[MingDao] ⚠ ${w}`);
+    if (packCtx.mounted.length && !jsonMode) {
+      io.print(style(`📦 已加载垂域 Pack：${packCtx.mounted.map((p) => `${p.name} v${p.version}`).join(', ')}`, C.dim));
+    }
+  }
   // 会话级 undo 备份仓：模型切换、子代理均共享，撤销记录不丢失
   const sessionUndoStore = { backups: new Map() };
   // MCP 服务器：后台启动（不阻塞交互），就绪后工具自动出现在后续轮次

package/src/commands/pack.js

@@ -0,0 +1,196 @@
+// `mingdao pack` 命令族（v0.5.0 阶段 A）：垂域 Pack 的查看 / 校验 / 脚手架。
+// 下游 CI 门禁入口是 `mingdao pack verify <dir>`——它只做静态校验（不 import Pack 代码），
+// 因此可以在没有内核运行时的环境里安全执行。
+import fs from 'node:fs';
+import path from 'node:path';
+import { listPacks, loadPack, validateManifest, coreVersionOf, SUPPORTED_PACK_API, CONSTRAINT_KINDS, packedDirsForHelp } from '../packs.js';
+
+const HELP = `用法：
+  mingdao pack list                 已发现的 Pack（名/版本/来源/兼容状态）
+  mingdao pack verify <目录>        静态校验 manifest + 文件齐全 + 约束合法（下游 CI 门禁）
+  mingdao pack new <名字>           生成最小可用 Pack 脚手架
+  mingdao pack info <名字>          单个 Pack 的贡献面明细
+
+说明：Pack API v${SUPPORTED_PACK_API.join('/')}（契约见 docs/PACK-API.md）。
+约束 kind：${[...CONSTRAINT_KINDS].join(' / ')}`;
+
+/**
+ * @param {any} cmd @param {any} args
+ * @returns {Promise<boolean>}
+ */
+export async function handlePack(cmd, args) {
+  if (cmd !== 'pack') return false;
+  const sub = String(args[0] || '').trim();
+
+  if (!sub || sub === 'help' || sub === '--help') {
+    console.log(HELP);
+    return true;
+  }
+
+  if (sub === 'list') {
+    const found = listPacks({}, process.cwd());
+    if (!found.length) {
+      console.log('未发现任何 Pack。');
+      console.log(`放置位置（三级遮蔽）：<项目>/.mingdao/packs/ > ${packedDirsForHelp()} > 内置 packs/`);
+      console.log('或运行 mingdao pack new <名字> 生成脚手架。');
+      return true;
+    }
+    console.log(`共 ${found.length} 个 Pack（内核 ${coreVersionOf()}）：`);
+    for (const p of found) {
+      const status = p.error ? `❌ ${p.error}` : `✅ apiVersion ${p.apiVersion}`;
+      console.log(`  ${p.name}${p.displayName ? '（' + p.displayName + '）' : ''} v${p.version || '?'} · 来源 ${p.source} · ${status}`);
+      console.log(`      ${p.dir}`);
+    }
+    return true;
+  }
+
+  if (sub === 'verify') {
+    const dir = String(args[1] || '').trim();
+    if (!dir) {
+      console.log('[错误] 用法：mingdao pack verify <目录>');
+      process.exitCode = 1;
+      return true;
+    }
+    const abs = path.resolve(dir);
+    if (!fs.existsSync(abs)) {
+      console.log(`[错误] 目录不存在：${abs}`);
+      process.exitCode = 1;
+      return true;
+    }
+    // 静态校验优先（不 import 代码）——把可操作的错误一次性列全
+    const mf = path.join(abs, 'pack.json');
+    if (!fs.existsSync(mf)) {
+      console.log(`[错误] 缺少 pack.json（${abs}）`);
+      process.exitCode = 1;
+      return true;
+    }
+    let manifest = null;
+    try {
+      manifest = JSON.parse(fs.readFileSync(mf, 'utf8'));
+    } catch (/** @type {any} */ err) {
+      console.log(`[错误] pack.json 解析失败：${err?.message || err}`);
+      process.exitCode = 1;
+      return true;
+    }
+    const v = validateManifest(manifest);
+    if (!v.ok) {
+      console.log(`[失败] ${manifest?.name || path.basename(abs)} 的 manifest 校验未通过：`);
+      v.errors.forEach((/** @type {any} */ e, /** @type {number} */ i) => console.log(`  ${i + 1}. ${e}`));
+      process.exitCode = 1;
+      return true;
+    }
+    // 再走一次完整加载（会 import pack.mjs，验证运行时契约）
+    const res = await loadPack(abs);
+    if (!res.ok) {
+      console.log(`[失败] ${manifest.name} 加载校验未通过：`);
+      res.errors.forEach((/** @type {any} */ e, /** @type {number} */ i) => console.log(`  ${i + 1}. ${e}`));
+      process.exitCode = 1;
+      return true;
+    }
+    const c = res.contributions;
+    console.log(`[通过] ${manifest.name} v${manifest.version}（apiVersion ${manifest.apiVersion}，内核窗口 ${manifest.engines?.mingdao}）`);
+    console.log(`  工具 ${Array.isArray(c.tools) ? c.tools.length : 0} 个 · 约束 ${Array.isArray(c.constraints) ? c.constraints.length : 0} 条 · 提示词段 ${Array.isArray(c.promptSections) ? c.promptSections.length : 0} 段`);
+    for (const w of Array.isArray(res.warnings) ? res.warnings : []) console.log(`  ⚠ ${w}`);
+    return true;
+  }
+
+  if (sub === 'new') {
+    const name = String(args[1] || '').trim();
+    if (!/^[a-z0-9][a-z0-9-]{1,31}$/.test(name)) {
+      console.log('[错误] 用法：mingdao pack new <名字>（小写字母/数字/连字符，2–32 位）');
+      process.exitCode = 1;
+      return true;
+    }
+    const dir = path.resolve(process.cwd(), 'packs', name);
+    if (fs.existsSync(dir)) {
+      console.log(`[错误] 目录已存在：${dir}`);
+      process.exitCode = 1;
+      return true;
+    }
+    fs.mkdirSync(path.join(dir, 'prompts'), { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, 'pack.json'),
+      JSON.stringify(
+        {
+          apiVersion: SUPPORTED_PACK_API[0],
+          name,
+          displayName: name,
+          version: '1.0.0',
+          engines: { mingdao: `>=${coreVersionOf()} <0.7` },
+          description: '（一句话说明这个垂域包做什么）',
+          license: 'private',
+          contributes: { tools: true, promptSections: ['prompts/domain.md'], constraints: true },
+        },
+        null,
+        2
+      ) + '\n'
+    );
+    fs.writeFileSync(path.join(dir, 'prompts', 'domain.md'), '（在这里写领域提示词：角色、边界、红线。）\n');
+    fs.writeFileSync(
+      path.join(dir, 'pack.mjs'),
+      `// ${name} —— 垂域 Pack 入口。契约见 docs/PACK-API.md（Pack API v1）。
+export const apiVersion = 1;
+
+export function createPack(ctx) {
+  return {
+    tools: [
+      {
+        name: 'hello',
+        description: '（示例工具：说明它能做什么、什么时候该用）',
+        parameters: { type: 'object', properties: {}, required: [] },
+        readOnly: true,
+        async run(_args, toolCtx) {
+          // toolCtx.llm(...) 可调用模型（自动入账 / 受护栏约束）——见 PACK-API §5
+          return { ok: true, output: '来自 ' + ctx.packName + ' 的问候' };
+        },
+      },
+    ],
+    constraints: [
+      // 领域红线示例：输出出现这些措辞即拦截（action: block / block-and-rewrite / warn）
+      { id: 'no-forbidden-claim', kind: 'output-forbid', pattern: '（替换为你的禁用措辞，正则）', action: 'block-and-rewrite' },
+    ],
+    promptSections: [{ id: 'domain', order: 100, content: '（由 prompts/domain.md 读取，见下）' }],
+  };
+}
+`
+    );
+    console.log(`✓ 已生成脚手架：${dir}`);
+    console.log('下一步：');
+    console.log(`  1. 编辑 ${path.join(dir, 'pack.json')}（描述/权限）与 pack.mjs（工具/约束）`);
+    console.log(`  2. mingdao pack verify ${dir}`);
+    return true;
+  }
+
+  if (sub === 'info') {
+    const name = String(args[1] || '').trim();
+    const found = listPacks({}, process.cwd()).find((p) => p.name === name);
+    if (!found) {
+      console.log(`[错误] 未发现 Pack "${name}"。可用：mingdao pack list`);
+      process.exitCode = 1;
+      return true;
+    }
+    if (found.error) {
+      console.log(`[错误] ${name} 校验未通过：${found.error}`);
+      process.exitCode = 1;
+      return true;
+    }
+    const res = await loadPack(found.dir);
+    if (!res.ok) {
+      console.log(`[错误] ${name} 加载失败：${res.errors.join('；')}`);
+      process.exitCode = 1;
+      return true;
+    }
+    const c = res.contributions;
+    console.log(`${found.name}${found.displayName ? '（' + found.displayName + '）' : ''} v${res.manifest.version}`);
+    console.log(`  来源     ${found.source} · ${found.dir}`);
+    console.log(`  兼容     apiVersion ${res.manifest.apiVersion} · engines.mingdao ${res.manifest.engines?.mingdao}`);
+    console.log(`  描述     ${res.manifest.description || '（无）'}`);
+    console.log(`  工具     ${(Array.isArray(c.tools) ? c.tools : []).map((/** @type {any} */ t) => `pack__${found.name}__${t.name}`).join(', ') || '（无）'}`);
+    console.log(`  约束     ${(Array.isArray(c.constraints) ? c.constraints : []).map((/** @type {any} */ x) => `${x.id}(${x.kind})`).join(', ') || '（无）'}`);
+    console.log(`  提示词段 ${(Array.isArray(c.promptSections) ? c.promptSections : []).map((/** @type {any} */ s) => s.id).join(', ') || '（无）'}`);
+    return true;
+  }
+
+  // 未知子命令：不劫持整句，交回普通提问（与 handleUpdateFamily 同口径的保留词防护）
+  return false;
+}