cli-calctool 1.0.0 → 1.0.2

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

@@ -1,195 +0,0 @@
-{
-  "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

@@ -1,13 +0,0 @@
-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

@@ -1,80 +0,0 @@
-// 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

@@ -1,53 +0,0 @@
-// 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

@@ -1,15 +0,0 @@
-{
-  "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

@@ -1,7 +0,0 @@
-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

@@ -1,69 +0,0 @@
-# 声明式页面规格系统
-
-把"信息型页面"从代码降级为**数据声明**，用通用渲染器渲染几十个页面，避免复制粘贴页面结构。这是生成工具页面的核心机制。
-
-## 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

@@ -1,123 +0,0 @@
-# 引擎元模型（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` **只在真实连接与探针后出现**；客户端不能提交健康状态。

package/skills/calctool/references/finance-example.md

@@ -1,132 +0,0 @@
-# 范例：经营健康诊断引擎（finance-health-diagnosis）
-
-完整走通「50 输入字段 → 归类 → 利润 → 十大指标评分 → 健康度 → 报告」的引擎定义范例。这是 calctool 的 reference implementation：任何新工具都可对照此结构生成。
-
-## 1. 引擎身份
-
-```yaml
-engineId: finance-health-diagnosis
-name: 经营健康诊断
-category: finance
-ownerType: platform-template
-status: published
-semanticVersion: 1.0.0
-compatibilityProfile: legacy-compatible
-decimalPolicy: decimal-string
-defaultCurrency: CNY
-defaultLocale: zh-CN
-schemaVersion: engine-spec/1
-```
-
-版本族：`1.x legacy-compatible`（复现原工具）；`2.x corrected`（修正财务口径，显式迁移发布）。
-
-## 2. 六层计算链路
-
-```
-输入层：利润表 50 个基础字段（货品成本、账单/订单/流量费用、薪酬、仓储…）
-  → 归类层：商品成本 / 账单费用 / 订单费用 / 流量费用 / 薪酬 / 仓储费用
-  → 利润层：GSV / 运营毛利 GP_oper / 管理费用 / 税前净利润 NP / 占比
-  → 诊断层：十大指标 / 动态阈值 / 单项得分 / 健康等级 / 加权健康度
-  → 专题层：增值税 / 盈亏平衡 / 私域复购 / 单品定价 / 利润率优化
-  → 展示层：历史分位 / 诊断重点 / HTML 报告 / 历史记录 / OGSM 执行方案
-```
-
-## 3. 十大指标权重（默认）
-
-| 指标 | 权重 |
-|---|---:|
-| 定价倍数 | 30% |
-| GSV | 17% |
-| 薪酬效率 | 15% |
-| GSV 人效 | 5% |
-| 毛利人效 | 5% |
-| 净利人效 | 5% |
-| 增值税率 | 10% |
-| 人均办公费用 | 3% |
-| 仓储费用占比 | 5% |
-| 单件发货成本 | 5% |
-
-## 4. 通用评分曲线（0-100）
-
-高值更优：
-```text
-S_high(A;P,E) = clamp(60 + 30 × (A-P)/(E-P), 0, 100)
-```
-
-低值更优（E < P，斜率自然为负）：
-```text
-S_low(A;P,E) = clamp(60 + 30 × (A-P)/(E-P), 0, 100)
-```
-
-带盈亏点的分段函数（定价倍数、GSV）：
-```text
-若 A < B： S_break = clamp(round(30 + 30 × (A-B)/(P-B)), 0, 100)
-否则：     S_break = clamp(round(60 + 30 × (A-P)/(E-P)), 0, 100)
-```
-（B=盈亏平衡，P=合格，E=优秀）
-
-## 5. 分数等级
-
-| 分数 | 等级 |
-|---:|---|
-| 非有限/空 | 需要优化成本结构而非数值 |
-| <60 | 危险 |
-| 60-<70 | 合格 |
-| 70-<80 | 良好 |
-| 80-<90 | 优秀 |
-| >=90 | 卓越 |
-
-## 6. 指标定义（当前值公式 + 目标 + 样例）
-
-| 指标 | 公式 | 合格/良好/优秀 | 样例分 |
-|---|---|---|---|
-| 定价倍数 | `S / 货品成本` | 动态阈值 | 63 |
-| GSV | `S` | 动态 | 63 |
-| 薪酬效率 | `GP_oper / 薪酬福利` | 2.0 / 2.5 / 3.0 | 71 |
-| GSV 人效 | `S / 正式员工数` | 100k / 120k / 150k | 60 |
-| 毛利人效 | `GP_oper / 正式员工数` | 17k / 20.4k / 25.5k | 61 |
-| 净利人效 | `NP / 正式员工数` | 5k / 6k / 7.5k | 64 |
-| 增值税率 | `C_tax / S` | 综合税率×1.0/0.9/0.8 | 38.4 |
-| 人均办公费用 | `办公费用 / 正式员工数` | 1,600 / 1,200 / 800 | 63.75 |
-| 仓储费用占比 | `仓储费用 / S` | 4.0% / 3.5% / 3.0% | 63 |
-| 单件发货成本 | `仓储费用 / 真实发货单量` | 1.80 / 1.60 / 1.40 | 76.5 |
-
-动态定价倍数阈值：
-```text
-c = 货品成本 / S
-n = 当前税前净利率
-盈亏倍数 B = 1 / (c + n)
-合格倍数 P = 1 / (c + n - 5%)
-```
-
-## 7. 总健康分
-
-- 加权：`总分 = Σ(指标分 × 权重)`，保留 2 位小数
-- 样例：62.2362（健康）
-- 历史百分位：程序按当前版本重算每条历史记录的十大指标，与全站用户样本比较
-
-## 8. 引擎定义产物（calctool 生成模板）
-
-```
-finance-health-diagnosis/
-├── manifest.yaml           # 引擎身份（见 §1）
-├── field-catalog.json      # 50 个输入字段 + 10 个派生指标
-├── scope-dimensions.json   # 公司 / 周期 维度
-├── formula-graph.json      # 六层公式图（§2）
-├── rule-packs.json         # 权重 + 评分曲线 + 等级（§3-5）
-├── import-profiles.json    # Excel 单元格映射 + OCR 字段映射
-├── report-template.json    # 指标卡 + 表格 + 诊断结论 + 建议
-└── tests/                  # 样例复算（健康分 62.2362 等）
-```
-
-## 9. 导入映射要点
-
-- 原工具为 Excel 导入：F 列单元格映射到字段目录，配置表覆盖顺序以算法主文档为准
-- 原生表格确定性解析，不做 OCR；截图/扫描件走 OCR + 人工草稿确认
-- 所有自动导入先进入草稿，人工确认后才写正式数据
-
-## 10. 生产注意事项
-
-- 增值税模块属于经营估算模型，生产使用前必须由持证财税人员复核
-- 本引擎复现的是当前产品口径，不代表会计准则、税法意见或税务筹划建议
-- 模型（Hermes/MiMo/OCR）只生成候选、草稿和解释，不能替代已发布确定性引擎给出正式财务数字