deterministic-calc-skill

Provides secure, sandboxed execution of mathematical expressions and code to deliver exact computation results without model guesswork.

Security Scan

The skill claims 'secure, sandboxed execution' for deterministic calculations but includes unsandboxed Python and shell execution plus arbitrary file I/O—this mismatch is risky and should be reviewed before use.

Purpose & Capability

The name/description focus on safe, sandboxed deterministic computation. The code provides a safe AST-based safe_eval (expected) but also exposes run_python (subprocess.run with python3 -c) and run_shell (subprocess.run with shell=True) plus read_file/write_file APIs. Those unsandboxed capabilities exceed the minimal needs of a 'deterministic calculator' and contradict the 'secure, sandboxed' claim.

Instruction Scope

SKILL.md documents and examples include read_file, write_file, run_python and run_shell usage. While the docs warn about risk, the runtime instructions and examples explicitly show how to perform arbitrary code execution and file operations, which broaden the scope to general remote code execution and filesystem access.

Install Mechanism

No install spec or external downloads are present; the package is distributed as source files in the skill bundle. No network fetches or archive extraction are attempted by an installer.

Credentials

The skill declares no required environment variables or credentials (appropriate for a math utility). However, because it lets callers run shell commands and read/write arbitrary file paths, it can be used to access local secrets or exfiltrate data even without explicit credential requests.

Persistence & Privilege

always:false and no code attempts to modify other skills or global agent settings. The included publish.sh can initialize a git repo and run a test invocation, but that script is for publishing and not part of runtime persistence.

What to consider before installing

This skill contains a safe AST-based evaluator (safe_eval) that is appropriate for deterministic math, but it also exposes run_python and run_shell which execute arbitrary code/commands on the host and file read/write functions. The README and SKILL.md acknowledge these risks, but the top-level description ('secure, sandboxed execution') is misleading. Before installing: (1) Treat run_python/run_shell as dangerous—do not enable them in production or on hosts with sensitive data. (2) If you need only deterministic math, restrict the skill's surface to safe_eval (and consider removing or disabling run_python/run_shell). (3) Run the skill in an isolated environment (container or sandbox) and limit agent permissions. (4) Review and vet the code (especially subprocess.run calls and file IO) and avoid granting the skill autonomous invocation for sensitive workflows. (5) If in doubt, ask the publisher for an explanation of their sandboxing guarantees or request a variant that lacks code/shell execution.

核心理念： 大模型擅长预测（猜），但不擅长确定性计算。本 Skill 将确定性计算固化为代码执行，避免模型"猜"结果。

---

🧠 问题背景

❌ 错误用法：让模型直接计算

用户：123456789 × 987654321 = ?
模型：（开始猜）大概是 121932631...（可能错）

✅ 正确用法：模型生成代码 → 执行 → 返回

用户：123456789 × 987654321 = ?
模型：（生成代码）print(123456789 * 987654321)
执行：121932631112635269
返回：正确答案

---

📦 安装

npx clawhub install deterministic-calc

---

🛠️ 可用函数

calculate(expression)

执行数学表达式计算。

参数：

• expression (string): 数学表达式

返回：

{
  "success": true,
  "expression": "123456789 * 987654321",
  "result": 121932631112635269
}

---

run_python(code)

执行 Python 代码并返回结果。

参数：

• code (string): Python 代码

返回：

{
  "success": true,
  "stdout": "121932631112635269\n",
  "stderr": "",
  "exit_code": 0
}

---

run_shell(command)

执行 Shell 命令并返回结果。

参数：

• command (string): Shell 命令

返回：

{
  "success": true,
  "stdout": "...",
  "stderr": "",
  "exit_code": 0
}

---

safe_eval(expression)

安全执行数学表达式（无代码注入风险）。

参数：

• expression (string): 数学表达式

返回：

{
  "success": true,
  "result": 42
}

---

📝 使用示例

数学计算

from deterministic_calc import calculate

result = calculate("123456789 * 987654321")
print(result["result"])  # 121932631112635269

复杂计算

from deterministic_calc import run_python

code = """
import math
result = sum(i**2 for i in range(1000))
print(result)
"""
result = run_python(code)
print(result["stdout"])  # 332833500

Shell 命令

from deterministic_calc import run_shell

result = run_shell("ls -la /tmp")
print(result["stdout"])

---

⚠️ 安全说明

• calculate() 和 safe_eval() 是沙箱安全的
• run_python() 和 run_shell() 可执行任意代码，需谨慎使用
• 生产环境建议只暴露 calculate() 和 safe_eval()

---

📄 License

MIT