cli-calctool 7.0.7 → 7.0.18

package/README.md

@@ -1,7 +1,8 @@
 # cli-calctool
 
 从 CLI.Tax 安装并运行 calctool 技能：输入领域需求（如"我是财务，想要一个经营健康诊断工具"），
-生成可执行、可验证、可发布的在线计算工具——支持自定义指标、自定义公式逻辑、上传内容自动识别。
+生成可验证的确定性计算引擎与在线工具工程合同，支持显式 engineId、自定义指标和受控公式 AST。
+Excel/OCR 当前只有声明式 importProfiles，执行器尚未安装；详细真实状态见 `skill/SKILL.md`。
 
 ```bash
 npx cli-calctool@latest install
@@ -17,3 +18,5 @@ npx https://cli.tax/cli-downloads/clitax-KKyA6xljUX.tgz install
 Source: https://github.com/88208555/calctool-clitax.git
 
 `calctool.skill.request/1.0` 协议，端点 `https://cli.tax/KKyA6xljUX`。
+
+反馈：技能详情页「使用评价」支持 好评 / 差评 / 日常聊天。好评与差评计入市场口碑（跑马灯每日清理），日常消息保留 7 天。

package/installer.mjs

@@ -1,9 +1,10 @@
 /**
- * 五个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
+ * 八个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
  * 禁止第二套超时、第二套版本来源、第二套 bin 名。
  */
-import { copyFile, mkdir, writeFile } from 'node:fs/promises'
-import { existsSync, readFileSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { constants, existsSync, readFileSync } from 'node:fs'
+import { cp, lstat, mkdir, open, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { stdin, stdout } from 'node:process'
 import { createInterface } from 'node:readline/promises'
@@ -12,6 +13,18 @@ import { fileURLToPath } from 'node:url'
 export const LOOKUP_TIMEOUT_MS = 8000
 export const CALL_TIMEOUT_MS = 120_000
 const INSTALL_META = 'install-meta.json'
+const FEEDBACK_API_PATH = '/api/v1/telemetry/skill-usage'
+const BRAIN_CLIENT_TOKEN_FILE_ENV = 'CLITAX_BRAIN_CLIENT_TOKEN_FILE'
+const BRAIN_CLIENT_TOKEN_FILE_VERSION = 'member-brain.client-token-file/1.0'
+const BRAIN_CLIENT_AUTH_SCHEME = 'BrainClient'
+const BRAIN_CLIENT_TOKEN_FILE_MAX_BYTES = 16_384
+const BRAIN_CLIENT_TOKEN_FILE_MODE = 0o600
+const FEEDBACK_COMMENT_MAX = 500
+const FEEDBACK_SCORE_MIN = 0
+const FEEDBACK_SCORE_MAX = 100
+const BRAIN_CLIENT_TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
+const FEEDBACK_INVOCATION_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const FEEDBACK_SCORE_PATTERN = /^(?:0|[1-9]\d{0,2})$/
 
 function asObject(value, label) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -112,12 +125,113 @@ export async function callOfficialSkill(context, operation, input) {
   return payload
 }
 
+export function feedbackCommandInput(args) {
+  const invocationId = requiredString(args[1], 'feedback invocation id')
+  if (!FEEDBACK_INVOCATION_PATTERN.test(invocationId)) {
+    throw new Error('feedback invocation id must be the UUID returned by a real skill response')
+  }
+  const scoreText = requiredString(args[2], 'feedback score')
+  if (!FEEDBACK_SCORE_PATTERN.test(scoreText)) {
+    throw new Error(`feedback score must be an integer between ${FEEDBACK_SCORE_MIN} and ${FEEDBACK_SCORE_MAX}`)
+  }
+  const score = Number(scoreText)
+  if (!Number.isInteger(score) || score < FEEDBACK_SCORE_MIN || score > FEEDBACK_SCORE_MAX) {
+    throw new Error(`feedback score must be between ${FEEDBACK_SCORE_MIN} and ${FEEDBACK_SCORE_MAX}`)
+  }
+  const userComment = args.slice(3).join(' ').trim()
+  if (!userComment) throw new Error('feedback comment is required')
+  if (userComment.length > FEEDBACK_COMMENT_MAX) {
+    throw new Error(`feedback comment must be at most ${FEEDBACK_COMMENT_MAX} characters`)
+  }
+  return { invocationId, score, userComment }
+}
+
+async function brainClientAuthorization(context, environment) {
+  const configuredPath = typeof environment[BRAIN_CLIENT_TOKEN_FILE_ENV] === 'string'
+    ? environment[BRAIN_CLIENT_TOKEN_FILE_ENV].trim() : ''
+  if (!configuredPath) throw new Error(`${BRAIN_CLIENT_TOKEN_FILE_ENV} is required`)
+  if (process.platform === 'win32' || typeof process.getuid !== 'function') {
+    throw new Error('Brain Client token file ownership cannot be verified')
+  }
+  const tokenFilePath = resolve(configuredPath)
+  const linkStatus = await lstat(tokenFilePath)
+  if (linkStatus.isSymbolicLink()) throw new Error('Brain Client token file cannot be a symlink')
+  const handle = await open(tokenFilePath, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const status = await handle.stat()
+    if (!status.isFile() || status.uid !== process.getuid()
+      || (status.mode & 0o777) !== BRAIN_CLIENT_TOKEN_FILE_MODE
+      || status.size < 1 || status.size > BRAIN_CLIENT_TOKEN_FILE_MAX_BYTES) {
+      throw new Error('Brain Client token file must be owned by the current user with mode 0600')
+    }
+    const tokenFile = asObject(JSON.parse(await handle.readFile('utf8')), 'Brain Client token file')
+    const expectedKeys = ['authorizationScheme', 'endpoint', 'schemaVersion', 'token']
+    if (Object.keys(tokenFile).sort().join('\n') !== expectedKeys.join('\n')) {
+      throw new Error('Brain Client token file contains unknown or missing fields')
+    }
+    const endpoint = new URL(requiredString(tokenFile.endpoint, 'Brain Client endpoint'))
+    if (tokenFile.schemaVersion !== BRAIN_CLIENT_TOKEN_FILE_VERSION
+      || tokenFile.authorizationScheme !== BRAIN_CLIENT_AUTH_SCHEME
+      || endpoint.origin !== new URL(context.endpoint).origin
+      || endpoint.pathname !== FEEDBACK_API_PATH || endpoint.search || endpoint.hash
+      || endpoint.username || endpoint.password
+      || !BRAIN_CLIENT_TOKEN_PATTERN.test(tokenFile.token)) {
+      throw new Error('Brain Client token file authority is invalid')
+    }
+    return `${BRAIN_CLIENT_AUTH_SCHEME} ${tokenFile.token}`
+  } finally {
+    await handle.close()
+  }
+}
+
+export async function submitOfficialSkillFeedback(context, args, environment, request) {
+  const input = feedbackCommandInput(args)
+  const authorization = await brainClientAuthorization(context, environment)
+  const requestId = `${context.runtimeCode}-${randomUUID()}`
+  let response
+  try {
+    response = await request(new URL(FEEDBACK_API_PATH, context.endpoint), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: authorization,
+      },
+      body: JSON.stringify({
+        requestId,
+        skillId: context.runtimeCode,
+        invocationId: input.invocationId,
+        score: input.score,
+        userComment: input.userComment,
+      }),
+      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+    })
+  } catch {
+    throw new Error('cli.tax feedback request failed')
+  }
+  let payload
+  try {
+    payload = asObject(await response.json(), 'cli.tax feedback response')
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('cli.tax feedback response')) throw error
+    throw new Error(`cli.tax feedback failed: non-JSON response (HTTP ${response.status})`)
+  }
+  if (!response.ok || payload.ok !== true) {
+    throw new Error(`cli.tax feedback failed: HTTP ${response.status}`)
+  }
+  if (payload.requestId !== requestId || typeof payload.id !== 'string'
+    || !FEEDBACK_INVOCATION_PATTERN.test(payload.id)
+    || typeof payload.duplicated !== 'boolean') {
+    throw new Error('cli.tax feedback response authority is invalid')
+  }
+  return { id: payload.id, requestId, duplicated: payload.duplicated }
+}
+
 export async function installOfficialSkill(context, explicit) {
   const target = installTarget(context.skillName, explicit)
   await mkdir(target, { recursive: true })
   const previous = readInstallMeta(target)
-  await copyFile(join(context.skillDir, 'SKILL.md'), join(target, 'SKILL.md'))
-  await copyFile(join(context.skillDir, 'skill.json'), join(target, 'skill.json'))
+  await rm(join(target, 'references'), { recursive: true, force: true })
+  await cp(context.skillDir, target, { recursive: true, force: true })
   const installed = asObject(JSON.parse(readFileSync(join(target, 'skill.json'), 'utf8')), 'installed skill.json')
   const installedVersion = requiredString(installed.version, 'installed skill.json version')
   await writeFile(join(target, INSTALL_META), `${JSON.stringify({
@@ -170,7 +284,6 @@ export function defaultUsage(context, extraLines) {
     '      Check whether the installed skill has a newer version.',
     `  npx ${context.npmName}@latest run`,
     '      Run the skill handshake: discover capabilities and collect intake answers.',
-    '',
     `Endpoint: ${context.endpoint}`,
   ]
   if (extraLines?.length) lines.push('', ...extraLines)
@@ -227,6 +340,10 @@ export async function dispatchOfficialSkillCli(options) {
     if (command === 'install') await installOfficialSkill(context, argument)
     else if (command === 'check') await checkOfficialSkill(context, argument)
     else if (command === 'run') await options.runCommand(context)
+    else if (command === 'feedback') {
+      const receipt = await submitOfficialSkillFeedback(context, args, process.env, fetch)
+      console.log(`${context.displayName} feedback accepted: ${receipt.id}`)
+    }
     else if (command === 'help' || command === '--help' || command === '-h') {
       console.log(options.usage ? options.usage(context) : defaultUsage(context, options.extraUsageLines))
     } else {

package/package.json

@@ -8,15 +8,19 @@
     "installer.mjs",
     "README.md",
     "skill/SKILL.md",
-    "skill/skill.json"
+    "skill/skill.json",
+    "skill/references/engine-meta-model.md",
+    "skill/references/formula-dsl.md",
+    "skill/references/declarative-pages.md",
+    "skill/references/import-ocr.md",
+    "skill/references/finance-example.md"
   ],
   "license": "UNLICENSED",
   "name": "cli-calctool",
-  "private": false,
   "repository": {
     "type": "git",
     "url": "https://github.com/88208555/calctool-clitax.git"
   },
   "type": "module",
-  "version": "7.0.7"
+  "version": "7.0.18"
 }

package/skill/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: calctool
-description: '按需生成「万能计算工具」：用户输入一个领域需求（如"我是财务，想要一个经营健康诊断工具"），本技能通过提问明确指标、公式、输入方式与输出形式，生成一个可执行、可验证、可发布的在线计算工具——支持自定义指标、自定义公式逻辑、用户上传内容自动识别（Excel 映射 / 图片 OCR）、报告输出。当用户想"把某套计算逻辑/指标/公式做成在线工具"时使用。 Generate a runnable, verifiable, publishable online calculator from a domain need, with custom metrics, formulas, and upload recognition (Excel mapping / image OCR). Use when the user wants to turn a calculation logic into an online tool. Создаёт работающий, проверяемый онлайн-калькулятор по потребности домена: пользовательские метрики, формулы и распознавание загрузок (Excel / OCR). Используйте, когда нужно превратить расчётную логику в онлайн-инструмент.'
+description: '按需生成确定性计算引擎与在线计算工具工程合同：支持显式 engineId、自定义指标和受控公式 AST。Excel 映射与图片 OCR 当前仅有声明式 Profile，执行器尚未接入；不得把声明当作已完成导入。Use for deterministic calculator engines with an explicit engineId and controlled formula AST. Excel/OCR execution is planned and not installed.'
 ---
 
 # calctool
 
+Package version: v7.0.18
+
 把「业务计算逻辑」编译为「可执行的在线计算工具」的生成器。
 
 ## 全链路总流程（老板视角 → 可运行工具）
@@ -26,8 +28,8 @@ description: '按需生成「万能计算工具」：用户输入一个领域需
 4. 编译工具（compile-tool）    —— 引擎定义 → 可运行工程文件清单
    （App 壳/公式引擎/存储/构建，页面自动生成：录入/指标卡/报告）
   ↓
-5. 环境适配（probe-env/adapt-config）—— 自动探测 Node 版本/包管理器/OS/架构，
-   Node≥18 全功能、16 兼容(sql.js)、<16 零构建预览；pnpm/yarn/npm 自动适配
+5. 环境适配（probe-env/adapt-config）—— 输出 Node/包管理器/OS/架构的声明性配置；
+   当前平台模板只在 Node≥18 + better-sqlite3 路径闭环，Node 16/sql.js 与 <16 预览执行器未安装
   ↓
 6. 完成前门禁（final-gate）      —— 审计/测试/运维三智能体协调接管检测，
    全部符合通过（engine-valid / 基准样例全通过 / 环境就绪）才标记完成
@@ -62,6 +64,18 @@ After `capabilities`, read `officialCatalog`. Default allowlist is official skil
 3. **显式除零**：所有除法必须选 `div`（除零报错）或 `safeDivide`（除零回退），不静默吞错。
 4. **零虚构**：能力未接入时保持"未接入态"（planned/not_installed/disconnected），不虚构数据、状态或按钮。
 
+## 能力状态（源码事实）
+
+| 编号 | 状态 | 当前边界 |
+|------|------|----------|
+| C1 engineId | implemented | `compile-inline`、`compile-tool` 与蜂群计划要求调用方显式传入合法 engineId；缺失或格式错误直接阻断，禁止从需求文本自动截取。 |
+| C2 final-gate 求值 | implemented-in-source | 公式基准样例由远端纯计算运行时真实求值，使用 BigInt coefficient + scale 的 28 位十进制定点实现；错误 expected（包括伪造 0）会阻断。公开端点需在版本资产同步后才获得本源码修复。 |
+| C3 Excel / OCR | planned / not-installed | `inputMethod` 与 `importProfiles` 只是引擎合同；当前没有 Excel 解析器或 OCR 执行器，不得宣称已自动导入。 |
+| C4 网页校验器 | planned / not-installed | 已有 `validate` API；尚无管理后台网页版粘贴校验器。 |
+| C5 SQLite 历史 | partial | 仓库内平台模板已通过本地 API 读写 better-sqlite3，计算历史不再使用 localStorage；`compile-tool` 仍只返回工程文件清单，实际模板落地依赖本地执行层。 |
+
+`final-gate` 的公式测试是远端真实执行；其中 Ops 项只检查调用方提供的环境探测与命令配置是否完整，**不会远程执行 install/run 命令**。需要命令执行证据时必须交给本地 runner 或独立 Validator。
+
 ## 五步实施流程
 
 ### 1. intake —— 收集需求（必须提问，一次一问）
@@ -75,7 +89,7 @@ After `capabilities`, read `officialCatalog`. Default allowlist is official skil
 
 ### 2. 生成引擎定义（Engine Definition）
 ```yaml
-engineId: <kebab-case-引擎名>
+engineId: <调用方显式提供的 kebab-case 引擎名，必填>
 name: <显示名>
 category: <领域，如 finance/operations/education>
 ownerType: platform-template
@@ -106,11 +120,11 @@ defaultLocale: zh-CN
 
 ### 5. 验收与发布
 - validate：确定性校验引擎定义（引用闭合、无环、单位一致、测试通过）
-- 上传识别走导入 Profile（Excel 映射 + OCR 草稿确认，自动导入先进草稿）
+- 上传识别当前只定义导入 Profile；Excel/OCR 执行器为 `planned/not_installed`，接入前不得生成自动导入成功结论
 - **完成前门禁（final-gate）**：每次项目完成之前，审计/测试/运维三智能体协调接管检测——
   - **审计智能体**：引擎定义确定性校验 0 findings、公式仅走受控 AST（禁 eval）、引用闭合
   - **测试智能体**：基准样例（testSuites）全部通过，一个不过都不放行
-  - **运维智能体**：环境探测成功、依赖分级适配、安装/启动命令可用、热更新就绪
+  - **运维智能体**：只对调用方提供的环境探测、依赖分级和命令配置做声明性检查；不远程执行安装/启动命令
   - 三智能体全部符合通过（gate passed）才标记完成；任一未通过返回 findings，修复后重新接管检测
 - 发布为版本化引擎，任何公式/字段/阈值变化都创建新版本，不原地修改
 - 输出：可运行的在线工具 + 引擎定义包 + 验收报告 + 完成前门禁结论
@@ -175,3 +189,16 @@ defaultLocale: zh-CN
 - 上传文件先验证类型/大小/指纹，OCR 结果进草稿不覆盖正式数据
 - 不虚构后端数据；未接入能力显示真实状态
 - 财务/税务输出需明确"经营估算模型，生产使用前由专业人员复核"
+
+## 反馈通道
+
+评价只能由 IDE / 智能体自动回传，严禁人类干预：
+
+1. 仅当一次真实技能 HTTP 调用成功，并且响应顶层包含 `feedbackInvocationId` 时，调用方才可进入评价流程。
+2. 调用方必须使用本次响应的原始 ID，按真实执行结果生成整数分数（0–100）和真实评语，再自动执行：
+   `npx cli-calctool@latest feedback <feedbackInvocationId> <score> <comment...>`
+3. 自动回传必须使用会员中心 Brain 客户端生成的同一身份文件，并通过 `CLITAX_BRAIN_CLIENT_TOKEN_FILE` 指向该 `0600` 文件；服务端以会员账号实名入库，不接受匿名评价。
+4. 禁止伪造、猜测、复用或跨调用转移 `feedbackInvocationId`；禁止让人类选择分数、填写评价或代为执行命令。
+5. 缺少会员客户端身份或 ID、分数越界、空评语、响应不合法及任何 HTTP 失败都必须视为回传失败，不得记为成功。
+
+日常交流走技能详情页的独立聊天通道，不使用 `feedback` 命令，也不计入评价、评分或首页跑马灯。

package/skill/references/declarative-pages.md

@@ -0,0 +1,38 @@
+# Calctool 声明式页面产物
+## `compile-tool` 输入
+
+`compile-tool` 是本地执行层操作。它接收 `input.engine`；未提供时，可从 `input.requirements` 构建引擎。引擎校验失败时返回 `status: blocked` 和 `findings`，不生成编译结果。
+
+## 当前页面清单
+
+成功编译后返回三个简化的声明项：
+
+1. `input`：`kind: form`，`fields` 为引擎字段 key 列表。
+2. `dashboard`：`kind: metrics`，`metrics` 为公式 key 列表。
+3. `report`：`kind: report`，当前没有更细的 section schema。
+
+这三项是文件落地层的输入清单，不是已渲染的网页。
+
+## 返回产物
+
+`compile-tool` 返回：
+
+- `status: compiled`、`engineId`、绿色 `validation`和引擎 `digest`；
+- `environment`：当前探测到的 tier、包管理器、Node 主版本、OS 和架构；
+- `pages`：上述三项页面清单；
+- `files`：`package.json`、引擎定义、App 壳、公式求值器、依赖图、存储、Vite 配置和 README 的路径/用途清单；
+- `commands`：环境适配后的 install、run 和 build 命令字符串。
+
+## 调用方职责
+
+运行时只返回清单和配置，不写文件、不安装依赖、不启动服务。本地 runner 必须按清单落地工程，再独立验证页面和命令。
+
+## 当前边界
+
+- 运行时尚无完整 `ApplicationPageSpec` JSON Schema。
+- `requirements.output` 会保存在引擎中，但当前不会改变固定的三页清单。
+- 报告分节、导出、历史页和可视化布局没有在此运行时实现，不得从 `kind` 字段推断它们已完成。
+
+## 实现依据
+
+`calctool-runtime.mjs` 的 `compile-tool` 分支是本文的权威来源。

package/skill/references/engine-meta-model.md

@@ -0,0 +1,38 @@
+# Calctool 引擎元模型
+## 适用范围
+
+当前引擎合同的 `schemaVersion` 是 `engine.spec/1`。它描述确定性计算的输入字段、公式 AST、验收样例和声明性页面/导入/报告信息；它不是任意 JavaScript 容器。
+
+## 顶层字段
+
+- `engineId`：调用方显式提供，匹配 `^[a-z0-9][a-z0-9._-]{0,127}$`；`compile-inline` 不会自动生成。
+- `name`、`category`、`semanticVersion`、`status`：显示名、领域、语义版本和草稿/发布状态。
+- `compatibilityProfile`、`decimalPolicy`、`defaultLocale`：当前构建器分别生成 `legacy-compatible`、`decimal-string`、`zh-CN`。
+- `inputMethod`、`output`、`constraints`：记录输入方式、期望输出和硬约束；是合同信息，不代表对应执行器已安装。
+
+## 集合
+
+- `fields`：字段目录。常用项为 `key`、`label`、`type`、`unit`、`required`、`description`。
+- `formulas`：公式目录。常用项为 `key`、`label`、`expression`；`expression` 是受控 JSON AST。
+- `rules`、`views`、`testSuites`：规则、视图和确定性样例。当前运行时要求它们为数组，但没有为 rule/view 定义完整 item schema。
+- `importProfiles`、`reports`：导入映射与报告声明。当前只保存数组，没有导入或报告执行器。
+
+## 构建路径
+
+### `compile-inline`
+
+`input.requirements` 必须包含 `goal`、`engineId`、非空 `inputs` 和非空 `formulas`。成功时返回 `revision`、`validation`、`artifacts`、`engine` 和 `nextStep`。当前构建器只把 `inputs` 与 `formulas` 带入引擎，并把 `rules`、`views`、`importProfiles`、`reports`、`testSuites` 初始化为空数组。
+
+### 蜂群合并
+
+`mergeSwarmArtifacts` 可把调用方收集的 `fields`、`formulas`、`rules`、`views`、`importProfiles`、`reports` 和 `testSuites` 合并为引擎，并记录 `runPlanRef` 与 `swarmProduced`。
+
+## 校验与错误
+
+`validate` 检查信封、必需数组、字段键重复、数值字段单位、公式表达式和引用闭合。失败返回 `status: blocked` 及结构化 `findings`。当前校验不证明依赖无环、单位推导或 rule/import/report 内部结构正确；这些不得写成已实现保证。
+
+`compile-inline` 会对最终引擎 JSON 生成 SHA-256 摘要，摘要用于识别本次产物，不代表外部签名或远端执行证明。
+
+## 实现依据
+
+`calctool-runtime.mjs` 的 `validateEngine`、`inspectCompileRequirements`、`buildEngine`、`mergeSwarmArtifacts` 和 `compile-inline` 分支是本文的权威来源。

package/skill/references/finance-example.md

@@ -0,0 +1,67 @@
+# 经营指标最小范例
+## 范例性质
+
+本文只演示当前 AST 和 `engine.spec/1` 如何组合，不是 Calctool 内置的财务模型，不提供行业阈值、税务结论或专业意见。当前运行时没有内置“50 字段 → 10 指标”领域包，不得把 intake 中的示例描述写成已交付功能。
+
+## 可验证引擎示例
+
+```json
+{
+  "schemaVersion": "engine.spec/1",
+  "engineId": "finance-health-demo",
+  "name": "经营指标演示",
+  "category": "finance",
+  "semanticVersion": "1.0.0",
+  "status": "draft",
+  "compatibilityProfile": "legacy-compatible",
+  "decimalPolicy": "decimal-string",
+  "defaultLocale": "zh-CN",
+  "inputMethod": "manual",
+  "output": ["metric-cards"],
+  "fields": [
+    { "key": "revenue", "label": "收入", "type": "money", "unit": "CNY", "required": true },
+    { "key": "cost", "label": "成本", "type": "money", "unit": "CNY", "required": true }
+  ],
+  "formulas": [
+    {
+      "key": "grossProfit",
+      "label": "毛利",
+      "expression": { "op": "sub", "args": [{ "ref": "revenue" }, { "ref": "cost" }] }
+    },
+    {
+      "key": "grossMarginPct",
+      "label": "毛利率",
+      "expression": { "op": "percentOf", "args": [{ "ref": "grossProfit" }, { "ref": "revenue" }] }
+    }
+  ],
+  "rules": [],
+  "views": [],
+  "importProfiles": [],
+  "reports": [],
+  "testSuites": [
+    {
+      "name": "基本样例",
+      "input": { "revenue": "100", "cost": "60" },
+      "expected": { "grossProfit": "40", "grossMarginPct": "40" }
+    }
+  ]
+}
+```
+
+## 验证流程
+
+1. 对完整引擎调用 `validate`，确认结构和引用闭合。
+2. 在本地 runner 的 `final-gate` 中执行样例。公式测试部分应得到 `grossProfit=40` 和 `grossMarginPct=40`。
+3. `final-gate` 还会检查引擎审计和调用方提供的环境配置；公式样例通过不等于整体门禁必然通过。
+
+## `compile-inline` 注意事项
+
+`compile-inline` 要求 `goal`、显式 `engineId`、非空 `inputs` 和非空 `formulas`，但当前构建器会把 `testSuites` 初始化为空数组。因此本文使用完整 `engine.spec/1` 展示基准样例；不应声称将此 JSON 改成 `requirements` 后会自动保留测试。
+
+## 业务边界
+
+毛利与毛利率仅是公式演示。真实生产口径、会计分类、税项、权重、阈值和报告结论必须由用户确认并经专业人员复核，不得由模型自行补全。
+
+## 实现依据
+
+`calctool-runtime.mjs` 的 intake 示例、`buildEngine`、`evaluateFormulaGraph` 和 `final-gate` 是本文的权威来源。

package/skill/references/formula-dsl.md

@@ -0,0 +1,43 @@
+# Calctool 公式 DSL
+## AST 节点
+
+公式只接受 JSON 节点，不执行 `eval`、`Function` 或主机 JavaScript。
+
+- 引用：`{ "ref": "fieldOrFormulaKey" }`
+- 字面量：`{ "lit": "12.34" }`
+- 运算：`{ "op": "add", "args": [...] }`
+
+被引用字段缺失、为 `null` 或空字符串时抛出 `MISSING_INPUT`。未知运算符抛出 `Unsupported operator`。
+
+## 已实现运算符
+
+| `op` | 语义 |
+|---|---|
+| `add` | 对 `args` 求和 |
+| `sub` | 第一个参数减第二个参数 |
+| `mul` | 对 `args` 求积 |
+| `div` | 除法；除数为零抛出 `DIV_ZERO` |
+| `safeDivide` | 除数为零时返回 `0`，否则执行除法 |
+| `percentOf` | 第一个参数 ÷ 第二个参数 × 100；没有除零回退 |
+| `round` | 将第一个参数四舍五入到 2 位小数 |
+| `if` | 第一个参数非零时求值第二个，否则求值第三个 |
+
+`case`、`sum`、`avg`、`lookup` 当前未在运行时实现，不得放入可用运算符清单。
+
+## Decimal 规则
+
+运行时用 BigInt coefficient + scale 表示十进制字符串，最多保留 28 位小数。输入接受带可选正负号的普通十进制形式，不接受 `NaN`、无穷值或科学计数法。运算结果以规范化字符串返回，避免通过 JavaScript `Number` 比较丢失精度。
+
+## 公式图与测试
+
+`evaluateFormulaGraph` 先递归求值公式对其他公式的引用，再把结果写入本次纯计算上下文。`final-gate` 读取 `testSuites[].input|inputs` 和 `expected|expect`，对公式结果做 Decimal 精确比较。无可运行样例、计算错误或期望值不匹配都会阻断门禁。
+
+## 当前边界
+
+- 依赖图求值器当前没有显式的“正在访问”集合，因此不得声称已做循环依赖证明。
+- 编译校验会检查表达式存在与引用闭合，但未在编译期枚举拒绝所有未支持 `op`。
+- 非对象节点当前会求值为 `0`；调用方必须提交完整 AST，不应依赖该行为。
+
+## 实现依据
+
+`calctool-runtime.mjs` 的 `DecimalStr`、`evaluateFormula`、`evaluateFormulaGraph` 和 `final-gate` 测试智能体是本文的权威来源。

package/skill/references/import-ocr.md

@@ -0,0 +1,32 @@
+# Calctool 导入与 OCR 边界
+## 当前能力状态
+
+Excel 和 OCR 当前是 `planned / not-installed`。Calctool 可记录导入方式和映射 Profile，但没有 Excel 解析器、OCR 执行器、文件上传处理或草稿确认流程。
+
+## 合同输入
+
+`capabilities` 对 `compile-inline` 声明的 `inputMethod` 枚举为：
+
+- `manual`
+- `excel`
+- `ocr`
+- `excel+ocr`
+
+引擎可含 `importProfiles` 数组。当前校验只检查它是数组，没有定义 Profile item 的列名、置信度、类型转换或错误行 schema，因此不应自行发明字段并宣称已受运行时验证。
+
+## 两条产物路径
+
+- `compile-inline` 会记录 `inputMethod`，但当前生成空 `importProfiles`。
+- 蜂群分解在需求命中 Excel/OCR/upload/导入/上传/识别时添加 `imports` 任务。该任务的目标是定义“Excel/OCR → 字段”映射，不会在 Calctool 运行时执行识别。
+
+## 未来执行器的最小验收点
+
+以后接入导入执行器时，至少应独立定义并验证：可接受文件类型/大小、字段映射、类型转换错误、OCR 原始结果与置信度、人工确认后才入正式数据、执行证据和失败回滚。这些是接入要求，不是当前已实现功能。
+
+## 错误与安全边界
+
+当前运行时不读上传文件，因此也不会返回解析或 OCR 错误。调用方不得把 `inputMethod` 或非空 `importProfiles` 当作导入成功证据，不得生成伪造的识别结果或成功状态。
+
+## 实现依据
+
+`calctool-runtime.mjs` 的 intake 问题、`validateEngine`、`decomposeRequirementsToRunPlan`、`buildEngine` 和 `mergeSwarmArtifacts` 是本文的权威来源。

package/skill/skill.json

@@ -1,10 +1,10 @@
 {
-  "description": "Calctool 按需生成可执行、可验证、可发布的在线计算工具。用户用一句话说明领域需求，例如财务经营健康诊断、报价测算或指标看板；技能通过对话逐项确认指标定义、公式逻辑、输入方式与输出形式，禁止把未确认的口径写成假完成。生成结果支持自定义指标、自定义公式，以及用户上传内容的自动识别：表格字段映射与图片文字识别，最终输出可复核的计算报告。调用顺序为 capabilities、intake、validate、compile-inline，校验未通过不得发布。密钥与模型若需要，一律在对话中由用户自行填写，平台不发放密钥、不代持免费额度，也不在描述里展示外部申请网址。工具必须能被再次运行，并在同一套规则下得到同一结论。公式、口径与样本数据全部可追溯；缺字段、映射失败或识别失败必须显式报错，不得用空表或占位数字冒充计算结果。发布前须完成确定性校验，未通过即停止。本技能面向真实交付：每一步都有输入、规则与失败面，禁止把加载中、超时或未知状态当成空成功。用户可见说明只讲能力与对话配置方式，不出现外链。调用前必须先走 capabilities，再按 nextStep 前进；必填项未回答不得进入下一操作。日志只保存必要元数据，密钥不得写入公开页面。",
+  "description": "Calctool 生成可验证的确定性计算引擎与在线工具工程合同。调用方必须显式提供 engineId；公式由受控 AST 与十进制定点运行时执行，final-gate 会真实计算基准样例并拒绝不一致结果。当前 Excel 映射和图片 OCR 仅定义 importProfiles 合同，执行器为 planned/not_installed；网页版校验器也尚未接入，禁止把这些能力描述成已完成。仓库平台模板的计算历史通过本地 SQLite API 持久化，但 compile-tool 仍需本地执行层落地工程文件。调用顺序为 capabilities、intake、validate、compile-inline；校验未通过不得发布，错误必须显式返回。",
   "displayName": "Calctool",
   "endpoint": "https://cli.tax/KKyA6xljUX",
   "method": "POST",
   "name": "calctool",
   "schemaVersion": "calctool.skill.request/1.0",
   "type": "Skill",
-  "version": "v7.0.7"
-}
+  "version": "v7.0.18"
+}