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

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

版本：0.3.1b1 | 作者：wUwproject | 许可证：Apache 2.0

目录

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

一、它是什么

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

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

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

二、环境要求与依赖

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

三、搭建步骤

方式一：Windows 一键启动

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

方式二：手动启动

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

无需 pip install（纯标准库）。

四、使用流程总览

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

五、8 种前置规范方式

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

六、启动模式

通用参数：--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 描述将包含「更新说明」区块