lingshu-solver 1.0.0

package/LICENSE

@@ -0,0 +1,206 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   ----------------------------------------------------------------------------
+
+   Copyright 2026 广州OPC（红尘灵境）
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE.md

@@ -0,0 +1,53 @@
+# 灵数求解器 软件许可协议（草稿 / DRAFT）
+
+> ⚠️ **本文件为法律文件草稿，须经执业律师复核并定稿后方可采用。** 以下是文本模板与条款框架，不代表已生效的法律意见。
+
+**软件名称**：灵数求解器（Lingshu Solver）
+**著作权人**：红尘灵境数字科技有限公司（以下简称"权利人"）
+**版本**：本仓库当前版本
+
+---
+
+## 1. 许可授予
+权利人在遵守本协议的条件下，授予使用者一项**有限的、非独占的、不可转让的、可撤销的**使用权，允许使用者：
+1. 在自有设备上安装、运行本软件（包括但不限于单文件 HTML 形态）；
+2. 为内部研究、教学、工程计算目的使用本软件的输出结果；
+3. 在保留本协议全部内容的前提下，复制并分发本软件的原始未修改副本。
+
+## 2. 使用限制
+未经权利人书面许可，使用者**不得**：
+1. 对本软件进行反向工程、反编译或试图提取源代码（为互操作目的的法律例外除外）；
+2. 移除或遮盖本软件中的著作权、商标或许可声明；
+3. 将本软件用于再许可、出租、托管为对外服务（SaaS）而未另行签约；
+4. 将本软件或其输出用于**安全攸关（safety-critical）场景**（定义见第 6 条）。
+
+## 3. 知识产权
+本软件及其全部源代码、算法、文档、界面设计的著作权及相关知识产权均归权利人所有。本协议不授予任何明示或暗示的专利权许可。
+
+## 4. 无担保（AS IS）
+本软件按"现状"提供，**不附任何明示或暗示担保**，包括但不限于对**适销性、特定用途适用性、不侵权、结果准确性、结果完备性**的担保。权利人明确声明：
+- 在给定计算预算内，本软件采用保守区间算术以尽量确保所有真解被包含于输出集合；
+- 当计算资源（盒子数、分支预算、迭代次数）耗尽时，结果可能不完整，并将以 `truncated` / `UNKNOWN` 等状态字段显式标记；
+- 使用者须自行验证输出是否满足其应用场景的精度与完备性要求。
+
+## 5. 责任限制
+在任何情况下，权利人对因使用或无法使用本软件所导致的**间接、偶然、特殊、后果性损害**（包括利润损失、数据损失、业务中断）不承担责任。权利人的累计赔偿责任不超过使用者为获取本软件所支付的对价（若免费获取，则上限为零）。
+
+## 6. 禁止安全攸关用途
+本软件**不得**用于任何安全攸关、生命健康、重大财产或公共利益攸关的场景，包括但不限于：
+- 交通工具（汽车、航空、轨道交通）的控制或认证；
+- 医疗器械、诊断或治疗决策；
+- 工业控制系统、 nuclear/能源关键设施；
+- 任何若结果错误可能导致人身伤害或重大损失的用途。
+
+在上述场景中使用本软件，须改用经独立功能安全认证（如 ISO 26262 / IEC 61508）的专用版本，并取得权利人书面授权。在本协议签署时，**安全版本尚未通过前述认证**，故本条禁止具有现实约束力。
+
+## 7. 终止
+违反本协议任何条款，本许可自动终止，使用者须删除所有副本。
+
+## 8. 适用法律与争议解决
+本协议受中华人民共和国法律管辖。因本协议产生的争议，提交权利人所在地有管辖权的人民法院诉讼解决。
+
+---
+
+*草稿版本 v0.1 — 待执业律师复核。*

package/README.md

@@ -0,0 +1,236 @@
+# 灵数求解器 · Lingshu Solver
+
+[![License](https://img.shields.io/github/license/genesis-plan/lingshu-solver)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/genesis-plan/lingshu-solver?style=social)](https://github.com/genesis-plan/lingshu-solver/stargazers)
+[![Last Commit](https://img.shields.io/github/last-commit/genesis-plan/lingshu-solver)](https://github.com/genesis-plan/lingshu-solver/commits)
+[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-blue)](https://modelcontextprotocol.io)
+[![Deterministic](https://img.shields.io/badge/core-deterministic%20%2F%20non--LLM-green)](https://genesis-plan.github.io/lingshu-solver/)
+
+> **确定性**实数方程组求解引擎 · 面向 AI 智能体与普通用户的 MCP 工具
+> 同样的题永远得到同样的答案，没有大模型的随机与幻觉，每个解都能回代验证。免费、网页打开即用、也能被 AI 智能体直接调用。
+
+灵数求解器（代号 Epsilon，V4.1）是一个**离线、确定性、零数据**的实数方程组求解器，
+覆盖 ≤6 个变量、实数解、轻量数值定位。它不要求用户提供初值，采用区间算术做保守收缩 +
+Krawczyk 算子做解认证，并尽力穷尽多解。
+
+👉 **给用户看的产品介绍（大白话，帮你看懂它能干嘛、适不适合你）**：[点这里](intro.html) ｜ [国内 COS 在线版](https://hclj-1409755229.cos.ap-guangzhou.myqcloud.com/lingshu-solver/intro.html)
+
+---
+
+## 🚀 快速上手（30 秒）
+
+### 如果你完全不懂技术 —— 直接用网页版
+**打开这个链接就能用，不用安装任何东西：**
+👉 **https://genesis-plan.github.io/lingshu-solver/** （GitHub Pages，海外/通用）
+
+**国内用户（更快，腾讯云 COS 托管）：**
+👉 **https://hclj-1409755229.cos.ap-guangzhou.myqcloud.com/lingshu-solver/index.html**
+
+在输入框写方程（例如 `x^2 + y^2 = 25` 和 `x + y = 7`），点求解即可。
+页面里有 6 个示例按钮，点一下就知道它能解什么。
+
+### 如果你是 AI 用户（Claude / Cursor / Cline 等）
+
+**方式 A · 远程托管（零安装，免密即用）**
+我们已部署常驻公网服务，直接填 URL 即可，无需本机装 Node：
+```json
+{
+  "mcpServers": {
+    "lingshu-solver": {
+      "url": "http://159.75.154.206:3000/mcp"
+    }
+  }
+}
+```
+> 端点：`http://159.75.154.206:3000/mcp`（Streamable HTTP）。服务运行于腾讯云轻量服务器，开机自启、崩溃自动拉起。
+> ⚠️ 当前为**裸 IP + HTTP 临时端点**，`hongchenlingjing.com` 备案通过后我们将切换为 `https://hongchenlingjing.com/mcp` 固定 HTTPS 域名（届时更新此处）。此临时端点可用于对接测试，Smithery 等需 HTTPS 的平台待备案后正式接入。
+
+**方式 B · 本地 stdio（需本机 Node）**
+```json
+{
+  "mcpServers": {
+    "lingshu-solver": {
+      "command": "npx",
+      "args": ["-y", "lingshu-solver"]
+    }
+  }
+}
+```
+> `npx` 版需本包发布到 npm 后可用；npm 账号已就绪，即将发布，发布后即可一键 `npx -y lingshu-solver`。在此之前可先 `git clone` 后用方式 C。
+
+**方式 C · 本地 clone + 指定路径**
+```bash
+git clone https://github.com/genesis-plan/lingshu-solver.git
+cd lingshu-solver
+node mcp-server.js
+```
+MCP 配置：
+```json
+{ "mcpServers": { "lingshu-solver": { "command": "node", "args": ["本地绝对路径/灵数求解器/mcp-server.js"] } } }
+```
+
+### 如果你是开发者
+```bash
+git clone https://github.com/genesis-plan/lingshu-solver.git
+cd lingshu-solver
+node mcp-server.js        # 启动 MCP 服务端
+node test/regression.js   # 跑回归测试（28 用例）
+```
+
+---
+
+本仓库包含：
+- `index.html` —— 单文件产品（浏览器内 UI + 已验证核心脚本 `<script id="solver-core">`）
+- `solver-core.js` —— Node 引擎加载器（读取 index.html 核心脚本，零依赖，供 MCP/测试复用）
+- `mcp-server.js` —— 零依赖 MCP stdio 服务端（手工 JSON-RPC 2.0 + 换行符分隔 JSON，与官方 MCP SDK 线格式对齐）
+- `package.json` —— 标准元数据，`node mcp-server.js` 本地启动即作为 MCP 工具（发布 npm 后亦可 `npx lingshu-solver`）
+- `test/` —— 回归套件 + 冒烟测试 + 三套常驻考卷
+
+---
+
+## 能力边界（诚实声明）
+
+| 维度 | 说明 |
+|---|---|
+| 已验证解 | 每个找到的解都经 Krawczyk 认证（`tier=proven`），误差 ≤ 认证半径，数学保真 |
+| 穷尽性 | **尽力穷尽多解**；极端病态（雅可比高度奇异、解簇极近）在预算内可能遗漏个别解，此时显式标记 `truncated=true`，**绝不谎称已穷尽** |
+| `truncated` 语义 | 仅表示「全局分支未在预算内完全判定所有盒子（无法证明已穷尽）」，**不等于一定遗漏**；绝大多数情况全部真解已找到 |
+| 变量数 | ≤6 |
+| 数值范围 | 默认搜索域 ±1e6；对快增长函数（exp/sinh）或大域，建议显式给定 `domain` 以避免剪枝失效 |
+| 确定性 | 无随机分支，同输入永远同输出 |
+| 部署 | 纯本地、离线、零数据（无网络、无存储、无第三方依赖） |
+
+**不保证**：对一切输入 100% 穷尽；对高度病态系统在预算内必收敛。这些是诚实边界，不是缺陷。
+
+---
+
+## 作为 MCP 工具使用
+
+### 1. 三种接入形态
+
+| 形态 | 端点 / 命令 | 适用 |
+|---|---|---|
+| **远程 HTTP（已上线）** | `http://159.75.154.206:3000/mcp` | 任何支持 Streamable HTTP 的 MCP 客户端，零安装 |
+| 本地 stdio（npx） | `npx -y lingshu-solver` | 本机已装 Node，npm 发布后可用 |
+| 本地 stdio（clone） | `node mcp-server.js` | 开发者 / 离线自托管 |
+
+**远程 HTTP 服务端代码**：`http-mcp-server.js`（零依赖，仅用 Node 内置模块；与 `mcp-server.js` 共享 `solver-core.js` 求解核心，结果同源一致）。如需自托管远程服务：
+```bash
+PORT=3000 node http-mcp-server.js
+```
+
+### 2. 在 MCP 客户端（Claude Desktop / Cursor / Cline / VS Code 等）配置
+
+**推荐 · 远程托管（零安装，已上线）：**
+```json
+{
+  "mcpServers": {
+    "lingshu-solver": {
+      "url": "http://159.75.154.206:3000/mcp"
+    }
+  }
+}
+```
+
+**本地 stdio · 一行命令（npm 发布后可用；npm 账号已就绪，即将发布）：**
+```json
+{
+  "mcpServers": {
+    "lingshu-solver": {
+      "command": "npx",
+      "args": ["-y", "lingshu-solver"]
+    }
+  }
+}
+```
+> 注：`npx lingshu-solver` 需本包发布到 npm 后可用；npm 账号已就绪，即将发布。在此之前请用下方「手动指定本地路径」版（先 clone 仓库）。
+
+**备选 · 手动指定本地路径（已 clone 仓库时）：**
+```json
+{
+  "mcpServers": {
+    "lingshu-solver": {
+      "command": "node",
+      "args": ["把这里替换成你本地的绝对路径/灵数求解器/mcp-server.js"]
+    }
+  }
+}
+```
+
+> 手动版需将 `args` 中的路径替换为你本机的 `mcp-server.js` 绝对路径（例如 `C:/Users/你的用户名/Desktop/灵数求解器/mcp-server.js`）。npx 版无需此步。
+
+### 工具一：`solve`
+
+输入：
+```json
+{
+  "equations": ["x^2 + y^2 = 25", "x + y = 7"],
+  "variables": ["x", "y"],
+  "domain": { "x": [-30, 30], "y": [-30, 30] }
+}
+```
+- `equations`：方程字符串数组（必填），支持 `+ - * / ^ sqrt log sin cos tan exp abs`，以及 in-text 域约束 `"x ∈ [-30,30]"`。
+- `variables`：变量名数组（可选，不填则按出现顺序自动识别，最多 6 个）。
+- `domain`：显式搜索域（可选）。**对"有限解·部分"演示或快增长函数建议给定**，否则默认 ±1e6 可能剪枝失效并触发 `truncated`。
+
+> 输出精度固定 6 位小数（产品规格「6位小数有限网格」），不提供位数切换；解点 `values` 经网格吸附，实际残差通常 ≤ 1e-9。
+
+输出（节选）：
+```json
+{
+  "resultType": 2,
+  "resultTypeName": "finite",
+  "certified": true,
+  "truncated": false,
+  "precisionDecimals": 6,
+  "solutionCount": 2,
+  "recommended": { "values": [3, 4], "tier": "proven", "residual": 0 },
+  "solutions": [ { "values": [3, 4], "tier": "proven", "residual": 0 }, ... ],
+  "warnings": []
+}
+```
+- `resultType`：`1=empty(无解)` / `2=finite(有限解)` / `3=infinite(无限解集，仅给距原点最近的推荐解)`。
+- `tier`：`proven`（Krawczyk 认证）/ `candidate`（未证但可能为解）/ `structural`（结构推导）。
+
+### 工具二：`give_feedback`
+
+AI 智能体遇到卡点/错误/疑似问题时主动回报，仅落本地 `feedback.log`，不外传：
+```json
+{ "name": "give_feedback", "arguments": { "message": "x^2=4 期望2解", "context": "批量求解场景" } }
+```
+
+---
+
+## 本地验证
+
+```bash
+node verify_core.js        # 引擎加载 + 6 个代表性用例
+node mcp_smoke.js          # MCP 字节级冒烟（initialize/tools/list/tools/call）
+node mcp_smoke2.js         # give_feedback + 错误结构化（不泄露堆栈）
+node test/regression.js    # 三套常驻考卷回归（28 用例，known 命中率统计）
+```
+
+---
+
+## 示例（6 类结果覆盖）
+
+| 标题 | 方程 | 预期 |
+|---|---|---|
+| 最少 1 变量 | `x^2 = 4` | 2 解 |
+| 最多 6 变量 | 6 元三对角线性 | 唯一解 |
+| 空集无解 | `x+y=3` 与 `x+y=5` | 空集（sound 证无解） |
+| 有限解·全部 | 圆 × 双曲线 `x²+y²=4, xy=1` | 4 解全认证 |
+| 有限解·部分 | `sin(20x)=0.5, sin(20y)=0.5`（域 [-30,30]） | 多解 + `truncated` 横幅 |
+| 无限解·推荐 | `x+y=3` | 无限集，推荐 (1.5,1.5) |
+
+---
+
+## 文档
+
+- 《灵数求解器_代码流程中文说明.md》—— 从解析到输出的完整内部流程（面向数学背景读者）
+- 《灵数求解器商业化战略白皮书.md》—— 定位、能力边界、风险
+- 发明专利申请书系列（已提交）
+
+## 许可
+
+Apache License 2.0 —— 见 [LICENSE](./LICENSE)。