cli-calctool 0.1.0

package/skills/calctool/platform-template/src/engine/evaluate.ts

@@ -0,0 +1,114 @@
+// calctool 公式引擎：JSON AST + decimal.js 确定性求值
+// 公式 DSL 规范见 references/formula-dsl.md
+import Decimal from 'decimal.js'
+
+export type FormulaNode =
+  | { ref: string }
+  | { lit: string | number }
+  | { op: string; args: FormulaNode[] }
+
+export type CalcError =
+  | { code: 'DIV_ZERO'; nodeId: string }
+  | { code: 'MISSING_INPUT'; fieldId: string }
+  | { code: 'NON_FINITE'; nodeId: string }
+
+export type EngineValues = Record<string, string | number | null>
+
+/** 安全除法：除数为 0 用 fallback（默认 0），与 div 报错区分 */
+function safeDiv(a: Decimal, b: Decimal, fallback = '0'): Decimal {
+  if (b.isZero()) return new Decimal(fallback)
+  return a.div(b)
+}
+
+/** 求值一个公式 AST 节点（纯函数，无副作用）
+ * 节点形态：{ ref: 'field' } 引用 / { lit: 1 } 字面量 / { op, args } 运算
+ */
+export function evaluate(node: FormulaNode, values: EngineValues): Decimal {
+  // 引用节点（无 op，只有 ref）
+  if ('ref' in node && node.ref !== undefined) {
+    const raw = values[node.ref]
+    if (raw === null || raw === undefined || raw === '') {
+      throw { code: 'MISSING_INPUT', fieldId: node.ref } as CalcError
+    }
+    return new Decimal(String(raw))
+  }
+  // 字面量节点（无 op，只有 lit）
+  if ('lit' in node && node.lit !== undefined) {
+    return new Decimal(String(node.lit ?? 0))
+  }
+  switch (node.op) {
+    case 'add':
+      return node.args.reduce((acc, arg) => acc.plus(evaluate(arg, values)), new Decimal(0))
+    case 'sub': {
+      const [a, b] = node.args
+      return evaluate(a, values).minus(evaluate(b, values))
+    }
+    case 'mul':
+      return node.args.reduce((acc, arg) => acc.times(evaluate(arg, values)), new Decimal(1))
+    case 'div': {
+      const [a, b] = node.args
+      const divisor = evaluate(b, values)
+      if (divisor.isZero()) throw { code: 'DIV_ZERO', nodeId: 'div' } as CalcError
+      return evaluate(a, values).div(divisor)
+    }
+    case 'safeDivide': {
+      const [a, b] = node.args
+      return safeDiv(evaluate(a, values), evaluate(b, values))
+    }
+    case 'percentOf': {
+      const [a, b] = node.args
+      return evaluate(a, values).div(evaluate(b, values)).times(100)
+    }
+    case 'round': {
+      const [a] = node.args
+      return evaluate(a, values).toDecimalPlaces(2)
+    }
+    case 'if': {
+      const [cond, thenNode, elseNode] = node.args
+      const v = evaluate(cond, values)
+      return v.isZero() ? evaluate(elseNode, values) : evaluate(thenNode, values)
+    }
+    default:
+      throw new Error(`Unsupported operator: ${node.op}`)
+  }
+}
+
+/** 从 AST 提取引用的字段 key（依赖图构建用） */
+export function extractRefs(node: FormulaNode | undefined): string[] {
+  if (!node) return []
+  if ('ref' in node && node.ref !== undefined) return [node.ref]
+  if ('lit' in node && node.lit !== undefined) return []
+  return (node.args ?? []).flatMap(extractRefs)
+}
+
+/** 按公式定义计算全部结果（含跨公式引用，安全除零） */
+export function evaluateEngine(
+  formulas: Array<{ key: string; expression: FormulaNode }>,
+  inputs: EngineValues,
+): Record<string, string> {
+  const values: EngineValues = { ...inputs }
+  const results: Record<string, string> = {}
+  const visited = new Set<string>()
+  const stack: string[] = []
+
+  const compute = (key: string) => {
+    if (visited.has(key)) return
+    if (stack.includes(key)) throw new Error(`Cycle detected: ${[...stack, key].join(' → ')}`)
+    const formula = formulas.find((f) => f.key === key)
+    if (!formula) return
+    stack.push(key)
+    const refs = extractRefs(formula.expression)
+    for (const ref of refs) {
+      if (formulas.some((f) => f.key === ref)) compute(ref) // 跨公式引用先算
+    }
+    const result = evaluate(formula.expression, values)
+    const str = result.toFixed(4).replace(/\.?0+$/, '')
+    values[key] = str
+    results[key] = str
+    stack.pop()
+    visited.add(key)
+  }
+
+  for (const f of formulas) compute(f.key)
+  return results
+}

package/skills/calctool/platform-template/src/engine-definition.json

@@ -0,0 +1,195 @@
+{
+  "engineId": "ecommerce-ops-dashboard",
+  "name": "电商运营仪表盘",
+  "semanticVersion": "1.0.0",
+  "category": "ecommerce",
+  "decimalPolicy": "decimal-string",
+  "fields": [
+    {
+      "key": "visitors",
+      "label": "访客数",
+      "type": "integer",
+      "unit": "人",
+      "required": true
+    },
+    {
+      "key": "orders",
+      "label": "订单数",
+      "type": "integer",
+      "unit": "单",
+      "required": true
+    },
+    {
+      "key": "gmv",
+      "label": "GMV",
+      "type": "money",
+      "unit": "CNY",
+      "required": true
+    },
+    {
+      "key": "adSpend",
+      "label": "广告费",
+      "type": "money",
+      "unit": "CNY",
+      "required": true
+    },
+    {
+      "key": "customRate",
+      "label": "自定义转化率修正",
+      "type": "percent",
+      "unit": "%"
+    }
+  ],
+  "formulas": [
+    {
+      "key": "conversionRate",
+      "label": "转化率",
+      "expression": {
+        "op": "safeDivide",
+        "args": [
+          {
+            "ref": "orders"
+          },
+          {
+            "ref": "visitors"
+          }
+        ]
+      }
+    },
+    {
+      "key": "aov",
+      "label": "客单价",
+      "expression": {
+        "op": "safeDivide",
+        "args": [
+          {
+            "ref": "gmv"
+          },
+          {
+            "ref": "orders"
+          }
+        ]
+      }
+    },
+    {
+      "key": "roas",
+      "label": "ROAS",
+      "expression": {
+        "op": "safeDivide",
+        "args": [
+          {
+            "ref": "gmv"
+          },
+          {
+            "ref": "adSpend"
+          }
+        ]
+      }
+    },
+    {
+      "key": "gmvPerVisitor",
+      "label": "访客价值",
+      "expression": {
+        "op": "safeDivide",
+        "args": [
+          {
+            "ref": "gmv"
+          },
+          {
+            "ref": "visitors"
+          }
+        ]
+      }
+    }
+  ],
+  "rules": [],
+  "views": [],
+  "testSuites": [
+    {
+      "name": "基准样例",
+      "inputs": {
+        "visitors": 10000,
+        "orders": 300,
+        "gmv": 50000,
+        "adSpend": 12000
+      },
+      "expect": {
+        "conversionRate": "3",
+        "aov": "166.6667",
+        "roas": "4.1667"
+      }
+    }
+  ],
+  "pipeline": {
+    "engineId": "ecommerce-ops-dashboard",
+    "nodes": [
+      {
+        "id": "input",
+        "kind": "input",
+        "label": "录入/导入",
+        "inputs": [],
+        "outputs": [
+          "validate"
+        ]
+      },
+      {
+        "id": "validate",
+        "kind": "validate",
+        "label": "数据校验",
+        "inputs": [
+          "input"
+        ],
+        "outputs": [
+          "compute"
+        ]
+      },
+      {
+        "id": "compute",
+        "kind": "compute",
+        "label": "确定性计算",
+        "inputs": [
+          "validate"
+        ],
+        "outputs": [
+          "store",
+          "output"
+        ]
+      },
+      {
+        "id": "store",
+        "kind": "store",
+        "label": "数据存储",
+        "inputs": [
+          "compute"
+        ],
+        "outputs": [
+          "output"
+        ]
+      },
+      {
+        "id": "output",
+        "kind": "output",
+        "label": "指标卡/报告",
+        "inputs": [
+          "compute",
+          "store"
+        ],
+        "outputs": []
+      },
+      {
+        "id": "automate",
+        "kind": "automate",
+        "label": "自动化（可选）",
+        "inputs": [
+          "store"
+        ],
+        "outputs": [
+          "output"
+        ],
+        "config": {
+          "enabled": false
+        }
+      }
+    ]
+  }
+}

package/skills/calctool/platform-template/src/main.tsx

@@ -0,0 +1,13 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { ConfigProvider } from 'antd'
+import zhCN from 'antd/locale/zh_CN'
+import App from './App'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ConfigProvider locale={zhCN}>
+      <App />
+    </ConfigProvider>
+  </React.StrictMode>,
+)

package/skills/calctool/platform-template/src/pipeline.ts

@@ -0,0 +1,80 @@
+// calctool 链路编排：整套工具 = 联通节点（非单页孤岛）
+// 定义数据如何在节点间流动：输入 → 校验 → 计算 → 存储 → 输出 → 自动化
+// 节点可增删改，链路随之更新 —— 后期改工具只动这里，不改页面
+
+import type { FormulaNode } from './engine/evaluate'
+
+export type PipelineNodeKind =
+  | 'input'          // 数据输入（表单/导入）
+  | 'validate'       // 校验（必填/类型/范围）
+  | 'compute'        // 确定性计算（公式引擎）
+  | 'store'          // 数据存储（持久化）
+  | 'output'         // 输出（指标卡/报告/导出）
+  | 'automate'       // 自动化（触发器/定时/通知）
+
+export type PipelineNode = {
+  id: string
+  kind: PipelineNodeKind
+  label: string
+  inputs: string[]        // 上游节点 id
+  outputs: string[]       // 下游节点 id
+  config?: Record<string, unknown>
+}
+
+export type Pipeline = {
+  engineId: string
+  nodes: PipelineNode[]
+  // 数据流：input -> validate -> compute -> store -> output (+ automate)
+}
+
+/** 默认链路：整套工具的骨架（模块联通，非孤岛） */
+export function defaultPipeline(engineId: string): Pipeline {
+  return {
+    engineId,
+    nodes: [
+      { id: 'input', kind: 'input', label: '录入/导入', inputs: [], outputs: ['validate'] },
+      { id: 'validate', kind: 'validate', label: '数据校验', inputs: ['input'], outputs: ['compute'] },
+      { id: 'compute', kind: 'compute', label: '确定性计算', inputs: ['validate'], outputs: ['store', 'output'] },
+      { id: 'store', kind: 'store', label: '数据存储', inputs: ['compute'], outputs: ['output'] },
+      { id: 'output', kind: 'output', label: '指标卡/报告', inputs: ['compute', 'store'], outputs: [] },
+      { id: 'automate', kind: 'automate', label: '自动化（可选）', inputs: ['store'], outputs: ['output'], config: { enabled: false } },
+    ],
+  }
+}
+
+export type FieldDef = {
+  key: string
+  label: string
+  type: 'number' | 'integer' | 'money' | 'percent' | 'text' | 'date' | 'enum'
+  unit?: string
+  required?: boolean
+}
+
+export type FormulaDef = {
+  key: string
+  label: string
+  expression: FormulaNode
+}
+
+export type EngineDefinition = {
+  engineId: string
+  name: string
+  semanticVersion: string
+  category: string
+  decimalPolicy: string
+  fields: FieldDef[]
+  formulas: FormulaDef[]
+  rules: unknown[]
+  pipeline: Pipeline
+}
+
+/** 在链路中找节点的上下游（改工具时定位影响范围） */
+export function nodeNeighbors(pipeline: Pipeline, nodeId: string) {
+  const node = pipeline.nodes.find((n) => n.id === nodeId)
+  if (!node) return null
+  return {
+    node,
+    upstream: pipeline.nodes.filter((n) => node.inputs.includes(n.id)),
+    downstream: pipeline.nodes.filter((n) => n.inputs.includes(nodeId)),
+  }
+}

package/skills/calctool/platform-template/src/store.ts

@@ -0,0 +1,53 @@
+// calctool 存储层：数据持久化
+// 默认 localStorage（零依赖，任何环境可用）；Node 全功能模式可换 better-sqlite3
+export type ToolRecord = {
+  id: string
+  engineId: string
+  inputs: Record<string, string | number>
+  results: Record<string, string>
+  createdAt: string
+  updatedAt: string
+}
+
+const KEY_PREFIX = 'calctool:record:'
+
+export class ToolStore {
+  constructor(private readonly engineId: string) {}
+
+  list(): ToolRecord[] {
+    if (typeof localStorage === 'undefined') return []
+    const records: ToolRecord[] = []
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i)
+      if (key?.startsWith(`${KEY_PREFIX}${this.engineId}:`)) {
+        try {
+          records.push(JSON.parse(localStorage.getItem(key) ?? 'null'))
+        } catch { /* 跳过损坏记录 */ }
+      }
+    }
+    return records.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+  }
+
+  save(inputs: Record<string, string | number>, results: Record<string, string>): ToolRecord {
+    const now = new Date().toISOString()
+    const record: ToolRecord = {
+      id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+      engineId: this.engineId,
+      inputs, results, createdAt: now, updatedAt: now,
+    }
+    if (typeof localStorage !== 'undefined') {
+      localStorage.setItem(`${KEY_PREFIX}${this.engineId}:${record.id}`, JSON.stringify(record))
+    }
+    return record
+  }
+
+  clear(): void {
+    if (typeof localStorage === 'undefined') return
+    const keys: string[] = []
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i)
+      if (key?.startsWith(`${KEY_PREFIX}${this.engineId}:`)) keys.push(key)
+    }
+    keys.forEach((k) => localStorage.removeItem(k))
+  }
+}

package/skills/calctool/platform-template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"]
+}

package/skills/calctool/platform-template/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: { port: 5173, host: true },
+})

package/skills/calctool/references/declarative-pages.md

@@ -0,0 +1,69 @@
+# 声明式页面规格系统
+
+把"信息型页面"从代码降级为**数据声明**，用通用渲染器渲染几十个页面，避免复制粘贴页面结构。这是生成工具页面的核心机制。
+
+## 1. 规格 Schema
+
+```ts
+interface ApplicationPageSpec {
+  title: string;
+  description?: string;
+  tabs?: TabSpec[];
+  actions?: ActionSpec[];       // 页头操作（default|primary|danger）
+  sections?: SectionSpec[];     // 内容分区
+}
+
+interface SectionSpec {
+  layout: 'rows' | 'grid' | 'table' | 'steps';
+  rows?: RowSpec[];             // 标签/值/说明/状态/行内操作
+  metrics?: MetricSpec[];       // 指标卡
+  columns?: ColumnSpec[];
+  data?: (string | number)[][]; // 表格数据
+  empty?: EmptyStateSpec;       // 空状态（标题/说明/操作）
+}
+```
+
+## 2. 注册与路由匹配
+
+- 规格文件按域拆分（core/settings/management/finance/studio/supplementary），每份是 `Record<string, ApplicationPageSpec>` + 路由映射
+- 支持参数化路由：`/tools/:toolId/runs/:runId`、`/automations/:automationId/edit`
+- 匹配算法：按路径段数**从长到短**排序 → 逐段精确匹配（`:` 前缀为参数位）→ 命中后提取 params → `encodeURIComponent` 回填规格内 `href`
+
+## 3. 渲染器
+
+`ApplicationPageSpec → 通用构建块组件树`：
+
+```
+PageShell（内容 768px）
+  → PageHeader（标题/说明/操作）
+  → SectionCard × N（分区）
+    → 按 layout 分发：
+      rows   → SettingRow 行
+      grid   → 网格卡
+      table  → 表格
+      steps  → 步骤条
+      empty  → EmptyState
+```
+
+- 无 `href` 的操作自动 `disabled`——保证"未接入"按钮不产生假交互
+- 所有构建块来自共享组件（PageShell/PageHeader/SectionCard/SettingRow/EmptyState/StatGrid/PageList/Toolbar），页面只提供数据
+- 单文件 ≤ 1000 行（审计脚本强制），接近上限必须拆分
+
+## 4. 生成工具时的页面映射
+
+| 工具模块 | 页面规格 |
+|---|---|
+| 录入表单 | 字段目录 → 自动生成 rows/grid 表单（含必填/类型/单位） |
+| 指标卡 | 公式结果 → metrics 数组（StatGrid） |
+| 专题工具 | 每个专题 → 独立 SectionCard（增值税/盈亏平衡/定价/利润率优化） |
+| 历史记录 | table 布局 + 分页 |
+| 诊断报告 | 指标卡 + 表格 + 诊断结论 + 建议 |
+| 空状态 | 无数据时 EmptyState（不虚构装饰图标） |
+
+## 5. 硬约束（从工具项目继承）
+
+- 正文内容容器统一 768px（与 Composer 同宽），窄屏等比收窄，禁止按页面类型自由设宽
+- 禁内联 style、禁硬编码颜色、禁阴影
+- 图标统一 Lucide、14px、描边 2
+- 空页面不显示装饰图标，不虚构状态/数据/提示/按钮
+- 能拆成组件的内容禁止堆积在页面文件中

package/skills/calctool/references/engine-meta-model.md

@@ -0,0 +1,123 @@
+# 引擎元模型（Engine Meta-Model）
+
+一个可发布、可运行、可验收的"计算工具"= 一份**引擎定义**。本文件规定引擎定义的结构与约束。
+
+## 1. 顶级对象
+
+```ts
+interface EngineDefinition {
+  id: string;                    // kebab-case 稳定机器标识
+  name: string;                  // 中文显示名，可改
+  semanticVersion: string;       // 语义版本，发布后不可原地修改
+  status: 'draft' | 'review' | 'published' | 'retired';
+  compatibilityProfile?: string; // 如 legacy-compatible（复现旧口径）
+  decimalPolicy: 'decimal-string' | 'source-compatible-float';
+  inputSchema: JsonSchema;       // 输入校验
+  fields: FieldDefinition[];     // 字段目录
+  tables: TableDefinition[];     // 表格定义（如成本结构表）
+  dimensions: DimensionDefinition[]; // 维度（公司/部门/周期）
+  entities: EntitySchemaDefinition[]; // 实体
+  relations: RelationDefinition[];    // 关系
+  choiceSources: ChoiceSourceDefinition[];
+  interactionRules: InteractionRuleDefinition[];
+  formulas: FormulaDefinition[]; // 公式图
+  rules: RuleDefinition[];       // 规则包（阈值/评分/分级）
+  views: ViewDefinition[];       // 视图
+  documents: MarkdownDocumentDefinition[]; // Markdown 说明/报告
+  approvalPolicyRefs: string[];
+  importProfiles: ImportProfile[]; // 导入映射
+  reports: ReportDefinition[];   // 报告模板
+  outputs: OutputContract[];     // 输出契约（跨引擎引用用）
+  permissions: EnginePermissionPolicy;
+  testSuites: EngineTestSuite[]; // 确定性测试
+  migrationFrom?: EngineMigration[];
+}
+```
+
+**铁律**：
+- `id` 与字段 `key` 是稳定机器标识；中文标签可以改，ID 不改
+- 所有引用用 ID，不用页面标题或表格坐标作主键
+- 发布版本不可原地修改；运行记录绑定精确的 `engineVersionId`
+- 跨引擎只允许引用对方声明的输出契约
+
+## 2. 字段类型
+
+```text
+number, money, percent, integer, text, richText, boolean,
+date, dateTime, enum, singleSelect, multiSelect, dimensionRef,
+entityRef, file, image, object, repeatGroup, table, reference, derived
+```
+
+每个数值字段至少含：
+- `key`（稳定 ID）、`label`（中文标签）、`type`
+- `required` / `defaultValue`
+- `precision` / `rounding`（金额、比例、整数分别定义）
+- `unit`（如 CNY、CNY/person、%）
+- 枚举字段含 `choiceSourceRef`
+
+## 3. 公式定义
+
+```ts
+interface FormulaDefinition {
+  key: string;
+  label: string;
+  type: 'derived' | 'score' | 'aggregate' | 'lookup';
+  expression: FormulaAst;        // 编译后的 AST（见 formula-dsl.md）
+  source?: string;               // 可读字符串（仅编辑用，保存必须 AST）
+  outputUnit?: string;
+  description?: string;
+}
+```
+
+## 4. 规则包（Rule Pack）
+
+```ts
+interface RuleDefinition {
+  id: string;
+  name: string;
+  kind: 'threshold' | 'scoring' | 'grading' | 'validation';
+  // 阈值：区间 → 级别
+  // 评分：指标值 → 0-100 分（可曲线/分段）
+  // 分级：总分 → 健康等级（如 优/良/中/差）
+  inputs: string[];              // 引用字段/公式 key
+  evaluation: RuleAst;           // 条件 AST
+}
+```
+
+## 5. 导入 Profile
+
+```ts
+interface ImportProfile {
+  id: string;
+  kind: 'excel' | 'ocr' | 'manual';
+  sourceFormat: string;          // Excel 列 / OCR 字段布局
+  mapping: { source: string; targetField: string; transform?: string }[];
+  verification: 'draft' | 'auto'; // 自动导入先进草稿
+}
+```
+
+## 6. 报告模板
+
+```ts
+interface ReportDefinition {
+  id: string;
+  name: string;
+  sections: ReportSection[];
+  // 指标卡 / 表格 / 诊断结论 / 历史分位 / 建议
+}
+```
+
+## 7. 版本与迁移
+
+- `1.x legacy-compatible`：复现原工具结果（保留旧公式、边界、取整）
+- `2.x corrected`：修正数据质量问题（通过显式迁移发布，绝不静默改变旧运行）
+- 任何公式/字段/阈值/导入映射/报告变化 → 新版本
+
+## 8. 引擎状态机（能力接入）
+
+```text
+planned → not_installed → disconnected → configuring
+  → pending_verification → connected → disabled | unavailable
+```
+
+健康状态 `healthy/degraded/failed/unknown` **只在真实连接与探针后出现**；客户端不能提交健康状态。