Metadata-Version: 2.4
Name: silprespec-emulator-ldxs
Version: 0.3.1b1
Summary: silprespec-emulator — AI Agent
Home-page: https://github.com/Ldxs001/maby_agent
Author: Ldxs (wUwproject)
Author-email: wuwofc@yeah.net
Project-URL: GitHub, https://github.com/Ldxs001/maby_agent
Project-URL: Gitee, https://gitee.com/wUwproject/maby_agent
Project-URL: Documentation, https://github.com/Ldxs001/maby_agent#readme
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# silprespec-emulator — 前置规范效果模拟器

> 前置规范效果实验台。按方法论（08a 前置规范>后置验证 / 08b 填空的边界 / 08c 槽位的减法 / 09b 穷举一致性）提供 **8 种前置规范方式**，用户按场景选一种或多种、自由裁剪，对输入**真实执行**（LLM 真填空），观测填入了什么、重试次数、撑满失败、重现性——验证"前置规范 > 后置验证"在自家场景里的实际效果。
>
> 版本：0.3.1b1 | 作者：wUwproject | 许可证：Apache 2.0

---

## 目录

- [一、它是什么](#一它是什么)
- [二、环境要求与依赖](#二环境要求与依赖)
- [三、搭建步骤](#三搭建步骤)
- [四、使用流程总览](#四使用流程总览)
- [五、8 种前置规范方式](#五8-种前置规范方式)
- [六、启动模式](#六启动模式)
- [七、界面](#七界面)
- [八、观测结果](#八观测结果)
- [九、核心模块](#九核心模块)
- [十、常见问题](#十常见问题)
- [协议](#协议)

---

## 一、它是什么

silprespec-emulator 是一个**通用实验台**。8 种前置规范方式都是**前置**，作用在生成通道 / 填空出口；用户根据自己的场景裁剪配置，对输入真实执行（LLM 真填空），直接观测：

1. **填入了什么**——门禁填了哪个穷举词、凝练成什么、槽位填了什么（填入内容本身就是结果）
2. **重试次数**——是否撑满 max_retry、撑满失败次数
3. **命中 / 留空 / 编造分布**——观测原子逐项统计
4. **重现性**——并行 N 次各方式跨 run 填入一致率

核心设计理念：**8 种都是前置规范；后置验证（任务完成后对全量结果的验证）不在本系统；本系统不替用户选方式**——用户按自己场景裁剪，系统只管执行并产出可观测结果。

---

## 二、环境要求与依赖

| 依赖 | 说明 |
|------|------|
| **Python** | 3.11 及以上，**仅标准库**（http.server / threading / json / urllib），无第三方 pip 依赖 |
| **LLM 推理服务** | LM Studio 或 Ollama，二选一，本机运行（见「启动模式」后端参数） |

LLM 推理由外部后端服务提供：LM Studio / Ollama / 任意 OpenAI 兼容 API。

---

## 三、搭建步骤

### 方式一：Windows 一键启动

```
1. 确保 LM Studio（或 Ollama）已运行，且已加载一个模型
2. 双击 setup.bat
3. 浏览器访问 http://localhost:8805
```

### 方式二：手动启动

```bash
python main.py                     # 默认 LM Studio
python main.py --backend ollama    # Ollama 后端
python main.py --port 8790         # 指定端口
```

无需 pip install（纯标准库）。

---

## 四、使用流程总览

```
选方式（一种或多种）→ 按场景裁剪配置 → 输入
    ↓
并行执行 N 次（LLM 真填空）
    ↓
观测：填入内容 / 重试次数 / 撑满失败 / 命中留空编造分布 / 跨 run 重现性
```

---

## 五、8 种前置规范方式

| 方式 | 方法论出处 | 执行 | 观测 |
|---|---|---|---|
| ① 门禁·穷举词组（减法） | 08c论断三/四 | LLM 在每道门禁穷举词里填一个或"未指定"，不 block | 填了哪个词/留空/编造 |
| ② 软引导·引导提示词 | 08a§4 | LLM 在引导下填空 | 填入内容 |
| ③ 凝练+代码固定枚举拼接 | 08c场景二 | LLM 凝练（锚定禁泛化）→ 代码枚举组合 | 凝练成什么/编造数 |
| ④ 槽位限定+查多余编造 | 08c场景一 | LLM 填槽位 → 在填空出口查多余编造 | 各槽位填入/多余编造 |
| ⑤ 发散+确定性纠偏 | 08c场景三 | LLM 发散生成 → 代码纠偏 | 纠偏前后 |
| ⑥ 确定性后处理（完全封死） | 08a§4.3 | LLM 生成 → 代码钉死 | 钉死后内容 |
| ⑦ 检出即上报 | 08a§7 | LLM 生成 → 检出+标记+上报人工 | 内容+检出标记 |
| ⑧ required最小化 | 08c§4.3 | required 槽必填，可留空槽留空 | 填入/留空数 |

**空坐标形态**（由校验原子承载，非独立配置项）：点对点 = 严格相等（`eq_exact`）、点对面 = 集合成员（`in_set`）、面对面 = 区间容差（`in_range`）、不校验（`none`）。

---

## 六、启动模式

| 模式 | 命令 | 用途 |
|------|------|------|
| **Web 界面** | `python main.py` | 默认 8805 端口，三 Tab 实验台 |
| **指定后端** | `python main.py --backend ollama` | Ollama；`--backend lm-studio` / `--backend custom --base-url ... --model ...` |
| **连接检测** | `python main.py --check` | 仅检测后端连接，不进入服务 |
| **批处理** | `python main.py --batch input.json output.json` | 读 input（pipeline + 输入），写 output（并行产出） |
| **一键启动** | 双击 `setup.bat` | 端口 8805，自动清理旧进程并拉起服务 |

> **通用参数**：`--port`（默认 8805，`auto`=自动分配空闲端口）、`--host`（默认 0.0.0.0）、`--pidfile`、`--jsonl`（stdin/stdout 逐行管道）。

后端：LM Studio（默认 `http://localhost:1234`）/ Ollama（`http://localhost:11434`）/ Custom（任意 OpenAI 兼容 API，需 `--base-url`）。

---

## 七、界面

深色主题，三 Tab：

- **配置**：方式卡片按 **5 阶段分组**（①生成 / ②后处理 / ③校验 / ④重试 / ⑤观测），每个原子标注所属**轴**（格式轴 / 集合轴 / 数值轴 / 内容轴）与理论形态（A 封死 / B 检出即上报）；预置方式阶段只读展示，custom 方式阶段可编辑；配置全部**表单化**（非 JSON），改动自动落盘
- **运行**：输入 + 并行数
- **结果**：填入内容 + 重试 + 撑满 + 重现性

---

## 八、观测结果

- **填入了什么**（实际填空内容——门禁填了哪个词、凝练成什么、槽位填了什么）
- **重试次数**（是否撑满 max_retry）
- **撑满失败次数**
- 命中 / 留空 / 编造分布（`hit` / `left_empty` / `fabricated`）
- 多余编造（`extra_keys`，槽位场景查超出槽位定义的 key）
- 检出标记（`flagged`，⑦ 检出即上报的未命中上报数）
- 纠偏前后（`changed`，⑤⑥ 发散/钉死是否真的改了内容）
- **重现性**：并行 N 次各方式跨 run 填入一致率

---

## 九、核心模块

```
silprespec-emulator/
├── main.py / setup.bat / requirements.txt
├── config.json             # 持久化配置（配置推动）
├── llms.txt                # LLM 导读
├── data/experiment.json    # 实验自动落盘
└── silprespec_emulator/
    ├── config_manager.py   # ConfigManager + DEFAULT_CONFIG（配置推动）
    ├── pipeline_model.py   # 方式配置 + 结果模型 + 重现性计算
    ├── atoms.py            # 19 个原子（生成3/后处理4/校验6/观测6）+ 8 方式配方 + 通用执行器
    ├── simulator.py        # 执行引擎（ExperimentRunner 编排并行与重现性）
    ├── llm_client.py       # 多后端 LLM
    └── web_ui.py           # 实验台 Web UI（5 阶段表单 + 原子轴标注）
```

---

## 十、常见问题

**Q：需要安装依赖吗？**
A：不需要。纯 Python 标准库，无第三方 pip 包。LLM 推理由外部后端服务（LM Studio / Ollama）提供。

**Q：启动后提示连接失败？**
A：运行 `python main.py --check` 看具体错误。LM Studio 需已加载模型（默认 `http://localhost:1234`）；Ollama 需 `ollama serve`（`http://localhost:11434`）；custom 模式必须传 `--base-url`。

**Q：某方式一直撑满失败（重试耗尽）？**
A：撑满本身是观测结果——说明该配置对当前输入不可达（08b 的"空收到多小开始撑满"）。把方式/配置换成更宽松的形态（如 required 最小化、允许未指定）再跑一轮对比。

**Q：跨 run 重现性低说明什么？**
A：一致率乱跳 = 偏差不可枚举、点位还没统一（09b 的"偏差一致才谈得上校准"）。先在实验台上锁定点位，再谈校准。

---

## 协议

Apache 2.0 © wUwproject


---

## 更新说明

##\s*\[?版本号\]?[^\n]*\n.*?(?=\n##\s|\Z)`：兼容带方括号（`## [2.4.1] - 日期`）与不带方括号（`## 0.3.1b0 — 标题`）两种版本行格式，终止于下一个 `## ` 行或文件尾
- manifest 修正：type=skill→agent、source_path→独立源 `C:/Users/sm001/WorkBuddy/silprespec-emulator`、repo_path→`silprespec-emulator`

### 文档
- README 对齐智能体发布骨架（rag-assistant / structured-writer 同型）：版本行 / 目录锚点 / 中文数字编号章节（一~十）/ 协议；修正空坐标形态描述（0.2.5b0 已删 coord 字段，改由校验原子承载）、界面描述（0.2.9b0 表单化 + 0.3.1b0 5 阶段分组）、目录树补 atoms.py/llms.txt
- llms.txt 方式表关键配置列改真实字段（enums/regex_replaces/slots 等），标注单次不重试方式；核心模块补 atoms.py
- atoms.py 头部注释 10→19 个原子（0.2.0b0 遗留），`_record_attempt`→`_attempt_for`

### 验证
- 修复后正则对三份 CHANGELOG（silprespec 无方括号 / rag / sw 带方括号）全部正确匹配当前版本区块
- 0.3.1b1 发布后 PyPI 描述将包含「更新说明」区块
