Document-to-Skill Pipeline

将一组同主题领域文档挖掘为可执行的 Agent Skill，并同步生成可复跑的评测基准与稳定性报告。

项目基于 Hermes 的 hermes -z 单次调用能力实现，Python 部分仅使用标准库。

能力

1. 样本包构建：按证据视角和上下文容量把输入文档组织成若干样本包。
2. 语义发现：从每个样本包归纳可复用的决策单元、流程和边界，并标注证据缺口（GAP）。
3. Skill 编译：生成 SKILL.md 与配套的 EVALUATION.md，并给出置信档与待补缺口清单。
4. 反思环：在置信档未收敛且仍有补充素材时，携带上一轮缺口进行定向补证（默认最多 3 轮）。
5. Benchmark：依据 EVALUATION.md 构建题库，支持多轮对话（模拟客户）与单轮作答两种跑分方式、难度分布配额。
6. 多次构建 · 交集 · 稳定性复跑：把多次构建的题库存为快照、求交集，再对交集项各跑多个 session，观察 skill 在多轮对话下的行为稳定性。
7. 覆盖报告：统计语义单元采纳率、GAP 消解率和维度证据覆盖。
8. Web 控制台：提供真实运行、人工检查点、跑分和覆盖报告入口。

项目结构

.
├── data/input/                         # 放入待挖掘的领域文档（默认输入，仓库不含业务语料）
├── sample-package-constructor-agent-skill/
├── semantic-discovery-agent-skill/
├── evaluation-compiler-agent-skill/    # 三个流水线 Agent Skill
├── web_console/                        # 标准库 SSE 控制台
├── run_pipeline.py                     # 主流水线：Step 1-3 + 反思环
├── run_benchmark.py                    # 构建 / 执行 benchmark
├── run_coverage_report.py              # 语义覆盖报告
├── run_multi_session.py                # 多次 benchmark 的快照 / 交集 / 稳定性复跑
├── run_skill_test.py                   # 通用 smoke test
├── test_pipeline_static.py             # 不调用模型的静态自检
├── clean_artifacts.sh                  # 清理运行产物
├── .env.example                        # 凭据环境变量示例
└── .gitignore

运行时生成的产物目录默认被 Git 忽略：

sample_packages/      # Step 1 产物：样本包 + 全局/分包笔记
semantic_reports/     # Step 2 产物：各样本包的语义分析报告
compiled_skill/       # Step 3 产物：/SKILL.md、EVALUATION.md、benchmark.*
reflection_rounds/    # 反思环各轮的中间产物
benchmark_sessions/   # 快照、交集清单与多 session 复跑留档
.hermes_home/         # Hermes 运行时状态（含 config.yaml，不应提交）

此外 logs/ 下的运行日志按 *.log 规则被忽略；clean_artifacts.sh 会清理上述除 .hermes_home/ 外的产物目录（.hermes_home/ 已配好 provider，如需重置请手动删除）。

前置条件

• Python 3.8+
• 已安装并可从 PATH 调用的 Hermes：

hermes --version

• 一个可用的模型 provider。本项目默认对接火山方舟（Volcengine Ark），在 .hermes_home/config.yaml 中以 custom:volcengine-ark provider 配置，默认模型为 doubao-seed-1-6-250615（256k 上下文，输出上限 32768）。密钥通过环境变量注入，不要写进仓库：

cp .env.example .env
# 在 shell 或密钥管理工具中设置：
export ARK_API_KEY="your-api-key"

说明：run_pipeline.py / run_benchmark.py / run_multi_session.py 启动时会读取 ARK_API_KEY 并注入 Hermes 运行环境，并先做一次连通性自检（返回 HERMES_OK 即通过）。若换用其他 OpenAI 兼容端点，改 config.yaml 里的 providers.*.base_url 与 model.default 即可。首次运行会创建项目本地 .hermes_home/；该目录已配好上述 provider，重跑不会被覆盖。

快速开始

1. 将同一主题的 Markdown 文档放入 data/input/。
2. 运行静态自检（不调用模型）：

python3 test_pipeline_static.py

3. 运行一次挖掘（Step 1-3 + 反思环）：

python3 run_pipeline.py --input data/input --max-rounds 1

4. 查看输出：

compiled_skill//SKILL.md
compiled_skill//EVALUATION.md

5. 生成并执行 benchmark：

python3 run_benchmark.py --difficulty-dist "easy:3,medium:8,hard:7" --target-total 16

6. 生成语义覆盖报告：

python3 run_coverage_report.py

多次构建 · 交集 · 稳定性复跑

出题带随机性，单次题库不足以判断 skill 是否稳定。推荐做法是多次构建题库 → 每次存快照 → 求交集 → 对交集项跑多个 session：

# 1) 多次仅构建题库，每次构建后存一个快照
python3 run_benchmark.py --build-only
python3 run_multi_session.py snapshot          # 序号自增，也可 --slot N 指定

# 2) 查看快照与交集概况（不调用模型）
python3 run_multi_session.py status

# 3) 求交集并写清单（不调用模型）
#    默认先按情境文本相似度求交集；若为空（各次构建情境措辞差异大），
#    自动回退到「按考核维度」求交集。也可 --by-dimension 强制维度口径。
python3 run_multi_session.py intersect

# 4) 对交集项各跑 M 个 session（会调用模型），生成 SESSIONS_REPORT.md
python3 run_multi_session.py run --sessions 3

# 只重跑某个维度（其余维度复用已有结果，报告仍完整）——定向修题后省额度重验
python3 run_multi_session.py run --sessions 3 --only EVAL-01

产物位于 benchmark_sessions/：snapshots/build-N.jsonl 快照、intersection.md 交集清单、DIM_*/session-N.md 每个 session 的完整对话与阅卷、SESSIONS_REPORT.md 逐维稳定性汇总。

Web 控制台

python3 web_console/server.py

打开 http://127.0.0.1:8765。控制台只提供真实流水线运行，不包含模拟运行模式。

常用命令

# 指定输入和反思轮数
python3 run_pipeline.py --input data/input --max-rounds 3

# 仅构建题库 / 复用现有题库跑分 / 快速冒烟
python3 run_benchmark.py --build-only
python3 run_benchmark.py --skip-build
python3 run_benchmark.py --limit 3

# 单轮作答模式（默认是多轮对话）
python3 run_benchmark.py --mode single

# 清理所有运行产物（保留 data/input/）
bash clean_artifacts.sh

数据与安全

• 请仅使用有权处理和分发的领域文档。
• 不要提交 .env、.hermes_home/、模型响应、运行日志或生成产物。
• 生成的 skill 与 benchmark 应经过领域专家审核后再用于生产环境。