cli-blueprint 0.1.0 → 0.2.1

package/README.md

@@ -1,8 +1,14 @@
-# dsh-skillpack
+# cli-blueprint
 
-**多 IDE 通用 skill 插件包** —— 一键安装 / 更新 / 卸载一组 skills，自动适配你本机已安装的每个 IDE，可无限扩展，可分发给任何人。
+**多 skill 多 IDE 安装器** —— 一条命令从 cli.tax 拉取并分发到本机所有已装 IDE，可无限扩展。
 
-默认包含：`blueprint`（CLI.Tax 工程规划 skill，`https://cli.tax/wvz6zmRWmX`）。
+```bash
+npx cli-blueprint@latest install
+```
+
+默认包含：
+- `blueprint`（CLI.Tax 工程规划 skill，`https://cli.tax/wvz6zmRWmX`）
+- `calctool`（万能计算工具生成器，`https://cli.tax/VjFfeR6wdB`）
 
 ## 这是什么机制？
 
@@ -72,34 +78,45 @@ node install.mjs uninstall          # 从相同目标卸载本包安装的 skill
 
 ## 分发给别人
 
-### 方式 A：Git 仓库（推荐，最简单）
-把本目录推到一个 git 仓库，使用者：
+### 方式 A：npm 一条命令（推荐，最简单）
+已发布到 npm（`cli-blueprint@0.1.0` / `cli-calctool@0.1.0`），使用者只需：
+```bash
+npx cli-blueprint@latest install     # 装 blueprint + calctool 两个 skill
+npx cli-calctool@latest install      # 同样内容（calctool 命名入口）
+```
+自动完成：从 cli.tax 拉取 blueprint + calctool → 检测本机已装 IDE → 分发到每个 IDE。
+更新：同一命令（`@latest` 自动拉新版），且每次 install 会对比 cli.tax 最新版本并提示 ⤴。
+
+### 方式 B：Git 仓库
 ```bash
-git clone <repo-url> && cd dsh-skillpack && node install.mjs install
+git clone https://github.com/88208555/Blueprint-clitax.git
+cd Blueprint-clitax
+node install.mjs install
 ```
-更新：`git pull && node install.mjs update`
+更新：`git pull && node install.mjs update`（install/update 会对比已装版本与 cli.tax 最新版本并提示）。
 
-### 方式 B：发布为 npm 包（一条命令装）
-本包已配好 `bin`，发布后使用者只需：
+### 更新感知（check）
+安装器写入 `install-meta.json`（来源/版本/时间）到每个 skill 目录；SKILL.md 注入版本横幅，
+IDE 每次读取即可见版本与更新入口。主动检查：
 ```bash
-npx dsh-skillpack@latest install
+node install.mjs check               # 遍历本机已装 IDE，对比 cli.tax 最新版本
+npx cli-blueprint@latest check       # 单包检查（calctool 同理）
 ```
-更新：同一命令（`@latest` 自动拉新版）。
-> 注意 npm 官方源对包名唯一性有要求；内部使用可部署私有 registry（如 Verdaccio）。
 
-### 方式 C：直接用 clitaxio（如果只想引第三方 skill）
+### 方式 C：直接用 clitaxio（只装单个 IDE，作为对照）
 ```bash
-npx clitaxio@latest install <runtime-code> ~/.codex/skills/<slug>
+npx clitaxio@latest install wvz6zmRWmX
 ```
-本包是更可控的本地化替代：离线可用、可审计、可 git 管理、可批量管理多个 skill、自动多 IDE 分发。
+> ⚠️ 注意：clitaxio **只把 skill 装到默认的 Codex 目录**（单一 IDE），不会自动检测/分发到
+> 其他 IDE，也不处理 `~/.agents/skills` 共享根重复问题。需要多 IDE 分发请用方式 A/B。
 
 ## 目录结构
 
 ```
-dsh-skillpack/
+cli-blueprint/
 ├── install.mjs       # 安装器（Node ≥18，零依赖）：pull / install / uninstall / list / ides
 ├── sources.json      # ★ cli.tax skill 源清单（code → 自动拉取），扩展就加一行
-├── package.json      # npm 包元数据（可发布）
+├── package.json      # npm 包元数据（cli-blueprint）
 ├── README.md
 └── skills/           # skill 内容（pull 生成，可提交 git 离线兜底）
     └── blueprint/

package/install.mjs

@@ -15,6 +15,11 @@
  *     需要时用 --agents 显式开启（会打印警告）；
  *   - --ide / --skip 精确控制；新增 IDE 只需在 IDES 表加一行。
  *
+ * 更新感知：
+ *   - pull 时把 cli.tax 返回的 version 写入 skills/<slug>/install-meta.json；
+ *   - install / update 时对比「已安装版本」与「远端最新版本」，有新版本会提示；
+ *   - check 子命令：遍历本机已装 IDE 的 skill 目录，对比远端最新版本并报告更新。
+ *
  * 用法:
  *   node install.mjs pull                  # 从 sources.json（cli.tax）拉取全部 skill 到 skills/
  *   node install.mjs install               # 自动匹配：只装本机已安装的 IDE（推荐）
@@ -26,6 +31,7 @@
  *   node install.mjs install --agents      # 额外安装到共享 ~/.agents/skills（警告）
  *   node install.mjs install --target /abs/path    # 仅自定义目录
  *   node install.mjs update                # 同 install（幂等覆盖）
+ *   node install.mjs check                 # 检查已安装 skill 是否有新版本（对比 cli.tax）
  *   node install.mjs uninstall             # 从相同目标移除本包安装的 skills
  *   node install.mjs list                  # 列出本包包含的 skills
  *   node install.mjs ides                  # 列出已知 IDE 及本机检测结果
@@ -45,6 +51,9 @@ const SKILLS_SRC = join(__dirname, 'skills')
 const HOME = homedir()
 const CWD = process.cwd()
 
+/** 每个 skill 安装/拉取时的版本元数据文件名（IDE 目录与 skills/ 内都会写） */
+const INSTALL_META = 'install-meta.json'
+
 /**
  * 全世界已知 IDE/编码 agent 的 skills 安装位置表（官方文档核实，2026-08）。
  *   key:     命令行标识
@@ -126,14 +135,37 @@ async function syncOne(name, targetRoot, { remove = false } = {}) {
     return
   }
   await mkdir(dest, { recursive: true })
-  await cp(join(SKILLS_SRC, name), dest, { recursive: true, force: true })
-  print(`  ✓ 已安装 ${name} → ${dest}`)
+  const sourceDir = join(SKILLS_SRC, name)
+  const destMeta = readMeta(dest) // 覆盖前读取旧版本
+  await cp(sourceDir, dest, { recursive: true, force: true })
+  const srcMeta = readMeta(sourceDir)
+  // 安装时注入版本横幅到 SKILL.md（IDE 每次读取即见版本与更新入口）
+  if (srcMeta?.version) {
+    const installedSkillMd = readFileSync(join(dest, 'SKILL.md'), 'utf8')
+    await writeFile(join(dest, 'SKILL.md'), injectVersionBanner(installedSkillMd, srcMeta.version, name))
+  }
+  if (srcMeta) {
+    await writeMeta(dest, { ...srcMeta, installedAt: new Date().toISOString() })
+  }
+  const upgrade = destMeta && srcMeta && destMeta.version && srcMeta.version && destMeta.version !== srcMeta.version
+  if (upgrade) {
+    print(`  ⤴ 已更新 ${name} ${destMeta.version} → ${srcMeta.version} → ${dest}`)
+  } else {
+    print(`  ✓ 已安装 ${name} → ${dest}${srcMeta?.version ? `（${srcMeta.version}）` : ''}`)
+  }
 }
 
-async function syncAll(targetRoot, { remove = false } = {}) {
+async function syncAll(targetRoot, { remove = false, reportUpdated } = {}) {
   const skills = await listSkills()
   if (!remove) await mkdir(targetRoot, { recursive: true })
-  for (const s of skills) await syncOne(s, targetRoot, { remove })
+  for (const s of skills) {
+    const before = reportUpdated ? readMeta(join(targetRoot, s)) : null
+    await syncOne(s, targetRoot, { remove })
+    if (reportUpdated && before && before.version) {
+      const after = readMeta(join(targetRoot, s))
+      if (after && after.version && after.version !== before.version) reportUpdated(1)
+    }
+  }
 }
 
 /** 解析目标列表：--target / --ide / --skip / 默认（全部已知 IDE） */
@@ -202,6 +234,31 @@ function parseTargets(args) {
 
 const [cmd, ...rest] = process.argv.slice(2)
 
+/** 读取 skill 目录的 install-meta.json（没有则返回 null） */
+function readMeta(skillDir) {
+  const p = join(skillDir, INSTALL_META)
+  if (!existsSync(p)) return null
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return null }
+}
+
+/** 写入 skill 目录的 install-meta.json（来源/版本/时间/地址） */
+async function writeMeta(skillDir, meta) {
+  await writeFile(join(skillDir, INSTALL_META), `${JSON.stringify(meta, null, 2)}\n`)
+}
+
+/** 在 SKILL.md frontmatter 之后注入版本横幅：IDE 每次读取即见版本与更新命令 */
+function injectVersionBanner(skillMd, version, slug) {
+  if (!skillMd || !version) return skillMd
+  const banner = `<!-- calctool-installer: version ${version} · 检查更新见 install-meta.json / npx cli-${slug}@latest check -->\n`
+  if (skillMd.startsWith('---')) {
+    const end = skillMd.indexOf('\n---', 3)
+    if (end !== -1) {
+      return `${skillMd.slice(0, end + 5)}\n\n${banner}${skillMd.slice(end + 5).replace(/^\n+/, '')}`
+    }
+  }
+  return `${banner}${skillMd}`
+}
+
 /** 从 cli.tax 拉取一个 skill 到 skills/<slug>/（覆盖本地副本） */
 async function pullSkill(source) {
   const url = source.endpoint.replace('{code}', source.code)
@@ -215,10 +272,83 @@ async function pullSkill(source) {
   await mkdir(dir, { recursive: true })
   await writeFile(join(dir, 'SKILL.md'), data.skillMd)
   await writeFile(join(dir, 'skill.json'), data.skillJson)
-  print(`  ✓ 已拉取 ${data.displayName} ${data.version ?? ''} → skills/${data.slug}/`)
+  const previous = readMeta(dir)
+  await writeMeta(dir, {
+    source: source.code,
+    slug: data.slug || source.slug,
+    version: data.version ?? '',
+    endpoint: url,
+    installedAt: new Date().toISOString(),
+  })
+  const changed = previous && previous.version && previous.version !== data.version
+  if (changed) {
+    print(`  ⤴ 已更新 ${data.displayName} ${previous.version} → ${data.version ?? ''} → skills/${data.slug}/`)
+  } else {
+    print(`  ✓ 已拉取 ${data.displayName} ${data.version ?? ''} → skills/${data.slug}/`)
+  }
   return true
 }
 
+/** 从 cli.tax 拉取单个 skill 的最新元数据（check 用，不写盘） */
+async function fetchLatestMeta(source) {
+  const url = source.endpoint.replace('{code}', source.code)
+  try {
+    const resp = await fetch(url)
+    if (!resp.ok) return null
+    const data = await resp.json()
+    return {
+      source: source.code,
+      slug: data.slug || source.slug,
+      version: data.version ?? '',
+      displayName: data.displayName ?? data.slug ?? source.slug,
+      endpoint: url,
+    }
+  } catch {
+    return null
+  }
+}
+
+/** check：遍历已安装目标的 skill 目录，对比远端最新版本，报告更新 */
+async function checkUpdates(targets) {
+  const sources = loadSources()
+  if (!sources.length) {
+    print('⚠ sources.json 无源，无法检查更新。')
+    return 1
+  }
+  let found = 0
+  for (const t of targets) {
+    print(`[${t.label}] ${t.path}`)
+    if (!existsSync(t.path)) { print('  · 未安装'); continue }
+    const entries = (await readdir(t.path, { withFileTypes: true }).catch(() => []))
+      .filter((e) => e.isDirectory())
+    if (!entries.length) { print('  · 无已安装 skill'); continue }
+    for (const e of entries) {
+      const skillDir = join(t.path, e.name)
+      const local = readMeta(skillDir)
+      const source = sources.find((s) => (s.slug === e.name)
+        || (local && local.source === s.code))
+      if (!source) continue
+      const remote = await fetchLatestMeta(source)
+      if (!remote) { print(`  · ${e.name}：远端查询失败，跳过`); continue }
+      if (!local || !local.version) {
+        print(`  · ${e.name}：本地无版本记录（旧安装），远端最新 ${remote.version} —— 运行 install 补齐`)
+        found++
+      } else if (local.version === remote.version) {
+        print(`  ✓ ${e.name} 已是最新（${remote.version}）`)
+      } else {
+        print(`  ⤴ ${e.name} 有新版本 ${local.version} → ${remote.version} —— 运行 install 更新`)
+        found++
+      }
+    }
+  }
+  if (found) {
+    print(`\n发现 ${found} 个 skill 可更新。执行: node install.mjs install`)
+  } else {
+    print('\n全部已是最新。')
+  }
+  return 0
+}
+
 /** 读取 sources.json 中的源列表 */
 function loadSources() {
   const p = join(__dirname, 'sources.json')
@@ -269,14 +399,22 @@ if (cmd === 'list') {
   if (!skills.length) { print('skills/ 目录为空，无法安装'); process.exit(1) }
   if (rest.includes('--agents') && !targets.some((t) => t.path === AGENTS.path)) targets.push(AGENTS)
   print(`将安装 ${skills.length} 个 skills → ${targets.length} 个目标`)
+  let updated = 0
   for (const t of targets) {
     print(`[${t.label}] ${t.path}`)
-    await syncAll(t.path)
+    await syncAll(t.path, { reportUpdated: (n) => { updated += n } })
   }
   if (rest.includes('--agents')) {
     print('⚠ 已安装到共享 ~/.agents/skills：该目录会被 Codex/Gemini/Zed/OpenCode/Cursor 等同时扫描，同一 skill 可能被重复发现。')
   }
   print('完成。各 IDE 会自动发现各自用户级根中的新目录（可立即在新会话中调用）。')
+  if (updated) {
+    print(`提示：${updated} 个 skill 有更新。以后可用 node install.mjs check 检查新版本。`)
+  }
+} else if (cmd === 'check') {
+  const targets = parseTargets(rest)
+  if (rest.includes('--agents') && !targets.some((t) => t.path === AGENTS.path)) targets.push(AGENTS)
+  process.exitCode = await checkUpdates(targets)
 } else if (cmd === 'uninstall') {
   const targets = parseTargets(rest)
   if (rest.includes('--agents') && !targets.some((t) => t.path === AGENTS.path)) targets.push(AGENTS)
@@ -290,8 +428,11 @@ if (cmd === 'list') {
   node install.mjs install [--all|--ide <key>|--skip <key>|--project|--agents|--pull|--target <dir>]
   node install.mjs pull
   node install.mjs update
+  node install.mjs check
   node install.mjs uninstall
   node install.mjs list
-  node install.mjs ides`)
+  node install.mjs ides
+
+  npm 安装后（npx cli-blueprint@latest / npx cli-calctool@latest）用法相同。`)
   process.exit(1)
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cli-blueprint",
-  "version": "0.1.0",
-  "description": "Blueprint skill 多 IDE 安装器：从 cli.tax 自动拉取并分发到本机所有已装 IDE（Codex/DSH/Claude/Cursor/…）。",
+  "version": "0.2.1",
+  "description": "Blueprint + calctool 多 IDE 安装器：从 cli.tax 自动拉取并分发到本机所有已装 IDE（Codex/DSH/Claude/Cursor/…）。支持 check 更新检测。",
   "type": "module",
   "bin": {
     "cli-blueprint": "install.mjs"

package/skills/blueprint/SKILL.md

@@ -1,39 +1,47 @@
 ---
-name: "blueprint"
-description: "Blueprint 是一个跨工具的工程规划 CLI，把明确目标编译为可执行、可追溯、可验收的全站工程蓝图，并通过确定性规则检查每个节点、分支、合同、任务与验收闭环。默认由当前 IDE 的多智能体协同推演，也可连接用户自行安装的本地 Hermes；平台不托管模型密钥。"
+name: blueprint
+description: Compile one goal into an implementable engineering blueprint with deterministic checks. Use when the user wants to turn an idea, product, or site goal into an executable engineering plan with nodes, dependencies, acceptance criteria, and validation.
 ---
 
-# blueprint
+# Blueprint Skill
 
-Use this Skill only when the user's request matches the capability described below.
+Endpoint: https://cli.tax/wvz6zmRWmX
+Request schema: blueprint.skill.request/1.0
+Response schema: blueprint.skill.response/1.0
 
-## Capability
+## Request envelope
 
-- Source type: Skill
-- Version: v0.4.0
-- Status at generation: published
-- Address: `https://cli.tax/wvz6zmRWmX`
-- Method: `POST`
-- Content type: `application/json`
-
-Blueprint 是一个跨工具的工程规划 CLI，把明确目标编译为可执行、可追溯、可验收的全站工程蓝图，并通过确定性规则检查每个节点、分支、合同、任务与验收闭环。默认由当前 IDE 的多智能体协同推演，也可连接用户自行安装的本地 Hermes；平台不托管模型密钥。
-
-## Invocation
-
-Send JSON to the exact CLI address and put capability arguments inside `input`:
+POST JSON to the endpoint with an `input` wrapper:
 
 ```json
 {
-  "input": {}
+  "input": {
+    "schemaVersion": "blueprint.skill.request/1.0",
+    "requestId": "<unique-id>",
+    "operation": "<operation>",
+    "input": {}
+  }
 }
 ```
 
-Do not rewrite the CLI address, invent parameters, or include API keys, tokens, cookies, passwords, or private keys. Ask for missing non-secret inputs. Runtime invocation is available only after the CLI is published and the owner has an active subscription.
+## Operations
+
+- `capabilities`: discover the operation list, per-operation inputs, and the recommended next step.
+- `help`: return the usage guide, operation catalog, and request examples.
+- `intake`: return the questions the IDE must ask the user before building the Blueprint.
+- `validate`: deterministically validate a Blueprint object conforming to `blueprint.ir/1.0`.
+- `compile-inline`: validate and compile a Blueprint, returning the generated artifacts inline.
+
+## Required flow
+
+1. Call `capabilities` first and read the returned `nextStep`.
+2. Call `intake` and ask the user the returned questions one at a time, waiting for each answer.
+3. Do not compile a Blueprint until all required questions are answered.
+4. Build a Blueprint conforming to `blueprint.ir/1.0`, then call `validate`.
+5. Fix every validation finding until the report is green, then call `compile-inline` and save the artifacts.
 
-## Errors
+## Safety rules
 
-- `402`: subscription or quota unavailable
-- `404`: CLI is unavailable or not published
-- `422`: invalid input or contract
-- `429`: rate or concurrency limit reached
-- `5xx`: execution or upstream failure
+- Never send credentials, model keys, provider endpoints, or personal secrets inside the request envelope or `input`.
+- The response `status` must be `succeeded`; a `failed` response is an error, not a result.
+- Public responses never prove that code was developed, tested, or deployed.

package/skills/blueprint/install-meta.json

@@ -0,0 +1,7 @@
+{
+  "source": "wvz6zmRWmX",
+  "slug": "blueprint",
+  "version": "v0.4.0",
+  "endpoint": "https://cli.tax/api/public/skills/wvz6zmRWmX",
+  "installedAt": "2026-08-17T00:00:00.000Z"
+}

package/skills/calctool/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: calctool
+description: 按需生成「万能计算工具」：用户输入一个领域需求（如"我是财务，想要一个经营健康诊断工具"），本技能通过提问明确指标、公式、输入方式与输出形式，生成一个可执行、可验证、可发布的在线计算工具——支持自定义指标、自定义公式逻辑、用户上传内容自动识别（Excel 映射 / 图片 OCR）、报告输出。当用户想"把某套计算逻辑/指标/公式做成在线工具"时使用。
+---
+
+# calctool
+
+把「业务计算逻辑」编译为「可执行的在线计算工具」的生成器。
+
+## 全链路总流程（老板视角 → 可运行工具）
+
+```
+老板（任何 IDE / DSH）："我要搭电商运营计算工具"
+  ↓
+1. 顾问式对话（intake-round）   —— 智能体主动给方案（基于领域参考包），
+   老板逐轮确认指标/公式/口径，直到说"创建"
+  ↓
+2. 情报蜂群（research）        —— 自动派情报智能体搜索行业标准/抓指定地址，
+   产出可溯源参考包（老板说"电商"等关键词时自动触发）
+  ↓
+3. 蜂群执行（brain-invoke/complete）—— 需求自动拆解为 fields/formulas/rules/
+   imports/reports/pages 任务，依赖图驱动并行，独立复核，确定性合并
+  ↓
+4. 编译工具（compile-tool）    —— 引擎定义 → 可运行工程文件清单
+   （App 壳/公式引擎/存储/构建，页面自动生成：录入/指标卡/报告）
+  ↓
+5. 环境适配（probe-env/adapt-config）—— 自动探测 Node 版本/包管理器/OS/架构，
+   Node≥18 全功能、16 兼容(sql.js)、<16 零构建预览；pnpm/yarn/npm 自动适配
+  ↓
+6. 完成前门禁（final-gate）      —— 审计/测试/运维三智能体协调接管检测，
+   全部符合通过（engine-valid / 基准样例全通过 / 环境就绪）才标记完成
+  ↓
+7. 交付运行                     —— 按适配命令一键搭建（pnpm install → pnpm run dev）
+   → 老板得到可交互工具；后续对话继续改指标/公式（热更新）
+
+或直接走「全自动流水线」（auto-pipeline）——老板只需说需求 + 授权一次：
+  授权(告知消耗) → 情报蜂群 → 蜂群生成 → 测试审计 → 编译 → 自动启动弹出页面
+  → 完成前门禁（审计/测试/运维三智能体协调接管，全部符合通过才标记完成）
+  全程无需老板参与，热更新即时生效
+```
+
+**关键**：老板一句话 → 对话确认 → 情报 → 蜂群 → 编译 → 环境适配 → **可运行工具**。全程框架不变，需求变更只改配置。
+
+## 何时使用
+
+- 用户描述了一个领域场景（财务、运营、工程、教育、医疗……）并想要一个可交互的在线计算工具
+- 用户已有指标、公式、评分或报告逻辑，想固化成工具
+- 用户需要"自定义指标 + 自定义公式 + 上传识别"能力
+
+不要用于：纯展示型页面（无计算）、与计算无关的 CRUD 后台。
+
+## 核心原则
+
+1. **确定性计算**：正式数字由版本化确定性引擎（公式 AST + Decimal 运行时）产生；模型/OCR/AI 只产生候选、草稿与解释，绝不直接给出不可追溯的正式结果。
+2. **配置化而非代码化**：工具 = 一份可发布的引擎定义（字段目录 + 公式图 + 规则包 + 导入映射 + 视图 + 报告），不是散落的页面代码。
+3. **显式除零**：所有除法必须选 `div`（除零报错）或 `safeDivide`（除零回退），不静默吞错。
+4. **零虚构**：能力未接入时保持"未接入态"（planned/not_installed/disconnected），不虚构数据、状态或按钮。
+
+## 五步实施流程
+
+### 1. intake —— 收集需求（必须提问，一次一问）
+调用运行时 intake 或按下面问题逐条问用户：
+- 目标：这个工具帮用户完成什么？什么必须发生、什么绝不允许发生？
+- 输入指标：用户会输入哪些字段？（如收入、成本、人数、月份）
+- 公式逻辑：哪些指标由公式算出？（如毛利 = 收入 - 成本）
+- 输入方式：手工录入 / Excel 上传 / 图片 OCR / 三者都要？
+- 输出形式：指标卡、表格、诊断报告、历史记录？
+- 约束：单位、精度、语言、离线/在线、禁止项？
+
+### 2. 生成引擎定义（Engine Definition）
+```yaml
+engineId: <kebab-case-引擎名>
+name: <显示名>
+category: <领域，如 finance/operations/education>
+ownerType: platform-template
+status: draft
+semanticVersion: 1.0.0
+compatibilityProfile: legacy-compatible
+decimalPolicy: decimal-string
+defaultLocale: zh-CN
+```
+包含（详见 references/engine-meta-model.md）：
+- field-catalog：字段目录（类型：amount/ratio/int/enum/dimension/date）
+- formula-graph：公式图（节点 = 字段/公式，边 = 依赖）
+- rule-packs：规则包（阈值、评分、分级）
+- import-profiles：导入映射（Excel 列 / OCR 字段 → 字段目录）
+- report-template：报告模板（指标卡 + 表格 + 诊断结论）
+
+### 3. 编译公式（详见 references/formula-dsl.md）
+- 把自然语言/Excel 公式编译为 JSON AST（禁止 eval/new Function）
+- 运算符走最小注册表（add/sub/mul/div/safeDivide/percentOf/if/case/sum/avg/lookup…）
+- 数值用 Decimal 字符串，单位编译期推断，错误结构化传播
+- 发布前跑依赖图检查：引用存在、无环、可见范围
+
+### 4. 生成在线工具（详见 references/declarative-pages.md）
+- 表单页：录入字段（按 field-catalog 自动生成）
+- 指标卡页：公式结果 StatGrid
+- 报告页：结构化输出 + 可导出
+- 页面用声明式规格（ApplicationPageSpec），不手写重复模板
+
+### 5. 验收与发布
+- validate：确定性校验引擎定义（引用闭合、无环、单位一致、测试通过）
+- 上传识别走导入 Profile（Excel 映射 + OCR 草稿确认，自动导入先进草稿）
+- **完成前门禁（final-gate）**：每次项目完成之前，审计/测试/运维三智能体协调接管检测——
+  - **审计智能体**：引擎定义确定性校验 0 findings、公式仅走受控 AST（禁 eval）、引用闭合
+  - **测试智能体**：基准样例（testSuites）全部通过，一个不过都不放行
+  - **运维智能体**：环境探测成功、依赖分级适配、安装/启动命令可用、热更新就绪
+  - 三智能体全部符合通过（gate passed）才标记完成；任一未通过返回 findings，修复后重新接管检测
+- 发布为版本化引擎，任何公式/字段/阈值变化都创建新版本，不原地修改
+- 输出：可运行的在线工具 + 引擎定义包 + 验收报告 + 完成前门禁结论
+
+## 多智能体蜂群模式（大脑协同，推荐复杂工具用）
+
+单智能体 `compile-inline` 适合简单工具；复杂工具（多字段 + 多公式 + 规则 + 导入 + 报告）用**蜂群协同**，多智能体并行生成、独立复核、确定性合并——准确率更高、产出更强。
+
+### 大脑模式（brain-handshake）
+- `ide`：用当前 IDE 的多智能体（subagent）执行蜂群（默认）
+- `hermes_local`：用用户本地安装的 Hermes 执行蜂群
+
+### 蜂群流程（协议 calctool.coordinator.run-plan/1.0）
+
+1. **brain-handshake**：协商大脑模式（ide/hermes_local），返回蜂群能力
+2. **brain-invoke**：传需求 → **自动拆解**为蜂群任务（按需派发，需要几个派几个）：
+   - `fields` 字段目录（入口，总是有）
+   - `formulas` 公式图（有公式才派）· 独立复核
+   - `rules` 规则包（有规则才派）· 独立复核
+   - `imports` 导入映射（有导入才派）
+   - `reports` 报告模板（有报告才派）
+   - `pages` 页面规格（总是有）
+   依赖图驱动：fields 先 → formulas/imports 并行 → reports → pages；maxParallel 控制并发
+3. **brain-invoke 批量派发**：每个就绪 work item 派给一个独立智能体，收集产物
+4. **brain-events / brain-status**：流式收集事件、查询蜂群状态（就绪/运行/阻塞）
+5. **brain-complete**：提交全部产物 → **确定性合并**为引擎定义 → 校验 → 发布
+6. **brain-cancel**：随时取消蜂群
+
+### 准确率与用户控制
+- **准确率**：合并后引擎定义必须通过确定性校验（引用闭合/公式链/单位/Decimal/无环），0 findings 才发布
+- **用户控制**：每一步产物可查看、修改、重试（budget.maxAttempts）；最终工具可测算、改公式、调阈值
+- **编程能力**：蜂群产物是真实可编译的引擎定义（JSON AST + Decimal 运行时），不是伪代码
+
+## 输出产物
+
+```
+<engine-id>/
+├── manifest.yaml           # 引擎身份与版本
+├── field-catalog.json      # 字段目录
+├── formula-graph.json      # 公式图（AST）
+├── rule-packs.json         # 规则包
+├── import-profiles.json    # 导入映射
+├── report-template.json    # 报告模板
+└── tests/                  # 确定性测试（样例 → 期望结果）
+```
+
+## 参考文档
+
+- `references/engine-meta-model.md` —— 引擎元模型（字段/公式/规则/导入/报告）
+- `references/formula-dsl.md` —— 公式 DSL 与运行时（AST/Decimal/依赖图/错误值）
+- `references/declarative-pages.md` —— 声明式页面规格系统（表单/指标/报告渲染）
+- `references/import-ocr.md` —— 导入与 OCR（Excel 映射/图片识别/草稿确认）
+- `references/finance-example.md` —— 经营健康诊断完整范例（50 字段 → 10 指标 → 报告）
+
+## 安全规则
+
+- 不执行任意 JavaScript；公式只走受控 AST
+- 上传文件先验证类型/大小/指纹，OCR 结果进草稿不覆盖正式数据
+- 不虚构后端数据；未接入能力显示真实状态
+- 财务/税务输出需明确"经营估算模型，生产使用前由专业人员复核"

package/skills/calctool/install-meta.json

@@ -0,0 +1,7 @@
+{
+  "source": "KKyA6xljUX",
+  "slug": "calctool",
+  "version": "v0.3.0",
+  "endpoint": "https://cli.tax/api/public/skills/KKyA6xljUX",
+  "installedAt": "2026-08-17T00:00:00.000Z"
+}

package/skills/calctool/platform-template/README.md

@@ -0,0 +1,74 @@
+# calctool 平台模板
+
+由 calctool 生成的**可运行计算工具**工程模板（配置驱动、框架不变）。
+
+## 一键运行
+
+```bash
+npm install        # 或 pnpm install / yarn install（环境自动适配）
+npm run dev        # 启动开发服务器 http://localhost:5173
+```
+
+## 结构
+
+```
+├── src/
+│   ├── main.tsx                    # 入口（Ant Design X ConfigProvider）
+│   ├── App.tsx                     # 应用壳（录入/指标卡/链路/报告/授权 五页）
+│   ├── engine-definition.json      # ★ 引擎定义 + 链路（改这里 = 改工具，框架不动）
+│   ├── engine/
+│   │   ├── evaluate.ts             # JSON AST + decimal.js 确定性求值
+│   │   └── (recompute.ts 依赖图增量重算，按需扩展)
+│   ├── pipeline.ts                 # ★ 链路编排（联通节点，非单页孤岛）
+│   ├── authz.ts                    # ★ 授权管理（首次使用同意 + 逐能力授权，一次授权持久化）
+│   └── store.ts                    # 存储层（localStorage，可换 sqlite）
+├── vite.config.ts
+└── package.json
+```
+
+## 整套工具（联通节点，非单页孤岛）
+
+工具由**联通节点**组成，数据流在节点间流动：
+
+```
+录入/导入 → 数据校验 → 确定性计算 → 数据存储 → 指标卡/报告
+                                    ↘ 自动化（可选）
+```
+
+- 改动指标/公式：只改 `engine-definition.json`，链路自动感知
+- 新增能力：在 `pipeline.ts` 加节点（如导入、导出、告警），页面无需改
+- 页面「链路」Tab 可视化每个节点及其上下游，改工具时定位影响范围
+
+## 授权与消耗提示
+
+1. **首次使用总提示**：打开工具时弹窗告知"可能调用其他技能辅助、可能增加消耗"，同意后持久化不再提示（可按工具分别记录）
+2. **逐能力授权**：实际调用外部能力（Blueprint/搜索/模型/存储/自动化）前询问，一次授权永久记住
+3. **授权管理页**：随时查看已授权能力、撤销授权
+
+
+## 改指标/公式（需求变更，框架不变）
+
+编辑 `src/engine-definition.json`：
+
+```json
+{
+  "fields": [{ "key": "visitors", "label": "访客数", "type": "integer", "unit": "人" }],
+  "formulas": [
+    { "key": "conversionRate", "label": "转化率",
+      "expression": { "op": "safeDivide", "args": [{ "ref": "orders" }, { "ref": "visitors" }] } }
+  ]
+}
+```
+
+保存即热更新——**不用改任何代码**。
+
+## 公式运算符（详见 formula-dsl.md）
+
+`add / sub / mul / div（除零报错）/ safeDivide（除零回退）/ percentOf / round / if / ref / lit`
+
+## 环境适配
+
+- Node ≥18：全功能（可换 better-sqlite3 持久化）
+- Node 16：兼容（sql.js WASM）
+- Node <16：建议只用 L0 配置预览
+- 包管理器：npm/pnpm/yarn 命令自动适配

package/skills/calctool/platform-template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>calctool 计算工具</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>