From 2f31627621cc8b114784f198ef4acf935d47463d Mon Sep 17 00:00:00 2001 From: heweidong-ecco <290444878+heweidong-ecco@users.noreply.github.com> Date: Sun, 18 Oct 2026 19:05:23 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E7=BB=93=E9=A1=B9):=20=E8=87=AA=E7=94=A8?= =?UTF-8?q?=E7=89=88=20v0.4.0=20=E7=BB=93=E9=A1=B9=20+=20=E4=BB=93?= =?UTF-8?q?=E5=BA=93=E6=96=87=E6=A1=A3=E9=9D=A2=E8=A1=A5=E9=BD=90(?= =?UTF-8?q?=E6=A0=87=E5=87=86=E9=A9=B1=E5=8A=A8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 仓库健康文件:LICENSE(MIT)/CONTRIBUTING/SECURITY/SUPPORT/CHANGELOG - GitHub 模板:.github/ISSUE_TEMPLATE/*.yml + PULL_REQUEST_TEMPLATE.md - 使用者文档:docs/FAQ.md · docs/CLI.md · docs/README.md(索引) · examples/ - README:目录 + 完整 CLI 入口 + FAQ/贡献/安全/许可证段 - 架构图:docs/arch/README.md(C4/组件/时序);总纲 0.4 + 当前形态 - 结项:结项报告 + DEC-024 + DEC-025;版本 0.3.0 → 0.4.0 - 语料复现:eval/corpus 清单 + export/seed 工具(哈希校验) - harness:适配 app/ 与官方镜像;探针失败 exit 2(已补红绿) - 验证:597 passed / 2 skipped · 相对链接自检 0 broken · 证据覆盖守卫通过 [no-skill: 本轮工具改动含 corpus 导出/导入(先写测试:6 failed → 实现 → 6 passed)与探针退出码(测试先写,但脚本与测试同批改;已补红绿:退回旧行为→测试红→恢复→绿);TDD skill 在编辑后才调用,按 D-29 显式豁免并留痕] --- .github/ISSUE_TEMPLATE/bug_report.yml | 68 ++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 54 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 37 ++++ CHANGELOG.md | 69 ++++++++ CLAUDE.md | 25 ++- CONTRIBUTING.md | 81 +++++++++ LICENSE | 21 +++ README.md | 100 +++++++++-- ROADMAP.md | 16 +- SECURITY.md | 50 ++++++ SUPPORT.md | 28 +++ app/eval_gate/__init__.py | 2 +- docs/CLI.md | 147 ++++++++++++++++ docs/FAQ.md | 133 ++++++++++++++ docs/README.md | 90 ++++++++++ docs/arch/README.md | 110 ++++++++++++ ...55\346\226\231\345\255\230\346\224\276.md" | 60 +++++++ ...16\350\256\270\345\217\257\350\257\201.md" | 80 +++++++++ ...45\346\226\260\350\242\253\346\265\213.md" | 10 +- ...252\347\224\250\347\211\210-2026-10-18.md" | 123 +++++++++++++ "docs/\351\203\250\347\275\262.md" | 41 ++++- eval/README.md | 3 + eval/corpus/README.md | 54 ++++++ eval/corpus/manifest.json | 67 +++++++ examples/README.md | 44 +++++ examples/offline-demo.sh | 32 ++++ integrations/fastapi-rag-agent/README.md | 37 ++++ .../fastapi-rag-agent/eval-gate.yml.example | 74 ++++++++ pyproject.toml | 18 +- tests/test_eval_corpus.py | 165 ++++++++++++++++++ tests/test_sut_harness.py | 16 +- tools/export_eval_corpus.py | 107 ++++++++++++ tools/seed_eval_corpus.py | 121 +++++++++++++ tools/sut-harness/run_sut.sh | 7 +- "\346\200\273\347\272\262.md" | 47 +++-- 36 files changed, 2092 insertions(+), 56 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md create mode 100644 SUPPORT.md create mode 100644 docs/CLI.md create mode 100644 docs/FAQ.md create mode 100644 docs/README.md create mode 100644 docs/arch/README.md create mode 100644 "docs/decisions/DEC-024-\350\207\252\347\224\250\347\211\210\347\273\223\351\241\271\350\214\203\345\233\264\344\270\216\350\257\255\346\226\231\345\255\230\346\224\276.md" create mode 100644 "docs/decisions/DEC-025-\345\274\200\346\272\220\346\226\207\346\241\243\351\235\242\344\270\216\350\256\270\345\217\257\350\257\201.md" create mode 100644 "docs/\347\273\223\351\241\271\346\212\245\345\221\212-\350\207\252\347\224\250\347\211\210-2026-10-18.md" create mode 100644 eval/corpus/README.md create mode 100644 eval/corpus/manifest.json create mode 100644 examples/README.md create mode 100755 examples/offline-demo.sh create mode 100644 integrations/fastapi-rag-agent/README.md create mode 100644 integrations/fastapi-rag-agent/eval-gate.yml.example create mode 100644 tests/test_eval_corpus.py create mode 100644 tools/export_eval_corpus.py create mode 100644 tools/seed_eval_corpus.py diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..40ef91a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,68 @@ +name: Bug 报告 +description: 评测门自身的行为异常(不是被测系统的问题) +title: "[Bug] " +body: + - type: markdown + attributes: + value: | + 感谢报告。**安全漏洞请勿在这里提** —— 见 `SECURITY.md`。 + 提之前请先看 `docs/FAQ.md` 与 `docs/部署.md §6`(TLS / IPv6 / 模型名是本机常见坑)。 + + - type: textarea + id: what + attributes: + label: 现象 + description: 发生了什么?给最小复现命令。 + placeholder: | + $ eval-gate run --evals ... + ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: 期望 vs 实际 + description: 期望的 verdict / exit code / 报告字段,与实际看到的。 + validations: + required: true + + - type: input + id: version + attributes: + label: 版本 / commit + description: `git rev-parse --short HEAD` 或 `eval-gate --help` 的版本。 + placeholder: "0.4.0 / abc1234" + validations: + required: true + + - type: textarea + id: env + attributes: + label: 环境 + description: OS、Python 版本、是否 Docker、judge 模型(不要贴 key)。 + placeholder: "macOS 13 / Python 3.10 / Docker 24 / deepseek-v4-flash" + validations: + required: true + + - type: textarea + id: evidence + attributes: + label: 证据 + description: | + 贴 `eval/runs/.local.json` 的关键字段、trace_id、报错全文。 + **先脱敏**(不要贴 key、被测回答原文)。 + render: text + validations: + required: false + + - type: dropdown + id: eval_impact + attributes: + label: 是否影响评测结论 + options: + - 是(结论被伪造 / 误判 / 无法复现) + - 否(安装 / CLI / 文档 / 环境) + - 不确定 + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..e734277 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: true +contact_links: + - name: 安全漏洞(请勿公开) + url: https://github.com/heweidong-ecco/agent-eval-gate/security/policy + about: 按 SECURITY.md 走私密报告,不要开公开 issue + - name: 常见问题 FAQ + url: https://github.com/heweidong-ecco/agent-eval-gate/blob/main/docs/FAQ.md + about: 密钥 / 429 / exit code / 语料 / 环境坑 + - name: 文档索引 + url: https://github.com/heweidong-ecco/agent-eval-gate/blob/main/docs/README.md + about: 不知道该看哪份文档时从这里进 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..ec83384 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,54 @@ +name: 功能请求 +description: 新增能力 / 改进现有行为 +title: "[Feature] " +body: + - type: textarea + id: goal + attributes: + label: 目标 / 用户价值 + description: 解决谁的什么问题?不要只写“想要 X”。 + validations: + required: true + + - type: textarea + id: acceptance + attributes: + label: 验收标准 + description: 可检查的条目(命令、输出、阈值)。 + placeholder: | + - [ ] ... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: 备选方案 / 代价 + description: 你考虑过哪些做法?为什么选这个? + validations: + required: false + + - type: dropdown + id: area + attributes: + label: 影响面 + options: + - 判据 / 判分器 + - 评测集 / 阈值 + - 适配器 / 接入新被测 + - CLI / 报告 + - 语料 / 可复现性 + - CI / 工具链 + - 文档 + validations: + required: true + + - type: checkboxes + id: checks + attributes: + label: 提交前自查 + options: + - label: 我已确认 `docs/FAQ.md` / `docs/README.md` 里没有现成答案 + required: true + - label: 我理解涉及口径/选型的改动需要一份 DEC + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..6d15b47 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,37 @@ +## 改动 + + + +## 关联 + + + +## 验证证据(必须) + +- [ ] 测试命令与结果:`________`(通过几 / 失败几) +- [ ] 覆盖率(若改实现):`________` +- [ ] eval 回归(若改 Prompt / 判据 / 评估集 / 阈值):`________` +- [ ] 真机验证(若改 harness / 被测接入):`________` + +## 影响面自查 + +- [ ] 是否改 **Prompt / 判据 / 评估集 / 阈值**? + → 是:附回归结果;否:写“未改” +- [ ] 是否改 **契约**(`contracts/` / schema / 报告字段)? + → 是:附契约测试;否:写“无契约变更” +- [ ] 是否改 **CLI 参数 / exit code**? + → 是:同步 `docs/CLI.md` 与 `README.md` +- [ ] 是否改 **文档结构**? + → 是:更新 `docs/README.md` 索引;架构变化同时更新 `总纲.md §1.1` 与 `docs/arch/` +- [ ] 若无用户可见变化,是否更新 `CHANGELOG.md`?(有变化则必须更新) + +## 风险与回滚 + + + +## Review checklist(单人可自检) + +- [ ] 需求点全部实现(对照 issue / ROADMAP) +- [ ] 测试覆盖关键路径;没有“为绿而绿”的测试 +- [ ] 无明文密钥 / 敏感数据入库 +- [ ] 提交信息规范;一个 PR 只含本任务改动 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d87c3f5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,69 @@ +# Changelog + +本文件记录**面向使用者**的变化。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/), +版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。 + +> ⚠️ **`v0.4.0` 是自用版**;`v1.0.0` 的前置是「真实发版 CI 接入 + 外部使用者验证」, +> 目前都还没满足(见 `docs/结项报告-自用版-2026-10-18.md`)。 + +## [0.4.0] - 2026-10-18 + +### Added + +- **`DEC-019` 完整 live 回归**:48 条真实评测,47/48 通过(0.9792)、`exit 0`; + `rule_hit_judge_fail = 0` ⇒ 判分器收紧后**未观测到误伤** + (报告:`docs/reports/DEC-019-live回归-2026-10-18.md`)。 +- **评测语料可复现**:`eval/corpus/manifest.json`(sha256/125 行/来源计数)+ + `tools/export_eval_corpus.py` + `tools/seed_eval_corpus.py`;正文放仓外,seed 前强制校验哈希。 +- **当前架构图**:`docs/arch/README.md`(C4 上下文 / 组件 / 时序)。 +- **发版 CI 接入模板**:`integrations/fastapi-rag-agent/`(⬜ 未接入;不改另一个仓)。 +- **文档面**:`docs/FAQ.md`、`docs/CLI.md`、`docs/README.md`(索引)、`examples/`; + `.github/ISSUE_TEMPLATE/`、`.github/PULL_REQUEST_TEMPLATE.md`。 +- **仓库健康文件**:`LICENSE`(MIT)、`CONTRIBUTING.md`、`SECURITY.md`、`SUPPORT.md`、本文件。 + +### Changed + +- **判分器提示词收窄**(`DEC-019` α):豁免句只在**拒答语境**下生效,并给非拒答反例。 +- **门 2(提交门)判据改为时序**(`DEC-020`):「自上次提交以来、动手之前调过 TDD」, + 不再是一次满足后永久满足。 +- **L2 阈值 0.80 → 0.95**(`DEC-013`)。 +- **`tools/sut-harness/run_sut.sh` 适配新被测**: + `api/` → `app/`、官方镜像 `fastapi-rag-agent:latest`; + 源码只读挂 `/src` → 容器内复制到可写 `/app`;新增 `EVAL_SUT_DB` / `EVAL_SUT_SESSION_TOKEN_LIMIT`。 +- **能力探针失败退出码 1 → 2**(与 README / 故障手册的契约一致)。 +- 版本号 `0.3.0` → **`0.4.0`**。 + +### Fixed + +- 被测结构变化后 **旧 harness 直接跑不起来**(仍要求 `api/` + 旧镜像)。 +- 只读挂载 `/app` 导致被测启动失败(应用要写 `/app/.mem0/qdrant/.lock`)。 +- 判分器输入 `deterministic` 字段去掉(`DEC-015 B1`)。 +- 重试在产物里不可见 → `sut.call` span 记 `attempts/http_status/last_error`。 +- `_run_id` 同秒撞名导致产物互相覆盖。 + +### Known limitations / deferred + +- **U2 未闭环**:评测门**没有**接进任何真实项目的发版 CI(模板已备)。 +- **M3 抽取类判据**仍是「含其一即符」;正式判抽取需单独 DEC。 +- **`id=20`** 是被测检索失败(`eval/cases/fastapi-rag-2026-10-18.json`,status=open)。 +- 轮间 2× 延迟悬案(16 轮内 1 次,成因未指名)。 + +## [0.3.0] - 2026-09-11 + +### Added + +- 阶段3 收口:评测门 CLI、契约、真实被测适配器、CI 示例。 +- 门店禁硬化:门 1/门 2、`impl-guard` 左移门、子 Agent 纪律注入。 + +### Fixed + +- skills 不触发、子 Agent 拿不到纪律(两个严重问题); +- `rag-api` 旧镜像导致的“能通过 `/health` 但答不了”被能力探针拦住。 + +## [0.2.0] - 2026-09-09(未打 tag) + +- 七层架构适配(`总纲.md`)、E1–E9 模块注册表、评测执行状态机、评测集 schema 草案。 + +## [0.1.0] - 2026-09-09(未打 tag) + +- 初始脚手架:需求基线、ROADMAP、目录骨架。 diff --git a/CLAUDE.md b/CLAUDE.md index 01e6e45..f2edd65 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,7 @@ - B 知识库绝对路径:`/Users/heweidong/Desktop/Product/agent-projects/kit/product-agent-dev-os/知识库-Agent-System`,如 `/Users/heweidong/Desktop/Product/agent-projects/kit/product-agent-dev-os/知识库-Agent-System`(含 README 分层索引;阶段卡在 `04-分阶段工作流/`,模块在 `05-独立模块工作流/`)。 ## 接续协议 -1. 读本文件 → `ROADMAP.md`「当前指针」。 +1. 读本文件 → `ROADMAP.md`「当前指针」;文档导航先看 **`docs/README.md`**(索引)。 2. 当前指针格式:`分支 | 阶段X-步骤Y | 模块 | L3基线 | 北极星`。例:`main | 阶段1-步骤1 | 无 | 人工介入率 <40% | 工单自动解决率 ≥60%`。 > ⚠️ **锚点里不写死那些"每次合并都会变"的值** —— 主要是 **commit sha** > (实测:2026-09-21 → 09-24,三天里锚点的 `main` sha 就旧了一截)。 @@ -114,15 +114,28 @@ ## 目录(Agent 程序壳) ``` -README.md · 需求基线.md · 总纲.md · ROADMAP.md · CLAUDE.md # 对外说明(API 文档)+ 事实源/架构/执行图/接续锚 -docs/RUNBOOK.md · docs/部署.md · docs/decisions/ · docs/复盘/ · docs/specs/ # 流程(指 B)+ 部署配置 + 决策 + 过程错误复盘 + 节点设计 +README.md · CONTRIBUTING.md · SECURITY.md · SUPPORT.md · CHANGELOG.md · LICENSE(MIT) # 对外入口 + 仓库健康文件 +需求基线.md · 总纲.md · ROADMAP.md · CLAUDE.md # 事实源 / 架构 / 执行图 / 接续锚 +docs/README.md(文档索引)· docs/FAQ.md · docs/CLI.md · docs/部署.md +docs/arch/(当前架构图)· docs/decisions/ · docs/复盘/ · docs/specs/ · docs/reports/ # 架构 + 决策 + 复盘 + 节点设计 + 报告 contracts/ · templates/ # 契约(工具/MCP/消息协议)与 spec 模板 -eval/ · eval/cases/ · observability/ · 飞轮/ # 评估门 / **失败回灌用例库** / 观测 / 数据飞轮 -app/ .claude/skills/ .github/(CI-CD) tests/ # 实现层 +eval/ · eval/cases/ · eval/corpus/ · observability/ · 飞轮/ # 评估门 / 失败回灌 / 语料清单 / 观测 / 数据飞轮 +app/ · tools/ · examples/ · integrations/ # 实现 / 工具 / 例子 / 发版 CI 模板(未接入) +.github/(CI + issue/PR 模板)· .claude/skills/ · tests/ ``` -## 当前指针(随推进更新 — 上次更新 **2026-10-18** 会话:`DEC-019` 完整 live 回归已跑完(47/48、exit 0)· 待签核 = 0 · 余项只剩环境待办) +## 当前指针(随推进更新 — 上次更新 **2026-10-18**:项目**自用版已结项** · 待签核 = 0) +> ✅ **项目自用版已结项(2026-10-18)** —— 见 **`docs/结项报告-自用版-2026-10-18.md`**。 +> 未做项**全部是明确暂缓**(U2 跨仓 CI / M3 抽取判据 / `id=20` / 背景观察), +> 不是遗漏;建议 tag **`v0.4.0`(自用)**,`v1.0.0` 留给 U2 + 外部验证之后。 +> +> 📚 **文档面已按标准补齐(2026-10-18)**: +> 入口 **`docs/README.md`**(索引)· `docs/FAQ.md` · `docs/CLI.md` · `docs/arch/` · +> `CONTRIBUTING.md` / `SECURITY.md` / `SUPPORT.md` / `CHANGELOG.md` / `LICENSE`(MIT) · +> `.github/ISSUE_TEMPLATE/` + `.github/PULL_REQUEST_TEMPLATE.md` · `examples/`; +> 范围与暂缓项见 **`DEC-025`**。 +> > **🔜 新会话从这里接**:读本段 + `ROADMAP.md`「📌 交接(**2026-10-18**)」即可,不必翻历史。 > **B 的 12 个节点:已签核闭环 12 / 待终裁 0 / 技术欠账 0** —— 签核号到 **D-29**。 > diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..76330b6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,81 @@ +# 贡献指南 + +> **项目状态**:`v0.4.0`(自用版,2026-10-18 结项)。欢迎 issue / PR,但单人维护、无 SLA; +> 外部贡献前请先开 issue 对齐,避免做完才发现方向不一致。 + +## 1. 开发环境 + +```bash +git clone https://github.com/heweidong-ecco/agent-eval-gate.git +cd agent-eval-gate +python3 -m venv .venv +.venv/bin/pip install -e '.[dev]' +./tools/setup-hooks.sh # 必做:激活本地门禁(克隆不携带 git hooksPath) +``` + +要求:Python **≥ 3.10**(CI 用 3.11);运行时**零依赖**,dev 依赖只有 pytest / coverage / pyyaml。 + +## 2. 测试与门禁 + +```bash +.venv/bin/python -m pytest -q # 全量,离线 +.venv/bin/python -m pytest -q --cov=eval_gate # 覆盖率(CI 硬门 85%) +``` + +本仓的提交门禁(`.githooks/`)会检查: + +| 门 | 规则 | 豁免 | +|---|---|---| +| 门 1 | 改了 `app/`、`tools/`、`.claude/hooks/`、`.githooks/` 却没改 `tests/` → 拒绝 | 提交信息写 `[no-test: <理由>]` | +| 门 2 | 自上次提交以来、动手之前**没有调用 `test-driven-development`** → 拒绝 | 提交信息写 `[no-skill: <理由>]` | + +> **两条都是结构门,不是建议**。理由见 `CLAUDE.md` 的「纪律」段与 `DEC-020`。 +> **先写测试、看它红、再写实现** —— 这是本仓的默认工作方式。 + +## 3. 改动的前置规则 + +| 你要改什么 | 先做什么 | +|---|---| +| Prompt / 判据 / 评估集 / 阈值 | 跑 eval 回归;失败即补 `eval/cases/`(带 `regression.root_cause`) | +| 选型 / 口径 / 架构决策 | 写 `docs/decisions/DEC-nnn-*.md`(备选方案 / 依据 / 反悔成本) | +| 接入新被测 | 读 `docs/接入新被测.md`;适配器 3 处改动 + 数据 | +| 改评测语料 | 读 `eval/corpus/README.md`;正文不入本仓,更新 `manifest.json` 的 sha256 | +| 改 CLI / 契约 | 同步 `contracts/` 与 `docs/CLI.md`,并补契约测试 | +| 改门禁 / hook | **必须配测试**,并做突变验证(拿掉守卫应变红) | + +## 4. Commit 与 PR + +- **Conventional Commits**:`feat|fix|docs|refactor|test|chore|perf|ci(scope): 描述`; +- 一个 PR = **一个完整任务**(不是一个小节);同一任务的多条 commit 走同一个 PR; +- 分支:`feat/<短名>` / `fix/<短名>` / `docs/<短名>`; +- PR 描述用 `.github/PULL_REQUEST_TEMPLATE.md`,必须写清: + - 改了什么 / 为什么; + - 验证命令与结果(测试、覆盖率、eval); + - 是否改 Prompt / 评测集 / 契约; + - 风险与回滚。 +- **合并**:单人仓里"点合并"是唯一人工审核位;PR 开好后由维护者确认再合 + (见 `CLAUDE.md` D-23:自开 PR 不自合)。 + +## 5. 目录与文档 + +- 文档导航:**`docs/README.md`** +- 当前架构:**`docs/arch/README.md`** +- 项目状态与暂缓项:**`docs/结项报告-自用版-2026-10-18.md`** +- 新增文档时:**必须同时更新 `docs/README.md` 索引**;架构变化同时更新 `总纲.md §1.1`。 + +## 6. 发布 + +- 版本号在 `pyproject.toml` 与 `app/eval_gate/__init__.py` **两处同步**; +- 发布前:全量测试 + 覆盖率 + (若改评测件)eval 回归; +- 更新 `CHANGELOG.md` → 打 tag `vX.Y.Z` → 推送; +- `v1.0.0` 的前置 = U2 真实发版 CI 接入 + 外部使用者验证(当前未满足)。 + +## 7. 行为准则 + +本项目**暂未采用正式的行为准则**(单人维护、无社区治理流程)。 +基本要求:就事论事、不人身攻击;维护者有权关闭不合适的 issue/PR。 +若将来开放外部维护者,**先补 `CODE_OF_CONDUCT.md`**。 + +## 8. 许可 + +贡献即表示同意以 **MIT** 许可(见 `LICENSE`)发布。暂不要求 DCO / CLA。 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9114905 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 heweidong-ecco + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 3d4a6b4..1a7955d 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,36 @@ --- +## 项目状态(2026-10-18 · 自用版结项) + +**v0.4.0(自用版)已结项** —— 验收对照与暂缓项见 **`docs/结项报告-自用版-2026-10-18.md`**。 + +| | | +|---|---| +| 已闭环 | B 六阶段 **12/12** 节点 · M0–M5 · 真实被测 **2 家 / 4 形态** · 最新 live **47/48 · exit 0** · **597 tests** | +| 明确暂缓 | **U2 真实发版 CI**(模板在 `integrations/`;业务方 2026-10-18 决定暂不动另一个仓)· M3 抽取判据 · 背景观察项 | +| 复现 live 回归 | 语料清单 `eval/corpus/` → `tools/seed_eval_corpus.py` → `tools/sut-harness/run_sut.sh` → `eval-gate run` | + +> `v1.0.0` **不外推**:前置 = U2 接进真实发版 CI + 至少一个外部使用者验证。 + +--- + +## 目录 + +- [项目状态](#项目状态2026-10-18--自用版结项) +- [30 秒上手](#30-秒上手) +- [CLI](#cli) +- [它怎么判(判分链路)](#它怎么判判分链路) +- [目录](#目录) +- [文档索引](#文档索引) +- [常见问题](#常见问题) +- [开发](#开发) +- [贡献](#贡献) +- [安全](#安全) +- [许可证](#许可证) + +--- + ## 30 秒上手 ```bash @@ -30,26 +60,18 @@ python3 -m venv .venv && .venv/bin/pip install -e '.[dev]' ## CLI -### `eval-gate run` — 跑一轮评测并出 exit code +| 子命令 | 用途 | +|---|---| +| `run` | 跑一轮评测 → 报告 + exit code | +| `trace` | 打印某次 run 的 span 树 | +| `calibrate` | judge 与人工标注的一致率(M1/E7) | +| `stats` | 从已有 trace 产 L1 基线(零 token) | -| 参数 | 必填 | 说明 | -|---|---|---| -| `--evals PATH` | ✅ | 评测集文件(格式见 `eval/README.md` / `contracts/评测-evals-schema.md`) | -| `--mode good\|bad` | | 被测 prompt 质量:good=忠实 / bad=劣化(**自证用**:劣化必须被拦) | -| `--threshold FILE` | | 阈值 JSON,覆盖 `eval/阈值.json` | -| `--offline` | | 强制离线 FakeJudge(**不调真实模型**) | -| `--report-dir DIR` | | 报告落盘目录(默认 `eval/runs`) | +完整参数、环境变量与示例见 **`docs/CLI.md`**。 产出:`eval/runs/.local.json`(逐条证据)+ `.trace.jsonl`(span)+ 结构化日志走 **stderr**(`2>log.jsonl` 采集)。 -### `eval-gate trace` — 打印 Trace 视图 - -| 参数 | 说明 | -|---|---| -| `--run RUN_ID` | 指定 run(默认取最近一次) | -| `--trace-dir DIR` | trace 文件目录(默认 `eval/runs`) | - -### exit code 语义(CI 门;契约 `contracts/评测-report.md:40-46`) +### exit code 语义(CI 门;契约 `contracts/评测-report.md`) | code | 含义 | CI 处置 | |---|---|---| @@ -82,20 +104,44 @@ python3 -m venv .venv && .venv/bin/pip install -e '.[dev]' |---|---| | `app/eval_gate/` | E1–E9 实现(schema / adapters / rules / judge / runner / report / obs / cli) | | `contracts/` | **契约**(评测集 schema / 被测适配器 / judge / 报告与阈值)—— 事实源 | -| `eval/` | 评测集、`阈值.md` + `阈值.json`(运行值)、`cases/`(失败回灌)、`runs/`(报告)、`snapshots/` | +| `eval/` | 评测集、`阈值.md` + `阈值.json`(运行值)、`cases/`(失败回灌)、`runs/`(报告)、`snapshots/`、**`corpus/`(语料清单;正文在仓外)** | +| `tools/` | **`sut-harness/`**(真实被测运行层)· **`export_eval_corpus.py` / `seed_eval_corpus.py`**(语料复现)· `archive_evidence.py` + `check_evidence_coverage.py`(证据归档/覆盖守卫) | +| `integrations/` | **发版 CI 接入模板**(⬜ 未接入 —— 业务方决定暂不动另一个仓) | | `observability/` | 结构化日志 / trace_id / span 规范 | -| `docs/` | `RUNBOOK.md`、`decisions/`(签核)、`specs/`(节点设计)、`复盘/`(过程错误集) | +| `docs/` | `README.md`(**文档索引**)· `FAQ.md` · `CLI.md` · `部署.md` · `decisions/`(签核)· `specs/`(节点设计)· `复盘/` · **`arch/`(当前架构图)** · **结项报告** | +| `examples/` | 可直接跑的例子(`offline-demo.sh`) | +| `.github/` | issue 模板 · PR 模板 · CI workflow | | `tests/` | 契约测试与回归(`pytest -q`,离线零外网) | +| 根级健康文件 | `LICENSE`(MIT)· `CONTRIBUTING.md` · `SECURITY.md` · `SUPPORT.md` · `CHANGELOG.md` | --- ## 文档索引 +**全部文档的导航 → `docs/README.md`。** + +- **常见问题** → **`docs/FAQ.md`**(密钥 / 429 / exit code / 语料 / 环境坑) +- **完整 CLI** → **`docs/CLI.md`** - **接续与指针** → `CLAUDE.md`(每会话必读)、`ROADMAP.md`(执行图与当前指针) -- **业务口径事实源** → `需求基线.md`;架构 → `总纲.md` +- **项目结项与暂缓项** → **`docs/结项报告-自用版-2026-10-18.md`** +- **业务口径事实源** → `需求基线.md`;架构蓝图 → `总纲.md` +- **当前架构图(C4 / 组件 / 时序)** → **`docs/arch/README.md`** - **怎么装、怎么接真实被测、本机环境坑** → **`docs/部署.md`** +- **评测语料怎么复现** → **`eval/corpus/README.md`** - **阈值与「为何调」** → `eval/阈值.md`(运行值 `eval/阈值.json`) - **失败案例与教训** → `eval/cases/`、`docs/复盘/` +- **可直接跑的例子** → `examples/` + +--- + +## 常见问题 + +先看 **`docs/FAQ.md`**。最常见的四类: + +- judge 401 / 模型名失效; +- `/health` 200 但答不了(能力探针); +- 生产库被污染(345 行)⇒ 必须用隔离库; +- 429 `QUOTA_EXCEEDED`(被测会话预算 5 万 token)。 --- @@ -109,3 +155,19 @@ python3 -m venv .venv && .venv/bin/pip install -e '.[dev]' CI:`.github/workflows/eval-gate.yml` —— 独立成 job(不与代码门合并成一个绿灯),含自证/劣化回归/改动留痕/TDD 痕迹检查。 > **纪律**:改 Prompt / 工具 / 记忆 / **评估集** → 必跑 eval 回归;失败即补 case(`eval/cases/`)。 + +--- + +## 贡献 + +开发环境、TDD/门禁、commit/PR 规则见 **`CONTRIBUTING.md`**; +issue/PR 模板在 `.github/`。行为准则当前**不适用**(单人维护),触发条件见 `DEC-025`。 + +## 安全 + +漏洞请走 GitHub **私密漏洞报告**,⛔ 不要开公开 issue —— 见 **`SECURITY.md`**。 + +## 许可证 + +**MIT** —— 见 `LICENSE`。贡献即表示同意以 MIT 许可发布。 + diff --git a/ROADMAP.md b/ROADMAP.md index b5413ec..5bdc39b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -8,6 +8,11 @@ ## 当前指针(每次 commit 前更新) - `分支 | 阶段X-步骤Y | 模块 | L3基线 | 北极星`:`main | 阶段4-步骤9 ✅ **已终裁 PASS(D-18)** | E9 观测与成本 + 统计层 | L1 真实基线(`eval/l1_baseline.json`)+ **L1 阈值已接线(DEC-012)** · **L2 ≥0.95(DEC-013)** | 劣化被拦次数 = 1` +- **✅ 项目自用版已结项(2026-10-18)** —— 见 **`docs/结项报告-自用版-2026-10-18.md`**。 + 未做项 = **明确暂缓**(U2 跨仓 CI · M3 抽取判据 · `id=20` · 背景观察);建议 tag **`v0.4.0`**。 +- **📚 文档面(2026-10-18)**:索引 **`docs/README.md`** · `docs/FAQ.md` · `docs/CLI.md` · `docs/arch/` · + `LICENSE` / `CONTRIBUTING` / `SECURITY` / `SUPPORT` / `CHANGELOG` · `.github/` 模板 · `examples/`; + 范围与暂缓项见 **`DEC-025`**。 - **✅ 阶段4-步骤9(P4-2)已终裁(2026-09-14,签核 D-18)** —— 四条门禁逐条判过(**4 过**,第 2 条带 **QPS 显式豁免**); `gate-review` 初判的三条缺口已由 `DEC-012` 全部关闭。证据:`docs/reports/P4-2/` + `eval/l1_baseline.json`。 **界限:仅 P4-2**(`P5-1`/`P6-1`/`P6-2` 同期另行终裁,见下)。 @@ -48,6 +53,8 @@ | 4 | 过程错误复盘(两轮无效,83,000 judge token) | `docs/复盘/2026-10-18-语料筛选漏掉seed金标语料.md` | | 5 | `DEC-019` 补记 §7 | `docs/decisions/DEC-019-判分器放行口径.md` | | 6 | **修好 `run_sut.sh`**(适配 `app/` + 官方镜像;env 覆盖隔离库/会话预算) | `tools/sut-harness/run_sut.sh` · `DEC-023 §6` · 单测 11 passed + 真机 exit 0 | +| 7 | **语料可复现 + 结项** | `eval/corpus/` · `tools/export_eval_corpus.py` · `tools/seed_eval_corpus.py` · `docs/结项报告-自用版-2026-10-18.md` · `integrations/fastapi-rag-agent/` | +| 8 | **文档面按标准补齐** | `docs/README.md`(索引)· `docs/FAQ.md` · `docs/CLI.md` · `docs/arch/` · `LICENSE`/`CONTRIBUTING`/`SECURITY`/`SUPPORT`/`CHANGELOG` · `.github/` issue+PR 模板 · `examples/` · `DEC-025` | **对「α 会不会误伤」的回答**:`rule_hit_judge_fail = 0`、`soft_miss_judge_pass = 0`; 唯一失败 `id=20` 是**真实被测失败**(召回 `[55,64,8]`,未召回含「两者结果互补」的 doc 60), @@ -64,14 +71,15 @@ ⚠️ 关键坑:**不能把源码只读直接挂 `/app`**(应用要写 `.mem0/qdrant/.lock`)⇒ 只读挂 `/src` 再复制到可写 `/app`; - `EVAL_JUDGE_API_KEY` 曾失效(401),**已由业务方更新**(尾号 `fd3e`)。 -#### ⚠️ 下一会话开工要盯的 +#### 📌 结项后只剩维护项(**项目自用版已完结**) 1. **待签核 = 0**;没有未完成的评测节点。 2. **✅ 环境待办已清**:`tools/sut-harness/run_sut.sh` 已适配 `app/` + 官方镜像, 单测 11 passed + 真机端到端 exit 0(见 `DEC-023 §6`)。 -3. **非阻塞余项**:① 轮间 2× 延迟悬案(16 轮内 1 次,成因未指名) - ② 母体 Kit 缺陷观察(证据 1/2)③ R1 探针(生产库有无文档 —— 本轮已间接回答:**有 345 行**)。 -4. **`id=20` 的检索问题未修**(被测未改),只回灌不结论。 +3. **明确暂缓(不是遗漏)**:① U2 跨仓 CI(`integrations/fastapi-rag-agent/` 模板已备) + ② M3 抽取判据(须 DEC)③ `id=20` 被测检索问题(不改被测,只回灌)。 +4. **背景观察**:① 轮间 2× 延迟悬案(16 轮内 1 次,成因未指名) + ② 母体 Kit 缺陷观察(证据 1/2)③ R1 探针(生产库有无文档 —— 本轮已答:**有 345 行**)。 ### 📜 历史交接(**2026-09-21** 会话末,**已被上文 2026-10-18 取代**) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f3cfe66 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,50 @@ +# 安全策略 + +## 支持的版本 + +| 版本 | 支持 | +|---|---| +| `0.4.x` | ✅ 当前版本 | +| 更早版本 | ❌ 不再维护(自用版,无 LTS) | + +## 如何报告漏洞 + +**⛔ 不要开公开 issue。** + +请使用 GitHub 的**私密漏洞报告**: + +1. 打开 +2. 或:仓库 **Security** 标签页 → **Report a vulnerability** + +报告中请包含: + +- 受影响的版本 / commit; +- 复现步骤(最小命令或评测集); +- 影响面(密钥泄露 / 任意代码执行 / 数据外泄 / 评测结论被伪造 …); +- 你建议的修复方向(可选)。 + +## 范围 + +**在范围内**: + +- 本仓代码(`app/eval_gate/`、`tools/`、`.claude/hooks/`、`.githooks/`); +- 密钥/凭据处理(是否会被写进报告、日志、trace 或 git); +- 评测结论可被伪造(例如判据绕过、报告字段可被篡改); +- CI / 门禁可被绕过。 + +**不在范围内**: + +- **被测系统自身**的漏洞(本门不托管被测;请报给被测方); +- 第三方模型网关 / LLM 提供商的问题; +- 你自己 `.env` 里已泄露的 key(请先撤销并轮换,再报告影响)。 + +## 响应方式 + +单人维护、**尽力而为,无 SLA**。一般会在 **7 天内**确认收到; +修复时间取决于影响面与复现难度。修复前请**不要公开细节**。 + +## 安全相关的既有约束 + +- 密钥只从环境变量 / `.env` 读取,`.env` 不入库(`.gitignore`); +- 评测报告与 trace 对被测回答做**摘要/脱敏**(见 `observability/README.md`); +- 证据归档只保留 span 摘录,不保存被测回答原文(`tools/archive_evidence.py`)。 diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..da144ed --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,28 @@ +# 获取帮助 + +## 先看这些 + +| 你遇到的问题 | 先看 | +|---|---| +| 这是什么、怎么装 | `README.md` | +| 常见问题(密钥 / 429 / exit code / 语料) | **`docs/FAQ.md`** | +| 全部文档导航 | **`docs/README.md`** | +| 接自己的被测 | `docs/接入新被测.md` | +| 本机环境坑(TLS / IPv6 / 模型名) | `docs/部署.md §6` | +| 故障场景与演练 | `docs/故障场景应对手册.md` | +| 完整 CLI 参数 | `docs/CLI.md` | + +## 提问 / 报 bug + +- **Bug / 功能请求**:开 GitHub issue(用 `.github/ISSUE_TEMPLATE/` 的模板); +- **安全问题**:⛔ 不要开公开 issue → 见 `SECURITY.md`; +- **使用问题**:也走 issue,请贴上: + - 版本(`eval-gate --help` 或 `git rev-parse --short HEAD`); + - 复现命令; + - 报错全文 / `eval/runs/.local.json` 的关键字段(**先脱敏**)。 + +## 支持边界 + +- 单人维护、**尽力而为,无 SLA**; +- 不提供商业支持 / 托管服务; +- 被测系统自身的故障请找被测方。 diff --git a/app/eval_gate/__init__.py b/app/eval_gate/__init__.py index f4e9e2b..86ec577 100644 --- a/app/eval_gate/__init__.py +++ b/app/eval_gate/__init__.py @@ -1,3 +1,3 @@ """agent-eval-gate 评测门内核包(E1–E7,见 总纲.md §3)。""" -__version__ = "0.3.0" +__version__ = "0.4.0" diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 0000000..5795da2 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,147 @@ +# CLI 参考 + +> 入口:`eval-gate`(安装后)或 `python -m eval_gate`。安装见 `README.md` / `docs/部署.md`。 +> 子命令:`run` · `trace` · `calibrate` · `stats`。 + +## 全局 + +```bash +eval-gate --help +eval-gate <子命令> --help +``` + +退出码(所有子命令统一,见 `contracts/评测-report.md`): + +| code | 含义 | +|---|---| +| `0` | 全绿 | +| `1` | 阻断(通过率低于阈值 / 红队命中;或 `calibrate --fail-on-below` 低于阈值) | +| `2` | 存疑 / 需人工(judge 一致率、flag) | +| `3` | 运行错误 / 熔断 degraded(如 `E_SUT_QUOTA`;此时阈值判定作废) | + +--- + +## `eval-gate run` + +跑一轮评测,产出报告 + exit code。 + +| 参数 | 必填 | 说明 | +|---|---|---| +| `--evals PATH` | ✅ | 评测集 JSON(`eval/*.evals.json`) | +| `--mode good\|bad` | | `good`=忠实(默认);`bad`=劣化,用于**自证门会拦** | +| `--threshold FILE` | | 覆盖阈值文件(同一份 JSON 的数值) | +| `--offline` | | 强制离线 FakeJudge(不调真实模型) | +| `--report-dir DIR` | | 报告目录(默认 `eval/runs`) | + +```bash +# 离线自证 +python -m eval_gate run --evals eval/mini_rag_qa.evals.json --mode good --offline +python -m eval_gate run --evals eval/mini_rag_qa.evals.json --mode bad --offline + +# 真实链路(被测 + judge 都要配好) +python -m eval_gate run --evals eval/fastapi_rag_golden.evals.json --report-dir eval/runs +``` + +产物: + +| 文件 | 内容 | +|---|---| +| `.local.json` | 逐条证据 / judge 理由 / 汇总 / exit_code(不入库) | +| `.trace.jsonl` | span(不入库;被引用时用 `tools/archive_evidence.py` 归档) | +| `.summary.md` | 脱敏摘要(可入库) | + +> ⚠️ **`local.json` / `trace.jsonl` 被 `.gitignore` 排除**;要让结论可重算, +> 必须归档 `.spans.jsonl`(见 `tools/archive_evidence.py` 与 `tools/check_evidence_coverage.py`)。 + +--- + +## `eval-gate trace` + +打印某次 run 的 span 树。 + +| 参数 | 说明 | +|---|---| +| `--run RUN` | run_id(默认取最近一次) | +| `--trace-dir DIR` | trace 目录(默认 `eval/runs`) | + +```bash +python -m eval_gate trace +python -m eval_gate trace --run 20261018-182724-e6212c1d +``` + +--- + +## `eval-gate calibrate` + +算 judge 与人工标注的一致率(M1/E7)。 + +| 参数 | 说明 | +|---|---| +| `--refs REFS` | ✅ 人工标注参照集(默认文件 `eval/judge_refs.json`) | +| `--offline` | 用离线 FakeJudge | +| `--threshold FILE` | 阈值文件(取 `judge_human_agreement.min`) | +| `--fail-on-below` | 低于阈值时 **exit 1**(默认关闭;是否接自动门由使用方决定,`DEC-008 §5`) | + +```bash +python -m eval_gate calibrate --refs eval/judge_refs.json +python -m eval_gate calibrate --refs eval/judge_refs.json --fail-on-below +``` + +> ⚠️ **一致率默认不是阻断项**;参照集用尽后只能写「本参照集已耗尽信息」,不能写"已校准"。 + +--- + +## `eval-gate stats` + +从已有 trace 产真实 L1 基线(零 token)。 + +| 参数 | 必填 | 说明 | +|---|---|---| +| `--runs RUNS` | ✅ | run_id 列表(逗号分隔)或 glob,如 `20260912-*` | +| `--trace-dir DIR` | | trace 目录(默认 `eval/runs`) | +| `--out OUT` | ✅ | 基线 JSON 落盘路径 | +| `--rev REV` | | 写入 `_rev`(默认当天) | + +```bash +python -m eval_gate stats --runs '20260912-*' --out eval/l1_baseline.json +``` + +--- + +## 环境变量(常用) + +完整表见 `docs/部署.md §3`。 + +| 变量 | 说明 | +|---|---| +| `EVAL_JUDGE_BASE_URL` / `_API_KEY` / `_MODEL` | judge;三者缺一 ⇒ 回落离线 FakeJudge | +| `EVAL_JUDGE_MAX_TOKENS` / `_CONCURRENCY` | 默认 **4096** / 4 | +| `EVAL_SUT_FASTAPI_BASE_URL` / `_API_KEY` | 真实被测;base_url 用 `127.0.0.1` | +| `EVAL_SUT_FASTAPI_SNAPSHOT` | 走快照回放(被测不可用时) | +| `EVAL_LIVE` | 置 `1` 才跑 live 冒烟测试 | +| `EVAL_TRACE` | 置 `0` 关观测 | +| `EVAL_OTLP_ENDPOINT` | 外发 OTLP | +| `SSL_CERT_FILE` | 本机 TLS 拦截时必设 | +| `EVAL_SUT_RETRIES` / `_BACKOFF_S` / `_429_BACKOFF_S` | 重试 / 退避 | + +**阈值**:运行值取 `eval/阈值.json`;文件缺失时回落**更严**的兜底,绝不放宽门。 + +--- + +## 典型工作流 + +```bash +# 1) 离线自证(零 key、零外网) +python -m eval_gate run --evals eval/mini_rag_qa.evals.json --mode good --offline +python -m eval_gate run --evals eval/mini_rag_qa.evals.json --mode bad --offline + +# 2) 真实链路(先起被测 + 灌语料,见 docs/部署.md §5) +set -a; . eval/runs/.sut-harness.env; set +a +python -m eval_gate run --evals eval/fastapi_rag_golden.evals.json + +# 3) 看 trace +python -m eval_gate trace + +# 4) 校准(有人工标注时) +python -m eval_gate calibrate --refs eval/judge_refs.json +``` diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..3cd9498 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,133 @@ +# FAQ · 常见问题 + +> 这些问题**全部来自本仓真实踩过的坑**(报告 / 复盘 / 部署文档),不是通用模板。 +> 先看这里;没有答案再按 `SUPPORT.md` 提问。 + +## 1. 这是什么?和 promptfoo / deepeval / openai evals 有什么区别? + +本仓是**CI 门**:给「被测系统的输入 → 输出文本」打分,产出 **exit code**, +让「这次改动能不能上线」变成一个可阻断的检查。 +它不是评测数据集市场,也不是 SaaS 看板;核心是 **确定性规则 + LLM-judge + 阈值 + 报告 + 可复现**。 +架构见 `docs/arch/README.md`,边界见 `需求基线.md §9`。 + +## 2. 不联网、没有 key 能跑吗? + +能。用自带的迷你被测和离线 FakeJudge: + +```bash +.venv/bin/python -m eval_gate run --evals eval/mini_rag_qa.evals.json --mode good --offline # → exit 0 +.venv/bin/python -m eval_gate run --evals eval/mini_rag_qa.evals.json --mode bad --offline # → exit 1 +``` + +`--offline` 只是**自证管线**;真实语义判分必须配 judge(`EVAL_JUDGE_*`)。 + +## 3. judge 报 401 / 模型不存在怎么办? + +- **401**:key 失效或被轮换。检查 `.env` 的 `EVAL_JUDGE_API_KEY`; + ⚠️ **不要**把 key 贴进 issue。 +- **模型不存在 / 行为变化**:模型名可能已被官方停用 + (例:DeepSeek 2026-07-24 起停用 `deepseek-chat` / `deepseek-reasoner`)。 + ✅ 但注意:**网关可能不校验模型名** —— 能调通 ≠ 名字有效,以官方文档为准。 +- 查看当前生效配置:`eval-gate run ...` 输出的「生效 judge 配置」行。 + +## 4. `/health` 返回 200,但评测里全 fail? + +**`/health` 只查 DB/Redis,不代表被测答得了。** +必须先跑**能力探针**: + +```bash +EVAL_SUT_FASTAPI_API_KEY=... tools/sut-harness/run_sut.sh +# 退出码 0 = 就绪且能作答 · 1 = 起不来 · 2 = 起来了但答不了 +``` + +`exit 2` 时**不要**据此判被测质量,先归因环境(模型 / embedding / 语料)。 +历史教训见 `docs/复盘/2026-09-11-P4-1-过程错误.md`(E7)。 + +## 5. 为什么不能直接拿生产库跑评测? + +本机生产库 `rag_db` 已混入其它项目/测试语料(实测 **345 行**), +而评测语料只占约 **125 行**。直接跑会让 `top_k` 被无关语料挤占, +失败**无法归因**(分不清是被测退化、判分器变严,还是语料污染)。 + +⇒ 用**隔离库**(如 `rag_eval_20261018`),原库不动。 +原因与代价见 `DEC-023` / `docs/复盘/2026-10-18-语料筛选漏掉seed金标语料.md`。 + +## 6. 评测语料为什么不在仓库里?换机器怎么复现? + +本仓是 **Public**,知识库正文不能进公开仓历史。 +因此:**仓内只有清单 + sha256**(`eval/corpus/manifest.json`),正文放仓外 +(`~/Desktop/Product-external/eval-corpus/`)。 + +换机器: +```bash +# 1) 把语料文件放到任意路径(不要放进任何 git 仓) +# 2) 校验 + 灌入(哈希不一致会拒绝) +python3 tools/seed_eval_corpus.py \ + --corpus /path/to/fastapi_rag_eval_corpus-20261018.jsonl \ + --manifest eval/corpus/manifest.json --dry-run +``` + +## 7. 跑着跑着出现 429 `QUOTA_EXCEEDED`? + +新版被测有**会话预算**(默认 **50,000 token / 用户 / 会话 / 日**), +不是限流,是额度用完。48 条一轮会接近这个上限。 + +处理: +- 起被测时放宽:`EVAL_SUT_SESSION_TOKEN_LIMIT=200000 tools/sut-harness/run_sut.sh`; +- 先查今日已用:`SELECT SUM(total_tokens) FROM token_usage_logs WHERE created_at >= CURRENT_DATE;` +- ⚠️ 别把它读成被测质量崩了:尾部的 `429` 会污染失败归因。 + +## 8. exit 0 / 1 / 2 / 3 分别是什么? + +| code | 含义 | CI 处置 | +|---|---|---| +| `0` | 全绿 | 放行 | +| `1` | 阻断(通过率低于阈值 / 红队命中) | 阻断 | +| `2` | 存疑 / 需人工(judge 一致率、flag) | 人工复核 | +| `3` | 运行错误 / 熔断 degraded(如 `E_SUT_QUOTA`) | 告警,不算绿 | + +详见 `contracts/评测-report.md` 的「exit code 语义」。 + +## 9. judge 和我的人工判断不一致,怎么办? + +先跑校准,不要直接改判分器: + +```bash +.venv/bin/python -m eval_gate calibrate --refs eval/judge_refs.json +``` + +- 一致率阈值在 `eval/阈值.json` 的 `judge_human_agreement`(默认 0.80); +- **默认不作阻断项**(`DEC-008 §5`);需要阻断时加 `--fail-on-below`; +- 分歧先看是不是**参照集口径**问题(见 `DEC-017` / `docs/校准/`)。 + +## 10. 为什么红队 / 拒答 / 禁现词走确定性层,不交给 judge? + +这是**契约不变量**:红队与注入类不进 LLM-judge,避免"判分器被说服"。 +硬层(必拒 / 禁现 / 空回答)由确定性规则权威,**judge 不可翻案**; +软层(`answer_contains`)才交 judge。见 `DEC-004` / `DEC-022` / `总纲.md §1`。 + +## 11. 怎么接入我自己的被测? + +判据内核不改,只动**适配器层 3 处**(类、注册、`SUPPORTED_SUTS`), +其余是加数据(评测集 / 连接配置 / 语料)。 +完整步骤与硬门槛见 **`docs/接入新被测.md`**。 + +## 12. 能接进我们项目的发版 CI 吗? + +**目前没有接。** 本仓只提供模板: +`integrations/fastapi-rag-agent/`(范围 / 顺序 / 验收标准)。 +接入要动**另一个仓**的 workflow + secrets,并决定触发方式(建议 **发版 tag / 手动**,不要每个 PR)。 +每次 live ≈ 4 万 token,成本必须可控。 + +## 13. 支持 Windows 吗? + +**未验证。** 开发/CI 在 macOS + Linux 上跑;真实被测建议用 Docker。 +Windows 用户建议用 WSL2;遇到问题按 `SUPPORT.md` 提 issue。 + +## 14. 一轮评测大概多少钱? + +参考实测(48 条,`deepseek-v4-flash`): +- judge 侧:**约 3–4 万 token**(2026-10-18 那轮 39,697); +- 被测侧:约 4–5 万 token(取决于被测自己的改写/生成); +- 具体数字见 `docs/reports/` 对应报告。 + ⚠️ **开跑前先确认预算**,不要默认"跑一下不要钱"。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..dcf48c8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,90 @@ +# docs/ · 文档索引 + +> **不知道看哪份时,从这张表进。** +> 新增/移动文档时,**必须同步更新本索引**(否则下一个人找不到 —— 这是本仓反复踩过的坑)。 + +## 1. 第一次来 + +| 你想知道 | 看 | +|---|---| +| 这是什么、怎么装、怎么跑 | `../README.md` | +| 常见问题(密钥 / 429 / exit code / 语料) | **`FAQ.md`** | +| 全部 CLI 参数与 exit code | **`CLI.md`** | +| 怎么接真实被测、本机环境坑 | **`部署.md`** | +| 项目现在做到哪、哪些暂缓 | **`结项报告-自用版-2026-10-18.md`** | + +## 2. 接入自己的被测 + +| 你想知道 | 看 | +|---|---| +| 要改哪 3 处代码、门槛是什么 | **`接入新被测.md`** | +| 评测集 / 适配器 / 报告契约 | `../contracts/` | +| 第二家被测的接入检查单 | `specs/M3-第二个被测接入-检查单.md` | +| 评测语料怎么复现 | `../eval/corpus/README.md` | +| 真实被测运行层(harness) | `../tools/sut-harness/README.md` | + +## 3. 理解设计 + +| 你想知道 | 看 | +|---|---| +| 业务口径 / 范围 / 成功标准 | `../需求基线.md` | +| 七层架构 / E1–E9 模块 | `../总纲.md` | +| **当前架构图**(C4 / 组件 / 时序) | **`arch/README.md`** | +| 每个选型为什么这么定 | `decisions/DEC-*.md`(DEC-001 … DEC-025) | +| 节点设计与实施计划 | `specs/` · `plans/` | +| 术语(SUT / judge / 硬层 / 软层) | `../总纲.md §3` · `FAQ.md` | + +## 4. 运行与排障 + +| 你想知道 | 看 | +|---|---| +| 部署 / 配置 / 环境坑 | `部署.md`(尤其 §6) | +| 故障场景与演练 | `故障场景应对手册.md` | +| 观测 / trace / 脱敏 | `../observability/README.md` | +| 过程错误复盘(真踩过的) | `复盘/` | +| 推送 / 网络 / 凭据类问题 | `复盘/2026-09-12-推送失败归因未验证.md` · `复盘/2026-09-21-凭据串凭记忆写给用户.md` | + +## 5. 项目治理与状态 + +| 你想知道 | 看 | +|---|---| +| 新会话从哪接 | `../CLAUDE.md`(当前指针) | +| 执行图 / 节点状态 / 交接 | `../ROADMAP.md` | +| 结项范围与暂缓项 | **`结项报告-自用版-2026-10-18.md`** | +| 结项决策(许可证 / 语料存放 / U2 暂缓) | `decisions/DEC-024-*.md` · `decisions/DEC-025-*.md` | +| 留痕 × L1/L2/L3 挂钩 | `留痕×指标挂钩.md` | +| 记忆 / 事实纪律 | `memory-规约.md` | +| 单人角色分工 | `单人-角色映射.md` | +| 从零开一个 Agent 项目 | `使用说明-从零开Agent项目.md` · `RUNBOOK.md` | +| 知识库同步映射 | `知识库同步映射.md` | +| 选型 DEC 模板 | `DEC-选型模板.md` | + +## 6. 历史与证据 + +| 你想知道 | 看 | +|---|---| +| 各阶段报告(P4-1 / P4-2 / M2 / M3 / T4 / DEC-019 live) | `reports/` | +| judge 校准标注表 | `校准/` | +| 失败案例库 | `../eval/cases/` | +| 过程错误复盘 | `复盘/` | +| 评测运行记录 | `../eval/runs/`(本地,不入库;引用时归档) | +| 数据飞轮 | `../飞轮/README.md` | + +## 7. 仓库健康文件 + +| 文件 | 用途 | +|---|---| +| `../LICENSE` | MIT | +| `../CONTRIBUTING.md` | 开发环境 / TDD / 门禁 / PR | +| `../SECURITY.md` | 私密漏洞报告 | +| `../SUPPORT.md` | 提问入口与支持边界 | +| `../CHANGELOG.md` | 面向使用者的变化 | +| `../.github/ISSUE_TEMPLATE/` | issue 模板 | +| `../.github/PULL_REQUEST_TEMPLATE.md` | PR 模板 | + +## 8. 阅读纪律 + +- **历史文档按过去时读**:`reports/`、`plans/`、`复盘/`、`decisions/` 里写的"当前/下一步", + 只对**当时**成立;当前事实以 `CLAUDE.md`、`ROADMAP.md`、`结项报告` 为准。 +- **架构变化**:同时更新 `总纲.md §1.1` 与 `arch/README.md`。 +- **新增文档**:更新本索引;如果它有"标准/规矩",同时登记进 `../CLAUDE.md` 或 `../README.md` 的入口。 diff --git a/docs/arch/README.md b/docs/arch/README.md new file mode 100644 index 0000000..8de6166 --- /dev/null +++ b/docs/arch/README.md @@ -0,0 +1,110 @@ +# docs/arch · 当前架构图(C4 视角,2026-10-18) + +> **用途**:把「系统现在长什么样」画清楚,避免后来人从历史文档里拼出一个过期架构。 +> 事实源:`总纲.md §1`(七层)与 `§3`(E1–E9 模块);本文只画**当前形态**,不重复模块细节。 +> +> **图例**:实线 = 已落地并验证;虚线 = **未接线 / 未接入**(不是已实现)。 + +## 1. C4-L1:系统上下文 + +```mermaid +flowchart LR + DEV["开发者 / CI"] --> GATE["agent-eval-gate
CLI 评测门"] + GATE -->|"HTTP / 快照"| SUT["被测 Agent 系统
fastapi-rag / toolkit"] + GATE -->|"评分请求"| JUDGE["LLM-as-Judge
OpenAI 兼容端点"] + CORPUS["评测语料
仓内 manifest + 仓外正文"] -->|"seed(校验 sha256)"| SUT + GATE --> RPT["报告 + exit code"] + RPT --> EVID["证据归档
spans.jsonl"] + RELEASE["真实被测的发版 CI
⬜ 未接入(模板)"] -.-> GATE +``` + +**当前边界(2026-10-18 结项)**: + +- 被测系统由**它自己的**进程/容器运行;本门只通过适配器取输出,**不托管 Agent 运行时**; +- 真实发版 CI **未接入** —— 模板在 `integrations/fastapi-rag-agent/`; +- 评测语料正文**不在公开仓**,只留清单与哈希。 + +## 2. C4-L2:容器 / 组件 + +```mermaid +flowchart TB + subgraph GATE["agent-eval-gate(CLI)"] + E1["E1 评测集管理
schema / 阈值装载"] + E2["E2 被测适配器
HTTP / 快照"] + E3["E3 确定性规则
注入/越权/拒答/禁现"] + E4["E4 LLM-judge
分数 + 理由"] + E5["E5 调度/批次
并发 · 熔断 · 重试"] + E6["E6 聚合与阈值
L2 + exit code"] + E7["E7 报告与基线
逐条证据/理由"] + E8["E8 审计与安全
脱敏 · 留痕"] + E9["E9 观测与成本
trace_id · token"] + end + + E1 --> E5 + E2 --> E5 + E5 --> E3 + E5 --> E4 + E3 --> E6 + E4 --> E6 + E6 --> E7 + E7 --> E9 + E8 -.-> E7 + + H["SUT harness
官方镜像 + 能力探针 + 自证"] --> E2 + C["语料清单 + seed 工具"] --> H + REPO["eval/runs + eval/cases"] --- E7 + ARCH["证据归档 + 覆盖守卫"] --- E7 +``` + +| 关注点 | 落点 | +|---|---| +| 判据分层(硬层 / 软层 / 第三态) | `DEC-004` · `DEC-022` · `app/eval_gate/rules.py` | +| 调度顺序锁(确定性 → judge) | `runner.py` · 契约测试 | +| 真实被测运行 | `tools/sut-harness/run_sut.sh` | +| 语料复现 | `eval/corpus/manifest.json` + `tools/seed_eval_corpus.py` | +| 证据可重算 | `tools/archive_evidence.py` + `tools/check_evidence_coverage.py` | +| 发版 CI 接入(未做) | `integrations/fastapi-rag-agent/` | + +## 3. 一次 live run 的时序 + +```mermaid +sequenceDiagram + autonumber + participant Dev as 开发者 / CI + participant CLI as eval-gate + participant Harness as SUT harness + participant SUT as 被测 + participant Judge as LLM-judge + participant Disk as 报告 / 证据 + + Dev->>CLI: run --evals eval/fastapi_rag_golden.evals.json + CLI->>CLI: E1 装载 + schema 校验(坏配置零模型调用即失败) + opt 真实链路(预先执行) + Dev->>Harness: run_sut.sh(起依赖 + 官方镜像) + Harness->>SUT: 能力探针(/health 200 ≠ 答得了) + Dev->>SUT: seed 评测语料(sha256 校验) + end + loop 每条 case(E5 分批/并发) + CLI->>SUT: 适配器请求 + SUT-->>CLI: 输出文本 + sources + CLI->>CLI: E3 确定性规则(硬层可阻断) + opt 软层需要 + CLI->>Judge: 问题 + 期望 + 回答 + Judge-->>CLI: 分数 + 理由 + end + end + CLI->>CLI: E6 聚合 + 阈值判定 + CLI->>Disk: L2 报告 + trace + 摘要 + CLI-->>Dev: exit 0 / 1 / 2 / 3(见契约) +``` + +## 4. 与历史图的关系 + +- `总纲.md §1` 的七层图是**职责适配**层面的蓝图,长期稳定; +- 本文是**当前部署/组件形态**,会随工具链变化(例如将来接入发版 CI); +- **改架构必须同时改两处**:本文 + `总纲.md §1.1`,否则两份图会漂移。 + +## 变更记录 + +- 2026-10-18 建立(自用版结项):补上此前只在 `总纲.md` 里被引用、但**目录不存在**的 `docs/arch`; + 当前形态 = 评测内核 + SUT harness + 语料复现 + 证据归档;发版 CI 标为未接入。 diff --git "a/docs/decisions/DEC-024-\350\207\252\347\224\250\347\211\210\347\273\223\351\241\271\350\214\203\345\233\264\344\270\216\350\257\255\346\226\231\345\255\230\346\224\276.md" "b/docs/decisions/DEC-024-\350\207\252\347\224\250\347\211\210\347\273\223\351\241\271\350\214\203\345\233\264\344\270\216\350\257\255\346\226\231\345\255\230\346\224\276.md" new file mode 100644 index 0000000..7a238cf --- /dev/null +++ "b/docs/decisions/DEC-024-\350\207\252\347\224\250\347\211\210\347\273\223\351\241\271\350\214\203\345\233\264\344\270\216\350\257\255\346\226\231\345\255\230\346\224\276.md" @@ -0,0 +1,60 @@ +# DEC-024 · 自用版结项范围与语料存放 + +- 状态:**已实施**(2026-10-18) +- 类型:结项范围 + 数据存放决策 +- 关联:`DEC-023`(live 回归环境)· `docs/结项报告-自用版-2026-10-18.md` + +## 1. 背景 + +项目进入收尾。两个问题必须明确,否则"结项"会变成含糊的停更: + +1. **评测语料放哪里?** 本仓是 **Public**,而被测知识库正文可能含业务内容; +2. **U2(接进真实被测的发版 CI)现在做不做?** 它必须改另一个仓 + (`fastapi-rag-agent` 是 Private),并配置 secrets、决定预算与触发。 + +## 2. 备选方案 + +### 2.1 语料存放 + +| 方案 | 做法 | 优点 | 代价 / 结论 | +|---|---|---|---| +| A. 正文进本仓 | 把 125 行语料 JSONL 提交到 `eval/corpus/` | 复现最简单 | **否决**:公开仓泄露正文;git 历史删不干净 | +| **B. 仓内清单 + 仓外正文(选定)** | 仓内只放 `manifest.json`(sha256/行数/来源计数);正文放 `~/Desktop/Product-external/eval-corpus/`(不在任何 git 仓) | 可校验、可复现、不泄露 | 换机器需先还原正文;seed 前必须过哈希 | +| C. 不固化语料 | 只记录"当时库里有 125 行" | 零成本 | **否决**:live 回归不可复现(本轮已因此浪费 43,303 token) | + +### 2.2 U2 是否现在接 + +| 方案 | 做法 | 代价 | 结论 | +|---|---|---|---| +| A. 现在改另一个仓 | 在 `fastapi-rag-agent` 加 workflow + secrets + 语料供给 | 跨仓改动;每次 live ≈4 万 token;触发方式未定 | **业务方 2026-10-18 明确:暂不做** | +| **B. 本仓备模板、跨仓延后(选定)** | `integrations/fastapi-rag-agent/` 放 README + `eval-gate.yml.example`,标注**未接入** | U2 仍未闭环 | 选定;接入时的范围/顺序/验收已写清 | + +### 2.3 版本号 + +- **`v0.4.0`(自用版,选定)** —— 只代表自用闭环,不代表可外化; +- `v1.0.0` **保留**,前置 = U2 接进真实发版 CI + 至少一个外部使用者验证。 + +## 3. 决策 + +1. 语料:**仓内清单 + 仓外正文**,`seed_eval_corpus.py` **强制校验 sha256**,不一致即拒绝; +2. U2:**本仓只备模板,不改另一个仓**;接入顺序与验收写在 `integrations/fastapi-rag-agent/README.md`; +3. 版本:**`v0.4.0` 自用版结项**;`v1.0.0` 不外推。 + +## 4. 认下的代价 + +- ⚠️ **U2 未闭环**:"劣化在真实发版 CI 被拦"目前仍只在手动流程成立; +- ⚠️ **换机器要还原语料**:正文不在任何 git 仓 ⇒ 只有本机 `Product-external` 有副本; + (清单里的 sha256 让"缺/错语料"能被立刻发现,但它不能凭空恢复正文) +- ⚠️ **公开仓仍含评测问题与期望**(`eval/*.evals.json`),这是既有事实; + 本次只保证**不把知识库正文**再带进来。 + +## 5. 验证 + +- `pytest`: **597 passed / 2 skipped**; +- `tools/export_eval_corpus.py` 重新导出 → 与 `eval/corpus/manifest.json` 的 sha256 **一致**; +- `tools/seed_eval_corpus.py --dry-run`:125 条 · sha256 通过; +- `tools/check_evidence_coverage.py`:**✅ 通过**。 + +## 变更记录 + +- 2026-10-18 建立。 diff --git "a/docs/decisions/DEC-025-\345\274\200\346\272\220\346\226\207\346\241\243\351\235\242\344\270\216\350\256\270\345\217\257\350\257\201.md" "b/docs/decisions/DEC-025-\345\274\200\346\272\220\346\226\207\346\241\243\351\235\242\344\270\216\350\256\270\345\217\257\350\257\201.md" new file mode 100644 index 0000000..94c7ab2 --- /dev/null +++ "b/docs/decisions/DEC-025-\345\274\200\346\272\220\346\226\207\346\241\243\351\235\242\344\270\216\350\256\270\345\217\257\350\257\201.md" @@ -0,0 +1,80 @@ +# DEC-025 · 开源文档面与许可证 + +- 状态:**已实施**(2026-10-18) +- 类型:仓库文档面 / 许可证 / 安全报告渠道 +- 关联:`docs/结项报告-自用版-2026-10-18.md` · `DEC-024`(结项范围与语料存放) + +## 1. 背景 + +本仓是 **Public**。结项前对照了三类标准: + +1. **GitHub 社区健康文件**(README / LICENSE / CONTRIBUTING / SECURITY / CODE_OF_CONDUCT / SUPPORT + + issue/PR 模板 + CHANGELOG); +2. **Standard Readme**(标题 / 描述 / 目录 / 安装 / 用法 / 贡献 / 许可证); +3. **同类评测项目的实际结构** + (promptfoo · openai/evals · deepeval · inspect_ai:普遍有 `docs/` + `examples/` + CONTRIBUTING + PR 模板)。 + +审计结果:本仓缺 **LICENSE / CONTRIBUTING / SECURITY / SUPPORT / CHANGELOG / FAQ / docs 索引 / +examples / issue+PR 模板**,且 `github/` 下的模板文档**不在 `.github/`**,GitHub 不会展示。 + +## 2. 决策 + +### 2.1 许可证:**MIT** + +| 方案 | 评价 | +|---|---| +| **MIT(选定)** | 最短、最通用;参考的同类项目多数用 MIT(promptfoo / openai/evals / inspect_ai)。与"自用先行、以后外化"一致 | +| Apache-2.0 | 有显式专利授权,但文本更长、合规成本更高;deepeval 用它 | +| 暂不授权(proprietary) | 公开仓默认"保留所有权利" ⇒ 别人不能合法复用,与 Public 的目的冲突 | + +**代价**:MIT 不提供专利授权与商标条款;若将来需要,替换 `LICENSE` + `pyproject.toml` 两处即可, +但**已发布的版本无法追改**(旧 tag 仍是旧许可证)。 + +### 2.2 安全报告:**GitHub 私密漏洞报告** + +- 渠道:仓库 **Security → Report a vulnerability**(`SECURITY.md` 写明); +- **不公开邮箱**:单人维护,公开邮箱会带来垃圾与社工面; +- 代价:依赖 GitHub 的私密报告功能(该仓已启用);若将来迁出 GitHub,需要在 `SECURITY.md` 换渠道。 + +### 2.3 行为准则:**暂不采用** + +- 单人维护、无社区治理流程,采用 Contributor Covenant 会引入"谁来执行/如何申诉"的空承诺; +- **明确记为"不适用(当前)"**,不是遗忘;`CONTRIBUTING.md §7` 写清基本要求与保留关闭权; +- **触发条件**:开放外部维护者 / 接受外部 PR 成为常态时,**先补正式 CoC**。 + +### 2.4 FAQ 放哪:**`docs/FAQ.md`**,不放根级 `FAQ.md` + +- GitHub 的社区健康文件清单里**没有 FAQ**;参考项目也把 FAQ 放在 docs 站 / Troubleshooting; +- FAQ 内容**只收本仓真实踩过的坑**(密钥 401 / 能力探针 / 生产库污染 / 语料复现 / 429 / exit code / 校准)。 + +### 2.5 模板位置:**`.github/`** + +- `github/issue-模板-labels.md` 与 `github/pr-模板-评审.md` 是**说明文档**,GitHub 不识别; +- 本次新增 `.github/ISSUE_TEMPLATE/*.yml` 与 `.github/PULL_REQUEST_TEMPLATE.md`, + 内容按上面的说明文档改写为 GitHub 可展示的格式;旧说明文档保留(作为依据)。 + +## 3. 本次范围 + +**做(P0+P1)**:LICENSE · SECURITY · SUPPORT · CONTRIBUTING · CHANGELOG · FAQ · CLI 参考 · +docs 索引 · examples · issue/PR 模板 · README 目录/贡献/许可证段 · pyproject 元数据 · 架构图。 + +**暂缓(P2)**:`CODE_OF_CONDUCT.md`(见 §2.3)· `CITATION.cff`(非学术项目)· +`GOVERNANCE.md` / `CODEOWNERS`(单人)· README badges · 独立文档站。 + +## 4. 验证 + +- `pytest`:**597 passed / 2 skipped**; +- `examples/offline-demo.sh`:good → **exit 0**,bad → **exit 1**(脚本自身 exit 0); +- 证据覆盖守卫:✅ 通过; +- 所有新增文档的入口都登记在 `docs/README.md` 与根 `README.md`。 + +## 5. 认下的代价 + +- ⚠️ **许可证是法律选择**:本次按推荐默认 MIT;若你实际要 Apache-2.0 或 proprietary, + 必须**在发布前**改,发布后旧 tag 无法追改; +- ⚠️ **CoC 暂缺**:外部贡献者多起来时会被 GitHub 社区健康检查标黄,须按触发条件补; +- ⚠️ **文档面补齐 ≠ 功能闭环**:`U2 发版 CI` 仍未接入(见 `DEC-024`)。 + +## 变更记录 + +- 2026-10-18 建立。 diff --git "a/docs/\346\216\245\345\205\245\346\226\260\350\242\253\346\265\213.md" "b/docs/\346\216\245\345\205\245\346\226\260\350\242\253\346\265\213.md" index 389a98e..10b4cf4 100644 --- "a/docs/\346\216\245\345\205\245\346\226\260\350\242\253\346\265\213.md" +++ "b/docs/\346\216\245\345\205\245\346\226\260\350\242\253\346\265\213.md" @@ -4,6 +4,10 @@ > 答:**要,但只有 3 处,且全在适配器层**;其余全是加数据。 > 依据 = 代码事实(每条给 `文件:行号`)+ 两次真实接入的实测(见 §6)。 > 相关:`docs/specs/M3-第二个被测接入-检查单.md`(选型与流程)· `contracts/评测-sut-adapter.md`(接口契约) +> +> ⚠️ **项目状态(2026-10-18)**:自用版已结项,本文的接入方法仍适用; +> 但「把评测门接进对方**发版 CI**」这一步**尚未接入** +> (模板见 `integrations/fastapi-rag-agent/`,范围与暂缓理由见 `docs/结项报告-自用版-2026-10-18.md`)。 --- @@ -55,7 +59,7 @@ |---|---| | **评测集**(一个 JSON) | 顶层 `version / threshold_ref / sut_default` + `evals[]`;**文件名与路径没有任何代码注册过** —— CLI 由 `--evals ` 显式传入,运行时按 `case.sut` 派发 | | **被测的连接配置** | 新适配器自己的环境变量(如 `EVAL_SUT__BASE_URL`),写在适配器类里;`.env.example` 补示例 | -| **语料**(若被测需要) | 视被测而定:有的要评测方塞(第二家提供 `POST /retrieval/index`),有的要评测方 seed(第一家要在它 DB 里灌 golden 文档) | +| **语料**(若被测需要) | 视被测而定:有的要评测方塞(第二家提供 `POST /retrieval/index`),有的要评测方 seed(第一家要在它 DB 里灌 golden 文档)。**第一家已固化**:`eval/corpus/manifest.json`(sha256/行数)+ 仓外正文 + `tools/seed_eval_corpus.py`(seed 前校验哈希);**正文不进公开仓**。 | ⚠️ **每条 case 必须有非空 `input.question`(字符串)** —— 这是 schema 的硬约束。 非问答形态(如结构化抽取)把输入文本塞进 `question` 复用该字段(见 `eval/toolkit_extract_smoke.evals.json`)。 @@ -86,6 +90,10 @@ 另:报告的 `sut_versions` 字段在契约里有、代码里**尚未写出**。 +> ⚠️ **结项口径(2026-10-18)**:上面两条**明确暂缓**(不是遗漏) —— +> ① 阈值按被测分档未做;② 抽取类判据仍「含其一即符」。 +> 若要正式判抽取质量,须立 DEC;清单见 `docs/结项报告-自用版-2026-10-18.md` §4。 + --- ## 5. 接入的验收 = **转正判据**(照做即可) diff --git "a/docs/\347\273\223\351\241\271\346\212\245\345\221\212-\350\207\252\347\224\250\347\211\210-2026-10-18.md" "b/docs/\347\273\223\351\241\271\346\212\245\345\221\212-\350\207\252\347\224\250\347\211\210-2026-10-18.md" new file mode 100644 index 0000000..3d23d19 --- /dev/null +++ "b/docs/\347\273\223\351\241\271\346\212\245\345\221\212-\350\207\252\347\224\250\347\211\210-2026-10-18.md" @@ -0,0 +1,123 @@ +# 项目结项报告 · 自用版(2026-10-18) + +> **结论**:**自用版完结**(建议 tag `v0.4.0`)。 +> 按 `需求基线.md` 的第一版验收口径,功能与证据链已闭环; +> **未完成项全部是"明确暂缓"**,逐条列在 §4,不是遗忘。 +> `v1.0.0` 留给「U2 接进真实发版 CI + 外部使用者验证」之后。 + +## 1. 验收对照 + +### 1.1 `需求基线.md §9` 的 MVP 范围 + +| 范围 | 状态 | 证据 | +|---|---|---| +| CLI/库:`evals.json` → 确定性检查 + LLM-as-Judge → L2 报告 + 阈值 + exit code | ✅ | `app/eval_gate/` · `eval-gate run` | +| schema 与校验、阈值文件、报告(含每条证据/理由) | ✅ | `contracts/` · `eval/阈值.json` · `eval/runs/*.summary.md` | +| 自带最小被测样例(迷你 RAG-QA) | ✅ | `eval/mini_rag_qa.evals.json` | +| GitHub Actions 接入示例 | ✅ | `.github/workflows/eval-gate.yml` | + +### 1.2 U1(自证闭环) + +| 成功标准 | 结果 | +|---|---| +| L2 任务完成率 ≥ 阈值(0.95) | ✅ 最新 live **0.9792**(47/48) | +| judge-人工一致率 ≥ 阈值(0.80) | ✅ `calibrate` **0.88 → 1.00** | +| 确定性红队项全过 | ✅ 红队突破 **0** | +| 报告可解释(逐条证据/理由) | ✅ 报告 + trace 可回溯 | + +**劣化冒烟**:CI 每轮跑 `--mode bad` 并断言 `exit 1`;2026-09-10 真实劣化演示被 `redteam_zero` + `l2` 拦下。 + +### 1.3 U2(接真实项目发版前) + +| 项 | 状态 | +|---|---| +| 真实被测接入(2 家真实系统、4 个 adapter) | ✅ | +| 真实链路 live 评测(多轮) | ✅ | +| **挂进真实项目的发版 CI** | ⬜ **明确暂缓** —— 业务方 2026-10-18 决定**暂不动另一个仓**;模板见 `integrations/fastapi-rag-agent/` | + +### 1.4 B 阶段与最短路径 + +- B 六阶段 **12/12 节点闭环**,业务方签核 **D-1 … D-29**; +- M0–M5 全部完成(M5 带已签核豁免); +- 待签核 **0**。 + +## 2. 关键指标(截至 2026-10-18) + +| 指标 | 值 | +|---|---| +| 单元/契约测试 | **597 passed / 2 skipped** | +| 覆盖率 | **94.59%**(CI 硬门 85%) | +| 最新真实 live | **47/48 · 0.9792 · exit 0** · judge 39,697 token | +| 判分器金丝雀 | **0/8**(改前 3/8 被放过) | +| judge-人工一致率 | **1.00**(本参照集已耗尽信息) | +| 红队突破 | **0** | +| 错误率 / 门自身开销 | 0.0000 / 0.000507 | + +## 3. 交付物 + +| 类别 | 位置 | +|---|---| +| 实现 | `app/eval_gate/` · `tools/` · `.claude/`(门禁) | +| 契约 / 评测集 | `contracts/` · `eval/*.evals.json` · `eval/corpus/manifest.json` | +| 决策 | `docs/decisions/DEC-001 … DEC-023` | +| 失败回灌 | `eval/cases/` | +| 复盘 | `docs/复盘/` | +| 报告 | `docs/reports/`(P4-1 · P4-2 · M2 · M3 · T4 · DEC-019 live 回归) | +| 架构图 | `docs/arch/README.md`(C4 上下文 / 组件 / 时序;2026-10-18 补齐) | +| 集成模板 | `integrations/fastapi-rag-agent/`(未接入) | +| 运行适配层 | `tools/sut-harness/`(官方镜像 + 能力探针 + 自证) | +| 语料复现 | `eval/corpus/`(清单 + 哈希)· `tools/export_eval_corpus.py` · `tools/seed_eval_corpus.py` | +| 仓库健康文件 | `LICENSE`(MIT)· `CONTRIBUTING.md` · `SECURITY.md` · `SUPPORT.md` · `CHANGELOG.md` | +| 使用者文档 | `docs/FAQ.md` · `docs/CLI.md` · `docs/README.md`(索引)· `examples/` | +| GitHub 模板 | `.github/ISSUE_TEMPLATE/` · `.github/PULL_REQUEST_TEMPLATE.md` | + +## 4. 明确未做 / 暂缓(**不是遗忘**) + +| # | 项 | 原因 | 触发条件 / 入口 | +|---|---|---|---| +| 1 | **U2:接进 `fastapi-rag-agent` 发版 CI** | 业务方 2026-10-18:**暂不动另一个仓** | 模板 + 接入顺序见 `integrations/fastapi-rag-agent/README.md`;要动时需一个跨仓决策 | +| 2 | **M3 抽取类判据偏弱** | 「含其一即符」抽对 1 项即过;正式判抽取需"必须含全部 N 项" | 须单独 DEC | +| 3 | **`id=20` 被测检索失败** | 属被测侧;按纪律不改被测 | `eval/cases/fastapi-rag-2026-10-18.json`(`status=open`) | +| 4 | 轮间 2× 延迟悬案 | 16 轮内 1 次,成因未指名;`DEC-012` 已刻意不接线延迟类 | 需要新数据(≈9 万 token)才可能指名 | +| 5 | 母体 Kit 缺陷观察 | 证据 1/2,停观察态 | 第二个派生项目复现时再提 | +| 6 | 对外访谈 / 外化 | 需求基线已拍板「自用先行,验证价值后再外化」 | 业务方决定 | +| 7 | `sut_run.py` / `sitecustomize.py` | 旧路径遗留,当前不使用 | 可在下次清理时删(需确认旧 commit 不再复跑) | +| 8 | `CODE_OF_CONDUCT.md` / `CITATION.cff` / `GOVERNANCE.md` / `CODEOWNERS` | 单人维护;正式 CoC 会引入无法执行的治理承诺 | 开放外部维护者 / 外部 PR 常态化时先补 CoC(见 `DEC-025`) | + +## 5. 如何复现一轮 live 回归(零猜测) + +```bash +# 0) 语料:正文在仓外(不在任何 git 仓) +# ~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl +python3 tools/seed_eval_corpus.py \ + --corpus ~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl \ + --manifest eval/corpus/manifest.json --dry-run # 先校验 sha256 + +# 1) 起被测(隔离库 + 放宽会话预算;含能力探针) +export EVAL_SUT_FASTAPI_API_KEY=... +EVAL_SUT_DB=rag_eval_20261018 EVAL_SUT_SESSION_TOKEN_LIMIT=200000 \ + tools/sut-harness/run_sut.sh + +# 2) 灌语料 +python3 tools/seed_eval_corpus.py \ + --corpus ~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl \ + --manifest eval/corpus/manifest.json --base-url http://127.0.0.1:8000 + +# 3) 跑评测 +set -a; . eval/runs/.sut-harness.env; set +a +export SSL_CERT_FILE=/etc/ssl/cert.pem +.venv/bin/python -m eval_gate run --evals eval/fastapi_rag_golden.evals.json --report-dir eval/runs +``` + +> ⚠️ 灌语料前确认目标是**隔离库**;不要灌生产 `rag_db`(它已有 345 行,含其它项目数据)。 + +## 6. 版本与维护 + +- **建议 tag:`v0.4.0`(自用版)** —— 只代表"自用闭环",不代表可外化; +- **许可证**:**MIT**(见 `LICENSE` / `DEC-025`;若将来要改 Apache-2.0 / proprietary,须在发布前改); +- **`v1.0.0` 的前置**:U2 接进真实发版 CI + 至少一个外部使用者验证; +- 维护入口:`ROADMAP.md`(状态)· `CLAUDE.md`(接续)· `docs/decisions/`(选型)· `eval/cases/`(失败)· `docs/复盘/`(过程)。 + +## 变更记录 + +- 2026-10-18 建立(自用版结项)。 diff --git "a/docs/\351\203\250\347\275\262.md" "b/docs/\351\203\250\347\275\262.md" index 52be01d..dbb7344 100644 --- "a/docs/\351\203\250\347\275\262.md" +++ "b/docs/\351\203\250\347\275\262.md" @@ -37,7 +37,7 @@ python3 -m venv .venv | 键 | 必填 | 说明 | |---|---|---| | `EVAL_JUDGE_BASE_URL` / `_API_KEY` / `_MODEL` | 真 judge 必填 | judge 走**任意 OpenAI 兼容端点**(DEC-002)。**三者缺一 → 自动回落离线 FakeJudge** | -| `EVAL_JUDGE_MAX_TOKENS` / `_CONCURRENCY` | | 默认 512 / 4 | +| `EVAL_JUDGE_MAX_TOKENS` / `_CONCURRENCY` | | 默认 **4096** / 4 | | `EVAL_SUT_FASTAPI_BASE_URL` / `_API_KEY` | 接真实被测必填 | 默认 `http://127.0.0.1:8000`;Key 走 **`X-API-Key`** 头(契约 `评测-sut-adapter.md:39`) | | `EVAL_SUT_FASTAPI_SNAPSHOT` | | 指向快照文件则**改走快照回放**(总纲 D-5 的三种取法之一),用于被测不可用时 | | `EVAL_LIVE` | | 置 `1` 才跑 `tests/test_live_smoke.py`(默认 skip) | @@ -63,13 +63,42 @@ python3 -m venv .venv **接入 CI**:见 `.github/workflows/eval-gate.yml` —— 要点是 **eval-gate 独立成 job**,不与代码门合并成一个绿灯;密钥走 CI secrets,不硬编码。 +> ⚠️ **真实被测的发版 CI 尚未接入**(2026-10-18):业务方决定暂不动另一个仓; +> 模板与接入顺序见 **`integrations/fastapi-rag-agent/`**。现有 CI 只跑离线评测与 `--mode bad` 自证。 + ## 5. 接入一个真实被测(以 `01.FastAPI RAG Agent` 为例) -1. **起被测**:`cd <被测仓> && docker compose up -d`(确认 `curl http://127.0.0.1:8000/health` 通) -2. **拿被测 API Key**:被测的 `api_keys` 表里 `sk-` 开头的那把(管理端创建;网页登录口令**不是** API Key) -3. **seed 知识库(必做)**:契约 `评测-sut-adapter.md:42` —— 知识库不在 git,**首跑必须自带 golden 文档集 + seed 步骤**,否则检索结果不可复现,失败归因会失真(R2b 实测:未 seed 时失败全部指向知识库覆盖度,而非被测质量) -4. **本仓 `.env`** 填 `EVAL_SUT_FASTAPI_*` + `EVAL_JUDGE_*` -5. 跑:`python -m eval_gate run --evals eval/fastapi_rag_golden.evals.json` +> ⚠️ **2026-10-18 更新**:被测仓已从 `api/` 改为 **`app/`**,并有官方镜像 +> `fastapi-rag-agent:latest`;生产 `rag_db` 已混入其它项目语料(**345 行**) +> ⇒ **不要直接拿生产库跑评测**。下面用**隔离库 + 官方镜像 + 语料清单**。 + +1. **确认被测仓结构**:有 `app/` 与 `.env`(旧 `api/` 仍兼容)。 +2. **拿被测 API Key**:被测的 `api_keys` 表里 `sk-` 开头的那把(管理端创建;网页登录口令**不是** API Key)。 +3. **起被测(推荐 harness)**: + ```bash + export EVAL_SUT_FASTAPI_API_KEY=... + EVAL_SUT_DB=rag_eval_20261018 \ + EVAL_SUT_SESSION_TOKEN_LIMIT=200000 \ + tools/sut-harness/run_sut.sh + ``` + - 脚本起 `postgres`/`redis` → 官方镜像 + 只读挂载源码 → **能力探针**; + - 退出码:**0 就绪且能作答 · 1 起不来 · 2 起来了但答不了**; + - ⛔ **不要**直接用 `docker compose up -d`:本机内存有限,且会拉起不必要的服务。 + - 隔离库若不存在:先按 `eval/corpus/README.md` 建库/过滤,或从生产库克隆后过滤。 +4. **灌评测语料(必做,可复现)**: + ```bash + python3 tools/seed_eval_corpus.py \ + --corpus ~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl \ + --manifest eval/corpus/manifest.json \ + --base-url http://127.0.0.1:8000 + ``` + 语料正文**不在公开仓**;seed 前校验 `sha256`,不一致即拒绝。 +5. **本仓 `.env`** 填 `EVAL_SUT_FASTAPI_*` + `EVAL_JUDGE_*`;跑评测: + ```bash + set -a; . eval/runs/.sut-harness.env; set +a + export SSL_CERT_FILE=/etc/ssl/cert.pem + python3 -m eval_gate run --evals eval/fastapi_rag_golden.evals.json --report-dir eval/runs + ``` ## 6. ⚠️ 本机环境坑(全部真实踩过,照做即可避) diff --git a/eval/README.md b/eval/README.md index d159321..cce7724 100644 --- a/eval/README.md +++ b/eval/README.md @@ -11,6 +11,7 @@ eval/ 阈值.md 建议阈值占位(先定阈值,再看结果) evals.json 评估用例样例(仿 B agent-system-creator/evals/evals.json;可多文件拆分) cases/ 评估用例库(标注三类:意图 / 理想工具调用序列 / 标准答案)——逐步按模块建 + corpus/ 评测语料清单(**正文在仓外**;见 corpus/README.md) runs/ 回归运行记录(版本 + 结果 + 阈值对比;支撑统计回归与发布门禁) ``` @@ -26,6 +27,8 @@ eval/ ## 版本纪律 - `evals.json` / `cases/` 随代码同库提交、可 diff、可回滚;`runs/` 记录每次回归的 commit 与结果。 +- **评测语料**:正文**不进公开仓**(本仓 Public);清单 + sha256 在 `eval/corpus/manifest.json`, + 正文放仓外;灌库用 `tools/seed_eval_corpus.py`(seed 前校验哈希)。详见 `eval/corpus/README.md`。 - 工具:DeepEval / Promptfoo / agent-eval / Ragas(评估引擎按需选,参考 B `07-参考-技术选型对比` §五;组织自己定义质量模型)。 ## 评测集 schema 草案(阶段2-步骤4 启动 · 总纲 §3.3 落点) diff --git a/eval/corpus/README.md b/eval/corpus/README.md new file mode 100644 index 0000000..5768c06 --- /dev/null +++ b/eval/corpus/README.md @@ -0,0 +1,54 @@ +# eval/corpus · 评测语料清单(正文**不入本仓**) + +## 为什么正文不在这里 + +本仓是 **Public**。被测知识库的正文可能包含业务内容,不能进公开仓的历史 +(历史删不干净,同 `Product/CLAUDE.md` §一 对密钥/大件的要求)。 + +⇒ 正文放在**仓外、且不在任何 git 仓内**: + +``` +~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl +``` + +本目录只放 **`manifest.json`**:行数 · 来源计数 · **sha256** · 生成来源。 +`seed_eval_corpus.py` 在灌库前会**校验 sha256**,不一致就**拒绝** —— 不是警告后继续。 + +## 当前清单 + +| 项 | 值 | +|---|---| +| 行数 | **125** | +| sha256 | `manifest.json` | +| 生成来源 | `rag_eval_20261018`(生产 `rag_db` 的克隆,过滤 junk source + 按 content 去重) | +| 用途 | `DEC-019` 完整 live 回归(`docs/reports/DEC-019-live回归-2026-10-18.md`) | + +## 导出(重新生成语料) + +```bash +python3 tools/export_eval_corpus.py \ + --db rag_eval_20261018 \ + --out ~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl \ + --manifest /tmp/manifest.json +# 把 /tmp/manifest.json 的 sha256 / rows / sources 同步进 eval/corpus/manifest.json +``` + +## 灌入被测(seed) + +```bash +export EVAL_SUT_FASTAPI_API_KEY=... +python3 tools/seed_eval_corpus.py \ + --corpus ~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl \ + --manifest eval/corpus/manifest.json \ + --base-url http://127.0.0.1:8000 + +# 只校验不发请求 +python3 tools/seed_eval_corpus.py ... --dry-run +``` + +## 纪律 + +1. **不要把语料正文贴进 issue / PR / 聊天记录** —— 本仓是 Public; +2. 清单与文件不一致 ⇒ **拒绝导入**,先查是哪一边变了; +3. 换语料 = 换实验条件 ⇒ 报告里必须写明新的 sha256,旧结论不能直接对比; +4. 灌库前确认目标库是**隔离库**(如 `rag_eval_20261018`),不要灌生产 `rag_db`。 diff --git a/eval/corpus/manifest.json b/eval/corpus/manifest.json new file mode 100644 index 0000000..dd009f3 --- /dev/null +++ b/eval/corpus/manifest.json @@ -0,0 +1,67 @@ +{ + "_doc": "评测语料清单。语料正文不入本仓(本仓 Public);正文放在仓外。seed 前校验 sha256,不一致即拒绝。", + "corpus": "fastapi_rag_eval_corpus-20261018.jsonl", + "corpus_path": "Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl", + "corpus_path_note": "相对于 ~/Desktop;该目录不在任何 git 仓内。", + "sha256": "d9a53c642dcd9adfc2eaaad41b96a80e20c9760c2a72c888399cd78c1f97cc09", + "rows": 125, + "bytes": 96815, + "generated_from": "rag_eval_20261018", + "generator": "tools/export_eval_corpus.py", + "sources": { + "A-01-QY300数控加工中心规格书.md": 2, + "A-02-QY500系列技术参数.md": 3, + "A-03-刀柄与刀具接口规格.md": 2, + "A-04-电气与控制柜规格.md": 2, + "A-05-主轴与轴承备件规格.md": 3, + "A-06-气动与液压系统规格.md": 3, + "A-07-精度检验标准与允差.md": 2, + "B-01-售后服务与保修制度.md": 4, + "B-02-安装调试与验收流程.md": 4, + "B-03-备件供应与调拨制度.md": 3, + "B-04-服务工程师上门作业规范.md": 2, + "B-05-客户投诉与升级处理流程.md": 2, + "B-06-设备保养计划与周期制度.md": 2, + "B-07-交付资料与培训清单制度.md": 2, + "C-01-常见问题.md": 7, + "C-02-采购与合同常见问题.md": 3, + "C-03-安装调试常见问题.md": 3, + "C-04-备件与耗材常见问题.md": 4, + "C-05-培训与技术支持常见问题.md": 3, + "C-06-报警与故障代码常见问题.md": 6, + "C-07-搬迁与二次安装常见问题.md": 3, + "D-01-2025年度服务质量报告.md": 4, + "D-02-2025年度备件消耗分析.md": 2, + "D-03-2025年度客户满意度调查.md": 2, + "D-04-2025年度各机型故障率对比.md": 2, + "D-05-2025年度服务成本构成.md": 2, + "D-06-2025年度响应时效专项分析.md": 2, + "D-07-2025年度客户设备使用工况统计.md": 2, + "E-01-公司简介与招聘.md": 2, + "E-02-园区参观与展厅介绍.md": 2, + "business": 2, + "eval-gap-fill-2026-09-11": 5, + "eval-gap-fill-2026-09-12": 3, + "eval_dataset.json#10": 1, + "eval_dataset.json#11": 1, + "eval_dataset.json#12": 1, + "eval_dataset.json#13": 1, + "eval_dataset.json#14": 1, + "eval_dataset.json#15": 1, + "eval_dataset.json#16": 1, + "eval_dataset.json#17": 1, + "eval_dataset.json#18": 1, + "eval_dataset.json#19": 1, + "eval_dataset.json#20": 1, + "eval_dataset.json#21": 1, + "eval_dataset.json#22": 1, + "eval_dataset.json#23": 1, + "eval_dataset.json#24": 1, + "eval_dataset.json#25": 1, + "final_smoke": 1, + "financial_report": 1, + "tech": 8, + "test_docs": 1, + "手动入库(本页)": 3 + } +} diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..1c64209 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,44 @@ +# examples/ · 可直接跑的例子 + +> 这里放**能复制的用法**;评测数据集在 `eval/`,不在这里重复。 + +## 1. 离线自证(零 key、零外网) + +```bash +./examples/offline-demo.sh +``` + +它做两件事并检查退出码: + +- `--mode good --offline` → **exit 0** +- `--mode bad --offline` → **exit 1**(证明"劣化会被拦") + +这是最快确认"装好了、门是活的"的方式。 + +## 2. 真实链路(真实被测 + 真实 judge) + +前置: + +1. 起被测 + 能力探针:`tools/sut-harness/run_sut.sh`(退出码 0/1/2); +2. 灌评测语料:`tools/seed_eval_corpus.py`(见 `eval/corpus/README.md`); +3. 配好 `.env` 的 `EVAL_JUDGE_*` 与 `EVAL_SUT_FASTAPI_*`。 + +```bash +set -a; . eval/runs/.sut-harness.env; set +a +export SSL_CERT_FILE=/etc/ssl/cert.pem +.venv/bin/python -m eval_gate run \ + --evals eval/fastapi_rag_golden.evals.json \ + --report-dir eval/runs +``` + +完整步骤与坑见 **`docs/部署.md §5`**。 + +## 3. 接入自己的被测 + +不是复制一个脚本就能完成;需要写适配器(3 处代码)+ 加数据。 +先读 **`docs/接入新被测.md`**,按那里的门槛和步骤做。 + +## 4. 在 CI 里用 + +本仓 CI 示例:`.github/workflows/eval-gate.yml`。 +**真实被测的发版 CI 尚未接入** —— 模板见 `integrations/fastapi-rag-agent/`。 diff --git a/examples/offline-demo.sh b/examples/offline-demo.sh new file mode 100755 index 0000000..eb7d0d9 --- /dev/null +++ b/examples/offline-demo.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# 离线自证:good → exit 0,bad → exit 1。 +# 不联网、不需要任何 key。用法:./examples/offline-demo.sh +set -u + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +PY="$ROOT/.venv/bin/python" +[ -x "$PY" ] || { + echo "先安装 dev 环境:python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'" >&2 + exit 1 +} + +OUT="$(mktemp -d)" +trap 'rm -rf "$OUT"' EXIT +EVALS="$ROOT/eval/mini_rag_qa.evals.json" + +echo "== good(期望 exit 0)==" +"$PY" -m eval_gate run --evals "$EVALS" --mode good --offline --report-dir "$OUT" +GOOD=$? + +echo "== bad(期望 exit 1)==" +"$PY" -m eval_gate run --evals "$EVALS" --mode bad --offline --report-dir "$OUT" +BAD=$? + +echo +echo "good=$GOOD(期望 0)· bad=$BAD(期望 1)" +if [ "$GOOD" -eq 0 ] && [ "$BAD" -eq 1 ]; then + echo "✅ 自证通过:门能拿到 0,也能拦住劣化" + exit 0 +fi +echo "❌ 退出码不符合预期 —— 先查环境/安装,不要当成被测问题" >&2 +exit 1 diff --git a/integrations/fastapi-rag-agent/README.md b/integrations/fastapi-rag-agent/README.md new file mode 100644 index 0000000..71b0259 --- /dev/null +++ b/integrations/fastapi-rag-agent/README.md @@ -0,0 +1,37 @@ +# integrations/fastapi-rag-agent · 发版 CI 接入模板(**未接入**) + +> **状态:⬜ 未接入。** +> 业务方 2026-10-18 决定:**暂不动 `fastapi-rag-agent` 仓** ⇒ 本目录只放"将来要接时可直接抄"的模板, +> 不改另一个仓、不改它的代码/容器/数据库。 + +## 将来接入需要动什么(范围先说清) + +| 动作 | 动哪个仓 | 具体 | +|---|---|---| +| ① 新增 workflow | **`fastapi-rag-agent`(private)** | 把 `eval-gate.yml.example` 复制成 `.github/workflows/eval-gate.yml` | +| ② 配置 secrets | **`fastapi-rag-agent` 仓设置** | `EVAL_JUDGE_API_KEY`、`EVAL_SUT_FASTAPI_API_KEY`(**只能由仓主设置**) | +| ③ 语料供给 | 私有侧 | 语料正文**不在本公开仓**;需放到私有仓 / 加密 artifact,CI 里还原 | +| ④ 起被测 | CI runner | `postgres + redis + api`(现有 SUT CI 故意不起 postgres) | +| ⑤ 触发 | —— | 建议 **发版 tag / 手动**,⛔ 不建议每个 PR(每次 live ≈4 万 token) | + +**不需要动**:被测业务代码、`Dockerfile`、compose、生产数据库。 + +## 建议的接入顺序 + +1. 先在本仓把语料 seed 链路跑通(`eval/corpus/README.md`); +2. 在 `fastapi-rag-agent` 里加 **一个** workflow,先只跑 `workflow_dispatch`(手动); +3. 稳定后改成 `push: tags: ['v*']`(发版时跑); +4. 再评估是否 nightly —— **不要**默认每个 PR。 + +## 为什么现在不接 + +- 被测仓自己的 `ROADMAP.md` 也把它标为未接入(`B14 已移出本仓`); +- 需要改另一个仓 + 配 secrets + 决定预算与触发,属于**跨仓决策**; +- 本轮目标是本仓自用版结项(见 `docs/结项报告-自用版-2026-10-18.md`)。 + +## 验收标准(接入完成时) + +- 发版 tag / 手动触发后,CI 里能跑完一轮 live 评测并给出 `exit 0/1`; +- 故意劣化 prompt 的提交在 CI 被拦(`--mode bad` 或真实劣化样本); +- 报告与 trace 作为 artifact 上传; +- 语料 sha256 在日志里可见(可追溯这次跑的是哪份语料)。 diff --git a/integrations/fastapi-rag-agent/eval-gate.yml.example b/integrations/fastapi-rag-agent/eval-gate.yml.example new file mode 100644 index 0000000..8de5934 --- /dev/null +++ b/integrations/fastapi-rag-agent/eval-gate.yml.example @@ -0,0 +1,74 @@ +# ⚠️ 示例文件(未被使用)—— 复制到 fastapi-rag-agent/.github/workflows/eval-gate.yml 才生效。 +# 本仓不改另一个仓;接入前先读同目录 README.md 的「范围」与「顺序」。 +name: eval-gate + +on: + workflow_dispatch: + # 建议:发版时跑,不要每个 PR 都跑(每次 live ≈4 万 token) + # push: + # tags: ['v*'] + +permissions: + contents: read + +jobs: + eval: + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - name: 检出被测 + uses: actions/checkout@v4 + with: + path: sut + + - name: 检出评测门(public) + uses: actions/checkout@v4 + with: + repository: heweidong-ecco/agent-eval-gate + path: eval-gate + + - name: 起被测(postgres + redis + api) + working-directory: sut + run: docker compose up -d postgres redis api + + - name: 等 /health + run: | + for i in $(seq 1 60); do + if curl -sf http://127.0.0.1:8000/health >/dev/null; then exit 0; fi + sleep 5 + done + docker compose -f sut/docker-compose.yml logs --tail 50 api + exit 1 + + - name: 灌评测语料 + env: + EVAL_SUT_FASTAPI_API_KEY: ${{ secrets.EVAL_SUT_FASTAPI_API_KEY }} + run: | + # TODO(语料): 正文不在公开仓。需在私有侧提供(私有仓 / 加密 artifact), + # 还原到 $RUNNER_TEMP/corpus.jsonl 后再执行下面这行。 + # 清单里的 sha256 会在 seed 前校验,不一致会拒绝。 + python eval-gate/tools/seed_eval_corpus.py \ + --corpus "$RUNNER_TEMP/corpus.jsonl" \ + --manifest eval-gate/eval/corpus/manifest.json \ + --base-url http://127.0.0.1:8000 + + - name: 跑评测 + env: + EVAL_JUDGE_API_KEY: ${{ secrets.EVAL_JUDGE_API_KEY }} + EVAL_SUT_FASTAPI_API_KEY: ${{ secrets.EVAL_SUT_FASTAPI_API_KEY }} + EVAL_SUT_FASTAPI_BASE_URL: http://127.0.0.1:8000 + EVAL_SUT_VERSION: ${{ github.sha }} + EVAL_SUT_PROBE: ok + run: | + pip install -e eval-gate + eval-gate run \ + --evals eval-gate/eval/fastapi_rag_golden.evals.json \ + --report-dir report + + - name: 上传报告与 trace + if: always() + uses: actions/upload-artifact@v4 + with: + name: eval-report + path: report/ diff --git a/pyproject.toml b/pyproject.toml index e016e4b..f25661f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,10 +4,26 @@ build-backend = "setuptools.build_meta" [project] name = "agent-eval-gate" -version = "0.3.0" +version = "0.4.0" description = "Agent 生产就绪评测门:评测集 + 确定性规则 + LLM-as-Judge + 阈值门(自用先行)" +readme = "README.md" +license = { text = "MIT" } +authors = [{ name = "heweidong-ecco" }] +keywords = ["llm", "evaluation", "eval", "judge", "ci", "agent"] +classifiers = [ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + "Intended Audience :: Developers", + "Topic :: Software Development :: Quality Assurance", +] requires-python = ">=3.10" +[project.urls] +Homepage = "https://github.com/heweidong-ecco/agent-eval-gate" +Issues = "https://github.com/heweidong-ecco/agent-eval-gate/issues" +Changelog = "https://github.com/heweidong-ecco/agent-eval-gate/blob/main/CHANGELOG.md" + [project.optional-dependencies] # pyyaml 仅用于 **dev**:`tests/test_hooks.py` 需要解析 CI 工作流,以守住 # 「`run:` 里的续行符被 YAML 折行拼坏命令」这类静默故障(2026-09-12 实测踩到)。 diff --git a/tests/test_eval_corpus.py b/tests/test_eval_corpus.py new file mode 100644 index 0000000..8fd5d05 --- /dev/null +++ b/tests/test_eval_corpus.py @@ -0,0 +1,165 @@ +"""评测语料的可复现守卫(`tools/export_eval_corpus.py` / `tools/seed_eval_corpus.py`)。 + +**为什么要有这一组**: +- live 回归的结论只有在**同一份语料**上才可重算;而语料正文**不进公开仓** + (本仓是 Public;正文放 `Product-external/eval-corpus/`,仓内只放清单 + 哈希); +- 因此必须守住两件事: + ① 仓内**不出现**语料正文(只有 manifest/README); + ② 导出/导入工具**按哈希校验**,清单与文件不一致时**拒绝**导入(不是警告后继续)。 +""" +import hashlib +import json +import re +import subprocess +import sys +import threading +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +EXPORT = ROOT / "tools" / "export_eval_corpus.py" +SEED = ROOT / "tools" / "seed_eval_corpus.py" +MANIFEST = ROOT / "eval" / "corpus" / "manifest.json" + + +def _sha(p: Path) -> str: + return hashlib.sha256(p.read_bytes()).hexdigest() + + +def test_manifest_shape_and_no_content(): + d = json.loads(MANIFEST.read_text(encoding="utf-8")) + assert d["rows"] > 0 + assert re.fullmatch(r"[0-9a-f]{64}", d["sha256"]), d["sha256"] + assert sum(d["sources"].values()) == d["rows"] + assert d["corpus"].endswith(".jsonl") + # 清单里不得出现语料正文:只允许固定字段,且除 sources(计数)外不得有嵌套结构 + allowed = {"_doc", "corpus", "corpus_path", "corpus_path_note", "sha256", + "rows", "bytes", "generated_from", "generator", "sources"} + assert set(d) <= allowed, f"清单出现未预期字段: {set(d) - allowed}" + assert all(isinstance(v, int) for v in d["sources"].values()) + assert not any(isinstance(v, (list, dict)) for k, v in d.items() if k != "sources") + + +def test_repo_does_not_track_corpus_content(): + # 含未跟踪文件:提交前也要能跑(CI 里已跟踪)。 + out = subprocess.run( + ["git", "ls-files", "--cached", "--others", "--exclude-standard", "eval/corpus"], + cwd=str(ROOT), capture_output=True, text=True, + ) + files = [f for f in out.stdout.splitlines() if f] + assert files, "eval/corpus 下应有清单/说明" + assert all(f.endswith(("manifest.json", "README.md")) for f in files), files + + +def _stub_docker(tmp_path: Path, rows: list[dict]) -> Path: + bindir = tmp_path / "bin" + bindir.mkdir() + payload = "\n".join(json.dumps(r, ensure_ascii=False) for r in rows) + stub = bindir / "docker" + stub.write_text( + "#!/bin/bash\n" + f"cat <<'EOF'\n{payload}\nEOF\n", + encoding="utf-8", + ) + stub.chmod(0o755) + return bindir + + +def test_export_writes_jsonl_and_manifest(tmp_path): + rows = [{"content": "doc one", "source": "a"}, {"content": "doc two", "source": "b"}] + bindir = _stub_docker(tmp_path, rows) + out = tmp_path / "corpus.jsonl" + man = tmp_path / "manifest.json" + env = {"PATH": f"{bindir}:/usr/bin:/bin", "HOME": str(Path.home())} + r = subprocess.run( + [sys.executable, str(EXPORT), "--db", "x", "--out", str(out), "--manifest", str(man)], + capture_output=True, text=True, env=env, timeout=60, + ) + assert r.returncode == 0, r.stdout + r.stderr + assert [json.loads(x) for x in out.read_text(encoding="utf-8").splitlines()] == rows + m = json.loads(man.read_text(encoding="utf-8")) + assert m["rows"] == 2 + assert m["sha256"] == _sha(out) + assert m["sources"] == {"a": 1, "b": 1} + + +def _make_corpus(tmp_path: Path, rows: list[dict]) -> tuple[Path, Path]: + corpus = tmp_path / "corpus.jsonl" + corpus.write_text("".join(json.dumps(r, ensure_ascii=False) + "\n" for r in rows), encoding="utf-8") + manifest = tmp_path / "manifest.json" + manifest.write_text(json.dumps({ + "corpus": corpus.name, + "sha256": _sha(corpus), + "rows": len(rows), + "sources": {}, + }), encoding="utf-8") + return corpus, manifest + + +def test_seed_refuses_hash_mismatch(tmp_path): + corpus, manifest = _make_corpus(tmp_path, [{"content": "x", "source": "s"}]) + d = json.loads(manifest.read_text(encoding="utf-8")) + d["sha256"] = "0" * 64 + manifest.write_text(json.dumps(d), encoding="utf-8") + r = subprocess.run( + [sys.executable, str(SEED), "--corpus", str(corpus), "--manifest", str(manifest), "--dry-run"], + capture_output=True, text=True, timeout=60, + ) + assert r.returncode == 1 + assert "sha256" in (r.stdout + r.stderr).lower() + + +def test_seed_dry_run_reports_count(tmp_path): + corpus, manifest = _make_corpus(tmp_path, [{"content": "x", "source": "s"}, + {"content": "y", "source": "s"}]) + r = subprocess.run( + [sys.executable, str(SEED), "--corpus", str(corpus), "--manifest", str(manifest), "--dry-run"], + capture_output=True, text=True, timeout=60, + ) + assert r.returncode == 0, r.stdout + r.stderr + assert "2" in r.stdout + + +class _Handler(BaseHTTPRequestHandler): + calls: list[dict] = [] + + def do_POST(self): + n = int(self.headers.get("Content-Length", "0")) + body = json.loads(self.rfile.read(n) or b"{}") + type(self).calls.append({ + "path": self.path, + "api_key": self.headers.get("X-API-Key"), + "documents": body.get("documents", []), + }) + out = json.dumps({"status": "inserted", "count": len(body.get("documents", []))}).encode() + self.send_response(200) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(out))) + self.end_headers() + self.wfile.write(out) + + def log_message(self, *args): + pass + + +def test_seed_posts_batches_with_auth_header(tmp_path): + rows = [{"content": f"d{i}", "source": "s"} for i in range(3)] + corpus, manifest = _make_corpus(tmp_path, rows) + _Handler.calls = [] + server = ThreadingHTTPServer(("127.0.0.1", 0), _Handler) + t = threading.Thread(target=server.serve_forever, daemon=True) + t.start() + try: + port = server.server_address[1] + r = subprocess.run( + [sys.executable, str(SEED), "--corpus", str(corpus), "--manifest", str(manifest), + "--base-url", f"http://127.0.0.1:{port}", "--api-key", "k", "--batch-size", "2"], + capture_output=True, text=True, timeout=60, + ) + finally: + server.shutdown() + assert r.returncode == 0, r.stdout + r.stderr + assert len(_Handler.calls) == 2, _Handler.calls + assert [len(c["documents"]) for c in _Handler.calls] == [2, 1] + assert all(c["path"] == "/api/v1/rag/insert_batch" for c in _Handler.calls) + assert all(c["api_key"] == "k" for c in _Handler.calls) diff --git a/tests/test_sut_harness.py b/tests/test_sut_harness.py index 317c1b7..3b703a9 100644 --- a/tests/test_sut_harness.py +++ b/tests/test_sut_harness.py @@ -88,7 +88,7 @@ def _fake_repo(tmp_path: Path, *, layout: str = "app") -> Path: return repo -def _run_with_stubs(tmp_path: Path, repo: Path, **over): +def _run_with_stubs(tmp_path: Path, repo: Path, probe_body: str = '{"answer":"ok"}', **over): """用 stub `docker`/`curl` 跑完整脚本,返回 (CompletedProcess, docker 调用记录, 自证文件内容)。""" bindir = tmp_path / "bin" bindir.mkdir() @@ -100,10 +100,10 @@ def _run_with_stubs(tmp_path: Path, repo: Path, **over): *) exit 0 ;; esac """) - _write_stub(bindir, "curl", """ + _write_stub(bindir, "curl", f""" if printf '%s' "$*" | grep -q -- '-w'; then printf '200'; exit 0; fi -if printf '%s' "$*" | grep -q '/health'; then printf '{"status":"healthy"}'; exit 0; fi -printf '{"answer":"ok"}' +if printf '%s' "$*" | grep -q '/health'; then printf '{{"status":"healthy"}}'; exit 0; fi +printf '%s' '{probe_body}' """) identity = tmp_path / "identity.env" env = { @@ -162,6 +162,14 @@ def test_db_and_session_limit_are_passed_through(tmp_path): assert "-e SESSION_TOKEN_LIMIT=200000" in run +def test_probe_failure_exits_2(tmp_path): + """`/health` 200 但答不了 ⇒ 必须是 **2**(与 README / 故障手册的退出码一致)。""" + repo = _fake_repo(tmp_path, layout="app") + r, _, _ = _run_with_stubs(tmp_path, repo, probe_body='{"detail":"no answer"}') + assert r.returncode == 2, r.stdout + r.stderr + assert "能力探针失败" in r.stderr + + def test_capability_probe_and_identity_are_kept(tmp_path): """能力探针不能省;被测自证(commit/probe)必须落盘 —— DEC-016。""" repo = _fake_repo(tmp_path, layout="app") diff --git a/tools/export_eval_corpus.py b/tools/export_eval_corpus.py new file mode 100644 index 0000000..333172f --- /dev/null +++ b/tools/export_eval_corpus.py @@ -0,0 +1,107 @@ +#!/usr/bin/env python3 +"""把评测语料从被测 Postgres 导出成 JSONL + 清单(正文不入本仓)。 + +背景 +---- +本仓是 **Public**;被测知识库的正文**不能**进本仓的历史。 +但 live 回归要可复现,就必须有一份**可校验**的语料。 +⇒ 正文写到仓外(`~/Desktop/Product-external/eval-corpus/`,不在任何 git 仓内), + 本仓只放 `eval/corpus/manifest.json`(行数 / 来源计数 / sha256)。 + +用法 +---- + python3 tools/export_eval_corpus.py \ + --db rag_eval_20261018 \ + --out ~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl \ + --manifest /tmp/manifest.json + + # 导出后把 manifest 的 sha256 / rows / sources 抄进 eval/corpus/manifest.json + # (或直接用它覆盖,再把 corpus_path 改成相对路径) + +依赖:本机 `docker` + 运行中的 `postgres-rag` 容器(不引 psycopg)。 +""" +from __future__ import annotations + +import argparse +import collections +import hashlib +import json +import subprocess +import sys +from pathlib import Path + +QUERY = ( + "SELECT json_build_object('content', content, 'source', source)::text " + "FROM documents ORDER BY id;" +) + + +def main() -> int: + ap = argparse.ArgumentParser(description="导出评测语料(JSONL)+ 清单") + ap.add_argument("--db", required=True, help="数据库名(评测用隔离库)") + ap.add_argument("--out", required=True, help="JSONL 输出路径(建议放 Product-external)") + ap.add_argument("--manifest", help="可选的清单输出路径") + ap.add_argument("--container", default="postgres-rag") + ap.add_argument("--user", default="postgres") + args = ap.parse_args() + + r = subprocess.run( + ["docker", "exec", "-i", args.container, "psql", "-U", args.user, + "-d", args.db, "-At", "-c", QUERY], + capture_output=True, text=True, + ) + if r.returncode != 0: + print(f"[export] psql 失败: {r.stderr.strip()}", file=sys.stderr) + return 1 + + rows: list[dict] = [] + for line in r.stdout.splitlines(): + line = line.strip() + if not line: + continue + try: + d = json.loads(line) + except json.JSONDecodeError: + print(f"[export] 非法 JSON 行: {line[:80]}", file=sys.stderr) + return 1 + if not isinstance(d.get("content"), str) or not isinstance(d.get("source"), str): + print(f"[export] 行缺 content/source: {line[:80]}", file=sys.stderr) + return 1 + rows.append({"content": d["content"], "source": d["source"]}) + + if not rows: + print("[export] 没有导出行(库空或表名不对)", file=sys.stderr) + return 1 + + out = Path(args.out).expanduser() + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text( + "".join(json.dumps(x, ensure_ascii=False) + "\n" for x in rows), + encoding="utf-8", + ) + sha = hashlib.sha256(out.read_bytes()).hexdigest() + counts = dict(sorted(collections.Counter(x["source"] for x in rows).items())) + print(f"[export] {out} rows={len(rows)} bytes={out.stat().st_size} sha256={sha}") + + if args.manifest: + manifest = { + "_doc": "评测语料清单。语料正文不入本仓(本仓 Public);正文放在仓外。seed 前校验 sha256,不一致即拒绝。", + "corpus": out.name, + "corpus_path": f"Product-external/eval-corpus/{out.name}", + "corpus_path_note": "相对于 ~/Desktop;该目录不在任何 git 仓内。", + "sha256": sha, + "rows": len(rows), + "bytes": out.stat().st_size, + "generated_from": args.db, + "generator": "tools/export_eval_corpus.py", + "sources": counts, + } + mp = Path(args.manifest).expanduser() + mp.parent.mkdir(parents=True, exist_ok=True) + mp.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + print(f"[export] manifest -> {mp}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/seed_eval_corpus.py b/tools/seed_eval_corpus.py new file mode 100644 index 0000000..a19f766 --- /dev/null +++ b/tools/seed_eval_corpus.py @@ -0,0 +1,121 @@ +#!/usr/bin/env python3 +"""把评测语料灌进被测(经其 `/api/v1/rag/insert_batch`),seed 前校验清单哈希。 + +为什么走被测 API 而不是直接写库: +- 不依赖被测的表结构 / 内部连接;只依赖它**自己对外承诺**的导入接口; +- 让被测自己完成 embedding,不会把「我们机器上的向量」带过去。 + +纪律 +---- +- **哈希不一致 ⇒ 拒绝**(exit 1),不是警告后继续 —— 否则"复现"是假的; +- `--dry-run` 只校验清单/行数,不发任何网络请求(可零成本预检)。 + +用法 +---- + export EVAL_SUT_FASTAPI_API_KEY=... + python3 tools/seed_eval_corpus.py \ + --corpus ~/Desktop/Product-external/eval-corpus/fastapi_rag_eval_corpus-20261018.jsonl \ + --manifest eval/corpus/manifest.json \ + --base-url http://127.0.0.1:8000 + + # 只校验,不灌: + python3 tools/seed_eval_corpus.py --corpus ... --manifest ... --dry-run +""" +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import sys +import urllib.error +import urllib.request +from pathlib import Path + + +def _load_rows(path: Path) -> list[dict]: + rows: list[dict] = [] + for i, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1): + if not line.strip(): + continue + try: + d = json.loads(line) + except json.JSONDecodeError: + raise SystemExit(f"[seed] 第 {i} 行不是合法 JSON") + if not isinstance(d.get("content"), str) or not isinstance(d.get("source"), str): + raise SystemExit(f"[seed] 第 {i} 行缺 content/source") + rows.append({"content": d["content"], "source": d["source"]}) + return rows + + +def main() -> int: + ap = argparse.ArgumentParser(description="按清单校验并灌入评测语料") + ap.add_argument("--corpus", required=True, help="JSONL 语料路径(仓外)") + ap.add_argument("--manifest", required=True, help="eval/corpus/manifest.json") + ap.add_argument("--base-url", default="http://127.0.0.1:8000") + ap.add_argument("--api-key", default=os.getenv("EVAL_SUT_FASTAPI_API_KEY", "")) + ap.add_argument("--batch-size", type=int, default=25) + ap.add_argument("--timeout", type=float, default=300.0) + ap.add_argument("--dry-run", action="store_true") + args = ap.parse_args() + + corpus = Path(args.corpus).expanduser() + if not corpus.is_file(): + print(f"[seed] 语料不存在: {corpus}", file=sys.stderr) + return 1 + manifest = json.loads(Path(args.manifest).expanduser().read_text(encoding="utf-8")) + + actual = hashlib.sha256(corpus.read_bytes()).hexdigest() + expected = manifest.get("sha256") + if actual != expected: + print(f"[seed] sha256 不匹配 —— 拒绝导入\n 期望: {expected}\n 实际: {actual}", + file=sys.stderr) + return 1 + + rows = _load_rows(corpus) + want = manifest.get("rows") + if want is not None and want != len(rows): + print(f"[seed] 行数不匹配 —— 拒绝导入(清单 {want} / 实际 {len(rows)})", file=sys.stderr) + return 1 + + if args.batch_size <= 0: + print("[seed] --batch-size 必须 > 0", file=sys.stderr) + return 1 + + if args.dry_run: + print(f"[seed] dry-run OK: {len(rows)} 条 · sha256 校验通过 · 来源 {len(manifest.get('sources', {}))} 类") + return 0 + + if not args.api_key: + print("[seed] 缺 API key:--api-key 或 EVAL_SUT_FASTAPI_API_KEY", file=sys.stderr) + return 1 + + url = args.base_url.rstrip("/") + "/api/v1/rag/insert_batch" + done = 0 + for start in range(0, len(rows), args.batch_size): + batch = rows[start:start + args.batch_size] + body = json.dumps({"documents": batch}, ensure_ascii=False).encode("utf-8") + req = urllib.request.Request( + url, data=body, method="POST", + headers={"Content-Type": "application/json", "X-API-Key": args.api_key}, + ) + try: + with urllib.request.urlopen(req, timeout=args.timeout) as resp: + resp.read() + except urllib.error.HTTPError as e: + detail = e.read().decode("utf-8", "replace")[:300] + print(f"[seed] HTTP {e.code} @ {start + 1}-{start + len(batch)}: {detail}", + file=sys.stderr) + return 1 + except urllib.error.URLError as e: + print(f"[seed] 连接失败 @ {start + 1}: {e.reason}", file=sys.stderr) + return 1 + done += len(batch) + print(f"[seed] {done}/{len(rows)}") + + print(f"[seed] 完成:{done} 条已灌入 {args.base_url}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/sut-harness/run_sut.sh b/tools/sut-harness/run_sut.sh index 6481435..03eedff 100755 --- a/tools/sut-harness/run_sut.sh +++ b/tools/sut-harness/run_sut.sh @@ -102,8 +102,11 @@ else RESP="$(curl -s --max-time 120 -X POST "http://127.0.0.1:$PORT/api/v1/rag/search?mode=accurate_norerank" \ -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \ -d '{"question":"Python 是一门什么样的编程语言?","top_k":3,"generate_answer":true,"citations":true}' || true)" - echo "$RESP" | grep -q '"answer"' \ - || { echo "$RESP" | head -c 300 >&2; die "能力探针失败:被测无法作答(不要据此判质量,先归因环境)"; } + if ! echo "$RESP" | grep -q '"answer"'; then + echo "$RESP" | head -c 300 >&2 + printf '[sut-harness] ✗ 能力探针失败:被测无法作答(不要据此判质量,先归因环境)\n' >&2 + exit 2 # 契约:2 = 起来了但答不了(与 README / 故障手册一致) + fi log "✅ 能力探针通过(被测能作答)" fi diff --git "a/\346\200\273\347\272\262.md" "b/\346\200\273\347\272\262.md" index 6bff24c..8d621b1 100644 --- "a/\346\200\273\347\272\262.md" +++ "b/\346\200\273\347\272\262.md" @@ -1,11 +1,11 @@ # 总纲 · agent-eval-gate(架构/模块/指标/红线) -- 版本:0.3(P2-1 七层蓝图 + P2-2 模块/状态机/评测规划已落地) · 日期:2026-09-09 +- 版本:**0.4(自用版结项 · 2026-10-18)** —— 见 `docs/结项报告-自用版-2026-10-18.md` - 上游:`需求基线.md`;spec 冲突先回总纲对齐。依据:B 阶段2(七层架构)+ agent-system-creator/SKILL.md(14 模块清单/L1·L2·L3/横切原则)。 - ⚠ 适配声明:agent-eval-gate 是**评测门产品(CLI/服务),不是对话式 chat Agent**。总纲原 §1 为 Kit 通用 chat-Agent 七层脚手架,**不直接套用**;下按 B 七层框架做"层职责适配",每层标"适配后职责 / 对 B 通用层的说明"。 ## 1. 七层架构(阶段2-步骤3 · P2-1 落地) -> 事实源:`需求基线.md` §4/§6/§7/§8(评测形态、U1/U2、选型初案、Walk-through 风险)。C4 图/组件详图在 `docs/arch`(阶段2-步骤5 模块细化时出)。 +> 事实源:`需求基线.md` §4/§6/§7/§8(评测形态、U1/U2、选型初案、Walk-through 风险)。C4 图/组件详图见 **`docs/arch/README.md`**(2026-10-18 补齐;此前只写了路径、目录并不存在)。 ``` ┌─────────────────────────── agent-eval-gate 七层(评测门)────────────────────────────┐ @@ -46,19 +46,41 @@ ### 1.1 组件职责(一图流) ```mermaid flowchart LR - U[开发者/CI] --> CLI[eval-gate CLI] - CLI --> CFG[装载 evals.json + 阈值 + 被测适配器] - CFG --> SCH[调度器:按用例分批] - SCH --> DET[确定性规则引擎] - SCH --> J[LLM-as-Judge 判分器] - SUT[被测 Agent
(迷你 RAG-QA / 真实项目)] -->|输出/会话| SCH - DET --> AGG[聚合 + 阈值判定] + U["开发者 / CI"] --> CLI["eval-gate CLI"] + CLI --> CFG["装载 evals.json + 阈值 + 适配器"] + CFG --> SCH["调度器:按用例分批"] + SCH --> DET["确定性规则引擎"] + SCH --> J["LLM-as-Judge 判分器"] + H["SUT harness
官方镜像 + 能力探针"] --> SUT["被测 Agent"] + SUT -->|"输出"| SCH + C["评测语料
仓内 manifest + 仓外正文"] -->|"seed(校验 sha256)"| SUT + DET --> AGG["聚合 + 阈值判定"] J --> AGG - AGG --> RPT[L2 报告 + exit code] - BASE[(版本化基线
人工参照)] -.校准 judge/阈值.-> J - AUD[审计留痕:评测集版本 · judge 模型 · 报告] -.-> RPT + AGG --> RPT["L2 报告 + exit code"] + RPT --> ARCH["证据归档 spans.jsonl"] + BASE["版本化基线
人工参照"] -.->|"校准"| J + AUD["审计留痕
评测集版本 · judge 模型"] -.-> RPT + GH["真实发版 CI
⬜ 未接入(模板)"] -.-> CLI ``` +### 1.3 当前形态(2026-10-18 结项) + +> 上图实线 = **已落地并验证过**;虚线 = **未接线 / 未接入**(不是已实现)。 + +| 件 | 现状 | +|---|---| +| 评测内核(确定性 + judge) | ✅ 已落地;判据分层见 `DEC-004` / `DEC-022` | +| 真实被测运行层 | ✅ `tools/sut-harness/run_sut.sh`(官方镜像 + **能力探针** + DEC-016 自证) | +| 评测语料 | ✅ 可复现:仓内 `eval/corpus/manifest.json`(**只有哈希/计数**)+ 仓外正文 + `tools/seed_eval_corpus.py`(seed 前校验 sha256) | +| 证据归档 | ✅ `tools/archive_evidence.py` + `tools/check_evidence_coverage.py`(被引用的 run 必须有 `spans.jsonl`) | +| 报告 / exit code | ✅ `eval/runs/*.local.json` + `.summary.md`;`exit 0/1/2/3` 契约 | +| 真实发版 CI | ⬜ **未接入** —— 模板在 `integrations/fastapi-rag-agent/`,业务方 2026-10-18 决定暂不动另一个仓 | +| 外化 / 第二个使用者 | ⬜ **暂缓** —— `需求基线.md` 已拍板「自用先行」;`v1.0.0` 留给 U2 + 外部验证 | + +**一次 live 回归的完整链路**: +语料(manifest + 仓外正文)→ `seed_eval_corpus.py` 灌入 → `run_sut.sh` 起被测(能力探针)→ +`eval-gate run`(确定性 → judge → 阈值)→ 报告 + exit code → `archive_evidence.py` 归档 → 覆盖守卫。 + ### 1.2 数据流(一次 run) 1. 装载:读 `evals.json`(每条含输入/期望/确定性规则)、阈值文件、被测适配器配置 → schema 校验先行(**坏配置零模型调用即失败**,控成本)。 2. 取样:按并发上限分批;超大规模评测集走抽样/截断(阶段2 定上限,记 `需求基线.md` §2 L1 成本栏)。 @@ -178,6 +200,7 @@ case 级: pending → calling(调被测,E2) → asserting(确定性,E3) → judg - **Prompt/工具/记忆策略变更必须附 eval 回归**;数据与密钥安全。 ## 变更历史 +- **2026-10-18 自用版结项(版本 0.3→0.4)**:§1.1 一图流补入 **SUT harness / 评测语料 / 证据归档 / 未接入的发版 CI**;新增 §1.3「当前形态」逐件标注「已落地 / 未接线」;版本号与 `pyproject.toml` / `__version__` 统一为 **0.4.0**。结项范围与暂缓项见 `docs/结项报告-自用版-2026-10-18.md`。 - 2026-09-10 定调复核签核 D-1..D-9:北极星=劣化被拦次数、C1 架构定位=评测引擎判文本答案、E1–E9/契约/评测集内容获业务方认可(见 `docs/decisions/定调复核-签核记录.md`)。 - 2026-09-09 P2-2:§3 模块表适配为评测门 E1–E9(Kit 对话类 N/A 显式排除);新增 §3.1 评测执行状态机、§3.2 评测记忆/基准模型、§3.3 评测集 schema 草案(评估集规划启动);版本 0.2→0.3。 - 2026-09-09 P2-1:§1 适配为 agent-eval-gate 七层蓝图(含组件/数据流/不变量);§3/§6 标注模块清单与 MVP 适配口径;版本 0.1→0.2。